learn.sapedb.com: twelve pages, and an audit of whether the rule they claim was actually kept

Status

In progress

Component

docs

Priority

High — ships before SAPE-16, which links into it

Blocked by

—

Blocks

SAPE-16

Description

Finish the learn site and publish it. Twelve pages are built. The governing rule is that every example must have been run against a real daemon before it is published; where a feature does not exist or a page is unfinished, the section stays an empty frame with a marker rather than becoming plausible prose. The remaining work is largely the audit: verifying the rule was kept, page by page, because nobody has done that pass.

Why now

It is the second half of "a stranger can run it" — SAPE-5 gets them to a running daemon, this gets them to knowing what to do with one. It also has to land before SAPE-16, because the marketing site links into it and a 404 in the first hour is the first impression.

Measured 2026-09-20 in projects/sapedb-site/learn. Twelve HTML pages, 50 <pre> blocks between them. The empty-frame convention is real and in use: the navigation carries partly written 39 times and not written 16 times across the twelve pages, and external-operations.html is an outline with zero <pre> blocks and three sections tagged needs the feature. The rule itself is stated on all twelve pages: "Every command and every output on this site was run against a real daemon before it was published." That sentence is a claim about 50 code blocks, and no record shows anyone has checked it against them.

Acceptance criteria

1. All 50 <pre> blocks across the twelve pages are audited against the rule, and each one is recorded as either run-and-matching or not. An unaudited block counts as failing; the pass condition is that the not-run list is empty.
2. "Run-and-matching" means the command was executed against a daemon and its output compared to what the page shows, character for character in the parts that are not timestamps or identifiers. A command that ran but whose output was tidied for the page fails.
3. Any block that cannot be run is replaced by an empty frame with the existing marker. Prose describing behaviour nobody produced is removed, not softened.
4. Every internal link resolves. Checked by a crawl over the twelve pages that reports zero broken links and zero broken anchors, run against the built site rather than the sources.
5. Both known first-week sharp edges are on a page and findable: count stopping at its ceiling, and a composed operation's Rows being flat and unlabelled.
6. The site is published and reachable at its domain before SAPE-16 goes up.

Out of scope

• Prose for external operations. That page stays an outline until SAPE-12 lands; the empty frame is the correct state, not a gap to fill.
• Automating the audit. Fifty blocks by hand once is cheaper than a harness, and the harness is a v1.1 item if the pages keep changing.
• Search, versioned documentation, or per-version pages. There is one version.
• A reference for every public name. This site teaches; the API surface is SAPE-2's concern.