@craft-ts/mcp 0.8.1 → 0.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craft-ts/mcp",
-  "version": "0.8.1",
+  "version": "0.8.2",
   "description": "MCP server, Agent Skills, and LLM files for coding agents using @craft-ts/core",
   "author": "Romain Geffrault",
   "license": "MIT",
@@ -35,7 +35,7 @@
     "test": "vitest run --config vitest.config.mts"
   },
   "dependencies": {
-    "@craft-ts/dev-tools": "^0.8.1",
+    "@craft-ts/dev-tools": "^0.8.2",
     "@modelcontextprotocol/sdk": "1.26.0",
     "zod": "4.3.6"
   },

package/skills/craft-ts-architecture-tests/SKILL.md

@@ -28,7 +28,7 @@ generates the application, API/page example, routes, ESLint, unit tests,
 architecture suite and Playwright commands together:
 
 ```shell
-npx craft create my-app --effect=none --agents=codex,cursor,cloud-code
+npx craft create my-app --effect=none --agents=codex,cursor,claude-code
 ```
 
 For an Effect v4 starter:

package/skills/craft-ts-routes/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: craft-ts-routes
-description: Best practices for creating and maintaining type-safe routes in Angular apps that use @craft-ts/core (craft-ts). Use this whenever you create or edit a routes file, call craftRoutes(...) / route(...), declare componentDeps, wire loadChildren, add a pendingComponent or a view-transition payload, see a "TS2589 excessively deep" error in a routes file, or need a per-file DI check (ValidateCascadeRoutesFile / RouteCheckedDI). Apply it even when the user only says "add a route", "split this routes file", "fix this routing type error", or "the injectXxx helper is missing" — getting the DI checks, the loadChildren split, and exhaustiveness right is non-obvious and easy to skip, and skipping it silently disables type-safe DI.
+description: Best practices for creating and maintaining type-safe routes in Angular apps that use @craft-ts/core (craft-ts). Use this whenever you create or edit a routes file, call craftRoutes(...) / route(...), declare componentDeps, wire loadChildren, add a pendingComponent or a view-transition payload, or need a per-route DI check (RouteCheckedDI). Apply it even when the user only says "add a route", "split this route file", "fix this routing type error", or "the injectXxx helper is missing" — getting the DI checks, the loadChildren split, and exhaustiveness right is non-obvious and easy to skip, and skipping it silently disables type-safe DI.
 ---
 
 # Creating craft-ts routes
@@ -9,9 +9,9 @@ description: Best practices for creating and maintaining type-safe routes in Ang
 
 Produce route files that keep **compile-time dependency-injection safety** intact. In craft-ts a route
 is not just a path → component map: each route declares the dependencies its component injects
-(`componentDeps`), and a per-file check turns any unmet dependency into a TypeScript error. The whole
+(`componentDeps`), and a per-route check turns any unmet dependency into a TypeScript error. The whole
 value proposition collapses the moment a route ships without its check, so the rules below are about
-never letting that happen — while staying under TypeScript's instantiation ceiling.
+never letting that happen.
 
 If the public API names here don't match the installed version, confirm against the app's own routes and
 `node_modules/@craft-ts/core`; prefer the patterns already used in the repo.
@@ -22,23 +22,19 @@ If the public API names here don't match the installed version, confirm against
    component route a `componentDeps: {} as import('./x').GenDeps_X` line. That line is the wire between
    the component's generated dependency type and the route check; without it the route's DI is invisible.
 
-2. **Every `craftRoutes(...) file carries its own DI check.`** Add, in the same file:
+2. **Every routed component carries its own DI check.** Add, in the route file:
    ```ts
-   type _CheckXDI = ValidateCascadeRoutesFile<ParentNames, ParentValues, typeof xRoutes>;
+   type _CheckXDI = RouteCheckedDI<ComponentDeps, ParentNames, ParentValues, 'route'>;
    type _CanRunX = CanRun<_CheckXDI>;
    ```
-   This is the *iron rule*: the check reads only the current collection and **does not descend into
-   `loadChildren`**, so each file — including lazy children — must re-declare it or its components go
-   unchecked. A missing provider then surfaces as `Injected SomeService is not provided in path: "…"`.
-   Architecture tests (`assertRouteDiProofs`) fail CI if a collection ships without an armed check.
+   A missing provider then surfaces as `Injected SomeService is not provided in path: "…"`.
+   Architecture tests (`assertRouteDiProofs`) fail CI if a routed component ships without an armed check.
    That helper belongs in the app's `architecture/` suite — load `craft-ts-architecture-tests` to
    scaffold or keep it armed. Do not add an architecture rule for the feature.
 
-3. **Stay under the instantiation ceiling — split with `loadChildren`.** One collection has a finite
-   route budget; past it TypeScript throws `TS2589: Type instantiation is excessively deep`, which then
-   **collapses inference for the whole file** (helpers vanish, `route(...)` calls degrade). The fix is
-   architectural, not a tweak: move routes into lazy child collections joined by `loadChildren`, each with
-   its own check. See [references/scaling-and-pitfalls.md](references/scaling-and-pitfalls.md).
+3. **Keep route ownership clear — split with `loadChildren`.** Move a feature into a lazy child collection
+   when it deserves a separate loading or ownership boundary. Each routed component in the child still
+   carries its own `RouteCheckedDI` check. See [references/scaling-and-pitfalls.md](references/scaling-and-pitfalls.md).
 
 4. **Keep exception handling exhaustive.** A route whose `canActivate` / `canMatch` / `resolve` can throw
    a typed `craftException` must handle exactly those codes. Use the 3-arg `route(path, def, handlers)`
@@ -62,11 +58,11 @@ import {
   route,
   assertExhaustiveRouteExceptions,
   type CanRun,
-  type ValidateCascadeRoutesFile,
+  type RouteCheckedDI,
 } from '@craft-ts/core';
 import type { Router } from '@angular/router';
 
-export const { featureRoutes, injectFeatureUserIdParams } = craftRoutes('feature', [
+export const { featureRoutes, FeatureUserIdParams } = craftRoutes('feature', [
   route(':userId', {
     componentDeps: {} as import('./user-detail').GenDeps_UserDetailComponent,
     loadComponent: () => import('./user-detail'),
@@ -77,8 +73,13 @@ export const { featureRoutes, injectFeatureUserIdParams } = craftRoutes('feature
 // Exhaustive over canActivate ∪ canMatch ∪ resolve for the whole collection.
 assertExhaustiveRouteExceptions(featureRoutes);
 
-// DI safety for THIS collection — the parent's cascade does NOT cover loadChildren.
-type _CheckFeatureDI = ValidateCascadeRoutesFile<never, Router, typeof featureRoutes>;
+// DI safety for this routed component.
+type _CheckFeatureDI = RouteCheckedDI<
+  import('./user-detail').GenDeps_UserDetailComponent,
+  never,
+  Router,
+  'feature/:userId'
+>;
 type _CanRunFeature = CanRun<_CheckFeatureDI>;
 ```
 
@@ -97,18 +98,17 @@ The parent registers the child as a near-free lazy entry:
 - **Adding a component route** → add `loadComponent` (or `component`) **and** `componentDeps:
   {} as import('./x').GenDeps_X`. If `GenDeps_X` doesn't exist yet, generate it (ESLint Quick Fix
   `brand-angular-gen-deps-required`, or `craft:brand`), don't write it by hand.
-- **A routes file is getting large / hits TS2589** → don't fight the type; split a slice into a new
-  `craftRoutes(...)` file mounted via `loadChildren`, and give that file its own check. Repeat as a tree.
+- **A feature needs a separate loading or ownership boundary** → split it into a new `craftRoutes(...)`
+  file mounted via `loadChildren`, and give every routed component in that file its own check.
 - **A lazy child only makes sense under one specific path** (it relies on that route's params, payload, or
   providers) → pin it with `.withParent<ParentRoutes<'path'>>()` and enforce placement in the parent with
   `assertChildRouteMounts(parentRoutes)`. See the scaling reference.
 - **Slow guard/resolve + you want a skeleton** → add `pendingComponent: () => import('./skeleton')`. The
-  cascade never sees the skeleton, so verify its DI separately with a per-component `RouteCheckedDI`. For a
+  route check does not cover the skeleton, so verify its DI separately with a per-component `RouteCheckedDI`. For a
   shared-element morph, declare the payload with `viewTransitionPayload<T>()`. See
   [references/pending-and-exceptions.md](references/pending-and-exceptions.md).
-- **A single file genuinely must hold a big flat list** (no natural `loadChildren` boundary) → switch from
-  `ValidateCascadeRoutesFile` to the per-route `RouteCheckedDI` (no recursion between routes, scales to
-  thousands). See the DI-checks reference.
+- **A single file genuinely must hold a big flat list** → use one `RouteCheckedDI` / `CanRun` pair per
+  routed component. The checks do not recurse through sibling routes.
 - **You changed a component's `inject`/`imports`/`providers`** → regenerate its `GenDeps_*` (Quick Fix /
   `craft:brand`) so the route check sees the new shape, then re-run ESLint `--fix` on the routes file.
 
@@ -116,19 +116,15 @@ The parent registers the child as a near-free lazy entry:
 
 - Export a plain `Routes` array, or omit `componentDeps` on a routed component — the route's DI becomes
   unchecked.
-- Ship a `craftRoutes(...)` file without its own check, or assume the parent's check covers a
-  `loadChildren` child — it does not.
-- "Fix" a `TS2589` by deleting the check or casting to `any` — that hides every DI error in the file.
-  Split with `loadChildren` instead.
+- Ship a routed component without its own check, or assume a parent's check covers a `loadChildren` child.
 - Hand-edit the generated `_Check*` / `_CanRun*` blocks or `GenDeps_*` aliases — run ESLint `--fix`.
 
 ## References
 
-- [references/di-checks.md](references/di-checks.md) — the per-file check in depth: `ValidateCascadeRoutesFile`,
-  threading the parent DI context, the `RouteCheckedDI` escape hatch, and `GenDeps_*` regeneration.
-- [references/scaling-and-pitfalls.md](references/scaling-and-pitfalls.md) — the TS2589 ceiling, the
-  loadChildren-tree architecture, `.withParent` + `assertChildRouteMounts`, and approaches that look
-  tempting but don't work (so you don't re-derive them).
+- [references/di-checks.md](references/di-checks.md) — the per-route check, parent DI context, and
+  `GenDeps_*` regeneration.
+- [references/scaling-and-pitfalls.md](references/scaling-and-pitfalls.md) — the loadChildren tree,
+  `.withParent` + `assertChildRouteMounts`, and route ownership pitfalls.
 - [references/pending-and-exceptions.md](references/pending-and-exceptions.md) — `pendingComponent` DI
   verification, `viewTransitionPayload`, `handleExceptions`, and exhaustiveness.
 - [references/eslint-workflow.md](references/eslint-workflow.md) — the ESLint rules that keep all of the

package/skills/craft-ts-routes/references/di-checks.md

@@ -1,101 +1,55 @@
-# Per-file DI checks
+# Per-route DI checks
 
 ## What the check does
 
-`ValidateCascadeRoutesFile<ParentNames, ParentValues, typeof xRoutes>` walks every route in the
-collection at the type level and, for each routed component, compares the dependencies it injects
-(`componentDeps` → its `GenDeps_*`) against what is provided — the route's own auto-provided services
-(params, `data`, `queryParams`, guarded/resolved data), the route `providers`, and the **parent context**
-you pass in. Any gap becomes a TypeScript error on `_CanRun*`:
-
-```
-Injected SomeService is not provided in path: "some/path"
-Input "userId" is not provided in path: "some/path"
-```
-
-`CanRun<Check>` is what turns the check result into a hard compile error — always pair them:
+`RouteCheckedDI<ComponentDeps, ParentNames, ParentValues, Context, RouteInputs>` compares one
+routed component's dependencies against the providers available at its mount point, the route, and
+the component itself. Any gap becomes a TypeScript error when the result is consumed by `CanRun`:
 
 ```ts
-type _CheckXDI = ValidateCascadeRoutesFile<ParentNames, ParentValues, typeof xRoutes>;
+type _CheckXDI = RouteCheckedDI<
+  import('./detail').GenDeps_DetailComponent,
+  AppProvidedNames,
+  AppProvidedValues,
+  'detail/:id',
+  'id'
+>;
 type _CanRunX = CanRun<_CheckXDI>;
 ```
 
-## The iron rule (why every file needs its own)
-
-The check reads only the **current** collection's metadata. It does **not** descend into `loadChildren`.
-So a lazy child loaded from another file is invisible to the parent's check — that child file must
-declare its own, or its components are never verified. This is the single most common way DI safety
-silently disappears.
+Typical errors are:
 
 ```
-app.routes.ts          → ValidateCascadeRoutesFile<…, typeof appRoutes>     (checks its own leaves)
-└── loadChildren → feature.routes.ts → ValidateCascadeRoutesFile<…, typeof featureRoutes>  (MUST have its own)
+Injected SomeService is not provided in path: "detail/:id"
+Input "id" is not provided in path: "detail/:id"
 ```
 
-## Threading the parent DI context
-
-`ParentNames` / `ParentValues` describe everything provided **at the collection's mount point** — app
-providers **plus** every ancestor route's `providers`.
-
-- **App-level / no ancestor providers** (the common case): `<never, Router>`. No extra named providers;
-  `Router` is provided by value via `provideCraftRouter` / `provideRouter`. This pair is identical in
-  every file mounted directly under the app.
-
-  ```ts
-  type _Check = ValidateCascadeRoutesFile<never, Router, typeof featureRoutes>;
-  ```
+The `CanRun` alias is what turns the result into a hard compile error. Keep both aliases next to the
+route metadata.
 
-- **Mounted under a route that adds `providers: [provideBilling()]`**: re-export the ancestor's cumulative
-  context next to the route that adds it, and union your own onto it:
+## One check per routed component
 
-  ```ts
-  // billing.routes.ts
-  export type BillingChildNames  = AppProvidedNames | 'BillingService';
-  export type BillingChildValues = AppProvidedValues;
+`RouteCheckedDI` does not recurse through sibling routes or lazy route collections. Every routed
+component, including components in a `loadChildren` child file, therefore needs its own check. This
+per-route shape keeps the cost stable as a route file grows and makes the failing route easy to find.
 
-  // sub-billing.routes.ts
-  type _Check = ValidateCascadeRoutesFile<BillingChildNames, BillingChildValues, typeof subRoutes>;
-  ```
+The architecture assertion `assertRouteDiProofs` catches a missing or unarmed check in CI. TypeScript
+still validates the dependency semantics; the architecture suite validates that the check was invoked.
 
-Forgetting to fold in an ancestor's provider makes the check wrong in **both** directions: a genuinely
-missing provider can slip through, or a provided service gets flagged as missing. Keep the re-export
-beside the route that adds the providers.
-
-> Note: deriving the names automatically (e.g. `AppProvidedServiceNamesOf<typeof appConfig>`) can itself
-> hit TS2589 when app providers are complex (function wrappers, monitoring, …). Listing the value types
-> explicitly (`<never, Router, …>`) is the reliable workaround.
-
-## The `RouteCheckedDI` escape hatch (O(1) per route)
-
-When a single file genuinely must hold a large **flat** list with no natural `loadChildren` boundary,
-switch from the aggregated cascade to the per-route check. It validates one component at a time with **no
-recursion between routes**, so it never hits the depth ceiling and scales to thousands of routes — at the
-cost of one block per component instead of one per file:
-
-```ts
-import { type CanRun, type RouteCheckedDI } from '@craft-ts/core';
-
-type _CheckItem0 = RouteCheckedDI<
-  import('./item-0').GenDeps_Item0Component,
-  AppProvidedNames,   // available provider names (parent context)
-  AppProvidedValues,  // provided value types
-  'Item0Component'    // label shown in the error
->;
-type _CanRunItem0 = CanRun<_CheckItem0>;
-// …one pair per route component
-```
+## Threading the parent DI context
 
-Prefer the `loadChildren` tree (it also code-splits); reach for `RouteCheckedDI` only when one big flat
-file is unavoidable — or to verify a component the cascade can't see, like a `pendingComponent`.
+`ParentNames` / `ParentValues` describe everything provided at the route's mount point — app providers
+plus ancestor route providers.
 
-## `GenDeps_*` — keep it fresh
+- **App-level / no ancestor providers:** use the app's named provider union and value type.
+- **Mounted under a route that adds providers:** re-export the ancestor's cumulative context next to
+  the route that adds them and pass it to the child route checks.
 
-`componentDeps: {} as import('./x').GenDeps_X` points at a generated alias describing the component's DI
-shape. It is **generated, not hand-written**. Regenerate it whenever the component's DI changes:
+Forgetting an ancestor provider can either hide a missing-provider error or report a provided service
+as missing, so keep the context definition beside the provider boundary.
 
-- adding/removing `inject(...)` or constructor injection
-- changing component `imports`, `providers`, or `viewProviders`
+## Pending and error components
 
-Use the ESLint Quick Fix (`brand-angular-gen-deps-required` to create, `brand-angular-deps-match` to
-refresh) or the project's `craft:brand` codemod. A stale `GenDeps_*` makes the route check validate the
-wrong shape — so after regenerating it, re-run ESLint `--fix` on the routes file.
+Pending components and error-component descriptors are not the routed target. Verify them independently
+with `RouteCheckedDI` or `RouteExceptionComponentCheckedDI`, then consume each result with `CanRun`.
+The ESLint rules for pending and exception components maintain those independent blocks.

package/skills/craft-ts-routes/references/eslint-workflow.md

@@ -1,52 +1,37 @@
-# ESLint workflow — let the rules keep the checks in sync
+# ESLint workflow — keep route checks in sync
 
-The route DI checks, the `GenDeps_*` aliases, the asserts and their imports are **generated and refreshed
-by ESLint**, not hand-written. This matters because an ESLint error is **not** a TypeScript compile error:
-a stale or missing check passes the build while silently hiding real DI bugs. So the discipline is: after
-touching routes or a component's DI shape, run `--fix` and trust the rules to regenerate the bookkeeping.
+The route checks, dependency metadata, exception asserts and their imports are maintained by the
+project's ESLint rules. An ESLint error is not a TypeScript compile error, so run ESLint after editing
+routes or a component's dependency shape.
 
-## The routing-relevant rules
+## Routing-relevant rules
 
-Enable these in the flat ESLint config (plugin exposed as `@craft-ts/dev-tools/eslint-rules`, registered
-under the `craft-ts/` namespace):
+Enable these in the flat ESLint config (plugin exposed as `@craft-ts/dev-tools/eslint-rules`):
 
 | Rule | Keeps in sync |
 | --- | --- |
-| `brand-angular-gen-deps-required` | creates a missing `GenDeps_*` alias for a component/directive/pipe |
-| `brand-angular-deps-match` | refreshes an existing `GenDeps_*` when the component's DI changes |
-| `require-assert-exhaustive-route-exceptions` | adds `assertExhaustiveRouteExceptions(xRoutes)` (+ import) per collection |
+| `require-assert-exhaustive-route-exceptions` | adds `assertExhaustiveRouteExceptions(xRoutes)` per collection |
 | `require-pending-component-di-check` | generates/refreshes the `RouteCheckedDI` block for a `pendingComponent` |
-| `require-child-route-mount-check` | adds `assertChildRouteMounts(xRoutes)` (+ import) for collections mounting lazy `loadChildren` |
+| `require-exception-component-di-check` | generates/refreshes `RouteExceptionComponentCheckedDI` blocks |
+| `require-child-route-mount-check` | adds `assertChildRouteMounts(xRoutes)` for collections mounting lazy `loadChildren` |
 | `global-exception-registry-match` | mirrors `globalError()` codes into `CraftGlobalExceptionRegistry` |
 
-> The aggregated `ValidateCascadeRoutesFile<…>` check itself is **not** auto-generated (its parent context
-> can't be guessed across files). Write that one block by hand per file — see di-checks.md — and let the
-> rules above handle everything else.
-
 ## The loop
 
-1. **Create/edit a routed component** → run the Quick Fix `brand-angular-gen-deps-required` (or
-   `brand-angular-deps-match` if it already has a `GenDeps_*`), or the project's `craft:brand` codemod, to
-   (re)generate the alias.
-2. **Edit the routes file** → run ESLint `--fix` on it. The asserts, the pending-component `RouteCheckedDI`
-   block, the child-mount assert and their imports are added/refreshed.
-3. **Read the remaining TypeScript errors** — those are the real DI gaps (`Injected X is not provided…`,
-   `Input "y" is not provided…`). Fix by providing the service / adding the input / correcting the route.
+1. **Edit a routed component or route** → keep its `RouteCheckedDI` / `CanRun` block beside the route.
+2. **Run ESLint `--fix`** on the changed route file. Exception, pending-component and child-mount
+   bookkeeping is added or refreshed.
+3. **Read the remaining TypeScript errors** — these are the real DI gaps (`Injected X is not provided…`,
+   `Input "y" is not provided…`).
 
 ```bash
-# one file
 eslint --fix src/app/feature/feature.routes.ts
-# the component whose DI changed
-eslint --fix src/app/feature/feature-detail.ts
 ```
 
 ## Gotchas
 
-- **Quick Fix is per-file.** It won't cascade to other files; run it on each file you changed.
-- **Rename a component class → rerun the generator** so the `GenDeps_*` alias name stays aligned with the
-  class name.
-- **Flat config resolves rules from the CWD.** If `--fix` seems to do nothing, run it from the directory
-  whose ESLint config actually enables the `craft-ts/*` rules (often the app project root, not the repo
-  root).
-- **Don't commit a green build with a red ESLint.** Because the ESLint error isn't a compile error, a route
-  can build fine while its check is stale — CI should run both.
+- Checks are per-file and per-route; a parent file does not cover a component loaded through
+  `loadChildren`.
+- Quick fixes are per-file. Run them on each route file you changed.
+- Do not commit a green build with a red ESLint result: a missing or unarmed check can otherwise pass
+  TypeScript while the architecture test catches it only later.

package/skills/craft-ts-routes/references/pending-and-exceptions.md

@@ -15,17 +15,12 @@ route('user/:userId', {
 }),
 ```
 
-### Verifying the skeleton's DI (the cascade can't see it)
+### Verifying the skeleton's DI
 
-`ValidateCascadeRoutesFile` only checks the **target** component — it never descends into
-`pendingComponent`. A skeleton is a real component that injects things (route params, a payload,
-monitoring), so verify it **directly** with the per-component `RouteCheckedDI` (not a second aggregated
-pass — that would add to the budget the cascade already spends):
+The skeleton is a real component that injects things (route params, a payload, monitoring), so verify it
+independently with the per-component `RouteCheckedDI`:
 
 ```ts
-type _CheckTargetDI = ValidateCascadeRoutesFile<AppNames, AppValues, typeof userRoutes>;
-type _CanRunTarget = CanRun<_CheckTargetDI>;
-
 // The skeleton injects the route-auto-provided :userId param — list its service name as available.
 type _CheckPendingDI = RouteCheckedDI<
   import('./user-skeleton').GenDeps_UserSkeletonComponent,
@@ -38,8 +33,7 @@ type _CanRunPending = CanRun<_CheckPendingDI>;
 
 The ESLint rule `require-pending-component-di-check` **generates and refreshes this whole block** on
 `--fix` — deriving the skeleton's `GenDeps_*`, the auto-provided service names from the route's path params
-(+ view-transition payload), and the parent context from the collection's own `ValidateCascadeRoutesFile`.
-Don't hand-maintain it.
+(+ view-transition payload), and the parent context. Don't hand-maintain it.
 
 ## View transitions (shared-element morph across a slow chain)
 

package/skills/craft-ts-routes/references/scaling-and-pitfalls.md

@@ -1,111 +1,58 @@
-# Scaling routes & the instantiation ceiling
+# Scaling routes and avoiding type blow-ups
 
-## The ceiling, and why it's loud
+`RouteCheckedDI` checks one routed component at a time. It does not recurse through sibling routes,
+so the DI proof cost remains local to the component being checked.
 
-`ValidateCascadeRoutesFile` instantiates a recursive type over the route tuple. TypeScript caps both how
-**deep** it will recurse and how many instantiations it will do in **total**, so a single collection has a
-finite budget — in practice a few dozen routes, sooner if routes carry guards / `resolve` /
-`handleExceptions` (each costs several times more than a trivial route).
+## Use a route tree when ownership or loading requires it
 
-Past the budget:
+Split features into child collections joined by `loadChildren` when that improves code-splitting or
+ownership:
 
 ```
-TS2589: Type instantiation is excessively deep and possibly infinite.
-  app.routes.ts → ValidateCascadeRoutesFile<never, Router, typeof appRoutes>
+app.routes.ts
+├── billing.routes.ts       # each routed component has RouteCheckedDI + CanRun
+├── admin.routes.ts         # each routed component has RouteCheckedDI + CanRun
+└── reporting.routes.ts
 ```
 
-**Watch the knock-on collapse.** A `TS2589` makes TypeScript abandon that type and fall back to `any`,
-which poisons inference of neighbouring `const`s in the *same file*. The symptoms are misleading:
-`route(...)` calls degrade to a bare builder type, the `craftRoutes(...)` helpers go missing
-(`Property 'injectXxx' does not exist`), `craftRouterLink` targets type as `never`. The root cause is the
-overflowing check — fix that, not the symptoms.
-
-## The fix is architectural: a tree of `loadChildren`
-
-Don't shrink the check or cast to `any`. Move routes into lazy child collections joined by `loadChildren`
-(which you want anyway for code-splitting), each with **its own** check:
+The child returns its named collection from `loadChildren`:
 
-```
-app.routes.ts                 # "manifest": ~N cheap { path, loadChildren } entries
-├── billing.routes.ts         # ~15–20 leaf routes + its own ValidateCascadeRoutesFile
-├── admin.routes.ts           # ~15–20 leaf routes + its own check
-└── reporting.routes.ts       # if itself large → re-split into sub-loadChildren (level 3+)
+```ts
+{
+  path: 'billing',
+  loadChildren: ({ withRetry }) =>
+    withRetry(import('./billing.routes')).then((m) => m.billingRoutes),
+}
 ```
 
-- A `{ path, loadChildren }` entry has no `componentDeps`, so it is **nearly free** in the parent's check —
-  the manifest can list dozens.
-- Each feature file pays only for its own leaves. ~500 routes ÷ ~17 per file ≈ ~30 files; two levels are
-  plenty and you can nest further without limit.
-- The takeaway: **DI is always verified — never drop the check; move it next to the routes it covers.**
+A parent check does not cover components in the lazy child. Keep each child's route checks beside
+the components they validate.
 
-The child returns its named collection from `loadChildren`:
+## Thread the parent DI context
 
-```ts
-// app.routes.ts
-{ path: 'billing', loadChildren: () => import('./billing.routes').then((m) => m.billingRoutes) },
-```
+`ParentNames` / `ParentValues` passed to `RouteCheckedDI` describe everything provided at the route's
+mount point: app providers plus ancestor route providers. Re-export the cumulative context when an
+ancestor adds route providers, then pass it to the child checks.
 
-## Pinning a child to its mount — `.withParent` + `assertChildRouteMounts`
+## Pin a child to its mount
 
-A child whose components rely on a *specific* mount (its `:param`, a view-transition payload, an ancestor's
-providers) is only correct under that one path. Nothing enforces that by default. Pin it:
+A child whose components rely on a specific mount (a route param, a view-transition payload, or an
+ancestor provider) can declare `.withParent<ParentRoutes<'path'>>()`. Enforce placement in the parent
+with `assertChildRouteMounts(parentRoutes)`:
 
 ```ts
-// view-transitions.routes.ts — the child declares where it belongs
-import { craftRoutes, route, type ParentRoutes } from '@craft-ts/core';
-
 export const { viewTransitionsRoutes } = craftRoutes('viewTransitions', [
-  route(':photoId', { /* … */ }),
+  craftRoute(':photoId', { /* … */ }),
 ]).withParent<ParentRoutes<'view-transitions'>>();
-```
-
-```ts
-// app.routes.ts — the parent enforces placement (scoped to this file)
-import { assertChildRouteMounts, craftRoutes } from '@craft-ts/core';
-
-export const { demoRoutes } = craftRoutes('demo', [
-  { path: 'view-transitions', loadChildren: () => import('./view-transitions.routes').then((m) => m.viewTransitionsRoutes) },
-]);
 
 assertChildRouteMounts(demoRoutes);
 ```
 
-Mount the pinned collection elsewhere and the **parent file** fails to compile:
+`assertChildRouteMounts` reads only the parent's own routes and does not re-validate the child.
 
-```
-craftRoutes(...).withParent<ParentRoutes<'view-transitions'>>() must be
-loadChildren-mounted under the route with path 'view-transitions', not 'admin'
-```
+## Pitfalls
 
-- **Opt-in.** A collection without `.withParent` is unpinned and mountable anywhere (backward compatible).
-  Pin only the children whose placement actually matters.
-- **Scoped to the parent.** `assertChildRouteMounts` reads the parent's own routes — it doesn't re-validate
-  the child, so it adds nothing to the child's budget.
-- **Type-only.** `.withParent<…>()` returns the same object at runtime; `ParentRoutes<'path'>` carries only
-  the path string, so it creates no runtime coupling.
-- **ESLint** (`require-child-route-mount-check`) adds the missing `assertChildRouteMounts(...)` + import on
-  `--fix`. Whether a child opts in with `.withParent` stays your call.
-
-## Pitfalls — approaches that look tempting but don't work
-
-These were tried and rejected; recording them so they aren't re-derived.
-
-- **Casting away a `TS2589`** (`as any`, deleting the check, `@ts-ignore`). It silences the error but
-  disables DI checking for the whole file — the opposite of the goal. Always split with `loadChildren`.
-
-- **Enforcing child placement inside `craftRoutes(...)` itself** (weaving a mount check into the `routes`
-  argument type so a wrong mount errors at the literal). It type-checks, but the extra per-collection
-  instantiation tips already-at-ceiling files into `TS2589` — even a 2-route child with no `loadChildren`
-  pays the cost, because *every* collection runs the same inference. Placement checks must be **scoped to
-  the parent** that mounts children (a standalone `assertChildRouteMounts`), not folded into the hot
-  `craftRoutes` path every file pays.
-
-- **A `loadChildrenType: {} as typeof import('./x').xRoutes` carrier** to skip inferring the child through
-  `import().then()`. In isolation it builds; applied broadly it **materialises the child's full type
-  (components included)**, creating a **circular reference** for any child whose components inject the
-  *parent's* route data (`TS2615` "circularly references itself" + `TS2589`). The dynamic-import resolution
-  it replaced is cycle-safe and, measured against build-time noise, no slower — so don't add such a carrier.
-
-- **Auto-deriving the parent context** from the app config in a generic constraint
-  (`AppProvidedServiceNamesOf<typeof appConfig>`). It overflows when app providers are complex. List the
-  value types explicitly: `<never, Router, …>`.
+- Do not cast away a DI error with `any` or `@ts-ignore`.
+- Do not assume a parent route check covers a `loadChildren` child.
+- Do not omit `CanRun`: the type alias is what consumes the check and turns a mismatch into a compile
+  error.

package/skills/craft-ts-service-migration/SKILL.md

@@ -44,7 +44,7 @@ Use this skill when a task touches dependency injection, service architecture, o
 
 6. Refresh generated artifacts:
    - Run ESLint `--fix` for `brand-angular-gen-deps-required` and `brand-angular-deps-match`.
-   - Check route files still have `componentDeps` and `ValidateCascadeRoutesFile` or `RouteCheckedDI`.
+   - Check route files still have `componentDeps` and per-route `RouteCheckedDI` checks.
    - If direct Angular tokens disappeared, remove them from `ProvidedValues`; prefer `never`.
 
 ## Route DI Rule
@@ -52,10 +52,11 @@ Use this skill when a task touches dependency injection, service architecture, o
 For migrated features, prefer:
 
 ```ts
-type _CheckFeatureDI = ValidateCascadeRoutesFile<
+type _CheckFeatureDI = RouteCheckedDI<
+  ComponentDeps,
   AppProvidedNames,
-  never,
-  typeof featureRoutes
+  AppProvidedValues,
+  'feature'
 >;
 type _CanRunFeature = CanRun<_CheckFeatureDI>;
 ```

package/skills/migrate-to-craft-ts/SKILL.md

@@ -113,8 +113,7 @@ cannot be inferred safely. Preserve unrelated user changes.
 
 - Complete unresolved guards, redirects, lazy collections, inherited
   providers, and dynamic route diagnostics manually.
-- Keep `componentDeps` and file-level `ValidateCascadeRoutesFile` or
-  `RouteCheckedDI` checks.
+- Keep `componentDeps` and per-route `RouteCheckedDI` checks.
 - Prefer provider names and `ProvidedValues = never` after direct Angular DI is
   removed.
 - Run ESLint fixes to regenerate `GenDeps_*` aliases after dependency changes.