@aurorajs.dev/catalyst-cli 1.0.0

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

@@ -0,0 +1,307 @@
+# additionalApis Workflow
+
+## When it applies
+
+The operation you need is a custom verb — `activate`, `approve`, `cancel`, `publish`,
+`change-status`, `inherit-permissions`, `check-unique-<field>`, `*-me` variants, and similar — that
+does not fit the CRUD vocabulary cleanly. Even though you could technically do the work through
+`updateById`, a dedicated endpoint gives the action a clear name, a scoped permission, and room for
+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.
+
+## The three files the CLI scaffolds
+
+For each `additionalApis` entry the CLI emits exactly three files. No DTO or GraphQL schema fragment
+is produced specifically for the custom endpoint — it reuses the module-wide types.
+
+| File                                                              | Purpose                          |
+| ----------------------------------------------------------------- | -------------------------------- |
+| `@api/<bc>/<mod>/controllers/<bc>-<verb>-<mod>.controller.ts`     | REST controller                  |
+| `@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
+`.../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
+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` |
+
+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).
+- `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 }`.
+
+## Anchor example: `iam/role/inherit-permissions-role`
+
+This is the canonical scaffolded `additionalApis` on disk today. The YAML declares:
+
+```yaml
+# cliter/iam/role.aurora.yaml
+additionalApis:
+  - path: iam/role/inherit-permissions-role
+    resolverType: mutation
+    httpMethod: post
+```
+
+The CLI emits three files with the shape shown below.
+
+### Resolver scaffold
+
+```typescript
+// @api/iam/role/resolvers/iam-inherit-permissions-role-role.resolver.ts
+@Resolver()
+@Auth('iam.role.update')
+export class IamInheritPermissionsRoleRoleResolver {
+  constructor(private readonly handler: IamInheritPermissionsRoleRoleHandler) {}
+
+  @Mutation('iamInheritPermissionsRoleRole')
+  async main(
+    @Args('payload') payload: IamUpdateRoleByIdInput,
+    @Args('constraint') constraint?: QueryStatement,
+    @Timezone() timezone?: string,
+    @Auditing() auditing?: AuditingMeta,
+  ): Promise<boolean> {
+    return await this.handler.main(payload, constraint, {
+      timezone,
+      repositoryOptions: { auditing },
+    });
+  }
+}
+```
+
+### Controller scaffold
+
+```typescript
+// @api/iam/role/controllers/iam-inherit-permissions-role-role.controller.ts
+@ApiTags('[iam] role')
+@Controller('iam/role/inherit-permissions-role')
+@Auth('iam.role.update')
+export class IamInheritPermissionsRoleRoleController {
+  constructor(private readonly handler: IamInheritPermissionsRoleRoleHandler) {}
+
+  @Post()
+  @ApiOperation({ summary: 'inherit-permissions-role role' })
+  @ApiCreatedResponse({
+    description: 'The operation has been successfully executed.',
+    type: Boolean,
+  })
+  async main(
+    @Body() payload: IamUpdateRoleByIdDto,
+    @Body('constraint') constraint?: QueryStatement,
+    @Timezone() timezone?: string,
+    @Auditing() auditing?: AuditingMeta,
+  ) {
+    return await this.handler.main(payload, constraint, {
+      timezone,
+      repositoryOptions: { auditing },
+    });
+  }
+}
+```
+
+### Handler scaffold
+
+```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
+  }
+
+  async main(
+    payload: IamUpdateRoleByIdInput | IamUpdateRoleByIdDto,
+    constraint?: QueryStatement,
+    handlerMeta?: HandlerMeta,
+  ): Promise<boolean> {
+    // TODO: implement business logic
+    return true;
+  }
+}
+```
+
+Everything above is generated output. Your job is to refine it.
+
+## The five refinement phases (in order)
+
+### Phase 1 — Payload type
+
+The CLI picks `<Bc>Update<Mod>ByIdInput` / `<Bc>Update<Mod>ByIdDto` for mutations because those
+types always exist for any module. They are almost never the right shape for a custom action. For
+`inherit-permissions-role`, the real action probably needs a payload like
+`{ targetRoleId: string; sourceRoleId: string }` — nothing to do with `UpdateRoleByIdInput`.
+
+Options:
+
+1. **Reuse an existing type** that already captures the shape you need.
+2. **Define a new input/DTO** specifically for the action. This usually means:
+   - Add a type definition to the module's GraphQL schema (`@api/<bc>/<mod>/graphql/*.graphql`).
+   - Add a matching DTO class under `@api/<bc>/<mod>/dto/` with the appropriate class-validator
+     decorators.
+   - Update the resolver's `@Args('payload')` type.
+   - Update the controller's `@Body()` type.
+   - Update the handler signature to accept the new type (or a union with it).
+3. **Use primitives** for a single-parameter action. For example, `check-unique-email` might accept
+   just `email: string` via `@Args('email')`.
+
+### Phase 2 — Auth permission
+
+The CLI sets `@Auth('<bc>.<mod>.update')` for mutations and `@Auth('<bc>.<mod>.get')` for queries.
+If the operation has a distinct authorization profile, register a more specific permission:
+
+- Pick a verb-scoped identifier: `<bc>.<mod>.<action>` — e.g., `iam.role.inheritPermissions`.
+- Declare it wherever the module's permissions are seeded.
+- Replace `@Auth(...)` on both the resolver and the controller.
+
+### Phase 3 — Return type
+
+The CLI returns `boolean` for mutations and `Entity[]` for queries. Decide what the operation should
+actually return:
+
+- **Boolean status** — keep as-is if the client only needs to know success/failure.
+- **Updated entity** — return `<Bc><Mod>` (singular). Change the resolver's return type, the
+  controller's `@ApiCreatedResponse({ type: ... })`, and the handler's `Promise<...>`.
+- **Custom result shape** — define a return type (GraphQL + DTO) and update all three files.
+
+### Phase 4 — Service injection
+
+Replace the empty `constructor()` with the real dependencies. Most custom operations reuse the CRUD
+services already generated for the module: `findByIdService`, `updateByIdService`,
+`deleteByIdService`. Sometimes a handler of a different module is needed (e.g., the
+`check-password-me` action injects the password-verification service from `o-auth`).
+
+Also inject `EventEmitter2` if the operation emits events via `@EmitEvent`.
+
+### Phase 5 — Business logic in `main()`
+
+Replace the `// TODO: implement business logic` stub with the real body. Typical patterns:
+
+- Fetch → validate → mutate → return: same skeleton as an update handler, but with the verb's own
+  rules in the middle. The find + NotFoundException pattern from
+  [`update-handler.md`](update-handler.md) applies.
+- Multi-service orchestration: the handler calls multiple services in sequence. Keep each service
+  thin; the orchestration lives here.
+- Domain event emission: add `@EmitEvent('<bc>.<mod>.<past-tense>')` above `main()` once the
+  operation changes state and other modules should react. Reuse the CRUD event topics is an
+  anti-pattern — the topic name is the semantic contract.
+
+## Illustrative refinement (synthesized)
+
+Continuing with `inherit-permissions-role`, a realistic completion looks like:
+
+```typescript
+// Refined handler
+@Injectable()
+export class IamInheritPermissionsRoleRoleHandler {
+  constructor(
+    private readonly eventEmitter: EventEmitter2,
+    private readonly findByIdService: IamFindRoleByIdService,
+    private readonly updateByIdService: IamUpdateRoleByIdService,
+    private readonly findPermissionsByRoleService: IamFindPermissionsByRoleService,
+  ) {}
+
+  @EmitEvent('iam.role.permissionsInherited')
+  async main(
+    payload: IamInheritPermissionsPayload, // new type, not IamUpdateRoleByIdInput
+    constraint?: QueryStatement,
+    handlerMeta?: HandlerMeta,
+  ): Promise<IamRole> {
+    const sourceRole = await this.findByIdService.main(
+      payload.sourceRoleId,
+      constraint,
+      handlerMeta,
+    );
+    if (!sourceRole) {
+      throw new NotFoundException(`Source IamRole with id: ${payload.sourceRoleId}, not found`);
+    }
+
+    const targetRole = await this.findByIdService.main(
+      payload.targetRoleId,
+      constraint,
+      handlerMeta,
+    );
+    if (!targetRole) {
+      throw new NotFoundException(`Target IamRole with id: ${payload.targetRoleId}, not found`);
+    }
+
+    const sourcePermissions = await this.findPermissionsByRoleService.main(
+      payload.sourceRoleId,
+      constraint,
+      handlerMeta,
+    );
+
+    await this.updateByIdService.main(
+      { id: payload.targetRoleId, permissions: sourcePermissions },
+      constraint,
+      handlerMeta,
+    );
+
+    return await this.findByIdService.main(payload.targetRoleId, constraint, handlerMeta);
+  }
+}
+```
+
+This is illustrative — no real implementation lives in `iam/role` today. Update the example here
+when one lands.
+
+## Mutation vs query — what differs
+
+The refinement phases are identical in structure, but the defaults and the resolver decorator
+differ.
+
+| Aspect                  | Mutation                                    | Query                            |
+| ----------------------- | ------------------------------------------- | -------------------------------- |
+| Resolver decorator      | `@Mutation('<verb><Bc><Mod>')`              | `@Query('<verb><Bc><Mod>')`      |
+| Controller HTTP         | Whatever `httpMethod:` says, typically POST | Usually POST with body (not GET) |
+| Default payload         | `<Bc>Update<Mod>ByIdInput` / `Dto`          | `QueryStatement`                 |
+| Default return          | `Promise<boolean>`                          | `Promise<<Bc><Mod>[]>`           |
+| `@Auth` default         | `<bc>.<mod>.update`                         | `<bc>.<mod>.get`                 |
+| Tenant decorator        | `@TenantPolicy()`                           | `@TenantConstraint()`            |
+| `@Auditing()` parameter | Present (resolver + controller)             | Absent                           |
+| Controller `@HttpCode`  | Absent (defaults to 201 Created)            | `@HttpCode(200)`                 |
+| Swagger response        | `@ApiCreatedResponse`                       | `@ApiOkResponse`                 |
+| Handler default body    | `return true;`                              | `return [];`                     |
+
+## Archetype-specific anti-patterns
+
+- **Hand-writing the three files instead of declaring in `additionalApis` + regenerating.** The CLI
+  produces the scaffolds with the right imports, decorators, and wiring. Starting from scratch
+  misses those defaults.
+- **Leaving the TODO stubs in place in production.** A handler that returns `true` without
+  implementing anything passes tests silently and masks the missing logic. If the action is declared
+  in YAML but not yet implemented, remove the resolver / controller wiring so the endpoint is not
+  exposed — or implement the stub properly.
+- **Reusing the CRUD event topic.** If the custom action changes state, emit a verb-specific event
+  (e.g., `iam.role.permissionsInherited`) rather than `iam.role.updated`. Listeners depend on the
+  verb.
+- **Mixing business logic into the service.** Custom operations tempt the developer to fill the
+  empty service with orchestration. The split stays the same: handler orchestrates; service
+  persists.
+- **Forgetting to update all three files when changing the payload type.** The resolver, the
+  controller, and the handler must agree. Changing only the handler produces TS errors or, worse,
+  runtime unmarshalling errors.
+
+## Reference back to Step 0
+
+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.

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

@@ -0,0 +1,180 @@
+# CLI-First Workflow
+
+## When it applies
+
+You arrived here from Step 0 of `SKILL.md`. The task is either (a) adding or removing a standard
+CRUD operation from a module, or (b) understanding how the regeneration interacts with hand edits
+already in place. For custom endpoints declared via `additionalApis`, use
+[`additional-apis-workflow.md`](additional-apis-workflow.md) instead.
+
+## 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**.
+
+## The regeneration command
+
+```bash
+catalyst load back module --name=<bounded-context>/<module> --force
+```
+
+Short aliases:
+
+```bash
+catalyst load back module -n <bc>/<module> -f
+```
+
+Relevant flags:
+
+| Flag               | Alias | Purpose                                                        |
+| ------------------ | ----- | -------------------------------------------------------------- |
+| `--name`           | `-n`  | `<bc>/<module>` (required)                                     |
+| `--force`          | `-f`  | Overwrite existing files whose lockfile integrity hash matches |
+| `--tests`          | `-t`  | Also generate e2e test files                                   |
+| `--verbose`        | `-v`  | Report every step on screen                                    |
+| `--noGraphQLTypes` | `-g`  | Skip the automatic `pnpm back:graphql:types` after generation  |
+| `--noReview`       | —     | Skip the interactive `.origin` file review at the end          |
+| `--target=<dir>`   | —     | Override the output subdirectory (defaults to `backend`)       |
+
+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.
+
+## YAML switches that control generation
+
+Both switches live at the top level of `<module>.aurora.yaml`, next to `aggregateProperties` and
+`additionalApis`.
+
+### `excludedOperations`
+
+Tells the CLI to skip generating the named operations. Absent or empty list means "generate
+everything".
+
+```yaml
+excludedOperations:
+  - count
+  - getRaw
+  - max
+  - min
+  - sum
+  - upsert
+```
+
+Operations the CLI recognizes:
+
+| Operation             | Generates handler/service for                   |
+| --------------------- | ----------------------------------------------- |
+| `count`               | Count the rows matching a filter                |
+| `create`              | Create a single row                             |
+| `createBatch`         | Create many rows in one call                    |
+| `delete`              | Delete many rows by filter                      |
+| `deleteById`          | Delete one row by id                            |
+| `find`                | Find one row by filter                          |
+| `findById`            | Find one row by id                              |
+| `get`                 | Get many rows by filter                         |
+| `getRaw`              | Get many rows with raw SQL shape (no `@Format`) |
+| `paginate`            | Paginated list                                  |
+| `update`              | Update many rows by filter                      |
+| `updateAndIncrement`  | Update + atomic increment of a counter field    |
+| `updateById`          | Update one row by id                            |
+| `upsert`              | Insert or update depending on key presence      |
+| `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,
+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.
+
+### `excludedFiles`
+
+Fine-grained opt-out: skip specific file paths even if the operation itself is enabled. Mostly used
+when an `additionalApis` variant collides with a CRUD file, or when a module has a custom
+hand-written file that must not be overwritten.
+
+```yaml
+excludedFiles:
+  - backend/src/@api/business-partner-portal/partner-address/handlers/business-partner-portal-create-partner-address-tenant.handler.ts
+  - backend/src/@api/business-partner-portal/partner-address/handlers/business-partner-portal-update-by-id-partner-address-tenant.handler.ts
+```
+
+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
+`excludedFiles` (the CLI will skip it on the next run, but again won't delete what already exists on
+disk).
+
+## Lockfile and `.origin` interaction
+
+Every generated file has a lockfile entry recording the SHA-1 of the contents the CLI emitted. On
+regeneration, the CLI compares the integrity hash of the file currently on disk with the lockfile
+hash:
+
+- **Hashes match** → no hand edits. The CLI overwrites the file with the new generated output.
+- **Hashes differ** → the file has hand edits. The CLI writes the new generated output to
+  `<file>.origin` next to the user's file. The user reviews the `.origin` and decides whether to
+  merge changes. The `--noReview` flag skips the interactive step.
+
+Consequence for hand edits: if you change only the body of a generated handler's `main()` and leave
+the scaffold intact, regeneration produces a `.origin` with the (probably identical) scaffold.
+Reviewing is trivial. But if you change decorators, imports, or the signature, the CLI regenerates
+the "canonical" scaffold into `.origin` and you must decide each time whether your divergence is
+intentional.
+
+This is why Step 0 prefers editing YAML over hand-editing generated files for structural changes.
+
+## Decision matrix
+
+```
+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.
+  └─ Neither? → The operation is already generated; look under @app/<bc>/<module>/application/.
+
+Need a custom verb (activate, approve, cancel, …)?
+  └─ Go to additional-apis-workflow.md — not this file.
+
+Need to remove an operation the CLI currently generates?
+  └─ Add it to excludedOperations (or the relevant files to excludedFiles).
+  └─ Run catalyst load --force.
+  └─ Delete the now-orphaned files on disk by hand.
+
+Need to change the body of a generated handler's main()?
+  └─ Edit the handler file directly. The lockfile tracks the divergence; .origin review on
+     next regen is trivial because your edits do not touch the scaffold.
+
+Need to change decorators, signatures, or imports of a generated handler?
+  └─ First ask: is this a YAML-expressible change? If yes, edit YAML. If no (truly custom),
+     hand-edit and accept the .origin review on each regen. Consider whether the operation
+     should move to additionalApis instead.
+```
+
+## Quick reference: YAML fragment shapes
+
+```yaml
+version: 0.0.1
+boundedContextName: iam
+moduleName: role
+# ... aggregateProperties ...
+additionalApis:
+  - path: iam/role/inherit-permissions-role
+    resolverType: mutation
+    httpMethod: post
+excludedOperations:
+  - count
+  - getRaw
+  - max
+  - min
+  - sum
+excludedFiles:
+  - backend/src/@app/iam/role/application/upsert/iam-upsert-role.handler.ts
+```
+
+For `additionalApis` refinement after regeneration, continue with
+[`additional-apis-workflow.md`](additional-apis-workflow.md).

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

@@ -0,0 +1,125 @@
+# Create Handler
+
+> **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.
+
+## When it applies
+
+File matches `*-create-*.handler.ts` under `@app/<pkg>/<module>/application/create/`. A create
+handler is the write path that accepts a payload, validates it, emits a creation event, and returns
+the newly-created entity.
+
+## Canonical signature
+
+Exact shape from `backend/src/@app/iam/tag/application/create/iam-create-tag.handler.ts`:
+
+```typescript
+/**
+ * @aurora-catalyst-generated
+ * @source cliter/iam/tag.aurora.yaml
+ */
+import { IamCreateTagInput, IamTag } from '@api/graphql';
+import { IamCreateTagService, IamFindTagByIdService } from '@app/iam/tag';
+import { IamTagFieldSchema } from '@app/iam/tag/domain';
+import { ApplySchema, EmitEvent, HandlerMeta } from '@aurorajs.dev/core-back';
+import { Injectable } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+
+@Injectable()
+export class IamCreateTagHandler {
+  constructor(
+    private readonly eventEmitter: EventEmitter2,
+    private readonly createService: IamCreateTagService,
+    private readonly findByIdService: IamFindTagByIdService,
+  ) {}
+
+  @EmitEvent('iam.tag.created')
+  @ApplySchema(IamTagFieldSchema)
+  async main(payload: IamCreateTagInput, handlerMeta?: HandlerMeta): Promise<IamTag> {
+    await this.createService.main(payload, handlerMeta);
+
+    return await this.findByIdService.main(payload.id, {}, handlerMeta);
+  }
+}
+```
+
+Role of each moving part:
+
+- **`@Injectable()`** — standard NestJS DI. No `@CommandHandler`.
+- **Constructor deps** — the event emitter is injected because the `@EmitEvent` decorator reads it
+  off `this`; the create service persists; the find-by-id service returns the freshly-created entity
+  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()`.
+- **`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
+  controller builds it; the handler forwards it to every service call. Do not construct it inside
+  the handler.
+- **Return shape** — the entity type from `@api/graphql`. Catalyst handlers return the full entity
+  (not just an id) so the resolver can short-circuit the follow-up query.
+
+## Typical `main()` body
+
+```
+1. (optional) pre-persistence validation — repository lookups, business rules, conflict checks.
+2. call createService.main(payload, handlerMeta) to persist.
+3. call findByIdService.main(payload.id, {}, handlerMeta) to return the hydrated entity.
+```
+
+The service is thin: it does not validate, it does not emit. It creates the aggregate from the
+payload and writes it.
+
+## Expected errors
+
+- **`ConflictException`** — when a pre-persistence uniqueness check finds an existing entity that
+  would collide with the payload.
+- **`ValidationException`** / field-level throws from `@ApplySchema` — surface automatically before
+  `main()` runs, so you never need to re-throw them.
+- **`BadRequestException`** — when business rules reject the payload for semantic reasons that the
+  `FieldSchema` cannot express (e.g., "role X cannot own resource Y because of a relationship
+  constraint").
+
+## Pre-persistence validation placement
+
+Put validation **before** `this.createService.main(...)`. Anything after the service call runs on an
+already-persisted aggregate, which is too late to reject cleanly.
+
+```typescript
+@EmitEvent('iam.tag.created')
+@ApplySchema(IamTagFieldSchema)
+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({
+    where: { slug: payload.slug, tenantId: payload.tenantId },
+  });
+
+  if (existing) {
+    throw new ConflictException(`IamTag with slug '${payload.slug}' already exists`);
+  }
+
+  await this.createService.main(payload, handlerMeta);
+  return await this.findByIdService.main(payload.id, {}, handlerMeta);
+}
+```
+
+If the check requires a repository that the generated handler does not inject, add it to the
+constructor — it is a hand edit the CLI preserves when you mark the block with the canonical
+`@aurora-catalyst-generated` boundary rules (see `catalyst-project-structure`).
+
+## Archetype-specific anti-patterns
+
+- **Validation in the service.** The service is a thin persistence wrapper. Put the pre-persistence
+  query or rule in the handler so the service stays regenerable.
+- **Manual `eventEmitter.emit(...)` call.** Let `@EmitEvent` do it. A manual call duplicates the
+  emission or, worse, emits before persistence succeeded.
+- **Returning the payload instead of the persisted entity.** The payload may diverge from the
+  persisted row (server-side defaults, generated timestamps, resolved relations). Always return via
+  `findByIdService.main(payload.id, {}, handlerMeta)`.