ci: add docs Pages export guardrails

.github/workflows/pages.yml

@@ -10,6 +10,8 @@ on:
       - 'docs.json'
       - 'package.json'
       - 'scripts/docs-dev.mjs'
+      - 'scripts/docs-static-compat.test.mjs'
+      - 'scripts/export-docs-site.test.mjs'
       - 'scripts/export-docs-site.mjs'
   workflow_dispatch:
 
@@ -34,9 +36,17 @@ jobs:
         with:
           node-version: '22'
 
+      - name: Setup Bun
+        uses: oven-sh/setup-bun@v2
+        with:
+          bun-version: latest
+
       - name: Configure Pages
         uses: actions/configure-pages@v5
 
+      - name: Run docs export safety checks
+        run: bun test scripts/docs-static-compat.test.mjs scripts/export-docs-site.test.mjs
+
       - name: Export static docs site
         run: node scripts/export-docs-site.mjs --output .pages-dist
 

AGENTS.md

@@ -21,9 +21,12 @@ echo "say hello" | bun run src/entrypoints/cli.tsx -p
 
 # Build (outputs dist/cli.js, ~25MB)
 bun run build
+
+# Targeted docs export safety checks
+bun test scripts/docs-static-compat.test.mjs scripts/export-docs-site.test.mjs
 ```
 
-No test runner is configured. No linter is configured.
+The repo has Bun tests and a Biome lint script, but the current CI lint baseline is noisy.
 
 ## Architecture
 
@@ -113,3 +116,4 @@ All `feature('FLAG_NAME')` calls come from `bun:bundle` (a build-time API). In t
 - **React Compiler output** — Components have decompiled memoization boilerplate (`const $ = _c(N)`). This is normal.
 - **`bun:bundle` import** — In `src/main.tsx` and other files, `import { feature } from 'bun:bundle'` works at build time. At dev-time, the polyfill in `cli.tsx` provides it.
 - **`src/` path alias** — tsconfig maps `src/*` to `./src/*`. Imports like `import { ... } from 'src/utils/...'` are valid.
+- **Docs export rules** — for `docs/**/*.mdx`, use relative internal links, avoid root-relative `/docs/...` paths, and avoid Mintlify `Frame` diagram embeds on GitHub Pages. See `docs/MAINTAINING.md`.

docs/MAINTAINING.md

@@ -0,0 +1,23 @@
+# Docs Maintenance
+
+This docs site is authored in MDX, exported through Mintlify, and published on GitHub Pages.
+
+## GitHub Pages Compatibility Rules
+
+- Use relative links for internal docs and asset references inside `docs/**/*.mdx`.
+- Do not use root-relative internal paths such as `/docs/...` in MDX content.
+- Avoid Mintlify `Frame` wrappers for diagrams and screenshots on Pages-exported docs.
+- Prefer plain relative links to large diagrams and screenshots when in doubt.
+- If you need to add a new interactive or custom MDX component, verify the exported site with a real browser reload before merging.
+
+## Required Checks
+
+Run these checks after editing docs content or the export pipeline:
+
+```bash
+bun test scripts/docs-static-compat.test.mjs scripts/export-docs-site.test.mjs
+```
+
+## Why These Rules Exist
+
+GitHub Pages serves a static export. Root-relative internal links and some Mintlify component patterns can survive the initial render but fail after hydration or refresh, which can surface as Mintlify's `Error loading page` 500 screen.