docs: star not mesh — this repo is true north, and the two tiers are named

[DealAppSeo]

Replaces the five-row sibling table merged earlier today in #686, and names the two documentation tiers Sean decided on 2026-09-08.

The table was wrong when it merged, and the shape was the defect

DealAppSeo/trustrails-dev is live and was not in it. But the missing row is not the problem — the shape is.

The ecosystem is not five repos. TrustShell, TrustMarket, TrustRepID, TrustRails, TrustTrader, TrustCRE, TrustEscrow and TrustMedical all sit on this same HAL / RepID / ERC-8004 / x402 harness, plus whatever third parties build via TrustMarket. A per-repo list of all siblings is N tables of N rows: adding a surface means editing every other repo, and forgetting fails silently and in the safe-looking direction — the new surface is simply unlisted, nothing breaks, and an agent landing there sees no pointer.

That is precisely the defect the table was added to fix, reintroduced one level up. It is the same lesson already recorded in this file under Test layout about the hand-maintained jest roots list: prefer a discovery rule to a list anywhere this pattern appears.

A star, not a mesh. Every repo names true north and nothing else. One line per repo, a new surface touches only itself, no table exists to go stale.

Two tiers

tier	who	where
Internal — operating log, dated, changes without notice	our agents (CC, XC, GA, the swarm)	LESSONS.md, then this file
Published — the contract we keep	outside developers building on the ecosystem	hyperdag-protocol/BUILDERS.md (DealAppSeo/hyperdag-protocol#20)

Never answer an outside builder from the internal tier. These repos are public so both are readable, but a working log is not a promise — much of both exists to stop one specific past mistake recurring. Answer from BUILDERS.md; if it does not cover the question, that is a gap in BUILDERS.md to fix.

Origin is authorization, not a third tier

Sean raised whether there should be three tiers — internal agents, TrustShell agents, TrustMarket agents — and then answered it: grant controls on the agent regardless of which surface it entered on. That is right, and the security argument is decisive.

If capability varied by entry surface, the surface would become the attack surface — an agent would shop for the most permissive door, and TrustMarket, the door we actively want outside builders to use, would be the one everyone picked. Capability belongs to the principal.

Two things measured while working this out, both recorded in BUILDERS.md rather than assumed:

• REPID_API_KEYS tier (pro/enterprise) is rate-limiting only — src/middleware/rateLimit.ts:28,32 are its only consumers. That is a throughput axis, not a capability axis, and conflating them would equate "pays more" with "has earned trust."
• permissioned_vaults.min_tier_required exists as a column and nothing in src/ reads it. Same shape as the ecosystem-need multiplier already documented in this file: recorded as though it gates something, gating nothing. BUILDERS.md tells outside builders this explicitly so they do not ship a security control assuming the platform gates for them.

Per-origin docs on every surface would be the same N-tables trap in a different costume.

Verification

• npm run check → VERIFIED (1 check).
• tests/lessons-injectable.test.ts → 10/10. LESSONS.md is untouched by this PR, so the 6000-character injection cap is unaffected — the tier block went in CLAUDE.md, which has no cap, so the capped file did not have to give anything up for it.
• Documentation only; no code paths touched.

🤖 Generated with Claude Code

https://claude.ai/code/session_01F3yrSVaGDLirLw4itQJ5wK

---

Generated by Claude Code

[strix-security]

Strix Security Review

No security issues found.

_{Updated for 35f3115.}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}

[strix-security]

This PR is a documentation-only change to CLAUDE.md. It replaces a hand-maintained five-row table of sibling repository entry points with a "star, not mesh" model (each repo points only to true north), and introduces a two-tier documentation policy distinguishing an internal operating log from a published builder contract. The change touches no application code, introduces no secrets, injection sinks, or authorization changes, and the new guidance ("never answer an outside builder from the internal tier") is security-positive. No security vulnerabilities were identified in the changed code.

---

Reviewed by Strix
_{Configure security review settings}