docs: scaffold Starlight documentation site

.github/settings.yml

@@ -11,7 +11,7 @@ branches:
     protection:
       required_status_checks:
         strict: true
-        contexts: [Build, Typecheck, Lint, Test, Release, Analyze (typescript), CodeQL, Renovate / Renovate]
+        contexts: [Build, Docs Build, Typecheck, Lint, Test, Release, Analyze (typescript), CodeQL, Renovate / Renovate]
       enforce_admins: true
       required_pull_request_reviews: null
       restrictions: null

.github/workflows/docs.yaml

@@ -0,0 +1,83 @@
+name: Docs
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'skills/**'
+      - 'agents/**'
+      - 'commands/**'
+      - 'README.md'
+  workflow_dispatch:
+
+concurrency:
+  group: docs-deploy
+  cancel-in-progress: true
+
+permissions:
+  contents: read
+
+jobs:
+  build-and-deploy:
+    name: Build and Deploy Docs
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Generate reference content
+        run: bun run docs:generate
+
+      - name: Build docs
+        run: bun run --cwd docs build
+
+      - name: Create GitHub App token
+        if: github.repository == 'marcusrbrown/systematic'
+        uses: actions/create-github-app-token@29824e69f54612133e76f7eaac726eef6c875baf # v2.2.1
+        id: app-token
+        with:
+          app-id: ${{ secrets.FRO_BOT_APPLICATION_ID }}
+          private-key: ${{ secrets.FRO_BOT_APPLICATION_PRIVATE_KEY }}
+          owner: fro-bot
+
+      - name: Deploy to fro-bot/systematic
+        if: github.repository == 'marcusrbrown/systematic'
+        env:
+          GH_TOKEN: ${{ steps.app-token.outputs.token }}
+          APP_SLUG: ${{ steps.app-token.outputs.app-slug }}
+        run: |
+          name="${APP_SLUG}[bot]"
+          user_id=$(gh api "/users/${name}" --jq .id)
+          email="${user_id}+${name}@users.noreply.github.com"
+          git config --global user.email "${email}"
+          git config --global user.name "${name}"
+
+          # Verify docs build output exists
+          if [ ! -d "docs/dist" ]; then
+            echo "✗ Docs build output not found"
+            exit 1
+          fi
+
+          # Clone deployment repository
+          git clone "https://x-access-token:${GH_TOKEN}@github.com/fro-bot/systematic.git" deploy-repo
+          cd deploy-repo
+
+          # Clean and copy new docs (preserve .git directory)
+          find . -mindepth 1 -not -path './.git' -not -path './.git/*' -delete
+          cp -r ../docs/dist/* .
+
+          # Commit and push if there are changes
+          git add -A
+          if ! git diff-index --quiet HEAD --; then
+            git commit -m "Deploy docs from marcusrbrown/systematic@${{ github.sha }}"
+            git push
+          else
+            echo "No changes to commit"
+          fi

.github/workflows/main.yaml

@@ -83,6 +83,21 @@ jobs:
       - name: Run tests
         run: bun test tests/unit
 
+  docs:
+    name: Docs Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@3d267786b128fe76c2f16a390aa2448b815359f3 # v2.1.2
+
+      - name: Install dependencies
+        run: bun install --frozen-lockfile
+
+      - name: Build docs
+        run: bun run docs:build
+
   release:
     env:
       DRY_RUN: ${{ github.event_name == 'pull_request' || github.event.inputs.dry-run && 'true' || 'false' }}

.gitignore

@@ -29,3 +29,10 @@ tests/tmp/
 
 # Sisyphus (OMO)
 .sisyphus/
+
+# Docs build artifacts
+docs/dist/
+docs/.astro/
+docs/src/content/docs/reference/**
+!docs/src/content/docs/reference/**/
+!docs/src/content/docs/reference/**/index.mdx

README.md

@@ -10,6 +10,7 @@
 
 [![Build Status](https://img.shields.io/github/actions/workflow/status/marcusrbrown/systematic/main.yaml?style=flat-square&label=build&labelColor=1a1a2e&color=4FD1C5)](https://github.com/marcusrbrown/systematic/actions)
 [![npm version](https://img.shields.io/npm/v/@fro.bot/systematic?style=flat-square&label=npm&labelColor=1a1a2e&color=E91E8C)](https://www.npmjs.com/package/@fro.bot/systematic)
+[![Docs](https://img.shields.io/badge/docs-fro.bot/systematic-4FD1C5?style=flat-square&labelColor=1a1a2e)](https://fro.bot/systematic)
 [![License](https://img.shields.io/badge/license-MIT-F5A623?style=flat-square&labelColor=1a1a2e)](LICENSE)
 
 <br>
@@ -324,7 +325,7 @@ See [`AGENTS.md`](./AGENTS.md) for detailed development guidelines, code style c
 
 ## Converting from Claude Code
 
-Migrating skills, agents, or commands from Claude Code (CEP) to Systematic? See the [Conversion Guide](./docs/CONVERSION-GUIDE.md) for field mappings and examples.
+Migrating skills, agents, or commands from Claude Code (CEP) to Systematic? See the [Conversion Guide](https://fro.bot/systematic/guides/conversion-guide) for field mappings and examples. (Also available as [local Markdown](./docs/CONVERSION-GUIDE.md).)
 
 ## References
 

biome.json

@@ -30,7 +30,9 @@
       "!**/dist",
       "!**/.opencode",
       "!**/node_modules",
-      "!**/*.md"
+      "!**/*.md",
+      "!**/.astro",
+      "!.sisyphus"
     ]
   }
 }