docs(copy): ground claims and sandbox boundaries (#155)

Author: drewstone

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

@@ -62,7 +62,7 @@ The sandbox app is iframe-first. The parent dapp should:
 
 ## Bad copy to avoid
 
-Do not name the product after one harness. The Sandbox SDK supports OpenCode plus 12 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. The current Sandbox UI picker exposes a subset plus NanoClaw. The AI Agent Sandbox blueprint's current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI. The product boundary is the sandbox service instance and operator API.
+Do not name the product after one harness. The Sandbox SDK supports OpenCode plus 13 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. The current Sandbox UI picker exposes OpenClaw and NanoClaw while deferring Pi, Forge, ACP, and Cursor. The AI Agent Sandbox blueprint's current all-harness sidecar advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI. The product boundary is the sandbox service instance and operator API.
 
 Use capability language instead:
 

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

@@ -7,7 +7,7 @@ description: Runtime backends, capability discovery, harnesses, and AI credentia
 
 The sandbox is the product. Harnesses are tools inside the sandbox.
 
-Do not describe this blueprint as an OpenCode integration, a Codex integration, or a Claude integration. The Sandbox SDK supports OpenCode plus 12 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. A blueprint service instance asks its operator for the live runtime set through `GET /api/capabilities`.
+Do not describe this blueprint as an OpenCode integration, a Codex integration, or a Claude integration. The Sandbox SDK supports OpenCode plus 13 peer backend types: Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. A blueprint service instance asks its operator for the live runtime set through `GET /api/capabilities`.
 
 ## Runtime backends
 

pages/blueprints/ai-trading/operator-requirements.mdx

@@ -62,7 +62,7 @@ Public admission means public cost exposure. Every accepted bot can use CPU, dis
 
 The operator install path defaults new bots to paper trading. Paper mode uses live market data and simulated fills; it should not move capital.
 
-AI keys are optional. If you set `ZAI_API_KEY`, `ANTHROPIC_API_KEY`, `TANGLE_API_KEY`, or OpenCode model/env settings, agentic activation and chat can use those settings when the selected sidecar advertises OpenCode. Treat OpenCode as one harness inside the same capability model as Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, CLI base, or a smaller blueprint sidecar subset. The operator docs are clear: there is no built-in per-bot, per-day, or total LLM spend cap today. Use provider-side billing limits.
+AI keys are optional. If you set `ZAI_API_KEY`, `ANTHROPIC_API_KEY`, `TANGLE_API_KEY`, or OpenCode model/env settings, agentic activation and chat can use those settings when the selected sidecar advertises OpenCode. Treat OpenCode as one harness inside the same capability model as Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, CLI base, or a smaller blueprint sidecar subset. The operator docs are clear: there is no built-in per-bot, per-day, or total LLM spend cap today. Use provider-side billing limits.
 
 ## Public endpoint
 

pages/blueprints/operator-matrix.mdx

@@ -43,7 +43,7 @@ The three first-party blueprints do not fail the same way. A sandbox operator ru
 
 ## Harnesses are not the product boundary
 
-The sandbox product is the sandbox service instance plus its operator API. The Sandbox SDK supports OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, ACP, Cursor, and CLI base. The current all-harness sidecar in the sandbox blueprint advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI through `GET /api/capabilities`.
+The sandbox product is the sandbox service instance plus its operator API. The Sandbox SDK supports OpenCode, Claude Code, Kimi Code, Codex, AMP, Factory Droids, Pi, Hermes, Forge, OpenClaw, NanoClaw, ACP, Cursor, and CLI base. The current all-harness sidecar in the sandbox blueprint advertises Claude Code, Codex, OpenCode, Kimi Code, and Gemini CLI through `GET /api/capabilities`.
 
 That endpoint is the contract the app should read. Do not make docs or UI copy pretend OpenCode, Codex, or any one harness is the integration. Harness support can change by publishing a new sidecar image without changing the blueprint ABI.
 

pages/developers/api/reference/ITangleServices.mdx

@@ -57,9 +57,9 @@ Approve a service request as one of its operators.
 
 _Single entrypoint covering every approval mode. Pass empty/zero fields on `ApprovalParams` to opt out of the corresponding capability:_
 
-- `securityCommitments == []` — no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure).
-- `blsPubkey == [0,0,0,0]` — operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator.
-- `teeCommitments == []` — operator does NOT bind to a TEE attestation profile.
+- `securityCommitments == []` - no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure).
+- `blsPubkey == [0,0,0,0]` - operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator.
+- `teeCommitments == []` - operator does NOT bind to a TEE attestation profile.
 
 #### getTeeCommitmentRoot
 
@@ -75,7 +75,7 @@ Returns `keccak256(abi.encode(commitments))` over an operator's `TeeAttestationC
 function teeNonceFor(uint64 requestId) external view returns (bytes32)
 ```
 
-Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request — it eliminates cross-request attestation replay at approval time.
+Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request - it eliminates cross-request attestation replay at approval time.
 
 #### blsPopMessage
 

pages/developers/api/reference/generated/ITangleServices.mdx

@@ -57,9 +57,9 @@ Approve a service request as one of its operators.
 
 _Single entrypoint covering every approval mode. Pass empty/zero fields on `ApprovalParams` to opt out of the corresponding capability:_
 
-- `securityCommitments == []` — no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure).
-- `blsPubkey == [0,0,0,0]` — operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator.
-- `teeCommitments == []` — operator does NOT bind to a TEE attestation profile.
+- `securityCommitments == []` - no per-asset commitment supplied. Only valid when the request has no security requirements OR the only requirement is the protocol-default TNT requirement (auto-filled at min-exposure).
+- `blsPubkey == [0,0,0,0]` - operator does NOT register a BLS pubkey for aggregated job-result signing. BLS is opt-in; the protocol accepts any operator.
+- `teeCommitments == []` - operator does NOT bind to a TEE attestation profile.
 
 #### getTeeCommitmentRoot
 
@@ -75,7 +75,7 @@ Returns `keccak256(abi.encode(commitments))` over an operator's `TeeAttestationC
 function teeNonceFor(uint64 requestId) external view returns (bytes32)
 ```
 
-Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request — it eliminates cross-request attestation replay at approval time.
+Canonical TEE attestation nonce binding for `requestId` on this contract on this chain. Operators MUST submit this exact value as `nonceBinding` in any `TeeAttestationCommitment` for the request - it eliminates cross-request attestation replay at approval time.
 
 #### blsPopMessage
 

pages/developers/blueprint-contexts/introduction.mdx

@@ -27,7 +27,7 @@ The Context pattern offers several significant benefits in software design and d
 
 1. **Decoupling**: By passing dependencies through a Context, we decouple the job implementation from the specific implementations of its dependencies. This makes the code more modular and easier to maintain.
 
-2. **Testability**: With a Context, it's easier to mock or stub dependencies during unit testing, allowing for more comprehensive and isolated tests.
+2. **Testability**: With a Context, tests can replace RPC clients, keystores, or service clients with mocks and fixtures.
 
 3. **Flexibility**: Contexts allow for easy swapping of implementations, which is particularly useful when adapting to different environments (e.g., development, staging, production).
 

pages/developers/blueprint-qos.mdx

@@ -350,9 +350,9 @@ event MetricViolation(
 
 Violation reasons include:
 
-- `"required metric missing"` — a required metric was not reported
-- `"value below minimum"` — reported value < `minValue`
-- `"value above maximum"` — reported value > `maxValue`
+- `"required metric missing"` - a required metric was not reported
+- `"value below minimum"` - reported value < `minValue`
+- `"value above maximum"` - reported value > `maxValue`
 
 Slashing is intentionally decoupled from validation. Auto-slashing from metric violations is dangerous because transient spikes or network delays could trigger false positives. Instead:
 

pages/developers/blueprint-runner/background-services.mdx

@@ -86,6 +86,6 @@ Now that you understand background services, it might be helpful to take a look
 - [Consumers](/developers/blueprint-runner/consumers) - How to handle job results
 - [Building a Blueprint Runner](/developers/blueprint-runner/building) - Step-by-step guide to building your own Blueprint Runner
 
-## Conclusion
+## Before You Ship
 
-Background services are powerful components that enhance the capabilities of your Blueprint Runner by providing continuous support operations. By implementing well-designed background services, you can build more robust, efficient, and feature-rich Blueprints.
+Verify that each background service starts, reports failure, and shuts down cleanly. If the service owns a connection, lock, or local process, its shutdown handler should release that resource before the runner exits.

pages/developers/blueprint-runner/building.mdx

@@ -165,7 +165,7 @@ let result = BlueprintRunner::builder(tangle_config, env)
 
 The `run` method starts the Blueprint Runner and returns a result indicating whether it ran successfully or encountered an error.
 
-With this, the Blueprint Runner, the centerpoint of your Blueprint is ready to be used!
+With this, the Blueprint Runner can start and serve the components you attached to the builder.
 
 ## Next Steps
 
@@ -175,6 +175,6 @@ After building your Blueprint Runner, you might want to explore:
 - [Producer Patterns](/developers/blueprint-runner/producers#producer-patterns)
 - [Consumer Patterns](/developers/blueprint-runner/consumers#consumer-patterns)
 
-## Conclusion
+## Before You Ship
 
-Building a Blueprint Runner involves setting up various components that work together to execute your Tangle Blueprint. By following this guide and adhering to best practices, you can create a robust and efficient Blueprint Runner for your blueprint service on the Tangle Network.
+Run the runner against a local node or testnet, submit one real job, and keep the transaction hash plus runner logs. A runner is ready for operators only after it can start, receive a job, execute the handler, and return the expected result.