How the Book Works

The Book is the single source of truth for everyone working in network-access — engineers, agents, and future collaborators. It answers the questions a new person or a fresh agent would ask: what are we building, how does it fit together, what decisions have been made and why, and how do we work day to day. It is explicitly modeled on handbook-first practice (GitLab, Oxide), Diátaxis, and MADR/ADR supersession discipline.

This page explains how the Book itself is structured, maintained, and protected.

The three layers

The repo has three distinct layers, each with a different purpose and a different relationship to git:

notes/   (gitignored, local)      ── SCRATCH ── raw thinking, brainstorm specs,
   │                                             plan drafts, research, experiment logs
   │  ⇧ deliberate PROMOTION (skill-assisted, PR-reviewed)
docs/    (git, curated)           ── THE BOOK ── Diátaxis-organized single source of
   │                                             truth; built into a Starlight site + llms.txt
   │  read-first / maintained-by
AGENTS.md + .claude/              ── THE SCHEMA ── the constitution: how agents read and
                                                   tend the Book (rules, skills, hooks)

notes/ is where thinking happens. It is gitignored and never committed. Superpowers plans, research spikes, brainstorm specs — they all land in notes/. docs/ is where truth lives. It is curated, git-controlled, and protected by gates. The schema layer (AGENTS.md, .claude/settings.json, .claude/skills/) is the constitution that tells agents how to read and tend the Book.

The anti-corruption boundary is the notes/ → docs/ crossing. Nothing crosses it by accident. Crossing it is an act — a promotion PR, described below.

Canon vs. scratch

Everything in docs/ is canon: peer-reviewed, single-homed, machine-checked. Every page has one home and one owner. Contradictions cannot silently coexist because there is only one place to look.

Everything in notes/ is scratch: disposable, local, unreviewed. Drafts belong in notes/specs/. Research spikes belong in notes/research/. Plans belong in notes/plans/. When a draft reaches a verdict worth keeping — when it has been distilled, reviewed, and made permanent — it gets promoted into the Book. When it does not, it is discarded or left in notes/ without consequence.

This boundary is what keeps the Book sacred while many sessions run in parallel. Agents cannot silently corrupt canon because canon-writing is blocked or warned; the only sanctioned path into docs/ is through a deliberate skill invocation and a PR.

The rooms (Diátaxis)

Canon markdown is organized by Diátaxis register — each page serves exactly one purpose. The rooms are:

Room	Register	Holds
Start Here (`/start-here/`)	tutorial / explanation	The narrative: what we’re building, why, the arc. Show-not-tell onboarding.
Vision & Principles (`/vision/`)	explanation	North star, principles, invariants, tradeoffs, whys and why-nots.
Architecture (`/architecture/`)	reference	Reality Kernel, data model, topology engine, agent runtime — each links its ADR.
Decisions (ADRs) (`/adrs/`)	reference + explanation	Architecture Decision Records, governed by ADR-0000.
How We Work (`/how-we-work/`)	how-to	Runbooks: deploy, JIRA sync, the agent dev loop, how to promote a note, how to write an ADR, how the Book works.
Patterns & Conventions (`/patterns/`)	reference	Dos/don’ts, coding patterns, gotchas (Vinxi class-fields trap, PUBLIC_ env prefix, etc.).
Domain Knowledge (`/domain-knowledge/`)	tutorial	The fiber and oil-gas domain courses.
Experiments & Results (`/experiments/`)	explanation	Concluded spikes promoted from `notes/` when they reach a verdict.

ADRs deliberately straddle reference (the decision) and explanation (the why). Keep those registers clearly separated within each ADR record. See /adrs/ for the current index.

The lifecycle skills

Every mutation of canon goes through a deliberate, skill-assisted path. The lifecycle skills are the Book’s machinery:

Skill	Intent
`book-promote`	Distill a `notes/` draft into a canon page in the right room; update the room index; open a promotion PR.
`book-new`	Author a fresh canon page directly (no notes draft); wire frontmatter, Diátaxis register, room index.
`book-update`	Revise an existing canon page in place, keeping cross-refs and the room index coherent. ADRs are exempt — use `book-adr` to supersede.
`book-retire`	Deliberately remove or deprecate a page; record why; update back-links and the index. Prefer supersede-and-link over silent deletion.
`book-adr`	Scaffold a new ADR; update the README index; wire supersession links bidirectionally.
`book-lint`	Health check: broken links, orphan pages, missing frontmatter, ADR supersession integrity.
`book`	Meta-skill: loads “how the Book works” so any agent self-grounds before editing canon.

The set is extensible. The rule is: every add, update, or delete of a canon page happens through one of these skills, never silently.

See AGENTS.md for the full skills table and the invariants.

Promotion: scratch → canon

Promotion is the ritual that crosses the anti-corruption boundary. The typical flow:

Draft lands in notes/specs/ or notes/research/ (never committed).
The author invokes book-promote with the draft as input.
The skill distills the draft into canon prose — no spec scaffolding, no open questions, no “Status: Approved” headers. Pure narrative in the author’s voice.
The skill files the page into the correct Diátaxis room, adds frontmatter, and updates the room’s index.md.
book-lint runs on the staged changes. Any broken links, missing frontmatter, or ADR integrity failures block the commit.
The change ships via PR with keeper review (see Governance below).

The source in notes/ is never committed. The Book only ever contains the distillate.

The enforcement layer

Convention rots. AGENTS.md is context, not enforcement. Deterministic gates, committed to git, enforce the guarantees team-wide across two tiers:

Claude hooks in committed .claude/settings.json — every teammate’s Claude Code session.
Git pre-commit via committed core.hooksPath — every commit, any tool (Claude, Cursor, human, CI).

#	Guarantee	Mechanism	Mode
1	Accepted ADRs are immutable — supersede, never edit	`PreToolUse` (Edit/Write) on `docs/adrs/NNNN-*.md`	block → use `book-adr`
2	`notes/` never enters git	`.gitignore` + `pre-commit` rejecting staged `notes/**`	block
3	Writing canon is deliberate	`PreToolUse` on `docs/**` injects a reminder: this is canon; prefer `book-promote`; scratch goes to `notes/`	nudge
4	Every session self-grounds	`SessionStart` prints read-first order and the canon/scratch rule	inject
5	No mess lands (dead links, orphans, ADR gaps)	`Stop` hook + `pre-commit` run `book-lint` if `docs/**` changed	warn in-session / block on hard failures at commit
6	Constitution stays lean	`PostToolUse` on `AGENTS.md`/`CLAUDE.md` warns if > ~200 lines	warn

Hard blocks (#1, #2, #5) cover the irreversible and mess-making moves. Nudges (#3, #4, #6) cover the frictionless guidance. Strict where it counts; low friction elsewhere — so nobody disables it.

Governance

The Book has a single keeper: Nikhil, enforced via CODEOWNERS on docs/, AGENTS.md, and CLAUDE.md. Every change to canon requires a keeper review before merge.

The operating principle is handbook-first: if it is not in the Book, it is not canon. Everything enters via PR. Nothing enters by accident.

For concurrent agent work: agents isolate in notes/ or worktrees, never auto-write canon, and the keeper compacts into the Book via reviewed PRs. Facts are never auto-merged.

For architecture decisions specifically, see the ADR supersession discipline documented in /adrs/ (ADR-0000).