How these docs are checked
The Nym docs describe software that changes with each release. A docs page can fail its reader in two ways. The reader never gets a fact, or the reader gets a fact that is no longer true.
For some kinds of fact, the docs build takes the fact from the code. For others, a check compares the docs with the code or with the threat model. The checks run in CI on each push and each pull request that changes the docs. Two of them also run in the build of the site, so a fault in those stops the deploy.
A person in a browser and an agent that reads the docs through the MCP server get the same content and the same checks. An agent cannot see the age of a page. If a fact is false, the agent can act on it as if it were true.
Most sections of the docs have one source
On most docs pages, each section is a snippet: one MDX file with its own id. The page file holds only a title and a list of snippet imports. The generated references (TypeDoc, the command output), the changelog and some long operator pages stay whole files.
The docs site, the Markdown copy of each page, llms-full.txt and the MCP search index all read the same snippet files. When an author changes a section, each of these surfaces gets the change in the same build.
A link from one snippet to another names the id of the target, and the build writes the route. If no page shows the target, the build stops.
Each snippet must read alone, because a search result can show it with no page around it. A check lists each snippet that points at text outside itself.
The threat model is typed data
The threat model is TypeScript data, with one entity for each actor, attack vector, privacy property and network configuration. The build turns each entity into a record. A snippet cites the record, and the site draws the table, the diagram or the assessment from it.
Before each build, an integrity step checks the data. It stops the build when two verdicts for the same actor and property disagree, or when an entity names an id that does not exist. It prints a warning for a gap in the data, for example a matrix verdict that the per-actor assessment does not state. The current data has such gaps.
The site renders the tables into static HTML, so the site search reads the same text as a person. The MCP index holds a text projection of the same data.
Some facts come from the code
For the facts in this table, the docs take the value from its source, and no author types it by hand:
| Fact | Source |
|---|---|
| The TypeScript types that cross the wasm boundary | tsify generates them from the Rust types |
| The TypeScript SDK reference | TypeDoc. A CI job fails when the committed reference differs from a fresh build |
| The REST API reference | The live OpenAPI spec of each API |
The --help output of nym-node, nym-api and nymvisor | A CI job that a maintainer starts builds each binary, runs it and commits the output |
| Versions, for example the minimum Rust version | One file of named values, which snippets read by name |
| Network counts, for example the number of nodes | A script reads them from the mainnet APIs, and the site uses its last output |
Placeholders in commands, for example <PUBLIC_IP> | One list. The variables table and the guide lint both read it |
| The complete code of each Rust tutorial | An SDK example file that CI builds. A test fails when the tutorial and its example differ |
A snippet can also cite a Rust item by its file and its symbol, in place of a copy of the code. The snippet tools take the text from the source file. If a pull request renames or removes the symbol, CI fails in that pull request. When a pull request changes a cited excerpt, a bot comment shows the change and the pages that show the excerpt. This site does not render code citations yet.
Guides and tutorials follow a checked form
A page that states diataxis: how-to or diataxis: tutorial in its frontmatter must follow the fixed form of that type. Today these pages are the operator guides and the Rust tutorials. A lint checks each one:
- Each procedure is in a
Stepselement. - Each step heading has a stable anchor and no number, because
Stepsadds the number. - Each code block names its language from a fixed list.
- Each placeholder in a command comes from the shared placeholder list.
The lint checks the form of a guide. It does not run the commands.
The docs checks that run on each change
| Check | It fails when |
|---|---|
| Site build | A link names a section that no page shows, or the threat-model data has an integrity error |
| Snippet check | A snippet, an import or a link is broken, a cited code symbol does not resolve, or a snippet does not compile alone |
| Unit tests and type check | A test of the docs build tools fails, or the tools have a type error |
| Guide lint | A how-to or tutorial page breaks the form of its type |
| Link check | A link to another docs page or file is broken. External links are not checked |
| TypeDoc check | The committed SDK reference differs from a fresh build |
The workflows are in .github/workflows/ of the Nym repository. Their names start with ci-docs and ci-codex.
Each docs record states its authority
The docs tools turn each snippet, each requirement in a specification and each threat-model entity into a record: the text, its id and its links. Each record gets an authority label from its kind:
| Label | Records | Meaning |
|---|---|---|
normative | A requirement in a specification, an entity of the threat model | What the system must do |
descriptive | A specification page, an explanation, a code item | What the system does today |
illustrative | A how-to guide, a tutorial | One way to use the system |
The label tells a reader which record states a commitment. This matters most for an agent. An agent can read a true description of a fault in the code as a rule, and then write code that depends on the fault. The MCP server does not return the label yet.
What the docs checks do not cover
The checks confirm that a fact matches its source, and that a link reaches its target. They do not confirm that an explanation is correct. A sentence about why the design is as it is, or about when to choose one configuration over another, has no source in the code. People write it, and people review it.
A check that follows a link or a name does not read the meaning of the code. The code can change its behaviour and keep its names. Only a test of the behaviour finds that change.
A number that an author types into prose has no check. Where a named value exists, a snippet reads the number from that value.
Docs checks in progress
These changes are not on the live site yet:
| Change | State | What it adds |
|---|---|---|
| Specifications for the mixnet core | On a branch, not merged | Requirements for the Sphinx packet format, client cover traffic and the delay that a mix node adds. A comment above the code that keeps a requirement names its id, and so does a comment above the test that checks it. Tracey reads these comments, and CI fails a pull request when a requirement has no code or no test |
| Links from requirements to the threat model | On a branch, not merged | Each requirement names the privacy property that it serves, or states that it serves none. A reader can then follow a privacy claim to its requirement, its code and its test |
| A shared search index | Partly built, not live | The MCP index moves from the docs build to a shared store, so that other Nym repositories can add their docs and code |
| Code citations on the site | Planned | The site renders a cited Rust item from its source, so a tutorial shows its example code by citation in place of a copy |