@aurorajs.dev/catalyst-cli 1.0.2 → 2.0.0

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/SKILL.md

@@ -1,25 +1,24 @@
 ---
 name: catalyst-handler-composer
 description: >
-  Fill in business logic inside CLI-generated NestJS handlers in the Aurora Catalyst backend,
-  refine the controller/resolver/handler scaffolds the CLI produces from `additionalApis`
-  declarations, AND compose hand-written COMPOSITE HANDLERS for protocol-flow endpoints (e.g.,
-  OAuth token issuance dispatching PASSWORD vs REFRESH_TOKEN variants to sub-handlers). The skill
-  is CLI-first for aggregates: `aurora-catalyst-cli` generates the handler, service, controller,
-  resolver, DTO, and GraphQL files from the module's `*.aurora.yaml`. For hand-written protocol
-  flows, see the "Composite handlers" section below — the dispatch lives in the handler, NEVER
-  duplicated in the transports. Trigger: editing any *.handler.ts under
-  @app/<pkg>/<module>/application/<op>/, adding pre-persistence validation or business rules
-  inside an existing handler's main(), wiring @EmitEvent / @ApplySchema / @Format decorators,
-  refining the payload types / auth permission / return shape of a scaffolded additionalApis
-  handler, deciding between handler and service for where logic belongs, OR composing a
-  composite/dispatch handler that fronts a protocol-flow endpoint exposed over multiple transports.
-  Fires even when the user says only "write a handler", "implement the business logic for X", or
-  "the OAuth flow needs a handler" — Step 0 of SKILL.md routes the CLI-territory case through the
-  CLI if the target file does not yet exist; the Composite handlers section routes the
-  hand-written protocol-flow case. Does NOT apply to guards, interceptors, pipes, or filters (use
-  `catalyst-nestjs-primitives`) and does NOT replace full-module audits (use
-  `catalyst-review-module`).
+  Fill in business logic inside CLI-generated NestJS handlers in the Aurora Catalyst backend, refine
+  the controller/resolver/handler scaffolds the CLI produces from `additionalApis` declarations, AND
+  compose hand-written COMPOSITE HANDLERS for protocol-flow endpoints (e.g., OAuth token issuance
+  dispatching PASSWORD vs REFRESH_TOKEN variants to sub-handlers). The skill is CLI-first for
+  aggregates: `aurora-catalyst-cli` generates the handler, service, controller, resolver, DTO, and
+  GraphQL files from the module's `*.aurora.yaml`. For hand-written protocol flows, see the
+  "Composite handlers" section below — the dispatch lives in the handler, NEVER duplicated in the
+  transports. Trigger: editing any *.handler.ts under @app/<pkg>/<module>/application/<op>/, adding
+  pre-persistence validation or business rules inside an existing handler's main(), wiring
+  @EmitEvent / @ApplySchema / @Format decorators, refining the payload types / auth permission /
+  return shape of a scaffolded additionalApis handler, deciding between handler and service for
+  where logic belongs, OR composing a composite/dispatch handler that fronts a protocol-flow
+  endpoint exposed over multiple transports. Fires even when the user says only "write a handler",
+  "implement the business logic for X", or "the OAuth flow needs a handler" — Step 0 of SKILL.md
+  routes the CLI-territory case through the CLI if the target file does not yet exist; the Composite
+  handlers section routes the hand-written protocol-flow case. Does NOT apply to guards,
+  interceptors, pipes, or filters (use `catalyst-nestjs-primitives`) and does NOT replace
+  full-module audits (use `catalyst-review-module`).
 license: MIT
 metadata:
   author: aurora
@@ -32,7 +31,7 @@ Before touching any file, answer: **"should I be writing this file by hand at al
 backend is CLI-generated end-to-end. The `aurora-catalyst-cli` emits every standard artifact —
 controller, resolver, handler, service, DTO, GraphQL schema — from the module's YAML and keeps them
 regenerable. Hand-writing what the CLI would produce means fighting the generator: the next
-`catalyst load` either overwrites your file or emits a `.origin` conflict.
+`catalyst generate` either overwrites your file or emits a `.origin` conflict.
 
 Route every handler task through one of these three branches before reading the pre-flight checklist
 below.
@@ -56,24 +55,24 @@ below.
 └──────┬───────┘   └───────────┬───────────┘   └─────────┬────────┘
        │                       │                         │
        ▼                       ▼                         ▼
-Edit YAML              Declare in YAML              STOP.
-(operations /          `additionalApis`.            Surface to user.
- excludedOperations    Run catalyst load.           Almost always
- / excludedFiles).     CLI scaffolds 3 files.       the wrong path.
-Run catalyst load.     Refine the scaffold          If truly custom
-CLI (re)generates      (types → auth → return       and CLI can't
-the files.             → services → logic).         help, document
-                                                    why in the user
-Read                   Read                         conversation.
-`references/           `references/
- cli-first-            additional-apis-
- workflow.md`.         workflow.md`.
+Edit YAML               Declare in YAML              STOP.
+(operations /           `additionalApis`.            Surface to user.
+ excludedOperations     Run catalyst generate.       Almost always
+ / excludedFiles).      CLI scaffolds 3 files.       the wrong path.
+Run catalyst generate.  Refine the scaffold          If truly custom
+CLI (re)generates       (types → auth → return       and CLI can't
+the files.              → services → logic).         help, document
+                                                     why in the user
+Read                    Read                         conversation.
+`references/            `references/
+ cli-first-             additional-apis-
+ workflow.md`.          workflow.md`.
 ```
 
 **The regeneration command** (same in all branches):
 
 ```bash
-catalyst load back module --name=<bounded-context>/<module> --force
+catalyst generate back module --name=<bounded-context>/<module> --force
 ```
 
 Full command documentation, YAML switches, and lockfile interaction:
@@ -146,12 +145,12 @@ The handler orchestrates and validates. The service persists. Event emission is
 
 ## Composite handlers — one business flow, two transports
 
-A **composite handler** is a hand-written handler that fronts a protocol-flow endpoint exposed
-over MULTIPLE transports (REST + GraphQL, REST + gRPC, etc.). Its job is to:
+A **composite handler** is a hand-written handler that fronts a protocol-flow endpoint exposed over
+MULTIPLE transports (REST + GraphQL, REST + gRPC, etc.). Its job is to:
 
 1. Receive a single polymorphic input.
-2. Dispatch to a sub-handler based on a discriminator field (typically a `grantType`,
-   `eventType`, `action`, etc.).
+2. Dispatch to a sub-handler based on a discriminator field (typically a `grantType`, `eventType`,
+   `action`, etc.).
 3. Return a single response shape that the transports map to their on-wire format.
 
 The transports (controller, resolver) **MUST NOT replicate the dispatch logic**. Each transport
@@ -226,8 +225,8 @@ export class <Flow>Resolver {
 }
 ```
 
-Neither transport checks the discriminator. Neither knows what variants exist. They MUST be
-ignorant of the dispatch — that's what makes "one business flow, two transports" work.
+Neither transport checks the discriminator. Neither knows what variants exist. They MUST be ignorant
+of the dispatch — that's what makes "one business flow, two transports" work.
 
 ### Antipattern detection — dispatch duplicated across transports
 
@@ -243,14 +242,14 @@ if (payload.<discriminator> === '<VARIANT_B>') {
 throw new UnsupportedError();
 ```
 
-…STOP. This is the antipattern. The dispatch belongs in a composite handler, not in the
-transports. To refactor:
+…STOP. This is the antipattern. The dispatch belongs in a composite handler, not in the transports.
+To refactor:
 
 1. Create `<flow>.handler.ts` with the dispatch.
 2. Move the sub-handler injections from the controller/resolver to the composite handler.
 3. Reduce the controller/resolver to: parse → call `composite.main(input)` → return.
-4. Update tests: the composite handler's spec asserts the dispatch table; the transport specs
-   assert ONLY their parsing/mapping.
+4. Update tests: the composite handler's spec asserts the dispatch table; the transport specs assert
+   ONLY their parsing/mapping.
 
 ### Where the composite handler lives
 
@@ -258,8 +257,8 @@ Per `catalyst-project-structure` "Hand-written protocol-flow endpoints" section:
 
 - Composite handler: `@app/<bc>/<flow>/application/<flow>.handler.ts`
 - Sub-handlers: `@app/<bc>/<flow>/application/<variant>/<flow>-<variant>.handler.ts`
-- Composite registered as provider in the FLOW's dedicated module (`@api/<bc>/<flow>/<flow>.module.ts`),
-  NOT in the Cliter-generated `<bc>.module.ts`.
+- Composite registered as provider in the FLOW's dedicated module
+  (`@api/<bc>/<flow>/<flow>.module.ts`), NOT in the Cliter-generated `<bc>.module.ts`.
 
 ### Worked example — `IssueTokenHandler` (OAuth2)
 
@@ -274,10 +273,14 @@ export class IssueTokenHandler {
 
   async main(input: IssueTokenInput): Promise<IssueTokenResponse> {
     if (input.grantType === 'PASSWORD') {
-      return this.passwordHandler.main({ /* mapped to password input */ });
+      return this.passwordHandler.main({
+        /* mapped to password input */
+      });
     }
     if (input.grantType === 'REFRESH_TOKEN') {
-      return this.refreshHandler.main({ /* mapped to refresh input */ });
+      return this.refreshHandler.main({
+        /* mapped to refresh input */
+      });
     }
     throw new UnsupportedGrantTypeError();
   }
@@ -288,8 +291,6 @@ Both `IssueTokenController` (REST, parses `application/x-www-form-urlencoded` +
 `IssueTokenResolver` (GraphQL, parses typed `OAuthCreateCredentialsInput`) call
 `IssueTokenHandler.main(input)`. Neither knows about `passwordHandler` or `refreshHandler`.
 
-
-
 Minimal shape from `iam/tag`:
 
 ```typescript
@@ -302,7 +303,7 @@ export class IamCreateTagHandler {
   ) {}
 
   @EmitEvent('iam.tag.created')
-  @ApplySchema(IamTagFieldSchema)
+  @ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
   async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
     // pre-persistence validation would sit here, before the service call
     await this.createService.main(payload, handlerMeta);
@@ -324,9 +325,9 @@ training-memory instincts, reach for the alternative instead.
    resolver/controller holds a reference to the handler directly and calls
    `this.handler.main(payload, { timezone, repositoryOptions: { auditing } })`. There is no bus.
 
-3. **Constructing Value Objects inside the handler.** → Use `@ApplySchema(FieldSchema)` and let the
-   `FieldSchema` declare validation (nullable, maxLength, rules, etc.). The decorator validates the
-   payload before `main()` runs. See
+3. **Constructing Value Objects inside the handler.** → Use `@ApplySchema({ schema, operation })`
+   and let the `FieldSchema` declare validation (nullable, maxLength, rules, etc.). The decorator
+   validates the payload before `main()` runs. See
    [`catalyst-field-schema/references/field-schema-and-decorators.md`](../catalyst-field-schema/references/field-schema-and-decorators.md)
    for the full `FieldSchema` interface, the 16 type handlers, and the `@Sanitize` / `@Format` /
    `@ApplySchema` decision tree.
@@ -349,17 +350,17 @@ training-memory instincts, reach for the alternative instead.
 7. **Hand-writing a controller, resolver, or handler file the CLI would generate.** → This is the
    Step 0 violation. If the operation is a standard CRUD, edit the module's YAML (`operations` /
    `excludedOperations` / `excludedFiles`) and run
-   `catalyst load back module --name=<bc>/<module> --force`. If the operation is a custom verb,
+   `catalyst generate back module --name=<bc>/<module> --force`. If the operation is a custom verb,
    declare it in `additionalApis` in the YAML and run the same command — the CLI scaffolds the three
    files and you refine them per
    [`references/additional-apis-workflow.md`](references/additional-apis-workflow.md). A
    hand-written file that duplicates what the CLI would produce drifts from the generator on the
    next regeneration (integrity hash mismatch → `.origin` conflict) and loses the benefit of the
-   shared scaffold. **EXCEPTION**: hand-written protocol-flow composite handlers (e.g.,
-   OAuth token issuance, JWKS) are legitimate — they implement non-aggregate concerns the CLI
-   does not cover. They live under `@app/<bc>/<flow>/application/<flow>.handler.ts` and are
-   registered in a dedicated `@api/<bc>/<flow>/<flow>.module.ts` (see "Composite handlers" section
-   above + `catalyst-project-structure` "Hand-written protocol-flow endpoints" section).
+   shared scaffold. **EXCEPTION**: hand-written protocol-flow composite handlers (e.g., OAuth token
+   issuance, JWKS) are legitimate — they implement non-aggregate concerns the CLI does not cover.
+   They live under `@app/<bc>/<flow>/application/<flow>.handler.ts` and are registered in a
+   dedicated `@api/<bc>/<flow>/<flow>.module.ts` (see "Composite handlers" section above +
+   `catalyst-project-structure` "Hand-written protocol-flow endpoints" section).
 
 8. **Dispatch logic duplicated across transports** (controller AND resolver both checking the same
    discriminator field to choose a sub-handler). → See "Composite handlers — Antipattern detection"
@@ -392,7 +393,7 @@ hand-written handlers match it to keep diffs clean on regeneration.
 
 1. Node.js built-ins (rare in handlers — example: `import { readFile } from 'fs/promises'`).
 2. NestJS (`@nestjs/common`, `@nestjs/event-emitter`, `@nestjs/graphql`).
-3. External libraries (`@aurorajs.dev/core-back`, `@aurorajs.dev/core-common`, `uuid`, …).
+3. External libraries (`@aurorajs.dev/core-back`, `uuid`, …).
 4. Internal path aliases in order: `@api/*`, `@app/*`, `@infrastructure/*`, `@aurora/*`.
 5. Relative imports.
 
@@ -403,10 +404,11 @@ hand-written handlers match it to keep diffs clean on regeneration.
 - **`catalyst-review-module`** — coherence audit of a whole module, including handlers. This
   composer skill and the review skill are complementary: compose here, audit there.
 - **`catalyst-field-schema`** — the declarative data-access layer: `FieldSchema` type, 16 type
-  handlers, the three decorators (`@ApplySchema` / `@Format` / `@Sanitize`), `Obj.diff` helper,
-  `QueryStatement` shape, `Operator` enum, and the current `include` + `formatRecord` security gap
-  with its workaround. Read this whenever you wire a decorator on `main()` or reach for a custom
-  `where` / `include` clause.
+  handlers, the three decorators (`@ApplySchema` / `@Format` / `@Sanitize`), the
+  `Obj.diffAtomic` / `Obj.diff` pair, and the Aurora Query DSL `QueryStatement` shape (`where` / `relations` / `order` / `aggregation`), the
+  `WHERE_OPERATOR`/`LOGICAL_OPERATOR` vocabulary, and the `relation`-entry recursive formatting
+  pipeline. Read this whenever you wire a decorator on `main()` or reach for a custom `where` /
+  `relations` clause.
 - **`catalyst-nestjs-primitives`** — catalyst-authored primitives (`@Auth`,
   `AuthenticationJwtGuard`, `AuthorizationPermissionsGuard`), upstream catalog (`@Timezone`,
   `@Auditing`, `@CurrentAccount`, `@ContentLanguage`, `@TenantPolicy`, `@TenantConstraint`), the

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/additional-apis-workflow.md

@@ -9,8 +9,8 @@ does not fit the CRUD vocabulary cleanly. Even though you could technically do t
 domain-specific inputs and outputs.
 
 The solution is **not** to hand-write a controller/resolver/handler. It is to declare the endpoint
-in the module's `additionalApis` block, regenerate with `catalyst load`, and refine the scaffold the
-CLI produces.
+in the module's `additionalApis` block, regenerate with `catalyst generate`, and refine the scaffold
+the CLI produces.
 
 ## The three files the CLI scaffolds
 
@@ -23,36 +23,86 @@ is produced specifically for the custom endpoint — it reuses the module-wide t
 | `@api/<bc>/<mod>/resolvers/<bc>-<verb>-<mod>.resolver.ts`         | GraphQL resolver                 |
 | `@app/<bc>/<mod>/application/<verb>/<bc>-<verb>-<mod>.handler.ts` | Application-layer handler (stub) |
 
-Template source lives at `aurora-catalyst-cli/src/templates/codegen/backend/additional-@api/` and
+Template source lives at `packages/cli/src/templates/codegen/backend/additional-@api/` and
 `.../additional-@app/`.
 
 ## The defaults the CLI chooses (which you will usually override)
 
-The CLI has to guess at five things because the YAML only declares the path, resolver type, and HTTP
+The CLI has to guess at six things because the YAML only declares the path, resolver type, and HTTP
 method. The guesses are conservative but frequently wrong for the real operation.
 
-| Dimension       | CLI default (mutation)                                | CLI default (query)                   |
-| --------------- | ----------------------------------------------------- | ------------------------------------- |
-| Payload type    | `<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto` | `QueryStatement` (no payload)         |
-| Auth permission | `<bc>.<mod>.update`                                   | `<bc>.<mod>.get`                      |
-| Return type     | `Promise<boolean>`                                    | `Promise<<Bc><Mod>[]>`                |
-| Handler body    | `return true;`                                        | `return [];`                          |
-| Constructor     | empty with `// TODO: inject services`                 | empty with `// TODO: inject services` |
+| Dimension          | CLI default (mutation)                                                  | CLI default (query)                   |
+| ------------------ | ----------------------------------------------------------------------- | ------------------------------------- |
+| Payload type       | `<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto`                   | `QueryStatement` (no payload)         |
+| Payload validation | `@ApplySchema({ schema: <Aggregate>FieldSchema, operation: 'update' })` | none                                  |
+| Auth permission    | `<bc>.<mod>.update`                                                     | `<bc>.<mod>.get`                      |
+| Return type        | `Promise<boolean>`                                                      | `Promise<<Bc><Mod>[]>`                |
+| Handler body       | `return true;`                                                          | `return [];`                          |
+| Constructor        | empty with `// TODO: inject services`                                   | empty with `// TODO: inject services` |
 
 Tenancy and auditing branches the CLI also emits conditionally:
 
-- `hasTenant: true` → the handler, resolver, and controller receive `account: IamAccountResponse` as
-  the first argument; the resolver/controller carry `@TenantPolicy()` (mutation) or
-  `@TenantConstraint()` (query).
+- `hasTenant: true` → the handler, resolver, and controller receive `account: IamAccount` (from
+  `@api/graphql`), positioned per the decorator's own signature: first for a query
+  (`@TenantConstraint()` puts `account` before `queryStatement`/`constraint`), after the payload for
+  a mutation (`@TenantPolicy()` is payload-first); the resolver/controller carry the matching
+  decorator.
 - `hasAuditing: true` and mutation → the resolver/controller add
   `@Auditing() auditing?: AuditingMeta` and forward it as `repositoryOptions: { auditing }` into the
   handler meta.
 - The module has i18n properties → `@ContentLanguage()` is added and forwarded as
   `meta: { contentLanguage }`.
 
+## Payload validation: `@ApplySchema` on the mutation branch
+
+Every mutation `additionalApis` handler carries
+`@ApplySchema({ schema: <Aggregate>FieldSchema, operation: 'update' })` above `main()`, with a
+guiding comment above the decorator naming the three edits below. The query branch carries no such
+decorator: it takes no payload, so there is nothing to sanitize. It emits no `@Format` either,
+unlike the core `get`/`find`/`paginate` templates, so a custom query handler that returns aggregate
+rows returns them unmasked and in the raw stored timezone.
+
+**What it does.** The decorator validates and normalizes `payload` (argument 0) against the
+aggregate's `FieldSchema` before `main()` runs, and formats the return value on the way out — the
+same mechanism the `create`/`update`/`upsert` templates already emit. The pipeline is SCHEMA-driven:
+it validates a payload key only when the aggregate's schema declares a field of that name, so a key
+the schema does not declare passes through untouched. But a key matching a `readOnly` property, or a
+`createOnly` property under `operation: 'update'`, is rejected with 400 — a custom payload shape
+that reuses one of THOSE field names is not safe just because it is custom.
+
+**It rewrites, it does not only check.** The sanitize direction transforms values before `main()`
+sees them: a `password` key is bcrypt-hashed by `PasswordTypeHandler.sanitize`. A decorated handler
+must therefore never forward its `payload` to a second decorated handler — the second pass hashes
+the hash, and the account can never authenticate again. `iam/user` is the live case: it declares
+`forgot-password` and `reset-password` as mutation `additionalApis`, and its aggregate declares
+`password` with `type: 'password'`.
+
+**What it does NOT do.** It validates by NAME COINCIDENCE — it does not understand what the custom
+verb actually does. `operation: 'update'` is fixed because it mirrors the payload type the template
+already emits (`<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto`); it is not an inference about
+whether the operation inserts or updates a row.
+
+**The developer's three edits:**
+
+1. Switch `operation` to `'create'` when the custom API only ever inserts a new row. For example,
+   `business-partner-portal/supplier-document/tenant/create` inserts a new
+   `BusinessPartnerPortalSupplierDocument` row and never touches an existing one — `operation`
+   should read `'create'` there, not the emitted default of `'update'`.
+2. Declare `payloadIndex: N` if `payload` is moved off argument 0 during refinement (Phase 1 above).
+   The emitted default of `0` is correct for the scaffold as generated; it stops being correct the
+   moment the handler's signature changes shape.
+3. Remove the decorator entirely once the payload stops being aggregate-shaped (a primitive
+   parameter, a bespoke DTO with no overlapping field names). This is not cosmetic. `sanitizeRecord`
+   opens with `const result = { ...payload }`, and `@Sanitize` writes that copy back over the
+   argument, so a primitive payload reaches the body mangled and no error is raised:
+   `'a@b.c'` arrives as `{ 0: 'a', 1: '@', 2: 'b', 3: '.', 4: 'c' }`, and a number arrives as `{}`.
+
 ## Anchor example: `iam/role/inherit-permissions-role`
 
-This is the canonical scaffolded `additionalApis` on disk today. The YAML declares:
+This is what the CLI emits today for that entry. The file on disk does not carry the decorator:
+`iam/role` has not been regenerated since the template started emitting it. Prettier also reformats
+the braces on the way to disk, so the on-disk file reads K&R where the template emits Allman. The
+YAML declares:
 
 ```yaml
 # cliter/iam/role.aurora.yaml
@@ -123,16 +173,25 @@ export class IamInheritPermissionsRoleRoleController {
 ```typescript
 // @app/iam/role/application/inherit-permissions-role/iam-inherit-permissions-role-role.handler.ts
 @Injectable()
-export class IamInheritPermissionsRoleRoleHandler {
-  constructor() {
-    // TODO: inject services needed for this operation
-  }
-
+export class IamInheritPermissionsRoleRoleHandler
+{
+  // TODO: inject services needed for this operation
+  constructor() {}
+
+  // @ApplySchema runs the aggregate's FieldSchema over `payload`. Two behaviours to know: it
+  // REWRITES values (a `password` key is bcrypt-hashed right here, so never forward this payload
+  // to another decorated handler), and it rejects with 400 a key matching a `readOnly` property,
+  // or a `createOnly` one under 'update'. Yours to adjust: switch `operation` to 'create',
+  // declare `payloadIndex: N` if `payload` moves off argument 0, or remove the decorator when
+  // `payload` is not aggregate-shaped — removal is required, not cosmetic: a primitive arrives
+  // mangled, because the pipeline copies it with a spread.
+  @ApplySchema({ schema: IamRoleFieldSchema, operation: 'update' })
   async main(
     payload: IamUpdateRoleByIdInput | IamUpdateRoleByIdDto,
     constraint?: QueryStatement,
     handlerMeta?: HandlerMeta,
-  ): Promise<boolean> {
+  ): Promise<boolean>
+  {
     // TODO: implement business logic
     return true;
   }
@@ -304,4 +363,4 @@ differ.
 
 If you arrived here and the three scaffold files do not exist yet, you skipped the regenerate step.
 Return to Step 0 of `SKILL.md`: declare `additionalApis` in the YAML, run
-`catalyst load back module --name=<bc>/<mod> --force`, then come back and refine the output.
+`catalyst generate back module --name=<bc>/<mod> --force`, then come back and refine the output.

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/cli-first-workflow.md

@@ -10,23 +10,23 @@ already in place. For custom endpoints declared via `additionalApis`, use
 ## Why CLI-first
 
 The `aurora-catalyst` CLI emits every standard artifact of a module — controller, resolver, handler,
-service, DTO, GraphQL schema, Sequelize model, repository, field schema, seed — from a single
-source: `cliter/<bc>/<module>.aurora.yaml`. Hand-writing one of those files is fighting the
-generator: the next `catalyst load` will either overwrite your file (if the integrity hash matches
-the previous generation) or emit a `.origin` file next to yours (if it detects a divergence) and
-leave you to reconcile. Both outcomes waste work that a YAML edit would have avoided. The rule is:
-**if the CLI can generate it, let it**.
+service, DTO, GraphQL schema, Drizzle schema, repository, field schema, seed — from a single source:
+`cliter/<bc>/<module>.aurora.yaml`. Hand-writing one of those files is fighting the generator: the
+next `catalyst generate` will either overwrite your file (if the integrity hash matches the previous
+generation) or emit a `.origin` file next to yours (if it detects a divergence) and leave you to
+reconcile. Both outcomes waste work that a YAML edit would have avoided. The rule is: **if the CLI
+can generate it, let it**.
 
 ## The regeneration command
 
 ```bash
-catalyst load back module --name=<bounded-context>/<module> --force
+catalyst generate back module --name=<bounded-context>/<module> --force
 ```
 
 Short aliases:
 
 ```bash
-catalyst load back module -n <bc>/<module> -f
+catalyst generate back module -n <bc>/<module> -f
 ```
 
 Relevant flags:
@@ -44,8 +44,8 @@ Relevant flags:
 The command also runs `pnpm back:graphql:types` automatically unless `--noGraphQLTypes` is set, so
 the GraphQL type exports stay in sync with the YAML.
 
-The frontend variant is `catalyst load front module --name=<bc>/<module>`; it is out of scope for
-this skill.
+The frontend variant is `catalyst generate front module --name=<bc>/<module>`; it is out of scope
+for this skill.
 
 ## YAML switches that control generation
 
@@ -88,10 +88,10 @@ Operations the CLI recognizes:
 | `max` / `min` / `sum` | Aggregate handlers over a column                |
 
 To add an operation the YAML currently excludes: remove it from `excludedOperations` and run
-`catalyst load back module --name=<bc>/<module> --force`. The CLI emits the handler, service,
+`catalyst generate back module --name=<bc>/<module> --force`. The CLI emits the handler, service,
 resolver, controller, DTO, and GraphQL fragment. To remove an operation that was previously
-generated: add it to `excludedOperations` and run `catalyst load ...` — **note**: the CLI does not
-delete already-generated files; you have to remove them by hand after updating the YAML.
+generated: add it to `excludedOperations` and run `catalyst generate ...` — **note**: the CLI does
+not delete already-generated files; you have to remove them by hand after updating the YAML.
 
 ### `excludedFiles`
 
@@ -106,7 +106,7 @@ excludedFiles:
 ```
 
 To include a previously-excluded file: remove its path from `excludedFiles` and run
-`catalyst load ...`. The CLI will emit it. To exclude a newly generated file: add its path to
+`catalyst generate ...`. The CLI will emit it. To exclude a newly generated file: add its path to
 `excludedFiles` (the CLI will skip it on the next run, but again won't delete what already exists on
 disk).
 
@@ -133,8 +133,8 @@ This is why Step 0 prefers editing YAML over hand-editing generated files for st
 
 ```
 Need a new CRUD operation?
-  └─ Is it in excludedOperations? → Remove the entry, run catalyst load --force.
-  └─ Is it blocked by excludedFiles? → Remove the entry, run catalyst load --force.
+  └─ Is it in excludedOperations? → Remove the entry, run catalyst generate --force.
+  └─ Is it blocked by excludedFiles? → Remove the entry, run catalyst generate --force.
   └─ Neither? → The operation is already generated; look under @app/<bc>/<module>/application/.
 
 Need a custom verb (activate, approve, cancel, …)?
@@ -142,7 +142,7 @@ Need a custom verb (activate, approve, cancel, …)?
 
 Need to remove an operation the CLI currently generates?
   └─ Add it to excludedOperations (or the relevant files to excludedFiles).
-  └─ Run catalyst load --force.
+  └─ Run catalyst generate --force.
   └─ Delete the now-orphaned files on disk by hand.
 
 Need to change the body of a generated handler's main()?

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/create-handler.md

@@ -3,9 +3,9 @@
 > **Prerequisite**: this reference applies only when the handler file already exists on disk — the
 > CLI generated it from a standard `create` operation declared in the module's YAML. If the file
 > does not exist, return to Step 0 of `SKILL.md`: edit the YAML, run
-> `catalyst load back module --name=<bc>/<module> --force`, and the CLI emits the handler, service,
-> resolver, controller, DTO, and GraphQL fragment together. Hand-writing the handler bypasses the
-> generator and breaks on the next regeneration.
+> `catalyst generate back module --name=<bc>/<module> --force`, and the CLI emits the handler,
+> service, resolver, controller, DTO, and GraphQL fragment together. Hand-writing the handler
+> bypasses the generator and breaks on the next regeneration.
 
 ## When it applies
 
@@ -38,7 +38,7 @@ export class IamCreateTagHandler {
   ) {}
 
   @EmitEvent('iam.tag.created')
-  @ApplySchema(IamTagFieldSchema)
+  @ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
   async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
     await this.createService.main(payload, handlerMeta);
 
@@ -55,9 +55,11 @@ Role of each moving part:
   in its fully-hydrated shape so the resolver does not have to re-query.
 - **`@EmitEvent('iam.tag.created')`** — publishes on `EventEmitter2` after `main()` resolves without
   throwing. You do not call `eventEmitter.emit(...)` by hand.
-- **`@ApplySchema(IamTagFieldSchema)`** — runs declarative validation over `payload` before `main()`
-  begins. Anything the `FieldSchema` expresses (required fields, maxLength, enum membership, custom
-  rules) is enforced here; do not duplicate those checks inside `main()`.
+- **`@ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })`** — runs declarative
+  validation over `payload` before `main()` begins. Anything the `FieldSchema` expresses (required
+  fields, maxLength, enum membership, custom rules) is enforced here; do not duplicate those checks
+  inside `main()`. `operation: 'create'` is REQUIRED on every create handler — it is what lets a
+  `createOnly` property stay writable here while an update handler rejects it.
 - **`payload`** — the GraphQL input type (or DTO in REST controllers); the type comes from
   `@api/graphql`.
 - **`handlerMeta?`** — carries `timezone` and `repositoryOptions.auditing`. The resolver or
@@ -94,7 +96,7 @@ already-persisted aggregate, which is too late to reject cleanly.
 
 ```typescript
 @EmitEvent('iam.tag.created')
-@ApplySchema(IamTagFieldSchema)
+@ApplySchema({ schema: IamTagFieldSchema, operation: 'create' })
 async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
   // Pre-persistence: reject if a tag with the same slug already exists in the same tenant.
   const existing = await this.repository.find({

package/dist/templates/backend/application/.claude/skills/catalyst-handler-composer/references/delete-handler.md

@@ -3,9 +3,9 @@
 > **Prerequisite**: this reference applies only when the handler file already exists on disk — the
 > CLI generated it from a standard `delete` or `deleteById` operation declared in the module's YAML.
 > If the file does not exist, return to Step 0 of `SKILL.md`: edit the YAML, run
-> `catalyst load back module --name=<bc>/<module> --force`, and the CLI emits the handler, service,
-> resolver, controller, DTO, and GraphQL fragment together. Hand-writing the handler bypasses the
-> generator and breaks on the next regeneration.
+> `catalyst generate back module --name=<bc>/<module> --force`, and the CLI emits the handler,
+> service, resolver, controller, DTO, and GraphQL fragment together. Hand-writing the handler
+> bypasses the generator and breaks on the next regeneration.
 
 ## When it applies
 
@@ -26,7 +26,7 @@ import { IamTag } from '@api/graphql';
 import { IamDeleteTagByIdService, IamFindTagByIdService } from '@app/iam/tag';
 import { IamTagFieldSchema } from '@app/iam/tag/domain';
 import { EmitEvent, Format, HandlerMeta } from '@aurorajs.dev/core-back';
-import { QueryStatement } from '@aurorajs.dev/core-common';
+import { QueryStatement } from '@aurorajs.dev/core-back';
 import { Injectable, NotFoundException } from '@nestjs/common';
 import { EventEmitter2 } from '@nestjs/event-emitter';
 
@@ -79,9 +79,9 @@ find-first step makes the failure loud.
 Catalyst services are thin and do not orchestrate cascades. When a delete must also tear down
 dependent rows, the options are:
 
-1. **Database-level cascade** — declared in the Sequelize model or the YAML relation
-   (`onDelete: CASCADE`). Preferred when the relation is stable and every delete should trigger the
-   cascade.
+1. **Database-level cascade** — declared in the Drizzle schema's foreign key (or the YAML relation
+   that generates it) via `onDelete: CASCADE`. Preferred when the relation is stable and every
+   delete should trigger the cascade.
 2. **Domain-level cascade inside the handler** — call multiple services in sequence from `main()`,
    typically with explicit order to respect referential integrity. Use this when the cascade depends
    on domain rules (e.g., only delete children in state `draft`).