The Docs' Code Checks

link-docs-check-code checks documentation against the code Link ships. Its rules validate commands, examples, environment declarations and source-backed references. Run cargo test -p link-docs-check-code to check them without invoking a built plugin. The text and reading-tree rules belong to link-docs-check, as Writing Docs explains.

commands

Every lnk command a page gives is one a plugin's plugin.toml declares, or one the core handles itself. The registry holds every group and every command the components declare, those hidden from lnk --help too: a page may name lnk agent state-send, which an agent's harness runs, not a person. A group whose first word may be a name, such as lnk measure --agent <agent>, takes any.

flags

Flags in explicit inline commands and shell examples come from the referenced command's typed declaration, including parent flags and short aliases. Continued lines, quoted values and attached values are read as one invocation. After --, flags belong to the invoked program; a pipeline's other programs have their own arguments.

Scope

The check covers named flags on explicit lnk invocations, including internal registry commands. Help and version switches follow the CLI's built-in behavior. A flag mentioned on its own in prose has no command to check against. Value types, required arguments and flags that conflict remain separate checks.

arguments

Explicit literal values use the actual Clap value parser, including enums, numeric ranges and custom types. Complete shell examples also satisfy required arguments, cardinality, conflicts and dependencies. Inline fragments may omit required arguments. The check clears parser environment inputs and treats shell placeholders as symbolic values.

Expected errors

A deliberately rejected example uses a sh expect=error fence. Its arguments must actually be rejected. Parsing verifies the command contract; quickstart fixtures verify supported examples' effects in an isolated environment.

environment-reads

The source audit follows production Rust environment reads through imports, constants and reader helpers. Every static LNK_* name needs an owning command declaration or library Cargo declaration. Dynamic namespaces and caller-selected reader APIs have separate declarations. A wildcard never authorizes a newly added literal name. Tests, fixtures and build-only code are outside this production audit.

json

A JSON fence has an immediately preceding <!-- json: owner-id --> marker. The registered binding deserializes it through the shipped wire type or website schema. Duplicate keys, trailing data, unknown fields, missing fields and wrong types fail. Defaults that silently discard supplied fields fail too. A new owner needs a binding rather than a copied shape.

Website schemas

The sponsors and offers examples use the same TypeScript schema constants as the runtime readers. Rust reads their strict JSON literal declaration and rejects unsupported schema keywords. Website tests validate the same published examples through the runtime validator.

references

The writer derives each spec's field summary from its real deserializer, with source discovery for flattened or custom representations. Nested fields and struct variants are included; an opaque representation fails closed. Checked defaults come from actual deserialized values and owner constants. The generated summary supplements the authored explanation of each setting.

Reference ownership

Every published spec page binds to an owning type or an existing bound shared section. A proposed format must visibly say it is unimplemented and cannot present a runnable TOML example. Machine configuration includes extensible consumer settings, so its summary explicitly covers its typed identity and machine-kind records.

specs

A TOML block a page shows is a spec Link reads, read strictly by its type: a box spec on the boxes' pages (or a setup stage's sandbox spec), a sandbox spec on the sandbox's, and elsewhere one of them, an agent's spec or a team's, an agent's sandbox file, a model's, or /etc/lnk/kind.toml, its first line naming it.

Other TOML a page may show

A plugin.toml, or a spec test case, its first line # tests/specs/<group>/<case>.toml, whose [spec] is its group's.

inventories

Inventories enumerate their owning sources, and the check compares the whole generated block. Missing, obsolete, duplicated or changed entries fail. The writer updates only unique marker pairs and preserves the surrounding explanation.

Sources

The command index reads registered routes and core command declarations. The environment index reads command and library declarations, including internal and test overrides, with dynamic namespaces listed separately. The spec index reads the published spec and shared-section reference pages, excluding design rationale. The shared-state inventory reads the same state::Area table that Link's code resolves paths from.

Namespace commands and aliases

The namespace command and alias references read command-surface actions from the agent and model registries consumed by Link Harness. The alias inventory records each spelling and its canonical target. Replaced and CLI-only actions are excluded. Duplicate primary names, duplicate aliases, aliases shadowing primary commands and missing targets fail. Root-level /help is a discovery command outside these namespaces.

Credentials

The credential index reads the runtime catalogue, checks unique identifiers and labels, and resolves each owning document anchor and production source symbol. New credential categories enter through that typed catalogue, rather than a second expected list.

Regenerate

Run the inventory writer after changing a declaration or reference, then the reading-tree writer to persist any new page's navigation. The default inventory mode checks without writing.

cargo run -p link-docs-check-code --bin docs-inventories -- --write
cargo run -p link-docs-check --bin docs-tree -- --root . --write

sandbox-keys

The sandbox spec's table of keys is the one its type makes, lnk sandbox spec --keys: the type, its comments and its flags are the one source, so the page is never edited by hand there.

skill-code

The writing-docs skill has a line for each of these rules, naming its id, as it has for link-docs-check's.