Migrate the docs site from Quarto to Astro Starlight

.github/workflows/docs.yml

@@ -23,19 +23,28 @@ jobs:
     steps:
       - uses: actions/checkout@v4
 
-      - name: Set up Quarto
-        uses: quarto-dev/quarto-actions/setup@v2
+      - uses: pnpm/action-setup@v4
+        # version is taken from packageManager in package.json
 
-      - name: Render site
-        run: quarto render site
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+
+      - run: pnpm install --frozen-lockfile
+
+      - name: Build site
+        run: pnpm --filter site build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: site/_site
+          path: site/dist
 
   deploy:
     needs: build
+    # workflow_dispatch from a branch validates the build without publishing
+    if: github.ref == 'refs/heads/main'
     runs-on: ubuntu-latest
     environment:
       name: github-pages

.gitignore

@@ -16,9 +16,9 @@ coverage/
 apps/api/data/
 # Generated release artifact (pnpm validation-pack)
 validation-pack/
-# Quarto docs site build output
-site/_site/
-site/.quarto/
+# Astro docs site build output and generated types
+site/dist/
+site/.astro/
 __pycache__/
 
 # terraform (infra/terraform/*): state is local and contains secrets

CLAUDE.md

@@ -5,7 +5,7 @@
 - **Regulatory claims are verified against source text, never cited from model
   memory.** Any statement attributing a requirement or position to 21 CFR
   Part 11, ICH E6(R3), GAMP 5, CDISC standards, or similar — in
-  `docs/regulatory-traceability.md`, `site/compliance.qmd`, ADRs, the
+  `docs/regulatory-traceability.md`, `site/src/content/docs/compliance.md`, ADRs, the
   validation pack, or PR descriptions — must be checked against the
   authoritative full text before it lands. Maintainers keep a local mirror at
   `~/claude-clinical-skills/sources/` (integrity-checked via its

CONTRIBUTING.md

@@ -46,7 +46,7 @@ tests skip locally (and fail on CI).
 
 ## Refreshing docs screenshots
 
-The screenshots in `site/images/` are generated, not hand-captured. After a
+The screenshots in `site/src/assets/screenshots/` are generated, not hand-captured. After a
 UI change that shows up in the docs, regenerate them:
 
 ```sh
@@ -72,7 +72,7 @@ unpublished protocol import), then captures every page at 1440x900 with
 The state setup is idempotent, so the script can be re-run against a stack it
 already touched — useful with `--only name,name` to redo a subset (names are
 the PNG basenames) and `--out dir` to write somewhere other than
-`site/images/`. But the pages show whatever is in the database, so canonical
+`site/src/assets/screenshots/`. But the pages show whatever is in the database, so canonical
 screenshots want the fresh stack above; leftover dev data will appear in
 list pages.
 

biome.json

@@ -7,8 +7,9 @@
       "!**/node_modules",
       "!**/coverage",
       "!validation-pack",
-      "!site/_site",
-      "!site/.quarto"
+      "!.claude",
+      "!site/.astro",
+      "!**/*.astro"
     ]
   },
   "formatter": {