Move the documentation into the cgp-knowledge-base repository

.claude/skills/cgp

@@ -1 +1 @@
-../../docs/skills/cgp
+../../../cgp-skills/cgp

README.md

@@ -143,6 +143,8 @@ Learn CGP at the project website, **[contextgeneric.dev](https://contextgeneric.
 > [!NOTE]
 > The crates' API docs on `docs.rs` are still sparse. The website is the place to start while the inline documentation is filled in.
 
+Contributors and coding agents have a second, deeper source: the [CGP knowledge base](https://github.com/contextgeneric/cgp-knowledge-base), which holds the exhaustive per-construct reference, the concept overviews, the writing guides, the compile-error catalog, the worked examples, and the internals of the macros in this repository. It is written for AI agents rather than for learners, so start at the website if you are learning CGP and reach for the knowledge base when you need the exact semantics of a construct or are changing this repository. Start from [AGENTS.md](AGENTS.md) for the conventions this repository follows, and [sibling-projects.md](sibling-projects.md) for the related repositories.
+
 ## Project status
 
 CGP works today on stable Rust and already offers a broad feature set: components and providers, abstract types, extensible records and variants, a handler and computation family, namespaces, and modular error handling. It is also young — the paradigm and its ecosystem are still evolving, and v0.8.0 is a pre-release — so adopting it is a real decision rather than a foregone one.

crates/macros/cgp-macro-core/AGENTS.md

@@ -80,7 +80,7 @@ into the existing stage rather than collapsing the pipeline.
 [src/macros/keyword.rs](src/macros/keyword.rs) and `types/keyword*.rs`).
 
 **6. Keep inline docs brief and current as you go.** When you review a file — whether to change it
-or to write its [implementation document](../../../docs/implementation/README.md) — improve the
+or to write its [implementation document](https://github.com/contextgeneric/cgp-knowledge-base/blob/main/cgp/implementation/README.md) — improve the
 inline docs in the same pass. Add a one-line `///` to any public struct, trait, or function that
 lacks one, saying what it is or does (for a pipeline stage, its role in the sequence); prefer naming
 the *why* or a corner case over restating the signature. Fix a doc that no longer matches the code,

crates/macros/cgp-macro-core/src/types/attributes/prefix.rs

@@ -32,7 +32,7 @@ impl PrefixAttribute {
         // Insert the components table as the leading generic. Position 0 sits
         // ahead of any lifetime, which the `parse_internal! { impl #type_generics
         // … }` re-parse below normalizes (`syn` re-emits lifetimes first). See
-        // docs/implementation/README.md, "Generic-parameter insertion and
+        // cgp-knowledge-base/cgp/implementation/README.md, "Generic-parameter insertion and
         // lifetime ordering".
         type_generics
             .params

crates/macros/cgp-macro-core/src/types/attributes/use_provider/attribute.rs

@@ -25,7 +25,7 @@ impl UseProviderAttribute {
             // Insert the context as the inner provider bound's leading type
             // argument. Position 0 sits ahead of any lifetime argument, which the
             // `parse_internal(#bound)` re-parse below normalizes (`syn` re-emits
-            // lifetimes first). See docs/implementation/README.md,
+            // lifetimes first). See cgp-knowledge-base/cgp/implementation/README.md,
             // "Generic-parameter insertion and lifetime ordering".
             bound
                 .type_args

crates/macros/cgp-macro-core/src/types/cgp_auto_getter/blanket.rs

@@ -23,7 +23,7 @@ pub fn derive_blanket_impl(
 
     // Insert the context as the leading impl generic. Position 0 is safe with a
     // lifetime present because `syn::Generics::to_tokens` emits lifetimes first.
-    // See docs/implementation/README.md, "Generic-parameter insertion and
+    // See cgp-knowledge-base/cgp/implementation/README.md, "Generic-parameter insertion and
     // lifetime ordering".
     generics
         .params

crates/macros/cgp-macro-core/src/types/cgp_component/preprocessed/to_consumer_impl.rs

@@ -22,7 +22,7 @@ impl PreprocessedCgpComponent {
             // Insert the context as the leading type argument. Position 0 sits
             // ahead of any lifetime argument, which the `parse_internal` re-parse
             // on the next line normalizes (`syn` re-emits lifetimes first). See
-            // docs/implementation/README.md, "Generic-parameter insertion and
+            // cgp-knowledge-base/cgp/implementation/README.md, "Generic-parameter insertion and
             // lifetime ordering".
             provider_type_generics
                 .generics
@@ -37,7 +37,7 @@ impl PreprocessedCgpComponent {
 
             // Insert the context as the leading impl generic. Position 0 is safe
             // with a lifetime present because `syn::Generics::to_tokens` emits
-            // lifetimes first. See docs/implementation/README.md,
+            // lifetimes first. See cgp-knowledge-base/cgp/implementation/README.md,
             // "Generic-parameter insertion and lifetime ordering".
             generics
                 .params

crates/macros/cgp-macro-core/src/types/cgp_component/preprocessed/to_provider_blanket_impl.rs

@@ -37,7 +37,7 @@ impl PreprocessedCgpComponent {
 
             // Insert the provider as the leading impl generic. Position 0 is safe
             // with a lifetime present because `syn::Generics::to_tokens` emits
-            // lifetimes first. See docs/implementation/README.md,
+            // lifetimes first. See cgp-knowledge-base/cgp/implementation/README.md,
             // "Generic-parameter insertion and lifetime ordering".
             impl_generics
                 .params

crates/macros/cgp-macro-core/src/types/cgp_component/preprocessed/to_provider_trait.rs

@@ -28,7 +28,7 @@ impl PreprocessedCgpComponent {
         // Insert the context as the provider trait's leading generic parameter.
         // Position 0 is safe even when the trait already has a lifetime, because
         // `syn::Generics::to_tokens` emits lifetimes ahead of type/const
-        // parameters. See docs/implementation/README.md,
+        // parameters. See cgp-knowledge-base/cgp/implementation/README.md,
         // "Generic-parameter insertion and lifetime ordering".
         provider_trait
             .generics

crates/macros/cgp-macro-core/src/types/cgp_data/derive_builder/finalize_build_impl.rs

@@ -51,6 +51,6 @@ pub fn derive_finalize_build_impl(
     };
 
     // Key the error span on the struct name the user wrote, not the whole
-    // derive. See docs/implementation/README.md#spans.
+    // derive. See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_builder/has_builder_impl.rs

@@ -46,6 +46,6 @@ pub fn derive_has_builder_impl(
     };
 
     // Key the error span on the struct name the user wrote, not the whole
-    // derive. See docs/implementation/README.md#spans.
+    // derive. See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_builder/has_field_impls.rs

@@ -58,7 +58,8 @@ pub fn derive_has_field_impls(
         };
 
         // Point an error on this per-field impl at the field the user wrote
-        // rather than at the whole derive. See docs/implementation/README.md#spans.
+        // rather than at the whole derive. See
+        // cgp-knowledge-base/cgp/implementation/README.md#spans.
         let field_span = current_field
             .ident
             .as_ref()

crates/macros/cgp-macro-core/src/types/cgp_data/derive_builder/into_builder_impl.rs

@@ -49,6 +49,6 @@ pub fn derive_into_builder_impl(
     };
 
     // Key the error span on the struct name the user wrote, not the whole
-    // derive. See docs/implementation/README.md#spans.
+    // derive. See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_builder/partial_data.rs

@@ -34,6 +34,6 @@ pub fn derive_partial_data_impl_from_struct(
     };
 
     // Key the error span on the struct name the user wrote, not the whole
-    // derive. See docs/implementation/README.md#spans.
+    // derive. See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_builder/update_field_impls.rs

@@ -102,7 +102,8 @@ pub fn derive_update_field_impls(
         };
 
         // Point an error on this per-field impl at the field the user wrote
-        // rather than at the whole derive. See docs/implementation/README.md#spans.
+        // rather than at the whole derive. See
+        // cgp-knowledge-base/cgp/implementation/README.md#spans.
         let field_span = current_field
             .ident
             .as_ref()

crates/macros/cgp-macro-core/src/types/cgp_data/derive_extractor/extract_field_impls.rs

@@ -118,7 +118,8 @@ pub fn derive_extract_field_impls(
         };
 
         // Point an error on this per-variant impl at the variant the user wrote
-        // rather than at the whole derive. See docs/implementation/README.md#spans.
+        // rather than at the whole derive. See
+        // cgp-knowledge-base/cgp/implementation/README.md#spans.
         item_impls.push(override_item_span(
             current_variant.ident.span(),
             &item_impl,

crates/macros/cgp-macro-core/src/types/cgp_data/derive_extractor/finalize_extract_impl.rs

@@ -63,6 +63,6 @@ pub fn derive_finalize_extract_impl(
     };
 
     // Key the error span on the enum name the user wrote, not the whole derive.
-    // See docs/implementation/README.md#spans.
+    // See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_enum.ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_extractor/has_extractor_impl.rs

@@ -64,7 +64,7 @@ pub fn derive_has_extractor_impl(
     };
 
     // Key the error span on the enum name the user wrote, not the whole derive.
-    // See docs/implementation/README.md#spans.
+    // See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }
 
@@ -141,7 +141,7 @@ pub fn derive_has_extractor_ref_impl(
     };
 
     // Key the error span on the enum name the user wrote, not the whole derive.
-    // See docs/implementation/README.md#spans.
+    // See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }
 
@@ -215,6 +215,6 @@ pub fn derive_has_extractor_mut_impl(
     };
 
     // Key the error span on the enum name the user wrote, not the whole derive.
-    // See docs/implementation/README.md#spans.
+    // See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_extractor/partial_data.rs

@@ -58,6 +58,6 @@ pub fn derive_partial_data_impl_from_enum(
     };
 
     // Key the error span on the enum name the user wrote, not the whole derive.
-    // See docs/implementation/README.md#spans.
+    // See cgp-knowledge-base/cgp/implementation/README.md#spans.
     override_item_span(context_ident.span(), &item_impl)
 }

crates/macros/cgp-macro-core/src/types/cgp_data/derive_from_variant.rs

@@ -36,7 +36,7 @@ pub fn derive_from_variant_from_enum(item_enum: &ItemEnum) -> syn::Result<Vec<It
         // Aim a compiler error on this impl at the variant the user wrote rather
         // than at the whole `#[derive(...)]`, which is where the impl's
         // `call_site`-spanned boundary would otherwise put the caret. See
-        // docs/implementation/README.md#spans.
+        // cgp-knowledge-base/cgp/implementation/README.md#spans.
         item_impls.push(override_item_span(variant_ident.span(), &item_impl)?);
     }
 

crates/macros/cgp-macro-core/src/types/cgp_data/derive_has_field.rs

@@ -23,7 +23,7 @@ pub fn derive_has_field_impls_from_struct(item_struct: &ItemStruct) -> syn::Resu
                 // same tag, say — at the field the user wrote rather than at the
                 // whole `#[derive(HasField)]`, which is where the impl's
                 // `call_site`-spanned `impl`/`{ … }` boundary would otherwise put
-                // the caret. See docs/implementation/README.md#spans.
+                // the caret. See cgp-knowledge-base/cgp/implementation/README.md#spans.
                 let field_span = field_ident.span();
 
                 let field_symbol = Symbol::from_ident(field_ident.clone());

crates/macros/cgp-macro-core/src/types/cgp_data/derive_has_fields/derive_enum.rs

@@ -48,7 +48,7 @@ pub fn derive_has_fields_impls_from_enum(item_enum: &ItemEnum) -> syn::Result<Ve
 
     // These impls are all keyed on the whole enum, so aim an error on any of
     // their headers at the enum name the user wrote rather than at the whole
-    // `#[derive(...)]`. See docs/implementation/README.md#spans.
+    // `#[derive(...)]`. See cgp-knowledge-base/cgp/implementation/README.md#spans.
     [
         has_fields_impl,
         has_fields_ref_impl,

crates/macros/cgp-macro-core/src/types/cgp_data/derive_has_fields/derive_struct.rs

@@ -49,7 +49,7 @@ pub fn derive_has_fields_impls_from_struct(item_struct: &ItemStruct) -> syn::Res
 
     // These impls are all keyed on the whole struct, so aim an error on any of
     // their headers at the struct name the user wrote rather than at the whole
-    // `#[derive(...)]`. See docs/implementation/README.md#spans.
+    // `#[derive(...)]`. See cgp-knowledge-base/cgp/implementation/README.md#spans.
     [
         has_fields_impl,
         has_fields_ref_impl,

crates/macros/cgp-macro-core/src/types/cgp_fn/preprocessed.rs

@@ -94,7 +94,7 @@ impl PreprocessedItemCgpFn {
         item_impl.generics = generics.clone();
         // Insert the context as the leading impl generic. Position 0 is safe with
         // a lifetime present because `syn::Generics::to_tokens` emits lifetimes
-        // first. See docs/implementation/README.md, "Generic-parameter insertion
+        // first. See cgp-knowledge-base/cgp/implementation/README.md, "Generic-parameter insertion
         // and lifetime ordering".
         item_impl
             .generics

crates/macros/cgp-macro-core/src/types/cgp_impl/item.rs

@@ -54,7 +54,7 @@ impl ItemCgpImpl {
                 // Insert the context as the leading impl generic. Position 0 is
                 // safe even when the impl already has a lifetime, because
                 // `syn::Generics::to_tokens` emits lifetimes ahead of type/const
-                // parameters. See docs/implementation/README.md,
+                // parameters. See cgp-knowledge-base/cgp/implementation/README.md,
                 // "Generic-parameter insertion and lifetime ordering".
                 item_impl
                     .generics

crates/macros/cgp-macro-core/src/types/cgp_impl/lowered.rs

@@ -92,7 +92,7 @@ impl LoweredCgpImpl {
         // Position 0 places it ahead of any lifetime argument, which is invalid
         // Rust ordering on its own — it is only safe because the path is
         // re-parsed through `syn` below (`parse_internal(… .to_token_stream())`),
-        // and `syn` re-emits lifetimes first. See docs/implementation/README.md,
+        // and `syn` re-emits lifetimes first. See cgp-knowledge-base/cgp/implementation/README.md,
         // "Generic-parameter insertion and lifetime ordering".
         provider_trait_path
             .type_args

crates/macros/cgp-macro-core/src/types/cgp_type/item.rs

@@ -42,7 +42,7 @@ impl ItemCgpType {
         let mut generics = provider_trait.generics.clone();
         // Insert the abstract type as the leading generic. Position 0 is safe
         // with a lifetime present because `syn::Generics::to_tokens` emits
-        // lifetimes first. See docs/implementation/README.md, "Generic-parameter
+        // lifetimes first. See cgp-knowledge-base/cgp/implementation/README.md, "Generic-parameter
         // insertion and lifetime ordering".
         generics.params.insert(0, parse_internal!(#type_name));
 

crates/tests/AGENTS.md

@@ -5,6 +5,11 @@ moving, or refactoring any test here. Invoke the `/cgp` skill first — every te
 in this tree is CGP code, and the skill is the authoritative source for CGP
 semantics and vocabulary.
 
+This repository's documentation lives in the sibling
+[`cgp-knowledge-base`](https://github.com/contextgeneric/cgp-knowledge-base) repository, under its
+`cgp/` directory, so a doc pointer below names a path there (`cgp-knowledge-base/cgp/…`) rather than a
+local one. See [../../sibling-projects.md](../../sibling-projects.md) for finding that checkout.
+
 The test suite has two jobs, split across crates:
 
 - **`cgp-tests`** is the main suite: realistic example code that must **compile and
@@ -36,7 +41,7 @@ so on.
 
 The right granularity is driven by the feature, its implementation complexity, and
 how many cases are needed to cover it exhaustively — **not** by mirroring the
-concept documents under `docs/concepts/`. The names may coincide, but the split is
+concept documents under `cgp-knowledge-base/cgp/concepts/`. The names may coincide, but the split is
 chosen for coverage. **When a category accumulates too many test cases to stay
 coherent, split it into finer categories** rather than letting it sprawl; prefer
 splitting early.
@@ -71,10 +76,10 @@ that test exercises.
 
 Open every test file with a brief comment stating **what behavior it exercises**,
 and annotate individual tricky cases inline. Link to the owning **implementation
-document** — the one under `docs/implementation/` whose Tests and Snapshots
-sections index this test (for example `// see docs/implementation/entrypoints/cgp_impl.md`);
+document** — the one under `cgp-knowledge-base/cgp/implementation/` whose Tests and Snapshots
+sections index this test (for example `// see cgp-knowledge-base/cgp/implementation/entrypoints/cgp_impl.md`);
 that document is where test pointers live, since a reference document never links
-to a test (per `docs/AGENTS.md`). You may additionally link to a reference
+to a test (per the knowledge base's `cgp/AGENTS.md`). You may additionally link to a reference
 document when a reader needs the user-facing semantics. Tests link **to** the
 documentation; the reference documents never link back to a test.
 
@@ -150,9 +155,9 @@ compiles even though the code would not), with a comment explaining **why** the
 is wrong and **what the correct output should be**.
 
 **Where a post-codegen class is documented.** Such a class is cataloged in the
-[error catalog](../../docs/errors/README.md) under `docs/errors/`, the canonical
+[error catalog](https://github.com/contextgeneric/cgp-knowledge-base/blob/main/cgp/errors/README.md) under `cgp-knowledge-base/cgp/errors/`, the canonical
 reader-facing documentation for these errors (see
-[docs/errors/AGENTS.md](../../docs/errors/AGENTS.md)): the class doc describes the raw
+[cgp-knowledge-base/cgp/errors/AGENTS.md](https://github.com/contextgeneric/cgp-knowledge-base/blob/main/cgp/errors/AGENTS.md)): the class doc describes the raw
 diagnostic *and* how cargo-cgp presents it, and links the backing `cargo-cgp` UI fixture
 as a GitHub URL. When a construct change alters such a diagnostic, the cross-project
 [sync rule](../../AGENTS.md) applies — update the `cargo-cgp` fixture and the class doc
@@ -165,10 +170,9 @@ and its `cargo-cgp` fixture rather than to a local fixture.
 ## Keep the docs in sync
 
 This suite is one of the views of CGP's truth, alongside the macro implementation
-in `cgp-macro-core`, the reference documents in `docs/reference`, the
-implementation documents in `docs/implementation`, and the `/cgp` skill (see
-`docs/AGENTS.md`). The implementation documents are the ones tightly coupled to
-this suite: each macro's implementation document has a `## Tests` section linking
+in `cgp-macro-core`, the knowledge base's `cgp/reference` and `cgp/implementation`
+documents, and the `/cgp` skill (see the knowledge base's `cgp/AGENTS.md`). The
+implementation documents are the ones tightly coupled to this suite: each macro's implementation document has a `## Tests` section linking
 every behavioral test and failure case that exercises it, and every entrypoint
 document a `## Snapshots` section indexing the expansion snapshots and calling out
 which variants are still missing. When a test reveals or pins a behavior worth

crates/tests/README.md

@@ -29,7 +29,7 @@ migrated to `cargo-cgp`'s UI test suite, which snapshots the readable, root-caus
 errors `cargo-cgp` renders for each class (its `.rust.stderr` still records the raw
 compiler output as the "before"). `cargo-cgp` is CGP's first-class error toolchain, so
 those diagnostics are pinned where the tool that improves them lives; the
-[error catalog](../../docs/errors/README.md) links each class to the fixture that
+[error catalog](https://github.com/contextgeneric/cgp-knowledge-base/blob/main/cgp/errors/README.md) links each class to the fixture that
 backs it. See
 [cargo-cgp's UI tests](https://github.com/contextgeneric/cargo-cgp/blob/main/tests/README.md).
 

crates/tests/cgp-macro-tests/tests/invalid_expansion_tests.rs

@@ -13,7 +13,7 @@
 //! 2. add a code comment explaining **why** the output is wrong and **what the
 //!    correct output should be**;
 //! 3. record the limitation in the owning reference document's `## Known issues`
-//!    section (per docs/AGENTS.md), and link from the test to that document.
+//!    section (per cgp-knowledge-base/cgp/AGENTS.md), and link from the test to that document.
 //!
 //! No cases are enumerated yet; see crates/tests/AGENTS.md ("Migration status").
 #![allow(dead_code)]