@craft-ts/mcp 0.7.0-beta.13

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

@@ -0,0 +1,135 @@
+---
+name: migrate-to-craft-ts
+description: Migrate an Angular application to @craft-ts/core with the craft-migrate codemod, then resolve its manual diagnostics and verify the result. Use when the user asks to migrate an Angular project, services, signals, Signal Forms, dependency injection, HTTP resources, or routes to CraftTS; asks to run craft-migrate; or needs help finishing work left by the migration scripts.
+---
+
+# Migrate To NG Craft
+
+Run the deterministic codemods first, then complete semantic migrations that
+cannot be inferred safely. Preserve unrelated user changes.
+
+## Workflow
+
+1. Inspect the repository before modifying it:
+   - Read `AGENTS.md`, `CONTEXT.md`, and relevant ADRs when present.
+   - Check `git status --short`; do not overwrite existing changes.
+   - Locate the application `tsconfig.app.json`, source root, ESLint config,
+     tests, and build commands.
+   - Read the installed `@craft-ts/core` version and avoid generating APIs that
+     version does not expose.
+
+2. Install or build `@craft-ts/dev-tools` only when needed.
+
+3. Preview the complete migration:
+
+   ```shell
+   npx craft-migrate \
+     --project path/to/tsconfig.app.json \
+     --root path/to/src \
+     --dry-run \
+     --json craft-migration-report.json
+   ```
+
+4. Review diagnostics before writing. Classify them by primitives/forms,
+   services/DI, and routes.
+
+5. Apply deterministic changes:
+
+   ```shell
+   npx craft-migrate \
+     --project path/to/tsconfig.app.json \
+     --root path/to/src \
+     --write \
+     --json craft-migration-report.json
+   ```
+
+6. Complete the manual work described below.
+
+7. Re-run in enforcement mode:
+
+   ```shell
+   npx craft-migrate \
+     --project path/to/tsconfig.app.json \
+     --root path/to/src \
+     --check \
+     --fail-on-manual
+   ```
+
+8. `craft-migrate --write` scaffolds the baseline architecture suite as its last
+   step. If `architecture/` is still missing, load `craft-ts-architecture-tests`
+   and offer `craft-migrate-architecture --write`. Do not add an architecture
+   rule for each migrated feature.
+
+9. Run targeted tests first, then lint, application type-check, architecture
+   tests (`npx nx architecture <app>` or `npx vitest run --config vitest.architecture.config.ts`),
+   full tests, and production build. Report command exit codes separately;
+   filtered output is not proof that the complete command succeeded.
+
+## Manual Migration Rules
+
+### Signals and forms
+
+- Convert Angular `signal` usage to `state`; preserve broad explicit types with
+  `value as T satisfies T` when inference would narrow the state incorrectly.
+- Convert Signal Forms to:
+
+  ```ts
+  const { myForm } = state(
+    'myForm',
+    initialValue,
+    (context) =>
+      craftPipe(
+        context,
+        ({ set, update }) => ({ set, update }),
+        insertForm(/* field trees and submit */),
+      ),
+  )
+  ```
+
+- Use `insertSelectFormTree` and `insertFormAttributes` for nested fields.
+- Map validators to `cRequired`, `cMaxLength`, and other Craft validators.
+- Capture a parent sub-form state when a child validator depends on a sibling.
+- Convert `validateAsync`/`rxResource` to a tracked `query` plus
+  `cAsyncValidate`.
+- Convert `submission.action` to a tracked `mutation` plus `insertFormSubmit`.
+- Represent validation and submit failures with `craftException`.
+- Do not generate `makeFormTreeInsert` solely to migrate a form.
+
+### Services and dependency injection
+
+- Author application/domain services with `craftService`.
+- Adapt Angular, framework, and third-party tokens once with `toCraftService`.
+- Use the generated `X()` helper in components and `yield* X(...)` in generators.
+- Use `CraftRouter` directly instead of wrapping Angular Router.
+- Prefer `scope: 'function'` for a dependency used by one function and
+  `scope: 'toProvide'` for feature-owned services.
+- Place `provideX(...)` near the route or feature owning the instance.
+- Resolve every generated `CRAFT_IMPLEMENTATION_REQUIRED` companion.
+- Wrap dependent primitives in `yield* track(...)`.
+- Use `query` for reads and `mutation` for writes. Keep mutations with the
+  lifecycle owner when moving subscription callbacks would alter semantics.
+
+### Routes
+
+- Complete unresolved guards, redirects, lazy collections, inherited
+  providers, and dynamic route diagnostics manually.
+- Keep `componentDeps` and file-level `ValidateCascadeRoutesFile` or
+  `RouteCheckedDI` checks.
+- Prefer provider names and `ProvidedValues = never` after direct Angular DI is
+  removed.
+- Run ESLint fixes to regenerate `GenDeps_*` aliases after dependency changes.
+
+## Verification Checklist
+
+- No unreviewed migration diagnostics or migration marker comments remain.
+- No new direct Angular `inject(...)` or application `@Injectable` service was
+  introduced.
+- Signal Forms validate conditional and asynchronous fields correctly.
+- Submit success, submit errors, navigation, and store cleanup work.
+- HTTP mutations retain their intended callback and lifecycle behavior.
+- Route pending/error UI and exception exhaustiveness compile.
+- Targeted regression tests cover semantic rewrites.
+- Lint, type-check, architecture tests, tests, and production build all pass.
+
+If a diagnostic requires a business decision, stop before guessing and present
+the exact file, diagnostic, available options, and behavioral tradeoff.

package/skills/translate-spec-to-craft-ts/SKILL.md

@@ -0,0 +1,86 @@
+---
+name: translate-spec-to-craft-ts
+description: Translate functional specifications, user stories, page requirements, CRUD flows, list/detail screens, filters, pagination, bulk actions, optimistic updates, forms, and Angular feature-store architecture into @craft-ts/core primitives, insertions, store utilities, and source helpers. Use when a request asks which craft-ts utility to choose, or when wording such as "afficher", "liste", "detail", "supprimer", "selection multiple", "pagination", "filtre URL", "formulaire", "recharger en cas d'erreur", or "feature store" must be mapped to `query`, `mutation`, `state`, `queryParams`, `craft*`, form helpers, or entity helpers.
+---
+
+# Translate Spec To Ng Craft
+
+## Objective
+
+Translate business wording into concrete `@craft-ts/core` APIs and default compositions.
+Prioritize documented public APIs from the installed `@craft-ts/core` package and
+the published docs (MCP `search_documentation`, or https://ng-angular-stack.github.io/craft/llms.txt).
+
+## Workflow
+
+1. Decompose the spec into:
+   - remote reads
+   - remote writes
+   - local UI state
+   - URL state
+   - events and triggers
+   - forms and validation
+   - store boundaries and dependency injection
+2. Read [references/lexical-map.md](references/lexical-map.md) first.
+3. Read [references/pattern-recipes.md](references/pattern-recipes.md) when the spec combines several concerns or asks for defaults.
+4. Read [references/project-index.md](references/project-index.md) when examples or exact local paths are needed.
+5. Return a concrete mapping, not a generic architecture overview.
+
+## Decision Rules
+
+- Match server reads to `query`.
+- Match server writes to `mutation`.
+- Match generic asynchronous client tasks to `asyncProcess`.
+- Match local UI-only state to `state`.
+- Match URL-backed state to `queryParams`.
+- Match reusable, page-level, or global store requirements to `craft` plus `craft*` helpers.
+- Match event buses, resets, refreshes, and hidden triggers to `source$` and `on$`.
+- Match list collection semantics to `insertEntities` and the entity helpers when the spec explicitly talks about add, remove, update, upsert, replace, or clear.
+- Match nested sub-state behavior to `insertSelect`.
+- Match forms to `insertForm`, `insertSelectFormTree`, `insertFormAttributes`, and `insertFormSubmit`.
+- Treat `computedSource`, `toSource`, `signalSource`, `linkedSource`, `resourceById`, `toInject`, and other infra helpers as advanced choices. Do not choose them first unless the spec is about plumbing.
+
+## Default Heuristics
+
+- A primitive accepts ONE insertion. When composing 2+ insertions on the same primitive, use the universal `craftPipe` with an explicit context: `primitive(config, (context) => craftPipe(context, insertion1, insertion2))`. Never generate the removed variadic form `primitive(config, insertion1, insertion2)`. The same form applies to the nested insertions of `insertSelect`: `insertSelect('grid', (gridContext) => craftPipe(gridContext, ...))`. Exception: the form-tree helpers stay variadic.
+- When a mutation affects data already visible in a `query`, add `insertReactOnMutation` on the `query`.
+- When the optimistic path is obvious, prefer `optimisticPatch` for shallow field edits and `optimisticUpdate` for array or structural changes.
+- When using optimistic update, enable `reload: { onMutationError: true }` by default unless the spec forbids a refetch.
+- When optimistic deletion can empty the current page, consider a second `insertReactOnMutation(..., { reload: { onMutationResolved: true } })`.
+- When the spec mentions pagination or page transitions, consider `identifier` on the `query` and `insertPaginationPlaceholderData`.
+- When the spec mentions remembered filters, remembered results, refresh survival, or lightweight cache, consider `insertLocalStoragePersister`.
+- When the spec mentions parent-provided values or route or context values that are not URL query params, consider `craftInputs`.
+- When the spec mentions Angular services or a facade over a service, consider `craftInject` or `injectService`.
+
+## Output Contract
+
+Always structure the answer as:
+
+1. `Spec fragment -> utility`
+2. `Recommended composition`
+3. `Default behaviors`
+4. `Baseline helper already covering this` — the existing architecture-suite helper (`assertMutationHasReactOn`, `assertHttpEndpointUnique`, `assertCraftUnique`, `assertPersistedPrimitiveHasUnique`, `assertInsertSelectUnique`, `assertInteractiveElementNamed`, `assertRouteDiProofs`, …). This is not a new `it()`. Do not add an architecture rule for the feature.
+5. `Open questions or assumptions`
+
+Propose a **new** custom architecture rule only when the spec states a product invariant the baseline helpers do not cover (this feature must not depend on that one). Then load `craft-ts-architecture-tests`.
+
+Name the concrete public APIs exactly as exported by the library.
+When the spec implies a helper method, name it too: `removeOne`, `removeMany`, `updateOne`, `upsertMany`, `cRequired`, `cMinLength`, and similar helpers.
+
+## Example Mappings
+
+Spec: `Creer une page qui affiche une liste d'utilisateurs.`
+Mapping: `query` for remote list loading. Add `queryParams` only if pagination, filters, sort, or shareable URL state are part of the spec.
+
+Spec: `Creer une page qui affiche une liste d'utilisateurs. On peut supprimer un utilisateur via un bouton, ou en selectionner plusieurs pour en supprimer plusieurs.`
+Mapping: `query` for the list, one `mutation` for single delete, one `mutation` for bulk delete, one selection `state` or `craftState` for selected ids, and `insertReactOnMutation` on the `query` with optimistic removal plus `reload.onMutationError = true`. Use `removeOne` and `removeMany` for the optimistic transforms.
+Baseline helper already covering this: `assertMutationHasReactOn` (and `assertHttpEndpointUnique` if the list HTTP is owned once). Do not add an architecture rule for the feature.
+
+Spec: `Creer une page de recherche avec filtres dans l'URL et pagination sans flicker.`
+Mapping: `queryParams` for filter and pagination state, `query` for results, `insertPaginationPlaceholderData` to keep previous page data visible during transitions, `craftSetAllQueriesParamsStandalone` if the page must generate URLs outside injection context.
+
+## References
+
+- Read [references/lexical-map.md](references/lexical-map.md) for the lexical mapping.
+- Read [references/pattern-recipes.md](references/pattern-recipes.md) for default compositions.
+- Read [references/project-index.md](references/project-index.md) for the local source material to consult.

package/skills/translate-spec-to-craft-ts/references/lexical-map.md

@@ -0,0 +1,322 @@
+# Lexical Map
+
+## Read This First
+
+Use this file to translate product wording into concrete public APIs.
+Prefer the documented APIs first. Use the advanced exports only when the request is explicitly about plumbing, source wiring, or custom infrastructure.
+
+## Primary Primitives
+
+### `query`
+
+Match: `afficher`, `liste`, `tableau`, `detail`, `charger`, `recuperer`, `fetch`, `read`, `dashboard`, `feed`, `resultats`, `historique`, `stats`, `donnees serveur`, `recharger`, `rafraichir`.
+Pair with: `queryParams`, `insertReactOnMutation`, `insertPaginationPlaceholderData`, `insertLocalStoragePersister`, `craftQuery`.
+Default: Use `params` for reactive inputs, `method` for explicit trigger flows, `identifier` for pagination or parallel instances, and `preservePreviousValue` or placeholder strategies when flicker matters.
+
+### `mutation`
+
+Match: `creer`, `ajouter`, `enregistrer`, `modifier`, `mettre a jour`, `editer`, `patcher`, `supprimer`, `archiver`, `activer`, `desactiver`, `publier`, `bulk action`, `submit`, `confirmer`.
+Pair with: `insertReactOnMutation`, `insertFormSubmit`, `craftMutations`, `query`.
+Default: Create one mutation per server intent. Add `identifier` when row-level actions need independent loading states or cancellation semantics.
+
+### `asyncProcess`
+
+Match: `debounce`, `temporiser`, `retarder`, `valider en asynchrone`, `autosave`, `partager`, `clipboard`, `native API`, `background task`, `processus asynchrone`, `polling`.
+Pair with: `source$`, `afterRecomputation`, `craftAsyncProcesses`.
+Default: Choose this when the flow is asynchronous but is not the canonical server read cache and is not a write that should drive query synchronization.
+
+### `state`
+
+Match: `etat local`, `selection`, `toggle`, `ouvert`, `ferme`, `modal`, `onglet actif`, `draft`, `brouillon`, `checkbox`, `expanded`, `wizard step`, `current tab`, `UI state`.
+Pair with: `insertSelect`, `insertEntities`, `insertForm`, `craftState`.
+Default: Keep the state granular. Use it for client-only state and view state that should not live in the URL.
+
+### `queryParams`
+
+Match: `URL`, `query string`, `search params`, `filtre URL`, `pagination URL`, `tri dans l'URL`, `onglet partageable`, `deep link`, `etat partageable`, `back-forward`.
+Pair with: `query`, `craftQueryParams`, `craftQueryParams`, `craftSetAllQueriesParamsStandalone`.
+Default: Split URL concerns by group when useful. Put `page`, `pageSize`, `sort`, `search`, `filters`, `tab`, and similar shareable state here.
+
+### `source$`
+
+Match: `trigger`, `refresh`, `reset`, `bus evenementiel`, `broadcast`, `declencher`, `signal d'action`, `event stream`, `cross feature trigger`.
+Pair with: `on$`, `afterRecomputation`, `craftSources`.
+Default: Choose this when the spec describes an event, not a persistent state.
+
+### `on$`
+
+Match: `quand X arrive alors`, `react to`, `reset on`, `sync on`, `internal reaction`, `hidden binding`, `do not expose this method`.
+Pair with: `source$`, `state`, `mutation`, `asyncProcess`, `injectService`.
+Default: Use this for hidden reactive wiring that should run from a source but should not become part of the public API.
+
+### `injectService`
+
+Match: `facade`, `wrapper de service`, `exposer une petite API`, `renommer des methodes`, `derive from service signals`, `hide imperative router/service API`.
+Pair with: `on$`, `computed`, `craftInject`.
+Default: Choose this outside store composition when the user wants a smaller typed service-facing API.
+
+## Store Composition
+
+### `craft`
+
+Match: `feature store`, `page store`, `global store`, `store reutilisable`, `compose store`, `DI`, `providedIn`, `scope`, `reusable state module`.
+Pair with: `craftState`, `craftQuery`, `craftMutations`, `craftSources`, `craftInputs`, `craftQueryParams`, `craftQueryParams`, `craftInject`, `craftComputedStates`, `craftAsyncProcesses`.
+Default: Use `providedIn: 'feature'` for page or route scoped logic and `providedIn: 'root'` for global shared logic.
+
+### `craftState`
+
+Match: `etat local dans le store`, `selection store`, `modal store`, `draft store`, `store-owned UI state`.
+Pair with: `state`, `on$`.
+Default: Use when the state belongs inside a `craft` store and should be exposed as store entries and prefixed methods.
+
+### `craftQuery`
+
+Match: `requete dans le store`, `server state in store`, `cached resource in feature store`, `page query`.
+Pair with: `query`, `craftInputs`, `craftInject`, `craftQueryParams`, `insertReactOnMutation`.
+Default: Use when a `query` belongs inside a composed store boundary.
+
+### `craftMutations`
+
+Match: `actions serveur du store`, `store mutations`, `CRUD actions grouped in store`, `row actions in store`.
+Pair with: `mutation`, `craftQuery`, `insertReactOnMutation`.
+Default: Group server write actions here so the store gets prefixed trigger methods and typed state access.
+
+### `craftAsyncProcesses`
+
+Match: `async workflow in store`, `debounced action in store`, `delayed delete`, `background task in store`.
+Pair with: `asyncProcess`, `craftSources`.
+Default: Use when async client tasks belong to a `craft` store but are not the primary server-read/write state.
+
+### `craftSources`
+
+Match: `reset event`, `refresh event`, `select event`, `open modal event`, `trigger inside store`.
+Pair with: `source$`, `on$`, `afterRecomputation`.
+Default: Use this to define event channels inside a store and to auto-generate `emit*`, `set*`, or `next*` methods.
+
+### `craftInputs`
+
+Match: `parent provides id`, `route provides id`, `component input`, `external signal`, `context value`, `page receives userId`.
+Pair with: `craftQuery`, `craftState`, `craftMutations`.
+Default: Use this instead of `queryParams` when the value does not belong in the URL.
+
+### `craftQueryParams`
+
+Match: `one query param group in store`, `pagination in store`, `filters in store`, `search params in store`.
+Pair with: `queryParams`, `craftQuery`, `craftSetAllQueriesParamsStandalone`.
+Default: Use when one named query-params group should live inside a `craft` store.
+
+### `craftQueryParams`
+
+Match: `several URL state groups`, `pagination + filters + active tab`, `multiple query param groups`.
+Pair with: `queryParams`, `craftSetAllQueriesParamsStandalone`.
+Default: Use when the store needs several named query-params groups.
+
+### `craftComputedStates`
+
+Match: `derived store data`, `isAllSelected`, `count`, `filtered count`, `UI flags`, `aggregation`, `composed loading state`.
+Pair with: `computed`, `craftState`, `craftQuery`.
+Default: Use for derived store-level signals instead of duplicating state.
+
+### `craftInject`
+
+Match: `inject ApiService`, `inject Router`, `inject HttpClient`, `inject token`, `service dependency in store`.
+Pair with: `craft`, `craftQuery`, `craftMutations`.
+Default: Use inside `craft` when store factories need Angular services or tokens.
+
+### `craftSetAllQueriesParamsStandalone`
+
+Match: `generate URL`, `router navigate queryParams`, `shareable link`, `build full query string outside injection context`.
+Pair with: `craftQueryParams`, `craftQueryParams`.
+Default: Use when the spec mentions programmatic navigation or link generation from the current query-params model.
+
+## Insertions
+
+Every primitive accepts **one** insertion. To attach several insertions,
+compose them with the universal `craftPipe`, passing the context explicitly:
+`primitive(config, (context) => craftPipe(context, insertion1, insertion2))`.
+Members run left to right, previous outputs are visible on
+`context.insertions`. Generated code MUST use this form — the variadic
+`primitive(config, insertion1, insertion2, ...)` signature no longer exists.
+The same applies to the nested insertions of `insertSelect`
+(`insertSelect('grid', (gridContext) => craftPipe(gridContext, ...))`).
+Exception: the form-tree helpers
+(`insertForm`/`insertSelectFormTree`/`makeFormTreeInsert`) stay variadic.
+
+### `craftPipe`
+
+Match: `plusieurs insertions`, `combine insertions`, `persister + optimistic update`, `several reactions on one query`.
+Pair with: every insertion below.
+Default: Wrap 2+ insertions of one primitive in `(context) => craftPipe(context, ...)`; a single insertion is passed directly without a pipe.
+
+### `insertReactOnMutation`
+
+Match: `optimistic update`, `keep list in sync`, `instant UI update`, `cache invalidation`, `reload on failure`, `patch visible data after mutation`, `remove row immediately`, `sync query with mutation`.
+Pair with: `query`, `mutation`, `removeOne`, `removeMany`, `updateOne`, `setOne`.
+Default: Put this on the `query`, not on the mutation. Use `optimisticPatch` for shallow fields, `optimisticUpdate` for arrays and structural changes, and `reload.onMutationError: true` by default when optimistic behavior is enabled.
+
+### `insertPaginationPlaceholderData`
+
+Match: `pagination without flicker`, `keep previous page visible`, `placeholder data`, `smooth page transition`.
+Pair with: `query`, `queryParams`.
+Default: Prefer this when pagination is user-visible and loading empty states would degrade the UX.
+
+### `insertLocalStoragePersister`
+
+Match: `remember filters`, `remember last data`, `persist cache`, `survive refresh`, `restore session`, `client cache`.
+Pair with: `query`, `state`, `mutation`, `asyncProcess`.
+Default: This is the public insertion name even if some docs page titles still say `insertLocalStorage`.
+
+### `insertEntities`
+
+Match: `entity collection`, `array of entities`, `manage list items by id`, `adapter-like methods`, `bulk array operations`, `collection helper methods`.
+Pair with: `state`, `query`, `queryParams`, entity helpers such as `removeOne`, `updateMany`, and `upsertOne`.
+Default: Use this when the spec repeatedly talks about item-level collection operations and the collection should expose reusable typed methods.
+
+### `insertSelect`
+
+Match: `nested state`, `row-level behavior`, `cell`, `grid`, `sub-tree`, `select nested object`, `per-item nested methods`.
+Pair with: `state`, `craftPipe`.
+Default: Use this for object or array sub-state behavior. It accepts ONE nested insertion; for several, use `insertSelect('name', (selectedContext) => craftPipe(selectedContext, ...))`.
+
+### `insertNoopTypingAnchor`
+
+Match: `form tree typing issue`.
+Pair with: `insertSelectFormTree`.
+Default: Use only as a typing anchor for the form-tree helpers. No longer needed with `insertSelect` (craftPipe preserves nested contextual typing).
+
+## Entity Helpers
+
+| Helper | Match |
+| --- | --- |
+| `addOne` | `add one`, `append`, `insert item`, `push row`, `create local row` |
+| `addMany` | `add several`, `append many`, `bulk insert local items` |
+| `setOne` | `replace one by id`, `sync one entity`, `override row` |
+| `setMany` | `replace several by id`, `merge incoming entities` |
+| `setAll` | `replace whole list`, `reset collection from server` |
+| `updateOne` | `partial update one`, `patch one row`, `edit one entity` |
+| `updateMany` | `partial update several`, `bulk patch` |
+| `upsertOne` | `create or update one`, `insert if missing` |
+| `upsertMany` | `create or update several`, `merge or append` |
+| `removeOne` | `delete one`, `remove one`, `remove row`, `optimistic single delete` |
+| `removeMany` | `delete several`, `bulk delete`, `remove selected`, `optimistic bulk delete` |
+| `removeAll` | `clear list`, `empty collection`, `reset all` |
+| `map` | `transform all`, `recompute whole list`, `toggle all`, `mark all` |
+| `mapOne` | `transform one by id`, `toggle one`, `edit one with custom mapper` |
+| `computedTotal` | `count`, `total`, `number of items` |
+| `computedIds` | `all ids`, `selected ids`, `row ids` |
+
+## Forms
+
+### `insertForm`
+
+Match: `form`, `inline edit`, `edition`, `create form`, `submit form`, `field state`.
+Pair with: `insertSelectFormTree`, `insertFormAttributes`, `insertFormSubmit`.
+Default: Use this when the spec explicitly talks about a form experience. The form API is currently early-stage, so keep implementations close to the documented examples.
+
+### `insertSelectFormTree`
+
+Match: `field`, `field subtree`, `name input`, `email input`, `nested form field`.
+Pair with: `insertForm`, `insertNoopTypingAnchor`, `insertFormAttributes`.
+Default: Use this to target form fields or nested form paths.
+
+### `insertFormAttributes`
+
+Match: `validation rules`, `disabled field`, `hidden field`, `field attributes`, `visible exceptions`.
+Pair with: `insertSelectFormTree`, validators such as `cRequired` and `cEmail`.
+Default: Put synchronous validators and field presentation rules here.
+
+### `insertFormSubmit`
+
+Match: `submit form`, `save form`, `form -> mutation`, `validated submit`, `submitting state`.
+Pair with: `mutation`, `insertForm`.
+Default: Connect form submission to the mutation that owns the server write intent.
+
+### Validators
+
+| Validator | Match |
+| --- | --- |
+| `cRequired` | `required`, `mandatory`, `must not be empty` |
+| `cEmail` | `email`, `must be a valid email` |
+| `cMin` | `minimum numeric value`, `at least N`, `lower bound` |
+| `cMax` | `maximum numeric value`, `at most N`, `upper bound` |
+| `cMinLength` | `minimum length`, `at least N characters` |
+| `cMaxLength` | `maximum length`, `no more than N characters` |
+| `cPattern` | `regex`, `format`, `must match pattern` |
+| `cValidate` | `custom validator`, `domain rule`, `business validation` |
+| `cAsyncValidate` | `async validator`, `server-side validation`, `check availability` |
+
+## Event And Source Bridges
+
+### `afterRecomputation`
+
+Match: `auto-trigger from source`, `map source payload before query`, `hidden transformed trigger`, `source-based execution`.
+Pair with: `source$`, `signalSource`, `query`, `mutation`, `asyncProcess`.
+Default: Use this when the spec is about event-driven execution and the payload needs a transformation before reaching the resource.
+
+### `fromEventToSource$`
+
+Match: `DOM event to source`, `click stream`, `input stream`, `scroll source`, `window resize source`.
+Pair with: `on$`, `state`, `asyncProcess`.
+Default: Prefer this when the event must become a readonly source with signal access to the last emitted value.
+
+### `sourceFromEvent`
+
+Match: `DOM event to state reducer`, `event mapper`, `legacy event bridge`.
+Pair with: `state`.
+Default: Choose this only if the reducer-style event mapping fits better than `fromEventToSource$`.
+
+### `toSource`
+
+Match: `signal to source`, `route signal to event pipeline`, `form signal to auto query`, `debounced signal bridge`.
+Pair with: `afterRecomputation`, `query`, `mutation`, `asyncProcess`.
+Default: Use only when the starting point is already a signal and the next stage expects a source.
+
+### `computedSource`
+
+Match: `source to source transformation`, `extract field from source`, `format source payload`, `compose source pipeline`.
+Pair with: `afterRecomputation`, `signalSource`.
+Default: Use when the spec is explicit about source transformation pipelines.
+
+### `signalSource`
+
+Match: `source with signal shape`, `event source with set`, `lazy event signal`, `source semantics with preserveLastValue`.
+Pair with: `craftSources`, `afterRecomputation`, `linkedSource`.
+Default: Choose this only when the implementation specifically wants signal-like source behavior rather than `source$`.
+
+### `linkedSource`
+
+Match: `derived signalSource`, `preserve last computed source value`, `source derivation with writable source semantics`.
+Pair with: `signalSource`.
+Default: Keep this for advanced source composition.
+
+### `stackedSource`
+
+Match: `collect several source payloads`, `stack events in same cycle`, `aggregate source emissions`.
+Pair with: advanced source composition only.
+Default: Treat this as infrastructure-level. Do not infer it from ordinary product wording.
+
+## Persistence And Infra
+
+### `GlobalPersisterHandlerService`
+
+Match: `logout clears cache`, `switch account`, `privacy wipe`, `force full cache reset`, `clear persisted data`.
+Pair with: `insertLocalStoragePersister`.
+Default: Use this when the requirement explicitly asks to clear all craft-ts persisted cache.
+
+### `localStoragePersister`
+
+Match: `custom persister factory`, `storage backend`, `manual persistence infrastructure`.
+Pair with: `insertLocalStoragePersister`.
+Default: Prefer the insertion for product specs. Use this lower-level factory only for custom persistence infrastructure.
+
+### `resourceById`
+
+Match: `low-level resource registry`, `resources keyed by identifier`, `manual per-id cache infrastructure`, `bind one resource-by-id to another`.
+Pair with: `query.identifier`, `mutation.identifier`.
+Default: Prefer ordinary `query` and `mutation` with `identifier` until the request explicitly asks for custom resource infrastructure.
+
+### `toInject`
+
+Match: `bind external signals into service entries`, `service ...Entry wiring`, `service adapter for signals`.
+Pair with: Angular services exposing writable `...Entry` signals.
+Default: Use only when the service API already follows the `...Entry` convention and the request is about service binding infrastructure.

package/skills/translate-spec-to-craft-ts/references/pattern-recipes.md

@@ -0,0 +1,123 @@
+# Pattern Recipes
+
+> Composition rule: a primitive takes ONE insertion. When a recipe below lists
+> several insertions for the same primitive, compose them with `craftPipe`,
+> passing the context explicitly, e.g.
+> `query(name, cfg, (context) => craftPipe(context, insertLocalStoragePersister(...), insertReactOnMutation(...), insertReactOnMutation(...)))`.
+> The same form works for the nested insertions of `insertSelect`:
+> `insertSelect('grid', (gridContext) => craftPipe(gridContext, ...))`.
+> Exception: the form-tree helpers stay variadic.
+
+## Read-Only List Page
+
+Use:
+- `query` for the remote collection.
+- `queryParams` when pagination, sort, search, filters, or tabs live in the URL.
+- `insertPaginationPlaceholderData` when page transitions should keep old data visible.
+- `insertLocalStoragePersister` when results or params should survive a refresh.
+
+Default policy:
+- Put `page`, `pageSize`, `search`, `sort`, and filters in `queryParams`.
+- Use `identifier` on the `query` when page or filter combinations should keep independent cached instances.
+- Prefer `currentPageData()` and `currentPageStatus()` when using pagination placeholders.
+
+## Detail Page
+
+Use:
+- `query` for the entity detail.
+- `mutation` for update or delete intents.
+- `insertReactOnMutation` on the detail `query` when edits should be reflected immediately.
+- `craftInputs` when the entity id comes from component or route context but does not belong in query params.
+
+Default policy:
+- Keep one detail `query` per detail intent.
+- Use `optimisticPatch` when a shallow field like `name`, `status`, or `email` changes.
+
+## List Page With Single Delete And Bulk Delete
+
+Use:
+- one `query` for the list.
+- one `mutation` for single delete.
+- one `mutation` for bulk delete.
+- one selection `state` or `craftState` holding selected ids.
+- `insertReactOnMutation` on the list `query` for each mutation.
+
+Default policy:
+- For single delete, prefer `optimisticUpdate` with `removeOne`.
+- For bulk delete, prefer `optimisticUpdate` with `removeMany`.
+- Enable `reload: { onMutationError: true }` on both optimistic reactions by default.
+- Add a second `insertReactOnMutation(..., { reload: { onMutationResolved: true } })` when optimistic delete can empty the current page and the next page should be reloaded; compose all the reactions on the list `query` with `(context) => craftPipe(context, ...)`.
+- Add `mutation.identifier` when row-level loading or cancel buttons matter.
+
+## Inline Edit Or Create Form
+
+Use:
+- `state` plus `insertForm`.
+- `insertSelectFormTree` to target the edited fields.
+- `insertFormAttributes` for validators, disable rules, visibility, or field metadata.
+- `mutation` for submit.
+- `insertFormSubmit(mutationRef)` to connect the form to the mutation.
+- `insertReactOnMutation` on visible queries when the updated entity is already displayed elsewhere.
+
+Default policy:
+- Put synchronous business validation in form validators first.
+- Use `cRequired`, `cEmail`, `cMinLength`, and the other validator helpers before writing custom validators.
+- Keep one mutation per submit intent, not one mutation per field.
+
+## Search Page With URL Filters
+
+Use:
+- `queryParams` or `craftQueryParams` for the filters.
+- `query` for the result list.
+- `craftSetAllQueriesParamsStandalone` when links or router navigation must be generated outside injection context.
+
+Default policy:
+- Reset `page` to `1` when a search term or filter changes.
+- Keep URL parsing and serialization explicit for each field.
+- Choose `craftQueryParams` when the page has several named query-params groups.
+
+## Feature Or Page Store
+
+Use:
+- `craft` as the boundary.
+- `craftInject` for services and tokens.
+- `craftInputs` for non-URL external values.
+- `craftQueryParams` or `craftQueryParams` for URL-backed state.
+- `craftSources` for reset, refresh, and cross-entry triggers.
+- `craftQuery`, `craftMutations`, `craftState`, and `craftComputedStates` for the actual feature logic.
+
+Default policy:
+- Choose `providedIn: 'feature'` for page or route scoped stores.
+- Choose `providedIn: 'root'` for global shared stores.
+- Keep remote state in `craftQuery` and `craftMutations`, not in ad-hoc service fields.
+
+## Smaller Facade Over An Angular Service
+
+Use:
+- `injectService` when no `craft` store is needed.
+- `craftInject` when the service participates in a store composition.
+
+Default policy:
+- Expose only the service surface the feature actually needs.
+- Hide reactive bindings with `on$` when they should not become part of the public API.
+
+## Event-Driven Execution
+
+Use:
+- `source$` or `signalSource` for the trigger.
+- `afterRecomputation` when the trigger payload needs adaptation.
+- source-based `query`, `mutation`, or `asyncProcess` when the resource should run automatically on emission.
+
+Default policy:
+- Prefer `source$` for ordinary product flows.
+- Escalate to `toSource`, `computedSource`, or `linkedSource` only when the inputs are already signals or the request is explicitly about source pipelines.
+
+## Persistence And Cache Reset
+
+Use:
+- `insertLocalStoragePersister` when a specific state or query should survive refreshes.
+- `GlobalPersisterHandlerService` when the requirement says logout, account switch, or privacy reset must clear persisted cache.
+
+Default policy:
+- Persist only the state that improves UX.
+- Clear all persisted cache on user boundary changes when the stored data becomes invalid or sensitive.