docs: two-tier true north — public BUILDERS.md, star pointer, npm claim corrected

[DealAppSeo]

Description

Sean's decision: two documentation tiers. An internal operating log for our own agents, and a published contract for outside developers building on the ecosystem. Origin — TrustShell agent vs TrustMarket agent vs direct integration — is an authorization input, not a third documentation axis; per-origin docs on every surface would reintroduce exactly the N-tables problem this change removes.

1. BUILDERS.md — the published tier

What is actually installable today, what is stable versus what will move, the three-outcome reporting rule, the anti-Sybil counterparty gate, and what an outside builder must not design against.

Two things in it are worth calling out because most projects would omit them:

• It says tier-gated capability is largely NOT ENFORCED in code today. The schema carries a minimum-tier field on permissioned resources and nothing in the engine reads it. Rather than let a builder infer a guarantee from a column name and ship a security control that assumes the platform gates for them, the doc says so and tells them to enforce their own boundaries.
• It points builders away from CLAUDE.md and repid-engine/LESSONS.md. Those are readable — the repos are public — but they are an operating log, not a contract, and reading them as an API guarantee will mislead.

Capability is framed as a property of the principal, not the entry surface. If it varied by surface, the surface would become the attack surface, and the most open door — the one we actively want outside builders to use — would be the one everyone picked. The ladder is earned RepID tier, which is already ERC-8004-anchored (portable) and already demoted on unique-counterparty count (unfarmable). A second private trust ladder would be neither portable nor auditable.

2. The npm claim in CLAUDE.md was wrong — measured and corrected

That file, merged earlier today, said this repo is "published as @hyperdag/protocol on npm." It is not.

NOT PUBLISHED (404)  @hyperdag/protocol
PUBLISHED            @hyperdag/trustshell@1.3.0
NOT PUBLISHED (404)  @hyperdag/identity-erc8004
NOT PUBLISHED (404)  @hyperdag/reputation-zkp

I read it off the npm badge at the top of README.md — while the README's own "Known broken / not live" table, three screens further down, said plainly that it 404s. A badge is a link, not a measurement. Same class as reading -stub in a filename as evidence about production, which is the error repid-engine/CLAUDE.md already records.

BUILDERS.md sends builders to @hyperdag/trustshell, the one package that exists, and names the badge as a known trap.

3. The mesh table is gone; a star replaces it

The five-row sibling table added here earlier today was already wrong when it merged — DealAppSeo/trustrails-dev is live and was not in it. The shape was the defect, not the missing row.

The ecosystem spans TrustShell, TrustMarket, TrustRepID, TrustRails, TrustTrader, TrustCRE, TrustEscrow and TrustMedical on the same HAL / RepID / ERC-8004 / x402 harness, plus third-party builders. 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 — the new surface is simply unlisted, nothing breaks, and an agent landing there sees no pointer.

Every repo now names true north and nothing else. One line per repo; a new surface touches only itself; no table exists to go stale.

README.md links BUILDERS.md above the existing trustshell install line.

Type of change

• Bug fix (non-breaking change which fixes an issue)
• New feature (non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to not work as expected)
• Documentation update

How Has This Been Tested?

Documentation only — three files, no code paths touched, nothing built or imported differently.

Every factual claim in BUILDERS.md was measured rather than carried over:

• npm publication state — npm view <pkg> version run against all four packages; output above.
• Registry addresses and chain id — taken from README.md's live table, not restated from memory.
• REPID_API_KEYS tier is rate-limiting only — src/middleware/rateLimit.ts:28,32 in repid-engine are the only consumers; nothing else reads it. This is why the doc separates the throughput axis from the capability axis.
• min_tier_required is unenforced — the column exists on permissioned_vaults in the generated database types, and grep across repid-engine/src (excluding the generated types file) returns no reader. This is the claim the doc makes to builders, so it was verified as a negative before being published as one.
• The six-interface kernel is not on main — stated from this repo's own "Known broken / not live" table.

NOT CHECKED: whether any consumer outside repid-engine/src enforces min_tier_required — the doc's wording is scoped to "nothing in the engine reads it" for that reason, and tells builders to enforce their own boundaries regardless.

Checklist:

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• I have commented my code, particularly in hard-to-understand areas
• I have made corresponding changes to the documentation
• My changes generate no new warnings
• Any dependent changes have been merged and published in downstream modules

🤖 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 cad69f9.}

---

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