CLI and deployment

Silen exposes a small CLI. Run it through the project package manager so the command and Agent Contract always match the installed version.

Primary commands

pnpm silen init docs
pnpm silen dev docs --host 127.0.0.1 --port 5173
pnpm silen build docs
pnpm silen preview docs --port 4173

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:

pnpm silen ai init docs
pnpm silen ai index docs
pnpm silen ai audit docs
pnpm silen ai eval docs
pnpm silen ai skills ./agent-skills
pnpm silen mcp docs

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.

Static deployment

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:

export default defineConfig({
  siteUrl: 'https://example.github.io',
  base: '/handbook/',
})

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.

Release check

Repository maintainers run one canonical command:

pnpm site:ai-check

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.