AI Updates #8: document cargo cgp expand, and restate error coalescing as cause-keyed

[soareschen]

AI overview

This PR is documentation only: seven Markdown files under docs/, +151/−16 lines, and no change to any crate, macro, test, or snapshot. Both commits bring the knowledge base back in line with cargo-cgp, which has gained a second command and changed how it groups the diagnostics it rewrites. Nothing here alters CGP's behavior, so nothing here can break a build; what it changes is what a reader — and an agent — is told to do when a CGP error stops making sense.

The high-level concepts

The first and larger change makes cargo cgp expand a documented part of the CGP workflow. Until now the toolchain was presented as one command, check, whose job is to reshape a CGP compile error into a root-cause-first form. expand answers a different question that check structurally cannot: what did that macro actually generate? Every CGP wiring failure is "the emitted impls do not resolve," and the impls are generated, so reading them is often faster than reasoning about the diagnostic that describes them. The PR threads that idea through the knowledge base wherever reading generated code or debugging a wiring failure already came up.

What makes the command worth documenting rather than deferring to plain cargo expand is resugaring. cargo cgp expand prints the post-expansion crate with CGP's type-level constructs folded back into their source vocabulary — a field tag reads Symbol!("width") instead of the raw Symbol<5, Chars<'w', …>> spine, a pipeline reads Product![StepOne, StepTwo], a namespace key reads Path!(@app.GreeterComponent). That turns the expansion into something legible in the same terms as the source, which is precisely what the compiler's own rendering of those types is not.

The second concept the PR adds is the --item selection model, because a whole crate's expansion is unusable in practice. The docs now spell out that --item behaves by three rules according to what the path names: a module yields its contents, a type yields its declaration and every impl written for it, and a trait yields its definition and every impl of it. The trait rule is called out as the one to reach for on CGP code, since a component's generated items are almost all impls and an impl has no name to select by. Naming a component's provider trait therefore gathers the provider trait, the delegation blanket impl, the UseContext and RedirectLookup impls, and each wired provider's own impl — the whole set of things that can answer "which provider serves this component, and under what bounds?" — while the consumer trait is the smaller companion selection.

The second commit restates a claim about how cargo-cgp coalesces a verbose cascade, because the tool's grouping rule changed underneath it. The error catalog previously said the tool groups failures by a consumer-independent cause signature, which demanded that two failures carry identical cause sets. It now keys on each root cause separately and groups the failures that share one, transitively. The distinction matters for a shape the old rule missed: because CGP wiring is lazy, one omission surfaces at several depths, and each depth sees a different subset of the causes — a check_components! entry stops at the first unmet leaf on its own branch, while a use-site call walks every wired component and reaches them all — so those subsets overlap without ever being equal, and an exact-match key grouped none of them, leaving a single mistake reported as several blocks.

The structural changes

The reference gains a new top-level section and the skill gains its agent-facing twin. docs/reference/cargo-cgp.md grows an "Expanding the generated code" section — roughly sixty lines covering when to reach for the command, what resugaring buys over plain cargo expand, the one-target requirement and cargo's exact refusal without --lib/--bin NAME, the three --item rules, and the two limits (it is not a check, and its output is for reading rather than compiling). Its worked sample expands the area-calculation example's own rectangle_area, so one snippet shows both what #[cgp_fn] emits and what #[implicit] arguments become — a HasField bound per argument plus a cloning get_field call. The document's framing lines and its opening paragraph were widened from "the error toolchain" to cover both commands, and docs/reference/README.md extends the same document's catalog entry.

The skill's tooling section gains the parallel treatment, and it ships in the same edit. docs/skills/cgp/SKILL.md gets a "Reading what a macro generated: cargo cgp expand" subsection written for an agent rather than a reader: the four situations where the answer lives in the generated code rather than the message, the commands, the --item rules in compressed form, and an instruction to redirect long output to a file rather than flood its own context. Because .claude/skills/cgp is a symlink to docs/skills/cgp, the deployed skill and the documented skill are one file — there is no second copy left to drift.

Three smaller edits re-point existing "read the expansion" advice at the new command. The debugging guide now leads its "inspect what the macro actually emitted" step with cargo cgp expand and demotes plain cargo expand and the snapshot_*! helpers to fallbacks; the error-extraction sub-skill does the same for its expansion step; and the type-level-primitives decoder notes that a raw spine appearing in a cargo cgp expand dump means the resugaring declined, whereas an error message or a plain cargo expand shows the spines as they are. The coalescing restatement touches docs/errors/checks/verbose-cascade.md in two places: the "How cargo-cgp presents it" mechanism paragraph and the "Notes for tooling" summary.

Impacts

The impacts are a set of independent consequences rather than one argument, so they are listed. Each is something a reviewer or a downstream reader should expect to be different after this merges.

• A new documented capability for users. Anyone debugging CGP now has a documented second tool, with the availability caveat stated in both the reference and the skill: expand postdates the v0.1.0-alpha release, so a cargo install cargo-cgp from crates.io does not carry it yet, and the two ways to get it in the meantime (an untagged Nix reference tracking main, or a source checkout) are named.
• A changed default for agent behavior. The skill previously sent an agent to plain cargo expand or the snapshot helpers; it now sends it to cargo cgp expand first, with an explicit context-hygiene instruction to narrow with --item or redirect to a file. Agents following the skill will therefore issue different commands when diagnosing wiring failures.
• The toolchain's scope statement is now accurate in both views. The line that read "cargo-cgp adds only check" now reads "check and expand" in the skill, and the reference's corresponding paragraph was rewritten the same way. The load-bearing part is unchanged and still stated in both: there is no cargo cgp build/run/test, CGP compiles on any stable Rust ≥ 1.89, and you build, run, and test with ordinary cargo.
• One documented claim was corrected against the real tool. The commit records that every command and snippet was run rather than recalled, which surfaced a wrong assumption: --item <provider trait> does not include the consumer blanket impl — --item <consumer trait> selects that. The reference and the skill both state the split correctly.
• The error catalog's coalescing description now matches the implementation. I verified this against the sibling checkout: cargo-cgp's group_by_shared_cause groups failures sharing at least one root cause, transitively, keyed structurally on context plus leaf rather than on rendered wording. The two edited paragraphs say exactly that, including that overlapping-but-unequal cause sets group.
• No cross-project sync debt is left open. ../cargo-cgp already carries both the expand command and the shared-cause grouping, and its own docs/reference/usage.md already documents expand, so this PR is the cgp side catching up rather than a change that obliges an update there. The one cross-repo link added — the source-install anchor in the installation doc — is written as a GitHub URL per the repository's convention.
• Documentation coverage is complete for this change. A sweep of docs/, AGENTS.md, README.md, and CHANGELOG.md for cargo expand and cargo cgp expand finds no mention outside the five files this PR edits, so no other document is left recommending the un-resugared fallback as the primary route.
• No code, test, or release impact. No crate under crates/ is touched, so no macro behavior, expansion snapshot, trybuild fixture, or wiring check is affected, and the cargo nextest suite is unaffected by construction. Nothing here changes the published surface or requires a version edit — the tree remains the 0.8.0-alpha pre-release documented as v0.8.0.
• One risk worth naming. The documented --item rules, the one-target refusal message, and the two limits describe an unreleased expand, tracked from main in the sibling repository. If that behavior shifts before the next cargo-cgp release, these five documents are what needs re-verifying, and the anchors added here (#expanding-the-generated-code, referenced from three other documents) are what would need to survive any restructure.