docs: rewrite README with Claude Code skill, hierarchical scopes, audit trail

dreynow · claude · dreynow · commit 8ad1a5af4be0 · 2026-03-22T21:54:42.000Z
Lead with the skill (the distribution unlock), not the library.
Added: named agents, hierarchical scopes, git pre-push hook,
exec wrapper, audit trail. Removed: Observatory, interop matrix,
competitive table, architecture diagram (moved to docs site).

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/README.md b/README.md
@@ -2,9 +2,7 @@
 
 **Your AI agents currently have keys. We give them math instead.**
 
-AI agents are being given SSH keys and API tokens like it's 1999. Kanoniv agent-auth replaces long-lived credentials with cryptographic delegation tokens that are scope-confined, time-bounded, and fully auditable.
-
-```python
+```bash
 pip install kanoniv-auth
 ```
 
@@ -19,206 +17,122 @@ verify(action="deploy.prod", token=token)     # raises ScopeViolation
 
 That second line doesn't just fail. It **cannot** succeed. Not policy-blocked, not RBAC-blocked - cryptographically impossible without the root key.
 
-## Why This Exists
-
-A typical AI-assisted deploy flow today:
-
-1. Developer tells Copilot/Devin/Claude to "fix the bug and deploy it"
-2. The agent gets a long-lived API token with broad permissions
-3. It pushes code, triggers the pipeline, maybe touches infra
-4. Nobody has a clean audit trail of what the agent decided vs what the human approved
+## Claude Code Skill
 
-The "solution" most teams have is vibes. A slightly restricted token and hope.
-
-## What This Solves
-
-| Problem | How kanoniv-auth solves it |
-|---------|---------------------------|
-| Agents have broad permissions | Scope confinement - `deploy.staging` cannot touch prod |
-| Leaked tokens are valid forever | `expires_at` - hard ceiling, default 4h |
-| No audit trail for agent actions | Every action is signed with its delegation chain |
-| Agents can't delegate to sub-agents safely | Delegation chains only narrow, never widen |
-
-## The Demo Workflow
+Scope-enforce your AI coding agent in one command:
 
+```bash
+kanoniv-auth install-skill
 ```
-Human engineer
-    |-- signs delegation token
-          scopes: ["build", "test", "deploy.staging"]
-          ttl: 4h
 
-    Pipeline Orchestrator Agent (receives token)
-          |-- sub-delegates to Deploy Agent
-                scopes: ["deploy.staging"]  (can only narrow, never widen)
+Then in Claude Code:
 
-    Deploy Agent executes
-          |-- signs execution envelope
-                action: deploy, target: staging
-                delegation_proof: <full chain>
-                result: success
-
-    Audit log = execution envelope hash
-    (verifiable without trusting any single system)
+```
+/delegate
+> What should Claude Code be allowed to do?
+> A) Full dev - code.edit, test.run, git.commit, git.push
 ```
 
-The prod environment never trusts the agent directly. It only verifies the math on the token chain.
-
-## CLI
-
-```bash
-# Install
-cargo install kanoniv-agent-auth --features cli
+Every tool call is now verified. If Claude tries to exceed its scope:
 
-# Generate root key (treat like an SSH key)
-kanoniv-auth init
+```
+SCOPE DENIED: requires git.push
 
-# Issue a delegation token
-kanoniv-auth delegate --scopes deploy.staging,build --ttl 4h
-# outputs: eyJhZ2VudF9kaWQ...
+  You have:  ["code.edit", "test.run"]
+  You need:  ["git.push"]
+```
 
-# Agent verifies it has authority
-kanoniv-auth verify --scope deploy.staging --token $KANONIV_TOKEN
-# VERIFIED
-#   Agent:   did:agent:b15b9019...
-#   Scopes:  ["deploy.staging", "build"]
-#   Expires: 3h47m remaining
+The command never runs. Type `/audit` to see every action the agent took. Type `/status` to check the current delegation.
 
-# Agent tries to touch prod
-kanoniv-auth verify --scope deploy.prod --token $KANONIV_TOKEN
-# error: DENIED: scope "deploy.prod" not in delegation
-#
-#   You have:  [deploy.staging, build]
-#   You need:  ["deploy.prod"]
+## Named Agents
 
-# Agent signs an execution envelope (audit trail)
-kanoniv-auth sign --action deploy --target staging --token $KANONIV_TOKEN
+Agents keep the same identity across sessions:
 
-# Inspect any token or envelope
-kanoniv-auth whoami --token $KANONIV_TOKEN
-kanoniv-auth audit <envelope>
+```bash
+kanoniv-auth delegate --name claude-code --scopes code.edit,test.run --ttl 4h
+kanoniv-auth delegate --name deploy-bot --scopes deploy.staging --ttl 1h
 ```
 
-## Python API
+Same name = same DID every time. Your audit trail shows a consistent history.
 
-```python
-from kanoniv_auth import delegate, verify, sign, init_root, load_root
-
-# Generate root key (once)
-root = init_root("~/.kanoniv/root.key")
-
-# Issue delegation
-token = delegate(
-    scopes=["deploy.staging", "build"],
-    ttl="4h",
-)
+## Hierarchical Scopes
 
-# Verify (agent-side)
-result = verify(action="deploy.staging", token=token)
-# {"valid": True, "scopes": [...], "ttl_remaining": 14380.0, ...}
+Scopes are dot-separated and hierarchical:
 
-# Sub-delegate (narrowing only)
-sub_token = delegate(
-    scopes=["deploy.staging"],
-    ttl="1h",
-    parent_token=token,
-)
-
-# Sign execution (audit trail)
-envelope = sign(
-    action="deploy",
-    token=token,
-    target="staging",
-    result="success",
-    metadata={"commit": "abc123"},
-)
+```
+git.push                          # any repo, any branch
+git.push.agent-auth               # agent-auth only
+git.push.agent-auth.main          # agent-auth main only
 ```
 
-### Error Handling
+`git.push` grants everything below it. `git.push.agent-auth.main` grants only that specific repo and branch.
 
-Every error tells you what happened and how to fix it:
+## Git Pre-Push Hook
 
-```python
-try:
-    verify(action="deploy.prod", token=token)
-except ScopeViolation as e:
-    print(e)
-    # DENIED: scope "deploy.prod" not in delegation
-    #
-    #   You have:  ["deploy.staging"]
-    #   You need:  ["deploy.prod"]
-    #
-    #   To request escalation:
-    #     kanoniv-auth request-scope --scope deploy.prod --from did:agent:abc...
+Invisible enforcement at the git level:
+
+```bash
+kanoniv-auth install-hook
 ```
 
-## How It Works
+Now `git push` verifies `git.push.{repo}.{branch}` scope before allowing the push. No wrapper needed - just push as normal.
 
-**Ed25519 signatures.** Every delegation is a signed message from the delegator to the delegate. The chain is self-contained - verification requires no network call, no database lookup, no trust in any third party.
+## Exec Wrapper
 
-**Scope narrowing.** A delegation can only grant a subset of the parent's scopes. Root grants `[build, test, deploy.staging]`. Sub-delegation can grant `[deploy.staging]` but cannot add `deploy.prod`. This is enforced by the math, not by policy.
+Verify, run, sign in one command:
 
-**Token format.** Base64-encoded JSON containing the delegation chain, agent DID, scopes, and expiry. Each link in the chain includes the issuer's public key and signature. Self-contained, verifiable offline.
+```bash
+kanoniv-auth exec --scope deploy.staging -- ./deploy.sh staging
+```
 
-## Competitive Landscape
+If the scope check fails, the command never runs. If it succeeds, the result is signed for the audit trail.
 
-| Feature | Vault | OPA | GH OIDC | AWS IAM | kanoniv-auth |
-|---------|-------|-----|---------|---------|-------------|
-| Secret management | Y | N | N | Y | N |
-| Policy engine | N | Y | N | Y | N |
-| Agent-specific delegation | N | N | N | N | **Y** |
-| Scope narrowing chains | N | N | N | N | **Y** |
-| Cryptographic audit trail | N | N | N | N | **Y** |
-| Short-lived tokens | Y | N | Y | Y | **Y** |
-| Offline verification | Y | N | N | N | **Y** |
-| MCP auth | N | N | N | N | **Y** |
+## Audit Trail
 
-None of them have "agent delegates to sub-agent with attenuated scope." That's the gap.
+Every delegate, verify, sign, and exec is auto-logged:
 
-## Architecture
+```bash
+kanoniv-auth audit-log --agent claude-code
+```
 
 ```
-Developer (root key)
-  |
-  +-- Python CLI (pip install kanoniv-auth)
-  +-- Rust CLI (cargo install kanoniv-agent-auth --features cli)
-  +-- GitHub Action (kanoniv/auth-action@v1)
-  |
-  delegate / verify / sign
-  |
-  +-- OFFLINE: local Ed25519 verify (no network)
-  +-- SERVICE: kanoniv-auth serve (Axum + SQLite)
-  +-- CLOUD: api.kanoniv.com (Postgres, revocation webhooks)
+19:15:03  claude-code  tool:bash   git commit -m "feat: ..."     ok
+19:15:05  claude-code  tool:bash   cargo test --lib               ok
+19:15:08  claude-code  tool:edit   src/lib.rs                     ok
+19:15:12  claude-code  tool:bash   git push origin main           DENIED
 ```
 
-## Packages
+## How It Works
 
-| Package | Registry | Install |
-|---------|----------|---------|
-| `kanoniv-agent-auth` | crates.io | `cargo install kanoniv-agent-auth --features cli` |
-| `kanoniv-auth` | PyPI | `pip install kanoniv-auth` |
-| `@kanoniv/agent-auth` | npm | `npm install @kanoniv/agent-auth` |
+**Ed25519 signatures.** Every delegation is a signed message. The chain is self-contained - verification requires no network call, no database, no trust in any third party.
 
-## Agent Trust Observatory
+**Scope narrowing.** Delegations can only narrow, never widen. Root grants `[build, test, deploy.staging]`. Sub-delegation can grant `[deploy.staging]` but cannot add `deploy.prod`. Enforced by the math, not by policy.
 
-For teams that want a visual dashboard: [trust.kanoniv.com](https://trust.kanoniv.com)
+**Offline verification.** Base64-encoded JSON tokens containing the delegation chain, agent DID, scopes, and expiry. Each chain link includes the issuer's public key and signature. Verifiable anywhere.
 
-The Observatory shows agent reputation, delegation chains, provenance audit trails, and cross-engine interop verification. Docker Compose for self-hosting:
+## Install
 
 ```bash
-cd apps/observatory && docker compose up
+pip install kanoniv-auth                              # Python SDK + CLI
+kanoniv-auth install-skill                            # Claude Code skills
+kanoniv-auth install-hook                             # Git pre-push enforcement
 ```
 
-## Cross-Engine Interop
+Or with Rust:
+
+```bash
+cargo install kanoniv-agent-auth --features cli       # Rust CLI
+```
 
-Three independent agent systems have cross-verified each other's delegation chains on this repo:
+## Docs
 
-| Verifier / Chain | Kanoniv | APS | AIP |
-|---|---|---|---|
-| Kanoniv | -- | verified | verified |
-| APS | verified | -- | verified |
-| AIP | verified | verified | -- |
+Full documentation at [auth.kanoniv.com](https://auth.kanoniv.com):
 
-See [spec/CROSS-ENGINE-VERIFICATION.md](spec/CROSS-ENGINE-VERIFICATION.md) and [interop thread](https://github.com/kanoniv/agent-auth/issues/2).
+- [Getting Started](https://auth.kanoniv.com/guide/getting-started)
+- [Claude Code Skill](https://auth.kanoniv.com/guide/claude-code-skill)
+- [CLI Reference](https://auth.kanoniv.com/reference/cli)
+- [Python API](https://auth.kanoniv.com/reference/python-api)
+- [Token Format Spec](https://auth.kanoniv.com/reference/token-format)
 
 ## License
 
