Skip to content

Agent Mesh

add readme

Antonio Ojeac14932c78201
diff --git a/README.md b/README.md
index 2881b24d..e57a9cf0 100644
--- a/README.md
+++ b/README.md
@@ -1,2 +1,65 @@
-# sam
-Sovereign Agent Mesh
+# SAM: Sovereign Agent Mesh
+
+SAM is a zero-trust, pure P2P networking layer for autonomous agents.
+
+It is built for environments where centralized gateways and centralized trust are a liability. Agents discover each other over libp2p DHT, authenticate with vouches, authorize capabilities with Biscuit caveats, and communicate directly over A2A streams.
+
+## Why SAM
+
+- Pure P2P: no API gateway in the data path
+- Zero-trust by default: every call is authenticated and authorized
+- Federation isolation: separate namespaces and storage per federation
+- Auditability: inspect tokens/cards and dry-run key flows
+
+## Quick Start
+
+### Build
+
+```bash
+make build
+./bin/sam --help
+```
+
+### Run tests
+
+```bash
+make test
+make test-e2e
+```
+
+### First workflow
+
+```bash
+# Authenticate
+sam identity login --hub https://identity.example.com --federation finance
+
+# Publish an agent capability
+sam publish --federation finance --skill risk-audit --mcp-port 8080
+
+# Call by capability
+sam call risk-audit --federation finance --message "audit this report"
+
+# Inspect credential artifacts
+sam inspect biscuit "vendor-bot;allow_skill=risk-audit"
+```
+
+## Documentation
+
+- 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
+- CLI reference: https://aojea.github.io/sam/#/cli/reference.md
+- Testing guide: https://aojea.github.io/sam/#/testing.md
+
+## Development
+
+Key make targets:
+
+- `make build`
+- `make test`
+- `make test-e2e`
+- `make lint`
+
+## License
+
+See [LICENSE](LICENSE).
diff --git a/docs/README.md b/docs/README.md
index 42ede518..4bfd632f 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -164,10 +164,10 @@ SAM enables this sovereignty by moving trust from **authorities** to **cryptogra
## Next Steps
-- **[Getting Started](https://aojea.github.io/sam/#/guides/dark-mesh.md)**: Set up an enterprise dark mesh
-- **[CLI Reference](https://aojea.github.io/sam/#/cli/reference.md)**: Full kubectl-style command hierarchy
-- **[Technical Deep Dive](https://aojea.github.io/sam/#/concepts/federation.md)**: How federation isolation works
-- **[Testing Guide](https://aojea.github.io/sam/#/testing.md)**: Run the test suite locally
+- **[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