docs(website): TypeDoc router 'module' — one API page per entry point (#590)

.github/dependabot.yml

@@ -4,6 +4,14 @@ updates:
     directory: /
     schedule:
       interval: weekly
+    groups:
+      # website/ pins @rspress/core and @rspress/shared to the same exact
+      # version: plugins/mirror-api-locale.ts imports the slugger Rspress runs
+      # from @rspress/shared/github-slugger so heading ids match byte for byte,
+      # which only holds while the two move together. One PR per release.
+      rspress:
+        patterns:
+          - '@rspress/*'
     ignore:
       # typescript@7.0.x is a native compiler: import('typescript') is only
       # { version, versionMajorMinor }. website/rspress.config.ts,

website/docs/en/api/_meta.json

@@ -1,39 +1,82 @@
 [
-  "index",
   {
-    "type": "dir",
-    "name": "modules",
-    "label": "Modules",
-    "collapsed": true
+    "type": "file",
+    "name": "index",
+    "label": "agent-bundle"
   },
   {
-    "type": "dir",
-    "name": "functions",
-    "label": "Functions",
-    "collapsed": true
+    "type": "file",
+    "name": "index-1",
+    "label": "index"
   },
   {
-    "type": "dir",
-    "name": "classes",
-    "label": "Classes",
-    "collapsed": true
+    "type": "file",
+    "name": "config",
+    "label": "config"
   },
   {
-    "type": "dir",
-    "name": "interfaces",
-    "label": "Interfaces",
-    "collapsed": true
+    "type": "file",
+    "name": "api",
+    "label": "api"
   },
   {
-    "type": "dir",
-    "name": "types",
-    "label": "Type aliases",
-    "collapsed": true
+    "type": "file",
+    "name": "app",
+    "label": "app"
   },
   {
-    "type": "dir",
-    "name": "variables",
-    "label": "Variables",
-    "collapsed": true
+    "type": "file",
+    "name": "routes/public",
+    "label": "routes/public"
+  },
+  {
+    "type": "file",
+    "name": "test",
+    "label": "test"
+  },
+  {
+    "type": "file",
+    "name": "test/browser",
+    "label": "test/browser"
+  },
+  {
+    "type": "file",
+    "name": "eval",
+    "label": "eval"
+  },
+  {
+    "type": "file",
+    "name": "rstest",
+    "label": "rstest"
+  },
+  {
+    "type": "file",
+    "name": "mcp-apps",
+    "label": "mcp-apps"
+  },
+  {
+    "type": "file",
+    "name": "mcp-entry",
+    "label": "mcp-entry"
+  },
+  {
+    "type": "file",
+    "name": "cli-entry",
+    "label": "cli-entry"
+  },
+  {
+    "type": "file",
+    "name": "serve-app-command",
+    "label": "serve-app-command"
+  },
+  {
+    "type": "file",
+    "name": "launch-env",
+    "label": "launch-env"
+  },
+  {
+    "type": "file",
+    "name": "meta",
+    "label": "meta"
   }
 ]

website/docs/en/guide/authoring/index.mdx

@@ -102,7 +102,7 @@ handlers only. The adapter-owned fields are:
 | `claude` (`ClaudeHostConfig`) | `bin`, `channels`, `defaultEnabled`, `dependencies`, `displayName`, `lspServers`, `marketplace`, `metadata`, `monitors`, `outputStyles`, `settings`, `themes`, `userConfig`, `workflows` | `bin`, `outputStyles`, and `workflows` are project directories copied to the plugin-root conventions of the same name; `channels`, `dependencies`, `defaultEnabled`, `displayName`, `metadata`, and `userConfig` are validated into `.claude-plugin/plugin.json` (`channels` must name servers in the emitted `.mcp.json`); `marketplace` enriches the generated marketplace entry; `monitors` and `themes` are experimental and emit `monitors/monitors.json` and one `themes/<key>.json` per key; `lspServers` and `settings` are described below. |
 | `codex` (`CodexHostConfig`) | `apps`, `author`, `homepage`, `interface`, `keywords`, `license`, `marketplace`, `repository` | `author`, `homepage`, `keywords`, `license`, and `repository` are publisher metadata in `.codex-plugin/plugin.json`; `interface` (brand color, category, capabilities, composer icon, default prompts, developer name, …) is merged over the compiler's generated install-surface defaults; `apps` maps registered MCP connection ids into the root `.app.json` compatibility document; `marketplace` authors the emitted `.agents/plugins/marketplace.json` entry — `category` (defaults to the interface category), `displayName` (defaults to the plugin name), and `policy` with `installation` (`AVAILABLE`, `INSTALLED_BY_DEFAULT`, `NOT_AVAILABLE`) and `authentication` (`ON_INSTALL`, `ON_USE`); the source always stays the local plugin root, and any other key is an error rather than a silently shipped field. |
 | `cursor` (`CursorHostConfig`) | `author`, `category`, `homepage`, `keywords`, `license`, `minClientVersions`, `publisher`, `repository`, `tags` | Manifest metadata layered onto the generated `.cursor-plugin/plugin.json`, every field admitted by the pinned Cursor plugin schema. `author` is a closed `{ name, email? }` object (no `url`); `minClientVersions` maps client identifiers to strict `X.Y.Z` semver strings, e.g. `{ cursor: '3.13.0' }`, and anything else is an error. Cursor documents no `nativeHooks` surface, so `cursor` does not extend `AgentBundleHostConfig`. |
-| `portable` ([`PortableManifestConfig`](../../api/interfaces/index.PortableManifestConfig.md)) | `author`, `extensions`, `homepage`, `keywords`, `license`, `repository` | Agent Plugins 1.0.0 §5.4 metadata layered onto the emitted root `plugin.json`; `extensions` maps reverse-domain client namespaces to opaque object payloads (§8). Omitted fields are omitted from the manifest. |
+| `portable` ([`PortableManifestConfig`](../../api/index-1.md#portablemanifestconfig)) | `author`, `extensions`, `homepage`, `keywords`, `license`, `repository` | Agent Plugins 1.0.0 §5.4 metadata layered onto the emitted root `plugin.json`; `extensions` maps reverse-domain client namespaces to opaque object payloads (§8). Omitted fields are omitted from the manifest. |
 
 Everything else about a Cursor plugin is derived from the cross-host model. The host capability
 tables in the [host reference](../../reference/hosts.md) record which of these surfaces each pinned

website/docs/en/guide/concepts/architecture.mdx

@@ -387,7 +387,7 @@ session identity the host did not supply.
 
 The writer is `build/build.ts` `manifestFor`. It assembles an
 `ArtifactManifest` (`build/manifest.ts`; TypeDoc:
-[`ArtifactManifest`](../../api/interfaces/index.ArtifactManifest.md)) and
+[`ArtifactManifest`](../../api/index-1.md#artifactmanifest)) and
 `writeManifest` serializes it with `assembleArtifactManifest`: canonical
 `stableJson` plus a trailing newline. `parseArtifactManifest` rejects any other byte sequence, duplicate
 keys, unknown keys, missing keys, unsorted arrays, and a file entry that

website/docs/en/guide/development/evaluations.mdx

@@ -51,9 +51,9 @@ npx agent-bundle eval compare <baseline-run-id> <candidate-run-id>
 resolved relative to the suite file and must not climb out of the suite directory (`../` past it
 is rejected; the check is on the path, so a symlink inside the suite is followed wherever it
 points). `agent-bundle/eval`
-exports its contract: [`EvalGraderFunction`](../../api/types/eval.EvalGraderFunction.md) takes an
-[`EvalGraderContext`](../../api/interfaces/eval.EvalGraderContext.md) and returns an
-[`EvalScriptOutcome`](../../api/interfaces/eval.EvalScriptOutcome.md), synchronously or as a
+exports its contract: [`EvalGraderFunction`](../../api/eval.md#evalgraderfunction) takes an
+[`EvalGraderContext`](../../api/eval.md#evalgradercontext) and returns an
+[`EvalScriptOutcome`](../../api/eval.md#evalscriptoutcome), synchronously or as a
 promise. This is `examples/skills-starter/evals/graders/release-result.ts` verbatim; the suite
 above names `./graders/status-result.ts`, which has the same shape in `examples/mcp-app`:
 

website/docs/en/reference/api.mdx

@@ -1,5 +1,5 @@
 ---
-description: 'The generated agent-bundle type API: which entry points it covers, how it is produced, and why generated symbol documentation is language-neutral.'
+description: 'The generated agent-bundle type API: one page per public entry point, how members are addressed, and why generated symbol documentation is language-neutral.'
 ---
 
 # Type API
@@ -9,36 +9,53 @@ The symbol-level reference is **generated from the source**, not written by hand
 
 ## What it covers
 
-Every public entry point is documented from its declarations:
-
-| Entry point | Contents |
-| --- | --- |
-| `agent-bundle` | The authoring and orchestration surface: `defineSkill`, `canonicalAgentEvents`, `startDevServer`, `runEvals`, `compareEvals`, the eval harness factories, and the artifact-manifest helpers. |
-| `agent-bundle/api` | The programmatic compiler: `build`, `validate`, `inspect`, `prepack`, their option and result types, the `AgentComponentKind` / `componentKindCapability` component-kind helpers, and the artifact operations `listMcp`, `invokeMcp`, `runMcp`, `serveApp` (a built MCP App served standalone in a browser — a host-process API for scripts and tests; a routed CLI command inside the artifact uses `spawnServeApp` from `agent-bundle/serve-app-command` instead, see [Serving an App standalone](../guide/authoring/mcp.mdx#serving-an-app-standalone)), `listHooks`, and `simulateHook`; plus the Rspack stats formatters `rspackStatsErrors`, `describeRspackStatsError`, and `formatRspackStatsError`, which render a compile error as the same `<file>:<line>:<column>: <message>` line the compiler's `AB4770` carries, for tools that drive their own Rsbuild compile. |
-| `agent-bundle/app` | The browser-safe MCP App client: `createAppClient`, the `AppClient` lifecycle (`connect`, `call`, `request`, `onToolInput`, `onToolResult`, `onToolError`, `onToolCancelled`, `rebind`, `dispose`), `AppClientError` and its `code` union for every wire and lifecycle failure (option misuse is a plain `TypeError` or `RangeError`), the `AppRegister` interface the generated `.agent-bundle/routes.d.ts` augments with the project's `tool:<server>/<name>` contracts, `AppRouteId` / `AppRouteInput` / `AppRouteResult`, the injectable `AppWindow` / `AppMessageTarget` ports, and `APP_PROTOCOL_VERSION`. Imports nothing from Zod, Node, or the compiler; for App views only. |
-| `agent-bundle/config` | `defineConfig` and the configuration types. |
-| `agent-bundle/test` | The route-testing harness, matchers, and contract matrices. |
-| `agent-bundle/test/browser` | The MCP App bridge harness for browser-rendered views. |
-| `agent-bundle/eval` | Eval suite definitions, assertions, and run comparison. |
-| `agent-bundle/rstest` | The Rstest configuration helper. |
-| `agent-bundle/meta` | The build-time project identity constant, replaced by the compiler in every compiled surface. |
-| `agent-bundle/mcp-apps` | The MCP App resource registry contract, replaced by the compiler in local MCP servers. |
-| `agent-bundle/cli-entry` | The routed-CLI shell every generated CLI executable is built on. |
-| `agent-bundle/mcp-entry` | The stdio MCP entry shell every generated MCP server is wrapped in. |
-| `agent-bundle/launch-env` | The operator `.env` layer every emitted shell applies at launch (`applyOperatorEnv`, `parseOperatorEnv`, `AGENT_BUNDLE_ENV_FILE`), for hand-rolled entries that want the same behavior. |
-| `agent-bundle/serve-app-command` | Plain Node, no dependencies: `spawnServeApp`, `serveAppArgv`, `locateFrameworkCli`, `parseServeAppReadyLine`, `serveAppAllowCapabilities`, `ServeAppCommandError`, and their types — a routed CLI command (or any other generated executable) serves a built MCP App by spawning `agent-bundle serve-app` instead of importing `serveApp`. |
-| `agent-bundle/routes` | The route-module authoring types (`AgentEventRouteProps`, `ToolRouteProps`, `CliRouteProps`, the `config` shapes) and `appResourceUri`, the static reference to a sibling MCP App the compiler resolves to its `resourceUri`. |
+Every public entry point is documented from its declarations, one page per entry point:
+
+| Entry point | Module page | Contents |
+| --- | --- | --- |
+| `agent-bundle` | [index](/api/index-1) | The authoring and orchestration surface: `defineSkill`, `canonicalAgentEvents`, `startDevServer`, `runEvals`, `compareEvals`, the eval harness factories, and the artifact-manifest helpers. |
+| `agent-bundle/api` | [api](/api/api) | The programmatic compiler: `build`, `validate`, `inspect`, `prepack`, their option and result types, the `AgentComponentKind` / `componentKindCapability` component-kind helpers, and the artifact operations `listMcp`, `invokeMcp`, `runMcp`, `serveApp` (a built MCP App served standalone in a browser — a host-process API for scripts and tests; a routed CLI command inside the artifact uses `spawnServeApp` from `agent-bundle/serve-app-command` instead, see [Serving an App standalone](../guide/authoring/mcp.mdx#serving-an-app-standalone)), `listHooks`, and `simulateHook`; plus the Rspack stats formatters `rspackStatsErrors`, `describeRspackStatsError`, and `formatRspackStatsError`, which render a compile error as the same `<file>:<line>:<column>: <message>` line the compiler's `AB4770` carries, for tools that drive their own Rsbuild compile. |
+| `agent-bundle/app` | [app](/api/app) | The browser-safe MCP App client: `createAppClient`, the `AppClient` lifecycle (`connect`, `call`, `request`, `onToolInput`, `onToolResult`, `onToolError`, `onToolCancelled`, `rebind`, `dispose`), `AppClientError` and its `code` union for every wire and lifecycle failure (option misuse is a plain `TypeError` or `RangeError`), the `AppRegister` interface the generated `.agent-bundle/routes.d.ts` augments with the project's `tool:<server>/<name>` contracts, `AppRouteId` / `AppRouteInput` / `AppRouteResult`, the injectable `AppWindow` / `AppMessageTarget` ports, and `APP_PROTOCOL_VERSION`. Imports nothing from Zod, Node, or the compiler; for App views only. |
+| `agent-bundle/config` | [config](/api/config) | `defineConfig` and the configuration types. |
+| `agent-bundle/test` | [test](/api/test) | The route-testing harness, matchers, and contract matrices. |
+| `agent-bundle/test/browser` | [test/browser](/api/test/browser) | The MCP App bridge harness for browser-rendered views. |
+| `agent-bundle/eval` | [eval](/api/eval) | Eval suite definitions, assertions, and run comparison. |
+| `agent-bundle/rstest` | [rstest](/api/rstest) | The Rstest configuration helpers `agentBundleRstest` and `agentBundleBrowserRstest`. |
+| `agent-bundle/meta` | [meta](/api/meta) | The build-time project identity constant, replaced by the compiler in every compiled surface. |
+| `agent-bundle/mcp-apps` | [mcp-apps](/api/mcp-apps) | The MCP App resource registry contract, replaced by the compiler in local MCP servers. |
+| `agent-bundle/cli-entry` | [cli-entry](/api/cli-entry) | The routed-CLI shell every generated CLI executable is built on. |
+| `agent-bundle/mcp-entry` | [mcp-entry](/api/mcp-entry) | The stdio MCP entry shell every generated MCP server is wrapped in. |
+| `agent-bundle/launch-env` | [launch-env](/api/launch-env) | The operator `.env` layer every emitted shell applies at launch — `applyOperatorEnv`, `parseOperatorEnv`, and the `OPERATOR_ENV_FILE_*` constants behind the `AGENT_BUNDLE_ENV_FILE` variable — for hand-rolled entries that want the same behavior. |
+| `agent-bundle/serve-app-command` | [serve-app-command](/api/serve-app-command) | Plain Node, no dependencies: `spawnServeApp`, `serveAppArgv`, `locateFrameworkCli`, `parseServeAppReadyLine`, `serveAppAllowCapabilities`, `ServeAppCommandError`, and their types — a routed CLI command (or any other generated executable) serves a built MCP App by spawning `agent-bundle serve-app` instead of importing `serveApp`. |
+| `agent-bundle/routes` | [routes/public](/api/routes/public) | The route-module authoring types (`AgentEventRouteProps`, `ToolRouteProps`, `CliRouteProps`, the `config` shapes) and `appResourceUri`, the static reference to a sibling MCP App the compiler resolves to its `resourceUri`. |
 
 Because it is generated, it always matches the shipped types: signatures, unions, defaults, and
 the error classes each surface can throw. When this Reference section and the generated pages
 disagree, the generated pages are correct.
 
+## How the pages are organized
+
+[/api/](/api/) lists the modules. Each module page is named after the entry point's source file
+(`agent-bundle/routes` is compiled from `routes/public.ts`, so its page is `routes/public`; the
+root `agent-bundle` export is `index`, served at `/api/index-1` because `/api/` is the module
+index itself) and groups its members under `Classes`, `Interfaces`, `Type Aliases`, `Variables`,
+and `Functions`. A name an entry point re-exports from another entry point is listed under
+`References` with a link to the page that documents it — `runEvals` on `index` points to
+[`runEvals`](/api/api#runevals) on `api`.
+
+Every member is a heading, so it has a URL: `/api/<module>#<member>`, the fragment being the name
+lowercased with `()` dropped — [`/api/eval#defineevalsuite`](/api/eval#defineevalsuite) documents
+`defineEvalSuite`. Ids are unique per page: when the same text already appears higher up — a
+property named `build`, or `AgentEventPayloadFields` beside `agentEventPayloadFields` — the later
+heading is suffixed, so `build` in `agent-bundle/api` is [`#build-2`](/api/api#build-2). The `#`
+link beside each heading carries its exact id.
+
 ## Generated pages are language-neutral
 
 The site mirrors the generated reference under both locales, so [/api/](/api/) and
 [/zh/api/](/zh/api/) resolve for readers of either language. The **content** is not translated:
-the symbol documentation is extracted from source comments and stays in the language it was
-authored in.
+the Chinese copy is the English Markdown with a notice under each page title saying so, and the
+symbol documentation stays in the language it was authored in.
 
 That is deliberate. A translated copy of generated output would drift from the source on the first
 refactor, and a symbol reference whose types are current but whose prose is stale is worse than
@@ -47,8 +64,8 @@ this Reference — are complete translations.
 
 ## Where to start
 
-- Compiling from a script: `build` and `validate` in `agent-bundle/api`.
+- Compiling from a script: [`build`](/api/api#build-2) and [`validate`](/api/api#validate-1) in `agent-bundle/api`.
 - Calling typed tools from an MCP App: `createAppClient` in `agent-bundle/app`, explained in
   [The typed App client](../guide/authoring/mcp.mdx#the-typed-app-client).
-- Writing tests: `renderRoute`, `expectDocument`, and the matrices in `agent-bundle/test`, explained in [Testing](../guide/development/testing.mdx).
-- Writing evals: `defineEvalSuite` and the assertions in `agent-bundle/eval`, explained in [Evaluations](../guide/development/evaluations.mdx).
+- Writing tests: [`renderRoute`](/api/test#renderroute), [`expectDocument`](/api/test#expectdocument), and the matrices in `agent-bundle/test`, explained in [Testing](../guide/development/testing.mdx).
+- Writing evals: [`defineEvalSuite`](/api/eval#defineevalsuite) and the assertions in `agent-bundle/eval`, explained in [Evaluations](../guide/development/evaluations.mdx).