Write documentation #29
Description
Summary
Complete all documentation files with real content.
Files
README.md
- 30-second elevator pitch
- Problem statement (1000+ tools, context blowup)
- Solution overview (Kernel + Capability Tokens + Firewall)
- Architecture diagram (Mermaid)
- Quickstart: pip install + 10-line code example (must work — match actual API)
- Security disclaimers
docs/architecture.md
- Component diagram (Mermaid)
- Data flow: request → grant → invoke → expand
- Each component's responsibility (registry, policy, tokens, router, drivers, firewall, handles, trace)
docs/security.md
- Threat model: confused deputy, token replay, privilege escalation
- How the library addresses each (token binding, HMAC signatures, policy rules)
- Disclaimers: "v0.1 tokens are tamper-evident but not encrypted"
docs/integrations.md
- How to implement a custom Driver
- How to map MCP tools to capabilities
- How to map A2A agents to capabilities
docs/capabilities.md
- Naming conventions (namespaced, task-shaped)
- Designing good capabilities vs capability explosion
- Safety class and sensitivity tag guidelines
docs/context_firewall.md
- Why raw output is dangerous
- Budgets, response modes, frames, handles
- Redaction rules
- Expand query patterns
AGENTS.md
- Repo purpose (1 paragraph)
- Module map (file → responsibility)
- Commands: make fmt, make lint, make type, make test, make example
- How to add a new capability
- How to add a new driver
Acceptance criteria
- Each doc file has >= 200 words of real content
- README quickstart code snippet matches actual API
- Mermaid diagrams render correctly
- AGENTS.md has all sections