@aurorajs.dev/catalyst-cli 1.0.2 → 1.1.3

package/dist/templates/backend/application/.claude/skills/catalyst-project-structure/SKILL.md

@@ -10,7 +10,7 @@ description: >
 license: MIT
 metadata:
   author: aurora
-  version: '3.0'
+  version: '3.1'
   auto_invoke: >
     Creating a new file under backend/src/@(api|app|aurora|bridges)/; planning a new module,
     controller, handler, service, port, adapter, or bridge; user asks "where does X go"; 
@@ -78,7 +78,7 @@ memory `[CLI scaffold vs codegen]` for the `.ts` (scaffold) vs `.eta` (regenerab
 | **API**            | `src/@api/[bc]/[module]/`                | Entry points (REST/GraphQL), DTOs, Resolvers   | YES (incl. generated files via `.origin`)          |
 | **Application**    | `src/@app/[bc]/[module]/application/`    | Handlers and services per operation            | YES (incl. generated files via `.origin`)          |
 | **Domain**         | `src/@app/[bc]/[module]/domain/`         | Field schemas, value objects, types            | YES (generated; hand-written sub-files allowed)    |
-| **Infrastructure** | `src/@app/[bc]/[module]/infrastructure/` | Sequelize models, repositories, mocks          | YES (incl. generated files)                        |
+| **Infrastructure** | `src/@app/[bc]/[module]/infrastructure/` | Drizzle schema (`*.schema.ts`, `pgTable`) + repository classes (`*.repository.ts`, extending `DrizzleCatalystRepository`) | YES (incl. generated files)                        |
 | **Shared**         | `src/@aurora/`                           | Cross-BC infrastructure (decorators, modules)  | YES — this is hand-written, custom for the project |
 | **Cross-BC**       | `src/@bridges/`                          | Ports + adapters bridging two bounded contexts | YES — hand-written, follows cross-BC skill         |
 
@@ -93,9 +93,9 @@ freely.
 
 NestJS `@Module()` declarations are **composition roots**, not domain code. They wire controllers
 (`@api/`), handlers + services + repositories (`@app/`), and cross-BC adapters (`@bridges/`) into a
-single DI container. Conceptually they belong to all three layers at once.
+single DI container.
 
-**Convention in Aurora Catalyst**: every BC's `.module.ts` lives in `@api/<bc>/<bc>.module.ts`.
+**Convention**: every BC's `.module.ts` lives in `@api/<bc>/<bc>.module.ts`.
 
 | Module kind              | Path                                                      | Reason                                                |
 | ------------------------ | --------------------------------------------------------- | ----------------------------------------------------- |
@@ -105,63 +105,19 @@ single DI container. Conceptually they belong to all three layers at once.
 | App root                 | `src/app.module.ts`                                       | NestJS bootstrap entrypoint                           |
 
 Every module lives **where its feature lives**, except BC composition roots, which live in
-`@api/<bc>/`. That's the asymmetry — and it's intentional.
+`@api/<bc>/`. That asymmetry is intentional.
 
-### Why `@api/` and not `@app/` for BC composition roots
+**WHY `@api/` and not `@app/`** — the dependency direction is `@api → @app → domain` (with
+`@bridges` to the side). `@app` knows nothing about `@api`: handlers and repositories run without
+REST or GraphQL. If the module lived in `@app/<bc>/` it would have to register controllers and
+resolvers from `@api/`, inverting that arrow into a cycle (`@app ↔ @api`) and breaking the property
+"the domain runs without presentation". Keeping the module in `@api/` continues the existing
+direction (outer layer imports inner). Read `@api/` as "everything the outside world touches of this
+BC" — endpoints, DTOs, AND the `<bc>.module.ts` that other modules import (`imports: [IamModule]`).
 
-The dependency direction in Aurora Catalyst hexagonal layering is:
-
-```
-@api → @app → domain
-   ↘     ↗
-   @bridges
-```
-
-`@app` knows nothing about `@api`. Handlers, services, and repositories function without REST or
-GraphQL — that's the proof-of-separation: you could swap the entire `@api/` layer and the
-application layer would not notice.
-
-If the `.module.ts` lived in `@app/<bc>/`, it would have to register controllers and resolvers from
-`@api/`. That forces `@app` to import from `@api`, **inverting the dependency arrow**:
-
-```
-@app ↔ @api   ← circular dependency at the architecture level
-```
-
-NestJS resolves it at runtime (TypeScript doesn't care about layer rules), but conceptually it's a
-ring, not a stack. You lose the property "the domain runs without presentation."
-
-Keeping the module in `@api/` is **continuing the existing direction**: the outer layer (api)
-already imports from the inner layer (app) via controllers. The module file participating in that
-same direction is consistent, even if the module file itself is "more than just API."
-
-### Why not a dedicated `@composition/` layer
-
-Pure hexagonal would put composition roots in their own layer above api/app/bridges. The cost in
-Aurora:
-
-- New path alias to maintain in `tsconfig.json`
-- Migrate every BC module + `bridges.module.ts` + `authentication.module.ts`
-- Patch Cliter codegen templates
-- Update every skill that references `@api/<bc>/<bc>.module.ts`
-
-Benefit: architectural purism. Real-world impact on developers: zero (NestJS DI works the same,
-imports are equally discoverable).
-
-**Decision**: don't refactor. Document the convention so the next developer or AI knows it was a
-deliberate trade-off, not an oversight.
-
-### What `@api/` means in Aurora Catalyst
-
-Read `@api/` as "**everything the outside world touches of this BC**":
-
-- HTTP endpoints (controllers)
-- GraphQL endpoints (resolvers)
-- DTOs that cross the wire
-- The `<bc>.module.ts` — the NestJS DI handle other modules import to consume the BC
-
-Under that reading, the module file fits naturally. It's not "an HTTP endpoint" but it IS the public
-contract for `imports: [IamModule]` consumers.
+> A dedicated `@composition/` layer would be "purer" hexagonal, but the cost (new tsconfig alias,
+> migrate every BC module + bridges + authentication, patch Cliter templates, update every skill)
+> buys zero developer benefit. Deliberate trade-off, not an oversight — don't refactor.
 
 ---
 
@@ -169,16 +125,19 @@ contract for `imports: [IamModule]` consumers.
 
 Sometimes a BC needs hand-written REST/GraphQL endpoints that are NOT CRUD on a Cliter-managed
 aggregate. Examples: OAuth2 token issuance (`POST /api/o-auth/token`), the JWKS endpoint
-(`GET /.well-known/jwks.json`), webhook receivers, protocol flows. These are **first-class
-features of the BC**, not Cliter-managed aggregates.
+(`GET /.well-known/jwks.json`), webhook receivers, protocol flows. These are **first-class features
+of the BC**, not Cliter-managed aggregates.
 
-### The convention is: SAME shape as a Cliter aggregate, barrel + spread into `<bc>.module.ts`
+### The convention: SAME shape as a Cliter aggregate, barrel-and-spread into `<bc>.module.ts`
 
 Each Cliter aggregate has an `index.ts` barrel (e.g. `@api/o-auth/application/index.ts`) that
-imports controllers + resolvers from their subdirs and exports them as ARRAYS
-(`OAuthApplicationApiControllers`, `OAuthApplicationApiResolvers`) which `<bc>.module.ts` then
-spreads into its `controllers:` / `providers:` arrays. Hand-written flows follow the SAME
-pattern.
+imports its controllers + resolvers and re-exports them as ARRAYS (`OAuthApplicationApiControllers`,
+`OAuthApplicationApiResolvers`), which `<bc>.module.ts` then spreads into its `controllers:` /
+`providers:` arrays. **Hand-written flows follow the SAME pattern** — a `<flow>/` dir with the same
+subdir layout and a barrel, spread into the generated `<bc>.module.ts`. No dedicated
+`<flow>.module.ts`: a flow is a feature of the BC, not its own BC, so splitting it into a separate
+NestJS module fragments the BC's surface for no benefit. The familiarity matters: the next reader
+sees ONE convention for aggregates and flows, not two.
 
 ```
 @api/<bc>/<flow>/
@@ -193,26 +152,13 @@ pattern.
     └── <flow>.graphql
 ```
 
-The familiarity matters: the next person reading the code sees the SAME directory structure
-for aggregates and flows and doesn't have to learn two conventions.
-
 ### `<flow>/index.ts` shape (mirrors aggregate barrels)
 
 ```typescript
 // @api/<bc>/<flow>/index.ts
-export { <FlowFooController>, <FlowBarController> };
-export { <FlowFooResolver> };
-export { <FlowFooHandler>, <FlowBarHandler> };
-
-import { <FlowFooController> } from './controllers/<foo>.controller';
-import { <FlowBarController> } from './controllers/<bar>.controller';
-import { <FlowFooResolver> } from './resolvers/<foo>.resolver';
-import { <FlowFooHandler> } from '@app/<bc>/<feature>/application/<action>/<foo>.handler';
-import { <FlowBarHandler> } from '@app/<bc>/<feature>/application/<action>/<bar>.handler';
-
 export const <Bc>FlowsApiControllers = [<FlowFooController>, <FlowBarController>];
-export const <Bc>FlowsApiResolvers = [<FlowFooResolver>];
-export const <Bc>FlowsApiHandlers = [<FlowFooHandler>, <FlowBarHandler>];
+export const <Bc>FlowsApiResolvers   = [<FlowFooResolver>];
+export const <Bc>FlowsApiHandlers    = [<FlowFooHandler>, <FlowBarHandler>];
 ```
 
 ### Registration in the Cliter-generated `<bc>.module.ts`
@@ -220,48 +166,36 @@ export const <Bc>FlowsApiHandlers = [<FlowFooHandler>, <FlowBarHandler>];
 ```typescript
 // @aurora-catalyst-generated <bc>/<bc>.module.ts (header preserved)
 import { <Bc>ApplicationApiControllers, <Bc>ApplicationApiResolvers } from './application';
-// Manually maintained — hand-written flow barrel.
 import { <Bc>FlowsApiControllers, <Bc>FlowsApiHandlers, <Bc>FlowsApiResolvers } from './flows';
 
 @Module({
   controllers: [
     ...<Bc>ApplicationApiControllers,
-    /* ...other Cliter aggregates */
-    // Manually maintained — flow controllers.
-    ...<Bc>FlowsApiControllers,
+    ...<Bc>FlowsApiControllers,        // spread the flow barrel
   ],
   providers: [
     ...<Bc>ApplicationApiResolvers,
-    /* ...other Cliter aggregates */
-    // Manually maintained — flow resolvers + composite/non-aggregate handlers.
     ...<Bc>FlowsApiResolvers,
     ...<Bc>FlowsApiHandlers,
-    // Manually maintained — any sub-handlers that inject local services + repos.
-    <SubHandlerA>,
+    <SubHandlerA>,                     // sub-handlers needing intra-module DI
     <SubHandlerB>,
   ],
 })
 export class <Bc>Module {}
 ```
 
-The "manually maintained" sections of `<bc>.module.ts` shrink to: import the flow barrel,
-spread its three arrays, plus any sub-handlers that need intra-module DI to the BC's
-generated services. Cliter's three-way merge handles the regen.
-
-### Why NOT a dedicated `<flow>.module.ts`
+Spreading the flow arrays into the generated module IS the convention — it is not "polluting" the
+module. The three-way merge reconciles it; conflicts surface as `.origin` and are rare because the
+spread lines are stable.
 
-An earlier version of this convention recommended creating a dedicated `<flow>.module.ts`
-imported by `app.module.ts` alongside the BC module. That was rejected because:
+### Composite handlers — one business flow, two transports
 
-1. **Breaks the project's barrel-and-spread convention.** Every Cliter aggregate uses the
-   `index.ts` pattern; hand-written flows that diverge force the reader to learn two
-   conventions for the same kind of thing.
-2. **Creates artificial module boundaries inside a single BC.** A "flow" is not its own
-   bounded context — it's a feature of the existing BC. Splitting it into its own NestJS
-   module fragments the BC's surface area without functional benefit.
-3. **The supposed benefit (no manual code in `<bc>.module.ts`) was false.** `<bc>.module.ts`
-   already has manually-maintained entries for sub-handlers, cross-BC adapters, retention
-   crons, etc. Adding three spread lines does not change that reality.
+When the same business flow is exposed over BOTH REST and GraphQL (e.g., OAuth token issuance via
+`POST /api/o-auth/token` AND the GraphQL `oAuthCreateCredentials` mutation), all business logic —
+including dispatch between variants (PASSWORD vs REFRESH_TOKEN vs ...) — MUST live in a single
+handler in `@app/<bc>/<flow>/application/`. The controllers and resolvers parse the transport shape
+and call that handler. They MUST NOT each implement their own dispatch. See
+`catalyst-handler-composer` SKILL.md, "Composite handlers", for the dispatch pattern.
 
 ### Worked example — OAuth2 flows in this repo
 
@@ -281,17 +215,11 @@ imported by `app.module.ts` alongside the BC module. That was rejected because:
 ├── create/o-auth-create-token.handler.ts    (composite — dispatches PASSWORD vs REFRESH_TOKEN)
 ├── password/issue-token-password.handler.ts (sub-handler — injected by composite)
 └── refresh/issue-token-refresh.handler.ts   (sub-handler — injected by composite)
-
-@app/o-auth/jwks/application/
-└── get/o-auth-get-jwks.handler.ts           (JWKS builder)
 ```
 
-`@api/o-auth/o-auth.module.ts` (Cliter-generated, manually-maintained sections):
-- Imports `OAuthFlowsApiControllers` + `OAuthFlowsApiResolvers` + `OAuthFlowsApiHandlers` from
-  `./flows`.
-- Spreads them in the module's `controllers:` / `providers:` arrays.
-- Still registers `IssueTokenPasswordHandler` + `IssueTokenRefreshHandler` directly
-  (sub-handlers — the composite injects them, and they need the local OAuth services).
+`@api/o-auth/o-auth.module.ts` imports `OAuthFlowsApiControllers` + `OAuthFlowsApiResolvers` from
+`./flows` and spreads them; the composite + sub-handlers come in via `OAuthFlowsHandlers` from
+`@app/o-auth/flows`.
 
 ### Antipattern — flat files in the directory root
 
@@ -302,155 +230,137 @@ imported by `app.module.ts` alongside the BC module. That was rejected because:
 └── <flow>.graphql                ← FLAT — wrong
 ```
 
-If you find yourself writing this layout, STOP and apply the canonical structure with
-`controllers/` + `resolvers/` + `graphql/` subdirs. The flat layout looks "lighter" but it
-fragments the convention: the next aggregate-like reader of this BC has to switch mental models
-between "subdirs" (aggregates) and "flat" (flows). Pick one — and the project picked subdirs.
+Apply the canonical `controllers/` + `resolvers/` + `graphql/` subdirs instead. The flat layout
+looks "lighter" but forces the reader to switch mental models between "subdirs" (aggregates) and
+"flat" (flows). The project picked subdirs.
 
-### Antipattern — registering hand-written code in the generated BC module
+### Antipattern — a parallel shadow module
 
-```typescript
-// @api/<bc>/<bc>.module.ts (Cliter-generated)
-@Module({
-  controllers: [
-    ...AggregateApiControllers,
-    HandWrittenController,           // ← WRONG — pollutes the generated module
-  ],
-  providers: [
-    ...AggregateApiResolvers,
-    HandWrittenResolver,             // ← WRONG
-    HandWrittenHandler,              // ← WRONG
-  ],
-})
-```
+Do NOT create a sibling top-level module (e.g. `@api/oauth/oauth.module.ts` next to
+`@api/o-auth/o-auth.module.ts`) to host hand-written controllers. That is the shadow-module
+antipattern: it ESCAPES Cliter by creating a parallel BC. The flow lives INSIDE the BC's directory
+and registers via the existing barrel-and-spread — a single composition root per BC.
 
-This forces every Cliter regen of the BC to reconcile your hand-written entries via `.origin`,
-even though semantically those entries are independent of the aggregate codegen. The dedicated
-module pattern eliminates that friction.
+---
 
-### Why a single hand-written `.module.ts` IS justified here (and IS NOT a shadow module)
+## Auxiliary / helper functions — placement by scope
 
-Earlier sections warn against creating "sibling top-level modules" (e.g.,
-`@api/oauth/oauth.module.ts` next to `@api/o-auth/o-auth.module.ts`) — that IS the shadow-module
-antipattern. The hand-written `<flow>.module.ts` is different:
+Not every piece of logic is a handler, service, guard, or adapter. Sometimes you need a **pure
+auxiliary function**: a plain function with no dependency injection, no NestJS decorators, no state
+— it takes input and returns output (or throws). Real examples in this repo:
+`oAuthSafeStringCompare`, `oAuthParseBasicAuth`, `hubValidateRedirectUri`.
 
-- It lives INSIDE the BC's directory (`@api/<bc>/<flow>/<flow>.module.ts`), not parallel to it.
-- It is IMPORTED by the BC's main module — there is a single composition root for the BC.
-- Its scope is narrow and named: one flow, one module.
+Where such a function lives is decided by ONE question: **how widely is it reused?** Location
+follows the consumer, not the conceptual origin of the logic. (A redirect-URI validator is
+conceptually "OAuth-ish", but if only hub consumes it and its errors are `hub.error.*`, it is a hub
+function.)
 
-The shadow-module antipattern is about ESCAPING Cliter by creating a parallel BC; the dedicated
-flow module is about ISOLATING hand-written code INSIDE an existing BC.
+### The scope decision tree
 
-### Composite handlers — one business flow, two transports
+```
+Who consumes this function?
+├─ ONE module only
+│     → @app/<bc>/<module>/shared/functions/<bc>-<verb>-<noun>.function.ts
+│
+├─ SEVERAL modules of the SAME bounded context
+│     → @app/<bc>/shared/functions/<bc>-<verb>-<noun>.function.ts
+│
+└─ SEVERAL bounded contexts (backend only)
+      → does NOT live in @app/. Upstream it to @aurorajs.dev/core-back.
+        This is a SEPARATE, concrete task (a cross-package change) — open a task to
+        upstream it; do NOT inline a core-back change into an unrelated feature PR.
+```
 
-When the same business flow is exposed over BOTH REST and GraphQL (e.g., OAuth token issuance via
-`POST /api/o-auth/token` AND the GraphQL `oAuthCreateCredentials` mutation), all business logic —
-including dispatch between variants (PASSWORD vs REFRESH_TOKEN vs ...) — MUST live in a single
-handler in `@app/<bc>/<flow>/application/`. The controllers and resolvers parse the transport
-shape and call that handler. They MUST NOT each implement their own dispatch.
+The first two tiers live inside the BC's `@app/` tree. The last two **leave the app** — they belong
+to the shared packages, and moving them is a deliberate cross-package task you schedule separately.
+WHY: an `@app/<bc>` function that another BC imports re-creates the cross-BC coupling the
+`@bridges/` layer exists to mediate; promoting a genuinely shared helper to `core-back` removes the
+coupling instead of hiding it.
 
-See `catalyst-handler-composer` SKILL.md, "Composite handlers" section, for the dispatch pattern
-and the antipattern detection.
+### Naming + the mandatory two-barrel rule
 
-### Worked example — OAuth2 flows in this repo
+| Aspect          | Convention                                  | Example                                      |
+| --------------- | ------------------------------------------- | -------------------------------------------- |
+| File            | `<bc>-<verb>-<noun>.function.ts`            | `hub-validate-redirect-uri.function.ts`      |
+| Exported symbol | `<bc><Verb><Noun>` (camelCase, bc-prefixed) | `hubValidateRedirectUri`                     |
+| Spec            | `<same>.function.spec.ts`, co-located       | `hub-validate-redirect-uri.function.spec.ts` |
 
-```
-@api/o-auth/oauth-flows/
-├── oauth-flows.module.ts                 ← dedicated module
-├── controllers/
-│   ├── issue-token.controller.ts         ← REST endpoint: POST /api/o-auth/token
-│   └── jwks.controller.ts                ← REST endpoint: GET /.well-known/jwks.json
-├── resolvers/
-│   └── issue-token.resolver.ts           ← GraphQL mutation: oAuthCreateCredentials
-└── graphql/
-    └── oauth-flows.graphql               ← schema fragment for the mutation
-```
+When you create a `shared/` directory, it MUST carry BOTH barrels:
 
-```
-@app/o-auth/issue-token/application/
-├── issue-token.handler.ts                ← composite dispatch (PASSWORD | REFRESH_TOKEN)
-├── issue-token-response.types.ts
-├── password/issue-token-password.handler.ts
-└── refresh/issue-token-refresh.handler.ts
-```
+- `shared/functions/index.ts` — re-exports each `*.function.ts`.
+- `shared/index.ts` — re-exports `./functions` (and any sibling like `./services`).
+
+Consumers import from the `shared` barrel (`@app/<bc>/<module>/shared`), not by reaching into the
+`functions/` file directly.
+
+> Note: `@app/o-auth/shared/` predates this convention — it has a single `shared/index.ts` that
+> re-exports each function file and NO `shared/functions/index.ts`. It is grandfathered; do NOT
+> retrofit it as part of unrelated work. New `shared/` directories use the two-barrel layout.
+
+### Anti-pattern — a pure function under `@bridges/.../adapters/`
+
+`@bridges/` is EXCLUSIVELY for cross-BC ports + adapters: injectable providers that bridge two
+bounded contexts (the 4-file port + token + adapter + bridge pattern — see skill
+`catalyst-cross-bounded-context-ports`). A pure stateless helper is NOT a bridge adapter: it has no
+port, it is not injectable, it does not bridge two BCs by itself. Placing it there mislabels a plain
+helper as cross-BC infrastructure plumbing.
 
-Both `issue-token.controller.ts` (REST) and `issue-token.resolver.ts` (GraphQL) call
-`IssueTokenHandler.main(input)`. The handler does the dispatch. The transports are slim parsers.
+A new-file write of any `@app/**/shared/functions/*.function.ts` triggers an advisory nudge from the
+`architecture-checkpoint` hook restating this decision tree.
 
 ---
 
 ## Decision trees
 
+The full reasoning for each branch lives in the sections above — these are quick routers.
+
 ### "I need a new file. Where does it go?"
 
 ```
 Is the file a CRUD operation on an aggregate?
-├─ YES → Declare it (or `additionalApis`) in cliter/<bc>/<module>.aurora.yaml
-│         and regenerate. Cliter creates the scaffold in the right places.
-└─ NO  → Continue ↓
-
-Is the file a hand-written REST/GraphQL endpoint that is NOT a Cliter-generated aggregate
-operation? (e.g., OAuth2 token endpoint, JWKS, custom webhooks, protocol flows)
-├─ YES → SEE the dedicated section "Hand-written protocol-flow endpoints" below.
-│         TL;DR: create a `<flow>/` directory under `@api/<bc>/` with the SAME shape Cliter
-│         uses for aggregates (`controllers/`, `resolvers/`, `graphql/` subdirs) PLUS a
-│         dedicated `<flow>.module.ts`. Do NOT put hand-written code flat in the directory,
-│         and do NOT register it in the Cliter-generated `<bc>.module.ts`.
-└─ NO  → Continue ↓
-
-Is the file a NestJS provider/service that other BCs need to consume?
-├─ YES → Declare a port in the CONSUMER BC at `@bridges/<consumer>/<feature>/ports/`,
-│         and an adapter in the SUPPLIER BC at `@bridges/<supplier>/<module>/adapters/`.
-│         Follow skill `catalyst-cross-bounded-context-ports`. Register both in `BridgesModule`.
-└─ NO  → Continue ↓
-
-Is the file a shared utility / decorator / module used by multiple BCs?
-├─ YES → Goes in `@aurora/`. Examples: `@aurora/decorators/`, `@aurora/modules/<feature>/`,
-│         `@aurora/services/`. Hand-written.
-└─ NO  → Continue ↓
-
-Is the file infrastructure-only (cron, retention, background tasks)?
-└─ Place it in the BC that OWNS the data, at `@app/<bc>/shared/services/`.
-   Register it (provider only — do NOT export) in the BC's `<bc>.module.ts`.
-   WHY: keeping it in `@aurora` would require an `@aurora → @app/<bc>` import, which is
-   an upward inversion forbidden by HR-PORTS-001. The service is concrete BC code
-   (it knows the BC's tables, env vars, aggregates) — so the whole file moves to
-   the BC, and the repository imports become intra-BC.
-   REAL EXAMPLE: `@app/o-auth/shared/services/token-retention.service.ts`
-   is registered as a provider in `@api/o-auth/o-auth.module.ts`.
-```
-
-### "I need to add a controller. Which module registers it?"
-
-```
-Is the controller for an aggregate already covered by Cliter (access-token, client, etc.)?
-└─ YES → Cliter handles registration via the auto-generated `<bc>.module.ts`. Just regen.
-
-Is the controller a hand-written protocol-flow endpoint (e.g., /oauth/token, /.well-known/jwks.json)?
-└─ It belongs in a DEDICATED `<flow>.module.ts` under `@api/<bc>/<flow>/`. The generated
-   `<bc>.module.ts` then imports that module. SEE the "Hand-written protocol-flow endpoints"
-   section below for the full shape.
-
-DO NOT create a sibling top-level module file (e.g., `@api/oauth/oauth.module.ts` next to
-`@api/o-auth/o-auth.module.ts`) to host hand-written controllers. That's the shadow-module
-antipattern. The dedicated `<flow>.module.ts` lives INSIDE the BC, not parallel to it.
-
-DO NOT mix hand-written controllers/resolvers into the Cliter-generated `<bc>.module.ts`'s
-`controllers:` / `providers:` arrays under a "manually maintained" comment. That blurs the
-Cliter regen surface and forces every regen to reconcile your edits via `.origin`. The dedicated
-module isolates hand-written code so Cliter regens of the BC do not touch it.
+├─ YES → Declare it (or `additionalApis`) in cliter/<bc>/<module>.aurora.yaml and regen.
+└─ NO  → ↓
+
+Is it a hand-written REST/GraphQL endpoint, NOT a Cliter aggregate op?
+(OAuth token endpoint, JWKS, webhooks, protocol flows)
+├─ YES → § "Hand-written protocol-flow endpoints". TL;DR: a `<flow>/` dir under @api/<bc>/ with the
+│         SAME subdir shape Cliter uses (controllers/ resolvers/ graphql/) + a barrel, spread into
+│         the generated <bc>.module.ts. NO dedicated <flow>.module.ts. NOT flat files.
+└─ NO  → ↓
+
+Is it a PURE auxiliary/helper function (plain fn, no DI, no decorators)?
+├─ YES → § "Auxiliary / helper functions". Place by reuse scope; naming <bc>-<verb>-<noun>.function.ts;
+│         two barrels required. NEVER under @bridges/.../adapters/.
+└─ NO  → ↓
+
+Is it a NestJS provider/service that OTHER BCs need to consume?
+├─ YES → Port in CONSUMER BC at @bridges/<consumer>/<feature>/ports/; adapter in SUPPLIER BC at
+│         @bridges/<supplier>/<module>/adapters/. Register both in BridgesModule.
+│         Skill: catalyst-cross-bounded-context-ports.
+└─ NO  → ↓
+
+Is it a shared utility / decorator / module used by multiple BCs?
+├─ YES → @aurora/ (decorators/, modules/<feature>/, services/). Hand-written.
+└─ NO  → ↓
+
+Is it infrastructure-only (cron, retention, background tasks)?
+└─ Place it in the BC that OWNS the data, at @app/<bc>/shared/services/, registered (provider only,
+   NOT exported) in the BC's <bc>.module.ts. WHY: living in @aurora would require an
+   @aurora → @app/<bc> import — an upward inversion forbidden by HR-PORTS-001. The service knows the
+   BC's tables/env/aggregates, so the whole file moves to the BC and its repo imports become intra-BC.
+   REAL EXAMPLE: @app/o-auth/shared/services/token-retention.service.ts, registered in o-auth.module.ts.
 ```
 
 ### "Two modules look like they overlap. What do I do?"
 
 ```
-Are both modules in the same bounded context conceptually?
-└─ YES → Merge: pick one (the generated one if it exists), move the hand-written controllers
-          and providers in, delete the redundant module file. Update `app.module.ts` imports.
-          The `@aurora-catalyst-generated` header is NOT a barrier — edit.
+Same bounded context conceptually?
+└─ YES → Merge: keep one (the generated one if it exists), move the hand-written controllers and
+          providers in, delete the redundant module file, update app.module.ts imports.
+          The @aurora-catalyst-generated header is NOT a barrier — edit.
 
-Are the modules in different bounded contexts (cross-BC dependency)?
-└─ Use ports + adapters via `@bridges/`. Skill: `catalyst-cross-bounded-context-ports`.
+Different bounded contexts (cross-BC dependency)?
+└─ Ports + adapters via @bridges/. Skill: catalyst-cross-bounded-context-ports.
 ```
 
 ---
@@ -466,27 +376,38 @@ o-auth-get-credentials.controller.ts             # plural for collection ops
 o-auth-paginate-credentials.controller.ts
 ```
 
-Module files: `<bc>.module.ts` for the BC's main module (Cliter-generated). For hand-written
-auxiliary modules in the same BC, use a descriptive suffix: `<bc>-<feature>.module.ts`.
+Module files: `<bc>.module.ts` for the BC's main module (Cliter-generated). A BC has a SINGLE
+composition root — do not hand-write extra `*.module.ts` files inside it (flows register via
+barrel-and-spread; see § "Hand-written protocol-flow endpoints").
 
-Bounded context names use `kebab-case` matching the YAML directory: `o-auth`, `iam`, `library`. The
+Bounded context names use `kebab-case` matching the YAML directory: `o-auth`, `iam`, `hub`. The
 corresponding URL prefixes also use kebab-case: `/api/o-auth/...`, NOT `/api/oauth/...`.
 
 ---
 
-## Installed bounded contexts (live list)
+## Installed bounded contexts
+
+The canonical, always-current source is the `cliter/` directory at the monorepo root — each
+subdirectory (except `business-rules/`, `harness-rules/`) is a bounded context with its
+`*.aurora.yaml` schemas. Do NOT maintain a duplicate list here; it rots immediately. To see what's
+installed, list `cliter/`. To add a BC, create its `cliter/<bc>/` schemas and run
+`catalyst generate back module ...`.
 
-The canonical source is `cliter/` at the monorepo root. As of this skill's last update:
+---
 
-| Path              | Bounded Context | Notes                                                                                |
-| ----------------- | --------------- | ------------------------------------------------------------------------------------ |
-| `cliter/iam/`     | `iam`           | Identity + Access Management (accounts, users, roles, tenants, permissions)          |
-| `cliter/o-auth/`  | `o-auth`        | OAuth2 (clients, applications, access/refresh/credential tokens, authorization-code) |
-| `cliter/library/` | `library`       | Sample library entities                                                              |
+## Test file placement
 
-If you add a new BC to `cliter/`, run `catalyst generate back module ...` and update this table.
+| Kind                     | Location                                                                            | Notes                                                                                                                                                                                                                                                                        |
+| ------------------------ | ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Unit `.spec.ts`          | Co-located next to the file under test (e.g. `handler.spec.ts` beside `handler.ts`) | Discovered by the default Jest config                                                                                                                                                                                                                                        |
+| App-level scaffold smoke | `backend/test/app.e2e-spec.ts`                                                      | Stays at `test/` root; not a BC acceptance test                                                                                                                                                                                                                              |
+| BC e2e / acceptance      | `backend/test/acceptance/<bounded-context>/`                                        | One folder per bounded context (or shared module) under test. Name it after the `cliter/<bc>` directory for Cliter-managed BCs (e.g. `o-auth`, `iam`, `hub`), or after the `@aurora`/`@app` module for hand-written features with no `cliter/` entry (e.g. `authentication`) |
 
----
+**Import style in acceptance tests**: use the `@`-aliases (`@api/`, `@app/`, `@aurora/`,
+`@bridges/`, `@config/`) for anything inside `src/@…/`. Both `test/jest-e2e.json` and
+`tsconfig.json` map these aliases to `src/@…/`, so the imports are location-independent — depth from
+`test/acceptance/<bc>/` does not matter. Only `src/app.module` and other top-level `src/` files that
+have no alias need a relative path (`../../../src/…`).
 
 ## Reference