docs(usai-catalog): seven sites assert the catalog pipeline is unbuilt after it shipped #489

Finding

Seven documentation sites in and around the USAi catalog subsystem assert things that are no longer true — in several cases describing the repository as it was before the work they describe had landed. Each was verified by reading the file and measuring the countering fact; verdicts and evidence below.

This is scoped deliberately against three existing issues so the boundaries are explicit:

• usai-provider README's vendor mapping table documents a dead Cohere row #393 already owns the dead Cohere row in the usai-provider README's vendor table. Not duplicated here.
• Cleanup: strip pre-existing ephemeral issue/PR refs from code comments (repo-wide) #384 owns the repo-wide sweep of ~80 bare #NNN tracker refs in comments. The items below are factually false claims, not reference-hygiene, so they are a different defect class.
• prime-agent kit: docs + ADRs (independently authored) #375 owns writing prime-agent's README/TROUBLESHOOTING and ADRs, and depends on #370/#371/#372 — all still open. The false claims below should be corrected now rather than waiting for that, because they actively mislead anyone evaluating whether the kit is usable.

Two of these are worth separating from ordinary drift, because the text was authored or re-authored after the thing it denies already existed:

• Item 5's comment was written in the same commit that added the emitter it says does not exist yet — and the next sentence of that same comment depends on the emitter existing.
• Item 3's sentence was re-authored on 2026-09-23, after the catalog it calls future work had already been populated.

A third is a genuine regression rather than drift: item 6's claim was true, the code it described was deleted, and the prose was never updated.

1. prime-agent/spec.yaml:99-104 — claims the emitter does not exist and the catalog is empty

# prime-agent emitter (...#362) — the emitter does
# not exist yet, so the committed models.json is a minimal, valid PLACEHOLDER
# (apiKey is the ENV-VAR NAME "USAI_API_KEY", not a secret; empty models[]).

CONFIRMED FALSE, twice over. integrations/providers/usai/emitters/prime-agent.mjs exists and exports emitPrimeAgentModelsFromCatalog. The committed files/home/prime-agent-config/models.json has 20 models, not an empty list — and it is byte-identical to the emitter's output, enforced by tests/models-json-regen.test.mjs ("committed kit models.json equals the emitter output byte-for-byte", passing). There is also no top-level models key at all; the shape is providers.usai.models.

The apiKey clause is true (it really is the env-var name), and "do not hand-edit the model list" is now more true than when written — a hand edit breaks the byte-exact test.

Same claim repeats at spec.yaml:108 ("placeholder committed here" — the provenance half is correct, "placeholder" is not). spec.yaml:30-32 is accurate and should be left alone: it asserts generation-by-emitter without claiming absence, and its "#372" deferral is still real.

2. prime-agent/README.md:23-27 — same claim

| `files/home/prime-agent-config/models.json` | placeholder catalog | generated by the USAi catalog emitter (#362) |
...
env-var **name** `USAI_API_KEY` (not a secret) and `models` is empty. The #362
emitter replaces its contents later — do not hand-edit the model list.

CONFIRMED FALSE. Same measurement as item 1. The status table marks as pending-future the one artifact in it that is already done and CI-gated. "replaces its contents later" is false only in tense — it already did.

3. acq-kits/kits.yaml:135-137 — the catalog "land[s] in follow-up work"

only: the three scripts are placeholders; the real install/CA-bundle/
kernel logic and the generated model catalog
(files/home/prime-agent-config/models.json) land in follow-up work tracked
in the patterns repo's prime-agent epic.

PARTIALLY TRUE — the false part is one clause. "The three scripts are placeholders" is verified true (all three only echo), and the egress sentence that follows is correct. But the model catalog has already landed, so that clause is false while welded into a true sentence, which is why it reads as plausible.

Note this was re-authored at 5d1a877 (2026-09-23), after the catalog was populated — not simple staleness.

4. providers/usai/scripts/build-catalog.mjs:10-12 — the render half "lives in a later issue"

// `usai-model-catalog/v1`). It DOES NOT render any harness config — the RENDER
// half (the opencode.jsonc emitter) lives in a later issue and consumes this
// catalog. The byte-exact round-trip test against the shipped opencode.jsonc is

CONFIRMED FALSE. emitters/opencode.mjs exists, self-describes as "the RENDER half of the USAi catalog pipeline (opencode target)", is imported by tests/emitters.test.mjs:23, and its two byte-exact round-trip tests pass against both shipped copies.

The decisive detail: line 11 was authored in 305dfa8 — the same commit that added emitters/opencode.mjs. The emitter did not land later; it landed simultaneously. And the very next sentence of that comment presupposes the emitter exists ("The byte-exact round-trip test against the shipped opencode.jsonc is the safety gate"), so the paragraph contradicts itself internally.

5. usai-provider/README.md:172 — scripts/verify recognizes the ownership marker

> It ... survives the verbatim-copy
> path and lets `scripts/verify` recognize the kit's own config.

PARTIALLY TRUE — the final clause is false, and it is a regression. scripts/verify never greps for usai-provider:owns-opencode-config (zero occurrences in the file). It greps for the provider key:

verify:96   grep -q '"usai"' "$glob"
verify:110  grep -q "usai-verify-probe" ... && grep -q '"usai"' ...

And it explicitly disclaims the marker check at verify:92-95: "we don't require the marker here since a merge into a foreign config drops comments."

History shows this was once true: the grep was added at 598a57c as grep -q 'usai-provider-kit:owns-opencode-config' and removed at 5de0f3b. The acq-kits copy branched from the post-removal version, so its verify never had it, while the README sentence carried the pre-removal claim forward.

The other three clauses are true: the marker is present, it is a comment not a key, and it does survive the verbatim-copy path — asserted by tests/merge-global-config.test.mjs:128. So something does consume the marker: the test suite, not scripts/verify. Same false sentence appears in sbx-kits/usai-provider-kit/README.md.

6. Two citations of an ADR that does not exist

usai-provider/spec.yaml:47 and scripts/normalize-catalog.mjs:13 both cite:

integrations/isolation/docs/decisions/0004-neutral-model-provider-discovery.md

That directory contains only 0001-neutral-hybrid-v1-acq-kits.md and 0002-neutral-network-egress-tiers.md. The cited file has never existed on any ref in this tree — it is on the unmerged branch for #423.

Both citations are hedged ("this ADR is pending merge in a separate PR; the path will resolve once it lands"), so the text is honest about the absence. The unhedged defect is a number collision: the same kit directory contains usai-provider/docs/decisions/0004-global-config-merge-instead-of-opencode-config.md, so a reader following "ADR 0004" by number lands on a document about OpenCode global-config merge — an unrelated subject. Nothing warns them.

Separately, normalize-catalog.mjs:12-15 is garbled independent of the ADR question — "that some other process (build-catalog.mjs, upstream in / <path> / ... for why a provider-neutral shape exists" has no verb. A clause was lost in an edit.

7. Two incomplete enumerations presented as complete

providers/usai/README.md:37-41 has a ## Files section listing 2 of 17 files. It omits both emitters — the components its own data-flow line centers on (:10 "live feeds → build-catalog.mjs → catalog.json → per-harness emitters") — and scripts/build-catalog.mjs, which the README instructs the reader to run two sections earlier. It omits every file the README elsewhere tells you to use.

usai-provider/README.md:247-261 has a ## Layout block drawn as a closed tree. files/home/usai-config/ is drawn with └── merge-global-config.mjs asserting last-child, but spec.yaml:97-99 declares a third shipped file in that exact directory: model-catalog-snapshot.json (real, acq-neutral-model-catalog/v1, 4 models). Also missing: scripts/normalize-catalog.mjs (the tool that generates it) and TROUBLESHOOTING.md (which the same README links at :134). Neither "normalize-catalog" nor "snapshot" appears anywhere in that README.

So the kit ships a guest-visible model catalog and its generator, and its README mentions neither.

Not filed, deliberately

I checked one more candidate and it is still true, so it is excluded: kits.yaml:156-158's pi-coding-agent claim "no emitter exists yet to populate it". Read in isolation that looks false (two emitters exist), but the clause is bound by its own sentence to a pi-specific emitter — "will land in a follow-up alongside a real pi USAi-catalog emitter" — and no pi emitter exists. The kit's own spec.yaml:37-39 and README.md:30-33 say so explicitly and correctly describe prime-agent's catalog as populated, making pi-coding-agent the one place in the repo that gets item 1-3's fact right. At most kits.yaml is ambiguous when quoted alone because it drops the word "pi"; that is a wording nit, not an error.

Suggested fix

One docs-only PR. For each item, state the present tense fact rather than deleting the sentence — several of these comments carry real rationale (the apiKey-is-a-name note, the don't-hand-edit warning, the marker's comment-not-key reasoning) that should survive the correction.

Two worth a little more than a wording change: the ADR number collision (item 6) needs either a renumber or an explicit disambiguating note, and the normalize-catalog.mjs:12-15 sentence needs reconstructing rather than patching.

AI-assisted (OpenCode). Advisory — requires human review.