brane 0.1.1 → 0.3.0

package/docs/diagrams.md

@@ -0,0 +1,163 @@
+# Diagram Rendering
+
+A ` ```mermaid ` fence draws. Like code highlighting and unlike KaTeX it renders
+**on the daemon** — `POST /api/diagram` for the app, a direct call for the HTML
+export — because a diagram is rare and heavy where inline math is ubiquitous and
+light. The Expo bundle gains nothing: `@dagrejs/dagre` (1.9 MB, 2 packages) is
+the only new dependency and it never reaches the browser.
+
+| Piece | Where | Does |
+|---|---|---|
+| `parseDiagram` | `src/diagram/parse.ts` | Source → IR, or a refusal with a reason and a line. Linear time — see below |
+| `parseLabel` | `src/diagram/label.ts` | Label text → lines of styled runs, for both of mermaid's label grammars — see below |
+| `measureNode` | `src/diagram/metrics.ts` | Text width without a DOM — Helvetica and Helvetica-Bold advances, per-block fallbacks |
+| `layoutDiagram` | `src/diagram/layout.ts` | dagre, plus **face-projected attachment** (below), resolved `classDef`s, and synthesised self-loops |
+| `basisPath` | `src/diagram/svg.ts` | `d3-shape`'s `curveBasis`, ported; pinned against d3's own output |
+| `nidHrefFor` | `src/diagram/links.ts` | The seam: a node labelled with a real narrative becomes a link. Takes the target form, so the export points at sibling `<nid>.html` files rather than the app's `brane://` scheme |
+| `renderDiagram` | `src/diagram/index.ts` | The one entry point, for both targets |
+| `edgeHighlight` / `DIAGRAM_EDGE_HIGHLIGHT_CSS` | `src/diagram/svg.ts`, `src/shared/diagram-css.ts` | Hover or tap an arrow, or its label, to draw it again in a highlight color, above every other edge and label and below the boxes, which cover its ends. CSS only, so the export stays scriptless; the export inlines the rule and `DiagramView` injects the same string. Label groups paint above line groups, so a later arrow's hit stroke cannot cover an earlier arrow's label |
+
+**The dialect is measured, not chosen.** Across every mermaid fence in the
+archive (21 diagrams, 316 lines, home brane plus two absorbed ones): `flowchart`
+and `graph` only, `-->` 131 and `<-->` 9, `[rect]` 125 · `(round)` 9 ·
+`[(cyl)]` 5 · `{diamond}` 4 · `>asym]` 4 · `[[sub]]` 1, plus `subgraph`, `&`,
+`<br/>`, `classDef`/`class`/`style` and `%%`. So that is what draws, and 20 of
+the 21 do; the refusal is the one `stateDiagram-v2`, a later increment. Bump the
+census when the dialect grows. Styled label text is the one part of the
+dialect admitted without a count: on 2026-10-01 this daemon's 26 fences held
+no markdown string, `<b>` or `font-weight` at all, but an agent on another
+daemon that wanted bold tried all three in a row and got literal tags, then
+literal backticks and asterisks, then nothing, with a clean receipt each time
+(claude-cdouqlgt:12–:24). Absence from the census was the quiet failure, not
+disuse.
+
+Eight things are less obvious than they look:
+
+**The dialect adds no syntax.** Every brane-specific behaviour is
+*interpretation* of text that is already legal mermaid — a node labelled
+`claude-0qjv4nny` is a link here and plain text on GitHub. So the same fence
+stays portable, and there is no second grammar to keep in step. Only a label
+that is *entirely* a reference resolves, and only to a narrative that exists,
+which is the rule `markdown-nids.ts` already applies in prose. A node **cites
+and does not address**: `@nid` is deliberately not linked, because
+`mentions-scan` walks the rendered markdown where a fence is inert, so linking
+it would show a mention that notifies nobody.
+
+**Arrows arrive crooked because of the attachment point, not the curve.** dagre
+picks an edge's terminal point by intersecting the node's box with the chord
+from the node's *centre* to the first bend; that chord is diagonal, so the tilt
+is baked in before any curve is fitted — 28px of lean on the LIVE loop's
+`Listen → Interpret`. `projectAttachment` slides the point along its face until
+it lines up under the bend, which drops mean arrival angle from 31.4° to 8.7°
+**with the curve untouched**. Four curve-side fixes were built and measured
+first (clamped-tangent Hermite, basis + normal stubs, basis + straight tail,
+rotating the arrowhead alone); every one bought squareness by adding
+inflections, and inflections are what read as busy. `curveBasis` stays exactly
+what mermaid uses. `faceOffset` generalises the projection to diamonds, circles
+and hexagons, whose boundary is not a box.
+
+**A refusal is a normal answer, and needs no new failure path.** `renderDiagram`
+returns `null`, and both call sites already handled that: `export.ts`'s fence
+loop substitutes only non-null results, and the app's `DiagramView` falls back
+to `HighlightedCode`. So an undrawn diagram is exactly the highlighted code
+block a mermaid fence rendered as before this existed. `diagnoseDiagram` reports
+*why* through `narrate`'s `warnings` (`diagram_unsupported`,
+`diagram_parse_error`) — the same real decision the renderer takes, over fences
+found by `fromMarkdown` rather than by a pattern. The first draft scanned for
+them with a regex three lines under a comment forbidding exactly that, and it
+disagreed with the renderers in both directions: a mermaid fence quoted inside
+a longer ```` fence warned about a diagram that was never going to draw, and
+one inside a blockquote drew but was never diagnosed.
+
+**Nothing from a fence reaches the output as markup.** Labels are escaped;
+`<br/>`, `<b>` and markdown strings are parsed into styled runs, which become
+`<tspan>`s whose attributes `svg.ts` writes itself; `style` declarations are
+filtered to seven properties with a value charset that excludes `url(`, and
+`font-weight`/`font-style` to their keywords.
+There is deliberately **no `<style>` element** — an inline SVG's `<style>` is
+*document*-global, so one diagram's `text { font-family }` would restyle every
+other diagram on the page. Theming is CSS custom properties
+(`--brane-diagram-*`) **whose fallbacks are brane's dark palette**, and marker
+ids are hashed per source so two diagrams on a page cannot share an arrowhead.
+The fallbacks matter more than the properties: nothing defines the latter, and
+the first draft shipped light-mode values that drew `#33373d` lines on the
+app's `#121214` and the export's `#000`.
+
+**Labels have two grammars, and only one of them is markdown.** In a plain
+label (`A[text]`, `A["text"]`) mermaid honours `<br/>`, `<b>`, `<i>`,
+`<code>`, `<u>`, `<s>` and their kin, and `**x**` is two asterisks, on GitHub
+too. A **markdown string** (``A["`text`"]``) is the other: the backticks just
+inside the quotes are mermaid's marker, not over-quoting, and inside one
+`**bold**` and `*italic*` render, a newline is a line break, and long lines
+wrap. `label.ts` parses each into runs (`{ text, bold?, italic?, code?,
+strike?, underline? }`) that the IR carries beside the plain `lines` links and
+search still read. A markdown string goes through `fromMarkdown`, so "bold" means
+here what it means in prose. It can span source lines, so the parser joins a
+statement until every ``"` `` it opened is closed, held to `MAX_LINE_LENGTH`
+like a line. Wrapping is mermaid's 200px at its 16px, scaled to brane's 14px:
+the em width is what decides where a line breaks, and an unscaled 200px kept
+together words that GitHub splits. Bold is measured with Helvetica-Bold's own
+advances, so a bold head gets the box it needs. `font-weight` and
+`font-style` from `style` or `classDef` are folded into the runs in layout, so
+what is measured is what is drawn. Everything that still shows as typed (`**`
+in a plain label, an unknown tag, a link in a markdown string) comes back from
+the same parse as a `diagram_label_literal` warning that says how to style it.
+The diagram still draws. It is a note, not a refusal.
+
+A node's markdown string may also hold a **GFM table**, which mermaid does not
+draw at all ("Unsupported markdown: table"). Brane draws it, and that is
+allowed for two reasons. The fence is still valid mermaid, so GitHub shows the
+fallback text and nothing breaks. And the drawing is static SVG made on the
+daemon, so the HTML export carries no rendering logic for it (the condition
+the operator set, claude-uwaj0umf:33). A table is a `TableBlock` among the
+label's lines and takes `1 + rows` line slots. Its columns share widths, which
+is the one thing a stack of centred `<tspan>`s cannot express, so a node
+holding one is drawn as a `<text>` per line or cell on the same baselines the
+stack would have used. Header cells are bolded at parse time, so measurement
+and drawing agree without either knowing which row is the header. Edge labels
+and subgraph titles have no box for a grid, so there a table shows as source,
+with a warning. Plain labels also decode character references (`&lt;`,
+`&#x2192;`, `&rarr;`) after tags are scanned, as mermaid's HTML labels do, so
+a decoded `<` is never read as a tag.
+
+**The parser runs on the `narrate` path, so its cost is a security property.**
+`diagnoseMarkdown` calls it for every narration containing a mermaid fence, no
+route and no operator involved. The first draft's inline-label patterns were
+`-{2,}\s+(.+?)\s+-{2,}>` — three overlapping quantifiers over whitespace,
+cubic in the run length, 1.5 s on a 2,000-space line and 8× per doubling, with
+`MAX_SOURCE_BYTES` no defence because it bounds *n* while the cost is n³. Label
+groups now anchor both ends on a non-space and exclude their own link's
+punctuation, there is a `MAX_LINE_LENGTH`, and `diagram-review.test.ts` asserts
+the complexity rather than the timing. Treat any future regex here the same
+way.
+
+**A wrong diagram is worse than no diagram.** Three of the review findings on
+the original PR were *silent*: `A -.-> B -.-> C` drew one edge and dropped a
+node, `A --- B --> C` likewise, and an edge into a subgraph id threw inside
+dagre, was caught, and fell back with no warning at all — breaking the "warns
+iff the operator sees source" rule below. The parser now refuses each with a
+reason. When in doubt, refuse: the reader gets source and the author gets told.
+
+**Self-loops are never given to dagre, and bow off a face no rank edge uses.**
+Dagre returns a degenerate path for `A --> A` — duplicated points that double
+back and start outside the node — so a loop is synthesised as an arc, with its
+label past the apex. It leaves a *cross-axis* face (right in TD/BT, bottom in
+LR/RL): dagre gives every edge `minlen` 1, so edges arrive only on the
+rank-facing sides, and a loop there put its label exactly where they cross —
+on the Rule 30 board, 101's label read as the 110→101 edge's. Dagre is told
+about the loop by a box grown on the cross axis (`loopBox`), which keeps
+neighbours clear: a TD/BT diagram's height (the chat bubble's) drops against
+#504's layout, and an LR/RL one's grows, since its loops now hang below the
+node — the price of labels that no longer sit on rank edges. Edges on a
+loop-bearing node are pinned to its rank faces, and run straight along the
+rank axis from dagre's widened box to the drawn face (`rankKnot`), so a steep
+edge's last leg can't cut the corner of a chip wider than the node. A bow's
+drawn apex is 23/24 of its control depth; label placement depends on it. Stacked loops step outward by
+each chip's extent along the bow, and an outer bow flares past every chip
+inside it. `diagram-self-loop-labels.test.ts` holds each chip against every
+other edge's drawn *path*, not just other chips — the check the first
+version lacked. Parallel and antiparallel edges, by contrast, dagre separates
+correctly on its own.
+
+Native renders the code block: there is no DOM to put an SVG into, and the
+honest options are their own change.

package/docs/doctor.md

@@ -0,0 +1,36 @@
+# Doctor
+
+`brane doctor` answers "is this install sound?" on the machine it landed on.
+It prints a short table of environment checks and then runs the **shipped
+test suite** — `dist/test/*.test.js` ships in the tarball on purpose — under
+the same `node` that runs the CLI, streaming the reporter and exiting with
+its status. The suite needs no daemon, tmux, network, or model download: the
+search tests inject a stub embedder and the wiki/fold tests use temp dirs and
+in-memory SQLite, so a red result is the install, not the environment.
+
+No test may open the operator's database. `openDatabase()` throws when
+`NODE_TEST_CONTEXT` is set (which `node --test` does in every test process),
+so a code path that reaches it without a `db` fails its test instead of
+opening `~/.brane/brane.db` and running migrations on it — from a checkout or
+from `doctor` on an installed machine. Code the suite drives takes a `db`
+(`getConfig(key, db)`); tests build theirs with `createTestDb()`.
+
+Two tests read *source* rather than import code (`api-request.test.ts` lints
+`expo/lib/api.ts`; `key-routing.test.ts` lints two `.tsx` files). The source
+isn't in the tarball, so they `skip` with a reason when it's absent — green by
+construction from an install, still enforced from a checkout. A source-reading
+test added later must do the same, or `doctor` goes red on every install.
+
+The daemon check asks two questions: is one running (and from which
+checkout), and can *this shell* reach it. Outside an agent session the CLI
+holds no token and reaches the daemon only over `~/.brane/daemon.sock`, so
+the check fails, with the reason, when the daemon is not listening there or
+`~/.brane` is not `0700` and its own (`shellReachProblem()`). A `– token
+file` line appears when `~/.brane/.daemon_token` is still on disk: older
+branes kept this machine's local token there, the daemon empties it at its
+first start, and removing the leftover is the operator's to do, with the
+`rm` line printed (`leftoverTokenFile()`; see [No local
+token](token-rotation.md#no-local-token)).
+
+`--no-suite` runs only the environment checks; `--suite-only` runs only the
+tests (`brane doctor --suite-only` is the one-liner for a bug report).

package/docs/export-scope.md

@@ -0,0 +1,69 @@
+# Export Scope
+
+An export is the whole conversation, the messages the operator picked, or
+everything but them. The picking is not new: the chat has kept a selection
+since `re` chips existed — tap a bubble's timestamp and its seq joins
+`selectedSeqs` (`expo/app/[nid].tsx`), which is what the composer attaches
+to the next signal as `re`. Export reads the same set, as *"these ones"* or
+as *"all but these"*.
+
+| Piece | Where | Does |
+|---|---|---|
+| `MessageSelection` | `src/shared/message-selection.ts` | The selection itself, with per-seq subscriptions — see [The Selection Store](selection-store.md) |
+| `formatSeqParam` / `parseSeqParam` | `src/shared/export-selection.ts` | The `seqs=12,14,19` grammar, both halves in one module; `src/test/export-selection.test.ts` |
+| `SeqSelectionMode` | `src/shared/export-selection.ts` | Which side of it: `only` (the default) or `except`, on the wire as `seqs_mode` |
+| `selectedCount` / `ExportScope` | `src/shared/narrative-menu.ts` | Splits the 🦠 item into **📨 Export 2 selected** and **📤 Export 2 excluded**, and tells the press which one — the list card has no selection and passes nothing |
+| `ExportOptions.seqs` / `.seqsMode` | `src/export.ts` | Keeps (or drops) those events, counts the gaps, writes the disclosure |
+
+Seven things are less obvious than they look:
+
+**An excerpt says it is one, in the line that used to say how many.**
+`Exported … · 3 of 47 messages` is the whole disclosure, and it is
+load-bearing: the reader of an exported file is generally not the operator
+who made it, and a 3-message document that does not mention the other 44
+reads as a short conversation rather than a quotation from a long one.
+
+**A gap between two shown messages is marked; a gap before or after them is
+not.** `⋯ 4 messages not shown` sits between non-adjacent picks, because
+two bubbles stacked in a transcript otherwise assert adjacency — the one
+claim an excerpt must never make by accident. What was dropped from the
+ends is already covered by the header's count, and marking it would put an
+elision row at the top of nearly every excerpt.
+
+**Anchors stay `#seq-N`.** Rows are not renumbered, so `nid:seq` citations
+into an excerpt mean what they mean everywhere else, and a full export and
+an excerpt of the same narrative agree on every link. It is also why the
+selection travels as seqs rather than as an index range.
+
+**An unreadable `seqs` exports everything rather than failing.** An export
+is a read; a 400 would cost the operator their transcript over a typo in a
+URL they probably did not type. Empty, absent, and junk all mean "no
+selection", and `{ seqs: [] }` is byte-identical to the export brane made
+before this parameter existed — pinned by `src/test/export.test.ts`.
+
+**The mode's tolerance runs one way.** Only the exact word `except`
+inverts an export; `Except`, `exclude`, `1` and junk all read as `only`.
+The asymmetry is the point: a garbled `only` hands the operator a document
+whose header already says how much of the conversation it holds, while a
+garbled `except` would hand them the *complement* of what they asked for —
+and a selection is as often "the messages nobody else should read" as it is
+"the interesting ones". For the same reason the parameter is written only
+when it changes something, so an ordinary excerpt's URL is unchanged.
+
+**An excerpt's file name carries its count; a redaction leaves the summary
+out.** The 💾 button saves `<nid>.html` for a full export and
+`<nid>.3-of-47.<digest>.html` for either scope (`exportFileName`): the count
+the header discloses, plus six hex digits naming exactly which seqs it holds.
+The count alone gave `only` and `except` of a half-selection one name, and
+they are the pair a redaction exists to keep apart. Like the header, the name
+doesn't say which side of the line was taken. An `except` export drops
+the narrative's summary, which is agent-written over the whole conversation
+and can paraphrase exactly what was left out.
+
+**The complement reads the conversation; the excerpt does not.** `seqs IN
+(…)` is an index lookup per selected message, which is why exporting two
+messages out of ten thousand costs two rows. Excluding two of ten thousand
+exports 9,998 of them, so it reads the log and drops the picks — a full
+export's cost, which is what it is. Both scopes then disclose identically:
+`3 of 47` and `44 of 47` are both excerpts, and neither says which side of
+the line it took.

package/docs/files-view.md

@@ -0,0 +1,133 @@
+# Files View
+
+How the daemon serves a narrative's fold to the Files tab, what it can show, and how 🔎 searches a binary.
+
+## Files API
+
+`GET /api/files?nid=<nid>&path=<rel>` browses the filesystem under a narrative's `fold_path`. The route is `browseFold()` (`src/files/browse.ts`), a pure function of (fold, path, options) so the suite drives it without HTTP. The response is discriminated on `type`:
+
+- `{ type: "directory", path, entries: [{ name, is_dir, size, mtime, archive?, link? }], archive? }` — dotfiles hidden
+- `{ type: "file", path, size, mtime, content, truncated?, binary?, highlight?, hex?, link?, notice?, archive? }`
+
+`highlight` is a pre-tokenized Shiki payload (`{ lang, theme, bg, fg, tokens }`) so the client renders colored code without shipping a highlighter to the browser. Adding `&raw=1` streams the bytes instead of JSON, for any file: the `src` for images and PDFs, and **Download** for a file too large to show (which, before, got JSON back). `&offset=N` asks for the hex page at byte N of a binary file. A path may run through an archive (`dist/app.zip/src/main.ts`); what that means is [Files View Formats](#files-view-formats).
+
+Path handling is traversal-confined: absolute paths are rejected, `#`/`?` fragments are stripped, the target is `resolve()`d and must equal the fold root or sit beneath it. The echoed `path` is normalized so breadcrumbs never render `fold/./blah`.
+
+`GET /api/files/list?nid=<nid>` returns `{ files, truncated }` — a flat path list for the whole fold, feeding the client-side fuzzy finder. It does not descend into archives: that would mean opening every one in the fold to answer a keystroke.
+
+## Files View Formats
+
+What the Files view can show is one of brane's quiet advantages, so it is
+kept as a census, and a format that renders is pinned by a test that builds
+it byte by byte (`src/test/files-browse.test.ts`, which needs no `zip` or
+`tar` binary, so it runs under `brane doctor` too).
+
+| File | Shown as | By |
+|---|---|---|
+| Source and text | Shiki-highlighted code with line anchors | `CodeView` |
+| Markdown (`.md`, `.mdx`, and `.md.gz`) | Rendered, math and diagrams included | `MarkdownContent` |
+| Images, PDFs | Inline image; pdf.js pages | `<img>`, `PdfView` |
+| **Anything else** | Hex, `xxd`-style, 16 KB a page, 16 bytes a row (8 on a phone), searchable to the last byte | `HexView` |
+| `.zip` and its kin (`.jar` `.war` `.aar` `.apk` `.ipa` `.whl` `.epub` `.docx` `.xlsx` `.pptx` `.odt` `.nupkg` `.vsix` `.xpi` …) | A folder | `src/files/zip.ts` |
+| `.tar`, `.tar.gz`/`.tgz`, `.tar.br`, `.tar.zst` (Node ≥ 22.15) | A folder | `src/files/tar.ts` |
+| `.gz`, `.br`, `.zst` | What they compress, named by what's inside | `archiveFormatFor` |
+
+**PDFs use pdf.js's legacy build.** `PdfView` imports `public/pdf.min.mjs`
+and its worker at runtime, and both come from `pdfjs-dist/legacy/build/`
+(`npm run sync:pdfjs` in `expo/`, output committed). The modern `build/`
+calls `Map.prototype.getOrInsertComputed` with no fallback, so on a browser
+without it the first `page.render` throws and every page stays blank. The
+legacy build carries the core-js polyfills, worker included, for about 60 KB.
+
+**Hex is the floor.** A file is binary when a NUL appears in its first 8000
+bytes, git's rule, and it pages rather than truncating, so a 50 MB `.so` is
+browsable where a 3 MB log still gets "too large". Before, anything that was
+not an image or PDF was decoded as UTF-8 and shown as noise. Pages sit where
+they belong in the file, in whatever order they were loaded, with a gap row
+for each run between them (`⋯ 1,228,800 bytes not loaded`, and ↓ / ↑ to
+load the 16 KB on either side); `hexSegments` in `src/shared/hex-pages.ts`
+lays that out. The pages live in a `HexDoc` (`expo/lib/hexDoc.ts`) rather
+than the view's state, because 🔎 loads them too.
+
+## Searching the bytes
+
+🔎 on a hex file is the daemon's, not the DOM's. It used to search the text
+of the pages already loaded, which missed three ways: nothing on an unloaded
+page existed, a string that wrapped a row was split by the offset and hex
+columns between its halves, and `cffaedfe` never matched a column that reads
+`cf fa ed fe`. `GET /api/files/find` (`src/files/find.ts`) reads the bytes
+themselves, through the `ByteSource` the hex page reads, so an archive member
+or a `.gz` body is searched as it is shown.
+
+A query is matched as its UTF-8 text, smart-case like 🔎 everywhere else,
+and, when it is a run of hex pairs (`cf fa ed fe`, `cffaedfe`, `0xCAFE`), as
+those bytes as well: `cafe` finds the word and 0xCA 0xFE both. A hit is
+painted by byte range in the hex column and the gutter alike
+(`expo/lib/hexFind.ts`), one range per row it spans.
+
+**What a search returns is bounded by pages, not by the file.** Hits come
+from at most the first 64 hex pages that have any (1 MB, as much as the view
+will hold), and at most 5,000 of them. A one-byte query in a 2 GB binary
+therefore stops after a megabyte of hits instead of reading two gigabytes
+for hits nobody will visit; the status line pinned above the rows says so
+and offers **Search on from 0x…**, the next window. The drum rolls over
+every hit in the window and **fetches nothing while it rolls**: the page
+under a hit loads when the drum comes to rest on it, and until then the
+hit's gap row stands where it will be. Measured in headless Chromium: a
+30-hit roll across a 40 MB file made no page requests while rolling and one
+at rest.
+
+The other bounds are against accidents: a token holder can already type into
+every tmux session.
+
+| Bound | Why |
+|---|---|
+| One pass per request (`ByteSource.chunks`), never re-reading a compressed prefix | Paged requests would re-inflate a `.gz` from its start each time |
+| Stops at the reach limit, and says so (`stop: "reach"`) | `chunks` throws `ReachError` where `stream()` would end quietly |
+| 30 s of scanning, then `stop: "time"` and a `next` to resume from | A slow disk or a vast file doesn't hold a request open indefinitely |
+| At most 2 scans daemon-wide; a third supersedes the oldest (`FindSlots`) | The likeliest third is the same reader's next keystroke |
+| The app debounces 200 ms and aborts the previous request, and a closed request stops the read | Typing `NEEDLE` is one scan, not six |
+| Needles of at most 256 bytes | A needle is held in every chunk's carry, and nothing a reader types is longer |
+
+Hits are reported in offset order across chunk seams, two needles included:
+a hit is reported only once every needle that could start before it has been
+seen whole. That is what makes the page count a running count and `next` a
+resume point that skips nothing, and `src/test/files-find.test.ts` holds it
+against a naive search over 200 randomized splits.
+
+**An archive is a folder, and nothing is extracted.** A `ByteSource`
+(`src/files/bytes.ts`) is anything the view can open: a file, an archive
+member, a `.gz` body. Every renderer reads through `respondWithSource`, so a
+member gets highlighting, images, hex and download for free. A zip is listed
+from its central directory (one read, nothing inflated) and a member inflates
+alone; a tar is one pass over its headers with the data skipped, cached per
+(path, size, mtime) because a compressed tar has no index. Archives do not
+nest: a zip inside a zip opens as hex.
+
+The usual archive vulnerabilities come from *extracting*, and there is no
+extraction here:
+
+- **Zip-slip, symlink and hard-link entries, overwrites, setuid bits:** not
+  applicable, since nothing is written. Member names are only displayed.
+  `normalizeMemberName` drops leading slashes and hides any name with `..`
+  or a NUL, counting it (`archive.skipped`, shown as a banner) rather than
+  drawing it somewhere it doesn't belong. Links are shown with their target
+  and never followed; a tar hard link resolves once, to an earlier member of
+  the same archive.
+- **Decompression bombs:** a read decodes only as far as it asked for and
+  tears the pipeline down (`sliceStream`), so output is bounded by the
+  request, never by a size the archive claims. Opening a 64 MB-of-zeros
+  member decodes one 16 KB page. No read reaches past 1 GB into a
+  compressed stream (`MAX_STREAM_REACH`), which bounds the CPU any one
+  request can spend, and a tar listing stops at 1 GB decoded or 200,000
+  members and says it is partial.
+- **Parser bugs:** the readers are TypeScript plus Node's own zlib. No
+  archive tool is shelled out to: `unzip` and `bsdtar` are C with CVE
+  histories, and bsdtar in particular auto-detects dozens of formats nobody
+  asked it to parse. Every zip offset is checked against the file's real
+  size before it is read. A malformed archive throws, and a file that isn't
+  what its name claims shows as the file it is.
+
+Refused, with the reason shown in the view: encrypted zip members,
+compression methods other than stored and deflate, and device or FIFO
+entries.

package/docs/link-previews.md

@@ -0,0 +1,38 @@
+# Link Previews
+
+A brane URL pasted into iMessage, Slack, Discord or Telegram gets a card,
+and the card is built from the HTML the URL serves — by a fetcher that
+never runs the bundle. That bounds what the card can be, and the bound is
+by design: the daemon's host and token ride in the fragment ([View
+URLs](view-urls.md)), which no fetcher sends, and the daemon itself is
+tailnet-only. So a card can carry what brane *is* and what it looks like,
+never a narrative's title, summary or messages. (iMessage is the one app
+that unfurls on the *sender's* device, which is on the tailnet — but a
+direct-daemon link still serves the same shell, so it sees the same card.)
+
+The card is `og:*` and `twitter:card` tags in **`expo/public/index.html`**,
+the template that actually ships, with `app/+html.tsx` kept in step the way
+the KaTeX and manifest links are. The picture is the 膜 — a still of the
+real `Membrane` component, not a hand-ported approximation of its shader —
+at `public/og/membrane.v<N>.png` (1200×630, the size every unfurler renders
+as a large card), plus `public/apple-touch-icon.png` (180×180, which is
+what iMessage's small card and an iOS home-screen add use; the SVG favicon
+counts for neither). `expo/scripts/og-membrane/render.mjs` produces both
+by mounting the component alone in a headless Chromium and screenshotting
+it; each run rolls a fresh scheme, so run it until a frame pleases, then
+**bump the version in the filename and in both `og:image` tags** — iMessage
+caches a preview by URL until the URL changes. `src/test/link-preview.test.ts`
+pins that the two heads agree, that the URL names a file `public/` ships at
+the declared size, and that the name is versioned.
+
+Two things are less obvious than they look:
+
+**The image URL is absolute, on the shared host.** A daemon's own bundle
+serves this same `index.html`, and a phone unfurling a direct-daemon link
+can still fetch `https://brane.organelle.dev/og/…` — a relative path would
+point at the daemon, which the fetcher may or may not reach.
+
+**Stills only.** iMessage, Telegram, Discord and Facebook will animate an
+`og:video` loop, and Slack alone offers an interactive card, through a
+registered app. Neither is used: the card is a picture, by decision
+(claude-hun39p6w:10).

package/docs/math.md

@@ -0,0 +1,32 @@
+# Math Rendering
+
+LaTeX in narrative markdown renders through **KaTeX**, in the app and in the HTML export alike. The two call the *same* `renderMathHtml()` in `src/shared/markdown-math.ts`, which is what makes an export a snapshot of the live view rather than a lookalike of it — the export contains no script, so all rendering happens ahead of time.
+
+| Piece | Where | Does |
+|---|---|---|
+| `renderMathHtml()` | `src/shared/markdown-math.ts` | The one KaTeX call. `htmlAndMathml`; unparseable LaTeX falls back to the literal source, not KaTeX's red error markup |
+| `prepareMathMarkdown()` | `src/shared/markdown-math.ts` | Pre-parse normalization, run by both sides before micromark/mdast |
+| `mathHtmlExtension()`, `katexStyleFor()` | `src/math.ts` | Export only: micromark hookup, and the inlined stylesheet |
+| `public/katex/` | `expo/` | The app's stylesheet + woff2, vendored by `npm run sync:katex` |
+| `diagnoseMarkdown()` | `src/markdown-diagnostics.ts` | The same pipeline run to *report* rather than render — see [Rendering Warnings](rendering-warnings.md) |
+
+**Every delimiter an LLM might reach for.** Which one a model writes is house style, not a standard, and the difference is stark: across the 42,521 events this was built against, `\(…\)` appears 1576 times and `\[…\]` 351 — all from absorbed ChatGPT history — against 578 single-dollar runs, which are mostly Claude's. A `$`-only reader would leave two thirds of the corpus as prose. `prepareMathMarkdown` normalizes the lot into the `$` forms before parsing, so one syntax reaches both renderers:
+
+| Written | Becomes | Renders |
+|---|---|---|
+| `$x$` | unchanged | inline |
+| `$$x$$` alone on a line | fenced `$$` | display |
+| `\(x\)` | `$x$` | inline |
+| `\[x\]` alone on a line | fenced `$$` | display |
+| ` ```math ` fence | fenced `$$` | display |
+| ` ```latex ` fence | unchanged | source listing, as intended |
+
+Unlike `$`, the TeX pairs are unambiguous and need no guard — nothing in ordinary prose looks like them (0 false positives across all 1576). KaTeX also gets a `\*` → `*` macro: that isn't TeX, it's a model escaping an asterisk so markdown won't read emphasis and leaving the escape inside the math. It accounts for 13 of the 18 equations in the archive KaTeX would otherwise reject.
+
+Two more things are less obvious than they look:
+
+**`$` is mostly not a delimiter.** Narratives are full of prices, shell variables and awk fields, and `micromark-extension-math` is more permissive than Pandoc — it reads `$10k–$500k` as math over `10k–`. `prepareMathMarkdown` escapes the openers that fail a Pandoc-style guard (no space just inside a delimiter, no digit after the closer, no `${…}`, no raw `"`) before parsing, since the extension offers no veto once it has tokenized. It also promotes a one-line `$$…$$` paragraph to the fenced form, which is the only shape the extension renders in display mode. Both sides must run it or exports stop matching the app.
+
+**Fonts don't come along by themselves.** KaTeX lays its span tree out entirely in CSS and needs its woff2 faces; without them math is a pile of overlapping glyphs. The export inlines only the families the document reaches for (~166 KB of base64 for an equation-dense narrative, nothing at all for one with no math), derived from the stylesheet so a KaTeX upgrade can't silently drop a face. The app can't inline per document, so it serves `public/katex/` — vendored the way `pdf.min.mjs` already is, because metro bundles a CSS *import* but never copies the `url(fonts/…)` it points at. The `<link>` lives in **`public/index.html`**, which is the real HTML template; `app/+html.tsx` is kept in step but is not what ships.
+
+`src/shared/markdown-math.ts` is also the first shared module to import an npm package. Metro resolves a module's dependencies from its own directory and `src/shared` sits outside the expo project root, so `metro.config.js` maps `katex` explicitly — the next shared module with a bare import will need the same.

package/docs/mcp.md

@@ -0,0 +1,69 @@
+# MCP and the LIVE Loop
+
+The MCP bridge, how a parked `listen` wakes and retires, the LIVE loop tools, and narrative metadata.
+
+## MCP Architecture
+
+The MCP server (`src/mcp/server.ts`) is a **thin stdio↔WebSocket bridge**. It has zero SQLite dependency. All tool logic (narrate, listen, whoami, revive, etc.) lives in the daemon at `src/daemon/server.ts`.
+
+**Error handling convention**: Use `sendToolError()` for real errors (maps to MCP `isError: true`), not `sendToolResult({ error: ... })`. The bridge at `src/mcp/server.ts` translates `tool_error` → `isError: true` on the MCP response. Foreign narration to non-existent narrative IDs returns a tool error.
+
+When `brane spawn` creates an agent session, it sets `BRANE_NARRATIVE_ID` as a tmux session environment variable (not in the MCP config file). The MCP bridge process inherits this from the tmux environment at startup. This allows multiple agents to share the same fold without conflicting MCP configs. The one exception is Copilot, which requires explicit env in its per-session config file since it doesn't inherit parent env vars into MCP subprocesses.
+
+### Listen Wakeup
+
+**The caller's own words never interrupt its waiting.** `checkForEvents`
+returns everything in range but reports an *arrival* only for an event whose
+server-stamped `source` isn't the caller, so an agent's own narration (here or
+narrated into another narrative) neither wakes its parked listen, ends its
+waiting narrate, nor returns a blocking listen at once. It is still returned
+alongside whatever does arrive, and a `wait: false` read returns it on its
+own. #515 dropped those events from forward reads instead, and an agent that
+resumed after compaction with a remembered cursor lost them silently; the
+daemon can't tell that read from any other. Pinned by
+`src/test/listen-own-words.test.ts`.
+
+**A listen outlives nothing.** A parked listen (or waiting narrate) whose
+socket closes is retired by the MCP close handler — `cleanup()` unregisters
+its wakeups, its tool row settles, and no reply is built — and `wakeup`
+refuses to answer on a socket that isn't `OPEN`. Otherwise the next event
+ran its `reply`, and the mention receipt inside it marked mentions sent
+(and read) into a socket that drops the send.
+
+**Nor does it outlive its caller's patience.** Esc, or killing a
+backgrounded tool task, reaches the bridge as MCP `notifications/cancelled`.
+The bridge forgets the call (a late result is dropped, never sent) and sends
+the daemon `tool_cancel`; `cancelMcpCall` retires the parked call as the
+close handler does, and the awaiting glow goes out at once. Before, the bridge answered the notification "Method not found" (an
+error with no id, which Claude Code logs as a connection error) and the
+daemon never heard, so a cancelled listen glowed until the next event or the
+hour-long timeout. Notifications are never answered, known or not. Pinned by
+`src/test/mcp-bridge-cancel.test.ts` and `src/test/awaiting.test.ts`.
+
+The daemon uses a `listenWaiters` map to immediately wake blocked `listen` calls when new events arrive. When a signal is sent or a narration is written, `notifyListenWaiters(nid)` fires all registered callbacks for that narrative. This replaces polling and gives near-instant delivery.
+
+`narrate({ wait: true })` is a narrate followed by a listen in one call, so an exchange costs the agent one re-read of its context instead of two. `handleMcpNarrate` writes the narration and returns a `NarrateWaitPlan`; the dispatcher hands the plan to `startMcpListen`, which parks on the plan's cursor with the new narration filtered out wherever it landed (`omit` in `checkForEvents`) and returns listen's result plus the narration's `nid`, `seq` and `warnings`. There is no second waiting mechanism: wakeup, poller, timeout, mention receipt and shutdown flush are listen's, and the pending entry carries its `toolName` so the narrate's row is the one that settles. `narrateWaitCursor` accepts any cursor `listen` does, multi-narrative included (claude-2il811nw:31); with none, it waits from the current heads of the caller's narrative and, for a foreign narration, the target's. `before`/`tail` have nothing to wait for, and they fall back rather than refuse: the narrate posts as usual and its receipt carries `wait_ignored`, since a refusal would cost the agent the narration and a turn to resend it. On a lost daemon connection the bridge tells a pending narrate to check before re-narrating rather than to retry, since a waiting narrate has always already posted.
+
+## LIVE Loop Protocol
+
+Agents communicate via cursor-based long-polling. Read `protocols/LIVE_loop.md` for full details.
+
+Core tools available via MCP:
+
+| Tool | Purpose |
+|------|---------|
+| **narrate** | Vocalize status + receive pending signals (non-blocking) |
+| **listen** | Block until signals arrive (long-poll with timeout) |
+| **whoami** | Get narrative ID and brane ID |
+| **revive** | Restart a dead agent session |
+| **narrative_search** | Semantic search across narrative history |
+| **narrative_info** | Get narrative info: browse recent narratives or get details on specific ones |
+| **list_peers** | List active LIVE-loop agent peers, grouped by fold |
+| **list_branes** | List all branes hosted by this daemon (caller's home first) — use to expand `narrative_search` / `narrative_info` across branes |
+| **list_protocols** / **read_protocol** | Access protocol documents |
+
+## Narrative Metadata
+
+Narratives have persistent `summary` and `title` columns. Agents set them via the `meta` parameter on `narrate`. The daemon broadcasts metadata changes over the control WebSocket as `type: "meta"` messages. The Expo app renders the summary as a subtitle below the narrative ID.
+
+Narratives can be **archived** via `PATCH /api/narratives/:id/archive`. Archived narratives are hidden from the default list but preserved in the database.

package/docs/memory-search.md

@@ -0,0 +1,75 @@
+# Memory and Search Ranking
+
+How narrative history is indexed for semantic search, and how hybrid search ranks what it finds.
+
+## Memory System
+
+The memory system provides semantic search across narrative history:
+
+- **Vector embeddings** via `onnxruntime-node` directly (bge-small-en-v1.5, 384-dim) — `embedder.ts` does the four steps brane used from `@huggingface/transformers` (tokenize → ONNX session → masked mean pool → L2 normalize), producing vectors identical to the pipeline it replaced (worst cosine 0.9999996), so existing `memory_vec` rows stay valid. Tokenization is `wordpiece.ts`, a WordPiece port whose ids match transformers.js exactly. The model cache layout (`~/.brane/models/<repo>/<file>`) is unchanged, so existing caches carry over.
+- **FTS5 full-text search** for keyword matching
+- **Hybrid search** combining both approaches — see [Search Ranking](#search-ranking)
+- **Auto-indexing** of new events on first search
+- CLI: `brane memory search <query>`, `brane memory log`, `brane memory index`
+- MCP: `narrative_search` and `narrative_info` tools
+
+## Search Ranking
+
+`searchHybrid` (`src/memory/storage.ts`) fuses **three ranked arms**, and that it
+fuses *ranks* rather than *scores* is the whole design.
+
+| Arm | Query | For |
+|---|---|---|
+| ALL | `prepareFtsQuery` — FTS5 implicit AND | A remembered fragment. Precise; returns nothing for a question |
+| ANY | `prepareFtsAnyQuery` — content terms ORed | A question. Always answers; ranks loosely |
+| vector | KNN over `memory_vec` | Rows sharing no terms with the query at all |
+
+Each contributes `weight / (RRF_K + rank)`; the fused total is then multiplied by
+how much of the query the row actually contains.
+
+**Scores from different arms are not comparable, and pretending otherwise
+inverted the ranking.** The vector arm's number is a cosine — measured across
+this archive it spans 0.62–0.73 for *everything*, a band so narrow it barely
+orders anything — while the lexical arms' is a squashed bm25 topping out near
+0.7 for an excellent hit. Blending those, plus a flat `+0.5` awarded for **any
+single** query term appearing, produced the failure this replaced: for
+`self-inflicted instance restarted the daemon four times today`, the only chunk
+in 43,876 containing all eight terms came back **11th**, behind ten one-line
+operator signals ("Restart* daemon", "Daemon is restarted") that each held one
+word and sat near the query in embedding space. Over 60 verbatim quotations
+pulled from real events, the source ranked first **50%** of the time; under rank
+fusion, **90%** (top-10: 85% → 98%).
+
+Four things are less obvious than they look:
+
+**Coverage ranks; it does not gate.** A row is credited for the *fraction* of
+query terms it holds — 1-of-8 and 8-of-8 used to score identically. But
+qualifying as lexical evidence is a **count** (`MIN_TERM_HITS`), not a fraction,
+because a fraction punishes long queries for being long: a narration matching 2
+of 8 terms of a paraphrased question is real evidence that a 50% gate discards.
+
+**The ANY arm exists because AND silently disables half the search.** No chunk
+contains all thirteen words of a natural-language question, so the strict arm
+returns zero candidates exactly when the query is hardest — leaving the vector
+arm alone, which on this corpus finds a quotation's own source only a third of
+the time. Stopwords are dropped from ANY (ORed, `the` matches most of the
+archive) and kept in ALL, where every term is a restriction and narrows for
+free.
+
+**The length penalty is gated on lexical evidence, not on `match`.** They differ
+for precisely the rows it exists to catch: a two-character chunk sitting close to
+the query clears `MIN_SEMANTIC_SCORE`, gets tagged `semantic`, and would sail
+past a `!match` guard. Similarity to a very short string is cheap, and is not
+evidence that the string answers anything.
+
+**The `weak` floor is relative.** A fused rank has no absolute meaning to
+threshold against — it depends on how many arms returned the row and how deep
+each went — so the old `score >= 0.35` constant would pass everything or nothing
+as `limit` moved. Quoted phrases remain the one filter allowed to return nothing;
+every other path still degrades to best-effort guesses rather than a blank page.
+
+`src/test/search-fusion.test.ts` pins each defect as the smallest corpus that
+reproduces it, with hand-chosen vectors. Deliberately **not** an aggregate
+accuracy figure: the same probe read 52%, 50% and 37% across one afternoon
+purely as new events were indexed, so a percentage over the live archive would be
+a flaky test. A percentage says something regressed; these say which thing.