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

* ci(docs): drift, built-link, and diagnostics-coverage gates for the docsite; pin docs.yml actions; Dependabot scans composite actions (#590 lane E)

website/scripts (plain Node >= 22, no dependencies), wired into the website
`check` script that `pnpm docs:site:build` and docs.yml run:

- check-locale-drift.mjs: every authored en/ page needs a zh/ twin with the
  same fenced-code count, the same code per fence (comments stripped in
  sh/bash/ts/tsx/js/json fences, trailing `# note` in text tree listings),
  the same ABnnnn code set, the same table-row count, and an h2/h3 count
  within 2; _meta.json/_nav.json must match in entries, order, and link
  targets modulo the /zh prefix. Rspress's languageParity compares only the
  set of page paths.
- check-built-links.mjs: post-build walk of doc_build/**/*.html (+ sitemap
  <loc>s) resolving every site-internal href/src/og:url honouring cleanUrls
  and requiring each #fragment to name an id in the target. Rspress's own
  checks see only mdast links, so frontmatter hero/feature links, _nav.json,
  raw <a href>, and every generated page were unchecked, and a warm
  persistent cache let dead anchors into unchanged pages pass.
- check-diagnostics-coverage.mjs: every ABnnnn cited in website/docs
  {en,zh}/**/*.mdx and (strict, `--no-src` to skip) every ABnnnn literal in
  packages/agent-bundle/src must have an explicit row, range row, or code
  heading in docs/diagnostics.md; family catch-all rows do not count.

website `check` builds with RSPRESS_PERSISTENT_CACHE=false (the variable
@rspress/core reads to disable Rsbuild buildCache) so the anchor checks run
against a cold compile. Drops the two website devDependencies nothing
imports (@types/react-dom, agent-bundle); lockfile regenerated with
`pnpm install --lockfile-only`.

The root `typecheck` now also runs the website tsconfig (config, plugins,
theme), which only `docs:site:build` compiled before.

docs.yml pins actions/checkout, upload-pages-artifact, configure-pages, and
deploy-pages to full commit SHAs (job name unchanged; it is a required
check). dependabot.yml scans /.github/actions/* so the composite
setup-workspace action's pnpm/setup pin is updated too.

* docs(site): feed twoslash from tsconfig.typedoc.json paths, SSG worker, sidebar/nav tidy-ups (#590 lane A2)

- rspress.config.ts reads `compilerOptions.paths` from tsconfig.typedoc.json
  (JSONC, via ts.readConfigFile), makes the targets absolute, and merges them
  with the four `agent-bundle*` entries for pluginTwoslash, so
  `@agent-bundle/runtime*` and `rsc-markdown-stream` resolve to workspace
  sources without `pnpm build`. The 12 `: any` hovers on
  guide/development/testing (en + zh) are gone; the tsconfig comment now
  states that this file is the single source of the map.
- ssg.experimentalWorker: true; builderConfig.performance.printFileSize.detail: false.
- head: static theme-color meta. Per-route canonical/og:url functions are
  left out: renderPages passes config.head to the SSG worker threads through
  workerData, and a function fails structured cloning (DataCloneError).
- themeConfig.footer: Apache-2.0 message (home layout).
- Remove transformerNotationDiff/Focus (no [!code ++/--/focus] in docs) and
  search.codeBlocks (restates the default); TypeDoc index title template
  drops the empty {version} placeholder.
- api/_meta.json: collapsed: true on the six dir groups, both locales.
- _nav.json: "Type API" links to the hand-written /reference/api overview;
  activeMatch covers /api/ and /reference/api, both locales.
- mirror-api-locale: per-target `notice`, inserted as an :::info container
  directly under the title of every mirrored zh/api page.
- docs/public/robots.txt with the sitemap URL.

* docs(diagnostics): document every emitted AB0000–AB5999 code explicitly

Add explicit rows for the 103 emitted codes in AB3000–AB4716 that were
covered only by a family catch-all (AB30xx, AB40xx–AB46xx, AB470x/AB471x),
plus dedicated sections for AB4500 and AB5000, whose only mention was the
Code families summary row. New sections sit after the Code families table.
Adds the missing AB4204 and AB5000 rows; gives AB4716 a table row in its
Declaration generation section; folds the AB4834 recovery text into its
Trigger cell so the row matches its three-column header (GFM was dropping
the fourth cell). Every emitted code in AB0000–AB5999 now has an explicit
row; no ragged table rows remain in the file.

Refs #590

* docs(en): accuracy fixes, description lengths, and fence reflow for #590 (lane C)

- reference/cli: exit-code rows 1/2 state which option validators throw
  Commander InvalidArgumentError (exit 2) versus a plain TypeError reported
  as one AB5000 diagnostic (exit 1), per src/cli.ts and runCli.
- guide/authoring/hooks: result-contract table and per-event bullets match
  hook-handler.ts / hook-contract.ts — no event admits outcome 'stop',
  Cursor alone tolerates a denying agentStart, only Claude carries
  additionalContext from agentStop.
- reference/configuration: targets defaults to ['portable'], marketplace to
  false; evals and routes ride the AgentBundleConfig index signature, evals
  rules fire as EVAL_* errors when an eval or the Workbench loads the config.
- Tighten 13 en frontmatter descriptions to <=160 code points.
- Reflow every fenced code line over 90 columns in en (36 -> 0) and mirror
  the identical reflow in the zh twin fences (28 -> 0); zh prose untouched.

* docs(zh): mirror #590 accuracy fixes — CLI exit code 2 scope, hook result contract, config defaults and untyped evals/routes

Chinese twins of the lane-C English corrections for the docsite audit:

- reference/cli.mdx: exit code 2 is only a Commander error (unknown option,
  missing argument, InvalidArgumentError from --profile/--allow/doctor --host);
  the install <host>/--scope/--mode/--port/--trials validators throw a plain
  TypeError that runCli reports as one AB5000 diagnostic with exit 1.
- guide/authoring/hooks.mdx: outcome is continue or deny (no event accepts
  stop); agentStop additionalContext is rejected on Codex and Cursor, only
  Claude Code carries it; the typed contract rejects an agentStart denial
  while Cursor's wrapper tolerates one with a reason.
- reference/configuration.mdx: targets defaults to ['portable'] (--target
  overrides), marketplace defaults to false; evals and routes ride the
  index signature so tsc does not check them — evals rules fire at eval time
  (EVAL_CONFIG_INVALID), routes overrides are validated during route
  discovery and reported through validateSource.

Prose only; no fenced code block, heading, table row, or AB code set changed.

* docs(website): nav matcher excludes reference/api; drift check normalises regex alternatives

* docs(diagnostics): document every emitted AB6000–AB9999 code (#590, lane B2)

Add explicit rows or explicit ranges for the 121 agent-bundle codes in
AB6000–AB9999 that only a family row covered: built-artifact validation
(AB6000–AB6004, AB6006–AB6018, AB6023–AB6025), Workbench artifact
inspection (AB6200–AB6202), install/uninstall and project-preparation
codes (AB7000–AB7004), the AB7103 package-build warning, the whole
AB80xx development-server surface grouped by route module, the
route-manifest client code AB8123, and the eval API refusals
AB9001–AB9005/AB9007–AB9011. Refine the AB6xxx–AB9xxx family rows.
AB6005 is left untouched for PR #588.

* fix(website): patch @rspress/core LocalProvider.init to await FlexSearch indexing (#590)

LocalProvider.init() fired addAsync() for every document without awaiting,
so SearchPanel flipped initStatus to 'inited' while FlexSearch was still
indexing and an early query rendered 'No matching results' for documents
that had not been added yet (8/8 trials with a late-indexed query on the
971-document en index). Collect the three addAsync promises per item and
await them before init() resolves; PageSearcher hard-codes the provider, so
a pnpm patch is the smallest fix. Upstream main still has the bug.

* fix(website): edit links, llms rows, 404 trailing slash, and code width in the docsite theme (#590)

- EditLink: return null on TypeDoc pages (<lang>/api/**), point the
  generated reference pages at their sources (capabilities JSON directory
  for hosts/events/notices, docs/diagnostics.md for diagnostics), and defer
  to the original everywhere else. The patterns track .gitignore lines 20-27.
- LlmsCopyRow / LlmsOpenRow / LlmsHint: render nothing when the route path
  includes /api/, mirroring the pluginLlms exclude, so the outline no longer
  offers Copy Markdown / Open in chat for the 1,832 routes that have no
  Markdown twin.
- NotFoundLayout: cleanUrls emits quick-start.html, so a trailing-slash URL
  is a 404 on GitHub Pages; retry without the slash (query and hash kept).
- Desktop layout tokens (>= 1280px): sidebar 320 -> 280, outline 268 -> 240,
  content padding 80 -> 48. At 1440x900 the code scroller grows from 686 to
  818 px, so 92 monospace columns fit (was 76 once Shiki's line padding is
  paid) and a 90-column line no longer scrolls; overflowing fences on the 33
  authored en pages drop from 59/169 to 23/169, all of them >= 93 columns.

* docs(diagnostics): explicit AB6005 row (restates #588) so every emitted code has a row

* changeset: diagnostics contract rows (#599)

* docs(diagnostics): shorten the install-receipt placeholder so the fence fits 90 columns

* chore(patches): cite upstream rspress#3658 beside the @rspress/core patch

* review: built-link check rejects targets outside doc_build; changeset says recovery where the diagnostic carries one

Author: ScriptedAlchemy

.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

docs/diagnostics.md

@@ -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",

package.json

@@ -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;

patches/@rspress__core@2.0.21.patch

@@ -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

pnpm-lock.yaml

@@ -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"
   }
 ]

pnpm-workspace.yaml

@@ -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
   }
 ]