The plain-text document is now the expensive one

Prose was never the best explanation. It was the affordable one

Markdown is good. Google Docs and Notion are good. They are fast to write, they diff, they survive tooling changes, and a reader with no context can open one. None of that is in dispute here, and a document that pretended otherwise would be arguing with the wrong thing.

The claim is narrower and harder to escape: for explaining a system, a rich HTML page beats all of them, and it always did. A diagram that responds to a click shows a mechanism that a static picture can only assert. An example the reader can run answers the question the paragraph was going to raise. A state machine the reader can step through settles an argument that three paragraphs of prose leave open. Nobody has ever preferred the flat version on its merits.

They preferred it on its cost. A rich page was a small application: a build, a bundle, a stylesheet that had to work in both themes, and a week of someone's attention. An internal architecture document is read by about a dozen people. A week of engineering time to serve twelve readers is not a defensible trade, so the flat version won every time, and the reasoning became invisible — a convention rather than a calculation.

The cost that replaced it is collaboration, not authoring

Removing the authoring cost exposes the cost that was hiding behind it. Google Docs is not chosen for its typography. It is chosen because a document is a conversation: somebody comments on a sentence, somebody else suggests a rewrite, and an owner decides. A static HTML file has none of that. It is a better explanation and a worse workspace, and the workspace is why teams keep reaching for the worse explanation.

No column wins. That is the problem worth solving, and it is the one Archon takes on: the right-hand column is the better artifact, and it is missing exactly two rows. Adding those two rows without losing the two it already wins is the whole design.

The honest counter-argument, stated first. A page an agent writes in an afternoon is a page nobody has read line by line. Prose fails visibly; a broken interactive element fails by quietly showing the wrong thing. This is a real cost of the position and it is not fully paid off. The partial answer is in Design: the build refuses to emit a document with an unbalanced tag, an unfilled placeholder or a duplicate section id, and it prints an anchor report on every rebuild. That catches structure, not meaning.

Degradation is the design, not the fallback

Each layer is inlined into the artifact by its own placeholder in layout.html, and an absent asset contributes zero bytes — not an empty wrapper, not a blank line. A document built with no features is byte-for-byte the document that existed before the feature slots were added. That property is what makes the additive claim checkable rather than aspirational.

The client contract is one mechanism, not four. session.js calls /api/session once and sets data-session on the root element; CSS reveals controls; every other module listens for a session event and nothing polls. data-session is a rendering hint and never a security control. A reader can set it in the developer tools and make an edit button appear. The button calls a function, the function resolves the caller's real role, and the function returns 403.

What this buys that a hosted document does not

Where this is weakest. In standalone mode there is no repository, so the overlay is the document and nobody reviews it. That is the price of having no repository, and it is why export-back had to be built before editing rather than after. Design says how both modes work and what each one gives up.

Layer 1: data-aid is the one block identity in the platform

anchors.ts scans each section into a list of block elements, normalises their text (collapse whitespace, trim), and diffs that list against the previous build's list with a sequence matcher. A new block is minted "a" + sha1(text)[:8]. Everything else is carried:

Then one move pass: an orphaned id whose exact text reappears elsewhere in the section reclaims that block. Sequence alignment respects order, so two similar siblings cannot swap. And the build prints a report on every rebuild — how many blocks kept an id, how many were re-anchored, how many moved, how many were orphaned, with the orphans named. A writer who orphans twelve threads finds out at the moment they do it, not when a reader complains.

Two rejected alternatives are worth stating, because both look reasonable. An id derived from position — sha256(doc|section|ordinal), or "p:7" — renumbers every block below an insertion, and every anchor below it silently moves. That failure is invisible, which is worse than being wrong loudly. A quote with no block id fails the moment somebody rewrites the quoted words, which is precisely the change that made the comment worth reading.

Layer 2: the quote, resolved in the browser, degrading in four visible states

An anchor stores block, the normalised exact text, up to 32 characters of prefix and suffix, and a start offset used only as a tiebreak. The page finds the block by data-aid, searches its normalised text, and scores hits by common affix length minus a gentle distance penalty. There is no fuzzy matching: it hides failure instead of reporting it, and it blocks the main thread on long documents with short generic quotes.

Anchor state is never stored. The client computes it at read time, every time. A stored state goes stale on the next rebuild, and the whole point of two layers is that they degrade independently. moved requires a unique hit; nothing is ever silently relocated.

One consequence sharpens the design more than any other rule. The builder is JavaScript, so norm() and the block scanner are one module compiled once and inlined into the page. Under earlier builders this code existed twice — in Python the two whitespace sets genuinely differed, and in Rust they were kept in step by a CI fixture whose only job was to prove two languages agreed. There is now nothing to drift. This is the single largest benefit of the builder being JavaScript, and a client that reimplements norm() "for convenience" recreates the entire problem.

Two modes, selected by configuration and never by a request

An edit is an overlay keyed by aid, applied over the built HTML. Promoting that overlay to a durable source is a separate, explicit act, and the two modes differ only in what that act does. An overlay replaces the contents of a block and never the block's identity, which is why editing cannot break anchoring; a DOM patch that rewrote block boundaries would be forbidden in both modes.

The mode is chosen by four environment variables and nothing else. With DOCS_REPO absent and none of its three companions present, the service is standalone. With DOCS_REPO present, all of DOCS_GITHUB_TOKEN, DOCS_BOT_EMAIL and a valid branch must validate. Partial configuration is fatal in both directions: a configured repository never falls back to standalone, and standalone never borrows a repository value. Both produce a 500 with the stable code invalid-state rather than a quiet degradation, because the quiet degradation would mean writing a reader's edit somewhere nobody is reviewing.

The cost of standalone mode, said plainly. The overlay is the document, and nobody reviews it. That is not an oversight to be fixed later; it is what "no repository" means. It is also why promotion had to be built before editing rather than after, and why a direct edit in standalone mode is restricted to a decider while repository mode lets any member propose one.

The storage boundary: nothing durable is only in the database

State lives in Netlify Blobs, one store named doc-state, strong consistency, one blob per record — never a shared mutable array. Two readers appending to one array lose a comment; a compare-and-swap loop prevents the loss but makes every write on a document contend with every other write on that document, and a live review session is exactly when concurrent writes happen. The permanent six-hex id from doc.json is the key, never the slug and never the directory name, so renaming a document orphans nothing.

The pending edit is the clearest statement of the boundary. It is a receipt carrying a baseHash of the text it replaced, and /api/pending drops any entry whose baseHash no longer matches the deployed build's manifest. When the pull request merges and the site rebuilds, the hash changes and the entry disappears on its own; there is no cleanup job. If Blobs lost everything tomorrow, no published content would be lost — comments and grants would be, and that is the honest limit of the claim.

The route table

Each function declares its own path in export const config. There is no redirect table and no /.netlify/functions/ path in use; /api/* is excluded from the edge gate because every function gates itself. That is a division of labour, not a hole: the edge gate decides who may see HTML, and it never decides who may write.

Four rules that hold across every endpoint

An author field in a request body is an impersonation attempt, not an input. Several endpoints accept author, email and name in the body and discard them. Every actor stored anywhere comes from the session.

Every mutating handler verifies the origin first. The identity token is a cookie, so every POST, PATCH and DELETE is otherwise exposed to cross-site forgery. requireOrigin(req) is the first statement, not a middleware someone can forget to register.

Failure is uninformative on purpose. The sign-in routes collapse a bad state, a bad PKCE verifier, a refused consent and an unexpected scope into one /login/?status=expired, because a message that distinguished them would tell somebody probing the callback which half of the transaction they had guessed right. /api/suggestion answers a withdrawal by a non-author with 403 if they can read the document and 404 if they cannot, so the status code never reveals that a suggestion exists.

Absence is a status code, not an error. With no ABLY_API_KEY, /api/realtime-token returns 204. That single switch is the entire degradation story: a file opened from disk stops at the protocol test, an embedded copy never gets a session because the CSP blocks /api/session, and a standalone site works untouched until its owner decides otherwise.

The capability matrix

Five roles, and the row is what an endpoint actually checks — never the role name.

Resolution has a fixed precedence: the bound owner subject, then an explicit grant by subject, then an unexpired invitation matched on the caller's verified email, then the document's own allowedDomains list — exact, case-insensitive, full-domain equality against a verified address, yielding viewer and never more — then none. A site-wide PUBLIC_DEFAULT_ROLE tier used to sit at the end and is gone: with open sign-in, "any other authenticated caller" is the internet. "Verified" is load-bearing: sign-in is open to anyone with a Google or GitHub account, so anyone can present any address to an identity provider, and the provider's verification claim is the only thing standing between an invitation and whoever guessed the invited address. An unverified match resolves none and consumes nothing, and an identity carrying no address at all is a valid session that matches no invitation.

Sharing is opt-in — a document with no access record behaves exactly as it did before roles existed, and shows no share panel. The first owner is captured once from the DOC_OWNERS environment variable on that person's first sign-in, by a create-only write, so ownership is not first-come and not seizable from the client.

threadControl: "own" is checked inside the compare-and-swap, not before it. A commenter resolving somebody else's thread is refused against every fresh draft the retry loop reads, and denial takes precedence over the no-op shortcut — otherwise a silent 200 for "already resolved" would tell a non-owner the thread's current status.

Each ticket is written before its code, and names its file surface

The forty-two specifications live in docs/tickets/ as P1-A through P4-T. Each one declares what it changes, what it depends on, and how it is verified. Above them sits docs/research/00-integration-plan.md, which rules: nine research documents were written in parallel, they agreed on the large facts and disagreed on twenty-six concrete points, and the plan lists every disagreement with the ruling and the reason. Where the plan and a research document differ, the plan is correct.

"Frozen" would be the wrong word, and the record says so. Specifications freeze contracts between tickets — a session projection, an event shape, a client surface — so a downstream ticket cannot renegotiate them. The plan itself was revised twice and says where. Ruling #10, "there is no editor role", was reopened when a share panel became a requirement. P4-E was retired outright: a bearer share link cannot attribute a comment, because a stored comment needs a proven subject, and it cannot be revoked. The letter gap between P4-D and P4-F is that decision, left visible.

Four phases, and what a reader has at the end of each

The dependency graph, and its longest chain

Three tickets have no dependencies at all and start immediately: P1-A (permanent ids), P1-C (the identity contract) and P1-E (Netlify configuration). Everything else names its predecessors. The graph is wide in the middle and narrow at both ends.

The tail is the expensive part, and it is expensive for a reason worth stating: P4-B, P4-M and P4-N cannot run in parallel because they share edit.mjs and gitedit.mjs. P4-B builds the edit write path, P4-M wires capability enforcement into every existing write handler, and P4-N then extracts the single apply path so that accepting a suggestion and saving a direct edit cannot drift into two different conflict checks. Doing P4-N first would mean extracting a shared path from one caller, which is a guess rather than an extraction.

A second chain of comparable length runs through sharing — P1-C → P2-B → P2-G → P3-H → P3-J → P4-J → P4-K and P4-L — and it is genuinely parallel to the editing chain, which is what phase 3 being ten wide buys.

Open questions

Each of these is a decision that is not the author's to make alone, written so a reader can answer one without reading the rest of the document. They are ranked by how much the answer changes the design, not by how hard they are.

What is deliberately not being built

• A second identity vendor. There is one, and it is Auth0 — which brokers Google and GitHub, so a visitor continues with an account they already have and Archon never sees a password. This entry originally read "no GitHub OAuth, no Auth0, no single sign-on"; the platform now has all three through one broker, and the sentence is kept rather than deleted because what it was defending is still true: one identity vendor, chosen once. No second broker, no per-deployment provider matrix, and still no multi-factor authentication of Archon's own — that is the identity provider's to enforce, and an organisation that mandates it configures its own tenant.
• Cross-document features. No "shared with me" list, no cross-document revoke, no unread count and no full-text search of comment bodies. The storage decision rules these out, and they were cut deliberately rather than deferred.
• A diagram library. It renders one fixed theme, cannot be checked before publishing, and needs a script the CSP blocks. Diagrams are hand-built from the template's components.
• Conflict-free merging of two edits to one block. Two people editing the same block is a genuine conflict and the second writer is told. Merging the text would be the fix that hides the problem.