docs(website): Rspress docsite audit — every P1/P2 from #590 plus cheap P3s

.changeset/590-diagnostics-contract-rows.md

@@ -0,0 +1,5 @@
+---
+"agent-bundle": patch
+---
+
+Document every emitted diagnostic code explicitly in `docs/diagnostics.md` (the `reference/diagnostics` page). Codes that were covered only by a family row now each have a row with severity, trigger message, and — where the diagnostic carries one — recovery, read from the emitting site: `AB3000`–`AB3006`, `AB3008`–`AB3010`, `AB4000`, `AB4002`–`AB4007`, `AB4012`, `AB4100`–`AB4102`, `AB4200`–`AB4212` (including the previously undocumented `AB4204`), `AB4300`–`AB4339`, `AB4400`–`AB4408`, `AB4600`–`AB4602`, `AB4700`–`AB4716`, `AB6000`–`AB6001`, `AB6002`–`AB6003` (reserved, never emitted), `AB6004`–`AB6018` (`AB6005` restates #588), `AB6023`–`AB6025`, `AB6200`–`AB6202`, `AB7000`–`AB7004`, `AB7103`, `AB8000`–`AB8023` (including `AB8003` and `AB8004`), `AB8030`–`AB8034`, `AB8040`–`AB8057`, `AB8060`–`AB8068`, `AB8070`–`AB8083`, `AB8085`–`AB8088`, `AB8090`–`AB8093`, `AB8120`–`AB8123`, `AB9001`–`AB9005`, and `AB9007`–`AB9011`. The `AB4834` row is rewritten to three cells so the table renders. `pnpm docs:site:build` now fails when a code cited in the docs or a code literal in `packages/agent-bundle/src` has no explicit row (`website/scripts/check-diagnostics-coverage.mjs`). (#599)

.github/dependabot.yml

@@ -5,6 +5,10 @@ updates:
     schedule:
       interval: weekly
   - package-ecosystem: github-actions
-    directory: /
+    # `/` covers .github/workflows/*; the composite actions under
+    # .github/actions/* (where pnpm/setup lives) are separate directories.
+    directories:
+      - /
+      - /.github/actions/*
     schedule:
       interval: weekly

.github/workflows/docs.yml

@@ -44,21 +44,26 @@ jobs:
     name: Docs site (Node 22.19)
     runs-on: ubuntu-latest
     timeout-minutes: 25
+    # Third-party actions are pinned to full commit SHAs (a moving `vN` tag
+    # can be repointed at unreviewed code); the trailing comment names the
+    # release Dependabot keeps in step.
     steps:
-      - uses: actions/checkout@v7
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
       - uses: ./.github/actions/setup-workspace
         with:
           node-version: 22.19.0
       # Website-only PRs skip every ci.yml job that lints, so lint here too.
       - run: pnpm lint
-      # Typecheck the site config and build it. Rspress's own dead-link,
-      # dead-anchor, dead-image, and language-parity checks fail the build if
-      # TypeDoc or the generated reference pages are missing, since the
-      # authored pages link to them.
+      # Typecheck the site config, run the locale-drift and diagnostics-
+      # coverage checks (website/scripts), build with the persistent Rspack
+      # cache off, then walk the emitted HTML for dead links and anchors.
+      # Rspress's own dead-link, dead-anchor, dead-image, and language-parity
+      # checks fail the build if TypeDoc or the generated reference pages are
+      # missing, since the authored pages link to them.
       - run: pnpm docs:site:build
       - name: Upload Pages artifact
         if: github.ref == 'refs/heads/main' && (github.event_name == 'push' || github.event_name == 'workflow_dispatch')
-        uses: actions/upload-pages-artifact@v5
+        uses: actions/upload-pages-artifact@fc324d3547104276b827a68afc52ff2a11cc49c9 # v5.0.0
         with:
           path: website/doc_build
 
@@ -96,7 +101,7 @@ jobs:
             echo "Skipped deploy: main moved to ${head}; this run built ${GITHUB_SHA}." >> "$GITHUB_STEP_SUMMARY"
           fi
       - if: steps.head.outputs.deploy == 'true'
-        uses: actions/configure-pages@v6
+        uses: actions/configure-pages@45bfe0192ca1faeb007ade9deae92b16b8254a0d # v6.0.0
       - if: steps.head.outputs.deploy == 'true'
         id: deployment
-        uses: actions/deploy-pages@v5
+        uses: actions/deploy-pages@368f82528645a54fb793d4d04e342629a3f51346 # v5.0.1

package.json

@@ -22,7 +22,7 @@
     "test:watch": "rstest --config rstest.config.ts --watch",
     "lint": "rslint .",
     "bench:hook-cold-start": "node scripts/measure-hook-cold-start.mjs",
-    "typecheck": "node scripts/check-dist-fresh.mjs && tsc --noEmit && tsc --project packages/workbench/tsconfig.json && tsc --project packages/create-agent-bundle/tsconfig.json && tsc --project packages/rsc-markdown-stream/tsconfig.json",
+    "typecheck": "node scripts/check-dist-fresh.mjs && tsc --noEmit && tsc --project packages/workbench/tsconfig.json && tsc --project packages/create-agent-bundle/tsconfig.json && tsc --project packages/rsc-markdown-stream/tsconfig.json && pnpm --filter @agent-bundle/docs typecheck",
     "check": "pnpm build && pnpm test:unit && pnpm test:route-unit && pnpm test:projection && pnpm test:integration:run && pnpm lint && pnpm typecheck",
     "check:local-ci": "node scripts/local-ci.mjs",
     "check:host-cli": "node scripts/host-cli-pins.mjs verify",

patches/@rspress__core@2.0.21.patch

@@ -0,0 +1,20 @@
+diff --git a/dist/theme/components/Search/logic/providers/LocalProvider.js b/dist/theme/components/Search/logic/providers/LocalProvider.js
+index 1f49672061c56144b8299aef61d6b25029b143c4..3bb16cddef4176194a939202c5a1ec6a581dd82a 100644
+--- a/dist/theme/components/Search/logic/providers/LocalProvider.js
++++ b/dist/theme/components/Search/logic/providers/LocalProvider.js
+@@ -78,12 +78,12 @@ class LocalProvider {
+                 finalize: (str)=>str.flatMap((s)=>tokenize(s, cyrillicRegex))
+             }
+         });
++        const pending = [];
+         for (const item of pagesForSearch){
+             const flexSearchItem = item;
+-            this.#index.addAsync(item.routePath, flexSearchItem);
+-            this.#cjkIndex.addAsync(item.routePath, flexSearchItem);
+-            this.#cyrillicIndex.addAsync(item.routePath, flexSearchItem);
++            pending.push(this.#index.addAsync(item.routePath, flexSearchItem), this.#cjkIndex.addAsync(item.routePath, flexSearchItem), this.#cyrillicIndex.addAsync(item.routePath, flexSearchItem));
+         }
++        await Promise.all(pending);
+     }
+     async search(query) {
+         const { keyword, limit } = query;

pnpm-workspace.yaml

@@ -26,3 +26,8 @@ minimumReleaseAgeExclude:
   - '@effect/tsgo-win32-arm64@0.39.0'
   - '@effect/tsgo-win32-x64@0.39.0'
   - '@effect/tsgo@0.39.0'
+# LocalProvider.init() awaits FlexSearch addAsync so the first search query
+# cannot race the index build (#590; upstream web-infra-dev/rspress#3658).
+# Drop the patch once a release awaits the adds.
+patchedDependencies:
+  '@rspress/core@2.0.21': patches/@rspress__core@2.0.21.patch

website/docs/en/_nav.json

@@ -7,7 +7,7 @@
   {
     "text": "Reference",
     "link": "/reference/",
-    "activeMatch": "/reference/"
+    "activeMatch": "/reference/(?!api$)"
   },
   {
     "text": "Examples",
@@ -21,7 +21,7 @@
   },
   {
     "text": "Type API",
-    "link": "/api/",
-    "activeMatch": "/api/"
+    "link": "/reference/api",
+    "activeMatch": "/api/|/reference/api"
   }
 ]

website/docs/en/api/_meta.json

@@ -3,31 +3,37 @@
   {
     "type": "dir",
     "name": "modules",
-    "label": "Modules"
+    "label": "Modules",
+    "collapsed": true
   },
   {
     "type": "dir",
     "name": "functions",
-    "label": "Functions"
+    "label": "Functions",
+    "collapsed": true
   },
   {
     "type": "dir",
     "name": "classes",
-    "label": "Classes"
+    "label": "Classes",
+    "collapsed": true
   },
   {
     "type": "dir",
     "name": "interfaces",
-    "label": "Interfaces"
+    "label": "Interfaces",
+    "collapsed": true
   },
   {
     "type": "dir",
     "name": "types",
-    "label": "Type aliases"
+    "label": "Type aliases",
+    "collapsed": true
   },
   {
     "type": "dir",
     "name": "variables",
-    "label": "Variables"
+    "label": "Variables",
+    "collapsed": true
   }
 ]

website/docs/en/examples/audiobook-curator.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'The Audiobook Curator example: a complete agent-bundle application built from route modules, request-context providers, durable state, MCP-to-CLI projection, and the framework-owned package build.'
+description: 'Audiobook Curator: a complete agent-bundle app from route modules, request-context providers, durable state, MCP-to-CLI projection, and the package build.'
 ---
 
 # Audiobook Curator

website/docs/en/examples/hooks-and-scripts.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'The Hooks and Scripts example: a session-start hook, two emitted scripts including a blocking exit code, durable Playground traces, and a reversible diagnostic walkthrough.'
+description: 'The Hooks and Scripts example: a session-start hook, two scripts (one blocking exit code), durable Playground traces, and a reversible diagnostic walkthrough.'
 ---
 
 # Hooks and Scripts

website/docs/en/examples/mcp-app.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'The MCP App example: one service-readiness workflow expressed as a generated stdio MCP server, a typed tool, an interactive MCP App resource, a Skill, a hook, a script, and a deterministic eval.'
+description: 'The MCP App example: a service-readiness workflow as a stdio MCP server, a typed tool, an MCP App resource, a Skill, a hook, a script, and a deterministic eval.'
 ---
 
 # MCP App