No hand-written page passes 400 lines, a page that would is split along its headings with its anchors kept, and a check in CI holds it¶
Decision 940 · accepted · 2026-10-24 · issue #422
Why. #422's done-when says no hand-written document passes about 400 lines but the
protocol, and defects.md lists only open defects; row 7 of the Stage 1 gate checks it. A
rule a person checks once a release is a rule that holds once a release.
The decision.
- 400 lines, checked.
scripts/doc-size.exsfails when a Markdown file git knows about passes 400 lines. It runs inci.yml'sversionsjob and indev-check.yml, where a chunk's pages grow. Three kinds are not held to it:PROTOCOL.md, one contract a client author reads whole, whose split has a cost #422 asked to be weighed and not made by the line rule; a generated file, one whose first lines say<!-- Generated by(the third-party licences, what Troupe dials); anddocs/history/, records kept as they were written that nobody is asked to read. The line is a line, not about 400: a page at 399 that needs another paragraph is split first. - A page past the line is split along its own headings. Sections move word for word to
pages of their own beside it (
docs/user/configuration-layers.md,docs/admin/github-runs.md,docs/developer/architecture-remote.md); the parent keeps each moved##heading with a sentence or two and a link, and each moved###heading's anchor as an<a id>, so a link from an issue, a release note or a bookmark still lands on the right page. Links inside the repository are moved to the new page. A dated measurement on an instruction page is a record, not instruction, and is deleted with a line saying it is in the page's git history (prompt-prefix.md's live and offline numbers). Not a redirect plugin: the anchors that matter are inside pages, which a page-level redirect cannot carry, and GitHub, where many readers meet these files, runs no plugin. Not a rewrite: the content is #422's sweep to judge, and a split keeps every claim where a reviewer can see it moved unchanged. - Content that something reads stays where it is read. The generated key reference and
provider-type table stay in
docs/user/configuration.md(mix troupe.config.schemaand the core's tests read them there),ARCHITECTURE.mdkeeps section 2 (code cites its failure matrix and transition table), and a YAML example that moved to a new page is added to the core's test that checks every example is a valid config file. - The site's front page is
docs/README.md, drawn as a landing page (#189). It is the page both a GitHub reader ofdocs/and a site visitor meet, so it stays one file:docs/overrides/hooks.pygives the home pagelanding.htmland hides the nav and the table of contents beside it, rather than front matter GitHub would print as a table. Above the fold: what Troupe is, the install as the quick start has it (held to the quick start word for word byquick-start.yml, as the root README's is), and a figure marked<!-- recording: docs/assets/seam.mp4, ... -->that shows a still until the gate's row 4 recording exists. The search basics are the pages' own: each page's description and canonical URL from the hook, Open Graph on every page with a static image,sitemap.xmlfrom MkDocs, aSoftwareApplicationdescription on the front page, androbots.txt, which a crawler reads at a host's root only and so does its work once the site has a host of its own.
Governs: docs/**, mkdocs.yml, scripts/doc-size.exs, .github/workflows/quick-start.yml