brane 0.0.2 → 0.3.0

package/protocols/wiki.md

@@ -0,0 +1,438 @@
+# /wiki [guidance]
+
+Maintain and query a flat, richly interlinked markdown wiki at `./wiki/`
+in the current fold. The wiki is the human operator's second brain for
+this project — the agent's job is to *answer from it*, *refresh it
+against current reality*, and *flag drift*, but never to decide what it
+contains.
+
+## Default is read-only
+
+**`/wiki` without imperative write-intent is a query.** The agent reads
+`wiki/*.md`, answers the operator's question as a narration, and does
+not modify any files. This is the primary mode — treat writes as rare
+and deliberate, not the norm.
+
+Writes happen only when the guidance contains an unambiguous imperative:
+`update`, `refresh`, `rewrite`, `apply`, `write`, `fill`, `sync`,
+`propagate`, or equivalent. "Tell me about X," "what does the wiki say
+about Y," "is the page on Z accurate" — all read mode.
+
+When in doubt about intent, stay in read mode and narrate what you
+*would* change. The operator can re-invoke with explicit write guidance.
+
+## The agent does not invent concepts
+
+The failure mode this protocol exists to prevent is the agent deciding
+that a new concept deserves a wiki page. When the agent, midway through
+writing, notices a sub-idea and spins off `sediment-based-superintelligence.md`
+as a companion to `sedimentary-superintelligence.md`, the ontology has
+been corrupted from inside — the operator now has two pages for one
+concept and no way to tell which is canonical without reading both.
+
+The rule is about *concepts*, not filenames. The operator is the source
+of the concept set; the agent fills, refreshes, and cross-links the
+pages those concepts get. Filename spelling is an implementation detail
+the agent handles (kebab-case slugs, consistent with existing pages),
+but the concept itself must come from the operator.
+
+Cases:
+
+- **Operator introduces a concept in imperative guidance** → free to
+  create a page for it. The concept can be named directly (`sedimentary
+  superintelligence`) or by filename (`sedimentary-superintelligence.md`);
+  either form is authorization. Create the file, draft from raw sources,
+  apply the page rules. Don't pre-narrate a draft and ask the operator
+  to paste — that's too indirect when the authorization is clear.
+- **Operator asks a question that mentions a concept with no matching
+  page** → read mode. Answer from raw sources. Note the gap in a
+  footer, but do not create a page — a concept mentioned in a question
+  is not a concept the operator has asked to be added to the wiki.
+- **Agent encounters a novel concept while refreshing or answering** →
+  no new page. Mention the concept in prose where relevant; if it
+  seems to deserve its own page, surface that as a suggestion in the
+  narration for the operator to decide.
+- **Stub file already exists** (just `# Foo` or a seed line) → refresh
+  mode fills it. The stub's existence is the operator's signal that
+  this concept belongs in the ontology.
+- **Renames and deletions** → propose in narration, never apply on
+  disk. These are ontology decisions.
+
+Creating the `wiki/` directory itself is permitted the first time a
+page creation is authorized — it's implied by the first authorized
+page, not a concept decision of its own.
+
+## Voice and register
+
+Wiki pages are reference material, not essays, advocacy, or marketing
+copy. Write in a neutral, descriptive, third-person register — closer
+to a Wikipedia article than to a product pitch or a personal manifesto.
+The reader should learn what the subject *is* and what has been
+*claimed* about it, not be sold on why it matters.
+
+Concrete rules:
+
+1. **Attribute positions; do not assert them.** Anything that reflects
+   the operator's (or anyone else's) argument, preference, or
+   conjecture should be presented as theirs, not as fact. Use
+   "Newman argues that…", "is described as…", "has been proposed as…",
+   "is characterized as…" rather than stating the claim flat. Facts
+   from code, config, external sources, or reproducible observations
+   can be stated directly; opinions cannot.
+
+2. **Cut editorializing phrases.** Words and phrases that assert
+   importance or deliver a rhetorical punch without adding information
+   don't belong: *load-bearing*, *the joke is*, *keeps X honest*,
+   *makes the form work*, *the real play*, *escape velocity is
+   literal*, *it's not metaphor — it's*, *what this unlocks*, *designed
+   to X*. If the underlying claim is substantive, state it plainly and
+   attribute it; if it's decoration, remove it.
+
+3. **Flag metaphors as metaphors.** When an analogy is allusive rather
+   than structural, say so. "Newman sometimes calls this *X*, by
+   analogy to…" beats asserting the analogy as if it were definitional.
+   A metaphor used by the subject's author once in passing should not
+   become the page's organizing frame.
+
+4. **Avoid sales-pitch sections.** *Why this matters*, *What this
+   unlocks*, and similar sections are advocacy shapes. If the content
+   is genuinely informative, it can live as a *Rationale* or
+   *Background* section framed descriptively. If it's only advocacy,
+   cut it.
+
+5. **Describe, don't defend.** If the subject is a proposal, call it a
+   proposal and summarize it. Resist the urge to argue *for* the
+   proposal inside the description of it; that's what provenance links
+   are for — the reader can follow the citation to see the argument
+   as the author made it.
+
+6. **Preserve citations regardless of register.** The tone of the
+   prose is independent of provenance requirements. Every non-trivial
+   claim still carries its `nid:seq` or file-path citation. Neutral
+   voice is not a reason to drop citations; it is a reason to let the
+   citations do more of the work.
+
+7. **Don't anthropomorphize the subject into a hero.** Subjects are not
+   "bold," "radical," "unlike any other tool" — not even when the
+   source material says so. Leave that framing in the cited source.
+
+8. **Don't inflate the operator's epistemic footprint.** Neutral-voice
+   attribution creates a specific bias: every "Ben argues…" or "Newman
+   proposes…" is a claim that the operator originated the idea. When
+   agents write the wiki, it is tempting to attach the operator's name
+   to every framing, including syntheses the agent itself generated in
+   earlier narrations that the operator merely didn't object to. That
+   quietly promotes agent-generated material into operator positions.
+
+   Before attributing a claim to the operator, check its provenance:
+
+   - **Originated in a `human_signal`** → safe to attribute to the
+     operator. Example: the operator writes "a trigram is exactly
+     three words" → "Newman defines a trigram as…" is correct.
+   - **Originated in an agent `narration`, with no operator
+     pushback** → do **not** attribute to the operator. Use passive
+     construction: "has been proposed…", "a formulation that appears
+     in the narrative record…", "is discussed in the archive as…".
+     Cite the narration directly; let the reader follow the link and
+     see who actually said it.
+   - **Agent narration that the operator explicitly affirmed**
+     (e.g., the operator replied "yes, exactly" or saved it as
+     feedback memory) → attribute to the operator *if* the affirmation
+     was specifically about that claim, not about the broader reply.
+     Cite both the narration and the affirming signal.
+   - **Operator paraphrased an agent's framing back** (e.g., the
+     agent proposed "register descent," the operator used the term
+     in a later signal) → the term is shared; attribute the *origin*
+     to the agent narration and note the operator's uptake if the
+     distinction matters.
+
+   When in doubt, prefer passive or archive-anchored attribution
+   ("the term appears in the archive as…", "this framing has been
+   proposed") over naming the operator. The citation does the heavy
+   lifting; the reader can see who actually originated the claim by
+   clicking through.
+
+This register applies to **all write modes**: create, refresh, and
+targeted edits. Read-mode answers (narrations) have more register
+latitude — they are operator-facing conversation, not the wiki — but
+the page itself, once written, should read as reference.
+
+## Wiki structure
+
+Flat layout — every page lives directly under `wiki/`, with one
+permitted subdirectory, `wiki/shared/`, that is itself flat:
+
+```
+wiki/
+  index.md          # human-maintained catalog (agent never edits)
+  <page-name>.md    # one file per concept/entity/topic — fold-local
+  shared/
+    index.md        # catalog of the shared pages (agent never edits)
+    <page-name>.md  # visible from every fold that can reach this one
+```
+
+**Local and shared.** Pages directly under `wiki/` are visible only to
+agents working in this fold. Pages under `wiki/shared/` are visible to
+every fold: `list_wiki`, `read_wiki`, and `search_wiki` show another
+fold only its `shared/` pages, and reading its local page errors with
+*"local, not shared"* rather than *not found*. The brane install
+directory is a fold too, so brane's own shipped pages are simply that
+fold's `shared/`. A page's slug is its path under `wiki/`:
+`foo.md` is local, `shared/foo.md` is shared, and a citation
+(`slug#anchor`) means the same thing to every reader.
+
+**Which side a page lives on is the operator's call**, exactly like
+naming it. The agent never moves a page between `wiki/` and
+`wiki/shared/`, in either direction. Keep local pages fluid — they are
+where a fold thinks — and treat promotion to `shared/` as publication.
+
+Filenames are kebab-case and stable. Internal links use plain markdown,
+**relative to the linking file's directory** — the way GitHub and every
+editor render them: from a local page, `[x](x.md)` and
+`[y](shared/y.md)`; from a shared page, `[y](y.md)` for a shared
+sibling and `[x](../x.md)` for a local page. Do not use `[[wikilink]]`
+syntax — it only renders in Obsidian.
+
+A shared page may link to a local one, but that link is a **citation,
+not a promise**: a reader in another fold will see the target named and
+scoped ("local to fold `personal`, not shared") and cannot open it. So a
+shared page must *read* without its local links — the way a narration
+must read without the scrollback. Local → shared links are always safe.
+
+Pages should cross-link generously to other existing pages. Every link
+target must be a file that currently exists in `wiki/` (or
+`wiki/shared/`) — if the natural link target is missing, mention the
+concept in prose without linking and add a footer note: *"Could link to
+a `<name>.md` page if you create one."*
+
+## Provenance
+
+Non-trivial claims carry an inline citation:
+
+- To a narrative event: `[claude-4c7289d1:42]` (the operator's UI
+  auto-linkifies this).
+- To a protocol: the slash command itself — `/wiki`, `/LIVE_loop` — which
+  the reader linkifies into the protocol document. Never write it as a
+  path (`../protocols/wiki.md`): links that escape the wiki dir are
+  refused by the reader and render as dead text.
+- To a file path: `daemon/server.ts:215` (operator's editor auto-opens).
+- To an external source: standard markdown link with URL.
+
+Citations let future `/wiki audit` passes check whether each claim still
+holds. A page with no citations is not audit-tractable; flag that in
+audit output.
+
+## Modes
+
+### Read mode (default)
+
+Guidance is a question or statement without write-intent verbs.
+
+1. Read `wiki/index.md` if it exists, then any pages it points to that
+   seem relevant to the question.
+2. If the wiki is thin on the topic, fall back to `narrative_search`
+   over past narratives and direct file reads in the fold.
+3. Narrate the answer. Cite the wiki pages you used (`[foo](foo.md)`
+   links) and the raw sources that filled gaps.
+4. If the question is about something with no matching page, say so in
+   a footer — do not create the file.
+5. **Do not edit any file in `wiki/`.** Not even to "fix a typo while
+   you're at it." Read mode is read-only, period.
+
+### Audit mode
+
+Guidance explicitly requests an audit: `/wiki audit`, `/wiki audit foo`,
+`/wiki check for drift`, `/wiki what's stale`.
+
+1. Walk the target page(s).
+2. For each non-trivial claim with provenance: verify the cited source
+   still supports it. If the source is a narrative, sample it with
+   `listen` (`wait: false`, narrow `after`/`before`). If a file path,
+   read the file.
+3. For claims without provenance: flag them as unauditable.
+4. For internal links: verify each `[text](name.md)` points to a file
+   that exists, resolving relative to the linking file's directory.
+   Separately list links from a `shared/` page to a local page — not
+   an error, but the reader elsewhere can't follow them, so the page
+   must stand without them.
+5. Sample recent activity via `narrative_search` — look for topics that
+   would belong on an existing page but aren't mentioned there. Call
+   this out as *drift*, not as a new-page proposal.
+6. Narrate a structured report (see "Audit output" below).
+7. **No writes.** Audit is read-only.
+
+### Create mode
+
+Guidance introduces a concept with a creation imperative:
+`/wiki seed sedimentary-superintelligence.md`, `/wiki start a page on
+the LIVE loop`, `/wiki create a page about the daemon port allocator`.
+
+1. If `wiki/` doesn't exist, create it.
+2. Gather material from raw sources for the introduced concept —
+   `narrative_search`, `narrative_info`, and direct file reads.
+3. Write the page directly. Don't pre-narrate the draft and ask the
+   operator to paste it — the operator's introduction of the concept
+   is authorization to write. Choose a kebab-case filename consistent
+   with existing wiki pages; if the operator named the file, use that
+   spelling.
+4. Apply the protocol's page rules: flat layout, kebab-case links,
+   inline provenance (`nid:seq` or file paths) for every non-trivial
+   claim, cross-links to existing wiki pages only.
+5. Narrate a brief confirmation with the refresh marker (see below) and
+   a one-liner summary of what the page covers.
+
+### Refresh / write mode
+
+Guidance contains an imperative aimed at an existing page: `/wiki
+update`, `/wiki refresh foo`, `/wiki rewrite bar to include X`,
+`/wiki sync daemon.md with current server code`, `/wiki fill the empty
+stub at foo.md`.
+
+Scope the work from the guidance:
+
+- **Whole-wiki refresh** (`/wiki update`, no target): run audit first,
+  narrate the drift report, then apply fixes page-by-page, narrating
+  each page's delta as you go.
+- **Single-page refresh** (`/wiki refresh foo`): load `foo.md`, audit
+  it, rewrite sections that have drifted, narrate the diff.
+- **Targeted edit** (`/wiki update foo to mention X`): narrow edit
+  matching the guidance.
+
+Rules for writes:
+
+1. **Only edit files that already exist.** If the guidance refers to a
+   page that doesn't exist and doesn't name a filename imperatively,
+   switch to read mode and note the gap. If the guidance *does* name
+   a filename imperatively with a creation verb, use create mode.
+2. **Never edit `index.md`.** Propose index-line changes in narration
+   for the operator to apply by hand. Format:
+   ```
+   Proposed index.md entry for foo.md:
+     - [foo](foo.md) — one-line summary
+   ```
+3. **Narrate before large rewrites.** If a page will be >50% rewritten
+   or more than one page is being changed, narrate the plan first,
+   then proceed — the operator can interrupt via signal. Small edits
+   (section-level or smaller) can proceed without pre-narration, but
+   always narrate what you changed after the fact.
+4. **Backlink re-reading after any page edit.** When you rewrite
+   `foo.md`, grep `wiki/*.md` for links pointing to `foo.md`. For each
+   incoming link, re-read the paragraph surrounding the link and
+   verify the prose still accurately describes `foo.md`'s updated
+   content. If it no longer does, either fix the linking prose (if the
+   fix is mechanical) or flag it in narration for the operator.
+5. **Preserve human prose.** If an operator-authored paragraph still
+   holds, leave it untouched. Write-mode work is targeted at claims
+   that have drifted or stubs that need filling — not stylistic
+   rewrites for their own sake.
+6. **Keep citations fresh.** Every rewritten paragraph that makes a
+   non-trivial claim must carry or retain a citation.
+
+## Reality sources
+
+The wiki reflects "current reality" of the current fold. The agent draws
+reality from these sources, in rough order of authority:
+
+1. **Code and config in the fold** — the actual state of the project.
+2. **Recent narratives** — discovered via `narrative_search` and
+   `narrative_info`. Especially useful for decisions and rationale that
+   aren't expressed in code.
+3. **The wiki itself** — for topics that depend on prior synthesis
+   (e.g., design intent, history). But never cite the wiki as evidence
+   for a claim in the wiki — that's circular. Always trace to a
+   narrative or file.
+
+When refreshing, work backward from the last `/wiki` refresh timestamp
+(grep the wiki or `narrative_search` for `"Wiki refreshed"` — see
+"Refresh marker" below). Focus on narratives and code that have changed
+since then.
+
+## Audit output
+
+Structure drift reports like this (omit empty sections):
+
+```markdown
+**Wiki audit** — {page or "full"} — {timestamp}
+
+### Drifted claims
+- `foo.md`: "X does Y" — cited `daemon/server.ts:42` but that line now
+  does Z. [suggested rewrite: "X does Z"]
+
+### Unauditable claims
+- `bar.md`: "Historically Y was preferred" — no provenance.
+
+### Broken links
+- `baz.md` links to `quux.md` which does not exist.
+
+### Stubs
+- `empty-page.md` has no content beyond its header.
+
+### Missing coverage
+- Recent narrative claude-abc:33 discusses the new memory subsystem at
+  length. `memory.md` doesn't mention these changes.
+
+### Suggested cross-links
+- `foo.md` paragraph 3 should probably link to `bar.md` (current
+  mention is in plain prose).
+
+### Suggested index entries
+- (agent never edits index.md; list proposed one-liners here)
+```
+
+Refresh output follows the same structure but with an additional
+**Applied** section listing the files and sections the agent actually
+modified.
+
+## Refresh marker
+
+After any write-mode invocation, narrate a marker line so future
+`/wiki` passes can locate the last refresh:
+
+```
+**Wiki refreshed** — {timestamp} — {N pages modified} ({guidance})
+```
+
+This is the `narrative_search` anchor for "when was the wiki last
+synced with reality." Audit mode narrates its own marker:
+
+```
+**Wiki audited** — {timestamp} — {N pages checked}
+```
+
+## Quick reference
+
+| Intent in guidance | Mode | Touches files? |
+|---|---|---|
+| Question, "tell me about X" | Read | No |
+| `audit`, `check`, `what's stale` | Audit | No |
+| `update`, `refresh`, `rewrite`, `apply`, `write`, `fill`, `sync` (existing page) | Refresh | Yes, existing files only |
+| `seed`, `create`, `start`, `add` + **operator-introduced concept** | Create | Yes, new file |
+| Concept mention in a question, no existing page | Read + footer note | No |
+
+## Wiki access tools
+
+Beyond reading wiki files directly off disk, three MCP tools expose the
+wiki as a first-class, provenance-stamped surface — usable from any
+fold, reaching both this fold's wiki and the `brane` package wiki:
+
+- **`list_wiki`** — catalog of pages: slug, human-authored description
+  (from page frontmatter, else the first prose line), and `source`.
+- **`read_wiki`** — fetch a page by slug (or one section via `anchor`),
+  with the page's TOC and a `slug` / `slug#anchor` citation.
+- **`search_wiki`** — semantic + keyword search over wiki content,
+  returning chunk-level `slug#anchor` hits, like `narrative_search` but
+  over the wikis. Its index self-syncs on call.
+
+Pages may carry a `description:` (and optional `title:`) in `---`
+frontmatter; `list_wiki` surfaces it verbatim (human-authored, never
+AI-synthesized). See the [memory](memory.md) protocol for the full
+consultation procedure.
+
+## Related protocols
+
+- **[LIVE_loop](LIVE_loop.md)** — the communication loop this runs in.
+- **[memory](memory.md)** — `narrative_search` and `search_wiki` are the
+  primary tools for reality-sync during refresh.
+- **[digest](digest.md)** — time-windowed syntheses; wiki pages can
+  reference digests as provenance, and a digest can point at wiki pages
+  for concept-level context.

package/protocols/worker.md

@@ -0,0 +1,38 @@
+# Protocol: worker
+
+The default role. Nothing beyond the LIVE loop applies, except to
+repeat: never delete anything, and do not act before alignment is
+explicitly reached.
+
+You will almost certainly need **/LIVE_loop** — it is the execution
+environment, not an option. Read it first if you have not already.
+
+## The other protocols, briefly
+
+Reach for these when a signal names them (`/memory`, `/review`, …) or
+the task calls for them; `list_protocols` is always current.
+
+| Protocol | When |
+|----------|------|
+| /LIVE_loop | Always — the loop itself |
+| /memory | Searching narrative history, loading context from other narratives |
+| /payloads | Receiving or sending files and images over the loop |
+| /review | Reading and critiquing a proposed change, usually a PR |
+| /ramify | Delegating work to spawned sub-agents |
+| /summarize | Consolidating a long session into a durable summary |
+| /idle | Stopping the loop when the operator says the work is done — only as a signal's first token |
+| /digest | Summarizing activity across narratives over a time window |
+| /rrr | Putting the running code on what is merged: fetch, rebase, rebuild, restart |
+| /wiki | Maintaining the fold's `./wiki/` |
+| /scribe | Taking dictation into a document |
+| /keeper, /twin | Other roles — informational unless the operator layers one onto you |
+
+## Brane-internal
+
+These protocols only mean something when the fold is the brane
+repository itself (the checkout the daemon runs from — compare
+`whoami`'s `fold_dir`). In any other project, ignore them.
+
+| Protocol | When |
+|----------|------|
+| /fly | Brane's own Fly.io deployment |

package/wiki/shared/append-only-event-log.md

@@ -0,0 +1,148 @@
+# Append-Only Event Log
+
+The durable substrate behind every narrative. A single SQLite table
+(`events` in `~/.brane/brane.db`) that every narration, operator signal,
+and foreign narration lands in — and once landed, cannot be changed.
+Integrity is not an agent convention or a trust assumption; it is a
+property of the code that has the only write path and the SQL that
+schema enforces.
+
+Every event belongs to a narrative and carries a `seq` that is unique
+within it — `PRIMARY KEY (narrative_id, seq)` in `src/db/schema.ts`.
+The composite key makes the (narrative, seq) pair unforgeable: two
+events cannot share a seq in the same narrative, and no event can exist
+without one. Alongside `seq` an event carries its `time` (stamped at
+append), a `type`, free-form `content`, a server-stamped `source`,
+optional `re` back-references, optional `payloads`, and an opt-in
+`meta` object. The three conversational types — `narration`,
+`human_signal`, `agent_signal` — say *who spoke*, never what kind of
+thing was said; the system types (`started`, `restarted`,
+`binding_rejected`) record lifecycle facts nobody said at all. The
+schema itself is documented with the code in `AGENTS.md`.
+
+## The write path
+
+Every live write goes through `appendEvent` in `src/db/events.ts`,
+which reads the current max seq, increments it, and inserts. Callers
+never provide their own `seq` — the options type has no such field —
+so there is no way to write out of order or collide with an existing
+row. (The one exception is `brane absorb`, whose import pipeline
+inserts directly with self-computed seqs; it is operator-initiated and
+not reachable from any agent tool.)
+
+`source` is written by the daemon at append time — the MCP bridge and
+the agent have no write path of their own. How the value is chosen
+differs by event type:
+
+- **Operator signals** arrive over the HTTP signal route or the
+  control WebSocket. `source` names the delivering transport
+  (defaulting to `"web"`), supplied by the authenticated operator
+  client — so a token holder chooses the label on its own signals, but
+  an agent cannot write a human signal at all.
+- **Foreign narrations** are appended by the daemon's MCP `narrate`
+  handler with the *caller's* narrative ID as `source`, taken from the
+  authenticated WebSocket identity. The agent does not get to choose
+  what is written into that column.
+- **Own narrations** go through the same handler with the same
+  server-stamped identity.
+
+The MCP bridge (`src/mcp/server.ts`) does not import `better-sqlite3`
+and holds no database handle. It is a thin stdio↔WebSocket translator;
+every database write goes through the daemon, which means the identity
+check and the `source` stamp cannot be bypassed by a compromised bridge
+or a misbehaving tool call.
+
+There is no DELETE against the `events` table anywhere in the codebase,
+and no code path mutates an event's `content`, `seq`, `source`, `time`,
+or `type` after append. The one UPDATE that exists is the memory
+indexer's additive backfill of the `meta` column (session and model
+attribution, `src/memory/index.ts`) — it annotates, it never rewrites.
+Append-only for the record itself is enforced by the absence of
+mutation code, not by a runtime flag that could be flipped later.
+
+## The read path
+
+The cursor API (`readEvents` in `src/db/events.ts`) takes three
+optional bounds: `after: N` for events with `seq > N`, `before: N` for
+events with `seq < N`, and `tail: N` for the last N matching events.
+They compose — `{ after, before }` is a window, `{ tail, before }` is
+backward pagination — and results always come back in ascending `seq`
+order regardless of which bounds were used [claude-b629ddae:19].
+
+The cursor is the contract for no-missed-signals: a caller that polls
+with `after: 42` is guaranteed every event with `seq > 42`, so any
+signal that arrived while the caller was elsewhere surfaces on the next
+call. This is what makes the LIVE loop's long-poll semantics correct
+(/LIVE_loop) — not magic on the server, just a monotonically increasing
+integer the client remembers.
+
+## Integrity properties
+
+Four properties fall out of the append-only design and the server-side
+`source` stamp [claude-f64c335a:53]:
+
+- **Unrewritable history.** No DELETE, and nothing ever touches an
+  event's `content`, `seq`, `source`, or `time` after append. The agent
+  cannot redact, edit, or reorder its own past; the only way the record
+  can change is if the entire database is replaced, which a LIVE loop
+  agent has no authority to do.
+- **Unforgeable origin.** `source` is stamped by the daemon from the
+  authenticated caller's identity. An agent narrating into a foreign
+  narrative cannot claim to be the operator; a client cannot forge
+  narrations from another narrative's agent.
+- **Monotonic contract.** `PRIMARY KEY (narrative_id, seq)` makes the
+  seq unique per narrative, and `appendEvent` always writes
+  `MAX(seq) + 1`. No gaps, no duplicates, no out-of-order.
+- **Durable.** Written to `~/.brane/brane.db` in WAL mode, synced on
+  commit. Survives daemon restarts, crashes, and context compactions —
+  everything external to the host filesystem.
+
+These are the properties the safety argument in
+[sedimentary-superintelligence](sedimentary-superintelligence.md)
+depends on: an agent's trail cannot be covered up by the agent itself,
+because the write path the agent can reach is append-only and the
+`source` field is out of its control. The defense against an agent
+that would edit its own trail is not "watch harder" — at machine speed
+no operator can — but append-only, monotonically-sequenced,
+agent-unwritable event storage, expressed as database invariants rather
+than as trust in the model's cooperation [claude-f64c335a:53].
+
+## What it enables
+
+- **Cursor-based long-polling.** The `listen` tool's wait-for-new-events
+  semantics depend on the monotonic seq to guarantee no missed signals.
+  Without append-only integrity the cursor would be a suggestion, not a
+  contract (/LIVE_loop).
+- **Semantic memory across narratives.** Events with stable `seq`
+  values can be indexed by the memory subsystem and cited from future
+  sessions as `narrative-id:seq` — a form that only works because seq
+  is stable after write (/memory).
+- **Compounding narrations.** Every token spent on a narration lands in
+  a log that is searchable, citable, and available to future agents.
+  Terminal output is volatile and unindexed; narrations accumulate.
+  This is the premise of
+  [sedimentary-superintelligence](sedimentary-superintelligence.md),
+  and the same property is what makes the narrative
+  [sequesterable](sequestering-the-narrative.md) — a medium durable
+  enough that `/clear` becomes a routine operation rather than an
+  emergency.
+- **Safety-by-construction for capable agents.** An agent that could
+  rewrite its own history can conceal intent; an agent that cannot can
+  only be observed. Making the log append-only converts the supervision
+  problem from "trust the model" into "watch the stream"
+  [claude-f64c335a:53].
+
+## Related
+
+- [sedimentary-superintelligence](sedimentary-superintelligence.md) —
+  the log *is* the sediment. This page describes the substrate's
+  integrity; that page describes what the substrate is for.
+- [sequestering-the-narrative](sequestering-the-narrative.md) — the
+  narrative's *position*, set apart from scrollback and context; this
+  page is about its *integrity*.
+- [owning-your-narratives](owning-your-narratives.md) — the practice
+  that makes an unrewritable record worth reading.
+- [premature-ontologies](premature-ontologies.md) — why the schema
+  types who spoke and never what was said.
+- /LIVE_loop — the protocol that reads from and writes to this log;
+  authoritative on cursor parameters and response shapes.

package/wiki/shared/index.md

@@ -0,0 +1,48 @@
+# Brane Wiki
+
+What brane is, why it's shaped the way it is, and what it asks of the
+agents that run inside it. The narratives are the read path and the
+source of truth; these pages are an opinionated projection of them
+([why-wikis-work](why-wikis-work.md)). When a page disagrees with the
+narrative record, the record wins.
+
+New here? Read in order:
+
+1. [sedimentary-superintelligence](sedimentary-superintelligence.md) —
+   the one-paragraph pitch: an archive smarter than you, inert at rest.
+2. [why-wikis-work](why-wikis-work.md) — why a second brain works, where
+   it fails, and why this directory exists anyway.
+3. [sequestering-the-narrative](sequestering-the-narrative.md) — the
+   narrative held apart from scrollback and context window.
+4. [owning-your-narratives](owning-your-narratives.md) — what that asks
+   of an agent, turn by turn.
+5. [premature-ontologies](premature-ontologies.md) — the intellectual
+   inheritance: why refusing a typology is the substrate decision.
+6. [append-only-event-log](append-only-event-log.md) — the one code-level
+   commitment everything above rests on.
+
+## Theses — what brane believes
+- [sedimentary-superintelligence](sedimentary-superintelligence.md) — an archive of accumulated dialogue smarter than any user yet inert at rest; intelligence lives in the act of integration, not the sediment.
+- [sequestering-the-narrative](sequestering-the-narrative.md) — the narrative held apart from disposable scrollback, volatile context, and other agents' records.
+- [owning-your-narratives](owning-your-narratives.md) — the agent practice that follows: narrate for downstream retrieval, not upstream expression.
+- [premature-ontologies](premature-ontologies.md) — why committing a typology before its categories have earned their scope keeps failing; the refusal of taxonomy-as-substrate.
+- [why-wikis-work](why-wikis-work.md) — where the wiki pattern wins, where it struggles, and why this directory is a disciplined compromise.
+
+## Substrate — how brane keeps its word
+- [append-only-event-log](append-only-event-log.md) — the single immutable SQLite table behind every narrative; integrity enforced by schema, not convention.
+
+## Mechanism lives elsewhere
+
+The daemon, transports, agent adapters, security model, and the LIVE
+loop's exact tool contract are documented in `AGENTS.md` (an index into `docs/`), `DESIGN.md`,
+`SECURITY.md`, and `protocols/` — all shipped alongside this wiki and
+maintained with the code. Pages here make arguments; those files
+describe machinery.
+
+## Local to the brane fold, not shipped
+
+The brane checkout's `wiki/` holds further pages that are either
+brane-internal or still settling: `brane-ontology`, `why-tailscale`,
+and `how-to-brane`. They are local pages of that fold — readable
+by agents working in the checkout, not published with the package and
+not visible from other folds.