flatbread-cli 0.1.0 → 0.2.0

package/README.md

@@ -10,8 +10,7 @@ npm install -g flatbread-cli          # installs the `flatbread` command (Node 2
 npx -y flatbread-cli --help           # or run it without installing
 ```
 
-**Not on npm until the owner runs the first `npm publish`** - until then, `npm pack` (below) and
-`npm install -g ./flatbread-cli-<version>.tgz`. **The npm package is `flatbread-cli`, not `flatbread`.** `flatbread` on npm is an unrelated
+On npm since 2026-10-18 (0.1.0). **The npm package is `flatbread-cli`, not `flatbread`.** `flatbread` on npm is an unrelated
 project, so `npx flatbread` runs somebody else's code. The command it installs is `flatbread`.
 
 ## Commands
@@ -123,8 +122,12 @@ Visibility is `private` unless a human raises it - in the review UI, or from the
 panel on the site while signed in as the run's owner. There is no `--visibility` flag
 and no API field for it: `--no-review` is non-interactive and must never publish.
 
-`parse` writes `packages/cli/.tmp/last-parse.json`.
-`share` writes `packages/cli/.tmp/last-share.json` and refreshes `last-parse.json`.
+`parse` writes nothing: it prints the run's summary and brief. `parse --save` writes the raw
+(unredacted) trace to `packages/cli/.tmp/last-parse.json`, and `parse --out <file>` writes it there instead.
+`share` writes `packages/cli/.tmp/last-share.json`. `--title <text>` sets the run's title (the review
+page opens with it and can still change it; every secret in a typed title is redacted), and
+`--commit [sha]` binds the run to a commit (bare = HEAD) and records whether the working tree was
+clean against it.
 `view` reads the newest artifact (share draft preferred over raw parse), builds the
 deterministic Execution Brief with `buildExecutionBrief`, writes `last-brief.json` and
 `CAPSULE.md`, and prints `open http://127.0.0.1:3000/r/local`. It does **not**
@@ -136,6 +139,33 @@ capsule quotes trace text verbatim and inherits whatever the source still contai
 session's working directory is a git repository. Nothing else is read from git, the index is
 never written, and a log that names a different branch than the checkout gets no commit.
 
+### Auto-capture: `flatbread setup`
+
+`flatbread setup` turns on capture for this machine. It installs the Claude Code hook (as `hook
+install` does) with one difference - the SessionEnd handler also starts `flatbread capture` for the
+session that just ended - and, inside a git repository, a chained `post-commit` that records each
+commit against the newest session of that repository (if that session moved in the last two hours).
+
+Every capture goes to `~/.flatbread/bucket` (`FLATBREAD_HOME/bucket`): one record per session, with
+EVERY redaction match redacted, visibility `private`, never uploaded. A capture is not a share; to
+publish one, run `share --file` on its session, which opens the review. `capture.log` in the bucket
+has one line per capture, including the ones that skipped or were refused.
+
+The post-commit hook never replaces yours: an existing `post-commit` is kept as
+`post-commit.pre-flatbread`, runs first with git's arguments, and its exit status is the hook's.
+It runs after the commit exists, so no SHA changes. When the repository sets `core.hooksPath`
+(husky, lefthook) nothing is written and the line to add is printed. When `core.hooksPath` is
+set machine-wide (system or global config), the hook goes in the repository's own hooks
+directory and setup says it fires only if that machine-wide hook runs it.
+
+`setup --dry-run` writes nothing. `setup --uninstall` removes the handlers and the hook, and puts
+a chained hook back byte for byte. `FLATBREAD_HOOK_DISABLED=1` stops every capture.
+
+`flatbread search <words>` answers from this machine's shared runs, its captured runs, then the
+site - the same text the MCP tool returns. Words are matched as typed, and by stem ("retry" finds
+"retries" and "retrying"). `--local` leaves the site out; a site that did not answer is said, and
+exits 1.
+
 `pull` and `mcp` only read. A token from `flatbread login` goes only to the site that issued it;
 a private run's share link (`?t=`) is sent as a header, never in a URL. Add the MCP server to
 Claude Code with `claude mcp add flatbread -- flatbread mcp`.