Docs Rules
Every rule the docs checks hold a page, README or source file to, by its id, so a writer sees each rule and its limit before a check fails.
How the Rules Are Checked
Each rule names its check in tests/docs (the text) or
tests/docs/code (what needs Link's types), and its numbers come from
tests/docs/limits.toml. The hook guide applies when
writing or changing a hook. Generated artifacts/ directories are excluded
from source discovery, so reports never become README navigation. YAML
frontmatter is metadata rather than prose, and :::cards delimiters wrap a
normal list whose links remain checked.
Declared Data
Folders declared in large-files.toml's data are inputs or records
consumed as a whole. Their Markdown remains raw data for inventories and
line checks, without joining current navigation or contributing outgoing
documentation links. Links from current pages to those files and headings
still resolve, and adjacent paths outside each declared folder remain
current documents.
Every page of the website
These rules hold every page the websites publish, by what a reader sees first: openings, sections, lists, tables, code and links.
- Every authored heading opens with a paragraph (
heading-paragraph), before any list, table, code block or the next heading. A generated Docs index begins directly with its links; it needs no repeated introduction. - A spec kind's reference page keeps its generator's layout, a heading
per field opening with its quoted line, and a command reference has a
heading per resource. Each is one page, however long:
limits.toml's[spec-pages]and[reference-pages]name the rules, such asmarkdown-linesandheadings, that don't hold them. - A spec page or command reference generated from declarations says
each entry as its declaration's help does, as deep as they make it.
[spec-pages]and[reference-pages]name the rules that don't hold it for that:duplicates,depth,item-length,thin-sectionand the two click rules. Theitem-length,thin-section,duplicatesanddepthrules don't hold it. - A generated page's kind has a doc comment on every field and an
about, its Every Option reads back through its reader, and its module's section page links it in its opening (references). - One paragraph a section (
one-paragraph): two in a row get a heading between them. - At most 600 characters in a paragraph (
paragraph-length), link targets left out: split a longer one into subsections. - A section's lone paragraph has at least 80 characters (
thin-section): fold a thinner one into the section beside it. A page's opening and a License section are exempt. - At most 60 characters in a table cell (
cell-length): a row that needs explaining is a subsection. - At most 400 characters in a list item (
item-length): one that needs a paragraph is a subsection. No limit on how many items or rows. - A list is three or more like things, or links (
list-items): fewer fit in a sentence. A short item may lead with its name in bold. - A table compares two rows or more (
table-rows): one row is a paragraph. - Keys, flags and commands are subsections, never a table's rows
(
table-code): a table whose rows each open with inline code fails. - A row is scanned by its first word (
table-articles): a table's first cells don't open with "a", "an" or "the", but one catch-all row. - A section's page, one with pages under it in
## Pages, has a hook (hooks): a one-line quote right under its plain title. Documentation shows the short title; the marketing site may show the quote as its heading. No other page has one. A section inlarge-files.toml'sunhookedhas none yet: none joins. - At most 45 characters in a hook (
hook-length), opening with its keyword, never "it", "its", "a" or "the", and holding no colon. Before writing one, read the hook guide. - A hook is a title, so it's in Title Case (
hook-case), and it says more than its page's name (hook-words, 3 words at least). - Code is in backticks: every command and what's typed in a terminal
(
bare-commandfails a barelnkcommand), environment variables (bare-variable), paths and file names (bare-path), types, functions, crates and programs, settings' keys and values, hosts and ports that aren't links, what a user types to the agent, and output to match. Names of products, parts and ideas are not. - A module a user acts on opens its first page with a quickstart
(
quickstart): anshblock before the first##, or inside the first task section introduced by<!-- quickstart -->, of the commands that get it working. It ends at the first thing that works. - A quickstart assumes only
lnkinstalled andlnk uprun, so everything else it needs comes first, in order (lnk agent startbeforelnk agent connect slack), and a command installs its own module. One only Link runs saysquickstart = falsein itsmodule.toml's[documentation]. - A quickstart sets no environment variable (
quickstart-env): each command runs alone and asks for what it needs, aslnk agent startasks for a model's key. - Link writes only under
~/Linkand~/.lnk(output-paths): anlnkcommand's--out,--toor--dir, andLNK_INSTALL_DIR, in a page'sshblock name a folder there, or are left out for the layout's default. - Troubleshooting is a page of its own (
troubleshooting):troubleshooting.mdbeside the feature's page, one heading per symptom with its fix.decisions.md,security.mdandtroubleshooting.mdhave no line limit: they're grouped by topic in sections and subsections, and never name a run, a date, a person or anything private. - A page in
large-files.toml'sunshaped(unshaped) was written before these: none joins, and a page leaves once it keeps them. - Paragraphs and subsections come before lists and tables; a list or table is for short parallel items or for links. A page opens with a focused quickstart block; every other command is under a heading of its own. Each spec key, flag or setting is a subsection: its name the heading, a paragraph on what it takes and its default.
- Present tense (
history): how it works now. No dates of development, no "we tried", "it used to", "decided by". - Links resolve (
links): every relative link and anchor, in every page and every document the README indexes hold, in any workspace; a link to a page is a relative path to its file, never its address on a website. - At most 10 headings under a heading (
headings), and 10 at a page's top: group more a level deeper, keeping their words. Generated index headings are outside the authored heading budget. - An abbreviation is learned along the way (
abbreviations): a page spells it out where it first uses it, as "Agent State Protocol (ASP)", and uses only the abbreviation after. Headings may spell it out. The checked abbreviations aretests/docs/abbreviations.toml's. - One word per meaning (
words): a phrasetests/docs/words.tomllists, fromAGENTS.md's Words, such assigning keyfor a signer, is never in a page's prose. Among them, "ships" never says what Link offers (Link ships,ships with,the shipped): Link comes with harnesses, includes its model facts and provides ready-made agents, while a release still ships. - A page's title names its subject, never a pronoun (
title-pronouns):words.tomllists "it", "they" and their forms, since a title stands alone in a tab, a search result or another page's index. - Headings start with their subject or action, never "a", "an", "the", "it", "its", "it's", "this", "that", "these" or "they".
- At most 10 pages under a page (
pages) innavigation.md's## Pages, and one page at each URL. - A page with pages under it holds at least 3 (
group-pages): fold one or two into it, or move them beside it, so no level opens for a page or two. - A page's children are read by their kind,
tests/docs/kinds.toml's order: the guide, the section's own pages, developer pages (More, contracts, interfaces, developing, command line and adapters), generated references, then decisions, security and troubleshooting. The tree writer orders them so, keeping the curated order within a kind, and thenavigationrule holds the outline to it. - A guide, decisions, security or troubleshooting page holds no pages
(
kind-leaves): what it holds is one page's subject. - A module with commands of its own, so a generated command reference,
has a
guide.mdand atroubleshooting.mdin itsdocs/(module-pages): where a reader starts, and where they go when it breaks. - Website prose stays in docs (
website-words): no Markdown in itssrc/orweb/packages/site/src/. Each app'sdocs/navigation.mdholds structure and order; shared locale catalogs hold interface text. - A translation (
translations) is<page>.<language>.mdbeside its English page, its language one ofpackages/component/languages.toml's, and its first line names that English and the hash it was made from. While the English is unchanged, it keeps the English's headings and code blocks: edit the English, never a translation. - A page is introduced in a paragraph of the page at its address's
parent (
introduced), the nearest that's a page: a sentence there says why it exists and links to it. A list, a table or a generated index is no introduction, so the links in prose alone reach every page. - A paragraph is on one page only (
duplicates, from 120 characters): keep it where its subject is owned and link there. - A heading is one level below the heading it's under
(
heading-levels): no###right under a#. - A page's deepest heading is at most 7 levels down (
depth) from the home page: its address's segments, then a level for each heading below its title, since the address and the headings are one tree. - A package's pages are under the address its enclosing package's
pages share (
follows-code), so the docs' tree follows the code's. A typed configuration reference also establishes a logical home for that owner's configuration pages through the checked spec catalogue; unrelated pages still follow their enclosing package. - A page or package these structure rules held when they came in is
in its workspace's
large-files.tomlunder[held](held), by the rule's id: none joins, one leaves once it keeps the rule, and an entry whose rule or file is gone fails. - Design rationale goes in a
decisions.mdbeside the page (decisions), never a## Decisionssection; why someone would use the feature belongs in its main explanation. - A website app's own pages (its
docs/, outline aside) put every heading in Title Case (title-case): each word capitalized but the short words inside it. - No page is titled
# Get Started(get-started): a section's first page has a short pitch of its own. - A page opens with a paragraph under its title (
opening): its first sentence is what every README linking the page says of it. - Terminal explanations are prose, never padded inline comments (
comments). Thezshrule still applies to shell syntax. - A comment pastes into zsh (
zsh): plain words, none of' " ? * [ ] ( ) { } ; | & < >or a backtick, and none after--. - Nothing public names what's private (
private): no private folder, plan, person-only settings file, or session scratch path. Omit absent internals entirely, including explanations that they are missing. - Repository layout inventories list only existing source folders
(
repository-layout). List and table entries in Layout, Source Tree, Folder Structure, or Repository Organization sections resolve inside this workspace or the owning component. Placeholders match existing folders; omit absent entries rather than explaining them. - Every
lnkcommand a page gives exists (commands), in a shell block or in inline code. - A flag on an explicit command example exists on that command or its
parents (
flags), including continued shell lines. Flags after--belong to the invoked program. Standalone flag mentions need enough context for a reader to identify their command. - Provided literal values use the command's actual value parsers (
arguments). Complete shell examples also satisfy required arguments and conflicts. Inline fragments may omit arguments; placeholders are not literal values. A deliberately rejected shell example sayssh expect=error. - Production Rust reads of static variables have declarations in the reading
crate's
variables.toml(environment-reads): a definition, or a use of a variable another crate defines. Each variable has one definition, and a flag's fallback names a defined one. Dynamic namespaces and caller-selected reader functions need explicit declarations, and a wildcard never permits an undeclared literal. - Every JSON block names its owning released type or schema (
json) with<!-- json: owner-id -->immediately before its fence. Show complete valid values, not ellipses or pseudocode, and reject unknown or mistyped fields. - Published spec references bind to their actual types (
references). Generate their field and checked-default summaries with the inventory writer. Shared sections name their owner; proposed formats visibly say they are unimplemented. Preserve the authored explanations around generated summaries. - Every TOML block a page shows is a spec Link reads (
specs), by the page's kind: box, sandbox, agent, environment, job or policy. A block whose first line names its file, as# types.tomlor# schema.toml, is read as that file. - The writing guide's table of limits is
limits.toml's (limits). - A spec kind's reference page is written whole from its module's
types.tomlbylink-actions-surfaces, with the module's command reference, and the references check refuses one absent, stale or edited by hand (references). - Source-backed inventories match their declared sets (
inventories): regenerate withcargo run -p link-docs-check-code --bin lnk-docs-inventories -- --writeafter changing commands, declared variables, credentials, spec references or shared state locations. Credential kinds come from the runtime catalogue and retain owning code and docs. - A command a person runs, on the command line and not plumbing, names
the section explaining it (
command-pages),docs = "<address>#<anchor>"in itsactions.toml, and that section shows it aslnk <command>, outside the generated indexes and inventories. A primary command's section is a heading of its own. - Each verb a module's public commands start with has a page or folder
of its own in its
docs/, named for the verb (verb-pages): a suggestion, so it warns and never fails. - A page's first mention of a command another package owns links to
that section (
owner-links), so a page explains its own function and sends the reader to the owner for the rest.lnk-docs-inventories --writeinserts the links. - A command group whose word is no approved verb, such as
lnk box image(command-folders), has a folder named its word in its owner's docs, whose pages show it: a major command gets room of its own. The owner is the package containing its declared documentation section. An agent command driving a tool uses that tool's existing folder. - An inventory lists what exists; a page says what it's for. Every
LNK_*variable (variable-pages) and every folder of Link's state (state-pages) is named in backticks on a page beyond its inventory. What these three held when they came in is under[held], by<declaring file>#<name>. - Every tracked TOML file is of a kind in
tests/docs/code/files.toml(files), and each kind with a notice,module.tomlandlayer.toml, opens with the header the catalogue writes, as does the Repository Files page's lists: regenerate them withlnk-docs-inventories --write.
Every file in a workspace
These rules hold every file of a workspace, a page or not: READMEs,
Markdown and Rust lengths, layers, and what a docs/ folder holds.
- Every Cargo package has a page in its own
docs/(crate-page), saying what its code is and does, but a test's fixture. One listed inlarge-files.toml'sundocumentedwas written before this: none joins, and one leaves once it has a page. - A non-root README outside
docs/is a map (hub-words): at most 120 words, a sentence on what the folder holds, its pages under## Docs, then entry points under## Code. How it works is a page indocs/. The workspace root README introduces the product, its features and its mission without the map word limit. Its other checks still apply. - A README's shape (
readme-shape), at most 5 links under## Code: a paragraph under its title on its folder (its long description), then## Docs, its pages and child hubs once each, briefly described, in the website's order and nesting, in Pages, References and More. A README of code sorts them under subheadings by kind (Indexes of Code). A hub with nothing under it has no## Docsindex. - A README's or
docs/page's title, the name every index lists it by, is in Title Case like a website heading (titles). Code in a title goes in backticks. - A package's README then has
## Code, at least one link, to code only: each a file's name in backticks, linked, then a colon and what it is, for its entry points, three or so, alphabetically by name. Any other section goes after them. - At most 500 lines in a Markdown file (
markdown-lines): split it by subject before it grows past them. Generated files and validated generated index blocks are exempt from the authored line budget; their links and prose still pass the other checks. - A library's existing doc examples run (
doc-tests): adding the first Rust example to a library's docs (a fence that is plain,rust,no_run,compile_failorshould_panic) takesdoctest = falseout of its[lib]; a library with none keeps it. A block that isn't Rust says its language:text,sh,toml. - A
docs/folder holds only what people read (docs-files): Markdown, the shell a person types, and the data or pictures a page shows (.yaml,.json,.svg,.png). A program, its inputs and its output go beside the code that runs them. Adocsfolder that is a package of its own is code, but its owndocs/is docs again. - A package's docs lines are within its Rust's prediction
(
docs-ratio, 3.5 times either way), itssrc/lines to the 0.7: docs grow with code, more slowly. Test-only packages use maintained test code.limits.tomlholds the curve;lnk-docs-surveyreports production, test, generated, and documentation counts separately. - At most 1,000 lines in a Rust file (
rust-lines): split it where a responsibility ends before it grows past them. - A file already over its limit is in its workspace's
large-files.toml(large-files): it may shrink, never grow, and no file joins it. - Only
link-formatprints (output): codelnkruns writes blocks to itsOut, neverprintln!,eprintln!,print!, an ANSI escape or a backtick in a string. A file inlarge-files.toml's[output], with its print sites, may shrink, never grow, and none joins it. - Each group folder is a layer (
layers): itslayer.tomllists every group folder it is built on, with no cycle, and a crate depends on, runs (lnk <group>, or throughensure) and answers the questions of only its own group's crates or a listed one's. - Every Cargo package, every folder holding two or more, and every
folder grouping two or more files or folders outside a package, a
docs/tree and a hidden folder has a README hub (readmes), but underfixtures/,assets/or a package'ssrc/andtests/, and in the folders a program reads or writes whole, whichlarge-files.toml'sdatanames. - A folder hub links one level down (
through-readmes), to a folder'sREADME.md. The workspace README introduces the products and may link directly to their documentation. Source links still follow folder hubs. - README indexes are generated from documents and nearest child hubs
(
navigation): runcargo run -p link-docs-check --bin lnk-docs-tree -- --root <workspace> --write, then verify with--check. Preserve prose outside marked indexes. Site pages follow their nearest address ancestor and retain sibling order. - Every selected document has a reading path from its root README
(
doc-reachability), including English public pages and private planning documents; the writer and checks use the same discovery. - A page is at most 5 links from the workspace's root README (
clicks): link it where a reader meets what it explains.lnk-docs-clicksreports each workspace's clicks, naming the deepest pages. - The pages are on average at most 265 hundredths (
average-clicks) of a link from the root README. Lower both limits as they're reached, never raise them. Both measure the authored pages: a generated page is looked up from its index, never read on the way to another. - A package's
Cargo.tomldescription is its README's first sentence, but for the package's name opening it (descriptions): every index lists the package by it, andlnk module listshows it. - A non-package grouping with one child hub and no documentation of its own
is reported for review (
single-child-groups): advisory only; architectural layers and docs bridges are exempt, and no folder is flattened automatically.