Skip to content

AI-ready documentation

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.

Agent Contract

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.

Read-only Agent Skill

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.

sh
pnpm silen ai skills ./agent-skills

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.

Add public project instructions

Only publish instructions that are safe for every site visitor:

ts
export default defineConfig({
  ai: {
    contract: {
      instructions: '.silen/ai-public.md',
      tasksDir: '.silen/ai-tasks',
    },
  },
})

These files become explicit public Agent instructions. Never place private paths, secrets, internal endpoints, or credentials in them.

Public AI artifacts

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.

Copy for AI

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.

Local MCP workspace

sh
pnpm silen ai init docs
pnpm silen ai index docs
pnpm silen ai audit docs
pnpm silen ai eval docs
pnpm silen mcp docs

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.

Model-free quality gate

Use the production search index itself as a deterministic retrieval contract:

sh
pnpm silen build docs
pnpm silen ai audit docs
pnpm silen ai eval docs

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:

json
{
  "schemaVersion": 3,
  "topK": 5,
  "cases": [
    {
      "id": "install-quick-start",
      "query": "How do I install and start a site?",
      "expected": {
        "acceptable": [
          { "route": "/guide/", "heading": "Quick start" },
          { "route": "/guide/cli-deployment/" }
        ],
        "forbidden": [{ "route": "/draft-notes/" }],
        "maxRank": 1
      }
    }
  ]
}

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.

Ask AI

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.