Merge pull request #4222 from anthropics/morganl/receipts-readme

receipts: trim the README to what a user needs

.claude-plugin/marketplace.json

@@ -2606,7 +2606,7 @@
     },
     {
       "name": "receipts",
-      "description": "Generate a personal Claude Code impact report from your local ~/.claude/projects transcripts, cross-referenced against your local git history — what you shipped, which projects it went to, and each project's share of your usage — for justifying usage to a manager or a self-review. Reads your session transcripts and runs read-only git commands in the projects they mention; mining is local and only a small aggregate summary (counts and project names) is sent to write the report, which is saved to your home directory and published nowhere.",
+      "description": "A personal Claude Code impact report for justifying your usage to a manager or a self-review: what you shipped, which projects it went to, and each project's share of your usage. Reads your ~/.claude/projects transcripts and runs read-only git locally; only counts and project names are sent to write it up, and the report stays on your machine.",
       "author": {
         "name": "Anthropic",
         "email": "support@anthropic.com"

plugins/receipts/README.md

@@ -4,6 +4,14 @@ Generate a personal Claude Code impact report — "receipts" — from your own
 session transcripts, for the conversation where someone asks what all this
 Claude Code usage is actually buying.
 
+## Install
+
+```
+/plugin install receipts@claude-plugins-official
+```
+
+## Use
+
 ```
 /receipts            # last 30 days (default)
 /receipts week       # last 7 days
@@ -12,115 +20,52 @@ Claude Code usage is actually buying.
 /receipts for myrepo # scope to one project
 ```
 
-You get two files in your home directory: a markdown report to paste into a
-doc or a review, and a self-contained HTML receipt to open or attach. The
-receipt has an **Export CSV** button for the by-project table, and prints to a
-clean PDF.
+Two files land in your home directory: a markdown report to paste into a doc or
+a review, and a self-contained HTML receipt to open or attach. The receipt has
+an **Export CSV** button and prints to a clean PDF. Nothing is published
+anywhere.
 
-## What it reports
+Takes a few seconds — about 1s for a week, 5s for a year.
+
+## What you get
 
 - **What you shipped** — files and lines touched, commits carrying that work,
   PRs opened.
 - **By project** — sessions, active days, and each project's share of your
-  total compute.
+  usage. Work outside a repo is named for its directory; sessions that touched
+  no files at all (web searches, chat tools, dashboards) show as
+  *Research & investigation (no project)*, which for a lot of people is the
+  biggest row.
 - **Framing for a manager** — how to present the above without overclaiming.
 
-## What counts
-
-The report's universe is **work you did with Claude Code**, mapped to the
-project you did it on. Two consequences worth knowing before you read a number:
-
-**Claude Code's own machinery isn't your work.** The agent's scratchpad, its
-per-session tool output, and `~/.claude` are excluded. On a real 30-day corpus
-that removed 82% of the raw "lines touched" figure — files Claude wrote to talk
-to itself, which no one shipped.
-
-**A project is where work landed, not where your shell was.** Sessions are
-attributed to the projects their file operations touched (reads included —
-reading a repo to answer a question is work in that repo), resolved to the git
-root, or to the containing directory when it isn't a repo. Work outside a repo
-still counts; it's named for its directory. Subagents share their parent's
-session, so their work lands on the same project — there's no "delegated"
-category, because delegation is a mechanism, not a kind of work.
-
-Sessions that touched no files and didn't run in a repo — web searches, Slack
-reads, dashboard queries — land in **Research & investigation (no project)**.
-That row is often the biggest one. It's real work that genuinely has no home on
-disk, and naming it beats inventing a project for it.
-
-## Design notes
-
-**No dollar figures, anywhere.** A cost computed from local token counts is
-inferred, not measured, and won't match your actual bill. Presenting one
-invites the "that can't be right" reaction that discredits everything else in
-the report. Spend appears only as relative percentages.
-
-**No invented "hours saved."** There's no baseline in local data to compute a
-counterfactual from, and a fabricated multiplier undermines the real numbers
-sitting next to it. The report deliberately leaves room for you to add
-concrete wins by hand — those land better than any aggregate anyway.
-
-**No breakdown of spend by activity.** "38% of your compute went to reading
-code" is the chart everyone wants and the data can't support. A turn's cost is
-~90% context handling, half of it re-reading what earlier turns added, so
-charging it to whichever tool fired that turn is a modeling choice rather than
-a measurement — and the choice decides the answer. On one real month, three
-equally defensible weightings put web search at 11%, 28% or 51%. Spend appears
-once, per project, where it divides a real quantity by a real fact and the
-ranking holds whichever weighting you pick.
-
-**Careful claims.** Commits are counted only when they were authored under the
-identity git uses in that repo *and* their changed files include something
-Claude Code touched. Both tests have to pass, which is what keeps a snapshot
-cron out — it commits under your name but never touches the files Claude
-edited — while still counting the commit you made by hand after Claude wrote
-the code. The gap it leaves: a repo configured with a *shared* identity (a
-release bot's, say) makes that bot "you" for that repo, so a bot commit
-touching a file Claude also edited would count. Rare, and the alternative —
-reading only your global identity — silently zeroes the commit count for
-anyone using git's standard `includeIf` work/personal split, which is far more
-common.
-
-Lines are "touched", not "written". Sessions, active days and commits are all
-marked as columns that don't sum: a session spanning two projects is genuinely
-in both, and worktrees of one repo share commits.
+A few things the report deliberately won't tell you: no dollar figures, no
+"hours saved", and no breakdown of spend by activity. Each of those would be a
+guess dressed up as a measurement, and one bad number discredits the rest of
+the page. What's left is meant to survive someone pushing back on it.
 
 ## Privacy
 
-Mining is a local Node script — file I/O and `git`, no network calls.
+Everything is read locally — file I/O and read-only `git`, no network calls.
 
-It reads `~/.claude/projects/**/*.jsonl` — your own session history, already on
-disk, all projects, for the window you ask for. To find out which of the
-directories in there are repos, it runs `git rev-parse` in **every** directory
-any session mentioned (on one real month, 152 of them), and in the ones that
-are repos it also reads `user.email` and runs `git log`. All read-only, all
-local.
+It reads `~/.claude/projects/**/*.jsonl`, your own session history, already on
+disk. To work out which of the directories mentioned there are git repos, it
+runs `git rev-parse` in each of them, and in the ones that are, reads
+`user.email` and runs `git log`.
 
-The only thing that reaches the model is a small JSON summary: your name from
-`git config user.name`, aggregate counts, and project names. Your email is read
-but never emitted — it's used locally to match commit authorship. No code, no
-conversation content, and no tool or MCP server names — the report has no
-per-tool breakdown at all, so the list of services you've connected never
-leaves the script.
+The only thing that reaches the model is a small summary: your name from
+`git config`, aggregate counts, and project names. No code, no conversation
+content, and no tool or MCP server names — so the list of services you've
+connected never leaves your machine. Your email is used locally to match commit
+authorship and is never sent.
 
-The report is written to your disk and published nowhere unless you explicitly
-ask for a shareable version. Because repo names appear verbatim, the skill
-lists them before you send the report anywhere.
+Project names appear verbatim in the report, so the skill reads them back to
+you before you send it anywhere. Use `/receipts for <project>` to scope it down.
 
-## Relationship to `session-report`
+## Which plugin do I want?
 
-Both plugins read the same transcripts, and that's about where the similarity
-ends.
+[`session-report`](../session-report) reads the same transcripts to answer
+*where am I wasting tokens* — cache hit rates, expensive prompts — and hands
+you a list of optimizations. Install it to make your usage cheaper.
 
-[`session-report`](../session-report) is a tuning tool. It asks *where am I
-wasting tokens* — cache hit rates, disproportionate projects, expensive
-prompts — and its output is a list of optimizations. The audience is you, and
-the goal is to drive usage down.
-
-`receipts` is a justification tool. It asks *was this worth it* — what shipped,
-in which repos, against what spend — and cross-references local git history to
-tie usage to output. The audience is your manager, and the goal is to defend
-the spend rather than trim it.
-
-Install `session-report` to make your usage cheaper. Install `receipts` to
-explain why it was worth paying for.
+`receipts` answers *was this worth it* — what shipped, in which projects,
+against what spend. Install it to explain why the usage was worth paying for.