constant-docs 0.4.0__py3-none-any.whl

constant_docs/guides/quickstart.md

@@ -0,0 +1,124 @@
+# Writing a quickstart
+
+A quickstart answers **how do I get this working right now?** Its reader has
+already decided to try it. They want to reach something that works and then
+stop reading.
+
+The measure of a quickstart is time to first success, and the way it is failed
+is by being complete. Every branch, caveat and alternative costs every reader
+time, and the ones who needed the caveat were going to read the reference
+anyway.
+
+## The shape
+
+1. **What they will have at the end**, in one sentence. A reader who does not
+   know where they are going cannot tell whether a step went wrong.
+2. **Prerequisites, as a short list**, each checkable in one command. Say what
+   version, and how to find out.
+3. **Numbered steps, each one command and one result.** Show what appears.
+   Where a step fails in a way a beginner will hit, say what that looks like
+   once, in a sentence, not as a troubleshooting section.
+4. **The result, shown.** The file that now exists, the output that now
+   appears. Something they can compare against.
+5. **One next step**, and one only. A link to the reference, or the single
+   thing most people do second.
+
+## Rules
+
+- **Every command copyable and runnable in order**, from a clean checkout,
+  with nothing skipped. Test it by doing exactly that.
+- **One path.** No "or, if you prefer". Choose for them; the reference carries
+  the alternatives.
+- **Real values, not placeholders.** If a placeholder is unavoidable, make it
+  obviously fake and say what to put there.
+- **Show the output of anything that produces one.** A reader whose output
+  differs needs to know at that step, not three steps later.
+- **Keep it to one screen if you can**, and two at the very most.
+- **Link the reference for commands.** A quickstart that documents flags has
+  become a reference with a friendly tone, and it will drift from the real
+  one.
+
+## What loses the reader
+
+Certain vocabulary marks a page as machine-written, and a reader who decides
+that nobody wrote this stops believing what it claims. There is no tolerance
+to spend here — one of these in the opening costs more than the rest of the
+document can earn back. Every entry is a word that sounds like value and
+carries none.
+
+- **Significance inflation** — *powerful*, *robust*, *seamless*, *crucial*,
+  *transformative*, *game-changing*, *blazingly fast*, *production-ready*.
+  Each asserts the conclusion the evidence was there to earn
+- **Vocabulary tells** — *unlock*, *elevate*, *streamline*, *empower*,
+  *leverage*, *delve*, *journey*, *landscape*. If it would not be said aloud
+  across a desk, it does not get written
+- **Adjective lists** — *fast, secure and developer-friendly*, an emoji on
+  each. Claims with no mechanism behind them. Say what the thing does, or cut
+  the line
+- **Contrastive negation** — defining a thing by what it is not. *"Not just a
+  linter, but a formatter"*. *"A property rather than a roadmap"*. *"It
+  proposes instead of removing"*. The shape flatters the writer and makes the
+  reader wait a clause for the meaning. Worse, it spreads: once it is in the
+  ear, every sentence grows a foil. Say what is true and delete the half that
+  says what is not. **Ban `rather than`, `instead of`, `not X but Y` and `X,
+  not Y` outright.** A sentence that needs a real contrast survives being
+  written as two
+- **Negative definition** — describing a thing by its absences. *"Never calls a model, never reads your
+  source, no AST, no import graph."* A list of absences draws the shape of a
+  hole. The reader still has to guess the object. Say what it does. Limits earn their own section, where somebody
+  hunting for them will find them
+- **Rhetorical triplets** — three parallel clauses that buy rhythm and no
+  content. Use three when there are three
+- **The universal address** — *"whether you are a solo developer or a large
+  team"*. It is written to nobody, and nobody is who it persuades
+- **Minimisers** — *simply*, *just*, *easily* in front of an instruction. If
+  the step is easy, the word adds nothing. If it is hard, the word lies, and
+  your reader has already hit the error
+- **Meta-signposting** — *"let us dive in"*, *"it is worth noting"*, *"here is
+  the thing"*. A document has no host
+
+**Sentences.** The words above are the easy half. What follows makes a page
+tiring to read even when every word in it is right.
+
+- **One idea per sentence.** A semicolon or an em-dash joining two complete
+  thoughts gives you two sentences wearing one coat. Split them. Aim under
+  twenty words and stop at about twenty-five
+- **Verbs, not `is`.** *"Modules are globs and files are bytes, which is what
+  makes any language a property here"* hangs on three copulas and lands
+  nothing. Find the action and put it in the verb. Where half the sentences on
+  a page lean on *is*, *are* or *was*, the page describes states where it
+  should describe what happens
+- **Say who does what, and say it first.** Name the actor, then the action.
+  *"The tool hashes every file"* beats *"every file is hashed"*. A sentence
+  with no actor makes your reader guess one
+- **Subject first.** *"On every write, the tool marks the module"* holds a
+  phrase in the air before the reader learns what it modifies. *"The tool
+  marks the module on every write"* lands immediately. Anything opening on a
+  preposition or a stray clause was usually written backwards, so turn it
+  round
+- **Nothing that sounds quotable.** Balanced clauses, an aphorism, a line that
+  would fit on a slide: all of it puts rhythm where content belongs. Write the
+  sentence that tells somebody the thing
+- **The reader's word for it.** *Prose*, *narrative* and *copy* are what
+  writers call writing. Everyone else says *the docs*, *the writing*, or names
+  the document. Take the short word over the formal one every time: *use* over
+  *utilise*, *buy* over *purchase*, *about* over *approximately*
+
+Three mechanical tests, all cheap. Delete the word and read the sentence
+again: if nothing was lost, the word was there to sound like something. Count
+the words against what the sentence actually says and cut until the two match.
+A first draft carries about a third more than it needs, and that third always
+sounds the most like writing. Then read it aloud. Anything you would not say
+to somebody at a desk gets rewritten as what you would have said.
+
+## What does not belong
+
+- Explanation of why the tool works the way it does. That is the specification
+  or the README, and it stops the reader mid-flow
+- Configuration options beyond the one or two the path needs
+- Troubleshooting sections. A reader who has hit an error is no longer doing
+  the quickstart; send them to the error catalogue
+- Alternative installation methods, platform variations, or "on Windows,
+  instead…" branches. Pick one and link the rest
+- Anything that cannot be run. A quickstart is a script written out in
+  sentences, and a step nobody can run is a step nobody trusts

constant_docs/guides/readme.md

@@ -0,0 +1,198 @@
+# Writing a README
+
+A README answers one question: **should I use this?** How to drive it, and
+what every option does, belong in a reference. A README that tries to be a
+reference becomes the document nobody updates.
+
+Your reader decides in about ninety seconds whether to keep going. They
+arrived from a search or a link. They know nothing about the project, and they
+are hunting for a reason to leave. Most of them find one. Everything below
+closes that exit.
+
+Persuading that reader and being straight with them are the same job, because
+their scepticism is the audience. Marketing language spends trust: an
+adjective, an exclamation, a decoration. Evidence earns it: a number, a
+mechanism, an admitted limit.
+
+## Above the fold
+
+Everything that persuades happens in the first screenful. A reader who scrolls
+has already decided to keep going, so the space above that scroll carries
+three things:
+
+- **The claim** — what this is, in one line, at its strongest and still true
+- **What it is** — the kind of thing, and where it runs
+- **The problem it removes** — one line, because the reader already feels it
+- **One piece of evidence** — a number, an output, or a demonstration
+
+Put a table of contents, a badge row, a history or an architecture note there
+and you spend attention you have not earned.
+
+## The shape
+
+1. **The claim, in one line.** The strongest true thing the project does,
+   written so that someone could disagree with it. Most people read this line.
+   Many read only this line, so it carries the whole product: *"documentation
+   that writes and maintains itself"*. Name the category and you have
+   described a shelf; make a claim and you have described a reason.
+2. **What kind of thing it is, in one line.** A command-line tool, a library,
+   an editor extension, a hosted service, a plugin for something. Say which,
+   and say where it runs. A reader who cannot tell what they would be installing
+   cannot judge any of what follows. It is also the fact a claim carries
+   worst: *"documentation that writes and maintains itself"* could be any of
+   the six.
+3. **The problem it removes, in one line.** One line. The reader already feels
+   the pain, so naming it confirms they are in the right place and nothing
+   more. Most READMEs skip it. Usage instructions appear in roughly nine files
+   in ten, a statement of purpose in one in four. That gap is what makes one
+   sentence here worth so much. Spend two and you bury the claim above it.
+4. **How it works, in three sentences.** What it does, how, and the constraint
+   that matters: no key, no network, any language, whatever yours is.
+5. **Proof, before instructions.** Show the thing working before you explain
+   how to work it. Use a recorded terminal session, a before and after, or a
+   measurement that names what it beats. One is enough. Skip it and you are
+   asking for an install on the strength of a paragraph.
+6. **How to install it.** One line, copyable.
+7. **The shortest path to something working.** From nothing to a result they
+   can see, in about a minute. One command if possible. Show the output.
+8. **The thing that makes it worth having**, demonstrated. One realistic
+   example, complete enough to run.
+9. **What it does not do.** Genuinely — the limits, the cases it will not
+   catch. Readers trust this section most, and it is the only one that costs
+   you anything to write.
+10. **Links out**: the specification, the reference, the examples, the
+    licence.
+
+## Rules
+
+- **Cut the draft by a third, and cut the opening twice.** Padding hides in
+  the first paragraph, where the writer is still warming up and the reader has
+  agreed to nothing. Three sentences doing one sentence's work is the
+  commonest failure in a README. It is also the most expensive, because you
+  spend it on the one screenful everybody sees. Say it once, at its shortest,
+  and stop.
+- **A heading says what is in the section.** *"Sixty seconds"* names a
+  measurement, so somebody scanning the page learns nothing from it. Name what
+  they get or what they will do: *"Install"*, *"Try it"*, *"What it does not
+  do"*. People read headings far more often than the paragraphs under them.
+- **Every command example must be runnable as written.** A placeholder that
+  looks like a real value is worse than one that obviously is not.
+- **Replace every adjective with a number, a mechanism, or nothing.** *"Fast"*
+  is a word the reader has discounted a thousand times. *"Three seconds where
+  the tool it replaces takes four minutes"* can be checked, and being
+  checkable is what makes it land. Where no number exists, name the mechanism:
+  *"no network call"* explains a speed claim without making one. An adjective
+  that survives neither test is decoration.
+- **Show output.** A command with no output is a claim; a command with output
+  is evidence.
+- **Show it running.** For anything with a terminal or a screen, a recording
+  does in five seconds what a paragraph does in thirty. Generate it from a
+  script, so a change in behaviour is a re-render. A demo nobody can
+  regenerate is a document that goes stale in public. Keep every fact in the
+  text as well as the image. A reader with images off, a search index and an
+  agent all see the text alone.
+- **Attribute your proof, or drop it.** A named person saying a specific thing
+  carries weight. A wall of logos and a count of stars carry none, and readers
+  discount them: bought stars move no downloads at all. Ask whether a sceptic
+  could check it.
+- **Link to the reference; never restate it.** A command list in a README is a
+  second home for the thing that changes most, and it goes stale first because
+  nothing checks it.
+- **State limits plainly.** *"It cannot catch X"* buys more trust than any
+  amount of enthusiasm, and a reader who finds the limit themselves stops
+  believing the rest.
+- **Do not narrate the project's history.** What it used to be is a changelog
+  entry.
+
+## What loses the reader
+
+Certain vocabulary marks a page as machine-written, and a reader who decides
+that nobody wrote this stops believing what it claims. There is no tolerance
+to spend here — one of these in the opening costs more than the rest of the
+document can earn back. Every entry is a word that sounds like value and
+carries none.
+
+- **Significance inflation** — *powerful*, *robust*, *seamless*, *crucial*,
+  *transformative*, *game-changing*, *blazingly fast*, *production-ready*.
+  Each asserts the conclusion the evidence was there to earn
+- **Vocabulary tells** — *unlock*, *elevate*, *streamline*, *empower*,
+  *leverage*, *delve*, *journey*, *landscape*. If it would not be said aloud
+  across a desk, it does not get written
+- **Adjective lists** — *fast, secure and developer-friendly*, an emoji on
+  each. Claims with no mechanism behind them. Say what the thing does, or cut
+  the line
+- **Contrastive negation** — defining a thing by what it is not. *"Not just a
+  linter, but a formatter"*. *"A property rather than a roadmap"*. *"It
+  proposes instead of removing"*. The shape flatters the writer and makes the
+  reader wait a clause for the meaning. Worse, it spreads: once it is in the
+  ear, every sentence grows a foil. Say what is true and delete the half that
+  says what is not. **Ban `rather than`, `instead of`, `not X but Y` and `X,
+  not Y` outright.** A sentence that needs a real contrast survives being
+  written as two
+- **Negative definition** — describing a thing by its absences. *"Never calls a model, never reads your
+  source, no AST, no import graph."* A list of absences draws the shape of a
+  hole. The reader still has to guess the object. Say what it does. Limits earn their own section, where somebody
+  hunting for them will find them
+- **Rhetorical triplets** — three parallel clauses that buy rhythm and no
+  content. Use three when there are three
+- **The universal address** — *"whether you are a solo developer or a large
+  team"*. It is written to nobody, and nobody is who it persuades
+- **Minimisers** — *simply*, *just*, *easily* in front of an instruction. If
+  the step is easy, the word adds nothing. If it is hard, the word lies, and
+  your reader has already hit the error
+- **Meta-signposting** — *"let us dive in"*, *"it is worth noting"*, *"here is
+  the thing"*. A document has no host
+
+**Sentences.** The words above are the easy half. What follows makes a page
+tiring to read even when every word in it is right.
+
+- **One idea per sentence.** A semicolon or an em-dash joining two complete
+  thoughts gives you two sentences wearing one coat. Split them. Aim under
+  twenty words and stop at about twenty-five
+- **Verbs, not `is`.** *"Modules are globs and files are bytes, which is what
+  makes any language a property here"* hangs on three copulas and lands
+  nothing. Find the action and put it in the verb. Where half the sentences on
+  a page lean on *is*, *are* or *was*, the page describes states where it
+  should describe what happens
+- **Say who does what, and say it first.** Name the actor, then the action.
+  *"The tool hashes every file"* beats *"every file is hashed"*. A sentence
+  with no actor makes your reader guess one
+- **Subject first.** *"On every write, the tool marks the module"* holds a
+  phrase in the air before the reader learns what it modifies. *"The tool
+  marks the module on every write"* lands immediately. Anything opening on a
+  preposition or a stray clause was usually written backwards, so turn it
+  round
+- **Nothing that sounds quotable.** Balanced clauses, an aphorism, a line that
+  would fit on a slide: all of it puts rhythm where content belongs. Write the
+  sentence that tells somebody the thing
+- **The reader's word for it.** *Prose*, *narrative* and *copy* are what
+  writers call writing. Everyone else says *the docs*, *the writing*, or names
+  the document. Take the short word over the formal one every time: *use* over
+  *utilise*, *buy* over *purchase*, *about* over *approximately*
+
+Three mechanical tests, all cheap. Delete the word and read the sentence
+again: if nothing was lost, the word was there to sound like something. Count
+the words against what the sentence actually says and cut until the two match.
+A first draft carries about a third more than it needs, and that third always
+sounds the most like writing. Then read it aloud. Anything you would not say
+to somebody at a desk gets rewritten as what you would have said.
+
+## What does not belong
+
+- An options table, a flag list, or a full command reference — that is a
+  reference document, and duplicating it here guarantees the two disagree
+- Installation instructions for six package managers. Pick the one your users
+  have; link the rest
+- A roadmap. It ages into a list of the things that did not happen, and it
+  helps nobody's ninety-second decision
+- Unattributable proof — a logo wall, a user count, a comparison table scored
+  by the author. Named users and named quotations outperform all of it and
+  belong high up; an anonymous aggregate belongs nowhere
+- Badges beyond the two that mean something: does it build, and what licence
+- An architecture explanation. A reader deciding whether to adopt does not
+  care yet, and one who does care has a specification to read
+- Emoji in headings or feature rows. Decoration is the cheapest thing to fake,
+  which is exactly why restraint now reads as a trust signal
+- Apologies, "work in progress" notices, or anything hedging what it does.
+  Either it does the thing or the README should say it does not
+

constant_docs/house-style.md

@@ -0,0 +1,70 @@
+Certain vocabulary marks a page as machine-written, and a reader who decides
+that nobody wrote this stops believing what it claims. There is no tolerance
+to spend here — one of these in the opening costs more than the rest of the
+document can earn back. Every entry is a word that sounds like value and
+carries none.
+
+- **Significance inflation** — *powerful*, *robust*, *seamless*, *crucial*,
+  *transformative*, *game-changing*, *blazingly fast*, *production-ready*.
+  Each asserts the conclusion the evidence was there to earn
+- **Vocabulary tells** — *unlock*, *elevate*, *streamline*, *empower*,
+  *leverage*, *delve*, *journey*, *landscape*. If it would not be said aloud
+  across a desk, it does not get written
+- **Adjective lists** — *fast, secure and developer-friendly*, an emoji on
+  each. Claims with no mechanism behind them. Say what the thing does, or cut
+  the line
+- **Contrastive negation** — defining a thing by what it is not. *"Not just a
+  linter, but a formatter"*. *"A property rather than a roadmap"*. *"It
+  proposes instead of removing"*. The shape flatters the writer and makes the
+  reader wait a clause for the meaning. Worse, it spreads: once it is in the
+  ear, every sentence grows a foil. Say what is true and delete the half that
+  says what is not. **Ban `rather than`, `instead of`, `not X but Y` and `X,
+  not Y` outright.** A sentence that needs a real contrast survives being
+  written as two
+- **Negative definition** — describing a thing by its absences. *"Never calls a model, never reads your
+  source, no AST, no import graph."* A list of absences draws the shape of a
+  hole. The reader still has to guess the object. Say what it does. Limits earn their own section, where somebody
+  hunting for them will find them
+- **Rhetorical triplets** — three parallel clauses that buy rhythm and no
+  content. Use three when there are three
+- **The universal address** — *"whether you are a solo developer or a large
+  team"*. It is written to nobody, and nobody is who it persuades
+- **Minimisers** — *simply*, *just*, *easily* in front of an instruction. If
+  the step is easy, the word adds nothing. If it is hard, the word lies, and
+  your reader has already hit the error
+- **Meta-signposting** — *"let us dive in"*, *"it is worth noting"*, *"here is
+  the thing"*. A document has no host
+
+**Sentences.** The words above are the easy half. What follows makes a page
+tiring to read even when every word in it is right.
+
+- **One idea per sentence.** A semicolon or an em-dash joining two complete
+  thoughts gives you two sentences wearing one coat. Split them. Aim under
+  twenty words and stop at about twenty-five
+- **Verbs, not `is`.** *"Modules are globs and files are bytes, which is what
+  makes any language a property here"* hangs on three copulas and lands
+  nothing. Find the action and put it in the verb. Where half the sentences on
+  a page lean on *is*, *are* or *was*, the page describes states where it
+  should describe what happens
+- **Say who does what, and say it first.** Name the actor, then the action.
+  *"The tool hashes every file"* beats *"every file is hashed"*. A sentence
+  with no actor makes your reader guess one
+- **Subject first.** *"On every write, the tool marks the module"* holds a
+  phrase in the air before the reader learns what it modifies. *"The tool
+  marks the module on every write"* lands immediately. Anything opening on a
+  preposition or a stray clause was usually written backwards, so turn it
+  round
+- **Nothing that sounds quotable.** Balanced clauses, an aphorism, a line that
+  would fit on a slide: all of it puts rhythm where content belongs. Write the
+  sentence that tells somebody the thing
+- **The reader's word for it.** *Prose*, *narrative* and *copy* are what
+  writers call writing. Everyone else says *the docs*, *the writing*, or names
+  the document. Take the short word over the formal one every time: *use* over
+  *utilise*, *buy* over *purchase*, *about* over *approximately*
+
+Three mechanical tests, all cheap. Delete the word and read the sentence
+again: if nothing was lost, the word was there to sound like something. Count
+the words against what the sentence actually says and cut until the two match.
+A first draft carries about a third more than it needs, and that third always
+sounds the most like writing. Then read it aloud. Anything you would not say
+to somebody at a desk gets rewritten as what you would have said.

constant_docs/index.py

@@ -0,0 +1,210 @@
+"""Root index assembly for constant-docs.
+
+Builds ``index.md`` from module descriptions, enforces token budget,
+and conformance-checks every document under the docs root.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import tempfile
+from pathlib import Path, PurePosixPath
+
+import yaml
+
+from constant_docs.config import Config, is_tool_owned
+from constant_docs.document import (
+    DocumentCache,
+    DocumentError,
+    extension_block,
+    replace_preserving_mode,
+)
+from constant_docs.document import load as load_document
+from constant_docs.paths import doc_path_for
+
+# The index carries no frontmatter, so this note is how a later run recognises
+# a file as its own before overwriting it. Changing the wording orphans every
+# index already on disk, which then reads as somebody else's file.
+_GENERATED_NOTE = "Auto-generated by `constant-docs`."
+
+# Every wording this note has ever had, because recognition has to reach back
+# further than generation does. A 0.1-era repository — the upgrade path
+# `tests/test_compat.py` exists to keep working — carries an index written
+# under the tool's former name, and refusing to overwrite it would tell a user
+# to delete a file the tool itself generated.
+_GENERATED_NOTES = (_GENERATED_NOTE, "Auto-generated by `module-docs`.")
+
+REQUIRED_FM_KEYS = [
+    "module",
+    "source_glob",
+    "source_files",
+    "source_hash",
+    "hash_method",
+    "hash_covers",
+    "generator",
+    "generator_spec",
+]
+
+
+def _estimate_tokens(text: str) -> int:
+    """Rough token estimate — 1 token per 4 characters."""
+    return len(text) // 4
+
+
+def build(config: Config, repo_root: Path) -> str:
+    """Assemble the root index from module descriptions.
+
+    Returns the markdown content for ``index.md`` as a string.
+    """
+    lines: list[str] = [
+        "# Module Index\n",
+        (f"{_GENERATED_NOTE} Each entry links to the corresponding module document.\n"),
+    ]
+
+    current_estimate = 2  # for the heading + blank line
+
+    for mod in config.modules:
+        desc = ""
+        doc_file = doc_path_for(config, mod.key)
+        doc_abs = repo_root / doc_file
+        if doc_abs.exists():
+            try:
+                doc = load_document(doc_abs)
+                desc = doc.frontmatter.get("description", "") or ""
+            except DocumentError:
+                desc = "*(malformed)*"
+
+        # Relative to the index itself, which lives at <docs_root>/index.md.
+        # A repository-relative link here reads as `docs/modules/docs/modules/…`
+        # when followed from the index, which resolves nowhere and stays
+        # invisible until someone clicks it.
+        #
+        # A document declared outside the docs root cannot be made relative to
+        # it by stripping a prefix it does not have, so the link is computed
+        # as a walk between the two and comes out as `../README.md`. The index
+        # still lists it: a reader asking what is documented here wants the
+        # answer whatever directory the answer lives in.
+        rel_link = PurePosixPath(os.path.relpath(doc_file, config.docs_root)).as_posix()
+        entry = (
+            f"- [`{mod.key}`]({rel_link}): {desc}"
+            if desc
+            else f"- [`{mod.key}`]({rel_link})"
+        )
+        lines.append(entry)
+        current_estimate += _estimate_tokens(entry)
+
+    lines.append("")  # trailing newline
+
+    if config.index_token_budget is not None:
+        budget = config.index_token_budget
+        if current_estimate > budget:
+            print(
+                f"Warning: index token estimate ({current_estimate}) exceeds "
+                f"configured budget ({budget})",
+                file=sys.stderr,
+            )
+
+    return "\n".join(lines) + "\n"
+
+
+def _is_generated_index(target: Path) -> bool:
+    """Return whether *target* is an index this tool assembled.
+
+    The index is the one file under the docs root that deliberately carries no
+    frontmatter, so `paths.is_ours` cannot recognise it and the generated note
+    stands in as the mark. Read conservatively: a file we cannot read is not
+    ours, which is the same direction `is_ours` takes and for the same reason.
+    """
+    try:
+        head = target.read_text(encoding="utf-8")[:512]
+    except (OSError, UnicodeDecodeError):
+        return False
+    return any(note in head for note in _GENERATED_NOTES)
+
+
+def write(config: Config, repo_root: Path) -> Path:
+    """Assemble the index and write it to ``<docs_root>/index.md``.
+
+    Returns the path written. The file is left byte-identical when the
+    assembled content already matches, for the same reason document writes
+    are: a run that changes nothing must not move a timestamp or an mtime.
+    """
+    content = build(config, repo_root)
+    target = repo_root / config.docs_root / "index.md"
+    target.parent.mkdir(parents=True, exist_ok=True)
+    if target.exists() and target.read_bytes() == content.encode():
+        return target
+
+    # The same question `prune` asks before it deletes, asked before a write
+    # that is just as unrecoverable. Pointing `docs_root` at an existing
+    # `docs/` folder is the documented first step and `index.md` is the most
+    # common file in one, so overwriting it lands on first adoption — and no
+    # scan would have reported it, because all three skip `index.md` by name.
+    if target.exists() and not _is_generated_index(target):
+        raise DocumentError(
+            f"{target} exists and was not written by constant-docs. The index "
+            f"is assembled from scratch on every run, so writing it would "
+            f"discard what is there. Move or delete that file, or point "
+            f"'docs_root' somewhere the tool owns."
+        )
+
+    fd, tmp_path = tempfile.mkstemp(dir=str(target.parent), prefix=".index.md.tmp.")
+    try:
+        with os.fdopen(fd, "w", encoding="utf-8") as f:
+            f.write(content)
+        replace_preserving_mode(tmp_path, target)
+    except BaseException:
+        if os.path.exists(tmp_path):
+            os.unlink(tmp_path)
+        raise
+    return target
+
+
+def conformance_check(
+    config: Config, repo_root: Path, cache: DocumentCache | None = None
+) -> list[str]:
+    """AC 25 — Verify every ``.md`` under the docs root has valid frontmatter.
+
+    Returns a list of problematic document paths (relative to repo root).
+
+    *cache* lets `verify` hand in the documents it has already parsed. Every
+    document under the docs root was read once by `plan` and again here, and a
+    parse is a read plus a DOTALL regex plus a YAML load.
+    """
+    read = (cache or DocumentCache()).load
+    docs_root_abs = repo_root / config.docs_root
+    issues: list[str] = []
+
+    if not docs_root_abs.is_dir():
+        return issues
+
+    for md_file in sorted(docs_root_abs.rglob("*.md")):
+        if is_tool_owned(md_file, docs_root_abs):
+            continue
+        try:
+            doc = read(md_file)
+            doc_type = doc.frontmatter.get("type", "")
+            if not doc_type or not isinstance(doc_type, str) or not doc_type.strip():
+                issues.append(str(md_file.relative_to(repo_root)))
+                continue
+            # AC 35 — the keys live inside the namespaced producer-extension
+            # block, so a host schema and this tool cannot collide.
+            block = extension_block(doc.frontmatter)
+            if not block:
+                issues.append(
+                    f"{md_file.relative_to(repo_root)} — missing the "
+                    "'constant_docs' frontmatter block"
+                )
+                continue
+            for key in REQUIRED_FM_KEYS:
+                if key not in block:
+                    issues.append(
+                        f"{md_file.relative_to(repo_root)} — missing required "
+                        f"frontmatter key: {key!r}"
+                    )
+                    break
+        except (OSError, yaml.YAMLError, DocumentError, ValueError):
+            issues.append(str(md_file.relative_to(repo_root)))
+
+    return issues