feat(website): tool cards for the trios loop tri, generated from trios/bin/tri

[gHashTag]

What

The #/tools catalog now documents every command of the third tri program, the trios loop CLI (trios/bin/tri on gHashTag/BrowserOS branch feat/queen-supervisor). Each command is a .t27 card under apps/website/public/t27/files/specs/tools/trios/tri/, generated by scripts/tools-from-trios-tri.mjs from the source pinned at 7366096248dfb09893e9a7d1a0f1c56ced13d16e (gHashTag/BrowserOS#529, which makes the dispatcher in the repo match the live CLI).

• 295 cards. 252 commands are listed in tri help, and those cards carry the help line as their description (ABOUT_SOURCE = help). The other 43, all tc-*, are dispatched but missing from tri help, so their cards say so instead of inventing a description.
• Witness source-parse. Every card names the dispatch line it was read from, pinned to the commit above. Home-directory paths in the dispatch text are rewritten to ~/, so the contract's home-path rule holds.
• The 1 MB rule. With the trios cards inline, public/tools/spec-tools.json was 1.51 MB. The trios cards now keep a reduced field set, and they live in a separate file, public/tools/spec-tools-trios.json (888 KB). The main file (431 KB) names that file with its card count and a sha256 of its contents. readToolCatalog() in the generator and loadToolSpecs() in the UI both check the count and the hash before merging the two files.
• The docs generator, the four QA contracts and the UI all read the catalog through that join. tools-spec-contract has a new trios/tri branch. It checks the repo, the source path, the witness, the 40-hex pin, a dispatch line with no home path, documented against the help line, and a non-empty WHEN_TO_USE.
• The #/tools meta description and the notes in both languages now name all three tri programs.

Tests

Run locally in the worktree:

• node scripts/agents-from-specs.mjs --check and node scripts/docs-from-specs.mjs --check: both in sync.
• node scripts/agents-from-specs.test.mjs: 47/47. node scripts/docs-from-specs.test.mjs: 8/8.
• QA contracts: tools-spec (387 cards), tools-site, agents-spec and docs-spec pass.
• The pre-commit hooks explorer-language-contract and queen-language-contract pass.

The Vite build and tsc are left to CI.

Limitations

• No RU summaries for the trios cards yet (tools i18n covers 92/387), so the RU page shows the English text for them.
• The generator's own --check needs the external trios source checkout, so it is not CI-gated. CI gates the cards and the catalog, not their freshness against BrowserOS.
• Two problems that predate this PR are still open. sync-t27-specs.mjs empties its output directory, which would also delete site-authored tool cards. canonicalSpecEditUrl points every card at gHashTag/t27, including the cards that are only authored here.

{
  "version": 1,
  "head_sha": "5a982ba7cc6df1015722c6ca1c8653e4be425d67",
  "summary": "The tools catalog gains 295 generated .t27 cards documenting every command of the trios loop tri, read from trios/bin/tri at a pinned BrowserOS commit, with the trios cards split into a hash-checked part file to stay under the 1 MB limit.",
  "changes": [
    "Added scripts/tools-from-trios-tri.mjs, which parses trios/bin/tri at a pinned commit and writes one .t27 card per dispatched command.",
    "Generated 295 cards under specs/tools/trios/tri: 252 carry their tri help line, 43 tc-* commands are marked as missing from tri help.",
    "Split the trios cards into public/tools/spec-tools-trios.json and recorded its count and sha256 in the main catalog, which keeps both files under 1 MB.",
    "Added readToolCatalog in the generator and a joining loadToolSpecs in the UI; both verify the part count and hash before merging.",
    "Extended tools-spec-contract with a trios/tri branch covering repo, source path, witness, 40-hex pin, dispatch line, documented flag and WHEN_TO_USE.",
    "Rewrote home-directory paths in dispatch text to ~/ so no card leaks a local user path."
  ],
  "tests": [
    {"command": "node scripts/agents-from-specs.test.mjs", "result": "47 of 47 unit tests passed", "status": "passed", "evidence": "Local run in the PR worktree at the reported head commit."},
    {"command": "node scripts/docs-from-specs.test.mjs", "result": "8 of 8 unit tests passed", "status": "passed", "evidence": "Local run in the PR worktree at the reported head commit."},
    {"command": "node scripts/agents-from-specs.mjs --check && node scripts/docs-from-specs.mjs --check", "result": "generated catalogs match the committed files", "status": "passed", "evidence": "Both generators reported no drift for the committed JSON outputs."},
    {"command": "node qa/tools-spec-contract.mjs", "result": "387 tool cards pass the contract", "status": "passed", "evidence": "Includes the new trios/tri branch for all 295 trios cards."},
    {"command": "node qa/tools-site-contract.mjs && node qa/agents-spec-contract.mjs && node qa/docs-spec-contract.mjs", "result": "all three site contracts pass", "status": "passed", "evidence": "Each contract reads the catalog through readToolCatalog."},
    {"command": "vite build and tsc for apps/website", "result": "left to CI, not run locally", "status": "not_run", "evidence": "Heavy builds run in CI rather than on the development laptop."}
  ],
  "limitations": [
    "RU summaries for the 295 trios cards are not written yet, so the RU page shows English text for them.",
    "The generator check needs the external trios source checkout and is therefore not gated in CI.",
    "sync-t27-specs.mjs still empties its output directory, which would also delete site-authored tool cards.",
    "canonicalSpecEditUrl still points every card at gHashTag/t27, including cards authored only on the site."
  ],
  "tags": ["tri", "t27", "website", "docs"],
  "blog": {
    "title": "Every trios loop command now has a .t27 card",
    "summary": "The site catalog documents all three tri programs. The third, the trios loop CLI, contributes 295 cards generated from its own dispatcher, and 43 of them reveal commands missing from tri help.",
    "outline": [
      "Trinity has three programs called tri: the t27 Rust compiler CLI, the Trinity Zig CLI, and the trios loop CLI used by the queen supervisor.",
      "The first two already had .t27 cards on the tools page; the trios loop CLI had none, even though agents call it every day.",
      "The new generator reads the dispatcher in trios/bin/tri at a pinned commit and writes one card per command, with the help line as its description.",
      "Forty-three tc-* commands are dispatched but absent from tri help, and their cards record that gap rather than guessing what they do.",
      "Keeping the catalog under the 1 MB file limit meant moving the trios cards into a part file whose count and hash the loader verifies."
    ]
  }
}

🤖 Generated with Claude Code