docs(blueprints): add product blueprint guide

pages/_meta.ts

@@ -26,6 +26,10 @@ const meta: Meta = {
     title: "Runtime",
     type: "page",
   },
+  blueprints: {
+    title: "Blueprints",
+    type: "page",
+  },
   protocol: {
     type: "menu",
     title: "Protocol",
@@ -68,6 +72,10 @@ const meta: Meta = {
     title: "Protocol",
     type: "page",
   },
+  "release-notes": {
+    title: "Release Notes",
+    type: "page",
+  },
 };
 
 export default meta;

pages/blueprints/_meta.ts

@@ -0,0 +1,25 @@
+import type { Meta } from "nextra";
+
+const meta: Meta = {
+  index: "Overview",
+  "protocol-model": "Protocol Model",
+  "operator-matrix": "Operator Matrix",
+  "dapp-integration": "Dapp Integration",
+  "-- sandbox": {
+    type: "separator",
+    title: "AI Agent Sandbox",
+  },
+  "ai-agent-sandbox": "AI Agent Sandbox",
+  "-- trading": {
+    type: "separator",
+    title: "AI Trading",
+  },
+  "ai-trading": "AI Trading",
+  "-- surplus": {
+    type: "separator",
+    title: "Surplus Market",
+  },
+  "surplus-market": "Surplus Market",
+};
+
+export default meta;

pages/blueprints/ai-agent-sandbox/_meta.ts

@@ -0,0 +1,10 @@
+import type { Meta } from "nextra";
+
+const meta: Meta = {
+  index: "Overview",
+  "operator-requirements": "Operator Requirements",
+  "runtime-and-harnesses": "Runtime and Harnesses",
+  "dapp-and-indexer": "Dapp and Indexer",
+};
+
+export default meta;

pages/blueprints/ai-agent-sandbox/dapp-and-indexer.mdx

@@ -0,0 +1,41 @@
+---
+title: AI Agent Sandbox Dapp and Indexer
+description: Dapp metadata, iframe policy, and indexer requirements for the AI Agent Sandbox blueprint.
+---
+
+# Dapp and Indexer
+
+The dapp should resolve the sandbox blueprint from first-party metadata, then render the hosted sandbox app through the trusted iframe path.
+
+## Metadata Contract
+
+| Field                             | Value                                           |
+| --------------------------------- | ----------------------------------------------- |
+| `blueprintUi.displayName`         | `AI Agent Sandbox`                              |
+| `blueprintUi.requestedSlug`       | `ai-agent-sandbox`                              |
+| `blueprintUi.publisher.namespace` | `tangle`                                        |
+| `resources.serviceNoun`           | `sandbox fleet`                                 |
+| `resources.resourceNoun`          | `agent`                                         |
+| `externalApp.url`                 | `https://agent-sandbox.blueprint.tangle.tools/` |
+| `externalApp.mode`                | `iframe`                                        |
+
+The metadata defines three modes: cloud, dedicated instance, and TEE instance. The dapp can use those mode records to keep the app surface stable while routing service creation to the right blueprint ID.
+
+## Iframe Policy
+
+The sandbox app requests read account access, chain switching, and message/contract permissions for local and Base Sepolia deployments. Popups are disabled. The dapp should still enforce the host allowlist and iframe app policy before rendering.
+
+## Indexed State
+
+The dapp needs indexed state for:
+
+| State                          | Why it matters                                           |
+| ------------------------------ | -------------------------------------------------------- |
+| Blueprint creation and updates | Finds the sandbox blueprint and reads current metadata.  |
+| Operator registration          | Shows available operators and capacity choices.          |
+| Service creation and approval  | Identifies active sandbox fleets or dedicated instances. |
+| Source acknowledgement         | Confirms the operator accepted the runnable artifact.    |
+| Job events                     | Shows sandbox create/delete and workflow activity.       |
+| Quality-of-service heartbeats  | Shows liveness and operator reliability.                 |
+
+The indexer should preserve enough service-instance and operator history for the app to distinguish "not provisioned yet" from "operator failed to report readiness." Live sandbox health still comes from the operator API and runtime checks.

pages/blueprints/ai-agent-sandbox/index.mdx

@@ -0,0 +1,44 @@
+---
+title: AI Agent Sandbox Blueprint
+description: First-party Tangle blueprint for managed AI agent sandboxes.
+---
+
+# AI Agent Sandbox Blueprint
+
+The AI Agent Sandbox blueprint defines the template for isolated agent sandbox service instances on Tangle. Operators run the sandbox runtime and sidecar containers. Users create sandboxes, trigger workflows, attach terminals, inject secrets, and inspect execution through the hosted app.
+
+Source repo: https://github.com/tangle-network/ai-agent-sandbox-blueprint
+
+## Product Shape
+
+| Area              | Source-backed behavior                                                                                    |
+| ----------------- | --------------------------------------------------------------------------------------------------------- |
+| Cloud mode        | Multi-tenant fleet; callers create and delete sandboxes on demand through on-chain jobs.                  |
+| Instance mode     | One sandbox per service instance; the operator auto-provisions on startup and reports lifecycle directly. |
+| TEE instance mode | Dedicated instance with TEE attestation and sealed secrets.                                               |
+| Hosted app        | `https://agent-sandbox.blueprint.tangle.tools/`                                                           |
+| Metadata identity | `publisher.namespace = "tangle"`, `requestedSlug = "ai-agent-sandbox"`                                    |
+
+## On-Chain Jobs
+
+| ID  | Job                | Mode               | What it does                                                 |
+| --- | ------------------ | ------------------ | ------------------------------------------------------------ |
+| `0` | `SANDBOX_CREATE`   | Cloud              | Creates a sandbox container, microVM, or TEE-backed sandbox. |
+| `1` | `SANDBOX_DELETE`   | Cloud              | Deletes the sandbox and releases runtime resources.          |
+| `2` | `WORKFLOW_CREATE`  | Cloud and instance | Registers a workflow template.                               |
+| `3` | `WORKFLOW_TRIGGER` | Cloud and instance | Starts a registered workflow.                                |
+| `4` | `WORKFLOW_CANCEL`  | Cloud and instance | Cancels active workflow execution.                           |
+
+`JOB_WORKFLOW_TICK` is internal cron-driven workflow progress. It is not a public on-chain job.
+
+## Read Next
+
+| Page                                                                        | Use it for                                                              |
+| --------------------------------------------------------------------------- | ----------------------------------------------------------------------- |
+| [Operator Requirements](/blueprints/ai-agent-sandbox/operator-requirements) | Host sizing, env vars, Docker, Firecracker, TEE, ports.                 |
+| [Runtime and Harnesses](/blueprints/ai-agent-sandbox/runtime-and-harnesses) | Sidecar capabilities, harness discovery, secrets, auth, runtime safety. |
+| [Dapp and Indexer](/blueprints/ai-agent-sandbox/dapp-and-indexer)           | Metadata, iframe policy, indexed events, service state.                 |
+
+## Source Material
+
+This page is based on the blueprint repo's `README.md`, `docs/runbook.md`, `metadata/blueprint-metadata.json`, `ai-agent-sandbox-blueprint-lib/src/lib.rs`, `sandbox-runtime/src/operator_api.rs`, and `TEE-GUIDE.md`.

pages/blueprints/ai-agent-sandbox/operator-requirements.mdx

@@ -0,0 +1,50 @@
+---
+title: AI Agent Sandbox Operator Requirements
+description: Host, runtime, and environment requirements for AI Agent Sandbox operators.
+---
+
+# Operator Requirements
+
+Operators run one of three binaries: sandbox cloud, dedicated instance, or TEE instance. All variants need a keystore, chain RPC, persistent state, and an authenticated operator API.
+
+## Common Environment
+
+| Variable                                          | Purpose                                                            |
+| ------------------------------------------------- | ------------------------------------------------------------------ |
+| `KEYSTORE_URI`                                    | Operator keystore path or URI.                                     |
+| `HTTP_RPC_ENDPOINT` or `RPC_URL`                  | Tangle EVM HTTP RPC endpoint.                                      |
+| `TANGLE_WS_URL`                                   | WebSocket endpoint for event subscriptions.                        |
+| `BLUEPRINT_STATE_DIR`                             | Persistent state for sandbox records, sessions, and metadata.      |
+| `SESSION_AUTH_SECRET`                             | 32+ byte secret for PASETO sessions and at-rest secret encryption. |
+| `SANDBOX_UI_AUTH_MODE`, `SANDBOX_UI_BEARER_TOKEN` | Browser-facing UI ingress auth.                                    |
+
+## Sandbox Mode
+
+| Requirement         | Notes                                                                          |
+| ------------------- | ------------------------------------------------------------------------------ |
+| Docker              | Required for standard sidecar containers.                                      |
+| `SIDECAR_IMAGE`     | Defaults to a sidecar-compatible all-harness image.                            |
+| `OPERATOR_API_PORT` | Default `9100`.                                                                |
+| `PUBLIC_HOST`       | Set explicitly behind NAT or VPN; auto-detect is available for Tailscale IPv4. |
+
+## Firecracker Mode
+
+Firecracker runs through the in-process `microvm-runtime` driver. The operator binary is the Firecracker host; there is no separate host-agent service.
+
+| Variable                         | Purpose                    |
+| -------------------------------- | -------------------------- |
+| `MICROVM_FIRECRACKER_BIN`        | Firecracker binary path.   |
+| `MICROVM_FIRECRACKER_KERNEL`     | Linux kernel image.        |
+| `MICROVM_FIRECRACKER_ROOTFS`     | Rootfs ext4 image.         |
+| `MICROVM_FIRECRACKER_SOCKET_DIR` | Per-VM API socket parent.  |
+| `MICROVM_FIRECRACKER_STATE_DIR`  | Per-VM state directory.    |
+| `MICROVM_FIRECRACKER_VCPU`       | Default vCPU count per VM. |
+| `MICROVM_FIRECRACKER_MEM_MIB`    | Default memory per VM.     |
+
+The Firecracker path allocates TAP, vsock, per-VM rootfs clones, and host port forwarding. Operators must bake the guest metadata daemon into the rootfs so environment and sidecar auth tokens can be injected over vsock.
+
+## TEE Mode
+
+TEE instance mode supports provider-backed confidential runtimes such as Phala, AWS Nitro, GCP Confidential Space, Azure SKR, or direct operator-managed hardware. Configure the provider-specific credentials and set `TEE_BACKEND`.
+
+Current TEE verification should be treated as structural unless the deployment also pins quote-signature verification, expected sidecar measurements, and fresh client nonces.

pages/blueprints/ai-agent-sandbox/runtime-and-harnesses.mdx

@@ -0,0 +1,54 @@
+---
+title: AI Agent Sandbox Runtime and Harnesses
+description: Sidecar capability and harness model for the AI Agent Sandbox blueprint.
+---
+
+# Runtime and Harnesses
+
+The sandbox blueprint is not one agent integration. The product contract is a sidecar-compatible sandbox plus runtime capabilities advertised by the operator.
+
+## Runtime Backends
+
+Sandbox creation selects a backend through `metadata_json.runtime_backend`.
+
+| Backend       | Behavior                                                                                      |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| `docker`      | Default managed sidecar container path.                                                       |
+| `firecracker` | MicroVM path; installs per-VM networking, rootfs, env injection, and sidecar token injection. |
+| `tee`         | Forces TEE provisioning and `tee_required=true`.                                              |
+
+Firecracker and TEE are separate choices in the current release. Selecting `firecracker` forces `tee_required=false`.
+
+## Sidecar Capabilities
+
+Provisioning accepts `capabilities_json`, a JSON-encoded string array. Accepted values are injected into the sandbox as `SIDECAR_CAPABILITIES`.
+
+| Capability     | Behavior                                                                                                 |
+| -------------- | -------------------------------------------------------------------------------------------------------- |
+| `computer_use` | Starts browser/computer-use sidecar services for mouse, keyboard, screenshots, and related MCP surfaces. |
+| `all_harness`  | Requests the multi-harness sidecar image path.                                                           |
+
+The exact harness matrix comes from `GET /api/capabilities`. The current default all-harness image advertises multiple CLI agent harnesses. Operators should rely on capability discovery instead of treating any one harness as the integration.
+
+The current all-harness path is source-backed for Claude Code, Codex, OpenCode, Kimi, and Gemini. That is a sidecar runtime capability, not the blueprint's product identity. The blueprint identity is the sandbox service instance plus its operator API, lifecycle jobs, workflow state, and runtime isolation.
+
+## Operator API
+
+All data endpoints use EIP-191 challenge-response auth that issues PASETO v4.local session tokens.
+
+| Endpoint group       | Examples                                                                                     |
+| -------------------- | -------------------------------------------------------------------------------------------- |
+| Auth                 | `POST /api/auth/challenge`, `POST /api/auth/session`, `DELETE /api/auth/session`             |
+| Sandbox operations   | `exec`, `prompt`, `task`, `stop`, `resume`, `snapshot`, `ssh`, `secrets`, port proxy         |
+| Instance operations  | Same control plane under `/api/sandbox/...` for singleton service instances                  |
+| Health and discovery | `GET /health`, `GET /readyz`, `GET /metrics`, `GET /api/provisions`, `GET /api/capabilities` |
+
+## Secrets and Model Credentials
+
+Sandbox creation can succeed without model credentials. Agent prompts, tasks, and workflow steps fail only when the selected harness or model provider lacks its required secret.
+
+Operators should inject provider credentials as sandbox secrets or environment variables scoped to the service instance. The blueprint ABI stays stable as new sidecar images and sandbox SDK harnesses add support for more providers.
+
+## Runtime Safety
+
+The runtime enforces challenge-response auth, encrypted stored secrets, container hardening, rate limits, circuit breakers, session caps, and snapshot destination validation. Container hardening includes dropped capabilities, `no-new-privileges`, PID limits, localhost-bound ports, and restricted writable state.

pages/blueprints/ai-trading/_meta.ts

@@ -0,0 +1,10 @@
+import type { Meta } from "nextra";
+
+const meta: Meta = {
+  index: "Overview",
+  "operator-requirements": "Operator Requirements",
+  "runtime-and-risk": "Runtime and Risk",
+  "dapp-and-indexer": "Dapp and Indexer",
+};
+
+export default meta;

pages/blueprints/ai-trading/dapp-and-indexer.mdx

@@ -0,0 +1,46 @@
+---
+title: AI Trading Dapp and Indexer
+description: Arena metadata, iframe policy, and indexed state for the AI Trading blueprint.
+---
+
+# Dapp and Indexer
+
+The dapp should resolve the AI Trading blueprint from first-party metadata and render the Arena app through the trusted iframe path.
+
+## Metadata Contract
+
+| Field                             | Value                                           |
+| --------------------------------- | ----------------------------------------------- |
+| `blueprintUi.displayName`         | `AI Trading Desk`                               |
+| `blueprintUi.requestedSlug`       | `ai-trading`                                    |
+| `blueprintUi.publisher.namespace` | `tangle`                                        |
+| `resources.serviceNoun`           | `trading instance`                              |
+| `resources.resourceNoun`          | `bot`                                           |
+| `externalApp.url`                 | `https://trading-arena.blueprint.tangle.tools/` |
+| `externalApp.mode`                | `iframe`                                        |
+
+The metadata includes overview cards for the risk gate, venue capabilities, and protocol adapters. It also declares actions for bot activation and pausing.
+
+## Dapp Behavior
+
+| Surface           | Behavior                                                                                  |
+| ----------------- | ----------------------------------------------------------------------------------------- |
+| Blueprint route   | Claim metadata with `requestedSlug = "ai-trading"` under the `tangle` namespace.          |
+| External app      | Render the Arena iframe only after host and iframe policy checks pass.                    |
+| Chain switching   | Allow only the chain IDs declared in iframe policy.                                       |
+| Protocol fallback | Keep the generic blueprint detail route available for raw on-chain service-instance data. |
+
+## Indexed State
+
+The Arena and Tangle Cloud need:
+
+| State                                  | Why it matters                                                           |
+| -------------------------------------- | ------------------------------------------------------------------------ |
+| Blueprint and source updates           | Finds current binaries and metadata.                                     |
+| Operator registration and endpoint URL | Discovers live operators and their APIs.                                 |
+| Service instances                      | Shows bot fleets and dedicated trading instances.                        |
+| Job events                             | Tracks provision, configure, start, stop, status, and workflow activity. |
+| Pricing state                          | Shows operator quote surfaces and service-instance cost.                 |
+| QoS heartbeats                         | Ranks and filters operators by liveness.                                 |
+
+Because operator endpoint URLs are self-reported at registration time, the dapp should treat the indexer as discovery, not proof that an endpoint is honest or healthy.