Add modern idioms documentation and other minor docs updates

[soareschen]

AI Overview

This PR establishes CGP's newer, higher-level idioms as the recommended way to write components, providers, and wiring — first by documenting the full migration from the explicit forms, then by applying those idioms to the library's own trait definitions and across the docs. The branch (minor-docs-update, two commits) is overwhelmingly documentation, with a small, behavior-preserving set of source changes that bring the shipped crates in line with the guidance. Nothing here changes runtime behavior or the public API; the changes are about how the code and the docs read.

What changed, at a high level

The centerpiece is a new concept document, docs/concepts/modern-idioms.md, that reads as a migration guide. It maps each older, explicit CGP form to the modern idiom that should now be preferred, organized by the shift each idiom makes: writing providers with #[cgp_impl] instead of the raw provider-trait shape, omitting the explicit for Context parameter, declaring dependencies with #[uses]/#[use_provider] rather than hand-written where clauses, reading fields with #[implicit] arguments rather than getter traits, importing abstract types with #[use_type] and writing them as bare aliases, adding capability supertraits with #[extend] instead of native : syntax, and dispatching per type with the open statement or a namespace instead of a legacy UseDelegate table. The guide is explicit that the old forms still work and remain what the macros desugar to, and it closes by naming the narrow cases where an explicit form is still the right choice.

The second theme is that the library now practices what the guide preaches. Several of CGP's own error- and computation-related trait definitions were rewritten to the modern idiom, converting the : HasErrorType supertrait plus Self::Error qualification into #[use_type(HasErrorType::Error)] with a bare Error in the signatures. This touches the error components (CanRaiseError, CanWrapError), the handler family (CanHandle, CanHandleRef, CanTryCompute, CanTryComputeRef), the task runners (CanRun, CanSendRun), and the runtime getter (HasRuntime, which now imports HasRuntimeType::Runtime). These are equivalent desugarings: #[use_type] adds the same supertrait the : form did and rewrites the bare type back to the qualified path, so the traits keep the identical supertrait bound, method signatures, and dispatch attributes they had before.

The third theme is consistency across the rest of the documentation. The existing concept pages, reference pages (macros, attributes, components, providers), worked examples, and the bundled docs/skills/cgp/ skill were all revised to demonstrate the modern idioms and to cross-reference the new guide. The concept index gains a link to the migration guide, and the reference pages for #[cgp_component] and #[use_type] gain new prose explaining when to prefer #[use_type] over a hand-written supertrait and — importantly — the one rule that bounds the rewrite: a construct's own local associated type (such as a handler's type Output) always stays qualified as Self::Output, because it is not an imported type.

Structural changes

The change set spans 37 files with roughly 522 insertions and 229 deletions, and its shape is lopsided toward documentation. One file is new (docs/concepts/modern-idioms.md, about 211 lines); everything else is an edit to an existing file. The edits fall into four groups: the documentation crate's concept and reference pages, the three worked examples (application-builder, money-transfer-api, shell-scripting-dsl), the bundled CGP skill and its reference sub-files, and six source files under crates/ (in cgp-error, cgp-handler, cgp-run, and cgp-runtime). No files were deleted, no modules were moved, and no new crates or public items were introduced — the structure of the repository is unchanged, and the diff is edits-in-place plus one added document.

Impacts

The impacts are concentrated in guidance and readability rather than behavior, but the source edits carry a real obligation to verify. The following are the full set of impacts this PR carries.

No API or behavioral change. The rewritten trait definitions are equivalent to their originals: #[use_type(HasErrorType::Error)] reintroduces HasErrorType as a supertrait and expands bare Error to <Self as HasErrorType>::Error, so downstream code that implements or consumes CanRaiseError, CanWrapError, the handler traits, the runners, or HasRuntime sees the same trait contract. There is no breaking change for users of these crates.

The shipped crates must still compile and pass tests. Because the source edits change how these traits are written, they need to be confirmed by a build and test run even though the desugaring should be identical. This is the one place the PR could regress if a rewrite is subtly wrong (for example, a signature where a bare Error was left where a local associated type belonged), so cargo build and cargo test across the touched crates are the gating check before merge.

The bundled CGP skill changes how AI agents write CGP. The docs/skills/cgp/ files — including the top-level SKILL.md and several reference sub-files — now instruct agents to strongly prefer the modern idioms and to reach for explicit forms only in the narrow exception cases. Any agent that loads this skill after the change will produce different, more vanilla-looking CGP code by default, and will steer users toward #[cgp_impl], #[implicit], #[use_type], #[extend], and open-based dispatch.

Human-facing guidance is now consistent and cross-linked. Readers of the documentation get a single authoritative migration guide plus aligned examples and reference pages, which reduces the risk of a newcomer copying an explicit form from one page while a neighboring page recommends the modern one. The new prose on the local-associated-type rule (Self::Output stays qualified; #[use_type] only rewrites imported types) closes a genuine source of confusion that the mixed signature Result<Self::Output, Error> would otherwise raise.

A soft deprecation signal for the explicit forms. By stating a clear preference and marking UseDelegate-based dispatch as legacy, the PR sets direction for future code without removing anything. Existing code that uses the explicit forms remains correct and is still what generated code and desugaring show, so no migration is forced on any downstream user — the impact is on what new code should look like, not on what old code must become.