AI-generate implementation documentation

[soareschen]

AI Overview

This PR adds a new docs/implementation/ documentation tree that describes how
the CGP macros are built, and rewires the existing reference docs, tests, and
inline source comments to point at it. It is a documentation-and-comments change
only — no macro behavior, expansion, or public API changes. The work spans three
commits on ai-implementation-docs (scaffold, fan-out, then a formatting pass),
touching roughly 160 files: 55 new implementation documents, 84 reference
documents, 21 Rust source/test files, and four CLAUDE.md governance files.

The core idea: two views of the same macros

The change splits CGP's macro documentation into two complementary views that
were previously blended. The reference documents (docs/reference/) already
explained what each construct does for a user — its syntax and the code it
expands to. The new implementation documents (docs/implementation/) explain
how each macro produces that behavior — its parse-to-emit pipeline, the AST
types behind each stage, the functions that synthesize each generated item, its
corner cases, and its known bugs. An agent asked to use CGP reads the reference;
an agent asked to review, debug, or extend the macro source reads the
implementation doc first.

A second, sharper rule accompanies the split: all test and snapshot pointers now
live exclusively in the implementation tree. Reference documents point only at
library source and never at a test file. Every pointer into crates/tests —
behavioral tests, parser-rejection failure cases, and macro-expansion snapshots —
moves into the implementation document's new Tests and Snapshots sections. The
Snapshots section is deliberately built to also record which expansion variants
have no snapshot yet, so coverage gaps become visible rather than silently
absent.

This makes the implementation tree the code-level counterpart to the reference
tree, completing a set of mutually-synchronized views of "CGP's truth": the macro
source, the expansion snapshots, the reference docs, the implementation docs, and
the /cgp skill.

Structural changes

The bulk of the PR is the new docs/implementation/ directory — 55 files and
about 3,160 lines. It carries its own README.md (the catalog of every
implementation document) and CLAUDE.md (the authoring rules, per-kind document
templates, and the source-synchronization rule for the tree), and is organized
into four subdirectories by the kind of source construct each document
describes.

The entrypoints/ subdirectory holds one document per user-facing macro — the
proc-macros a programmer invokes, such as #[cgp_component], #[cgp_impl],
delegate_components!, the Symbol!/Product!/Sum!/Path! type-level macros,
the data derives, and the handler macros — plus the snapshot_*! test-util
family. The asts/ subdirectory holds one document per evaluation stack of
Parse/ToTokens types in cgp-macro-core, grouping the types of one pipeline
into a single document. The functions/ subdirectory holds the standalone helper
functions, split into parse/ and derive/. The macros/ subdirectory holds the
internal macro_rules! (parse_internal!, define_keyword!, the
export_construct(s)! family) the codegen is written in.

The #[cgp_component] slice is built out in full as the template for the rest.
Its entrypoint document walks the preprocess → eval → to_items pipeline, the five
core generated items and their fixed order, the corner cases (supertrait lowering,
default-method preservation, generic-parameter and lifetime handling, the reserved
__Context__/__Provider__ identifiers), the const-generic panic recorded under
Known issues, and the complete index of its snapshots and tests.

The 84 reference documents change in one consistent, mechanical way. Each Source
section is rewritten from a flowing paragraph into a bullet list — one pointer
per bullet — its test-file pointers are removed, and a new bullet links to the
construct's implementation counterpart. The reference README.md and top-level
docs/CLAUDE.md gain the rules that formalize this: reference docs point only at
library source, a new "implementation directory" section is added, and the
document-structure and review-workflow rules are updated to forbid test links in
the reference.

The Rust changes are confined to comments. Across 15 files in cgp-macro-core and
cgp-macro-lib, brief /// doc comments are added to public structs, traits, and
functions that lacked them (for example, explaining why generic_params_to_path
keeps only type parameters, or that parse_is_provider_params panics on a const
generic) — the "improve inline docs while documenting a construct" convention now
recorded in cgp-macro-core/CLAUDE.md. Four test files have their header comments
repointed from the reference doc to the implementation doc, and crates/tests/CLAUDE.md
is updated so tests link to the implementation doc as the canonical index of
coverage.

Impacts

The impacts below follow from the split and the "tests point only into
docs/implementation" rule, and are worth keeping in mind for future changes.

A new home for macro-internals knowledge. Reviewing, debugging, or extending a
CGP macro now has a designated first-stop document that records the current state
of the code — pipeline, AST types, synthesizing functions, corner cases, and known
bugs — so the next agent does not reconstruct it from source.

Test and snapshot coverage is now indexed in one place. Because every test and
snapshot pointer lives in the implementation tree, the Tests and Snapshots
sections are the single index of what each construct guards, and the Snapshots
section explicitly names missing variants, surfacing coverage gaps that were
previously invisible.

The synchronization burden grows by one view. Changing a macro now requires
updating both the reference (user-facing contract and expansion) and the
implementation document (pipeline, generated items, mechanics) in the same change,
and the two must not drift or duplicate. Adding, moving, or renaming a test now
updates the implementation document's Tests/Snapshots section — never a
reference document.

Reference Source sections have a new, stricter shape. They are bullet lists,
they never link to a test, and each must carry a link to its implementation
counterpart. Any future reference document must follow this shape, and any old
reference-to-test link is now a defect.

Inline source docs are now expected to be maintained alongside the docs. Per
the updated cgp-macro-core/CLAUDE.md, reviewing a file to write its
implementation document also means adding or correcting its brief /// comments in
the same pass, with deep mechanics left to the implementation document rather than
duplicated inline.

No runtime or compile-time behavior changes. All Rust edits are comments; the
macros emit exactly what they did before, so downstream crates and existing
snapshots are unaffected.

The build-out is intentionally incomplete. The #[cgp_component] vertical
slice is the reviewed template; the implementation/README.md catalog tracks the
documented-versus-pending state for the roughly 30 remaining entrypoints and their
AST and function documents, and the fan-out continues from there.