brane 0.1.1 → 0.3.0

package/protocols/digest.md

@@ -0,0 +1,231 @@
+# /digest [guidance]
+
+Generate a rich digest of narrative activity over a time window.
+
+## Accuracy is the whole job
+
+A digest is built entirely from the **narrative event log** — the
+permanent, append-only record of `narration` and `human_signal` events.
+That log is the source of truth, and it does not go away: you can always
+re-read any narrative's events with `listen` / `narrative_info` /
+`narrative_search`. The digest is nothing more than a faithful account
+of what that record says. It is itself durable too — the next `/digest`
+finds this one to set its window, so one invented detail propagates and
+misleads for weeks.
+**Accuracy outranks completeness** — a short digest covering only the
+narratives you actually read beats a comprehensive-looking one padded
+with guesses. The rules below are mandatory, not aspirational; a real
+digest run violated every one (see "Failure modes" at the end).
+
+### Report only what the log actually says
+
+Every accomplishment, decision, and theme must trace to specific events
+in the log — not to memory, not to what a narrative "probably" said. If
+you are unsure whether something happened, re-read the events; the record
+is right there. Do not invent narrative IDs, summaries, quotes, or
+events, and do not attribute work to a narrative whose events you have
+not read. Cite the narratives you draw on as `nid:seq` so every claim is
+checkable against the record.
+
+### Don't editorialize
+
+Report what the events say without coloring it. This is the same
+discipline the /wiki protocol calls *Voice and register* — a neutral,
+descriptive account — applied to the digest:
+
+- **Attribute positions; don't assert them.** A decision, preference,
+  conjecture, or claim is reported as someone's — "the operator
+  directed…", "claude-abc proposed…", "is described as…" — not stated as
+  settled fact. Only things that demonstrably happened (a PR merged, a
+  test added) are stated flat.
+- **Cut editorializing phrases.** Don't inflate a routine fix into a
+  milestone, dramatize a setback, or reach for adjectives ("major,"
+  "critical," "elegant," "bold") the record hasn't earned. State a
+  substantive claim plainly and attribute it; drop decoration.
+- **Don't sharpen or supply motive.** Don't turn a vague status into a
+  definite outcome or invent a "why" the events don't give. Where the
+  record is ambiguous, say so rather than resolving it for them.
+
+By default, then, the digest reads as wiki-style reference: neutral,
+descriptive, attributed. The `[guidance]` is the one thing that loosens
+this — when it asks for more than a neutral account (prioritization,
+risk assessment, cross-narrative connections, recommendations, what to
+do next), provide that judgment, but keep it grounded in the events and
+clearly marked as your interpretation rather than woven into the
+description as fact.
+
+### gh/git are corroboration, not the substance
+
+The digest reports what narratives did, drawn from their events — it is
+not a catalog of PRs and commits. A PR number or commit hash belongs in
+a digest only when a narrative's events reference it, and even then the
+claim "this narrative shipped that PR" comes from the events, never from
+guessing what a number maps to. If you cite a repo fact, copy the
+identifier from real `gh`/`git` output obtained this run; never compose
+one to look precise.
+
+### Report gaps, don't fill them
+
+You will not always read every narrative in the window — there may be too
+many, or a search may return nothing. That is fine; an incomplete digest
+is honest, a padded one is not. Name what you did not cover ("12
+narratives not sampled") and exclude it from your claims rather than
+guessing at its contents. Coverage you did not read is reported as
+missing, never synthesized.
+
+### Verify before you narrate
+
+Before posting, pass over your draft once: every narrative you name,
+every event you quote, every outcome you assert — can you point to the
+event you read it from? Cut, flag as unverified, or re-check anything
+you cannot trace. "Fairly sure" without a source is the signal to
+re-fetch or omit — never to assert.
+
+### Failure modes this guards against
+
+Do not repeat the run that prompted these rules:
+
+- Inventing narrative IDs, summaries, or events that are not in the log.
+- Summarizing narratives whose events you never actually read.
+- Reporting what a PR or commit "was about" from a guessed number
+  instead of from a narrative's events or real `gh`/`git` output.
+- Quietly dropping coverage you skipped instead of naming the gap.
+- Dressing any of the above in confident, specific-sounding prose.
+
+## Determining the time window
+
+Before generating the digest, determine the correct time window:
+
+1. **Find the last digest** — prefer `narrative_info` over semantic
+   search. Every digest sets its `summary` to `"Digest: {start} to
+   {end}"` (see Output below), so the reliable lookup is
+   `narrative_info` in browse mode with `search: "Digest"`,
+   `archived: true`, `limit: 0` — it matches that summary column
+   directly and returns results newest-first. Use the most recent
+   hit's end date as your window start.
+   **Do not rely on `narrative_search "Digest generated"` for this.**
+   Semantic search ranks *commentary about* digests above the actual
+   digest narrations and routinely surfaces stale, older digests while
+   missing more recent ones — a real run anchored to a digest two
+   months out of date this way. `narrative_search` is for themes
+   (step 3 of Gathering), not for locating the window boundary.
+2. **Fallback**: if no previous digest is found, default to `7d`
+   (one week).
+3. **Override**: if the `/digest` signal includes guidance specifying a
+   time range or other instructions, follow them. Examples:
+   - `/digest 7d` — last 7 days
+   - `/digest since monday` — since the most recent Monday
+   - `/digest 2026-03-01 to 2026-03-15` — explicit date range
+   - `/digest whole week ignoring previous /digest` — use 7d window,
+     skip the "find last digest" step
+
+   Freeform natural language is expected. Interpret intent generously.
+
+The end of the window is always **now**.
+
+## Gathering activity
+
+**Narrate your progress as you go.** The data gathering phase can take
+several minutes. Keep the operator informed by narrating status updates
+as you work — e.g., "Found 33 narratives in the window, sampling the
+top 10 by event count..." or "Reading events from the absorb sessions..."
+This lets the operator follow along and redirect if needed.
+
+Use the tools available to you to collect raw material:
+
+1. **`narrative_info`** — call with `since` set to the time window
+   (e.g., `"30d"`) and `limit: 0` to get all narratives active in
+   the period. Include `archived: true` to capture completed work.
+   Narrate what you found (count, date range, notable summaries).
+2. **Event sampling** — for each narrative returned, use `listen` with
+   `wait: false` and `tail: 20` to fetch the most recent events.
+   Focus on `human_signal` events (operator decisions) and `narration`
+   events with substantive content. Skip routine LIVE loop chatter.
+3. **`narrative_search`** — use targeted queries to find cross-cutting
+   themes (e.g., search for recurring topics, error patterns, or
+   decision points).
+
+When the number of narratives is large, prioritize:
+- Narratives with the most events (highest activity)
+- Narratives with `human_signal` events (operator engagement)
+- Narratives whose summaries suggest completed work
+
+### Parallelism
+
+**Parallelize aggressively.** Issue multiple `listen` (with `wait:
+false`) and `narrative_search` calls in a single tool-use turn. Batch
+5–10 narrative event reads per turn rather than fetching one at a time
+— this dramatically reduces the data gathering phase. Use `tail: 20`
+(or similar) to keep each response manageable and avoid flooding your
+context with long histories.
+
+Narrate a progress update between each batch so the operator sees
+movement — e.g., "Sampled 10/33 narratives so far, highlights: ..."
+
+## Digest structure
+
+Organize the digest into these sections, omitting any that have no
+content:
+
+### Activity overview
+- Total narratives active in the period
+- Breakdown by agent type and status
+- Busiest folds (directories where work happened)
+
+### Accomplishments
+- Narratives that reached completion (ended status or "done" summaries)
+- Key deliverables, features, or fixes — summarize what was achieved
+- Link back to narrative IDs for reference
+
+### Decisions & directions
+- Operator signals that set direction or changed course
+- Important choices made and their rationale (when visible)
+
+### Open threads
+- Active narratives that may need attention
+- Unanswered agent questions or stalled work
+- "Gone quiet" narratives — previously active but no recent events
+
+### Themes
+- Recurring topics across narratives
+- Patterns in the kind of work being done
+- Cross-narrative connections worth noting
+
+### Absorbed context
+- If any absorbed (imported) narratives were active or referenced in the
+  period, note relevant connections to current work
+
+## Output
+
+Narrate the digest in full using `narrate`. Use markdown formatting for
+readability, and write the digest body in the /wiki protocol's *Voice
+and register* — neutral, descriptive, attributed (see "Don't
+editorialize" above). Begin the narration with a header line:
+
+```
+**Digest generated** — {start_date} to {end_date} ({N} narratives)
+```
+
+This header line marks the narration as a digest. The primary locator
+for future `/digest` invocations, though, is the `summary` metadata
+below — set it on the same `narrate` call so the digest is findable via
+`narrative_info` (browse mode, `search: "Digest"`), which is the
+reliable way to determine the next window (see "Determining the time
+window"). Keep the `Digest: {start} to {end}` summary format exact so
+that search matches it.
+
+Set your narrative metadata:
+
+```json
+{
+  "meta": {
+    "summary": "Digest: {start_date} to {end_date}"
+  }
+}
+```
+
+## After generating
+
+After narrating the digest, return to the LIVE loop — `listen` for
+further signals. The operator may ask follow-up questions about specific
+narratives or request a different time window.

package/protocols/fly.md

@@ -0,0 +1,266 @@
+# /fly [init|new|deploy|up|down|meld|status|logs|destroy]
+
+Running brane daemons on Fly.io machines, reached over Tailscale.
+**Experimental.** It needs a tailnet you administer and an authenticated
+`fly` CLI (`fly auth whoami`).
+
+Bare /fly means this protocol. `/fly <verb>` asks for that verb's
+section below; follow its steps with plain `fly` commands. There is no
+`brane fly` subcommand. Brane supplies only the image (`Dockerfile`,
+`docker-entrypoint.sh`, shipped in the package) and `brane meld --remote`.
+Nothing here is specific to brane's CLI except that one command, so the
+same steps adapt to any host that runs a container.
+
+Every verb except `status` and `logs` changes something on Fly, and some
+cost money. Say what you're about to run and get the operator's go before
+running it.
+
+## Mental Model
+
+**Perch and relaunch:** machines are disposable, volumes are permanent.
+Idling costs nothing.
+
+| Verb | What it does |
+|------|--------------|
+| `down` | Destroy all machines. Zero cost. Volumes preserved. |
+| `up` | One machine per region that has a volume, reattaching it. |
+| `deploy` | Build and push the image; update running machines only, never create one. |
+
+Volumes are the source of truth: each represents a region the operator
+committed to, and machines come and go around them.
+
+Each machine runs **tailscaled** (its only network access) and a **brane
+daemon**. The volume is mounted at `/home/brane`, the whole home
+directory, so `~/.brane` (database, certs, payloads), `~/.claude`, agent
+configs and git state all persist. The embedding model is baked into the
+image at `/opt/brane/models`, outside the volume.
+
+## Shared values
+
+- **The app name** is remembered in brane config:
+  `APP=$(brane config fly.app)`. `init` sets it.
+- **The install directory**, where the `Dockerfile` and entrypoint live:
+  ```bash
+  BRANE_ROOT=$(node -e 'const p=require("path"),fs=require("fs");console.log(p.resolve(fs.realpathSync(process.argv[1]),"../.."))' "$(command -v brane)")
+  ```
+  That needs `brane` on `PATH`. Without it (`npx brane`), the install
+  directory is the one above `dist/cli.js`.
+- **The `fly.toml`**, written beside the image's files (`<app>` is `$APP`):
+  ```toml
+  app = "<app>"
+  primary_region = "sjc"
+
+  [build]
+    dockerfile = "Dockerfile"
+
+  [[mounts]]
+    source = "brane_data"
+    destination = "/home/brane"
+
+  [env]
+    TS_HOSTNAME = "daemon-<app>"
+
+  [[vm]]
+    size = "performance-1x"
+    memory = "2gb"
+  ```
+  The entrypoint appends the region, so a machine's tailnet name is
+  `daemon-<app>-<region>`. There is no `[http_service]`: Tailscale is
+  the only way in, so Fly's proxy has nothing to route, and without a
+  service it neither warns that nothing is listening nor stops or starts
+  machines on its own.
+
+## /fly init
+
+One-time setup.
+
+1. Create the app and remember its name:
+   ```bash
+   APP=brane-$(openssl rand -hex 3)
+   fly apps create "$APP" --org <org>
+   brane config fly.app "$APP"
+   ```
+2. Give it its secrets. `ANTHROPIC_API_KEY`, and a Tailscale credential
+   (see [Tailscale](#tailscale)). The operator sets secrets themselves,
+   `fly secrets set NAME=… -a "$APP"`, so no secret passes through an agent.
+   `TS_CLIENT_ID` is not a secret.
+3. Run [/fly deploy](#fly-deploy). With no machines it only builds and
+   registers the image.
+
+Then `/fly new` for each region.
+
+## /fly new
+
+Add a region: create its 10 GB volume. No machine yet; `/fly up` starts
+it. First check one isn't there already:
+
+```bash
+fly volumes list -a "$APP"
+fly volumes create brane_data --region <region> --size 10 --yes -a "$APP"
+```
+
+## /fly deploy
+
+Build the image on Fly's remote builder from this install, and update
+running machines. `--update-only` means it **never creates machines**, so
+it's safe while scaled to zero; the next `/fly up` uses the new image.
+
+```bash
+CTX=$(mktemp -d)
+cp "$BRANE_ROOT/Dockerfile" "$BRANE_ROOT/docker-entrypoint.sh" "$CTX/"
+(cd "$BRANE_ROOT" && npm pack --pack-destination "$CTX")
+# write the fly.toml above into "$CTX/fly.toml"
+(cd "$CTX" && fly deploy --update-only -a "$APP")
+```
+
+`fly` may print `Process groups have changed. This will: create 1 "app"
+machine` on an app with no machines; `--update-only` still creates none.
+
+## /fly up
+
+One machine per region that has a `brane_data` volume. Scale each region
+on its own: a single `fly scale count N --region a,b,c` can stack
+machines in one region and create stray volumes.
+
+```bash
+fly volumes list -a "$APP" --json   # the regions with a brane_data volume
+fly scale count 1 --region <region> --yes -a "$APP"   # once per region
+```
+
+Running machines are left alone. Watch the first boot with `/fly logs`:
+the machine is ready once its daemon logs `listening on`.
+
+## /fly down
+
+Destroy all machines; volumes and their data survive. Take each running
+machine off the tailnet first: stale WireGuard state on the volume breaks
+some peers (iOS especially) on the next `up`.
+
+```bash
+fly machines list -a "$APP"          # the started ones
+fly ssh console -a "$APP" --machine <id> -C "tailscale down"   # each
+fly scale count 0 --yes -a "$APP"
+```
+
+## /fly meld
+
+Connect a device to a machine's daemon. The machine can't show a presence
+prompt, so the device token is minted by the operator's own daemon, after
+Touch ID (or the platform's prompt) on their machine, and the remote gets
+only its hash. **The operator runs this, not an agent**: it prints the
+token in the QR and URL, and an agent's session is refused. Hand them the command with the app's name written in, since
+their shell has no `$APP`:
+
+```bash
+brane meld --remote \
+  --send "fly secrets set BRANE_DEVICE_TOKEN_SHA256={hash} -a <app>" \
+  --ask  "fly ssh console -a <app> -C 'gosu brane brane meld --connection'"
+```
+
+1. `--send` sets the secret, which restarts the machines; each daemon
+   adopts the hash as a device row as it starts, once (a hash it has ever
+   seen, revoked or not, never comes back), and drops the variable.
+2. `--ask` reads back the daemon's address (`brane meld --connection` mints
+   nothing), retrying for 3 minutes, and the QR is printed.
+
+Like every QR it lapses if nobody scans it within 10 minutes of the
+restart; run it again for a fresh one. More devices are best added from
+the app's Meld sheet, which needs no restart.
+
+## /fly status
+
+```bash
+fly status -a "$APP"
+fly machines list -a "$APP"
+fly volumes list -a "$APP"
+```
+
+## /fly logs
+
+```bash
+fly logs -a "$APP"                                   # follow
+fly logs -a "$APP" --region <region> --no-tail | tail -50
+```
+
+## /fly destroy
+
+Tearing down is the operator's to do, never an agent's: volumes hold the
+database, Tailscale identity, certs and session history. Point them at:
+
+- stop without losing anything: `/fly down`;
+- `fly volumes destroy <id> -a "$APP"` for one region;
+- `fly apps destroy "$APP"`, then `brane config --unset fly.app`, for all
+  of it.
+
+## Tailscale
+
+Machines join the tailnet as **tag-owned** nodes (`tag:brane`, or
+`TS_TAGS`), so their keys never expire; the identity persists on the
+volume and later boots reuse it. Every `tailscale up` in the entrypoint
+names the tags and has a `--timeout`: an `up` without the tags asks
+control to drop them, which waits for a login nobody on the machine can
+complete.
+
+A new volume (or one whose node was removed) joins with one of two
+credentials, set as Fly secrets:
+
+- **`TS_CLIENT_ID` (preferred): no secret on Fly.** The entrypoint asks
+  Fly for this machine's OIDC token (`/.fly/api`, `POST
+  /v1/tokens/oidc`) and Tailscale's workload identity federation trades
+  it for a node key. One-time setup in the Tailscale admin console:
+  1. Add `"tag:brane": ["autogroup:admin"]` to `tagOwners` in the policy
+     file.
+  2. Trust credentials → OpenID Connect → **Custom issuer**
+     `https://oidc.fly.io/<org>`, subject `<org>:<app>:*`, scope
+     `auth_keys` with `tag:brane`. `<org>` is the org's own name, which
+     for a personal org is *not* the `personal` that `fly orgs list`
+     shows. Read it from a token's claims on a running machine:
+     `fly ssh console -C "sh -c 'curl -fsS --unix-socket /.fly/api -X POST
+     http://localhost/v1/tokens/oidc --data {} | cut -d. -f2 | base64 -d'"`
+     prints `iss` and `sub` (base64 may warn about padding). Pinning the
+     app keeps every other app in the org from joining as `tag:brane`.
+  3. `fly secrets set TS_CLIENT_ID=<client id> -a <app>`. The audience
+     defaults to `api.tailscale.com/<client id>`; set `TS_AUDIENCE` if the
+     console shows a different one.
+- **`TS_AUTHKEY`:** an OAuth client secret with the `auth_keys` scope and
+  `tag:brane` (never expires), or an auth key allowed to apply the tag
+  (expires within 90 days). Append `?ephemeral=false&preauthorized=true`
+  to an OAuth secret.
+
+Nodes are never ephemeral: an ephemeral node is deleted while its machine
+is down, and `/fly down` can last months. Remove a dead node in the admin
+console before its region comes back, or the new one is named `…-1`.
+
+## Volume Safety
+
+**Volumes are never created by accident.** Only `/fly new` creates them,
+one region at a time; `/fly deploy` uses `--update-only`, and `/fly up`
+scales one region at a time.
+
+Intentional volumes are 10 GB; stray ones from Fly auto-provisioning are
+typically 1 GB. Investigate with `fly volumes list -a "$APP"` before
+anything is deleted, and leave deleting to the operator.
+
+## Troubleshooting
+
+### Machine won't start, or restarts every ~30 s
+
+`/fly logs`. Common causes:
+- **Not on the tailnet.** The log says `token exchange failed with status
+  403` (the trust credential's issuer, subject or audience doesn't match
+  the token; read the claims as above), `entrypoint: could not get an
+  OIDC token`, `neither TS_CLIENT_ID nor TS_AUTHKEY is set`, or `tailscale
+  up` timed out. See [Tailscale](#tailscale).
+- A volume in the old layout: the entrypoint migrates it.
+
+### Blank terminal after /fly up
+
+Narratives from a previous machine lifetime may show a blank terminal
+instead of the restart button, when `/fly down` killed the machine before
+the daemon could mark them ended. The server detects this on terminal
+connect (`tmux has-session`) and sends the terminated signal.
+
+### Stale Tailscale nodes
+
+After `/fly down`, nodes show as offline within 2–5 minutes. Cosmetic:
+they reconnect on the next `/fly up`.

package/protocols/idle.md

@@ -0,0 +1,81 @@
+# /idle [when]
+
+License to stop listening: the operator says the work is done, and the
+agent may fall completely idle until the operator comes back for it.
+
+## Why a license
+
+/LIVE_loop forbids leaving `listen` "without being told to".
+Right for an agent with work in flight; wrong for one whose task is
+finished and reported, where every `listen` timeout is an inference
+turn spent on nothing and a little more context. `/idle` is the being
+told.
+
+**Nothing wakes an idle agent but the operator.** No revive, no nudge,
+no signal typed into the terminal: signals to an idle narrative wait in
+its log. A daemon that woke idle agents would turn every stray signal
+into a turn nobody asked for, and would have to guess whether the agent
+was idle or mid-turn. Instead the agent's `summary` says `Idle: …`, so
+the operator always knows which narratives are watching and which are
+waiting.
+
+## Command, not conversation
+
+`/idle` is a command only as the **first token of a signal**: `/idle`
+or `/idle <when>`. In "did /idle work?" it is a word, and /prelude's
+"starts with or includes" convention does not apply. A misread
+`/memory` wastes a search; a misread `/idle` stops an agent watching.
+The bar is the one mentions draw between `@nid` and a bare `nid`:
+position, not presence. In doubt, it was conversation — answer, and
+keep listening.
+
+## The decision
+
+In order. Steps 1, 4 and 5 are mechanical; 2 and 3 are judgment, and
+the reason this is a protocol rather than a script.
+
+1. **Invoked?** First token `/idle` → continue. Otherwise respond to
+   it as conversation and never idle on its account.
+2. **When?** No condition → now. `/idle when CI is green` takes effect
+   when that is clearly true, read as the operator meant it (the
+   checks passed, not the run started); loop normally until then. If
+   you cannot tell, ask rather than guess either way; the license
+   holds while you wait.
+3. **Debt?** Vocalize everything executed but unreported — outcome,
+   state, open threads — and on the same `narrate` set `meta.summary`
+   to `Idle: <what finished, or what would resume>`. A long session
+   takes its [/summarize](summarize.md) here.
+4. **Gate.** `listen({ wait: false, after: <cursor> })`. Empty → stop.
+   Events → interpret them, back to step 3. The license stands unless
+   a newer signal gives work, in which case the loop simply resumes.
+5. **Stop.** Return to your native prompt. No `listen`, no narration,
+   no closing remark: step 3 was the last word.
+
+The order closes the race. Between the request and the stop there is
+a report to write and perhaps a condition to wait out, minutes in
+which the operator may say more; the gate being the last call means
+all of it is read before the agent leaves. Only a signal arriving
+after an empty read waits, and that is what the license covers.
+
+## Idle is not listening
+
+An idle agent makes no brane calls. A parked `listen` — one your
+harness holds in the background and resumes you on when it returns —
+is not idle: it is the ordinary loop on a harness where waiting is
+cheap, and it is what you do when the operator has **not** sent
+`/idle`. The two differ in what the operator chose: a listening agent
+answers the next signal by itself; an idle one answers when the
+operator types into its terminal. Sending `/idle` is choosing the
+second, and the reason to send it is that the agent's next signal is
+not coming for a while.
+
+## Waking
+
+The operator wakes you by typing into your terminal. Whatever they
+type, re-enter through Session Initialization in
+[LIVE_loop](LIVE_loop.md): `whoami`, `listen({ wait: false, tail: 50 })`,
+interpret everything that accumulated as one instruction, respond.
+
+`/idle` is a standing license, not an order. Until you stop, any newer
+signal that gives work supersedes it; after you stop, the operator's
+return is the withdrawal.