Add AI-maintained knowledge base documentation

[soareschen]

AI Overview

This PR introduces a CGP knowledge base: a structured, agent-maintained body of documentation that records the full semantics of Context-Generic Programming so that an AI coding agent can read the conclusion instead of re-deriving it from proc-macro source every time. The branch adds 21 commits and changes 131 files, but the shape is simple — it is almost entirely additive (+17,646 lines, −1), it touches one line of shipping Rust, and everything else is new Markdown under docs/ plus three CLAUDE.md maintenance files. A reader skimming this document can stop here with an accurate picture: a large new documentation system landed, and the library code is untouched apart from exposing one already-implemented macro.

The single code change

The only functional Rust change adds Path to the macro re-exports in crates/main/cgp-core/src/prelude.rs. This makes the Path! type-level construction macro reachable from cgp::prelude alongside its siblings Symbol!, Product!, and Sum!. The macro itself already existed; this line closes the gap between an implemented construct and the public export surface, which matters because the new reference documentation describes Path! as a first-class construct and the prelude should agree. No runtime behavior, trait, or expansion changes — this is export plumbing in service of the documentation.

What the knowledge base is

The knowledge base is written by and for AI agents, and its premise is that proc-macro source is a poor place to learn semantics from. An agent reading the macro implementation sees token-stream manipulation, not the meaning those transforms produce — the fact that #[cgp_component] generates a consumer trait, a provider trait, and two connecting blanket impls has to be reconstructed by mentally running the macro on every visit. The new docs/ tree captures that reconstruction once, in prose, and commits to keeping it in sync with the code so the next agent reads the conclusion. It also serves as a contract: when a macro's expansion changes, the matching document is where the intended new behavior is stated in plain language, checkable against both the code and the expansion snapshots.

Overall structure

The documentation is organized into four complementary views of the same truth, each with a distinct job. The structure is deliberate — a reader looking for "the idea", "the exact construct", "a worked use case", or "the distilled skill" each has one obvious place to go.

The reference (docs/reference/, 84 files) holds one self-contained document per CGP construct, each explaining a single construct completely: its purpose, accepted syntax, exact desugaring, worked examples, and related constructs. The documents are grouped by kind of construct into subdirectories — macros/ (21) for the procedural macros a programmer invokes, derives/ (8) for the #[derive(...)] family, attributes/ (7) for the modifier attributes that refine what a host macro generates, components/ (9) for the built-in consumer/provider trait pairs CGP ships, providers/ (15) for the zero-sized provider structs that appear in wiring, traits/ (15) for the capability and mechanism traits that are not themselves components, and types/ (8) for the type-level building blocks. The dividing line between components/ and traits/ is whether a trait is defined with a CGP component macro and therefore has a generated provider trait that contexts wire.

The concepts (docs/concepts/, 18 files) hold the cross-cutting overviews that span several constructs — the consumer/provider duality, bypassing coherence, the modularity hierarchy, impl-side dependencies, abstract types, modular error handling, namespaces, handlers, extensible records and variants, dispatching, type-level DSLs, and recovering Send bounds. Where the reference explains the individual trees, the concepts explain the shape of the forest, carrying only enough mechanism to make an idea legible before linking down to the reference for the detail.

The examples (docs/examples/, 10 files) hold self-contained worked use cases, each developing one realistic scenario end to end — area calculation, a shell-scripting DSL, profile-picture lookup, a money-transfer API, an application builder, an expression interpreter, extensible shapes, a social-media CRUD backend, and a Serde-style modular serialization. These are the canonical source of code snippets the rest of the knowledge base reuses, so the same running scenarios recur everywhere a reader looks, and they double as raw material an agent can quote when writing tutorials or guides.

The skills (docs/skills/) hold the distilled, deployable synthesis of the other three. The cgp skill is a top-level SKILL.md carrying the mental model and a router, plus twelve topic sub-skills under references/ covering components, wiring, checking, functions and getters, abstract types, higher-order providers, error handling, handlers, extensible data, namespaces, type-level primitives, and the modularity hierarchy. The skill is the view that /cgp resolves to, and unlike the rest of the knowledge base it is copied out of the repository and run standalone, so it may not link to any file outside its own directory.

Maintenance machinery

Three CLAUDE.md files encode the rules that keep this system honest, and they are as much a part of the PR as the prose. The new docs/CLAUDE.md states the synchronization rule — documentation must stay in sync with the code, and keeping it in sync is part of the change rather than a follow-up — along with authoring conventions: write in dual-reader prose, verify against the source rather than memory, document the present rather than the history, and reuse the example scenarios for snippets. The new root CLAUDE.md orients an agent to the repository as the CGP implementation itself, mandating the /cgp skill before touching CGP code and laying out the layered micro-crate architecture, the build/test/lint commands, and repo conventions. The new crates/macros/cgp-macro-core/CLAUDE.md does the same for the proc-macro core, where the real parsing and codegen live.

Impacts

The impacts follow directly from what landed, and they are almost all upside with one standing obligation. They are listed here from most to least consequential.

Agents gain a durable, deep reference for CGP semantics. An agent working on CGP can now read the meaning of a construct — its expansion, defaults, and relationships — without re-deriving it from macro source, which is the central goal of the PR and the largest practical effect.

A four-way consistency contract now exists and must be maintained. The macro implementation, the expansion snapshots in cgp-macro-tests, the reference documents, and the cgp skill are now four views of one truth, and any disagreement among them is defined as a defect. This is a benefit — a reviewer can compare prose against code — but it imposes a real ongoing cost: every future change to a construct's syntax, expansion, defaults, or error behavior must update the matching reference document, propagate to the skill, and be registered in the relevant index, all within the same change. Stale documentation here is treated as actively harmful, so this is a hard requirement on subsequent PRs rather than optional housekeeping.

Path! becomes usable from the prelude. Downstream code can now reach the Path! macro through cgp::prelude without a deeper import path, matching how the documentation presents it. This is a small additive surface change with no risk to existing code.

The /cgp skill is now backed by a version-controlled source of truth. The skill is positioned as the distilled working subset of the knowledge base and the orientation an agent loads first; this PR establishes the exhaustive record it synthesizes from, and pins the skill's self-contained deployment constraints (no links outside its directory, online knowledge base for omitted detail).

Build, test, and runtime behavior are unchanged. Because the change is documentation plus one re-export line, there is no effect on compilation output, the public trait surface, macro expansions, or runtime behavior. Review effort concentrates entirely on prose accuracy against the implementation, not on code correctness — the risk profile of merging is low, and the durable cost is the synchronization discipline the maintenance files now require.