@aurorajs.dev/catalyst-cli 1.0.0

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

@@ -0,0 +1,110 @@
+# Delete Handler
+
+> **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.
+
+## When it applies
+
+File matches `*-delete-*.handler.ts` under `@app/<pkg>/<module>/application/delete/`. The primary
+archetype is `delete-by-id`, which accepts an id, confirms the row exists, persists the deletion,
+and returns the deleted entity so the caller can render confirmation UI without an extra query.
+
+## Canonical signature
+
+Exact shape from `backend/src/@app/iam/tag/application/delete/iam-delete-tag-by-id.handler.ts`:
+
+```typescript
+/**
+ * @aurora-catalyst-generated
+ * @source cliter/iam/tag.aurora.yaml
+ */
+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 { Injectable, NotFoundException } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+
+@Injectable()
+export class IamDeleteTagByIdHandler {
+  constructor(
+    private readonly eventEmitter: EventEmitter2,
+    private readonly deleteByIdService: IamDeleteTagByIdService,
+    private readonly findByIdService: IamFindTagByIdService,
+  ) {}
+
+  @EmitEvent('iam.tag.deleted')
+  @Format(IamTagFieldSchema)
+  async main(id: string, constraint?: QueryStatement, handlerMeta?: HandlerMeta): Promise<IamTag> {
+    const tag = await this.findByIdService.main(id, constraint, handlerMeta);
+
+    if (!tag) {
+      throw new NotFoundException(`IamTag with id: ${id}, not found`);
+    }
+
+    await this.deleteByIdService.main(id, constraint, handlerMeta);
+
+    return tag;
+  }
+}
+```
+
+Role of each moving part:
+
+- **`@EmitEvent('iam.tag.deleted')`** — fires after a successful `main()`. If the find returns empty
+  and `NotFoundException` is thrown, no event is emitted.
+- **`@Format(IamTagFieldSchema)`** — applied because the delete handler **returns** the deleted
+  entity, not a void or boolean. The decorator reshapes the returned object using the same schema
+  that find/paginate handlers use.
+- **`find` before `delete`** — the find confirms existence (so the handler can throw
+  `NotFoundException` instead of silently no-op-ing), and the returned reference is what the handler
+  ultimately sends back.
+- **Return value is the pre-delete snapshot** — the service is called after the find, so by the time
+  the handler returns, the row is gone. Returning the snapshot preserves the caller's ability to
+  display "tag 'foo' was deleted" without a second query.
+
+## `NotFoundException` pattern
+
+Same contract as update and find-by-id: the handler owns the "not found" semantics. The delete
+service would happily run a zero-row DELETE without complaint, masking a client error. The handler's
+find-first step makes the failure loud.
+
+## Cascading considerations
+
+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.
+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`).
+3. **Event-driven cascade** — other handlers listen to the emitted `*.deleted` event and perform
+   their own cleanup. Decouples modules but is harder to reason about; reserve for
+   cross-bounded-context teardown.
+
+Do not mix strategies for the same relation. Pick one explicitly.
+
+## Expected errors
+
+- **`NotFoundException`** — missing row after the find.
+- **`ConflictException`** / `BadRequestException` — when a domain rule forbids deletion (e.g., a tag
+  in use by active sessions cannot be deleted). Perform that check between the find and the delete
+  service call.
+
+## Archetype-specific anti-patterns
+
+- **Returning `void` or `boolean`.** The catalyst contract returns the deleted entity. Callers rely
+  on it.
+- **Deleting before validating existence.** Losing the distinction between "wasn't there" and "was
+  deleted successfully" produces silent client bugs.
+- **Manual `eventEmitter.emit(...)` after delete.** Let `@EmitEvent` do it. A manual call fires
+  twice or fires before the delete completes.
+- **Soft-delete logic in the handler.** If the entity supports soft delete, express that in the
+  domain model and the delete service; the handler is the same either way.

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

@@ -0,0 +1,186 @@
+# Read Handlers
+
+> **Prerequisite**: this reference applies only when the handler file already exists on disk — the
+> CLI generated it from a standard `find`, `findById`, `get`, or `paginate` 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
+
+Any handler under `@app/<pkg>/<module>/application/{find,get,paginate}/`. Read handlers do not emit
+events (there is no state change to broadcast) and do not mutate data. They shape the response via
+the `@Format(FieldSchema)` decorator.
+
+Four read archetypes exist, distinguished by what they return:
+
+| Archetype          | File pattern                        | Returns              | `NotFoundException` on empty? |
+| ------------------ | ----------------------------------- | -------------------- | ----------------------------- |
+| Find one by id     | `*-find-*-by-id.handler.ts`         | `Entity`             | Yes                           |
+| Find one by filter | `*-find-*.handler.ts` (no `-by-id`) | `Entity`             | Yes                           |
+| Get many           | `*-get-*.handler.ts`                | `Entity[]`           | No (empty array is valid)     |
+| Paginate           | `*-paginate-*.handler.ts`           | `Pagination<Entity>` | No (empty page is valid)      |
+
+## Canonical signatures
+
+All from `backend/src/@app/iam/tag/application/`.
+
+### `find-by-id`
+
+```typescript
+import { IamTag } from '@api/graphql';
+import { IamFindTagByIdService } from '@app/iam/tag';
+import { IamTagFieldSchema } from '@app/iam/tag/domain';
+import { Format, HandlerMeta } from '@aurorajs.dev/core-back';
+import { QueryStatement } from '@aurorajs.dev/core-common';
+import { Injectable, NotFoundException } from '@nestjs/common';
+
+@Injectable()
+export class IamFindTagByIdHandler {
+  constructor(private readonly findByIdService: IamFindTagByIdService) {}
+
+  @Format(IamTagFieldSchema)
+  async main(id: string, constraint?: QueryStatement, handlerMeta?: HandlerMeta): Promise<IamTag> {
+    const tag = await this.findByIdService.main(id, constraint, handlerMeta);
+
+    if (!tag) {
+      throw new NotFoundException(`IamTag with id: ${id}, not found`);
+    }
+
+    return tag;
+  }
+}
+```
+
+### `find` (by filter)
+
+```typescript
+@Injectable()
+export class IamFindTagHandler {
+  constructor(private readonly findService: IamFindTagService) {}
+
+  @Format(IamTagFieldSchema)
+  async main(
+    queryStatement?: QueryStatement,
+    constraint?: QueryStatement,
+    handlerMeta?: HandlerMeta,
+  ): Promise<IamTag> {
+    const tag = await this.findService.main(queryStatement, constraint, handlerMeta);
+
+    if (!tag) {
+      throw new NotFoundException(`IamTag not found`);
+    }
+
+    return tag;
+  }
+}
+```
+
+### `get`
+
+```typescript
+@Injectable()
+export class IamGetTagsHandler {
+  constructor(private readonly getService: IamGetTagsService) {}
+
+  @Format(IamTagFieldSchema)
+  async main(
+    queryStatement?: QueryStatement,
+    constraint?: QueryStatement,
+    handlerMeta?: HandlerMeta,
+  ): Promise<IamTag[]> {
+    return await this.getService.main(queryStatement, constraint, handlerMeta);
+  }
+}
+```
+
+### `paginate`
+
+```typescript
+@Injectable()
+export class IamPaginateTagsHandler {
+  constructor(private readonly paginateService: IamPaginateTagsService) {}
+
+  @Format(IamTagFieldSchema)
+  async main(
+    queryStatement?: QueryStatement,
+    constraint?: QueryStatement,
+    handlerMeta?: HandlerMeta,
+  ): Promise<Pagination> {
+    return await this.paginateService.main(queryStatement, constraint, handlerMeta);
+  }
+}
+```
+
+## Role of `@Format`
+
+`@Format(FieldSchema)` shapes the handler's return value using the same schema that `@ApplySchema`
+uses for write-side validation. It strips fields the schema marks as hidden, applies formatting
+rules, and resolves virtual fields. Put it on every read handler — the generator always emits it,
+and omitting it causes silent drift between read and write shapes.
+
+## `QueryStatement` with `include` for relations
+
+`queryStatement` is the client-facing filter/sort/pagination payload. `constraint` is the
+server-side scope (tenant isolation, permission filter). The two are merged by the service; the
+handler forwards them unchanged.
+
+To fetch relations in a single query, include them:
+
+```typescript
+const queryStatement: QueryStatement = {
+  where: { tenantId: handlerMeta.repositoryOptions?.tenantId },
+  include: [{ association: 'owner' }, { association: 'roles' }],
+  limit: 50,
+  offset: 0,
+};
+```
+
+Relations are declared in the aurora YAML; the field names (`'owner'`, `'roles'`) match the YAML
+`aggregateProperties`. If you are hand-writing a handler that needs a relation that the
+CLI-generated variant does not include, adjust the service-side default or pass the `include`
+through a hand edit to the handler — both are accepted, though adjusting the service is preferred
+because it keeps the handler regenerable.
+
+## Pagination response shape
+
+`Pagination` (imported from `@api/graphql`) has the shape:
+
+```typescript
+{
+  total: number;
+  count: number;
+  rows: Entity[];
+}
+```
+
+The paginate service fills all three fields. The handler does not reshape; it returns the service
+output verbatim (after `@Format` post-processing).
+
+## `NotFoundException` placement
+
+Only `find-by-id` and `find` throw. `get` and `paginate` return empty arrays/pages because "nothing
+matches the filter" is a valid, expected outcome — not an error.
+
+## Archetype-specific anti-patterns
+
+- **Emitting events from read handlers.** Reads do not change state; there is nothing to announce.
+  Do not add `@EmitEvent` here.
+- **Using `@ApplySchema` on reads.** That decorator is for validating incoming payloads. The
+  read-side equivalent is `@Format`.
+- **Re-querying the entity manually after the service call.** The service already returns it; a
+  second call duplicates round-trips.
+- **Throwing on empty results in `get` / `paginate`.** Treat emptiness as a normal result, not an
+  error.
+- **Leaking `constraint` details to the client.** `constraint` encodes server-side security scope;
+  do not serialize it back in the response or echo it in error messages.
+
+## Cross-reference
+
+The internals of `QueryStatement` (full shape, the 40+ `Operator` enum values, `include` semantics,
+and the current security gap where `formatRecord` does NOT recurse into included relations) are
+documented in
+[`catalyst-field-schema/references/query-statement.md`](../../catalyst-field-schema/references/query-statement.md).
+Read it whenever composing a custom `where`, reaching for an `Operator`, or loading a relation via
+`include` — especially when the relation loads an entity with masked fields (passwords, tokens).

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

@@ -0,0 +1,134 @@
+# Update Handler
+
+> **Prerequisite**: this reference applies only when the handler file already exists on disk — the
+> CLI generated it from a standard `update` or `updateById` 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 `*-update-*.handler.ts` under `@app/<pkg>/<module>/application/update/`. The primary
+archetype is `update-by-id`, which accepts a partial payload, fetches the existing row, computes a
+delta, and persists only the changed fields. Bulk updates (no `-by-id`) share the skeleton but skip
+the find-first step.
+
+## Canonical signature
+
+Exact shape from `backend/src/@app/iam/tag/application/update/iam-update-tag-by-id.handler.ts`:
+
+```typescript
+/**
+ * @aurora-catalyst-generated
+ * @source cliter/iam/tag.aurora.yaml
+ */
+import { IamTag, IamUpdateTagByIdInput } from '@api/graphql';
+import { IamFindTagByIdService, IamUpdateTagByIdService } from '@app/iam/tag';
+import { IamTagFieldSchema } from '@app/iam/tag/domain';
+import { ApplySchema, EmitEvent, HandlerMeta } from '@aurorajs.dev/core-back';
+import { Obj, QueryStatement } from '@aurorajs.dev/core-common';
+import { Injectable, NotFoundException } from '@nestjs/common';
+import { EventEmitter2 } from '@nestjs/event-emitter';
+
+@Injectable()
+export class IamUpdateTagByIdHandler {
+  constructor(
+    private readonly eventEmitter: EventEmitter2,
+    private readonly updateByIdService: IamUpdateTagByIdService,
+    private readonly findByIdService: IamFindTagByIdService,
+  ) {}
+
+  @EmitEvent('iam.tag.updated')
+  @ApplySchema(IamTagFieldSchema)
+  async main(
+    payload: IamUpdateTagByIdInput,
+    constraint?: QueryStatement,
+    handlerMeta?: HandlerMeta,
+  ): Promise<IamTag> {
+    const tag = await this.findByIdService.main(payload.id, constraint, handlerMeta);
+
+    if (!tag) {
+      throw new NotFoundException(`IamTag with id: ${payload.id}, not found`);
+    }
+
+    const dataToUpdate = Obj.diff(payload, tag);
+
+    await this.updateByIdService.main(
+      {
+        ...dataToUpdate,
+        id: payload.id,
+      },
+      constraint,
+      handlerMeta,
+    );
+
+    return await this.findByIdService.main(payload.id, constraint, handlerMeta);
+  }
+}
+```
+
+Role of each moving part:
+
+- **`constraint?: QueryStatement`** — extra criteria that scope the operation. Most commonly used
+  for multi-tenant isolation (ensuring the updated row belongs to the caller's tenant). Pass it
+  through to every service call unchanged.
+- **`Obj.diff(payload, tag)`** — from `@aurorajs.dev/core-common`. Computes the subset of fields
+  that differ between the incoming payload and the persisted row. The service therefore receives
+  only the fields that actually change, which keeps the UPDATE statement minimal and plays well with
+  auditing.
+- **Two `findByIdService.main()` calls** — the first validates existence (throw on missing); the
+  second returns the freshly-updated entity. Both receive the same `constraint`.
+- **`@EmitEvent('iam.tag.updated')`** — fires after a successful `main()`. If `NotFoundException`
+  throws, no event is emitted.
+
+## `Obj.diff()` pattern
+
+`Obj.diff(payload, existing)` answers the question "which fields in `payload` differ from
+`existing`?". Apply it so the service receives:
+
+- fields the client actually changed, plus
+- the `id` (explicitly re-added via `{ ...dataToUpdate, id: payload.id }`).
+
+The `id` is re-added because `Obj.diff` would omit it when both sides match, but the service needs
+it as the target key.
+
+## `NotFoundException` handling
+
+The handler owns "not found" semantics. The service does not throw on missing rows; it would simply
+perform a no-op UPDATE. Letting that happen silently masks client errors, so the handler fetches
+first and throws if the row is absent. Same pattern in `delete-by-id` and `find-by-id`.
+
+## Expected errors
+
+- **`NotFoundException`** — missing row after the first `findByIdService.main()` call.
+- **`ValidationException`** / field-level throws from `@ApplySchema` — surface automatically; no
+  manual re-throw.
+- **`BadRequestException`** / `ConflictException` — when business rules reject the transition (e.g.,
+  status `archived` cannot be updated, or the new slug collides in-tenant).
+
+## `HandlerMeta` flow
+
+```
+resolver.main()            constructs { timezone, repositoryOptions: { auditing } }
+  ↓
+handler.main(payload, constraint, handlerMeta)
+  ↓
+findByIdService.main(id, constraint, handlerMeta)  ← unchanged passthrough
+  ↓
+updateByIdService.main(payload, constraint, handlerMeta)  ← unchanged passthrough
+```
+
+The handler never mutates `handlerMeta`. It only forwards it. Any auditing/timezone effect happens
+at the repository layer by reading the meta on the way in.
+
+## Archetype-specific anti-patterns
+
+- **Sending the full payload to the update service.** Use `Obj.diff()`. Writing all fields, changed
+  or not, pollutes the audit log and masks real changes.
+- **Omitting the second `findByIdService.main()` call.** The handler contract returns the persisted
+  entity, not the payload-with-id. The second fetch accounts for server-side mutations (timestamps,
+  derived fields).
+- **Validation duplicated inside the update service.** `@ApplySchema` already validated the payload;
+  any domain check lives in the handler. The service stays a thin persistence step.
+- **Mutating `constraint` between calls.** Treat it as read-only and forward verbatim.

package/dist/templates/backend/application/.claude/skills/catalyst-nestjs-primitives/SKILL.md

@@ -0,0 +1,233 @@
+---
+name: catalyst-nestjs-primitives
+description: >
+  Catalog and guide for NestJS primitives in the Aurora Catalyst backend: custom decorators, guards,
+  interceptors, pipes, filters. Documents the three catalyst-authored primitives (`@Auth` composite
+  decorator, `AuthenticationJwtGuard`, `AuthorizationPermissionsGuard`), references upstream
+  primitives from `@aurorajs.dev/core-back` (`@Timezone`, `@Auditing`, `@CurrentAccount`,
+  `@ContentLanguage`, `@TenantPolicy`, `@TenantConstraint`, `Permissions`), the dual REST/GraphQL
+  context pattern via `Api.getRequestFromExecutionContext()`, and the `dPermissions.all` convention
+  on IamAccount. Trigger: writing or reasoning about a guard, interceptor, pipe, filter, or custom
+  decorator; protecting an endpoint with auth and permission checks; composing a custom composite
+  decorator with `applyDecorators`; understanding why every catalyst guard overrides `getRequest`;
+  understanding how `user.dPermissions.all` is read at guard time; deciding between `@Auth` and a
+  custom guard. Fires even if the user says only "add auth to this endpoint" or "I need a guard for
+  X". Does NOT apply to field-level validation (use `catalyst-field-schema`) and does NOT replace
+  full-module audits (use `catalyst-review-module`).
+license: MIT
+metadata:
+  author: aurora
+  version: '1.0'
+---
+
+## Step 0 — Reuse-first Gate (Read Before Anything Else)
+
+Before writing a new primitive, answer: **"is a custom primitive actually needed?"** In most cases
+it is not — catalyst offers an upstream decorator, an `@Auth` composite, or a `FieldSchema` rule
+that covers the intent. Primitives are hand-written (unlike handlers or field-schemas, which the CLI
+generates), so the gate here is NOT "do not bypass the generator" but **"do not duplicate an
+existing primitive or reinvent `@Auth`"**.
+
+Route every primitive task through one of these four branches.
+
+```
+Need a NestJS primitive?
+  │
+  ├── Does `@aurorajs.dev/core-back` already export it?   ───→ USE UPSTREAM
+  │   (@Timezone, @Auditing, @CurrentAccount,
+  │    @ContentLanguage, @TenantPolicy, @TenantConstraint, …)
+  │
+  ├── Is the task "protect an endpoint with auth +       ───→ USE @Auth('<pkg>.<mod>.<op>')
+  │   permission checks"?                                    (composite: Permissions +
+  │                                                           AuthenticationJwtGuard +
+  │                                                           AuthorizationPermissionsGuard)
+  │
+  ├── Is it actually field-level validation / formatting?───→ catalyst-field-schema
+  │   (maxLength, nullable, enum, timezone, password            (@ApplySchema, @Format,
+  │    hashing, format masking, …)                              @Sanitize, `rules`)
+  │
+  └── Truly new primitive needed?                         ───→ references/minimum-templates.md
+       (domain-specific orchestration, a cross-cutting          (and the dual-context
+        concern not covered above)                              override is non-negotiable
+                                                                for guards / interceptors)
+```
+
+Only when the first three branches do NOT apply does the fourth branch fire — and even then, the
+template you copy must respect catalyst's dual REST/GraphQL context pattern (see below).
+
+## When to Use
+
+- Writing a new guard, interceptor, pipe, exception filter, or custom decorator in catalyst backend.
+- Reasoning about an existing primitive (`@Auth`, `AuthenticationJwtGuard`,
+  `AuthorizationPermissionsGuard`) or deciding whether to extend it vs write a new one.
+- Choosing between `@Auth('<permission>')` and a handcrafted `@UseGuards(...)` — the answer is
+  always `@Auth`, and this skill explains why.
+- Understanding the `dPermissions.all` shape consumed by permission-aware guards.
+- Understanding why catalyst guards override `getRequest()` and what breaks when they do not.
+
+This skill is **REFERENCE / CATALOG** — it inventories what exists, routes creation through a
+reuse-first gate, and provides templates only as a last resort.
+
+## Inventory — Catalyst-authored primitives
+
+| Primitive                       | Type                | Purpose                                                                                                                                                                                                                                                                                                 | Path                                                                            |
+| ------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
+| `@Auth(...permissions)`         | Composite decorator | Protects an endpoint via `Permissions(...)` metadata + `UseGuards(AuthenticationJwtGuard, AuthorizationPermissionsGuard)`. Canonical endpoint-protection decorator used on every resolver / controller.                                                                                                 | `backend/src/@aurora/decorators/auth.decorator.ts`                              |
+| `AuthenticationJwtGuard`        | Guard               | Extends passport's `AuthGuard('jwt')`. Overrides `getRequest()` via `Api.getRequestFromExecutionContext(context)` so it works in both REST (HTTP context) and GraphQL (execution context). Throws `UnauthorizedException` with `statusCode: 401` when the JWT is missing or invalid.                    | `backend/src/@app/authorization-code/guards/authentication-jwt.guard.ts`        |
+| `AuthorizationPermissionsGuard` | Guard               | Reads the `permissions` reflection metadata set by `Permissions(...)` (i.e., by `@Auth(...)`) and checks if the authenticated user's `dPermissions.all` intersects the required set via `Arr.intersects`. Same dual-context pattern. Throws `UnauthorizedException` with `statusCode: 403` on mismatch. | `backend/src/@app/authorization-code/guards/authorization-permissions.guard.ts` |
+
+That is the entire catalyst-authored primitive surface on disk today: one composite decorator and
+two guards. No custom pipes, interceptors, filters, or middleware exist in the repo. If a new
+pattern needs expressing, it is more likely a FieldSchema concern or belongs behind `@Auth` than a
+fresh primitive.
+
+## Inventory — Upstream primitives (`@aurorajs.dev/core-back`)
+
+> **Snapshot as of change-archival time.** This is a catalog, not documentation. Upstream semantics
+> may evolve; the canonical reference is the source package. When creating any custom primitive,
+> re-check the upstream package index first — a new decorator may have landed since this snapshot.
+
+| Primitive               | Purpose (one line)                                                                                                                                                                   | Source                                   |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------- |
+| `@Timezone()`           | Param decorator — extracts timezone from the request headers / context.                                                                                                              | `@aurorajs.dev/core-back` (`decorators`) |
+| `@Auditing()`           | Param decorator — extracts auditing metadata (user id, timestamp, correlation id).                                                                                                   | `@aurorajs.dev/core-back` (`decorators`) |
+| `@CurrentAccount()`     | Param decorator — extracts the authenticated account object from the request.                                                                                                        | `@aurorajs.dev/core-back` (`decorators`) |
+| `@ContentLanguage()`    | Param decorator — extracts the content-language preference from the request.                                                                                                         | `@aurorajs.dev/core-back` (`decorators`) |
+| `@TenantPolicy()`       | Method / class decorator — enforces tenant write scope (use on mutations).                                                                                                           | `@aurorajs.dev/core-back` (`decorators`) |
+| `@TenantConstraint()`   | Method / class decorator — enforces tenant read scope (use on queries).                                                                                                              | `@aurorajs.dev/core-back` (`decorators`) |
+| `Permissions(...names)` | Metadata decorator — sets the `permissions` reflection key read by `AuthorizationPermissionsGuard`. Rarely used directly; prefer `@Auth(...)` composite which wires it consistently. | `@aurorajs.dev/core-back` (`decorators`) |
+
+Everything not listed here that a catalyst resolver / controller uses (`@Args`, `@Body`,
+`@Mutation`, `@Query`, `@Resolver`, `@Controller`, `@Post`, `@Get`, `@Put`, `@Delete`, …) is
+standard NestJS and covered by the NestJS documentation. Do not duplicate NestJS docs here.
+
+## Dual REST/GraphQL Context Pattern (Catalyst-specific)
+
+Catalyst exposes every module over both REST and GraphQL. A guard, interceptor, or param decorator
+that reads the request MUST work in both contexts. NestJS's default behavior in `CanActivate` /
+`NestInterceptor` / `createParamDecorator` assumes an HTTP execution context and returns the wrong
+object (or throws) under GraphQL.
+
+The fix is a single helper from `@aurorajs.dev/core-back`:
+
+```typescript
+Api.getRequestFromExecutionContext(context: ExecutionContext): Request
+```
+
+It inspects the context type and returns the correct request object for either REST or GraphQL.
+Every catalyst guard overrides `getRequest()` to call it. The real shape, from
+`backend/src/@app/authorization-code/guards/authentication-jwt.guard.ts`:
+
+```typescript
+import { Api } from '@aurorajs.dev/core-back';
+import { ExecutionContext, Injectable, UnauthorizedException } from '@nestjs/common';
+import { AuthGuard } from '@nestjs/passport';
+
+@Injectable()
+export class AuthenticationJwtGuard extends AuthGuard('jwt') {
+  getRequest<Request>(context: ExecutionContext): Request {
+    return Api.getRequestFromExecutionContext(context);
+  }
+
+  handleRequest<AccountResponse>(err: any, user: AccountResponse): AccountResponse {
+    if (err || !user) {
+      throw (
+        err ||
+        new UnauthorizedException({
+          statusCode: 401,
+          message: 'OAuthAccessToken not allowed',
+        })
+      );
+    }
+    return user;
+  }
+}
+```
+
+`AuthorizationPermissionsGuard` follows the same pattern (see its path above). Any NEW custom guard
+or interceptor in catalyst MUST include the override — otherwise the primitive silently works in one
+API style and breaks in the other. This is the single most important rule in this skill.
+
+## `dPermissions.all` Convention (Catalyst-specific)
+
+Permission-aware guards in catalyst read the authenticated user's permissions from a pre-computed
+array on the `IamAccount` entity:
+
+```typescript
+const accountPermissions = this.getRequest(context).user.dPermissions.all;
+```
+
+**Shape** — `dPermissions` is a jsonb field on IamAccount (`iam-account.field-schema.ts`:
+`{ name: 'dPermissions', type: 'jsonb', nullable: false }`). Its Sequelize model types it as `any`;
+at runtime the shape is `{ all: string[] }` where `.all` is the flattened array of every permission
+string the account has.
+
+**Why the `d` prefix** — stands for **denormalized**. The field caches permissions derived from the
+account's roles so permission-aware guards can read it in O(1) without traversing relations at guard
+time. How `dPermissions` is populated is an iam/account concern (sagas, role-change event handlers)
+and out of scope for this skill.
+
+**How guards consume it** — `AuthorizationPermissionsGuard` reads `user.dPermissions.all` and
+compares against the required permissions via `Arr.intersects(required, user.dPermissions.all)` from
+`@aurorajs.dev/core-common`. Any custom permission-aware primitive you write MUST follow the same
+pattern. Do not traverse roles. Do not read a different field. Use `Arr.intersects` for the check —
+it handles edge cases (empty arrays, non-array inputs) consistently.
+
+## Anti-patterns
+
+1. **Writing a pipe for field-level validation.** → Use `@ApplySchema(FieldSchema)` from
+   `catalyst-field-schema`. The schema's `maxLength`, `nullable`, `enumOptions`, and `rules` already
+   enforce what a pipe would re-implement. A pipe duplicates the check and drifts from the
+   declarative contract.
+
+2. **Writing an interceptor for audit logging.** → Use the upstream `@Auditing()` decorator on the
+   resolver / controller parameter. It extracts user id, timestamp, and correlation id consistently;
+   an interceptor has to reinvent that extraction and reconcile with
+   `HandlerMeta.repositoryOptions.auditing`.
+
+3. **Writing a guard for authentication / authorization.** → Use `@Auth('<pkg>.<mod>.<op>')`
+   composite. It applies `Permissions(...)` metadata + both guards in the correct order. A
+   hand-rolled guard skips the metadata hook and breaks permission checks silently.
+
+4. **Writing a custom guard or interceptor WITHOUT overriding `getRequest()` via
+   `Api.getRequestFromExecutionContext(context)`.** → The primitive silently works in only one API
+   style. If it reads from the HTTP request, it fails on GraphQL queries; vice versa. Every catalyst
+   guard / interceptor that touches the request MUST override.
+
+5. **Hardcoding permission strings in `@UseGuards(...)` directly.** → Use `@Auth('<permission>')`
+   composite so `Permissions(...)` metadata + both guards are wired consistently. Manually wiring
+   `@UseGuards(AuthenticationJwtGuard, AuthorizationPermissionsGuard)` + `Permissions(...)`
+   separately is noise that drifts across files.
+
+6. **Re-documenting upstream decorators inside this skill's references.** → The upstream catalog
+   above is a SNAPSHOT with source pointers, not inline documentation. Upstream semantics may
+   evolve; re-documenting creates drift. When a new upstream decorator is worth knowing about, add a
+   ROW to the catalog — do not copy its implementation notes.
+
+## Naming Conventions
+
+| Primitive type             | File name pattern       | Placement                                                                              |
+| -------------------------- | ----------------------- | -------------------------------------------------------------------------------------- |
+| Guard                      | `<name>.guard.ts`       | `@app/<bc>/<mod>/guards/` (module-specific) or `@aurora/guards/` (cross-cutting, rare) |
+| Interceptor                | `<name>.interceptor.ts` | `@app/<bc>/<mod>/interceptors/` or `@aurora/interceptors/`                             |
+| Pipe                       | `<name>.pipe.ts`        | `@app/<bc>/<mod>/pipes/` or `@aurora/pipes/`                                           |
+| Exception filter           | `<name>.filter.ts`      | `@aurora/filters/` (exception filters are typically cross-cutting)                     |
+| Custom composite decorator | `<name>.decorator.ts`   | `@aurora/decorators/` (cross-cutting — see `@Auth`)                                    |
+| Custom param decorator     | `<name>.decorator.ts`   | `@aurora/decorators/` (cross-cutting) or module-specific as needed                     |
+
+The dot-type suffix is the NestJS convention and aligns with how `catalyst-review-module` audits
+naming coherence.
+
+## Cross-references
+
+- **`catalyst-handler-composer`** — where `@Auth`, `@Timezone`, `@Auditing` land (on resolvers and
+  controllers). Handler-composer references this skill back; the two are complementary.
+- **`catalyst-field-schema`** — the destination for any "pipe for field validation" redirection. If
+  the task is about a field's `maxLength`, `nullable`, `enumOptions`, or `rules`, go there.
+- **`catalyst-project-structure`** — where new primitive files go physically (`@aurora/decorators/`
+  for cross-cutting composites, `@app/<bc>/<mod>/guards/` for module-scoped guards, etc.).
+- **`catalyst-backend-testing`** — testing guards and interceptors including the dual-context
+  pattern: test doubles MUST fake both `'http'` and `'graphql'` execution context types to exercise
+  the `Api.getRequestFromExecutionContext()` override in both branches. Covers `TestingModule`
+  setup, mocking request shape, and the e2e supertest + seeded `dPermissions.all` pattern for
+  `@Auth`-protected endpoint tests.