docs: add AGENTS.md and agent discoverability layer

AGENTS.md

@@ -0,0 +1,88 @@
+# AGENTS.md: capsule
+
+Capsule Protocol Specification (CPS) plus reference implementations. Open source, Apache 2.0 with patent grant. **The spec in `spec/` is the source of truth, not any single implementation.**
+
+## Stack
+
+- **Spec:** `spec/` plus `conformance/` (16 valid + 15 negative golden vectors). Language-agnostic.
+- **Python reference:** `reference/python/` publishes `qp-capsule` on PyPI. Python 3.11+, pynacl, hatchling.
+- **TypeScript reference:** `reference/typescript/` publishes `@quantumpipes/capsule` on npm. TypeScript 5.9+ strict, Node 20.19+, ESM-only.
+- **Ecosystem libraries** (not in this repo): capsule-go, capsule-litellm.
+
+## Commands
+
+Python (always `cd reference/python` first):
+```bash
+make install      # pip install -e ".[storage,dev]"
+make lint         # ruff check src/ tests/
+make typecheck    # mypy src/qp_capsule/ (strict)
+make test         # pytest, 100% coverage enforced (--cov-fail-under=100)
+make test-golden  # golden conformance vectors only
+make test-all     # lint + typecheck + test + golden
+```
+
+TypeScript (always `cd reference/typescript` first):
+```bash
+npm ci
+npm run lint         # tsc --noEmit
+npm test             # vitest run
+npm run conformance  # golden fixtures only
+```
+
+## Structure
+
+```
+spec/                  CPS v1.0 specification, URI scheme, VERSION
+conformance/           golden vectors every implementation must pass
+reference/python/      qp-capsule (src/, tests/, Makefile, pyproject.toml)
+reference/typescript/  @quantumpipes/capsule (src/, tests/, package.json)
+docs/                  architecture, security, 11 compliance mappings
+examples/              language-agnostic example Capsules
+nist-submission/       NIST materials
+```
+
+## Style
+
+- **No em dashes** anywhere in code, commits, or docs. Use commas, periods, colons, parentheses.
+- Python: type hints on all public functions, async where I/O happens, mypy strict, filterwarnings = ["error"] (any new warning fails CI).
+- TypeScript: strict mode, ESM-only (`.js` extensions in imports).
+- **Crypto allowlist:** SHA3-256 (FIPS 202), Ed25519 (FIPS 186-5), ML-DSA-65 (FIPS 204), AES-256-GCM (FIPS 197). **Never** MD5, SHA1, SHA2, RSA, ECDSA-P256, 3DES, RC4.
+
+Canonical seal (Python):
+```python
+from qp_capsule import Capsule, Seal, CapsuleType, TriggerSection
+c = Capsule(type=CapsuleType.AGENT, trigger=TriggerSection(source="bot", request="deploy"))
+seal = Seal(); seal.seal(c); assert seal.verify(c)
+```
+
+## Git workflow
+
+- Conventional commits with scope: `feat(spec): ...`, `fix(python): ...`, `docs(compliance): ...`.
+- **Never** include `Co-Authored-By`, `Generated by`, or any AI attribution.
+- Protocol changes to `spec/` go through the CPS change proposal process (rare, requires spec-change issue plus updated golden vectors in the same PR).
+- Implementation PRs must keep every golden vector green in every reference language.
+
+## Boundaries
+
+**Always:**
+- Run `make test-all` (or `npm test`) in the affected reference before committing.
+- Keep `canonicalize()` byte-identical across languages for the same input.
+- Update `conformance/` vectors together with any spec change, same commit.
+
+**Ask first:**
+- Any change to `spec/` (the protocol itself).
+- Adding a dependency to a reference implementation.
+- Adding a new reference language (open a new-implementation issue first).
+
+**Never:**
+- Break the 16 golden vectors. Regenerate only via `make golden-regenerate` after an approved spec change.
+- Introduce deprecated cryptography (see Style).
+- Add runtime network dependencies. Air-gap compatibility is a protocol invariant.
+- Change `to_dict()` or `canonicalize()` output in one implementation without matching changes in the others.
+
+## Related
+
+- Contributors: [CONTRIBUTING.md](./CONTRIBUTING.md)
+- Security policy: [SECURITY.md](./SECURITY.md)
+- Patent grant: [PATENTS.md](./PATENTS.md)
+- Compliance mappings: [docs/compliance/](./docs/compliance/)

README.md

@@ -11,9 +11,12 @@ Every AI action produces a Capsule — a tamper-evident, content-addressable rec
 [![Conformance](https://img.shields.io/badge/Conformance-16_vectors-ff69b4.svg)](./conformance/)
 [![FIPS](https://img.shields.io/badge/Crypto-FIPS_202%20·%20186--5%20·%20204-purple.svg)](#cryptographic-seal)
 [![Coverage](https://img.shields.io/badge/Coverage-100%25-brightgreen.svg)](./reference/python/)
+[![AI Agents](https://img.shields.io/badge/AI%20Agents-AGENTS.md-blueviolet.svg)](./AGENTS.md)
 
 </div>
 
+> **AI coding agents:** start with [AGENTS.md](./AGENTS.md). It contains build and test commands, project structure, code style, crypto allowlist, and the guardrails that keep the protocol intact.
+
 ---
 
 ## The Protocol
@@ -188,6 +191,20 @@ See more examples in [`examples/`](./examples/).
 
 ---
 
+## Explore the fit with your AI coding agent
+
+Paste this prompt into Claude Code, Cursor, Codex, or any other agent:
+
+```text
+Read the Capsule Protocol README and AGENTS.md at https://github.com/quantumpipes/capsule.
+Then survey my codebase for every place an AI agent takes autonomous action (tool calls,
+LLM completions, scheduled jobs, deploy triggers) and currently lacks a tamper-evident
+audit trail. For each, explain what a capsule would record. Recommend the single
+highest-leverage place to start, with concrete files and functions to change.
+```
+
+---
+
 ## Implementations
 
 ### Reference Implementations