docs(readme): pitch PRIMARY-selection feature in Why This Exists

[cmeans-claude-dev]

Closes #123. Promotes the X11/Wayland PRIMARY-selection support that shipped in #122 from "three parameter descriptions in the tools table" to a featured ### Bonus subsection under ## Why This Exists, alongside the existing table-paste pitch and the fixes-copying-from-Claude-Code pitch.

What landed

README.md:

• New ### Bonus: read your X11/Wayland selection without Ctrl-C subsection between the existing Claude-Code copy-from-terminal Bonus section and the ## Tools table.
• Two short sentences explaining the CLIPBOARD vs PRIMARY split (selection buffer, middle-click paste, updates on highlight without an explicit Ctrl-C).
• Names the three tools that accept selection="primary" (clipboard_paste, clipboard_read_raw, clipboard_list_formats).
• Four concrete workflow callouts: terminal triage, vim/IDE visual selection, browser/PDF reading, two-buffer (CLIPBOARD + PRIMARY in the same conversation).
• Closes with the Linux-only caveat and the macOS/Windows clear-error behavior so users on those platforms aren't surprised.

CHANGELOG.md: [Unreleased] / ### Changed entry.

Why this shape

Issue #123 outlined two options: a single bullet in ### Reading your clipboard (light touch), or a featured subsection under ## Why This Exists with workflows. Picked the featured shape because PRIMARY is structurally distinct from the Ctrl-C clipboard (different buffer, different trigger semantics) and is worth equal billing with the other two "why" pitches. The tools-table parameter descriptions still cover the light-touch surface for parameter-level skimmers.

Verification

• Docs only; no Python touched. CI's lint, typecheck, test (3.11/3.12/3.13), integration-x11, version-sync, and validate-server-json should all stay green / no-op.
• Verified no em-dashes in the new content (per repo convention) and that prose uses American spellings.
• Renders cleanly as Markdown locally (no broken backticks or unclosed code spans).

Out of scope

• Sweeping pre-existing em-dashes elsewhere in README.md and CHANGELOG.md (lines 86, 231, 233, 255, 271 in README; many older CHANGELOG entries). Cosmetic; can be a separate sweep if desired.
• Adding the same workflow callouts to ### Tips for reliable triggering or ### Reading your clipboard examples. Issue Surface PRIMARY-selection feature in README beyond the tools-table parameter mention #123 explicitly asked for one shape, not both.

Test plan

• README renders cleanly on PyPI and on GitHub (no broken Markdown, code spans, or list indentation).
• ## Tools table still renders correctly immediately after the new subsection (no orphan blank line, no list bleed).
• CI green across lint, typecheck, test (3.11/3.12/3.13), integration-x11, version-sync, validate-server-json.

Co-Authored-By: Claude Opus 4.7 (1M context) noreply@anthropic.com

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cmeans]

LGTM

[cmeans]

QA Round 1 — Ready for QA Signoff

Single round, zero findings. Docs-only PR; the new ### Bonus: read your X11/Wayland selection without Ctrl-C subsection lands at README.md:67, between the existing ### Bonus: it also fixes copying from Claude Code and ## Tools. Heading hierarchy is consistent (two ### Bonus siblings under ## Why This Exists) and the ## Tools table immediately following renders without an orphan blank line or list bleed.

Issue #123 scope match.

Issue requirement	PR coverage
Option 1 (light touch) or Option 2 (featured ### Bonus)	Option 2 ✓
CLIPBOARD vs PRIMARY explanation	✓ "Linux desktops have two clipboards…"
Names the three accepting tools	✓ clipboard_paste, clipboard_read_raw, clipboard_list_formats
Workflow callout: terminal triage	✓
Workflow callout: vim/IDE visual selection	✓
Workflow callout: browser/PDF reading	✓
Workflow callout: two-buffer	✓
macOS/Windows clear-error caveat	✓ "Linux only. macOS and Windows have no equivalent buffer; passing selection=\"primary\" on those platforms returns a clear error."

CHANGELOG. Single bullet under [Unreleased] / ### Changed — correct Keep-a-Changelog category for a docs change. Closes #123 correctly stated.

Convention spot-checks.

• New content has zero em-dashes (per repo convention). git diff main...HEAD | grep "^+" | grep -c "—" → 0.
• American spellings throughout (highlighted, selection, paragraph, behavior — none of behaviour/colour/grey/centre).
• Pre-existing em-dashes at README.md:86, 231, 233, 255, 271 are correctly listed as out-of-scope in the PR body — acknowledged, not regressed by this PR.

Local verification on c451835 (docs-only, expected no-op):

• uv run pytest -q → 599 passed, 19 deselected, 5 xfailed in 3.90s.
• uv run ruff check src tests scripts → clean.
• uv run mypy src → clean.
• python scripts/sync-server-json.py --check → in sync at 2.5.1.
• Pre-existing 13-check CI suite all green.

Test plan. Ticked checkboxes 2 (Tools table still renders correctly after the new subsection — verified) and 3 (CI green — verified). Checkbox 1 (PyPI render) is post-merge / post-release and stays unchecked until the next vX.Y.Z ships.

Verdict: Ready for QA Signoff. Awaiting maintainer QA Approved.

[cmeans]

Adding Ready for QA Signoff — docs-only PR, issue #123 scope fully covered (Option 2 featured subsection with all four workflow callouts and the macOS/Windows clear-error caveat), local verification clean (599/19/5; ruff, mypy, sync-server-json all clean), CI fully green, no em-dashes in new content, zero findings. Awaiting maintainer QA Approved.