backthread 0.1.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,11 @@
+{
+  "name": "backthread",
+  "displayName": "Backthread",
+  "description": "Keep the thread on what the agent shipped: Backthread captures the \"why\" of every session and answers \"how does X work?\" on a live \"how it works\" diagram — no diving through PRs. Provides the /backthread:capture slash command, the SessionEnd capture hook, and the backthread MCP server (capture + query).",
+  "version": "0.1.0",
+  "author": {
+    "name": "Backthread"
+  },
+  "homepage": "https://backthread.dev",
+  "hooks": "./hooks/hooks.json"
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Backthread
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,431 @@
+# backthread — CLI / plugin
+
+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.
+
+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.
+
+## Status (F7.1 / ARP-432, F7.2 / ARP-433, F7.3 / ARP-434, F7.4 / ARP-435, F7.7 / ARP-438)
+
+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.
+
+## 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:
+
+- **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 install` — onboarding (F7.7 / ARP-438)
+
+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):
+
+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.
+
+Flags: `--skip-auth`, `--skip-hook`, `--skip-backfill`.
+
+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"] }
+  }
+}
+```
+
+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.
+
+## 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_…"
+}
+```
+
+Always written at `0600` (dir `~/.backthread` at `0700`).
+
+## Environment overrides (dev/testing)
+
+- `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).
+
+## 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
+
+```
+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)
+```
+
+The root `vitest run` excludes `cli/` (own test runner, like `worker/`).
+
+## Two build paths (8A.1 / ARP-474)
+
+There are **two** ways to build the bin, for two distribution targets:
+
+- **`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.
+
+The bundle is what:
+
+- 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.
+
+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.

package/commands/capture.md

@@ -0,0 +1,29 @@
+---
+description: Manually capture this Claude Code session's decisions (the "why") into your Backthread "How it works" log. Use mid-session to capture what you just decided, or to re-run a session's capture.
+argument-hint: "[transcript-path]"
+disable-model-invocation: true
+---
+
+# /backthread:capture — capture this session now
+
+Captures this session's DECISIONS (the "why" behind the changes) into your Backthread
+decision log, using the same local-redact → derive → persist pipeline as the
+automatic SessionEnd hook. No source code or tool I/O ever leaves the machine.
+
+The capture has already run for this session (its summary is below). It resolves
+the transcript from this session id + working directory; if that failed, the
+summary tells you to re-run with an explicit path:
+`backthread capture --manual --transcript <path>`.
+
+## Capture result
+
+!`npx backthread capture --manual --session "${CLAUDE_SESSION_ID}" --cwd "$(pwd)" $ARGUMENTS`
+
+## Your task
+
+Relay the capture result above to the user verbatim — the status line and the
+decision count. Do not re-run the capture or invoke any other tool. If the result
+says "not logged in", tell the user to run `backthread login`. If it says nothing was
+captured, that's a normal outcome (the session may have been all code / tool work)
+— just report it. If it reports a number of decisions captured, confirm that and,
+when a "How it works" diagram link is present, surface it.

package/commands/start.md

@@ -0,0 +1,27 @@
+---
+description: First-run setup for Backthread — shows how your code is handled, authorizes this device, and tells you your next step. Run once after installing; it's idempotent (a returning user is not re-onboarded).
+argument-hint: "[--claim <code>]"
+disable-model-invocation: true
+---
+
+# /backthread:start — set up Backthread
+
+Runs the one-time first-run setup: the never-store-source trust note (how Backthread
+handles your code), a one-tap device authorization, and your next step toward a
+non-empty "How it works" diagram. It is idempotent — if you've already set up
+Backthread on this machine, it just tells you you're good to go.
+
+If the web app handed you a claim code, pass it: `/backthread:start --claim <code>`
+(no browser needed). Otherwise it opens your browser once to authorize this device.
+
+## Setup result
+
+!`npx backthread start $ARGUMENTS`
+
+## Your task
+
+Relay the setup result above to the user verbatim — the trust note, the auth status
+line, and the next-step line (including any link). Do not run any other tool. If the
+result says auth failed, tell the user to run `/backthread:start` again (or `backthread
+login`) to authorize. If it says they're already set up, just confirm that. When a
+"How it works" diagram link or a connect link is present, surface it.