@pattern-stack/codegen 0.9.1 → 0.10.0

package/README.md

@@ -193,6 +193,11 @@ detection:
 
 `codegen.config.yaml` in your project root:
 
+Definition directories (`entities_dir`, `events_dir`) are discovered
+recursively — a flat `entities/contact.yaml` and a domain-foldered
+`entities/crm/contact.yaml` are both picked up. Group definitions into
+per-domain subfolders freely; codegen walks the whole tree.
+
 ```yaml
 paths:
   backend_src: src

package/consumer-skills/bridge/SKILL.md

@@ -0,0 +1,265 @@
+---
+name: bridge
+description: Load when wiring the event-to-job bridge or authoring `@JobHandler.triggers` in a project that ran `codegen subsystem install bridge`. Triggers include declaring `triggers:` on a `@JobHandler`; deciding between an in-process subscriber, `eventFlow.publishAndStart`, and a bridge trigger; registering `BridgeModule.forRoot()` in `app.module.ts`; wiring the reserved `events_*` pools via `BRIDGE_RESERVED_POOLS`; same-aggregate ordering with a `concurrency` key; or running `codegen events consumers <type>` to find who reacts to an event.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+user-invocable: false
+---
+
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Event-to-Job Bridge
+
+The bridge is the durable, typed, observable path from *"an event was
+published"* to *"a job was started"* in your app. It is its own subsystem —
+the combiner between the `events` and `jobs` subsystems, owned by neither. You
+opt into it by running `codegen subsystem install bridge`, which vendors the
+runtime into `<paths.subsystems>/bridge/` (imported as
+`@shared/subsystems/bridge`) and adds a `bridge:` block to
+`codegen.config.yaml`.
+
+Use this skill when you want one event to fan out to one or more durable async
+jobs, authored by teams that don't know about each other. If you only need a
+cheap in-process reaction, or a request-path job the caller already knows by
+name, you probably want a lower tier instead — see the decision table below.
+
+## Mental model: three tiers of event-driven work
+
+You pick the tier by use case. The bridge is Tier 3.
+
+| Tier | Mechanism | Durability | Latency | Use for |
+|---|---|---|---|---|
+| 1. Subscribe | `@OnEvent('x.y')` / `IEventBus.subscribe()` in-process | None (at-most-once) | ~ms | metrics, cache busts, logs |
+| 2. Direct invoke | `eventFlow.publishAndStart(event, jobType, input)` | Yes (caller's tx) | ~1 poll cycle | request-path work, caller knows the job |
+| 3. Bridge | `@JobHandler({ triggers: [{ event, map, when }] })` | Yes (outbox + ledger) | 2–3 poll cycles | durable async fanout, decoupled authors |
+
+Tier 1 is events-only and never touches the bridge. Tier 2 and Tier 3 both
+flow through the bridge at runtime — the difference is *who declares the
+link*. In Tier 2 the caller writes the `publishAndStart` call explicitly; in
+Tier 3 the job declares `triggers:` and the link fires automatically whenever
+the event is published anywhere.
+
+**How a trigger actually runs (Tier 3).** When the events outbox drain claims
+a `domain_events` row, it inserts — in one per-event transaction — one ledger
+row in `bridge_delivery` plus one *wrapper* job in a reserved `events_*` pool,
+per matched trigger. A normal job worker claims the wrapper. The wrapper reads
+the ledger, evaluates your `when:` predicate, applies your `map:` function, and
+calls the orchestrator to start your real job in *its* declared pool, parented
+to the wrapper so cascade-cancel works. Then it marks the delivery `delivered`.
+The reserved `events_*` pools thus host cheap wrappers (high concurrency); your
+own pools host the actual work (concurrency tuned to its scarce resource).
+
+**The ledger is the source of truth.** `bridge_delivery` has a
+`UNIQUE (event_id, trigger_id)` constraint. That is the idempotency primitive
+— it dedups outbox replay, and it dedups the case where a caller uses
+`publishAndStart` AND the same job also declares a matching `triggers:` entry
+(exactly one execution per event/trigger pair, whichever path got there first).
+
+## Install and wiring
+
+```bash
+codegen subsystem install bridge
+```
+
+Config block (`codegen.config.yaml`):
+
+```yaml
+bridge:
+  backend: drizzle       # 'drizzle' (production) or 'memory' (tests)
+  multi_tenant: false    # pair with BridgeModule.forRoot({ multiTenant: true })
+```
+
+Register the module in `app.module.ts`:
+
+```ts
+import { BridgeModule } from '@shared/subsystems/bridge';
+
+BridgeModule.forRoot({ backend: 'drizzle', multiTenant: false }),
+```
+
+### Wire the reserved `events_*` pools
+
+The bridge wrappers run in three reserved pools — `events_inbound`,
+`events_change`, `events_outbound`. A worker process must actually *drain* them,
+or wrappers sit `pending` forever (and `BridgeModule` fails fast at boot). The
+exported `BRIDGE_RESERVED_POOLS` is the list of those three pool names — spread
+it into the active-pools list of your `JobWorkerModule.forRoot` (see the
+`subsystems` skill for the full wiring + order):
+
+```ts
+import { BRIDGE_RESERVED_POOLS } from '@shared/subsystems/bridge';
+import { JobWorkerModule } from '@shared/subsystems/jobs';
+
+JobWorkerModule.forRoot({
+  mode: 'embedded',
+  backend: 'drizzle',
+  // active pool names this worker drains — include the reserved lanes:
+  pools: ['interactive', 'batch', ...BRIDGE_RESERVED_POOLS],
+}),
+```
+
+Pool *definitions* (concurrency per lane) live in `codegen.config.yaml` under
+`jobs.pools`, not in `forRoot`; `JobWorkerModule.forRoot({ pools })` only names
+which lanes this process drains. (Alternatively, `JobWorkerModule.forRoot({
+allPools: true })` drains every pool including the reserved ones — that's what
+the standalone `worker.ts` uses.) Wrappers are cheap (read ledger → evaluate
+`when:` → start the user job → update ledger), so the reserved lanes can run at
+high concurrency safely.
+
+## Authoring triggers
+
+Triggers are **job-owned**. Declare them on the `@JobHandler` decorator of the
+job you want to run — never on the event side.
+
+```ts
+@JobHandler<SendWelcomeEmailInput>('send_welcome_email', {
+  pool: 'outbound_email',
+  triggers: [
+    {
+      event: 'user.created',
+      map: (e) => ({ userId: e.aggregateId, email: e.payload.email }),
+      when: (e) => e.payload.email !== undefined,  // optional
+    },
+  ],
+})
+export class SendWelcomeEmailJob extends JobHandlerBase<SendWelcomeEmailInput> {
+  // ...
+}
+```
+
+`map:` and `when:` are typed TS callbacks — they typecheck against the payload
+type of the event you named. They must be **self-contained**: no calls to
+project helpers, services, or imports. The codegen inlines the arrow body
+verbatim into the generated bridge registry, so anything outside the arrow's
+own scope will not be in scope there.
+
+After authoring or changing a trigger, regenerate the registry
+(`codegen entity new --all` or your project's gen-all task). Unknown event
+types referenced in `triggers[].event` fail the build at generation time —
+that is the build-time validation against the event registry, and it is the
+primary safety net.
+
+If `when:` returns false at runtime, the wrapper records the delivery as
+`skipped` (with a reason) and does not start your job.
+
+## Ordering
+
+**The default configuration gives parallelism, not ordering.** Two events of
+the same type may be processed concurrently; same-aggregate ordering is NOT
+guaranteed out of the box. Pick the knob that matches your real requirement:
+
+1. **`concurrency` key on the user job** *(recommended when ordering matters)*
+   — granular per-aggregate serialization, parallelism preserved across
+   unrelated aggregates. The `key` callback receives the job input:
+
+   ```ts
+   @JobHandler<ProvisionInput>('provision_workspace', {
+     concurrency: { key: (input) => input.accountId, collisionMode: 'queue' },
+     triggers: [/* ... */],
+   })
+   ```
+
+2. **`events_<direction>` pool `concurrency: 1`** *(blunt)* — serializes
+   **every** wrapper in that direction, i.e. every bridge fanout for that
+   direction end to end. Simplest config, highest throughput cost. Use only
+   when every event in the direction genuinely needs strict order.
+
+## When NOT to use the bridge
+
+The bridge adds 2–3 outbox poll cycles of latency (typically 1–3 s). If you
+need request-path durability at lower latency and the caller already knows the
+job, use the `IEventFlow` facade directly (Tier 2 — runs off the next poll
+cycle, in the caller's transaction):
+
+```ts
+constructor(private eventFlow: IEventFlow) {}
+
+async signup(input: SignupInput, tx: Tx): Promise<void> {
+  await this.eventFlow.publishAndStart(
+    'user.created',
+    'provision_workspace',
+    { userId: input.id },
+    { tx },
+  );
+}
+```
+
+`IEventFlow` exposes exactly two verbs: `publish()` and `publishAndStart()`.
+All request-path publishing goes through this facade, not through `IEventBus`
+directly. Tier 1 subscribers stay declarative (`@OnEvent`) and bypass it.
+
+Decision table:
+
+| Need | Tier | Pattern |
+|---|---|---|
+| Cheap in-process reaction (metrics, cache bust) | 1 | `@OnEvent('x.y')` or `IEventBus.subscribe` |
+| Request-path durable, caller knows the job | 2 | `eventFlow.publishAndStart(...)` |
+| Async fanout, decoupled authors, multiple handlers per event | 3 | `@JobHandler.triggers[]` (the bridge) |
+
+## Discovering fanout: `codegen events consumers <type>`
+
+```bash
+codegen events consumers user.created
+```
+
+Prints a greppable report with all three tiers and file:line citations:
+
+```
+Event: user.created
+Tier 3 — Bridge triggers (2):
+  - send_welcome_email#0     (src/jobs/send-welcome-email.job.ts:14)
+  - provision_workspace#0    (src/jobs/provision-workspace.job.ts:18)
+Tier 2 — Direct invoke via publishAndStart (1):
+  - src/use-cases/signup.uc.ts:42
+Tier 1 — Subscribers (1):
+  - MetricsListener.onCreate @OnEvent('user.created') at src/observability/metrics.ts:28
+```
+
+Unknown event types print a suggestion-bearing warning to stderr but the
+command still exits 0. If the scan finds zero `publishAndStart` call sites but
+`EventFlowService` exists in the codebase, a fallback warning prints — the AST
+scan can miss non-standard injection (property injection, dynamic dispatch);
+grep for `publishAndStart` to verify Tier 2 manually.
+
+## Multi-tenancy
+
+Set `multi_tenant: true` in the config block and pass
+`BridgeModule.forRoot({ backend: 'drizzle', multiTenant: true })`. When on,
+three write-side sites throw `MissingTenantIdError` if `tenantId === undefined`
+(explicit `null` passes, for deliberate cross-tenant work): the
+`publishAndStart` request-path entry, the wrapper handler entry, and the
+delivery-repo write boundary. Event metadata carries `tenantId` from the typed
+event bus; the bridge threads it into the job's `tenant_id` when it starts your
+job. Your bridge, events, and jobs configs must all agree on the flag.
+
+## Renaming or removing a trigger
+
+The generated `trigger_id` is `<jobType>#<index>` — stable across generations,
+so replays resolve to the same ledger row. Renaming a `@JobHandler('<name>')`
+changes that id, so in-flight `pending` deliveries with the old `trigger_id`
+become orphans: the wrapper detects the missing registry entry, marks the
+delivery `skipped` with `skip_reason='trigger_unregistered'`, and stops. No
+auto-migration, no replay. If you need the old deliveries to run under the new
+name, drain the queue before deploying the rename.
+
+## Do not
+
+- **Do not collapse the three tiers** into "the bridge is the only path."
+  Tier 1 stays valid for cheap in-process reactions; Tier 2 is the request-path
+  durable option; Tier 3 is async fanout. The right tool depends on durability
+  and latency.
+- **Do not put your `@JobHandler` classes on reserved `events_*` pools.**
+  Module init rejects it. Those pools host framework wrappers only; your work
+  lives in a pool you declare.
+- **Do not declare triggers on the event side.** Triggers are job-owned. The
+  events subsystem stays zero-knowledge about jobs.
+- **Do not reference helpers, services, or imports inside `map:` / `when:`.**
+  They are inlined verbatim into the generated registry and must be
+  self-contained.
+- **Do not skip regenerating the registry** after changing a trigger. The
+  build-time validation against the event registry only runs at generation; a
+  stale registry silently drifts from your decorators.
+- **Do not expect ordering from the default config.** Add a `concurrency` key
+  (granular) or set a reserved pool's `concurrency: 1` (blunt) when
+  same-aggregate order matters.
+- **Do not drop `tenantId`** when `multi_tenant: true`. Missing tenant context
+  throws `MissingTenantIdError` at the write-side enforcement sites.

package/consumer-skills/codegen/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: codegen
+description: >-
+  Load when working in a project that uses @pattern-stack/codegen to scaffold a
+  NestJS + Drizzle backend from YAML — i.e. when the request is to add or change
+  an entity / module / CRUD resource, generate code from `entities/*.yaml`, run
+  the `codegen` (aka `cdp`) CLI, install or wire an infrastructure subsystem, or
+  refresh the project after a package upgrade. This is the entry-point router;
+  it points at the focused `entities`, `subsystems`, `jobs`, `events`, `bridge`,
+  and `sync` skills for deep work.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+user-invocable: false
+---
+
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Using @pattern-stack/codegen in this project
+
+This project generates its backend (domain entities, repositories, services,
+controllers, DTOs, use cases, Drizzle schemas, NestJS modules) from YAML entity
+definitions, following Clean Architecture. You author small YAML files and run
+the `codegen` CLI; the generator owns a few directories and never touches the
+rest of your app.
+
+The CLI binary is `codegen` (alias `cdp`). Every noun supports `--json` for
+machine-readable output and `--cwd <path>` to target another project root.
+
+## Mental model
+
+- **You own**: `entities/*.yaml`, `events/*.yaml`, `app.module.ts`, `main.ts`,
+  `database.module.ts`, `codegen.config.yaml`, and your hand-written use cases /
+  adapters.
+- **Codegen owns** (don't hand-edit — regenerated every run):
+  - `src/generated/modules.ts` — the `GENERATED_MODULES` barrel
+  - `src/generated/schema.ts` — the Drizzle schema barrel
+  - the per-entity module tree (`src/modules/<plural>/…` in clean-lite-ps)
+- **The package vendors** managed copies of its runtime into `src/shared/**`
+  (base classes, types, the `DRIZZLE` token, the Zod pipe, the OpenAPI
+  registry) and installed subsystems into `<subsystems-root>/<name>/`. Treat
+  these as generated output: don't hand-edit; subclass instead. `codegen
+  update` refreshes them after a package bump.
+
+The generation pipeline: `YAML → parse → analyze → templates → code`. After any
+generation run the two barrels are rewritten and you wire them into
+`app.module.ts` exactly once — codegen never edits that file again.
+
+## Routing — load the focused skill for deep work
+
+| Task | Read |
+|---|---|
+| Author / change an entity YAML (fields, families, queries, EAV, relationships) | the `entities` skill |
+| Install or wire an infrastructure subsystem; get the `forRoot` registration order right | the `subsystems` skill |
+| Write a background `@JobHandler`, configure pools, set concurrency/ordering | the `jobs` skill |
+| Author a domain event, publish via the outbox, use the typed event bus | the `events` skill |
+| React to an event with a durable async job (the event-to-job bridge) | the `bridge` skill |
+| Pull/push data from an external system (`IChangeSource` / `ISyncSink`) | the `sync` skill |
+
+## CLI quick reference
+
+```bash
+# Project lifecycle
+codegen init                       # scaffold this project's shared layer + config + skills
+codegen project scan               # detect framework/ORM/architecture → propose config
+codegen project config             # print the resolved codegen.config.yaml
+codegen update                     # re-sync vendored runtime + subsystems + skills after a package bump
+
+# Entities
+codegen entity new entities/<file>.yaml   # generate one entity
+codegen entity new --all                  # regenerate every entity in entities/
+codegen entity new --all --dry-run        # preview
+codegen entity list                       # tabular list
+codegen entity validate --strict          # validate YAML + cross-refs (warnings fail)
+
+# Subsystems (see the `subsystems` skill for wiring + order)
+codegen subsystem                  # summary: installed vs available
+codegen subsystem install <name>   # vendor a subsystem's runtime + inject its config block
+codegen subsystem list
+
+# Skills
+codegen skills install             # (re)vendor these consumer skills into .claude/skills
+codegen skills list
+```
+
+## Non-obvious rules
+
+- **YAML is `snake_case`; generated TS properties are `camelCase`.** The
+  templates derive `accountId` from `account_id`. Entity names are singular
+  `snake_case` (`opportunity`).
+- **Two architectures, mutually exclusive.** `generate.architecture` in
+  `codegen.config.yaml` is either `clean-lite-ps` (the supported consumer
+  default — lighter per-entity module layout) or `clean` (full split). Don't mix.
+- **Barrels are wired once.** After the first `entity new`, add
+  `...GENERATED_MODULES` to `app.module.ts` and `export * from
+  './generated/schema'` to your schema root. Codegen keeps the barrel contents
+  fresh; you never re-touch `app.module.ts` for new entities.
+- **Migrations are not `drizzle-kit push` in shared/CI/prod.** Generate
+  reviewable SQL with Atlas (`atlas migrate diff` → review → `atlas migrate
+  apply`). `push` is dev-loop-only.
+- **Upgrades need a re-sync.** After `bun add @pattern-stack/codegen@latest`, run
+  `codegen update` — the vendored `src/shared/**` and installed subsystems are
+  otherwise stale against the new package.
+
+## Do not
+
+- **Do not hand-edit anything under `src/generated/`** or the vendored
+  `src/shared/**` runtime files — the next `entity new` / `codegen update`
+  overwrites them. Need different behavior? Subclass the base in your own module.
+- **Do not declare a fresh `DRIZZLE` token.** Import the one from
+  `@shared/constants/tokens`; a second token has a different identity and DI
+  won't resolve.
+- **Do not add tables directly to `src/generated/schema.ts`.** Hand-authored
+  tables go in your own file and are combined in the schema root re-export.
+- **Do not reach for `clean` vs `clean-lite-ps` arbitrarily.** Match the
+  project's existing `generate.architecture`; switching mid-project rewrites the
+  whole module layout.

package/consumer-skills/entities/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: entities
+description: >-
+  Load when authoring or changing an entity definition for a project that uses
+  @pattern-stack/codegen — creating `entities/<name>.yaml`, choosing an entity
+  family (Synced / Activity / Metadata / Knowledge / Base), adding fields,
+  behaviors, relationships, declarative `queries:`, or opting an entity into EAV
+  custom fields. Covers what each YAML block generates and the layer rules the
+  generated code obeys.
+allowed-tools: Read, Write, Edit, Glob, Grep, Bash
+user-invocable: false
+---
+
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Authoring entities
+
+An entity is one `entities/<name>.yaml` file. Running `codegen entity new
+entities/<name>.yaml` (or `codegen entity new --all`) turns it into a full
+vertical slice: a Drizzle table, a repository (extending a family base class), a
+service, use cases, a controller with Zod-validated routes, DTOs, and a NestJS
+module — plus an entry in the `GENERATED_MODULES` and schema barrels.
+
+## Mental model
+
+- **One YAML → one module.** You describe *what* the entity is (fields,
+  relationships, behaviors, queries); the templates produce the *how* (CRUD,
+  validation, wiring).
+- **Family = inherited capability.** Every entity picks a `pattern` (family).
+  The family decides which extra repository/service methods you get for free on
+  top of the standard CRUD set. See `families-and-queries.md`.
+- **Declarative queries beat hand-written finders.** A `queries:` block
+  generates typed repository methods, interface signatures, injectable query
+  use cases, and module registration. See `families-and-queries.md`.
+- **Naming**: YAML is `snake_case` (matches DB columns); generated TS
+  properties are `camelCase`; entity `name` is singular `snake_case`.
+
+## Routing
+
+| For | Read |
+|---|---|
+| The full YAML block reference — fields, types, behaviors, relationships, EAV flags, `generate:` | `yaml-reference.md` |
+| Choosing a family, the methods each family adds, and the `queries:` block shapes | `families-and-queries.md` |
+
+## Minimum viable entity
+
+```yaml
+entity:
+  name: account            # singular snake_case
+  pattern: Synced          # Base | Synced | Activity | Metadata | Knowledge (or app-defined)
+
+fields:
+  name:
+    type: string
+    required: true
+  email:
+    type: string
+    index: true
+  status:
+    type: enum
+    choices: [active, inactive]
+
+behaviors:
+  - timestamps             # createdAt, updatedAt
+  - soft_delete            # deletedAt + automatic query filtering
+
+queries:
+  - by: [email]
+    unique: true           # → FindAccountByEmail use case (unique)
+```
+
+```bash
+codegen entity new entities/account.yaml
+# barrels auto-update — no manual wiring for the new module
+```
+
+## Layer rules the generated code obeys
+
+Generated code is layered; your hand-written use cases must respect the same
+boundaries:
+
+- **Repository** — single table. Extends a family base. No business logic.
+  Write methods take an optional `tx?: DrizzleTx`.
+- **Service** — one aggregate. Composes repositories; may read cross-domain;
+  may call same-domain services. **May NOT write cross-domain.** This is the
+  mandatory API boundary.
+- **Use case** — a workflow. Composes services (including cross-domain), owns
+  the transaction for cross-domain writes, emits events, calls external ports.
+- **Controller** — thin adapter. Calls use cases only. `@Body()` is run through
+  `ZodValidationPipe` (422 on failure); `GET :id` throws 404 when the row is
+  missing or soft-deleted.
+
+## Non-obvious rules
+
+- **`generate.writes: true` (default) emits POST/PATCH/DELETE** + create/update/
+  delete use cases. Set it `false` for read-only entities.
+- **Cross-entity references must resolve.** If `account.yaml` references
+  `contact`, the analyzer needs `contact.yaml` present; `codegen entity new
+  --all` is the safe way to regenerate a set with cross-refs.
+- **Regenerating is safe and idempotent.** Re-run after any YAML edit; the
+  module tree + barrels are codegen-owned.
+- **Validate before generating** when unsure: `codegen entity validate --strict`.
+
+## Do not
+
+- **Do not hand-edit generated module files.** Override by composing in your own
+  module / subclassing the generated service.
+- **Do not put business logic in a repository** or cross-domain writes in a
+  service — the layer rules above are enforced by convention and reviewed.
+- **Do not invent field types.** Use the documented set (`yaml-reference.md`);
+  unknown types fail validation.

package/consumer-skills/entities/families-and-queries.md

@@ -0,0 +1,82 @@
+<!-- managed by @pattern-stack/codegen — re-run `codegen skills install` to refresh. Edit the package source, not this vendored copy. -->
+
+# Entity families & declarative queries
+
+## Families (the `pattern:` field)
+
+Every entity declares a `pattern`. The family decides which methods the
+generated repository and service inherit on top of the standard CRUD set. The
+base classes are vendored into `@shared/base-classes/*` at project init.
+
+**Standard CRUD set (every family):** `findById`, `findByIds`, `list`, `count`,
+`exists`, `create`, `update`, `delete`, `upsertMany`. Every write method accepts
+an optional `tx?: DrizzleTx` for transactional composition.
+
+| Family | Use it for | Adds on top of CRUD |
+|---|---|---|
+| `Base` | plain tables with no special access pattern | nothing — standard CRUD only |
+| `Synced` | records mirrored from an external system (have an external id + per-user visibility) | `findByExternalId`, `findAllByUserId`, `findVisibleByUserId`, `syncUpsert` |
+| `Activity` | time-ordered activity/event rows tied to a parent | `findByDateRange`, `findByUserId`, `findByOpportunityId`, `findRecentByOpportunityId` |
+| `Metadata` | key/value or definition/value rows describing other entities | `findByEntityIdAndType`, `listByEntityId`, `listHistoryByEntityId` |
+| `Knowledge` | semantically-searchable knowledge rows (pgvector at runtime) | `semanticSearch`, `findPendingByOpportunityId`, `updateStatus`, `updateStatusBatch` |
+
+Choosing a family:
+- Mirrors an external system (CRM, etc.)? → `Synced` (often paired with the
+  `sync` skill).
+- Append-only timeline tied to a parent record? → `Activity`.
+- Describes/annotates other entities (incl. the EAV value table)? → `Metadata`.
+- Vector search / RAG? → `Knowledge`.
+- None of the above? → `Base`.
+
+App-defined patterns are also supported (a project can register its own family
+base); use the project's existing convention if one is present.
+
+## Declarative queries (the `queries:` block)
+
+A `queries:` entry generates a typed repository method, the interface
+signature, an injectable query use case, and its module registration — no
+hand-written finder.
+
+```yaml
+queries:
+  - by: [user_id]                 # → findByUserId()
+  - by: [email]                   # → findByEmail()  (unique)
+    unique: true
+  - by: [account_id]              # → findByAccountId(), ordered
+    order: created_at desc
+  - by: [user_id, account_id]     # → findByUserIdAndAccountId()
+```
+
+Shapes:
+- **`by: [col, …]`** — equality finder on one or more columns. Method name is
+  derived (`findByUserIdAndAccountId`). Multi-column finders AND the conditions.
+- **`unique: true`** — returns a single row (or null) instead of an array, and
+  marks the underlying index unique.
+- **`order: <col> <dir>`** — default ordering for the finder (e.g. `created_at
+  desc`).
+
+### Filtered search with pagination
+
+```yaml
+queries:
+  - name: search                  # → SearchContacts use case + GET /contacts/search
+    filters: [user_id, account_id, email]   # optional equality filters
+    search: name                  # ilike column for free-text
+    paginate: true                # returns { items, total, limit, offset }
+```
+
+A `name`d query with `filters`/`search`/`paginate` generates a search use case
+and a `GET /<plural>/search` route. `paginate: true` makes the route accept
+`limit`/`offset` and return a paged envelope.
+
+## Non-obvious rules
+
+- **Finder names are generated** from the column list — don't also hand-write a
+  finder of the same name; compose on top instead.
+- **Unique finders return a single nullable result**; non-unique return arrays.
+- **`order:` is the default sort**, not a parameter — add a `queries:` search
+  entry if you need caller-controlled ordering.
+- **Family methods assume their columns exist.** `Synced` expects an external-id
+  + user-visibility shape; `Activity` expects a parent FK like
+  `opportunity_id`. If your table doesn't fit, pick `Base` and add explicit
+  `queries:`.