docs(blueprints): rewrite product docs voice

[drewstone]

Summary

• rewrites the Blueprint docs section in a plain technical voice across the overview, protocol model, operator matrix, dapp integration, and product pages
• centers the correct Blueprint model: template -> operator registration -> user service request -> service instance -> jobs and queries
• documents AI Agent Sandbox, AI Trading, and Surplus Market with operator requirements, runtime expectations, and dapp/indexer boundaries without OpenCode-only framing

Validation

• rg -n "—|seamless|robust|powerful|cutting-edge|groundbreaking|game-changing|revolutionary|innovative|next-generation|world-class|best-in-class|state-of-the-art|delve|tapestry|landscape|paradigm|synergy|leverage|holistic|At its core|Let's dive|not just|more than just|showcase|underscores|pivotal|crucial|key role|ecosystem|platform|serves as|stands as|testament|Additionally|Moreover|In order to|It is important to note|simply|just" pages/blueprints returned no matches\n- git diff --check\n- yarn format:check\n- yarn build\n- git merge-tree --write-tree origin/main HEAD

[netlify]

✅ Deploy Preview for tangle-docs ready!

Name	Link
🔨 Latest commit	be71066
🔍 Latest deploy log	https://app.netlify.com/projects/tangle-docs/deploys/6a2f302709e75500082357e5
😎 Deploy Preview	https://deploy-preview-149--tangle-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[tangletools]

✅ Auto-approved PR — 4dc1e03b

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-14T22:38:25Z}

[tangletools]

🟡 Value Audit — sound-with-nits

Verdict	sound-with-nits
Concerns	2 (2 weak-concern)
Heuristic	0.0s
Duplication	0.0s
Interrogation	265.9s (2 bridge agents)
Total	265.9s

💰 Value — sound

Rewrites 16 blueprint product docs from generic/marketing voice to a plain technical voice, centers the correct template→operator→service-instance→jobs model, and adds concrete operator, dapp, and indexer boundaries for the three first-party blueprints.

• What it does: This change rewrites the pages/blueprints section (16 MDX files: overview, protocol-model, operator-matrix, dapp-integration, plus AI Agent Sandbox, AI Trading, and Surplus Market product sub-pages). It strips buzzwords and vendor-specific framing, replaces abstract capability descriptions with concrete lifecycles, env vars, ports, API endpoints, health checks, risk boundaries, and proof boundarie
• Goals it achieves: The change achieves three things evident from the diff: (1) accuracy — docs no longer conflate the blueprint template with the live service instance or imply OpenCode/Codex/etc. are the product boundary; (2) operator usefulness — pages now list real binary names, blueprint IDs, env vars, admission knobs, ports, and local proof commands rather than hand-wavy capability statements; (3) dapp/indexer
• Assessment: Good change. The rewrite is coherent, internally consistent, and fits the Nextra docs structure already in use. Line count drops by ~500 while information density rises. Cross-references between the product index pages and their operator/runtime/dapp sub-pages resolve, and factual details (e.g. AI Trading blueprint IDs 13/14/15, sandbox binary variants, surplus settlement rails) are placed on the
• Better / existing approach: none — this is the right approach. The docs are site-specific MDX content; there is no shared blueprint-doc template or component in the codebase that would let these product pages be collapsed into a single reusable structure without losing product-specific detail. I checked pages/blueprints/_meta.ts, pages/_meta.ts, pages/operators/manager/sizing.mdx, and pages/infrastructure/sandboxing.mdx; the

🎯 Usefulness — sound-with-nits

A coherent, source-grounded rewrite of the first-party blueprint product docs that is wired into the Nextra site and aligned with the protocol model; only a minor operator-port inaccuracy and an unverifiable surplus repo link are worth cleaning up.

• Integration: The new pages are fully wired into the docs site. The top-level pages/blueprints/_meta.ts declares separators and entries for AI Agent Sandbox, AI Trading, and Surplus Market, and each subdirectory has its own _meta.ts mapping index, operator-requirements, the runtime/settlement page, and dapp-and-indexer (e.g. pages/blueprints/ai-agent-sandbox/_meta.ts:4-7). The overview page links in
• Fit with existing patterns: It fits rather than competes. The product docs at pages/blueprints/ share the same blueprint/service-instance/job lifecycle used by the developer docs at pages/developers/blueprints/ (Blueprint -> Service -> Job in pages/developers/blueprints/introduction.mdx:38-46), but they target a different reader (operators and app builders vs. blueprint developers). The rewrite explicitly centers the c
• Real-world viability: The docs will hold up well. They repeatedly distinguish what the indexer can prove from what needs live operator-API checks, attestations, settlement receipts, or SP1 proofs (pages/blueprints/protocol-model.mdx:62-75), warn about paper-mode limits, allowlist admission, and per-bot spend caps (pages/blueprints/ai-trading/operator-requirements.mdx:50-65), and hedge network-specific IDs as config

🎯 Usefulness Audit

🟡 Sandbox operator API default port is stated as "around 9100" but the source defaults to 9090 [robustness] ``

In pages/blueprints/ai-agent-sandbox/operator-requirements.mdx:40 and pages/blueprints/operator-matrix.mdx:32 the docs say the AI Agent Sandbox operator API defaults around 9100. The upstream source code shows both ai-agent-sandbox-blueprint-bin/src/main.rs and ai-agent-instance-blueprint-bin/src/main.rs use .unwrap_or(9090) for OPERATOR_API_PORT. The README also lists the default as 9090. Either update the docs to 9090 or, if production examples intentionally use 9100, add a

🟡 Surplus source repo link returns 404 for unauthenticated readers [integration] ``

pages/blueprints/surplus-market/index.mdx:12 and pages/blueprints/index.mdx:51 link to https://github.com/tangle-network/surplus, which returns 404 from an anonymous fetch. The docs do honestly flag Surplus as a link-out app with minimal blueprintUi metadata (pages/blueprints/surplus-market/dapp-and-indexer.mdx:10-22), so this does not block the change, but if the repo is private the docs should either omit the public source link or note that access is restricted.

---

What this audit checks

It judges the change on its merits — not whether it was tasked out in an issue. Unticketed, fast-moving work is fine; the question is whether the change is good and whether a better or existing approach should be used instead.

Pass	What it asks
Heuristic	Vague title? Whitespace-only or cruft-bearing diff? (content signals only)
Duplication	Do added function/class names already exist elsewhere in the repo?
Value Audit	What does it do? What goal does it achieve? Is it good? Better architecture or already-exists?
Usefulness Audit	Does it integrate and fit? Will it hold up in real use and actually get used?

Findings are concerns, not blocks — the human reviewer decides what to do with them.

_{value-audit · 20260614T224448Z}

[tangletools]

✅ No Blockers — 4dc1e03b

Readiness 53/100 · Confidence 65/100 · 12 findings (6 medium, 6 low)

	deepseek	glm	aggregate
Readiness	59	53	53
Confidence	65	65	65
Correctness	59	53	53
Security	59	53	53
Testing	59	53	53
Architecture	59	53	53

Full multi-shot audit completed 1/1 planned shots over 16 changed files. Global verifier still owns final merge decision. | Full multi-shot audit completed 1/1 planned shots over 16 changed files. Global verifier still owns final merge decision.

🟠 MEDIUM Operator env var names removed from sandbox requirements — pages/blueprints/ai-agent-sandbox/operator-requirements.mdx

Old version listed explicit env var names (KEYSTORE_URI, HTTP_RPC_ENDPOINT, TANGLE_WS_URL, SANDBOX_UI_AUTH_MODE, SANDBOX_UI_BEARER_TOKEN). New version replaces them with conceptual rows like 'Operator keystore' and 'UI/API ingress auth'. Operators setting up from docs must now discover exact variable names from source repos or settings.env.example. The SESSION_AUTH_SECRET and BLUEPRINT_STATE_DIR remain explicit. Consider restoring the exact variable names in a reference appendix or keeping the conceptual table rows but adding the env var name in each description.

🟠 MEDIUM Strategy Packs table with cadence and max turns removed — pages/blueprints/ai-trading/index.mdx

The old version had a 7-row table listing strategy packs (prediction, dex, yield, perp, volatility, mm, multi) with their default tick cadence (1-15 minutes) and max turns (10-20). This is operator-relevant capacity-planning data. The new version's 'What the bot controls' table mentions strategy packs generically but drops all cadence and turn-limit numbers. Fix: either restore the table or confirm these values are documented in the repo's OPERATORS.md and link to it.

🟠 MEDIUM Trading contract address env vars removed — pages/blueprints/ai-trading/operator-requirements.mdx

Old page listed VAULT_FACTORY, TRADE_VALIDATOR, POLICY_ENGINE, FEE_DISTRIBUTOR, ASSET_TOKEN_ADDRESS as required configuration. New page only references these contracts generically in the trading index runtime page. An operator configuring from these docs needs to discover these variable names and contract addresses from source. The runtime-and-risk.mdx page mentions contract names (PolicyEngine, TradeValidator, vault contracts, fee distribution) but not the env var names.

🟠 MEDIUM Trading contract address env vars removed from operator requirements — pages/blueprints/ai-trading/operator-requirements.mdx

The old version listed OPERATOR_PRIVATE_KEY, VAULT_FACTORY, TRADE_VALIDATOR, POLICY_ENGINE, FEE_DISTRIBUTOR, and ASSET_TOKEN_ADDRESS as required service configuration. The new version's 'Required state' table omits all of these. The new text says 'Keep secrets in an untracked settings.env' but an operator reading only these docs would not know which contract addresses to set. OPERATOR_PRIVATE_KEY is critical — the binary signs protocol actions with it. Fix: either restore these vars in the table or add an explicit cross-reference to settings.env.example listing them by name.

🟠 MEDIUM Surplus mm-sidecar and instrument env vars dropped — pages/blueprints/surplus-market/operator-requirements.mdx

Old page specified SURPLUS_SIDECAR_URL (default http://127.0.0.1:9110), SURPLUS_INSTRUMENT (defaulting to Anthropic output-credit), and SURPLUS_MM_SIZE (minimum 1000, default 50000). All three removed. The mm-sidecar port 9110 is still referenced in the operator-matrix.mdx row 'keep private' but not in the surplus operator page. An operator trying to configure market-making from these docs alone would miss the exact variable names and their defaults.

🟠 MEDIUM WalletConnect shared-fallback security warning removed — pages/blueprints/surplus-market/operator-requirements.mdx

The old version had an 'App Environment' section listing VITE_WALLETCONNECT_PROJECT_ID with the note 'do not ship a shared fallback.' The entire section was removed in the rewrite. This is security-relevant guidance: a shared WalletConnect project ID is an operational hazard. The new version does say 'Do not put these in frontend env. They are operator secrets.' for settlement keys, but the WalletConnect-specific warning is gone. Fix: restore the VITE_WALLETCONNECT_PROJECT_ID guidance or add it to the surplus dapp-and-indexer page.

🟡 LOW Protocol adapter version numbers dropped from venue list — pages/blueprints/ai-trading/index.mdx

The old 'Protocol Coverage' table categorized venues with versions: Hyperliquid, GMX v2, Vertex (perpetuals); Uniswap V3, Aerodrome (DEX); Aave V3, Morpho (lending); Polymarket (prediction). The new 'What the bot controls' table lists venues inline without versions: 'Hyperliquid, Uniswap, Aave, GMX, Morpho, Vertex, Polymarket, Aerodrome.' An operator integrating with GMX v1 vs v2 or Uniswap V2 vs V3 needs the version. Fix: restore version numbers or link to the repo's adapter manifest.

🟡 LOW Default paper-trade setting reference lost — pages/blueprints/ai-trading/operator-requirements.mdx

Old safety knobs table listed DEFAULT_PAPER_TRADE with default true in templates. New page says 'The operator install path defaults new bots to paper trading' which is descriptive but doesn't give the variable name an operator would need to deliberately change this behavior. Similarly OPERATOR_MAX_CAPACITY default changed from 10 (old) to '0 or unset means unlimited' (new) — a potentially meaningful behavioral documentation change.

🟡 LOW Staking test gate names changed without verification — pages/blueprints/dapp-integration.mdx

The old version documented yarn test:wallet-flows:staking:gate and yarn test:staking:local-release. The new version replaces these with yarn test:staking:local-ui and adds build gates (yarn build:tangle-dapp, yarn build:tangle-cloud, yarn nx test tangle-cloud --run, yarn nx run dapp-config:build). This docs repo's package.json does not contain any of these scripts (they live in the dapp monorepo), so I could not verify whether the old script names were renamed or simply dropped from docs. If the old names still exist, the new docs may cause operators to miss the browser-level wallet-flow staking gate. Fix: confirm the monorepo script names match the new docs.

🟡 LOW Numeric job IDs dropped from job tables — pages/blueprints/surplus-market/index.mdx

The old Surplus Market index listed job IDs: 0 (list_instrument), 1 (configure), 2 (start_making), 3 (stop_making), 4 (status), 30 (workflow_tick). The new version lists job names only. The same pattern appears in pages/blueprints/ai-agent-sandbox/index.mdx (old had IDs 0-4, new drops them). Operators debugging on-chain transactions or querying the Tangle job manager need numeric IDs. Fix: restore the ID column.

🟡 LOW Source file references changed in surplus index — pages/blueprints/surplus-market/index.mdx

Sources section changed from referencing operator/src/config.rs and operator/src/inference.rs to operator/src/bin/blueprint.rs and operator/src/http.rs. This may reflect an actual repo restructure (the source repo link is provided), but without verification against the surplus repo's current state, this could be an accidental change. Low impact since readers are directed to the GitHub repo.

🟡 LOW Surplus inference and market-making env vars removed — pages/blueprints/surplus-market/settlement-and-inference.mdx

The old version documented SURPLUS_VLLM_PORT, SURPLUS_VLLM_ARGS, SURPLUS_ROUTER_URL, and SURPLUS_ROUTER_API_KEY. The new version's inference backend table only lists SURPLUS_VLLM_MODEL, SURPLUS_INFERENCE_URL, and SURPLUS_INFERENCE_API_KEY. Router fallback variables are referenced in prose ('Router fallback: Testing or non-bonded operation only') but their env var names are not documented. Also in surplus-market/operator-requirements.mdx: SURPLUS_INSTRUMENT, SURPLUS_MM_SIZE (min 1000, default 50000), SURPLUS_SIDECAR_URL (default http://127.0.0.1:9110), and SURPLUS_TOR_SOCKS were all dropped.

---

_{tangletools · 2026-06-14T22:44:49Z · trace}

[tangletools]

✅ Auto-approved PR — be710663

Blanket team auto-approval is enabled for this reviewer service.
The full PR reviewer audit still runs separately and will publish findings if it detects issues.

_{tangletools · auto-approval · reason: blanket_auto_approve · 2026-06-14T22:50:26Z}