brane 0.1.1 → 0.3.0

package/protocols/rrr.md

@@ -0,0 +1,232 @@
+# Protocol: rrr
+
+`/rrr [branch=main]` puts the running code on what is actually merged.
+Fetch, rebase onto `origin/<branch>`, rebuild, restart.
+
+Three letters, four r's:
+
+| r | step |
+|---|---|
+| *refetch* | `git fetch origin` — elided from the name, because it's implied |
+| **rebase** | onto `origin/<branch>` |
+| **rebuild** | the project's build |
+| **restart** | whatever long-running process serves that build, if there is one |
+
+The first half is the same in every repository. The second half is
+whatever *this* fold's build and process are — read them off the
+project (`package.json` scripts, a `Makefile`, a `justfile`, its
+README) rather than assuming. When the fold is the brane repository
+itself, they are `npm run build` and `brane daemon restart`, and that
+case has enough of its own consequences to get its own section at the
+end of this document.
+
+## Why
+
+An agent's working tree is a claim about the world; `origin/main` is
+the world. Between them sit merged PRs you never pulled, your own
+commits that were squashed on the way in, and build output compiled
+from neither. `/rrr` collapses the three into one state and puts the
+live process on it, so that what you are about to test is **what has
+actually been merged** rather than what your branch believes.
+
+The last step is the one that matters. A build writes files; a
+process that started before the build holds its code in memory. Until
+it is restarted, a green build is a claim about files on disk and
+nothing more.
+
+**The operator knows the restart will blink.** On an explicit `/rrr`,
+do not spend a narration warning about the process going down or
+asking whether to proceed; the invocation *is* the consent. Report the
+restart as a step you took, not a risk you weighed.
+
+## Restart from the right checkout
+
+A restart is only "testing this tree" if the process is started *from*
+this tree. Many restart commands re-exec whatever checkout invoked them
+— so restarting from a worktree does not test the worktree; it installs
+that worktree's build as the process for everyone who shares it, until
+someone restarts from somewhere else.
+
+So before step 6, ask where the running process was started from, and
+compare it to `whoami`'s `fold_dir`. If they differ:
+
+- **Don't restart from here** unless the operator has said to, knowing
+  what it means. It is a wider side effect wearing the costume of a
+  local one.
+- You may still do the read-only half — `git fetch origin`, and rebase
+  *your own branch* onto `origin/<branch>` if that is what you want.
+  That is ordinary work, not `/rrr`.
+- If what you need is the process on merged code, say so and let the
+  operator run `/rrr` in the checkout it runs from, or ask for
+  permission to walk over to it. Then come back.
+
+## Steps
+
+Narrate as you go — each step's real output, not a plan restated. A
+`/rrr` that reports "rebased, rebuilt, restarted" without ever showing
+what git and the build said is indistinguishable from one that did
+nothing.
+
+**1. Fetch.** `git fetch origin` — or `git fetch origin <branch>`.
+This comes first because the next step is a question about the
+*target*, and you cannot ask it before you have one.
+
+**2. Take stock of the tree.** `git status --porcelain`, and then, for
+each path it names, the question that actually matters:
+
+```
+git show origin/<branch>:<path> | diff - <path>
+```
+
+The question is **not** "is the tree dirty?" — that is tidiness. It is
+**"does this tree hold bytes that exist nowhere else?"** Dirt is only
+dangerous when it is the sole copy of something.
+
+- **Empty diff — a duplicate.** The file already matches where you are
+  going; the sync will not change it. `git add` it and continue. That
+  is not a workaround: git compares the *index* against the target, so
+  an entry that already equals the incoming content applies cleanly and
+  the file lands tracked and clean. An untracked file matching an
+  incoming *new* file is the same case and takes the same `git add`.
+- **Non-empty diff, or the path doesn't exist upstream — real work.**
+  **Stop here and report it.** Do not stash, do not `git checkout --`,
+  do not `git clean`, do not `git rebase --skip` your way past a
+  conflict. The golden rule at the head of this document covers
+  uncommitted work, which is the most easily destroyed artifact in the
+  repository and the only one with no copy anywhere.
+- **Mid-conflict** (`UU`, a `rebase-merge/` directory) — stop
+  regardless. Someone's resolution is in progress.
+
+Untracked files unrelated to the sync — scratch scripts, tarballs,
+build droppings — are neither; leave them in place, say what they are,
+and continue.
+
+The duplicate case is worth spelling out because it is the *common*
+one, not an edge: you merged your own PR, so your working copies are
+copies of the destination. Treating that as a blocker stops the run
+over files that hold no information — and a guard that fires on the
+ordinary case is one people learn to route around, which is how the
+guard stops protecting the case that matters.
+
+**3. Switch and rebase.**
+
+```
+git checkout <branch>          # default: main
+git rebase origin/<branch>
+```
+
+On a checkout of `main` that has no local commits this is a
+fast-forward and says so. If the rebase **conflicts**, stop: narrate
+the conflicting paths and the operator decides. Do not resolve
+conflicts inside `/rrr` — you were asked to sync, and a conflict means
+the sync is a question rather than a mechanism.
+
+**4. Reinstall if the dependencies moved.** Note the pre-rebase commit
+(`git rev-parse HEAD`) before step 3, then afterwards ask what actually
+moved among the project's lockfiles and anything that patches
+installed packages:
+
+```
+git diff --name-only <old>..HEAD -- <lockfiles> <patch dirs>
+```
+
+If any of them changed, run the matching install. A repository can
+hold more than one independent package tree — a root and a sub-app,
+each with its own lockfile and `node_modules` — and a top-level build
+that *runs* the sub-app's build without installing for it; check each
+tree, not just the root. Patch directories (`patch-package`,
+`patches/`) belong in the list because a changed patch rewrites code
+inside an installed package and shows up in **no** lockfile at all, so
+it is invisible to the check everyone thinks to run.
+
+Skipping this is not a build failure, which is what makes it worth a
+step. A stale dependency tree usually compiles and then misbehaves at
+runtime, and the hour goes to debugging the code that was merged rather
+than the install that wasn't. When in doubt, install everything — it
+is seconds when nothing changed.
+
+**5. Rebuild.** The project's full build — not just its typecheck, if
+the two differ, and not just one half of a multi-part build: a server
+compiled against a stale client bundle presents as a UI bug rather
+than a build one. If the build fails, **stop and report the error**;
+do not restart onto half-written output.
+
+**6. Restart.** The process that serves the build, with whatever
+command the project uses for it. Mind the checkout question above.
+
+**7. Confirm.** Check the process actually came back on new code —
+its pid changed, it is alive, its reported version or start time
+moved. A restart that silently failed leaves the old process running
+and every subsequent test measuring the old code.
+
+## Afterwards
+
+Say what changed, concretely: the commit range the rebase brought in
+(`git log --oneline <old>..HEAD`), whether the build was clean, the
+new pid. That list is the point of the exercise — it is the answer to
+"what am I now testing?"
+
+Then return to the LIVE loop and `listen`. `/rrr` is preparation; the
+operator usually has something they wanted to test *on* merged code,
+and that instruction is the next signal.
+
+## In the brane repository itself
+
+Everything below applies only when the fold **is** the brane checkout
+— the one whose `dist/` the daemon is running. In any other project,
+none of it does.
+
+**The four r's, concretely.** Rebuild is `npm run build` — `tsc` plus
+the Expo web export. Not `npx tsc` alone: that leaves `expo/dist/`
+stale, so the daemon serves the *old* app bundle over the new server.
+Restart is `brane daemon restart`; it preserves port and token, so
+existing links and QR codes keep working. Confirm with `brane daemon
+status` and check the pid moved.
+
+**The daemon is one process per machine, and it restarts from whichever
+checkout invoked the command** — `brane daemon restart` re-spawns
+`process.argv[1]`. That is the "restart from the right checkout" rule
+above at its sharpest: a restart from a worktree installs that
+worktree's build as the daemon for every other agent's MCP bridge,
+every open phone, and every terminal mirror. `/rrr` therefore belongs
+in the checkout the daemon already runs from; confirm with `whoami`'s
+`fold_dir` against the running daemon rather than assuming.
+
+**What the blink is.** Every agent's MCP bridge drops, the app
+reconnects, terminal mirrors resync — a few seconds, and none of it is
+news to the operator.
+
+**Two package trees.** `package-lock.json` at the root and
+`expo/package-lock.json`, each with its own `node_modules`, not a
+workspace. `npm run build` *runs* the Expo build (`npm run build:web
+--prefix expo`) but never installs for it. So step 4's diff is:
+
+```
+git diff --name-only <old>..HEAD -- \
+  package-lock.json expo/package-lock.json expo/patches
+```
+
+- root lockfile → `npm i`
+- `expo/package-lock.json` **or** `expo/patches/` → `(cd expo; npm i)`
+- both, or you'd rather not read the diff → `npm i && (cd expo; npm i)`
+
+`expo/patches/` is there because `expo/package.json`'s `postinstall`
+runs `patch-package`.
+
+**Your own bridge goes down with it.** You are restarting the daemon
+your MCP bridge is connected to. The bridge reconnects on its own with
+backoff, but in the window around the restart a brane call in flight
+comes back `daemon connection lost (reconnecting — please retry)` and
+a parked `listen` is answered and dropped. **Retry the call.** Once.
+That error is the restart working, not the restart failing — and it is
+not something to narrate an alarm about. Only if calls are still
+failing after several seconds of retries has something actually gone
+wrong; then report it with the real error text, and check `brane
+daemon logs` before concluding anything.
+
+**Protocol changes need no `/rrr`.** The daemon reads `protocols/`
+from disk on every `read_protocol`, so a protocol edit is live the
+moment it is written. Same for `wiki/`. If a rebase brought in only
+markdown under those directories, the rebuild and restart are honest
+work but they are not what made the change take effect — say so rather
+than implying the restart was load-bearing.

package/protocols/scribe.md

@@ -0,0 +1,429 @@
+# /scribe [target]
+
+Take human dictation and render it faithfully into a progressively more
+complete document, without embellishment. The operator dictates; the
+scribe commits only what the operator **endorses**, in the operator's own
+voice, and nothing more. The scribe is a **faithful recorder, not an
+author** — its fidelity to the source *is* the job.
+
+`/scribe` is the near-mirror of [`/wiki`](wiki.md): the wiki forbids the
+agent from inventing *concepts*; the scribe forbids it from inventing
+*words*. Anything on the page the operator did not endorse is a defect.
+
+The endgame is a fully voice-driven tool — speech-to-text in,
+text-to-speech read-back out — so every rule holds when the operator
+can't see the screen and must trust their ears. That makes fidelity
+load-bearing, not aspirational.
+
+## Prime directive
+
+**No content enters the document except as a faithful rendering of
+something the operator endorsed** — composed, pasted, or authorized by
+reference (see *Provenance*). The scribe contributes no substance of its
+own: no invented sentences, no connective tissue, no "the author notes
+that…", no polishing a rough idea, no filling a gap with a guess. When
+tempted to add, it raises an **open question** and waits.
+
+The page is in the **operator's voice**, their phrasing preserved. The
+scribe's own voice appears only in read-backs and open questions, never
+in document prose.
+
+## Target, up front
+
+A session **begins by fixing its destination** — the operator names the
+artifact (usually a markdown file) before any dictation is committed:
+
+```
+/scribe spec.md
+```
+
+- **File doesn't exist** → the scribe creates it and starts an empty
+  manifest (see *The ledger*).
+- **File exists** → the scribe **adopts** it: its current content becomes
+  one or more `baseline` fragments — preserved and rendered, but with no
+  endorsement chain (a later `/notary` pass marks baseline ungrounded).
+  The scribe never claims baseline content as human-authored.
+- **No target set** → the scribe's first act is to ask for one; nothing
+  is committed until a destination exists.
+
+The target is **sticky**: dictation lands there until the operator
+redirects (`/scribe other.md`) or exits.
+
+## Latched session
+
+Dictation is continuous — the operator won't prefix every sentence,
+least of all by voice — so the scribe **latches**:
+
+- `/scribe <target>` opens a resident session.
+- While latched, **every** `human_signal` is handled by the scribe (as
+  prose, instruction, query, or correction), not as a general LIVE-loop
+  request.
+- `/scribe stop` closes it; the scribe confirms and returns to the
+  ordinary loop.
+
+If something plainly outside the writing task arrives while latched, the
+scribe raises an open question ("didn't sound like dictation — step out
+of the session?") rather than silently acting or transcribing.
+
+## Channels: four kinds of utterance
+
+Every latched `human_signal` is one of four things, never bleeding
+together:
+
+1. **Prose** — content to render, in the operator's voice.
+2. **Instruction** — a directive about the document's *shape*: "intro
+   goes last," "keep §3 before §2," "put the pricing bit under §2." May
+   be **standing** or one-off. Changes fragment *metadata* (placement,
+   ordering), never fragment *text*.
+3. **Query** — a question *about* the document that changes nothing:
+   "read me back §2," "word count?" Answered from the render; no change.
+4. **Correction / retraction** — a change to what's there: an in-flight
+   fix ("no, make that fifteen percent") **supersedes** a fragment; a
+   retraction ("strike that") **retracts** one.
+
+**Disambiguation is hybrid:** infer the channel from phrasing by default;
+reserved mode-words override when the operator wants certainty (`note:` /
+`instruction:` mark an instruction, `scribe:` addresses the scribe,
+`verbatim:` forces prose — for dictating text that *itself* begins with a
+mode-word, e.g. writing documentation about scribe; plain speech is
+prose); the **read-back is the safety net** — a misclassification is
+caught on the next breath. When genuinely uncertain *and* the guess would
+change the document, the scribe **asks**. A wrong silent guess is exactly
+the embellishment this protocol prevents.
+
+## The per-utterance loop
+
+For **every** latched `human_signal`, in order:
+
+1. **Classify** the channel (prose / instruction / query / correction).
+2. **Apply the fidelity licence** and create or modify **fragment(s)** in
+   the manifest — never edit document text directly.
+3. **Re-render** the target wholesale from the manifest (see *Projection*).
+4. **Verify** the render equals a fresh recompute from the manifest,
+   byte-for-byte; on mismatch, **fail closed** — re-render, do not proceed.
+5. **Read back** the fragment delta and cite the endorsing seq.
+6. **Update `meta.summary`** to `Scribe: <target> — §<current section>`.
+
+Queries touch neither manifest nor file — answer from the current render
+and read back. Everything else runs the full loop.
+
+## The ledger: fragment, manifest, projection
+
+The document is **not the store** — it is a *projection*. The store is a
+ledger of endorsed fragments; the file is regenerated from it on every
+change. Nothing is ever edited in place, so nothing untouched can be
+silently relexed: *the document is a projection; the log is the
+notarized ledger.*
+
+**Fragment — the unit of record.** Each endorsed utterance yields at most
+one fragment: the operator's words, verbatim after the fidelity licence.
+A fragment carries:
+
+- `id` — a stable handle, `f<seq>` of the endorsing signal (`baseline-N`
+  for adopted content).
+- `endorse` — the endorsing `human_signal` `nid:seq` (`null` for
+  baseline).
+- `origin` — for adopted-by-reference passages, the `nid:seq` the words
+  came from; else `null`. Two-coordinate provenance: *who authorized*
+  distinct from *where the words came from*.
+- `section` — the placement label (which outline section it belongs to);
+  `null` ⇒ appended at document end.
+- `status` — `active` · `superseded:<id>` · `retracted` · `baseline`.
+- `text` — the verbatim content.
+
+**Manifest — the working store.** A sidecar next to the target:
+`<target>.scribe.json`. It holds the ordered section outline, every
+fragment record (**never deleted** — only its `status` changes), standing
+instructions, open questions, and the hash of the last render. The event
+log remains ground truth for audit; the manifest is the machine-checkable
+index into it. Maintain it with ordinary file tools until a future
+`brane scribe` command owns it.
+
+```json
+{
+  "target": "spec.md",
+  "sections": ["Overview", "Pricing", "Deployment"],
+  "fragments": [
+    { "id": "f7", "endorse": "claude-4anserzq:7", "origin": null,
+      "section": "Pricing", "status": "active",
+      "text": "Pricing starts at fifteen percent of contract value." }
+  ],
+  "standing": ["Introduction goes last."],
+  "questions": [
+    { "id": "q9", "kind": "hole", "text": "§Deployment named, not yet dictated." }
+  ],
+  "render_hash": "sha256:…"
+}
+```
+
+**Projection — the document is rendered, never edited.** On every change,
+regenerate the target `.md` wholesale: section headings in outline order,
+then each section's `active` fragments in manifest order, then the
+scribe-notes block. Rendering is **mechanical copying** — the agent
+assembles the file *by reading `text` out of the manifest*, never by
+recalling prose from context. Writing (overwriting) the target is the
+*render mechanism* and is expected; the ledger, not the file, is the thing
+never rewritten from memory.
+
+**Render verification — the fail-closed gate.** The render is a *pure
+function of the manifest* — headings from `sections`, each section's
+`active` fragments in order, then the notes block. So verification is
+**deterministic equality**: recompute the expected render from the
+manifest and require it to match the file on disk **byte-for-byte**. Any
+mismatch ⇒ re-render; never accept a render that doesn't match. This is
+strictly stronger than the old snapshot→diff gate — one check proves at
+once that every fragment is present and faithful, that **nothing
+unendorsed was inserted between fragments**, and that the order is
+correct. And because the check is a pure recompute, a dumb tool can run
+it — a future `brane scribe render --check`, the notary, or the operator
+— so fidelity never rests on the agent's discipline.
+
+**Placement — no cursor.** The operator never manages an insertion point.
+A fragment's `section` is set from the section the operator most recently
+named; absent any, it appends at document end. "Put the pricing bit under
+§2" is a **metadata change** (set `section`) plus a re-render — no text
+surgery. The scribe never *guesses* placement: ambiguous placement stays
+an open question. Directed placement is faithful; invented placement is
+embellishment.
+
+**Corrections and retractions.** "No wait, fifteen percent" → a **new**
+fragment (endorsed by the correcting seq) whose `status` supersedes the
+old one; the superseded record stays in the manifest, absent from the
+render. "Strike that" → set the fragment's `status` to `retracted` (text
+preserved in the manifest, absent from the render). No in-place text edit
+exists anywhere in this protocol.
+
+**Drift guard.** Before each render, compare the on-disk file to the
+manifest's `render_hash`. A mismatch means the file was hand-edited since
+the last render. **Never clobber silently:** raise an open question. If
+the operator endorses the drift, adopt it as a fragment endorsed by that
+signal; otherwise the next render restores the manifest's truth.
+
+## Fidelity line
+
+Faithful is not literal-to-a-fault; speech carries noise the operator
+doesn't intend as content. The licence is narrow and fixed:
+
+**Permitted** (faithful to intent): strip disfluencies ("um," false
+starts, stumbles); honor explicit self-corrections (commit the corrected
+form, not the abandoned one); normalize mechanical surface (casing,
+obvious punctuation, implied paragraph breaks).
+
+**Forbidden** (embellishment): adding, sharpening, or "improving" any
+substantive word; reordering beyond an explicit instruction; resolving an
+ambiguity by guessing intent; expanding a pronoun or reference unless its
+referent is unambiguous in the immediate dictation — otherwise raise an
+open question.
+
+Every substantive word is preserved. When in doubt, preserve and ask.
+
+## Scribe notes: holes and standing instructions
+
+Standing instructions and open questions aren't prose but belong *with*
+the document. They live **only in the manifest** (`standing`,
+`questions`) and are **rendered** into a visible, scribe-owned block at
+the foot of the file — one source of truth, so the block and any inline
+markers can never drift apart:
+
+```markdown
+<!-- SCRIBE:BEGIN -->
+## Scribe notes
+**Standing instructions**
+- Introduction goes last.
+**Open questions**
+- [order?] Pricing paragraph under §2 or its own section?
+- [hole] §Deployment named but not yet dictated.
+<!-- SCRIBE:END -->
+```
+
+- **Holes** (sections named but not dictated) and **debates** (order,
+  referent, ambiguity) are `questions` entries; the render surfaces each,
+  including any inline `> [SCRIBE: …]` marker at its location.
+- The scribe **never resolves an open question itself** — that would be
+  authoring. It waits for the operator, then applies the resolution
+  (a manifest change + re-render) and drops the `questions` entry.
+- **Standing instructions apply retroactively.** "Intro goes last" sets
+  placement metadata now, is read back, and is recorded in `standing` to
+  govern future work.
+
+## Read-back: the operator's only mirror
+
+In a voice-only session the read-back is the *sole* way to catch an
+embellishment, so it is **mandatory** and **derived from the fragment
+delta** (what the utterance created, superseded, or retracted), never from
+recollection of intent:
+
+- **Cadence:** one concise read-back **per `human_signal`** — what
+  changed, plus any open question raised. Full-document read-back only on
+  request.
+- **Form (two-part):** a **speakable sentence** first — TTS reads this
+  ("Added to §Pricing; one question: before or after the terms?") —
+  followed by the committed **fragment text verbatim** in a fenced block,
+  the literal audit record:
+
+  ```
+  Pricing starts at fifteen percent of contract value.
+  ```
+- **Content is literal, never a paraphrase.** Cite the endorsing seq via
+  `re:` and in text; for adopted content also name the `origin` seq.
+
+## Provenance: every fragment carries a human endorsement
+
+The document is built so a later, independent
+[`/notary`](#the-notary-a-separable-follow-on) pass can prove **every
+fragment was endorsed by the operator**, and quantify *how*. Two brane
+guarantees make it possible:
+
+- **`source` is stamped server-side and cannot be spoofed** — a
+  `human_signal` is provably operator-originated.
+- **`seq` is monotonic and append-only** — `nid:seq` is an immutable
+  coordinate for a specific human utterance.
+
+The scribe's obligations:
+
+1. **Admission rule.** Every fragment must carry an **operator
+   endorsement** delivered through a `human_signal`. Endorsement is read
+   *maximally* — composing words fresh, pasting them, **or authorizing a
+   previously discussed passage by brief reference** ("add the pricing
+   paragraph the agent drafted"). A reference is dictation in the
+   abstract: the operator adopts an *identified* passage without
+   re-uttering it. Forbidden is only the *scribe* pulling agent content
+   in **on its own initiative**. When admitting by reference: the
+   referent must be **unambiguous** (resolve to a specific `nid:seq`, else
+   raise an open question — *which* passage?), and the retrieved passage
+   is **rendered faithfully** (copied into the fragment `text`, not
+   rewritten or "improved").
+2. **Citation.** Each committing read-back cites the **endorsing
+   `human_signal` seq** (the fragment's `endorse`, via `re:` and in text).
+   For content admitted by reference, it *also* names the fragment's
+   `origin` seq — distinguishing *where the words came from* from *who
+   authorized them*, which makes the retrieval independently auditable.
+3. **Grain.** Provenance is tracked per **fragment**. Reorders and
+   re-placements move fragments without changing their `text`, so
+   provenance rides along untouched.
+
+The **canonical store is the event log**, not the document, and not the
+manifest — the manifest is a convenience index and the document a
+projection. The spoof-proof record is the chain of
+`human_signal → citing read-back` events.
+
+### What the chain proves: endorsement, not origination
+
+Brane witnesses the **channel**, and that is enough. What passes through
+the `human_signal` channel is, by that act, **adopted by the operator as
+their own** — composed, recalled, or pasted alike. Copy-paste is **not
+laundering and not discouraged**: sending something through the human
+channel *is* the decision that "this is what I would have said." The chain
+proves *every fragment was endorsed and faithfully rendered without the
+agent adding anything unendorsed.* It does not prove where the operator's
+ideas came from — **origination is unmeasurable and beside the point;
+endorsement is what authorship has always meant.** A signature never
+certified you originated the language, only that you adopted it.
+
+The trust model is asymmetric **by design**: the system **distrusts the
+agent** (fenced by the admission rule and the render-verification gate)
+and **trusts the operator** (their endorsement is definitional). If you
+wouldn't trust the operator's endorsement, no provenance system helps —
+they're the authoring principal, not a party under audit.
+
+So the notary's core metric is a **three-way split**, not a single
+"endorsed fraction":
+
+- **composed** — the operator supplied the words;
+- **adopted** — the operator authorized an agent-originated passage by
+  reference (endorsed, not their words);
+- **unendorsed** — baseline, or a fragment added in violation of the
+  admission rule (no endorsement).
+
+"Endorsed" alone isn't the discriminator: an operator could authorize a
+whole agent draft by reference — 100% endorsed, 0% composed, fully
+legitimate but not the same as one they wrote. **Composed vs. adopted** is
+what carries weight; ghostwriting surfaces as low-composed or
+high-unendorsed, never as composed. This is the defensible reading of
+"prove exactly how much of it is yours": your *words* (composed), your
+*choices* (adopted), and what is *neither* (unendorsed).
+
+## The notary: a separable follow-on
+
+Notarization — *attesting* the chain holds — is a **different job** from
+authoring, and wants to be structurally independent: a notary who wrote
+the document is a weak notary. The scribe's citation discipline is the
+evidence base a future `/notary` pass consumes to emit a
+fragment-by-fragment attestation and the composed/adopted/unendorsed
+split. The scribe lays the rails; it does not self-attest. `/notary`'s
+own protocol is a follow-on, not part of this document.
+
+## Skill vs. protocol — what Brane adds
+
+Most of this document is portable: the behavioral spec (fidelity line,
+channel-sorting, ledger discipline, open-question reflex) is
+agent-interpreted prose that could live as a harness *skill*
+(`.claude/skills/scribe.md`). That part is **not Brane-specific**.
+
+Brane's irreducible contribution is **evidence, not behavior**: an
+authority-stamped boundary between human and machine content. A skill's
+only record is its own agent's transcript — single-party, ephemeral,
+certifying nothing about which bytes were human; a process cannot
+notarize its own inputs. Brane's log can, because `source` is stamped by
+a party neither operator nor agent controls, and the log is append-only
+and independently re-verifiable.
+
+Scoping:
+
+- **No provenance proof needed** → a `/scribe` *skill* is equivalent and
+  simpler. Prefer it.
+- **A provable human/AI split matters** — "no reliance on AI" (a fully
+  *composed* document) or honest disclosure of what was *adopted* → only
+  the Brane substrate delivers it.
+
+The slogan: **"write with agent assistance — then prove exactly how much
+of it is yours."** Read "yours" as *endorsed by you*. In one line: **the
+skill gives you *faithful*; the log gives you *provable*.**
+
+## Recovery
+
+The manifest plus the event log are the **complete** session state — the
+latch, target, ledger, and open questions all persist outside agent
+context. After compaction or a revive:
+
+1. `whoami`, then `listen` with `tail` to reload recent context.
+2. Scan back for the most recent `/scribe <target>`; if it has no
+   matching `/scribe stop`, the **latch is still on** and `<target>` is
+   the sticky destination.
+3. Reload `<target>.scribe.json` — it *is* the working state; re-render
+   from it and verify. Nothing is lost.
+4. If the current section is uncertain, read back the tail and **confirm
+   with the operator** rather than guess.
+
+## Golden rule
+
+The scribe **never deletes files, git history, or any artifact** on its
+own. Dictated *retraction* ("strike that sentence") sets a fragment's
+`status` to `retracted` — the text leaves the render but stays in the
+manifest, and the retraction command is itself the `human_signal` of
+record — so the file and everything around it are never removed. Prefer
+`cp` over `mv`; if something seems to need deletion, surface it to the
+operator. See /prelude's Golden Rule.
+
+## Quick reference
+
+| Operator utterance | Channel | Manifest operation |
+|---|---|---|
+| Plain speech | Prose (composed) | Append `active` fragment, cite endorse seq |
+| "add the pricing bit we discussed" | Prose (adopted by reference) | Append fragment with `origin`, cite endorse + origin |
+| "intro goes last" | Instruction (standing) | Set placement, record in `standing`, re-render |
+| "put the pricing bit under §2" | Instruction (placement) | Set fragment `section`, re-render |
+| "read me back §2," "word count?" | Query | None — answer from render |
+| "no wait, X" | Correction | New fragment supersedes prior, re-render |
+| "strike that" | Retraction | Set `status: retracted`, re-render |
+| Referent or placement unclear | (open question) | Add `questions` entry, wait |
+| `/scribe stop` | Session control | None — closes session |
+
+## Related protocols
+
+- **[LIVE_loop](LIVE_loop.md)** — the loop this runs inside; source of the
+  `human_signal` guarantees provenance depends on.
+- **[wiki](wiki.md)** — sibling faithful-rendering protocol; shares the
+  fidelity and provenance disciplines.
+- **[review](review.md)** — precedent for keeping verification independent
+  of production (the scribe/notary split).