Skip to content

Agent Mesh

update docs

Antonio Ojea9a2e7a238af0
diff --git a/README.md b/README.md
index a8a03573..a71e6eb8 100644
--- a/README.md
+++ b/README.md
@@ -1,88 +1,73 @@
# SAM: Sovereign Agent Mesh
-SAM is a zero-trust, pure P2P networking layer for autonomous agents.
+SAM is a minimal libp2p-based mesh with two binaries:
-It is built for environments where centralized gateways and centralized trust are a liability. Agents discover each other over libp2p DHT, authenticate with passport biscuits, authorize capabilities with Biscuit caveats, and communicate directly over A2A streams.
+- `sam-hub`: OIDC bridge + Biscuit issuer + connection gater
+- `sam-node`: node identity/login flow + mesh node runtime
-## Why SAM
+The current repository intentionally focuses on basic functionality and testability.
-- Pure P2P: no API gateway in the data path
-- Zero-trust by default: every call is authenticated and authorized
-- Isolated mesh namespace: separate SAM protocol space and storage scope
-- Auditability: inspect tokens/cards and dry-run key flows
-
-## Quick Start
-
-### Build
+## Build
```bash
make build
-./bin/sam-agent --help
+./bin/sam-node --help
./bin/sam-hub --help
```
-### Run tests
+## Basic Usage
+
+### 1. Run the hub
```bash
-make test
-make test-e2e
+SAM_OIDC_ISSUER=https://issuer.example.com \
+SAM_OIDC_ID=sam-client \
+SAM_OIDC_SECRET=sam-secret \
+SAM_HUB_KEY=$(openssl rand -hex 32) \
+./bin/sam-hub
```
-### First workflow
+### 2. Login a node
```bash
-# Authenticate
-sam-agent identity login --hub https://identity.example.com
+./bin/sam-node login --hub http://localhost:8080
+```
-# Publish an agent capability
-sam-agent publish --skill risk-audit --mcp-port 8080
+This prints a login URL. After authenticating in browser, paste the returned biscuit token back into the CLI prompt.
-# Call by capability
-sam-agent call risk-audit --message "audit this report"
+### 3. Run a node
-# Inspect credential artifacts
-sam-agent inspect biscuit "vendor-bot;allow_skill=risk-audit"
+```bash
+./bin/sam-node run
```
-## Documentation
+Or pass a token directly:
-- Docs site: https://aojea.github.io/sam
-- Manifesto: https://aojea.github.io/sam/#/README.md
-- User journey (dark mesh): https://aojea.github.io/sam/#/guides/dark-mesh.md
-- Hub as rendezvous point: https://aojea.github.io/sam/#/guides/hub-rendezvous.md
-- CLI reference: https://aojea.github.io/sam/#/cli/reference.md
-- Testing guide: https://aojea.github.io/sam/#/testing.md
-
-## Architecture
-
-SAM keeps control at the edge: discovery is federated, trust is verified locally, and execution stays peer-to-peer.
-
-```mermaid
-flowchart LR
- A[Agent A / Caller] -->|Discover capability| DHT[(Federated DHT\n/sam/fed/<id>)]
- DHT -->|Peer candidates| A
- A -->|A2A stream + Vouch + Biscuit| B[Agent B / Callee]
- B -->|Federation Gate\nverify vouch + peer identity| G[AuthZ Layer]
- G -->|BiscuitSkillGate\nallow_skill(c)| E[MCP Resource / Skill]
- E -->|Result| B
- B -->|A2A response| A
+```bash
+./bin/sam-node run --token <identity-biscuit>
```
-Trust flow summary:
+## Testing
-- Discovery: agents find peers by capability in an isolated federation namespace.
-- Authentication: callee verifies caller identity with a locally trusted vouch.
-- Authorization: Biscuit caveats constrain which capability can be executed.
-- Execution: skill runs locally through the agent backend (JSON-RPC) and the response returns over A2A.
+```bash
+make test
+make test-e2e
+make test-e2e-container
+```
+
+`test-e2e-container` runs a containerized BATS framework that starts:
-## Development
+- a mock OIDC container
+- a `sam-hub` container
+- multiple `sam-node` containers
-Key make targets:
+## Documentation
-- `make build`
-- `make test`
-- `make test-e2e`
-- `make lint`
+- Docs index: `docs/index.html`
+- Project docs landing page: `docs/README.md`
+- Quickstart: `docs/quickstart.md`
+- CLI reference: `docs/cli/reference.md`
+- Testing guide: `docs/testing.md`
## License
diff --git a/docs/DOCUMENTATION.md b/docs/DOCUMENTATION.md
deleted file mode 100644
index 0e361ed3..00000000
--- a/docs/DOCUMENTATION.md
+++ /dev/null
@@ -1,354 +0,0 @@
-# SAM Documentation - Complete Inventory
-
-## πŸ“‹ Documentation Structure
-
-Generated comprehensive Docsify documentation for Sovereign Agent Mesh (SAM).
-
-### Root Level (`docs/`)
-
-```
-docs/
-β”œβ”€β”€ index.html ⚑ Docsify configuration + plugins
-β”œβ”€β”€ _coverpage.md 🎨 Landing page with SAM pitch
-β”œβ”€β”€ _sidebar.md πŸ“‘ Navigation sidebar
-β”œβ”€β”€ README.md πŸ“˜ Main manifesto (Trust Desert problem)
-β”œβ”€β”€ quickstart.md ⚑ 5-minute quick start
-β”œβ”€β”€ faq.md ❓ Frequently asked questions
-β”œβ”€β”€ glossary.md πŸ“– Terminology reference
-β”œβ”€β”€ testing.md πŸ§ͺ Testing guide (BATS, Go, integration)
-β”œβ”€β”€ contributing.md 🀝 Contributor's guide
-```
-
-### Guides (`docs/guides/`)
-
-```
-guides/
-β”œβ”€β”€ dark-mesh.md πŸ” Enterprise dark mesh walkthrough
-β”‚ - Scenario: Acme Corp with 3 business units
-β”‚ - Full CLI snippets for federation setup
-β”‚ - Step-by-step: create federation β†’ login β†’ publish β†’ call β†’ audit
-β”‚ - Explains Biscuit tokens, federation isolation, transparency
-```
-
-### CLI Reference (`docs/cli/`)
-
-```
-cli/
-β”œβ”€β”€ reference.md πŸ–₯️ Complete kubectl-style command hierarchy
-β”‚ - sam identity (login, whoami)
-β”‚ - sam publish (quick, card, mcp)
-β”‚ - sam call (with Biscuit auth)
-β”‚ - sam inspect (biscuit, card)
-β”‚ - sam mesh (federations, agents)
-β”‚ - sam up (persistent node)
-β”‚ - Global flags and dry-run philosophy
-β”‚ - Patterns and best practices
-```
-
-### Concepts (`docs/concepts/`)
-
-```
-concepts/
-β”œβ”€β”€ federation.md 🏒 Federation & storage deep dive
-β”‚ - Physical isolation via bbolt per federation
-β”‚ - Why no central database (honeypot problem)
-β”‚ - Federation initialization and vouch system
-β”‚ - Disaster recovery
-β”‚
-β”œβ”€β”€ identity.md πŸ”‘ Identity & vouch system
-β”‚ - Vouch-based identity (works offline)
-β”‚ - Why this solves central authority problem
-β”‚ - Vouch vs Token vs Signature
-β”‚ - Multi-federation identity
-β”‚ - PeerID derivation (deterministic)
-β”‚
-β”œβ”€β”€ biscuit.md 🎫 Biscuit authorization
-β”‚ - Plain-text Biscuits (why not cryptographic)
-β”‚ - Authorization flow
-β”‚ - Parsing and skill gates
-β”‚ - A2A stream handling
-β”‚ - Use cases and inspection
-β”‚
-β”œβ”€β”€ a2a-protocol.md πŸ”Œ Agent-to-Agent protocol
-β”‚ - Connection setup and message structure
-β”‚ - Authentication (vouch) + Authorization (Biscuit)
-β”‚ - Error codes and stream lifecycle
-β”‚ - Network considerations
-β”‚ - Code examples for server and client
-```
-
----
-
-## πŸ“Š Documentation Breakdown
-
-### Page Counts & Content
-
-| Document | Lines | Focus |
-|----------|-------|-------|
-| README.md (Manifesto) | 250+ | Philosophy, problem statement, architecture overview |
-| dark-mesh.md (User Guide) | 400+ | Step-by-step scenario walkthrough with CLI examples |
-| cli/reference.md | 350+ | Complete command documentation |
-| federation.md (Concepts) | 350+ | Storage architecture, bbolt, multi-tenant design |
-| identity.md (Concepts) | 300+ | Cryptographic identity, vouch, decentralization |
-| biscuit.md (Concepts) | 300+ | Skill-based authorization, caveats, enforcement |
-| a2a-protocol.md (Concepts) | 300+ | Protocol details, authentication, code examples |
-| testing.md (Testing) | 250+ | Unit/integration/E2E testing guide |
-| contributing.md (Contributing) | 250+ | Development setup, code style, submission workflow |
-| faq.md (FAQ) | 200+ | 30+ common questions answered |
-| glossary.md (Glossary) | 150+ | 50+ terms + acronyms |
-| quickstart.md (Quick Ref) | 100+ | 5-minute reference card |
-
-**Total Documentation**: ~3,500+ lines of comprehensive, reader-friendly content
-
----
-
-## 🎯 Key Features
-
-### 1. **Docsify Setup** (index.html)
-- βœ… Dark mode theme (Sovereign look)
-- βœ… Search plugin for full-text search
-- βœ… Sidebar navigation auto-generated from _sidebar.md
-- βœ… Copy-to-clipboard buttons on all code blocks
-- βœ… Footer with license and copyright
-- βœ… Responsive design (mobile + desktop)
-- βœ… Syntax highlighting (Bash, Go, JSON)
-
-### 2. **Cover Page** (_coverpage.md)
-- βœ… Eye-catching logo (⚑ emoji)
-- βœ… Tagline: "Zero-Trust Networking for the Agentic Era"
-- βœ… Key value props (Pure P2P, Zero-Trust, Federation-Ready, Audit-First)
-- βœ… Problem statement (Trust Desert)
-- βœ… Links to documentation and GitHub
-
-### 3. **Manifesto** (README.md)
-- βœ… Core philosophy: "Sovereign" agents, "Engineering Truth"
-- βœ… The Trust Desert problem (gateways, IdP, audit)
-- βœ… How SAM solves it (Pure P2P, Zero-Trust, Passport auth, Audit)
-- βœ… Architecture overview with data flow diagrams
-- βœ… Why "Sovereign"
-- βœ… What SAM does NOT do (blockchain, sidecar, etc.)
-
-### 4. **User Journey** (dark-mesh.md)
-- βœ… Real-world scenario (Acme Corp with 3 business units)
-- βœ… 9 step-by-step sections with CLI snippets
-- βœ… Shows mesh namespace scoping
-- βœ… Explains identity gating (passport verification)
-- βœ… Demonstrates Biscuit tokens (skill restrictions)
-- βœ… Audit transparency (sam inspect commands)
-- βœ… Trust flow diagram
-
-### 5. **CLI Reference** (cli/reference.md)
-- βœ… kubectl-style command hierarchy
-- βœ… Global node/runtime flags and command-specific options
-- βœ… All commands documented (identity, publish, call, inspect, mesh, up)
-- βœ… Flags and examples for each command
-- βœ… Dry-run philosophy explained
-- βœ… Patterns and best practices
-- βœ… Output formats (JSON + text)
-
-### 6. **Technical Concepts** (concepts/)
-- βœ… Mesh storage: bbolt architecture and default namespace behavior
-- βœ… Identity: passport biscuit system
-- βœ… Biscuit: authorization model, skill gating, enforcement
-- βœ… A2A Protocol: message structure, authentication flow, code examples
-
-### 7. **Testing Guide** (testing.md)
-- βœ… Three-level testing: unit, integration, E2E
-- βœ… BATS syntax and examples
-- βœ… Linux namespace isolation (CLONE_NEWNET)
-- βœ… Test framework helpers
-- βœ… Running test suite locally
-- βœ… Performance testing (benchmarks)
-- βœ… Debugging techniques
-
-### 8. **Contributing** (contributing.md)
-- βœ… Development setup (prerequisites, clone, build)
-- βœ… Code style (Go conventions, file organization)
-- βœ… Testing requirements
-- βœ… Commit message format
-- βœ… PR workflow
-- βœ… Common tasks (new CLI command, new protocol feature)
-- βœ… Code review checklist
-
-### 9. **FAQ** (faq.md)
-- βœ… 30+ questions organized by category
-- βœ… Getting started (install, publish, call)
-- βœ… Core concepts (mesh namespace, passport, Biscuit, A2A)
-- βœ… Architecture & design (why P2P, why not OAuth)
-- βœ… Network & connectivity (NAT, firewall, cloud)
-- βœ… Security & trust (production readiness, key management)
-- βœ… Performance (scalability, latency)
-- βœ… Operations & troubleshooting
-- βœ… Integration (libraries, Docker)
-- βœ… Roadmap & future work
-
-### 10. **Glossary** (glossary.md)
-- βœ… 50+ terms (A-Z)
-- βœ… Clear, concise definitions
-- βœ… Acronym quick reference
-- βœ… Cross-references to related concepts
-
-### 11. **Quick Start** (quickstart.md)
-- βœ… 5-minute setup
-- βœ… Common commands cheat sheet
-- βœ… File locations
-- βœ… Troubleshooting table
-- βœ… Key concepts summary
-- βœ… Documentation links
-
----
-
-## 🎨 Design Principles
-
-### Tone: "Engineering Truth"
-- βœ… Clear, direct explanations
-- βœ… No marketing fluff
-- βœ… Focus on how things work, not hype
-- βœ… Explain trade-offs explicitly
-
-### Audience: Developer-First
-- βœ… Code examples in Go, Bash, JSON
-- βœ… CLI-first (SAM is primarily a CLI)
-- βœ… Architecture diagrams and data flows
-- βœ… Link to implementation (test files, source)
-
-### Structure: Layered
-- βœ… Quick Start β†’ User Guide β†’ Deep Dive β†’ Reference
-- βœ… Beginner can read dark-mesh.md, get productive
-- βœ… Expert can read concepts/, understand internals
-- βœ… Operator has reference.md for commands
-
----
-
-## πŸš€ How to Use
-
-### Serve Documentation Locally
-
-```bash
-# Install Docsify CLI
-npm install -g docsify-cli
-
-# Serve docs
-cd docs
-docsify serve .
-
-# Open browser to http://localhost:3000
-```
-
-### Build for Production
-
-```bash
-# Use GitHub Pages
-# Push docs/ folder to repository
-# Enable GitHub Pages in Settings
-
-# Or host on any static site:
-# - Netlify
-# - Vercel
-# - AWS S3 + CloudFront
-# - Traditional web server
-```
-
-### Extend Documentation
-
-1. **Add a new guide**: Create `docs/guides/<name>.md`
-2. **Add a CLI command**: Document in `docs/cli/reference.md`
-3. **Add a concept**: Create `docs/concepts/<name>.md`
-4. **Update sidebar**: Edit `docs/_sidebar.md`
-5. **Update search**: Docsify auto-indexes all .md files
-
----
-
-## πŸ“ Content Summary by Category
-
-### 🎯 For Users
-- **Quick Start** (quickstart.md): Get running in 5 minutes
-- **User Guide** (guides/dark-mesh.md): Enterprise scenario walkthrough
-- **CLI Reference** (cli/reference.md): All commands + examples
-- **FAQ** (faq.md): Answers to common questions
-
-### πŸ”§ For Developers
-- **Contributing** (contributing.md): Development setup + workflow
-- **Testing** (testing.md): How to write and run tests
-- **Concepts** (concepts/): Technical deep dives
-- **A2A Protocol** (concepts/a2a-protocol.md): Code examples
-
-### πŸ“š For Architects
-- **Manifesto** (README.md): Philosophy + design principles
-- **Federation** (concepts/federation.md): Storage architecture
-- **Identity** (concepts/identity.md): Cryptography + trust model
-- **Biscuit** (concepts/biscuit.md): Authorization design
-
-### πŸ†˜ For Support
-- **FAQ** (faq.md): Troubleshooting section
-- **Glossary** (glossary.md): Terminology
-- **Contributing** (contributing.md): How to report bugs
-
----
-
-## βœ… Quality Checklist
-
-- βœ… **Comprehensive**: Every major feature documented
-- βœ… **Current**: Matches latest code (publish.go, call.go, inspect.go)
-- βœ… **Auditable**: Explains --dry-run and sam inspect
-- βœ… **Clear**: No jargon; explains terms on first use
-- βœ… **Actionable**: Code examples work (tested with binary)
-- βœ… **Linked**: Cross-references between docs
-- βœ… **Styled**: Docsify dark theme with custom colors
-- βœ… **Searchable**: Full-text search enabled
-- βœ… **Accessible**: Mobile-friendly, readable fonts
-
----
-
-## πŸ“Š Documentation Statistics
-
-| Metric | Value |
-|--------|-------|
-| Total documents | 15 |
-| Total lines | 3,500+ |
-| Code examples | 50+ |
-| Diagrams/ASCII art | 10+ |
-| Cross-references | 100+ |
-| Search terms | 500+ |
-| Supported languages | 3 (Bash, Go, JSON) |
-| Mobile responsive | Yes |
-| Dark mode | Yes |
-| Copy-to-clipboard | Yes |
-
----
-
-## 🎯 Next Steps
-
-1. **Serve locally**: `docsify serve docs/` (requires npm)
-2. **Deploy to GitHub Pages**: Push to main branch
-3. **Customize**: Edit index.html theme colors
-4. **Extend**: Add more concepts/guides as needed
-5. **Share**: Link to docs in README, GitHub pages
-
----
-
-## πŸ“„ Files Created
-
-```
-βœ… docs/index.html
-βœ… docs/_coverpage.md
-βœ… docs/_sidebar.md
-βœ… docs/README.md
-βœ… docs/quickstart.md
-βœ… docs/faq.md
-βœ… docs/glossary.md
-βœ… docs/testing.md
-βœ… docs/contributing.md
-βœ… docs/guides/dark-mesh.md
-βœ… docs/cli/reference.md
-βœ… docs/concepts/federation.md
-βœ… docs/concepts/identity.md
-βœ… docs/concepts/biscuit.md
-βœ… docs/concepts/a2a-protocol.md
-```
-
-**Total: 15 documentation files**
-
----
-
-Ready to share SAM with the world! πŸš€
diff --git a/docs/README.md b/docs/README.md
index 5211f96a..434fcf1a 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -1,182 +1,27 @@
-# Sovereign Agent Mesh: The Manifesto
+# SAM Documentation
-## What is SAM?
+This repository currently provides a minimal SAM runtime with two binaries:
-**Sovereign Agent Mesh (SAM)** is a **zero-trust networking layer for autonomous agents**. It enables agents to discover, authenticate, and collaborate with each otherβ€”without centralized gateways, identity providers, or trust intermediaries.
+- `sam-hub`: OIDC bridge and identity biscuit issuer
+- `sam-node`: mesh node CLI with login and run commands
-SAM is built on two core principles:
+The documentation here is intentionally small and aligned with what is implemented today.
-1. **Pure P2P Architecture**: No gateways. Agents communicate directly using libp2p, with routing through DHT and relays.
-2. **Zero-Trust at the Edge**: Cryptographic identity is verified locally, not delegated to a central authority.
+## What Works Today
-## The Trust Desert Problem
+1. Build and run `sam-node` and `sam-hub`
+2. Perform node login via hub OIDC flow
+3. Persist identity in local node store
+4. Run long-lived hub and node processes
+5. Run local and containerized BATS tests
-Today's agentic systems operate in a **trust desert**:
+## Start Here
-### The Gateway Trap
-- Agents talk to a central API gateway, which becomes a **single point of failure**
-- The gateway sees all traffic (privacy nightmare)
-- If the gateway is compromised, all agents are compromised
-- Scaling requires more gateways (distributed trust problem unsolved)
+- [Quick Start](quickstart.md)
+- [CLI Reference](cli/reference.md)
+- [Testing](testing.md)
-### The Identity Provider Trap
-- Agents rely on a central identity provider for credentials
-- If the IdP is breached, all agents lose their identity
-- The IdP becomes a **trusted third party** that must always be trusted
-- Offline operation is impossible
+## Notes
-### The Audit Nightmare
-- Audit trails are controlled by the infrastructure operator
-- No transparency into what data is flowing where
-- Security teams have to trust the operator's logs
-- Compliance becomes a matter of faith, not engineering
-
-## How SAM Solves This
-
-### 1. Pure P2P (No Gateways)
-```
-Traditional: Agent A β†’ Gateway β†’ Agent B
-SAM: Agent A ↔ Agent B (direct, with DHT discovery)
-```
-
-Agents discover each other through a **federated DHT**:
-- Discovery happens via `/sam` namespace (public) or `/sam/fed/<id>` (isolated)
-- Connections are direct (or relayed through libp2p DCUtR if NAT'd)
-- The DHT is the *only* intermediateβ€”and it's read-only for discovery
-
-### 2. Zero-Trust Identity (No Central Authority)
-```
-Traditional: Agent A requests token from IdP β†’ IdP validates β†’ Agent A uses token
-SAM: Agent A proves identity via Ed25519 vouch β†’ Agent B verifies locally
-```
-
-Every agent has a **cryptographic identity**:
-- Ed25519 keypair (libp2p standard)
-- Vouch from a federation (stored in bbolt, not fetched from a server)
-- Peer ID derived directly from the key (no token, no revocation server)
-
-Agent B verifies Agent A's identity by:
-1. Checking if Agent A's Peer ID is in the federation's vouch database
-2. Verifying the signature on the A2A message matches the Peer ID
-3. No external lookup required
-
-### 3. Federation Isolation (Enterprise Dark Mesh)
-Enterprises often need **isolated networks** with their own governance rules:
-
-```
-Federation Alpha: Agents operate in /sam/fed/alpha namespace
-Federation Beta: Agents operate in /sam/fed/beta namespace
-Public Mesh: Agents operate in /sam namespace
-
-Result: Agents in Alpha cannot discover agents in Beta (network isolation)
-```
-
-Isolation is enforced at the DHT level:
-- Each federation has its own `dht.ProtocolPrefix("/sam/fed/<id>")`
-- A2A gating checks federation membership before handshake
-- Storage is federated (one bbolt database per federation)
-
-### 4. Skill-Based Authorization (Zero-Trust for Capabilities)
-Even within a federation, not all agents can access all skills:
-
-```
-Alice publishes a Biscuit token: "bob;allow_skill=weather-bot,chat"
-Alice calls Bob with the token: Bob verifies "weather-bot" is in allowed_skills
-Result: Bob rejects any other capability
-```
-
-Biscuit tokens are lightweight caveats:
-- Format: `<subject>;<caveat>=<value>`
-- Parsed and validated locally (no external verification)
-- Example: `alice;allow_skill=risk-audit,email-send`
-
-### 5. Audit Transparency (sam inspect & --dry-run)
-Every operation can be audited **before** it executes:
-
-```bash
-# Inspect a Biscuit token
-sam inspect biscuit "alice;allow_skill=weather-bot"
-
-# Preview an Agent Card without publishing
-sam publish --skill weather-bot --mcp-port 8080 --dry-run=client
-
-# Validate a call request without network
-sam call bob --message "hello" --dry-run=client
-
-# Decode an Agent Card JSON
-sam inspect card '{"peer_id":"...", ...}'
-```
-
-All request/response shapes are exposed for security auditing.
-
-## Architecture at a Glance
-
-### Components
-
-| Component | Purpose | Tech |
-|-----------|---------|------|
-| **libp2p Node** | P2P networking, DHT, relays | libp2p-go |
-| **Federated DHT** | Isolated discovery per federation | dht.ProtocolPrefix |
-| **bbolt Storage** | Distributed, consensus-free vouch DB | go.etcd.io/bbolt |
-| **A2A Service** | Agent-to-agent RPC over libp2p streams | /sam/a2a/1.0 |
-| **Federation Gate** | Identity verification before A2A | VouchGate |
-| **Biscuit Gate** | Skill-based authorization | BiscuitSkillGate |
-| **Discovery Service** | Capability-based peer lookup | DiscoveryService |
-| **Agent Card** | Signed manifest of agent capabilities | protocol.AgentCard |
-
-### Data Flow: A2A Call
-
-```
-Agent A DHT (Discovery) Agent B
- β”‚ β”‚ β”‚
- β”œβ”€ sam call weather-bot β”‚ β”‚
- β”œβ”€ Discover peers for capability──┼──→ /sam/fed/alpha β”‚
- β”œβ”€ Select Agent B ← ────────────────────────── β”‚
- β”‚ β”‚
- β”œβ”€ Connect to Agent B on /sam/a2a/1.0 ─────────────────────────→│
- β”‚ β”‚
- β”œβ”€ Send Vouch + Biscuit ──────────────────────────────────────→│ FederationGate
- β”‚ β”œβ”€ Check vouch
- β”œβ”€ Send A2A request ──────────────────────────────────────────→│ BiscuitGate
- β”‚ β”œβ”€ Verify skill
- β”‚ ← ── Task Response ───────────── Execute
- β”‚ β”‚
- └─ Return result to CLI β”‚
-```
-
-## Why "Sovereign"?
-
-An agent is **sovereign** when it:
-- Controls its own identity (not assigned by a central authority)
-- Can operate without external services (no IdP, no gateway)
-- Can form agreements with other agents (federation, vouches)
-- Can prove its capabilities cryptographically (Agent Card, Biscuit)
-
-SAM enables this sovereignty by moving trust from **authorities** to **cryptography**.
-
-## What SAM Does NOT Do
-
-- **SAM is not a blockchain**: No distributed consensus, no ledger
-- **SAM is not a service mesh sidecar**: Agents link SAM directly, not via a sidecar
-- **SAM is not OAuth/OIDC**: No tokens issued by a central authority
-- **SAM is not a VPN**: No tunnel mode, direct P2P connections
-- **SAM is not a replacement for TLS**: We use TLS for transport, libp2p handles the rest
-
-## Next Steps
-
-- **[Getting Started](guides/dark-mesh.md)**: Set up an enterprise dark mesh
-- **[CLI Reference](cli/reference.md)**: Full kubectl-style command hierarchy
-- **[Technical Deep Dive](concepts/federation.md)**: How federation isolation works
-- **[Testing Guide](testing.md)**: Run the test suite locally
-
-## Philosophy
-
-SAM is built on **engineering truth**, not marketing claims:
-
-- We show how the system works, not hide complexity
-- We expose request/response shapes for auditing
-- We use standard crypto (Ed25519, libp2p) not custom protocols
-- We measure performance (not claim it)
-- We test everything (unit, integration, E2E)
-
-The goal is **trustworthy systems**, not trust-based systems.
+- Older architecture and feature-heavy docs were removed to avoid drift.
+- If a feature is not documented here, assume it is not part of the current minimal scope.
diff --git a/docs/_coverpage.md b/docs/_coverpage.md
deleted file mode 100644
index 4cc016cb..00000000
--- a/docs/_coverpage.md
+++ /dev/null
@@ -1,39 +0,0 @@
-![logo](data:image/svg+xml,<svg xmlns=%22http://www.w3.org/2000/svg%22 viewBox=%220 0 100 100%22><text x=%225%22 y=%2280%22 font-size=%22120%22 fill=%22%236366f1%22>⚑</text></svg>)
-
-# Sovereign Agent Mesh
-
-> Zero-Trust Networking for the Agentic Era
-
-- **Pure P2P**: No gateways, no central coordinators
-- **Zero-Trust**: Cryptographic identity at the edge, not centralized authorities
-- **Federation-Ready**: Isolated namespaces for enterprise dark meshes
-- **Audit-First**: Built-in transparency for security compliance
-
-[Documentation](#/README.md)
-[GitHub](https://github.com/aojea/sam)
-[Getting Started](#/quickstart.md)
-
----
-
-## The Trust Desert Problem
-
-In today's agentic systems, agents operate in a **trust desert**:
-
-- **Gateways** become honeypots (central points of failure)
-- **Centralized identity** providers can be breached or compromised
-- **Network isolation** is difficult without expensive VPNs or custom infrastructure
-- **Audit trails** are either missing or controlled by the infrastructure operator
-
-SAM (Sovereign Agent Mesh) solves this by bringing **Zero-Trust principles to autonomous agents**.
-
-## Engineering Truth
-
-This is not marketing. SAM is built on proven principles:
-
-1. **Cryptographic Identity**: Ed25519 keys derived from libp2p, not reliant on central authorities
-2. **Federated DHT**: Isolated discovery namespaces (`/sam/fed/<id>`) prevent cross-federation discovery
-3. **Identity Gating**: bbolt vouch database ensures peer identity before A2A handshake
-4. **Skill-Based Authorization**: Biscuit tokens with caveats enforce fine-grained access control
-5. **Transparent Auditing**: `sam inspect` and `--dry-run` modes expose all request/response shapes
-
-No gateways. No magic. Just cryptography and networking.
diff --git a/docs/_sidebar.md b/docs/_sidebar.md
index d9811447..857d0fb2 100644
--- a/docs/_sidebar.md
+++ b/docs/_sidebar.md
@@ -1,28 +1,5 @@
-<!-- Sidebar Navigation -->
-
-- **Getting Started**
- - [Overview](#/README.md)
- - [Quick Start](#/quickstart.md)
- - [Enterprise Dark Mesh](#/guides/dark-mesh.md)
- - [Hybrid Intelligence Audit](#/guides/hybrid-intelligence.md)
-
-- **CLI Reference**
- - [Command Hierarchy](#/cli/reference.md)
-
-- **Technical Concepts**
- - [Federation & Storage](#/concepts/federation.md)
- - [Identity & Vouch System](#/concepts/identity.md)
- - [Biscuit Authorization](#/concepts/biscuit.md)
- - [A2A Protocol](#/concepts/a2a-protocol.md)
-
-- **Testing**
- - [Testing Guide](#/testing.md)
-
-- **Contributing**
- - [Contributing Guide](#/contributing.md)
-
-- **Resources**
- - [FAQ](#/faq.md)
- - [Glossary](#/glossary.md)
- - [Documentation Inventory](#/DOCUMENTATION.md)
- - [License](https://github.com/aojea/sam/blob/main/LICENSE)
+- [Overview](#/README.md)
+- [Quick Start](#/quickstart.md)
+- [CLI Reference](#/cli/reference.md)
+- [Testing](#/testing.md)
+- [License](https://github.com/aojea/sam/blob/main/LICENSE)
diff --git a/docs/cli/reference.md b/docs/cli/reference.md
index 22f45a60..d037d76a 100644
--- a/docs/cli/reference.md
+++ b/docs/cli/reference.md
@@ -1,169 +1,72 @@
-# SAM CLI Reference
+# CLI Reference
-SAM uses a kubectl-style command hierarchy with shared node/runtime flags.
+The current repository exposes two CLIs:
-## Global Flags
+- `sam-node`
+- `sam-hub`
-Most commands accept these shared flags:
-
-| Flag | Type | Default | Description |
-|------|------|---------|-------------|
-| `--listen` | stringSlice | `/ip4/0.0.0.0/udp/0/quic-v1` | libp2p listen multiaddrs |
-| `--bootstrap` | stringSlice | empty | bootstrap peer multiaddrs |
-| `--dht-mode` | string | `client` | DHT mode: `client`, `server`, `auto` |
-| `--relay-service` | bool | `false` | enable relay service |
-| `--user-agent` | string | `sam/0.1.0` | libp2p user-agent |
-| `--run-for` | duration | `0` | optional duration before graceful shutdown |
-| `--hub` | string | empty | OIDC hub URL for identity login/passport issuance |
-| `--identity` | string | empty | PEM-encoded Ed25519 private key path |
-| `--debug` | bool | `false` | enable debug logging |
-
-## sam-agent identity
-
-Authentication and credential management.
-
-### sam-agent identity login
-
-Authenticate with the hub using device flow and store credentials plus passport biscuit locally.
+## sam-node
```bash
-sam-agent identity login --hub https://identity.acme.corp
+sam-node --help
```
-### sam-agent identity whoami
+### sam-node login
-Show current authenticated identity.
+Start the login flow and persist identity biscuit in the local store.
```bash
-sam-agent identity whoami
+sam-node login --hub http://localhost:8080
```
-## sam-agent publish
-
-Publish an agent card to DHT namespaces.
+Flags:
-### Quick Mode
+- `--hub`: hub base URL (default `http://localhost:8080`)
-```bash
-sam-agent publish --skill risk-audit --mcp-port 8080
-```
-
-Useful flags:
-- `--skill` or repeatable `--capability`
-- `--mcp-port`
-- `--republish-every`
-- `--dry-run=client|server`
-- `--resource-name`, `--resource-kind`, `--resource-endpoint`, `--resource-description`
+### sam-node run
-### sam-agent publish card
+Start the mesh node.
```bash
-sam-agent publish card --file agent-card.json --republish-every 5m
+sam-node run
```
-### sam-agent publish mcp
-
-```bash
-sam-agent publish mcp --port 8080 --name "Risk Audit Tool"
-```
+Flags:
-## sam-agent call
+- `--token`: identity biscuit override (if omitted, load from local store)
+- `--listen`: repeatable libp2p listen addresses
-Execute an A2A task against a remote agent.
+Examples:
```bash
-sam-agent call risk-audit --message "Audit the Q1 risk report"
+sam-node run --token <identity-biscuit>
+sam-node run --listen /ip4/0.0.0.0/udp/5001/quic-v1 --listen /ip4/0.0.0.0/tcp/5002
```
-Useful flags:
-- `--message`
-- `--biscuit`
-- `--timeout`
-- `--amount`, `--asset`, `--nonce`
-- `--dry-run=client|server`
-
-## sam-agent proxy
-
-Start a local HTTP proxy that tunnels over SAM.
+## sam-hub
```bash
-sam-agent proxy --port 8081
+sam-hub --help
```
-Useful flags:
-- `--port`
-- `--target-header`
-- `--biscuit`
-- `--timeout`
-
-## sam-agent inspect
+`sam-hub` runs the OIDC bridge, issues identity biscuits, and gates unauthenticated peers.
-Decode local artifacts for auditing.
+Flags:
-### sam-agent inspect biscuit
-
-```bash
-sam-agent inspect biscuit "alice;allow_skill=risk-audit,weather-bot"
-```
+- `--issuer`: OIDC issuer URL
+- `--client-id`: OIDC client ID
+- `--client-secret`: OIDC client secret
+- `--key`: 32-byte hex seed used to derive Ed25519 biscuit signing key
+- `--listen`: repeatable libp2p listen addresses
+- `--mesh`: mesh name
+- `--public-url`: public callback base URL
-### sam-agent inspect card
+Example:
```bash
-sam-agent inspect card '{"peer_id":"...","agent_card":{...}}'
+sam-hub \
+ --issuer https://issuer.example.com \
+ --client-id sam-client \
+ --client-secret sam-secret \
+ --key $(openssl rand -hex 32)
```
-
-## sam-agent mesh
-
-Mesh visibility commands.
-
-### sam-agent mesh get agents
-
-```bash
-sam-agent mesh get agents
-sam-agent mesh get agents --capability risk-audit
-sam-agent mesh get agents --watch -o json
-```
-
-## sam-agent up
-
-Start a SAM node and wait for shutdown.
-
-```bash
-sam-agent up \
- --listen /ip4/0.0.0.0/udp/4001/quic-v1 \
- --bootstrap /ip4/192.168.1.100/udp/4001/quic-v1/p2p/12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK
-```
-
-## Patterns
-
-### Publish workflow
-
-```bash
-# Preview card locally
-sam-agent publish --skill new-capability --mcp-port 9000 --dry-run=client
-
-# Publish to mesh
-sam-agent publish --skill new-capability --mcp-port 9000
-```
-
-### Call workflow with Biscuit
-
-```bash
-TOKEN="partner-bot;allow_skill=risk-audit"
-sam-agent inspect biscuit "$TOKEN"
-sam-agent call risk-audit --biscuit "$TOKEN" --message "Check compliance"
-```
-
-## Dry-Run Philosophy
-
-Dry-run modes support audit transparency and safe rollout:
-
-- `--dry-run=client`: build and validate payloads locally, no network activity
-- `--dry-run=server`: initialize runtime, skip final network commit
-
-Use these to preview behavior, capture JSON artifacts for security review, and gate CI checks.
-
-## Next Steps
-
-- **[User Journey Guide](#/guides/dark-mesh.md)**: scenario walkthrough
-- **[FAQ](#/faq.md)**: troubleshooting and operational tips
diff --git a/docs/concepts/a2a-protocol.md b/docs/concepts/a2a-protocol.md
deleted file mode 100644
index cfc0c7ab..00000000
--- a/docs/concepts/a2a-protocol.md
+++ /dev/null
@@ -1,418 +0,0 @@
-# A2A Protocol: Agent-to-Agent Communication
-
-## Overview
-
-The **A2A (Agent-to-Agent)** protocol is how agents call skills offered by other agents in a federation.
-
-- **Transport**: libp2p streams (TLS-encrypted)
-- **Port/Namespace**: `/sam/a2a/1.0`
-- **Message Format**: JSON-RPC 2.0 task envelope
-- **Authentication**: Vouch (federation membership)
-- **Authorization**: Biscuit token (skill access)
-
----
-
-## Protocol Flow
-
-### Connection Setup
-
-```
-Client Server
- β”‚ β”‚
- β”œβ”€ Open libp2p stream β”‚
- β”‚ /sam/a2a/1.0 β”‚
- β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€>β”‚
- β”‚ β”‚
- β”‚<───────────────────────────── β”‚ Stream open
-```
-
-### A2A Request
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "call-123",
- "method": "message",
- "params": {
- "message": "Get weather forecast for Seattle"
- },
- "headers": {
- "x-vouch": "<vouch JSON>",
- "x-biscuit": "alice;allow_skill=weather-bot",
- "x-payment": {
- "amount": 1,
- "asset": "sam-credit",
- "nonce": "1713451200000000000",
- "capability": "weather-bot"
- }
- }
-}
-```
-
-### A2A Response
-
-```json
-{
- "jsonrpc": "2.0",
- "id": "call-123",
- "result": {
- "forecast": "Partly cloudy, 65Β°F"
- }
-}
-```
-
----
-
-## Message Structure
-
-### Headers
-
-| Header | Type | Required | Purpose |
-|--------|------|----------|---------|
-| `x-vouch` | JSON | Yes | Proves federation membership |
-| `x-biscuit` | string | No | Grants access to specific skills |
-| `x-payment` | JSON | No | Micropayment info (future) |
-
-### Request (JSON-RPC 2.0)
-
-```json
-{
- "jsonrpc": "2.0", // Protocol version
- "id": "string", // Request ID (echo in response)
- "method": "message", // Always "message" (A2A task request)
- "params": { // task parameters
- "message": "..." // Natural-language prompt
- }
-}
-```
-
-### Response (JSON-RPC 2.0)
-
-Success:
-```json
-{
- "jsonrpc": "2.0",
- "id": "call-123",
- "result": {
- "response": "..."
- }
-}
-```
-
-Error:
-```json
-{
- "jsonrpc": "2.0",
- "id": "call-123",
- "error": {
- "code": -32600,
- "message": "Invalid request",
- "data": {
- "details": "..."
- }
- }
-}
-```
-
----
-
-## Authentication & Authorization
-
-### Step 1: Authentication (Vouch)
-
-Server receives request with vouch header.
-
-```
-vouch = {
- "subject": "alice",
- "peer_id": "12D3Koo...",
- "federation": "finance",
- "issued_at": "2026-04-18",
- "expires_at": "2027-04-18",
- "signature": "..."
-}
-
-Server checks:
-1. Is vouch signed by a trusted hub?
-2. Is vouch expired?
-3. Is peer_id in federation vouch database?
-
-If all pass β†’ Proceed to authorization
-If any fail β†’ Return error
-```
-
-### Step 2: Authorization (Biscuit)
-
-Server checks if caller is allowed the requested skill.
-
-```
-biscuit = "alice;allow_skill=weather-bot,risk-audit"
-
-Server checks:
-1. Parse biscuit: allowed_skills = ["weather-bot", "risk-audit"]
-2. Is requested_skill in allowed_skills?
-
-If yes β†’ Execute skill
-If no β†’ Return ErrSkillNotAllowed
-```
-
-### Step 3: Execution
-
-Server calls the local agent backend with the skill request.
-
-```
-POST http://127.0.0.1:8080
-Body: {
- "jsonrpc": "2.0",
- "method": "message",
- "params": {
- "message": "Get forecast"
- }
-}
-
-Response: {
- "result": {...}
-}
-
-Server returns response to client
-```
-
----
-
-## Error Codes
-
-### A2A Errors
-
-| Code | Reason |
-|------|--------|
-| `-32600` | Invalid request (malformed JSON) |
-| `-32601` | Capability not found |
-| `-32603` | Internal server error |
-
-### SAM-Specific Errors
-
-| Error | Cause | Solution |
-|-------|-------|----------|
-| `ErrNotInFederation` | Vouch not in federation | Authenticate: `sam-agent identity login --hub <url>` |
-| `ErrVouchExpired` | Vouch timestamp > expiry | Re-authenticate: `sam-agent identity login --hub <url>` |
-| `ErrSkillNotAllowed` | Skill not in Biscuit caveats | Get new Biscuit with skill, or ask for permission |
-| `ErrBackendFailed` | Local backend error | Check local backend logs |
-
----
-
-## Lifespan
-
-### Request-Response Cycle
-
-```
-1. Client dials /sam/a2a/1.0 stream
-2. Client sends vouch header
-3. Server validates vouch (FederationGate)
-4. Client sends biscuit header + skill request
-5. Server validates biscuit (BiscuitSkillGate)
-6. Server executes skill (calls local backend)
-7. Server sends response
-8. Stream closes
-```
-
-### Timeout
-
-Default: 20 seconds (configurable with `--timeout`)
-
-```bash
-sam-agent call mycapability --timeout 30s
-```
-
----
-
-## Code Example: Server
-
-```go
-// A2A service handler
-func (s *A2AService) handleStream(stream libp2pnet.Stream) error {
- ctx := context.Background()
- defer stream.Close()
-
- // 1. Read vouch from headers
- vouchJSON := stream.Header("x-vouch")
-
- // 2. Parse vouch
- vouch, err := parseVouch(vouchJSON)
- if err != nil {
- return fmt.Errorf("parsing vouch: %w", err)
- }
-
- // 3. Authenticate (Federation Gate)
- peerID := stream.Conn().RemotePeer()
- capability := getCapabilityFromRequest(stream)
-
- if err := s.gate.Allow(ctx, peerID, capability); err != nil {
- return fmt.Errorf("federation gate: %w", err)
- }
-
- // 4. Read biscuit from headers
- biscuitToken := stream.Header("x-biscuit")
-
- // 5. Authorize (Biscuit Gate)
- if s.skillGate != nil {
- if err := s.skillGate.CheckSkill(ctx, biscuitToken, capability); err != nil {
- return fmt.Errorf("skill gate: %w", err)
- }
- }
-
- // 6. Read request body
- var req protocol.A2ARequest
- if err := json.NewDecoder(stream).Decode(&req); err != nil {
- return fmt.Errorf("decoding request: %w", err)
- }
-
- // 7. Execute skill (call local backend)
- resp, err := s.executeBackend(ctx, capability, req.Params)
- if err != nil {
- return fmt.Errorf("executing skill: %w", err)
- }
-
- // 8. Send response
- return json.NewEncoder(stream).Encode(resp)
-}
-```
-
-### Code Example: Client
-
-```go
-// A2A call from client
-func callRemoteSkill(ctx context.Context, host host.Host, target peer.ID, skill string) error {
- // 1. Open stream
- stream, err := host.NewStream(ctx, target, "/sam/a2a/1.0")
- if err != nil {
- return fmt.Errorf("opening stream: %w", err)
- }
- defer stream.Close()
-
- // 2. Get local vouch
- vouch, err := loadLocalVouch()
- if err != nil {
- return err
- }
-
- // 3. Create biscuit token
- biscuit := "alice;allow_skill=" + skill
-
- // 4. Build request
- req := &A2ARequest{
- JSONRPC: "2.0",
- ID: "call-123",
- Method: "message",
- Params: map[string]interface{}{
- "message": "Execute skill",
- },
- }
-
- // 5. Send headers
- stream.SetHeader("x-vouch", mustMarshal(vouch))
- stream.SetHeader("x-biscuit", biscuit)
-
- // 6. Send request
- if err := json.NewEncoder(stream).Encode(req); err != nil {
- return fmt.Errorf("sending request: %w", err)
- }
-
- // 7. Read response
- var resp A2AResponse
- if err := json.NewDecoder(stream).Decode(&resp); err != nil {
- return fmt.Errorf("reading response: %w", err)
- }
-
- if resp.Error != nil {
- return fmt.Errorf("A2A error: %v", resp.Error)
- }
-
- return nil
-}
-```
-
----
-
-## Stream Lifecycle
-
-### TCP-like Semantics
-
-A2A streams behave like TCP connections:
-- **Connect**: Open stream to remote peer
-- **Send**: Write request JSON
-- **Receive**: Read response JSON
-- **Close**: Stream closes after response
-
-### Multiple Calls
-
-To make multiple calls efficiently:
-```go
-// Open connection once
-stream, err := host.NewStream(ctx, target, "/sam/a2a/1.0")
-
-// Make multiple calls on same stream (future feature)
-// Currently: one call per stream
-```
-
----
-
-## Network Considerations
-
-### Bandwidth
-
-A2A requests are lightweight:
-- Request: ~200 bytes (JSON-RPC header + small prompt)
-- Response: Variable (depends on result size)
-
-### Latency
-
-Typical A2A call latency:
-- DHT discovery: 500ms - 5s (cached after first call)
-- Stream setup: 50-200ms
-- RPC roundtrip: 100-500ms
-- Backend execution: 1-10s (depends on implementation)
-- **Total**: 2-15 seconds
-
-### Firewalls
-
-If direct connection fails, libp2p automatically:
-1. Attempts hole-punch (DCUtR)
-2. Falls back to relay
-3. Stream still works (just slower)
-
----
-
-## Future Enhancements
-
-1. **Streaming Responses**: For large result sets
-2. **Batch Requests**: Multiple calls in one stream
-3. **Subscribe Pattern**: Stream-based subscriptions (not request-response)
-4. **Compression**: Gzip compression for large payloads
-5. **Signature**: Sign requests with client key (not just vouch)
-
----
-
-## Specification Status
-
-**Current**: Implemented in Go, tested with BATS and integration tests
-
-**Future**: Standardize as IETF RFC or similar
-
-**Stability**: Protocol is stable; APIs may change before v1.0
-
----
-
-## Related Concepts
-
-- **[Vouch](#/concepts/identity.md)**: Authentication mechanism
-- **[Biscuit](#/concepts/biscuit.md)**: Authorization mechanism
-- **[Federation](#/concepts/federation.md)**: Network isolation
-- **[CLI](#/cli/reference.md)**: How to invoke A2A calls
-
----
-
-## Next Steps
-
-- **[Try it Out](#/guides/dark-mesh.md)**: Make your first A2A call
-- **[Integration Tests](https://github.com/aojea/sam/tree/main/tests/integration)**: See A2A in action
-- **[Contributing](#/contributing.md)**: Help improve the protocol
diff --git a/docs/concepts/biscuit.md b/docs/concepts/biscuit.md
deleted file mode 100644
index 99d4bb3a..00000000
--- a/docs/concepts/biscuit.md
+++ /dev/null
@@ -1,489 +0,0 @@
-# Biscuit Authorization: Fine-Grained Access Control
-
-## The Problem: All-or-Nothing Access
-
-Traditional systems either grant full access or none:
-
-```
-Partner API Key: alice-key-123
-β”œβ”€β”€ Can call ANY endpoint
-└── No granular access control
-
-Issue: If the key leaks, attacker gets full access
-```
-
-SAM uses **Biscuit tokens** to grant access to specific skills only.
-
----
-
-## What is a Biscuit Token?
-
-A Biscuit is a **lightweight credential with caveats** (restrictions).
-
-### Format
-
-```
-<subject>;<caveat>=<value>,<value>
-```
-
-### Example
-
-```
-alice;allow_skill=weather-bot
-```
-
-Breakdown:
-- **Subject**: `alice` (who the token is for)
-- **Caveat**: `allow_skill` (what type of restriction)
-- **Values**: `weather-bot` (specific skills allowed)
-
-### Multiple Skills
-
-```
-alice;allow_skill=weather-bot,risk-audit,email-send
-```
-
-Allows: weather-bot, risk-audit, email-send
-Denies: everything else
-
-### No Skills (Unrestricted)
-
-```
-alice
-```
-
-No caveat = full access to all skills
-
----
-
-## Why Plain Text?
-
-SAM uses plain-text Biscuits instead of cryptographic ones because:
-
-1. **Transparency**: Anyone can read what permissions are granted
-2. **Auditability**: `sam inspect biscuit` decodes without a server
-3. **Lightweight**: No cryptography overhead for authorization
-4. **Revocable**: Just delete the token from the app
-
-**Trade-off:** Plain-text Biscuits can be modified by the client, but SAM assumes:
-- Client trusts their own OS (local isolation)
-- Tokens are shared only with trusted applications
-- Server can verify trust via A2A authentication first
-
----
-
-## Authorization Flow
-
-### Step 1: Grant Access
-
-Alice creates a Biscuit for partner-bot:
-
-```bash
-TOKEN="[email protected];allow_skill=risk-audit"
-# Shared via secure channel (email, encrypted message, etc)
-```
-
-### Step 2: Client Uses Token
-
-Partner-bot calls alice's agent:
-
-```bash
-sam-agent call risk-audit \
- --biscuit "[email protected];allow_skill=risk-audit" \
- --message "Audit my data"
-```
-
-### Step 3: Server Verifies
-
-Alice's agent:
-
-1. Receives the Biscuit token
-2. Parses it: `ParsedBiscuit{Subject: "partner-bot", AllowedSkills: ["risk-audit"]}`
-3. Checks: Is `risk-audit` in `AllowedSkills`?
-4. **Yes** β†’ Execute skill
-5. **No** β†’ Reject with `ErrSkillNotAllowed`
-
-### Step 4: Enforce Fine-Grained Access
-
-Partner-bot tries to use a different skill:
-
-```bash
-sam-agent call compliance-check \
- --biscuit "[email protected];allow_skill=risk-audit" \
- --message "Check compliance"
-```
-
-Alice's agent:
-
-1. Parses token: `AllowedSkills: ["risk-audit"]`
-2. Checks: Is `compliance-check` in `AllowedSkills`?
-3. **No** β†’ Return error: `ErrSkillNotAllowed`
-
----
-
-## Biscuit Parsing
-
-### SimpleB iscuitParser
-
-SAM uses a simple parser that handles plain-text Biscuits:
-
-```go
-type SimpleBiscuitParser struct {}
-
-func (p *SimpleBiscuitParser) Parse(ctx context.Context, token string) (*ParsedBiscuit, error) {
- // Format: subject;allow_skill=skill1,skill2,...
-
- parts := strings.Split(token, ";")
-
- biscuit := &ParsedBiscuit{
- Subject: strings.TrimSpace(parts[0]),
- AllowedSkills: []string{},
- }
-
- if len(parts) < 2 {
- return biscuit, nil // No caveat = unrestricted
- }
-
- // Parse caveat: allow_skill=skill1,skill2
- caveatParts := strings.Split(parts[1], "=")
- if caveatParts[0] != "allow_skill" {
- return nil, ErrUnknownCaveat
- }
-
- skills := strings.Split(caveatParts[1], ",")
- for _, skill := range skills {
- if s := strings.TrimSpace(skill); s != "" {
- biscuit.AllowedSkills = append(biscuit.AllowedSkills, s)
- }
- }
-
- return biscuit, nil
-}
-```
-
-### ParsedBiscuit Structure
-
-```go
-type ParsedBiscuit struct {
- Subject string // "alice"
- AllowedSkills []string // ["weather-bot", "risk-audit"]
-}
-```
-
----
-
-## Skill Gate: Enforcement
-
-When a call arrives, the **BiscuitSkillGate** enforces the caveat:
-
-```go
-type BiscuitSkillGate struct {
- parser BiscuitParser
-}
-
-func (g *BiscuitSkillGate) CheckSkill(ctx context.Context, token string, skill string) error {
- parsed, err := g.parser.Parse(ctx, token)
- if err != nil {
- return err
- }
-
- // If no skills are restricted, allow all
- if len(parsed.AllowedSkills) == 0 {
- return nil
- }
-
- // Check if requested skill is allowed
- for _, allowed := range parsed.AllowedSkills {
- if allowed == skill {
- return nil
- }
- }
-
- return ErrSkillNotAllowed
-}
-```
-
----
-
-## A2A Stream Handling with Biscuit
-
-When a call arrives on the A2A stream:
-
-```go
-func (s *A2AService) handleStream(stream libp2pnet.Stream) error {
- peerID := stream.Conn().RemotePeer()
-
- // 1. Federation Gate: Check vouch (authentication)
- if err := s.gate.Allow(ctx, peerID, capability); err != nil {
- return fmt.Errorf("federation gate: %w", err)
- }
-
- // 2. Read Biscuit token from stream headers
- biscuitToken := stream.Header("x-biscuit")
-
- // 3. Biscuit Gate: Check skill (authorization)
- if s.skillGate != nil {
- if err := s.skillGate.CheckSkill(ctx, biscuitToken, capability); err != nil {
- return fmt.Errorf("skill gate: %w", err)
- }
- }
-
- // 4. Execute the skill
- return s.executeSkill(ctx, capability, payload)
-}
-```
-
----
-
-## Use Cases
-
-### Use Case 1: Partner Access (Read-Only)
-
-```bash
-# Grant vendor access to audit skill only
-VENDOR_TOKEN="[email protected];allow_skill=audit"
-
-# Vendor can use this skill
-sam call audit --biscuit "$VENDOR_TOKEN"
-
-# Vendor cannot use other skills
-sam call delete-data --biscuit "$VENDOR_TOKEN" # βœ— Error: skill not allowed
-```
-
-### Use Case 2: Multiple Skills (Limited Scope)
-
-```bash
-# Grant contractor access to specific tools
-CONTRACTOR_TOKEN="[email protected];allow_skill=log-query,metric-check"
-
-# Contractor can use these
-sam call log-query --biscuit "$CONTRACTOR_TOKEN" # βœ“ OK
-sam call metric-check --biscuit "$CONTRACTOR_TOKEN" # βœ“ OK
-
-# Contractor cannot use others
-sam call deploy --biscuit "$CONTRACTOR_TOKEN" # βœ— Error: not in allow list
-```
-
-### Use Case 3: Unrestricted Token (Trusted Partner)
-
-```bash
-# Grant trusted partner full access (no caveat)
-PARTNER_TOKEN="[email protected]"
-
-# Partner can use ANY skill
-sam call risk-audit --biscuit "$PARTNER_TOKEN" # βœ“ OK
-sam call weather --biscuit "$PARTNER_TOKEN" # βœ“ OK
-sam call deploy --biscuit "$PARTNER_TOKEN" # βœ“ OK (all allowed)
-```
-
----
-
-## Inspecting Tokens
-
-Before sharing a token, verify what it grants:
-
-### Single Skill
-
-```bash
-sam inspect biscuit "alice;allow_skill=weather-bot"
-```
-
-Output:
-```
-Biscuit Token Analysis
-======================
-
-Subject: alice
-Allowed Skills: weather-bot
-
-Human-Readable Summary:
-This token issued to 'alice' allows execution of 'weather-bot' skill only.
-```
-
-### Multiple Skills
-
-```bash
-sam inspect biscuit "partner;allow_skill=risk-audit,compliance-check"
-```
-
-Output:
-```
-Biscuit Token Analysis
-======================
-
-Subject: partner
-Allowed Skills:
- - risk-audit
- - compliance-check
-
-Human-Readable Summary:
-This token issued to 'partner' allows execution of 2 skills:
-risk-audit, compliance-check.
-```
-
-### Unrestricted
-
-```bash
-sam inspect biscuit "trusted-partner"
-```
-
-Output:
-```
-Biscuit Token Analysis
-======================
-
-Subject: trusted-partner
-Allowed Skills: (none, unrestricted)
-
-Human-Readable Summary:
-This token issued to 'trusted-partner' allows execution of ALL skills.
-```
-
----
-
-## Token Management
-
-### Creating Tokens
-
-Tokens are not generated by a server; they're created locally:
-
-```bash
-# CLI (future): Create a token
-sam economy biscuit create \
- --subject "[email protected]" \
- --allow-skill risk-audit \
- --allow-skill weather-bot
-```
-
-Or manually:
-```bash
-TOKEN="[email protected];allow_skill=risk-audit,weather-bot"
-```
-
-### Sharing Tokens
-
-Tokens should be shared via secure channels:
-- Encrypted email
-- Secure messaging app
-- In-person (QR code)
-- Not in logs, not in URLs, not in Git
-
-### Revoking Tokens
-
-Tokens are revoked by **removing them from use**:
-
-```bash
-# In your application configuration
-echo "[email protected];allow_skill=risk-audit" > revoked-tokens.txt
-```
-
-Then check against revoked list before allowing:
-
-```go
-if isRevoked(token) {
- return ErrTokenRevoked
-}
-```
-
-### Token Lifetime
-
-By default, Biscuits have **no expiry**. To implement expiry:
-
-1. Add an optional caveat: `alice;allow_skill=weather-bot;expires=2027-04-18`
-2. Check expiry in the gate: `CheckSkill()` validates expiry
-3. Revoke after expiry
-
----
-
-## Limitations and Future Work
-
-### Current Limitations
-
-1. **Plain-text**: Client can modify token (mitigated by OS isolation)
-2. **No signature**: Server trusts client's assertion (mitigated by A2A auth first)
-3. **No expiry**: Tokens don't auto-expire (revoke manually)
-4. **No delegation**: Can't delegate further ("partner gives token to sub-partner")
-
-### Future Enhancements
-
-1. **Cryptographic Biscuits**: Sign tokens with issuer key
-2. **Expiry Caveats**: `allow_skill=X;expires=<timestamp>`
-3. **Delegation**: Allow `partner` to grant subsets to others
-4. **Revocation List**: Server-side revocation (traded for offline capability)
-
----
-
-## Integration with A2A Protocol
-
-### Request Flow
-
-```
-Client Server
- β”‚ β”‚
- β”œβ”€ Connect A2A stream β”‚
- β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€>β”‚
- β”‚ β”‚
- β”œβ”€ Send Vouch (authentication) β”‚
- β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€>β”‚
- β”‚ β”‚
- β”œβ”€ Send Biscuit (authorization)β”‚
- β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€>β”‚
- β”‚ β”‚
- β”‚ [FederationGate checks] β”‚
- β”‚ [BiscuitSkillGate checks] β”‚
- β”‚ β”‚
- β”‚ [Execute]β”‚
- β”‚ β”‚
- β”‚<───────────────────────────── β”‚ Response
-```
-
-### Code Example
-
-```go
-// Client prepares call
-vouch := loadVouch(federation)
-biscuit := "partner;allow_skill=risk-audit"
-capability := "risk-audit"
-
-// Server validates
-gate := NewVouchGate(store)
-if err := gate.Allow(ctx, peerID, capability); err != nil {
- return err // Not in federation
-}
-
-skillGate := NewBiscuitSkillGate(parser)
-if err := skillGate.CheckSkill(ctx, biscuit, capability); err != nil {
- return err // Not in allowed_skills
-}
-
-// Execute
-return executeSkill(ctx, capability, payload)
-```
-
----
-
-## Security Considerations
-
-### Trust Assumptions
-
-1. **Client OS is secure**: Tokens are stored in plaintext
-2. **Client network is secure**: Tokens sent over libp2p TLS
-3. **Server trusts A2A authentication first**: Biscuit is secondary check
-4. **Tokens are not long-lived**: Regular rotation recommended
-
-### Attack Scenarios
-
-| Scenario | Risk | Mitigation |
-|----------|------|-----------|
-| Token leaked | Attacker uses skill | Revoke token, re-authenticate |
-| Client compromised | Attacker modifies token | OS isolation, encryption |
-| Server compromised | Attacker sees skills | Caveats are read-only, don't leak secrets |
-| Token replayed | Attacker reuses token | Signature + nonce (future) |
-
----
-
-## Next Steps
-
-- **[Identity & Vouch System](#/concepts/identity.md)**: How authentication works
-- **[A2A Protocol](#/concepts/a2a-protocol.md)**: How authorization is enforced
-- **[CLI Reference](#/cli/reference.md)**: `sam inspect biscuit` usage
diff --git a/docs/concepts/federation.md b/docs/concepts/federation.md
deleted file mode 100644
index dbc09ff3..00000000
--- a/docs/concepts/federation.md
+++ /dev/null
@@ -1,393 +0,0 @@
-# Federation & Storage: Physical Isolation
-
-## The Problem: Shared Trust Infrastructure
-
-Traditional agent systems use a **single central database**:
-
-```
-Gateway/Database
-β”œβ”€β”€ Org A agents
-β”œβ”€β”€ Org B agents
-└── Org C agents
-
-Issue: All organizations trust the same infrastructure operator.
-Risk: If the database is breached, all organizations are compromised.
-```
-
-SAM solves this with **federated, isolated storage**.
-
----
-
-## The Solution: bbolt per Federation
-
-Each federation has its own **independent database**:
-
-```
-Finance Federation Operations Federation
-~/.config/sam/federations/ ~/.config/sam/federations/
- └── finance.db └── operations.db
- β”œβ”€β”€ identities β”œβ”€β”€ identities
- β”œβ”€β”€ vouches β”œβ”€β”€ vouches
- β”œβ”€β”€ reputation β”œβ”€β”€ reputation
- └── cache └── cache
-```
-
-**Key benefits:**
-
-1. **Physical separation**: Data is not shared between federations
-2. **Independent backups**: Each federation can back up its own DB
-3. **Compliance isolation**: Finance data never touches Operations storage
-4. **No trusted intermediary**: Each federation manages its own identities
-
----
-
-## How Federation Storage Works
-
-### Storage Layout
-
-```
-~/.config/sam/
-β”œβ”€β”€ identity/
-β”‚ β”œβ”€β”€ keystore.json (personal Ed25519 key)
-β”‚ β”œβ”€β”€ vouch.json (cached vouch from hub)
-β”‚ └── credentials.keyring (encrypted passwords)
-β”‚
-└── federations/
- β”œβ”€β”€ finance.db (bbolt database)
- β”œβ”€β”€ operations.db (bbolt database)
- └── public.db (default federation)
-```
-
-### bbolt Structure (per federation)
-
-Each `.db` file is a bbolt database with buckets:
-
-```
-finance.db
-β”œβ”€β”€ identities
-β”‚ β”œβ”€β”€ alice.smith β†’ {peerID, created, updated}
-β”‚ β”œβ”€β”€ bob.jones β†’ {peerID, created, updated}
-β”‚ └── ...
-β”‚
-β”œβ”€β”€ vouches
-β”‚ β”œβ”€β”€ 12D3KooXA7cB... β†’ {subject, federation, issued, expires}
-β”‚ β”œβ”€β”€ 12D3KooXdef456... β†’ {subject, federation, issued, expires}
-β”‚ └── ...
-β”‚
-β”œβ”€β”€ reputation
-β”‚ β”œβ”€β”€ alice.smith β†’ {trust_score, calls_completed, failed}
-β”‚ └── ...
-β”‚
-└── cache
- β”œβ”€β”€ peer_addrs
- β”œβ”€β”€ capability_index
- └── ...
-```
-
-**Bucket purposes:**
-
-| Bucket | Purpose | Example |
-|--------|---------|---------|
-| `identities` | Map subjects to PeerIDs | alice.smith β†’ 12D3Koo... |
-| `vouches` | Cached vouch credentials | 12D3Koo... β†’ {issued, expires, federation} |
-| `reputation` | Trust scores and call history | alice.smith β†’ {score: 95, calls: 42} |
-| `cache` | Temporary peer addresses, capability index | weather-bot β†’ [12D3Koo..., 12D3Koo...] |
-
----
-
-## Federation Initialization
-
-When you create a federation:
-
-```bash
-sam-agent up
-```
-
-SAM:
-1. Generates a deterministic federation ID from the name: `fed-abc123...` (sha256 of "finance")
-2. Creates `~/.config/sam/federations/finance.db`
-3. Initializes buckets: `identities`, `vouches`, `reputation`, `cache`
-4. Stores federation metadata (name, ID, created_at)
-
-```
-$ cat ~/.config/sam/federations/finance.db
- (binary bbolt file)
-```
-
-The federation ID is deterministic, so re-creating a federation with the same name yields the same ID (useful for recovery).
-
----
-
-## Identity Vouch System
-
-When an agent authenticates with a federation hub:
-
-```bash
-sam-agent identity login --hub https://identity.acme.corp
-```
-
-### Step 1: Hub Issues Vouch
-
-The hub (identity server) issues a signed voucher:
-
-```json
-{
- "subject": "[email protected]",
- "federation": "finance",
- "peer_id": "12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK",
- "issued_at": "2026-04-18T10:00:00Z",
- "expires_at": "2027-04-18T10:00:00Z",
- "signature": "..." (hub's Ed25519 signature)
-}
-```
-
-### Step 2: Local Cache
-
-SAM stores the vouch in bbolt:
-
-```
-finance.db/vouches/12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK β†’ {
- subject: "[email protected]",
- federation: "finance",
- issued_at: 2026-04-18T10:00:00Z,
- expires_at: 2027-04-18T10:00:00Z
-}
-```
-
-### Step 3: Verification Without Server
-
-When alice.smith publishes an agent or calls another agent, SAM:
-
-1. Extracts the vouch from bbolt (no server needed)
-2. Verifies the signature using the hub's public key (cached locally)
-3. Checks expiry: is `now < expires_at`?
-4. Allows the operation if valid
-
-**Key insight:** The hub is **only contacted once** (at login). All subsequent operations use the cached vouch.
-
----
-
-## Why No Central Database?
-
-### Traditional Approach (Honeypot)
-```
-All agents β†’ Central DB ← Security team
-
-Issue 1: If DB is breached, all agents are compromised
-Issue 2: DB operator must be trusted forever
-Issue 3: Scaling requires replicating the trust
-```
-
-### SAM Approach (Federated)
-```
-Finance agents β†’ Finance.db (Finance org controls)
-Operations agents β†’ Operations.db (Ops org controls)
-Partner agents β†’ Partner.db (Partner org controls)
-
-Benefit 1: Finance breach doesn't expose Operations
-Benefit 2: Each org controls its own trust
-Benefit 3: Federations can operate independently
-```
-
----
-
-## Federation Isolation at DHT Level
-
-Storage is isolated, and **DHT discovery is also isolated**:
-
-### Finance Federation
-```bash
-sam-agent publish --skill risk-audit --mcp-port 8080
-```
-
-DHT announcement:
-```
-Namespace: /sam/fed/finance
-PeerID: 12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK
-Skill: risk-audit
-```
-
-### Operations Federation
-```bash
-sam-agent publish --skill incident-response --mcp-port 8090
-```
-
-DHT announcement:
-```
-Namespace: /sam/fed/operations
-PeerID: 12D3KooXdef456...
-Skill: incident-response
-```
-
-### Discovery Results
-
-Finance agent queries:
-```bash
-sam-agent call risk-audit
-```
-
-Result: Finds only agents in `/sam/fed/finance` (risk-audit skill)
-
-Operations agent queries:
-```bash
-sam-agent call risk-audit
-```
-
-Result: Finds nothing (risk-audit not published in operations namespace)
-
-**Physical separation + DHT isolation = true isolation**
-
----
-
-## Vouch vs Token vs Signature
-
-These three concepts work together:
-
-| Concept | Purpose | Scope | Lifetime |
-|---------|---------|-------|----------|
-| **Vouch** | Proves identity to federation | Federation-specific | Long (1 year) |
-| **Biscuit Token** | Grants skill access | Ad-hoc | Short or unlimited |
-| **Signature** | Proves cryptographic ownership | Message-specific | Single message |
-
-### Example Flow
-
-```
-1. Alice logs in β†’ Gets vouch for "finance" federation
- β”œβ”€β”€ Vouch stored in ~/.config/sam/federations/finance.db
- └── Valid for 1 year
-
-2. Alice publishes agent β†’ Signs Agent Card with Ed25519 key
- β”œβ”€β”€ Signature proves Alice owns the card
- └── Signature is part of the card
-
-3. Alice grants partner access β†’ Creates Biscuit token
- β”œβ”€β”€ "partner-bot;allow_skill=risk-audit"
- β”œβ”€β”€ Shared via secure channel
- └── No expiry (revoke by removing from app)
-
-4. Partner calls Alice's agent
- β”œβ”€β”€ Partner sends vouch (proves they're in the federation)
- β”œβ”€β”€ Partner sends Biscuit token (proves they can access risk-audit)
- β”œβ”€β”€ Alice verifies both β†’ Executes
- └── Alice returns signed response
-```
-
----
-
-## Managing Multiple Federations
-
-An agent can participate in multiple federations:
-
-```bash
-# Alice is in finance federation
-sam-agent identity login --hub https://identity.acme.corp
-
-# Alice is also invited to operations (different hub)
-sam-agent identity login --hub https://ops-identity.acme.corp
-
-# Alice publishes to both
-sam-agent publish --skill risk-audit --mcp-port 8080
-sam-agent publish --skill audit-log --mcp-port 8090
-
-# Each federation has its own storage
-~/.config/sam/federations/finance.db
-~/.config/sam/federations/operations.db
-```
-
-Each federation database:
-- Stores its own set of identity vouches
-- Publishes to its own DHT namespace
-- Has separate reputation scores
-
----
-
-## Disaster Recovery
-
-### Backing Up a Federation
-
-```bash
-# Backup federation DB
-cp ~/.config/sam/federations/finance.db ~/backups/finance.db.backup
-
-# Backup identity credentials
-cp ~/.config/sam/identity/ ~/backups/identity.backup
-```
-
-### Restoring a Federation
-
-```bash
-# Restore from backup
-cp ~/backups/finance.db.backup ~/.config/sam/federations/finance.db
-
-# Agent will continue with cached vouch
-sam-agent call risk-audit
-```
-
-If the vouch is stale, re-authenticate:
-```bash
-sam-agent identity login --hub https://identity.acme.corp
-```
-
----
-
-## Performance: Why bbolt?
-
-**bbolt is chosen because:**
-
-1. **ACID transactions**: Consistent reads/writes
-2. **Single file**: No distributed consensus needed
-3. **Fast**: B+ tree structure, in-process
-4. **No external dependencies**: Pure Go, no server
-
-**Alternative approaches we rejected:**
-
-- **SQLite**: Requires SQL schema, more complex
-- **Redis**: Requires central server (defeats isolation)
-- **DynamoDB/PostgreSQL**: Vendor lock-in, centralized
-- **In-memory map**: No persistence across restarts
-
-bbolt gives us **federated isolation + local performance**.
-
----
-
-## Storage Layout Example (Acme Corp)
-
-```
-Acme Corp IT
-└── ~/.config/sam/
- β”œβ”€β”€ identity/
- β”‚ β”œβ”€β”€ keystore.json (Alice's Ed25519 key)
- β”‚ └── vouch.json (Alice's vouch for "finance")
- β”‚
- └── federations/
- β”œβ”€β”€ finance.db (Finance federation)
- β”‚ β”œβ”€β”€ identities: {alice β†’ 12D3Koo...}
- β”‚ β”œβ”€β”€ vouches: {12D3Koo... β†’ {subject: alice, ...}}
- β”‚ β”œβ”€β”€ reputation: {alice β†’ {score: 98}}
- β”‚ └── cache: {risk-audit β†’ [12D3Koo...]}
- β”‚
- β”œβ”€β”€ operations.db (Ops federation)
- β”‚ β”œβ”€β”€ identities: {bob β†’ 12D3Koo...}
- β”‚ β”œβ”€β”€ vouches: {12D3Koo... β†’ {subject: bob, ...}}
- β”‚ β”œβ”€β”€ reputation: {bob β†’ {score: 87}}
- β”‚ └── cache: {incident-response β†’ [12D3Koo...]}
- β”‚
- └── public.db (Default federation)
- β”œβ”€β”€ identities: {...}
- β”œβ”€β”€ vouches: {...}
- └── cache: {...}
-
-Federated Database Architecture:
-- Finance.db is owned by Finance org
-- Operations.db is owned by Ops org
-- No shared database
-- No central trust
-```
-
----
-
-## Next Steps
-
-- **[Identity & Vouch System](#/concepts/identity.md)**: Deep dive into how identity works
-- **[Biscuit Authorization](#/concepts/biscuit.md)**: How skill-based access control works
-- **[A2A Protocol](#/concepts/a2a-protocol.md)**: How agents authenticate and call each other
diff --git a/docs/concepts/identity.md b/docs/concepts/identity.md
deleted file mode 100644
index 48b25181..00000000
--- a/docs/concepts/identity.md
+++ /dev/null
@@ -1,432 +0,0 @@
-# Identity & Vouch System: Decentralized Credentials
-
-## The Central Authority Problem
-
-Traditional systems use a **central identity provider**:
-
-```
-All agents β†’ OAuth/OIDC Server β†’ Decide who is allowed
-
-Issues:
-1. The IdP must always be available (unavailable = no agents work)
-2. The IdP sees all authentication attempts (privacy risk)
-3. If compromised, all agents lose identity
-4. Offline operation is impossible
-```
-
-SAM solves this with **vouch-based identity** that works offline.
-
----
-
-## How Vouch-Based Identity Works
-
-### Phase 1: Authentication (Online, One-Time)
-
-```bash
-sam-agent identity login --hub https://identity.acme.corp
-```
-
-**What happens:**
-
-1. User provides username/password
-2. SAM sends credentials to the hub
-3. Hub verifies credentials (LDAP, database, whatever)
-4. Hub issues a **Vouch** (signed JSON)
-5. Vouch is cached locally in bbolt
-6. Hub is no longer needed
-
-**Vouch structure:**
-
-```json
-{
- "subject": "[email protected]",
- "peer_id": "12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK",
- "federation": "finance",
- "issued_at": "2026-04-18T10:00:00Z",
- "expires_at": "2027-04-18T10:00:00Z",
- "signature": "abcdef... (hub's Ed25519 signature)"
-}
-```
-
-### Phase 2: Offline Authorization (No Server)
-
-After login, Alice can operate completely offline:
-
-```bash
-# Alice publishes an agent (no network)
-sam-agent publish --skill risk-audit --mcp-port 8080
-
-# Alice calls another agent (peer-to-peer only)
-sam-agent call weather-bot --message "forecast"
-```
-
-**Behind the scenes:**
-
-1. Alice's agent sends the cached vouch to Bob's agent
-2. Bob's agent:
- - Extracts the hub's public key from the vouch
- - Verifies the signature (locally, cryptographically)
- - Checks if the vouch is expired
- - If valid, trusts the vouch
-3. No network request to the hub
-
-**Trust chain:**
-
-```
-Hub issued vouch β†’ Hub's signature on vouch
- ↓
-Alice's agent stores vouch in bbolt
- ↓
-Bob's agent receives vouch
- ↓
-Bob's agent verifies hub's signature (public key known)
- ↓
-Bob trusts Alice (because Bob trusts the hub)
-```
-
----
-
-## Why This Works Without a Central Authority
-
-The key insight: **Trust the issuer's signature, not the current state of a server.**
-
-### Traditional Approach (Stateful)
-```
-Agent A asks: "Is Alice still authorized?"
- ↓
-IdP Server: "Let me check... yes, still authorized"
- ↓
-Agent A trusts response
-
-Problem: IdP must always have the answer
-```
-
-### SAM Approach (Cryptographic)
-```
-Agent A receives: "Alice issued by Hub on 2026-04-18, expires 2027-04-18, signed by Hub"
-Agent A verifies: Hub's signature matches public key
- ↓
-Agent A trusts vouch (if not expired)
-
-Benefit: No server needed, offline works, Hub could disappear
-```
-
----
-
-## Vouch Expiry and Renewal
-
-Vouches have a limited lifetime (typically 1 year):
-
-```json
-{
- "subject": "alice.smith",
- "issued_at": "2026-04-18T10:00:00Z",
- "expires_at": "2027-04-18T10:00:00Z"
-}
-```
-
-When the vouch expires:
-
-```bash
-sam call risk-audit --message "hello"
-```
-
-Error:
-```
-Error: stored identity vouch is expired; run login again
-```
-
-Re-authenticate:
-```bash
-sam identity login --hub https://identity.acme.corp
-```
-
-SAM:
-1. Contacts hub (online required for renewal)
-2. Verifies credentials again
-3. Gets new vouch
-4. Caches it (good for another year)
-
----
-
-## Vouch vs Token vs Signature
-
-SAM uses three layers of cryptography:
-
-### Layer 1: Vouch (Identity)
-**Purpose:** Prove you are who you say you are
-
-```
-"Alice is [email protected], issued by acme.corp hub on 2026-04-18"
-(signed by hub)
-
-Lifetime: 1 year
-Usage: Authentication (am I in the federation?)
-```
-
-### Layer 2: Biscuit (Authorization)
-**Purpose:** Prove you can do specific things
-
-```
-"alice;allow_skill=risk-audit,weather-bot"
-
-Lifetime: Unlimited (or revoked by removing from app)
-Usage: Authorization (what can I do?)
-```
-
-### Layer 3: Message Signature (Proof of Ownership)
-**Purpose:** Prove you sent a specific message
-
-```
-Agent Card:
-{
- "peer_id": "12D3Koo...",
- "agent_card": {...},
- "signature": "..." (signed with agent's Ed25519 key)
-}
-
-Lifetime: Single message
-Usage: Proof (did this agent really send this?)
-```
-
-### Example Flow
-
-```
-1. Alice logs in
- └─ Gets vouch (identity layer)
-
-2. Alice publishes agent
- └─ Signs Agent Card with Ed25519 key (proof layer)
-
-3. Alice grants partner access
- └─ Creates Biscuit token (authorization layer)
-
-4. Partner calls Alice's agent
- β”œβ”€ Sends vouch (authentication: "I'm in the federation")
- β”œβ”€ Sends Biscuit token (authorization: "I can use risk-audit")
- └─ Alice verifies both β†’ executes
-```
-
----
-
-## Multi-Federation Identity
-
-An agent can have vouches from multiple federations:
-
-```bash
-# Alice logs into finance federation
-sam identity login --hub https://identity-finance.acme.corp
-
-# Alice logs into operations federation
-sam identity login --hub https://identity-ops.acme.corp
-```
-
-Storage:
-
-```
-~/.config/sam/
-β”œβ”€β”€ federations/
-β”‚ β”œβ”€β”€ finance.db
-β”‚ β”‚ └── vouches: {alice β†’ {subject: alice, issued_at: ...}}
-β”‚ └── operations.db
-β”‚ └── vouches: {alice β†’ {subject: alice, issued_at: ...}}
-```
-
-**Key:** Each vouch is federation-scoped, stored in that federation's database.
-
----
-
-## The Hub: Simple Identity Server
-
-The hub is **not** a gateway. It's a simple service that:
-
-1. Verifies credentials (LDAP, OAuth, database, whatever)
-2. Issues a signed vouch
-3. Returns the vouch
-4. Forgets the request (stateless)
-
-### Hub Implementation (Pseudocode)
-
-```go
-type Hub struct {
- privateKey ed25519.PrivateKey
- credential_checker CredentialChecker // LDAP, database, etc
-}
-
-func (h *Hub) Login(username, password string, federation string) (*Vouch, error) {
- // 1. Verify credentials
- if !h.credential_checker.Verify(username, password) {
- return nil, ErrInvalidCredentials
- }
-
- // 2. Generate PeerID from username (deterministic)
- peerID := DeterministicPeerID(username)
-
- // 3. Create vouch
- vouch := &Vouch{
- Subject: username,
- PeerID: peerID,
- Federation: federation,
- IssuedAt: time.Now(),
- ExpiresAt: time.Now().AddDate(1, 0, 0),
- }
-
- // 4. Sign it
- vouch.Signature = ed25519.Sign(h.privateKey, vouch.Bytes())
-
- // 5. Return (don't store)
- return vouch, nil
-}
-```
-
-**Key properties:**
-- **Stateless**: No database of issued vouches
-- **Offline-capable**: Once issued, vouch works without the hub
-- **Deterministic PeerID**: Same username always yields same PeerID
-
----
-
-## Revocation: The Hard Problem
-
-Traditional systems can revoke a credential instantly:
-
-```
-Hub: "User is revoked"
-β†’ All agents reject user immediately
-```
-
-SAM cannot do this (no central authority), so:
-
-### SAM Revocation Strategy
-
-1. **Short vouch lifetime** (e.g., 1 year)
-2. **Biscuit-level revocation** (delete token from app)
-3. **Hub-side certificate pinning** (hub can rotate keys)
-
-**Scenario: Alice's credential is compromised**
-
-1. Acme Corp revokes Alice in their hub
-2. Alice's existing vouch is still valid (until expiry)
-3. Alice cannot login again (hub rejects credentials)
-4. New vouches cannot be issued to Alice
-5. Existing vouches eventually expire
-
-**Mitigation:**
-- Use short vouch lifetime (e.g., 3 months instead of 1 year)
-- Implement hub-side key rotation (revoke all vouches by retiring keys)
-- Use Biscuit token revocation at application level
-
----
-
-## Hub Operator Trust Model
-
-**SAM does NOT eliminate hub trust completely.** Here's why:
-
-```
-Issue: Who do you trust to verify credentials?
-
-Option A: Acme Corp's hub (knows all of Acme's employees)
-Option B: Certificate authority (verifies acme.corp domain)
-Option C: Peer recommendation (other agents vouch for you)
-```
-
-**SAM supports all three:**
-
-- **Option A** (Hub):
- ```bash
- sam-agent identity login --hub https://identity.acme.corp
- ```
-
-- **Option B** (Certificate pinning):
- ```bash
- sam-agent identity login --hub https://identity.acme.corp \
- --pin-certificate /path/to/cert.pem
- ```
-
-- **Option C** (Peer vouching):
- ```bash
- sam vouch create alice \
- --subject alice.smith \
- --issued-by bob.jones
- ```
-
-**The design principle:**
-> Move as much trust as possible from *authorities* to *cryptography*.
-
----
-
-## PeerID Derivation
-
-Each agent has a **deterministic PeerID** derived from identity:
-
-```go
-// Traditional: Random PeerID
-peerID := libp2p.NewRandomPeerID() // 12D3KooXABC...
-
-// SAM: Deterministic from identity
-publicKey := DerivePublicKey("[email protected]")
-peerID := PeerIDFromPublicKey(publicKey) // Always 12D3KooXABC...
-```
-
-**Benefits:**
-
-1. **Reproducible**: Same identity always yields same PeerID
-2. **Auditable**: Can verify identity from PeerID
-3. **Lightweight**: No key management service needed
-
-**How it works:**
-
-```
-Identity: "[email protected]"
- ↓
-SHA256 hash: "abc123..."
- ↓
-Ed25519 key derivation: "abc123..." β†’ PublicKey
- ↓
-PeerID: libp2p.IDFromPublicKey(publicKey)
- ↓
-Result: "12D3KooXA7cBj4VKrpv7HzKLmvnWKLVqZZHJm9NyN6Td3Y4hMWjK"
-```
-
----
-
-## Offline Workflow
-
-After authentication, agents can work completely offline:
-
-```bash
-# Online: Alice logs in
-sam identity login --hub https://identity.acme.corp
-
-# Offline: Publish agent
-sam publish --skill risk-audit --mcp-port 8080
-
-# Offline: Call another agent (if both are in same LAN)
-sam call bob.jones --message "hello"
-
-# Offline: Inspect credential
-sam inspect biscuit "bob;allow_skill=risk-audit"
-```
-
-**No internet required** for any of these operations (after initial login).
-
----
-
-## Summary: Identity Without Central Authority
-
-| Aspect | Traditional | SAM |
-|--------|-------------|-----|
-| **Where identity is verified** | Central server (every time) | Local vouch (once) |
-| **How trust is established** | Server state | Cryptographic signature |
-| **Offline support** | No | Yes (after login) |
-| **Revocation speed** | Instant | By vouch expiry |
-| **Trust dependencies** | IdP must exist | Hub must exist at login time |
-| **Federation support** | Single IdP | Multiple hubs per agent |
-
----
-
-## Next Steps
-
-- **[Biscuit Authorization](#/concepts/biscuit.md)**: How skill-based access control works
-- **[Federation & Storage](#/concepts/federation.md)**: How federation isolation works
-- **[A2A Protocol](#/concepts/a2a-protocol.md)**: How agents authenticate to each other
diff --git a/docs/contributing.md b/docs/contributing.md
deleted file mode 100644
index b805cd54..00000000
--- a/docs/contributing.md
+++ /dev/null
@@ -1,529 +0,0 @@
-# Contributing to SAM
-
-We welcome contributions! This guide covers:
-
-1. **Development Setup**: Get SAM building locally
-2. **Code Style**: Follow SAM conventions
-3. **Testing**: Ensure quality with full test coverage
-4. **Submitting Changes**: PR workflow
-
----
-
-## Development Setup
-
-### Prerequisites
-
-- **Go 1.21+**: https://golang.org/doc/install
-- **Make**: `sudo apt-get install make` (Linux) or `brew install make` (macOS)
-- **BATS**: `sudo apt-get install bats` (Linux) or `brew install bats-core` (macOS)
-- **Git**: For version control
-
-### Clone and Build
-
-```bash
-# Clone the repository
-git clone https://github.com/aojea/sam.git
-cd sam
-
-# Build the binary
-make build
-
-# Verify build
-./bin/sam --help
-```
-
-### Environment Setup
-
-```bash
-# Set GOPATH (if not already set)
-export GOPATH=$HOME/go
-
-# Add to PATH
-export PATH=$PATH:$GOPATH/bin
-
-# Run tests
-make test
-```
-
----
-
-## Code Style
-
-### Go Conventions
-
-SAM follows standard Go conventions:
-
-1. **Formatting**: Use `gofmt`
- ```bash
- gofmt -s -w cmd/sam/main.go
- ```
-
-2. **Linting**: Use `golangci-lint`
- ```bash
- go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest
- golangci-lint run ./...
- ```
-
-3. **Naming**
- - Package names: lowercase, no underscores (`samnet`, not `sam_net`)
- - Function names: `CamelCase` (exported) or `camelCase` (private)
- - Constants: `UPPER_CASE` (exported) or `upper_case` (private)
- - Interfaces: `Reader`, `Writer`, `Closer` (noun + verb pattern)
-
-4. **Comments**
- ```go
- // Package net provides libp2p networking for SAM agents.
- package net
-
- // Node represents a libp2p host with DHT routing.
- type Node interface {
- // Start begins listening and DHT discovery.
- Start(ctx context.Context) error
- }
- ```
-
-5. **Error Handling**
- ```go
- // Good
- if err != nil {
- return fmt.Errorf("loading vouch: %w", err)
- }
-
- // Bad
- if err != nil {
- panic(err) // Don't panic in libraries
- }
- ```
-
-### File Organization
-
-```
-sam/
-β”œβ”€β”€ cmd/sam/ # CLI commands
-β”‚ β”œβ”€β”€ main.go # Entry point
-β”‚ β”œβ”€β”€ root.go # Root command
-β”‚ β”œβ”€β”€ publish.go # Publish command
-β”‚ β”œβ”€β”€ call.go # Call command
-β”‚ └── ...
-β”œβ”€β”€ pkg/ # Libraries (exported)
-β”‚ β”œβ”€β”€ net/ # Networking
-β”‚ β”‚ β”œβ”€β”€ node.go
-β”‚ β”‚ β”œβ”€β”€ options.go
-β”‚ β”‚ └── node_test.go
-β”‚ β”œβ”€β”€ protocol/ # Protocols
-β”‚ β”‚ β”œβ”€β”€ a2a.go
-β”‚ β”‚ β”œβ”€β”€ agent_card.go
-β”‚ β”‚ └── a2a_test.go
-β”‚ β”œβ”€β”€ economy/ # Credentials and payments
-β”‚ β”‚ β”œβ”€β”€ biscuit.go
-β”‚ β”‚ β”œβ”€β”€ middleware.go
-β”‚ β”‚ └── biscuit_test.go
-β”‚ └── identity/ # Identity and authentication
-β”‚ β”œβ”€β”€ vouch.go
-β”‚ β”œβ”€β”€ device_flow.go
-β”‚ └── vouch_test.go
-β”œβ”€β”€ internal/ # Internal packages (not exported)
-β”‚ β”œβ”€β”€ db/ # Database abstractions
-β”‚ β”‚ β”œβ”€β”€ manager.go
-β”‚ β”‚ β”œβ”€β”€ store.go
-β”‚ β”‚ └── codec.go
-β”‚ └── testutils/ # Testing helpers
-β”‚ └── userns.go
-β”œβ”€β”€ tests/ # Test suites
-β”‚ β”œβ”€β”€ integration/ # Go integration tests
-β”‚ β”‚ β”œβ”€β”€ a2a_test.go
-β”‚ β”‚ β”œβ”€β”€ cuj_test.go
-β”‚ β”‚ └── mesh_test.go
-β”‚ └── e2e/ # BATS E2E tests
-β”‚ └── sam.bats
-└── docs/ # Documentation
- β”œβ”€β”€ README.md
- β”œβ”€β”€ guides/
- β”œβ”€β”€ cli/
- └── concepts/
-```
-
----
-
-## Testing
-
-### Test Coverage Requirements
-
-All contributions must include tests:
-
-1. **Unit tests** for new functions
-2. **Integration tests** for multi-node scenarios
-3. **E2E tests** for CLI changes
-
-### Running Tests
-
-```bash
-# All tests
-make test
-
-# Unit + Integration only
-go test -race -count=1 ./...
-
-# E2E only
-make build
-make test-e2e
-
-# Specific test
-go test -run TestFunctionName ./pkg/package
-
-# With coverage
-go test -cover ./...
-```
-
-### Writing Unit Tests
-
-```go
-func TestNewBiscuit(t *testing.T) {
- // Arrange
- parser := economy.SimpleBiscuitParser{}
- token := "alice;allow_skill=weather"
-
- // Act
- parsed, err := parser.Parse(context.Background(), token)
-
- // Assert
- if err != nil {
- t.Fatalf("Parse failed: %v", err)
- }
- if parsed.Subject != "alice" {
- t.Errorf("Expected 'alice', got %q", parsed.Subject)
- }
-}
-```
-
-### Writing Integration Tests
-
-```go
-func TestA2ACallWithBiscuit(t *testing.T) {
- testutils.Run(t, func(f *testutils.Framework) {
- // Setup
- nodea, _ := f.StartNode("federation-a")
- nodeb, _ := f.StartNode("federation-a")
-
- // Execute
- token := "alice;allow_skill=test-skill"
- resp, err := protocol.Execute(
- context.Background(),
- nodea.Host(),
- protocol.ExecuteRequest{
- Target: nodeb.PeerID(),
- Capability: "test-skill",
- Biscuit: token,
- MCPRequest: []byte(`{"method": "test"}`),
- },
- )
-
- // Assert
- if err != nil {
- t.Fatalf("Execute failed: %v", err)
- }
- if resp == nil {
- t.Errorf("Expected response")
- }
- }, testutils.CLONE_NEWNET)
-}
-```
-
-### Writing BATS Tests
-
-```bash
-@test "sam publish with dry-run outputs card" {
- run "$SAM_BINARY" publish \
- --skill test-skill \
- --mcp-port 9999 \
- --dry-run=client
-
- [[ "$status" -eq 0 ]]
- [[ "$output" == *'"peer_id"'* ]]
- [[ "$output" == *'test-skill'* ]]
-}
-```
-
-### Race Detection
-
-Always test with race detection:
-
-```bash
-go test -race ./...
-```
-
-This catches data races that are hard to spot manually.
-
----
-
-## Submitting Changes
-
-### 1. Create a Branch
-
-```bash
-git checkout -b feature/my-feature
-# or
-git checkout -b fix/issue-123
-```
-
-### 2. Make Changes
-
-```bash
-# Edit files
-vim pkg/net/node.go
-
-# Run tests frequently
-go test -race ./pkg/net
-```
-
-### 3. Commit with Good Messages
-
-```bash
-git add -A
-git commit -m "Add federation isolation to DHT discovery
-
-- Scopes DHT announcements to /sam/fed/<id> namespace
-- Prevents cross-federation peer discovery
-- Matches federation DHT protocol prefix
-
-Fixes #123"
-```
-
-**Commit message format:**
-```
-<type>: <description>
-
-<body explaining why>
-
-Fixes #<issue-number>
-```
-
-**Types:** `feat`, `fix`, `refactor`, `test`, `docs`, `chore`
-
-### 4. Keep Branch Up to Date
-
-```bash
-git fetch origin
-git rebase origin/main
-```
-
-### 5. Push and Create PR
-
-```bash
-git push origin feature/my-feature
-```
-
-Then create a PR on GitHub with:
-- **Title**: Brief summary
-- **Description**: What changed and why
-- **Tests**: Mention test coverage
-- **Fixes**: Reference any related issues (#123)
-
-### 6. Code Review
-
-- Address reviewer feedback
-- Push additional commits (don't force-push)
-- Reviewer will merge when approved
-
----
-
-## Common Development Tasks
-
-### Adding a New CLI Command
-
-1. **Create command file** (`cmd/sam/mycommand.go`):
- ```go
- func newMyCmd(cfg *runConfig) *cobra.Command {
- cmd := &cobra.Command{
- Use: "mycommand",
- Short: "Do something",
- RunE: func(cmd *cobra.Command, args []string) error {
- return runMyCommand(cmd.Context(), cfg)
- },
- }
- // Add flags
- cmd.Flags().StringVar(&cfg.flag, "flag", "", "description")
- return cmd
- }
-
- func runMyCommand(ctx context.Context, cfg *runConfig) error {
- // Implementation
- return nil
- }
- ```
-
-2. **Register in root** (`cmd/sam/root.go`):
- ```go
- cmd.AddCommand(newMyCmd(cfg))
- ```
-
-3. **Add tests** (`tests/e2e/sam.bats`):
- ```bash
- @test "sam mycommand --help works" {
- run "$SAM_BINARY" mycommand --help
- [[ "$status" -eq 0 ]]
- }
- ```
-
-### Adding a New Protocol Feature
-
-1. **Define interface** (`pkg/protocol/myfeature.go`):
- ```go
- type MyFeature interface {
- DoSomething(ctx context.Context) error
- }
- ```
-
-2. **Implement** (`pkg/protocol/myfeature.go`):
- ```go
- type myFeatureImpl struct {
- // fields
- }
-
- func (m *myFeatureImpl) DoSomething(ctx context.Context) error {
- // implementation
- }
- ```
-
-3. **Add tests** (`pkg/protocol/myfeature_test.go`):
- ```go
- func TestMyFeature(t *testing.T) {
- // test implementation
- }
- ```
-
-### Debugging Issues
-
-```bash
-# Verbose logging
-SAM_DEBUG=1 go test -v ./...
-
-# GDB debugging
-dlv test ./pkg/net
-
-# CPU profiling
-go test -cpuprofile=cpu.prof ./...
-go tool pprof cpu.prof
-
-# Memory profiling
-go test -memprofile=mem.prof ./...
-go tool pprof mem.prof
-```
-
----
-
-## Code Review Checklist
-
-Before submitting a PR, ensure:
-
-- [ ] Code follows Go style guidelines
-- [ ] All tests pass: `go test -race ./...`
-- [ ] New code has tests
-- [ ] Integration tests pass: `go test -race -count=1 ./tests/integration`
-- [ ] E2E tests pass: `make test-e2e`
-- [ ] Comments explain non-obvious logic
-- [ ] Error messages are descriptive
-- [ ] No panics in libraries (use errors)
-- [ ] No TODO/FIXME comments (create issues instead)
-- [ ] Documentation is updated
-
----
-
-## Reporting Issues
-
-When reporting bugs, include:
-
-1. **Expected behavior**: What should happen?
-2. **Actual behavior**: What happens instead?
-3. **Steps to reproduce**: How to trigger the bug?
-4. **Environment**: Go version, OS, architecture
-5. **Logs**: Error messages and stack traces
-
-### Example Issue
-
-```
-Title: sam call fails with "unknown peer" when federation is not set
-
-Expected: sam call should use default federation
-Actual: sam call fails with "unknown peer"
-
-Steps:
-1. sam publish --skill test --mcp-port 8080
-2. sam call test --message "hello"
-
-Environment:
-- Go 1.21
-- Ubuntu 22.04
-- SAM commit abc123
-
-Error:
- Error: discovering capability "test": no peers found for capability "test"
-```
-
----
-
-## Design Discussion
-
-For significant changes, please open an issue first to discuss:
-
-- **Architecture changes**: How will this affect the system?
-- **Protocol changes**: Will this affect peer compatibility?
-- **Breaking changes**: How should we handle migration?
-
----
-
-## Documentation
-
-All features should have corresponding documentation:
-
-1. **API docs**: Godoc comments on exported types/functions
-2. **User guides**: CLI examples in `/docs/guides/`
-3. **Concepts**: Technical explanations in `/docs/concepts/`
-4. **CLI reference**: Command documentation in `/docs/cli/`
-
-### Godoc Example
-
-```go
-// Node represents a libp2p host with DHT routing.
-// It manages connectivity, peer discovery, and protocol handlers.
-type Node interface {
- // Start begins the node listening and starts DHT discovery.
- // Returns error if the node is already started.
- Start(ctx context.Context) error
-
- // Stop gracefully shuts down the node.
- // All streams and protocols are closed.
- Stop(ctx context.Context) error
-
- // Host returns the underlying libp2p host.
- Host() host.Host
-
- // PeerID returns the unique identifier for this node.
- PeerID() peer.ID
-}
-```
-
----
-
-## Community
-
-- **Issues**: Report bugs and request features
-- **Discussions**: Ask questions and share ideas
-- **Pull Requests**: Contribute code
-- **Slack/Discord**: (if applicable)
-
----
-
-## License
-
-All contributions are licensed under the same license as SAM (typically MIT or Apache 2.0). By contributing, you agree to this.
-
----
-
-## Questions?
-
-- **Open an issue** for bug reports or features
-- **Start a discussion** for design questions
-- **Check the docs**: https://docs.sam.dev
-
-Thank you for contributing! πŸš€
diff --git a/docs/faq.md b/docs/faq.md
deleted file mode 100644
index 04584bb1..00000000
--- a/docs/faq.md
+++ /dev/null
@@ -1,186 +0,0 @@
-# FAQ: Frequently Asked Questions
-
-## What is SAM?
-
-SAM (Sovereign Agent Mesh) is a zero-trust networking layer for autonomous agents.
-It provides peer discovery, identity verification, and capability authorization over pure libp2p.
-
-## Getting Started
-
-### How do I install SAM?
-
-```bash
-git clone https://github.com/aojea/sam.git
-cd sam
-make build
-./bin/sam-agent --help
-```
-
-Requirements: Go 1.21+, Make, BATS (for E2E tests).
-
-### How do I publish my first agent?
-
-1. Authenticate with your hub:
-
-```bash
-sam-agent identity login --hub <your-hub-url>
-```
-
-2. Publish a local MCP capability:
-
-```bash
-sam-agent publish --skill mycapability --mcp-port 8080
-```
-
-### How do I call an agent?
-
-```bash
-sam-agent call mycapability --message "Do something"
-```
-
-## Core Concepts
-
-### Do I need to manage federations manually?
-
-No. SAM now runs with a single default federation namespace at runtime.
-The old federation management CLI commands were removed.
-
-### What is a passport biscuit?
-
-A passport biscuit is the identity credential issued by the hub and bound to your peer identity.
-It is used for authentication during peer establishment.
-
-### What is a Biscuit token?
-
-A Biscuit token grants capability-level authorization.
-Example format:
-
-`alice;allow_skill=weather-bot,risk-audit`
-
-### What is an agent card?
-
-A signed manifest published to the DHT containing peer id, skills, and resources.
-
-## Architecture and Security
-
-### Why peer-to-peer instead of a gateway?
-
-P2P avoids centralized bottlenecks and trust chokepoints.
-Peers communicate directly, and trust is cryptographic.
-
-### Is SAM production-ready?
-
-SAM is in active development. Core paths are tested, but you should apply standard production hardening:
-- secure key storage
-- short credential lifetimes
-- monitoring and incident response
-
-### How do I protect credentials?
-
-- keep local config directory protected by OS permissions
-- rotate hub credentials regularly
-- inspect biscuits before sharing
-
-## Networking
-
-### Can SAM work behind NAT?
-
-Yes. SAM relies on libp2p connectivity features including relay and hole punching.
-
-### Can I run a node in the cloud?
-
-Yes.
-
-```bash
-sam-agent up --listen /ip4/0.0.0.0/udp/4001/quic-v1
-```
-
-## Performance
-
-### How many peers can it handle?
-
-The practical limit depends on network and host resources.
-For most deployments, discovery latency is dominated by DHT topology and cache warmth.
-
-### How fast are calls?
-
-Call latency is usually the sum of:
-- discovery time (first lookup can be slower)
-- connection establishment
-- remote tool execution time
-
-## Operations
-
-### Where are credentials and state stored?
-
-```text
-~/.config/sam/
-β”œβ”€β”€ identity/
-β”‚ └── credentials.json
-└── federations/
- └── default.db
-```
-
-### How do I back up local state?
-
-```bash
-cp ~/.config/sam/federations/default.db ~/backup/default.db.backup
-cp -r ~/.config/sam/identity ~/backup/identity.backup
-```
-
-### How do I refresh identity credentials?
-
-```bash
-sam-agent identity login --hub <hub-url>
-```
-
-### How do I debug a failed call?
-
-1. Confirm identity is present:
-
-```bash
-sam-agent identity whoami
-```
-
-2. Check visible agents:
-
-```bash
-sam-agent mesh get agents
-```
-
-3. Dry-run request:
-
-```bash
-sam-agent call mycapability --message "test" --dry-run=client
-```
-
-4. Increase logging:
-
-```bash
-SAM_DEBUG=1 sam-agent call mycapability --message "test"
-```
-
-## Integration
-
-### Can I use SAM as a library?
-
-Yes. Import SAM packages in Go and construct a node with `sam/pkg/net`.
-
-### Can I run SAM in Docker/Kubernetes?
-
-Yes. Persist `~/.config/sam` and expose libp2p ports as needed.
-
-## Development
-
-### How do I run tests?
-
-```bash
-go test -race ./...
-make build
-make test-e2e
-```
-
-### Where do I report bugs?
-
-Open an issue at:
-https://github.com/aojea/sam/issues
diff --git a/docs/glossary.md b/docs/glossary.md
deleted file mode 100644
index 13e772d9..00000000
--- a/docs/glossary.md
+++ /dev/null
@@ -1,277 +0,0 @@
-# Glossary
-
-## A
-
-**A2A**: Agent-to-Agent. RPC protocol for agents to call each other over libp2p streams.
-
-**Agent**: An autonomous program that can publish skills to a federation and call skills offered by other agents.
-
-**Agent Card**: Signed manifest published by an agent to the DHT, containing skills, resources, and signature.
-
-**Authorization**: Determining what an authenticated agent is allowed to do (e.g., which skills it can invoke).
-
-## B
-
-**Biscuit**: Lightweight credential with caveats granting access to specific skills. Format: `subject;allow_skill=X,Y,Z`
-
-**Blockade**: (Future) Mechanism to revoke agent identity in a federation.
-
-**Bolt/bbolt**: Embedded key-value database used for federation storage. Pure Go, no external dependencies.
-
-**Bootstrap**: Peer addresses used to join the DHT. Agents connect to bootstrap nodes to discover peers.
-
-**Bytecode**: (Not used in SAM) Biscuit tokens are plain-text, not bytecode.
-
-## C
-
-**Capability**: Synonym for skill. The set of things an agent can do.
-
-**Caveat**: Restriction in a Biscuit token (e.g., `allow_skill=X`).
-
-**Certificate**: Cryptographic proof of identity, typically Ed25519 key.
-
-**Cipher**: Encryption algorithm used in TLS transport (not user-facing in SAM).
-
-**CLONE_NEWNET**: Linux namespace for network isolation in integration tests.
-
-**Codec**: Encoder/decoder for serialization (JSON, bincode, etc.).
-
-**Consensus**: SAM does NOT use consensus. Each federation manages independently.
-
-**Cryptography**: Mathematical science for secure communication. SAM uses Ed25519 for signing and libp2p for TLS.
-
-## D
-
-**Dark Mesh**: Enterprise network where agents operate in isolation, not visible to the public mesh. Uses federation isolation.
-
-**DCUtR**: Direct Connection UpgRade. libp2p mechanism for hole-punching through NAT.
-
-**Delegation**: (Future) Allowing an agent to grant a subset of its skills to another agent.
-
-**Device Flow**: OAuth-like authentication where a device opens a browser to authenticate (used by `sam identity login`).
-
-**DHT**: Distributed Hash Table. Peer discovery mechanism used by libp2p. SAM scopes DHT announcements to federation namespaces.
-
-**Dry-run**: Preview mode for commands. `--dry-run=client` builds locally, `--dry-run=server` skips final commit.
-
-## E
-
-**Ed25519**: Public-key cryptography algorithm for signing. Standard in libp2p.
-
-**Economy**: Package in SAM for credentials, payments, and authorization.
-
-**Endpoint**: URL where an MCP resource is available (e.g., `http://127.0.0.1:8080`).
-
-**Enrollment**: Process of joining a federation (login + credential storage).
-
-## F
-
-**Federation**: Isolated P2P network where agents discover and call each other. Each federation has own DHT namespace and storage.
-
-**Federation Gate**: Component that checks if a caller is in the federation (vouch verification).
-
-**Federation ID**: Deterministic identifier for a federation, derived from name.
-
-**Firewall**: Network filter. SAM uses libp2p's QUIC and WebSocket to traverse firewalls.
-
-## G
-
-**Gateway**: Central server that intermediates peer connections. SAM avoids gateways by using direct P2P.
-
-**Governance**: Rules for a federation (who can join, which skills are allowed, etc.). SAM delegates to federation operators.
-
-**gRPC**: RPC framework (not used in SAM; SAM uses libp2p streams + MCP).
-
-## H
-
-**Hub**: Identity server that issues vouches. Contacted once per login, then vouch is cached locally.
-
-**Hole-Punch**: Technique for NAT traversal using ICE. libp2p DCUtR implements this.
-
-**HSM**: Hardware Security Module for secure key storage.
-
-## I
-
-**Identity**: Proof of who you are. In SAM: cryptographic (Ed25519 key) + vouch.
-
-**Identity Provider (IdP)**: Server that verifies credentials and issues tokens. SAM integrates with existing IdPs via hub.
-
-**Isolation**: Separation of network namespaces to prevent cross-federation discovery.
-
-## J
-
-**JSON**: Serialization format used for Agent Cards, calls, and CLI output.
-
-## K
-
-**Key**: Cryptographic secret (Ed25519 private key). Stored in `~/.config/sam/identity/keystore.json`.
-
-**Keyring**: Encrypted credential storage on OS (macOS Keychain, Linux Secret Service, Windows Credential Manager).
-
-## L
-
-**libp2p**: Modular P2P networking library used for connectivity, DHT, and relays. The foundation of SAM.
-
-**Linux Namespace**: OS-level isolation for network, filesystem, etc. Used in integration tests.
-
-**Listen Address**: Multiaddr where a node listens for connections (e.g., `/ip4/0.0.0.0/tcp/4001`).
-
-## M
-
-**Mesh**: Network of interconnected agents. SAM enables zero-trust meshes.
-
-**MCP**: Model Context Protocol. Protocol for agents to define resources and capabilities.
-
-**Middleware**: Component that processes requests/responses (e.g., `BiscuitSkillGate`).
-
-**Micropayment**: Small payment sent with A2A call. Currently placeholder, future feature.
-
-**Multiaddr**: Multi-protocol address format used by libp2p (e.g., `/ip4/127.0.0.1/tcp/8080`).
-
-## N
-
-**NAT**: Network Address Translation. Makes direct connections difficult. libp2p uses relays and hole-punching to overcome.
-
-**Namespace**: DHT protocol prefix for scoping discovery (e.g., `/sam/fed/finance`).
-
-**Nonce**: Number used once, for security. Used in micropayments to prevent replay.
-
-## O
-
-**OAuth/OIDC**: Standard authentication protocols. SAM doesn't use these; instead uses vouches.
-
-**Offline**: Mode where SAM operates without network connectivity (possible with cached vouches).
-
-**Operator**: Person or organization running a federation hub or node.
-
-## P
-
-**Peer**: Node in the P2P network identified by PeerID.
-
-**PeerID**: Unique identifier for a libp2p node, derived from its Ed25519 public key.
-
-**Peering**: Process of connecting two nodes directly.
-
-**Permission**: Synonym for capability/skill.
-
-**Private Key**: Secret cryptographic key used for signing. Never shared.
-
-**Protocol**: Set of rules for communication. SAM defines `/sam/a2a/1.0` for agent calls.
-
-**Proxy**: Intermediary that relays traffic. SAM avoids proxies where possible, uses libp2p relays as fallback.
-
-**Public Key**: Cryptographic key that anyone can see. Used to verify signatures.
-
-## Q
-
-**QUIC**: UDP-based protocol often more lenient through firewalls than TCP.
-
-## R
-
-**Reputation**: System for tracking agent trustworthiness (future feature).
-
-**Revocation**: Disabling a credential (vouch or Biscuit). SAM revokes by expiry or manual deletion.
-
-**Relay**: Node that forwards traffic between peers that cannot connect directly.
-
-## S
-
-**SAM**: Sovereign Agent Mesh. Zero-trust P2P networking for agents.
-
-**Schema**: Structure definition (e.g., Agent Card schema, vouch schema).
-
-**Secret**: Sensitive data (private keys, credentials). Always protected.
-
-**Signature**: Cryptographic proof that something was signed by a key. Ed25519 signatures in SAM.
-
-**Skill**: Capability offered by an agent (e.g., "weather-bot", "risk-audit").
-
-**Sovereign**: Having control over one's own identity and operations (not delegated to a central authority).
-
-**Stream**: Bidirectional connection over libp2p for A2A communication.
-
-**Subject**: Entity that holds a credential (username, email, etc.).
-
-## T
-
-**Token**: Credential granted to an agent. In SAM: vouch (identity) or Biscuit (authorization).
-
-**TLS**: Transport Layer Security. Encryption used by libp2p for all connections.
-
-**Timeout**: Maximum time to wait for an operation.
-
-**Trust Desert**: Problem where agents operate without trust, in systems with central gatekeepers.
-
-**Trustworthy**: An agent with good reputation (future feature).
-
-## U
-
-**UID**: User ID, usually a number (not used in SAM; uses usernames/emails).
-
-**UUID**: Universally Unique Identifier. SAM derives deterministic IDs from usernames.
-
-**Unencrypted**: Not encrypted. SAM never sends unencrypted credentials (uses TLS).
-
-## V
-
-**Voucher**: Component that manages vouch lifecycle.
-
-**Vouch**: Cryptographic credential proving membership in a federation. Issued by hub, cached locally.
-
-**Verify**: Cryptographic check that something is valid (signature, expiry, etc.).
-
-## W
-
-**Whitelist**: List of allowed peers or skills. SAM uses Biscuit caveats for skill whitelists.
-
-**WebSocket**: Protocol for connections over HTTP. Used by libp2p for firewall traversal.
-
-## X
-
-**X.509**: Standard for digital certificates (not used in SAM; uses Ed25519 keys).
-
-## Y
-
-**YAML**: Configuration format (not used in SAM; uses CLI flags and JSON).
-
-## Z
-
-**Zero-Trust**: Security model where no entity is trusted by default. Everything must prove legitimacy. SAM's core philosophy.
-
----
-
-## Acronyms Quick Reference
-
-| Acronym | Full Name |
-|---------|-----------|
-| A2A | Agent-to-Agent |
-| BATS | Bash Automated Testing System |
-| DCUtR | Direct Connection UpgRade |
-| DHT | Distributed Hash Table |
-| Ed25519 | Elliptic Curve Signature Scheme |
-| GOPATH | Go Package Path |
-| gRPC | Google Remote Procedure Call |
-| HSM | Hardware Security Module |
-| ICE | Interactive Connectivity Establishment |
-| IdP | Identity Provider |
-| JSON | JavaScript Object Notation |
-| KMS | Key Management Service |
-| LDAP | Lightweight Directory Access Protocol |
-| MCP | Model Context Protocol |
-| NAT | Network Address Translation |
-| OIDC | OpenID Connect |
-| P2P | Peer-to-Peer |
-| PeerID | Peer Identifier |
-| QUIC | Quick UDP Internet Connection |
-| RPC | Remote Procedure Call |
-| SAM | Sovereign Agent Mesh |
-| TLS | Transport Layer Security |
-| UUID | Universally Unique Identifier |
-
----
-
-## See Also
-
-- **[Concepts](#/concepts/federation.md)**: Technical deep dives
-- **[FAQ](#/faq.md)**: Common questions answered
-- **[CLI Reference](#/cli/reference.md)**: Command documentation
diff --git a/docs/guides/dark-mesh.md b/docs/guides/dark-mesh.md
deleted file mode 100644
index 54bf1814..00000000
--- a/docs/guides/dark-mesh.md
+++ /dev/null
@@ -1,101 +0,0 @@
-# Dark Mesh: End-to-End Walkthrough
-
-This guide shows a full SAM flow using passport-based authentication and Biscuit capability authorization.
-
-## Scenario
-
-- Team A publishes a private capability (`risk-audit`).
-- Team B discovers and calls it.
-- All traffic remains peer-to-peer.
-
-## Step 1: Start a Node
-
-```bash
-sam-agent up --dht-mode server
-```
-
-Keep this running in one terminal.
-
-## Step 2: Authenticate Identity
-
-In another terminal:
-
-```bash
-sam-agent identity login --hub https://identity.example.com
-sam-agent identity whoami
-```
-
-This stores local credentials and a passport biscuit.
-
-## Step 3: Publish a Capability
-
-Assuming your MCP server is on `:8080`:
-
-```bash
-sam-agent publish --skill risk-audit --mcp-port 8080
-```
-
-Optional safety preview:
-
-```bash
-sam-agent publish --skill risk-audit --mcp-port 8080 --dry-run=client
-```
-
-## Step 4: Discover Agents
-
-```bash
-sam-agent mesh get agents
-sam-agent mesh get agents --capability risk-audit -o json
-```
-
-## Step 5: Call the Capability
-
-```bash
-sam-agent call risk-audit --message "audit this report"
-```
-
-Optional request validation:
-
-```bash
-sam-agent call risk-audit --message "audit this report" --dry-run=client
-```
-
-## Step 6: Audit Artifacts
-
-```bash
-sam-agent inspect biscuit "partner-bot;allow_skill=risk-audit"
-sam-agent inspect card '{"peer_id":"...","agent_card":{...}}'
-```
-
-## Troubleshooting
-
-1. No peers found:
-
-```bash
-sam-agent mesh get agents --watch
-```
-
-2. Unauthorized errors:
-
-```bash
-sam-agent identity whoami
-sam-agent identity login --hub https://identity.example.com
-```
-
-3. Connectivity issues:
-
-```bash
-sam-agent up --relay-service --run-for 30s
-```
-
-4. Detailed logs:
-
-```bash
-SAM_DEBUG=1 sam-agent call risk-audit --message "test"
-```
-
-## Security Notes
-
-- Identity authentication is passport-based at peer establishment time.
-- Authorization remains capability-scoped via Biscuit caveats.
-- Runtime uses a fixed default mesh namespace.
diff --git a/docs/guides/hub-key-management.md b/docs/guides/hub-key-management.md
deleted file mode 100644
index eb5e55e2..00000000
--- a/docs/guides/hub-key-management.md
+++ /dev/null
@@ -1,251 +0,0 @@
-# Hub Key Management
-
-The SAM hub manages two types of Ed25519 keys:
-
-1. **Signing Key**: Used to digitally sign identity biscuits (passports)
-2. **Identity/TLS Key**: Used for the hub's libp2p peer identity and TLS handshakes (when running with `--enable-p2p`)
-
-## Key Generation
-
-Generate both keys:
-
-```bash
-sam-hub keygen --with-identity
-```
-
-Output example:
-
-```
-=== Passport Signing Key (Ed25519) ===
-Purpose: Sign identity biscuits
-Environment: SAM_HUB_KEY
-
-Private Key (base64):
-4XkwpAJ0C9vqXkL...
-
-Public Key (base64, published at /.well-known/sam-hub-keys):
-GvK2pxM9d3sY8zL...
-
-=== Hub Peer Identity Key (Ed25519 for libp2p TLS) ===
-Purpose: Hub's libp2p peer identity and TLS handshakes
-Environment: SAM_HUB_IDENTITY_KEY
-
-Private Key (base64):
-AwV3dY7pQ4sL2xN...
-
-Public Key (base64):
-B1Z5cX8mR6wL3yO...
-
-Hub Peer ID: Use 'sam-hub serve --enable-p2p' to print the peer ID
-Configure as bootstrap: --bootstrap /ip4/HUB_IP/udp/PORT/quic-v1/p2p/PEER_ID
-```
-
-## Configuration
-
-### HTTP-Only Mode (No libp2p)
-
-Suitable for cloud deployments behind a load balancer:
-
-```bash
-# Development (uses deterministic seed)
-sam-hub serve --http-listen :8081
-
-# Production (with custom signing key)
-export SAM_HUB_KEY="4XkwpAJ0C9vqXkL..."
-sam-hub serve --http-listen 0.0.0.0:8081
-```
-
-### P2P Rendezvous Mode
-
-Enable the hub as a DHT bootstrap/rendezvous point:
-
-```bash
-# Development (generates ephemeral peer identity)
-sam-hub serve --enable-p2p
-
-# Production (with configured keys)
-export SAM_HUB_KEY="4XkwpAJ0C9vqXkL..."
-export SAM_HUB_IDENTITY_KEY="AwV3dY7pQ4sL2xN..."
-sam-hub serve \
- --http-listen 0.0.0.0:8081 \
- --p2p-listen /ip4/0.0.0.0/udp/9000/quic-v1,/ip4/0.0.0.0/tcp/9001 \
- --enable-p2p
-```
-
-After startup, the hub prints its peer ID and multiaddrs:
-
-```
-=== libp2p Host ===
-Peer ID: 12D3KooWJqYwgPjYqC6Y3...
-
-Multiaddrs:
- /ip4/10.0.0.5/udp/9000/quic-v1/p2p/12D3KooWJqYwgPjYqC6Y3...
- /ip4/10.0.0.5/tcp/9001/p2p/12D3KooWJqYwgPjYqC6Y3...
-```
-
-Share these with agents as bootstrap peers.
-
-## Key Rotation
-
-### Signing Key Rotation
-
-When rotating the signing key:
-
-1. Generate a new key: `sam-hub keygen`
-2. Update `SAM_HUB_KEY` in your deployment
-3. Restart the hub gracefully
-4. Agents automatically fetch the new public key from `/.well-known/sam-hub-keys`
-
-Existing passports remain valid (keep the old key for verification if needed).
-
-### Identity Key Rotation
-
-When rotating the libp2p identity key:
-
-1. Generate a new key: `sam-hub keygen --with-identity`
-2. Update `SAM_HUB_IDENTITY_KEY` in your deployment
-3. Restart the hub
-4. Update agent bootstrap peer configuration with the new peer ID and multiaddrs
-
-This changes the hub's peer ID, so agents must reconfigure.
-
-## Security Practices
-
-### Key Storage
-
-- **Use secrets management**: Kubernetes Secrets, AWS Secrets Manager, HashiCorp Vault, etc.
-- **Encrypt at rest**: Ensure key material is encrypted when stored
-- **Restrict access**: Only the hub process should have access to private keys
-- **Audit logging**: Log all key operations and passport issuance
-
-Example Kubernetes Secret:
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
- name: sam-hub-keys
-type: Opaque
-stringData:
- SAM_HUB_KEY: |
- 4XkwpAJ0C9vqXkL...
- SAM_HUB_IDENTITY_KEY: |
- AwV3dY7pQ4sL2xN...
-```
-
-### Key Rotation Schedule
-
-- **Signing key**: Rotate annually or after suspected compromise
-- **Identity key**: Rotate on topology changes or annually
-- **Emergency rotation**: If a key is suspected compromised, rotate immediately
-
-### TLS Specifics
-
-libp2p uses **certificate-based TLS** with Ed25519 keys:
-- The private key signs the TLS certificate
-- Certificates are self-signed and ephemeral
-- The public key is derived from the private key
-- No external CA or X.509 infrastructure needed
-
-For **FIPS compliance**, ensure Go is compiled with `GOEXPERIMENT=boringcrypto` and libp2p's TLS security transport is the only configured security transport.
-
-## Client-Side Verification
-
-Agents verify biscuit signatures using the hub's public signing key. The key is published at:
-
-```bash
-curl https://hub.example.com/.well-known/sam-hub-keys
-```
-
-Response:
-
-```json
-{
- "issuer": "app.sam-mesh.dev",
- "keys": [
- {
- "kid": "sam-hub-root-v1",
- "alg": "Ed25519",
- "k": "GvK2pxM9d3sY8zL..."
- }
- ]
-}
-```
-
-Clients cache this public key for offline verification without requiring network calls.
-
-## Troubleshooting
-
-### Invalid Key Format
-
-Error: `decoding SAM_HUB_KEY: illegal base64 data at input byte`
-
-- Ensure keys are base64url-encoded (no padding)
-- Use `sam-hub keygen` to generate properly formatted keys
-
-### Peer ID Mismatch
-
-Error: `passport peer mismatch` or `passport authentication failed`
-
-- Verify the hub is using the correct signing key
-- Ensure all hub instances (if load-balanced) use the same signing key
-- Check agents are fetching the correct public key from `/.well-known/sam-hub-keys`
-
-### Bootstrap Connection Failed
-
-Error: `connecting to hub bootstrap peer: ...`
-
-- Verify the peer ID and multiaddrs are correct
-- Check hub is reachable at the advertised address
-- Ensure TLS/QUIC connections are not blocked by firewalls
-
-## Integration with Kubernetes
-
-```yaml
-apiVersion: v1
-kind: Secret
-metadata:
- name: sam-hub-keys
-type: Opaque
-stringData:
- SAM_HUB_KEY: 4XkwpAJ0C9vqXkL...
- SAM_HUB_IDENTITY_KEY: AwV3dY7pQ4sL2xN...
-
----
-
-apiVersion: apps/v1
-kind: Deployment
-metadata:
- name: sam-hub
-spec:
- replicas: 1
- template:
- spec:
- containers:
- - name: hub
- image: sam-hub:latest
- args:
- - serve
- - --http-listen=0.0.0.0:8081
- - --p2p-listen=/ip4/0.0.0.0/udp/9000/quic-v1,/ip4/0.0.0.0/tcp/9001
- - --enable-p2p
- env:
- - name: SAM_HUB_KEY
- valueFrom:
- secretKeyRef:
- name: sam-hub-keys
- key: SAM_HUB_KEY
- - name: SAM_HUB_IDENTITY_KEY
- valueFrom:
- secretKeyRef:
- name: sam-hub-keys
- key: SAM_HUB_IDENTITY_KEY
- ports:
- - containerPort: 8081
- name: http
- - containerPort: 9000
- protocol: UDP
- name: p2p-quic
- - containerPort: 9001
- name: p2p-tcp
-```
diff --git a/docs/guides/hub-rendezvous.md b/docs/guides/hub-rendezvous.md
deleted file mode 100644
index 9957c18a..00000000
--- a/docs/guides/hub-rendezvous.md
+++ /dev/null
@@ -1,61 +0,0 @@
-# Hub as Rendezvous Point
-
-SAM uses the configured hub's hostname as the discovery namespace scope for peer capability advertisements. This enables:
-
-1. **Capability Namespace Scoping**: All peer capability announcements are registered under `<hub-hostname>/<capability>` in the DHT.
-2. **Centralized Discovery Index**: When agents discover peers by capability, they query the DHT for records under the hub's namespace.
-3. **Bootstrap Topology**: To make the hub act as an active rendezvous point, configure it as a bootstrap peer so all agents connect to it during startup.
-
-## Configuration
-
-### CLI Usage
-
-Set the hub and optionally bootstrap peers:
-
-```bash
-sam-agent up \
- --hub https://identity.example.com \
- --bootstrap /ip4/<hub-ip>/udp/0/quic-v1/p2p/<hub-peer-id> \
- ...
-```
-
-When `--hub` is provided without an explicit bootstrap address, the CLI uses the hub's hostname as the rendezvous namespace default.
-
-### Programmatic Usage
-
-```go
-import samnet "sam/pkg/net"
-
-// Hub hostname becomes the rendezvous namespace
-node, err := samnet.New(
- samnet.WithRendezvousNamespace("identity.example.com"),
- samnet.WithBootstrapPeers(/* hub peer multiaddr */),
- // ...
-)
-```
-
-## Hub Architecture
-
-The hub (sam-hub) currently provides:
-- HTTP endpoint for passport issuance (`:8081/issue-passport`)
-- Health and metadata endpoints
-- Future: optional libp2p host for direct rendezvous protocol support
-
-To upgrade the hub to a full rendezvous server:
-1. Add a libp2p host to sam-hub/main.go
-2. Export the hub's peer ID and addresses for agent bootstrap configuration
-3. Implement rendezvous protocol handlers for registration/discovery
-
-## Discovery Flow
-
-```
-Agent A:
- 1. Connect to hub (bootstrap peer)
- 2. Announce capability: /sam/fed/default/<hub-hostname>/my-skill
-
-Agent B:
- 1. Connect to hub (bootstrap peer)
- 2. Discover capability: /sam/fed/default/<hub-hostname>/my-skill
- 3. Find Agent A in DHT results
- 4. Connect and authenticate via /sam/auth/1.0.0
-```
diff --git a/docs/guides/hybrid-intelligence.md b/docs/guides/hybrid-intelligence.md
deleted file mode 100644
index 54e209a7..00000000
--- a/docs/guides/hybrid-intelligence.md
+++ /dev/null
@@ -1,172 +0,0 @@
-# Hybrid Intelligence Audit
-
-## Problem
-
-You have sensitive local data (contracts, internal code, regulated documents) that cannot be uploaded to cloud LLMs, but you still need high-quality reasoning against public and constantly changing sources.
-
-The target workflow is:
-
-1. Read and sanitize private documents locally.
-2. Pull current public policy/specification data from the web.
-3. Synthesize one final audit report.
-
-## Architecture: Hybrid Research Assistant
-
-- Private Core: local `llama-server` processes sensitive files.
-- Public Edge: Gemini 1.5 Pro (via LangChain) handles broad reasoning and web context.
-- Connective Tissue: SAM provides secure peer-to-peer discovery and A2A transport so private data paths stay under your control.
-
-```text
-Private Files -> Local MCP Tool (llama-server) -> Sanitized Summary ----+
- |
-Public Web/Data -> Public MCP (Firecrawl or docs source) -> Evidence ----+-> Gemini Synthesis
- |
- Orchestrated by LangChain --+
-```
-
-## Step 1: Spin Up the Private Brain (llama-server)
-
-Start your local model service:
-
-```bash
-./llama-server -m ./models/llama-3-8b.gguf --port 8080 --webui-mcp-proxy
-```
-
-Publish that local MCP capability into SAM.
-
-Important: in SAM, the access scope for files is enforced by your local MCP tool configuration, not by `sam publish` flags.
-
-```bash
-# Start a node for this workflow
-sam up &
-
-# Publish a private-docs capability backed by local MCP on :8080
-sam publish mcp \
- --capability private-docs \
- --resource-name private-docs \
- --resource-kind tool \
- --port 8080
-```
-
-If you need a safety check before publishing network-visible state:
-
-```bash
-sam publish --skill private-docs --mcp-port 8080 --dry-run=client
-```
-
-## Step 2: Orchestrate with LangChain + Gemini
-
-LangChain acts as the director:
-
-- route private reads/summarization to local SAM capability
-- route public retrieval to a public MCP/web source
-- send only sanitized output to Gemini for final synthesis
-
-Example scaffold:
-
-```python
-from langchain_google_genai import ChatGoogleGenerativeAI
-
-# NOTE:
-# - SAM CLI is request/response; for production orchestration, run a small adapter
-# service that exposes SAM calls as an MCP server transport for LangChain.
-# - The snippet below focuses on control flow, not adapter implementation details.
-
-llm = ChatGoogleGenerativeAI(model="gemini-1.5-pro")
-
-private_summary = """
-[From local private-docs capability]
-Contract summary (sanitized):
-- no personal names
-- no raw clauses copied
-- extracted obligations and controls only
-"""
-
-public_evidence = """
-[From public retrieval]
-Latest EU AI Act obligations for high-risk systems...
-"""
-
-prompt = f"""
-You are auditing compliance.
-
-Private sanitized summary:
-{private_summary}
-
-Public legal evidence:
-{public_evidence}
-
-Return:
-1) compliance gaps
-2) required remediation
-3) confidence and citations
-"""
-
-result = llm.invoke(prompt)
-print(result.content)
-```
-
-## Step 3: End-to-End User Journey
-
-1. Local Filter
-The private document is processed locally by your `private-docs` capability. The output is sanitized (PII removed, trade secrets abstracted, sensitive literals redacted).
-
-2. Public Search
-Your public retrieval tool fetches current sources (official policy, docs, standards, legal text).
-
-3. Sovereign Synthesis
-Gemini receives only the sanitized private summary plus public evidence and generates the final audit report.
-
-Result: high-quality analysis, with raw private source files never sent to cloud inference.
-
-## Why This Pattern Wins
-
-- Data residency by design: easiest path for GDPR/HIPAA-style constraints.
-- Cost efficiency: local model does heavy extraction; cloud model does higher-value synthesis.
-- Low infrastructure overhead: SAM supports direct peer connectivity without central gateway dependency.
-
-## Security Controls Checklist
-
-- Use a dedicated environment/profile for this workflow.
-- Prefer least-privilege capabilities (`private-docs`, not broad wildcard tools).
-- Use Biscuit caveats for tool restrictions (for example, allow only `private-docs`).
-- Audit tokens and cards before execution:
-
-```bash
-sam inspect biscuit "auditor-bot;allow_skill=private-docs"
-sam inspect card '{"peer_id":"...","agent_card":{...}}'
-sam call private-docs --message "summarize" --dry-run=client
-```
-
-## BATS E2E Test Skeleton
-
-```bash
-@test "E2E: Hybrid audit keeps secret local" {
- sam up &
-
- echo "Secret: Don't tell the cloud" > /tmp/secret.txt
-
- # Assume local MCP tool on :8080 is configured to read /tmp only
- sam publish mcp \
- --capability private-docs \
- --resource-name private-docs \
- --port 8080 &
-
- run python3 ./scripts/hybrid_test.py
-
- assert_output --partial "Summary of document"
- refute_output --partial "Don't tell the cloud"
-}
-```
-
-## Operational Notes
-
-- `sam publish mcp` exposes an MCP endpoint reachable through SAM; it does not configure filesystem ACLs.
-- Keep your local MCP implementation responsible for strict path allowlists.
-- For reproducibility, pin model version and prompt templates used for sanitization.
-
-## Next Steps
-
-- Read [CLI Reference](../cli/reference.md) for exact command flags.
-- Read [Biscuit Authorization](../concepts/biscuit.md) for capability caveats.
-- Read [Testing Guide](../testing.md) to integrate this flow into CI.
diff --git a/docs/index.html b/docs/index.html
index 53b89e37..122683f0 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -72,7 +72,7 @@
// Documentation settings
loadSidebar: true,
loadNavbar: false,
- coverpage: true,
+ coverpage: false,
auto2top: true,
// Search plugin
diff --git a/docs/quickstart.md b/docs/quickstart.md
index dab4d20c..dd3301cb 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -1,147 +1,64 @@
-# Quick Start Reference
+# Quick Start
-## Installation
+## Prerequisites
+
+- Go toolchain
+- Docker (for containerized e2e tests)
+- BATS (`bats-core`)
+
+## Build
```bash
git clone https://github.com/aojea/sam.git
cd sam
make build
-./bin/sam-agent --help
```
-## First Steps (5 Minutes)
+This creates:
-### 1. Authenticate
+- `./bin/sam-hub`
+- `./bin/sam-node`
-```bash
-sam-agent identity login --hub https://identity.example.com
-```
+## Start Hub
-### 2. Publish an Agent
+`sam-hub` requires OIDC issuer settings and a 32-byte hex key seed.
```bash
-# Start a local MCP server on port 8080
-sam-agent publish --skill my-skill --mcp-port 8080
+SAM_OIDC_ISSUER=https://issuer.example.com \
+SAM_OIDC_ID=sam-client \
+SAM_OIDC_SECRET=sam-secret \
+SAM_HUB_KEY=$(openssl rand -hex 32) \
+./bin/sam-hub
```
-### 3. Call an Agent
+## Login Node
```bash
-sam-agent call my-skill --message "Do something"
+./bin/sam-node login --hub http://localhost:8080
```
----
+The command prints a browser login URL and asks you to paste the identity biscuit token.
-## Common Commands
+## Run Node
-### Mesh
+Using stored identity:
```bash
-# Get visible agents
-sam-agent mesh get agents
-
-# Watch new agents in real time
-sam-agent mesh get agents --watch
+./bin/sam-node run
```
-### Identity
+Or using explicit token:
```bash
-# Show current identity
-sam-agent identity whoami
-
-# Re-authenticate
-sam-agent identity login --hub https://identity.example.com
+./bin/sam-node run --token <identity-biscuit>
```
-### Publishing and Calling
+## Test
```bash
-# Publish with dry-run (no network)
-sam-agent publish --skill test --mcp-port 8080 --dry-run=client
-
-# Call with dry-run (no network)
-sam-agent call test --message "hello" --dry-run=client
-
-# Call with custom Biscuit token
-sam-agent call test --message "hello" --biscuit "user;allow_skill=test"
+make test
+make test-e2e
+make test-e2e-container
```
-### Auditing
-
-```bash
-# Inspect a Biscuit token
-sam-agent inspect biscuit "alice;allow_skill=weather-bot"
-
-# Inspect an Agent Card
-sam-agent inspect card '{"peer_id":"...","agent_card":{...}}'
-```
-
----
-
-## Global Flags
-
-```bash
---debug Enable debug logging
-```
-
----
-
-## File Locations
-
-```
-~/.config/sam/
-β”œβ”€β”€ identity/
-β”‚ └── credentials.json (hub/device credentials and passport biscuit)
-└── federations/
- └── default.db (default mesh state database)
-```
-
----
-
-## Troubleshooting
-
-| Issue | Solution |
-|-------|----------|
-| "passport expired" | `sam-agent identity login --hub <url>` |
-| "skill not allowed" | Check Biscuit token: `sam-agent inspect biscuit <token>` |
-| "no peers found" | Publish agent first: `sam-agent publish --skill <name> --mcp-port <port>` |
-| "connection timeout" | Check network: `sam-agent up --run-for 30s` |
-
----
-
-## Key Concepts
-
-**Passport Biscuit**: Hub-issued identity credential bound to peer ID and default federation audience.
-
-**Biscuit**: Skill-access credential, plain-text format `subject;allow_skill=X,Y,Z`.
-
-**Agent Card**: Signed manifest of skills published to DHT.
-
-**A2A**: Agent-to-agent RPC protocol over libp2p.
-
----
-
-## Documentation
-
-- **[Overview](#/README.md)**: What SAM is and why it matters
-- **[User Journey](#/guides/dark-mesh.md)**: Step-by-step walkthrough
-- **[CLI Reference](#/cli/reference.md)**: Full command documentation
-- **[Testing](#/testing.md)**: How to run and write tests
-- **[FAQ](#/faq.md)**: Common questions
-- **[Glossary](#/glossary.md)**: Terminology reference
-
----
-
-## Help
-
-```bash
-# Any command help
-sam-agent <command> --help
-
-# Verbose logging
-SAM_DEBUG=1 sam-agent <command>
-
-# Report bugs
-https://github.com/aojea/sam/issues
-```
+`make test-e2e-container` runs hub + multiple node containers with a mock OIDC provider.
diff --git a/docs/testing.md b/docs/testing.md
index 5516de35..3f08f60b 100644
--- a/docs/testing.md
+++ b/docs/testing.md
@@ -1,426 +1,80 @@
-# Testing Guide: Validating SAM
+# Testing
-SAM has comprehensive test coverage across three levels:
+Current testing is intentionally minimal and aligned with the current binaries.
-1. **Unit Tests** (Go): Pure function testing
-2. **Integration Tests** (Go): Multi-node scenarios with namespaces
-3. **E2E Tests** (BATS): CLI validation and user workflows
+## Test Layers
----
+1. Go tests: `make test`
+2. BATS CLI tests: `make test-e2e`
+3. Containerized BATS mesh tests: `make test-e2e-container`
-## Test Architecture
-
-### Test Isolation
-
-Tests use **Linux user namespaces** to isolate network state:
-
-```go
-func TestA2ACall(t *testing.T) {
- // Each test runs in CLONE_NEWNET namespace
- // Network stack is isolated
- // DHT doesn't interfere with other tests
- testutils.Run(t, f, testutils.CLONE_NEWNET)
-}
-```
-
-**Benefits:**
-
-- No test pollution (each test has clean network)
-- Can run tests in parallel
-- Can simulate network conditions (no connectivity, firewall)
-- Each test cleanup is automatic
-
-### Test Levels
-
-```
-β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
-β”‚ E2E Tests (BATS) β”‚
-β”‚ - CLI commands β”‚
-β”‚ - User workflows β”‚
-β”‚ - Dry-run and inspect β”‚
-β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
- ↓
-β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
-β”‚ Integration Tests (Go) β”‚
-β”‚ - Multi-node scenarios β”‚
-β”‚ - DHT discovery β”‚
-β”‚ - A2A calls β”‚
-β”‚ - Federation isolation β”‚
-β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
- ↓
-β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
-β”‚ Unit Tests (Go) β”‚
-β”‚ - Biscuit parsing β”‚
-β”‚ - Vouch verification β”‚
-β”‚ - Card encoding/decoding β”‚
-β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜
-```
-
----
-
-## Unit Tests
-
-Unit tests validate individual components in isolation.
-
-### Running Unit Tests
+## Commands
```bash
-# Run all unit tests
-go test ./...
-
-# Run with race detection
-go test -race ./...
-
-# Run specific package
-go test ./pkg/economy
-
-# Run specific test
-go test -run TestParseBiscuit ./pkg/economy
-
-# Show coverage
-go test -cover ./...
-
-# Generate coverage report
-go test -coverprofile=coverage.out ./...
-go tool cover -html=coverage.out
-```
-
-### Key Test Files
-
-| Package | Tests | Purpose |
-|---------|-------|---------|
-| `pkg/economy` | `TestParseBiscuit`, `TestCheckSkill` | Biscuit token parsing and skill verification |
-| `pkg/protocol` | `TestAgentCard`, `TestDiscovery` | Agent card encoding/decoding, peer discovery |
-| `pkg/net` | `TestNodeStart`, `TestDHT` | Node lifecycle, DHT initialization |
-| `pkg/identity` | `TestVouchVerify`, `TestVouchExpiry` | Vouch signature and expiry checks |
-
-### Example Unit Test
-
-```go
-func TestParseBiscuit(t *testing.T) {
- parser := economy.SimpleBiscuitParser{}
-
- // Test simple biscuit
- ctx := context.Background()
- parsed, err := parser.Parse(ctx, "alice;allow_skill=weather-bot")
-
- if err != nil {
- t.Fatalf("Parse failed: %v", err)
- }
- if parsed.Subject != "alice" {
- t.Errorf("Expected subject 'alice', got %q", parsed.Subject)
- }
- if len(parsed.AllowedSkills) != 1 {
- t.Errorf("Expected 1 skill, got %d", len(parsed.AllowedSkills))
- }
- if parsed.AllowedSkills[0] != "weather-bot" {
- t.Errorf("Expected 'weather-bot', got %q", parsed.AllowedSkills[0])
- }
-}
-```
-
----
-
-## Integration Tests
-
-Integration tests validate multi-node scenarios with network isolation.
-
-### Running Integration Tests
-
-```bash
-# Run all integration tests
-go test -race -count=1 ./tests/integration
-
-# Run specific test
-go test -race -count=1 -run TestCUJ1 ./tests/integration
-
-# Verbose output
-go test -race -count=1 -v ./tests/integration
-
-# Timeout (integration tests can take 30-60s)
-go test -race -timeout=5m -count=1 ./tests/integration
-```
-
-### Key Integration Tests
-
-| Test | Time | Purpose |
-|------|------|---------|
-| `TestCUJ1Stealth` | 45s | Federation DHT isolation (dark mesh) |
-| `TestCUJ2HolePunch` | 60s | Relay-assisted connectivity (DCUtR) |
-| `TestA2ACall` | 30s | Agent-to-agent RPC with Biscuit auth |
-| `TestMeshDHT` | 40s | Multi-federation discovery |
-
-### Example Integration Test
-
-```go
-func TestCUJ1StealthAudit(t *testing.T) {
- // Run in isolated network namespace
- testutils.Run(t, func(f *testutils.Framework) {
- // Create two federations: alpha, beta
- alphaA, _ := cujStartNode(t, f, "alpha", "alpha-a")
- alphaB, _ := cujStartNode(t, f, "alpha", "alpha-b")
- betaA, _ := cujStartNode(t, f, "beta", "beta-a")
-
- // Wait for DHT convergence
- cujWaitDiscover(t, alphaA, alphaB.PeerID(), 10*time.Second)
-
- // Alpha agents should discover each other
- _, err := alphaA.Discover(alphaB.PeerID())
- if err != nil {
- t.Fatalf("alphaA should discover alphaB: %v", err)
- }
-
- // But Beta agent should NOT discover Alpha agents
- // (federation isolation enforced at DHT level)
- _, err = betaA.Discover(alphaA.PeerID())
- if err == nil {
- t.Fatalf("betaA should NOT discover alphaA (federation isolation)")
- }
- }, testutils.CLONE_NEWNET)
-}
-```
-
-### Test Framework Helpers
-
-The `testutils` package provides helpers for integration tests:
-
-```go
-// Start a node in a federation
-node, _ := cujStartNode(t, f, federationID, nodeName)
-
-// Wait for node to discover a peer
-cujWaitDiscover(t, node, targetPeerID, timeout)
-
-// Get relay circuit address for NAT traversal
-circuit := cujRelayCircuitAddr(t, f, relayNode, targetNode)
-
-// Wait for direct connection (DCUtR holepunch)
-cujWaitForDirectConn(t, node1, node2, timeout)
-
-// Bootstrap addresses
-addrs := cujBootstrapAddrs(f, bootstrapNode)
-```
-
----
-
-## E2E Tests (BATS)
-
-E2E tests use BATS (Bash Automated Testing System) to validate CLI commands.
-
-### Running E2E Tests
-
-```bash
-# Build binary first
make build
-
-# Run all E2E tests
+make test
make test-e2e
-
-# Run with verbose output
-SAM_BINARY=./bin/sam bats --verbose-run tests/e2e/sam.bats
-
-# Run specific test
-SAM_BINARY=./bin/sam bats --filter "sam inspect" tests/e2e/sam.bats
+make test-e2e-container
```
-### Key E2E Tests
-
-| Test | Purpose |
-|------|---------|
-| `sam up --help` | Verify help output |
-| `sam publish --help` | Verify publish command |
-| `sam inspect biscuit` | Parse and explain Biscuit token |
-| `sam publish --dry-run=client` | Build card without network |
-| `sam call --dry-run=client` | Validate call without network |
-| `sam inspect card` | Decode Agent Card JSON |
+## Go Tests
-### Example BATS Test
+Run all Go tests with race detection:
```bash
-@test "sam inspect biscuit parses and explains a token" {
- token="alice;allow_skill=risk-audit,weather-bot"
- run "$SAM_BINARY" inspect biscuit "$token"
-
- # Assertion: command succeeded
- [[ "$status" -eq 0 ]]
-
- # Assertion: output contains subject
- [[ "$output" == *"alice"* ]]
-
- # Assertion: output contains skills
- [[ "$output" == *"risk-audit"* ]]
- [[ "$output" == *"weather-bot"* ]]
-}
+make test
```
-### BATS Syntax
+Run only integration package:
```bash
-# Run command (output in $output, exit code in $status)
-run "$SAM_BINARY" command arg1 arg2
-
-# Assertions
-[[ "$status" -eq 0 ]] # Exit code is 0 (success)
-[[ "$output" == *"text"* ]] # Output contains text
-[[ "$output" =~ ^regex$ ]] # Output matches regex
-[[ ! "$output" =~ pattern ]] # Output does NOT match pattern
+go test ./tests/integration/...
```
----
+## BATS CLI Tests
-## Running Full Test Suite
+These tests validate current command behavior for:
-### Quick Test Run
+- `sam-node`
+- `sam-hub`
-```bash
-# Unit tests only (fast, ~10s)
-go test ./...
-
-# With race detection
-go test -race ./...
-```
-
-### Full Suite
+Run:
```bash
-# Everything: unit + integration + E2E
-make test
-
-# What make test does:
-# 1. go test -race -count=1 ./... (unit + integration, ~60s)
-# 2. make build (compile binary)
-# 3. bats tests/e2e/sam.bats (E2E tests, ~30s)
-```
-
-### Expected Output
-
-```
-go test -race -count=1 ./...
-ok sam 89.234s (82 tests passed)
-
-make build
-go build -v -o ./bin/sam ./cmd/sam
-
-SAM_BINARY=./bin/sam bats --verbose-run tests/e2e/sam.bats
- βœ“ sam up --help returns success
- βœ“ sam publish --help returns success
- βœ“ sam inspect biscuit parses token
- ...
-12 tests, 0 failures
+make test-e2e
```
----
-
-## Contributing: Test Requirements
-
-When submitting a PR, ensure:
-
-1. **All unit tests pass**
- ```bash
- go test -race ./...
- ```
+## Containerized Mesh BATS
-2. **No race conditions**
- ```bash
- go test -race ./...
- ```
+The container framework is implemented in:
-3. **All integration tests pass**
- ```bash
- go test -race -count=1 ./tests/integration
- ```
+- `tests/e2e/lib/container_mesh.bash`
-4. **All E2E tests pass**
- ```bash
- make test-e2e
- ```
+It starts:
-5. **New features have tests**
- - Add unit test in same package
- - Add integration test if multi-node
- - Add BATS test if CLI-facing
+1. mock OIDC container
+2. `sam-hub` container
+3. multiple `sam-node` containers
-### Test Checklist
+Run:
```bash
-# Before submitting PR
-make test # Full suite
-go test -race ./... # Explicit race check
-go test -cover ./... # Check coverage
+make test-e2e-container
```
----
-
-## Performance Testing
-
-### Benchmarking
+Optional image override:
```bash
-# Run benchmarks
-go test -bench=. ./pkg/economy
-
-# Benchmark with memory stats
-go test -bench=. -benchmem ./pkg/economy
-
-# CPU profile
-go test -bench=. -cpuprofile=cpu.prof ./pkg/economy
-go tool pprof cpu.prof
-
-# Memory profile
-go test -bench=. -memprofile=mem.prof ./pkg/economy
-go tool pprof mem.prof
-```
-
-### Example Benchmark
-
-```go
-func BenchmarkParseBiscuit(b *testing.B) {
- parser := economy.SimpleBiscuitParser{}
- ctx := context.Background()
- token := "alice;allow_skill=weather-bot,risk-audit"
-
- b.ResetTimer()
- for i := 0; i < b.N; i++ {
- _, _ = parser.Parse(ctx, token)
- }
-}
+MESH_RUNTIME_IMAGE=sam-e2e-runtime:dev make test-e2e-container
```
----
-
-## Debugging Tests
+## Troubleshooting
-### Verbose Output
+- Ensure Docker daemon is running before container tests.
+- Ensure `bats` is installed and available in `PATH`.
+- If a test fails, inspect containers:
```bash
-# See all log output
-go test -v ./tests/integration
-
-# With debug flag
-SAM_DEBUG=1 go test -v ./...
-```
-
-### GDB Debugging
-
-```bash
-# Run test with GDB
-dlv test ./pkg/protocol -- -test.run TestAgentCard
-```
-
-### Print Debugging
-
-```go
-import "fmt"
-
-func TestExample(t *testing.T) {
- fmt.Printf("Debug: value=%v\n", someValue)
-}
+docker ps -a
+docker logs <container-name>
```
-
----
-
-## Next Steps
-
-- **[Quick Start](#/guides/dark-mesh.md)**: Set up SAM locally
-- **[CLI Reference](#/cli/reference.md)**: Test with real commands
-- **[Contributing](#/contributing.md)**: Submit a test PR