@craft-ts/mcp 0.7.0-beta.13

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

@@ -0,0 +1,135 @@
+---
+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.
+---
+
+# Creating craft-ts routes
+
+## Objective
+
+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
+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.
+
+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.
+
+## The rules you must not skip
+
+1. **Wrap routes in `craftRoutes(name, [...])`** — never export a plain Angular `Routes` array. Give every
+   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:
+   ```ts
+   type _CheckXDI = ValidateCascadeRoutesFile<ParentNames, ParentValues, typeof xRoutes>;
+   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.
+   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).
+
+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)`
+   form, or assert the whole collection with `assertExhaustiveRouteExceptions(xRoutes)`.
+
+5. **Let ESLint do the bookkeeping — don't hand-maintain the checks.** The check blocks, the `GenDeps_*`
+   aliases, the asserts and imports are all generated/refreshed by ESLint `--fix`. Run it after editing
+   routes or a component's DI shape rather than editing those blocks by hand (an ESLint error is *not* a
+   compile error, so a stale check silently hides real DI bugs). See
+   [references/eslint-workflow.md](references/eslint-workflow.md).
+
+## Anatomy of a correct routes file
+
+Use this as the template for a new collection. The app-level parent context is `<never, Router>` (no
+extra named providers; `Router` is provided by value). For a child mounted under a route that adds
+`providers`, thread the cumulative context instead — see the DI-checks reference.
+
+```ts
+import {
+  craftRoutes,
+  route,
+  assertExhaustiveRouteExceptions,
+  type CanRun,
+  type ValidateCascadeRoutesFile,
+} from '@craft-ts/core';
+import type { Router } from '@angular/router';
+
+export const { featureRoutes, injectFeatureUserIdParams } = craftRoutes('feature', [
+  route(':userId', {
+    componentDeps: {} as import('./user-detail').GenDeps_UserDetailComponent,
+    loadComponent: () => import('./user-detail'),
+    // guards / resolve / providers / queryParams as needed
+  }),
+]);
+
+// 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>;
+type _CanRunFeature = CanRun<_CheckFeatureDI>;
+```
+
+The parent registers the child as a near-free lazy entry:
+
+```ts
+// app.routes.ts
+{
+  path: 'feature',
+  loadChildren: () => import('./feature.routes').then((m) => m.featureRoutes),
+},
+```
+
+## Decision rules
+
+- **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 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
+  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.
+- **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.
+
+## Never do this
+
+- 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.
+- 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/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
+  above in sync, and the `--fix` workflow.

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

@@ -0,0 +1,101 @@
+# Per-file 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:
+
+```ts
+type _CheckXDI = ValidateCascadeRoutesFile<ParentNames, ParentValues, typeof xRoutes>;
+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.
+
+```
+app.routes.ts          → ValidateCascadeRoutesFile<…, typeof appRoutes>     (checks its own leaves)
+└── loadChildren → feature.routes.ts → ValidateCascadeRoutesFile<…, typeof featureRoutes>  (MUST have its own)
+```
+
+## 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>;
+  ```
+
+- **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:
+
+  ```ts
+  // billing.routes.ts
+  export type BillingChildNames  = AppProvidedNames | 'BillingService';
+  export type BillingChildValues = AppProvidedValues;
+
+  // sub-billing.routes.ts
+  type _Check = ValidateCascadeRoutesFile<BillingChildNames, BillingChildValues, typeof subRoutes>;
+  ```
+
+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
+```
+
+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`.
+
+## `GenDeps_*` — keep it fresh
+
+`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:
+
+- adding/removing `inject(...)` or constructor injection
+- changing component `imports`, `providers`, or `viewProviders`
+
+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.

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

@@ -0,0 +1,52 @@
+# ESLint workflow — let the rules keep the 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 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):
+
+| 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-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` |
+| `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.
+
+```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.

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

@@ -0,0 +1,93 @@
+# Pending UI, view transitions & exhaustive exceptions
+
+## Non-blocking navigation + pending component
+
+With `<craft-router-outlet>` (wired via `provideCraftRouter(...)`) navigation is non-blocking: the URL
+commits immediately, a `pendingComponent` (skeleton) shows while a slow guard/resolve chain is in flight,
+and the target mounts only on success. Add one per route as a craft-only field:
+
+```ts
+route('user/:userId', {
+  componentDeps: {} as import('./user').GenDeps_UserComponent,
+  loadComponent: () => import('./user'),
+  pendingComponent: () => import('./user-skeleton'),
+  canActivate: craftCanActivate(/* slow guard */),
+}),
+```
+
+### Verifying the skeleton's DI (the cascade can't see it)
+
+`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):
+
+```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,
+  'UserUserIdParams',     // route-auto-provided names the skeleton may inject
+  AppValues,              // same parent context the cascade uses
+  'pending component: user/:userId'
+>;
+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 transitions (shared-element morph across a slow chain)
+
+For a shared-element morph to survive a slow navigation, the route **declares the payload shape** with
+`viewTransitionPayload<T>()` — the view-transition analogue of how `queryParams` declares query-params shape:
+
+```ts
+export const { photosRoutes, injectPhotosPhotoIdViewTransition } = craftRoutes('photos', [
+  route(':photoId', {
+    componentDeps: {} as import('./photo-detail').GenDeps_PhotoDetailComponent,
+    loadComponent: () => import('./photo-detail'),
+    withLoaderViewTransitionImage: viewTransitionPayload<{ name: string; image: string | null }>(),
+    pendingComponent: () => import('./photo-skeleton'),
+  }),
+]).withParent<ParentRoutes<'photos'>>();
+```
+
+This makes a typed `viewTransition: T | null` **required** on every `craftRouterLink` / `navigate` targeting
+the route, and exposes a route-generated `injectPhotosPhotoIdViewTransition(): Signal<T | null>` helper the
+skeleton/target reads to wear the matching `view-transition-name`. Use `withCraftViewTransitions()` (not
+Angular's `withViewTransitions()`) so the morph is driven by the outlet's own swaps. The payload travels in
+navigation `state`, so it is lost on reload/direct URL — the app stays functional without the preview image.
+
+## Exhaustive exception handling
+
+A route whose `canActivate` / `canMatch` / `resolve` can short-circuit with a typed `craftException({ code })`
+must handle exactly those codes — no missing, no extra. Two equivalent ways:
+
+- **3-arg `route(path, def, handlers)`** — enforces exhaustiveness at the call site:
+
+  ```ts
+  route(':photoId', {
+    canActivate: craftCanActivate(/* may craftException({ code: 'DENIED' }) */),
+    // …
+  }, {
+    DENIED: ({ redirect }) => redirect('/photos'),
+  }),
+  ```
+
+- **`handleExceptions` field + a collection-level assert** as a safety net for 2-arg routes:
+
+  ```ts
+  assertExhaustiveRouteExceptions(photosRoutes);
+  ```
+
+  A route that can throw but was written with the 2-arg form surfaces its unhandled codes here. The ESLint
+  rule `require-assert-exhaustive-route-exceptions` adds this assert (+ import) on `--fix`.
+
+Handlers receive helpers like `redirect('/path')` and `globalError()` (delegates to the global error
+component). Codes routed to `globalError()` are mirrored in the `CraftGlobalExceptionRegistry` augmentation
+by the `global-exception-registry-match` ESLint autofix — don't edit that by hand either.

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

@@ -0,0 +1,111 @@
+# Scaling routes & the instantiation ceiling
+
+## The ceiling, and why it's loud
+
+`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).
+
+Past the budget:
+
+```
+TS2589: Type instantiation is excessively deep and possibly infinite.
+  app.routes.ts → ValidateCascadeRoutesFile<never, Router, typeof appRoutes>
+```
+
+**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:
+
+```
+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+)
+```
+
+- 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.**
+
+The child returns its named collection from `loadChildren`:
+
+```ts
+// app.routes.ts
+{ path: 'billing', loadChildren: () => import('./billing.routes').then((m) => m.billingRoutes) },
+```
+
+## Pinning a child to its mount — `.withParent` + `assertChildRouteMounts`
+
+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:
+
+```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', { /* … */ }),
+]).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:
+
+```
+craftRoutes(...).withParent<ParentRoutes<'view-transitions'>>() must be
+loadChildren-mounted under the route with path 'view-transitions', not 'admin'
+```
+
+- **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, …>`.

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

@@ -0,0 +1,86 @@
+---
+name: craft-ts-service-migration
+description: Guides migration of existing Angular services and direct Angular DI toward @craft-ts/core craftService/toCraftService patterns. Use when editing or reviewing Angular services, @Injectable classes, inject(...), InjectionToken adapters, HttpClient/Router/Dialog usage, service tests, or route DI checks affected by service migration.
+---
+
+# craft-ts Service Migration
+
+Use this skill when a task touches dependency injection, service architecture, or migration from an existing Angular codebase to `@craft-ts/core`.
+
+## Target Architecture
+
+- Application/domain services are authored with `craftService(...)`.
+- Existing Angular tokens, framework services, third-party services, and `InjectionToken`s are adapted once with `toCraftService(...)`.
+- Components, route guards, resolvers, primitives, and other craft services consume the generated `X()` helper, not Angular `inject(Token)`.
+- Direct Angular DI is treated as legacy at the app boundary. Do not add new direct `inject(...)` calls.
+- Route DI checks should rely on craft service provider names. Keep `ProvidedValues = never` unless supporting legacy direct Angular tokens is explicitly required.
+
+## Migration Workflow
+
+1. Inventory the current dependency:
+   - Find `@Injectable`, `inject(...)`, constructor injection, `InjectionToken`, `HttpClient`, `Router`, `Dialog`, `Title`, and app-specific API services.
+   - Classify each dependency as authored business logic, external Angular/framework token, or third-party adapter.
+
+2. Choose the right primitive:
+   - Business/domain logic -> `craftService({ name, scope }, function* () { ... })`.
+   - Existing Angular/third-party token -> `toCraftService({ name, scope, token })`.
+   - Existing token requiring `inject(...)` internally -> `toCraftService({ name, scope: 'global', inject: () => inject(TOKEN) })`.
+   - Dependencies that must be provided per feature/route/test -> `scope: 'toProvide'` or `scope: 'manuallyProvidedAtRoot'`.
+
+3. Preserve the public interface deliberately:
+   - Expose the smallest useful surface from adapters.
+   - Prefer yielding a narrowed method/property map: `yield* Router(undefined, ({ navigateByUrl }) => ({ navigateByUrl }))`.
+   - Avoid pass-through wrappers that expose the whole Angular service unless the service is intentionally an adapter.
+
+4. Replace consumption sites:
+   - In components/pages and craft service generators: use the generated `X()` helper, typically as `yield* X(...)`.
+   - In guards/resolvers/route helpers: use craft helpers and keep thrown exceptions typed.
+   - Remove direct Angular `inject(...)` and constructor injection from migrated code.
+
+5. Update DI registration:
+   - Add `provideX(...)` where the selected scope requires it.
+   - Keep route-level providers close to the route that owns the instance.
+   - Re-export cumulative route provider names only when child route files need them.
+
+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`.
+   - If direct Angular tokens disappeared, remove them from `ProvidedValues`; prefer `never`.
+
+## Route DI Rule
+
+For migrated features, prefer:
+
+```ts
+type _CheckFeatureDI = ValidateCascadeRoutesFile<
+  AppProvidedNames,
+  never,
+  typeof featureRoutes
+>;
+type _CanRunFeature = CanRun<_CheckFeatureDI>;
+```
+
+Use `ProvidedValues` only as a temporary legacy bridge for direct Angular tokens still injected by components. Treat unions like `Router | Dialog | Title | typeof SomeApi` in route files as migration debt unless the user explicitly wants legacy support.
+
+## ESLint Expectations
+
+Ensure these rules are enabled for migrated projects:
+
+- `craft-ts/prefer-craft-service`: blocks new `@Injectable` / `@Service` app services.
+- `craft-ts/prefer-craft-http-client`: keeps HTTP access inside craft-compatible APIs.
+- `craft-ts/brand-angular-gen-deps-required` and `craft-ts/brand-angular-deps-match`: keep `GenDeps_*` current.
+- Route rules: `require-assert-exhaustive-route-exceptions`, `require-pending-component-di-check`, and `require-child-route-mount-check`.
+
+## Review Checklist
+
+- [ ] No new direct Angular `inject(...)` in app code.
+- [ ] No new app-authored `@Injectable` service where `craftService` fits.
+- [ ] Angular/framework tokens adapted exactly once with `toCraftService`.
+- [ ] Consumption sites use the generated `X()` helper.
+- [ ] Route checks use provider names, with `ProvidedValues = never` after migration.
+- [ ] `GenDeps_*` aliases are regenerated after dependency changes.
+- [ ] Tests use craft service testing helpers instead of TestBed-only service wiring where possible.
+
+## When To Push Back
+
+Push back when a change adds a direct Angular token to `ProvidedValues` instead of adapting it with `toCraftService`, introduces a pass-through `craftService` with no meaningful interface, or disables DI checks to avoid fixing provider registration.