@aurorajs.dev/catalyst-cli 1.0.0

package/dist/templates/frontend/application/.claude/skills/catalyst-component-story-composer/SKILL.md

@@ -0,0 +1,203 @@
+---
+name: catalyst-component-story-composer
+description: >
+  Author and maintain `*.stories.ts` files for `@aurora/components` following a single procedure
+  that EXTRACTS mechanical facts from the component source and DEMANDS semantic intent from the
+  developer. Trigger: When adding, extending, or enriching `@aurora/components/` with a new
+  exported component; when editing a component whose inputs/outputs/behavior changed and the story
+  is now stale; when batch-documenting components in Framework mode — EVEN IF the user doesn't use
+  the word "story" (e.g. "extend @aurora/components with HlmToggle", "add this component to the
+  platform", "publish X into @aurora"). Must also fire on explicit phrases: "document X",
+  "generate story for X", "create a story for X", "update X's story". For CONSUMING existing
+  stories while composing screens, use `catalyst-component-catalog` instead.
+license: MIT
+metadata:
+  author: aurora
+  version: '2.1'
+---
+
+## When to Use
+
+- Adding a new `@aurora/components/<area>/<name>` component and writing its colocated story
+- Editing a component whose `inputs`/`outputs`/behavior changed and whose story is now stale
+- Asked to "document X", "generate story for X", "create a story for X", "update X's story"
+- Batch-documenting the catalog (e.g. "document all `data-table/components/`")
+- Working in **Framework mode** (building the platform), not Solution mode
+
+**Skip this skill** when consuming an existing component in a screen — that is consumption, covered by `catalyst-component-catalog`.
+
+## Core Principle
+
+A good story has two kinds of content:
+
+- **Mechanical facts** — selector, class name, input types, output shapes. The `.component.ts` already contains them. The skill READS them; the developer does NOT retype them.
+- **Semantic intent** — when to use, what sibling it competes with, which state matters enough to show as a variant, what a variant demonstrates in prose. The code CANNOT know these. The skill DEMANDS them from the developer.
+
+The skill follows the **same procedure regardless of the developer's clarity**. What changes is the shape of the dialogue, not the script:
+
+- **Clear developer**: answers the semantic questions in one pass → skill writes the story.
+- **Unclear developer**: each semantic question triggers a brief discussion. The skill proposes options, asks clarifying follow-ups, and pushes back on "skip it" until the skip is justified. Only then writes.
+
+Never skip a semantic question silently. If the final answer is "no applicable value", it is recorded as a justified omission (e.g. `parameters.aurora` is not declared because no sibling exists to disambiguate against).
+
+## Runtime Status — Storybook is NOT installed
+
+This project treats `*.stories.ts` files as **structured TypeScript documentation**, not as input to a running Storybook dev server. Authoring implications:
+
+1. Import `Meta` / `StoryObj` from the **local shim** at `frontend/src/@aurora/story.types` — NOT from `@storybook/angular`.
+2. **Never** declare a `play` function. Describe interactive behavior in prose inside `parameters.docs.description.story`.
+3. **Never** import from `storybook/test` or use `fn()` in `args`. Outputs go in `argTypes` with `action: '<name>'`.
+
+Full rationale in `openspec/changes/adopt-storybook-component-catalog/` (proposal + design > scope reduction 2026-04-20). The CSF3 shape is preserved so a future reintroduction of Storybook is additive.
+
+## The Procedure
+
+### Phase A — Extract mechanical facts (no questions to dev)
+
+#### A.1 Read the component source
+
+`Read` `frontend/src/@aurora/components/<area>/<name>.component.ts`. Extract verbatim:
+
+- Class name (e.g. `TableSearchComponent`)
+- `@Component` selector
+- Every `readonly foo = input<T>(...)` / `input.required<T>(...)` — name, type, default
+- Every `readonly bar = output<T>(...)` — name, payload type
+- The `imports` array — signal of runtime dependencies
+- Any context injection (`injectFlexRenderContext`, `inject(Table<T>)`, required `TemplateRef` inputs) — marks the component as **context-dependent**
+
+#### A.2 Derive `Meta.title`
+
+Rule: `@aurora/<area>/<name>` where `<area>` is the path between `components/` and the file, and `<name>` is the kebab-cased component name without `.component.ts`.
+
+| Component path | Title |
+|---|---|
+| `frontend/src/@aurora/components/breadcrumb/breadcrumb.component.ts` | `@aurora/components/breadcrumb` |
+| `frontend/src/@aurora/components/data-table/components/table-search.component.ts` | `@aurora/components/data-table/table-search` |
+
+#### A.3 Calculate the shim import path
+
+Count directories between the story file and `frontend/src/@aurora/`; emit that many `../` + `story.types`.
+
+| Story file | Import |
+|---|---|
+| `frontend/src/@aurora/components/breadcrumb/breadcrumb.stories.ts` | `'../../story.types'` |
+| `frontend/src/@aurora/components/data-table/components/table-search.stories.ts` | `'../../../story.types'` |
+
+#### A.4 Build `argTypes` and `args` from inputs
+
+For each input, emit an `argType` entry with `control` mapped from `T`:
+
+| Angular input `T` | `control` |
+|---|---|
+| `string` | `'text'` |
+| `number` | `{ type: 'number', min: 0, step: 1 }` (tune `step` for semantic values, e.g. ms → 100) |
+| `boolean` | `'boolean'` |
+| `'a' \| 'b' \| 'c'` | `{ type: 'select', options: ['a', 'b', 'c'] }` |
+| `T[]`, object, generic `T` | `'object'` |
+| `Date` | `'date'` |
+| `Signal<T>`, `WritableSignal<T>` | Unwrap to inner `T`, apply rules above |
+| `TemplateRef`, `Type<T>`, `Table<T>` | Do NOT expose as arg — marks context-dependence |
+
+Set each input's default in `args`. For `input.required<T>()` without a default, pick a representative value (`'Sample'`, `42`, `true`, first option of a union).
+
+#### A.5 Declare outputs with `action`
+
+For each `output<T>()`, add to `argTypes` with `action: '<outputName>'`. Do NOT add to `args` (no `fn()` — Storybook not installed).
+
+---
+
+### Phase B — Demand semantic intent (always asked; dialogue shape varies)
+
+Phase A produces a mechanical skeleton. Phase B fills in what the code cannot answer. The skill MUST ask every question below. If the developer's answer is unclear or "no sé", the skill discusses until a clear answer OR a justified skip is reached.
+
+#### B.1 Sibling disambiguation (drives `parameters.aurora`)
+
+1. `Glob frontend/src/@aurora/components/<area>/**/*.component.ts` — list siblings in the same area.
+2. **If ≥1 sibling exists:**
+   - Ask: _"This component shares `<area>` with `<sibling-list>`. Which one could a developer confuse with `<this>`, and why?"_
+   - If dev answers with a named sibling + reason → fill `parameters.aurora.whenNot` referencing that sibling by name.
+   - If dev says "ninguno se parece" → push back once: _"¿Aún si el nombre fuera ambiguo? ¿Alguien podría empezar por `<sibling>` y acabar cambiando a `<this>`?"_ If still no → justified skip, do not declare `parameters.aurora`.
+3. **If no siblings exist:**
+   - Do not ask. `parameters.aurora` is skipped by construction.
+
+#### B.2 Primary use case (`parameters.aurora.when`)
+
+Only ask if B.1 produced a `whenNot`. Otherwise skip (aurora metadata requires all three fields or none).
+
+- Ask: _"En una frase, ¿cuándo debería un desarrollador elegir este componente?"_
+- If vague ("para mostrar datos"): push back with _"¿Qué contexto concreto? ¿Qué problema resuelve que otro no?"_
+- If dev says "no sé": guide — _"Piensa en las últimas 3 pantallas donde lo usarías o lo has usado. ¿Qué tienen en común?"_ Extract the common thread.
+
+#### B.3 Non-trivial variant
+
+Ask regardless of B.1/B.2 outcomes. Every story MUST export at least `Default` + one meaningful variant.
+
+- Ask: _"Además de Default, nombra un estado que cambie cómo se comporta o se ve este componente: disabled, un valor edge, contenido traducido, algo largo/corto, loading, error..."_
+- If dev names one → use it.
+- If dev says "no sé": offer 2–3 options inferred from the code:
+  - An input with a literal-union type → variant for each option (pick one).
+  - A numeric input with a "significant" value (debounce, timeout, limit) → variant with a boundary value.
+  - Boolean input → variant with the opposite default.
+  - Transloco/string inputs → variant with translated content.
+- If dev rejects all options → push back: _"Si solo tuvieras Default, ¿qué información perdería alguien leyendo la story?"_ Use the answer.
+
+#### B.4 Variant description (`parameters.docs.description.story`)
+
+- Ask: _"Describe en una frase qué demuestra esta variante y por qué importa."_
+- If dev is terse ("muestra X") → propose a fuller version: _"¿Funciona algo así: 'Demuestra X cuando Y, útil para Z'?"_
+- If the component has interactive behavior, include in the prose what a `play` interaction WOULD assert when Storybook is reintroduced (this is the canonical record for now).
+
+#### B.5 Context-dependent confirmation
+
+Only triggered if Phase A.1 detected context injection (`injectFlexRenderContext`, required `Table<T>`, etc.).
+
+- Ask: _"Este componente necesita `<context>` para renderizar. ¿Escribo un proxy host que falsea ese contexto, o prefieres un TODO stub que queda pendiente?"_
+- If dev says proxy → emit a minimal host `@Component` inside the story file wrapping the target; document in `parameters.docs.description.component`.
+- If dev says TODO → emit a `Default` story with `// TODO: wire proxy host — see STORIES.md > Proxy Host Pattern` and leave `args` empty. FLAG to the user that the story is incomplete until the proxy is wired.
+
+---
+
+### Phase C — Produce + verify
+
+#### C.1 Write the file
+
+Path: replace `.component.ts` → `.stories.ts` next to the component. Shape per `STORIES.md`.
+
+#### C.2 Typecheck
+
+```
+pnpm --filter aurora-front exec tsc --noEmit -p tsconfig.app.json
+```
+
+MUST pass clean. Common failures:
+
+- Wrong shim depth (Phase A.3) → adjust `../` count.
+- Arg value doesn't match unwrapped input type → verify Signal unwrap (see `STORIES.md`).
+- Output declared in `args` instead of `argTypes.action` → move it.
+
+#### C.3 Report
+
+Summarize to the developer:
+- What was extracted (Phase A) and what was demanded (Phase B).
+- Any justified skips (e.g. "no `parameters.aurora` — no sibling to disambiguate").
+- File path written.
+- If Phase B.5 ended as a TODO stub, flag it.
+
+## Worked Example
+
+See `frontend/src/@aurora/components/data-table/components/table-search.stories.ts` — the seed. Traceable to the procedure:
+
+- **Phase A**: inputs `placeholder: string`, `debounce: number`, output `search: string` → `argTypes` with `'text'` + `{ type: 'number', step: 100 }` + `action: 'search'`.
+- **Phase B.1**: siblings include `table-filters.component.ts` → `whenNot` points to `TableFiltersComponent`.
+- **Phase B.2**: primary use case → "free-text search box that debounces user input and emits a single value...".
+- **Phase B.3**: variants chosen → `TranslatedPlaceholder` (Transloco content) and `FastDebounce` (`debounce: 50`, significant boundary).
+- **Phase B.4**: each variant has `parameters.docs.description.story` in prose, including what a future `play` interaction would assert.
+- **Phase B.5**: not triggered — no context injection.
+- **Phase C**: typechecks clean.
+
+## Related Skills
+
+- **`catalyst-component-catalog`** — sibling skill for **consuming** existing stories when composing screens. Fires in Solution mode; this one fires in Framework mode.
+- `transloco-i18n` — when your story demonstrates translated content.
+- `catalyst-data-table-management` — data-table family specifics.
+- `typescript` — strict patterns when refining a generated story.

package/dist/templates/frontend/application/.claude/skills/catalyst-component-story-composer/STORIES.md

@@ -0,0 +1,194 @@
+# Story Authoring Convention — `@aurora/components`
+
+This document is the single reference for humans **and** agents when writing a new `*.stories.ts`
+file under `frontend/src/@aurora/components/**`. Follow it exactly — the `catalyst-component-catalog`
+skill relies on these conventions to discover and interpret stories.
+
+## File Naming and Location
+
+- **Colocation (mandatory)**: the story lives next to the component.
+  Example: `frontend/src/@aurora/components/data-table/components/table-search.component.ts`
+  → `frontend/src/@aurora/components/data-table/components/table-search.stories.ts`.
+- **File name**: `<component-kebab-name>.stories.ts`. The base must match the `.component.ts`
+  sibling.
+- **No central `stories/` tree**: do not create a parallel hierarchy. Refactors must be able to move
+  a component and its story in a single diff.
+
+## Type Imports — local shim, not `@storybook/angular`
+
+Stories import `Meta<T>` and `StoryObj<T>` from the **local shim** at
+`frontend/src/@aurora/story.types.ts` — NOT from `@storybook/angular`. Storybook is not
+installed as a runtime in this project (see `catalyst-component-catalog/SKILL.md > Related
+Skills`); the shim provides the exact CSF3 shape so stories typecheck as structured
+documentation without a Storybook install. If/when Storybook is reintroduced, the shim is
+deleted and imports are redirected to `@storybook/angular`.
+
+## `Meta` Default Export
+
+Every story file MUST default-export a `Meta<TComponent>` object:
+
+```ts
+import type { Meta, StoryObj } from '../../../story.types'; // relative path to frontend/src/@aurora/story.types
+// ...adjust the number of `../` to reach `frontend/src/@aurora/story.types` from your story file.
+
+const meta: Meta<TableSearchComponent> = {
+  title: '@aurora/components/data-table/table-search',
+  component: TableSearchComponent,
+  tags: ['autodocs'],
+  argTypes: { ... },
+  args: { ... },
+  parameters: { aurora: { ... } }, // see "Aurora Semantic Metadata" below
+};
+
+export default meta;
+type Story = StoryObj<TableSearchComponent>;
+```
+
+### Title Path Format
+
+`@aurora/<area>/<name>` — where:
+
+- `<area>` is the folder segment(s) beneath `components/` (e.g. `components`, `data-table`,
+  `data-table/column-toggle`).
+- `<name>` is the kebab-cased component name.
+
+Good:
+
+- `@aurora/components/data-table/table-search`
+- `@aurora/components/data-table/column-toggle`
+
+Bad:
+
+- `Data Table / Search` (no namespace, not scannable)
+- `TableSearch` (missing area)
+
+### `component`
+
+Import the concrete component class. The catalog skill reads this to resolve the canonical import
+path — it is NOT optional.
+
+### `tags`
+
+Always include `['autodocs']` unless you have a concrete reason to opt out. Autodocs enables the
+Docs tab where `parameters.aurora` appears for AI consumption.
+
+### `argTypes` and `args`
+
+- Declare every meaningful `input()` / `output()` the component exposes.
+- Provide a `description` on each argType — this is the prop's AI-readable doc.
+- In `args`, set defaults that render the component in a sensible state.
+- For outputs (`@Output()` / `output()`), declare them in `argTypes` with `action: '<outputName>'`
+  (Storybook-compatible shorthand for action logging). Do NOT pass a mocked function in `args` —
+  `fn()` from `storybook/test` only exists when Storybook is installed, which is not the case here.
+
+## Aurora Semantic Metadata (OPTIONAL but strongly preferred)
+
+Declare on the `Meta.parameters` object:
+
+```ts
+parameters: {
+  aurora: {
+    category: 'data-table',
+    when: 'One sentence describing the primary use case.',
+    whenNot: 'One sentence describing when a different component fits better, naming that alternative.',
+  },
+},
+```
+
+Shape rules:
+
+- `category` — a coarse family grouping: `'data-table' | 'navigation' | 'form' | 'overlay' | ...`.
+  Pick from existing categories before inventing new ones.
+- `when` — the primary use case. One sentence. No "you can also..." laundry lists.
+- `whenNot` — a scenario where a different `@aurora/components` export is the better fit. Name that
+  alternative explicitly. This is what makes agent disambiguation work.
+- All three fields must be non-empty strings. No `null`, no `undefined`, no empty strings.
+
+Declare `parameters.aurora` whenever multiple `@aurora/components` could plausibly satisfy the same
+requirement, or whenever the component is near-trivial but has a specific preferred use-case. Do NOT
+declare it if every field would be a useless truism.
+
+## Minimum Required Story Exports
+
+Every `*.stories.ts` MUST export at least:
+
+1. A `Default: StoryObj<T>` variant — renders with the `args` from the Meta.
+2. One additional variant demonstrating a non-trivial state: a translated label, an edge-case
+   value, an interaction in-progress, a disabled state, etc.
+
+Interactive behavior (click, type, assert output emit) SHOULD be described in prose inside
+`parameters.docs.description.story` on the relevant variant. **Do NOT declare a `play` function**:
+`play` requires `storybook/test` utilities that only exist when Storybook is installed as a runtime
+(which is not the case in this project — see SKILL.md). When Storybook is reintroduced, `play`
+becomes the preferred way to encode these assertions; until then, descriptive prose is the
+canonical documentation.
+
+## Decorator Usage
+
+**Global decorators** (theme, Transloco, router, HTTP) would normally be registered in
+`.storybook/preview.ts`, but since Storybook is not installed in this project, per-story decorators
+are not wired to any runtime. Authors should still structure their stories as if these globals
+existed — when Storybook is reintroduced, the preview wiring is the only thing missing.
+
+**Per-story decorators** (when Storybook is present) only for:
+
+- Wrapping a composable or directive in a minimal host component (see "Proxy Host Pattern" below).
+- Overriding a provider value in a specific variant.
+- Adding layout context (e.g. a `matSidenavContainer` wrapper for sidenav stories).
+
+## Proxy Host Pattern (composables and directives)
+
+When the `@aurora/components` export is a composable (like `useBreadcrumbs()`) or a directive
+(no standalone component to instantiate), write a minimal host component inside the story file and
+use it as `Meta.component`:
+
+```ts
+@Component({
+  selector: 'aurora-use-breadcrumbs-host',
+  imports: [HlmBreadcrumbImports],
+  template: `...uses the composable/directive...`,
+})
+class UseBreadcrumbsHost {
+  readonly items = useBreadcrumbs([{ translation: 'navigation.Tags' }]);
+}
+
+const meta: Meta<UseBreadcrumbsHost> = {
+  title: '@aurora/components/breadcrumb/use-breadcrumbs',
+  component: UseBreadcrumbsHost,
+  ...
+};
+```
+
+The story title still follows `@aurora/<area>/<name>` — the `<name>` describes the composable, not
+the host.
+
+## Worked Example — `TableSearchComponent` (seed story)
+
+The canonical seed story lives at
+`frontend/src/@aurora/components/data-table/components/table-search.stories.ts`. It demonstrates:
+
+- Imports `Meta` and `StoryObj` from the local shim (`../../../story.types`), not `@storybook/angular`
+- Title format: `@aurora/components/data-table/table-search`
+- `argTypes` with descriptions on every input; the output `search` uses `action: 'search'`
+- `parameters.aurora` with `category: 'data-table'`, a concrete `when`, and a `whenNot` pointing to
+  `TableFiltersComponent` as the alternative for column-scoped filtering
+- Two additional variants: `TranslatedPlaceholder` (demonstrates a Transloco-sourced placeholder)
+  and `FastDebounce` (short debounce documented via `parameters.docs.description.story` — the
+  intended `play` interaction is described in prose, deferred to the day Storybook is reintroduced)
+
+Read it as the reference implementation before authoring a new story.
+
+## Checklist (agents: iterate on this before returning a story)
+
+- [ ] File lives next to the `.component.ts` sibling (same directory)
+- [ ] File name is `<component-kebab-name>.stories.ts`
+- [ ] Imports `Meta` / `StoryObj` from the local shim at `frontend/src/@aurora/story.types` (use the correct relative path from the story's location)
+- [ ] `Meta.title` follows `@aurora/<area>/<name>`
+- [ ] `Meta.component` imports the concrete class
+- [ ] `tags: ['autodocs']`
+- [ ] Every meaningful `input()` / `output()` has an `argType` with `description`
+- [ ] Outputs declared with `action: '<outputName>'`; no `fn()` in `args` (Storybook not installed)
+- [ ] At least one `Default` story and one non-trivial variant
+- [ ] `parameters.aurora.{category, when, whenNot}` declared whenever disambiguation value exists
+- [ ] Interactive behavior documented in `parameters.docs.description.story`; NO `play` function (Storybook not installed)
+- [ ] `pnpm --filter aurora-front exec tsc --noEmit -p tsconfig.app.json` passes (story typechecks against the shim)

package/dist/templates/frontend/application/.claude/skills/catalyst-data-layer/SKILL.md

@@ -0,0 +1,239 @@
+---
+name: catalyst-data-layer
+description: >
+  Wire Angular components, router resolvers, and ad-hoc code to the Aurora Catalyst GraphQL
+  data-access layer (`@aurora/modules/graphql`). Trigger: ANY time you are about to write code that
+  reads or mutates server data — composing a list or detail screen, writing a `ResolveFn`, adding a
+  custom query or mutation, picking between a fetcher (one-shot) and a composable (stateful). Also
+  fires when debugging Apollo / signal mismatches, when the user mentions "query", "mutation",
+  "resolver", "composable", "GraphQL", "Apollo", "useGraphql", or any `@aurora/modules/graphql`
+  import. Skip if the task is pure UI composition with no data access — use
+  `catalyst-component-catalog` instead.
+license: MIT
+metadata:
+  author: aurora
+  version: '1.0'
+---
+
+## When to Use
+
+- Wiring a list view to paginated data (component + resolver + data-table).
+- Wiring a detail view that loads, creates, and updates a single record.
+- Writing a `ResolveFn` that pre-loads data for a route.
+- Adding a custom query / mutation that is not covered by the generated configs.
+- Answering "how do I read / write data from this component?".
+- Debugging why a composable-in-resolver call creates dead signals, or why `runInInjectionContext`
+  is needed in a composable method.
+
+**Skip this skill** if the task is pure UI composition with no data access (no Apollo, no
+`useGraphql*`, no `query*` / `mutate*` fetcher). Use `catalyst-component-catalog` for that.
+
+## Mandatory Discovery Protocol
+
+BEFORE writing any code that calls `@aurora/modules/graphql`, follow this protocol. It keeps you in
+sync with the actual code instead of memorizing a list that ages.
+
+1. **Read the two index files to learn what exists**
+   - `Read frontend/src/@aurora/modules/graphql/fetchers/index.ts` — the pure call layer.
+   - `Read frontend/src/@aurora/modules/graphql/composables/index.ts` — the stateful layer.
+2. **Open the specific file you need**
+   - If you need a fetcher (one-shot): `Read frontend/src/@aurora/modules/graphql/fetchers/<name>.ts`
+     for the signature, parameter names, and return type.
+   - If you need a composable (component-scoped): `Read frontend/src/@aurora/modules/graphql/composables/<name>.ts`
+     for the returned shape (signals, methods, loading flag).
+3. **Consume, do NOT re-derive**
+   - Lift the signature from the file you opened. Do not guess parameter order or keys from
+     memory.
+   - Do not re-implement a call body "just to be safe". If a fetcher covers the need, use it.
+
+This protocol is also how you stay correct when new fetchers or composables are added — the skill
+does not need to be updated, the indexes are the catalog.
+
+## Conceptual Hierarchy
+
+The data-access layer is split in two sibling folders under `@aurora/modules/graphql/`:
+
+```
+fetchers/                  "how" — the call to the GraphQL server
+  queryX<T>(...)           reads  → Observable<T | T[] | DataTableData<T> | null>
+  mutateX(...)             writes → Observable<...>
+                           Pure functions. No signals. Only `inject(Apollo)`.
+                           Safe in any injection context (component, resolver, guard).
+
+composables/               "where" — stateful wrappers for component lifecycle
+  useGraphqlX(...)         wrap their matching fetcher AND add signals.
+                           Return { method, signal-projections, loading }.
+                           Designed for component bodies.
+```
+
+The folder name `fetchers/` describes the technical role (a call to the server, like `fetch()` in
+the JS API: covers both GET and POST). The function names use GraphQL vocabulary (`query*` for
+reads, `mutate*` for writes). The composables prefix `useGraphql*` follows the Angular / React
+convention for lifecycle-aware helpers.
+
+### When to use which layer
+
+| Consumer                    | Use                        | Why                                                   |
+| --------------------------- | -------------------------- | ----------------------------------------------------- |
+| Component (list / detail)   | Composable (`useGraphqlX`) | You want the signals for template reactivity.         |
+| Router resolver (`ResolveFn`) | Fetcher (`queryX`)         | One-shot fetch; resolver has no lifecycle for signals.|
+| Service, guard, interceptor | Fetcher                    | Same as resolver — no component to hold state.        |
+| Custom Apollo cache control | `inject(Apollo)` directly  | Only when a fetcher / composable does not fit.        |
+
+### Internal relationship
+
+Composables delegate their call to the matching fetcher, wrapped in `runInInjectionContext` so the
+inner `inject(Apollo)` resolves correctly when the composable method is invoked from a template
+event (click, submit, etc.):
+
+```typescript
+// the shape every primitive composable follows internally
+const injector = inject(Injector);
+// ...
+return runInInjectionContext(injector, () => queryX<T>(statement, key, fields, variables))
+  .pipe(tap((data) => { /* write to signals */ }));
+```
+
+If you are extending a composable, keep that wrapper. If you are reading composable code and
+wonder why `runInInjectionContext` appears there, this is why: the fetcher uses `inject(Apollo)`,
+and the method that calls it may fire outside the composable's constructor-time injection context.
+
+## Patterns
+
+All four patterns below have anchored, executable examples in
+[`references/known-patterns.md`](references/known-patterns.md). Read that file when you need to
+copy a structure.
+
+### 1. List pattern — component with facade
+
+**Shape**:
+
+```
+ResolveFn (queryPaginate)  →  route.data['pagination']  →  Component
+                                                            ├── useGraphqlList(CONFIG)
+                                                            ├── useDataTable(columns, data)
+                                                            └── buildSearch/Filter/SortWhere(...) for refetch
+```
+
+- Consume `useGraphqlList<Entity>(CONFIG)` to get `{ paginate, pagination, deleteById, loading }`.
+- Pre-load the first page via the resolver (fetcher), so the component opens with data already in
+  `route.snapshot.data[...]`. Store it in a local `page` signal.
+- Use `useDataTable({ data, columns, manualSorting, manualPagination, onSortingChange,
+  onPaginationChange })` to get the TanStack Table instance.
+- On sort / filter / search changes, call `list.paginate({ query: { where, order, offset, limit }
+  })` and push the result into the local `page` signal.
+- For `where` / `order`, use the builders `buildSearchWhere / buildFilterWhere / buildSortOrder`
+  from `@aurora/components/data-table/lib/` (see cross-reference below).
+
+### 2. Detail pattern — component with facade + pickModel
+
+**Shape**:
+
+```
+ResolveFn (queryFindById)  →  route.data['item']  →  Component
+                                                      ├── useGraphqlDetail(CONFIG)
+                                                      ├── pickModel(item, defaults)  → initial form values
+                                                      └── FormBuilder.group(...)      → signalForm
+```
+
+- Consume `useGraphqlDetail<Entity>(CONFIG)` to get `{ findById, item, create, update, lastPayload, loading }`.
+- The resolver pre-loads the item (fetcher) so the component receives it via
+  `route.snapshot.data['item']`.
+- Use `pickModel(item, defaults)` to project the loaded entity into the exact shape the form
+  needs — this never leaks extra properties and uses the defaults for missing keys. The defaults
+  object doubles as documentation of the form's shape.
+- Build the reactive form with `FormBuilder.group({ ... })` using the pickModel result as initial
+  values.
+- On submit, call `detail.create(...)` or `detail.update(...)` depending on mode.
+
+### 3. Resolver pattern — fetchers with config destructuring
+
+**Shape**:
+
+```
+ResolveFn → destructure { queryX, keyX, fields } from CONFIG → queryPaginate / queryFindById / ...
+```
+
+- Resolvers MUST use fetchers, not composables. Signals do not belong here.
+- Always destructure from the module's generated `*_LIST_CONFIG` / `*_DETAIL_CONFIG` so the query,
+  key, and fields are the single source of truth shared with the component.
+- For paginated list pre-loads without filters, pass a minimal variables object:
+  `{ query: { offset: 0, limit: DEFAULT_PAGE_SIZE, order: buildSortOrder([]) } }`.
+- Return the `Observable` directly — the router awaits it and exposes the value under
+  `route.snapshot.data[...]`.
+
+### 4. Escape hatch — `inject(Apollo)` directly
+
+This is reserved for the rare case that neither a fetcher nor a composable fits. Examples:
+
+- You need explicit Apollo cache policy tuning (`fetchPolicy`, `nextFetchPolicy`) that is not yet
+  exposed through the fetchers.
+- You need `watchQuery` with a subscription that updates reactively as the cache changes, not a
+  one-shot `query`.
+- You are implementing a new fetcher or composable and are by definition underneath the layer.
+
+**Before you reach for `inject(Apollo)`**, verify no fetcher covers your case — check
+`fetchers/index.ts`. The escape hatch is the exception, not the default.
+
+## QueryStatement builders — cross-reference
+
+The helpers `buildSearchWhere`, `buildFilterWhere`, and `buildSortOrder` live under
+`@aurora/components/data-table/lib/` and are fully documented in the
+[`catalyst-data-table-management`](../catalyst-data-table-management/SKILL.md) skill. They produce
+Sequelize-compatible `where` / `order` objects that pass straight into a fetcher's `variables.query`.
+
+- **In a resolver**: use `buildSortOrder([])` to produce the default empty ordering for the
+  initial list pre-load. No other builder is needed there.
+- **In a list component**: use all three to translate the current TanStack state (sorting,
+  filters, search) into the `paginate()` variables on refetch.
+
+Do NOT duplicate the builders' documentation here — consult the data-table skill.
+
+## Anti-patterns
+
+Three smells appear in AI-generated code because the correct shape is non-obvious. Each one has a
+prescribed alternative:
+
+### ❌ `HttpClient` for data access
+Use Apollo. The project is exclusively GraphQL. If you reach for `HttpClient`, you are bypassing
+the caching, typing, and error-handling that the Apollo layer provides. The composable / fetcher
+you want probably already exists; re-check `fetchers/index.ts` and `composables/index.ts`.
+
+### ❌ `BehaviorSubject` (or any RxJS Subject) for state
+Use `signal()` from `@angular/core`. The project follows the signals-first rule from
+`frontend/CLAUDE.md`. Mixing RxJS Subjects with signals fragments the change-detection model and
+breaks downstream `computed()` derivations.
+
+### ❌ GraphQL operator string literals like `'[iLike]'` or `'[or]'`
+Use the `Operator` enum from `@aurorajs.dev/core-common`:
+
+```typescript
+import { Operator } from '@aurorajs.dev/core-common';
+
+// ✅ correct
+return {
+  [Operator.or]: columns.map((col) => ({
+    [col]: { [Operator.iLike]: `%${value}%` },
+  })),
+};
+
+// ❌ anti-pattern — compiles, but drifts if the serialization changes
+return {
+  '[or]': columns.map((col) => ({
+    [col]: { '[iLike]': `%${value}%` },
+  })),
+};
+```
+
+The string literals compile today because the enum serializes to the same bracketed form, but they
+silently break if the enum's internal representation ever changes.
+
+## Related skills
+
+- [`catalyst-data-table-management`](../catalyst-data-table-management/SKILL.md) — column
+  definitions, TanStack table wiring, and the full contract of `buildSearchWhere` /
+  `buildFilterWhere` / `buildSortOrder`.
+- [`catalyst-form-composer-auditor`](../catalyst-form-composer-auditor/SKILL.md) — compose or
+  audit the body of a detail form after `pickModel` has given you the initial shape.
+- [`catalyst-component-catalog`](../catalyst-component-catalog/SKILL.md) — the UI side; the
+  visual components you render around the data.