backthread 0.1.0 → 0.1.1

package/README.md

@@ -1,431 +1,84 @@
-# backthread — CLI / plugin
+# backthread
 
-The local **agent plugin** spine for Backthread's live capture loop + in-Claude-Code
-query (F7). This package is the shared entrypoint the later F7 surfaces hang off:
-the `SessionEnd`/`Stop` capture hook (F7.2), the `/backthread capture` slash command
-(F7.3), and the MCP server (F7.4) all call into it.
+[![npm](https://img.shields.io/npm/v/backthread?logo=npm)](https://www.npmjs.com/package/backthread)
+[![license](https://img.shields.io/npm/l/backthread?label=license)](./LICENSE)
 
-It is a **separate npm package** from the diagram app (mirrors `worker/`): it
-does **not** modify the root `package.json` and has no app dependencies. Its only
-runtime dependency is the official MCP SDK (`@modelcontextprotocol/sdk`), pulled
-in by the F7.4 `backthread mcp` server; everything else uses Node builtins, so `npx backthread` stays a small, audit-light download.
+**Keep the thread on what your AI agent actually shipped.**
 
-## Status (F7.1 / ARP-432, F7.2 / ARP-433, F7.3 / ARP-434, F7.4 / ARP-435, F7.7 / ARP-438)
+When you hand code to AI agents (Claude Code, Codex, Cursor), you stop reading
+every change — and a few weeks later you own a codebase you never internalized.
+Debugging slows down, refactors get scary.
 
-Scaffold + `backthread login` (the browser OAuth-loopback device-token client), the
-`backthread capture` SessionEnd/Stop hook handler (F7.2), the `/backthread:capture` MANUAL
-slash command (F7.3), the `backthread mcp` server (F7.4) exposing the in-Claude-Code
-`capture` + `query` tools, and `backthread install` (F7.7) — the onboarding glue that
-authorizes the device, registers the SessionEnd hook, and backfills history.
+Backthread captures the **why** behind each change straight from your agent
+sessions, so you can ask *"how does X work?"* and stay oriented without
+spelunking through PRs. The decisions become a live **"How it works"** diagram
+and changelog at [backthread.dev](https://backthread.dev).
 
-## Commands
-
-```
-backthread start            First-run setup: trust copy + one-tap auth + your next step (backs /backthread:start)
-backthread login            Authorize this device (opens your browser)
-backthread login --device   Headless / SSH login (device-code flow — STUBBED, see below)
-backthread whoami           Show the current device's config (token is never printed)
-backthread capture          Capture this session's decisions (run by the SessionEnd/Stop hook)
-backthread capture --manual Manually capture a session now (backs the /backthread:capture slash command)
-backthread mcp              Start the MCP server (capture + query tools) over stdio
-backthread install          Set up capture for this repo: login + register hook + backfill history
-backthread help             Usage
-```
-
-## `backthread login` — the loopback flow
-
-1. Starts a localhost server on `http://127.0.0.1:<random-port>/callback`.
-2. Opens the browser to `app.backthread.dev/cli-auth?port=<port>&state=<nonce>`.
-3. You click **Authorize** (you're already signed into the web app). The page
-   mints a capture-scoped `backthread_pat_…` device token via the `mint-device-token`
-   Edge Function (F7.0 / ARP-448) and redirects back to the loopback with the
-   token + the same `state` nonce.
-4. The CLI validates the `state` nonce (CSRF guard) and writes the token to
-   `~/.backthread/config.json` at **chmod `0600`**.
-
-One browser click, zero copy-paste. **The token never touches the clipboard or
-terminal scrollback** — it goes straight from the loopback query string into the
-0600 config file and is never printed or logged.
-
-## Inference router — `infer.ts` (F7.IR / ARP-450)
-
-`inferDecisions(transcript, config, opts)` decides **how** decisions get derived
-from a normalized + redacted transcript and **whose** credentials pay, then
-returns the derived decisions for the caller (F7.2 hook / F7.4 MCP) to POST to
-`ingest-decisions` — **unless** the result says the server already persisted them.
-
-- **Model 2 (server-side, our keys) — the DEFAULT.** POSTs the redacted
-  transcript to the Worker's F7.SF `POST /infer-decisions` (auth: the F7.0
-  `backthread_pat_` device token), which runs the tuned Gemini-bulk → Sonnet-tiebreak
-  pipeline with our keys. Pass `persist: true` + `repo` to have the server also
-  write the decisions (membership-gated) — then `result.persisted` is `true` and
-  the caller MUST NOT re-POST to `ingest-decisions` (double-write). Default is
-  derive-only: the caller persists.
-- **Model 3 (BYO API key) — a power-user override, SEAM ONLY.** `localByokInfer`
-  is a stub marked `// TODO(F7.19 / ARP-463)` that always reports "no BYOK
-  configured", so the router falls through to Model 2. Local BYOK execution +
-  key storage/validation/settings UX ships in F7.18/19 (ARP-462/463).
-- **Model 4 — parked, not modelled here** (post-MVP, opt-in; ToS-blocked variants
-  are off the table per the F7.IV spike, ARP-449).
-
-**Trust boundary (be honest — Model 2 is the weaker claim).** Because the
-default path runs inference on our servers, the thing that leaves your machine
-on Model 2 is **the redacted transcript** — natural-language prose only. The
-plugin redacts LOCALLY first (drops every tool-use / tool-result record and
-redacts fenced code to `[code redacted]`), so **no source code and no tool I/O
-ever leave the machine**; the Worker re-runs the fenced-code scrub server-side
-as a fail-closed backstop against a plugin redaction bug, derives the decisions,
-and **discards the transcript right after extraction — processed in memory,
-never stored.** That is a *weaker* claim than the BYOK/Model-3 path, where
-nothing but the derived decisions ever leaves the machine — and we say so out
-loud rather than paper over it. (Model 3 is still a SEAM only; until F7.19/20
-ship, every run takes the Model-2 server path.) This is distinct from the
-hosted **repo-ingestion** pipeline (the diagram), which clones your code into a
-destroy-on-exit sandbox and never stores source either — two separate paths,
-same never-store-source posture for actual code. The canonical statement
-lives at [`/security`](https://backthread.dev/security).
-
-Dependency-free (global `fetch`); a `fetchImpl` seam lets tests run without a
-network or Worker. Worker origin is overridable via `BACKTHREAD_WORKER_URL`
-(e.g. `http://localhost:8787` for `wrangler dev`).
-
-## `backthread capture` — the SessionEnd/Stop hook (F7.2 / ARP-433)
-
-The self-maintaining moat: at the end of every agent session, derive the
-session's **decisions** (the "why") and land them in the hosted log, so it stays
-current after the one-time F5 backfill. `backthread capture` is the headless hook
-handler. Pipeline (all LOCAL until the last network hop):
-
-1. Read the hook input (JSON on **stdin**; `transcript_path` + `cwd` +
-   `session_id`). A `BACKTHREAD_HOOK_INPUT` env var is accepted as a dev/test fallback.
-2. Read the `.jsonl` transcript off disk.
-3. **Redact LOCALLY** (`redact.ts` — the security fence): drop every
-   tool-use / tool-result record, keep only natural-language prose, redact fenced
-   code blocks to `[code redacted]`. **No source code or tool I/O ever leaves the
-   machine.**
-4. Derive decisions via the **F7.IR router** (`inferDecisions`). When a repo
-   resolves from `cwd`, we pass `persist: true` so the server (membership-gated)
-   also writes them — then `result.persisted` is `true`.
-5. Persist:
-   - `result.persisted` → **done** (re-POSTing would double-write).
-   - else POST the **derived** decisions to `ingest-decisions`, which routes
-     connected vs **repo-less** (F7.8) server-side.
-
-**Best-effort + non-blocking (the load-bearing contract):** `runCapture` never
-throws — every failure mode resolves a structured outcome — and `backthread capture`
-**always exits 0**. A capture hiccup can never disrupt or delay the user's Claude
-Code session. If there's no device token, it kicks off `backthread login`
-fire-and-forget (never awaited) and **skips this capture** — the next session
-captures once a token exists.
-
-### Registering the hook — TWO mechanisms (F7.7 / ARP-438)
-
-Claude Code runs `SessionEnd` hooks, passing the session JSON on the hook
-process's **stdin**. `npx backthread capture` reads that payload, derives the session's
-decisions (locally-redacted), and persists them best-effort — always exiting 0, so
-the hook host never blocks on it and never sees a non-zero exit. There are two ways
-the hook gets registered, and Backthread uses both depending on how it was installed:
-
-1. **PRIMARY — the plugin manifest.** When Backthread is installed as a Claude Code
-   plugin, the hook is declared in **`hooks/hooks.json`** (referenced by the
-   `hooks` field of `.claude-plugin/plugin.json`) and Claude Code registers it
-   **automatically on install** — the user's `.claude/settings.json` is never
-   touched. This is the right home: the hook ships + versions with the plugin and
-   is removed cleanly on uninstall. (Schema confirmed against the current Claude
-   Code plugin docs: `hooks/hooks.json`, `command` type.)
-2. **FALLBACK — `backthread install` writes `.claude/settings.json`.** For the bare
-   `npx backthread` (non-plugin) path there is no manifest doing the wiring, so
-   `backthread install` merges this entry into the project's `.claude/settings.json`
-   itself (idempotent — re-running never duplicates it; a strict merge that never
-   clobbers other settings/hooks):
-
-   ```jsonc
-   {
-     "hooks": {
-       "SessionEnd": [
-         { "hooks": [ { "type": "command", "command": "npx backthread capture" } ] }
-       ]
-     }
-   }
-   ```
-
-## `backthread start` — the plugin first-run (8B.5 / ARP-486)
-
-The **in-agent** first-run for the plugin half of the both-equal front door (ARP-482),
-behind the **`/backthread:start`** slash command. Where `backthread install` wires the
-bare-`npx` (non-plugin) path (hook registration + backfill), `start` is the experience
-a founder gets after a **marketplace 1-click** install — the SessionEnd hook is already
-armed by the manifest, so `start` only does the *human* part:
-
-1. **Idempotence gate.** Reads `~/.backthread/first-run.json`. A returning user
-   (`onboarded` flag set) is **never re-onboarded** — it just confirms they're set up.
-2. **Trust gate.** Prints the **never-store-source** trust copy (the `TRUST_COPY` from
-   `install.ts`, consistent with [`/security`](https://backthread.dev/security)) **before
-   anything else** — the AC requires the claim to precede any transcript processing.
-3. **One-tap auth.** `--claim <code>` (8B.9) exchanges a web-app-minted claim code for a
-   device token — no browser, the web-initiated door. With no claim code it runs the
-   browser **loopback** (`ensureAuth`); an already-authed device short-circuits.
-   `--device` (headless device-code, F7.23) is **out of scope** (→ ARP-467) and is
-   **refused with the loud stub** rather than silently falling back to the loopback
-   (which would hang a headless box).
-4. **State-driven next step.** Reads the **unified onboarding state** (`fetchOnboardingState`,
-   8B.6 — the SAME backend signal the web wizard reads) and renders its canonical next
-   step. When the repo isn't connected this IS the **F7.10 connect nudge** copy
-   (server-driven); a terminal state renders cleanly with the diagram deep-link.
-5. **Mark onboarded.** Persists the flag so step 1 short-circuits next time.
-
-Exits non-zero **only** on a genuine auth failure (capture won't run until you act);
-the auth failure does **not** mark onboarded, so re-running retries.
-
-**"Onboarded" is an explicit flag**, not the derived "token present + ≥1 capture": the
-trust gate must precede the very first capture (so we can't key onboarding off having
-already captured), and a token rotation must not re-trigger the wizard. The derived
-onboarding *state* still drives the *next-step* copy — it's just not the onboarding gate.
-
-### The two confirmation surfaces in the capture path
-
-Two 8B.5 lines live in the capture path itself (not in `start`), each once-per-install:
+## Your code never leaves your machine
 
-- **Trust gate on the silent hook path** (`maybeShowTrustGate`): the manifest-armed
-  SessionEnd hook can fire **before** any `start`/`install` ran, and `runCapture`'s
-  no-auth path fire-and-forgets `ensureAuth` (which can open a browser). So `runCapture`
-  prints the trust copy **once, before reading the transcript or firing login** — the
-  never-store-source claim holds on both entrypoints. Best-effort + never-throws +
-  never-blocks: it can't break the always-exit-0 capture contract.
-- **First-capture confirmation** (`maybeFirstCaptureConfirm`): after the **first** capture
-  that lands decisions against a **connected** repo, a once-only **"captured N — view them
-  in your "How it works" diagram: <deep-link>"** line. Mutually exclusive with the connect
-  nudge (which owns the not-connected case). Throttled via `firstCaptureShown` in the
-  same `first-run.json`. Best-effort.
+Backthread reads your agent **transcripts**, not your repo. Before anything is
+sent, the CLI redacts every transcript **locally**:
 
-## `backthread install` — onboarding (F7.7 / ARP-438)
+- **Drops** every tool call and tool result — where source code and command output live.
+- **Keeps** only natural-language prompts and the agent's reasoning.
+- **Redacts** any fenced code block to `[code redacted]`.
 
-The one-motion first-run that lands capture in the rescue-mode aha moment. It runs
-three steps, reporting each, and exits non-zero **only** on a genuine auth failure
-(the hook + backfill legs are best-effort and never fail the install):
+Only the derived, natural-language *decisions* ever leave your machine. The
+redaction fence is open source ([`@backthread/redact`](https://www.npmjs.com/package/@backthread/redact))
+so you can verify it — read more at [backthread.dev/security](https://backthread.dev/security).
 
-1. **Auth handshake** — reuses `backthread login` via `ensureAuth` (F7.1): if a device
-   token already exists it's reused; otherwise the browser OAuth-loopback runs once.
-2. **Register the SessionEnd hook** — writes the `.claude/settings.json` fallback
-   above (skip with `--skip-hook` when installed as a plugin, where the manifest
-   already registers it).
-3. **Chain the backfill** — runs `backthread`'s **cli-native backfill** (below) so the
-   decision log is **non-empty at the aha moment**, then self-maintaining via the
-   live hook. Best-effort; skipped automatically when not yet authorized.
+## Quick start
 
-Flags: `--skip-auth`, `--skip-hook`, `--skip-backfill`.
+In your project:
 
-Before any transcript is read, `backthread install` prints the **never-store-source**
-trust copy (consistent with [`/security`](https://backthread.dev/security)):
-redaction happens locally; source code + tool I/O never leave the machine; only
-the **derived decisions** are stored. On the default server-inference path a
-*redacted, natural-language-only* transcript does leave the machine — never
-source, never tool output — and it's **discarded right after extraction, never
-stored** (the server re-redacts as a fail-closed backstop). The copy states this
-weaker claim plainly rather than hiding it behind "only decisions leave."
-
-### Cli-native backfill — `backfill.ts` (the architecture decision, FLAGGED)
-
-The original F5 backfill is `scripts/ingest/decisions/backfill-cli.ts`, but the
-`npx backthread` plugin **cannot ship `scripts/`** (separate dependency-light bundle,
-`rootDir: src`). So `backthread install` chains a **cli-native** backfill instead: it
-enumerates this repo's existing Claude Code transcripts at
-`~/.claude/projects/<encoded-cwd>/*.jsonl` (the layout F7.3 established) and runs
-each one through the **same `runCapture` pipeline** as the live hook. It does not
-reimplement the redact/derive/persist fence — the never-store-source posture is
-inherited verbatim. It is sequential (a one-shot seed has no latency budget),
-best-effort (a missing dir / unreadable file / per-transcript failure is tallied,
-never fatal), and idempotent (the pipeline's dedupe key makes re-running safe).
-
-> **SCOPE (flagged):** this cli-native backfill is **Claude-Code-only**. Claude
-> Code's per-repo transcript layout is enumerable with zero dependencies; the
-> **multi-agent** backfill (Codex / Cursor / Gemini CLI via the F7.26 provider
-> registry) stays the **dogfood / server path** in `scripts/`, whose adapters the
-> plugin must not depend on. A founder using other agents still gets *live* capture
-> for them via the per-agent surfaces; only the one-shot history seed is
-> Claude-Code-only here. A shared backfill layer is a follow-up.
-
-## `/backthread:capture` — the manual slash command (F7.3 / ARP-434)
-
-The explicit/manual counterpart to the automatic SessionEnd hook: the founder who
-wants to capture **mid-session** ("capture what we just decided, now") or re-run a
-session runs it. It drives the **same `runCapture` pipeline** as F7.2 (local-redact
-→ F7.IR router-derive → hosted-POST) — the redact fence is never reimplemented —
-but differs from the hook in two ways:
-
-1. **It resolves the transcript itself.** The hook is fed `transcript_path` on
-   STDIN by Claude Code; a slash command is **not** (Claude Code exposes
-   `${CLAUDE_SESSION_ID}` and the cwd to a command, but not the transcript path).
-   So the manual path derives it from Claude Code's on-disk layout:
-   `~/.claude/projects/<slugified-cwd>/<session_id>.jsonl` (the slug replaces every
-   non-alphanumeric char in the absolute cwd with `-`). An explicit
-   `--transcript <path>` always wins. If neither resolves a readable file, it
-   prints an **actionable hint** (run with `--transcript <path>`) — never a silent
-   no-op, and never a browser pop.
-2. **It surfaces a per-run summary to STDOUT** (status + decision count +
-   repo-connected state) and exits non-zero on a genuine failure or when not logged
-   in — the manual analogue of the local pipeline's `summarize()`. (The hook stays
-   silent-to-stderr and always exits 0.) A missing device token surfaces as a
-   `run backthread login` hint; manual mode injects a **no-op `ensureAuth`** so — unlike
-   the best-effort hook — it never kicks off a background browser login.
-
-### The slash-command mechanism (FLAGGED design choice)
-
-Claude Code custom commands are merged into **skills**: a file at
-`<plugin>/commands/capture.md` in a plugin named `backthread` becomes **`/backthread:capture`**
-(plugin-namespaced — the faithful realization of the ticket's `/backthread capture`). The
-command file uses Claude Code's **`!`shell injection`**` to run
-`npx backthread capture --manual --session "${CLAUDE_SESSION_ID}" --cwd "$(pwd)"` at
-render time; the bin's summary is inlined into the prompt and the agent relays it.
-
-This package therefore ships a minimal plugin manifest (`.claude-plugin/plugin.json`)
-+ the command file (`commands/capture.md`), in addition to the `backthread` bin. Both are
-in package.json `files` so they ship via npm. The same files load standalone for
-local dev with `claude --plugin-dir ./cli`. (The hook + MCP-server wiring into a
-user's settings is install-time automation owned by F7.7 / ARP-438, sequenced after
-this task; the command file is the slash-command half.)
-
-## `backthread mcp` — the MCP server (F7.4 / ARP-435)
-
-The in-Claude-Code surface for both halves of HMW #2 ("CC = capture/queries
-entry"). `backthread mcp` starts a long-running MCP server over **stdio** (stdout is the
-JSON-RPC channel; all diagnostics go to stderr) exposing two tools:
-
-- **`capture`** — capture the current/given session's DECISIONS (the "why"). It
-  reuses the **F7.2 `runCapture` pipeline verbatim** (local-redact → derive →
-  hosted-POST) — the redact fence is never reimplemented. Best-effort: a hiccup
-  never disrupts the session. Args: `transcript_path` (**required** — unlike the
-  hook, the MCP tool has no STDIN, so the host must supply the transcript path;
-  without it the tool returns an actionable hint and captures nothing), plus
-  optional `cwd` and `session_id`.
-- **`query`** ("how does X work?") — reads the **salience-ranked Flows +
-  Decisions** for the configured repo via the F7.5 `read-decisions` endpoint
-  (authenticated with the `backthread_pat_` device token), and returns them **plus a
-  deep-link** into the web-app "How it works" diagram
-  (`https://app.backthread.dev/<owner>/<repo>`) so the founder can jump from CC to the
-  visual. Read-only. Args (all optional): `question` (narrated against the returned
-  log, not a server-side filter), `repo` (`owner/name` override; else `config.repo`,
-  else the cwd git remote), `cwd`. Unauthed → it reports "run `backthread login`" — it
-  **never** triggers a browser login itself (unlike the best-effort capture hook).
-
-Register it in `.claude/settings.json` (install-time wiring is F7.7 / ARP-438):
-
-```jsonc
-{
-  "mcpServers": {
-    "backthread": { "command": "npx", "args": ["backthread", "mcp"] }
-  }
-}
+```bash
+npx backthread install
 ```
 
-The server module (`src/mcp.ts`) is thin: the tool handlers delegate to
-`runCapture` / `queryDecisions` (their own modules + tests). Both handlers and the
-full tool wiring are unit-tested over the SDK's in-memory transport with mocked
-impls — no live network, no browser, no real auth.
-
-### How `cli/` accesses the redact/parse fence (architecture decision)
-
-The redaction fence is owned by `scripts/ingest/decisions/transcript.ts` (the
-F3/ARP-427 fence, behind the F7.11 provider seam). The `cli/` package, however,
-is a **separate, dependency-light bundle** whose distribution target is `npx backthread`
-— where **`scripts/` does not ship** — and its tsconfig pins `rootDir: src`, so a
-`../scripts/...` import would also break the build layout. So the fence is
-**vendored** into `cli/src/redact.ts` (+ the git-remote→repo parser into
-`cli/src/repo.ts`) as pure, zero-dependency copies. Parity with the canonical
-implementations is enforced by golden cases in `redact.test.ts` / `repo.test.ts`,
-so the two cannot silently drift.
-
-> **Distribution follow-up (flagged on ARP-433):** the vendored copy is the
-> pragmatic dogfood call, **not** the end state. The end state is a tiny shared
-> package (e.g. `@backthread/redact`) that both `scripts/ingest/decisions` and `cli/`
-> depend on, so the security fence has exactly **one** implementation. Until then,
-> a change to one fence must be mirrored in the other (the parity tests will fail
-> loudly if not). This is a follow-up ticket, not in-scope here.
+That's the whole setup. `install`:
 
-## Local config — `~/.backthread/config.json`
-
-Read by F7.2 / F7.3 / F7.4. Shape (all fields optional):
-
-```json
-{
-  "account": "<account uuid>",
-  "repo": "owner/name",
-  "device_token": "backthread_pat_…"
-}
-```
+1. **Signs you in** — opens your browser for one click (you'll need a free
+   [Backthread](https://backthread.dev) account; the CLI never sees a password,
+   and your device token is never printed or copied to the clipboard).
+2. **Wires up capture** — registers a hook so each Claude Code session is
+   captured automatically when it ends.
+3. **Backfills history** — replays your recent Claude Code sessions in this repo
+   so your "How it works" log isn't empty on day one.
 
-Always written at `0600` (dir `~/.backthread` at `0700`).
+Already added Backthread as a Claude Code plugin? The hook is wired for you —
+run `/backthread:start` (or `npx backthread start`) just to sign in.
 
-## Environment overrides (dev/testing)
+## Onboard yourself in 3 steps
 
-- `BACKTHREAD_APP_URL` — point the loopback at a local web app (e.g.
-  `http://localhost:5173`) instead of production.
-- `BACKTHREAD_WORKER_URL` — point the inference router at a local ingest Worker (e.g.
-  `http://localhost:8787` for `wrangler dev`) instead of production.
-- `BACKTHREAD_FUNCTIONS_URL` — point the Supabase Functions calls (`ingest-decisions`,
-  and the F7.4 `query` tool's `read-decisions`) at a local stack (e.g.
-  `http://localhost:54321/functions/v1`) instead of production.
-- `BACKTHREAD_CONFIG_DIR` — point the config at a temp dir instead of `~/.backthread`
-  (used by the unit tests; no real `$HOME` is touched).
+1. **Install** — `npx backthread install` in your repo. One browser click to authorize.
+2. **Keep coding** — at the end of every Claude Code session, Backthread captures
+   the decisions automatically. Nothing to remember.
+3. **Ask "how does X work?"** — query your decision log right inside Claude Code
+   (the `backthread` MCP server exposes a `query` tool), or open the live diagram
+   at [app.backthread.dev](https://app.backthread.dev).
 
-## Distribution choice (was open in ARP-432)
-
-**Default: `npx backthread`** — a standalone npm package with a `backthread` bin. Rationale:
-it's the most portable spine — the F7.2 hook, F7.3 slash command, and F7.4 MCP
-all shell out to / import the same bin regardless of which agent host invokes
-them, and `npx backthread login` works on any machine with Node. A **Claude Code
-plugin manifest** can wrap this bin later (it would just declare the hook +
-slash command and call `backthread`), so picking `npx backthread` now does not foreclose the
-plugin-manifest path — it's the lower layer underneath it. Per-agent adapters
-(Cursor/Codex) are explicitly later (Thread B / ARP-455→458).
-
-## `--device` fallback — STUBBED in F7.1
-
-The headless device-code flow (`gh`-style: "go to <url>, enter code ABCD-1234")
-needs a **server-side device-authorization endpoint** (a `/device/code` +
-`/device/token` pair) that does not exist yet — the F7.0 primitive (ARP-448)
-only ships the session-path mint. `backthread login --device` currently prints clear
-guidance (run `backthread login` with a browser, or mint from Account → Connected
-devices) and exits non-zero. Full impl is a follow-up.
-
-## Build / test
+## Commands
 
 ```
-npm --prefix cli install      # dev deps (tsx, typescript, @types/node, esbuild)
-npm --prefix cli run typecheck
-npm --prefix cli test         # node:test + tsx (NOT vitest)
-npm --prefix cli run build    # tsc → dist/         (dev + `npx backthread` path)
-npm --prefix cli run bundle   # esbuild → dist-bundle/backthread.js  (self-contained)
+backthread install   Set up capture for this repo (sign in + hook + backfill)
+backthread start     First-run for the Claude Code plugin (sign in + your next step)
+backthread login     Authorize this device (opens your browser)
+backthread whoami    Show this device's config (your token is never printed)
+backthread capture   Capture a session's decisions (run automatically by the hook)
+backthread mcp       Start the MCP server — the capture + "how does X work?" query tools
+backthread help      Show usage
 ```
 
-The root `vitest run` excludes `cli/` (own test runner, like `worker/`).
-
-## Two build paths (8A.1 / ARP-474)
+## Requirements
 
-There are **two** ways to build the bin, for two distribution targets:
+- **Node.js ≥ 22.18**
 
-- **`npm run build` (tsc) → `dist/`** — the **dev + npm-package path**. Emits
-  multi-file `dist/` and resolves the one runtime dep
-  (`@modelcontextprotocol/sdk`) from `node_modules` at runtime. This is what
-  `npx backthread` uses (npm installs the dep tree), and what `dist/bin/backthread.js` — the
-  `package.json` `bin` target — points at.
-- **`npm run bundle` (esbuild) → `dist-bundle/backthread.js`** — the **self-contained
-  distribution path**. Bundles the bin **and** that runtime dep into a single
-  executable ESM file (`esbuild.config.mjs`: `--bundle --platform=node
-  --format=esm --target=node22`, tree-shaken so only the `server/mcp.js` +
-  `server/stdio.js` subpaths of the SDK are inlined). It runs with **no
-  `npm install`** — drop the one file anywhere with Node 22 and run it.
+## Learn more
 
-The bundle is what:
+- **Live app** — [backthread.dev](https://backthread.dev)
+- **How your data is handled** — [backthread.dev/security](https://backthread.dev/security)
+- **Source & internals** — [github.com/backthread/backthread](https://github.com/backthread/backthread)
 
-- the **Claude Code plugin (8A.4)** references via
-  `${CLAUDE_PLUGIN_ROOT}/cli/dist-bundle/backthread.js` (so the plugin ships a runnable
-  bin without vendoring `node_modules`), and
-- a **future standalone binary** (Node SEA / `pkg`) wraps.
+## License
 
-Both `dist/` and `dist-bundle/` are git-ignored (regenerated from `src/`); both
-are listed in `package.json` `files` so they ship via npm/`npm pack`. A
-`prepack` script (`build && bundle`) regenerates both from current source
-whenever the package is packed, so a tarball never ships stale/empty `dist*`.
-The bundle does not replace the tsc build — they coexist for their two targets.
-esbuild is the only new devDep.
+[MIT](./LICENSE) © Backthread

package/dist-bundle/backthread.js

@@ -7272,12 +7272,12 @@ function deviceLogin(log) {
       "Headless (--device) login is not available yet.",
       "",
       "The device-code fallback needs a server-side device-authorization endpoint",
-      "that ships in a later F7 task. For now, run `backthread login` on a machine with a",
+      "that ships in a later task. For now, run `backthread login` on a machine with a",
       "browser, or mint a token from the web app (Account \u2192 Connected devices) and",
       'place it in ~/.backthread/config.json under "device_token".'
     ].join("\n")
   );
-  return { ok: false, message: "--device fallback not implemented yet (F7.1 stub)." };
+  return { ok: false, message: "--device fallback not implemented yet." };
 }
 async function ensureAuth(opts = {}) {
   const env = opts.env ?? process.env;
@@ -7469,7 +7469,7 @@ async function serverInfer(transcript, config2, opts = {}) {
         Authorization: `Bearer ${token}`,
         "Content-Type": "application/json",
         ...versionHeaders()
-        // x-backthread-version — server-side compat guard (ARP-479)
+        // x-backthread-version — server-side compat guard
       },
       body: JSON.stringify(body)
     });
@@ -7974,7 +7974,7 @@ async function fetchOnboardingState(input = {}, deps = {}) {
           // never logged
           "Content-Type": "application/json",
           ...versionHeaders()
-          // x-backthread-version — server-side compat guard (ARP-479)
+          // x-backthread-version — server-side compat guard
         },
         // CLI shape: repo_slug = "owner/name". Omitted when no repo resolved.
         body: JSON.stringify(repo ? { repo_slug: `${repo.owner}/${repo.name}` } : {})
@@ -8314,10 +8314,10 @@ async function runCapture(input, deps = {}) {
       env,
       fetchImpl: deps.fetchImpl,
       log,
-      // Carry the session id so the connect-nudge (F7.10) can throttle once-per-session
+      // Carry the session id so the connect-nudge can throttle once-per-session
       // — the SessionEnd hook fires once, but manual/MCP captures fire many times.
       sessionId,
-      // 8B.5 first-capture confirmation seam (threaded so tests can stub it).
+      // first-capture confirmation seam (threaded so tests can stub it).
       firstCaptureConfirmImpl: deps.firstCaptureConfirmImpl
     });
   } catch (e) {
@@ -8346,7 +8346,7 @@ async function persistDerived(decisions, repo, config2, decidedAt, ctx) {
         // device token — never logged
         "Content-Type": "application/json",
         ...versionHeaders()
-        // x-backthread-version — server-side compat guard (ARP-479)
+        // x-backthread-version — server-side compat guard
       },
       body: JSON.stringify(body)
     });
@@ -32696,7 +32696,7 @@ async function queryDecisions(input, deps = {}) {
           Authorization: `Bearer ${config2.device_token}`,
           "Content-Type": "application/json",
           ...versionHeaders()
-          // x-backthread-version — server-side compat guard (ARP-479)
+          // x-backthread-version — server-side compat guard
         },
         body: JSON.stringify({ repo: { owner: repo.owner, name: repo.name } })
       });

package/hooks/hooks.json

@@ -1,5 +1,5 @@
 {
-  "$comment": "F7.7 / ARP-438 — the SessionEnd capture hook, declared in the PLUGIN MANIFEST (referenced from .claude-plugin/plugin.json). When Backthread is installed as a Claude Code plugin, this registers the hook automatically — no mutation of the user's .claude/settings.json. `npx backthread capture` reads the SessionEnd payload off stdin, derives this session's decisions LOCALLY-redacted, and persists them best-effort; it always exits 0 so a capture hiccup can never disrupt the session. Mirrored by the .claude/settings.json fallback that `backthread install` writes for the bare-npx (non-plugin) path. We register ONLY SessionEnd (once per session) on purpose — `runCapture` also handles a Stop payload, but Stop fires on every turn-end, which would capture far too aggressively, so Stop is intentionally NOT registered here.",
+  "$comment": "The SessionEnd capture hook, declared in the PLUGIN MANIFEST (referenced from .claude-plugin/plugin.json). When Backthread is installed as a Claude Code plugin, this registers the hook automatically — no mutation of the user's .claude/settings.json. `npx backthread capture` reads the SessionEnd payload off stdin, derives this session's decisions LOCALLY-redacted, and persists them best-effort; it always exits 0 so a capture hiccup can never disrupt the session. Mirrored by the .claude/settings.json fallback that `backthread install` writes for the bare-npx (non-plugin) path. We register ONLY SessionEnd (once per session) on purpose — `runCapture` also handles a Stop payload, but Stop fires on every turn-end, which would capture far too aggressively, so Stop is intentionally NOT registered here.",
   "hooks": {
     "SessionEnd": [
       {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "backthread",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Backthread CLI — capture the *why* of your AI-coded changes from your Claude Code sessions, and query your codebase's architectural memory without leaving the terminal. Source code and tool I/O are redacted locally before anything leaves your machine.",
   "license": "MIT",
   "author": "Backthread",