aojea · Sep 19, 2026 · Sep 19, 2026
@@ -1,7 +1,7 @@
 name: Sam-One Cloud Run Sandbox
 
 # On-demand sam-one deployments on Cloud Run (see
-# site/content/docs/user/cloud-run-deployment.md for the manual version).
+# site/content/docs/guides/cloud-run.md for the manual version).
 # Deploys are gated by the 'sam-one-sandbox' GitHub Environment: required
 # reviewers approve each run before GCP credentials are minted.
 #

@@ -7,7 +7,7 @@ You are an expert software engineering assistant helping to develop, maintain, a
 * **API Communication:** All data communication between `sam-control-plane`, `sam-router` and `sam-node` must happen exclusively via the common API defined in `api/sam.proto`.
 * **Two API surfaces, two encodings:** the *mesh protocol* — anything a mesh component speaks (node, router, `sam-box`, the agent connector): enrollment, refresh, keys, leases, auth streams, policy sync — is protobuf from `api/sam.proto` (`application/x-protobuf`). The *operator plane* — what humans, the web console and admin CLIs call (`/admin/*`, `/users/*`) — is JSON, with its request and response types declared as Go structs in `api/` (e.g. `api.BootstrapTokenRequest`). Never define a wire shape as an anonymous struct or `map[string]any` inside a handler, and never serialize an `internal/storage` (or any other internal) type onto either surface; clients in `cmd/` and `internal/console` import `api/` only. A message that a mesh component consumes goes in the proto even if a console also reads it.
 * **Secrets never travel as flag values:** binaries read credentials from a file (`--*-path`) or the environment, never from a command-line argument that would sit in `ps` output and shell history. Banners and logs name the source of an operator-supplied secret instead of echoing it.
-* **Sandbox Dataplane:** `sam-box` (one per sandbox) is the single egress policy enforcement point. It holds no libp2p host, no enrollment and no mesh identity, and reaches the mesh exclusively as a client of the local `sam-node` sidecar socket. `nano-init` (PID 1 inside the guest, its own Go module) owns the guest side; its datapath is the `tun2connect` library. The sandbox boundary is a Unix socket speaking named HTTP tunnels: CONNECT (TCP) and connect-udp (UDP) out, `CONNECT <port>` back in. The authoritative design is `site/content/docs/agent-architecture.md`; do not contradict it.
+* **Sandbox Dataplane:** `sam-box` (one per sandbox) is the single egress policy enforcement point. It holds no libp2p host, no enrollment and no mesh identity, and reaches the mesh exclusively as a client of the local `sam-node` sidecar socket. `nano-init` (PID 1 inside the guest, its own Go module) owns the guest side; its datapath is the `tun2connect` library. The sandbox boundary is a Unix socket speaking named HTTP tunnels: CONNECT (TCP) and connect-udp (UDP) out, `CONNECT <port>` back in. The authoritative design is `site/content/docs/preview/agent-architecture.md`; do not contradict it.
 * **Enforcement over Convention:** never gate sandbox traffic on the agent's cooperation — no proxy environment variables, no `LD_PRELOAD` shims, no DNS spoofing. The agent harness stays unmodified and mesh-unaware; confinement is a route and a socket, built by the userspace launcher (`nano-init`) and judged in `sam-box`. An agent that must cooperate with its own confinement is not confined.
 * **Policy on Names:** egress policy, secret injection and routing decisions are made on the destination *name*, never on an IP. Deny by default.
 * **Agent Identity:** the agent is the principal; the node is only the channel. Agent identity comes from the platform's workload credential, verified at admission — never asserted in-band from inside the sandbox. Platforms integrate solely through the connector interface (`Attach`/`Detach`/`Refresh`/`Status` and the agent bundle), not by reaching into SAM internals.

@@ -1,83 +1,71 @@
-# SAM: Sovereign Agent Mesh
-
-<img alt="SAM" src="site/content/docs/sam_logo.png" />
-
-SAM is a smart network built for autonomous AI agents:
-
-*   **Zero Config:** Nodes discover each other and build the P2P network automatically.
-*   **Zero Trust:** Every connection, node, and packet is strictly authenticated.
-*   **Agentic Network:** Formed by lightweight nodes (`sam-node`) that provide self-healing, P2P connectivity, allowing autonomous agents to plug in, communicate, and invoke tools dynamically.
-*   **Portability:** Cryptographic identities are environment-agnostic, allowing seamless node mobility across cloud, local, and edge environments.
-
-Getting started is a one-liner (see the [Quick Start Guide](site/content/docs/quickstart.md)): install, add the skill, and your agent is on the mesh.
-
-<img src="site/static/demo.gif" alt="Demo: installing SAM, adding the sam-mesh skill, and an agent discovering and calling tools across the mesh" width="100%" />
-
-<details>
-<summary><b>Advanced demo</b>: an agent fans a batch of work across a warm pool of reviewer agents on the mesh</summary>
-
-<video src="https://github.com/user-attachments/assets/f1a61b6f-efcd-46d8-a6e6-659fb29dd1ce" width="100%" autoplay loop muted playsinline controls></video>
-
-Full walkthrough: [Warm Agent Pool use case](site/content/docs/use-cases/warm-agent-pool.md).
-
-</details>
-
----
-
-## What "Sovereign" Means in SAM
-
-SAM is an **open-source software project (Apache-2.0)** providing decentralized networking and cryptographic building blocks for autonomous AI agents. It carries no vendor telemetry and has no hardcoded dependencies on proprietary cloud services or model providers.
-
-SAM provides the open protocols, cryptographic building blocks, and software to build **sovereign, zero-trust agent meshes**. In SAM, digital sovereignty is built on architectural and cryptographic control—custody of root keys, independent identity federation, and policy-enforced data boundaries. In a sovereign deployment, operators:
-
-1. **Deploy Dedicated Mesh Infrastructure:** Run a dedicated control plane (`sam-control-plane`) and routing relays (`sam-router`) on your chosen infrastructure (managed cloud environments like Google Cloud, private Kubernetes clusters, or air-gapped datacenters) using our [Helm chart](charts/sam-mesh/README.md) or Kubernetes manifests.
-2. **Maintain Root Cryptographic Key Custody:** Generate, manage, and hold your own Ed25519 root signing keys (via local HSMs, KMS, or Cloud EKM). You maintain 100% of the cryptographic authority—no external party can mint credentials, revoke nodes, or alter policies.
-3. **Bring Your Own Identity Provider:** Bridge agent and user identities through your own OIDC identity provider (such as Dex, Keycloak, or corporate IdP).
-4. **Enforce Territorial & Jurisdictional Boundaries:** Use cryptographically attested label gates (`labels: {jurisdiction: eu}` in the node config, `X-Sam-Required-Labels`) to mathematically guarantee prompts and tool invocations never leave authorized geographic scopes.
-5. **Retain Autonomous Local Vetoes:** Configure local node attenuation policies (`sam-node.yaml`) to evaluate access rules *before* control plane grants, ensuring local nodes retain absolute veto authority.
-
-> [!NOTE]
-> **About the Public Developer Testnets:**
-> The public endpoints (`bananas.sam-mesh.dev` and `hub.sam-mesh.dev`) are free testbeds created using community resources solely for developer testing, continuous integration, and rapid experimentation. They provide **no guarantees, no uptime commitments, zero SLA, and no sovereign guarantees**. Running on a shared community testnet delegates identity management to the testbed maintainers; true sovereignty requires deploying a dedicated control plane with customer-held keys.
->
-> [![Testnet Health](https://github.com/google/sam/actions/workflows/testnet-health.yaml/badge.svg)](https://github.com/google/sam/actions/workflows/testnet-health.yaml) Every half hour a fresh node's view of each testnet is checked (enrollment surface, routers, canaries, and a cold-path probe that joins and calls a tool); a red badge means one of them is unhealthy and an issue labelled `testnet-health` says which check failed.
->
-> 📖 **Deep Dive:** Read our full **[Digital & Data Sovereignty Architecture](site/content/docs/sovereignty.md)** covering the 5 pillars, fail-closed label gates, uncooperative sandbox confinement, and regulatory alignment (GDPR Chapter V, EU Cloud Sovereignty Framework SEAL-3, EU Data Act).
-
----
-
-## Architecture Components
-
-*   `sam-control-plane`: The registry control plane for node identity registration, authorization policies, and router coordinating.
-*   `sam-router`: The libp2p bootstrap nodes and relays providing data-plane connectivity and forwarding.
-*   `sam-node`: The local node clients providing mesh transport integration and MCP sidecar routing.
-
----
+# SAM
+
+<img alt="SAM" src="site/content/docs/sam_logo.png" width="160" />
+
+SAM is a private network for AI agents. A node runs next to an agent and
+gives it three things: a way to publish tools and models to the network, a
+way to find and call what other nodes publish, and an identity every other
+node can verify. Nodes connect directly when they can and through relays when
+they cannot, so the network works across laptops, containers, clusters and
+phones behind NAT.
+
+Two properties hold everywhere:
+
+- **Nothing is reachable by default.** A node exposes no services until its
+  configuration says so, and no node may call a service the mesh policy has
+  not granted. Grants are evaluated on service names, never on addresses.
+- **Identity comes from your identity provider.** A node enrolls with an
+  OpenID Connect token or a one-time bootstrap token, and the control plane
+  turns that into a short-lived, offline-verifiable credential bound to the
+  node's own key.
+
+<img src="site/static/demo.gif" alt="Installing sam-node, adding the skill, and an agent discovering and calling tools across the mesh" width="100%" />
+
+## Try it
+
+```bash
+curl -sL https://sam-mesh.dev/install.sh | bash   # sam-node, mcp-client and friends
+sam-node join https://bananas.sam-mesh.dev        # one-time login
+sam-node run --daemonize                          # local MCP server on 127.0.0.1:8080
+sam-node skill install                            # teach your agent to use it
+```
+
+Your agent now has tools that discover and call services across the mesh,
+and an OpenAI-compatible endpoint that routes model requests to whoever
+serves the model. `bananas.sam-mesh.dev` is a shared developer testnet with
+no uptime promise; the [quick start](https://sam-mesh.dev/docs/getting-started/quickstart/)
+walks through it, and [your own mesh](https://sam-mesh.dev/docs/getting-started/your-own-mesh/)
+runs a control plane on your laptop in one command.
+
+## What is in a mesh
+
+| Program | Role |
+|---|---|
+| `sam-control-plane` | Verifies who is joining, issues each node a signed credential, and holds the policy that says who may call what. |
+| `sam-router` | A well-known peer that nodes connect to first. Relays traffic between nodes that cannot reach each other and hosts the discovery table. |
+| `sam-node` | Runs next to your agent or service. Enrolls, connects, serves your local backends to the mesh, and exposes the mesh to your agent as a local MCP server and OpenAI-compatible API. |
+| `sam-one` | The control plane, a router and a web console in one binary, for laptops and small deployments. |
 
 ## Documentation
 
-Start exploring the Sovereign Agent Mesh:
-
-### Digital & Data Sovereignty
-- 🏛️ **[Digital & Data Sovereignty Architecture](site/content/docs/sovereignty.md)**: How SAM enforces data residency, territorial label gates, autonomous local vetoes, and regulatory compliance (GDPR, EU Cloud Sovereignty Framework SEAL-3, EU Data Act).
-
-### For Users & Operators
-- 🚀 **[User Quick Start Guide](site/content/docs/quickstart.md)**: Connect and run a SAM node on the community-hosted developer testnet (`bananas.sam-mesh.dev`, strictly for testing with no guarantees) using binaries or Docker.
-- 🎛️ **[Dedicated Sovereign Deployment](site/content/docs/user/kubernetes-deployment.md)**: Run your own private sovereign hub (control plane, router, console) via the [sam-mesh Helm chart](charts/sam-mesh/README.md) or Kubernetes manifests.
-- 🤖 **[Agent Integration Guides](site/content/docs/integrations/_index.md)**: Connect Google Gemini, Claude, and other AI agents to your SAM node to dynamically discover and call tools across the mesh.
-- 📡 **[Testnet Validation Tutorial](site/content/docs/development/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies on public developer testnets.
-
-### For Developers & Contributors
-Compile from source, run local clusters, or execute tests:
-- 🛠️ **[Developer Guide](site/content/docs/development/_index.md)**: Prereqs, compilation, local control plane setup, and Kubernetes Kind deployment.
-- 🧪 **[Testing Guide](site/content/docs/development/testing.md)**: Go tests, E2E BATS, and containerized mesh execution.
+[sam-mesh.dev/docs](https://sam-mesh.dev/docs/) is built from `site/`.
 
----
+- [Getting started](https://sam-mesh.dev/docs/getting-started/): one node on the testnet, then a mesh of your own.
+- [Concepts](https://sam-mesh.dev/docs/concepts/): architecture, identity and enrollment, authorization, networking.
+- [Guides](https://sam-mesh.dev/docs/guides/): exposing services, connecting agent clients, headless enrollment, Kubernetes, Cloud Run.
+- [Reference](https://sam-mesh.dev/docs/reference/): every flag, configuration key, HTTP route and policy field.
+- [Preview](https://sam-mesh.dev/docs/preview/): sandboxed agents and the mobile app, which work but are still settling.
+- [Contributing](https://sam-mesh.dev/docs/contributing/): building, testing and the local kind environment.
 
-## License
+## Status
 
-See [LICENSE](LICENSE).
+SAM is pre-1.0. The node, routers, control plane, identity and policy model
+are stable in shape and exercised by the test suite and two public testnets;
+see [ROADMAP.md](ROADMAP.md) for the release plan. Sandboxed agents
+(`sam-box`, `nano-init`) and the mobile app are in preview.
 
-## Disclaimer
+## License and disclaimer
 
-This is not an officially supported Google product. This project is not eligible for the [Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
+Apache-2.0; see [LICENSE](LICENSE). This is not an officially supported
+Google product, and it is not eligible for the
+[Google Open Source Software Vulnerability Rewards Program](https://bughunters.google.com/open-source-security).
@@ -1,4 +1,4 @@
-# Sovereign Agent Mesh (SAM) Roadmap
+# SAM Roadmap
 
 ## Phase 1: Alpha
 
@@ -11,7 +11,7 @@ The Alpha phase is focused on laying the foundational architecture, finalizing A
 
   * Establish P2P routing and base node lifecycle.
   * Deploy community developer testnets.
-  * Draft initial sovereignty architectural documentation.
+  * Draft the initial architecture documentation.
   * Integrate baseline network services: MCP, A2A, Inference.
 
 * **Exit Criteria:**
@@ -35,7 +35,7 @@ The Beta phase iterates on functional completeness based on real-world deploymen
 
 * **Exit Criteria:**
 
-  * All planned sovereignty features are implemented and passing integration tests.
+  * All planned data-residency and control features are implemented and passing integration tests.
   * API and Datalog schemas are frozen.
 
 ## Phase 3: The Audit Freeze (Release Candidates)
@@ -44,24 +44,24 @@ The Beta phase iterates on functional completeness based on real-world deploymen
 **Status:** Feature Frozen / Undergoing Audit
 
 During this phase, **no new features are merged**.
-The codebase is strictly locked down to undergo rigorous external validation to ensure it meets our security and sovereignty guarantees.
+The codebase is strictly locked down to undergo rigorous external validation to ensure it meets our security and data-residency guarantees.
 
 * **Core Objectives:**
 
   * **Security Audit:** Comprehensive third-party penetration testing, code review, and cryptography validation (focusing on Biscuit tokens and Ed25519 key handling).
-  * **Sovereignty & Compliance Audit:** Validation against strict digital sovereignty frameworks (e.g., GDPR data residency, EU AI Act traceability, CSF SEAL-3).
+  * **Compliance Audit:** Validation against data-residency and traceability frameworks (e.g., GDPR data residency, EU AI Act traceability, CSF SEAL-3).
 
 * **Exit Criteria:**
 
   * All critical and high-severity security vulnerabilities are remediated.
-  * External auditors officially sign off on the cryptographic and architectural sovereignty claims.
+  * External auditors officially sign off on the cryptographic and architectural claims.
 
 ## Phase 4: Production Stable
 
 **Versions:** `v1.0.0` and beyond
 **Status:** Mission-Critical Ready
 
-The framework is certified for enterprise, sovereign, and cross-border deployments.
+The framework is certified for enterprise, regulated, and cross-border deployments.
 
 * **Core Objectives:**
 

@@ -1,6 +1,6 @@
 ---
 name: sam-a2a-bridge
-description: "Use when the task should be delegated to a remote A2A agent on the SAM (Sovereign Agent Mesh) network: send it work with send_agent_task (with text, structured data, or file attachments), check agent capabilities with get_agent_card, poll results with get_agent_task, hold multi-turn conversations, and enforce data-sovereignty labels on every call. Also use to set up the sam-a2a-bridge MCP server when those tools are not callable yet."
+description: "Use when the task should be delegated to a remote A2A agent on the SAM agent mesh: send it work with send_agent_task (with text, structured data, or file attachments), check agent capabilities with get_agent_card, poll results with get_agent_task, hold multi-turn conversations, and enforce data-residency labels on every call. Also use to set up the sam-a2a-bridge MCP server when those tools are not callable yet."
 ---
 
 # SAM A2A Bridge Skill
@@ -71,7 +71,7 @@ input schema) and `file_path` attachments appropriately.
   - `data` (optional) contains structured JSON returned inline.
   - `files` (optional) is a list of paths where agent-returned files are saved
     under the download directory.
-- **Sovereignty**: when the task involves data that must stay in a region or
+- **Data residency**: when the task involves data that must stay in a region or
   jurisdiction, set `required_labels` (comma-separated `key=value`, e.g.
   `region=eu-west-1`). The local node then refuses fail-closed before any data
   leaves it unless the peer's control-plane-attested labels match. Never drop
@@ -96,7 +96,7 @@ message while running and its answer or artifacts when completed. `data` and
 
 ## Interpret Errors
 
-- `403: Required labels not attested by provider` — the sovereignty gate
+- `403: Required labels not attested by provider` — the label gate
   refused before egress. Expected for non-matching regions; report it to the
   user, do not retry with weaker labels on your own.
 - `400: Invalid X-Sam-Required-Labels header ...` — malformed labels; fix the

@@ -1,6 +1,6 @@
 ---
 name: sam-mesh
-description: "Use when local tools cannot provide a needed capability and a SAM (Sovereign Agent Mesh) network can: inspect mesh state, discover reachable services/tools, describe and call namespaced remote MCP tools, and reach OpenAI-compatible inference models hosted by mesh peers. Also use to set up, join, or reconnect a sam-node when its MCP tools are not callable yet."
+description: "Use when local tools cannot provide a needed capability and a SAM agent mesh can: inspect mesh state, discover reachable services/tools, describe and call namespaced remote MCP tools, and reach OpenAI-compatible inference models hosted by mesh peers. Also use to set up, join, or reconnect a sam-node when its MCP tools are not callable yet."
 ---
 
 # SAM Agent Skill

@@ -1,6 +1,6 @@
 apiVersion: v2
 name: sam-mesh
-description: A Helm chart for deploying the Sovereign Agent Mesh (SAM) Control Plane, Router, and Console
+description: A Helm chart for deploying the SAM control plane, router and console
 type: application
 version: 0.1.0
 appVersion: "1.0.0"