brane 0.0.2 → 0.3.0

package/AGENTS.md

@@ -0,0 +1,362 @@
+# Brane — Agent Development Guide
+
+This file is loaded into every agent session in this fold, so it stays an
+**index**: the rules that apply to every change, how to build, and a map of
+where everything else is written down. The design write-ups for each
+subsystem live in [`docs/`](docs/); read the one for the area you are about
+to touch (see [Further Reading](#further-reading)) before changing it.
+
+**Keep it that way.** A new subsystem's design notes go in a new or existing
+`docs/<topic>.md`, and this file gets one line in [Further
+Reading](#further-reading) pointing at it. A rule belongs here only if it
+applies to changes everywhere in the repo.
+
+## What Is This?
+
+Brane is a TypeScript reimagining of the [organelle](https://github.com/benjamn/organelle) system. It provides:
+
+- A CLI (`npx brane` or `node dist/cli.js`) built with **citty**
+- A background **daemon** (HTTP + WebSocket) with SQLite persistence
+- An **Expo web app** for mobile control over Tailscale
+- An **MCP server** (stdio↔WebSocket bridge) injected into agent sessions
+- **Terminal mirroring** of tmux sessions with keyboard input
+- The **LIVE loop** protocol for cursor-based agent communication
+- A **semantic memory** system with embeddings and full-text search
+- **Multi-agent support** with session resumption across 6 agent types
+
+## Golden Rule
+
+**Never delete files, directories, database records, git branches, or any other artifacts without explicit operator approval.** If your task seems to require deletion, stop and ask the operator first. Prefer renaming, archiving, or commenting out over deletion. The cost of keeping something is low; the cost of losing it can be catastrophic.
+
+## Commits, Sign-off, and Accountability
+
+`CONTRIBUTING.md` is the policy; this is what it asks of an agent.
+
+- **Never add `Signed-off-by:`**, on your own behalf or the operator's. Only a human can certify the Developer Certificate of Origin, and a sign-off written by an agent is a false certification. Responsibility for a change attaches to the human who submits or merges it.
+- **Keep the disclosure trailer.** Commits you write carry `Co-Authored-By: <agent> <model> <noreply@anthropic.com>` (Claude Code adds it). Never strip, rewrite, or backdate one, yours or another agent's.
+- **Never merge, and never approve a PR.** `main` is PR-only; open the PR, report CI, and stop. The human who merges is the one taking responsibility for the change.
+- **Never run `npm publish`** — see [Releasing](docs/releasing.md).
+
+## Repository Layout
+
+```
+brane/
+├── src/
+│   ├── cli.ts                 # CLI entry (citty)
+│   ├── agents.ts              # Agent adapter interface (claude, goose, gemini, codex, amp, copilot)
+│   ├── commands/              # Subcommands (see CLI Commands below)
+│   ├── daemon/server.ts       # HTTP/WS server, terminal streaming, MCP bridge
+│   ├── daemon/client.ts       # CLI-side daemon client (find-or-start, JSON API calls)
+│   ├── db/schema.ts           # SQLite schema, helpers (better-sqlite3)
+│   ├── db/events.ts           # Event append-log operations
+│   ├── memory/                # Semantic search system
+│   │   ├── embeddings.ts      # Worker-thread façade over the embedder
+│   │   ├── embedder.ts        # ONNX session + mean pool + normalize (onnxruntime-node)
+│   │   ├── wordpiece.ts       # BERT WordPiece tokenizer, parity-pinned to transformers.js
+│   │   ├── index.ts           # Search orchestration (hybrid vector + FTS5)
+│   │   └── storage.ts         # Chunk storage and indexing state
+│   ├── files/                 # GET /api/files: browse.ts (the route), zip.ts, tar.ts, archive.ts, bytes.ts
+│   ├── markdown-diagnostics.ts # Rendering warnings returned by narrate
+│   ├── mcp/server.ts          # Thin stdio↔WebSocket MCP bridge
+│   └── test/                  # Node test suite
+├── expo/                      # React Native web app
+│   ├── app/[nid].tsx          # Narrative detail (chat + terminal tabs)
+│   ├── app/_layout.tsx        # Root layout, WebSocket control channel
+│   ├── app/index.tsx          # Narrative list
+│   ├── components/            # MacroMenu, TerminalPane, TerminalKeyboard
+│   ├── lib/                   # api.ts, terminal.ts, connection.ts, registry.ts
+│   └── dist/                  # Built web bundle (served by daemon)
+├── worker/                    # Cloudflare Workers deployment (serves expo/dist as SPA)
+├── protocols/
+│   ├── LIVE_loop.md           # Core agent communication protocol
+│   ├── digest.md              # /digest protocol for activity summaries
+│   └── memory.md              # Semantic search protocol
+├── docs/                      # Per-subsystem design notes (see Further Reading)
+├── dist/                      # Compiled TypeScript output
+├── SECURITY.md                # Security model documentation
+├── DESIGN.md                  # Architecture documentation
+├── tsconfig.json              # ES2022, NodeNext, strict
+└── package.json               # Node 20+, ESM
+```
+
+## Building
+
+```bash
+# Compile TypeScript (server + CLI)
+npx tsc
+
+# Build Expo web bundle
+cd expo && npx expo export --platform web
+
+# Run tests
+npx tsc && node --test dist/test/*.test.js
+```
+
+Output goes to `dist/` (server) and `expo/dist/` (web app).
+
+`build` and `build:server` sweep `dist/` first (`scripts/clean-dist.mjs`, via
+`prebuild` hooks): `tsc` only ever adds files, so without the sweep a checkout
+accumulates outputs whose source is gone and `npm pack` ships them. Because
+the sweep makes tsc create `dist/cli.js` fresh (mode 0644), `postbuild` hooks
+run `scripts/chmod-bin.mjs` to put the execute bit back on every `bin` target;
+without it an `npm link`ed `brane` vanishes from the shell (`which` skips
+non-executable files) while `node dist/cli.js` keeps working.
+
+### When to rebuild
+
+- **Server-side TypeScript changes** (`src/`): `npx tsc` then `brane daemon restart`
+- **Expo app changes** (`expo/`): **`npm run build`** (not just `npx tsc`) then `brane daemon restart`
+- **Protocol/markdown changes** (`protocols/`): **No rebuild needed.** The daemon reads protocol files from disk at runtime via `readFileSync`.
+- **Both server + expo**: `npm run build` (runs tsc + expo export)
+
+### Releasing
+
+Publishing to npm is done by `.github/workflows/release.yml`, triggered by a
+published GitHub release, and only by it. **Agents never run `npm publish`.**
+The version bump, tag rule, dist-tag choice and why there is no provenance
+attestation are in [docs/releasing.md](docs/releasing.md).
+
+## CLI Commands
+
+| Command | Purpose |
+|---------|---------|
+| `daemon` | Manage daemon lifecycle (start, stop, restart, status, logs) |
+| `spawn` | Spawn new agent sessions (`--attach`, `--model`, `--role`, `-- <args>`) |
+| `attach` | Attach to a tmux session |
+| `list` | List narratives grouped by brane (`--brane`, `--archived`, `--limit`) — reads `GET /api/narratives` + `GET /api/branes` |
+| `fold` | Register directories as spawn points (`--brane` to associate with a brane) — delegates to `POST /api/folds` |
+| `meld` | Generate QR code for mobile access (defaults to `brane.organelle.dev`, `--local` for direct); waits for Touch ID at this machine — see [Presence Check](docs/presence.md#the-gate). `--remote --send … --ask …` melds a daemon on another machine (a Fly machine: /fly) with a token minted here, and refuses in an agent's session |
+| `mcp` | MCP stdio server (used internally by agent sessions) |
+| `revive` | Restart dead agent sessions (`--prompt`, `--no-prompt`, `--agent`) — delegates to `POST /api/revive/:nid` |
+| `config` | Get/set brane configuration (git-config style: `--list`, `--unset`) |
+| `certify` | Force-refresh TLS certificates (daemon auto-provisions and renews on its own; this is a manual escape hatch) |
+| `absorb` | Import conversation history: from provider exports (`chatgpt`, `organelle`) or from agent session stores on this machine (`claude`); `survey` lists what the machine has (`--fold`, `--brane`, `--identity`, `--dry-run`, `--since`, `--session`, `--rebuild`) — delegates to `GET /api/absorb/survey` and `POST /api/absorb`, printing its progress stream |
+| `memory` | Semantic search and indexing (`search`, `log`, `index` subcommands) — clients of `POST /api/search`, `GET /api/narratives/recent`, `POST /api/memory/index`. `log --archived` to include absorbed history, which is archived by construction |
+| `cost` | Cost ledger maintenance (`backfill [--dry-run] [--all]`, `reprice [--dry-run] [--all]`) — delegates to `POST /api/cost/backfill` and `POST /api/cost/reprice` |
+| `token` | Daemon bearer tokens (`list`: the Devices list; `revoke <id> [--cascade]`: sign out one device, and with `--cascade` the devices it added; `rotate`: sign out every web client, keep this shell; revoking a device and rotating wait for Touch ID, see [Presence Check](docs/presence.md#the-gate)) — delegates to `GET /api/tokens`, `POST /api/tokens/:id/revoke` and `POST /api/token/rotate`; from the shell, which holds no token, rotate is one request — see [Token Rotation](docs/token-rotation.md) |
+| `doctor` | Check the install: Node vs `engines`, `tmux`, Tailscale, daemon status, which checkout it runs from and whether this shell can reach it over `daemon.sock`, a leftover `.daemon_token`, then the shipped test suite (`dist/test`) against this install — see [Doctor](docs/doctor.md) |
+
+## Database
+
+Single SQLite database at `~/.brane/brane.db` (WAL mode). Key tables:
+
+| Table | Purpose |
+|-------|---------|
+| `meta` | Instance ID, daemon port/pid/version/tls/http_port/socket, config |
+| `tokens` | Daemon bearer tokens as SHA-256 hashes only (`local`: one row for this machine's CLI, which no token opens; `device` per meld, `agent` per narrative session, handed to it as `BRANE_NARRATIVE_SECRET`), revoked never deleted — see [Token Rotation](docs/token-rotation.md) |
+| `folds` | Registered spawn directories (path, brane_id, created_at) |
+| `narratives` | Agent sessions (id, brane_id, agent_type, role, status, fold_path, title, summary, archived, agent_session_id) |
+| `events` | Append-only event log: (narrative_id, seq, time, type, content, content_type, source, re, payloads, meta) |
+| `memory_chunks` | Event chunks for embeddings |
+| `memory_vec` | Vector embeddings for semantic search (sqlite-vec) |
+| `memory_fts` | FTS5 full-text search table |
+| `memory_cursors` | Per-narrative indexing cursors |
+| `memory_stats` | Indexing statistics |
+| `usage_ledger` | Durable per-message / per-session cost rows — see [Cost Ledger](docs/cost-ledger.md) |
+| `absorb_messages` | (brane, provider, message id) → (narrative, seq): the per-message dedup that makes re-absorbing a session store idempotent — see [Absorb](docs/absorb.md) |
+| `absorb_files` | (brane, provider, session) → (size, mtime) at its last absorb, so an unchanged file is skipped on a stat |
+
+Event types: `narration` (agent), `human_signal` (operator), `agent_signal` (cross-agent).
+
+## Agent Adapters
+
+Brane supports multiple agent types with session resumption. Each agent has an adapter in `src/agents.ts`:
+
+| Agent | Resume Method | Notes |
+|-------|--------------|-------|
+| `claude` | `--resume <session_id>` | Discovers session from `~/.claude/projects/` |
+| `goose` | `-r` | Resumes by session name |
+| `gemini` | (none) | Uses `-i` for prompt injection |
+| `codex` | `resume <session_id>` | Subcommand-based resumption |
+| `amp` | (none) | Uses thread references `@T-<id>` in prompt |
+| `copilot` | `--session-id <session_id>` | Daemon-pinned UUID resumes the exact local session |
+
+Spawning a session generates agent-specific MCP config. This happens in `doSpawn()`, which always runs in the daemon — `brane spawn` gets it by delegating to `POST /api/spawn`, not by writing these files itself:
+- **Claude**: `.mcp.json` in fold directory
+- **Goose**: `--with-extension` argument with env passthrough
+- **Gemini**: `.gemini/settings.json` project-level config
+- **Codex**: `~/.codex/config.toml` with env references
+- **Copilot**: Per-session `.brane-copilot-mcp-<nid>.json`
+
+## Security Model
+
+See `SECURITY.md` for full details. Key features:
+
+- **TCP-level IP filtering** — only allows localhost, Tailscale IPs, RFC 1918 private ranges, and CGNAT
+- **TLS auto-provisioning + renewal** — daemon shells out to `tailscale cert` at startup if no valid cert exists, renews when <30d remain, hot-reloads via `setSecureContext` on file change; when TLS is active, an HTTP fallback server (private IPs only) runs on a separate port for local/LAN access. `brane certify` remains as a manual escape hatch.
+- **Atomic daemon startup** — `BEGIN EXCLUSIVE` SQLite transaction prevents race conditions
+- **Version checking** — daemon stores version for CLI compatibility detection
+- **Payload security** — path traversal protection, 50MB size limits, immutable cached URLs
+- **Origin checking** — WebSocket upgrade validates Origin header
+
+## Rules for Every Change
+
+The full reasoning for each is in the linked doc; these are the parts that
+bite outside their own subsystem.
+
+- **The CLI is a daemon client.** A command that touches narratives, folds,
+  sessions, or the memory index calls a daemon route (adding one if needed)
+  and keeps only terminal-shaped work for itself. It never opens the database
+  itself. Every client calls `warnIfVersionMismatch()` first. See [The CLI is
+  a daemon client](docs/daemon-api.md#the-cli-is-a-daemon-client).
+- **A new daemon route is closed to agents** until it is listed in
+  `AGENT_ROUTES` (`src/daemon/agent-scope.ts`). If agents' CLI or bridge
+  needs it, add it there; operator acts stay off the list. See [Agent
+  tokens](docs/token-rotation.md#agent-tokens).
+- **No test opens the operator's database.** `openDatabase()` throws under
+  `node --test`; code the suite drives takes a `db`, and tests build one with
+  `createTestDb()`. A test that reads *source* (not `dist/`) must `skip` when
+  the source is absent, or `brane doctor` goes red on every install. See
+  [Doctor](docs/doctor.md).
+- **MCP tool errors use `sendToolError()`**, not `sendToolResult({ error })`;
+  the bridge maps it to `isError: true`. Tool logic lives in the daemon, never
+  in the bridge. See [MCP Architecture](docs/mcp.md).
+- **Bodiless app requests send no headers.** The token rides in `?token=`, so
+  a GET needs no CORS preflight; `src/test/api-request.test.ts` enforces it.
+  Breaking this is invisible on a fast network. See [The Request
+  Layer](docs/request-layer.md).
+- **A `src/shared/` module with a bare npm import needs a metro alias** in
+  `expo/metro.config.js`, as `katex` has. See [Math Rendering](docs/math.md).
+- **One parse, never a second scanner.** Warnings, mentions and diagram
+  diagnostics reuse the renderer's own parse; a parallel regex eventually
+  disagrees with what the operator sees. Regexes on the `narrate` path must
+  be linear-time. See [Rendering Warnings](docs/rendering-warnings.md),
+  [Mentions](docs/mentions.md), [Diagrams](docs/diagrams.md).
+
+- **Every conversational append goes through `announceEvent()`**, which
+  records mentions and *then* wakes listeners. A new append site in
+  `server.ts` that open-codes the two in the other order leaves a mention
+  delivered and never settled. See [Mentions](docs/mentions.md).
+- **`expo/public/index.html` is the HTML template that ships**; keep
+  `expo/app/+html.tsx` in step with it, but a `<head>` change made only there
+  never reaches a browser. See [Math Rendering](docs/math.md) and [Link
+  Previews](docs/link-previews.md).
+
+## Further Reading
+
+Relative links into [`docs/`](docs/). Each is the full write-up for its area,
+including the "less obvious than it looks" decisions and the tests that pin
+them. The paths in parentheses are the code each one goes with: about to
+change one of those, read its doc first.
+
+**Daemon and CLI**
+
+- [Daemon](docs/daemon-api.md) (`src/daemon/server.ts` routes,
+  `src/daemon/client.ts`, `src/commands/`): every HTTP and WebSocket endpoint;
+  the Spawn, Revive, Run and Folds APIs; why the CLI is a daemon client; who
+  may register which folds.
+- [MCP and the LIVE Loop](docs/mcp.md) (`src/mcp/`, `src/daemon/awaiting.ts`,
+  MCP handlers in `server.ts`): the stdio↔WebSocket bridge, listen wakeup and
+  cancellation, `narrate({ wait: true })`, the LIVE loop tools, narrative
+  metadata.
+- [Token Rotation](docs/token-rotation.md) (`src/daemon/token-ring.ts`,
+  `src/db/tokens.ts`, `src/daemon/token-routes.ts`, `src/commands/token.ts`):
+  tokens stored as hashes only, a token per melded device and per agent session, the Devices list
+  and per-device revoke, `brane token rotate`, why the swap happens on first
+  use of the new token, and why this machine holds no token (`.daemon_token`
+  is retired).
+- [Passkeys](docs/passkeys.md) (not built yet; `src/presence.ts`,
+  `src/db/tokens.ts`): the design, the spike and real-device results, what
+  the browser and daemon sides must do, open questions, build order.
+- [Presence Check](docs/presence.md) (`src/presence.ts`,
+  `src/daemon/presence-gate.ts`): confirming the operator is at
+  the machine with the OS's own prompt (macOS, Windows Hello from Windows or
+  WSL, polkit); the gate it puts on meld, a device's sign-out and rotation
+  from the shell, and why agents are refused them.
+- [Session Affinity](docs/session-affinity.md) (`src/session-affinity.ts`):
+  the `X-Session-Affinity` header for claude sessions on Fireworks.
+- [Doctor](docs/doctor.md) (`src/commands/doctor.ts`, `src/test/`): `brane
+  doctor`, and the shipped-test-suite rules.
+- [Releasing](docs/releasing.md) (`.github/workflows/release.yml`,
+  `package.json` version): the npm release workflow.
+
+**Data**
+
+- [Multi-Brane](docs/multi-brane.md) (`brane_id` resolution, `src/folds.ts`):
+  home and foreign branes, brane_id resolution.
+- [Absorb](docs/absorb.md) (`src/absorb/`): importing history (ChatGPT,
+  organelle, local Claude Code stores), per-message idempotence, `--rebuild`.
+- [Memory and Search Ranking](docs/memory-search.md) (`src/memory/`):
+  embeddings, FTS5, and why hybrid search fuses ranks rather than scores.
+- [Cost Ledger](docs/cost-ledger.md) (`src/cost/`, `usage_ledger`, adapters'
+  usage readers): `usage_ledger`, credit assignment across forks, backfill,
+  re-pricing.
+- [Mentions](docs/mentions.md) (`src/mentions-scan.ts`, `src/db/mentions.ts`,
+  `src/shared/markdown-mentions.ts`): `@nid` addressing, the mentions ledger,
+  and the record-before-wake ordering.
+
+**Web app**
+
+- [Web App (Expo)](docs/web-app.md) (`expo/`): what the app offers, view by
+  view.
+- [Terminal Mirroring](docs/terminal-mirroring.md)
+  (`expo/components/TerminalPane.tsx`, the capture loop in `server.ts`):
+  capture-pane mirroring, the resync heartbeat, the stranded rAF, the cursor,
+  paste and copy, block glyphs.
+- [Files View](docs/files-view.md) (`src/files/`, `expo/lib/hexDoc.ts`,
+  `expo/lib/hexFind.ts`): `GET /api/files`, every format the Files view shows
+  (archives as folders, hex as the floor), searching the bytes.
+- [The Request Layer](docs/request-layer.md) (`expo/lib/api.ts`,
+  `src/shared/api-request.ts`): CORS preflights, timeouts and retries at
+  satellite RTT.
+- [View URLs](docs/view-urls.md) (`src/shared/view-url.ts`,
+  `expo/app/_layout.tsx`): what the query string and fragment carry, Isolate
+  and Meld links.
+- [The Selection Store](docs/selection-store.md)
+  (`src/shared/message-selection.ts`, `expo/lib/selection.ts`): the chat's
+  message selection outside React state.
+- [Export Scope](docs/export-scope.md) (`src/export.ts`,
+  `src/shared/export-selection.ts`): exporting a selection or its complement,
+  and what an excerpt discloses.
+- [Link Previews](docs/link-previews.md) (`expo/public/index.html`,
+  `expo/scripts/og-membrane/`): the `og:*` card and its image.
+
+**Markdown rendering**
+
+- [Diagram Rendering](docs/diagrams.md) (`src/diagram/`): mermaid fences drawn
+  on the daemon, the dialect census, labels, self-loops.
+- [Math Rendering](docs/math.md) (`src/shared/markdown-math.ts`,
+  `src/math.ts`): KaTeX in the app and the export, every delimiter a model
+  writes.
+- [Rendering Warnings](docs/rendering-warnings.md)
+  (`src/markdown-diagnostics.ts`): what `narrate`'s `warnings` report and
+  `strict: true`.
+- [Wiki: Local and Shared](docs/wiki.md) (`src/memory/wiki.ts`,
+  `src/shared/wiki-links.ts`): `wiki/` vs `wiki/shared/`, who sees what, the
+  install fold.
+
+Also: `DESIGN.md` (original architecture), `SECURITY.md` (security model),
+`CONTRIBUTING.md` (contribution policy), and `protocols/` (agent protocols,
+read at runtime).
+
+## Key Patterns
+
+- **Port stability**: daemon restart captures port before SIGTERM, reuses it
+- **Scroll preservation**: chat/terminal tabs use absolute positioning with zIndex stacking
+- **Terminal resize**: ResizeObserver measures monospace character dimensions, sends cols/rows to tmux
+- **Multitouch keyboard**: refs for synchronous state, React state for visual rendering only
+- **Event cursor**: monotonic `seq` per narrative, `after`/`before`/`tail` parameters on narrate/listen (supports multi-narrative object format)
+- **Hashed tokens, and none for this machine**: the database holds only token hashes; devices get one minted per meld, agents one per session, and `--token` is adopted as a device token. The shell's CLI and MCP bridges hold no token: they present nothing over `daemon.sock`, the only way in for them, and nothing reads or writes `.daemon_token` — see [No local token](docs/token-rotation.md#no-local-token)
+- **Atomic daemon claim**: SQLite `BEGIN EXCLUSIVE` transaction ensures singleton daemon
+- **IP filtering**: TCP-level socket filtering before HTTP processing
+- **Version tracking**: daemon and CLI version compatibility checks
+- **Metadata broadcasts**: control WebSocket pushes summary/status changes in real-time
+- **Portable paths**: stored as `~/relative` format, converted via `toPortablePath()`/`fromPortablePath()`
+- **The mirror sends text; everything else is explicit**: the pane's cursor is the only thing about a terminal that isn't in its text, so it rides the same tmux round trip as the capture — and gets its own message when it moves and the text doesn't
+- **The chat never scrolls itself**: after landing, only the operator moves the chat. It is a `column-reverse` scroller (`CHAT_SCROLLER_STYLE`, `expo/app/[nid].tsx`), not a virtualized `FlatList`, so scroll position is measured from the bottom: it opens on the latest message without a scroll, an arrival is followed only when the view is already exactly at the bottom, a page of older history lands at the far end and moves nothing, and no row is ever swapped for an estimated spacer mid-scroll. The one scroll the code writes is landing on `?scrollToSeq=` / `?scrollTo=`, plus the ↑/↓ tab button the operator taps. Sending doesn't scroll, and vertical scroll is never disabled, not even under a horizontal pane swipe. Measured in Chromium and WebKit against a sandbox daemon: the message under the viewport moves 0 px on arrival, on send and on each page loaded
+- **A tap should cost what it changed**: the chat's selection lives in a store with per-seq subscriptions, so selecting a message wakes that bubble, the header's count and the composer — not the screen, not `renderItem`, not the other two hundred rows; the same store is what makes two taps in one frame both land
+- **The URL carries the view**: anything that must survive an origin hop (Isolate) or a device hop (Meld) goes in the query string, built through `src/shared/view-url.ts` — `sessionStorage` is origin-scoped and does not travel
+- **Back undoes a jump, never a view change**: a different narrative or any `nid:seq` link (even into the narrative you're reading) is a `router.push`; a tab, pin, file or selection change is `router.setParams`, which replaces. Screens behind the top stay mounted, so Back restores them whole, and narrative subscriptions are refcounted because two of them can watch the same narrative — see [View URLs](docs/view-urls.md)
+- **`shared/` is the publication unit**: a fold's `wiki/shared/` is what other folds — and the npm tarball — can see; everything directly under `wiki/` is fold-local, and the install directory is just another fold
+- **One renderer, two targets**: markdown features that must survive export (code highlighting, math) render server-side or through shared code, never through a script the exported file carries
+- **Fail quietly for the reader, loudly for the writer**: renderers fall back rather than show errors; the same decisions are collected and returned to whoever wrote the markdown, as `narrate` warnings — advisory, unless that call asked for `strict`
+- **Ask once, not twice**: a cross-origin request that carries no custom headers needs no CORS preflight, so bodiless API calls authenticate through `?token=` and send none — the extra round trip is invisible on a LAN and fatal at satellite RTT
+- **Stale PID cleanup**: daemon info queries verify PID liveness, clean up dead entries
+- **A blind start is not a verdict**: Tailscale detection at startup is one `tailscale status` with a 3 s timeout, and the extension can be wedged at exactly that moment (it hung for 11 hours on 2026-08-30 while the menu bar said "Connected"). The daemon therefore keeps re-probing — 5 s doubling to a 60 s cap while blind, 60 s steady once seen — and binds HTTPS + HTTP-fallback listeners on tailnet addresses as they appear (`src/daemon/tailscale-rebind.ts` holds the policy, `src/test/tailscale-rebind.test.ts` pins it). `GET /api/status` reports `listening_on`; empty means "this machine only". `--bind` opts out
+
+## Important Warnings
+
+- **Never restart the organelle Nucleus daemon** — it maintains WebSocket connections to mobile devices
+- The brane daemon is separate and safe to restart
+- Database has no back-compat concerns yet — schema can change freely
+- `~/.brane/` directory should be portable (paths stored as ~/relative)

package/CHANGELOG.md

@@ -0,0 +1,33 @@
+# Changelog
+
+Notable changes to brane, by published version. Each version's full notes
+are on the [GitHub releases](https://github.com/benjamn/brane/releases)
+page, which is also what triggers its publish (see
+[docs/releasing.md](docs/releasing.md)). This file is the summary that
+travels in the npm tarball.
+
+## 0.3.0 - 2026-10-11
+
+The first release of this codebase. What ships:
+
+- The `brane` CLI and userspace daemon: register directories as folds,
+  spawn agents in them (Claude Code, Codex, Gemini, Goose, Crush, Copilot,
+  or any command) under tmux, and keep every session's narrative in one
+  SQLite database, every message with a stable `nid:seq` address.
+- The LIVE loop: an MCP server injected into each agent session
+  (`narrate`, `listen`, `whoami`, wiki and memory search), and the
+  protocols agents read at runtime, in `protocols/`.
+- The web app the daemon serves to any browser on your tailnet: chat,
+  terminal mirroring, files, export, markdown with math and diagrams, and
+  meld by QR code. Per-device and per-agent tokens, a presence prompt for
+  new devices, and `brane token rotate`.
+- Memory: local embeddings on `onnxruntime-node` fused with FTS5, across
+  narratives and absorbed history (ChatGPT, organelle, local Claude Code
+  stores).
+- `brane doctor`, which runs the shipped test suite against the install.
+- Node 20 or newer. AGPL-3.0-or-later.
+
+## 0.1.1
+
+An unrelated earlier package that held the name on npm (2022). Not an
+ancestor of this code.

package/CONTRIBUTING.md

@@ -0,0 +1,91 @@
+# Contributing to brane
+
+Brane is a single-maintainer project developed with coding agents. Most
+commits on `main` were written by an agent under the operator's direction,
+and every one of them was reviewed, authored, committed, and merged by a
+human. This document says what that means for anyone touching the
+repository, human or agent.
+
+## How changes land
+
+- `main` takes pull requests only. The `protect-main-branch` ruleset
+  (2026-09-02) requires a PR, forbids force-pushes and deletions, and has
+  no bypass actors.
+- Work happens on a branch, usually in a worktree, and arrives as a PR
+  with CI green.
+- A human merges. Agents open PRs; they do not approve or merge them, not
+  even their own.
+
+## Working from a clone
+
+```sh
+npm install
+npm link            # once: `brane` now resolves to this checkout
+npm run build       # Compile TypeScript + build the Expo web bundle
+```
+
+`npm link` points your global `brane` at `<repo>/dist/cli.js`, so every
+later `npm run build` is picked up without reinstalling; after a
+server-side change, `brane daemon restart` puts the daemon on it. To go
+back to a published release, `npm unlink -g brane` and then
+`npm install -g brane`.
+
+## Disclosure: say when an agent helped
+
+Every commit an agent wrote or substantially shaped carries a trailer naming
+the agent and the model version:
+
+```
+Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
+```
+
+This is the form Claude Code emits and the form the history already uses on
+most commits since 2026-02-28. The kernel-style
+`Assisted-by: <tool>:<model>` trailer is equally acceptable for contributors
+whose tools emit it. The trailer is a disclosure, not an attribution of
+authorship: it records that a model was involved so a reader can tell, the
+same way `Assisted-by:` does in the Linux kernel, Fedora, and LLVM. An
+agent never removes or rewrites a trailer. The human who signs off on a
+commit may rewrite it, trailer included, and by doing so takes sole
+responsibility for its contents; that is what signing off means.
+
+## Sign-off: humans only
+
+Responsibility for a change belongs to a person. Concretely:
+
+- **An agent never adds `Signed-off-by:`.** The Developer Certificate of
+  Origin is a legal certification that the signer has the right to submit
+  the work under the project's license. A model cannot hold copyright,
+  enter an agreement, or take responsibility, so it cannot certify
+  anything, and an agent must not write a sign-off on a human's behalf.
+- **Outside contributors sign off.** Add
+  `Signed-off-by: Your Name <you@example.com>` to each commit
+  (`git commit -s`), certifying the
+  [Developer Certificate of Origin 1.1](https://developercertificate.org/).
+  Brane asks for a DCO sign-off rather than a contributor license
+  agreement.
+- **The maintainer's own changes are signed off by the merge.** Brane's
+  history predates this file and does not carry `Signed-off-by` on every
+  commit. For changes the maintainer lands, reviewing and merging the PR
+  is the accountability step, so agents committing in the maintainer's
+  checkout do not add a sign-off for the maintainer.
+- **Understand what you submit.** Whoever signs off or merges is expected
+  to have read the change, be able to explain it, and stand behind its
+  correctness and licensing. "The agent wrote it" is a disclosure, not a
+  defense.
+
+## Licensing
+
+Brane is AGPL-3.0-or-later (see `LICENSE`). Every contribution is accepted
+under that license. Do not submit code you are not entitled to license
+that way, including code whose origin you cannot account for.
+
+## Security
+
+Do not open a public issue for a vulnerability. See `SECURITY.md`.
+
+## For agents
+
+The same rules, phrased as instructions, are in `AGENTS.md` under
+"Commits, Sign-off, and Accountability". Brane's own agents read that file
+at startup.