The docs/ site architecture

docs/ is the public GitHub-Pages site (served from docs/ on master via its CNAME), repo-root-governed with no owning kit. This page is the load-triggered home for the site’s chrome and license line, and the index of the pages holding the rest — the mechanism CLAUDE.md §Housekeeping names by pointer rather than carries inline. The rest is the page-authoring rules, the generated projections and their fan-outs, the install parity contracts and the install block contracts. It is off-nav by design (scripts/docs-offnav.list): maintainer governance reached by citation, not a reader-nav destination.

Site chrome and the nav contract

The site chrome — the Jekyll layout, client-side search, the code-block copy button and theme selector — lives in docs/_config.yml, docs/_layouts/, docs/_includes/, and docs/assets/. jekyll-sitemap writes sitemap.xml, every HTML page less one setting sitemap: false, and a robots.txt naming it, so the tree carries neither file and a page leaves the sitemap only by that key. The nav is Liquid over front matter: nav_order / nav_parent place a page; a page’s nav_id parents its nav_child_order-sorted children, each child carrying derived suffix links to its generated:-marked directory siblings, the README and SPEC mirrors both. A nav page’s nav_suffix names further pages its entry suffixes, as <label>=<path> pairs relative to the docs root: the SPEC mirror of a component with no kit page, on the page documenting that component. A nav page naming a nav_children_key instead derives its children from the site pages carrying that key, path-descending, each labeled by the key’s value (the release notes under the Releases page), inside a details element that is open only on a page carrying the key. check-docs-nav-reachable holds every docs page to a title: front-matter block and a menu entry of its own: a nav slot, a derived child, a generated-sibling suffix link, or a nav_suffix pair. Reach through a page’s body is not reach: a page off the menu is either given an entry or listed off-nav by design in scripts/docs-offnav.list. That same gate models the front-matter facts, both suffix rules and the derived-children rule, no wider than the include renders them, since a wider model is a green the rendered site does not earn. It also reds a nav_suffix pair naming no docs page, and an overview among its siblings: under three or more children, one every sibling links and that links each of them. No separate gate covers these. check-docs-render-fidelity renders every tracked docs page through the Pages parser and holds the output against markdown corruption: a code span leaking a stray backtick or a raw tag into text, a code-fenced heading promoted to a real one, or fewer rendered tables than the source has GitHub-Flavored Markdown table starts. A missing renderer fails it closed (site-kit/SPEC.md §check-docs-render-fidelity). check-kit-registration holds a row per kit on docs/kits.md (the Kit Reference page) through GATE_SDK_REGISTRY_DOC, and check-docs-kit-parity the nav child block (nav_parent: kits + nav_child_order) on each docs/<kit>/index.md.

The license line

Every README’s ## License section and the site footer carry one sentence: Licensed under Apache-2.0, then where that copy’s license text is. A site a reader follows by link takes the linked form, the license name linked to the text. A README that travels without the repository takes the located form, which names LICENSE and says where it sits beside that copy. scripts/license-line.conf declares the license, each location clause and each site’s form. check-license-line holds each site to its rendering and every README carrying the heading to a declaration, printing the expected line on a red. The mirrors are generated from their sources and are not sites. The footer states the license on every page, so a hand-written page under the source’s pages root carries no License section of its own, and the gate reds one that does.

A markdown site’s section, blank lines dropped, is exactly its one line. An .html site carries exactly one line opening Licensed under, in the linked form only. The coverage walk reads every README.md under the root, and the page walk every other .md page under pages. Both apply the gate-sdk prune set and skip a file whose front matter sets generated: true. The gate exits 2 when it cannot read the source or a site. It also exits 2 on a malformed source: a key missing, repeated or unknown, a duplicate declaration, a clause named but undeclared, or a form other than link or at. Its positional form is check-license-line [source root].