Adopt cargo-cgp as CGP's first-class error toolchain

[soareschen]

AI Overview

This PR makes CGP treat cargo-cgp as its first-class, recommended tool for reading compiler errors, and moves the post-codegen compile-fail tests out of this repository to where that tool lives. It changes documentation, tests, and the project's cross-repository conventions only — no library crate, public API, or macro behavior is touched.

Why this change

The obstacle CGP's users cite most is not conceptual but practical: because a CGP macro expands to ordinary Rust, a small wiring mistake is caught by the compiler type-checking the generated code, so it surfaces as a wall of errors naming types the programmer never wrote, with the real cause buried or hidden. cargo-cgp is the tool built to fix exactly that — it re-runs the check under the next-generation trait solver and rewrites the errors it recognizes into a compact, root-cause-first form with [CGP-Exxx] codes. Until now this repository documented that tool as a future aspiration and kept its own trybuild compile-fail suite to pin the raw diagnostics; this PR catches the docs up to reality and consolidates the testing where it belongs.

High-level concepts

The change rests on four ideas, each worked out across the docs and tests below. cargo-cgp is now the recommended way to build, check, and debug CGP code, so the skill, the debugging guide, the README, and the communication strategy all lead with it rather than with by-hand error tracing. The post-codegen compile-fail cases have one home, and it is cargo-cgp, because a cargo-cgp UI fixture snapshots both the raw compiler output and the tool's reshaped output side by side, which is a strictly better artifact than the raw-only trybuild snapshot this repository used to keep. The error catalog is the shared reference between the two projects, documenting each error class from both sides — the raw diagnostic (as a fallback for when the tool is absent) and how cargo-cgp presents it — and linking the fixture that pins it. The two projects are one system in two repositories, so the PR codifies how they find each other, how they link to each other, and when a change in one obligates a change in the other.

Structural changes

The removals are the largest structural move. The cgp-compile-fail-tests crate and the two cross-crate helper crates cgp-test-crate-a and cgp-test-crate-b are deleted, dropping the workspace from four test crates to two (cgp-tests and cgp-macro-tests remain); their post-codegen and cross-crate coverage now lives as UI fixtures in cargo-cgp. The rust-toolchain.toml pin drops the rust-src component, which existed only so one compile-fail snapshot could render a standard-library source line deterministically.

The documentation gains two new files and restructures one section. A new tooling reference document, docs/reference/cargo-cgp.md, describes installing and using the tool for a reader who works only in this repository, and a new docs/errors/error_codes/cargo-cgp-codes.md catalogs the tool's [CGP-Exxx] codes as a pointer into cargo-cgp's own authoritative list. Every class document under docs/errors/ is restructured to carry a renamed The raw diagnostic section (kept as the fallback) plus a new How cargo-cgp presents it section, and its fixture links now point at the cargo-cgp UI fixtures as GitHub URLs.

The remaining edits update the knowledge base's guidance and voice. The /cgp skill gains a prominent, must-have tooling section; the debugging guide is reordered to lead with the tool and treat the hand techniques as a fallback; the communication-strategy documents reposition the errors obstacle as one being actively removed; and both AGENTS.md files, the docs index, the guides index, and the implementation docs are updated to redirect the old fixture-capture workflow and to state the new cross-project rules. The top-level README.md recommends installing cargo-cgp when getting started. All cross-project links from this repository to cargo-cgp are written as GitHub URLs.

Impacts

The impacts fall into five areas. Read the area lead-ins to find the ones that affect you, and the bullets for the specifics.

Testing and CI shift the most, because a whole test target is gone:

• cargo nextest run --workspace no longer runs any post-codegen compile-fail tests — that coverage moved to cargo-cgp — so the workspace test count drops and the run is faster.
• Any CI step or command that names cgp-compile-fail-tests (for example cargo nextest run -p cgp-compile-fail-tests or TRYBUILD=overwrite cargo test -p cgp-compile-fail-tests) will now fail, because the crate no longer exists, and must be removed.
• The cross-crate coherence tests in cgp-test-crate-a/-b no longer run here; their compile-time coverage is preserved as a cargo-cgp ok/ fixture, but the small set of runtime assert_eq! checks crate-b carried are not executed by cargo-cgp's compile-and-snapshot harness.
• rust-src is no longer installed by the toolchain file, so a fresh build or CI fetches slightly less, and the standard-library-snippet determinism caveat that pin addressed is gone from this repository.
• Verifying a post-codegen expansion failure now requires the sibling cargo-cgp checkout and its pinned nightly, rather than a plain cargo test here — a heavier loop, and the trade for getting the reader-facing output pinned.

Contributor and agent workflow changes, so the documented process is different:

• Adding an expansion-failure case is now done in cargo-cgp, as a UI fixture filed by output quality (ok/acceptable/usability), not as an acceptable/problematic trybuild fixture here; rejection cases the macro catches still stay in cgp-macro-tests.
• An agent debugging a CGP error is now told to run cargo-cgp first, and to fall back to the hand techniques in the debugging guide and the error-extraction sub-skill only when the tool is unavailable or leaves an error unrewritten.
• A macro change that alters a diagnostic now obligates a paired update — the cargo-cgp fixture and this repository's catalog class move together under the cross-project sync rule when both repositories are checked out.
• Cross-project references must be written as GitHub URLs, and an agent is expected to find the other project in the parent directory first and fall back to GitHub otherwise.

Documentation is broadly rewritten, so readers see a different story:

• The error catalog is now the canonical documentation for cargo-cgp's fixtures, and each class states both the raw diagnostic and the reshaped [CGP-Exxx] form, so it doubles as the reference behind the tool's output.
• The skill records both versions it was written against (CGP v0.8.0 and cargo-cgp v0.1.0-alpha) and tells the agent to reconcile a mismatch — recommend updating an older tool, or upgrading the skill when the library is newer.
• The communication strategy now frames readable errors as a de-risking selling point, with the honesty guardrail that cargo-cgp is an early pre-release that does not yet reshape every class.

Users of the CGP library are affected only in what they are advised to install, not in what they build:

• Getting-started guidance now recommends installing cargo-cgp alongside CGP for readable errors, while stating plainly that it is optional.
• Nothing about building CGP changes: the library still compiles on stable Rust (1.89+), cargo check/cargo build/cargo run/cargo test work unchanged, and cargo-cgp's pinned nightly is used only for its own check.

The known limitations are documented rather than left silent:

• The inheritance_cycle class has no automated coverage, because it compiles cleanly under cargo-cgp's next-generation solver — recorded as a next-solver divergence rather than dropped quietly.
• cargo-cgp does not yet reshape every class (orphan-rule errors, for instance, pass through as raw rustc output), which the catalog and the tool's own issue tracker state openly.

What this PR does not change

No library crate, its version, its public API, its prelude, or any macro's expansion is modified, so the change is safe to merge on those grounds alone: it is a documentation, test-suite, and cross-project-convention change. The published crates and their MSRV are untouched, cargo publish --workspace is unaffected (the removed crates were already publish = false), and a downstream user who never adopts cargo-cgp sees no difference in how CGP compiles.