sourcebound 1.2.1__py3-none-any.whl

clean_docs/standards/default.json

@@ -0,0 +1,309 @@
+{
+  "pack_version": 1,
+  "profile": "sourcebound-default",
+  "source": {
+    "name": "STANDARD.md",
+    "sha256": "86eb173495677069224628217adc075374ad4ab8526bf05e3e392072f4891185"
+  },
+  "tiers": {
+    "voice": "2. Voice at the sentence level",
+    "document": "3. How to explain something technical simply (the actual techniques)",
+    "corpus": "6. Beyond the single doc: does it earn its existence?",
+    "grounding": "7. Grounding: the doc must be true to the code (and stay true)"
+  },
+  "headings": [
+    {
+      "level": 2,
+      "title": "The one principle everything else follows",
+      "line": 19
+    },
+    {
+      "level": 3,
+      "title": "The rule constitution",
+      "line": 41
+    },
+    {
+      "level": 2,
+      "title": "1. The medium boundary (the decisions to get right)",
+      "line": 103
+    },
+    {
+      "level": 3,
+      "title": "Prose: carries the \"why\" and any logic spanning multiple items",
+      "line": 105
+    },
+    {
+      "level": 3,
+      "title": "Code: executable evidence, never bare",
+      "line": 116
+    },
+    {
+      "level": 3,
+      "title": "Table: for comparison or lookup, where order doesn't matter",
+      "line": 147
+    },
+    {
+      "level": 3,
+      "title": "Callout: an off-ramp, never where a concept is first taught",
+      "line": 155
+    },
+    {
+      "level": 3,
+      "title": "Architecture: structured text first, diagrams only when topology earns them",
+      "line": 162
+    },
+    {
+      "level": 3,
+      "title": "Screenshots and video: teach recognition and interaction",
+      "line": 181
+    },
+    {
+      "level": 2,
+      "title": "2. Voice at the sentence level",
+      "line": 198
+    },
+    {
+      "level": 3,
+      "title": "Whimsy: give precision a pulse",
+      "line": 225
+    },
+    {
+      "level": 2,
+      "title": "3. How to explain something technical simply (the actual techniques)",
+      "line": 257
+    },
+    {
+      "level": 3,
+      "title": "Define the subject, then state the BLUF purpose contract",
+      "line": 265
+    },
+    {
+      "level": 3,
+      "title": "Use repeatable explanation techniques",
+      "line": 304
+    },
+    {
+      "level": 2,
+      "title": "4. \"Don't do this\" and gotchas",
+      "line": 324
+    },
+    {
+      "level": 2,
+      "title": "5. Page shape by genre",
+      "line": 337
+    },
+    {
+      "level": 2,
+      "title": "6. Beyond the single doc: does it earn its existence?",
+      "line": 382
+    },
+    {
+      "level": 3,
+      "title": "Put the point, action, and proof on the first screen",
+      "line": 419
+    },
+    {
+      "level": 3,
+      "title": "Keep the register concrete",
+      "line": 438
+    },
+    {
+      "level": 3,
+      "title": "Give the corpus a navigation contract",
+      "line": 467
+    },
+    {
+      "level": 3,
+      "title": "One source, purpose-built projections",
+      "line": 485
+    },
+    {
+      "level": 3,
+      "title": "Keep facts next to the behavior that owns them",
+      "line": 530
+    },
+    {
+      "level": 3,
+      "title": "Enforce rules at the narrowest honest layer",
+      "line": 542
+    },
+    {
+      "level": 3,
+      "title": "Assign ownership and learn from failed tasks",
+      "line": 553
+    },
+    {
+      "level": 3,
+      "title": "What only judgment can check (the honest seam)",
+      "line": 570
+    },
+    {
+      "level": 2,
+      "title": "7. Grounding: the doc must be true to the code (and stay true)",
+      "line": 602
+    },
+    {
+      "level": 2,
+      "title": "8. Pre-publish checklist",
+      "line": 631
+    }
+  ],
+  "checklist": [
+    "In an overview, the first 15 lines contain the purpose, a primary action, and one proof; other roles open with the information their reader needs first.",
+    "Review a README over 90 lines, a guide over 150 lines, or a section over 40 lines for a second job. Split by reader job, but keep one complete safety, diagnostic, or lookup sequence intact.",
+    "The README routes decisions, first tasks, concepts, and lookup work through an `If you need to... | Start with | You will leave with...` table.",
+    "Each explanatory section over 80 words links to the deeper page that owns its detail.",
+    "No reader-facing sentence crosses the nominalization, significance-narration, or scoped qualifier-density thresholds.",
+    "Paragraph rhythm includes a short sentence when three or more sentences would otherwise all land between 15 and 35 words.",
+    "Authority and execution assurances have one canonical home; overview pages link there.",
+    "A rule collision resolves by truth, grounding, budget, register, then warmth; any unavoidable loss has an explicit yield naming the winning rule.",
+    "Every code block has a prose lead-in ending in `:` and (where useful) a follow-up.",
+    "Every fenced code block declares its language; literal output and prompts use `text`.",
+    "No table encodes precedence or an ordering rule; those are prose or numbered lists.",
+    "Every comparison table's columns are the reader's actual questions; ordered logic stays in prose or numbered steps.",
+    "Every \"don't\" is paired with an \"instead\"; every warning states a *mechanism*.",
+    "Callouts are semantic (Warning = harm, Note = easily-missed, Tip = optional) and none carries a concept's first explanation.",
+    "Placeholders and real values are never mixed on one line; language tags are correct (`bash` vs `text` vs `json`).",
+    "Code examples are realistic and sparse in comments; filenames, diffs, focus, or tabs expose placement and variants when needed.",
+    "Screenshots are cropped, scrubbed, annotated, captioned, and described; optional video has a complete text path. Architecture has one structured source, records only applicable dimensions, and remains usable without rendered pixels; a diagram appears only when topology or temporal interaction adds information.",
+    "Every Mermaid diagram has an adjacent text equivalent beginning with `Diagram:`.",
+    "Every image has useful alternative text or an explicit decorative-image marker.",
+    "The page names its one governing constraint early.",
+    "No booster adjectives (`seamless`, `powerful`, `simply`, `comprehensive`, `leverage`, `utilize`). <!-- slop-ok: banned-word registry for the checklist -->",
+    "Every clause adds information; claims needing separate evidence are split; the system is named as an actor; reader actions are imperative.",
+    "Every overview, conceptual, or tutorial page has at least one subject-derived memorable element unless its topic is wholly literal; each flourish passes the truth and deletion tests.",
+    "Commands, configuration, errors, repair steps, security and privacy boundaries, accessibility text, and reference facts stay literal; whimsy never carries a required fact or action.",
+    "Headings use sentence case; UI controls use semantic bold; link text names its destination.",
+    "Sections end by linking outward; version notes are inline at the claim.",
+    "The document's role is explicit in its structure, and every applied rule helps that role.",
+    "Ephemeral task state lives in git, PRs, or issues; durable evidence records and live plans retain their declared owner, time horizon, and evidence boundary.",
+    "The audience matches the role: human task pages address people; executable agent procedures preserve their runtime contract instead of imitating human prose.",
+    "No fact is restated across sibling docs; shared facts have one canonical home, cited.",
+    "The page fits the corpus navigation contract and its genre follows the reader's intended path.",
+    "Procedures include an observable result and verification; troubleshooting proceeds from symptom through diagnosis and repair before escalation.",
+    "Generated reference comes from the defining source; hand-written prose supplies context rather than copying signatures, schemas, defaults, or option lists.",
+    "Every deterministic rule has positive and negative fixtures, a repair, a severity, and a scoped exception model.",
+    "No reference doc carries provenance, receipts, or baseline deltas; those go in a changelog.",
+    "No sentence restates a prior sentence without a local safety or execution reason; each explanatory section leads with its takeaway.",
+    "Each standalone reader page names its job near the opening. Overview, tutorial, and task pages over their budgets split only when the split preserves safety and lookup; references, architecture records, evidence, agent procedures, and templates do not inherit those budgets.",
+    "Every factual claim (capabilities, flags, counts, routes) traces to a source in the code, not to memory or an old draft.",
+    "For every product, system, or concept overview, the first screen defines what category the subject belongs to with an ontological definition, not merely what it does; a reader with no context could state it back.",
+    "Every overview, concept, tutorial, and task page opens with the applicable part of a BLUF purpose contract: reader situation, consequential problem, and resulting capability are explicit, falsifiable, and true to the code. References, evidence, agent procedures, and templates use their role-specific opening instead of filler.",
+    "Purpose prose names the project-specific subject, operator, consequential failure, and authority boundary; it does not use a stock sentence shared across unrelated projects.",
+    "Canonical meaning has purpose-built human and agent projections rather than separately maintained copies; each projection identifies its authority and applicability.",
+    "Consequential tasks teach the model, procedure, and judgment boundary. They state permissions and side effects, show how to verify and recover, and tell the reader when to stop or ask.",
+    "Executable examples and audience-task evaluations prove correct action and at least one negative boundary; retrieval units remain intelligible outside their original page."
+  ],
+  "policy": {
+    "readme_max_lines": 90,
+    "guide_max_lines": 150,
+    "section_max_lines": 40,
+    "preamble_window_lines": 15,
+    "nominalization_threshold": 3,
+    "nominalization_allowlist": [
+      "documentation",
+      "application",
+      "section",
+      "configuration"
+    ],
+    "sentence_variance_min_words": 15,
+    "sentence_variance_max_words": 35,
+    "qualifier_threshold": 2,
+    "significance_phrases": [
+      "exactly the",
+      "the very",
+      "this demonstrates",
+      "deliberately",
+      "is itself",
+      "which is precisely"
+    ],
+    "prohibited_boosters": [
+      "seamless",
+      "powerful",
+      "simply",
+      "comprehensive",
+      "leverage",
+      "utilize"
+    ],
+    "require_grounded_facts": true,
+    "require_definition_first": true,
+    "require_one_job": false,
+    "require_purpose_contract": true,
+    "require_preamble_contract": true,
+    "require_readme_routes": true,
+    "require_depth_links": true
+  },
+  "style": {
+    "precedence": [
+      "truth and honesty",
+      "grounding",
+      "reader budget",
+      "register",
+      "warmth"
+    ],
+    "voice": {
+      "register": "helpful senior colleague",
+      "reader_actions": "second person and imperative",
+      "system_behavior": "name the system as an actor and state behavior as fact",
+      "sentence_shape": "split claims that need separate evidence or differ in scope",
+      "verbs": "plain and concrete",
+      "certainty": "direct facts; mark genuine uncertainty explicitly",
+      "contractions": "allowed"
+    },
+    "purpose_contract": {
+      "begin_marker": "<!-- sourcebound:purpose -->",
+      "end_marker": "<!-- sourcebound:end purpose -->",
+      "position": "first meaningful block after the H1",
+      "mechanical": [
+        "exactly one marked purpose block",
+        "purpose block precedes body content",
+        "purpose prose does not restate the H1"
+      ],
+      "judgment": [
+        "defines the project-specific subject and intended operator",
+        "names the consequential failure or decision the page addresses",
+        "states the authority boundary and a falsifiable resulting capability",
+        "uses authored language grounded in the implementation and cited sources"
+      ]
+    }
+  },
+  "generation": {
+    "instructions": "# Documentation style guide: clean, grounded developer docs\n\n<!-- sourcebound:policy register-v2 -->\n<!-- sourcebound:purpose -->\nSTANDARD.md is the canonical writing and documentation policy packaged with Sourcebound. Use it when writing or reviewing repository documentation for people or agents: it prevents correct facts from becoming hard to find, easy to misread, or detached from source, and it defines how to choose the right medium, voice, canonical home, and evidence boundary for each claim.\n<!-- sourcebound:end purpose -->\n\n**[Start with the governing principle](#the-one-principle-everything-else-follows)**.\n\nThe [pre-publish checklist](#pre-publish-checklist) is the proof surface for an authored review.\n\n<!-- sourcebound:allow audience reason=\"This standard names agent-workflow signals as policy examples rather than addressing an agent\" -->\n\nDerived from a close reading of a developer-documentation corpus spanning overview,\nquickstart, workflows, best practices, memory, hooks, integrations, settings, and CLI\nreference pages. Every rule below traces to an observed, repeated convention in that corpus.\nsourcebound packages this file as its canonical default standard.\n\n## The one principle everything else follows\n\n**Choose the medium by what the reader is doing at that sentence, not by what the content is about.**\n\n| Reader's current verb | Medium |\n| --- | --- |\n| Orienting, deciding, or asking why | Prose |\n| Doing something in code or a shell | Runnable code block |\n| Acting in a visual interface | Cropped screenshot or short video |\n| Choosing among options or comparing attributes | Table |\n| Looking up one fact by key | Registry or generated reference |\n| Following a sequence | Numbered steps |\n| Comparing state transitions | State table or state model |\n| Tracing cross-actor timing, retries, or overlap | Sequence or event model with an accessible text projection |\n| Understanding spatial, cyclic, or branching topology | Structured graph; rendered diagram when it helps |\n| Avoiding a non-obvious trap | Semantic callout |\n| Doing the same task in one of several environments | Deep-linkable tabs |\n| Checking whether the task worked | Expected result or verification command |\n\nA page is just this rule applied sentence by sentence. Reference pages look different from\ntutorials only because a reference reader looks-up more often than a tutorial reader orients.\n\n### The rule constitution\n\nRules resolve in this order: **truth and honesty → grounding → reader budget → register → warmth**.\nA lower rule never degrades a higher one. A repair must not widen a claim beyond its evidence, drop\na limitation, detach a receipt, or weaken the page's point to make a lower-priority check pass.\n\nClassify the document's job before applying a rule. An overview orients. A tutorial teaches ordered\nsteps, a task page gets work done, and troubleshooting moves from symptom to recovery. A reference\nsupports lookup. An architecture record preserves boundaries and time horizons, while an evidence\nrecord preserves observations. An agent procedure constrains actions, and a template is runtime\ninput.\n\nPrefer path, filename, frontmatter, title, and repository convention as role evidence. When those\nsignals are ambiguous, declare `<!-- sourcebound:role reference -->` with the narrowest matching role.\nThe supported roles are `overview`, `component-overview`, `tutorial`, `task`, `troubleshooting`,\n`reference`, `architecture`, `plan`, `evidence`, `agent-procedure`, and `template`. A role marker\nscopes rules; it never suppresses broken links, source drift, unreadable bytes, or concrete residue.\nA rule that helps one role can damage another. Purpose and routing checks help an overview; they\ncorrupt a two-line prompt template. Fixed page budgets can expose a sprawling guide; they can split\na safety constraint from the step it governs or make a reference harder to scan.\n\nRepositories may adopt the sourcebound register for one document by adding\n`<!-- sourcebound:policy register-v2 -->` after its title. The marker selects a policy profile; it\ndoes not decide which rules fit. The document's role still selects rules one by one. The marker\nnever changes that role, overrides a repository-native form, or turns an uncertain editorial call\ninto a mechanical failure.\n\nEvery rule passes three gates. **Applicability** asks whether the rule helps this document role.\n**Evidence strength** separates a demonstrable defect from an editorial inference. **Enforcement\nownership** asks whether the repository accepted that compatible policy rule as a gate.\n\nA provably broken local link, unreadable document, concrete machine-specific residue, or stale\nsource binding has a mechanical witness, but a witness alone is not authority to gate an untouched\nrepository. Before setup, integrity defects, role-compatible writing-policy candidates, and\nrepository-neutral corpus signals cannot become blockers. The default assessment reports integrity\nand corpus signals; `audit --preview-policy` adds bounded, role-compatible house-policy candidates.\nA manifest accepts repository integrity checks as gates. A policy marker accepts compatible\ndeterministic policy rules for that document. Neither activates an incompatible rule, makes a guess\ntrue, nor certifies that the chosen motivation matters, the teaching sequence works, or the page\nhas earned its personality.\n\nWhen two rules cannot both pass, move the detail one layer deeper before cutting it. Depth is the\nstandard pressure valve: the overview keeps the choice and route. A guide or lookup page keeps the\ncaveat, source proof, or schema. Delete only material that no reader layer needs.\n\nMark an unavoidable loss instead of hiding it:\n\n```markdown\n<!-- sourcebound:yield rule=\"qualifier-density\" to=\"truth-honesty\"\n     reason=\"The sentence preserves two independent safety boundaries\" -->\n```\n\nThe reason names the winning rule and the fact that would otherwise be lost. A repeated yield at\nthe same boundary means the threshold is wrong. Fix the rule instead of teaching the corpus to\nignore it.\n\nAuthor all applicable rules before rewriting a page. Then make one whole-document repair against\nthe complete battery and this precedence order. Sequential per-rule repair is forbidden because\nthe last repair silently wins.\n\n---\n\n## 1. The medium boundary (the decisions to get right)\n\n### Prose: carries the \"why\" and any logic spanning multiple items\nProse is for cause and effect: anything with a *because* in it. It always comes *before*\ncode, never after as cleanup. Precedence rules, tradeoffs, and mechanism are prose (or a\nnumbered list), never a table, because they're an *ordering*, not a *lookup*.\n\n> \"An agent stops when the work looks done. Without a check it can run, 'looks done' is the\n> only signal available, and you become the verification loop: every mistake waits for you\n> to notice it.\"\n\nThree sentences of pure mechanism before any command is named. That's the job of prose.\n\n### Code: executable evidence, never bare\nCode can teach the action directly once the reader knows why they are taking it. Two hard rules:\n- **No bare block.** Every code block has a prose lead-in ending in a colon that says what\n  it does, and often a follow-up naming what to notice or what breaks.\n- **Comments are sparse.** Use one only when the code cannot express a constraint or intent.\n  Do not make comments narrate the example line by line.\n\nWhen placement matters, name the file. Use realistic names and values that expose the shape of the\ntask. Use tabs for language or platform variants, visual diffs for a progressive edit, focus or\ncollapse markers for the lines that matter, and a copy action for install commands. A reader must be\nable to tell whether a block is runnable, configuration, output, or a prompt before copying it.\nEvery fenced block declares a language. Use `text` for literal output or prompts rather than leaving\nthe label empty.\n\nThe escalation ladder inside a single block is a signature move. It goes abstract form, then a\nreal named instance, then the complication:\n```bash\n# Basic syntax\ndocs-tool integration add --transport http <name> <url>\n\n# Real example: Connect to Notion\ndocs-tool integration add --transport http notes https://api.example.com/integration\n\n# Example with Bearer token\ndocs-tool integration add --transport http secure-api https://api.example.com/integration \\\n  --header \"Authorization: Bearer your-token\"\n```\nPlaceholders (`<name>`, `YOUR_TOKEN`, `/path/to/x`) and real recognizable values (Notion,\nStripe) are **never mixed on one line**. The language tag sets the reader's action: `bash` = run in a\nshell, `json`/`yaml` = config, `text` = type this *to* the agent (a prompt). Keep that split.\n\n### Table: for comparison or lookup, where order doesn't matter\nTables compare several items across several attributes, index facts by key, define terms in context,\nor show before-and-after states. Column design mirrors the questions the reader is asking:\n`Scope | Loads in | Shared with team | Stored in`. Cell rule: **left column is a bare token\nin code font; right columns are sentences that scale with complexity.** A simple flag gets a\nfragment; a hard one gets a paragraph *in the same cell* until it earns its own section. The\n\"do this / not that\" two-column ✅/❌ table is the canonical way to show a rule at scale.\n\n### Callout: an off-ramp, never where a concept is first taught\nCallout type is semantic, not decorative:\n- **Warning** = this will hurt you (data, security, a silent violation of what you expect).\n  Name the wrong assumption explicitly: \"…even though 1 is the conventional Unix failure code.\"\n- **Note** = a true-but-easily-missed clarification or a scope boundary.\n- **Tip** = optional power-user extra, often a `Tips:` bullet list.\n\n### Architecture: structured text first, diagrams only when topology earns them\n\nFor documentation consumed by people and agents, one structured source owns the architecture. It\nmay be a numbered contract, nested list, state table, or machine-readable graph, state, sequence, or\nevent model. Record only the dimensions that change interpretation: applicable actors, inputs,\ntransformations, branches, outputs, unknown states, and authority boundaries. Empty slots are not\ncompleteness.\n\nRender a diagram when spatial shape or timing lets readers see a relationship that another form\nwould force them to reconstruct: fan-in or fan-out, cycles, retries, overlapping work, nesting, or\na genuinely nonlinear branch. Rendered pixels are never the canonical source. Pair them with an\naccessible projection that preserves the applicable relationships on a narrow screen, through a\nscreen reader, in search, and in a text-only context window. If the image merely puts boxes around\nan ordered list, delete it. Alt text identifies the image and its purpose; it does not carry the\nonly complete explanation.\n\nEvery Mermaid diagram has an adjacent text equivalent after the block. Start it with `Diagram:` so\nrenderers, screen readers, search, and agent projections can identify the canonical description.\n\n### Screenshots and video: teach recognition and interaction\nUse a screenshot when the reader must find, distinguish, or verify something visual. Crop unrelated\nUI, use a consistent viewport, annotate the target, remove personal or sensitive data, write useful\nalt text, and provide light and dark variants when appearance changes. A caption states what to\nnotice rather than repeating the image.\n\nEvery image has useful alternative text unless it is decorative. Mark a decorative Markdown image\nwith `<!-- sourcebound:decorative-image -->`; native HTML uses `alt=\"\" role=\"presentation\"`.\n\nVideo is optional. Use it only when motion is necessary to understand a multi-step interaction or\ntemporal UI behavior and the team can maintain it. Prefer a controllable video to an animated image.\nProvide a complete text path to the same outcome and make code legible at full screen. A person or\nagent must be able to complete and verify every documented task without watching it. Do not use media\nas decoration or as the only record of a fact.\n\n---\n\n## 2. Voice at the sentence level\n\n- **Second person + imperative for the reader's actions.** \"Open your terminal.\" \"Set to\n  `true` to disable.\" Not \"one can\" or \"users should.\"\n- **Name the system as an actor** so behavior reads as fact, not promise: \"The tool skips\n  that server and reports the error.\" Behavior is stated, not sold, which is why the docs\n  never read as marketing.\n- **Every clause adds information.** Split a sentence when its claims need separate evidence or\n  differ in scope. Keep tightly coupled cause and effect together.\n- **Plain, concrete verbs.** Things fill, skip, block, load, collide. Never \"leverage\", \"utilize\", \"seamlessly\", \"powerful\", \"simply\", or \"comprehensive\". <!-- slop-ok: naming banned booster words as negative examples -->\n- **State facts without hedging.** \"The tool always asks for permission before modifying\n  files\" is absolute, not \"usually.\" When advice is *genuinely* situational, mark the\n  uncertainty explicitly (\"Sometimes you *should* let context accumulate…\") rather than blur it.\n- **Contractions are fine** (\"you'll\", \"won't\", \"let's\"); the register is a helpful senior\n  colleague, not a spec.\n- **Use present tense and active voice.** Use future tense only for behavior that has not happened.\n  Passive voice is useful only when the actor is unknown or irrelevant.\n- **Remove trivializers.** Words such as \"easy\", \"obvious\", and \"just\" dismiss the reader's\n  difficulty. State the action and its prerequisites instead. <!-- slop-ok -->\n- **Use sentence case for headings, American English, and the Oxford comma.** Spell out zero through\n  nine; use numerals from 10 onward and for percentages or technical values.\n- **Format interface paths consistently.** Bold control labels and write nested paths as\n  **Parent > Child > Control**. Reserve bold for semantic labels, definitions, and UI controls,\n  not general emphasis.\n- **Link the first meaningful mention.** Use descriptive link text, point to the exact destination,\n  and deep-link into the product when the reader's next action happens there. Never use \"click here\".\n\n### Whimsy: give precision a pulse\n\nPrecise does not mean bloodless. Dry wit, a physical metaphor, or a lightly playful example can\nmake a mechanism easier to remember. That personality is part of the teaching, not frosting spread\nacross the page.\n\n- **Personality has a budget.** Overview, conceptual, and tutorial pages get at least one\n  subject-derived memorable element unless the entire topic sits in a literal zone. Spend at most\n  one flourish in a conceptual section. A page does not owe the reader a joke.\n- **Earn the whimsy from the mechanism.** A metaphor must preserve how the system works. \"The cache\n  has not developed opinions; two configuration layers disagree\" earns its dry aside by naming the\n  real failure immediately. A generic quip teaches nothing.\n- **Give examples a small, coherent world.** Prefer plausible names with a little character, such as\n  Acorn Bakery or Moonbase Support, over `foo`, `test123`, and a different joke in every block. Keep\n  runnable commands and security-sensitive values literal.\n- **Keep the searchable noun in playful headings.** \"Retries: when the queue refuses to take a\n  hint\" is findable. \"Here we go again\" is not.\n- **Let visuals carry character only when the motif explains the system.** A tether can represent a\n  source binding; a decorative mascot cannot. Preserve high contrast, useful alt text, and the\n  adjacent structured contract.\n\nCommands, configuration, error messages, repair steps, security and privacy boundaries,\naccessibility text, and API or option reference are literal zones. Do not put wit between a reader\nand an exact action, failure, or fact. Never use sarcasm at the reader, stacked puns, meme or\npop-culture references, emoji decoration, or anthropomorphism that invents agency.\n\nRun two judgment checks. The **truth test** asks whether the source or mechanism supports the\nmetaphor. The **deletion test** removes the flourish and confirms that the technical claim, warning,\nand next action remain complete. If either test fails, cut it.\n\n---\n\n## 3. How to explain something technical simply (the actual techniques)\n\nThe bar: a competent reader who has never seen this system grasps what it is and does from the\nfirst screen. The first sentence plainly names its category (\"X is a Y that does A, B, C\").\nGround each new term on first use or cut it, and give each sentence one claim. The\nmeasure is a blind read: hand the doc to a reader with no prior context and check whether they can\nstate back what the system is. The docs hit that bar with specific, repeatable moves:\n\n### Define the subject, then state the BLUF purpose contract\n\nDefinition and purpose are separate reader contracts. An ontological definition names what category\nthe subject belongs to: \"X is a Y.\" A purpose contract states who should continue, what problem the\npage addresses, and what the reader can do afterward. A capability list or value proposition can\nanswer what a system does while leaving its category ambiguous, so neither substitutes for a\ndefinition.\n\nEvery product, system, or concept overview opens with a plain category definition before explaining\nvalue or mechanism. Name the narrowest category the sources support, then add the distinguishing\nboundary a reader needs. \"QueueKit is a Python task queue that stores jobs in PostgreSQL\" defines a\ncategory and boundary. \"QueueKit processes jobs quickly\" states behavior but never says what it is.\nProcedural pages whose subject is already established link to its canonical definition and open with\nthe purpose contract instead of repeating it.\n\nEvery standalone overview, concept, tutorial, and task page opens with the documentation equivalent\nof a function contract. State the bottom line before the explanation so the wrong reader can leave\nand the right reader knows what the page will change for them. A reference opens with scope and\nauthority. An architecture record, plan, or evidence record opens with status and time horizon. An\nagent procedure opens with typed identity and execution constraints. A template adds no reader\npreamble because its bytes are product input.\n\n| Contract slot | The opener answers |\n| --- | --- |\n| Precondition | Who this is for and when it applies |\n| Job | What problem leaves the reader stuck without this page |\n| Postcondition | What the reader can do after reading |\n\nKeep the contract falsifiable and true to the code. A title restatement adds no contract. A feature\nlist describes the implementation instead of the reader's problem. Booster prose cannot be checked.\nA scope claim the page or product does not deliver is documentation drift.\n\nFor applicable, registered reader pages, the deterministic floor checks that one purpose block\nexists, appears before body content, and does not restate the H1. A reviewer checks whether an\noverview names a true category and whether the purpose contract names who should read, what problem\nthey face, and what they can do afterward without overselling the tool. Category truth cannot be\ninferred from sentence shape: \"X is a platform\" passes a regex and can still be false. A mechanical\npass never substitutes for that truth check.\n\n### Use repeatable explanation techniques\n\n1. **Open with a definition, then the one constraint that explains everything downstream.**\n   Best-practices names it once (\"The context window fills up fast, and performance\n   degrades as it fills\") and refers back to it for the rest of the page. Find your page's\n   single governing constraint and name it early.\n2. **Restate the mechanism as a plain cause-and-effect chain with the reader as the actor,\n   *then* show code.** \"When an event fires and a matcher matches, the tool passes JSON to\n   your hook handler… Your handler can then inspect the input, take action, and return a decision.\"\n3. **Hand over a testable heuristic instead of an abstract rule.** \"For each line, ask: 'Would\n   removing this cause the agent to make mistakes?' If not, cut it.\" A question the reader can run\n   beats a principle they have to interpret.\n4. **Teach terms in use, not in a glossary.** New terms (\"matcher\", \"scope\") first appear\n   inside a working sentence that makes their meaning obvious from context.\n5. **Ground the abstract in a physical metaphor.** \"Before they touch disk\", \"so the edits\n   don't collide\", \"keep your context clean.\"\n6. **Lead a conceptual section with a one-line takeaway, then earn it** in the prose that follows.\n\n---\n\n## 4. \"Don't do this\" and gotchas\n\n- **Every \"don't\" ships with its \"instead.\"** \"'Use 2-space indentation' instead of 'Format\n  code properly.'\" Never state a prohibition alone.\n- **A warning states the failure's *mechanism*, not just its existence.** The reader is\n  trusted to generalize. \"JSON output is only processed on exit 0. If you exit 2, any JSON is\n  ignored.\"\n- **Tier by severity:** reasoned platform gotchas stay inline mid-paragraph; the non-obvious\n  thing that silently bites goes in a `Warning`; recurring behavioral mistakes get *named* and\n  collected (\"The kitchen sink session\", \"The over-specified agent instructions\") with a `Fix:` under each.\n\n---\n\n## 5. Page shape by genre\n\n\n**Overview** (decide): plain definition and value → supported environments and essential capabilities\n→ visual model where useful → routes to setup, concepts, and common jobs. It answers what this is,\nwhether it fits the reader's stack, and where to start.\n\n**Getting started** (first outcome): prerequisites shared before any platform branches → minimal\ninstallation → one useful result → explicit verification → next task. Exclude advanced configuration.\n\n**Start here** (adoption syllabus): visible milestones → required, recommended, and optional work →\nthe goal of each milestone → links to the focused procedure → next useful outcome. Progress markers\nreduce abandonment; they are not decoration.\n\n**Tutorial** (linear learning): payoff and prerequisites → imperative step spine → each step combines\nonly the media needed to act → observable result → next experiment or related guide. State a time cost\nonly when it is grounded.\n\n**Conceptual** (mental model): definition → the constraint or problem it explains → relationships,\ndata flow, or terms → consequences for the reader. Use diagrams for shape and tables for definitions.\nDo not force an instruction into a concept page.\n\n**Guide** (one job): outcome-shaped title → brief applicability and prerequisites → practical steps →\nverification → next related job. Name the job the reader is doing, not the feature they happen to use.\n\n**Troubleshooting** (recover): searchable symptom → likely cause → diagnostic → repair → expected\nresult → escalation. When several causes are possible, expose the decision path. Put setup off-ramps\nfirst and escalation last.\n\n**Reference** (lookup): one-line descriptor → minimal context for precedence or scope → generated or\nstructured entries → examples where they resolve ambiguity. Order by the reader's journey unless it\nis a pure alphabetic registry. Generate signatures, parameters, schemas, and defaults from the source\nthat defines them; hand-write only the context needed to use them correctly.\n\n**Safety, privacy, or cost controls** (choose a boundary): state what is protected, where the control\nexecutes, and what remains outside it → order options from least to most restrictive → name defaults,\ninheritance, and overrides → show how to verify the boundary.\n\n**Universal:** teach through **orient → act → observe → verify → extend**, omitting verbs the genre\ndoes not need. Order sections by the reader's journey, not the alphabet except in a pure registry.\nLink outward rather than expanding a second job inline. Keep version notes beside the claim they\nmodify; never add a changelog section to current reference.\n\n---\n\n## 6. Beyond the single doc: does it earn its existence?\n\nThe rules above make one doc good. These decide whether a doc should exist, how long it may\nbe, and whether its content already lives elsewhere. This is the level most prose fails at: a\ncorpus of individually-clean docs still sprawls. Each rule below is a check a reviewer can run.\n\n- **A record must earn its surface, but its filename does not decide.** Ephemeral worktree state,\n  branch ownership, or task accounting belongs in git history, a PR, or an issue. A package-owned\n  review or incident record may be durable evidence. The same holds for a longitudinal study or\n  live plan. Preserve the record until its owner and time horizon prove it is exhaust. A scanner may\n  flag the ambiguity; it must not move or delete the file.\n- **Match the document to its real reader.** A published guide addresses a person doing its task.\n  An agent skill or prompt legitimately addresses an agent and may use imperative execution\n  constraints, typed frontmatter, and deliberate repetition. Do not rewrite an executable agent\n  procedure into a generic human guide. Do not disguise a branch handoff as durable agent\n  documentation.\n- **One canonical home per fact.** A fact shared by a family of docs lives in exactly one doc;\n  siblings cite it and state only their own deviations. (Same invariant as the second brain:\n  link, never copy.) N sibling pages each re-deriving one shared spec is the tell.\n- **Reference states current truth; provenance goes in a changelog.** Verification receipts,\n  deltas from a prior baseline, and `(Program N)` / `(Wave N)` tags do not belong inside a\n  reference doc. Test: if a passage would be equally true with its history deleted, delete the\n  history.\n- **No sentence restates a prior one without a local reason.** This is the highest-yield concision\n  check for explanatory prose. Repeat a safety boundary at each irreversible action when distance\n  would make the procedure easier to misuse; preserve the constraint, not merely the wording.\n- **Each section leads with its takeaway in one sentence, then supports it or is cut.** A\n  section whose takeaway is \"see the table\" means the prose should *be* the table.\n- **Length prompts a depth review.** README pages over 90 lines and guides over 150 lines receive an\n  advisory. A section over 40 lines receives the same review. A line count cannot prove that a\n  second job exists. Move one behind a link when it does; keep a complete safety sequence,\n  diagnostic chain, or lookup surface together when splitting would make the page harder to use.\n  A length allowance is a subtraction receipt naming what moved, split, or was cut; breadth alone\n  and \"keeps everything together\" are not reasons.\n- **Prefer the denser medium.** An inline 3-to-7-item enumeration (vendor classes, data\n  sources, tested dimensions) is a table or list, not a sentence.\n\n### Put the point, action, and proof on the first screen\n\nThe first 15 lines of a reader-facing page contain three things: the marked purpose prose, the\nprimary action, and one proof. The action is a runnable command or a bold route to the next task.\nThe proof is a receipt or result link, a badge, or a verification command. A reader who stops there\ncan answer what this is, what to do first, and how to know it worked.\n\nThe README is a hub, not a warehouse. It owns the point, first action, proof, and a routing table.\nReference facts, schemas, and configuration examples longer than 12 lines live on reference pages.\nAn explanatory section over 80 words links to the deeper page that owns its detail. Link to the\ncanonical home instead of making the overview carry both the decision and its appendix.\n\nUse this routing-table shape:\n\n| If you need to... | Start with | You will leave with... |\n| --- | --- | --- |\n| Reach a first verified result | A focused tutorial | A working baseline and its proof |\n| Look up exact behavior | The reference | The current command, schema, or boundary |\n\n### Keep the register concrete\n\nThe deterministic register floor catches five repeatable failures:\n\n<!-- sourcebound:yield rule=\"nominalization-density\" to=\"truth-honesty\"\n     reason=\"The rule definition must name nominalization and its abstraction suffixes\" -->\n1. **Nominalization density.** A reader-facing sentence with three or more abstraction-suffix\n   tokens (`-tion`, `-sion`, `-ment`, `-ance`, `-ence`, `-ivity`) fails after the narrow allowlist\n   for `documentation`, `application`, `section`, and `configuration`.\n<!-- sourcebound:yield rule=\"nominalization-density\" to=\"truth-honesty\"\n     reason=\"The rule definition must preserve its exact sentence-variance terms\" -->\n2. **Sentence variance.** A paragraph of at least three sentences fails when every sentence is\n   15-35 words. Give the reader one short beat.\n<!-- sourcebound:yield rule=\"nominalization-density\" to=\"truth-honesty\"\n     reason=\"The rule definition must preserve its exact assurance and execution terms\" -->\n3. **Assurance deduplication.** Each authority or execution boundary has one canonical home.\n   Overview pages link to it instead of repeating it.\n<!-- sourcebound:yield rule=\"significance-narration\" to=\"truth-honesty\"\n     reason=\"The rule definition must quote each phrase that it rejects\" -->\n4. **Significance narration.** Cut \"exactly the\", \"the very\", \"this demonstrates\",\n   \"deliberately\", \"is itself\", and \"which is precisely\" when the page praises its own system.\n   State the consequence instead.\n5. **Qualifier density.** Overview and learning prose gets at most two `may`, `only`, `unless`,\n   or `except` guards in one sentence. Limits and security sections are exempt because guarding is\n   their job.\n\nThese diagnostics do not license flat prose. The constitution decides which rule wins. Each rule\nships with a collision fixture that pins that choice.\n\n### Give the corpus a navigation contract\n\nReaders should be able to predict where a fact lives. Use a stable taxonomy such as overview,\ngetting started, concepts, guides, troubleshooting, and reference. A product area does not need every\ncategory, but a label must keep the same reader intent everywhere it appears. Navigation names the\nreader's destination, not the repository's internal architecture.\n\nTreat each path as a contract:\n\n| Path | Reader question |\n| --- | --- |\n| Overview | What is this, does it fit, and where do I begin? |\n| Getting started | What is the shortest verified path to a useful result? |\n| Concepts | Why does the system behave this way? |\n| Guides | How do I complete this job? |\n| Troubleshooting | How do I recover from this symptom? |\n| Reference | What is the exact current value, shape, or behavior? |\n\n### One source, purpose-built projections\n\n\nThe documentation corpus is a maintained teaching system, not a pile of readable files. Encode\nmeaning once, then project it for the audience's task. A human surface may use progressive\ndisclosure, diagrams, and narrative. An agent surface may use stable identifiers, typed metadata,\ncompact context bundles, and explicit relationships. Neither projection may invent a second source\nof truth. When both audiences need an architecture, its canonical source may be structured prose or\na machine-readable model; a rendered image is one projection of it.\n\nCanonical content should carry the fields each projection needs: what it is, where it applies, who\ncontrols it, which release it describes, what must exist first, what it changes, how to check it,\nand where related concepts, tasks, choices, and definitions live. Keep those fields only\nwhen they change behavior; metadata without a consumer is another form of documentation theater.\n\nTeach every consequential surface at three levels:\n\n1. **Model:** name the entities, ownership, lifecycle, state transitions, trust boundaries, and\n   invariants that let a reader reason beyond the example.\n2. **Procedure:** state prerequisites, ordered actions, observable intermediate states, success,\n   failure handling, cleanup, rollback, and retry behavior.\n3. **Judgment:** state when to choose the path, when not to, what evidence changes the choice, and\n   when the documentation is insufficient and the reader must abstain or escalate.\n\nStructure is semantic. Label content as concept, tutorial, task, lookup, troubleshooting, design\nchoice, upgrade, policy, or ADR when tooling relies on that label. A high-consequence task\nalso states permissions, reversibility, side effects, blast radius, approval, and rollback. Agents\nmust not infer authorization from capability.\n\nDesign retrieval units to survive extraction. Each unit names its system, version or applicability,\nsubject, normative status, and authority without dangling pronouns. Stable anchors let a person,\nagent, test, or support record cite the exact governing rule. Controlled terminology preserves\nentity boundaries; preferred terms and deprecated synonyms are part of the contract.\n\nExamples are executable lessons. Reuse tested assets, pin their environment, show expected output,\nand include the failure or counterexample that defines the negative boundary. Documentation tests\ntherefore ask readers to choose the right path, supply parameters, meet preconditions, recover,\nstop when needed, and cite the governing rule. Schema, spelling, and link checks cannot prove that\nthe material teaches correct behavior.\n\nAuthority and uncertainty stay visible. Distinguish requirements, guidance, examples, history,\nexperiments, generated reference, and deprecated behavior. State non-guarantees and conflicts, and\ngive an escalation path for missing policy. A correct answer from the wrong version or a tutorial\ntreated as normative is still a documentation failure.\n\n### Keep facts next to the behavior that owns them\n\nPlace a fact's canonical source as close as practical to the code, schema, configuration, or product\nsurface that defines it. Render other surfaces from that source. A web guide, in-product onboarding,\ncommand help, and an agent projection may differ in presentation, but they must not independently\nrestate shared facts.\n\nGenerated reference and hand-written explanation are complements. Generate signatures, options,\ndefaults, and schemas. Hand-write motivation, mental models, examples, failure modes, and the links\nbetween tasks. When generation cannot prove a prose claim, label that boundary instead of implying\nthat inventory coverage validates the prose.\n\n### Enforce rules at the narrowest honest layer\n\nLayer checks by scope and severity. Corpus rules inspect ownership and duplication. Page rules inspect\nstructure and links. Sentence rules inspect terms, voice, and mechanics. Errors block demonstrably\nwrong or unsafe output; warnings flag likely defects; suggestions expose judgment calls.\n\nEvery deterministic rule needs a positive fixture, a negative fixture, and a documented repair.\nClassify exceptions by kind, such as proper names, case-sensitive technology terms, or accepted\njargon. Do not hide unrelated failures behind a blanket suppression. Use a model or human to judge\ntruth, usefulness, and pedagogy, not to rediscover punctuation that a linter can identify exactly.\n\n### Assign ownership and learn from failed tasks\n\nThe owner closest to a fact writes or approves its current truth. The documentation-system owner\nmaintains structure, tooling, navigation, and the reading experience. Every published area names an\nowner so stale pages have a destination.\n\nPrioritize changes from observed reader failures: repeated support questions, failed setup attempts,\nunhelpful-page feedback, missing search results, and tasks an agent cannot complete from published\nmaterial. Record the evidence outside the reader-facing page. Repair the canonical source, regenerate\nits projections, and rerun the failed task.\n\nA qualitative review issue becomes two test candidates before it becomes work: one candidate names\nthe documentation change and how a reader or checker would prove it, while the other names the\nproduct mechanism and its regression fixture. Keep both assessment-only until the observation is\nreproduced. A documentation caveat cannot close a missing mechanism, and a proposed lint rule cannot\nturn an editorial opinion into gate authority.\n\n### What only judgment can check (the honest seam)\n\n`sourcebound audit` sees document roles, names, structure, lengths, links, token overlap, registered\nprose tells, and exact accepted debt. Its role classifier is evidence for applicability, not proof\nof editorial intent. Patterns cannot decide several corpus and teaching rules. A reviewer or an\nadvisory judge owns them. Each rule is stated so a human can run it today; none is faked into a\nbrittle regex, because a pattern pretending to judge purpose or pedagogy misfires in both\ndirections.\n\n- **An executed or superseded plan is process exhaust; a live plan is a reference.** The\n  filename does not separate them: `EVAL_PLAN.md` is an active landing page, while a\n  `RESEED_PLAN.md` whose first line reads \"EXECUTED by Program 9\" is history. Read the status\n  line, not the name. Instead of a filename rule, an LLM-judge reads the opening lines and asks\n  whether the plan's work is finished.\n- **A doc about agent operation is not a doc written for a future agent.** An agent profile\n  legitimately says \"worktree\" and \"DoD table\" because that is its subject; the\n  vocabulary-density check flags it anyway. Instead of raising the threshold, judge the second\n  person: is the reader a human learning the system, or the next executor picking up a branch.\n- **Each section leads with its takeaway.** A section whose first sentence is \"see the table\"\n  buries its point, and no token pattern detects a missing lead. Instead of a mechanical check,\n  an LLM-judge scoring the first sentence of each section is where this one slots in.\n\n**A rule enforced mechanically is a floor, not a finish.** This document's own no-em-dash rule,\napplied by find-replace, once turned every em dash into a double hyphen: rule-compliant, and a\ntypewriter-ism in the one file that cannot afford one. The repair rephrased each line by hand,\nchoosing a colon, a period, or a new structure according to the line's job. Only a reviewer can\nchoose. That is the same seam as the sentence gate and the three rules above:\na checker enforces the letter of a rule, but whether the result reads well is the judgment it\ncannot make. Read every mechanical pass as the floor you start from, never the standard you ship.\n\n---\n\n## 7. Grounding: the doc must be true to the code (and stay true)\n\nA doc can be perfectly voiced, well structured, and accessible and still be wrong, because the\ncode moved and the prose did not. The other tiers check how a doc reads; grounding checks whether\nit matches the system. It is the truth tier.\n\n- **Derive the factual spine from source; do not paraphrase it.** Capability lists, CLI flags,\n  config options, routes, counts, and version facts each have a source of truth in the code (a\n  registry, a signature, a test). Render them from that source. A human paraphrasing an old draft\n  is how a doc goes stale.\n- **A factual defect is fixed at the code, not in a better sentence.** When a doc misstates what\n  the system does, re-derive the claim from the code. Editing the prose is the wrong altitude.\n- **Verify a claim against its source, never against a commit message or narrative.** \"24 of 24\n  tests pass\" is checked by running the tests. A changelog entry comes from the code delta, not\n  from what a commit said it did.\n- **Bind a factual claim to its source so drift is detectable:** a generated region re-renders and\n  diffs, an accepted source-claim check compares bounded prose with static evidence, and a cited\n  symbol is checked to still exist. A command pin checks configured output and, when declared,\n  reader-facing prose under the configured anchor.\n- **State the honest boundary.** Grounding makes the derivable spine drift-proof. It does not make\n  the judgment prose (the why, the framing, the positioning) drift-proof; that stays a human or\n  advisory-review concern, never a silent gate. Claim \"the documented spine cannot silently\n  drift,\" never \"the doc can never be stale.\"\n\nThis tier is the newest, added after a real doc described a nine-action system as one that \"drafts\ncustomer emails.\" No amount of voice or structure work catches that; only grounding does.\n\n---\n\n## 8. Pre-publish checklist\n\n\nRun this against any doc before shipping. Each line is a fail/pass check.\n\n- [ ] In an overview, the first 15 lines contain the purpose, a primary action, and one proof;\n      other roles open with the information their reader needs first.\n- [ ] Review a README over 90 lines, a guide over 150 lines, or a section over 40 lines for a second\n      job. Split by reader job, but keep one complete safety, diagnostic, or lookup sequence intact.\n- [ ] The README routes decisions, first tasks, concepts, and lookup work through an\n      `If you need to... | Start with | You will leave with...` table.\n- [ ] Each explanatory section over 80 words links to the deeper page that owns its detail.\n- [ ] No reader-facing sentence crosses the nominalization, significance-narration, or scoped\n      qualifier-density thresholds.\n- [ ] Paragraph rhythm includes a short sentence when three or more sentences would otherwise all\n      land between 15 and 35 words.\n- [ ] Authority and execution assurances have one canonical home; overview pages link there.\n- [ ] A rule collision resolves by truth, grounding, budget, register, then warmth; any unavoidable\n      loss has an explicit yield naming the winning rule.\n- [ ] Every code block has a prose lead-in ending in `:` and (where useful) a follow-up.\n- [ ] Every fenced code block declares its language; literal output and prompts use `text`.\n- [ ] No table encodes precedence or an ordering rule; those are prose or numbered lists.\n- [ ] Every comparison table's columns are the reader's actual questions; ordered logic stays\n      in prose or numbered steps.\n- [ ] Every \"don't\" is paired with an \"instead\"; every warning states a *mechanism*.\n- [ ] Callouts are semantic (Warning = harm, Note = easily-missed, Tip = optional) and none\n      carries a concept's first explanation.\n- [ ] Placeholders and real values are never mixed on one line; language tags are correct\n      (`bash` vs `text` vs `json`).\n- [ ] Code examples are realistic and sparse in comments; filenames, diffs, focus, or tabs expose\n      placement and variants when needed.\n- [ ] Screenshots are cropped, scrubbed, annotated, captioned, and described; optional video has a\n      complete text path. Architecture has one structured source, records only applicable\n      dimensions, and remains usable without rendered pixels; a diagram appears only when topology\n      or temporal interaction adds information.\n- [ ] Every Mermaid diagram has an adjacent text equivalent beginning with `Diagram:`.\n- [ ] Every image has useful alternative text or an explicit decorative-image marker.\n- [ ] The page names its one governing constraint early.\n- [ ] No booster adjectives (`seamless`, `powerful`, `simply`, `comprehensive`, `leverage`, `utilize`). <!-- slop-ok: banned-word registry for the checklist -->\n- [ ] Every clause adds information; claims needing separate evidence are split; the system is named\n      as an actor; reader actions are imperative.\n- [ ] Every overview, conceptual, or tutorial page has at least one subject-derived memorable element\n      unless its topic is wholly literal; each flourish passes the truth and deletion tests.\n- [ ] Commands, configuration, errors, repair steps, security and privacy boundaries, accessibility\n      text, and reference facts stay literal; whimsy never carries a required fact or action.\n- [ ] Headings use sentence case; UI controls use semantic bold; link text names its destination.\n- [ ] Sections end by linking outward; version notes are inline at the claim.\n- [ ] The document's role is explicit in its structure, and every applied rule helps that role.\n- [ ] Ephemeral task state lives in git, PRs, or issues; durable evidence records and live plans\n      retain their declared owner, time horizon, and evidence boundary.\n- [ ] The audience matches the role: human task pages address people; executable agent procedures\n      preserve their runtime contract instead of imitating human prose.\n- [ ] No fact is restated across sibling docs; shared facts have one canonical home, cited.\n- [ ] The page fits the corpus navigation contract and its genre follows the reader's intended path.\n- [ ] Procedures include an observable result and verification; troubleshooting proceeds from\n      symptom through diagnosis and repair before escalation.\n- [ ] Generated reference comes from the defining source; hand-written prose supplies context rather\n      than copying signatures, schemas, defaults, or option lists.\n- [ ] Every deterministic rule has positive and negative fixtures, a repair, a severity, and a scoped\n      exception model.\n- [ ] No reference doc carries provenance, receipts, or baseline deltas; those go in a changelog.\n- [ ] No sentence restates a prior sentence without a local safety or execution reason; each\n      explanatory section leads with its takeaway.\n- [ ] Each standalone reader page names its job near the opening. Overview, tutorial, and task pages\n      over their budgets split only when the split preserves safety and lookup; references,\n      architecture records, evidence, agent procedures, and templates do not inherit those budgets.\n- [ ] Every factual claim (capabilities, flags, counts, routes) traces to a source in the code,\n      not to memory or an old draft.\n- [ ] For every product, system, or concept overview, the first screen defines what category the\n      subject belongs to with an ontological definition, not merely what it does; a reader with no\n      context could state it back.\n- [ ] Every overview, concept, tutorial, and task page opens with the applicable part of a BLUF\n      purpose contract: reader situation, consequential problem, and resulting capability are\n      explicit, falsifiable, and true to the code. References, evidence, agent procedures, and\n      templates use their role-specific opening instead of filler.\n- [ ] Purpose prose names the project-specific subject, operator, consequential failure, and\n      authority boundary; it does not use a stock sentence shared across unrelated projects.\n- [ ] Canonical meaning has purpose-built human and agent projections rather than separately\n      maintained copies; each projection identifies its authority and applicability.\n- [ ] Consequential tasks teach the model, procedure, and judgment boundary. They state permissions\n      and side effects, show how to verify and recover, and tell the reader when to stop or ask.\n- [ ] Executable examples and audience-task evaluations prove correct action and at least one\n      negative boundary; retrieval units remain intelligible outside their original page.\n",
+    "constraint": "Phrase only the supplied evidence and preserve its scope.",
+    "voice": {
+      "register": "helpful senior colleague",
+      "reader_actions": "second person and imperative",
+      "system_behavior": "name the system as an actor and state behavior as fact",
+      "sentence_shape": "split claims that need separate evidence or differ in scope",
+      "verbs": "plain and concrete",
+      "certainty": "direct facts; mark genuine uncertainty explicitly",
+      "contractions": "allowed"
+    },
+    "purpose_contract": {
+      "begin_marker": "<!-- sourcebound:purpose -->",
+      "end_marker": "<!-- sourcebound:end purpose -->",
+      "position": "first meaningful block after the H1",
+      "mechanical": [
+        "exactly one marked purpose block",
+        "purpose block precedes body content",
+        "purpose prose does not restate the H1"
+      ],
+      "judgment": [
+        "defines the project-specific subject and intended operator",
+        "names the consequential failure or decision the page addresses",
+        "states the authority boundary and a falsifiable resulting capability",
+        "uses authored language grounded in the implementation and cited sources"
+      ]
+    },
+    "precedence": [
+      "truth and honesty",
+      "grounding",
+      "reader budget",
+      "register",
+      "warmth"
+    ],
+    "exemplars": "# Register exemplars\n\nThese pairs anchor phrasing without granting a model authority over facts. The source supplies every\nfact. The after side changes only altitude, rhythm, emphasis, or warmth.\n\n## README hub: point, action, proof, route\n\nBefore:\n\n> sourcebound is a source-bound documentation engine and CLI for maintainers whose code changes\n> faster than its documentation. It identifies stale claims and provides a local, deterministic\n> path from source change to repaired, verified docs.\n>\n> Start here for the product map, runnable drift tutorial, real-repository postmortem, and\n> deterministic-boundary explanation.\n\nAfter:\n\n> sourcebound is a source-bound documentation engine and CLI for maintainers who need code and prose\n> to change together. It turns selected source facts into checked documentation, so stale claims\n> fail in local workflows and CI.\n>\n> Install sourcebound and catch your first stale claim. The final `sourcebound verify` command prints\n> a receipt with `\"ok\": true`.\n\nThe after side defines the product, gives one first action, and names the proof. A routing table then\nsends tutorials, command lookup, binding setup, and security questions to their canonical pages.\nMechanism and reference detail move deeper; they are not deleted.\n\n## Outcome before mechanism\n\nBefore: The system performs repository documentation validation through deterministic extraction and\ncomparison mechanisms.\n\nAfter: sourcebound fails the change when a bound claim no longer matches its source. Static extraction\nand comparison produce that result.\n\n## Concrete actors\n\nBefore: Documentation synchronization and projection regeneration provide consistency.\n\nAfter: `repair` updates the bound region. `project` then refreshes every projection that includes it.\n\n## Rhythm\n\nBefore: A stale sentence can remain plausible after its source changes, and reviewers can miss the\nresult during a busy change. A source binding records the relationship so the repository can check\nit again. A failing gate then identifies the claim that needs repair.\n\nAfter: A stale sentence can remain plausible after its source changes, and reviewers can miss it.\nBindings give that sentence a tripwire. The failing gate names the claim that needs repair.\n\n## Assurance once\n\nBefore: Deterministic code owns the facts here. Deterministic code also owns the final gate result.\n\nAfter: [The deterministic seam](../../../docs/learn/deep-dive-the-deterministic-seam.md) assigns fact,\nphrasing, and gate authority once.\n\n## Consequence instead of significance\n\nBefore: This demonstrates exactly the contract that makes the system trustworthy.\n\nAfter: The receipt names the source, derived digest, and gate result, so a reviewer can inspect each\npart.\n\n## Honest qualification\n\nBefore: The command may run only when declared, unless the host blocks it, except when a plugin adds\nanother boundary.\n\nAfter: The manifest must declare the command. Host isolation and plugin boundaries remain separate;\nthe security model owns those limits.\n\n## Earned warmth\n\nBefore: Drift is detected reliably.\n\nAfter: A stale README keeps a straight face. The binding gives it a tripwire.\n\n## Depth instead of deletion\n\nBefore: The README includes the complete schema, every option, all precedence rules, and the install\npath so the reader has one comprehensive page.\n\nAfter: The README gives the first verified path. The reference keeps the schema and precedence rules\none click deeper.\n",
+    "exemplars_sha256": "d4fcaa14f3da2f3b1fbe9d525812ea5adf975d89b982392748f194fa5da3a26a"
+  },
+  "pack_sha256": "97f930fcf832ec89d56d712f28125206562cb84eec06a2502a832705917f2c83"
+}

clean_docs/standards/exemplars.md

@@ -0,0 +1,87 @@
+# Register exemplars
+
+These pairs anchor phrasing without granting a model authority over facts. The source supplies every
+fact. The after side changes only altitude, rhythm, emphasis, or warmth.
+
+## README hub: point, action, proof, route
+
+Before:
+
+> sourcebound is a source-bound documentation engine and CLI for maintainers whose code changes
+> faster than its documentation. It identifies stale claims and provides a local, deterministic
+> path from source change to repaired, verified docs.
+>
+> Start here for the product map, runnable drift tutorial, real-repository postmortem, and
+> deterministic-boundary explanation.
+
+After:
+
+> sourcebound is a source-bound documentation engine and CLI for maintainers who need code and prose
+> to change together. It turns selected source facts into checked documentation, so stale claims
+> fail in local workflows and CI.
+>
+> Install sourcebound and catch your first stale claim. The final `sourcebound verify` command prints
+> a receipt with `"ok": true`.
+
+The after side defines the product, gives one first action, and names the proof. A routing table then
+sends tutorials, command lookup, binding setup, and security questions to their canonical pages.
+Mechanism and reference detail move deeper; they are not deleted.
+
+## Outcome before mechanism
+
+Before: The system performs repository documentation validation through deterministic extraction and
+comparison mechanisms.
+
+After: sourcebound fails the change when a bound claim no longer matches its source. Static extraction
+and comparison produce that result.
+
+## Concrete actors
+
+Before: Documentation synchronization and projection regeneration provide consistency.
+
+After: `repair` updates the bound region. `project` then refreshes every projection that includes it.
+
+## Rhythm
+
+Before: A stale sentence can remain plausible after its source changes, and reviewers can miss the
+result during a busy change. A source binding records the relationship so the repository can check
+it again. A failing gate then identifies the claim that needs repair.
+
+After: A stale sentence can remain plausible after its source changes, and reviewers can miss it.
+Bindings give that sentence a tripwire. The failing gate names the claim that needs repair.
+
+## Assurance once
+
+Before: Deterministic code owns the facts here. Deterministic code also owns the final gate result.
+
+After: [The deterministic seam](../../../docs/learn/deep-dive-the-deterministic-seam.md) assigns fact,
+phrasing, and gate authority once.
+
+## Consequence instead of significance
+
+Before: This demonstrates exactly the contract that makes the system trustworthy.
+
+After: The receipt names the source, derived digest, and gate result, so a reviewer can inspect each
+part.
+
+## Honest qualification
+
+Before: The command may run only when declared, unless the host blocks it, except when a plugin adds
+another boundary.
+
+After: The manifest must declare the command. Host isolation and plugin boundaries remain separate;
+the security model owns those limits.
+
+## Earned warmth
+
+Before: Drift is detected reliably.
+
+After: A stale README keeps a straight face. The binding gives it a tripwire.
+
+## Depth instead of deletion
+
+Before: The README includes the complete schema, every option, all precedence rules, and the install
+path so the reader has one comprehensive page.
+
+After: The README gives the first verified path. The reference keeps the schema and precedence rules
+one click deeper.

clean_docs/standards/v0-migrations.json

@@ -0,0 +1,26 @@
+{
+  "version": 1,
+  "baseline": "docs/archive/v0/originals",
+  "differences": [
+    {
+      "rule": "archive-surface",
+      "change": "Directory scans skip any archive path segment; explicit file scans still inspect it.",
+      "reason": "Archived history is outside the reader-facing documentation surface."
+    },
+    {
+      "rule": "audience-if-then",
+      "change": "IF/THEN is not an audience signal.",
+      "reason": "Decision records use the token as reader-facing technical vocabulary."
+    },
+    {
+      "rule": "provenance-byte-identical",
+      "change": "byte-identical is not a provenance signal.",
+      "reason": "The phrase describes technical data fidelity."
+    },
+    {
+      "rule": "reasoned-allowance",
+      "change": "The audit command accepts named, reasoned suppressions while the compatibility linter preserves Version 0 output.",
+      "reason": "The canonical standard requires justified long documents and sections instead of unconditional rejection."
+    }
+  ]
+}

clean_docs/symbols.py

@@ -0,0 +1,47 @@
+from __future__ import annotations
+
+import ast
+import hashlib
+
+from clean_docs.errors import ExtractionError
+from clean_docs.models import EvidenceValue, Provenance, SymbolBinding
+from clean_docs.snapshot import RepositorySnapshot
+
+
+def resolve_symbol(snapshot: RepositorySnapshot, binding: SymbolBinding) -> EvidenceValue:
+    text = snapshot.read_text(binding.source.path)
+    locator = binding.source.symbol or binding.source.path.as_posix()
+    if binding.source.symbol is not None:
+        try:
+            tree = ast.parse(text, filename=binding.source.path.as_posix())
+        except SyntaxError as exc:
+            raise ExtractionError(f"cannot parse {binding.source.path}: {exc}") from exc
+        names = {
+            node.name
+            for node in ast.walk(tree)
+            if isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef))
+        }
+        names.update(
+            target.id
+            for node in ast.walk(tree)
+            for target in (
+                node.targets if isinstance(node, ast.Assign) else [node.target]
+                if isinstance(node, ast.AnnAssign)
+                else []
+            )
+            if isinstance(target, ast.Name)
+        )
+        if binding.source.symbol not in names:
+            raise ExtractionError(f"symbol not found: {binding.source.path}:{binding.source.symbol}")
+    digest = hashlib.sha256(locator.encode()).hexdigest()
+    return EvidenceValue(
+        kind="symbol",
+        value=locator,
+        provenance=Provenance(
+            ref=snapshot.label,
+            path=binding.source.path.as_posix(),
+            locator=locator,
+            extractor="symbol@1",
+            digest=digest,
+        ),
+    )