Lead the README with security guards and an honest pre_tool block matrix

[jothimani-rajendran]

What this changes

README only. It now presents agentseam as the layer that lets you write one security guard (deny / escalate / transform at pre_tool) and install it into 16 agents. It also says plainly where that guard can and cannot block.

• New header line, plus three static badges in the brand colours (16 agents, 192 capability cells, stdlib-only runtime). The existing demo GIF is still the hero image.
• The intro now opens with the risk: an agent has a shell, git history and credentials, and a rule in its prompt is forgotten when the context fills.
• New section What you can build: security guards first:
  • What each Decision does, and what it degrades to on an agent that cannot express it (the AWS-key Quick start handler is the example).
  • A table of where a guard can block at pre_tool, from matrix.enforcement_level(): enforced 0, enforceable 1 (Cursor), best-effort 11, detect 0 (55 cells at other events), none 4.
  • A short part on the chock security catalog built on top: 48 policies, 19 enforced at commit / 9 in-agent / 20 advisory, 1,179 eval cases. It links to chock-catalog areas.
• "What it is for" is renamed "Beyond security guards", with Guardrails listed first.
• Contributing:
  • New first-contribution table.
  • New subsection "Turning a vendor-docs row into a live-run row", which points to tools/VERIFY.md.
  • New subsection "Adding an agent adapter", with the 3 steps from AGENTS.md.
• Family table: the chock-catalog row went from 39 to 48 policies.

Claim check

• No capability claim is widened without a mechanism behind it. Every grade in the new table was read from matrix.enforcement_level(agent, "pre_tool").
• Any new/changed MATRIX row carries a verified record: n/a, no matrix change
• Payload shapes: n/a

Checks

• pytest -q passes (1894 passed, 4 skipped)
• ruff check . and ruff format --check . pass
• Runtime path is still stdlib-only (README only)
• Commits are signed off (git commit -s)
• The Quick start block is unchanged. tools/quickstart_block.py output still matches docs/quickstart.sh (the same diff as the quickstart.yml step), and the block was run end to end.

Notes for the reviewer

The catalog numbers (48 / 19 / 9 / 20 / 1,179 / 1,019) come from chock-catalog registry.yaml for framework v0.15.0. If the catalog changes they will go out of date, because no test in this repo pins them.

🤖 Generated with Claude Code

https://claude.ai/code/session_01LAxde3s5KW8N36kS8LF3er

---

Generated by Claude Code

[jothimani-rajendran]

Closing at the owner's request (2026-10-05). The README refresh will be redone once before launch.

---

Generated by Claude Code