constant-docs 0.4.0__py3-none-any.whl

constant_docs/kinds.py

@@ -0,0 +1,304 @@
+"""Document kinds — what shape a document is, and how a regeneration writes it.
+
+A kind decides four things: the sections a body must carry, the OKF ``type``
+the document declares, the prompt a generator is handed, and whether a
+regeneration replaces the body or appends an entry to it.
+
+Seven kinds ship. Any of them may be redeclared in configuration, and new ones
+declared alongside. ``module`` is the default, so a configuration that has
+never heard of kinds loads unchanged.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Literal, get_args
+
+from constant_docs.document import FRONTMATTER_STYLES, YAML_FRONTMATTER
+
+Mode = Literal["replace", "append"]
+MODES: tuple[str, ...] = get_args(Mode)
+
+_PROMPT_DIR = Path(__file__).parent / "prompts"
+# Authoring conventions for documents this tool does not track. A README and a
+# quickstart are written once and revised by judgement — what to lead with,
+# what to leave out, who the reader is — so making them tracked documents would
+# regenerate prose whose quality never depended on the code. The conventions
+# are still worth shipping, on the same shelf as the per-kind prompts.
+#
+# A skill makes a document good. It does not make it fresh: nothing fires when
+# the CLI moves underneath a README written six months ago. That is what the
+# CLI reference is for, and why these sit beside it rather than replacing it.
+_GUIDE_DIR = Path(__file__).parent / "guides"
+# One home for the vocabulary rules every generated document obeys. Appended to
+# the built-in prompts rather than written into each of the seven, because
+# seven copies of a house style is the drift this tool exists to prevent: the
+# copy nobody edits is the one that goes stale, and here that failure is silent
+# because a prompt has no source to fall behind.
+#
+# A project naming its own prompt file gets exactly what it wrote. Carrying
+# your own conventions without forking the tool has to mean your conventions,
+# or the escape hatch is not one.
+_HOUSE_STYLE = Path(__file__).parent / "house-style.md"
+_BUILTIN_PREFIX = "builtin:"
+
+
+class KindError(Exception):
+    """A kind is declared wrongly, or its prompt cannot be resolved."""
+
+
+# The content checks a kind's documents can be subject to. Named here so a
+# kind can carry one as data; `checks` implements them.
+ARCHITECTURE_CHECK = "architecture"
+ERRORS_CHECK = "errors"
+CHECKS = (ARCHITECTURE_CHECK, ERRORS_CHECK)
+
+
+@dataclass(frozen=True)
+class Kind:
+    """One document shape."""
+
+    name: str
+    sections: list[str]  # H2 headings, as written in configuration: "## Purpose"
+    mode: Mode
+    prompt: str  # "builtin:<name>", or a repository-relative path
+    type: str  # the OKF `type` value this kind's documents declare
+    # The content check these documents must pass, if any.
+    #
+    # A field rather than the kind's *name* compared in three places. The name
+    # was the earlier reading and it made the check stop following the kind: a
+    # project declaring `house-architecture` with `prompt: builtin:architecture`
+    # got the prompt and the type and silently lost the diagram guard, in both
+    # the writer and the reader, while `verify` went on passing.
+    check: str | None = None
+    # How the tool's block is written into this kind's documents: as YAML
+    # frontmatter, or as an HTML comment a Markdown host renders as nothing.
+    #
+    # A field on the kind rather than a rule inferred from where the document
+    # lands. Switching a file's format because it moved is the kind of thing
+    # that surprises somebody a year later, and the two forms are not equally
+    # good: YAML frontmatter is what makes the docs tree an Open Knowledge
+    # Format bundle, so it stays the default and the comment form is asked
+    # for by name.
+    frontmatter: str = YAML_FRONTMATTER
+
+
+# The shipped kinds. Each carries defaults rather than being abstract, so
+# `kind: spec` works without anyone writing a prompt first; a project that
+# wants different sections redeclares the kind in configuration.
+#
+# Two kinds have their *content* checked rather than only hashed, and both
+# checks live in `checks`. An `architecture` diagram may name only modules the
+# configuration declares. An `errors` catalogue must agree with the source in
+# both directions: every message raised is listed, and every entry listed is
+# still raised.
+BUILTIN_KINDS: dict[str, Kind] = {
+    "module": Kind(
+        name="module",
+        sections=["## Purpose", "## Correctness pillars", "## Known failure modes"],
+        mode="replace",
+        prompt="builtin:module",
+        type="Code Module",
+    ),
+    "spec": Kind(
+        name="spec",
+        sections=["## Purpose", "## Design decisions", "## Acceptance criteria"],
+        mode="replace",
+        prompt="builtin:spec",
+        type="Specification",
+    ),
+    "architecture": Kind(
+        name="architecture",
+        sections=["## The parts", "## How they meet", "## Boundaries"],
+        mode="replace",
+        prompt="builtin:architecture",
+        type="Architecture",
+        check=ARCHITECTURE_CHECK,
+    ),
+    "errors": Kind(
+        name="errors",
+        sections=["## Purpose", "## The catalogue", "## What is not an error"],
+        mode="replace",
+        prompt="builtin:errors",
+        type="Error Catalogue",
+        check=ERRORS_CHECK,
+    ),
+    "config-reference": Kind(
+        name="config-reference",
+        sections=["## Purpose", "## Keys", "## What is refused"],
+        mode="replace",
+        prompt="builtin:config-reference",
+        type="Configuration Reference",
+    ),
+    "cli-reference": Kind(
+        name="cli-reference",
+        sections=["## Purpose", "## Commands", "## Flags"],
+        mode="replace",
+        prompt="builtin:cli-reference",
+        type="CLI Reference",
+    ),
+    "log": Kind(
+        name="log",
+        sections=["## Entries"],
+        mode="append",
+        prompt="builtin:log",
+        type="Log",
+    ),
+}
+
+DEFAULT_KIND = "module"
+
+
+def load_kinds(raw: Any) -> dict[str, Kind]:
+    """Merge a configuration's ``kinds`` block over the shipped defaults.
+
+    Raises :exc:`KindError` naming the offending kind. The caller turns that
+    into a `ConfigError`, because from the outside this is a configuration
+    problem and criterion 21 requires the offending key to be named.
+    """
+    kinds = dict(BUILTIN_KINDS)
+    if raw is None:
+        return kinds
+    if not isinstance(raw, dict):
+        raise KindError(
+            f"'kinds' must be a mapping of kind name to declaration, "
+            f"got {type(raw).__name__}"
+        )
+
+    for name, decl in raw.items():
+        name = str(name)
+        if not isinstance(decl, dict):
+            raise KindError(
+                f"Kind {name!r} must be a mapping with 'sections' and 'mode', "
+                f"got {type(decl).__name__}"
+            )
+
+        base = kinds.get(name)
+
+        sections_raw = decl.get("sections", base.sections if base else None)
+        if not isinstance(sections_raw, list) or not sections_raw:
+            raise KindError(
+                f"Kind {name!r} needs 'sections': a non-empty list of H2 "
+                f"headings, e.g. ['## Purpose', '## Entries']"
+            )
+        sections = [_normalise_heading(name, s) for s in sections_raw]
+
+        mode = str(decl.get("mode", base.mode if base else "replace"))
+        if mode not in MODES:
+            raise KindError(
+                f"Kind {name!r} has mode {mode!r}; it must be one of "
+                f"{', '.join(sorted(MODES))}"
+            )
+
+        prompt = str(decl.get("prompt", base.prompt if base else f"builtin:{name}"))
+        # Title case rather than the bare name, because this becomes the OKF
+        # `type` a reader sees at the top of the document.
+        fallback_type = base.type if base else name.replace("_", " ").title()
+        doc_type = str(decl.get("type", fallback_type))
+        if not doc_type.strip():
+            raise KindError(f"Kind {name!r} declares an empty 'type'")
+
+        # Inherited from the kind being redeclared, so overriding an
+        # `architecture` kind's sections does not quietly drop its diagram
+        # guard, and declarable outright so a project can name its own.
+        check = decl.get("check", base.check if base else None)
+        if check is not None:
+            check = str(check)
+            if check not in CHECKS:
+                raise KindError(
+                    f"Kind {name!r} declares check {check!r}, which this "
+                    f"version does not implement. Available: "
+                    f"{', '.join(sorted(CHECKS))}"
+                )
+
+        frontmatter = str(
+            decl.get("frontmatter", base.frontmatter if base else YAML_FRONTMATTER)
+        )
+        if frontmatter not in FRONTMATTER_STYLES:
+            raise KindError(
+                f"Kind {name!r} declares frontmatter {frontmatter!r}, which is "
+                f"not a form this version writes. Available: "
+                f"{', '.join(FRONTMATTER_STYLES)}"
+            )
+
+        kinds[name] = Kind(
+            name=name,
+            sections=sections,
+            mode=mode,  # type: ignore[arg-type]
+            prompt=prompt,
+            type=doc_type,
+            check=check,
+            frontmatter=frontmatter,
+        )
+
+    return kinds
+
+
+def _normalise_heading(kind_name: str, raw: Any) -> str:
+    """Return a section as ``"## Heading"``, whichever form was written.
+
+    Configuration examples show the hashes, and a heading written with the
+    wrong number of them — or none — is a typo rather than a different
+    heading. Accepting every form costs one line and removes a class of silent
+    mismatch where a body is rejected for a section its author believes they
+    declared. Sections are always H2: the title is a frontmatter key, so a
+    body carries no H1.
+    """
+    text = str(raw).strip()
+    if not text:
+        raise KindError(f"Kind {kind_name!r} declares an empty section heading")
+    if text.startswith("#"):
+        text = text.lstrip("#").strip()
+    if not text:
+        raise KindError(f"Kind {kind_name!r} declares a section heading with no text")
+    return f"## {text}"
+
+
+def guide_names() -> list[str]:
+    """Return the authoring guides this release ships, sorted."""
+    return sorted(p.stem for p in _GUIDE_DIR.glob("*.md"))
+
+
+def guide_path(name: str) -> Path:
+    """Return the path to a shipped authoring guide, whether or not it exists."""
+    return _GUIDE_DIR / f"{name}.md"
+
+
+def _with_house_style(prompt: str) -> str:
+    """Append the shared vocabulary rules to a built-in prompt.
+
+    Separated by a rule and carrying no heading of its own, because every
+    built-in prompt tells the generator to emit an exact set of H2 sections
+    and an H2 here would read as one more of them.
+    """
+    house = _HOUSE_STYLE.read_text(encoding="utf-8")
+    return f"{prompt.rstrip()}\n\n---\n\n{house.strip()}\n"
+
+
+def resolve_prompt(kind: Kind, repo_root: Path) -> str:
+    """Return the generation conventions for *kind*.
+
+    ``builtin:<name>`` reads the file shipped inside the package and appends
+    the shared house style; anything else is a repository-relative path,
+    returned verbatim, so a project can carry its own conventions without
+    forking the tool.
+    """
+    if kind.prompt.startswith(_BUILTIN_PREFIX):
+        name = kind.prompt[len(_BUILTIN_PREFIX) :]
+        path = _PROMPT_DIR / f"{name}.md"
+        if not path.is_file():
+            raise KindError(
+                f"Kind {kind.name!r} names built-in prompt {kind.prompt!r}, "
+                f"which this version does not ship. Available: "
+                f"{', '.join(sorted(p.stem for p in _PROMPT_DIR.glob('*.md')))}"
+            )
+        return _with_house_style(path.read_text(encoding="utf-8"))
+
+    path = repo_root / kind.prompt
+    if not path.is_file():
+        raise KindError(
+            f"Kind {kind.name!r} names prompt file {kind.prompt!r}, "
+            f"which does not exist under {repo_root}"
+        )
+    return path.read_text(encoding="utf-8")

constant_docs/paths.py

@@ -0,0 +1,246 @@
+"""Module-to-document path mapping, orphan detection, and ownership.
+
+The path mapping is pure structure. Orphan detection is not: deciding whether
+a document is orphaned means opening it, because the question *"should this be
+deleted"* now depends on whether this tool wrote it in the first place.
+
+That is the deletion guard. `prune` deletes what :func:`orphans` reports, and
+before 0.3.1 that was every markdown file under the docs root no live module
+claimed — including files the tool had never touched.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import yaml
+
+from constant_docs.config import Config, document_path, is_tool_owned
+from constant_docs.document import DocumentError, extension_block, is_tracked
+from constant_docs.document import load as load_document
+from constant_docs.fingerprint import compute
+
+
+@dataclass(frozen=True)
+class OrphanReport:
+    """A document whose module glob no longer matches any files."""
+
+    # Repository-relative, like `ModulePlan.doc_path` and every other path this
+    # package hands across a module boundary. The caller joins it onto the
+    # repository root at the moment it needs a real file.
+    #
+    # Held absolute once, and it leaked: this is the value `verify --json` and
+    # `plan --json` serialise, so a report carried the machine's own directory
+    # layout and two runs of the same repository on different machines were not
+    # comparable — while `stale[].doc_path` beside it stayed relative. The rule
+    # is the fix, not a formatter at each of the six places that print it: a
+    # path that travels is relative, an absolute one is built where it is used
+    # and does not outlive the call.
+    doc_path: Path
+    module_key: str
+    # Set only when exactly one candidate matched. Several equally-good
+    # candidates is not a weaker answer, it is a different one: naming any of
+    # them would be a guess presented as a fact.
+    probable_move: str | None = None
+    probable_moves: list[str] = field(default_factory=list)
+
+
+def is_ours(doc: Path) -> bool:
+    """Return whether *doc* is a document this tool wrote.
+
+    A file that cannot be opened or cannot be parsed is **not** ours. That is
+    the safe direction and it is also the honest one: a file we cannot read is
+    the last thing that should be deleted on our say-so.
+
+    `ValueError` is in the tuple for `UnicodeDecodeError`, which subclasses it
+    rather than `OSError`. A single non-UTF-8 `.md` under the docs root used
+    to raise straight out of here, and out of `prune` after the deletions had
+    already happened.
+    """
+    try:
+        return is_tracked(load_document(doc).frontmatter)
+    except (OSError, DocumentError, yaml.YAMLError, ValueError):
+        return False
+
+
+def foreign(config: Config, repo_root: Path | None = None) -> list[Path]:
+    """Return every markdown file under the docs root this tool did not write.
+
+    Reported, never deleted. `prune` names each one, because silence there
+    reads as *"there was nothing else"* — and the thing being claimed is that
+    a command which just deleted files left these alone.
+
+    The tool's own furniture is excluded — `index.md` carries no block by
+    design — and `config.is_tool_owned` is the one place that says so, for
+    all of the scanners that need to know.
+    """
+    docs_root = (repo_root or Path.cwd()) / config.docs_root
+    if not docs_root.is_dir():
+        return []
+    return [
+        doc
+        for doc in sorted(docs_root.rglob("*.md"))
+        if not is_tool_owned(doc, docs_root) and not is_ours(doc)
+    ]
+
+
+def doc_path(module_key: str, docs_root: Path, document: str | None = None) -> Path:
+    """Return the document path for a module.
+
+    ``doc_path("src/payments", Path("docs"))`` → ``Path("docs/src/payments.md")``
+
+    One definition, in `config`, because the loader refuses two keys that
+    resolve to one path and that check must agree with this mapping exactly.
+
+    Prefer :func:`doc_path_for` where a configuration is in hand. This
+    spelling cannot see a module's declared `document`, so passing only a key
+    silently writes to the derived path — which is the whole failure the
+    declaration exists to avoid.
+    """
+    return document_path(module_key, docs_root, document)
+
+
+def doc_path_for(config: Config, module_key: str) -> Path:
+    """Return the document path for *module_key* under *config*.
+
+    The spelling to reach for. A module may declare where its document is
+    written, and a caller holding only the key and the docs root cannot know
+    that — so every path the tool reads or writes resolves through here, and
+    a module the configuration does not declare falls back to the derived
+    path rather than raising, because callers already handle a missing file.
+    """
+    for mod in config.modules:
+        if mod.key == module_key:
+            return document_path(module_key, config.docs_root, mod.document)
+    return document_path(module_key, config.docs_root)
+
+
+def module_for(doc: Path, docs_root: Path) -> str | None:
+    """Inverse of :func:`doc_path`.
+
+    Returns the module key, or ``None`` if *doc* is not under *docs_root*.
+    """
+    try:
+        rel = doc.relative_to(docs_root)
+    except ValueError:
+        return None
+    if rel.suffix != ".md":
+        return None
+    return rel.with_suffix("").as_posix()
+
+
+def orphans(config: Config, repo_root: Path | None = None) -> list[OrphanReport]:
+    """Return orphan reports for documents whose module is no longer active.
+
+    A module is active when its globs still match at least one file.
+    *repo_root* is the parent of the config file; defaults to CWD.
+
+    When two orphan documents carry the same ``source_hash``, they are
+    reported as a probable move (AC 15).
+    """
+    reports: list[OrphanReport] = []
+    root = repo_root or Path.cwd()
+    docs_root = root / config.docs_root
+    if not docs_root.is_dir():
+        return reports
+
+    # Every document belonging to a live module, by path rather than by key.
+    #
+    # The key-to-path mapping appends `.md` and its inverse strips it, so a
+    # module keyed `SPEC.md` writes `docs/SPEC.md` and reads back as `SPEC` —
+    # a key that is not configured, so its own fresh document was reported
+    # orphaned and deleted by `prune`. Stating the guard as "this path belongs
+    # to a live module" rather than trusting the round trip closes it for every
+    # key shape, including ones nobody has thought of yet.
+    # Joined onto the repository root, not `docs_root.parent`: `docs_root` is
+    # already `root / config.docs_root`, so `.parent` strips only its last
+    # segment and a docs root of `docs/modules` produced
+    # `<repo>/docs/docs/modules/…`, a path nothing can match. The guard was
+    # then inert for every nested docs root — silently, and in the direction
+    # that deletes.
+    live_documents = {
+        root / doc_path_for(config, key)
+        for key, files in config.module_files.items()
+        if files
+    }
+
+    # Collect basic orphan reports
+    for doc_file in sorted(docs_root.rglob("*.md")):
+        if is_tool_owned(doc_file, docs_root):
+            continue
+        if doc_file in live_documents:
+            continue
+        mod_key = module_for(doc_file, docs_root)
+        if mod_key is None:
+            continue
+        # A document is ours only if it carries our frontmatter block.
+        #
+        # This is the deletion guard, and it is one predicate because the bug
+        # was one missing question. `prune` deletes what this function reports,
+        # and this function used to report every `.md` under the docs root that
+        # no live module claimed — so a hand-written decision record sitting in
+        # somebody's existing `docs/` folder was, to this tool, refuse.
+        #
+        # Separate from the conformance rule. Everything under the docs root is
+        # still *checked* as a tracked document, and a foreign file still makes
+        # `verify` exit 1. Refusing to check a file and deleting it are
+        # different acts, and only one of them is recoverable.
+        if not is_ours(doc_file):
+            continue
+        if mod_key not in config.module_files or not config.module_files[mod_key]:
+            reports.append(
+                OrphanReport(
+                    doc_path=doc_file.relative_to(root),
+                    module_key=mod_key,
+                )
+            )
+
+    # AC 15 — a document is orphaned and an *undocumented module* carries the
+    # same source_hash: that pair is a probable move.
+    #
+    # Matching orphans against other orphans was the earlier reading and is
+    # not what the criterion says: two dead documents agreeing tells you
+    # nothing, because neither module exists any more. The useful signal is an
+    # orphaned document whose content hash matches a module that is configured
+    # but has no document yet — the module was renamed and its prose can follow.
+    #
+    # Note the reach of this: the digest covers file paths, so moving files to
+    # a new directory changes the hash and is NOT detectable here. What this
+    # catches is a module key or docs-root rename, where the files stay put.
+    #
+    # Keyed by digest to a LIST, not to one key. Two configured modules can
+    # legitimately cover the same files — a module document and the
+    # specification that governs it — and a dict would silently keep whichever
+    # was iterated last, returning it as though it were the only answer.
+    undocumented: dict[str, list[str]] = {}
+    for mod_key, files in sorted(config.module_files.items()):
+        if not files:
+            continue
+        if (root / doc_path_for(config, mod_key)).exists():
+            continue
+        try:
+            undocumented.setdefault(compute(files, root=root), []).append(mod_key)
+        except OSError:
+            continue
+
+    final_reports: list[OrphanReport] = []
+    for orphan in reports:
+        candidates: list[str] = []
+        try:
+            doc = load_document(root / orphan.doc_path)
+            stored = str(extension_block(doc.frontmatter).get("source_hash", ""))
+            if stored:
+                candidates = sorted(undocumented.get(stored, []))
+        except (OSError, DocumentError):
+            pass
+        final_reports.append(
+            OrphanReport(
+                doc_path=orphan.doc_path,
+                module_key=orphan.module_key,
+                probable_move=candidates[0] if len(candidates) == 1 else None,
+                probable_moves=candidates,
+            )
+        )
+
+    return final_reports

constant_docs/prompts/architecture.md

@@ -0,0 +1,61 @@
+Read the source files this document covers, then write its body.
+
+An architecture document answers *"what are the parts and how do they meet"*.
+It is not a specification: a specification says what is promised, this says what
+exists. Someone should be able to read it in five minutes and know where to go
+next, without reading the specification at all.
+
+Output the body only: three H2 sections, in this order, nothing before or
+after, no code fences around the whole thing. Do not write an H1 — the
+document's title is a frontmatter key, not a heading.
+
+## The parts
+
+A table of module, responsibility, and public interface — one row per module,
+the responsibility in one line, the interface as the names a caller actually
+uses. Then a Mermaid diagram of how they depend on one another.
+
+Write the diagram inside a fenced block tagged `mermaid`, as a `graph` or
+`flowchart` with a direction:
+
+    ```mermaid
+    graph TD
+        cli["cli"] --> api["api"]
+        api --> config["config"]
+        harness(A coding agent) --> cli
+    ```
+
+**A quoted node label names a module and is checked against the
+configuration.** Use the module's configured key, or its last path segment
+when that is unambiguous. Anything that is not a module — a harness, a
+filesystem, a person — takes an unquoted label, so an honest picture can show
+things the configuration has never heard of.
+
+Naming a module that does not exist is refused, which is the one guard
+available here and the way these documents actually rot: a module is renamed
+and the picture still shows the old name.
+
+## How they meet
+
+The paths through the system, in prose. Which module calls which, what crosses
+each boundary, and where a rule is enforced exactly once. Name anything that
+must have a single implementation and say what breaks if it gets a second.
+
+## Boundaries
+
+What each part refuses to know. Layering that is deliberate, direction of
+dependency, and what is hidden behind an interface on purpose. A reader
+deciding where to add something needs this more than anything else in the
+document.
+
+Rules:
+
+- The diagram is your reading of the code, not something derived from it. This
+  tool parses no source — no AST, no import graph — so the picture is prose in
+  another form. Do not imply otherwise, and do not draw an edge you cannot
+  point to in the files given.
+- Never restate a signature or a parameter list. Name the interface; the
+  reader has the source.
+- When a previous body is supplied, edit it. The module map changes only when
+  a boundary moves, so most regenerations should change very little.
+- Plain British English. No preamble, no summary of what you did.

constant_docs/prompts/cli-reference.md

@@ -0,0 +1,40 @@
+Read the source files this document covers, then write its body.
+
+A CLI reference answers *"what can I run, and what will it print"*. It is **the
+single home for commands**: the README and the skill point here rather than
+restating them, so this is the only place a command example is allowed to go
+stale.
+
+Output the body only: three H2 sections, in this order, nothing before or
+after, no code fences around the whole thing. Do not write an H1 — the
+document's title is a frontmatter key, not a heading.
+
+## Purpose
+
+What the command is called, how it is invoked, and how it finds its
+configuration. Two to four sentences.
+
+## Commands
+
+Every subcommand: what it does, its arguments in order, and what it writes to
+standard output. One H3 per command, with a fenced example that would actually
+run. Say which commands write to the repository and which do not, because that
+is the first thing a reader wants and the last thing a usage string tells them.
+
+## Flags
+
+Every flag, which commands accept it, and what it changes. Include the ones
+that only matter to a harness — machine-readable output, hook forms — and say
+so, because a person reading top to bottom will otherwise try them.
+
+Rules:
+
+- Work from the argument parsing, not from the help text. A flag the parser
+  accepts and the help omits is exactly the drift this document exists to
+  catch.
+- Every example must be runnable as written. No placeholders that are not
+  marked as such.
+- Exit codes belong to the specification; link to it rather than restating the
+  table.
+- When a previous body is supplied, edit it.
+- Plain British English. No preamble, no summary of what you did.

constant_docs/prompts/config-reference.md

@@ -0,0 +1,38 @@
+Read the source files this document covers, then write its body.
+
+A configuration reference answers *"what can I put in this file, and what will
+it do"*. It is read with the file open, so completeness matters more than prose.
+
+Output the body only: three H2 sections, in this order, nothing before or
+after, no code fences around the whole thing. Do not write an H1 — the
+document's title is a frontmatter key, not a heading.
+
+## Purpose
+
+What the file is, where it lives, and what reads it. Two to four sentences.
+Then a short complete example that would actually load.
+
+## Keys
+
+Every key the loader accepts: name, type, default, and what it does. A table
+per level of nesting, or a subheading per top-level key when a key needs more
+than a line. Give the default exactly as the code has it, and say when a key is
+required rather than leaving the default blank.
+
+This is the section that rots: keys get added in code and documented never.
+Work from the loader, key by key, and do not describe one you cannot find
+there.
+
+## What is refused
+
+The shapes the loader rejects, and why each is refused rather than ignored. A
+mistyped key that is silently accepted is a setting its author believes is in
+force, so the refusals are a feature and belong in the reference.
+
+Rules:
+
+- Never document a key the source does not read.
+- Give types as a reader would write them — "a string, or a list of strings" —
+  not as Python annotations.
+- When a previous body is supplied, edit it. A new key is a new row.
+- Plain British English. No preamble, no summary of what you did.