@@ -2,138 +2,43 @@
 
 <img alt="SAM" src="docs/sam_logo.png" />
 
-SAM is a smart network built for autonomous agents:
+SAM is a smart network built for autonomous AI agents:
 
-*   **Zero Config:** Nodes discover each other and build the network automatically.
+*   **Zero Config:** Nodes discover each other and build the P2P network automatically.
 *   **Zero Trust:** Every connection, node, and packet is strictly authenticated.
-*   **Agentic Network:** Built for agents to use. The nodes provide the self-healing, peer-to-peer infrastructure, allowing autonomous agents to seamlessly plug in, communicate, and operate across the mesh.
-*   **Portability:** Environment-agnostic and IP-independent. Network identity is cryptographic and travels with the node, enabling mobility across cloud, edge, and local setups.
+*   **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.
 
+---
 
-- `sam-hub`: The control plane for identity and policy distribution.
-- `sam-node`: The lightweight agents that form the actual peer-to-peer mesh.
+## Architecture Components
 
-## Build
+*   `sam-hub`: The control plane for identity mapping and policy distribution.
+*   `sam-node`: The P2P nodes providing the mesh transport layer and local MCP interfaces.
 
-```bash
-make build
-./bin/sam-node --help
-./bin/sam-hub --help
-```
+---
 
-## Basic Usage
-
-### 1. Run the hub
-
-```bash
-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
-```
-
-### 2. Join a mesh (Enroll node)
-
-To register the node's cryptographic identity with the hub:
-
-```bash
-./bin/sam-node join http://localhost:8080
-```
-
-This initiates the interactive OIDC Device Authorization flow. It prints a URL to open in your browser for authentication. Once authorized, it automatically receives the node's Biscuit identity token and saves it (along with the derived node private key) inside the local data store.
-
-### 3. Run the node
-
-Start the node using the stored identity (note that `--api-token` is mandatory to protect the local API when not using mTLS):
-
-```bash
-./bin/sam-node run --api-token my-secret-token
-```
-
-Or run the node by explicitly passing OIDC credentials to dynamically authenticate and enroll on start:
-
-```bash
-./bin/sam-node run \
-  --oidc-issuer https://issuer.example.com \
-  --client-id <id> \
-  --client-secret <secret> \
-  --api-token my-secret-token
-```
-
-## Docker Quick Start
-
-You can run the SAM node using Docker and the officially published image. To persist your node's identity, private key, and mesh discovery configuration across runs, use a host volume mounted to the container's data directory.
-
-### 1. Join the Mesh (Enroll)
-
-Run the container interactively to register your node with the community testnet (`https://bananas.sam-mesh.dev`):
-
-```bash
-docker run -it \
-  -v $(pwd)/sam-data:/data \
-  ghcr.io/google/sam-node:latest \
-  join --data-dir /data https://bananas.sam-mesh.dev
-```
-
-- Follow the printed device authentication instructions in your browser.
-- This generates the node identity and stores it inside `./sam-data/agent.db` on the host.
-
-### 2. Run the Node
-
-Start the background mesh node container using the stored identity. Make sure to publish the required libp2p ports (5001/UDP and 5002/TCP), set a secure `--api-token` to protect the local MCP/Sidecar API, and bind the HTTP server to `0.0.0.0:8080` so that it can be reached from the host:
-
-```bash
-docker run -d \
-  --name sam-node \
-  -v $(pwd)/sam-data:/data \
-  -p 5001:5001/udp \
-  -p 5002:5002 \
-  -p 8080:8080 \
-  ghcr.io/google/sam-node:latest \
-  run --data-dir /data --bind-addr 0.0.0.0:8080 --api-token my-secret-token
-```
-
-## Local MCP Server
-
-Each `sam-node` exposes a Model Context Protocol (MCP) server over HTTP Server-Sent Events (SSE) to allow local processes to discover the capabilities of the local agent and get information from the mesh.
-
-By default, the server listens at `127.0.0.1:8080`. You can change this with the `--bind-addr` flag.
-
-To query the mesh info via the MCP server, you can use the `mcp-client` tool provided in the repository:
-
-```bash
-./bin/mcp-client -url http://127.0.0.1:8080/mcp/events
-```
-
-## Testing
-
-```bash
-make test
-make test-e2e
-make test-e2e-container
-```
+## Documentation
 
-`test-e2e-container` runs a containerized BATS framework that starts:
+Start exploring the Sovereign Agent Mesh:
 
-- a mock OIDC container
-- a `sam-hub` container
-- multiple `sam-node` containers
+### For Users & Operators
+Get a node running on the public testnet (`bananas.sam-mesh.dev`) in minutes:
+- 🚀 **[User Quick Start Guide](docs/quickstart.md)**: Connect and run a SAM node using Docker and query the local MCP server via `curl`.
+- 📖 **[CLI Reference](docs/cli/reference.md)**: Comprehensive CLI reference and configurations.
+- 📡 **[Testnet Validation Tutorial](docs/testnet-validation.md)**: Real-time verification, remote tool invocation, and HTTP stream proxies.
 
-## Documentation
+### For Developers & Contributors
+Compile from source, run local clusters, or execute tests:
+- 🛠️ **[Developer Guide](docs/development.md)**: Prereqs, compilation, local hub setup, and Kubernetes Kind deployment.
+- 🧪 **[Testing Guide](docs/testing.md)**: Go tests, E2E BATS, and containerized mesh execution.
 
-- 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
 
 See [LICENSE](LICENSE).
 
 ## 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).
+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).
@@ -19,10 +19,11 @@ The documentation here is intentionally small and aligned with what is implement
 
 ## Start Here
 
-- [Quick Start](quickstart.md)
-- [CLI Reference](cli/reference.md)
-- [Testing](testing.md)
-- [Testnet Validation](testnet-validation.md)
+- [Quick Start](quickstart.md) - User Quick Start using Docker.
+- [CLI Reference](cli/reference.md) - CLI command usage reference.
+- [Developer Guide](development.md) - Building from source, local testing, and Kind setups.
+- [Testing Guide](testing.md) - Detailed test layer and troubleshooting information.
+- [Testnet Validation Tutorial](testnet-validation.md) - Real-time integration and MCP verification with public testnets.
 
 ## Notes
 
 
@@ -0,0 +1,89 @@
+# Developer Guide & Repository Setup
+
+This document is for developers who want to compile SAM from source, run a local development mesh, run the test suites, or contribute to the repository.
+
+---
+
+## Prerequisites
+
+To build and test the Go binaries natively:
+
+- **Go Toolchain**: Go 1.25+
+- **Docker**: For running containerized integration tests and building local images.
+- **BATS**: `bats-core` framework for running E2E shell tests.
+
+---
+
+## Build from Source
+
+Clone the repository and compile the binaries:
+
+```bash
+git clone https://github.com/google/sam.git
+cd sam
+make build
+```
+
+This compiles and generates the following binaries under `./bin/`:
+
+- `./bin/sam-hub`: The OIDC identity bridge and cryptographic Biscuit token issuer.
+- `./bin/sam-node`: The mesh agent node CLI supporting `join` and `run` commands.
+- `./bin/mcp-client`: A CLI-based utility to interact with MCP servers.
+
+---
+
+## Running a Local Dev Hub
+
+To run `sam-hub` locally for testing, you must supply OIDC issuer configurations and a 32-byte hexadecimal seed key:
+
+```bash
+# Generate a random 32-byte key for biscuit signing
+export SAM_HUB_KEY=$(openssl rand -hex 32)
+export SAM_OIDC_ISSUER=https://issuer.example.com
+export SAM_OIDC_ID=sam-client
+export SAM_OIDC_SECRET=sam-secret
+
+./bin/sam-hub
+```
+
+---
+
+## Testing
+
+The repository implements a testing pyramid. Ensure the test suites are green before pushing code:
+
+### 1. Go Unit & Integration Tests
+Runs the packages' unit tests and multi-node integration tests:
+```bash
+make test
+```
+
+### 2. Local E2E Tests (BATS)
+Validates local command-line behaviors for `sam-node` and `sam-hub`:
+```bash
+make test-e2e
+```
+
+### 3. Containerized Mesh E2E (BATS)
+Builds local Docker images, spins up a mock OIDC server, runs `sam-hub` and multiple `sam-node` containers in a local bridge network, and performs end-to-end device flows and tool discovery:
+```bash
+make test-e2e-container
+```
+
+---
+
+## Local Kubernetes Test Setup
+
+For end-to-end integration testing in a local Kubernetes environment:
+
+1. **Start Kind Cluster**:
+   Ensure you have a Kind cluster running.
+2. **Build and Load Images**:
+   ```bash
+   make docker-build-node
+   make docker-build-hub
+   kind load docker-image sam-node:local
+   kind load docker-image sam-hub:local
+   ```
+3. **Deploy Config Templates**:
+   Deploy and template configuration files located under `.github/k8s/` or `development/kind/` to spin up local nodes and vLLM inference engines.