book: the intrinsics guide covers only hand-written ops; the cuda-intrinsics-gen catalog workflow is undocumented #808

Filing the follow-up asked for in the #797 review.

What #797 fixed, and what it left

#797 corrected cuda-oxide-book/compiler/adding-new-intrinsics.md, which told contributors to define new dialect-nvvm ops in crates/dialect-nvvm/src/ops/thread.rs and ops/warp.rs. Neither file exists: both example ops are catalog entries, generated into ops/generated/. Following the old text either created a file nothing registers or edited a DO NOT EDIT generated file, and both fail quietly.

That PR's fix was to scope the page honestly — name the seven hand-written modules, and warn that catalog-described ops are generated. It deliberately did not document the generator, because that is a larger piece and the intended contributor path is yours to define.

So the page is now correct but incomplete: it explains the path for bespoke ops and tells you the other path exists without saying how to walk it. For scale, that other path is the majority — 986 catalog entries across 35 generated files.

What is undocumented today

No page in the book mentions cuda-intrinsics-gen or intrinsics/catalog.json except the warning #797 added. A contributor adding a catalog intrinsic gets no guidance on any of the following, all of which exist and are load-bearing:

The generator's surface, from its own usage text:

cuda-intrinsics-gen extract --intrinsics-json FILE --nvptx-json FILE
cuda-intrinsics-gen extract --llvm-src DIR --llvm-tblgen FILE
cuda-intrinsics-gen generate
cuda-intrinsics-gen check
cuda-intrinsics-gen coverage [--family NAME]
cuda-intrinsics-gen check-abi-history --base-ref REF
cuda-intrinsics-gen probe [--all | --intrinsic ID] [--llc FILE] [--skip-terminal]
cuda-intrinsics-gen probe --candidate --intrinsic ID --llc FILE --gpu-target TARGET --ptx-feature FEATURE (--ptxas FILE | --skip-terminal)

Three CI gates that a catalog change has to satisfy (unit-tests.yml), none of them discoverable from the docs:

Two non-obvious environment facts sit with those: the ABI-history job needs fetch-depth: 0, and the generator shells out to rustfmt when it writes sources (which is why the pin carries that component — #727).

And the concepts a reader needs before touching the catalog: what catalog.json's schema / catalog_version / intrinsic_abi / generator_version fields mean, why the ABI ledger is append-only (cf. #604, where positional ID assignment conflicted with it), and what probe evidence is for.

Why it is worth writing

The failure mode is the one #797 hit: a contributor reads the only page named "Adding New Intrinsics", follows it, and produces something that either does not register or gets overwritten on the next generator run. #797 stops the page from misleading them, but the majority path is still tribal knowledge, and three CI gates fail on a PR without explaining what to run locally first.

Suggested shape, entirely your call

A "Catalog-generated intrinsics" section or sibling page covering: when an intrinsic belongs in the catalog versus a hand-written op; the add-a-catalog-entry → generate → check loop; the three CI gates and their local invocations; and the ABI-ledger constraint. Cross-linked from the Stage 2 note #797 added, so the reader who hits "this one is generated" has somewhere to go.

Happy to write it if you want it from me — but I would rather you set the intended contributor path than infer one from the code, which is why this is an issue and not a PR. If some of it is deliberately internal and not for the book, saying so here is a useful answer too.