Specification note · doc.html project · the wiki shape

The Wiki Shape: A Root of Witnessed Documents

Multiple doc.html files can form a complete linked AI wiki. This note is the shape's specification in one place: its parts, its one new rule, the mechanism a reader uses to navigate it, the sealed runs that back each claim, and the boundaries of what it promises. Everything here is checkable — this document is itself a conformant leaf, and the verifiers it describes ship beside it.

Written by Georges Casseus and Claude (Fable 5) in the project's writing room, and reviewed in council before publication. It moves no canon — the shape is a convention with receipts, not a specification change — and it is itself pinned on the shelf of the wiki of witnessed documents, checked by the rule and the verifiers it specifies. The full account of the probe behind the shape is carried, as written, in the essay The Wiki That Witnesses Itself.

Every document this project publishes verifies alone: open any doc.html, run a shipped reader, and each section either hashes true to its manifest witness or is refused. What a single file cannot say is how a collection holds together — which documents belong to it, and whether one of them has been quietly rewritten and re-witnessed since the collection was assembled. The wiki shape answers that with the smallest possible addition: a root document whose entries pin each leaf's witnessed section content, in order, by a single cross-file digest called the doc-pin. A leaf pays nothing to join — it is an ordinary doc.html, unchanged — and the root pays one attribute per entry.

The shape is deliberately extra-canonical: the project's specification governs each single file, and its first vow — the artifact is one document — is untouched, because every artifact here is one document. The wiki is a shape over documents, not a change to them. This note exists so the shape can be shared, checked, and rebuilt by someone who has never read this repository.

From the specification note The Wiki Shape · § 2 of 8

1. The parts

Four parts, of which only the last is new.

Part	What it is	What is new about it
Leaf	An ordinary `doc.html`: one HTML file whose body carries witnessed `<section>` elements and a `<nav id="manifest">` that points at them, each manifest link carrying the section's `data-witness` (SHA-256 of the section's exact inner bytes) and `data-char-count`. A leaf verifies alone, with either shipped reader, knowing nothing of any wiki.	Nothing. That is the point: joining a wiki costs a leaf zero changes.
Root	Itself a conformant `doc.html` — its own manifest, its own witnessed sections, verifiable by the same shipped readers. Its body carries the shelf.	Nothing structural. The root is a leaf that happens to talk about other documents.
Shelf entry	An ordinary link in the root's body — `<a href="leaf.doc.html" data-doc-pin="…">` — naming one whole leaf document, with a human summary of why the leaf is on the shelf.	The one new attribute it carries.
Doc-pin	A SHA-256 hex digest over the leaf's manifest witnesses, in manifest order, joined by ASCII colon. The link does not merely point at the leaf; it pins the witnessed section content the leaf held, in order, when the shelf was written.	The only new rule in the entire shape. Everything else is the single-file format, unchanged.

Because the root is itself a conformant document, the shape composes with everything the single-file format already earned: the root's own sections are witnessed, its own manifest is checked by the shipped readers, and its history is pinned the same way every published document's is — by the repository's public record.

From the specification note The Wiki Shape · § 3 of 8

2. The doc-pin rule

The computation. Take the leaf document's manifest data-witness values, in manifest order. Join them with : (ASCII colon, one byte). Compute the SHA-256 hex digest of the resulting ASCII string. That digest is the entry's data-doc-pin.

doc_pin = sha256( w1 + ":" + w2 + ":" + … + ":" + wN )   # lowercase hex in, lowercase hex out

A leaf whose every section still verifies, in the same order, reproduces the same pin. A leaf whose section content was rewritten — even by a forger who dutifully recomputed every per-section witness — produces a different one, and the mismatch shows at the root. This is the property the per-section witness alone cannot give: a re-witnessed leaf passes its own reader; it cannot pass the shelf. The pin binds witnessed section content, in order — nothing else; the surfaces it does not bind are named in § 5.

The check, in three steps — one reader run and one hash utility, nothing else:

Open the linked leaf and run a shipped reader (tools/verify.py or tools/verify.mjs) — every section must verify.
Copy the leaf's manifest witnesses in order into the list and run: python -c "import hashlib;ws=['<w1>','<w2>'];print(hashlib.sha256(':'.join(ws).encode()).hexdigest())" — replacing '<w1>','<w2>' with the witnesses, one quoted entry per manifest line.
Compare against the shelf entry's data-doc-pin.

The shipped verifiers. Two companions, tools/verify_wiki.py (Python, stdlib only) and tools/verify_wiki.mjs (Node, built-ins only), automate all three steps for a whole wiki — and they delegate: root and leaf acceptance is the shipped Core reader's verdict, invoked per document, never re-implemented. The wiki layer owns only what is genuinely new — shelf discovery, leaf existence, base-resolution refusal, and pin comparison. (A wiki tool that copies pieces of document law inevitably lags a clause; this note's own first draft did, and council review caught it.) A root carrying <base href> is refused outright, fail closed: a base retargets every relative shelf link, so the pin and the link as written could name different files. For the same reason a shelf entry's href must fit a deliberately narrow portable shelf-link grammar — plain relative path segments of A–Z a–z 0–9 . _ - joined by /, with character references, percent-escapes, queries, fragments, and dot-segments all refused, fail closed, and every segment required to match a real directory entry with byte-exact spelling, checked against the directory listing rather than the operating system's own resolution, so that a case-insensitive filesystem cannot certify a root a case-sensitive host would serve broken. The grammar is a refusal, not a protection: it narrows what the companions will certify to shapes whose resolution is unambiguous, and everything outside it is a FAIL. Shelf-entry attribute reading uses the character-level tokenizer the Core readers converged on — not a regex — so a decoy attribute (x:data-doc-pin) does not displace the real carrier, and a duplicated or non-double-quoted shelf carrier is refused. Anchors inside five raw-text or inert containers (script, style, textarea, title, template) are masked out of discovery. That masking is hygiene, and it is disclosed as incomplete: five names are not HTML's tokenizer.

What the companions certify — and the step they hand back. They verify the shelf as serialized. A passing run certifies three things and no more: that carrier-shaped entries occur in the root's source bytes, that each named leaf verifies under the shipped Core reader, and that each recomputed pin equals the entry's claim. It does not certify that an HTML reader presents those carriers as live links. Discovery is a scan over serialized bytes, and HTML's full tokenizer can disagree with such a scan — custom elements, non-local raw-text openers, anchor-shaped text sitting inside a quoted attribute value. So the companions emit the exact list they checked: on a clean run each prints a VERIFIED SHELF block, every certified href beside its full pin, one line each, then the line NOT CHECKED: whether an HTML reader presents these carriers as live links., then a verdict naming what was actually verified — serialized shelf carriers, presentation not checked. This is the see-what-is-signed discipline, stated plainly: the certificate hands back the object it verified, so the last step of the check is the reader's own comparison of the emitted list against the shelf the page presents. Whether an HTML reader presents these carriers as live links is outside the companions' claim; no additional document grammar is specified here — the boundary stands disclosed.

Each verifier carries a --selftest proving its teeth on built fixtures: twenty-two in each language, same ids and same semantics on both sides. Tampered section; re-witnessed leaf caught at the pin; missing leaf; forged pin; colon-decoy on either carrier; duplicated carrier; <base href> refusal; hrefs outside the portable grammar (character reference, percent-escape, query, fragment, dot-segment) refused; a mis-cased href refused against the directory's own spelling; a carrier hidden in a raw-text container not counted as a shelf entry; an unlisted witnessed section caught by the delegated Core verdict; a named-but-missing Core reader refused rather than silently substituted; and three teeth on the receipt itself — that a passing run lists exactly the pairs it checked, that an entry the run never checked never appears in the list, and that the receipt states the SHA-256 sampled from the resolved reader file before invocation. An explicit --core path or DOC_HTML_CORE_READER binds exactly, and every run prints the resolved reader path and the digest of the file at that path, sampled once before the first invocation, so the receipt names the authority it resolved in a form checkable against the published seals — a fact the receipt states, not an authenticity it can prove, and the file's stability across the run's repeated invocations is not checked. Two independent languages, one document judge.

The name. The attribute is data-doc-pin, not data-witness, deliberately: a witness attests one section's inner bytes; a pin attests a document's ordered manifest-witness sequence. Earlier drafts of this note named the attribute data-doc-fold; the Operator renamed the mechanism so that fold stays the name of the format's published append-and-supersede office — the rule and every pin value are unchanged. Different claims carry different names, so a reader can never mistake which promise it is checking.

From the specification note The Wiki Shape · § 4 of 8

3. How a reader navigates: the resident map

The wiki's reading mechanism is virtual memory for a context window. The model never holds the wiki; it holds the maps, and the maps are small enough to be effectively permanent residents.

Root manifest resident. The root's shelf is a few kilobytes. Absorbing it buys the model the wiki's full top-level address space — every leaf document, by name and summary, held in context at negligible cost for the whole session.
Leaf manifest on approach. Each leaf's <nav id="manifest"> sits at the top of its file by construction, so following a shelf link is a bounded ranged read of the file's head — not a read of the document. The model absorbs that leaf's section list, a few kilobytes more, and the whole leaf becomes addressable.
Section on demand. Only the sections the question actually needs are ever read as bodies, each verifiable against its witness at the moment of reading.

At any moment the model's residency is: the root map, the maps of leaves it has approached, and the handful of sections it pulled. The reachable corpus is unbounded; the resident footprint grows with the depth of the current question, not with the size of the wiki. Two measured consequences follow. The index cost of one level of structure obeys a clean law — the enumeration advantage of a nested index over a flat one approaches the branching factor B, so organization is tunable arithmetic, not taste. And residency stays flat under growth: in the project's sealed scaling run, the archive grew to roughly two million tokens while the reader's peak resident input stayed under six thousand (§ 4). Nothing forces the cheap read — the shape affords selective reading; the discipline of reading maps before bodies belongs to the reader's protocol.

From the specification note The Wiki Shape · § 5 of 8

4. The receipts: which claim rests on which run

Every load-bearing claim above traces to a sealed, pre-registered run in the project's laboratory record. Stated with their bounds:

Knowledge-layer tamper-evidence, and the re-seal catch. The multi-file wiki probe ported a real markdown LLM-wiki to doc.html leaves under a witness-projecting root. A one-byte corruption of a distilled fact was undetected by the markdown toolchain as shipped and detected-and-localized by the doc.html readers; a forger who rewrote a leaf and recomputed every per-section witness fooled the per-section reader and was caught by the cross-file digest. A lone leaf, extracted to an empty directory, verified from itself. Retrieval parity on clean questions: no regression. Bound: existence and mechanism — one corpus, one model family; the probe's cross-file instrument used a rolling seeded digest, a different rule from the shipped one (§ 5).
The drill works, and the structure — not the model — is load-bearing. A blind agent with no spec and no skill, given only generic file operations and one question, drilled a nested manifest to the correct current value and cited the correct section; the structure-stripped control, same model and same bytes, failed to an ungrounded guess. Bound: n=1 existence, one designed trap.
The read-cost law. Deterministic, model-free measurement at 102,400 sections / 44.6 MB: index-enumeration advantage 4.0× at branching factor 4, 16.0× at 16, 62.9× at 64, 220× at 256, 286× at 1024 — the advantage per nesting level approaches B. Eight cumulative growth rounds re-projected the index with zero mutations of any witnessed record. Bound: an enumeration model of index cost; reader strategy sets the realized fraction (blind agents realized 12× and 3.3× at small scale against the model's 14.7×).
Flat residency under growth. In the bounded-return run, an archive of 8,192 sections (≈ 2M tokens) was navigated with peak resident input 5,715 tokens against a 16,384 cap, p95 cumulative 32,176 against a pre-sealed 62,113 envelope, with round count entering only as ceil(log₂₃ N) plus constants. Bound: the same run's live selection-at-depth leg failed its floor — carried honestly in § 5.
The honest small-corpus bound. On a single 118 KB document, selective hydration matched whole-read recall exactly (24/24 = 24/24 against a 0/24 floor) and cost more tokens than a grep-armed reader. The shape's economics begin where the corpus outgrows the map; below that, ordinary search wins and the shape claims nothing.

From the specification note The Wiki Shape · § 6 of 8

5. What this shape does not promise

Tamper-evident, never tamper-proof. The pin catches any change to a leaf's witnessed section content after the shelf was written, including a full re-witness. It cannot prevent the change; it reveals it.
The pin binds witnessed section content, in order — nothing else. Section ids, manifest link text and summaries, page chrome, the head, and every byte outside the witnessed inner spans are unbound surfaces: a leaf whose sections were merely renamed, or whose manifest gloss was edited, reproduces the same pin and still passes its old shelf entry. Two Core-valid leaves with identical section bodies and different section ids share one pin. Nothing in this shape pins those surfaces: they lie outside every witnessed inner span, so neither the per-section witnesses nor the doc-pin covers them. What pins them, when anything does, is the repository's public history or a separate whole-file commitment — not the doc-pin.
The certificate reads the source, not the render. The shipped companions verify the shelf as serialized: that carrier-shaped entries occur in the source, that each named leaf verifies, that each pin matches. Whether an HTML reader presents each carrier as a live link is not checked — the companions print the exact list they certified so that comparison stays the reader's own one-glance act. Presentation equivalence is outside the companions' claim, and no additional document grammar is specified to close the gap (§ 2).
The pin cannot date. It cannot say a leaf is current, or the latest recension — integrity is not currency. The root itself is only as fixed as its own pinning: its sections are witnessed, and its history lives in the repository's public record.
Not project canon. The single-file specification does not define the wiki shape, and no vow speaks of it. Each leaf is fully governed by the specification; the shape over them is this note's subject, offered as a convention with receipts, not as canon.
Two digest rules exist in the record, and they are not the same. The laboratory probe's cross-file instrument used a rolling seeded digest; the shipped public rule is the flat colon-join stated in § 2, chosen because it is checkable in one line of any language. The sealed probe therefore attests the mechanism class — a root digest over per-leaf witness sets catches what per-section witnesses cannot — not the shipped rule's exact bytes. This note names the shipped rule doc-pin v1; the shipped verifiers implement exactly it.
One hop, by construction. The shape specified here is root → leaf. A leaf that is itself a root — a wiki of wikis — is arithmetically straightforward and entirely unverified; no instrument in the record checks a grandchild.
Live selection at depth is an open frontier. The structure's costs are proven; a live model's ability to choose the right branch at depth, under adversarially answer-free summaries and zero slack, failed its pre-registered floor — while never fabricating (it refused or exhausted, zero wrong answers). Well-summarized wikis drilled at depth remain the unmeasured middle ground.
No cheapness claim below the map's own weight. Where the corpus is small enough that its map is a large fraction of it, ordinary search is cheaper, and this note says so (§ 4, last receipt).

From the specification note The Wiki Shape · § 7 of 8

6. Building your own wiki

The shape asks almost nothing: conformant leaves, one root, one attribute per shelf entry. What separates a wiki a model navigates well from one it fumbles is authoring discipline, and the record supports four rules.

Summaries route; they do not testify. Nothing certifies a manifest summary against its section — the witness covers bytes, never the gloss. So write each summary as a routing predicate: the answer to “what question should send a reader here?”, never a substitute for reading the section. If a workflow has a model draft your summaries, prompt it with exactly that question — “what would someone be looking for when they need this section?” — rather than “summarize this section”; the two produce different text, and only the first one navigates. A summary that makes a claim is lending the claim no authority: the authority lives in the witnessed section it points to. The one deep-drill run that failed its selection floor did so under summaries built to be answer-free; the runs with honest summaries recovered everything they were asked for.
Size the branching; split levels, not lists. One level of structure buys a factor of about B. Keep any single manifest at a size a model absorbs trivially; when a manifest outgrows an easy read, add a level rather than growing the list. Promote a section to its own leaf when it earns independent traffic — in this shape the promotion moves a document boundary without breaking a single address, because the shelf entry links a file and pins its ordered witnessed section content, and every fragment id survives.
State the rule in-band. A leaf should say, in a section of its own body, how to verify it; the root states the pin rule the same way (as this project's published root does). A file that leaves the wiki still explains itself — that property was demonstrated, not assumed: a lone leaf in an empty directory verified from itself, and blind readers found and used its in-band rule.
Honor the pin-churn law. Any edit to a leaf's witnessed section content changes that leaf's pin. Recompute the entry and rebuild the root in the same change, or the shelf truthfully reports what it is designed to report: that a leaf no longer matches its pin. A stale pin is not a false alarm; it is the mechanism working. (Edits outside the witnessed spans — ids, manifest gloss, chrome — do not move the pin; see § 5 for what that means.)

Keep every leaf's manifest at the top of its file. The resident-map mechanism (§ 3) depends on the map being reachable by a bounded read of the head; bury the nav and the shape still verifies, but the cheap approach dies.

From the specification note The Wiki Shape · § 8 of 8

7. Apparatus

The receipts of § 4, named to their repository paths in the project's laboratory record:

[W1] The multi-file wiki probe — experiments/probes/llm-wiki-doc-html/ (PREREG sealed prereg-llm-wiki-doc-html-20260630; RESULTS carries the post-seal adversarial recensions). Tamper-evidence, the re-seal catch, isolation self-verification, retrieval parity. The probe's full account, carried as written, is on this shelf: The Wiki That Witnesses Itself.
[W2] The blind drill and its control — experiments/probes/tracer-nested-manifest/ (sealed prereg-tracer-nested-manifest-20260620-r2; run leg in SUMMARY.md).
[W3] The read-cost law and the growth invariant — experiments/probes/nesting-scale/SCALE_RESULTS.md (deterministic; reproduce with python scale.py --max 100x).
[W4] Flat residency and the selection frontier — experiments/probes/bounded-return/RESULTS.md with LIMITS.md (run-02, seal of record in sealed/run02/SEAL.json).
[W5] The small-corpus bound — experiments/probes/claude-html/RESULTS.md (sealed prereg-claude-html-20260628), Test 1 recall table.
[W6] The published root this note describes — wiki.doc.html, whose in-band about section states the pin rule this note names doc-pin v1.

The verifiers:

python tools/verify_wiki.py  documents/wiki.doc.html   # the serialized shelf + every doc-pin entry; documents judged by the Core reader
node   tools/verify_wiki.mjs documents/wiki.doc.html   # same check, independent implementation
python tools/verify_wiki.py  --selftest                # prove the twenty-two teeth on built fixtures
node   tools/verify_wiki.mjs --selftest
# A clean run prints a VERIFIED SHELF block — every checked href with its full
# pin — and states that presentation was not checked. Compare that list with
# the shelf the page presents; that comparison is the reader's step.
# The receipt also prints the SHA-256 sampled from the resolved Core-reader
# file before invocation, for comparison against the published seals — a
# fact it states, not an authenticity it can prove (a receipt cannot
# authenticate itself), and file stability during the run is not checked.
# the Core reader is found beside the tool or in the working directory;
# override with --core <path> or DOC_HTML_CORE_READER. None found = refuse.

Provenance and status. Drafted 23 July 2026 in the project's writing room as a specification note for the wiki shape's first public showing; reviewed in council and published with that showing. This document is itself a conformant manifest-first doc.html — run a shipped Core reader on it — and its own doc-pin, computed by the rule it specifies, is carried on the shelf of the wiki of witnessed documents. It moves no canon; any promotion of the shape toward canon is the Operator's and the council's, not this note's.