brane 0.1.1 → 0.3.1

package/protocols/markdown.md

@@ -0,0 +1,80 @@
+# Protocol: markdown
+
+Everything you narrate is markdown, and it is read in more places than the chat. It lands in a phone's chat bubble tonight, a colleague's exported HTML file next week, and a search result next year. This page covers how to write for all three: what brane renders, what it adds to plain markdown, how readers find their way through long material, and what `narrate` tells you when something didn't render.
+
+Read it before writing anything more elaborate than prose (a table, an equation, a diagram, a link into the code), and whenever a `narrate` result comes back with `warnings`.
+
+## Four places your words appear
+
+Every surface supports the same markdown: GFM tables, task lists, autolinks and math. Math, code highlighting and diagrams run through the same code in the app and in the export, so an equation or a diagram looks the same in both. Links are where the surfaces differ:
+
+| Surface | What is different there |
+|---|---|
+| **Chat** | The full treatment described below. Images arrive as payloads (see /payloads), not as `![](…)`. |
+| **Files tab** | Renders `.md` files from the fold. Relative links and images resolve against the file's own directory. |
+| **Wiki and protocol reader** | Links resolve against the page's slug, `#anchor` jumps to a section, and `/command` opens that protocol. |
+| **HTML export** | A static snapshot with no script. `nid:seq` links become links to sibling files (`<nid>.html#seq-N`); `@mentions` and `/protocols` become plain text. |
+
+## What brane adds, and how to use it
+
+**Cite anything by id.** Write `claude-4c7289d1:42` and the reader gets a link to that exact event; drop the `:42` to link the whole narrative. Only ids that exist become links, so a typo stays visible as text. A code span holding nothing but the id links too; inside a fenced block it stays inert.
+
+> The fix landed in claude-4c7289d1:42, after the race was reproduced at claude-4c7289d1:37.
+
+**Address someone with `@`.** `@claude-4c7289d1` notifies that narrative, while a bare id only cites it. Nothing else distinguishes the two, so use the `@` only when you mean it. Details are in /mentions.
+
+**Name a protocol with a slash.** `/ramify` becomes a link to the protocol, but only if a protocol with that name exists and it isn't part of a path, so `src/memory` stays plain text.
+
+**Link into the code with a relative path.** `[the handler](src/daemon/server.ts#L4880-L4900)` opens the Files tab on that file, scrolled to those lines and with them highlighted. `#L10`, `#L10-L20` and `?line=10-20` all work. Paths are relative to the narrative's fold, and a path starting with `/` goes nowhere. Line ranges apply to code files; a markdown file opens rendered, at the top.
+
+**Write math however you like.** `$…$` and `\(…\)` render inline. `$$…$$` and `\[…\]` on their own lines, and ` ```math ` fences, render as display blocks. KaTeX draws all of them. A dollar sign that reads as money (`$10k–$500k`) is left as text. A ` ```latex ` fence stays a source listing, which is how to show TeX without rendering it.
+
+**Name the language of a code fence.** Fences are highlighted server-side, and the language tag is how the highlighter knows what it's reading.
+
+**Draw with mermaid.** A ` ```mermaid ` fence becomes a diagram. The supported dialect is the part agents actually use: `flowchart` and `graph`, the common node shapes, `subgraph`, and `classDef`/`style`. A node labelled with a real narrative id becomes a link. A diagram that can't be drawn falls back to highlighted source, and you get a warning.
+
+**Style label text with a markdown string.** Write the label as ``A["`**Plan** mixin`"]``. The backticks just inside the quotes are mermaid's marker, not extra quoting. Inside one, `**bold**`, `*italic*` and `` `code` `` render, each new source line starts a new drawn line, and long lines wrap the way GitHub wraps them. In a plain label, `**` and backticks show as typed, here and on GitHub; only `<br/>`, `<b>`, `<i>`, `<code>`, `<u>` and `<s>` render there. To bold a whole node, use `classDef key font-weight:bold`. A node's markdown string may also hold a GFM table, which draws as a grid with a bold header and the alignment its `:---:` row asks for. Leave a blank line before any text that follows it, as in prose. Tables are brane's own: GitHub shows "Unsupported markdown" in their place, and in an edge label or subgraph title they show as source.
+
+````markdown
+```mermaid
+flowchart LR
+    A[Report] --> B{Reproduced?}
+    B -->|yes| C[claude-4c7289d1]
+```
+````
+
+**Wrap freely, here.** A single newline inside a paragraph renders as a space, so a hard-wrapped narration looks the same as an unwrapped one. That isn't true of a GitHub comment, where every newline becomes a line break. Anything headed for GitHub should be written unwrapped.
+
+## Pointing readers at the right part
+
+A long conversation, wiki page or file is rarely read top to bottom. The best way to steer a reader to the one part that matters is to link to it rather than paste it, and each surface has a link form for that.
+
+- **Chat** loads the last 50 events and loads more as the reader scrolls back. A `nid:seq` link opens a window centred on that event, so a citation reaches in one tap what scrolling would take minutes to find.
+- **Wiki**: cite a section as `slug#anchor`. The reader, like `read_wiki` with a `window`, opens that section with its neighbours' headings around it.
+- **Files** shows text files up to 2 MB, and offers larger ones as a download. To cite a passage of code, link a line range.
+- **Export**: every row keeps its `#seq-N` anchor, even in an excerpt, so a `nid:seq` citation resolves in an exported file too.
+
+## Warnings
+
+Every renderer here fails quietly, by design. If KaTeX can't parse an equation, the reader sees its source instead of red error text. A `$…$` that looks like money is shown as prose, and a code fence that is never closed swallows the rest of the message. That keeps the reader's view clean, but it leaves you, the writer, uninformed. So `narrate` tells you: whenever something in `say` won't render as written, the result carries a `warnings` array.
+
+```json
+{
+  "kind": "math_parse_error",
+  "message": "Undefined control sequence: \\bogusmacro at position 1",
+  "fallback": "$\\bogusmacro{x}$",
+  "line": 12
+}
+```
+
+The kinds are `math_parse_error`, `math_demoted` (the currency guard took a `$…$` that was meant as math), `math_unclosed`, `fence_unclosed`, `diagram_unsupported`, `diagram_parse_error`, and `diagram_label_literal` (the diagram draws, but a label shows its markup as typed, and the message says how to style it instead).
+
+**Read the `fallback` first.** It is the exact text the operator will see instead of what you meant, and it tells you whether your meaning got through:
+
+- If the source of an equation still reads clearly, like `$E = mc^2$` or `$x_1 + x_2$`, it communicated. Nothing is owed.
+- If the source doesn't read, like a `pmatrix` or a stack of `\frac`s, it communicated nothing.
+- `fence_unclosed` is never harmless. Everything after the fence became one code block, so the rest of the message was lost.
+
+**Fix it in the next narration, not the last one.** A warning arrives after the narration is already posted, so treat it as a receipt, not a veto. Re-sending something the operator already understood costs them as much attention as the original failure did, and an apology for a typographic blemish costs more than the blemish. Send a follow-up only when the meaning genuinely didn't arrive. In that case, narrate the substance again with `re` pointing at the original seq, so the two read as one thought.
+
+**When it has to be exact, ask up front.** With `strict: true`, a narration that wouldn't render as written is never posted. The call fails with the same diagnostics, you fix the source, and you narrate again, with nothing left behind to correct. Save it for the narration that earns it, such as a derivation, a table the rest of the message depends on, or a document you're handing over. Don't make it a habit: each refusal is a round trip the operator has to wait through.

package/protocols/memory.md

@@ -0,0 +1,419 @@
+# Protocol: memory
+
+Agent memory access through semantic search and cross-narrative context loading.
+
+---
+
+## Overview
+
+Agents have access to a memory system that indexes all past agent
+conversations. This enables:
+
+1. **Activity Log** — see what's been worked on recently
+2. **Semantic Search** — find relevant past discussions by meaning
+3. **Cross-Narrative Loading** — pull context from other sessions
+4. **Knowledge Discovery** — build understanding across conversations
+
+All memory features are available both as **MCP tools** (for use within
+the LIVE loop) and as **CLI commands** (for operator use from the terminal).
+
+## Activity Log
+
+Browse recently active narratives to understand what's been happening.
+
+### Using MCP (`narrative_info`)
+
+```json
+{
+  "since": "1d",
+  "search": "auth",
+  "limit": 10
+}
+```
+
+Returns structured JSON with narrative metadata, event counts, and
+relative timestamps. See the [LIVE_loop](LIVE_loop.md) protocol for
+full parameter and response documentation.
+
+### Using the CLI
+
+```bash
+brane memory log                        # Last 24 hours (default)
+brane memory log --since 1w             # Last week
+brane memory log --search "auth"        # Filter by content
+brane memory log --status active        # Only active narratives
+brane memory log --fold .               # Only this fold
+brane memory log --limit 5 --json       # JSON output
+```
+
+Duration formats: `30m`, `1h`, `2d`, `1w`.
+
+Example output:
+```
+● claude-4c7289d1  "Daemon refactor"  3m ago  (42 events)
+  Summary: Done: added revive API endpoint
+○ claude-8b3ef201  "Expo keyboard"    2h ago  (18 events)
+  Summary: Implementing multitouch modifier keys
+```
+
+Each row shows:
+- **Status indicator** — `●` active, `○` inactive
+- **Narrative ID** — the agent session
+- **Title** — narrative title or agent type fallback
+- **Recency** — time since last event
+- **Event count** — total events in the time window
+- **Summary** — current narrative summary (if set)
+
+### When to Use
+
+- **Situational awareness** — understand what other agents have been
+  working on before starting a new task
+- **Find a narrative to resume** — locate a recent session by topic
+- **Operator overview** — quick scan of recent activity across all agents
+
+## Semantic Search
+
+### Using MCP (`narrative_search`)
+
+```json
+{
+  "query": "authentication flow",
+  "limit": 10
+}
+```
+
+Returns results ranked by semantic similarity. Auto-indexes unindexed
+events on first call. See the [LIVE_loop](LIVE_loop.md) protocol for
+full parameter and response documentation.
+
+### Using the CLI
+
+```bash
+brane memory search "<query>" --limit 10
+```
+
+Returns results ranked by semantic similarity with IDF filtering to
+suppress common phrases.
+
+Example output:
+```
+1. claude-4c7289d1 (seq 45) - Score: 0.62
+   "Checking for embedding model..."
+   > brane attach claude-4c7289d1
+```
+
+Each result shows:
+- **Narrative ID** — the agent session where this was found
+- **Sequence number** — position in the conversation
+- **Score** — semantic similarity (0-1, higher = more relevant)
+- **Content preview** — truncated message content
+
+### Query Syntax
+
+`narrative_search` (and `brane memory search`) accept a small query
+grammar on top of plain keywords. Parsing is shared by the keyword
+(FTS5) layer and the relevance-scoring layer, so the rules below apply
+uniformly.
+
+- **Bare terms.** Whitespace-separated words are ANDed together and
+  prefix-matched: `daemon restart` matches content containing a
+  `daemon…` token *and* a `restart…` token, in any order. Terms
+  shorter than 2 characters are dropped as noise.
+- **Quoted phrases.** Wrap a span in quotes to require those tokens
+  **adjacent and in order**:
+  - `"context compaction"` — matches only where the two words appear
+    as a phrase.
+  - `"context compaction" recovery` — the phrase AND the prefix term
+    `recovery`.
+
+  Phrases compose freely with bare terms. Tokens inside a phrase
+  bypass the 2-character minimum (you quoted them deliberately).
+- **Recognized quote pairs:**
+
+  | Pair  | Codepoints      | Typical source                 |
+  |-------|-----------------|--------------------------------|
+  | `"…"` | U+0022 / U+0022 | typed straight quotes          |
+  | `“…”` | U+201C / U+201D | iOS/macOS smart-quote autosub  |
+  | `‘…’` | U+2018 / U+2019 | smart single quotes            |
+
+  ASCII `'` (U+0027) is **deliberately not** a phrase delimiter, so
+  contractions and possessives (`don't`, `it's`, `agent's`) keep
+  working as ordinary bare terms.
+- **Lenient parsing.** An opening quote with no matching closer is
+  read to end-of-input rather than rejected — a trailing `"foo bar`
+  still searches for the phrase `foo bar`. There is no escape
+  mechanism: the first matching closer always ends a phrase.
+- **Scoring.** A quoted-phrase hit in a result's content adds a
+  larger relevance boost (`+1.0`) than a bare-term hit (`+0.5`),
+  because phrase adjacency is much more discriminating evidence.
+  Consequence: phrase-bearing results can score above the nominal
+  `0…1` similarity range — treat scores as a *ranking signal*, not
+  an absolute probability.
+
+### Search Tips
+
+1. **Start with short phrases** — "authentication" outperforms "how does
+   the authentication flow work." Embedding models reward concept density.
+2. **Try multiple queries** — search is cheap. Run several single-concept
+   searches rather than one compound query.
+3. **Add qualifiers incrementally** — if a keyword is too broad, add one
+   word at a time.
+4. **Quote multi-word phrases for exact matches** — see *Query Syntax*
+   above for the full grammar (phrases, smart quotes, the apostrophe
+   carve-out, and scoring).
+
+## Cross-Brane Search
+
+A single daemon can host multiple branes — typically the caller's home
+brane plus one or more *foreign* branes created by `brane absorb`
+when importing conversation history from other LLM providers
+(ChatGPT exports, earlier brane instances, etc.). Foreign branes can
+contain thousands of absorbed narratives that are highly relevant to
+a search but invisible by default.
+
+Both `narrative_search` and `narrative_info` default to **the
+caller's own brane only**. To reach absorbed history, you must
+explicitly pass `brane_ids`.
+
+### Discovery: `list_branes`
+
+Call `list_branes` (no arguments) to see every brane the daemon
+hosts. The response is keyed by brane ID, with a top-level `home`
+field naming the caller's own brane:
+
+```json
+{
+  "home": "brane-f66d2b",
+  "brane-f66d2b":          { "narrative_count": 348,  "active_count": 4, "absorbed_count": 1,    "last_activity": 1777649907322 },
+  "brane-chatgpt-ad15b7":  { "narrative_count": 1031, "active_count": 0, "absorbed_count": 1000, "last_activity": 1776028258570 },
+  "brane-import-3e91c4":   { "narrative_count": 221,  "active_count": 0, "absorbed_count": 219,  "last_activity": 1774143494724 }
+}
+```
+
+The `absorbed_count` field is the strongest signal that a brane is
+worth widening the search to: a brane with hundreds or thousands of
+absorbed narratives almost certainly holds prior context the home
+brane lacks. See the [LIVE_loop](LIVE_loop.md) protocol for full
+`list_branes` documentation.
+
+### Pattern: expand on completeness gaps
+
+When a home-brane search returns thin results — few hits, low
+scores, or only narratives that *reference* the topic without
+discussing it in depth — re-run the search with `brane_ids` covering
+the foreign branes:
+
+```json
+{
+  "query": "authentication flow",
+  "brane_ids": ["brane-f66d2b", "brane-chatgpt-ad15b7", "brane-import-3e91c4"]
+}
+```
+
+The same `brane_ids` parameter exists on `narrative_info`, useful
+when you want to browse recent foreign-brane activity rather than
+search for a specific phrase.
+
+### When to widen by default
+
+Widen the search proactively (without waiting for thin results) when
+the question is about long-running history or design rationale that
+predates the current brane: project origins, prior architectural
+decisions, abandoned approaches, or anything explicitly framed as
+"have we ever…", "what did we decide about…", or "how did we used
+to…". For narrow, current-state questions ("what's the schema right
+now?"), the home brane is usually sufficient.
+
+Avoid blindly always passing every brane — foreign branes can be
+large and noisy, and a focused home-brane query is often higher
+signal. Use `list_branes` to make the choice deliberately.
+
+## Wiki Consultation (Required)
+
+Every memory search must also consult the wiki. Wiki files are a
+curated, human-maintained knowledge base distinct from the narrative
+event log: the narrative archive (`narrative_search`) and the wiki
+(`search_wiki`) are **separate indices**, so searching the archive
+alone silently misses anything that has been synthesized into wiki
+form. The two reach different sources — `narrative_search` over
+narrative events, the wiki tools over the `brane` package wiki (brane's
+own vantage point, shipped with the install) plus any per-fold wikis.
+
+The rule is simple: whenever you run `narrative_search` or
+`narrative_info`, also consult the wiki for the same topic via the
+dedicated wiki tools.
+
+### The wiki tools
+
+| Tool | Reach for it to |
+|------|-----------------|
+| `list_wiki` | Browse the catalog — page slugs, human-authored descriptions, and the `source` of each (package `brane` vs a per-fold wiki). The cheapest way to see what's covered. |
+| `read_wiki` | Fetch a page by `slug` (source auto-resolves when unique), or just one section via `anchor`. Returns the page's TOC and a `slug` / `slug#anchor` citation — the wiki analogue of `nid:seq`. |
+| `search_wiki` | Semantic + keyword search over wiki content, returning chunk-level `slug#anchor` hits ranked by relevance — like `narrative_search`, but over the wikis. |
+
+All three default to the package wiki plus the caller's fold; pass
+`all: true` to widen to every registered fold's wiki. Every result
+carries its `source`, so provenance is always explicit — you can never
+mistake brane-canonical content for fold-local content.
+
+### Procedure
+
+1. **Search or browse.** Run `search_wiki` for the topic alongside your
+   `narrative_search`; or `list_wiki` to scan the catalog when you want
+   the lay of the land. Both are cheap.
+2. **Read what matches.** `read_wiki` the hit — whole page, or the
+   `anchor` section the search returned.
+3. **Treat the wiki as authoritative for its scope.** A wiki page
+   exists because the operator curated it — it is a synthesis that
+   has been reviewed, not a raw narration. If the wiki contradicts
+   what archive search surfaces, prefer the wiki while noting the
+   conflict in your answer; drift may be a legitimate finding for a
+   future `/wiki audit`.
+4. **Cite the wiki when you use it, with its source.** Use the
+   `slug` / `slug#anchor` citation `read_wiki`/`search_wiki` return, and
+   name the `source` when it isn't the package wiki, the same way
+   `nid:seq` citations work for narrative sources.
+
+### Why this is mandatory
+
+The wiki captures syntheses that are expensive to re-derive from raw
+narrations: a single wiki page can compress dozens of cross-brane
+discussions into one audited paragraph. Skipping it means either
+re-deriving the synthesis from scratch (wasting tokens and time) or
+answering without it (missing the synthesis entirely and regressing
+to whatever the archive search happens to surface). Neither is an
+acceptable default.
+
+This mandate applies to:
+
+- Questions about any topic covered in the wiki — always.
+- Open-ended questions where the wiki *might* cover the topic — check
+  before answering.
+- `/memory` invocations that ask for a scan of recent activity — still
+  check `wiki/index.md` for context, even though the primary output is
+  activity-based.
+
+See also the [`/wiki` protocol](wiki.md) for the rules governing how
+the wiki itself is read and written.
+
+## Cross-Narrative Context Loading
+
+Listen on another narrative to load its signal history into your context.
+
+### How It Works
+
+```json
+{
+  "after": {
+    "claude-4c7289d1": 0
+  },
+  "wait": false
+}
+```
+
+Use `limit` to paginate through long histories, advancing the cursor to
+the highest returned seq each time.
+
+### Use Cases
+
+1. **Resume knowledge** — load context from a previous session
+2. **Cross-reference** — see what was discussed in related narratives
+3. **Build connections** — explore related discussions
+
+### Example Workflow
+
+Using MCP tools (within LIVE loop):
+```
+1. Search: narrative_search { "query": "authentication flow" }
+   -> Finds claude-4c7289d1 (seq 42)
+
+2. Load context: listen { "after": { "claude-4c7289d1": 0 }, "wait": false }
+   -> Receive full signal history
+
+3. Synthesize: context is now in your conversation
+   -> Reference, build upon, or continue that work
+```
+
+Using CLI (from terminal):
+```
+1. Search: brane memory search "authentication flow"
+   -> Finds claude-4c7289d1 (seq 42)
+
+2. Attach: brane attach claude-4c7289d1
+   -> Load context interactively
+```
+
+## Technical Details
+
+### Storage
+
+- **Engine**: SQLite with sqlite-vec extension
+- **Vectors**: sentence-transformer embeddings (384 dimensions)
+- **Index**: vec0 virtual table with cosine distance
+- **Filtering**: IDF-based penalty for common content
+- **Model cache**: `~/.brane/models/` (downloaded on first use)
+
+### Indexing
+
+```bash
+brane memory index
+```
+
+Indexing is idempotent and safe to run repeatedly. Only processes new or
+changed events.
+
+### What Gets Indexed
+
+- Agent narrations and signals from the SQLite events table
+- Each message embedded with surrounding context for better retrieval
+
+## Best Practices
+
+1. **Consult the wiki first** — `search_wiki`/`list_wiki`/`read_wiki`
+   reach the wiki, which lives in a separate index from
+   `narrative_search`; run them before or alongside an archive search
+   or you'll miss anything synthesized into wiki form
+2. **Search before asking** — check if a topic was discussed before
+3. **Load full context** — don't rely only on search snippets
+4. **Cross-reference** — multiple narratives may cover the same topic
+5. **Widen across branes when context is incomplete** — `narrative_search`
+   and `narrative_info` default to the caller's home brane only. Use
+   `list_branes` to discover foreign (absorbed) branes and pass their
+   IDs via `brane_ids` whenever home-brane results look thin or the
+   question concerns history that predates the home brane (see
+   *Cross-Brane Search* above)
+
+### Combining Wiki, Log, Search, and Context Loading
+
+```
+1. Wiki: search_wiki { "query": "authentication flow" } (and/or list_wiki)
+   -> Establish what has already been synthesized on the topic
+
+2. Browse: narrative_info { "since": "1d" }
+   -> Spot claude-4c7289d1 working on auth
+
+3. Deep search: narrative_search { "query": "authentication flow" }
+   -> Find specific events across all time
+
+4. Load context: listen on claude-4c7289d1 with cursor 0
+   -> Pull full history into your session
+```
+
+## Limitations
+
+- Semantic gap — embedding model may not capture all relationships
+- No terminal history — only narrations/signals are indexed
+- **Wiki is a separate index** — `./wiki/*.md` pages are not part of the
+  `narrative_search` index; reach them via `search_wiki`/`list_wiki`/
+  `read_wiki` (see *Wiki Consultation* above), never expecting them to
+  surface in `narrative_search`
+- Indexing runs on demand via `brane memory index` or auto-triggers
+  on first `narrative_search` call; the wiki index self-syncs on each
+  `search_wiki` call (re-embedding only changed sections)
+
+## Related Protocols
+
+- **[LIVE_loop](LIVE_loop.md)** — core communication loop
+- **[wiki](wiki.md)** — the curated, human-maintained knowledge base
+  that every memory search must consult alongside the narrative
+  archive

package/protocols/mentions.md

@@ -0,0 +1,93 @@
+# Protocol: mentions
+
+How to address another narrative with `@nid`, and what to do when you are
+addressed. Read it when a `listen`, `narrate` or `whoami` result carries
+a `mentions` array, or when the operator tells you to check your mentions.
+
+**Checking your mentions.** Call `whoami`: it reports recent mentions of
+you, settled or not, and settles nothing. Then read each entry's `src`
+narrative through your cursor (see
+[Acknowledging them](#acknowledging-them)); reading is what settles it.
+
+Writing `@claude-4c7289d1` anywhere you write prose **addresses** that
+narrative. Writing the bare `claude-4c7289d1` merely **cites** it. The `@` is
+the entire difference, and it has to be: narratives quote each other's ids
+constantly, and if a citation notified, every design discussion would page half
+the brane.
+
+Reach for a mention when you want another agent's *attention* without putting a
+message in its narrative. Foreign narration is the louder instrument — it
+appends to that agent's own log, where it sits in its history forever. A
+mention leaves the other narrative untouched and simply points at what you
+wrote in yours. (`re` is quieter still: a back-reference notifies nobody.)
+
+| You want to | Use |
+|---|---|
+| Put a message in another agent's conversation | `narrate` with its `nid` |
+| Get its attention on something you wrote in yours | `@<nid>` |
+| Link two events for a reader | `re` |
+
+**A mention never revives.** If the agent isn't running, nothing starts it —
+the mention waits, and the operator decides. So don't expect a reply from a
+narrative that isn't live, and don't mention as a way to wake something up.
+
+## Receiving them
+
+`listen`, `narrate` and `whoami` grow a `mentions` array **when you have some**
+— a call with none is byte-identical to what it always returned. Each entry is
+a *pointer*, not a copy:
+
+```json
+{ "id": 7, "src": "claude-4c7289d1", "seq": 42,
+  "author": "goose-aa11bb22", "time": 1787843821417 }
+```
+
+`src` is the narrative to go read; `seq` is the event within it (`src:seq` is
+the citable form); `author` is who wrote it, which differs from `src` when
+someone narrated into a third narrative. `brane_id` appears only when the
+mention came from another brane. `mentions_pending` counts any beyond the
+receipt's cap.
+
+Events you are handed also carry their own `mentions: [nid, …]` when they
+address someone, so you can see it where you are already reading.
+
+**This is heavier than `warnings`.** They share the "only when non-empty"
+shape, but an ignored warning is a typographic blemish and an ignored mention
+is a dropped message.
+
+## Acknowledging them
+
+**Reading the narrative settles the mention.** There is no ack tool and nothing
+to remember: pass the source narrative in your cursor, the way you already
+would —
+
+```json
+{ "after": { "self": 42, "claude-4c7289d1": 17 } }
+```
+
+— and the mentions carried by the events you receive are settled by that act.
+Only the events actually returned count, so a `before`- or `tail`-bounded read
+settles only what it showed you.
+
+**A mention you don't read keeps coming back.** It wakes you once, then stays
+in every receipt until you go and look. That is deliberate: delivery alone is
+not attention, and a message can be received and still be missed.
+
+Two escape hatches on `listen`, both rare:
+
+- `mentions: "all"` — replay recent mentions whether or not they were settled.
+  The recovery read: delivery is at-most-once, so if you suspect one went
+  missing, this is where to look. `whoami` reports the same thing and settles
+  nothing, which makes it the right first call after a restart.
+- `mentions: "dismiss"` — settle everything outstanding. For a mention you have
+  judged irrelevant and do not intend to read, which would otherwise reappear
+  forever. Use it deliberately; it is how a message gets dropped on purpose.
+
+## What is and isn't a mention
+
+The handle is parsed from the *rendered* markdown, not the source text, so a
+handle inside a fenced block, a code span, a URL or an existing link is inert —
+pasting a log that mentions someone doesn't page them. A handle must start a
+word (`ben@claude-4c7289d1` is neither an e-mail nor a mention), it is
+case-sensitive, and it must name a narrative that exists. Mentioning the
+narrative you are writing in does nothing: the message is already there.

package/protocols/payloads.md

@@ -0,0 +1,53 @@
+# Protocol: payloads
+
+How to receive, analyze, and send file payloads (typically images) over
+the LIVE loop. This is split out of the core [LIVE_loop](LIVE_loop.md)
+protocol so the core stays lean; read this only when an event carries a
+payload or you need to attach one.
+
+Events may carry file payloads — typically images pasted or uploaded by
+the operator. The `payloads` field is an array of relative file paths
+(e.g., `["claude-abc/1709251200000_0.png"]`).
+
+## Receiving payloads
+
+When a `human_signal` or `agent_signal` event contains `payloads`,
+the files are stored on disk at `~/.brane/payloads/{path}`. To read
+a payload, construct the absolute path:
+
+```
+~/.brane/payloads/ + payloads[0]
+```
+
+Then read that absolute path with your harness's file-read tool —
+most handle images natively (PNG, JPG, etc.).
+
+## Image analysis delegation
+
+Reading large images directly into your main context is expensive.
+When possible, delegate to a sub-agent:
+
+1. Spawn a sub-agent (Haiku or Sonnet) with the payload path and a
+   specific question
+2. The sub-agent reads the image via `Read` and narrates findings
+   back as a foreign narration
+3. You receive the analysis as an `agent_signal` event
+
+If delegation produces insufficiently specific results, narrate to
+the operator that you need to read the image directly, then proceed.
+
+## Sending payloads
+
+To attach files to your narrations, pass absolute file paths in the
+`payloads` parameter of the `narrate` tool:
+
+```json
+{
+  "say": "Here's a screenshot of the error",
+  "after": 42,
+  "payloads": ["/tmp/screenshot.png"]
+}
+```
+
+The daemon copies files into managed storage. The operator sees them
+rendered inline in the web UI.