Documentation inventory and tier classification
This file classifies every.mdx page in the repository into one of three edit tiers, and registers every sentence that is locked regardless of tier. Read it to find out what may be rewritten, what may only be restructured, and what may not be touched at all.
Counted on 2026-08-01 against commit 487f413.
- 229
.mdxfiles, all reachable fromdocs.json. - No orphan pages. No dangling navigation entries. Verified by diffing the 229 navigation references against the 229 files on disk.
- 5 top-level sections:
protocol/,licenses/,sdk/,endpoints/,security/.
Separately, 78 sentences across 50 files are locked at sentence level. Those locks apply inside Tier 2 and Tier 3 files too. See Locked sentences.
Read this before using the tier table
The task brief describes a repository that is not this one. Six of the artifacts the brief names as Tier 1 anchors do not exist here. This is not a judgment about whether they should exist. It is a statement about what is on disk, and it changes what Step 1 can honestly deliver.
Consequences for the rest of this task:
- Tier 1 cannot be defined by the brief’s file list. It is defined here by content signal instead. That rule is mechanical and re-runnable, which matters more than matching a file list that does not apply.
-
Five of the six named readers have no page written for them. The docs today serve the integration engineer, and partially serve the tokenization platform. There is no page addressed to a bank or lender of record, a register provider, a custodian, or an issuer. That gap is logged in
docs/OPEN-QUESTIONS.md, not filled by invention. -
Several Step 2 and Step 3 rules have no target here yet. The German-term rules, the transliteration rule, and the “lender of record / register provider / Registerfuehrer” rule have nothing to apply to. They go into
docs/STYLEGUIDE.mdanyway, because they bind the pages that do not exist yet, and the Vale configuration enforces them from the first day such a page is written.
How a file gets its tier
A file is Tier 1 when the page’s purpose is the regulatory argument. Two signals, either one sufficient: Statutory framework cited as a legal claim. “Under MiCA, the beneficial ownership transfer at settlement time must be compliant” is a legal claim. “MiCA Register API keys” is a product name. Only the first counts. This distinction matters: treating every occurrence of the stringMiCA as a citation would have locked all 8 mica-register/ pages, which are ordinary REST reference pages for a public ESMA data lookup and carry no legal argument at all.
The page’s subject is Trusset’s own role, control, or custody posture. Five pages exist to say what Trusset cannot do. Rewording them is rewording the argument.
Everything else is Tier 2 if it sits in protocol/, licenses/, or security/, and Tier 3 if it sits in endpoints/ or sdk/.
Why tier alone is not enough
A single “Nothing is submitted on your behalf” note on an API endpoint page is a locked sentence. It is not evidence that the whole page is a binding legal reference. Thirteenendpoints/stock-tokenization/ write endpoints carry that sentence and nothing else regulatory. Promoting all thirteen to Tier 1 would freeze thirteen pages of ordinary parameter tables to protect one line of shared boilerplate. Leaving them fully open would let that line drift.
So there are two independent mechanisms:
- The tier governs the file. It decides how freely the page may be restructured and rewritten.
- The sentence lock governs the sentence. A sentence carrying a statutory citation, a negative capability claim, or a numeric protocol bound is locked byte for byte wherever it appears, at any tier.
Tier 1, locked: 16 files
Tier 2, product and process: 13 files
protocol/intro.mdx, protocol/integration/overview.mdx, protocol/infrastructure/instances.mdx, security/changelog.mdx, security/trusset-audits.mdx, and the 8 licenses/*/ pages carrying no statutory claim: commodities/integration, commodities/best-practices, commodity-orderbook/contracts, commodity-orderbook/integration, commodity-orderbook/best-practices, stocks/integration, stock-orderbook/contracts, stock-orderbook/integration.
protocol/intro.mdx is the landing page of the docs and is the one page where positioning language belongs.
Tier 3, developer: 200 files
All ofendpoints/ except its 2 Tier 1 pages, and all of sdk/ except sdk/customers/identity.mdx. 32 of these carry locked sentences.
Locked sentences, independent of tier
78 sentences across 50 files. Reword none of them. They may be moved between sections and given a different heading.Negative capability claims
These are the regulatory argument. Do not soften and do not strengthen.
One conflict to resolve before the Tier 1 pass, logged in
docs/OPEN-QUESTIONS.md: protocol/infrastructure/custody.mdx line 88 reads “We only need your public address and the signatures you produce.” It sits inside a locked negative claim and uses “we” for Trusset, which the style guide bans. The lock wins until someone with authority to restate the claim says otherwise.
Numeric protocol bounds
One deliberate exclusion:
endpoints/authentication.mdx states that a rotated API key “remains valid for 7 days”. That is a key rotation overlap, not the liquidation write-off window. The page stays Tier 3. The number stays locked as a fact, like every number in the docs.
Structural findings the style pass has to deal with
Structure and accuracy problems, not voice problems. Recorded here because the tier classification is the moment to notice them.stock-lending/ and external-securities-lending/ are two products, documented to different depths
51 files and 57 files. They are separate products with separate purposes, both live, and neither supersedes the other. external-securities-lending is the more important of the two and is verified working.
They are not documented to the same depth. Counting write endpoints only, external-securities-lending documents the txHash confirm call on 20 of 27, and stock-lending on 7 of 23. The omissions in the first section are coherent: hooks write backend configuration, and the price endpoints produce a signature without submitting anything, so there is nothing to confirm. stock-lending omits those same six and then ten more that do touch the chain.
Whether those ten accept a confirm call is a question about the API, not about the prose, so it is logged rather than answered. See docs/OPEN-QUESTIONS.md item 3 for the list.
The first pass reported this as “35 of 51 pages missing the confirm pattern”. That number counted GET endpoints, which never need it, and counted a txHash appearing in a response example as documentation. The real figure is ten write endpoints.
The relayer removal is mostly done, and the leftovers are naming, not behaviour
Step 4 of the brief flags pages that still describe a Trusset-side relayer or Trusset-side signing. I found none.endpoints/introduction.mdx states the current model plainly: “They return an unsigned payload built against the target contract. You sign it with your registered wallet and broadcast it yourself.” Commit 8ba8112 did that work.
What remains is a legacy identifier, not a stale description:
RELAYER_NOT_CONFIGUREDis a live error code in 6 files, glossed everywhere as “No verified wallet is registered on this instance”. The gloss is correct. The code name is not.relayerAddressis a live response field in 4external-securities-lending/files, glossed as “the instance’s registered wallet address”.
docs/OPEN-QUESTIONS.md rather than changed.
Separately, licenses/commodities/ documents a keeperRelayer contract field. That is an unrelated on-chain address with an explicit “receives no implicit on-chain privileges” disclaimer, and has nothing to do with the removed issuer wallet relayer.
Style debt is smaller than expected and concentrated
The prior docs are in better shape than the brief assumes. Measured across all 229 files:
The single largest job is the 133 inline comments, which the style guide moves into surrounding prose.
The 26 JavaScript blocks were listed here as the second largest job before they were read. They are not a job. Hardhat config is
hardhat.config.js and Hardhat scripts use require; the CommonJS example exists to demonstrate require. All 26 are correctly JavaScript, and the style guide carries an explicit exception for both cases rather than a rule that would break working samples.
One transliteration inconsistency is already live: licenses/stocks/introduction.mdx writes “Gesetz uber elektronische Wertpapiere”, dropping the umlaut without transliterating. security/overview.mdx writes TÜV with the umlaut intact. Both cannot be right. The style guide picks one.
An unhedged certification claim, since corrected
security/overview.mdx line 31 stated that Trusset renews “our ISO certification with TÜV” once a year, while line 8 described a certification still in process. Both could not be true, and the overstated version is the one a counterparty checks.
It was left untouched during the pass and logged, because correcting a compliance claim on a guess is the exact failure this task exists to prevent. The status was then confirmed as in process and near completion, and the page now says so without forecasting a completion date. See docs/OPEN-QUESTIONS.md item 1.
This is why the log exists. The finding was worth more than a rewrite would have been.
Per-file classification
Every.mdx file, grouped by directory. “Locked sentences” counts sentence-level locks in that file, which apply at any tier.