docs(copy): ground claims and sandbox boundaries#155
Conversation
✅ Deploy Preview for tangle-docs ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
tangletools
left a comment
tangletools
left a comment
There was a problem hiding this comment.
✅ Auto-approved PR — e6c77c31
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-15T23:03:36Z
tangletools
left a comment
tangletools
left a comment
There was a problem hiding this comment.
🟡 Value Audit — sound-with-nits
| Verdict | sound-with-nits |
| Concerns | 3 (3 weak-concern) |
| Heuristic | 0.0s |
| Duplication | 0.0s |
| Interrogation | 247.7s (2 bridge agents) |
| Total | 247.7s |
💰 Value — sound-with-nits
Documentation copy revision that grounds marketing claims in protocol mechanisms and adds actionable pre-ship checklists across 56 pages; a good change with one minor Gateway wording inconsistency.
- What it does: Revises 56 MDX documentation pages. Adds NanoClaw to sandbox harness lists (12→13 peer backends), replaces vague/marketing phrasing with concrete protocol concepts (service instances, Merkle proofs, operator endpoints, policy checks), converts generic 'Conclusion' sections into concrete 'Before You Ship' checklists, and normalizes em-dashes to hyphens in touched files. It also adds role-based navi
- Goals it achieves: Make the docs more accurate, actionable, and resistant to slop/marketing inflation; prevent readers from mistaking OpenCode or any single harness for the whole sandbox product; align Gateway, staking, network, and infrastructure copy with the actual on-chain and API mechanisms; give operators and developers explicit pre-flight and pre-ship steps instead of platitudes.
- Assessment: Coherent and worthwhile. The concrete checklists and protocol-grounded language are clear improvements over the previous generic conclusions. Harness framing now matches the canonical page at pages/infrastructure/harnesses.mdx and the existing check-harness-copy.mjs guard. Edits to pages/developers/api/reference/ITangleServices.mdx and its generated/ copy keep the parity enforced by scripts/check-
- Better / existing approach: none — this is the right approach for the harness and copy grounding work. The codebase already has scripts/check-harness-copy.mjs and scripts/check-tnt-core-sync.mjs to enforce the patterns the PR relies on. I searched pages/ for harness references and confirmed the canonical list lives at pages/infrastructure/harnesses.mdx; the PR propagates that framing. The duplicate ITangleServices files are
🎯 Usefulness — sound-with-nits
Docs copy cleanup that grounds claims in protocol mechanisms, adds actionable operator/developer guidance, and is fully wired into the existing Nextra navigation and automated copy/sync checks.
- Integration: All changed MDX files are reachable from the site navigation: pages/developers/_meta.ts:31 lists
endpoints; pages/gateway/_meta.ts:4-61 lists every changed gateway page; pages/infrastructure/_meta.ts:3-10 listsarchitecture,orchestration,harnesses, andsandboxing; pages/vibe/_meta.ts:3-14 listsintegrations,simulations,profiles, andprofile-schema; pages/staking/_meta.ts, pag - Fit with existing patterns: Changes follow established docs conventions: Nextra meta navigation, MDX pages, internal cross-references, and automated checks. The two-mode runtime framing in pages/infrastructure/architecture.mdx:5-12 matches the existing hosted-vs-protocol language in pages/infrastructure/introduction.mdx:7. Gateway routing language (
registered operators,advertised endpoints,X-Tangle-Blueprint/`Operato - Real-world viability: The new
Before You Shipsections in pages/developers/blueprint-runner/building.mdx:178-180, jobs.mdx:104-106, routers.mdx:77-79, producers.mdx:100-102, consumers.mdx:102-104, and background-services.mdx:89-91 explicitly cover invalid input, failed results, unknown job IDs, ordering, and clean shutdown, so they hold up beyond the happy path. Gateway operator routing honestly flags self-reported e
💰 Value Audit
🟡 Gateway 'centralized providers' wording remains inconsistent after the pass [better-architecture] ``
pages/gateway/index.mdx and pages/gateway/models.mdx were updated to 'provider APIs and registered Tangle operators' / 'operators registered on Tangle', but pages/gateway/operator-routing.mdx:35 still says the gateway checks operators 'before trying centralized providers'. A one-line update to 'before trying provider APIs' would complete the consistency pass the PR already did elsewhere.
🎯 Usefulness Audit
🟡 Unverifiable numeric sync interval in gateway docs [robustness] ``
pages/gateway/operator-routing.mdx:27 states the gateway 'syncs operator data from the chain every 60 seconds'. No source in this repo corroborates that interval, so the docs can silently go stale if the gateway implementation changes. Tie the number to a gateway config/ENV value or add a source pointer.
🟡 Generated ITangleServices copy is unlinked dead surface [integration] ``
pages/developers/api/reference/generated/ITangleServices.mdx has no inbound links (grep for
/api/reference/generated/returned no matches across pages) and is not in any_meta.ts; only scripts/check-tnt-core-sync.mjs:36-43 forces it to match the linked non-generated copy. This duplication predates the PR, but the PR keeps both copies in sync. Consider removing the generated/ copy or redirecting traffic to the linked reference page.
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.
2 participants
Summary
/api/capabilities.Preview
Verification
node /home/drew/code/dotfiles/claude/skills/docs-slop-audit/scripts/scan-docs-slop.mjs --json pages-> 42 low findings, 0 high, 0 medium.yarn format:check-> passed locally and in CI.yarn check:harness-copy-> passed locally and in CI.TNT_CORE_DIR=/home/drew/code/tnt-core yarn check:tnt-core-sync-> passed locally;tnt-core syncpassed in CI.yarn build-> passed locally; CIrun (22.x)passed.git merge-tree --write-tree origin/main HEAD->52efea27093b4ec290a9f26968da4ea932c7ece5.