altimate-receipts 0.3.2 → 0.4.0

package/README.md

@@ -18,9 +18,9 @@ read straight from the agent's own transcript, on your machine.
 npx altimate-receipts          # Report Card for your most recent agent session
 ```
 
-> **Adding it to a repo's PRs?** `receipts init` scaffolds the CI check, or see
-> [`docs/onboarding-internal.md`](./docs/onboarding-internal.md) — install, the pre-push
-> hook, and the one-block PR check.
+> **Adding it to a repo's PRs?** `npx altimate-receipts init` — one command, one PR,
+> and receipts attach themselves from then on. Contributors install nothing. See
+> [Add it to a repo](#add-it-to-a-repo-nothing-to-install).
 
 ```text
   ╔══════════════════════════════════════════════════════════════════════════╗
@@ -162,7 +162,10 @@ receipts stats            # dogfooding scoreboard: how often it ran + what it ca
 receipts eval             # flag-rate of the detectors over your real local sessions
 receipts badge [receipt]  # shields.io endpoint JSON for a README/PR badge
 receipts sarif [receipt]  # SARIF 2.1.0 for GitHub code-scanning (inline + Security tab)
-receipts init             # scaffold the PR-check workflow into this repo (1-command adopt)
+receipts prune            # remove committed receipts for merged/deleted branches (--dry-run)
+receipts init             # 1-command adopt: PR-check workflow + the repo-committed agent hook
+receipts install-hook     # write the self-updating git pre-push hook into .git/hooks
+receipts setup-local      # add the self-gated hook to YOUR ~/.claude/settings.json
 receipts rederive <t>     # reproduce the canonical receipt from a transcript
 receipts mcp              # start the MCP server (stdio) for IDEs/agents
 receipts --no-color       # plain text (also honors NO_COLOR)
@@ -198,45 +201,26 @@ wasn't hand-edited (`receipts verify --transcript`, [trust model](./docs/trust.m
 This is **opt-in** — the value is the Report Card; signing is there for when your
 org's compliance or settlement needs make it concrete.
 
-## Configure it locally (one prompt)
+## Add it to a repo (nothing to install)
 
-Your repo already has the **Verified by Receipts** check, but Receipts is local-first — the
-receipt is generated from *your* agent's transcript and committed to the branch; CI can't make
-it. So each contributor configures it once. Paste this prompt into your coding agent (Claude
-Code) **from inside the repo**, and it will set up local generation and verify the whole flow
-end to end — including that the receipt actually posts on the PR:
+**Repo owner, once:**
 
-```text
-Set up and verify altimate-receipts in this repo, end to end.
-
-1. Make the `receipts` CLI available. Try `receipts --version`. If missing, try
-   `npx --yes altimate-receipts --version`. If that also fails (private / not on npm),
-   clone + build it and use it via node:
-     git clone --depth 1 https://github.com/AltimateAI/altimate-receipts /tmp/altimate-receipts
-     (cd /tmp/altimate-receipts && npm ci && npm run build)
-   Then treat `receipts` as `node /tmp/altimate-receipts/dist/cli.js` everywhere below.
-
-2. Configure it locally so every future push auto-attaches my receipt: create a
-   `.githooks/pre-push` hook that runs `receipts pr`, and if it changes `.receipts/`,
-   `git add .receipts/` + commit, then asks me to push again. Make it executable and run
-   `git config core.hooksPath .githooks`. (Never let the hook fail the push.)
-
-3. Generate THIS branch's receipt now from my local Claude Code transcript:
-   `receipts pr --base <this repo's default branch>`  → writes `.receipts/<branch>.json`.
-
-4. Verify it is authentic and re-derivable: `receipts verify .receipts/<branch>.json` must pass.
+```sh
+npx altimate-receipts init
+```
 
-5. Commit it: `git add .receipts/<branch>.json && git commit -m "chore: attach agent receipt"`.
+Commit the files it writes, merge the PR — done. From then on, any Claude Code session
+that pushes a branch attaches its receipt automatically, *before* the push, so it lands
+on the PR with no extra step.
 
-6. Confirm uploading works end to end: push the branch and open/refresh the PR, then check that
-   the "Verified by Receipts" CI check runs AND a Receipts comment appears
-   (`gh pr checks` and `gh pr view --comments`). Report back whether the receipt is showing on
-   the PR, and paste the comment's headline line.
-```
+**Contributors install nothing.** The hook travels with `git clone` (Claude Code asks
+once to approve it), the CLI is fetched by npx on demand, and publishing a new release
+updates everyone automatically. Every path is best-effort — a missing session or an
+unreachable registry never blocks a push.
 
-If step 6 shows the check + comment, uploading works. If the comment is missing, the agent
-will report why (no receipt committed, workflow not present, or a permissions issue) — the same
-classification the fleet check (`script/dogfood-health.mjs`) uses.
+Humans pushing from a terminal, other coding agents, or repos that won't commit
+`.claude/` config: → **[the onboarding guide](./docs/onboarding.md)** has a one-command
+fallback for each.
 
 ## Dogfooding