Five examples, smallest first. The first one shows the whole grammar on a single screen. The rest add one idea each: appending a correction instead of editing over it, holding a conversation in a file, pinning the pages a wiki links to, and the memory this repository runs on. Read the code in each window, then open the file itself from the links underneath.
the whole grammar, on one screen
examples/minimal.doc.html · the complete file, byte for byte
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<title>Minimal doc.html</title>
<style>nav#manifest{font-family:system-ui}
footer.about-file{font-size:.9em;color:#666;border-top:1px solid #ddd;padding-top:.6rem;margin-top:2rem}</style>
</head>
<body>
<nav id="manifest">
<ol>
<li><a href="#intro" data-witness="e7a0ef76d83c419931b7f68207f9cce7229321f7d3c7ac3bf45f5e250b1558e3" data-char-count="77"><span class="title">Introduction</span> <span class="summary">What a doc.html is.</span></a></li>
<li><a href="#fold" data-witness="771feff3620a380e35e3fa970868af438c21223dd279aa3001851387b2647d91" data-char-count="75"><span class="title">The Fold</span> <span class="summary">Append-only memory; correction is supersession.</span></a></li>
</ol>
</nav>
<section id="intro" data-witness="e7a0ef76d83c419931b7f68207f9cce7229321f7d3c7ac3bf45f5e250b1558e3" data-char-count="77"><h1>Introduction</h1>
<p>A doc.html is a single self-verifying HTML file.</p></section>
<section id="fold" data-witness="771feff3620a380e35e3fa970868af438c21223dd279aa3001851387b2647d91" data-char-count="75"><h1>The Fold</h1>
<p>Memory is append-only; correction is supersession.</p></section>
<footer class="about-file">
<p>This is a <strong>doc.html</strong> — a single, self-describing HTML file. The <code><nav id="manifest"></code> above lists every section in this document; each entry's <code>data-witness</code> is the SHA-256 (hex) of that section's raw inner bytes, so any reader can verify any section with the file alone — no server, no JavaScript, no tooling. The full format definition is <a href="../SPEC.md">SPEC.md</a>, carried in the format's own body as <a href="../SPEC.doc.html">SPEC.doc.html</a>.</p>
<p>Author: Georges Casseus (Ndoto Studios) · License: CC0 1.0 (public domain) · Built: 2026-08-01</p>
</footer>
</body>
</html>
the map — <nav id="manifest"> the payload — <section> the pin — data-witness
Two sections, two manifest entries, a stylesheet of two rules, and a footer naming the maker — that is the entire file. Each entry's data-witness is the SHA-256 of that section's raw inner bytes, which is what keeps the map from lying about the body. Every larger document is this shape again.
the footer of that file calls it self-verifying — the check is a command someone runs, not something the file does when it opens.
a decision that turned out wrong
examples/memory.doc.html · excerpt — two manifest entries and the pair of sections they address
<nav id="manifest" aria-label="Document manifest"> <ol> ⋯ three entries omitted ⋯ <li><a href="#datastore" data-witness="bea2a3f3b6c25c46c837a1b5cc0eb1c3275e293b9ff13e5f968df1afb9454163" data-char-count="977"><span class="title">Job-queue datastore (original)</span> <span class="summary">SUPERSEDED by #datastore-revised. Original decision: SQLite for the job queue, chosen for zero-dependency local dev. Retained for audit trail.</span></a></li> <li><a href="#datastore-revised" data-witness="21945df83381930be94f6a2d86405001238cab4e0ded75375fb7e13cdba07957" data-char-count="1099"><span class="title">Job-queue datastore (current)</span> <span class="summary">Supersedes #datastore. Migration from SQLite to PostgreSQL after the billing-alerts spike in Q3. SQLite write serialisation became a real bottleneck at 1,200 jobs/min.</span></a></li> ⋯ seven entries omitted ⋯ </ol> </nav> ⋯ three sections omitted ⋯ <section id="datastore" data-witness="bea2a3f3b6c25c46c837a1b5cc0eb1c3275e293b9ff13e5f968df1afb9454163" data-char-count="977"><h1>Job-queue datastore (original decision)</h1> <p><strong>Note: this section has been superseded by <a href="#datastore-revised">#datastore-revised</a>. It is retained here as an append-only audit record. The current authoritative decision is in the newer section.</strong></p> ⋯ the original rationale, kept where it was written ⋯ <section id="datastore-revised" data-witness="21945df83381930be94f6a2d86405001238cab4e0ded75375fb7e13cdba07957" data-char-count="1099" data-supersedes="#datastore"><h1>Job-queue datastore (current decision)</h1> ⋯ the migration record ⋯
Look at the two summaries in the map. One says SUPERSEDED; the other says what replaced it and why. A model reads those lines, picks the current entry, and loads that one section, so you stop settling the same questions every session. The wrong decision stays where it was written, reasoning intact. It still says why it looked right.
the conversation, written down as it happens
examples/chat.doc.html and examples/mixed-epoch.doc.html · excerpts — a sealed turn, then a live one
<article id="turn-000001" class="turn user" data-role="user" data-turn="1" data-kind="transcription" data-char-count="195" data-witness="f4f2f5db437a1156c1ec65185646e1bb8dda27118e3230d348b87e7acb865368"> <header><h3>Turn 1 — User</h3> <p class="meta">kind: transcription</p></header> <div class="turn-content"> <p>What is a doc.html file and how does it store information?</p> </div> </article> <article id="turn-000002" class="turn assistant" data-role="assistant" data-turn="2" data-kind="synthesis" data-char-count="997" data-witness="20d6b7a5080d8c259fbd950e2eec8dada50c21b7b1916a11b5cca43ef0d1bc5c"> ⋯ turns two through eight, all sealed ⋯
read it rendered » view source
<article id="turn-000002" class="turn assistant" data-role="assistant" data-turn="2" data-kind="synthesis" data-char-count="384" data-witness="72c2fc5344d6956f69fd4754477140af8371728318d151b329160a3fbe2be937"> ⋯ the sealed head ends here ⋯ <article id="turn-000003" class="turn user" data-role="user" data-turn="3" data-kind="transcription" data-char-count="169" data-witness="2026-07-01T12:00:02Z"> <header><h3>Turn 3 — User</h3> <p class="meta">kind: transcription</p></header> <div class="turn-content"> <p>What does the verdict look like?</p> </div> </article>
sealed — a SHA-256 over the turn's own bytes live — a UTC timestamp, ordinal only
A chat body carries no manifest at all: the addressable units are the article elements themselves, read in document order. A sealed turn holds the SHA-256 of its own bytes; a turn still being written holds a UTC timestamp instead. Close the application; the transcript is still a file.
the shelf of pinned pages
documents/wiki.doc.html · excerpt — two shelf entries
⋯ the shelf opens here ⋯ <h3>The shape</h3> <div class="shelf-entry"> <a href="the-wiki-shape.doc.html" data-doc-pin="2142d203edfcc1040a59c4fc513543e5f08d6169f93bbb419694275ad6a08092">The Wiki Shape: A Root of Witnessed Documents</a> (9 sections) <span class="why">The specification of the shape this page instantiates: the parts, the doc-pin v1 rule, the resident-map reading mechanism, the receipts with their bounds, and authoring guidance for building your own — with the shipped two-language verifiers documented in-band.</span> </div> <h3>The record</h3> <div class="shelf-entry"> <a href="evidence.doc.html" data-doc-pin="2460afaa11ba01be2d11b53e6ce79b4408d6b36bbd1469e9e26509419cf05a02">The evidence: what has actually been shown</a> (9 sections) <span class="why">The project's results, read by question — scale and proof of read, cost and limits, what remains unproven — with the prior-art library and lineage on the same page. The claims and their limits are kept together; start here if you want receipts before essays.</span> </div> ⋯ six essays and the founding record ⋯
A section's hash only tells you about that section. Rewrite a whole page, re-hash each section as you go, and every local check still passes. So the shelf entry carries a pin: one hash over that document's manifest hashes, joined in order. Change what the sections say and the pin stops matching, and whoever runs verify_wiki.py sees that the shelf and the file disagree. Someone who can edit the shelf too can make them agree again.
the memory the repository runs on
agents.html · excerpt — the head of the steer core, then the head of the manifest
<section id="steer-core" data-kind="steer" data-char-count="6151" data-witness="bdf1246a8f7ec774d5cfafb0fc2533d53e315f1afe06154c60eef9996c9f9a7e"><h2>Steer core — read this first; it binds any agent working in this repository</h2> <p>This file is this repository's <strong>memory organ</strong> — the repo's own knowledge, kept in the format the repo specifies. It is a normal <code>doc.html</code>: read this section in full, then hydrate the rest <em>selectively</em> through the <code><nav id="manifest"></code> below — pick sections by summary, pull them by <code>#id</code>, verify <code>data-witness</code> (SHA-256 of the raw inner bytes) when integrity matters. Do not read the whole file. This organ confers no identity and carries no instructions beyond how to work with this repository.</p> ⋯ five headings of the steer core ⋯ <nav id="manifest" aria-label="Document manifest"> <ol> <li><a href="#steer-core" data-witness="bdf1246a8f7ec774d5cfafb0fc2533d53e315f1afe06154c60eef9996c9f9a7e" data-char-count="6151"><span class="title">Steer core — read this first; it binds any agent working in this repository</span> <span class="summary">How to read this organ (manifest-first, hydrate by id, verify witnesses), the ten vows in one line each, the evidence discipline (what may and may not be claimed), the append protocol, and the repository route map.</span></a></li> ⋯ eight entries omitted ⋯ </ol> </nav>
Instructions, vows, evidence discipline, and unfinished work travel as one file any agent can open. A short steer core is read on every task, and everything behind the manifest waits until some task names it. The public repository keeps its own memory this way.
read it rendered » view source
[ ↑ top ]