setup docs site with docs as source of truth

[rbessin]

Changes

Set up a Docusaurus documentation site where docs-site/docs/ is the source of truth and Claude skills are automatically generated from flagged documentation.

Architecture:

• Source of truth: docs-site/docs/ (tracked in Git)
• Auto-generated: .claude/skills/ (gitignored, synced via yarn skills:sync)
• 8 docs total: 7 synced as Claude skills, 1 docs-only (Postman guide)

Implementation:

• Added docs-site as yarn workspace for unified dependency management
• Created sync-skills.js: transforms docs with skill: true → .claude/skills/SKILL.md format
• Created generate-sidebar.js: auto-generates sidebar from folder structure
• Handles Windows/Unix line endings, bidirectional link transformation
• Docs run on port 3002 (no conflict with main app)

Developer Workflow:

1. Edit docs in docs-site/docs/
2. yarn docs:dev → preview at localhost:3002 (sidebar auto-generates)
3. yarn skills:sync → update .claude/skills/ (if doc has skill: true)
4. Commit changes to docs-site/docs/

Notes

• yarn.lock changes expected: workspace integration caused dependency hoisting (no version bumps)
• .claude/skills/ gitignored: now auto-generated, not tracked
• Decision: No skills-only content - if Claude needs it, developers probably do too
• Built with Docusaurus for React alignment, extensibility, and Meta backing

Test Cases

• yarn docs:dev starts dev server at localhost:3002
• yarn docs:build builds production site without errors
• yarn skills:sync generates 7 SKILL.md files (excludes Postman)
• Auto-generated sidebar reflects folder structure
• Internal doc links work (e.g., backend-endpoints → query-args)
• "Edit this page" links point to docs-site/docs/ files
• Logo and favicon display correctly
• Both docs site and main app run simultaneously

Screenshots

Checklist

• All commits are tagged with the ticket number
• No linting errors / newline at end of file warnings
• All code follows repository-configured prettier formatting
• No merge conflicts
• All checks passing
• Screenshots of UI changes (see Screenshots section)
• Remove any non-applicable sections of this template
• Assign the PR to yourself
• No yarn.lock changes - workspace integration (expected)
• Request reviewers & ping on Slack
• PR is linked to the ticket

Closes #3978