@playola-radio/slipstream 0.1.0 → 0.3.0

package/README.md

@@ -1,132 +1,458 @@
 # Slipstream
 
-**Review your coding agent's work as it happens, instead of facing a pile of
-files at the end.**
+**Watch your coding agent's work as it happens, instead of facing a pile of
+changed files at the end.**
 
-Slipstream streams the changes an AI coding agent makes to your code, live, so
-you can follow along and review in near-real-time while the agent works. The name
-is the thesis: a slipstream is the low-pressure pocket behind a fast-moving
-object, and riding in it makes following far cheaper than leading.
+Slipstream is a local daemon that watches the folder an AI coding agent (Claude
+Code, Codex, or any other) is working in and records every file change it
+observes into an append-only event log. You can follow that log live in your
+terminal, read it over a local HTTP API, or build your own viewer on top of it.
 
-Status: **pre-implementation.** The architecture is settled and the MVP plan is
-written. No code yet.
+The name is the idea: a slipstream is the low-pressure pocket behind a
+fast-moving object. Following there costs far less than leading. Reviewing an
+agent's changes as they land is easier than reviewing them all at once.
 
-- [`IMPLEMENTATION_PLAN.md`](IMPLEMENTATION_PLAN.md) — the five-stage MVP plan
-- [`NOTES-architecture.md`](NOTES-architecture.md) — decision record, verified
-  findings, and the Codex adversarial review
+> **Status: early and pre-1.0.** The capture engine, log format, reader API, and
+> agent integrations work and are tested. They are developed and used daily on
+> macOS. The event format may still change between releases. The Linux test
+> suite runs in CI, but live capture on Linux gets far less use.
+
+## What it is honest about
+
+Slipstream makes narrow claims on purpose, and the rest of the design follows
+from them.
+
+- **It records observed states, not every write.** Slipstream watches the
+  filesystem, so it sees what a file looked like when it read it. If a file goes
+  `A → B → C` faster than Slipstream can read it, you see `A → C`. A file that is
+  created and deleted within a fraction of a second may never appear. When
+  Slipstream knows it missed something, it records an explicit gap event.
+- **"Which agent made this change?" is a guess, and labeled as one.** Slipstream
+  can read an agent's local transcript and match file changes to the agent's tool
+  calls by timing. The result is marked `heuristic`, `ambiguous`, `unknown`, or
+  `pending`, and can be revised later. It is never presented as proof of
+  authorship.
+- **Missing content is marked missing.** If a file could not be read (too large,
+  permission denied, removed mid-read), the event says so and gives the reason.
+  It never shows a fake empty file.
 
 ## Install
 
+Requires **Node.js 24 or newer**. Day-to-day use is on **macOS**. Slipstream
+watches files with [`@parcel/watcher`](https://github.com/parcel-bundler/watcher),
+which also supports Linux.
+
 ```sh
 npm install -g @playola-radio/slipstream
 ```
 
-Node.js 24 or newer is required. The published package ships compiled
-JavaScript; developing in this repo still runs the TypeScript sources directly
-(`npm run slipstream`, `npm test`) with no build step. To put a clone on your
-PATH with `npm link`, run `npm run build` first, and again after pulling: the
-linked command runs the compiled `dist/`, not the sources.
+This installs two commands: `slipstream`, and `slipstream-mcp` (the connector
+agents use, see [Group changes by task](#group-changes-by-task)).
 
-## License
+**From a clone:** run `npm ci`, then `npm run slipstream -- <command>`. That
+runs the TypeScript sources directly, with no build step. To put a clone's
+commands on your PATH, run `npm run build && npm link`. Rebuild after pulling,
+because the linked commands run the compiled `dist/`, not the sources.
 
-Apache-2.0. Copyright Playola Radio, Incorporated. See [`LICENSE`](LICENSE).
+## Quick start: watch a folder
+
+The fastest way to see Slipstream work is to point it at a folder and follow
+the feed from a second terminal.
+
+**Terminal 1** — capture a folder and serve its feed:
+
+```sh
+slipstream serve ~/code/my-project --store ~/.slipstream-demo
+```
+
+It prints the new session's ID:
+
+```text
+slipstream: watching /Users/you/code/my-project
+slipstream: session 3a8aee17-d12c-42f0-9798-f72d81819c0e
+...
+```
+
+**Terminal 2** — follow it live:
+
+```sh
+slipstream view --store ~/.slipstream-demo --session <session-id>
+```
+
+```text
+1 · slipstream.session.started.v1 · -
+2 · slipstream.file.baselined.v1 · src/app.ts
+3 · slipstream.capture.baseline.completed.v1 · -
+4 · slipstream.enrichment.configured.v1 · -
+5 · slipstream.file.changed.v1 · src/app.ts · 2751a3a
+```
+
+Add `--changes` to see the changed lines of each file, not just one line per
+event. Edit something in the project, or let an agent work there, and the
+changes appear as they are captured. Press Ctrl-C in terminal 1 to stop. The
+history stays in the store.
+
+> If you create the store folder yourself, make it private first
+> (`mkdir -m 700 <dir>`). Slipstream refuses to use a store that other users on
+> the machine can read, because the store holds copies of your source code.
+
+## What gets captured
 
-## What it promises — and does not
+In a git repository, Slipstream records the files git would include in a
+commit. A file that git ignores and doesn't track is skipped. Git itself makes
+that call, so it matches your `.gitignore` exactly. Outside a git repository,
+every file is captured.
 
-> Slipstream streams **a live history of observed filesystem states, with
-> explicit coverage gaps.** It does not claim to be a complete record of every
-> write.
+To skip more, add a **`.slipstreamignore`** at the root of the repository. It
+uses `.gitignore` syntax. Unlike `.gitignore`, it can also skip files git
+tracks, such as a committed but noisy generated file. Slipstream reads it when a
+recording starts, so edits apply to the next recording. It only works inside a
+git repository. Skipped files are never read or stored, and reports from the
+reader API say when this filter was active.
 
-Capture is watcher-primary, so it observes states rather than writes. If a file
-goes `A → B → C` faster than it can be read, Slipstream reports `A → C`; an
-`A → B → A` cycle can be invisible entirely. Those gaps are disclosed in the
-event schema and surfaced in the UI rather than papered over.
+## Connect an agent chat
 
-Similarly, attribution is revisable inference with an explicit status
-(`pending` / `heuristic` / `ambiguous` / `unknown`), never a verified claim of
-authorship. A timestamp near an agent's tool call is evidence, not proof.
+For real work, Slipstream runs as one long-lived daemon that records the
+workspace an agent chat is working in. From inside the Claude Code or Codex
+chat, run this in the workspace (or ask the agent to run it):
 
-## Design constraints
+```sh
+slipstream attach
+```
+
+This is the path for a chat that runs outside the Slipstream app, such as a
+terminal or Conductor chat. The Slipstream app is being designed to link its own
+chat for you instead, naming it explicitly, with no command to run.
+
+It works out which chat it is in, starts the daemon if needed, and starts
+recording. It also installs a hook and a tool in that workspace's agent config,
+which let you [ask the agent about a change](#experimental-ask-the-agent-about-a-change).
+If the chat has to reload to pick those up, `attach` prints the exact command.
+Then:
+
+```sh
+slipstream status                       # every capture, its state and linked chat, and the reader URL
+slipstream status <session-id or dir>   # one capture
+slipstream view --store ~/.slipstream --session <capture-session-id>
+slipstream unlink --session <id>        # disconnect the chat; the workspace keeps recording
+slipstream detach [<session-id or dir>] # stop recording (default: this directory); history is kept
+```
 
-- **The event schema is the public interface.** The on-disk JSONL log plus
-  content-addressed blobs are the source of truth; the HTTP/SSE reader is a thin
-  view over them; the bundled UI is one client among possible many. You must be
-  able to delete the front-end and replace it.
-- **Slipstream does not launch agents.** Conductor stays the launcher.
-  Slipstream rides in through user-level MCP and skill configuration.
-- **Claude Code and Codex CLI from day one**, via a capture path that does not
-  depend on either.
+Several workspaces can record at once, each with its own session ID. To record
+a workspace without connecting a chat, run `slipstream attach --watch-only [dir]`
+(add `--wait` to return only once it is recording). Running `attach` from a chat
+in a workspace that is already recording connects the chat to that same capture:
+no new baseline and no gap.
 
-## Architecture
+After a detach, first resume recording with `slipstream attach --watch-only`,
+then run `slipstream attach` from the chat. A chat attach by itself returns
+`CAPTURE_PAUSED` and does not resume recording. Each capture has at most one
+linked chat, and a chat is linked to at most one capture; attach explains and
+changes nothing otherwise.
 
-A headless local daemon (TypeScript/Node) captures bytes and writes an
-append-only event log; a browser client (React + Monaco) renders the feed. The
-MCP server is a thin stdio forwarder per agent session — verified necessary,
-since each session spawns its own server process — and the daemon owns the store.
+Current limits:
 
+- **Any Claude Code version can attach; Codex only in versions Slipstream has
+  verified.** A Claude Code chat attaches if its transcript matches the chat and
+  the workspace, and shows as setup pending until it answers the setup check.
+  For Codex the verified versions are 0.154.0 and 0.155.1, launched through its
+  SDK; anything else is refused and nothing is recorded. The Codex version
+  Conductor ships today isn't on the list yet, so Conductor's Codex chats are
+  refused for now.
+- At most 32 workspaces record at once. Past that, an attach is refused
+  (`CAPTURE_LIMIT_REACHED`) and nothing is recorded or queued; pause another
+  workspace, then attach again. Freeing a slot starts nothing on its own.
+- A paused workspace stays paused: a chat attach is refused (`CAPTURE_PAUSED`)
+  until the workspace is recorded again in Slipstream (or with
+  `slipstream attach --watch-only`).
+- At most 10 chats are linked at once. Past that, the workspace keeps recording
+  without a chat (`BINDING_LIMIT_REACHED`); unlink another chat to connect it.
+- Captures survive a daemon restart. Each one resumes under the same session
+  ID, with a `restart` gap covering the time nobody was watching. A linked chat
+  comes back as `setup_pending` and counts as connected again only after it
+  answers a fresh setup check. A workspace whose folder was deleted or replaced
+  in the meantime is not resumed; it shows as stopped (`root-missing`).
 
-## Queue a question about a captured change
+### Capture every Conductor workspace (optional host)
 
-With the shared daemon running (`slipstream start`) and explicitly attached to a
-Claude Code or Codex session, an independent local client can queue a question:
+Conductor is an optional host. The Slipstream app can create and record
+workspaces itself (see [Workspaces without Conductor](#workspaces-without-conductor));
+this section is for capturing workspaces that Conductor creates.
 
 ```sh
-slipstream ask --store /path/to/store --session <capture-uuid> \
-  --request-id <caller-generated-lowercase-uuid> --input question.json
+slipstream conductor install   # once, and again after upgrading Node or Slipstream
+slipstream conductor enroll    # capture the workspaces that already exist
 ```
 
-`question.json` contains the question and immutable after-snapshot identity read
-from the public events API (sequence numbers are decimal strings):
-
-```json
-{
-  "text": "Why is this check needed?",
-  "context": {
-    "change_seq": "42",
-    "path": "src/example.ts",
-    "snapshot_sha256": "aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
-    "line_start": 3,
-    "line_end": 5
-  }
-}
+`install` adds a LaunchAgent that keeps the daemon running and restarts it after
+a crash or a login (log: `~/Library/Logs/slipstream/daemon.log`). It also puts
+`slipstream conductor setup` and `slipstream conductor archive` in your personal
+Conductor scripts (`~/.conductor/settings.toml`), ahead of anything already
+there. Both the LaunchAgent and the scripts use the absolute paths of the Node and
+Slipstream that ran `install`; nothing depends on nvm or your shell profile.
+
+A repo with its own Conductor setup or archive script overrides your personal one.
+For each such repo, `install` writes `.conductor/settings.local.toml` in the repo's
+folder. That file runs Slipstream first and then the repo's own command, and keeps
+anything else in the file. It is for this machine only; `install` warns you if git
+would commit it. If the repo's script changes later, `conductor setup` warns
+until you run `install` again.
+
+From then on, a new workspace starts recording before the repo's own setup runs.
+The repo's own setup always runs, even when recording can't start (for example,
+when all 32 capture slots are in use). In that case Slipstream prints the reason
+and the setup script still fails, so the workspace shows that it isn't recording.
+Archiving a workspace stops its capture first and keeps the history; the repo's
+own archive script runs even if that stop fails.
+Conductor does not wait for setup to finish before starting the agent. On this
+machine (October 2026), the agent's first tool call came about 10–15 seconds
+after the workspace was created, whatever the setup was doing. In a repo whose
+setup builds container images, setup ran for about 100 seconds and the agent
+made 14 tool calls before it ended. Slipstream runs first in setup, but whether
+recording is ready before the agent's first edit was not measured. If the agent
+edits first, the first recorded state is whatever was there when recording
+started, and those earlier edits are not shown as changes. This is a known gap, accepted as is: Slipstream does not add a hook, a second capture source, or a wait to close it.
+`slipstream workspace create` (below) does not have this gap: it waits for setup to
+finish, and no agent exists in the workspace yet.
+
+Conductor removes an archived workspace's folder. Archive scripts were seen to
+run while the folder was still there (they could still use files in it), but
+whether Conductor waits for an archive script to finish before removing the
+folder was not observed. [real-use-check.md](docs/autocapture/real-use-check.md)
+has a direct check: an archived workspace's capture should end `stopped
+(archived)`, not `root-missing`.
+
+`enroll` reads Conductor's own list of workspaces that aren't archived, including
+sleeping ones. It captures them most recently active first. At 32 recording
+workspaces, additional enrollments are refused and freeing a slot starts nothing
+on its own. Archive a workspace you no longer use, then retry `enroll` or attach
+the workspace after capacity is available. `enroll` is safe to run again.
+
+**Recording any chat, without Ask Agent.** If your agent version isn't
+verified, you can still record its workspace by naming the chat yourself:
+
+```sh
+slipstream start --enable claude-code &   # use --enable codex for a Codex chat
+# Wait until it prints "slipstream: reader ..." before attaching.
+slipstream attach ~/code/my-project \
+  --harness claude-code --harness-session-id <chat-session-id>
 ```
 
-A follow-up adds `"reply_to_question_id"` naming the earlier question; its
-`context` must be identical. The example hash is a placeholder: use the actual change's `after.sha256`. The
-daemon validates the durable event and original blob, derives the selected text,
-and copies the explicit attach target. It never reads the current working file
-or accepts client-supplied authorship. Only after-content up to 1 MiB is eligible;
-select at most 200 lines / 16 KiB. Questions are trimmed and capped at 8192 UTF-8
-bytes. `serve` has no attach/control path and does not support `ask`.
-
-Success prints JSON `{v:1,ok:true,session_id,request_id,question_id,seq,
-queued_at_ms,expires_at_ms,duplicate}`. It means **durably queued**, not delivered
-to an agent or answered. Read `slipstream.question.queued.v1` through the existing
-authenticated `GET /v1/sessions/<id>/events` endpoint; its self-contained schema is
-available at `GET /v1/schemas/slipstream.question.queued.v1`.
-
-Codex and Claude Code delivery require an explicit root transcript binding at
-`attach` and a `PostToolUse` hook configured before the chat starts. See
-[the delivery contract](docs/ask-agent/contract.md#delivery-through-posttooluse)
-for the control fields and setup. The public
-`slipstream.question.dispatch_attempted.v1` event means the daemon committed an
-attempt before answering the hook; it does not confirm receipt or an answer.
-Attach Claude shortly after its first root tool call, and keep the chat's
-current directory at the attached worktree when claiming a question.
-
-Retry with the **same request ID, capture ID and input**. Same-ID/body retries
-return the original result without extending the 30-minute TTL. A changed body
-returns `REQUEST_CONFLICT`; more than 16 unexpired questions returns
-`QUESTION_LIMIT`. Other domain errors are `INVALID_QUESTION`, `INVALID_CONTEXT`,
-`SESSION_NOT_SELECTED`, `CAPTURE_NOT_READY`, and `STORAGE_UNAVAILABLE`. Errors
-print structured JSON on stderr (exit 1); local file/syntax errors exit 2.
-`STORAGE_UNAVAILABLE`, or a lost/malformed response after transmission, exits 3:
-the outcome is unknown and the record may already be committed. Preserve the same
-request ID, capture ID and input when retrying. A new capture never resumes an old queue; inspect
-the old public log by `request_id` rather than retargeting a retry.
-
-The control wire request is `{v:1,verb:"ask",session_id,request_id,text,context}`
-over the owner-only `<store>/control.sock` using existing NDJSON framing. No
-harness identity is required from the client. Full details, limits and lifecycle:
-[queue contract](docs/ask-agent/contract.md). Receiving-answer UI remains
-separate work.
+`--harness` is `claude-code` or `codex`. The session ID is the chat
+transcript's file name. `--enable` tells the daemon to read that harness's
+transcripts and estimate which changes possibly came from the agent; without it,
+Slipstream still records filesystem states but leaves that attribution unavailable:
+
+- Claude Code: `~/.claude/projects/<project>/<session-id>.jsonl`
+- Codex: `~/.codex/sessions/<yyyy>/<mm>/<dd>/rollout-<timestamp>-<session-id>.jsonl`
+
+Everything about `attach`, including exactly which files it edits:
+[docs/connect-agent-chat.md](docs/connect-agent-chat.md).
+
+### Workspaces without Conductor
+
+```sh
+slipstream workspace create ~/code/myrepo
+slipstream workspace archive ~/slipstream/workspaces/myrepo/workspace-1
+```
+
+`create` makes a git worktree at `~/slipstream/workspaces/<repo>/workspace-N` on
+a new branch `slipstream/workspace-N`, using the smallest N that is free. It
+fetches `origin` and starts from `origin/develop`, or from origin's default
+branch when there is no `develop`. A repo with no `origin` is refused. Then it
+starts the daemon if needed, starts recording the workspace, and runs the repo's
+committed setup script (`.conductor/settings.toml` or `conductor.json`, the same
+files Conductor reads). It waits for setup to finish. Whenever the folder was
+made, even if recording or setup then failed, it prints `workspace_path: <folder>`
+twice: once before setup runs, and again as its last line. A failed setup leaves
+the workspace in place.
+
+`archive` only works on a folder directly under `~/slipstream/workspaces/<repo>/`.
+It refuses a workspace with uncommitted or untracked changes (ignored files are
+fine). Otherwise it stops the recording, runs the repo's archive script, and
+removes the worktree. The branch is kept. If the archive script fails, the
+worktree stays and you can run `archive` again.
+
+Both scripts run in the workspace with `CONDUCTOR_ROOT_PATH` (the repo's main
+checkout) and `CONDUCTOR_WORKSPACE_PATH` (the workspace) set, so scripts written
+for Conductor work unchanged.
+
+Open question: setup and archive scripts are read only from Conductor's files
+(`.conductor/settings.toml`, `conductor.json`). Whether Slipstream gets its own
+native config for them is not decided.
+
+## Group changes by task
+
+An agent can label its work so the feed groups changes under titles like "Fix
+the pagination off-by-one" instead of by time alone. Slipstream offers this
+through an MCP server, `slipstream-mcp`, which gives the agent a
+`slipstream_begin_task` tool. The included [`SKILL.md`](SKILL.md) tells the
+agent when to call it.
+
+Copy-paste setup for Claude Code and Codex is in
+[docs/mcp-forwarder-config.md](docs/mcp-forwarder-config.md). If the daemon isn't
+running, the tool returns an error the agent is told to ignore. Slipstream never
+blocks the agent's work.
+
+## Build on it: the data is the interface
+
+The bundled terminal viewer is just one client. Everything it shows is available
+to any program you write, through two public routes. The daemon has no private
+channel to its own UI.
+
+**On disk.** The store (`~/.slipstream` by default) is plain files:
+
+```text
+~/.slipstream/
+  sessions/<session-id>/events.jsonl   # append-only log, one JSON event per line
+  blobs/sha256/<ab>/<sha256>           # file contents, stored by hash
+  runtime/<id>.json                    # how to reach the running HTTP reader
+```
+
+Each line of `events.jsonl` is a [CloudEvents](https://cloudevents.io/)-style
+record with a type such as `slipstream.file.changed.v1`. File contents are not
+stored inline. Each change names its before and after content by SHA-256, and
+the bytes live under `blobs/`. Contents are written to disk before any event
+that refers to them, so a crash never leaves an event pointing at missing bytes.
+Every event type has a JSON Schema in [`schemas/`](schemas/).
+
+**Over HTTP.** The reader listens only on `127.0.0.1` and requires a bearer
+token. Both the URL and the token are in the `runtime/*.json` file, readable only
+by you.
+
+```sh
+STORE=~/.slipstream                               # or whichever --store you used
+DESC=$(ls -t "$STORE"/runtime/*.json | head -1)   # the newest running reader
+URL=$(node -p "require('$DESC').url")
+# Put the token in a private file so it never appears in the process list.
+HDR=$(mktemp); node -p "'Authorization: Bearer ' + require('$DESC').token" > "$HDR"
+
+curl -H @"$HDR" "$URL/v1/sessions"
+curl -H @"$HDR" "$URL/v1/sessions/<id>/events?after=0&follow=true"
+```
+
+| Route | Returns |
+|---|---|
+| `GET /v1/sessions` | Captured sessions |
+| `GET /v1/sessions/:id/events?after=N[&follow=true]` | Events after sequence `N`, streamed live with `follow=true` |
+| `GET /v1/blobs/sha256/:hash` | Raw file contents |
+| `GET /v1/sessions/:id/changes/:seq/clips` | The changed regions of one file change ([CLIP-PROJECTION.md](CLIP-PROJECTION.md)) |
+| `GET /v1/sessions/:id/interfaces?before_seq=B&after_seq=A` | Functions added, removed, or changed from sequence `B` through `A` in a session, for TypeScript and Swift ([FUNCTION-CHANGES.md](FUNCTION-CHANGES.md)) |
+| `GET /v1/schemas/:type` | The JSON Schema for an event type |
+
+To show the feed the same way the bundled viewer does, follow
+[DISPLAY-FOLD.md](DISPLAY-FOLD.md). It explains how to turn the event stream
+into what's displayed, and includes test cases a new client can check itself
+against.
+
+## Experimental: ask the agent about a change
+
+From a captured change, you can queue a question about specific lines
+("Why is this check needed?"). Slipstream delivers it to the attached chat the
+next time the agent uses a tool, and the agent's answer is recorded back into
+the log.
+
+```sh
+slipstream ask --store ~/.slipstream --session <capture-id> \
+  --request-id <uuid> --input question.json
+```
+
+This needs a chat connected with the one-command `slipstream attach` above.
+Until the chat confirms it can answer, questions are refused with
+`AGENT_NOT_CONNECTED`. A successful `ask` means the question is safely queued,
+not that the agent has seen it. The input format, limits, retry rules, and error
+codes are in [docs/ask-agent/contract.md](docs/ask-agent/contract.md).
+
+## Privacy and what Slipstream stores
+
+- **Everything stays on your machine.** There is no telemetry and no network
+  access beyond the local reader on `127.0.0.1`.
+- **The store contains real copies of your source files**, including any secrets
+  that pass through the watched folder and aren't excluded by git or
+  `.slipstreamignore`. It is created readable only by you.
+- **Slipstream reads your agents' local transcripts** (under `~/.claude` and
+  `~/.codex`) to estimate which changes came from the agent. It never writes to
+  them.
+- **`slipstream attach` edits the workspace's agent config** (`.claude/` or
+  `.codex/`) to add its hook and tool. Those entries contain local paths, so keep
+  them out of commits.
+- **History is kept until you delete it.** While the daemon is detached,
+  `slipstream delete <session-id>` removes a session and `slipstream gc` removes
+  file contents no remaining session refers to.
+
+## How it works
+
+```text
+ agent edits files ─▶ worktree ─▶ file watcher ─▶ daemon ─▶ blobs/ + events.jsonl
+                                                     │                   │
+ agent's transcript ─(read-only, async)─▶ attribution┘                   ▼
+                                                           HTTP/SSE reader ─▶ any client
+ agent ─▶ slipstream-mcp (stdio, one per chat) ─▶ daemon control socket
+```
+
+- **The file watcher is the only capture source.** Agent transcripts can
+  refine *who probably* made a change, but never create a change event. Each
+  change is therefore recorded once.
+- **Analysis never slows capture.** Transcript matching and code analysis run
+  separately and only add to the log. If a step fails, the view has less
+  detail, but no events are lost.
+- **The daemon never launches your agent.** The Slipstream app can run the chat
+  itself; an outside chat joins through its own MCP and hook configuration. Each
+  chat starts its own small `slipstream-mcp` process, which only relays to the
+  single daemon that owns the store.
+
+The full decision record is in [NOTES-architecture.md](NOTES-architecture.md).
+
+## Command reference
+
+| Command | Does |
+|---|---|
+| `watch [dir] [--store dir]` | Capture a folder into its own store, with no daemon or HTTP |
+| `serve [dir] [--store dir]` | Same as `watch`, plus an HTTP reader |
+| `start [--store dir] [--config file] [...]` | Run the shared daemon |
+| `attach [dir]` | Run inside an outside agent chat (terminal, Conductor): connect it and start recording |
+| `attach [dir] --harness h --harness-session-id id` | Record a worktree for a chat you name yourself |
+| `status` / `detach` | Show or stop the active recording |
+| `conductor install` / `conductor enroll` | Keep the daemon running and capture every Conductor workspace |
+| `conductor setup` / `conductor archive` | Run by Conductor's setup and archive scripts |
+| `workspace create <repo>` / `workspace archive <folder>` | Make a worktree workspace, set it up and record it / remove it |
+| `view --store dir [--session id] [--changes] [--context N] [--full] [--disk]` | List sessions, or follow one live in the terminal |
+| `ask --store dir --session id --request-id uuid --input file` | Queue a question for the agent (experimental) |
+| `hook <codex\|claude-code> post-tool-use` | The hook command agents run to receive questions |
+| `delete <session-id>` / `gc` | Remove a session / unused file contents (daemon detached) |
+
+Run `slipstream` with no arguments for every option. The daemon commands accept
+`--store <dir>`, which defaults to `~/.slipstream`; `view` needs it spelled out.
+The daemon, the CLI, and `slipstream-mcp` must all use the same store.
+
+## Contributing
+
+Pull requests go to `develop`. Read [CLAUDE.md](CLAUDE.md) first. It lists the
+rules that keep Slipstream honest, and the product decisions that need
+discussion before a change.
+
+```sh
+npm run typecheck
+npm test            # fast, deterministic tier; runs in CI on macOS and Linux
+npm run test:os     # real-filesystem tier; needs macOS FSEvents
+npm run test:tools
+```
+
+[TESTING.md](TESTING.md) covers the test layout and the fake filesystem the fast
+tier uses.
+
+### Design documents
+
+| Document | Covers |
+|---|---|
+| [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md) | Staged plan, success criteria, and status |
+| [NOTES-architecture.md](NOTES-architecture.md) | Architecture decisions and the evidence behind them |
+| [DISPLAY-FOLD.md](DISPLAY-FOLD.md) | How a client turns events into a display |
+| [CLIP-PROJECTION.md](CLIP-PROJECTION.md), [FUNCTION-CHANGES.md](FUNCTION-CHANGES.md), [INTERFACE-PROJECTION.md](INTERFACE-PROJECTION.md) | Derived views: changed regions and function-level changes |
+| [SWIFT-INTERFACE.md](SWIFT-INTERFACE.md), [INTERFACE-V2-TYPESCRIPT.md](INTERFACE-V2-TYPESCRIPT.md) | Language support for function-level changes |
+| [STAGE-1-REPORT.md](STAGE-1-REPORT.md), [B2-MEASUREMENT-REPORT.md](B2-MEASUREMENT-REPORT.md) | Measured capture latency and loss |
+| [docs/](docs/) | Agent setup, the ask-agent feature, reader API notes |
+
+## License
+
+Apache-2.0. Copyright Playola Radio, Incorporated. See [`LICENSE`](LICENSE).

package/SKILL.md

@@ -22,7 +22,10 @@ Each declaration marks the start of its own group; a second task is never a
 retry of the first.
 
 Do **not** call it for every individual edit, and do not re-call it to "resume"
-a task you already declared — one declaration per task is enough.
+a task you already declared — one declaration per task is enough. The one
+exception: after `slipstream attach` runs again following a detach, declare
+your current task again. A resumed attach starts with no current task; an
+attach that reports `already_active` changes nothing and does not reset it.
 
 ## How to use it
 

package/contracts/interface/v2/schema.json

@@ -98,8 +98,8 @@
         },
         "policy_exclusions": {
           "type": "array",
-          "items": { "enum": ["store-directory", ".git", "symlinks"] },
-          "$comment": "Static capture policy, always exactly [\"store-directory\", \".git\", \"symlinks\"] (checked in code; src/schema.ts const is not deep): these targets are never read, and the baseline records no event for them."
+          "items": { "enum": ["store-directory", ".git", "symlinks", "git-ignored", "slipstream-ignored"] },
+          "$comment": "Capture policy (checked in code; src/schema.ts const is not deep): these targets are never read, and the baseline records no event for them. Always [\"store-directory\", \".git\", \"symlinks\"], followed by \"git-ignored\" when a capture.scope event with policy git is recorded by after_seq: paths git ignores and does not track are outside capture. Then \"slipstream-ignored\" when such an event also carries slipstream_ignore active: a root .slipstreamignore excluded extra paths, including tracked ones."
         }
       }
     },
@@ -151,7 +151,7 @@
       "required": ["seq", "reason", "scope"],
       "properties": {
         "seq": { "$ref": "#/$defs/seq" },
-        "reason": { "enum": ["coalesced", "baseline-unreadable", "watcher-error", "restart", "storage"] },
+        "reason": { "enum": ["coalesced", "baseline-unreadable", "watcher-error", "restart", "storage", "capture-scope-unavailable"] },
         "scope": {
           "oneOf": [
             {