docs: README that leads with the matrix, and a GIF that tells the truth

[jothimani-rajendran]

What this changes

Rewrites the README to the org-wide landing-page order: hero demo GIF first, honest
capability table before the pitch copy, a 16-row Supported agents table with a Verified
column, and a one-sentence live-run-vs-doc-derived count. Adds docs/assets/demo.tape +
rendered demo.gif, a manual render-demo workflow, and a quickstart CI job that runs
the README's own Quick start block for real. Moves the Bundles, Design and per-vendor
example-page-generator sections to docs/ verbatim. One CHANGELOG [Unreleased] entry;
no version bump.

No agent is graded enforced at pre_tool on main today (11 best-effort, 1
enforceable/Cursor, 4 none), so the GIF's end frame and the README's install-output
example show those real levels rather than the enforced claim the original owner brief
assumed — see Deviations below.

Claim check

Not applicable — no adapter or MATRIX changes; this PR only reorganizes and re-verifies
existing claims already backed by data/matrix.json.

Checks

• pytest -q passes (1598 passed / 4 skipped on Python 3.11; 1595 passed / 7 skipped
  on Python 3.10) — includes the README-consistency tests
  (test_repo_standards.py::test_the_front_door_docs_name_every_decision_outcome,
  test_instructions.py::test_the_readme_arithmetic_cannot_drift)
• ruff check . and ruff format --check . pass
• Runtime path is still stdlib-only (tests/check_stdlib_only.py on 3.10 and 3.11)
• Commits are signed off (git commit -s)
• examples/generate.py --check passes (unaffected — no adapter/matrix changes)
• quickstart CI job: verified locally by extracting and running the README's real
  Quick start block end-to-end (wires 12 agents, exit 0), then deliberately breaking
  it (--nonexistent-flag) and confirming the same extraction exits 2 before
  reverting

Evidence gathered before writing

• agentseam matrix --evidence: of the 12 agents that claim pre_tool at all, 4
  (claude_code, codex_cli, cursor, vscode_copilot) rest on a live run; the other 8 rest on
  documentation or a third-party install, not on a live run.
• agentseam install all "python3 my_handler.py" --events pre_tool --repo .: wires 12
  agents, all best-effort except Cursor (enforceable); aider, copilot, replit, zed are
  skipped (no hook surface) — matches the brief's stated breakdown exactly.
• GIF: 184,795 bytes / 0.18 MB (budget 2.5 MB), last frame is the real install-output
  punchline.
• README word count excluding tables/code: 1,231 (target 1,200–1,600).

Deviations from the brief

• The Supported agents table now has a genuine 16th row for copilot (the GitHub Copilot
  CLI marketplace-bundle identity), which the prior README omitted entirely. Its own
  vendor notes say this is a packaging identity dispatched through the vscode_copilot
  adapter at runtime, not an independent hook surface — labelled accordingly rather than
  as a plain "no hook surface" row.
• tests/test_repo_standards.py::test_the_front_door_docs_name_every_decision_outcome
  requires README.md itself to name every Decision outcome in backticks. The sentence
  that did this previously lived in the "per-vendor examples" section the brief asks to
  move to docs/ verbatim, so a short equivalent sentence naming all eight outcomes
  (allow, deny, escalate/ask, transform/rewrite, warn, vouch) was added to
  the front-matter paragraph instead — per CONTRIBUTING.md/worker-protocol: fix the
  README, never the test.
• Junie/Kimi Code's install paths in the GIF and Quick start read under a fresh
  $(mktemp -d) $HOME (e.g. /tmp/tmp.XXXXXX/.junie/config.json) rather than a
  committed literal path, per the brief's own instruction to avoid a container-identifying
  path — this is a generic, non-identifying temp path, regenerated on every render. See
  the orchestrator-review response below for why this is not further reducible.

Orchestrator review response (2026-09-08)

Three findings verified and fixed:

• Tape's install command was missing --repo . that the README's quick-start block has —
  added, re-rendered the GIF.
• Contributing had no good-first-issue link — added.
• "8 rest on vendor documentation alone" overstated it (gemini_cli is vendor-source,
  windsurf is third-party-install) — reworded.

One finding investigated and not applied: the suggested fix for junie/kimi_code's absolute
/tmp/... path (export HOME="$PWD") does not do what was claimed. Tested it directly —
it still prints an absolute path, just under the demo dir instead of a separate temp dir —
because install_config.resolve() expands a ~-prefixed CONFIG_PATH with
os.path.expanduser and never relativizes it against repo_root for any HOME value.
Making these two rows read ./... needs an adapter/resolve() code change, out of scope
for a docs-only PR. Left HOME=$(mktemp -d) as originally written, which matches the
shared standard's own prescribed fix ("set HOME to a temp dir in the hidden setup") and
prints a fresh, non-identifying path on every render.

Notes for the reviewer

docs/render-demo.yml's SHA pins were copied verbatim from open-coder-ai/chock's
existing workflow of the same name, per the shared README-refresh standard.

🤖 Generated with Claude Code