Merge pull request #3987 from Northeastern-Electric-Racing/docs-site

setup docs site with docs as source of truth

Author: chpy04

.gitignore

@@ -28,6 +28,9 @@
 *.env
 .agent
 
+# Generated Claude skills (source is src/docs-site/docs/)
+.claude/skills/
+
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*

package.json

@@ -6,14 +6,15 @@
   "workspaces": [
     "src/backend",
     "src/frontend",
-    "src/shared"
+    "src/shared",
+    "src/docs-site"
   ],
   "scripts": {
     "prettier-check": "yarn prettier --check .",
     "frontend": "yarn workspace frontend start",
     "backend": "yarn workspace backend start",
     "backend:dev": "yarn workspace backend dev",
-    "start": "yarn workspace shared build; concurrently --kill-others-on-fail \"yarn backend:dev\"  \"yarn frontend\"",
+    "start": "yarn workspace shared build; concurrently --kill-others-on-fail --hide 2 \"yarn backend:dev\" \"yarn frontend\" \"yarn docs:dev\"",
     "prisma:seed": "cd src/backend; npx prisma db seed",
     "prisma:reset:force": "yarn workspace shared build; cd src/backend; npx prisma migrate reset --force",
     "prisma:reset": "yarn workspace shared build; cd src/backend; npx prisma migrate reset",
@@ -59,7 +60,11 @@
     "docker:i": "cd devContainerization && docker compose -f docker-compose.dev.yml exec -T backend sh -c \"yarn install && cd src/backend && npx prisma generate\" && docker compose -f docker-compose.dev.yml exec -T frontend sh -c \"yarn install\"",
     "docker:test": "yarn test:setup && cd devContainerization && docker compose -f docker-compose.dev.yml exec backend bash -c \"yarn test:backend\" && docker compose -f docker-compose.dev.yml exec frontend sh -c \"yarn test:frontend\" && yarn test:teardown",
     "docker:rebuild": "docker compose -f devContainerization/docker-compose.dev.yml rm -f -s && yarn docker:start",
-    "db:pull": "node scripts/db-pull.mjs"
+    "db:pull": "node scripts/db-pull.mjs",
+    "docs:dev": "yarn workspace finishline-docs docs:dev",
+    "docs:build": "yarn workspace finishline-docs docs:build",
+    "docs:serve": "yarn workspace finishline-docs serve",
+    "skills:sync": "yarn workspace finishline-docs sync-skills"
   },
   "resolutions": {
     "@types/react": "17.0.1",
@@ -153,6 +158,8 @@
       "build",
       "coverage",
       "docs",
+      "src/docs-site/.docusaurus",
+      "src/docs-site/build",
       "lambda",
       "node_modules",
       "public",

src/docs-site/.gitignore

@@ -0,0 +1,23 @@
+# Dependencies
+node_modules/
+/.pnp
+.pnp.js
+
+# Production
+/build
+
+# Generated files
+.docusaurus
+.cache-loader
+sidebars.js
+
+# Misc
+.DS_Store
+.env.local
+.env.development.local
+.env.test.local
+.env.production.local
+
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*

src/docs-site/README.md

@@ -0,0 +1,284 @@
+# FinishLine Documentation Site
+
+This directory contains the Docusaurus-based documentation site for FinishLine developers.
+
+## Architecture
+
+**Source of Truth:** `docs-site/docs/` contains all developer documentation in standard Docusaurus markdown format.
+
+**Claude AI Integration:** Documentation files flagged with `skill: true` in their frontmatter are automatically synced to `.claude/skills/` for Claude AI to use as context when helping with development.
+
+### Workflow
+
+1. **Developers edit**: `docs-site/docs/` (tracked in Git)
+2. **Run sync**: `yarn skills:sync` generates `.claude/skills/` (gitignored)
+3. **Claude reads**: `.claude/skills/` to understand the codebase
+
+This approach allows us to:
+
+- Maintain comprehensive documentation for developers
+- Selectively sync relevant docs to Claude's skills
+- Have docs-only content (deployment, architecture) that Claude doesn't need
+
+## Prerequisites
+
+- Node.js 18 or higher
+- Yarn package manager (this project uses Yarn workspaces)
+
+## Setup
+
+The docs-site is part of the FinishLine monorepo workspace. Dependencies are managed from the root:
+
+```bash
+# From the FinishLine root directory
+yarn install
+```
+
+This will install all dependencies for docs-site along with the rest of the project.
+
+## Development
+
+### Running the documentation site locally:
+
+**From the root directory:**
+
+```bash
+yarn docs:dev
+```
+
+**Or from within docs-site:**
+
+```bash
+cd docs-site
+yarn start
+```
+
+The Docusaurus development server will start at `http://localhost:3002`.
+
+The site will automatically reload when you edit files in `docs/`.
+
+## Building for Production
+
+To create a production build:
+
+**From root:**
+
+```bash
+yarn docs:build
+```
+
+**Or from docs-site:**
+
+```bash
+cd docs-site
+yarn build
+```
+
+The static site will be generated in the `build/` directory.
+
+To test the production build locally:
+
+```bash
+yarn docs:serve
+```
+
+## Syncing Skills for Claude
+
+After editing documentation that should be available to Claude:
+
+```bash
+yarn skills:sync
+```
+
+This command:
+
+1. Scans all files in `docs/` for `skill: true` in frontmatter
+2. Transforms them to Claude's SKILL.md format
+3. Writes them to `.claude/skills/` (gitignored)
+
+**When to sync:**
+
+- After adding or editing documentation flagged as a skill
+- Before using Claude for development (to ensure it has latest context)
+- Can be automated in a pre-commit hook if desired
+
+## Project Structure
+
+```
+docs-site/
+├── docs/                   # Source of truth - developer documentation
+│   ├── intro.md
+│   └── general-practices/
+│       ├── backend-endpoints.md
+│       └── ...
+├── scripts/
+│   ├── sync-skills.js      # Generate .claude/skills/ from docs/
+│   └── generate-sidebar.js # Auto-generate sidebars.js from docs/ structure
+├── src/
+│   ├── css/
+│   │   └── custom.css      # Custom styling
+│   └── pages/
+│       └── index.js        # Homepage redirect
+├── static/
+│   └── img/                # Static assets (logos, favicon)
+├── docusaurus.config.js    # Docusaurus configuration
+├── sidebars.js             # Auto-generated sidebar (gitignored)
+└── package.json            # Dependencies and scripts
+```
+
+## Adding New Documentation
+
+### For All Documentation (Developers):
+
+1. **Create a new markdown file** in `docs/`:
+
+   ```bash
+   docs/deployment/github-actions.md
+   ```
+
+2. **Add frontmatter:**
+
+   ```yaml
+   ---
+   title: GitHub Actions Deployment
+   description: Guide for deploying FinishLine using GitHub Actions
+   skill: false # This is docs-only, not a Claude skill
+   ---
+   ```
+
+3. **Test it:**
+   ```bash
+   yarn docs:dev
+   ```
+
+The sidebar will be automatically generated from the folder structure!
+
+### For Documentation That Should Be a Claude Skill:
+
+1. **Create the markdown file** as above
+
+2. **Use `skill: true` in frontmatter:**
+
+   ```yaml
+   ---
+   title: Backend Endpoints
+   description: Guide for creating API endpoints
+   skill: true
+   skill_name: backend-endpoints # Maps to folder name in .claude/skills/
+   ---
+   ```
+
+3. **Sync to Claude:**
+   ```bash
+   yarn skills:sync
+   ```
+
+The sidebar will be automatically generated!
+
+### Organizing Documentation
+
+The sidebar navigation is **automatically generated** from the `docs/` folder structure:
+
+- **Reorder pages**: Rename files (alphabetical order is used)
+- **Create categories**: Create nested folders in `docs/`
+- **Change labels**: Folder names become category labels (use hyphens: `my-category`)
+
+The sidebar regenerates automatically when you run `yarn docs:dev` or `yarn docs:build`.
+
+You can also manually regenerate it:
+
+```bash
+yarn generate-sidebar
+```
+
+## Frontmatter Fields
+
+All documentation files should have frontmatter:
+
+| Field         | Required      | Purpose                        | Example                            |
+| ------------- | ------------- | ------------------------------ | ---------------------------------- |
+| `title`       | Yes           | Page title                     | `Backend Endpoints`                |
+| `description` | Yes           | Page description               | `Guide for creating API endpoints` |
+| `skill`       | Yes           | Should sync to Claude?         | `true` or `false`                  |
+| `skill_name`  | If skill:true | Folder name in .claude/skills/ | `backend-endpoints`                |
+
+## Customization
+
+### Navbar and Footer
+
+Edit `docusaurus.config.js` to customize:
+
+- Site title and tagline
+- Navbar links
+- GitHub repository links
+- Production URL
+
+### Styling
+
+Edit `src/css/custom.css` to customize:
+
+- Primary colors (currently set to NER red: #ef4345)
+- Dark mode colors
+- Font sizes and spacing
+- Custom component styles
+
+### Sidebar Navigation
+
+The sidebar is **automatically generated** from the `docs/` folder structure. To customize it:
+
+- **Reorder pages**: Rename files (alphabetical sorting)
+- **Create categories**: Create nested folders in `docs/`
+- **Change labels**: Folder names become category labels (use hyphens: `my-category`)
+
+The sidebar regenerates each time you run `yarn docs:dev` or `yarn docs:build`.
+
+## Troubleshooting
+
+### Documentation not updating
+
+If your changes aren't appearing:
+
+1. Stop the dev server (Ctrl+C)
+2. Clear the cache: `yarn clear`
+3. Run `yarn docs:dev` again
+
+### Build errors
+
+Common issues:
+
+- **Node version**: Ensure you're running Node.js 18 or higher
+- **Dependencies**: From the root directory, try `rm -rf docs-site/node_modules && yarn install`
+- **Port conflict**: Docs run on port 3002. If it's in use, Docusaurus will try another port or you can stop the conflicting process
+
+### Skills not syncing
+
+If `yarn skills:sync` doesn't generate expected skills:
+
+- Verify the doc has `skill: true` in frontmatter
+- Verify `skill_name` is set for all docs with `skill: true`
+- Check the console output for warnings
+- Ensure `.claude/skills/` is gitignored (it will be regenerated)
+
+## Future Enhancements
+
+Potential improvements for future iterations:
+
+- **Public deployment**: Deploy to GitHub Pages or Vercel
+- **Search functionality**: Add DocSearch or local search plugin
+- **Versioning**: Support documentation for multiple FinishLine versions
+- **Interactive components**: Add live code examples or API explorers
+- **Automated sync**: Pre-commit hook to run skills:sync automatically
+
+## Contributing
+
+When contributing to the documentation:
+
+1. Edit markdown files in `docs-site/docs/`
+2. Test your changes locally with `yarn docs:dev` (sidebar auto-generates)
+3. If you edited a skill doc (`skill: true`), run `yarn skills:sync`
+4. Ensure the site builds successfully with `yarn docs:build`
+5. Submit a PR with your documentation changes
+
+## License
+
+This documentation is part of the FinishLine project, licensed under GNU AGPLv3.

src/docs-site/babel.config.cjs

@@ -0,0 +1,3 @@
+module.exports = {
+  presets: [require.resolve('@docusaurus/core/lib/babel/preset')]
+};

…ral-practices/backend-endpoints/SKILL.md …s/general-practices/backend-endpoints.md.claude/skills/general-practices/backend-endpoints/SKILL.md renamed to src/docs-site/docs/general-practices/backend-endpoints.md .claude/skills/general-practices/backend-endpoints/SKILL.md renamed to src/docs-site/docs/general-practices/backend-endpoints.md

@@ -1,6 +1,8 @@
 ---
-name: backend-endpoints
+title: Backend Endpoints
 description: Guide for creating backend API endpoints in FinishLine following the Route → Controller → Service pattern with multi-tenant security. Use when creating new endpoints, adding API routes, implementing controllers or services, building backend request handlers, or when asked how the backend works.
+skill: true
+skill_name: backend-endpoints
 ---
 
 # Backend Endpoints
@@ -264,7 +266,7 @@ export default class CalendarService {
 - ALWAYS filter `dateDeleted: null` on queries at both the top level and within nested includes/selects.
 - Deleting an entity MUST be a soft delete (`dateDeleted: new Date()`), never `prisma.*.delete()`.
 
-For query args and transformer patterns, see the [query-args-and-transformers](../query-args-and-transformers/SKILL.md) document.
+For query args and transformer patterns, see the [query-args-and-transformers](./query-args-and-transformers) document.
 
 ### Step 5: Deciding the Access Level
 
@@ -373,7 +375,7 @@ For complex reusable validators, spread them: `...descriptionBulletsValidators`.
 - [ ] Entity name added to `ExceptionObjectNames` if needed
 - [ ] All queries filter `dateDeleted: null` at every level
 - [ ] Delete operations are soft deletes
-- [ ] Service returns transformed shared types (see [query-args-and-transformers](../query-args-and-transformers/SKILL.md))
+- [ ] Service returns transformed shared types (see [query-args-and-transformers](./query-args-and-transformers))
 - [ ] Multiple writes wrapped in `prisma.$transaction()`
 - [ ] All imports use `.js` extensions
 - [ ] Router registered in `index.ts` (if new feature)