docs(website): mirror docs/*.md into the site + auto-deploy on a cadence

Make the repository's docs/*.md the single source of truth for the docs
site instead of maintaining a parallel set of hand-written MDX pages that
silently drift.

- scripts/sync-docs.mjs mirrors ../docs into content/docs/ on every build:
  derives title/description, injects Fumadocs frontmatter (+ githubSource),
  rewrites internal *.md links to /docs routes, and emits meta.json. Pages
  are written as .md so <placeholders>/{braces} in the docs stay literal
  and never break the MDX build.
- docs.sync.config.mjs is the one manifest deciding which docs publish and
  their slug/section/icon. content/docs/ is now generated + git-ignored;
  the curated .mdx pages are removed. The marketing landing page stays
  hand-authored.
- build/dev/types:check run sync:docs first, so the site is always current.
- .github/workflows/deploy-docs.yml rebuilds and deploys to Cloudflare
  Pages via Wrangler on push to docs/**|website/**, daily on a schedule,
  on demand, and as a build-only check on PRs. Needs CLOUDFLARE_API_TOKEN
  + CLOUDFLARE_ACCOUNT_ID secrets and the DOCS_SITE_URL variable.
- source.config.ts carries githubSource so "edit this page" opens the real
  docs/*.md; website/README.md documents the pipeline.

Verified: clean build, 23 pages generated, 78 static pages, no warnings;
all internal doc links resolve; MDX-hazard docs (cli, customization) build.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: clay-good

.github/workflows/deploy-docs.yml

@@ -0,0 +1,69 @@
+name: Docs site
+
+# The documentation site (website/) mirrors docs/*.md via scripts/sync-docs.mjs,
+# which runs as the first step of `npm run build`. This workflow rebuilds that
+# mirror and deploys the static export to Cloudflare Pages:
+#   - on every push to main that touches docs/ or website/ (deploy immediately),
+#   - on a daily schedule (re-mirror the latest docs even if nothing pushed),
+#   - manually via the Actions tab,
+#   - and as a build-only check on pull requests.
+#
+# Deploys require two repository secrets: CLOUDFLARE_API_TOKEN and
+# CLOUDFLARE_ACCOUNT_ID. Set the site's public URL via the DOCS_SITE_URL
+# repository variable (used for OG/sitemap absolute URLs).
+
+on:
+  push:
+    branches: [main]
+    paths:
+      - 'docs/**'
+      - 'website/**'
+      - '.github/workflows/deploy-docs.yml'
+  pull_request:
+    paths:
+      - 'docs/**'
+      - 'website/**'
+      - '.github/workflows/deploy-docs.yml'
+  schedule:
+    # Daily at 06:00 UTC — picks up any docs changes merged since the last run.
+    - cron: '0 6 * * *'
+  workflow_dispatch:
+
+# Never run two deploys at once; let an in-flight deploy finish.
+concurrency:
+  group: deploy-docs
+  cancel-in-progress: false
+
+jobs:
+  build-and-deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm
+          cache-dependency-path: website/package-lock.json
+
+      - name: Install dependencies
+        working-directory: website
+        run: npm ci
+
+      - name: Build site (mirrors docs/*.md, then next build)
+        working-directory: website
+        env:
+          NEXT_PUBLIC_SITE_URL: ${{ vars.DOCS_SITE_URL }}
+        run: npm run build
+
+      - name: Deploy to Cloudflare Pages
+        # Skip on pull requests (build-only check) and on forks without secrets.
+        if: ${{ github.event_name != 'pull_request' && github.repository == 'Fission-AI/OpenSpec' }}
+        uses: cloudflare/wrangler-action@v3
+        with:
+          apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+          accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+          workingDirectory: website
+          command: pages deploy out --project-name=openspec-docs --branch=main

website/.gitignore

@@ -4,6 +4,9 @@
 # generated content
 .source
 
+# docs pages are generated from ../docs by scripts/sync-docs.mjs (npm run build)
+/content/docs
+
 # test & build
 /coverage
 /.next/

website/README.md

@@ -2,6 +2,8 @@
 
 The marketing and documentation site for [OpenSpec](https://github.com/Fission-AI/OpenSpec), built with [Fumadocs](https://fumadocs.dev) and [Next.js](https://nextjs.org). It is configured as a **static export**, so it deploys to Cloudflare Pages (or any static host) with no server.
 
+> **The doc pages are generated, not authored here.** The repository's `docs/*.md` files are the single source of truth. `scripts/sync-docs.mjs` mirrors them into `content/docs/` (as `.md`) on every build, so the site stays current automatically — locally and in CI. Edit `../docs`, not `content/docs/`. Only the marketing landing page (`app/(home)/page.tsx`) is hand-authored. See [Keeping docs in sync](#keeping-docs-in-sync).
+
 ## Quick start
 
 ```bash
@@ -12,10 +14,13 @@ npm run dev      # http://localhost:3000
 
 | Script | What it does |
 |--------|--------------|
-| `npm run dev` | Start the dev server with hot reload |
-| `npm run build` | Produce the static site in `out/` |
+| `npm run sync:docs` | Mirror `../docs/*.md` into `content/docs/` |
+| `npm run dev` | Sync docs, then start the dev server with hot reload |
+| `npm run build` | Sync docs, then produce the static site in `out/` |
 | `npm run start` | Serve the built `out/` directory locally |
-| `npm run types:check` | Generate types and run `tsc --noEmit` |
+| `npm run types:check` | Sync docs, generate types, and run `tsc --noEmit` |
+
+`sync:docs` runs automatically inside `dev`, `build`, and `types:check`, so you rarely call it directly.
 
 ## Deploy to Cloudflare Pages
 
@@ -49,27 +54,46 @@ npm run build
 npx wrangler pages deploy out --project-name openspec-docs
 ```
 
-## Editing the docs
+## Keeping docs in sync
+
+The doc pages are a **mechanical mirror** of the repository's `docs/*.md`. There
+is nothing to hand-edit under `content/docs/` — those files are generated and
+git-ignored.
+
+**To change a page's content:** edit the corresponding file in `../docs`. The
+next `npm run build`/`npm run dev` regenerates the site from it.
+
+**To add, remove, reorder, or re-slug a page, or change its sidebar section or
+icon:** edit `docs.sync.config.mjs`. That manifest is the single place that
+decides which docs are published and how they appear. `scripts/sync-docs.mjs`
+then:
 
-All content lives in `content/docs/` as MDX. To add a page:
+- derives each page's title from its leading `# H1` and a description from its
+  first paragraph, and injects Fumadocs frontmatter (including `githubSource`, so
+  the "edit this page" link opens the real `docs/*.md`);
+- rewrites internal `*.md` links to their on-site `/docs/...` routes;
+- writes each page as `.md` (Fumadocs parses `.md` as plain Markdown, so
+  `<placeholders>` and `{braces}` in the docs are treated literally and never
+  break the build);
+- regenerates `content/docs/meta.json` and `content/docs/reference/meta.json`.
 
-1. Create `content/docs/my-page.mdx` with frontmatter:
+Because the docs are the source, the site cannot drift from them: every build
+re-mirrors, and CI redeploys on a schedule (see below).
 
-   ```mdx
-   ---
-   title: My Page
-   description: One-line summary used for search and previews.
-   icon: Sparkles      # optional: any lucide-react icon name
-   ---
+## Automated deploys
 
-   Your content here.
-   ```
+`.github/workflows/deploy-docs.yml` rebuilds the mirror and deploys to Cloudflare
+Pages via Wrangler:
 
-2. Add its slug to the `pages` array in `content/docs/meta.json` to place it in
-   the sidebar. Use `"---Section name---"` entries to add section separators.
+- on every push to `main` that touches `docs/**` or `website/**`,
+- daily on a schedule (so docs merged elsewhere still go live),
+- manually via the Actions tab,
+- and as a build-only check on pull requests.
 
-MDX pages can use these components without importing them: `Callout`, `Card`,
-`Cards`, `Tabs`/`Tab`, `Steps`/`Step`, and `Accordions`/`Accordion`.
+It needs two repository **secrets** — `CLOUDFLARE_API_TOKEN` and
+`CLOUDFLARE_ACCOUNT_ID` — and one optional repository **variable**,
+`DOCS_SITE_URL` (the site's public URL, used for OG/sitemap absolute links). The
+Cloudflare Pages project is named `openspec-docs`.
 
 ## Project structure
 
@@ -81,7 +105,9 @@ website/
 │   ├── api/search/          # static search index route
 │   ├── llms.txt / llms-full.txt / llms.mdx/   # machine-readable docs for AI
 │   └── og/                  # generated Open Graph images per page
-├── content/docs/            # ← all documentation MDX lives here
+├── content/docs/            # ← GENERATED from ../docs (git-ignored, do not edit)
+├── docs.sync.config.mjs     # which docs publish + their slug/section/icon
+├── scripts/sync-docs.mjs    # mirrors ../docs/*.md -> content/docs/
 ├── lib/
 │   ├── shared.ts            # site name, URLs, GitHub/Discord links
 │   ├── source.ts            # Fumadocs content source + sidebar icons

website/app/docs/[[...slug]]/page.tsx

@@ -29,7 +29,9 @@ export default async function Page(props: PageProps<'/docs/[[...slug]]'>) {
         <MarkdownCopyButton markdownUrl={markdownUrl} />
         <ViewOptionsPopover
           markdownUrl={markdownUrl}
-          githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/website/content/docs/${page.path}`}
+          githubUrl={`https://github.com/${gitConfig.user}/${gitConfig.repo}/blob/${gitConfig.branch}/${
+            page.data.githubSource ?? `website/content/docs/${page.path}`
+          }`}
         />
       </div>
       <DocsBody>