flatbread-cli 0.4.0 → 0.7.0

package/README.md

@@ -29,12 +29,13 @@ flatbread share --publish             # after review, upload to the signed-in si
 flatbread login | logout | whoami     # sign the CLI in to a site (device flow)
 
 flatbread share --pr <url>            # link the pull request this run belongs to (https)
+flatbread share --from <n|words>      # share only the part from prompt n (or the prompt with these words)
 
 flatbread view                        # write the Execution Brief and CAPSULE.md beside the newest artifact
 
 flatbread pull <id-or-url>            # print a published run's Context Capsule
 flatbread pull <id-or-url> --out <f>  # or write it to a file
-flatbread mcp                         # stdio MCP server: flatbread_search_traces, flatbread_get_capsule
+flatbread mcp                         # stdio MCP server: flatbread_search_traces, flatbread_get_capsule, flatbread_share
 
 flatbread hook install                # offer the share at the end of a Claude Code turn
 flatbread hook status                 # where it is installed, and what it has seen
@@ -113,9 +114,9 @@ moves the whole scratch directory (the store becomes `<tmp>/store`).
 `flatbread login`, or set BOTH `FLATBREAD_API_URL` and `FLATBREAD_API_TOKEN`. The URL
 and the token resolve independently, each falling back to the stored login, and a
 STORED token is never offered to a site that did not issue it. Being signed in is not
-permission to upload: that is what `--publish` is for. `packages/cli/src/publish.ts` is the only file in this repository
-permitted to make an outbound request, the verify suite enforces that by name across
-all four packages, and it refuses to send a token over plain `http` to anything but
+permission to upload: that is what `--publish` is for. `packages/cli/src/publish.ts` is the only file that uploads; the
+files allowed to make any request are a fixed list the verify suite enforces by name across
+all four packages, and publish.ts refuses to send a token over plain `http` to anything but
 loopback. A publish failure never invalidates the local record; it is reported.
 
 Visibility is `private` unless a human raises it - in the review UI, or from the owner
@@ -168,15 +169,69 @@ reload the VS Code window) afterwards.
 A connected tool is not a used one: in a real session the agent read the tool list and implemented
 the fix without searching. So setup also writes a skill that says when to search - before the first
 edit, after a failure - to `~/.claude/skills/flatbread/SKILL.md` (or under `$CLAUDE_CONFIG_DIR`) and
-`~/.agents/skills/flatbread/SKILL.md`, the shared skills folder Codex reads. A file there that
-flatbread did not write is left alone. `--no-mcp` skips the server and the skill.
+`~/.agents/skills/flatbread/SKILL.md`, the shared skills folder Codex, Cursor and Gemini CLI read.
+Where Antigravity is installed it also goes inside a plugin
+(`~/.gemini/config/plugins/flatbread/`, with its `plugin.json`), and where OpenCode is installed to
+`~/.config/opencode/skills/flatbread/SKILL.md`. A file there that flatbread did not write is left alone.
+
+The other agents get the MCP server too, each only if it is installed (its folder exists): Codex as a
+`[mcp_servers.flatbread]` table in `~/.codex/config.toml` (or `$CODEX_HOME`), Cursor in
+`~/.cursor/mcp.json`, Antigravity in `~/.gemini/config/mcp_config.json`. Same rules as Claude Code's
+file, and in the TOML every other line, comment and table stays where it was. `--no-mcp` skips every
+server and every skill.
+
+### Share this run from the chat (agent first)
+
+When a run went well, say so in the same chat: "share this run", "share to flatbread", or
+"flatbread share". The skill tells the agent to call the MCP tool `flatbread_share`. Flatbread
+finds this session, parses and scans it in the background, and opens the review page in your
+browser. The agent's reply says the page is open; nothing has been saved or uploaded yet.
+
+- **Confirm is the only gate.** You read the matches, pick what to keep and the visibility, then
+  Confirm. Cancel, or no answer within 30 minutes, keeps nothing.
+- **The page you land on is the receipt:** the link when it was uploaded (or why it was not -
+  not signed in, no site set, the upload failed), the run's ID, and its manage token, shown
+  once. The agent is never sent the token.
+- **The share request is not part of the run.** The last turn's `flatbread_share` call is cut,
+  and so is the prompt that only asked for it. "Fix it, then share it" keeps the fix.
+- **A part of a long session:** "share this run from the prompt where I asked about the retry
+  helper" - the agent passes `from` as a prompt number or words from that prompt, and the run
+  starts there. The page has a **Starts at** list to change it before Confirm. Words that match
+  no prompt, or more than one, come back to the agent as the list of prompts to choose from.
+- **One review at a time.** Asking again while a page is open returns that same page.
+- `publish: false` keeps it on this machine; the default uploads on Confirm when this machine is
+  signed in (`flatbread login`).
+
+How the session is found: first by the session ID the agent puts in its environment
+(`CLAUDE_CODE_SESSION_ID`, `CODEX_SESSION_ID`), when the MCP server can see it - not yet
+measured, so it is not relied on; then the newest session of this folder; then the newest
+session of the agent named in `harness`. The review page says which one it took ("Found as").
+
+The same thing by hand: `flatbread share` (newest session), `flatbread share --from 7`.
+
+### When your agent skips Flatbread
+
+The skill makes searching likely, not certain. Measured on 2026-10-19 with the same folder and
+the same sentence: Codex read the skill and searched before its first edit; Claude Code (Sonnet
+5.5) had the skill loaded and went straight to the edit. Flatbread does not search on every prompt
+by itself, on purpose: that would send each prompt's words to the site whether or not you wanted a
+search, add a network round trip before every reply, spend a call on prompts that need none, and
+put unrelated runs into the agent's context. So when it matters, ask for it:
+
+- say it in the prompt: "Search Flatbread first, then fix the retry helper in app.ts", or
+  "use the flatbread skill";
+- or add one line to the project's `CLAUDE.md` (Claude Code), `AGENTS.md` (Codex, Cursor) or
+  your agent's own rules file, so every session there gets it:
+  `Before your first edit, search Flatbread (flatbread_search_traces) for a run that already did this task.`
 
 `setup --dry-run` writes nothing. `setup --uninstall` removes the handlers, the MCP entry, the skill 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
+"retries" and "retrying"). When no run has every word, the runs sharing the most of them are
+listed under `Closest, by words in common`, each with how many it shares - an agent words a
+task as a task, not as a title. `--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;
@@ -302,9 +357,10 @@ another codebase, and no copy should ever suggest it does.
 
 # Sharing: `flatbread share`
 
-The command exists to put a human gate in front of the data. It never uploads
-anything, and it cannot: there is no outbound request anywhere in this package,
-and a test greps the sources to keep it that way.
+The command exists to put a human gate in front of the data. Nothing leaves the
+machine before Confirm: the review runs offline, and only a fixed list of files may
+make a request at all (upload, sign-in, search, pull), which a test asserts by
+grepping the sources.
 
 ```
 parse the session  ->  scan every string  ->  review in the browser  ->  write a sanitized draft
@@ -318,7 +374,9 @@ parse the session  ->  scan every string  ->  review in the browser  ->  write a
 3. Serve one page on `http://127.0.0.1:4321` (then 4322-4325 if busy).
 4. You tick any match to KEEP its original text; everything else is redacted.
 5. You pick visibility: `private` (default), `unlisted`, `public`.
-6. Confirm writes `packages/cli/.tmp/last-share.json`. Cancel writes nothing.
+6. Confirm writes `packages/cli/.tmp/last-share.json`, keeps the run under its own ID, and
+   with `--publish` (or from the agent's `flatbread_share`) uploads it. Cancel writes nothing.
+7. `--from <n|words>` starts the run at that prompt; the page can change it before Confirm.
 
 ## The redaction engine
 
@@ -391,6 +449,12 @@ An offline machine can run the whole review.
 - **Side:** every match with a rule label, a preview of the original capped at 24
   characters, and the field path. `redact all` / `keep all` buttons, the visibility
   radio, and Confirm / Cancel.
+- **Starts at:** when the session has more than one prompt, a list of them; picking one
+  reloads the page for the part from that prompt (`?from=N`). A start it did not offer is
+  refused (400).
+- **After Confirm:** a receipt - "Shared" with the link, or "Saved on this machine" with the
+  reason nothing was uploaded - plus the run's ID and its manage token, shown once. A second
+  Confirm is refused (409).
 
 The page shows unredacted secrets when you tick KEEP, by design — you cannot
 review what you cannot see. That is why it binds `127.0.0.1` only and is never