Reference
This page is the compact operational reference. Use the linked guides for explanations and examples.
Configuration
| 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.
CLI
| 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: [].
MCP and Agent Contract
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.
AI evaluation suites
.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.
Troubleshooting
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.