{
  "version": 1,
  "generatedBy": "Silen",
  "pages": [
    {
      "route": "/ai/agent-contract/",
      "title": "Agent Contract",
      "markdown": "# Agent Contract\n\nThe Agent Contract is a versioned, inspectable discovery layer. It keeps AI\nclients from guessing configuration fields, CLI syntax, MCP permissions, or\ndeployed site routes.\n\n## Installed package contract\n\nFor creating or maintaining a local project, start at:\n\n```text\n@aicode-nexus/silen/agent/manifest.json\n```\n\nThe package manifest points to the exact version’s configuration API, CLI and\nMCP contracts, public TypeScript exports, guide, and task playbooks. For\nexample, `agent/tasks/create-site.md` describes the supported activation path\nand links back to authoritative machine-readable resources rather than copying\ntheir definitions.\n\n## Deployed site contract\n\nEach enabled production build publishes a site-specific entry point at\n`/.well-known/silen/manifest.json`, resolved under `base`. This official site’s\nlive contract is [the Silen manifest](/silen/.well-known/silen/manifest.json).\nThe manifest schema has no deployment origin field. It describes the base,\nlanguage, resources, tasks, and public project guidance. Resource and task URLs\nremain base-relative.\n\n```ts\nai: {\n  contract: {\n    enabled: true,\n    instructions: '.silen/ai-public.md',\n    tasksDir: '.silen/ai-tasks',\n  },\n}\n```\n\nInstructions and tasks are explicit public build input. Do not include local\nabsolute paths, secrets, private endpoints, credentials, or unpublished\noperating details.\n\n## Schema version 2\n\nThe current manifest and API documents use `schemaVersion: 2`. The manifest's\nMCP capability declares `stdio`, protocol versions `2025-11-25` and\n`2026-07-28`, an empty extension list, local-only operation, read-only default,\nand the `--allow-write` gate. The API document adds an `outputSchema` for every\ntool. Successful MCP calls expose the corresponding schema-validated\n`structuredContent` alongside text.\n\nThis contract does not advertise remote transport or optional MCP extensions.\nThose capabilities require separate designs and authorization.\n\nThe package also contains the generated filesystem Skill at\n`dist/agent/skills/silen-docs-readonly`, and the CLI API records `silen ai\nskills` plus `--experimental-skills-over-mcp`. The default manifest still says\n`extensions: []` because an optional runtime flag is not a site capability.\nSkill text is procedural knowledge: it does not grant a host permission to run\ncommands, use the network, write files, commit, push, or deploy.\n\n## Client behavior\n\nCodex, Claude Code, Cursor, and other clients should consume the same manifest\ninstead of keeping client-specific API copies. When a client does not support\nthe declared contract schema, it must follow linked public Markdown and remain\nread-only. For deployed content, the site manifest is authoritative; for code\ngeneration against an installed package, the package contract is authoritative.\n\nContinue with the [local workspace and MCP](/silen/ai/local-workspace-mcp/).\n",
      "description": "Give AI clients one versioned discovery surface for Silen projects and sites."
    },
    {
      "route": "/ai/",
      "title": "AI-ready documentation",
      "markdown": "# AI-ready documentation\n\nSilen treats AI access as part of the documentation build instead of an\nafterthought. The default output is deterministic, inspectable, and does not\ncall a model. No model, API key, endpoint, embeddings service, or network is\nrequired for the core AI-ready documentation workflow.\n\n## Agent Contract\n\nSilen gives an AI one versioned discovery entry point instead of making every\nclient memorize a separate tutorial:\n\n- For a local project, begin with\n  `@aicode-nexus/silen/agent/manifest.json` from the installed package. It links\n  to the exact config, CLI, MCP, and public TypeScript API plus task playbooks\n  such as `agent/tasks/create-site.md`.\n- For a deployed site, begin with\n  `/.well-known/silen/manifest.json`. This official site publishes it at\n  `/silen/.well-known/silen/manifest.json`.\n- For bounded local reads, start `pnpm silen mcp docs`. It is read-only unless\n  the user explicitly adds `--allow-write`.\n\nCodex, Claude Code, and Cursor should all read that same manifest and use the\nsame local MCP command. Client setup stays thin; the contract remains the\nsingle API reference.\n\nIf a client does not support the declared schema version, it must fall back to\nthe linked public Markdown and remain read-only.\n\nThe current manifest and API use `schemaVersion: 2`. They declare local\n`stdio`, verified protocol versions `2025-11-25` and `2026-07-28`, an empty\nextension set, and every MCP tool's `outputSchema`.\n\n## Read-only Agent Skill\n\nThe npm package deterministically generates one `silen-docs-readonly` Agent\nSkill from the canonical English and Chinese `read-site` and `audit-site` task\npacks. Its package root is `dist/agent/skills/silen-docs-readonly`; it contains\n`SKILL.md` plus four progressively loaded references and no scripts, assets,\nwrite tasks, model calls, credentials, or implied permissions.\n\n```sh\npnpm silen ai skills ./agent-skills\n```\n\nThe command creates only `./agent-skills/silen-docs-readonly` and refuses to\noverwrite an existing directory. The filesystem form is the supported portable\nsurface and remains usable offline.\n\n## Add public project instructions\n\nOnly publish instructions that are safe for every site visitor:\n\n```ts\nexport default defineConfig({\n  ai: {\n    contract: {\n      instructions: '.silen/ai-public.md',\n      tasksDir: '.silen/ai-tasks',\n    },\n  },\n})\n```\n\nThese files become explicit public Agent instructions. Never place private\npaths, secrets, internal endpoints, or credentials in them.\n\n## Public AI artifacts\n\nEach production build can emit:\n\n- `llms.txt` for a concise page map\n- `llms-full.txt` for complete readable content\n- `ai-index.json` for structured discovery\n- clean Markdown routes for every public page\n\nPages marked `draft: true` or `ai: false` are excluded from these artifacts.\n\n## Copy for AI\n\nThe default theme lets readers copy clean page Markdown or a prompt-ready\nversion with the canonical source URL. The copied content comes from the same\nbuild artifacts, so it stays aligned with the rendered page.\n\n## Local MCP workspace\n\n```sh\npnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen mcp docs\n```\n\nThe MCP server uses the split SDK v2 and is read-only by default. Write tools\nappear only when it is started explicitly with `--allow-write`, and all writes\nremain inside the Markdown workspace. Successful calls return text plus\nschema-validated `structuredContent`; remote transport is not enabled.\n\n## Model-free quality gate\n\nUse the production search index itself as a deterministic retrieval contract:\n\n```sh\npnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs\n```\n\n`ai eval` reads the committed `.silen/ai-evals.json` suite and the built\n`.silen/dist/search-index.json`; it never calls a model or the network. Exit\ncodes `0`, `1`, and `2` mean pass, retrieval failure, and setup failure.\n\nVersion 1 keeps whole-`topK` matching. Version 2 adds optional\n`expected.maxRank` and reports its effective value plus `matchedRank`. Strict\n`\"schemaVersion\": 3` requires both target arrays and an explicit rank bound:\n\n```json\n{\n  \"schemaVersion\": 3,\n  \"topK\": 5,\n  \"cases\": [\n    {\n      \"id\": \"install-quick-start\",\n      \"query\": \"How do I install and start a site?\",\n      \"expected\": {\n        \"acceptable\": [\n          { \"route\": \"/guide/\", \"heading\": \"Quick start\" },\n          { \"route\": \"/guide/cli-deployment/\" }\n        ],\n        \"forbidden\": [{ \"route\": \"/draft-notes/\" }],\n        \"maxRank\": 1\n      }\n    }\n  ]\n}\n```\n\n`acceptable` and `forbidden` are both present arrays with zero to 20 targets;\nat least one must be non-empty. At least one acceptable target must appear at\nor before `maxRank`, and every forbidden target must stay out of the diagnostic\nTop K. A negative-only case uses `acceptable: []` and `maxRank: topK`. Unknown\nfields, overlapping targets, an empty combined target set, and invalid bounds\nare setup errors. Version 3 keeps authored case order and exposes `matchedRank`\nplus `forbiddenMatches`; v1 and v2 JSON and human output remain compatible.\n\nFor this repository, `pnpm site:ai-check` runs build, audit, evaluation, and\nsource-map checks once. It saves the exact JSON report to\n`artifacts/ai-eval/site-ai-eval.json` for CI, Pages, and release comparison.\n\nThe rebuildable `.silen/ai/index.json` workspace snapshot is optional. A\nmissing or stale snapshot appears as an audit notice while MCP search continues\nto run from its in-memory index.\n\n## Ask AI\n\nAsk AI is an optional endpoint integration. Silen never places provider keys in\nthe generated site: your server owns authentication and streams a small NDJSON\nprotocol back to the theme. With no explicitly configured endpoint, the Ask AI\ncontrol and its bundle remain absent.\n\nReturn to the [getting started guide](/silen/guide/).\n",
      "description": "Deterministic artifacts and a permission-gated local MCP workspace."
    },
    {
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "markdown": "# Local workspace and MCP\n\nThe local AI workspace is deterministic and model-free. It gives tools a\nbounded Markdown root, an inspectable index, and explicit write permission\nwithout exposing arbitrary shell execution. No model, API key, endpoint,\nembeddings service, or network is required.\n\n## Initialize, index, and audit\n\n```sh\npnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\n```\n\n`ai init` creates `wiki/` and the ignored `.silen/ai/` cache without changing\nexisting MDX. `ai index` rebuilds the optional `.silen/ai/index.json` workspace\nsnapshot. `ai audit` checks links, citations, generated artifacts, and the\nproduction contract. A missing or stale snapshot is only a notice because MCP\nsearch uses an in-memory index.\n\n## Build, audit, and evaluate\n\n```sh\npnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs\n```\n\n`ai eval` reads `.silen/ai-evals.json` and the production\n`.silen/dist/search-index.json`; it neither starts MCP nor calls a model or the\nnetwork. Version 1 uses one route and optional heading within `topK`. Version 2\nadds optional `expected.maxRank`. Strict `\"schemaVersion\": 3` requires present\n`acceptable` and `forbidden` arrays, at least one target between them, and an\nexplicit `maxRank` from 1 through `topK`. Negative-only cases use\n`acceptable: []` and `maxRank: topK`.\n\nVersion 3 reports `matchedRank: null` when no acceptable target appears and\nlists prohibited hits in `forbiddenMatches`. Exit `0` means every case passed,\nexit `1` means a retrieval expectation failed, and exit `2` means the suite or\ninput is invalid. The full diagnostic Top K remains in stable case order.\n\nFor the Silen repository, `pnpm site:ai-check` composes the complete read-only\ngate and saves exact evaluation JSON at\n`artifacts/ai-eval/site-ai-eval.json`. The optional `.silen/ai/index.json`\nsnapshot remains non-blocking and does not replace the production search index.\n\n## Connect an MCP client\n\nRun the server from the repository root:\n\n```json\n{\n  \"mcpServers\": {\n    \"silen\": {\n      \"command\": \"pnpm\",\n      \"args\": [\"silen\", \"mcp\", \"docs\"]\n    }\n  }\n}\n```\n\nThe default server registers seven read-only tools: `guide`, `list`, `search`,\n`read`, `backlinks`, `citations`, and `build`. The `build` tool is a bounded\npreflight: it reads Markdown inputs and existing artifacts but does not load\nproject config, execute MDX, invoke Vite, or write files.\n\n## Protocol and structured results\n\nThe command uses the stable split TypeScript SDK v2. One `stdio` entry accepts\nverified legacy `2025-11-25` and modern `2026-07-28` clients; see the\n[official protocol-version guide](https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions).\nThe server is read-only by default. Every successful tool call includes text\nand schema-validated `structuredContent`, and every listed tool declares an\n`outputSchema`. Remote transport is not enabled.\n\nFor the string-valued `guide` tool, modern clients receive the native string;\nlegacy clients receive the SDK's compatibility `{ result: ... }` object. The\nobject-valued tools keep their existing structured shape in both eras.\n\n## Experimental Skills over MCP\n\nFilesystem installation does not require MCP. Hosts that explicitly support\nthe draft Resources binding can opt into the same packaged bytes:\n\n```sh\npnpm silen mcp docs --experimental-skills-over-mcp\n```\n\nThe experiment declares `io.modelcontextprotocol/skills`, serves\n`skill://index.json`, and maps the five files beneath\n`skill://silen-docs-readonly/`. It is local stdio only and read-only. The\nexperiment is off by default. It adds no tools, scripts, subscriptions, network\ntransport, or write authority; `--allow-write` remains a separate explicit\ntool-registration flag.\n\n## Grant writes deliberately\n\n```sh\npnpm silen mcp docs --allow-write\n```\n\nThis explicit flag adds `write`, `link`, and `append`. Writes accept only\nworkspace-relative `.md` or `.mdx` paths, reject traversal and escaping\nsymlinks, use atomic replacement, and enforce a 2 MiB UTF-8 limit. It never\nadds a shell tool.\n\nGrant write mode only to a trusted local client for a bounded task. After a\nchange, run the audit and site build, inspect the Git diff, and obtain separate\nauthorization before committing or deploying.\n\nAsk AI is separate: it requires an explicitly configured endpoint. With no\nendpoint, Silen emits neither the control nor its bundle.\n\nRead [Agent Contract](/silen/ai/agent-contract/) for client discovery rules.\n",
      "description": "Index, audit, and expose a bounded documentation workspace to local AI clients."
    },
    {
      "route": "/guide/cli-deployment/",
      "title": "CLI and deployment",
      "markdown": "# CLI and deployment\n\nSilen exposes a small CLI. Run it through the project package manager so the\ncommand and Agent Contract always match the installed version.\n\n## Primary commands\n\n```sh\npnpm silen init docs\npnpm silen dev docs --host 127.0.0.1 --port 5173\npnpm silen build docs\npnpm silen preview docs --port 4173\n```\n\n`init <root>` writes a starter config and homepage without replacing existing\ntargets. `dev [root]` starts Vite-backed development. `build [root]` creates the\nstatic output and exits after validation. `preview [root]` serves that output\nwith route and locale-aware 404 behavior. The server commands accept `--host`\nand `--port`; the build has no deployment side effects.\n\nAI workspace commands are separate:\n\n```sh\npnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen ai skills ./agent-skills\npnpm silen mcp docs\n```\n\n`ai skills` requires the parent destination, creates only\n`silen-docs-readonly`, and never overwrites it; optional MCP Resource exposure\nuses `pnpm silen mcp docs --experimental-skills-over-mcp` and remains\nexperimental and off by default.\n\nThe MCP command is read-only unless a trusted user explicitly starts it with\n`--allow-write`. The model-free `ai eval` command reads\n`.silen/ai-evals.json` and `.silen/dist/search-index.json`; use `--json` for CI.\nIt needs no model, API key, endpoint, embeddings service, or network.\n\nSuite `\"schemaVersion\": 1` retains whole-`topK` matching. Version 2 supports\ncase-specific `expected.maxRank`, defaulting to `topK`, and reports\n`matchedRank` while preserving the full diagnostic result list.\n\n## Static deployment\n\nPublish the contents of `docs/.silen/dist` to any static host. Configure the\nhost to serve generated `index.html` files and assets as written. For a project\nsite such as `https://example.github.io/handbook/`, use:\n\n```ts\nexport default defineConfig({\n  siteUrl: 'https://example.github.io',\n  base: '/handbook/',\n})\n```\n\nDo not repeat `/handbook/` in `siteUrl`. The build combines the origin and\nbase for canonical URLs, `hreflang` and `x-default` locale alternates, sitemap\nentries, and basic Open Graph/Twitter metadata. Markdown and Agent Contract\nURLs remain base-relative.\n\n## Release check\n\nRepository maintainers run one canonical command:\n\n```sh\npnpm site:ai-check\n```\n\nIt executes `site:build` -> `ai audit` -> `ai eval` -> `check:no-maps` once and\nin order. `pnpm site:check` is a compatibility alias. Core CI, GitHub Pages,\nand npm release all use the canonical command; an audit or evaluation failure\nblocks deployment or publication.\n\nThe official `.silen/ai-evals.json` uses `\"schemaVersion\": 3`, explicit\n`maxRank`, and present `acceptable` and `forbidden` target arrays. Reports keep\nthe diagnostic `topK`, stable `matchedRank`, and forbidden evidence. Each\nworkflow uploads `artifacts/ai-eval/site-ai-eval.json` with an always condition\nwhen the evaluator produced valid JSON, including retrieval failures or a\nlater source-map failure.\n\nThen preview a nested route directly, open a missing route, and inspect\n`llms.txt` plus `.well-known/silen/manifest.json`. A successful build proves\nfiles were generated; those direct checks prove the host serves them at the\nexpected base.\n\nAsk AI remains endpoint-only. If no endpoint is configured, its control and\nbundle are absent.\n\nUse [Reference](/silen/reference/) for command syntax and troubleshooting.\n",
      "description": "Run Silen commands and deploy static output under the correct base."
    },
    {
      "route": "/guide/configuration/",
      "title": "Configuration",
      "markdown": "# Configuration\n\nCreate `.silen/config.ts` in the content root and export `defineConfig(...)`.\nThe file is trusted project code; keep secrets out because values can affect\npublic HTML and build artifacts.\n\n```ts\nimport { defineConfig } from '@aicode-nexus/silen'\n\nexport default defineConfig({\n  title: 'Engineering handbook',\n  description: 'Operating knowledge for the product team.',\n  lang: 'en-US',\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  outDir: '.silen/dist',\n  onBrokenLinks: 'error',\n})\n```\n\n## URL and metadata fields\n\n`base` is the normalized absolute pathname where the site is mounted; use `/`\nfor a domain root or `/handbook/` for a subpath. `siteUrl` is only the HTTP(S)\norigin—put the deployment path in `base`, not in `siteUrl`. Together they drive\ncanonical links, `hreflang` and `x-default` locale alternates, the sitemap, and\nbasic Open Graph/Twitter metadata. Markdown and Agent Contract URLs remain\nbase-relative. `lang` is a BCP 47 language tag.\n\n## Navigation and locales\n\n`themeConfig.nav` and `themeConfig.sidebar` accept `{ text, link }` entries.\nRoot-relative theme links are resolved under `base`. Locale entries can provide\na `root`, translated navigation, sidebar, home hero, and message overrides:\n\n```ts\nthemeConfig: {\n  locales: [\n    { lang: 'en-US', label: 'English', root: '/' },\n    { lang: 'zh-CN', label: '中文', root: '/zh/' },\n  ],\n  search: true,\n}\n```\n\nKeep locale route trees mirrored so the language switch can preserve the\ncurrent route rather than returning to a homepage.\n\n## Integrations and AI\n\n`analytics` configures Google, Baidu, or custom scripts. `plugins` is an ordered\narray of trusted plugin factories. The `ai` booleans control `llms.txt`,\n`llms-full.txt`, Markdown routes, and `ai-index.json`; all default to enabled.\nThe Agent Contract is also enabled by default and can include explicit public\ninstructions and tasks.\n\n```ts\nai: {\n  llmsTxt: true,\n  llmsFullTxt: true,\n  markdownRoutes: true,\n  index: true,\n  contract: { enabled: true, instructions: '.silen/ai-public.md' },\n}\n```\n\nSee the complete field table in [Reference](/silen/reference/) and integration\nexamples in [Integrations](/silen/integrations/).\n",
      "description": "Configure routes, metadata, navigation, integrations, and AI output."
    },
    {
      "route": "/guide/",
      "title": "Quick start",
      "markdown": "# Quick start\n\nSilen turns a directory of Markdown and MDX into a server-rendered static site,\nlocal search, and deterministic AI-readable output. Use Node.js `^20.19.0 || >=22.12.0`.\n\n## Install and activate\n\nFrom your project root, install Silen, then activate a `docs` directory:\n\n```sh\npnpm add -D @aicode-nexus/silen\npnpm silen init docs\n```\n\nSilen installs its required `react` and `react-dom` runtime, including MDX's\n`react/jsx-runtime`, automatically.\n\n`init` creates `docs/.silen/config.ts` and `docs/index.mdx`. It is safe for a\nnew or existing directory: if either target already exists, Silen reports the\ncollision instead of overwriting authored content.\n\n## Develop\n\n```sh\npnpm silen dev docs\n```\n\nEdit `docs/index.mdx` or add another `.md` or `.mdx` file. File routes are\ncreated from the directory tree, and client navigation updates without a full\npage reload. Local search stays on the site; no hosted search account is\nrequired.\n\n## Build and inspect\n\n```sh\npnpm silen build docs\npnpm silen preview docs\n```\n\nThe default output directory is `docs/.silen/dist`. A build emits complete\nHTML plus AI artifacts such as `llms.txt`, `llms-full.txt`, `ai-index.json`,\nand clean Markdown routes. Draft pages and pages with `ai: false` remain out of\nthose AI-facing artifacts.\n\n## Make the first decision explicit\n\nSet `base` when the site will live below a host subpath, and set `siteUrl` to\nthe origin when canonical metadata is required:\n\n```ts\nexport default defineConfig({\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  onBrokenLinks: 'error',\n})\n```\n\nContinue with [project structure](/silen/guide/project-structure/),\n[configuration](/silen/guide/configuration/), or inspect the\n[live AI output](/silen/ai/).\n",
      "description": "Activate, run, and build a Silen documentation site."
    },
    {
      "route": "/guide/markdown-mdx/",
      "title": "Markdown and MDX",
      "markdown": "# Markdown and MDX\n\nUse Markdown for durable prose and MDX when a page benefits from a typed React\ncomponent. Both produce the same route, SSR HTML, search record, and optional\nAI-readable Markdown. GitHub-flavored Markdown tables, task lists,\nstrikethrough, autolinks, and footnotes keep the same meaning across each\noutput.\n\n## Frontmatter\n\nFrontmatter supplies page metadata and layout decisions:\n\n```md\n---\ntitle: Service runbook\ndescription: Diagnose and recover the checkout service.\nlayout: doc\nlang: en-US\nai: true\n---\n```\n\n`doc` is the default layout. `home` renders the configured hero before page\nMDX, and `page` keeps the application shell without documentation pagination.\n`draft: true` excludes the page from AI-readable artifacts and indexes only.\nIt does not stop route scanning, building, or publishing; `ai: false` has the\nsame AI-output boundary for an otherwise public page. Never store private\ncontent in the content tree. Keep confidential material outside the site root\nand its build inputs.\n\n## Links and headings\n\nPrefer stable site routes and descriptive link text. Under a non-root `base`,\ntheme-config links are base-aware automatically; authored root-relative links\nmust point at the mounted site path. During build, Silen validates internal page\ntargets and can fail, warn, or ignore according to `onBrokenLinks`.\n\nHeadings create the document outline. Keep one `#` title, then descend without\nskipping levels so the outline remains useful to keyboard and screen-reader\nusers.\n\n## Code and components\n\nFenced code blocks receive syntax highlighting and a keyboard-accessible copy\nbutton. Silen loads supported Shiki grammars on demand, including `mdx`,\n`python`, and JSON Lines for `ndjson` fences. Unknown language names safely\nfall back to plain text. MDX can import components and use expressions:\n\n```mdx\nimport Status from './components/status.tsx'\n\n## Current status\n\n<Status service=\"checkout\" />\n```\n\nMDX executes during the build and can import project code. Treat every MDX file\nand component as trusted source; Silen is not a sandbox for untrusted user\nsubmissions. Keep browser-only access inside effects or client setup so server\nrendering remains deterministic.\n\nFor site-wide components, extend the [default theme](/silen/theme/extensions-accessibility/).\n",
      "description": "Author trusted content, metadata, links, code, and React components."
    },
    {
      "route": "/guide/plugins",
      "title": "Plugins",
      "markdown": "# Plugins\n\nSilen plugins extend the documentation lifecycle without importing internal\nfiles. A plugin is a local or npm factory configured directly in\n`.silen/config.ts`:\n\n```ts\nimport { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst readingTime = definePlugin(\n  (_context, options: { wordsPerMinute: number }) => ({\n    name: 'reading-time',\n    transformPageData(page, context) {\n      const words = context.source.trim().split(/\\s+/).length\n      return {\n        data: {\n          ...page.data,\n          minutes: Math.max(1, Math.ceil(words / options.wordsPerMinute)),\n        },\n      }\n    },\n  }),\n)\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})\n```\n\n## Lifecycle\n\nSilen runs plugins in configuration order. The first release supports\n`config`, `configResolved`, `extendMdx`, `vite`, `clientModules`,\n`transformPageData`, `transformHead`, and `buildEnd`.\n\n- Use `extendMdx` for Remark and Rehype plugins.\n- Use `vite` for standard Vite integrations. `virtual:silen/*` modules remain\n  protected by core.\n- Use `transformPageData` for JSON-serializable metadata consumed by SSR,\n  hydration, search, and AI artifacts.\n- Use `transformHead` for typed `meta`, `link`, `script`, `style`, or\n  `noscript` entries.\n- Use `clientModules` for an SSR-safe `wrapRoot` and optional browser-only\n  `setup` function.\n- Use `buildEnd` to add files such as a sitemap after the output directory is\n  installed.\n\nEvery plugin needs a `name`; add a distinct `id` when configuring multiple\ninstances. Failures include the identity and hook, such as\n`Silen plugin analytics:docs failed in transformHead`.\n\n## SSR and compatibility\n\nClient modules are imported during SSR and hydration. Do not access `window` or\n`document` at module scope or inside `wrapRoot`; browser APIs belong in\n`setup`. Plugin packages should declare `@aicode-nexus/silen` as a peer\ndependency and import only documented public exports.\n\nSee the npm-ready sitemap, reading-time, and analytics-client examples in\n[`examples/plugins`](https://github.com/AICode-Nexus/silen/tree/main/examples/plugins).\n",
      "description": "Extend Silen through a stable, ordered lifecycle."
    },
    {
      "route": "/guide/project-structure/",
      "title": "Project structure",
      "markdown": "# Project structure\n\nA Silen site is a content root. Keep content and its site configuration\ntogether so local development, production builds, and AI tools all resolve the\nsame boundary.\n\n```text\ndocs/\n├── .silen/\n│   ├── config.ts\n│   ├── theme.tsx          # optional theme extension\n│   ├── ai-public.md       # optional public agent instructions\n│   └── dist/              # generated; do not author here\n├── public/\n│   └── logo.svg\n├── assets/\n│   └── architecture.png\n├── guide/\n│   └── index.mdx\n└── index.mdx\n```\n\n## Content becomes routes\n\nBoth `.md` and `.mdx` files are scanned. `index.mdx` has compiler route `/`;\n`guide.mdx` and `guide/index.mdx` both have compiler route `/guide`. The\ndirectory form emits `guide/index.html`, with the usual browser URL `/guide/`.\nDo not create both source forms for the same route; the build rejects duplicate\nroutes instead of choosing one silently.\n\nUse directories for sections that will grow. This keeps nearby images,\nexamples, and future child pages easy to locate while preserving stable URLs.\n\n## Configuration and theme\n\n`.silen/config.ts` is executable, trusted project configuration. It defines the\nsite title, base, locales, navigation, integrations, and generated AI output.\n`.silen/theme.tsx` is optional and should extend the default theme when only a\ncomponent, layout, or wrapper needs to change.\n\n## Static and imported assets\n\nPlace files that must keep a public filename under `public/` and reference them\nfrom the site root, for example `/logo.svg` in configuration. Silen resolves\ntheme links and images against the configured `base`. Import content-owned\nimages from MDX when they should participate in the Vite asset pipeline.\n\n## Generated state\n\n`.silen/dist` is the default production output and `.silen/.temp` is temporary\nbuild state. Treat both as disposable. The local AI workspace uses `wiki/` for\nauthored Markdown and `.silen/ai/` for its generated index; review the\n[workspace boundary](/silen/ai/local-workspace-mcp/) before enabling writes.\n\nNext, define the site in [configuration](/silen/guide/configuration/).\n",
      "description": "Organize Silen content, configuration, assets, and generated output."
    },
    {
      "route": "/",
      "title": "Silen",
      "markdown": "Activate one docs directory\nFrom folder to knowledge interface\n\n```sh\npnpm add -D @aicode-nexus/silen\npnpm silen init docs\npnpm silen dev docs\n```\n\nInspect the evidence\nLive output from this build\n\nllms.txt\nConcise corpus map\n\nllms-full.txt\nComplete readable corpus\n\nai-index.json\nStructured page discovery\n\nAgent manifest\nVersioned capability contract\n\nGuide Markdown\nClean route-level source\n\nOne source, three proofs\nUseful to readers, agents, and maintainers\n\nHuman reading\n\nAI consumption\n\nExtensibility\n\nOpen source, deliberately small\nBuild the documentation layer with us\n\nAI Dev Hub on WeChat\n",
      "description": "React documentation for people and AI."
    },
    {
      "route": "/integrations/",
      "title": "Integrations",
      "markdown": "# Integrations\n\nSilen keeps integrations explicit. Plugins run trusted build or client code,\nanalytics is configured at the site layer, and Ask AI talks only to an endpoint\nyou operate. None of these features requires importing internal Silen files.\n\n## Plugins\n\nPlugins are ordered factories in `.silen/config.ts`. Use them for MDX\nprocessors, Vite integrations, page metadata, head entries, client setup, or\npost-build output:\n\n```ts\nimport { defineConfig } from '@aicode-nexus/silen'\nimport readingTime from './plugins/reading-time'\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})\n```\n\nEvery plugin has a `name`; add an `id` for multiple instances. Hooks execute in\nconfiguration order and failures report the plugin identity plus hook. Read\nthe complete [plugin lifecycle](/silen/guide/plugins).\n\n## Analytics\n\nAnalytics is theme-independent and production-only. Configure Google, Baidu,\nor an ordered custom provider:\n\n```ts\nanalytics: [\n  { provider: 'google', id: 'G-XXXXXXXXXX' },\n  { provider: 'baidu', id: 'site-id' },\n]\n```\n\nSilen reports the initial page and later client-route changes while ignoring\nhash-only navigation. Google users should disable automatic history-change\npageviews in Enhanced Measurement to avoid duplicates. A custom provider can\nload external or inline scripts and listen for `silen:pageview`. Scripts are\ntrusted public code; never embed credentials.\n\n## Ask AI\n\nAsk AI is an optional theme endpoint, not a bundled model provider:\n\n```ts\nthemeConfig: {\n  ai: { endpoint: '/api/ask' },\n}\n```\n\n## Ask AI request\n\nSilen sends an HTTP `POST` with `Content-Type: application/json`. The request\ncontract is exactly:\n\n```ts\ninterface AskAiRequest {\n  route: string\n  selectedText?: string\n  messages: Array<{\n    role: 'user' | 'assistant'\n    content: string\n  }>\n}\n```\n\n`selectedText` is optional; omit it when the reader has not selected content.\nMessages can include prior user and assistant turns. A concrete request is:\n\n```json\n{\n  \"route\": \"/guide/\",\n  \"selectedText\": \"pnpm silen init docs\",\n  \"messages\": [\n    { \"role\": \"user\", \"content\": \"How do I start?\" },\n    { \"role\": \"assistant\", \"content\": \"Install the package first.\" }\n  ]\n}\n```\n\n## Ask AI response\n\nReturn a successful streaming response with either\n`Content-Type: application/x-ndjson` or `Content-Type: application/ndjson`.\nThis NDJSON response writes one JSON object per line. The event shapes are text\n`{ type: 'text', value: string }`, citation\n`{ type: 'citation', title: string, url: string }`, and error\n`{ type: 'error', message: string }`:\n\n```ndjson\n{\"type\":\"text\",\"value\":\"Install with pnpm.\"}\n{\"type\":\"citation\",\"title\":\"Quick start\",\"url\":\"/guide/\"}\n{\"type\":\"error\",\"message\":\"Unable to answer.\"}\n```\n\nSilen supplies an `AbortSignal` to the request and aborts a superseded stream\nor a stream whose dialog closes. Treat that signal and the disconnected HTTP\nrequest as cancellation: stop upstream provider work and release resources.\n\nYour endpoint owns server-side authentication. Keep provider keys and raw\nprovider errors on the server, and return a safe public failure instead. With\nno endpoint, Silen emits no Ask AI control and no Ask AI client bundle.\n\nFor deterministic, provider-free AI access, use the [generated artifacts](/silen/ai/)\nand [local MCP workspace](/silen/ai/local-workspace-mcp/).\n",
      "description": "Add plugins, analytics, and an optional Ask AI endpoint."
    },
    {
      "route": "/plugins/",
      "title": "Plugins",
      "markdown": "# Plugins\n\nThis route remains available for existing bookmarks. Silen’s plugin API is the\nordered, public extension boundary for build and client integrations. A plugin\nfactory is configured in `.silen/config.ts`, receives the current command and\nroot, and returns a named plugin.\n\n```ts\nimport { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst metadata = definePlugin(() => ({\n  name: 'product-metadata',\n  transformPageData(page) {\n    return { data: { ...page.data, product: 'checkout' } }\n  },\n}))\n\nexport default defineConfig({ plugins: [metadata] })\n```\n\nAvailable hooks cover configuration, resolved configuration, Remark/Rehype,\nVite, client modules, page data, head entries, and build completion. Hooks run\nin configuration order. Client modules must be safe during SSR: browser APIs\nbelong in `setup`, not module scope or `wrapRoot`. Plugin packages should use\n`@aicode-nexus/silen` as a peer dependency and import only documented exports.\n\nContinue to the canonical [plugin guide](/silen/guide/plugins) for lifecycle,\nidentity, failure, and packaging details, or see [Integrations](/silen/integrations/)\nfor analytics and Ask AI.\n",
      "description": "Compatibility entry for the Silen plugin lifecycle documentation."
    },
    {
      "route": "/reference/",
      "title": "Reference",
      "markdown": "# Reference\n\nThis page is the compact operational reference. Use the linked guides for\nexplanations and examples.\n\n## Configuration\n\n| Field | Default | Purpose |\n| --- | --- | --- |\n| `title` | `Silen` | Human-readable site title |\n| `description` | empty | Generated page metadata |\n| `lang` | `en-US` | Default BCP 47 language |\n| `base` | `/` | Normalized deployment pathname |\n| `siteUrl` | unset | Canonical HTTP(S) origin |\n| `outDir` | `.silen/dist` | Output relative to content root |\n| `onBrokenLinks` | `error` | `error`, `warn`, or `ignore` |\n| `themeConfig` | `{}` | Navigation, locales, home, search, Ask AI |\n| `analytics` | `[]` | Ordered production analytics providers |\n| `plugins` | `[]` | Ordered trusted plugin entries |\n| `ai.*` | enabled | AI files, Markdown routes, index, contract |\n\n`base` must start with `/`, contain no query/hash or traversal, and is\nnormalized with a trailing slash. `siteUrl` is an origin only, without\ncredentials, path, query, or fragment.\n\n## CLI\n\n| Command | Effect |\n| --- | --- |\n| `silen init <root>` | Safely create starter config and homepage |\n| `silen dev [root]` | Start development; accepts `--host`, `--port` |\n| `silen build [root]` | Validate and generate static output |\n| `silen preview [root]` | Serve output; accepts `--host`, `--port` |\n| `silen ai <init\\|index\\|audit\\|eval> [path]` | Manage and evaluate the local AI workspace |\n| `silen ai skills <destination>` | Materialize the packaged `silen-docs-readonly` Skill without overwrite |\n| `silen mcp [root]` | Serve read-only MCP; optional `--allow-write` and experimental `--experimental-skills-over-mcp` |\n\nThe package stores the portable Skill at\n`dist/agent/skills/silen-docs-readonly`. The URI\n`skill://silen-docs-readonly/SKILL.md` exists only when\n`--experimental-skills-over-mcp` is present; the default Agent Contract remains\n`extensions: []`.\n\n## MCP and Agent Contract\n\nThe local MCP command uses SDK v2 over `stdio` and verifies `2025-11-25` and\n`2026-07-28`. It exposes seven read-only tools by default and three additional\nwrite tools with `--allow-write`; successful calls include text and validated\n`structuredContent`. Remote transport is not enabled.\n\nAgent Contract manifest and API files use `schemaVersion: 2`. The manifest\ndeclares the protocol versions and empty extensions; the API declares each\ntool's `outputSchema`.\n\n## AI evaluation suites\n\n`.silen/ai-evals.json` is strict JSON. Version 1 matches one route and optional\nheading within `topK`; version 2 adds optional `expected.maxRank`. Version 3\nuses this strict shape:\n\n| Field | Requirement |\n| --- | --- |\n| `schemaVersion` | Exact integer `3` |\n| `topK` | Integer `1..20` |\n| `cases` | One to 500 ordered cases |\n| `expected.acceptable` | Required array of zero to 20 unique targets |\n| `expected.forbidden` | Required array of zero to 20 unique targets |\n| `expected.maxRank` | Required integer `1..topK`; exact `topK` for negative-only cases |\n| Target | Strict `{ route, heading? }`; route starts with `/` |\n\nAt least one target array must be non-empty. Normalized duplicates, overlap\nwithin an array, overlap between `acceptable` and `forbidden`, and unknown\nfields are invalid. Version 3 reports preserve ordered `cases`, `matchedRank`,\n`forbiddenMatches`, and full diagnostic Top K; v1/v2 behavior remains\ncompatible. Evaluation is read-only and model-free.\n\nRepository maintainers run `pnpm site:ai-check`; its exact stable report is\n`artifacts/ai-eval/site-ai-eval.json`.\n\n## Troubleshooting\n\n**A link works locally but fails after deployment.** Confirm the host mount\nmatches `base`, authored root-relative content links include that mount, and\nthe host serves nested `index.html` files.\n\n**Canonical URLs include the path twice.** Keep `siteUrl` to the origin and put\nthe path only in `base`.\n\n**The language switch returns a missing page.** Create the exact mirrored route\nunder every locale root and include it in translated navigation.\n\n**Build reports a duplicate route.** Remove either `topic.mdx` or\n`topic/index.mdx`; both resolve to the same public route.\n\n**A build fails after pnpm reports an ignored esbuild build script.** Approve\nonly that dependency with `pnpm approve-builds esbuild`, reinstall, and retry.\nNo approval is needed when the build already succeeds.\n\n**MCP write tools are absent.** This is the safe default. Start the server with\n`--allow-write` only after the user authorizes a bounded write task.\n\nSee [configuration](/silen/guide/configuration/) and\n[CLI/deployment](/silen/guide/cli-deployment/) for longer guidance.\n",
      "description": "Configuration defaults, CLI syntax, and troubleshooting for Silen."
    },
    {
      "route": "/theme/extensions-accessibility/",
      "title": "Theme extensions and accessibility",
      "markdown": "# Theme extensions and accessibility\n\nExtend the default theme when tokens and configuration are not enough. A theme\ncan replace layouts or MDX components, provide a custom 404, and wrap the React\nroot while inheriting everything else.\n\n```tsx\n// docs/.silen/theme.tsx\nimport type { ReactNode } from 'react'\nimport DefaultTheme, { defineTheme } from '@aicode-nexus/silen/theme'\nimport './custom.css'\n\nfunction Note({ children }: { readonly children?: ReactNode }) {\n  return <aside className=\"product-note\">{children}</aside>\n}\n\nexport default defineTheme({\n  extends: DefaultTheme,\n  components: { Note },\n  wrapRoot({ children }) {\n    return <div data-product-docs=\"\">{children}</div>\n  },\n})\n```\n\n`defineTheme` merges inherited layouts and components by key. `NotFound` is\ninherited unless replaced. When both base and extension define `wrapRoot`, the\nextension wrapper composes outside the base wrapper. Recursive extension is\nrejected.\n\n## SSR-safe extensions\n\nTheme modules and root wrappers run during server rendering and hydration. Do\nnot read `window`, `document`, or `localStorage` at module scope or directly in\nrender. Put browser behavior in an effect or plugin client `setup` function and\nreturn cleanup when registering listeners.\n\n## Accessibility contract\n\nThe default shell includes a skip link and visible focus indicators. Mobile\nnavigation is a labelled modal: opening moves focus into navigation, Escape\ncloses it, and focus returns to the trigger. Search supports its shortcut,\narrow-key selection, Enter, Escape, and focus restoration. Code-copy controls\nare buttons with live status labels.\n\nThe appearance control is an explicit dark/system/light radio group. Its\ninline head script applies the stored preference before hydration to prevent a\ncolor flash, while system mode follows operating-system changes. Nonessential\ntransitions respect reduced-motion preferences.\n\nWhen replacing an interactive component, keep its accessible name, keyboard\npath, focus behavior, and server-rendered fallback. Test without a pointer,\nwith 200% zoom, and with reduced motion before shipping.\n",
      "description": "Extend the default theme without losing SSR, hydration, or keyboard behavior."
    },
    {
      "route": "/theme/",
      "title": "Theme, layouts, and navigation",
      "markdown": "# Theme, layouts, and navigation\n\nThe default theme is a responsive documentation shell rather than a closed\ntemplate. It supplies navigation, sidebars, page outlines, local search,\nappearance controls, code copying, pagination, home heroes, and a complete 404\npage. Start with configuration; extend React only when a product requirement\ncannot be expressed there.\n\n## Layouts\n\nChoose a content layout in frontmatter:\n\n```md\n---\nlayout: doc\n---\n```\n\n- `doc` is the default. It applies reading typography, the heading outline, and\n  previous/next links derived from the sidebar.\n- `home` renders the locale-resolved configured hero and optional feature row\n  before page MDX in a full-width shell.\n- `page` keeps navigation and a neutral article container without documentation\n  paging.\n\nHome hero artwork can provide separate light and dark assets while keeping one\naccessible description:\n\n```ts\nthemeConfig: {\n  home: {\n    hero: {\n      image: {\n        src: '/workflow-light.jpg',\n        darkSrc: '/workflow-dark.jpg',\n        alt: 'Documentation workflow',\n      },\n    },\n  },\n}\n```\n\n## Navigation and sidebar\n\n```ts\nthemeConfig: {\n  logo: { src: '/logo.svg', alt: 'Product docs' },\n  nav: [\n    { text: 'Guide', link: '/guide/' },\n    { text: 'GitHub', link: 'https://github.com/example/project' },\n  ],\n  sidebar: [\n    {\n      text: 'Getting started',\n      items: [{ text: 'Quick start', link: '/guide/' }],\n    },\n  ],\n}\n```\n\nInternal theme links are resolved under `base`. HTTP(S) nav links use ordinary\nbrowser navigation in the current context. Nav items pass only `href`; they do\nnot automatically add a new context or relationship attributes. MDX-authored\nlinks can explicitly set `target=\"_blank\"` and `rel=\"noopener noreferrer\"` when\na new context is genuinely useful. Below 960px the persistent sidebar becomes\na labelled modal sheet with collapsible groups. At desktop widths, every group\nremains visible as a semantic section beside the document, and the current page\nuses the primary theme treatment.\n\n## Search\n\nLocal search is enabled unless `themeConfig.search` is `false`. It loads on\ndemand, opens from the search button or `Control+K` / `Command+K`, supports\nkeyboard selection, and restores focus when dismissed. Search v2 records page\nlanguage so results from the active locale are ranked and grouped correctly.\n\n## Locales\n\nLocale entries define a BCP 47 `lang`, label, and route `root`; they may\noverride nav, sidebar, home, and UI messages. Mirrored routes let the language\nswitch preserve the current page. The longest matching configured locale root\ncontrols document and search language. Frontmatter `lang` does not override\nthe resolved route locale; content requiring another language should live\nunder the corresponding locale root.\n\nCustomize visual values with [theme tokens](/silen/theme/tokens/) or compose\nReact behavior through [theme extensions](/silen/theme/extensions-accessibility/).\n",
      "description": "Configure the default theme shell, layouts, search, and locales."
    },
    {
      "route": "/theme/tokens/",
      "title": "Theme tokens",
      "markdown": "# Theme tokens\n\nOverride semantic CSS variables instead of styling internal utility classes.\nTokens are the stable boundary between the default theme’s behavior and a\nproject’s visual identity.\n\n```css\n/* docs/.silen/custom.css */\n:root {\n  --silen-primary: oklch(0.55 0.17 245);\n  --silen-primary-foreground: oklch(0.99 0 0);\n  --silen-radius: 0.5rem;\n  --silen-content-width: 48rem;\n}\n\n.dark {\n  --silen-primary: oklch(0.76 0.12 245);\n}\n```\n\nImport the stylesheet from `.silen/theme.tsx` so Vite includes it in both SSR\nand the client bundle.\n\n## Color tokens\n\nThe primary semantic set is `--silen-background`, `--silen-foreground`,\n`--silen-card`, `--silen-card-foreground`, `--silen-primary`,\n`--silen-primary-foreground`, `--silen-muted`,\n`--silen-muted-foreground`, `--silen-border`, `--silen-input`,\n`--silen-ring`, and `--silen-destructive`. Secondary, accent, and popover\ntokens map the same semantics to interactive primitives.\n\nDefine light values on `:root` and dark overrides on `.dark`. Preserve usable\ncontrast between foreground/background and primary/primary-foreground pairs;\nthe appearance control can switch explicitly among dark, system, and light.\n\n## Shape and layout tokens\n\n- `--silen-radius` controls the shared corner language.\n- `--silen-nav-height` sizes the fixed top navigation.\n- `--silen-sidebar-width` controls the desktop navigation rail.\n- `--silen-content-width` limits readable document lines.\n- `--silen-layout-width` limits wide home and page layouts.\n\nChange one layer at a time and test long titles, code blocks, both appearance\nmodes, and mobile navigation. Increasing content width may look efficient on a\ndashboard but makes prose harder to scan.\n\n## Extension boundary\n\nTokens are best for visual changes. Use a [theme extension](/silen/theme/extensions-accessibility/)\nonly when you need a new MDX component, wrapper, layout, or 404 component.\n",
      "description": "Customize Silen colors, shape, and layout through semantic CSS variables."
    },
    {
      "route": "/zh/ai/agent-contract/",
      "title": "Agent Contract",
      "markdown": "# Agent Contract\n\nAgent Contract 是版本化、可检查的发现层，让 AI 客户端不必猜测配置字段、CLI 语法、MCP 权限与部署路由。\n\n## 安装包契约\n\n创建或维护本地项目时，从这里开始：\n\n```text\n@aicode-nexus/silen/agent/manifest.json\n```\n\n包清单会指向当前准确版本的配置 API、CLI/MCP 契约、公共 TypeScript 导出、指南与任务手册。例如 `agent/tasks/create-site.md` 描述受支持的激活路径，并链接回权威机器可读资源，而不是复制定义。\n\n## 部署站点契约\n\n开启后，每次生产构建都会发布站点专属的 `/.well-known/silen/manifest.json`，并按 `base` 解析。当前官网的[实时清单](/silen/.well-known/silen/manifest.json)描述 base、语言、资源、任务与公开项目指引；资源与任务 URL 保持 base 相对。manifest schema 不包含部署 origin 字段。\n\n```ts\nai: {\n  contract: {\n    enabled: true,\n    instructions: '.silen/ai-public.md',\n    tasksDir: '.silen/ai-tasks',\n  },\n}\n```\n\n指令与任务都是显式公开构建输入。不要包含本地绝对路径、密钥、私有端点、凭证或未公开运行信息。\n\n## Schema 版本 2\n\n当前 manifest 与 API 文档使用 `schemaVersion: 2`。manifest 的 MCP 能力声明\n`stdio`、协议版本 `2025-11-25` 与 `2026-07-28`、空扩展列表、本地运行、\n默认只读和 `--allow-write` 门禁。API 文档为每个工具增加 `outputSchema`；MCP\n成功调用会同时返回文本与对应的、经过 schema 校验的 `structuredContent`。\n\n该契约不声明远程传输或可选 MCP 扩展；这些能力需要独立设计和授权。\n\n包内还包含生成的文件系统 Skill：\n`dist/agent/skills/silen-docs-readonly`；CLI API 会记录 `silen ai skills` 和\n`--experimental-skills-over-mcp`。默认 manifest 仍声明 `extensions: []`，因为可选\n运行参数不等于站点能力。Skill 文本只是流程知识，不授予 Host 运行命令、访问\n网络、写文件、提交、推送或部署的权限。\n\n## 客户端行为\n\nCodex、Claude Code、Cursor 等客户端应使用同一份清单，不要维护各自的 API 副本。若客户端不支持声明的契约 schema，应退回到链接的公开 Markdown，并保持只读。读取部署内容时以站点清单为准；针对已安装包生成代码时以包契约为准。\n\n下一步配置[本地工作区与 MCP](/silen/zh/ai/local-workspace-mcp/)。\n",
      "description": "为 AI 客户端提供版本化的 Silen 项目与站点发现入口。"
    },
    {
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "markdown": "# AI-ready 文档\n\nSilen 把 AI 访问视为文档构建的一部分，而不是事后补上的功能。默认输出是\n确定、可检查的，并且不会调用模型。核心 AI-ready 文档流程不需要模型、API key、\n端点、向量服务或网络。\n\n## Agent Contract\n\nSilen 为 AI 提供一个带版本的发现入口，不需要为每一种客户端重复维护一份教程：\n\n- 操作本地项目时，先读取已安装包中的\n  `@aicode-nexus/silen/agent/manifest.json`。它会链接到准确的配置、CLI、\n  MCP、公开 TypeScript API，以及 `agent/tasks/create-site.md` 等任务手册。\n- 读取部署站点时，先访问 `/.well-known/silen/manifest.json`。当前官方站点的\n  地址是 `/silen/.well-known/silen/manifest.json`。\n- 在本地进行有边界的读取时，启动 `pnpm silen mcp docs`。除非用户显式添加\n  `--allow-write`，否则它始终只读。\n\nCodex、Claude Code 与 Cursor 都应读取同一份 manifest，并使用同一个本地 MCP\n命令。各客户端只保留轻量接入配置，API 真相始终由 Agent Contract 提供。\n\n如果客户端不支持声明的契约版本，必须退回链接的公开 Markdown，并保持只读。\n\n当前 manifest 与 API 使用 `schemaVersion: 2`，声明本地 `stdio`、已验证的\n`2025-11-25` 与 `2026-07-28` 协议版本、空扩展集合，以及每个 MCP 工具的\n`outputSchema`。\n\n## 只读 Agent Skill\n\nnpm 包会从规范的中英文 `read-site` 与 `audit-site` 任务包确定性生成唯一的\n`silen-docs-readonly` Agent Skill。包内路径是\n`dist/agent/skills/silen-docs-readonly`，其中只有 `SKILL.md` 和四个按需读取的\n参考文件，不包含脚本、资产、写任务、模型调用、凭据或隐含权限。\n\n```sh\npnpm silen ai skills ./agent-skills\n```\n\n该命令只创建 `./agent-skills/silen-docs-readonly`；如果目录已经存在就直接失败，\n不会覆盖。文件系统形式是受支持的可移植能力，并且可离线使用。\n\n## 添加公开项目指令\n\n只发布对所有站点访问者都安全的内容：\n\n```ts\nexport default defineConfig({\n  ai: {\n    contract: {\n      instructions: '.silen/ai-public.md',\n      tasksDir: '.silen/ai-tasks',\n    },\n  },\n})\n```\n\n这些文件会成为显式公开的 Agent 指令。不要写入私有路径、密钥、内部端点或凭据。\n\n## 面向 AI 的公开产物\n\n每次生产构建都可以输出：\n\n- `llms.txt`，用于精简页面地图\n- `llms-full.txt`，用于完整可读内容\n- `ai-index.json`，用于结构化发现\n- 每个公开页面对应的干净 Markdown 路由\n\n标记为 `draft: true` 或 `ai: false` 的页面会从这些产物中排除。\n\n## 复制给 AI\n\n默认主题允许读者复制干净的页面 Markdown，或复制带规范来源 URL 的\nprompt-ready 版本。复制内容来自同一套构建产物，因此会和渲染页面保持一致。\n\n## 本地 MCP 工作区\n\n```sh\npnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen mcp docs\n```\n\nMCP 服务使用拆分后的 SDK v2，并且默认只读。只有显式使用 `--allow-write`\n启动时，写入工具才会出现；所有写入仍被限制在 Markdown 工作区内。成功调用会\n同时返回文本和经过 schema 校验的 `structuredContent`，不启用远程传输。\n\n## 无模型质量门禁\n\n直接把生产搜索索引作为确定性的检索契约：\n\n```sh\npnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs\n```\n\n`ai eval` 只读取已提交的 `.silen/ai-evals.json` 与构建生成的\n`.silen/dist/search-index.json`，不会调用模型或网络。退出码 `0`、`1`、`2`\n分别表示通过、检索失败、初始化或配置失败。\n\n版本 1 保持完整 `topK` 匹配；版本 2 增加可选的 `expected.maxRank`，并报告\n生效值与 `matchedRank`。严格的 `\"schemaVersion\": 3` 要求两个目标数组与显式\n排名边界：\n\n```json\n{\n  \"schemaVersion\": 3,\n  \"topK\": 5,\n  \"cases\": [\n    {\n      \"id\": \"install-quick-start\",\n      \"query\": \"如何安装并启动站点？\",\n      \"expected\": {\n        \"acceptable\": [\n          { \"route\": \"/zh/guide/\", \"heading\": \"快速开始\" },\n          { \"route\": \"/zh/guide/cli-deployment/\" }\n        ],\n        \"forbidden\": [{ \"route\": \"/zh/draft-notes/\" }],\n        \"maxRank\": 1\n      }\n    }\n  ]\n}\n```\n\n`acceptable` 与 `forbidden` 都必须出现，每个数组可包含零到 20 个目标，但两者\n不能同时为空。至少一个可接受目标必须在 `maxRank` 以内出现，所有禁止目标都不能\n进入诊断 Top K。纯负例使用 `acceptable: []` 与 `maxRank: topK`。未知字段、\n重叠目标、空目标集合和非法边界都会成为初始化错误。版本 3 保持案例编写顺序，\n并输出 `matchedRank` 与 `forbiddenMatches`；v1/v2 的 JSON 与人类可读输出保持\n兼容。\n\n本仓库使用 `pnpm site:ai-check` 一次完成构建、审计、评测和 source map 检查，\n并把评测器的原始 JSON 保存到\n`artifacts/ai-eval/site-ai-eval.json`，供 CI、Pages 与发布流程比较。\n\n可重建的 `.silen/ai/index.json` 只是可选工作区快照。缺失或过期只会成为 audit\n提示，MCP 搜索仍使用内存索引。\n\n## Ask AI\n\nAsk AI 是可选的端点集成。Silen 不会把 provider key 放进生成站点：你的服务端\n负责鉴权，并把一套小型 NDJSON 协议流式返回给主题。未显式配置端点时，Ask AI\n控件及其 bundle 都不会出现。\n\n返回 [快速开始指南](/silen/zh/guide/)。\n",
      "description": "确定性的产物，以及有权限边界的本地 MCP 工作区。"
    },
    {
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "markdown": "# 本地工作区与 MCP\n\n本地 AI 工作区是确定性、无模型的能力层：它为工具提供有边界的 Markdown 根目录、可检查索引与显式写权限，不暴露任意 shell 执行。整个流程不需要模型、API key、端点、向量服务或网络。\n\n## 初始化、索引与审计\n\n```sh\npnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\n```\n\n`ai init` 创建 `wiki/` 与被忽略的 `.silen/ai/` 缓存，不修改已有 MDX；`ai index` 重建可选的 `.silen/ai/index.json` 工作区快照；`ai audit` 检查链接、引用、生成产物与生产契约。快照缺失或过期只会成为提示，因为 MCP 搜索使用内存索引。\n\n## 构建、审计与评测\n\n```sh\npnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs\n```\n\n`ai eval` 读取 `.silen/ai-evals.json` 与生产构建的\n`.silen/dist/search-index.json`；它不会启动 MCP，也不会调用模型或网络。版本 1\n在 `topK` 内使用单一路由与可选标题；版本 2 增加可选的\n`expected.maxRank`。严格的 `\"schemaVersion\": 3` 要求同时提供\n`acceptable` 与 `forbidden` 数组、两者至少包含一个目标，并显式设置 1 到\n`topK` 之间的 `maxRank`。纯负例使用 `acceptable: []` 与\n`maxRank: topK`。\n\n版本 3 在没有可接受目标时报告 `matchedRank: null`，并把禁止命中列入\n`forbiddenMatches`。退出码 `0` 表示全部通过，`1` 表示检索预期失败，`2`\n表示套件或输入无效；完整诊断 Top K 保持稳定的案例顺序。\n\nSilen 仓库使用 `pnpm site:ai-check` 组合完整只读门禁，并把评测原始 JSON\n保存到 `artifacts/ai-eval/site-ai-eval.json`。可选的\n`.silen/ai/index.json` 快照仍是非阻断能力，不会替代生产搜索索引。\n\n## 连接 MCP 客户端\n\n从仓库根目录启动：\n\n```json\n{\n  \"mcpServers\": {\n    \"silen\": {\n      \"command\": \"pnpm\",\n      \"args\": [\"silen\", \"mcp\", \"docs\"]\n    }\n  }\n}\n```\n\n默认服务注册七个只读工具：`guide`、`list`、`search`、`read`、`backlinks`、`citations`、`build`。`build` 是有边界的预检，只读取 Markdown 输入与现有产物，不加载项目配置、不执行 MDX、不调用 Vite，也不写文件。\n\n## 协议与结构化结果\n\n该命令使用稳定的拆分版 TypeScript SDK v2。同一个 `stdio` 入口接受已验证的\nlegacy `2025-11-25` 与 modern `2026-07-28` 客户端；版本规则见\n[官方协议版本指南](https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions)。\n服务默认只读。每次成功调用都同时返回文本与经过 schema 校验的\n`structuredContent`，每个工具都声明 `outputSchema`；不启用远程传输。\n\n字符串结果的 `guide` 在 modern 客户端中保持原生字符串，在 legacy 客户端中由\nSDK 兼容包装为 `{ result: ... }`；对象结果工具在两个协议时代保持原有结构。\n\n## 实验性 Skills over MCP\n\n文件系统安装不依赖 MCP。明确支持 Resources 草案绑定的 Host 可以选择暴露同一份\n包内字节：\n\n```sh\npnpm silen mcp docs --experimental-skills-over-mcp\n```\n\n该实验声明 `io.modelcontextprotocol/skills`，提供 `skill://index.json`，并把五个\n文件映射到 `skill://silen-docs-readonly/` 下。它只使用本地 stdio 并保持只读；该\n实验默认关闭，不增加工具、脚本、订阅、网络传输或写权限；`--allow-write` 仍是\n独立的显式工具注册开关。\n\n## 谨慎授权写入\n\n```sh\npnpm silen mcp docs --allow-write\n```\n\n显式参数会增加 `write`、`link`、`append`。写入只接受工作区相对 `.md`/`.mdx` 路径，拒绝目录穿越和逃逸符号链接，使用原子替换，并限制为 2 MiB UTF-8；它不会增加 shell 工具。\n\n只在边界明确的任务中授权可信本地客户端。修改后运行 audit 与站点构建，检查 Git diff，并在提交或部署前另行取得授权。\n\nAsk AI 是独立能力，必须显式配置端点；没有端点时，Silen 不会输出控件及其 bundle。\n\n客户端发现规则见 [Agent Contract](/silen/zh/ai/agent-contract/)。\n",
      "description": "为本地 AI 客户端索引、审计并暴露有边界的文档工作区。"
    },
    {
      "route": "/zh/guide/cli-deployment/",
      "title": "CLI 与部署",
      "markdown": "# CLI 与部署\n\nSilen 提供一组精简 CLI。通过项目包管理器运行，命令实现与 Agent Contract 就会始终匹配当前安装版本。\n\n## 主要命令\n\n```sh\npnpm silen init docs\npnpm silen dev docs --host 127.0.0.1 --port 5173\npnpm silen build docs\npnpm silen preview docs --port 4173\n```\n\n`init <root>` 写入起始配置与首页，不替换已有目标；`dev [root]` 启动基于 Vite 的开发服务；`build [root]` 校验并生成静态产物；`preview [root]` 提供包含路由与语言感知 404 的预览。服务命令支持 `--host` 和 `--port`，构建命令不会自动部署。\n\nAI 工作区使用独立命令：\n\n```sh\npnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen ai skills ./agent-skills\npnpm silen mcp docs\n```\n\n`ai skills` 必须指定父目录，只创建 `silen-docs-readonly` 且绝不覆盖；可选的 MCP\nResource 暴露使用 `pnpm silen mcp docs --experimental-skills-over-mcp`，仍是实验能力\n并默认关闭。\n\nMCP 默认只读，只有可信用户显式加入 `--allow-write` 才会注册写工具。无模型的\n`ai eval` 只读取 `.silen/ai-evals.json` 与 `.silen/dist/search-index.json`，\nCI 使用 `--json`；它不需要模型、API key、端点、向量服务或网络。\n\n套件 `\"schemaVersion\": 1` 保持完整 `topK` 匹配；版本 2 支持逐案例\n`expected.maxRank`，省略时默认等于 `topK`，并在保留完整诊断结果的同时\n报告 `matchedRank`。\n\n## 静态部署\n\n把 `docs/.silen/dist` 的内容发布到任意静态托管，并让托管平台按生成结果提供 `index.html` 与资源。例如项目地址为 `https://example.github.io/handbook/`：\n\n```ts\nexport default defineConfig({\n  siteUrl: 'https://example.github.io',\n  base: '/handbook/',\n})\n```\n\n不要在 `siteUrl` 中重复 `/handbook/`。构建会组合 origin 与 base，用于 canonical、`hreflang` 与 `x-default` 语言替代、站点地图和基础 Open Graph/Twitter 元数据。Markdown 与 Agent Contract URL 仍是 base 相对路径。\n\n## 上线前检查\n\n仓库维护者只运行一个规范命令：\n\n```sh\npnpm site:ai-check\n```\n\n它依次且只执行一次 `site:build` -> `ai audit` -> `ai eval` ->\n`check:no-maps`；`pnpm site:check` 只是兼容别名。Core CI、GitHub Pages 与\nnpm 发布都使用规范命令，audit 或评测失败会阻断部署和发布。\n\n正式 `.silen/ai-evals.json` 使用 `\"schemaVersion\": 3`、显式\n`maxRank`，以及必需的 `acceptable` 和 `forbidden` 目标数组。报告保留诊断\n`topK`、稳定的 `matchedRank` 与禁止命中证据。只要评测器产出了有效 JSON，\n每条工作流都会用 always 条件上传\n`artifacts/ai-eval/site-ai-eval.json`，包括检索失败或后续 source map\n检查失败的情况。\n\n随后直接预览一个嵌套路由和一个不存在的路由，并检查 `llms.txt` 与\n`.well-known/silen/manifest.json`。构建成功只证明文件已生成；直接访问才能\n证明托管平台按预期 base 提供了它们。\n\nAsk AI 仍然只通过端点接入；未配置端点时，不会出现控件或对应 bundle。\n\n命令语法与排错见[参考手册](/silen/zh/reference/)。\n",
      "description": "使用 Silen 命令，并在正确 base 下部署静态产物。"
    },
    {
      "route": "/zh/guide/configuration/",
      "title": "配置",
      "markdown": "# 配置\n\n在内容根目录创建 `.silen/config.ts`，并导出 `defineConfig(...)`。该文件是可信的项目代码；不要放入密钥，因为配置可能影响公开 HTML 与构建产物。\n\n```ts\nimport { defineConfig } from '@aicode-nexus/silen'\n\nexport default defineConfig({\n  title: '工程手册',\n  description: '产品团队的运行知识。',\n  lang: 'zh-CN',\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  outDir: '.silen/dist',\n  onBrokenLinks: 'error',\n})\n```\n\n## URL 与元数据\n\n`base` 是站点挂载位置的规范绝对路径；域名根路径使用 `/`，子路径可用 `/handbook/`。`siteUrl` 只能写 HTTP(S) 源，部署路径写在 `base` 中。两者共同生成 canonical、`hreflang` 与 `x-default` 语言替代、站点地图和基础 Open Graph/Twitter 元数据。Markdown 与 Agent Contract URL 仍是 base 相对路径。`lang` 使用 BCP 47 语言标签。\n\n## 导航与多语言\n\n`themeConfig.nav` 和 `themeConfig.sidebar` 使用 `{ text, link }`。主题里的根相对链接会自动加上 `base`。locale 可设置 `root`，并覆盖导航、侧栏、首页与界面消息：\n\n```ts\nthemeConfig: {\n  locales: [\n    { lang: 'en-US', label: 'English', root: '/' },\n    { lang: 'zh-CN', label: '中文', root: '/zh/' },\n  ],\n  search: true,\n}\n```\n\n保持语言路由镜像，语言切换器才能保留当前页面，而不是把读者送回首页。\n\n## 集成与 AI\n\n`analytics` 支持 Google、百度与自定义脚本；`plugins` 是有序的可信插件工厂数组。`ai` 可控制 `llms.txt`、`llms-full.txt`、Markdown 路由与 `ai-index.json`，默认全部开启。Agent Contract 默认开启，也可显式加入公开指令和任务。\n\n```ts\nai: {\n  markdownRoutes: true,\n  index: true,\n  contract: { enabled: true, instructions: '.silen/ai-public.md' },\n}\n```\n\n完整字段见[参考手册](/silen/zh/reference/)，集成示例见[集成](/silen/zh/integrations/)。\n",
      "description": "配置路由元数据、导航、集成与 AI 产物。"
    },
    {
      "route": "/zh/guide/",
      "title": "快速开始",
      "markdown": "# 快速开始\n\nSilen 将 Markdown 与 MDX 目录构建为服务端渲染的静态站点、本地搜索与确定性的 AI 可读产物。请使用 Node.js `^20.19.0 || >=22.12.0`。\n\n## 安装并激活\n\n在项目根目录安装 Silen，然后激活 `docs` 目录：\n\n```sh\npnpm add -D @aicode-nexus/silen\npnpm silen init docs\n```\n\nSilen 会自动安装所需的 `react`、`react-dom` 运行时以及 MDX 使用的 `react/jsx-runtime`，用户无需单独安装。\n\n`init` 会创建 `docs/.silen/config.ts` 和 `docs/index.mdx`。它既适用于新目录，也适用于已有内容：只要目标文件已存在，Silen 就会报告冲突，不会覆盖你的内容。\n\n## 本地开发\n\n```sh\npnpm silen dev docs\n```\n\n编辑 `docs/index.mdx`，或增加 `.md`、`.mdx` 文件。目录树会直接形成路由，客户端导航无需整页刷新。本地搜索完全随站点运行，不需要托管搜索账号。\n\n## 构建并检查\n\n```sh\npnpm silen build docs\npnpm silen preview docs\n```\n\n默认输出到 `docs/.silen/dist`。构建结果包括完整 HTML，以及 `llms.txt`、`llms-full.txt`、`ai-index.json` 和干净 Markdown 路由。草稿页与设置了 `ai: false` 的页面不会进入 AI 产物。\n\n## 明确部署边界\n\n站点部署在子路径时设置 `base`；需要规范链接与站点地图时，将 `siteUrl` 设置为域名源：\n\n```ts\nexport default defineConfig({\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  onBrokenLinks: 'error',\n})\n```\n\n下一步阅读[项目结构](/silen/zh/guide/project-structure/)、[配置](/silen/zh/guide/configuration/)，或直接检查[真实 AI 产物](/silen/zh/ai/)。\n",
      "description": "激活、运行并构建一个 Silen 文档站点。"
    },
    {
      "route": "/zh/guide/markdown-mdx/",
      "title": "Markdown 与 MDX",
      "markdown": "# Markdown 与 MDX\n\n持久说明优先使用 Markdown；页面确实需要类型化 React 组件时再使用 MDX。两者都会生成相同的路由、SSR HTML、搜索记录与可选 AI Markdown。GFM 表格、任务列表、删除线、自动链接与脚注会在这些产物中保持一致语义。\n\n## Frontmatter\n\nFrontmatter 用于页面元数据与布局选择：\n\n```md\n---\ntitle: 服务运行手册\ndescription: 诊断并恢复结算服务。\nlayout: doc\nlang: zh-CN\nai: true\n---\n```\n\n`doc` 是默认布局；`home` 会先渲染配置的 hero，再渲染页面 MDX；`page` 保留应用外壳，但不显示文档翻页。`draft: true` 只会让页面退出 AI 可读产物与索引。它不会阻止路由扫描、构建或发布；`ai: false` 对其他公开页面采用相同的 AI 输出边界。不要把私密内容放入内容树。机密材料应保存在站点根目录及其构建输入之外。\n\n## 链接与标题\n\n使用稳定站点路由和有意义的链接文字。非根 `base` 下，主题配置链接会自动感知 base；正文里的根相对链接应直接指向挂载路径。构建期间 Silen 会校验内部页面目标，并按 `onBrokenLinks` 选择报错、警告或忽略。\n\n标题会形成页面大纲。每页保留一个 `#` 标题，后续层级不要跳级，以保证键盘与屏幕阅读器用户都能理解结构。\n\n## 代码与组件\n\n围栏代码块带语法高亮和可键盘操作的复制按钮。Silen 会按需加载 Shiki 支持的语法，包括 `mdx`、`python`，并让 `ndjson` 使用 JSON Lines 语法；未知语言会安全降级为纯文本。MDX 可以导入组件：\n\n```mdx\nimport Status from './components/status.tsx'\n\n## 当前状态\n\n<Status service=\"checkout\" />\n```\n\nMDX 会在构建中执行，也能导入项目代码，因此必须把它当成可信源文件，而不是不受信任投稿的沙箱。浏览器 API 应放在 effect 或客户端 setup 内，确保服务端渲染可重复。\n\n需要全站组件时，请扩展[默认主题](/silen/zh/theme/extensions-accessibility/)。\n",
      "description": "编写可信内容、元数据、链接、代码与 React 组件。"
    },
    {
      "route": "/zh/guide/plugins",
      "title": "插件",
      "markdown": "# 插件\n\nSilen 插件无需导入内部文件，即可扩展文档生命周期。插件是直接配置在\n`.silen/config.ts` 中的本地或 npm 工厂函数：\n\n```ts\nimport { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst readingTime = definePlugin(\n  (_context, options: { wordsPerMinute: number }) => ({\n    name: 'reading-time',\n    transformPageData(page, context) {\n      const words = context.source.trim().split(/\\s+/).length\n      return {\n        data: {\n          ...page.data,\n          minutes: Math.max(1, Math.ceil(words / options.wordsPerMinute)),\n        },\n      }\n    },\n  }),\n)\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})\n```\n\n## 生命周期\n\nSilen 按配置顺序执行插件。首个版本支持 `config`、`configResolved`、\n`extendMdx`、`vite`、`clientModules`、`transformPageData`、\n`transformHead` 和 `buildEnd`。\n\n- `extendMdx` 接入 Remark 与 Rehype 插件。\n- `vite` 接入标准 Vite 能力；`virtual:silen/*` 模块仍由核心保护。\n- `transformPageData` 生成可 JSON 序列化、可供 SSR、hydration、搜索和\n  AI 产物共同使用的页面数据。\n- `transformHead` 添加类型化的 `meta`、`link`、`script`、`style` 或\n  `noscript` 节点。\n- `clientModules` 提供 SSR-safe 的 `wrapRoot` 和可选的浏览器端 `setup`。\n- `buildEnd` 在产物目录安装完成后生成 sitemap 等附加文件。\n\n每个插件都必须提供 `name`；同一插件配置多个实例时应提供不同的 `id`。\n错误信息会包含插件标识和钩子，例如\n`Silen plugin analytics:docs failed in transformHead`。\n\n## SSR 与兼容性\n\n客户端模块会同时进入 SSR 与 hydration。不要在模块顶层或 `wrapRoot` 中\n访问 `window`、`document`；浏览器 API 应放在 `setup` 中。插件包应把\n`@aicode-nexus/silen` 声明为 peer dependency，并且只导入文档化的公开 API。\n\n仓库的\n[`examples/plugins`](https://github.com/AICode-Nexus/silen/tree/main/examples/plugins)\n提供了可直接整理成 npm 包的 sitemap、阅读时间和 analytics-client 示例。\n",
      "description": "通过稳定且有序的生命周期扩展 Silen。"
    },
    {
      "route": "/zh/guide/project-structure/",
      "title": "项目结构",
      "markdown": "# 项目结构\n\n一个 Silen 站点就是一个内容根目录。把内容与站点配置放在同一边界内，本地开发、生产构建和 AI 工具就会解析同一套文件。\n\n```text\ndocs/\n├── .silen/\n│   ├── config.ts\n│   ├── theme.tsx          # 可选主题扩展\n│   ├── ai-public.md       # 可选公开 Agent 指令\n│   └── dist/              # 生成目录，不要手工编辑\n├── public/\n│   └── logo.svg\n├── assets/\n│   └── architecture.png\n├── guide/\n│   └── index.mdx\n└── index.mdx\n```\n\n## 内容如何形成路由\n\nSilen 扫描 `.md` 与 `.mdx`。`index.mdx` 的编译器路由是 `/`；`guide.mdx` 与 `guide/index.mdx` 的编译器路由是 `/guide`。目录形式会生成 `guide/index.html`，通常以 `/guide/` 访问。不要同时创建两个指向同一路由的源文件；构建会明确拒绝重复路由，而不是静默选一个。\n\n会继续增长的栏目适合使用目录，这样相邻图片、示例与子页面更容易维护，公开 URL 也能保持稳定。\n\n## 配置与主题\n\n`.silen/config.ts` 是可信、可执行的项目配置，定义标题、base、多语言、导航、集成与 AI 产物。`.silen/theme.tsx` 是可选项；仅替换组件、布局或根包装器时，应扩展默认主题。\n\n## 静态资源与导入资源\n\n必须保留公开文件名的资源放到 `public/`，例如在配置中使用 `/logo.svg`。Silen 会按配置的 `base` 解析主题链接与图片。与内容强关联、需要进入 Vite 资源管线的图片，可从 MDX 中导入。\n\n## 生成状态\n\n`.silen/dist` 是默认生产输出，`.silen/.temp` 是临时构建状态，都应视为可重新生成。本地 AI 工作区使用 `wiki/` 保存内容，并用 `.silen/ai/` 保存索引。启用写入前请阅读[工作区边界](/silen/zh/ai/local-workspace-mcp/)。\n\n下一步配置[站点选项](/silen/zh/guide/configuration/)。\n",
      "description": "组织 Silen 内容、配置、资源与生成产物。"
    },
    {
      "route": "/zh/",
      "title": "Silen",
      "markdown": "激活一个文档目录\n从文件夹到知识接口\n\n```sh\npnpm add -D @aicode-nexus/silen\npnpm silen init docs\npnpm silen dev docs\n```\n\n直接检查证据\n当前构建的真实产物\n\nllms.txt\n简明语料地图\n\nllms-full.txt\n完整可读语料\n\nai-index.json\n结构化页面发现\n\nAgent 清单\n版本化能力契约\n\n指南 Markdown\n干净的路由级内容\n\n一个内容源，三项证明\n同时服务读者、智能体与维护者\n\n人类阅读\n\nAI 消费\n\n可扩展性\n\n开源，也保持克制\n一起完善文档基础设施\n\n微信公众号：AI Dev Hub\n",
      "description": "为人类与 AI 构建的 React 文档。"
    },
    {
      "route": "/zh/integrations/",
      "title": "集成",
      "markdown": "# 集成\n\nSilen 让集成保持显式：插件运行可信构建或客户端代码，分析在站点层配置，Ask AI 只访问你自己运营的端点。三者都不需要导入 Silen 内部文件。\n\n## 插件\n\n插件是 `.silen/config.ts` 中有序排列的工厂，用于 MDX 处理器、Vite 集成、页面元数据、head、客户端 setup 或构建后产物：\n\n```ts\nimport { defineConfig } from '@aicode-nexus/silen'\nimport readingTime from './plugins/reading-time'\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})\n```\n\n每个插件必须有 `name`，配置多个实例时增加 `id`。钩子按配置顺序运行，失败信息会包含插件身份与钩子名称。完整说明见[插件生命周期](/silen/zh/guide/plugins)。\n\n## 站点分析\n\n分析与主题无关，只在生产构建中输出。可配置 Google、百度或有序的自定义 provider：\n\n```ts\nanalytics: [\n  { provider: 'google', id: 'G-XXXXXXXXXX' },\n  { provider: 'baidu', id: 'site-id' },\n]\n```\n\nSilen 上报初始页面和客户端路由变化，忽略仅 hash 变化。Google 用户应关闭 Enhanced Measurement 中的自动 history-change pageview，避免重复。自定义 provider 可加载外部或内联脚本并监听 `silen:pageview`。脚本是公开可信代码，不要放密钥。\n\n## Ask AI\n\nAsk AI 是可选主题端点，不捆绑模型 provider：\n\n```ts\nthemeConfig: {\n  ai: {\n    endpoint: '/api/ask'\n  }\n}\n```\n\n## Ask AI 请求\n\nSilen 通过 HTTP `POST` 发送 `Content-Type: application/json` 请求。请求契约严格如下：\n\n```ts\ninterface AskAiRequest {\n  route: string\n  selectedText?: string\n  messages: Array<{\n    role: 'user' | 'assistant'\n    content: string\n  }>\n}\n```\n\n`selectedText` 是可选字段；读者未选择正文时应省略。`messages` 可以包含之前的 user 与 assistant 对话。具体请求示例：\n\n```json\n{\n  \"route\": \"/guide/\",\n  \"selectedText\": \"pnpm silen init docs\",\n  \"messages\": [\n    { \"role\": \"user\", \"content\": \"如何开始？\" },\n    { \"role\": \"assistant\", \"content\": \"先安装依赖。\" }\n  ]\n}\n```\n\n## Ask AI 响应\n\n成功的流式响应必须使用 `Content-Type: application/x-ndjson` 或 `Content-Type: application/ndjson`。每行写入一个 JSON 对象。事件形状分别是文本 `{ type: 'text', value: string }`、引用 `{ type: 'citation', title: string, url: string }` 与错误 `{ type: 'error', message: string }`：\n\n```ndjson\n{\"type\":\"text\",\"value\":\"Install with pnpm.\"}\n{\"type\":\"citation\",\"title\":\"Quick start\",\"url\":\"/guide/\"}\n{\"type\":\"error\",\"message\":\"Unable to answer.\"}\n```\n\nSilen 会向请求提供 `AbortSignal`，并在新请求取代旧请求或对话框关闭时触发 abort。把该信号与 HTTP 连接断开视为取消：停止上游 provider 工作并释放资源。\n\n端点负责服务端鉴权。provider key 与原始 provider 错误必须留在服务端，只返回安全的公开错误。未配置端点时，不会生成 Ask AI 控件，也不会生成 Ask AI 客户端 bundle。\n\n无需模型 provider 的确定性访问见[生成产物](/silen/zh/ai/)与[本地 MCP](/silen/zh/ai/local-workspace-mcp/)。\n",
      "description": "添加插件、站点分析与可选 Ask AI 端点。"
    },
    {
      "route": "/zh/plugins/",
      "title": "插件",
      "markdown": "# 插件\n\n此路由为已有书签继续保留。Silen 插件 API 是有序、公开的构建与客户端扩展边界。插件工厂在 `.silen/config.ts` 中配置，接收当前 command 与 root，并返回有名称的插件。\n\n```ts\nimport { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst metadata = definePlugin(() => ({\n  name: 'product-metadata',\n  transformPageData(page) {\n    return { data: { ...page.data, product: 'checkout' } }\n  },\n}))\n\nexport default defineConfig({ plugins: [metadata] })\n```\n\n公开钩子覆盖配置、解析后配置、Remark/Rehype、Vite、客户端模块、页面数据、head 与构建结束。钩子按配置顺序运行。客户端模块必须兼容 SSR：浏览器 API 应放入 `setup`，而不是模块顶层或 `wrapRoot`。插件包应把 `@aicode-nexus/silen` 声明为 peer dependency，并只导入文档化导出。\n\n插件生命周期、身份、失败信息与打包规则请进入正式[插件指南](/silen/zh/guide/plugins)；分析与 Ask AI 见[集成](/silen/zh/integrations/)。\n",
      "description": "Silen 插件生命周期文档的兼容入口。"
    },
    {
      "route": "/zh/reference/",
      "title": "参考",
      "markdown": "# 参考\n\n本页是紧凑的运行参考；解释与完整示例请阅读链接的指南。\n\n## 配置\n\n| 字段 | 默认值 | 用途 |\n| --- | --- | --- |\n| `title` | `Silen` | 站点标题 |\n| `description` | 空 | 页面元数据 |\n| `lang` | `en-US` | 默认 BCP 47 语言 |\n| `base` | `/` | 规范化部署路径 |\n| `siteUrl` | 未设置 | canonical HTTP(S) origin |\n| `outDir` | `.silen/dist` | 相对内容根的输出目录 |\n| `onBrokenLinks` | `error` | `error`、`warn`、`ignore` |\n| `themeConfig` | `{}` | 导航、语言、首页、搜索、Ask AI |\n| `analytics` | `[]` | 有序生产分析 provider |\n| `plugins` | `[]` | 有序可信插件 |\n| `ai.*` | 开启 | AI 文件、Markdown、索引、契约 |\n\n`base` 必须以 `/` 开头，不含 query/hash 或穿越路径，并规范为结尾斜杠。`siteUrl` 只能是 origin，不含凭证、路径、query 或 fragment。\n\n## CLI\n\n| 命令 | 作用 |\n| --- | --- |\n| `silen init <root>` | 安全创建起始配置与首页 |\n| `silen dev [root]` | 启动开发，支持 `--host`、`--port` |\n| `silen build [root]` | 校验并生成静态产物 |\n| `silen preview [root]` | 预览产物，支持 `--host`、`--port` |\n| `silen ai <init\\|index\\|audit\\|eval> [path]` | 管理并评测本地 AI 工作区 |\n| `silen ai skills <destination>` | 无覆盖地写出包内 `silen-docs-readonly` Skill |\n| `silen mcp [root]` | 启动只读 MCP；可选 `--allow-write` 与实验性 `--experimental-skills-over-mcp` |\n\n包内可移植 Skill 位于 `dist/agent/skills/silen-docs-readonly`。只有显式使用\n`--experimental-skills-over-mcp` 时才会提供\n`skill://silen-docs-readonly/SKILL.md`；默认 Agent Contract 仍是\n`extensions: []`。\n\n## MCP 与 Agent Contract\n\n本地 MCP 命令使用 SDK v2 与 `stdio`，验证 `2025-11-25` 和 `2026-07-28`。\n默认提供七个只读工具，加入 `--allow-write` 后增加三个写工具；成功调用同时返回\n文本与经过校验的 `structuredContent`，不启用远程传输。\n\nAgent Contract manifest 与 API 使用 `schemaVersion: 2`。manifest 声明协议版本\n和空扩展集合，API 为每个工具声明 `outputSchema`。\n\n## AI 评测套件\n\n`.silen/ai-evals.json` 是严格 JSON。版本 1 在 `topK` 内匹配单一路由与可选\n标题；版本 2 增加可选的 `expected.maxRank`。版本 3 使用以下严格结构：\n\n| 字段 | 要求 |\n| --- | --- |\n| `schemaVersion` | 精确整数 `3` |\n| `topK` | 整数 `1..20` |\n| `cases` | 1 到 500 个有序案例 |\n| `expected.acceptable` | 必需数组，包含 0 到 20 个不重复目标 |\n| `expected.forbidden` | 必需数组，包含 0 到 20 个不重复目标 |\n| `expected.maxRank` | 必需整数 `1..topK`；纯负例必须精确等于 `topK` |\n| 目标 | 严格 `{ route, heading? }`；route 以 `/` 开头 |\n\n两个目标数组至少有一个非空。规范化后的重复、数组内部重叠、`acceptable` 与\n`forbidden` 之间的重叠，以及未知字段都无效。版本 3 报告保留有序 `cases`、\n`matchedRank`、`forbiddenMatches` 与完整诊断 Top K；v1/v2 行为保持兼容。\n评测仍然只读且不依赖模型。\n\n仓库维护者运行 `pnpm site:ai-check`；其精确稳定报告位于\n`artifacts/ai-eval/site-ai-eval.json`。\n\n## 排错\n\n**本地链接正常，部署后失败。** 检查托管路径是否匹配 `base`、正文根相对链接是否包含挂载路径，以及托管是否按原样提供嵌套 `index.html`。\n\n**canonical 路径重复。** `siteUrl` 只写 origin，路径只写在 `base`。\n\n**语言切换进入 404。** 在每个语言 root 下创建完全镜像的路由，并加入翻译后的导航。\n\n**构建报告重复路由。** 删除 `topic.mdx` 或 `topic/index.mdx` 之一；二者指向同一路由。\n\n**pnpm 提示忽略 esbuild 构建脚本，且 Silen 随后构建失败。** 执行 `pnpm approve-builds esbuild`，只批准该依赖，然后重新安装并重试。如果构建已经成功，则无需批准。\n\n**MCP 没有写工具。** 这是安全默认值。只有用户明确授权有边界的写任务后，才加入 `--allow-write`。\n\n深入阅读[配置](/silen/zh/guide/configuration/)与 [CLI/部署](/silen/zh/guide/cli-deployment/)。\n",
      "description": "Silen 配置默认值、CLI 语法与排错。"
    },
    {
      "route": "/zh/theme/extensions-accessibility/",
      "title": "主题扩展与无障碍",
      "markdown": "# 主题扩展与无障碍\n\n令牌与配置不够时再扩展默认主题。主题可以替换布局或 MDX 组件、提供自定义 404、包装 React 根节点，同时继承其余能力。\n\n```tsx\n// docs/.silen/theme.tsx\nimport type { ReactNode } from 'react'\nimport DefaultTheme, { defineTheme } from '@aicode-nexus/silen/theme'\nimport './custom.css'\n\nfunction Note({ children }: { readonly children?: ReactNode }) {\n  return <aside className=\"product-note\">{children}</aside>\n}\n\nexport default defineTheme({\n  extends: DefaultTheme,\n  components: { Note },\n  wrapRoot({ children }) {\n    return <div data-product-docs=\"\">{children}</div>\n  },\n})\n```\n\n`defineTheme` 按 key 合并继承的布局和组件；未替换时继续继承 `NotFound`。基础主题和扩展都定义 `wrapRoot` 时，扩展包装器组合在外层。递归扩展会被拒绝。\n\n## SSR 安全\n\n主题模块与根包装器会同时参与服务端渲染和 hydration。不要在模块顶层或 render 中直接读取 `window`、`document`、`localStorage`。浏览器行为放入 effect 或插件客户端 `setup`，注册监听器时返回清理函数。\n\n## 无障碍契约\n\n默认外壳包含跳转正文链接和清晰焦点样式。移动导航是带标签的模态框：打开后焦点进入导航，Escape 关闭，焦点返回触发按钮。搜索支持快捷键、方向键、Enter、Escape 与焦点恢复；代码复制是带实时状态文本的按钮。\n\n外观控件是明确的深色/系统/浅色单选组。head 内联脚本在 hydration 前应用已保存偏好，避免颜色闪烁；系统模式会跟随操作系统变化。非必要过渡遵循 reduced motion。\n\n替换交互组件时，保留可访问名称、键盘路径、焦点行为与 SSR 降级。上线前用纯键盘、200% 缩放和 reduced motion 检查。\n",
      "description": "在不破坏 SSR、hydration 与键盘行为的前提下扩展默认主题。"
    },
    {
      "route": "/zh/theme/",
      "title": "主题、布局与导航",
      "markdown": "# 主题、布局与导航\n\n默认主题是一套响应式文档外壳，而不是封闭模板。它提供导航、侧栏、页面大纲、本地搜索、外观控制、代码复制、翻页、首页 hero 与完整 404。优先使用配置；只有产品要求无法通过配置表达时才扩展 React。\n\n## 布局\n\n在 frontmatter 中选择布局：\n\n```md\n---\nlayout: doc\n---\n```\n\n- `doc` 是默认布局，提供阅读排版、标题大纲，以及从侧栏推导的上一篇/下一篇。\n- `home` 在页面 MDX 前渲染当前语言的 hero 与可选功能区，并使用全宽外壳。\n- `page` 保留导航和中性文章容器，但不显示文档翻页。\n\n首页 hero 可分别配置亮色与暗色图片，并共用一个无障碍说明：\n\n```ts\nthemeConfig: {\n  home: {\n    hero: {\n      image: {\n        src: '/workflow-light.jpg',\n        darkSrc: '/workflow-dark.jpg',\n        alt: '文档工作流',\n      },\n    },\n  },\n}\n```\n\n## 导航与侧栏\n\n```ts\nthemeConfig: {\n  logo: { src: '/logo.svg', alt: '产品文档' },\n  nav: [\n    { text: '指南', link: '/guide/' },\n    { text: 'GitHub', link: 'https://github.com/example/project' },\n  ],\n  sidebar: [\n    {\n      text: '开始使用',\n      items: [{ text: '快速开始', link: '/guide/' }],\n    },\n  ],\n}\n```\n\n内部主题链接会按 `base` 解析。HTTP(S) 导航链接会在当前上下文中按浏览器普通导航处理。nav 条目只传递 `href`，不会自动增加新上下文或关系属性。确实需要新上下文时，MDX 正文链接可显式设置 `target=\"_blank\"` 与 `rel=\"noopener noreferrer\"`。960px 以下，固定侧栏变成带标签、分组可折叠的模态 Sheet；桌面宽度下，每个分组都以语义化区段持续显示在正文旁，当前页面使用主题主色突出显示。\n\n## 搜索\n\n除非 `themeConfig.search` 为 `false`，否则本地搜索默认开启。搜索按需加载，可通过按钮或 `Control+K` / `Command+K` 打开，支持键盘选择，并在关闭后恢复焦点。search v2 记录页面语言，让当前语言结果得到正确排序与分组。\n\n## 多语言\n\nlocale 条目定义 BCP 47 `lang`、显示标签与路由 `root`，并可覆盖导航、侧栏、首页与界面消息。路由镜像后，语言切换会保留当前页面。匹配长度最长的已配置 locale root 决定文档与搜索语言。frontmatter `lang` 不会覆盖解析后的路由语言；需要另一种语言的内容应放在对应 locale root 下。\n\n视觉定制使用[主题令牌](/silen/zh/theme/tokens/)，React 行为使用[主题扩展](/silen/zh/theme/extensions-accessibility/)。\n",
      "description": "配置默认主题外壳、布局、搜索与多语言。"
    },
    {
      "route": "/zh/theme/tokens/",
      "title": "主题令牌",
      "markdown": "# 主题令牌\n\n覆盖语义 CSS 变量，不要依赖内部 utility class。令牌是默认主题行为与项目视觉身份之间稳定的边界。\n\n```css\n/* docs/.silen/custom.css */\n:root {\n  --silen-primary: oklch(0.55 0.17 245);\n  --silen-primary-foreground: oklch(0.99 0 0);\n  --silen-radius: 0.5rem;\n  --silen-content-width: 48rem;\n}\n\n.dark {\n  --silen-primary: oklch(0.76 0.12 245);\n}\n```\n\n从 `.silen/theme.tsx` 导入样式，让 Vite 同时把它加入 SSR 与客户端构建。\n\n## 颜色令牌\n\n核心语义集合包括 `--silen-background`、`--silen-foreground`、`--silen-card`、`--silen-primary`、`--silen-primary-foreground`、`--silen-muted`、`--silen-muted-foreground`、`--silen-border`、`--silen-input`、`--silen-ring` 与 `--silen-destructive`。secondary、accent、popover 令牌为交互组件提供同样的语义层。\n\n浅色值写在 `:root`，深色覆盖写在 `.dark`。保持前景/背景以及 primary/primary-foreground 之间的可读对比；外观控件允许用户明确选择深色、跟随系统或浅色。\n\n## 形状与布局\n\n- `--silen-radius` 控制统一圆角。\n- `--silen-nav-height` 定义顶部导航高度。\n- `--silen-sidebar-width` 控制桌面侧栏。\n- `--silen-content-width` 限制正文阅读宽度。\n- `--silen-layout-width` 限制首页与 page 布局宽度。\n\n每次只调整一层，并检查长标题、代码块、两种配色与移动导航。更宽不一定更好，正文过宽会降低扫读效率。\n\n令牌适合视觉变化；新增 MDX 组件、包装器、布局或 404 时再使用[主题扩展](/silen/zh/theme/extensions-accessibility/)。\n",
      "description": "用语义 CSS 变量定制 Silen 的颜色、形状与布局。"
    }
  ],
  "chunks": [
    {
      "id": "/ai/agent-contract/",
      "route": "/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [],
      "text": "The Agent Contract is a versioned, inspectable discovery layer. It keeps AI clients from guessing configuration fields, CLI syntax, MCP permissions, or deployed site routes.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/ai/agent-contract/#installed-package-contract",
      "route": "/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "Installed package contract"
      ],
      "text": "For creating or maintaining a local project, start at: The package manifest points to the exact version’s configuration API, CLI and MCP contracts, public TypeScript exports, guide, and task playbooks. For example, agent/tasks/create-site.md describes the supported activation path and links back to authoritative machine-readable resources rather than copying their definitions.",
      "code": [
        {
          "language": "text",
          "value": "@aicode-nexus/silen/agent/manifest.json"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/ai/agent-contract/#deployed-site-contract",
      "route": "/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "Deployed site contract"
      ],
      "text": "Each enabled production build publishes a site-specific entry point at /.well-known/silen/manifest.json , resolved under base . This official site’s live contract is the Silen manifest . The manifest schema has no deployment origin field. It describes the base, language, resources, tasks, and public project guidance. Resource and task URLs remain base-relative. Instructions and tasks are explicit public build input. Do not include local absolute paths, secrets, private endpoints, credentials, or unpublished operating details.",
      "code": [
        {
          "language": "ts",
          "value": "ai: {\n  contract: {\n    enabled: true,\n    instructions: '.silen/ai-public.md',\n    tasksDir: '.silen/ai-tasks',\n  },\n}"
        }
      ],
      "links": [
        "/silen/.well-known/silen/manifest.json"
      ],
      "order": 2
    },
    {
      "id": "/ai/agent-contract/#schema-version-2",
      "route": "/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "Schema version 2"
      ],
      "text": "The current manifest and API documents use schemaVersion: 2 . The manifest's MCP capability declares stdio , protocol versions 2025-11-25 and 2026-07-28 , an empty extension list, local-only operation, read-only default, and the --allow-write gate. The API document adds an outputSchema for every tool. Successful MCP calls expose the corresponding schema-validated structuredContent alongside text. This contract does not advertise remote transport or optional MCP extensions. Those capabilities require separate designs and authorization. The package also contains the generated filesystem Skill at dist/agent/skills/silen-docs-readonly , and the CLI API records silen ai skills plus --experimental-skills-over-mcp . The default manifest still says extensions: [] because an optional runtime flag is not a site capability. Skill text is procedural knowledge: it does not grant a host permission to run commands, use the network, write files, commit, push, or deploy.",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/ai/agent-contract/#client-behavior",
      "route": "/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "Client behavior"
      ],
      "text": "Codex, Claude Code, Cursor, and other clients should consume the same manifest instead of keeping client-specific API copies. When a client does not support the declared contract schema, it must follow linked public Markdown and remain read-only. For deployed content, the site manifest is authoritative; for code generation against an installed package, the package contract is authoritative. Continue with the local workspace and MCP .",
      "code": [],
      "links": [
        "/silen/ai/local-workspace-mcp/"
      ],
      "order": 4
    },
    {
      "id": "/ai/",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [],
      "text": "Silen treats AI access as part of the documentation build instead of an afterthought. The default output is deterministic, inspectable, and does not call a model. No model, API key, endpoint, embeddings service, or network is required for the core AI-ready documentation workflow.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/ai/#agent-contract",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Agent Contract"
      ],
      "text": "Silen gives an AI one versioned discovery entry point instead of making every client memorize a separate tutorial: For a local project, begin with @aicode-nexus/silen/agent/manifest.json from the installed package. It links to the exact config, CLI, MCP, and public TypeScript API plus task playbooks such as agent/tasks/create-site.md . For a deployed site, begin with /.well-known/silen/manifest.json . This official site publishes it at /silen/.well-known/silen/manifest.json . For bounded local reads, start pnpm silen mcp docs . It is read-only unless the user explicitly adds --allow-write . Codex, Claude Code, and Cursor should all read that same manifest and use the same local MCP command. Client setup stays thin; the contract remains the single API reference. If a client does not support the declared schema version, it must fall back to the linked public Markdown and remain read-only. The current manifest and API use schemaVersion: 2 . They declare local stdio , verified protocol versions 2025-11-25 and 2026-07-28 , an empty extension set, and every MCP tool's outputSchema .",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/ai/#read-only-agent-skill",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Read-only Agent Skill"
      ],
      "text": "The npm package deterministically generates one silen-docs-readonly Agent Skill from the canonical English and Chinese read-site and audit-site task packs. Its package root is dist/agent/skills/silen-docs-readonly ; it contains SKILL.md plus four progressively loaded references and no scripts, assets, write tasks, model calls, credentials, or implied permissions. The command creates only ./agent-skills/silen-docs-readonly and refuses to overwrite an existing directory. The filesystem form is the supported portable surface and remains usable offline.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen ai skills ./agent-skills"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/ai/#add-public-project-instructions",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Add public project instructions"
      ],
      "text": "Only publish instructions that are safe for every site visitor: These files become explicit public Agent instructions. Never place private paths, secrets, internal endpoints, or credentials in them.",
      "code": [
        {
          "language": "ts",
          "value": "export default defineConfig({\n  ai: {\n    contract: {\n      instructions: '.silen/ai-public.md',\n      tasksDir: '.silen/ai-tasks',\n    },\n  },\n})"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/ai/#public-ai-artifacts",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Public AI artifacts"
      ],
      "text": "Each production build can emit: llms.txt for a concise page map llms-full.txt for complete readable content ai-index.json for structured discovery clean Markdown routes for every public page Pages marked draft: true or ai: false are excluded from these artifacts.",
      "code": [],
      "links": [],
      "order": 4
    },
    {
      "id": "/ai/#copy-for-ai",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Copy for AI"
      ],
      "text": "The default theme lets readers copy clean page Markdown or a prompt-ready version with the canonical source URL. The copied content comes from the same build artifacts, so it stays aligned with the rendered page.",
      "code": [],
      "links": [],
      "order": 5
    },
    {
      "id": "/ai/#local-mcp-workspace",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Local MCP workspace"
      ],
      "text": "The MCP server uses the split SDK v2 and is read-only by default. Write tools appear only when it is started explicitly with --allow-write , and all writes remain inside the Markdown workspace. Successful calls return text plus schema-validated structuredContent ; remote transport is not enabled.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen mcp docs"
        }
      ],
      "links": [],
      "order": 6
    },
    {
      "id": "/ai/#model-free-quality-gate",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Model-free quality gate"
      ],
      "text": "Use the production search index itself as a deterministic retrieval contract: ai eval reads the committed .silen/ai-evals.json suite and the built .silen/dist/search-index.json ; it never calls a model or the network. Exit codes 0 , 1 , and 2 mean pass, retrieval failure, and setup failure. Version 1 keeps whole- topK matching. Version 2 adds optional expected.maxRank and reports its effective value plus matchedRank . Strict \"schemaVersion\": 3 requires both target arrays and an explicit rank bound: acceptable and forbidden are both present arrays with zero to 20 targets; at least one must be non-empty. At least one acceptable target must appear at or before maxRank , and every forbidden target must stay out of the diagnostic Top K. A negative-only case uses acceptable: [] and maxRank: topK . Unknown fields, overlapping targets, an empty combined target set, and invalid bounds are setup errors. Version 3 keeps authored case order and exposes matchedRank plus forbiddenMatches ; v1 and v2 JSON and human output remain compatible. For this repository, pnpm site:ai-check runs build, audit, evaluation, and source-map checks once. It saves the exact JSON report to artifacts/ai-eval/site-ai-eval.json for CI, Pages, and release comparison. The rebuildable .silen/ai/index.json workspace snapshot is optional. A missing or stale snapshot appears as an audit notice while MCP search continues to run from its in-memory index.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs"
        },
        {
          "language": "json",
          "value": "{\n  \"schemaVersion\": 3,\n  \"topK\": 5,\n  \"cases\": [\n    {\n      \"id\": \"install-quick-start\",\n      \"query\": \"How do I install and start a site?\",\n      \"expected\": {\n        \"acceptable\": [\n          { \"route\": \"/guide/\", \"heading\": \"Quick start\" },\n          { \"route\": \"/guide/cli-deployment/\" }\n        ],\n        \"forbidden\": [{ \"route\": \"/draft-notes/\" }],\n        \"maxRank\": 1\n      }\n    }\n  ]\n}"
        }
      ],
      "links": [],
      "order": 7
    },
    {
      "id": "/ai/#ask-ai",
      "route": "/ai/",
      "title": "AI-ready documentation",
      "headingPath": [
        "Ask AI"
      ],
      "text": "Ask AI is an optional endpoint integration. Silen never places provider keys in the generated site: your server owns authentication and streams a small NDJSON protocol back to the theme. With no explicitly configured endpoint, the Ask AI control and its bundle remain absent. Return to the getting started guide .",
      "code": [],
      "links": [
        "/silen/guide/"
      ],
      "order": 8
    },
    {
      "id": "/ai/local-workspace-mcp/",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [],
      "text": "The local AI workspace is deterministic and model-free. It gives tools a bounded Markdown root, an inspectable index, and explicit write permission without exposing arbitrary shell execution. No model, API key, endpoint, embeddings service, or network is required.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/ai/local-workspace-mcp/#initialize-index-and-audit",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [
        "Initialize, index, and audit"
      ],
      "text": "ai init creates wiki/ and the ignored .silen/ai/ cache without changing existing MDX. ai index rebuilds the optional .silen/ai/index.json workspace snapshot. ai audit checks links, citations, generated artifacts, and the production contract. A missing or stale snapshot is only a notice because MCP search uses an in-memory index.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/ai/local-workspace-mcp/#build-audit-and-evaluate",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [
        "Build, audit, and evaluate"
      ],
      "text": "ai eval reads .silen/ai-evals.json and the production .silen/dist/search-index.json ; it neither starts MCP nor calls a model or the network. Version 1 uses one route and optional heading within topK . Version 2 adds optional expected.maxRank . Strict \"schemaVersion\": 3 requires present acceptable and forbidden arrays, at least one target between them, and an explicit maxRank from 1 through topK . Negative-only cases use acceptable: [] and maxRank: topK . Version 3 reports matchedRank: null when no acceptable target appears and lists prohibited hits in forbiddenMatches . Exit 0 means every case passed, exit 1 means a retrieval expectation failed, and exit 2 means the suite or input is invalid. The full diagnostic Top K remains in stable case order. For the Silen repository, pnpm site:ai-check composes the complete read-only gate and saves exact evaluation JSON at artifacts/ai-eval/site-ai-eval.json . The optional .silen/ai/index.json snapshot remains non-blocking and does not replace the production search index.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/ai/local-workspace-mcp/#connect-an-mcp-client",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [
        "Connect an MCP client"
      ],
      "text": "Run the server from the repository root: The default server registers seven read-only tools: guide , list , search , read , backlinks , citations , and build . The build tool is a bounded preflight: it reads Markdown inputs and existing artifacts but does not load project config, execute MDX, invoke Vite, or write files.",
      "code": [
        {
          "language": "json",
          "value": "{\n  \"mcpServers\": {\n    \"silen\": {\n      \"command\": \"pnpm\",\n      \"args\": [\"silen\", \"mcp\", \"docs\"]\n    }\n  }\n}"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/ai/local-workspace-mcp/#protocol-and-structured-results",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [
        "Protocol and structured results"
      ],
      "text": "The command uses the stable split TypeScript SDK v2. One stdio entry accepts verified legacy 2025-11-25 and modern 2026-07-28 clients; see the official protocol-version guide . The server is read-only by default. Every successful tool call includes text and schema-validated structuredContent , and every listed tool declares an outputSchema . Remote transport is not enabled. For the string-valued guide tool, modern clients receive the native string; legacy clients receive the SDK's compatibility { result: ... } object. The object-valued tools keep their existing structured shape in both eras.",
      "code": [],
      "links": [
        "https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions"
      ],
      "order": 4
    },
    {
      "id": "/ai/local-workspace-mcp/#experimental-skills-over-mcp",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [
        "Experimental Skills over MCP"
      ],
      "text": "Filesystem installation does not require MCP. Hosts that explicitly support the draft Resources binding can opt into the same packaged bytes: The experiment declares io.modelcontextprotocol/skills , serves skill://index.json , and maps the five files beneath skill://silen-docs-readonly/ . It is local stdio only and read-only. The experiment is off by default. It adds no tools, scripts, subscriptions, network transport, or write authority; --allow-write remains a separate explicit tool-registration flag.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen mcp docs --experimental-skills-over-mcp"
        }
      ],
      "links": [],
      "order": 5
    },
    {
      "id": "/ai/local-workspace-mcp/#grant-writes-deliberately",
      "route": "/ai/local-workspace-mcp/",
      "title": "Local workspace and MCP",
      "headingPath": [
        "Grant writes deliberately"
      ],
      "text": "This explicit flag adds write , link , and append . Writes accept only workspace-relative .md or .mdx paths, reject traversal and escaping symlinks, use atomic replacement, and enforce a 2 MiB UTF-8 limit. It never adds a shell tool. Grant write mode only to a trusted local client for a bounded task. After a change, run the audit and site build, inspect the Git diff, and obtain separate authorization before committing or deploying. Ask AI is separate: it requires an explicitly configured endpoint. With no endpoint, Silen emits neither the control nor its bundle. Read Agent Contract for client discovery rules.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen mcp docs --allow-write"
        }
      ],
      "links": [
        "/silen/ai/agent-contract/"
      ],
      "order": 6
    },
    {
      "id": "/guide/cli-deployment/",
      "route": "/guide/cli-deployment/",
      "title": "CLI and deployment",
      "headingPath": [],
      "text": "Silen exposes a small CLI. Run it through the project package manager so the command and Agent Contract always match the installed version.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/guide/cli-deployment/#primary-commands",
      "route": "/guide/cli-deployment/",
      "title": "CLI and deployment",
      "headingPath": [
        "Primary commands"
      ],
      "text": "init <root> writes a starter config and homepage without replacing existing targets. dev [root] starts Vite-backed development. build [root] creates the static output and exits after validation. preview [root] serves that output with route and locale-aware 404 behavior. The server commands accept --host and --port ; the build has no deployment side effects. AI workspace commands are separate: ai skills requires the parent destination, creates only silen-docs-readonly , and never overwrites it; optional MCP Resource exposure uses pnpm silen mcp docs --experimental-skills-over-mcp and remains experimental and off by default. The MCP command is read-only unless a trusted user explicitly starts it with --allow-write . The model-free ai eval command reads .silen/ai-evals.json and .silen/dist/search-index.json ; use --json for CI. It needs no model, API key, endpoint, embeddings service, or network. Suite \"schemaVersion\": 1 retains whole- topK matching. Version 2 supports case-specific expected.maxRank , defaulting to topK , and reports matchedRank while preserving the full diagnostic result list.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen init docs\npnpm silen dev docs --host 127.0.0.1 --port 5173\npnpm silen build docs\npnpm silen preview docs --port 4173"
        },
        {
          "language": "sh",
          "value": "pnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen ai skills ./agent-skills\npnpm silen mcp docs"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/guide/cli-deployment/#static-deployment",
      "route": "/guide/cli-deployment/",
      "title": "CLI and deployment",
      "headingPath": [
        "Static deployment"
      ],
      "text": "Publish the contents of docs/.silen/dist to any static host. Configure the host to serve generated index.html files and assets as written. For a project site such as https://example.github.io/handbook/ , use: Do not repeat /handbook/ in siteUrl . The build combines the origin and base for canonical URLs, hreflang and x-default locale alternates, sitemap entries, and basic Open Graph/Twitter metadata. Markdown and Agent Contract URLs remain base-relative.",
      "code": [
        {
          "language": "ts",
          "value": "export default defineConfig({\n  siteUrl: 'https://example.github.io',\n  base: '/handbook/',\n})"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/guide/cli-deployment/#release-check",
      "route": "/guide/cli-deployment/",
      "title": "CLI and deployment",
      "headingPath": [
        "Release check"
      ],
      "text": "Repository maintainers run one canonical command: It executes site:build -> ai audit -> ai eval -> check:no-maps once and in order. pnpm site:check is a compatibility alias. Core CI, GitHub Pages, and npm release all use the canonical command; an audit or evaluation failure blocks deployment or publication. The official .silen/ai-evals.json uses \"schemaVersion\": 3 , explicit maxRank , and present acceptable and forbidden target arrays. Reports keep the diagnostic topK , stable matchedRank , and forbidden evidence. Each workflow uploads artifacts/ai-eval/site-ai-eval.json with an always condition when the evaluator produced valid JSON, including retrieval failures or a later source-map failure. Then preview a nested route directly, open a missing route, and inspect llms.txt plus .well-known/silen/manifest.json . A successful build proves files were generated; those direct checks prove the host serves them at the expected base. Ask AI remains endpoint-only. If no endpoint is configured, its control and bundle are absent. Use Reference for command syntax and troubleshooting.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm site:ai-check"
        }
      ],
      "links": [
        "/silen/reference/"
      ],
      "order": 3
    },
    {
      "id": "/guide/configuration/",
      "route": "/guide/configuration/",
      "title": "Configuration",
      "headingPath": [],
      "text": "Create .silen/config.ts in the content root and export defineConfig(...) . The file is trusted project code; keep secrets out because values can affect public HTML and build artifacts.",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig } from '@aicode-nexus/silen'\n\nexport default defineConfig({\n  title: 'Engineering handbook',\n  description: 'Operating knowledge for the product team.',\n  lang: 'en-US',\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  outDir: '.silen/dist',\n  onBrokenLinks: 'error',\n})"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/guide/configuration/#url-and-metadata-fields",
      "route": "/guide/configuration/",
      "title": "Configuration",
      "headingPath": [
        "URL and metadata fields"
      ],
      "text": "base is the normalized absolute pathname where the site is mounted; use / for a domain root or /handbook/ for a subpath. siteUrl is only the HTTP(S) origin—put the deployment path in base , not in siteUrl . Together they drive canonical links, hreflang and x-default locale alternates, the sitemap, and basic Open Graph/Twitter metadata. Markdown and Agent Contract URLs remain base-relative. lang is a BCP 47 language tag.",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/guide/configuration/#navigation-and-locales",
      "route": "/guide/configuration/",
      "title": "Configuration",
      "headingPath": [
        "Navigation and locales"
      ],
      "text": "themeConfig.nav and themeConfig.sidebar accept { text, link } entries. Root-relative theme links are resolved under base . Locale entries can provide a root , translated navigation, sidebar, home hero, and message overrides: Keep locale route trees mirrored so the language switch can preserve the current route rather than returning to a homepage.",
      "code": [
        {
          "language": "ts",
          "value": "themeConfig: {\n  locales: [\n    { lang: 'en-US', label: 'English', root: '/' },\n    { lang: 'zh-CN', label: '中文', root: '/zh/' },\n  ],\n  search: true,\n}"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/guide/configuration/#integrations-and-ai",
      "route": "/guide/configuration/",
      "title": "Configuration",
      "headingPath": [
        "Integrations and AI"
      ],
      "text": "analytics configures Google, Baidu, or custom scripts. plugins is an ordered array of trusted plugin factories. The ai booleans control llms.txt , llms-full.txt , Markdown routes, and ai-index.json ; all default to enabled. The Agent Contract is also enabled by default and can include explicit public instructions and tasks. See the complete field table in Reference and integration examples in Integrations .",
      "code": [
        {
          "language": "ts",
          "value": "ai: {\n  llmsTxt: true,\n  llmsFullTxt: true,\n  markdownRoutes: true,\n  index: true,\n  contract: { enabled: true, instructions: '.silen/ai-public.md' },\n}"
        }
      ],
      "links": [
        "/silen/reference/",
        "/silen/integrations/"
      ],
      "order": 3
    },
    {
      "id": "/guide/",
      "route": "/guide/",
      "title": "Quick start",
      "headingPath": [],
      "text": "Silen turns a directory of Markdown and MDX into a server-rendered static site, local search, and deterministic AI-readable output. Use Node.js ^20.19.0 || >=22.12.0 .",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/guide/#install-and-activate",
      "route": "/guide/",
      "title": "Quick start",
      "headingPath": [
        "Install and activate"
      ],
      "text": "From your project root, install Silen, then activate a docs directory: Silen installs its required react and react-dom runtime, including MDX's react/jsx-runtime , automatically. init creates docs/.silen/config.ts and docs/index.mdx . It is safe for a new or existing directory: if either target already exists, Silen reports the collision instead of overwriting authored content.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm add -D @aicode-nexus/silen\npnpm silen init docs"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/guide/#develop",
      "route": "/guide/",
      "title": "Quick start",
      "headingPath": [
        "Develop"
      ],
      "text": "Edit docs/index.mdx or add another .md or .mdx file. File routes are created from the directory tree, and client navigation updates without a full page reload. Local search stays on the site; no hosted search account is required.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen dev docs"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/guide/#build-and-inspect",
      "route": "/guide/",
      "title": "Quick start",
      "headingPath": [
        "Build and inspect"
      ],
      "text": "The default output directory is docs/.silen/dist . A build emits complete HTML plus AI artifacts such as llms.txt , llms-full.txt , ai-index.json , and clean Markdown routes. Draft pages and pages with ai: false remain out of those AI-facing artifacts.",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen build docs\npnpm silen preview docs"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/guide/#make-the-first-decision-explicit",
      "route": "/guide/",
      "title": "Quick start",
      "headingPath": [
        "Make the first decision explicit"
      ],
      "text": "Set base when the site will live below a host subpath, and set siteUrl to the origin when canonical metadata is required: Continue with project structure , configuration , or inspect the live AI output .",
      "code": [
        {
          "language": "ts",
          "value": "export default defineConfig({\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  onBrokenLinks: 'error',\n})"
        }
      ],
      "links": [
        "/silen/guide/project-structure/",
        "/silen/guide/configuration/",
        "/silen/ai/"
      ],
      "order": 4
    },
    {
      "id": "/guide/markdown-mdx/",
      "route": "/guide/markdown-mdx/",
      "title": "Markdown and MDX",
      "headingPath": [],
      "text": "Use Markdown for durable prose and MDX when a page benefits from a typed React component. Both produce the same route, SSR HTML, search record, and optional AI-readable Markdown. GitHub-flavored Markdown tables, task lists, strikethrough, autolinks, and footnotes keep the same meaning across each output.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/guide/markdown-mdx/#frontmatter",
      "route": "/guide/markdown-mdx/",
      "title": "Markdown and MDX",
      "headingPath": [
        "Frontmatter"
      ],
      "text": "Frontmatter supplies page metadata and layout decisions: doc is the default layout. home renders the configured hero before page MDX, and page keeps the application shell without documentation pagination. draft: true excludes the page from AI-readable artifacts and indexes only. It does not stop route scanning, building, or publishing; ai: false has the same AI-output boundary for an otherwise public page. Never store private content in the content tree. Keep confidential material outside the site root and its build inputs.",
      "code": [
        {
          "language": "md",
          "value": "---\ntitle: Service runbook\ndescription: Diagnose and recover the checkout service.\nlayout: doc\nlang: en-US\nai: true\n---"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/guide/markdown-mdx/#links-and-headings",
      "route": "/guide/markdown-mdx/",
      "title": "Markdown and MDX",
      "headingPath": [
        "Links and headings"
      ],
      "text": "Prefer stable site routes and descriptive link text. Under a non-root base , theme-config links are base-aware automatically; authored root-relative links must point at the mounted site path. During build, Silen validates internal page targets and can fail, warn, or ignore according to onBrokenLinks . Headings create the document outline. Keep one # title, then descend without skipping levels so the outline remains useful to keyboard and screen-reader users.",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/guide/markdown-mdx/#code-and-components",
      "route": "/guide/markdown-mdx/",
      "title": "Markdown and MDX",
      "headingPath": [
        "Code and components"
      ],
      "text": "Fenced code blocks receive syntax highlighting and a keyboard-accessible copy button. Silen loads supported Shiki grammars on demand, including mdx , python , and JSON Lines for ndjson fences. Unknown language names safely fall back to plain text. MDX can import components and use expressions: MDX executes during the build and can import project code. Treat every MDX file and component as trusted source; Silen is not a sandbox for untrusted user submissions. Keep browser-only access inside effects or client setup so server rendering remains deterministic. For site-wide components, extend the default theme .",
      "code": [
        {
          "language": "mdx",
          "value": "import Status from './components/status.tsx'\n\n## Current status\n\n<Status service=\"checkout\" />"
        }
      ],
      "links": [
        "/silen/theme/extensions-accessibility/"
      ],
      "order": 3
    },
    {
      "id": "/guide/plugins",
      "route": "/guide/plugins",
      "title": "Plugins",
      "headingPath": [],
      "text": "Silen plugins extend the documentation lifecycle without importing internal files. A plugin is a local or npm factory configured directly in .silen/config.ts :",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst readingTime = definePlugin(\n  (_context, options: { wordsPerMinute: number }) => ({\n    name: 'reading-time',\n    transformPageData(page, context) {\n      const words = context.source.trim().split(/\\s+/).length\n      return {\n        data: {\n          ...page.data,\n          minutes: Math.max(1, Math.ceil(words / options.wordsPerMinute)),\n        },\n      }\n    },\n  }),\n)\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/guide/plugins#lifecycle",
      "route": "/guide/plugins",
      "title": "Plugins",
      "headingPath": [
        "Lifecycle"
      ],
      "text": "Silen runs plugins in configuration order. The first release supports config , configResolved , extendMdx , vite , clientModules , transformPageData , transformHead , and buildEnd . Use extendMdx for Remark and Rehype plugins. Use vite for standard Vite integrations. virtual:silen/* modules remain protected by core. Use transformPageData for JSON-serializable metadata consumed by SSR, hydration, search, and AI artifacts. Use transformHead for typed meta , link , script , style , or noscript entries. Use clientModules for an SSR-safe wrapRoot and optional browser-only setup function. Use buildEnd to add files such as a sitemap after the output directory is installed. Every plugin needs a name ; add a distinct id when configuring multiple instances. Failures include the identity and hook, such as Silen plugin analytics:docs failed in transformHead .",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/guide/plugins#ssr-and-compatibility",
      "route": "/guide/plugins",
      "title": "Plugins",
      "headingPath": [
        "SSR and compatibility"
      ],
      "text": "Client modules are imported during SSR and hydration. Do not access window or document at module scope or inside wrapRoot ; browser APIs belong in setup . Plugin packages should declare @aicode-nexus/silen as a peer dependency and import only documented public exports. See the npm-ready sitemap, reading-time, and analytics-client examples in examples/plugins .",
      "code": [],
      "links": [
        "https://github.com/AICode-Nexus/silen/tree/main/examples/plugins"
      ],
      "order": 2
    },
    {
      "id": "/guide/project-structure/",
      "route": "/guide/project-structure/",
      "title": "Project structure",
      "headingPath": [],
      "text": "A Silen site is a content root. Keep content and its site configuration together so local development, production builds, and AI tools all resolve the same boundary.",
      "code": [
        {
          "language": "text",
          "value": "docs/\n├── .silen/\n│   ├── config.ts\n│   ├── theme.tsx          # optional theme extension\n│   ├── ai-public.md       # optional public agent instructions\n│   └── dist/              # generated; do not author here\n├── public/\n│   └── logo.svg\n├── assets/\n│   └── architecture.png\n├── guide/\n│   └── index.mdx\n└── index.mdx"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/guide/project-structure/#content-becomes-routes",
      "route": "/guide/project-structure/",
      "title": "Project structure",
      "headingPath": [
        "Content becomes routes"
      ],
      "text": "Both .md and .mdx files are scanned. index.mdx has compiler route / ; guide.mdx and guide/index.mdx both have compiler route /guide . The directory form emits guide/index.html , with the usual browser URL /guide/ . Do not create both source forms for the same route; the build rejects duplicate routes instead of choosing one silently. Use directories for sections that will grow. This keeps nearby images, examples, and future child pages easy to locate while preserving stable URLs.",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/guide/project-structure/#configuration-and-theme",
      "route": "/guide/project-structure/",
      "title": "Project structure",
      "headingPath": [
        "Configuration and theme"
      ],
      "text": ".silen/config.ts is executable, trusted project configuration. It defines the site title, base, locales, navigation, integrations, and generated AI output. .silen/theme.tsx is optional and should extend the default theme when only a component, layout, or wrapper needs to change.",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/guide/project-structure/#static-and-imported-assets",
      "route": "/guide/project-structure/",
      "title": "Project structure",
      "headingPath": [
        "Static and imported assets"
      ],
      "text": "Place files that must keep a public filename under public/ and reference them from the site root, for example /logo.svg in configuration. Silen resolves theme links and images against the configured base . Import content-owned images from MDX when they should participate in the Vite asset pipeline.",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/guide/project-structure/#generated-state",
      "route": "/guide/project-structure/",
      "title": "Project structure",
      "headingPath": [
        "Generated state"
      ],
      "text": ".silen/dist is the default production output and .silen/.temp is temporary build state. Treat both as disposable. The local AI workspace uses wiki/ for authored Markdown and .silen/ai/ for its generated index; review the workspace boundary before enabling writes. Next, define the site in configuration .",
      "code": [],
      "links": [
        "/silen/ai/local-workspace-mcp/",
        "/silen/guide/configuration/"
      ],
      "order": 4
    },
    {
      "id": "/",
      "route": "/",
      "title": "Silen",
      "headingPath": [],
      "text": "Activate one docs directory From folder to knowledge interface Inspect the evidence Live output from this build llms.txt Concise corpus map llms-full.txt Complete readable corpus ai-index.json Structured page discovery Agent manifest Versioned capability contract Guide Markdown Clean route-level source One source, three proofs Useful to readers, agents, and maintainers Human reading AI consumption Extensibility Open source, deliberately small Build the documentation layer with us AI Dev Hub on WeChat",
      "code": [
        {
          "language": "sh",
          "value": "pnpm add -D @aicode-nexus/silen\npnpm silen init docs\npnpm silen dev docs"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/integrations/",
      "route": "/integrations/",
      "title": "Integrations",
      "headingPath": [],
      "text": "Silen keeps integrations explicit. Plugins run trusted build or client code, analytics is configured at the site layer, and Ask AI talks only to an endpoint you operate. None of these features requires importing internal Silen files.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/integrations/#plugins",
      "route": "/integrations/",
      "title": "Integrations",
      "headingPath": [
        "Plugins"
      ],
      "text": "Plugins are ordered factories in .silen/config.ts . Use them for MDX processors, Vite integrations, page metadata, head entries, client setup, or post-build output: Every plugin has a name ; add an id for multiple instances. Hooks execute in configuration order and failures report the plugin identity plus hook. Read the complete plugin lifecycle .",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig } from '@aicode-nexus/silen'\nimport readingTime from './plugins/reading-time'\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})"
        }
      ],
      "links": [
        "/silen/guide/plugins"
      ],
      "order": 1
    },
    {
      "id": "/integrations/#analytics",
      "route": "/integrations/",
      "title": "Integrations",
      "headingPath": [
        "Analytics"
      ],
      "text": "Analytics is theme-independent and production-only. Configure Google, Baidu, or an ordered custom provider: Silen reports the initial page and later client-route changes while ignoring hash-only navigation. Google users should disable automatic history-change pageviews in Enhanced Measurement to avoid duplicates. A custom provider can load external or inline scripts and listen for silen:pageview . Scripts are trusted public code; never embed credentials.",
      "code": [
        {
          "language": "ts",
          "value": "analytics: [\n  { provider: 'google', id: 'G-XXXXXXXXXX' },\n  { provider: 'baidu', id: 'site-id' },\n]"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/integrations/#ask-ai",
      "route": "/integrations/",
      "title": "Integrations",
      "headingPath": [
        "Ask AI"
      ],
      "text": "Ask AI is an optional theme endpoint, not a bundled model provider:",
      "code": [
        {
          "language": "ts",
          "value": "themeConfig: {\n  ai: { endpoint: '/api/ask' },\n}"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/integrations/#ask-ai-request",
      "route": "/integrations/",
      "title": "Integrations",
      "headingPath": [
        "Ask AI request"
      ],
      "text": "Silen sends an HTTP POST with Content-Type: application/json . The request contract is exactly: selectedText is optional; omit it when the reader has not selected content. Messages can include prior user and assistant turns. A concrete request is:",
      "code": [
        {
          "language": "ts",
          "value": "interface AskAiRequest {\n  route: string\n  selectedText?: string\n  messages: Array<{\n    role: 'user' | 'assistant'\n    content: string\n  }>\n}"
        },
        {
          "language": "json",
          "value": "{\n  \"route\": \"/guide/\",\n  \"selectedText\": \"pnpm silen init docs\",\n  \"messages\": [\n    { \"role\": \"user\", \"content\": \"How do I start?\" },\n    { \"role\": \"assistant\", \"content\": \"Install the package first.\" }\n  ]\n}"
        }
      ],
      "links": [],
      "order": 4
    },
    {
      "id": "/integrations/#ask-ai-response",
      "route": "/integrations/",
      "title": "Integrations",
      "headingPath": [
        "Ask AI response"
      ],
      "text": "Return a successful streaming response with either Content-Type: application/x-ndjson or Content-Type: application/ndjson . This NDJSON response writes one JSON object per line. The event shapes are text { type: 'text', value: string } , citation { type: 'citation', title: string, url: string } , and error { type: 'error', message: string } : Silen supplies an AbortSignal to the request and aborts a superseded stream or a stream whose dialog closes. Treat that signal and the disconnected HTTP request as cancellation: stop upstream provider work and release resources. Your endpoint owns server-side authentication. Keep provider keys and raw provider errors on the server, and return a safe public failure instead. With no endpoint, Silen emits no Ask AI control and no Ask AI client bundle. For deterministic, provider-free AI access, use the generated artifacts and local MCP workspace .",
      "code": [
        {
          "language": "ndjson",
          "value": "{\"type\":\"text\",\"value\":\"Install with pnpm.\"}\n{\"type\":\"citation\",\"title\":\"Quick start\",\"url\":\"/guide/\"}\n{\"type\":\"error\",\"message\":\"Unable to answer.\"}"
        }
      ],
      "links": [
        "/silen/ai/",
        "/silen/ai/local-workspace-mcp/"
      ],
      "order": 5
    },
    {
      "id": "/plugins/",
      "route": "/plugins/",
      "title": "Plugins",
      "headingPath": [],
      "text": "This route remains available for existing bookmarks. Silen’s plugin API is the ordered, public extension boundary for build and client integrations. A plugin factory is configured in .silen/config.ts , receives the current command and root, and returns a named plugin. Available hooks cover configuration, resolved configuration, Remark/Rehype, Vite, client modules, page data, head entries, and build completion. Hooks run in configuration order. Client modules must be safe during SSR: browser APIs belong in setup , not module scope or wrapRoot . Plugin packages should use @aicode-nexus/silen as a peer dependency and import only documented exports. Continue to the canonical plugin guide for lifecycle, identity, failure, and packaging details, or see Integrations for analytics and Ask AI.",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst metadata = definePlugin(() => ({\n  name: 'product-metadata',\n  transformPageData(page) {\n    return { data: { ...page.data, product: 'checkout' } }\n  },\n}))\n\nexport default defineConfig({ plugins: [metadata] })"
        }
      ],
      "links": [
        "/silen/guide/plugins",
        "/silen/integrations/"
      ],
      "order": 0
    },
    {
      "id": "/reference/",
      "route": "/reference/",
      "title": "Reference",
      "headingPath": [],
      "text": "This page is the compact operational reference. Use the linked guides for explanations and examples.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/reference/#configuration",
      "route": "/reference/",
      "title": "Reference",
      "headingPath": [
        "Configuration"
      ],
      "text": "Field Default Purpose title Silen Human-readable site title description empty Generated page metadata lang en-US Default BCP 47 language base / Normalized deployment pathname siteUrl unset Canonical HTTP(S) origin outDir .silen/dist Output relative to content root onBrokenLinks error error , warn , or ignore themeConfig {} Navigation, locales, home, search, Ask AI analytics [] Ordered production analytics providers plugins [] Ordered trusted plugin entries ai.* enabled AI files, Markdown routes, index, contract base must start with / , contain no query/hash or traversal, and is normalized with a trailing slash. siteUrl is an origin only, without credentials, path, query, or fragment.",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/reference/#cli",
      "route": "/reference/",
      "title": "Reference",
      "headingPath": [
        "CLI"
      ],
      "text": "Command Effect silen init <root> Safely create starter config and homepage silen dev [root] Start development; accepts --host , --port silen build [root] Validate and generate static output silen preview [root] Serve output; accepts --host , --port silen ai <init|index|audit|eval> [path] Manage and evaluate the local AI workspace silen ai skills <destination> Materialize the packaged silen-docs-readonly Skill without overwrite silen mcp [root] Serve read-only MCP; optional --allow-write and experimental --experimental-skills-over-mcp The package stores the portable Skill at dist/agent/skills/silen-docs-readonly . The URI skill://silen-docs-readonly/SKILL.md exists only when --experimental-skills-over-mcp is present; the default Agent Contract remains extensions: [] .",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/reference/#mcp-and-agent-contract",
      "route": "/reference/",
      "title": "Reference",
      "headingPath": [
        "MCP and Agent Contract"
      ],
      "text": "The local MCP command uses SDK v2 over stdio and verifies 2025-11-25 and 2026-07-28 . It exposes seven read-only tools by default and three additional write tools with --allow-write ; successful calls include text and validated structuredContent . Remote transport is not enabled. Agent Contract manifest and API files use schemaVersion: 2 . The manifest declares the protocol versions and empty extensions; the API declares each tool's outputSchema .",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/reference/#ai-evaluation-suites",
      "route": "/reference/",
      "title": "Reference",
      "headingPath": [
        "AI evaluation suites"
      ],
      "text": ".silen/ai-evals.json is strict JSON. Version 1 matches one route and optional heading within topK ; version 2 adds optional expected.maxRank . Version 3 uses this strict shape: Field Requirement schemaVersion Exact integer 3 topK Integer 1..20 cases One to 500 ordered cases expected.acceptable Required array of zero to 20 unique targets expected.forbidden Required array of zero to 20 unique targets expected.maxRank Required integer 1..topK ; exact topK for negative-only cases Target Strict { route, heading? } ; route starts with / At least one target array must be non-empty. Normalized duplicates, overlap within an array, overlap between acceptable and forbidden , and unknown fields are invalid. Version 3 reports preserve ordered cases , matchedRank , forbiddenMatches , and full diagnostic Top K; v1/v2 behavior remains compatible. Evaluation is read-only and model-free. Repository maintainers run pnpm site:ai-check ; its exact stable report is artifacts/ai-eval/site-ai-eval.json .",
      "code": [],
      "links": [],
      "order": 4
    },
    {
      "id": "/reference/#troubleshooting",
      "route": "/reference/",
      "title": "Reference",
      "headingPath": [
        "Troubleshooting"
      ],
      "text": "A link works locally but fails after deployment. Confirm the host mount matches base , authored root-relative content links include that mount, and the host serves nested index.html files. Canonical URLs include the path twice. Keep siteUrl to the origin and put the path only in base . The language switch returns a missing page. Create the exact mirrored route under every locale root and include it in translated navigation. Build reports a duplicate route. Remove either topic.mdx or topic/index.mdx ; both resolve to the same public route. A build fails after pnpm reports an ignored esbuild build script. Approve only that dependency with pnpm approve-builds esbuild , reinstall, and retry. No approval is needed when the build already succeeds. MCP write tools are absent. This is the safe default. Start the server with --allow-write only after the user authorizes a bounded write task. See configuration and CLI/deployment for longer guidance.",
      "code": [],
      "links": [
        "/silen/guide/configuration/",
        "/silen/guide/cli-deployment/"
      ],
      "order": 5
    },
    {
      "id": "/theme/extensions-accessibility/",
      "route": "/theme/extensions-accessibility/",
      "title": "Theme extensions and accessibility",
      "headingPath": [],
      "text": "Extend the default theme when tokens and configuration are not enough. A theme can replace layouts or MDX components, provide a custom 404, and wrap the React root while inheriting everything else. defineTheme merges inherited layouts and components by key. NotFound is inherited unless replaced. When both base and extension define wrapRoot , the extension wrapper composes outside the base wrapper. Recursive extension is rejected.",
      "code": [
        {
          "language": "tsx",
          "value": "// docs/.silen/theme.tsx\nimport type { ReactNode } from 'react'\nimport DefaultTheme, { defineTheme } from '@aicode-nexus/silen/theme'\nimport './custom.css'\n\nfunction Note({ children }: { readonly children?: ReactNode }) {\n  return <aside className=\"product-note\">{children}</aside>\n}\n\nexport default defineTheme({\n  extends: DefaultTheme,\n  components: { Note },\n  wrapRoot({ children }) {\n    return <div data-product-docs=\"\">{children}</div>\n  },\n})"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/theme/extensions-accessibility/#ssr-safe-extensions",
      "route": "/theme/extensions-accessibility/",
      "title": "Theme extensions and accessibility",
      "headingPath": [
        "SSR-safe extensions"
      ],
      "text": "Theme modules and root wrappers run during server rendering and hydration. Do not read window , document , or localStorage at module scope or directly in render. Put browser behavior in an effect or plugin client setup function and return cleanup when registering listeners.",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/theme/extensions-accessibility/#accessibility-contract",
      "route": "/theme/extensions-accessibility/",
      "title": "Theme extensions and accessibility",
      "headingPath": [
        "Accessibility contract"
      ],
      "text": "The default shell includes a skip link and visible focus indicators. Mobile navigation is a labelled modal: opening moves focus into navigation, Escape closes it, and focus returns to the trigger. Search supports its shortcut, arrow-key selection, Enter, Escape, and focus restoration. Code-copy controls are buttons with live status labels. The appearance control is an explicit dark/system/light radio group. Its inline head script applies the stored preference before hydration to prevent a color flash, while system mode follows operating-system changes. Nonessential transitions respect reduced-motion preferences. When replacing an interactive component, keep its accessible name, keyboard path, focus behavior, and server-rendered fallback. Test without a pointer, with 200% zoom, and with reduced motion before shipping.",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/theme/",
      "route": "/theme/",
      "title": "Theme, layouts, and navigation",
      "headingPath": [],
      "text": "The default theme is a responsive documentation shell rather than a closed template. It supplies navigation, sidebars, page outlines, local search, appearance controls, code copying, pagination, home heroes, and a complete 404 page. Start with configuration; extend React only when a product requirement cannot be expressed there.",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/theme/#layouts",
      "route": "/theme/",
      "title": "Theme, layouts, and navigation",
      "headingPath": [
        "Layouts"
      ],
      "text": "Choose a content layout in frontmatter: doc is the default. It applies reading typography, the heading outline, and previous/next links derived from the sidebar. home renders the locale-resolved configured hero and optional feature row before page MDX in a full-width shell. page keeps navigation and a neutral article container without documentation paging. Home hero artwork can provide separate light and dark assets while keeping one accessible description:",
      "code": [
        {
          "language": "md",
          "value": "---\nlayout: doc\n---"
        },
        {
          "language": "ts",
          "value": "themeConfig: {\n  home: {\n    hero: {\n      image: {\n        src: '/workflow-light.jpg',\n        darkSrc: '/workflow-dark.jpg',\n        alt: 'Documentation workflow',\n      },\n    },\n  },\n}"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/theme/#navigation-and-sidebar",
      "route": "/theme/",
      "title": "Theme, layouts, and navigation",
      "headingPath": [
        "Navigation and sidebar"
      ],
      "text": "Internal theme links are resolved under base . HTTP(S) nav links use ordinary browser navigation in the current context. Nav items pass only href ; they do not automatically add a new context or relationship attributes. MDX-authored links can explicitly set target=\"_blank\" and rel=\"noopener noreferrer\" when a new context is genuinely useful. Below 960px the persistent sidebar becomes a labelled modal sheet with collapsible groups. At desktop widths, every group remains visible as a semantic section beside the document, and the current page uses the primary theme treatment.",
      "code": [
        {
          "language": "ts",
          "value": "themeConfig: {\n  logo: { src: '/logo.svg', alt: 'Product docs' },\n  nav: [\n    { text: 'Guide', link: '/guide/' },\n    { text: 'GitHub', link: 'https://github.com/example/project' },\n  ],\n  sidebar: [\n    {\n      text: 'Getting started',\n      items: [{ text: 'Quick start', link: '/guide/' }],\n    },\n  ],\n}"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/theme/#search",
      "route": "/theme/",
      "title": "Theme, layouts, and navigation",
      "headingPath": [
        "Search"
      ],
      "text": "Local search is enabled unless themeConfig.search is false . It loads on demand, opens from the search button or Control+K / Command+K , supports keyboard selection, and restores focus when dismissed. Search v2 records page language so results from the active locale are ranked and grouped correctly.",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/theme/#locales",
      "route": "/theme/",
      "title": "Theme, layouts, and navigation",
      "headingPath": [
        "Locales"
      ],
      "text": "Locale entries define a BCP 47 lang , label, and route root ; they may override nav, sidebar, home, and UI messages. Mirrored routes let the language switch preserve the current page. The longest matching configured locale root controls document and search language. Frontmatter lang does not override the resolved route locale; content requiring another language should live under the corresponding locale root. Customize visual values with theme tokens or compose React behavior through theme extensions .",
      "code": [],
      "links": [
        "/silen/theme/tokens/",
        "/silen/theme/extensions-accessibility/"
      ],
      "order": 4
    },
    {
      "id": "/theme/tokens/",
      "route": "/theme/tokens/",
      "title": "Theme tokens",
      "headingPath": [],
      "text": "Override semantic CSS variables instead of styling internal utility classes. Tokens are the stable boundary between the default theme’s behavior and a project’s visual identity. Import the stylesheet from .silen/theme.tsx so Vite includes it in both SSR and the client bundle.",
      "code": [
        {
          "language": "css",
          "value": "/* docs/.silen/custom.css */\n:root {\n  --silen-primary: oklch(0.55 0.17 245);\n  --silen-primary-foreground: oklch(0.99 0 0);\n  --silen-radius: 0.5rem;\n  --silen-content-width: 48rem;\n}\n\n.dark {\n  --silen-primary: oklch(0.76 0.12 245);\n}"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/theme/tokens/#color-tokens",
      "route": "/theme/tokens/",
      "title": "Theme tokens",
      "headingPath": [
        "Color tokens"
      ],
      "text": "The primary semantic set is --silen-background , --silen-foreground , --silen-card , --silen-card-foreground , --silen-primary , --silen-primary-foreground , --silen-muted , --silen-muted-foreground , --silen-border , --silen-input , --silen-ring , and --silen-destructive . Secondary, accent, and popover tokens map the same semantics to interactive primitives. Define light values on :root and dark overrides on .dark . Preserve usable contrast between foreground/background and primary/primary-foreground pairs; the appearance control can switch explicitly among dark, system, and light.",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/theme/tokens/#shape-and-layout-tokens",
      "route": "/theme/tokens/",
      "title": "Theme tokens",
      "headingPath": [
        "Shape and layout tokens"
      ],
      "text": "--silen-radius controls the shared corner language. --silen-nav-height sizes the fixed top navigation. --silen-sidebar-width controls the desktop navigation rail. --silen-content-width limits readable document lines. --silen-layout-width limits wide home and page layouts. Change one layer at a time and test long titles, code blocks, both appearance modes, and mobile navigation. Increasing content width may look efficient on a dashboard but makes prose harder to scan.",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/theme/tokens/#extension-boundary",
      "route": "/theme/tokens/",
      "title": "Theme tokens",
      "headingPath": [
        "Extension boundary"
      ],
      "text": "Tokens are best for visual changes. Use a theme extension only when you need a new MDX component, wrapper, layout, or 404 component.",
      "code": [],
      "links": [
        "/silen/theme/extensions-accessibility/"
      ],
      "order": 3
    },
    {
      "id": "/zh/ai/agent-contract/",
      "route": "/zh/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [],
      "text": "Agent Contract 是版本化、可检查的发现层，让 AI 客户端不必猜测配置字段、CLI 语法、MCP 权限与部署路由。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/ai/agent-contract/#安装包契约",
      "route": "/zh/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "安装包契约"
      ],
      "text": "创建或维护本地项目时，从这里开始： 包清单会指向当前准确版本的配置 API、CLI/MCP 契约、公共 TypeScript 导出、指南与任务手册。例如 agent/tasks/create-site.md 描述受支持的激活路径，并链接回权威机器可读资源，而不是复制定义。",
      "code": [
        {
          "language": "text",
          "value": "@aicode-nexus/silen/agent/manifest.json"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/ai/agent-contract/#部署站点契约",
      "route": "/zh/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "部署站点契约"
      ],
      "text": "开启后，每次生产构建都会发布站点专属的 /.well-known/silen/manifest.json ，并按 base 解析。当前官网的 实时清单 描述 base、语言、资源、任务与公开项目指引；资源与任务 URL 保持 base 相对。manifest schema 不包含部署 origin 字段。 指令与任务都是显式公开构建输入。不要包含本地绝对路径、密钥、私有端点、凭证或未公开运行信息。",
      "code": [
        {
          "language": "ts",
          "value": "ai: {\n  contract: {\n    enabled: true,\n    instructions: '.silen/ai-public.md',\n    tasksDir: '.silen/ai-tasks',\n  },\n}"
        }
      ],
      "links": [
        "/silen/.well-known/silen/manifest.json"
      ],
      "order": 2
    },
    {
      "id": "/zh/ai/agent-contract/#schema-版本-2",
      "route": "/zh/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "Schema 版本 2"
      ],
      "text": "当前 manifest 与 API 文档使用 schemaVersion: 2 。manifest 的 MCP 能力声明 stdio 、协议版本 2025-11-25 与 2026-07-28 、空扩展列表、本地运行、 默认只读和 --allow-write 门禁。API 文档为每个工具增加 outputSchema ；MCP 成功调用会同时返回文本与对应的、经过 schema 校验的 structuredContent 。 该契约不声明远程传输或可选 MCP 扩展；这些能力需要独立设计和授权。 包内还包含生成的文件系统 Skill： dist/agent/skills/silen-docs-readonly ；CLI API 会记录 silen ai skills 和 --experimental-skills-over-mcp 。默认 manifest 仍声明 extensions: [] ，因为可选 运行参数不等于站点能力。Skill 文本只是流程知识，不授予 Host 运行命令、访问 网络、写文件、提交、推送或部署的权限。",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/ai/agent-contract/#客户端行为",
      "route": "/zh/ai/agent-contract/",
      "title": "Agent Contract",
      "headingPath": [
        "客户端行为"
      ],
      "text": "Codex、Claude Code、Cursor 等客户端应使用同一份清单，不要维护各自的 API 副本。若客户端不支持声明的契约 schema，应退回到链接的公开 Markdown，并保持只读。读取部署内容时以站点清单为准；针对已安装包生成代码时以包契约为准。 下一步配置 本地工作区与 MCP 。",
      "code": [],
      "links": [
        "/silen/zh/ai/local-workspace-mcp/"
      ],
      "order": 4
    },
    {
      "id": "/zh/ai/",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [],
      "text": "Silen 把 AI 访问视为文档构建的一部分，而不是事后补上的功能。默认输出是 确定、可检查的，并且不会调用模型。核心 AI-ready 文档流程不需要模型、API key、 端点、向量服务或网络。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/ai/#agent-contract",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "Agent Contract"
      ],
      "text": "Silen 为 AI 提供一个带版本的发现入口，不需要为每一种客户端重复维护一份教程： 操作本地项目时，先读取已安装包中的 @aicode-nexus/silen/agent/manifest.json 。它会链接到准确的配置、CLI、 MCP、公开 TypeScript API，以及 agent/tasks/create-site.md 等任务手册。 读取部署站点时，先访问 /.well-known/silen/manifest.json 。当前官方站点的 地址是 /silen/.well-known/silen/manifest.json 。 在本地进行有边界的读取时，启动 pnpm silen mcp docs 。除非用户显式添加 --allow-write ，否则它始终只读。 Codex、Claude Code 与 Cursor 都应读取同一份 manifest，并使用同一个本地 MCP 命令。各客户端只保留轻量接入配置，API 真相始终由 Agent Contract 提供。 如果客户端不支持声明的契约版本，必须退回链接的公开 Markdown，并保持只读。 当前 manifest 与 API 使用 schemaVersion: 2 ，声明本地 stdio 、已验证的 2025-11-25 与 2026-07-28 协议版本、空扩展集合，以及每个 MCP 工具的 outputSchema 。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/ai/#只读-agent-skill",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "只读 Agent Skill"
      ],
      "text": "npm 包会从规范的中英文 read-site 与 audit-site 任务包确定性生成唯一的 silen-docs-readonly Agent Skill。包内路径是 dist/agent/skills/silen-docs-readonly ，其中只有 SKILL.md 和四个按需读取的 参考文件，不包含脚本、资产、写任务、模型调用、凭据或隐含权限。 该命令只创建 ./agent-skills/silen-docs-readonly ；如果目录已经存在就直接失败， 不会覆盖。文件系统形式是受支持的可移植能力，并且可离线使用。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen ai skills ./agent-skills"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/ai/#添加公开项目指令",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "添加公开项目指令"
      ],
      "text": "只发布对所有站点访问者都安全的内容： 这些文件会成为显式公开的 Agent 指令。不要写入私有路径、密钥、内部端点或凭据。",
      "code": [
        {
          "language": "ts",
          "value": "export default defineConfig({\n  ai: {\n    contract: {\n      instructions: '.silen/ai-public.md',\n      tasksDir: '.silen/ai-tasks',\n    },\n  },\n})"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/ai/#面向-ai-的公开产物",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "面向 AI 的公开产物"
      ],
      "text": "每次生产构建都可以输出： llms.txt ，用于精简页面地图 llms-full.txt ，用于完整可读内容 ai-index.json ，用于结构化发现 每个公开页面对应的干净 Markdown 路由 标记为 draft: true 或 ai: false 的页面会从这些产物中排除。",
      "code": [],
      "links": [],
      "order": 4
    },
    {
      "id": "/zh/ai/#复制给-ai",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "复制给 AI"
      ],
      "text": "默认主题允许读者复制干净的页面 Markdown，或复制带规范来源 URL 的 prompt-ready 版本。复制内容来自同一套构建产物，因此会和渲染页面保持一致。",
      "code": [],
      "links": [],
      "order": 5
    },
    {
      "id": "/zh/ai/#本地-mcp-工作区",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "本地 MCP 工作区"
      ],
      "text": "MCP 服务使用拆分后的 SDK v2，并且默认只读。只有显式使用 --allow-write 启动时，写入工具才会出现；所有写入仍被限制在 Markdown 工作区内。成功调用会 同时返回文本和经过 schema 校验的 structuredContent ，不启用远程传输。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen mcp docs"
        }
      ],
      "links": [],
      "order": 6
    },
    {
      "id": "/zh/ai/#无模型质量门禁",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "无模型质量门禁"
      ],
      "text": "直接把生产搜索索引作为确定性的检索契约： ai eval 只读取已提交的 .silen/ai-evals.json 与构建生成的 .silen/dist/search-index.json ，不会调用模型或网络。退出码 0 、 1 、 2 分别表示通过、检索失败、初始化或配置失败。 版本 1 保持完整 topK 匹配；版本 2 增加可选的 expected.maxRank ，并报告 生效值与 matchedRank 。严格的 \"schemaVersion\": 3 要求两个目标数组与显式 排名边界： acceptable 与 forbidden 都必须出现，每个数组可包含零到 20 个目标，但两者 不能同时为空。至少一个可接受目标必须在 maxRank 以内出现，所有禁止目标都不能 进入诊断 Top K。纯负例使用 acceptable: [] 与 maxRank: topK 。未知字段、 重叠目标、空目标集合和非法边界都会成为初始化错误。版本 3 保持案例编写顺序， 并输出 matchedRank 与 forbiddenMatches ；v1/v2 的 JSON 与人类可读输出保持 兼容。 本仓库使用 pnpm site:ai-check 一次完成构建、审计、评测和 source map 检查， 并把评测器的原始 JSON 保存到 artifacts/ai-eval/site-ai-eval.json ，供 CI、Pages 与发布流程比较。 可重建的 .silen/ai/index.json 只是可选工作区快照。缺失或过期只会成为 audit 提示，MCP 搜索仍使用内存索引。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs"
        },
        {
          "language": "json",
          "value": "{\n  \"schemaVersion\": 3,\n  \"topK\": 5,\n  \"cases\": [\n    {\n      \"id\": \"install-quick-start\",\n      \"query\": \"如何安装并启动站点？\",\n      \"expected\": {\n        \"acceptable\": [\n          { \"route\": \"/zh/guide/\", \"heading\": \"快速开始\" },\n          { \"route\": \"/zh/guide/cli-deployment/\" }\n        ],\n        \"forbidden\": [{ \"route\": \"/zh/draft-notes/\" }],\n        \"maxRank\": 1\n      }\n    }\n  ]\n}"
        }
      ],
      "links": [],
      "order": 7
    },
    {
      "id": "/zh/ai/#ask-ai",
      "route": "/zh/ai/",
      "title": "AI-ready 文档",
      "headingPath": [
        "Ask AI"
      ],
      "text": "Ask AI 是可选的端点集成。Silen 不会把 provider key 放进生成站点：你的服务端 负责鉴权，并把一套小型 NDJSON 协议流式返回给主题。未显式配置端点时，Ask AI 控件及其 bundle 都不会出现。 返回 快速开始指南 。",
      "code": [],
      "links": [
        "/silen/zh/guide/"
      ],
      "order": 8
    },
    {
      "id": "/zh/ai/local-workspace-mcp/",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [],
      "text": "本地 AI 工作区是确定性、无模型的能力层：它为工具提供有边界的 Markdown 根目录、可检查索引与显式写权限，不暴露任意 shell 执行。整个流程不需要模型、API key、端点、向量服务或网络。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/ai/local-workspace-mcp/#初始化索引与审计",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [
        "初始化、索引与审计"
      ],
      "text": "ai init 创建 wiki/ 与被忽略的 .silen/ai/ 缓存，不修改已有 MDX； ai index 重建可选的 .silen/ai/index.json 工作区快照； ai audit 检查链接、引用、生成产物与生产契约。快照缺失或过期只会成为提示，因为 MCP 搜索使用内存索引。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/ai/local-workspace-mcp/#构建审计与评测",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [
        "构建、审计与评测"
      ],
      "text": "ai eval 读取 .silen/ai-evals.json 与生产构建的 .silen/dist/search-index.json ；它不会启动 MCP，也不会调用模型或网络。版本 1 在 topK 内使用单一路由与可选标题；版本 2 增加可选的 expected.maxRank 。严格的 \"schemaVersion\": 3 要求同时提供 acceptable 与 forbidden 数组、两者至少包含一个目标，并显式设置 1 到 topK 之间的 maxRank 。纯负例使用 acceptable: [] 与 maxRank: topK 。 版本 3 在没有可接受目标时报告 matchedRank: null ，并把禁止命中列入 forbiddenMatches 。退出码 0 表示全部通过， 1 表示检索预期失败， 2 表示套件或输入无效；完整诊断 Top K 保持稳定的案例顺序。 Silen 仓库使用 pnpm site:ai-check 组合完整只读门禁，并把评测原始 JSON 保存到 artifacts/ai-eval/site-ai-eval.json 。可选的 .silen/ai/index.json 快照仍是非阻断能力，不会替代生产搜索索引。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen build docs\npnpm silen ai audit docs\npnpm silen ai eval docs"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/ai/local-workspace-mcp/#连接-mcp-客户端",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [
        "连接 MCP 客户端"
      ],
      "text": "从仓库根目录启动： 默认服务注册七个只读工具： guide 、 list 、 search 、 read 、 backlinks 、 citations 、 build 。 build 是有边界的预检，只读取 Markdown 输入与现有产物，不加载项目配置、不执行 MDX、不调用 Vite，也不写文件。",
      "code": [
        {
          "language": "json",
          "value": "{\n  \"mcpServers\": {\n    \"silen\": {\n      \"command\": \"pnpm\",\n      \"args\": [\"silen\", \"mcp\", \"docs\"]\n    }\n  }\n}"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/ai/local-workspace-mcp/#协议与结构化结果",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [
        "协议与结构化结果"
      ],
      "text": "该命令使用稳定的拆分版 TypeScript SDK v2。同一个 stdio 入口接受已验证的 legacy 2025-11-25 与 modern 2026-07-28 客户端；版本规则见 官方协议版本指南 。 服务默认只读。每次成功调用都同时返回文本与经过 schema 校验的 structuredContent ，每个工具都声明 outputSchema ；不启用远程传输。 字符串结果的 guide 在 modern 客户端中保持原生字符串，在 legacy 客户端中由 SDK 兼容包装为 { result: ... } ；对象结果工具在两个协议时代保持原有结构。",
      "code": [],
      "links": [
        "https://ts.sdk.modelcontextprotocol.io/v2/protocol-versions"
      ],
      "order": 4
    },
    {
      "id": "/zh/ai/local-workspace-mcp/#实验性-skills-over-mcp",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [
        "实验性 Skills over MCP"
      ],
      "text": "文件系统安装不依赖 MCP。明确支持 Resources 草案绑定的 Host 可以选择暴露同一份 包内字节： 该实验声明 io.modelcontextprotocol/skills ，提供 skill://index.json ，并把五个 文件映射到 skill://silen-docs-readonly/ 下。它只使用本地 stdio 并保持只读；该 实验默认关闭，不增加工具、脚本、订阅、网络传输或写权限； --allow-write 仍是 独立的显式工具注册开关。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen mcp docs --experimental-skills-over-mcp"
        }
      ],
      "links": [],
      "order": 5
    },
    {
      "id": "/zh/ai/local-workspace-mcp/#谨慎授权写入",
      "route": "/zh/ai/local-workspace-mcp/",
      "title": "本地工作区与 MCP",
      "headingPath": [
        "谨慎授权写入"
      ],
      "text": "显式参数会增加 write 、 link 、 append 。写入只接受工作区相对 .md / .mdx 路径，拒绝目录穿越和逃逸符号链接，使用原子替换，并限制为 2 MiB UTF-8；它不会增加 shell 工具。 只在边界明确的任务中授权可信本地客户端。修改后运行 audit 与站点构建，检查 Git diff，并在提交或部署前另行取得授权。 Ask AI 是独立能力，必须显式配置端点；没有端点时，Silen 不会输出控件及其 bundle。 客户端发现规则见 Agent Contract 。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen mcp docs --allow-write"
        }
      ],
      "links": [
        "/silen/zh/ai/agent-contract/"
      ],
      "order": 6
    },
    {
      "id": "/zh/guide/cli-deployment/",
      "route": "/zh/guide/cli-deployment/",
      "title": "CLI 与部署",
      "headingPath": [],
      "text": "Silen 提供一组精简 CLI。通过项目包管理器运行，命令实现与 Agent Contract 就会始终匹配当前安装版本。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/guide/cli-deployment/#主要命令",
      "route": "/zh/guide/cli-deployment/",
      "title": "CLI 与部署",
      "headingPath": [
        "主要命令"
      ],
      "text": "init <root> 写入起始配置与首页，不替换已有目标； dev [root] 启动基于 Vite 的开发服务； build [root] 校验并生成静态产物； preview [root] 提供包含路由与语言感知 404 的预览。服务命令支持 --host 和 --port ，构建命令不会自动部署。 AI 工作区使用独立命令： ai skills 必须指定父目录，只创建 silen-docs-readonly 且绝不覆盖；可选的 MCP Resource 暴露使用 pnpm silen mcp docs --experimental-skills-over-mcp ，仍是实验能力 并默认关闭。 MCP 默认只读，只有可信用户显式加入 --allow-write 才会注册写工具。无模型的 ai eval 只读取 .silen/ai-evals.json 与 .silen/dist/search-index.json ， CI 使用 --json ；它不需要模型、API key、端点、向量服务或网络。 套件 \"schemaVersion\": 1 保持完整 topK 匹配；版本 2 支持逐案例 expected.maxRank ，省略时默认等于 topK ，并在保留完整诊断结果的同时 报告 matchedRank 。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen init docs\npnpm silen dev docs --host 127.0.0.1 --port 5173\npnpm silen build docs\npnpm silen preview docs --port 4173"
        },
        {
          "language": "sh",
          "value": "pnpm silen ai init docs\npnpm silen ai index docs\npnpm silen ai audit docs\npnpm silen ai eval docs\npnpm silen ai skills ./agent-skills\npnpm silen mcp docs"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/guide/cli-deployment/#静态部署",
      "route": "/zh/guide/cli-deployment/",
      "title": "CLI 与部署",
      "headingPath": [
        "静态部署"
      ],
      "text": "把 docs/.silen/dist 的内容发布到任意静态托管，并让托管平台按生成结果提供 index.html 与资源。例如项目地址为 https://example.github.io/handbook/ ： 不要在 siteUrl 中重复 /handbook/ 。构建会组合 origin 与 base，用于 canonical、 hreflang 与 x-default 语言替代、站点地图和基础 Open Graph/Twitter 元数据。Markdown 与 Agent Contract URL 仍是 base 相对路径。",
      "code": [
        {
          "language": "ts",
          "value": "export default defineConfig({\n  siteUrl: 'https://example.github.io',\n  base: '/handbook/',\n})"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/guide/cli-deployment/#上线前检查",
      "route": "/zh/guide/cli-deployment/",
      "title": "CLI 与部署",
      "headingPath": [
        "上线前检查"
      ],
      "text": "仓库维护者只运行一个规范命令： 它依次且只执行一次 site:build -> ai audit -> ai eval -> check:no-maps ； pnpm site:check 只是兼容别名。Core CI、GitHub Pages 与 npm 发布都使用规范命令，audit 或评测失败会阻断部署和发布。 正式 .silen/ai-evals.json 使用 \"schemaVersion\": 3 、显式 maxRank ，以及必需的 acceptable 和 forbidden 目标数组。报告保留诊断 topK 、稳定的 matchedRank 与禁止命中证据。只要评测器产出了有效 JSON， 每条工作流都会用 always 条件上传 artifacts/ai-eval/site-ai-eval.json ，包括检索失败或后续 source map 检查失败的情况。 随后直接预览一个嵌套路由和一个不存在的路由，并检查 llms.txt 与 .well-known/silen/manifest.json 。构建成功只证明文件已生成；直接访问才能 证明托管平台按预期 base 提供了它们。 Ask AI 仍然只通过端点接入；未配置端点时，不会出现控件或对应 bundle。 命令语法与排错见 参考手册 。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm site:ai-check"
        }
      ],
      "links": [
        "/silen/zh/reference/"
      ],
      "order": 3
    },
    {
      "id": "/zh/guide/configuration/",
      "route": "/zh/guide/configuration/",
      "title": "配置",
      "headingPath": [],
      "text": "在内容根目录创建 .silen/config.ts ，并导出 defineConfig(...) 。该文件是可信的项目代码；不要放入密钥，因为配置可能影响公开 HTML 与构建产物。",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig } from '@aicode-nexus/silen'\n\nexport default defineConfig({\n  title: '工程手册',\n  description: '产品团队的运行知识。',\n  lang: 'zh-CN',\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  outDir: '.silen/dist',\n  onBrokenLinks: 'error',\n})"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/guide/configuration/#url-与元数据",
      "route": "/zh/guide/configuration/",
      "title": "配置",
      "headingPath": [
        "URL 与元数据"
      ],
      "text": "base 是站点挂载位置的规范绝对路径；域名根路径使用 / ，子路径可用 /handbook/ 。 siteUrl 只能写 HTTP(S) 源，部署路径写在 base 中。两者共同生成 canonical、 hreflang 与 x-default 语言替代、站点地图和基础 Open Graph/Twitter 元数据。Markdown 与 Agent Contract URL 仍是 base 相对路径。 lang 使用 BCP 47 语言标签。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/guide/configuration/#导航与多语言",
      "route": "/zh/guide/configuration/",
      "title": "配置",
      "headingPath": [
        "导航与多语言"
      ],
      "text": "themeConfig.nav 和 themeConfig.sidebar 使用 { text, link } 。主题里的根相对链接会自动加上 base 。locale 可设置 root ，并覆盖导航、侧栏、首页与界面消息： 保持语言路由镜像，语言切换器才能保留当前页面，而不是把读者送回首页。",
      "code": [
        {
          "language": "ts",
          "value": "themeConfig: {\n  locales: [\n    { lang: 'en-US', label: 'English', root: '/' },\n    { lang: 'zh-CN', label: '中文', root: '/zh/' },\n  ],\n  search: true,\n}"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/guide/configuration/#集成与-ai",
      "route": "/zh/guide/configuration/",
      "title": "配置",
      "headingPath": [
        "集成与 AI"
      ],
      "text": "analytics 支持 Google、百度与自定义脚本； plugins 是有序的可信插件工厂数组。 ai 可控制 llms.txt 、 llms-full.txt 、Markdown 路由与 ai-index.json ，默认全部开启。Agent Contract 默认开启，也可显式加入公开指令和任务。 完整字段见 参考手册 ，集成示例见 集成 。",
      "code": [
        {
          "language": "ts",
          "value": "ai: {\n  markdownRoutes: true,\n  index: true,\n  contract: { enabled: true, instructions: '.silen/ai-public.md' },\n}"
        }
      ],
      "links": [
        "/silen/zh/reference/",
        "/silen/zh/integrations/"
      ],
      "order": 3
    },
    {
      "id": "/zh/guide/",
      "route": "/zh/guide/",
      "title": "快速开始",
      "headingPath": [],
      "text": "Silen 将 Markdown 与 MDX 目录构建为服务端渲染的静态站点、本地搜索与确定性的 AI 可读产物。请使用 Node.js ^20.19.0 || >=22.12.0 。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/guide/#安装并激活",
      "route": "/zh/guide/",
      "title": "快速开始",
      "headingPath": [
        "安装并激活"
      ],
      "text": "在项目根目录安装 Silen，然后激活 docs 目录： Silen 会自动安装所需的 react 、 react-dom 运行时以及 MDX 使用的 react/jsx-runtime ，用户无需单独安装。 init 会创建 docs/.silen/config.ts 和 docs/index.mdx 。它既适用于新目录，也适用于已有内容：只要目标文件已存在，Silen 就会报告冲突，不会覆盖你的内容。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm add -D @aicode-nexus/silen\npnpm silen init docs"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/guide/#本地开发",
      "route": "/zh/guide/",
      "title": "快速开始",
      "headingPath": [
        "本地开发"
      ],
      "text": "编辑 docs/index.mdx ，或增加 .md 、 .mdx 文件。目录树会直接形成路由，客户端导航无需整页刷新。本地搜索完全随站点运行，不需要托管搜索账号。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen dev docs"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/guide/#构建并检查",
      "route": "/zh/guide/",
      "title": "快速开始",
      "headingPath": [
        "构建并检查"
      ],
      "text": "默认输出到 docs/.silen/dist 。构建结果包括完整 HTML，以及 llms.txt 、 llms-full.txt 、 ai-index.json 和干净 Markdown 路由。草稿页与设置了 ai: false 的页面不会进入 AI 产物。",
      "code": [
        {
          "language": "sh",
          "value": "pnpm silen build docs\npnpm silen preview docs"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/guide/#明确部署边界",
      "route": "/zh/guide/",
      "title": "快速开始",
      "headingPath": [
        "明确部署边界"
      ],
      "text": "站点部署在子路径时设置 base ；需要规范链接与站点地图时，将 siteUrl 设置为域名源： 下一步阅读 项目结构 、 配置 ，或直接检查 真实 AI 产物 。",
      "code": [
        {
          "language": "ts",
          "value": "export default defineConfig({\n  base: '/handbook/',\n  siteUrl: 'https://docs.example.com',\n  onBrokenLinks: 'error',\n})"
        }
      ],
      "links": [
        "/silen/zh/guide/project-structure/",
        "/silen/zh/guide/configuration/",
        "/silen/zh/ai/"
      ],
      "order": 4
    },
    {
      "id": "/zh/guide/markdown-mdx/",
      "route": "/zh/guide/markdown-mdx/",
      "title": "Markdown 与 MDX",
      "headingPath": [],
      "text": "持久说明优先使用 Markdown；页面确实需要类型化 React 组件时再使用 MDX。两者都会生成相同的路由、SSR HTML、搜索记录与可选 AI Markdown。GFM 表格、任务列表、删除线、自动链接与脚注会在这些产物中保持一致语义。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/guide/markdown-mdx/#frontmatter",
      "route": "/zh/guide/markdown-mdx/",
      "title": "Markdown 与 MDX",
      "headingPath": [
        "Frontmatter"
      ],
      "text": "Frontmatter 用于页面元数据与布局选择： doc 是默认布局； home 会先渲染配置的 hero，再渲染页面 MDX； page 保留应用外壳，但不显示文档翻页。 draft: true 只会让页面退出 AI 可读产物与索引。它不会阻止路由扫描、构建或发布； ai: false 对其他公开页面采用相同的 AI 输出边界。不要把私密内容放入内容树。机密材料应保存在站点根目录及其构建输入之外。",
      "code": [
        {
          "language": "md",
          "value": "---\ntitle: 服务运行手册\ndescription: 诊断并恢复结算服务。\nlayout: doc\nlang: zh-CN\nai: true\n---"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/guide/markdown-mdx/#链接与标题",
      "route": "/zh/guide/markdown-mdx/",
      "title": "Markdown 与 MDX",
      "headingPath": [
        "链接与标题"
      ],
      "text": "使用稳定站点路由和有意义的链接文字。非根 base 下，主题配置链接会自动感知 base；正文里的根相对链接应直接指向挂载路径。构建期间 Silen 会校验内部页面目标，并按 onBrokenLinks 选择报错、警告或忽略。 标题会形成页面大纲。每页保留一个 # 标题，后续层级不要跳级，以保证键盘与屏幕阅读器用户都能理解结构。",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/guide/markdown-mdx/#代码与组件",
      "route": "/zh/guide/markdown-mdx/",
      "title": "Markdown 与 MDX",
      "headingPath": [
        "代码与组件"
      ],
      "text": "围栏代码块带语法高亮和可键盘操作的复制按钮。Silen 会按需加载 Shiki 支持的语法，包括 mdx 、 python ，并让 ndjson 使用 JSON Lines 语法；未知语言会安全降级为纯文本。MDX 可以导入组件： MDX 会在构建中执行，也能导入项目代码，因此必须把它当成可信源文件，而不是不受信任投稿的沙箱。浏览器 API 应放在 effect 或客户端 setup 内，确保服务端渲染可重复。 需要全站组件时，请扩展 默认主题 。",
      "code": [
        {
          "language": "mdx",
          "value": "import Status from './components/status.tsx'\n\n## 当前状态\n\n<Status service=\"checkout\" />"
        }
      ],
      "links": [
        "/silen/zh/theme/extensions-accessibility/"
      ],
      "order": 3
    },
    {
      "id": "/zh/guide/plugins",
      "route": "/zh/guide/plugins",
      "title": "插件",
      "headingPath": [],
      "text": "Silen 插件无需导入内部文件，即可扩展文档生命周期。插件是直接配置在 .silen/config.ts 中的本地或 npm 工厂函数：",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst readingTime = definePlugin(\n  (_context, options: { wordsPerMinute: number }) => ({\n    name: 'reading-time',\n    transformPageData(page, context) {\n      const words = context.source.trim().split(/\\s+/).length\n      return {\n        data: {\n          ...page.data,\n          minutes: Math.max(1, Math.ceil(words / options.wordsPerMinute)),\n        },\n      }\n    },\n  }),\n)\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/guide/plugins#生命周期",
      "route": "/zh/guide/plugins",
      "title": "插件",
      "headingPath": [
        "生命周期"
      ],
      "text": "Silen 按配置顺序执行插件。首个版本支持 config 、 configResolved 、 extendMdx 、 vite 、 clientModules 、 transformPageData 、 transformHead 和 buildEnd 。 extendMdx 接入 Remark 与 Rehype 插件。 vite 接入标准 Vite 能力； virtual:silen/* 模块仍由核心保护。 transformPageData 生成可 JSON 序列化、可供 SSR、hydration、搜索和 AI 产物共同使用的页面数据。 transformHead 添加类型化的 meta 、 link 、 script 、 style 或 noscript 节点。 clientModules 提供 SSR-safe 的 wrapRoot 和可选的浏览器端 setup 。 buildEnd 在产物目录安装完成后生成 sitemap 等附加文件。 每个插件都必须提供 name ；同一插件配置多个实例时应提供不同的 id 。 错误信息会包含插件标识和钩子，例如 Silen plugin analytics:docs failed in transformHead 。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/guide/plugins#ssr-与兼容性",
      "route": "/zh/guide/plugins",
      "title": "插件",
      "headingPath": [
        "SSR 与兼容性"
      ],
      "text": "客户端模块会同时进入 SSR 与 hydration。不要在模块顶层或 wrapRoot 中 访问 window 、 document ；浏览器 API 应放在 setup 中。插件包应把 @aicode-nexus/silen 声明为 peer dependency，并且只导入文档化的公开 API。 仓库的 examples/plugins 提供了可直接整理成 npm 包的 sitemap、阅读时间和 analytics-client 示例。",
      "code": [],
      "links": [
        "https://github.com/AICode-Nexus/silen/tree/main/examples/plugins"
      ],
      "order": 2
    },
    {
      "id": "/zh/guide/project-structure/",
      "route": "/zh/guide/project-structure/",
      "title": "项目结构",
      "headingPath": [],
      "text": "一个 Silen 站点就是一个内容根目录。把内容与站点配置放在同一边界内，本地开发、生产构建和 AI 工具就会解析同一套文件。",
      "code": [
        {
          "language": "text",
          "value": "docs/\n├── .silen/\n│   ├── config.ts\n│   ├── theme.tsx          # 可选主题扩展\n│   ├── ai-public.md       # 可选公开 Agent 指令\n│   └── dist/              # 生成目录，不要手工编辑\n├── public/\n│   └── logo.svg\n├── assets/\n│   └── architecture.png\n├── guide/\n│   └── index.mdx\n└── index.mdx"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/guide/project-structure/#内容如何形成路由",
      "route": "/zh/guide/project-structure/",
      "title": "项目结构",
      "headingPath": [
        "内容如何形成路由"
      ],
      "text": "Silen 扫描 .md 与 .mdx 。 index.mdx 的编译器路由是 / ； guide.mdx 与 guide/index.mdx 的编译器路由是 /guide 。目录形式会生成 guide/index.html ，通常以 /guide/ 访问。不要同时创建两个指向同一路由的源文件；构建会明确拒绝重复路由，而不是静默选一个。 会继续增长的栏目适合使用目录，这样相邻图片、示例与子页面更容易维护，公开 URL 也能保持稳定。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/guide/project-structure/#配置与主题",
      "route": "/zh/guide/project-structure/",
      "title": "项目结构",
      "headingPath": [
        "配置与主题"
      ],
      "text": ".silen/config.ts 是可信、可执行的项目配置，定义标题、base、多语言、导航、集成与 AI 产物。 .silen/theme.tsx 是可选项；仅替换组件、布局或根包装器时，应扩展默认主题。",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/guide/project-structure/#静态资源与导入资源",
      "route": "/zh/guide/project-structure/",
      "title": "项目结构",
      "headingPath": [
        "静态资源与导入资源"
      ],
      "text": "必须保留公开文件名的资源放到 public/ ，例如在配置中使用 /logo.svg 。Silen 会按配置的 base 解析主题链接与图片。与内容强关联、需要进入 Vite 资源管线的图片，可从 MDX 中导入。",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/guide/project-structure/#生成状态",
      "route": "/zh/guide/project-structure/",
      "title": "项目结构",
      "headingPath": [
        "生成状态"
      ],
      "text": ".silen/dist 是默认生产输出， .silen/.temp 是临时构建状态，都应视为可重新生成。本地 AI 工作区使用 wiki/ 保存内容，并用 .silen/ai/ 保存索引。启用写入前请阅读 工作区边界 。 下一步配置 站点选项 。",
      "code": [],
      "links": [
        "/silen/zh/ai/local-workspace-mcp/",
        "/silen/zh/guide/configuration/"
      ],
      "order": 4
    },
    {
      "id": "/zh/",
      "route": "/zh/",
      "title": "Silen",
      "headingPath": [],
      "text": "激活一个文档目录 从文件夹到知识接口 直接检查证据 当前构建的真实产物 llms.txt 简明语料地图 llms-full.txt 完整可读语料 ai-index.json 结构化页面发现 Agent 清单 版本化能力契约 指南 Markdown 干净的路由级内容 一个内容源，三项证明 同时服务读者、智能体与维护者 人类阅读 AI 消费 可扩展性 开源，也保持克制 一起完善文档基础设施 微信公众号：AI Dev Hub",
      "code": [
        {
          "language": "sh",
          "value": "pnpm add -D @aicode-nexus/silen\npnpm silen init docs\npnpm silen dev docs"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/integrations/",
      "route": "/zh/integrations/",
      "title": "集成",
      "headingPath": [],
      "text": "Silen 让集成保持显式：插件运行可信构建或客户端代码，分析在站点层配置，Ask AI 只访问你自己运营的端点。三者都不需要导入 Silen 内部文件。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/integrations/#插件",
      "route": "/zh/integrations/",
      "title": "集成",
      "headingPath": [
        "插件"
      ],
      "text": "插件是 .silen/config.ts 中有序排列的工厂，用于 MDX 处理器、Vite 集成、页面元数据、head、客户端 setup 或构建后产物： 每个插件必须有 name ，配置多个实例时增加 id 。钩子按配置顺序运行，失败信息会包含插件身份与钩子名称。完整说明见 插件生命周期 。",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig } from '@aicode-nexus/silen'\nimport readingTime from './plugins/reading-time'\n\nexport default defineConfig({\n  plugins: [[readingTime, { wordsPerMinute: 250 }]],\n})"
        }
      ],
      "links": [
        "/silen/zh/guide/plugins"
      ],
      "order": 1
    },
    {
      "id": "/zh/integrations/#站点分析",
      "route": "/zh/integrations/",
      "title": "集成",
      "headingPath": [
        "站点分析"
      ],
      "text": "分析与主题无关，只在生产构建中输出。可配置 Google、百度或有序的自定义 provider： Silen 上报初始页面和客户端路由变化，忽略仅 hash 变化。Google 用户应关闭 Enhanced Measurement 中的自动 history-change pageview，避免重复。自定义 provider 可加载外部或内联脚本并监听 silen:pageview 。脚本是公开可信代码，不要放密钥。",
      "code": [
        {
          "language": "ts",
          "value": "analytics: [\n  { provider: 'google', id: 'G-XXXXXXXXXX' },\n  { provider: 'baidu', id: 'site-id' },\n]"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/integrations/#ask-ai",
      "route": "/zh/integrations/",
      "title": "集成",
      "headingPath": [
        "Ask AI"
      ],
      "text": "Ask AI 是可选主题端点，不捆绑模型 provider：",
      "code": [
        {
          "language": "ts",
          "value": "themeConfig: {\n  ai: {\n    endpoint: '/api/ask'\n  }\n}"
        }
      ],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/integrations/#ask-ai-请求",
      "route": "/zh/integrations/",
      "title": "集成",
      "headingPath": [
        "Ask AI 请求"
      ],
      "text": "Silen 通过 HTTP POST 发送 Content-Type: application/json 请求。请求契约严格如下： selectedText 是可选字段；读者未选择正文时应省略。 messages 可以包含之前的 user 与 assistant 对话。具体请求示例：",
      "code": [
        {
          "language": "ts",
          "value": "interface AskAiRequest {\n  route: string\n  selectedText?: string\n  messages: Array<{\n    role: 'user' | 'assistant'\n    content: string\n  }>\n}"
        },
        {
          "language": "json",
          "value": "{\n  \"route\": \"/guide/\",\n  \"selectedText\": \"pnpm silen init docs\",\n  \"messages\": [\n    { \"role\": \"user\", \"content\": \"如何开始？\" },\n    { \"role\": \"assistant\", \"content\": \"先安装依赖。\" }\n  ]\n}"
        }
      ],
      "links": [],
      "order": 4
    },
    {
      "id": "/zh/integrations/#ask-ai-响应",
      "route": "/zh/integrations/",
      "title": "集成",
      "headingPath": [
        "Ask AI 响应"
      ],
      "text": "成功的流式响应必须使用 Content-Type: application/x-ndjson 或 Content-Type: application/ndjson 。每行写入一个 JSON 对象。事件形状分别是文本 { type: 'text', value: string } 、引用 { type: 'citation', title: string, url: string } 与错误 { type: 'error', message: string } ： Silen 会向请求提供 AbortSignal ，并在新请求取代旧请求或对话框关闭时触发 abort。把该信号与 HTTP 连接断开视为取消：停止上游 provider 工作并释放资源。 端点负责服务端鉴权。provider key 与原始 provider 错误必须留在服务端，只返回安全的公开错误。未配置端点时，不会生成 Ask AI 控件，也不会生成 Ask AI 客户端 bundle。 无需模型 provider 的确定性访问见 生成产物 与 本地 MCP 。",
      "code": [
        {
          "language": "ndjson",
          "value": "{\"type\":\"text\",\"value\":\"Install with pnpm.\"}\n{\"type\":\"citation\",\"title\":\"Quick start\",\"url\":\"/guide/\"}\n{\"type\":\"error\",\"message\":\"Unable to answer.\"}"
        }
      ],
      "links": [
        "/silen/zh/ai/",
        "/silen/zh/ai/local-workspace-mcp/"
      ],
      "order": 5
    },
    {
      "id": "/zh/plugins/",
      "route": "/zh/plugins/",
      "title": "插件",
      "headingPath": [],
      "text": "此路由为已有书签继续保留。Silen 插件 API 是有序、公开的构建与客户端扩展边界。插件工厂在 .silen/config.ts 中配置，接收当前 command 与 root，并返回有名称的插件。 公开钩子覆盖配置、解析后配置、Remark/Rehype、Vite、客户端模块、页面数据、head 与构建结束。钩子按配置顺序运行。客户端模块必须兼容 SSR：浏览器 API 应放入 setup ，而不是模块顶层或 wrapRoot 。插件包应把 @aicode-nexus/silen 声明为 peer dependency，并只导入文档化导出。 插件生命周期、身份、失败信息与打包规则请进入正式 插件指南 ；分析与 Ask AI 见 集成 。",
      "code": [
        {
          "language": "ts",
          "value": "import { defineConfig, definePlugin } from '@aicode-nexus/silen'\n\nconst metadata = definePlugin(() => ({\n  name: 'product-metadata',\n  transformPageData(page) {\n    return { data: { ...page.data, product: 'checkout' } }\n  },\n}))\n\nexport default defineConfig({ plugins: [metadata] })"
        }
      ],
      "links": [
        "/silen/zh/guide/plugins",
        "/silen/zh/integrations/"
      ],
      "order": 0
    },
    {
      "id": "/zh/reference/",
      "route": "/zh/reference/",
      "title": "参考",
      "headingPath": [],
      "text": "本页是紧凑的运行参考；解释与完整示例请阅读链接的指南。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/reference/#配置",
      "route": "/zh/reference/",
      "title": "参考",
      "headingPath": [
        "配置"
      ],
      "text": "字段 默认值 用途 title Silen 站点标题 description 空 页面元数据 lang en-US 默认 BCP 47 语言 base / 规范化部署路径 siteUrl 未设置 canonical HTTP(S) origin outDir .silen/dist 相对内容根的输出目录 onBrokenLinks error error 、 warn 、 ignore themeConfig {} 导航、语言、首页、搜索、Ask AI analytics [] 有序生产分析 provider plugins [] 有序可信插件 ai.* 开启 AI 文件、Markdown、索引、契约 base 必须以 / 开头，不含 query/hash 或穿越路径，并规范为结尾斜杠。 siteUrl 只能是 origin，不含凭证、路径、query 或 fragment。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/reference/#cli",
      "route": "/zh/reference/",
      "title": "参考",
      "headingPath": [
        "CLI"
      ],
      "text": "命令 作用 silen init <root> 安全创建起始配置与首页 silen dev [root] 启动开发，支持 --host 、 --port silen build [root] 校验并生成静态产物 silen preview [root] 预览产物，支持 --host 、 --port silen ai <init|index|audit|eval> [path] 管理并评测本地 AI 工作区 silen ai skills <destination> 无覆盖地写出包内 silen-docs-readonly Skill silen mcp [root] 启动只读 MCP；可选 --allow-write 与实验性 --experimental-skills-over-mcp 包内可移植 Skill 位于 dist/agent/skills/silen-docs-readonly 。只有显式使用 --experimental-skills-over-mcp 时才会提供 skill://silen-docs-readonly/SKILL.md ；默认 Agent Contract 仍是 extensions: [] 。",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/reference/#mcp-与-agent-contract",
      "route": "/zh/reference/",
      "title": "参考",
      "headingPath": [
        "MCP 与 Agent Contract"
      ],
      "text": "本地 MCP 命令使用 SDK v2 与 stdio ，验证 2025-11-25 和 2026-07-28 。 默认提供七个只读工具，加入 --allow-write 后增加三个写工具；成功调用同时返回 文本与经过校验的 structuredContent ，不启用远程传输。 Agent Contract manifest 与 API 使用 schemaVersion: 2 。manifest 声明协议版本 和空扩展集合，API 为每个工具声明 outputSchema 。",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/reference/#ai-评测套件",
      "route": "/zh/reference/",
      "title": "参考",
      "headingPath": [
        "AI 评测套件"
      ],
      "text": ".silen/ai-evals.json 是严格 JSON。版本 1 在 topK 内匹配单一路由与可选 标题；版本 2 增加可选的 expected.maxRank 。版本 3 使用以下严格结构： 字段 要求 schemaVersion 精确整数 3 topK 整数 1..20 cases 1 到 500 个有序案例 expected.acceptable 必需数组，包含 0 到 20 个不重复目标 expected.forbidden 必需数组，包含 0 到 20 个不重复目标 expected.maxRank 必需整数 1..topK ；纯负例必须精确等于 topK 目标 严格 { route, heading? } ；route 以 / 开头 两个目标数组至少有一个非空。规范化后的重复、数组内部重叠、 acceptable 与 forbidden 之间的重叠，以及未知字段都无效。版本 3 报告保留有序 cases 、 matchedRank 、 forbiddenMatches 与完整诊断 Top K；v1/v2 行为保持兼容。 评测仍然只读且不依赖模型。 仓库维护者运行 pnpm site:ai-check ；其精确稳定报告位于 artifacts/ai-eval/site-ai-eval.json 。",
      "code": [],
      "links": [],
      "order": 4
    },
    {
      "id": "/zh/reference/#排错",
      "route": "/zh/reference/",
      "title": "参考",
      "headingPath": [
        "排错"
      ],
      "text": "本地链接正常，部署后失败。 检查托管路径是否匹配 base 、正文根相对链接是否包含挂载路径，以及托管是否按原样提供嵌套 index.html 。 canonical 路径重复。 siteUrl 只写 origin，路径只写在 base 。 语言切换进入 404。 在每个语言 root 下创建完全镜像的路由，并加入翻译后的导航。 构建报告重复路由。 删除 topic.mdx 或 topic/index.mdx 之一；二者指向同一路由。 pnpm 提示忽略 esbuild 构建脚本，且 Silen 随后构建失败。 执行 pnpm approve-builds esbuild ，只批准该依赖，然后重新安装并重试。如果构建已经成功，则无需批准。 MCP 没有写工具。 这是安全默认值。只有用户明确授权有边界的写任务后，才加入 --allow-write 。 深入阅读 配置 与 CLI/部署 。",
      "code": [],
      "links": [
        "/silen/zh/guide/configuration/",
        "/silen/zh/guide/cli-deployment/"
      ],
      "order": 5
    },
    {
      "id": "/zh/theme/extensions-accessibility/",
      "route": "/zh/theme/extensions-accessibility/",
      "title": "主题扩展与无障碍",
      "headingPath": [],
      "text": "令牌与配置不够时再扩展默认主题。主题可以替换布局或 MDX 组件、提供自定义 404、包装 React 根节点，同时继承其余能力。 defineTheme 按 key 合并继承的布局和组件；未替换时继续继承 NotFound 。基础主题和扩展都定义 wrapRoot 时，扩展包装器组合在外层。递归扩展会被拒绝。",
      "code": [
        {
          "language": "tsx",
          "value": "// docs/.silen/theme.tsx\nimport type { ReactNode } from 'react'\nimport DefaultTheme, { defineTheme } from '@aicode-nexus/silen/theme'\nimport './custom.css'\n\nfunction Note({ children }: { readonly children?: ReactNode }) {\n  return <aside className=\"product-note\">{children}</aside>\n}\n\nexport default defineTheme({\n  extends: DefaultTheme,\n  components: { Note },\n  wrapRoot({ children }) {\n    return <div data-product-docs=\"\">{children}</div>\n  },\n})"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/theme/extensions-accessibility/#ssr-安全",
      "route": "/zh/theme/extensions-accessibility/",
      "title": "主题扩展与无障碍",
      "headingPath": [
        "SSR 安全"
      ],
      "text": "主题模块与根包装器会同时参与服务端渲染和 hydration。不要在模块顶层或 render 中直接读取 window 、 document 、 localStorage 。浏览器行为放入 effect 或插件客户端 setup ，注册监听器时返回清理函数。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/theme/extensions-accessibility/#无障碍契约",
      "route": "/zh/theme/extensions-accessibility/",
      "title": "主题扩展与无障碍",
      "headingPath": [
        "无障碍契约"
      ],
      "text": "默认外壳包含跳转正文链接和清晰焦点样式。移动导航是带标签的模态框：打开后焦点进入导航，Escape 关闭，焦点返回触发按钮。搜索支持快捷键、方向键、Enter、Escape 与焦点恢复；代码复制是带实时状态文本的按钮。 外观控件是明确的深色/系统/浅色单选组。head 内联脚本在 hydration 前应用已保存偏好，避免颜色闪烁；系统模式会跟随操作系统变化。非必要过渡遵循 reduced motion。 替换交互组件时，保留可访问名称、键盘路径、焦点行为与 SSR 降级。上线前用纯键盘、200% 缩放和 reduced motion 检查。",
      "code": [],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/theme/",
      "route": "/zh/theme/",
      "title": "主题、布局与导航",
      "headingPath": [],
      "text": "默认主题是一套响应式文档外壳，而不是封闭模板。它提供导航、侧栏、页面大纲、本地搜索、外观控制、代码复制、翻页、首页 hero 与完整 404。优先使用配置；只有产品要求无法通过配置表达时才扩展 React。",
      "code": [],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/theme/#布局",
      "route": "/zh/theme/",
      "title": "主题、布局与导航",
      "headingPath": [
        "布局"
      ],
      "text": "在 frontmatter 中选择布局： doc 是默认布局，提供阅读排版、标题大纲，以及从侧栏推导的上一篇/下一篇。 home 在页面 MDX 前渲染当前语言的 hero 与可选功能区，并使用全宽外壳。 page 保留导航和中性文章容器，但不显示文档翻页。 首页 hero 可分别配置亮色与暗色图片，并共用一个无障碍说明：",
      "code": [
        {
          "language": "md",
          "value": "---\nlayout: doc\n---"
        },
        {
          "language": "ts",
          "value": "themeConfig: {\n  home: {\n    hero: {\n      image: {\n        src: '/workflow-light.jpg',\n        darkSrc: '/workflow-dark.jpg',\n        alt: '文档工作流',\n      },\n    },\n  },\n}"
        }
      ],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/theme/#导航与侧栏",
      "route": "/zh/theme/",
      "title": "主题、布局与导航",
      "headingPath": [
        "导航与侧栏"
      ],
      "text": "内部主题链接会按 base 解析。HTTP(S) 导航链接会在当前上下文中按浏览器普通导航处理。nav 条目只传递 href ，不会自动增加新上下文或关系属性。确实需要新上下文时，MDX 正文链接可显式设置 target=\"_blank\" 与 rel=\"noopener noreferrer\" 。960px 以下，固定侧栏变成带标签、分组可折叠的模态 Sheet；桌面宽度下，每个分组都以语义化区段持续显示在正文旁，当前页面使用主题主色突出显示。",
      "code": [
        {
          "language": "ts",
          "value": "themeConfig: {\n  logo: { src: '/logo.svg', alt: '产品文档' },\n  nav: [\n    { text: '指南', link: '/guide/' },\n    { text: 'GitHub', link: 'https://github.com/example/project' },\n  ],\n  sidebar: [\n    {\n      text: '开始使用',\n      items: [{ text: '快速开始', link: '/guide/' }],\n    },\n  ],\n}"
        }
      ],
      "links": [],
      "order": 2
    },
    {
      "id": "/zh/theme/#搜索",
      "route": "/zh/theme/",
      "title": "主题、布局与导航",
      "headingPath": [
        "搜索"
      ],
      "text": "除非 themeConfig.search 为 false ，否则本地搜索默认开启。搜索按需加载，可通过按钮或 Control+K / Command+K 打开，支持键盘选择，并在关闭后恢复焦点。search v2 记录页面语言，让当前语言结果得到正确排序与分组。",
      "code": [],
      "links": [],
      "order": 3
    },
    {
      "id": "/zh/theme/#多语言",
      "route": "/zh/theme/",
      "title": "主题、布局与导航",
      "headingPath": [
        "多语言"
      ],
      "text": "locale 条目定义 BCP 47 lang 、显示标签与路由 root ，并可覆盖导航、侧栏、首页与界面消息。路由镜像后，语言切换会保留当前页面。匹配长度最长的已配置 locale root 决定文档与搜索语言。frontmatter lang 不会覆盖解析后的路由语言；需要另一种语言的内容应放在对应 locale root 下。 视觉定制使用 主题令牌 ，React 行为使用 主题扩展 。",
      "code": [],
      "links": [
        "/silen/zh/theme/tokens/",
        "/silen/zh/theme/extensions-accessibility/"
      ],
      "order": 4
    },
    {
      "id": "/zh/theme/tokens/",
      "route": "/zh/theme/tokens/",
      "title": "主题令牌",
      "headingPath": [],
      "text": "覆盖语义 CSS 变量，不要依赖内部 utility class。令牌是默认主题行为与项目视觉身份之间稳定的边界。 从 .silen/theme.tsx 导入样式，让 Vite 同时把它加入 SSR 与客户端构建。",
      "code": [
        {
          "language": "css",
          "value": "/* docs/.silen/custom.css */\n:root {\n  --silen-primary: oklch(0.55 0.17 245);\n  --silen-primary-foreground: oklch(0.99 0 0);\n  --silen-radius: 0.5rem;\n  --silen-content-width: 48rem;\n}\n\n.dark {\n  --silen-primary: oklch(0.76 0.12 245);\n}"
        }
      ],
      "links": [],
      "order": 0
    },
    {
      "id": "/zh/theme/tokens/#颜色令牌",
      "route": "/zh/theme/tokens/",
      "title": "主题令牌",
      "headingPath": [
        "颜色令牌"
      ],
      "text": "核心语义集合包括 --silen-background 、 --silen-foreground 、 --silen-card 、 --silen-primary 、 --silen-primary-foreground 、 --silen-muted 、 --silen-muted-foreground 、 --silen-border 、 --silen-input 、 --silen-ring 与 --silen-destructive 。secondary、accent、popover 令牌为交互组件提供同样的语义层。 浅色值写在 :root ，深色覆盖写在 .dark 。保持前景/背景以及 primary/primary-foreground 之间的可读对比；外观控件允许用户明确选择深色、跟随系统或浅色。",
      "code": [],
      "links": [],
      "order": 1
    },
    {
      "id": "/zh/theme/tokens/#形状与布局",
      "route": "/zh/theme/tokens/",
      "title": "主题令牌",
      "headingPath": [
        "形状与布局"
      ],
      "text": "--silen-radius 控制统一圆角。 --silen-nav-height 定义顶部导航高度。 --silen-sidebar-width 控制桌面侧栏。 --silen-content-width 限制正文阅读宽度。 --silen-layout-width 限制首页与 page 布局宽度。 每次只调整一层，并检查长标题、代码块、两种配色与移动导航。更宽不一定更好，正文过宽会降低扫读效率。 令牌适合视觉变化；新增 MDX 组件、包装器、布局或 404 时再使用 主题扩展 。",
      "code": [],
      "links": [
        "/silen/zh/theme/extensions-accessibility/"
      ],
      "order": 2
    }
  ]
}