docs: README reads for people, grouped by what you give and get

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - `jam`, `jam-to-tasks`, `jam-to-ticket` and `jam-proof-table` handle screenshot, replay and silent Jams, and Jams that raise several problems: the router reads the transcript and a silent Jam's description, a task cites its field when there is no timestamp, a screenshot counts as proof, and an existing ticket covers only its own problem.
+- The README groups the skills by what you hand the agent and what you get back, with one plain line each, and lists the requirements one per line. It follows Jam's docs writing rules: no semicolons, and bold only for UI labels.
 - Added `jam`: type `/jam` and what you want, and it routes to the matching Jam skill. It also catches a bare jam.dev link or a vague ask, reads the Jam, and routes by what it holds; a clear ask still goes straight to its own skill.
 - The README lists skills as one bulleted list instead of a table plus a section per skill. `scripts/check.mjs` checks for the list entry.
 - The skills no longer download and run an installer. If `jam` is missing, they ask you to install it from jam.dev/cli. Addresses the remote-code-execution audit finding on `jam-proof` and `jam-annotate`.

README.md

@@ -28,30 +28,40 @@ Then paste a Jam link and say what you want:
 - "make a ticket for this jam"
 - "record a jam showing it works"
 
-A Jam is a screen recording with the console logs, network requests and user actions already attached, on one link. Bug reports, feedback walkthroughs and demos already live there. These skills let your agent read them, and record its own Jam when it's done, so you check the result by watching it.
+A Jam is a screen recording or screenshot with the console logs, network requests and user actions attached, on one link. You'd record one for a bug report, a feedback walkthrough or a demo. These skills let your agent read a Jam, and record its own when it's done, so you check the result by watching it.
 
 Works with Claude Code, Cursor, Codex, GitHub Copilot, Gemini CLI, OpenCode and [every agent skills.sh supports](https://skills.sh). Add `--skill jam-fix` to install one skill.
 
 ## Skills
 
-- [jam](./skills/jam/SKILL.md): "Take a look at this jam." Paste a bare link or a vague ask and it **reads the Jam**, then hands it to the skill that fits: a narrated walkthrough to `jam-to-tasks`, a bug to `jam-fix`. A clear ask goes straight to its own skill. `/jam` works too.
-- [jam-fix](./skills/jam-fix/SKILL.md): "Fix this jam.dev link." Reads the recording's **console errors**, **failed requests**, **user steps**, **frames** and **transcript**, then writes the **root cause with evidence**. Changes code only when you ask.
-- [jam-proof](./skills/jam-proof/SKILL.md): "Record a Jam showing it works." Records the change working and hands back a **Jam link for the pull request**, with **console** and **network** attached. Headless Chrome by default: it records the page, not your screen.
-- [jam-annotate](./skills/jam-annotate/SKILL.md): "Mark what's broken and file it." Turns a screenshot into a Jam that points at the problem: **boxes**, **arrows**, **notes**, **redactions** and **blurs**, with the retina math done right.
-- [jam-to-e2e](./skills/jam-to-e2e/SKILL.md): "Write an e2e test for this Jam." Turns a Jam into a test in **your own runner and language**, with first-class guidance for **Playwright** and [tester-army/e2e](https://github.com/tester-army/e2e). A Jam of a flow becomes a test that **guards it**. A Jam of a bug becomes a **failing test**, so the fix has something to turn green.
-- [jam-to-tasks](./skills/jam-to-tasks/SKILL.md): "Do what I said in this jam." Reads a narrated walkthrough to the end and lists **every change asked for**, each with its **timestamp**, **frame** and **quote**, then works the list: done, deferred with a reason, or asked about.
-- [jam-to-ticket](./skills/jam-to-ticket/SKILL.md): "Make a ticket for this jam." Files a Jam into **Linear**, **GitHub Issues** or **Jira** with steps, expected result, the key frame and errors, after checking it is **not ticketed already**.
-- [jam-proof-table](./skills/jam-proof-table/SKILL.md): "Give me the jams for each fix." Ends a batch of work with **one table**: each claim, its status, and the Jam that shows it. Names and files those Jams so they can be **found later**.
-- [video-to-jam](./skills/video-to-jam/SKILL.md): "Split this recording by bug." Turns an MP4, a Loom download or a long call into **one Jam per issue**, cut where the speaker moves on, titled and filed in a folder.
+You don't need to remember these names. Paste a Jam link, say what you want, and your agent picks the skill.
 
+### Give your agent a Jam
+
+- [jam](./skills/jam/SKILL.md): "Take a look at this jam." For a link with no instructions. It reads the Jam and picks the skill below that fits.
+- [jam-fix](./skills/jam-fix/SKILL.md): "Fix this jam." Finds the root cause from the errors, failed requests and steps in the recording, and shows the evidence. It changes code only when you ask.
+- [jam-to-tasks](./skills/jam-to-tasks/SKILL.md): "Do what I said in this jam." Turns your feedback into a numbered to-do list, each item tied to the moment you said it, then works through it.
+- [jam-to-e2e](./skills/jam-to-e2e/SKILL.md): "Write a test for this jam." Writes an end-to-end test with your project's own test setup. A Jam of a bug becomes a test that fails until the fix lands.
+- [jam-to-ticket](./skills/jam-to-ticket/SKILL.md): "Make a ticket for this jam." Files it in Linear, GitHub Issues or Jira with the steps, a frame from the recording and the errors, unless a ticket already exists.
+- [video-to-jam](./skills/video-to-jam/SKILL.md): "Split this recording by bug." Turns an MP4, a Loom download or a long call into one Jam per issue.
+
+### Get a Jam back
+
+- [jam-proof](./skills/jam-proof/SKILL.md): "Record a jam showing it works." Records the change working and gives you a Jam link for the pull request.
+- [jam-annotate](./skills/jam-annotate/SKILL.md): "Mark what's broken and share it." Draws boxes, arrows and notes on a screenshot, blurs anything private, and shares it as a Jam.
+- [jam-proof-table](./skills/jam-proof-table/SKILL.md): "Give me the jams for each fix." After a batch of work, one table: each claim, whether it works, and the Jam that shows it.
 
 ## Requirements
 
-Every skill needs a free [Jam](https://jam.dev?utm_source=github&utm_medium=readme&utm_campaign=skills) account. `jam-fix` and `jam-to-e2e` read a Jam through the Jam MCP server or the [Jam CLI](https://jam.dev/cli); `jam-proof` and `jam-annotate` create Jams, which needs the CLI. `jam-to-tasks`, `jam-to-ticket`, `jam-proof-table` and `video-to-jam` use the CLI; `video-to-jam` also needs ffmpeg and a local transcriber such as Whisper. Install the CLI from [jam.dev/cli](https://jam.dev/cli); a skill signs in when it needs it. In CI or a cloud agent, set `JAM_TOKEN` to a [personal access token](https://jam.dev/docs/personal-access-tokens). Window and display capture in `jam-proof` need macOS or Linux (X11); its default, recording a headless browser, needs only Chrome.
+- A free [Jam](https://jam.dev?utm_source=github&utm_medium=readme&utm_campaign=skills) account.
+- The [Jam CLI](https://jam.dev/cli). A skill signs in when it needs to. `jam`, `jam-fix` and `jam-to-e2e` can read a Jam through Jam MCP instead, the Model Context Protocol (MCP) server the plugin connects.
+- For `video-to-jam`: ffmpeg and a local transcriber such as Whisper.
+- In CI or a cloud agent: a [personal access token](https://jam.dev/docs/personal-access-tokens) in `JAM_TOKEN`.
+- For `jam-proof`: recording a web page needs only Chrome. Recording a window or the whole screen needs macOS or Linux (X11).
 
 ## Install as a plugin
 
-The plugin installs every skill, connects the [Jam MCP server](./docs/plugin.md) and updates itself. Use the plugin or `npx skills add`, not both, or the agent sees every skill twice.
+The plugin installs every skill, connects [Jam MCP](./docs/plugin.md) and updates itself. Use the plugin or `npx skills add`, not both, or the agent sees every skill twice.
 
 <details>
 <summary><strong>Claude Code</strong></summary>
@@ -111,11 +121,11 @@ Run `/mcp auth Jam` once to sign in. To test a checkout, run `gemini extensions
 
 </details>
 
-Sign-in, tokens, what the MCP server can do, and permissions: [docs/plugin.md](./docs/plugin.md).
+Sign-in, tokens, what Jam MCP can do, and permissions: [docs/plugin.md](./docs/plugin.md).
 
 ## Contribute
 
-Bug in a skill, or a skill you want? [Open an issue](https://github.com/jamdotdev/skills/issues/new/choose). Pull requests are welcome; [CONTRIBUTING.md](./CONTRIBUTING.md) is short.
+Bug in a skill, or a skill you want? [Open an issue](https://github.com/jamdotdev/skills/issues/new/choose). Pull requests are welcome, and [CONTRIBUTING.md](./CONTRIBUTING.md) is short.
 
 ---