Documentation system

Quirl has two deliberately connected documentation layers. They serve different consumers, and each has one authoritative source.

Truth and evidence hierarchy

When sources disagree, use this order rather than copying the most attractive claim into another document:

1. The engineering contract and accepted ADRs define enduring ownership, support, safety, and release-policy decisions. Proposed ADRs remain proposals and do not describe delivered behavior.
2. Runtime canonical sources define executable interfaces: Catalog::builtin() for Quirl's own commands and HOST_API for Lua. Strict KDL is the canonical human source for curated external native command specifications. Generated SDK, catalog, JSON, and SQLite outputs are projections, never independent contracts.
3. Integrated implementation and behavioral tests establish what the current source tree actually does. User-facing prose must not outrun them.
4. README, changelog, guides, and website entry pages are user-facing projections of the first three levels. Website mirrors are generated from repository sources and must not be edited by hand.
5. Benchmarks, recordings, and release reports are exact-artifact evidence. Their result applies only to the recorded revision, digest, environment, and method; it never transfers automatically to a later candidate.

docs/language-design.md deliberately contains two kinds of material: its current-implementation contract is explicitly labeled, while its remaining sections preserve labeled long-term direction and illustrative designs. Neither historical research nor future direction can be used as a current release claim.

Rust API documentation

Public Rust APIs use ordinary Rust doc comments: //! for crates and modules, and /// for public items. A useful contract states what the item represents or does and records relevant invariants, units, limits, side effects, errors, and security assumptions. It does not just expand the item's name into a sentence.

The workspace denies Rust's missing_docs lint. It also denies broken intra-doc links, bare URLs, and malformed Rust code blocks. The existing canonical gate runs the documentation build automatically:

cargo xtask check

For a faster documentation-only iteration, run:

cargo xtask docs

That command builds every workspace crate with dependencies excluded and all Rustdoc warnings denied. Rust examples in doc comments are exercised by the workspace tests as doctests. Generated HTML lives under target/doc and is not checked in.

Command and extension documentation

Rust has no stable runtime reflection for /// comments, so Quirl does not scrape source files or pretend Rustdoc can supply runtime command metadata. Instead, the versioned semantic catalog is the command-level equivalent of a docstring:

Exact catalog records must include stable identity, version, signature, summary, details, typed arguments and their documentation, examples, I/O, effects, and exit-code descriptions. Catalog::quality_issues() and its tests reject incomplete records. The CLI contract test independently checks that every visible Clap leaf and argument agrees structurally with the catalog, so a new command cannot silently disappear from generated documentation or AI discovery.

That exact-record quality contract applies to Quirl builtin and trusted plugin CommandSpec records. The initial external native KDL schema is intentionally narrower: it captures commands, aliases, summaries, descriptions, intents, platforms, flags, arguments, provenance, and closed completion actions. It does not invent typed IO, effects, exit codes, or other schema-v4 facts. The compiled native SQLite is immutable input; the CLI intelligence SQLite remains the mutable composed cache with discovery state and embeddings.

Clap doc comments remain short parser-facing navigation text. Full Quirl builtin contracts belong only in Catalog::builtin(). External native prose belongs only in curated KDL, never in generated SQLite or a Carapace-derived draft. Changing HOST_API requires cargo xtask sdk to refresh the checked-in Lua stub.

Website mirrors and release validation

The website's canonical Markdown mirrors are produced only by website/scripts/sync-docs.mjs; composed builtin catalog and Lua reference pages are produced only by website/scripts/sync-generated-reference.mjs. The external native QCNC SQLite artifact is not a website authoring source. Never repair a generated MDX page directly. Run the appropriate sync command, review the canonical source and generated diff, then run both syncs a second time to prove byte idempotence.

Release evidence status has an additional semantic source of truth: the strict quirl-release-evidence:v1 header in docs/benchmarks/release-v1.0.md. The shared website parser accepts only the closed historical/current states, exact commit and digest shapes, a UTC measurement timestamp, and a bounded platform scope. sync-docs.mjs derives the marked README, changelog, language-design, checklist, audit, and website status regions from that header. The release-attribution check also verifies named Git objects and, for current evidence, the evidence-only direct child of the measured candidate. A byte-fresh mirror cannot therefore override or contradict the canonical evidence state.

An evidence commit cannot embed its own Git object ID. A new current record may therefore use evidence-documentation-commit: none; normal generation may project that transitional form before commit, but it does not attest it. The post-commit check resolves the checked-out HEAD as the evidence commit and proves its parent and diff. Once named, an evidence commit must use its full lowercase ID and exist locally; any later path through HEAD must remain evidence-only. This keeps the next evidence transition possible without weakening the relationship check or inventing a self-hash.

With dependencies installed by the lock-preserving npm ci --prefix website, npm --prefix website run check:generated is the deterministic, non-mutating freshness and semantic-attribution check. npm --prefix website run check adds lint, Next route type checking, and the production build. cargo xtask website-check exposes that website gate explicitly, and cargo xtask release-gate runs it as part of the release workflow; cargo xtask check intentionally remains Rust-focused and does not require Node.

Adding or changing an interface

1. Add /// documentation with the public Rust item.
2. If it is a Quirl command or argument, update Catalog::builtin() in the same change. If it is a curated external native fact, update strict KDL, review its provenance and license, and regenerate the deterministic native database and checksum. If it is a Lua host capability, update HOST_API and regenerate the SDK.
3. Add behavioral tests for the contract, including limits and errors where relevant.
4. Run cargo xtask check. No separate documentation checklist or personal skill is required; the repository gate remembers the rules.

Carapace can only propose an external native draft from a pinned revision. The contributor operations are import to a separate draft, explicit non-overwriting promotion of a reviewed first version, canonical format, strict check, and deterministic build. Use cargo xtask catalog import-carapace, cargo xtask catalog promote --command <name>, cargo xtask catalog fmt, cargo xtask catalog check, and cargo xtask catalog build; the exact pin, checkout, and review procedure is documented in the catalog schema.