@open-mercato/cli 0.6.7-develop.6677.1.beabb7ca12 → 0.6.7-develop.6686.1.bdda5ed397

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md

@@ -0,0 +1,19 @@
+# API and Domain Writes
+
+Load this reference for CRUD, commands, and action routes.
+
+1. Implement create/update/delete as command objects with stable IDs and call `registerCommand` from `@open-mercato/shared/lib/commands` for each object. A route action naming a command ID does not register it. Include audit/undo/event/cache/index side effects.
+2. Create `api/<resource>/route.ts`; import `makeCrudRoute` from `@open-mercato/shared/lib/crud/factory`, then export per-method `metadata`, the selected factory handlers, and matching `openApi`.
+3. Build current `makeCrudRoute` options: `metadata`, `orm`, `list`, `actions: { create, update, delete }`, and `indexer`. Each command action uses `commandId`, `schema`, optional `mapInput`, `response`, and `status`—never a `command` key. Add `enrichers: { entityId: '<module>:<entity>' }` only when the route intentionally publishes that stable host contract; keep the colon-form ID aligned with the UI/widget host and test injected read/write round trips. Export `openApi` separately—it is not a factory option—and build it with `createCrudOpenApiFactory`/`createPagedListResponseSchema` from `@open-mercato/shared/lib/openapi/crud` or a typed `OpenApiRouteDoc` from `@open-mercato/shared/lib/openapi`.
+   - Exact current ORM keys are `entity`, `idField`, `tenantField`, `orgField`, and `softDeleteField` (not `organizationField`).
+   - The list query validator key is `schema` (not `querySchema`). Exact current callbacks are `buildFilters(query, ctx)` and `transformItem(item)` (not `findMany`, `filters`, or `transform`); there is no `findAndCount` key. Projections use database field names such as `tenant_id`, `organization_id`, and `updated_at`.
+   - The factory applies trusted tenant/organization scope from the ORM keys. Public request schemas never accept `tenantId` or `organizationId`; runtime scope comes only from the trusted request/command context. `buildFilters` adds only validated business filters; do not read nullable `ctx.auth` merely to repeat scope. Commands derive required trusted scope and fail closed.
+   - `mapInput` receives `{ parsed, raw, ctx }`; use `({ parsed }) => parsed` when no route adaptation is needed. `response` is a callback receiving `{ result, logEntry, ctx }`, never a response schema.
+   - `createCrudOpenApiFactory({ defaultTag: '<Tag>' })` returns a builder. Call that builder with `resourceName`, `querySchema`, `listResponseSchema`, and optional `create`/`update`/`del` objects containing Zod `schema`, optional `responseSchema`, and `description`; the key is not `body`. Do not pass resource options to the factory itself.
+   - A manual `OpenApiRouteDoc` nests HTTP method docs under `methods`, for example `const openApi: OpenApiRouteDoc = { methods: { GET: { summary, tags, responses } } }`; `GET` is uppercase but is not a top-level `GET` key.
+4. Include `updated_at` in the list/detail projection and serialize `updatedAt`. Keep stable response keys and colon-form entity IDs.
+5. Validate all query/body data. Reject malformed ID/filter values and derive tenant/org scope from context.
+6. For a non-factory action, run mutation guards, enforce aggregate optimistic lock, dispatch a command, then run callbacks/side effects only after commit.
+7. Test allowed/denied/wildcard users, two scopes, malformed input, stale version, and action retry/undo.
+
+Command IDs in `actions` are stable strings; a route does not import command implementations merely to declare them. Use exact installed `customers` route/command patterns when a remaining signature is uncertain; do not use the obsolete flat CRUD action options or HTTP-method directory routes.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md

@@ -0,0 +1,107 @@
+# Business One-Shot Blueprints
+
+Load this reference when the user describes a business outcome rather than files or framework mechanisms. Pick the closest row, state inferred scope in one sentence, then build its smallest end-to-end slice. Combine rows only when the brief clearly spans them; do not scaffold every optional surface named here.
+
+## Route Key
+
+- `M` — `om-module-scaffold` plus architecture/contracts; add `om-data-model-design` when persisting records.
+- `U` — `om-system-extension` plus the extensions guide for additive installed-module behavior.
+- `P` — `om-integration-builder` plus the integrations guide for a reusable external provider.
+- `B` — `om-backend-ui-design` for admin, public, or portal UI.
+- `W` — `om-build-workflow` for durable business-process state, activities, or human tasks; not schedules, queues, retries, or progress alone.
+- `A` — `om-create-ai-agent` only when the brief actually requests agentic behavior.
+
+`App module` owns app-specific records and behavior under `src/modules/`. `UMES` augments an installed module without copying it. `Provider` is a dedicated package/module for a reusable external system. A mixed choice names the owner of each leg.
+
+Once a row matches, its route key is binding: invoke every unparenthesized route letter and its skill before implementation. Scalar IDs or snapshots keep modules independent, but they do not remove `U` when the slice still links to, enriches, guards, or renders installed-module behavior. A parenthesized route remains conditional on the parenthesized reason.
+
+## Customers and CRM
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Build a customer and contact management module.” | Enable/use installed `customers`; UMES for app-specific behavior; app module only for genuinely separate records | `U+B` (`+M`) | verify activation/capabilities, customer list/detail/forms/search, then add only requested fields, policies, widgets, or related records | do not duplicate the installed customer identity; tenant+organization scope; encrypted PII reads; optimistic locking; stable IDs |
+| “Add customer success health, owner, and renewal fields to CRM customers.” | App module extension entity + UMES widgets/enricher/interceptor | `M+U+B` | health record keyed by customer ID, list/detail enrichment, editable panel, renewal filter, reminder event | read `.ai/guides/upstream/BACKWARD_COMPATIBILITY.md` before extending existing customer response, event, or ID surfaces; no cross-module ORM relation; complete read/write/UI round trip; optional CRM absence degrades safely; lock extension records |
+| “Manage communication consent and channel preferences for every customer.” | App module + mandatory UMES customer panel and mutation guard | `M+U+B` | consent history, current preferences, customer widget, API, audit event, suppression query | append-only consent evidence; encrypted PII; purpose/channel granularity; deny sends without valid consent |
+
+## Deals Pipeline
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Modify the deals pipeline with our stages, probabilities, and required fields.” | UMES over the installed `customers` deal/pipeline surfaces; app module only for extra persisted policy | `U+B` | inspect exact `customers` hosts/contracts, then add stage-aware fields/validation, board/table rendering, translations, and transition tests | preserve shipped IDs; validate transitions server-side; wildcard ACL; unsupported replacement requires approval |
+| “Add qualification scoring and next-best-action to every deal.” | App module extension entity + UMES enricher/widgets; optional AI tool only if requested | `M+U+B` (`+A`) | score inputs, deterministic calculator, deal list/detail field, recompute event, explainable action panel | score is reproducible and scoped; no hidden AI mutation; optional deals module safe; stale writes conflict |
+| “Build a sales forecast and pipeline coaching dashboard.” | App analytics module + UMES reads/enrichers | `M+U+B` | scoped forecast query, stage-weighted totals, owner/time filters, drill-down, snapshot/export | currency/time-zone correctness; access-filtered aggregates; deterministic totals; no cross-tenant cache keys |
+
+## CRM-Integrated Lead Capture
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Generate an app that gathers website leads and adds them to the CRM.” | App module owns public capture + UMES/events create or link CRM customer/deal; MUST invoke `om-data-model-design` and report `smallest-validation` for the lead record and scalar CRM link | `M+U+B` (`+W` for async handoff) | public form, spam/consent validation, lead inbox, dedupe, qualification command, CRM handoff, attribution, success/error paths | public input never supplies scope; idempotent submission key; PII encryption; CRM optional/degraded; handoff retry cannot duplicate |
+| “Build partner referral intake connected to CRM.” | App module + UMES CRM handoff | `M+U+B` | partner-authenticated form, referral record/status, customer/deal match, owner assignment, partner-visible outcome | partner sees only its referrals; deterministic dedupe; immutable attribution; CRM IDs stored as scalars |
+| “Assign incoming leads fairly across eligible staff.” | App assignment policy + UMES customer/staff seams | `M+U` | read both `customers` and `staff` facts; scoped cursor, deterministic selector, availability resolver, assignment command/audit, fallback | concurrency-safe round robin; retries preserve the winner; unauthorized/unavailable staff excluded; staff module optional |
+| “Import trade-show badge scans and turn qualified leads into deals.” | App module + data-sync provider when scanner API is reusable + UMES | `M+P+U+W` | upload/sync, mapping preview, lead staging, dedupe, qualification queue, CRM conversion report | resumable/idempotent batches; row-level errors; encrypted credentials; no partial duplicate conversions |
+
+## Catalog and Sales
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Add customer-specific assortments and price lists.” | App module + UMES catalog/customer enrichment and guards | `M+U+B` | assortment/pricing entities, assignment UI, catalog query enrichment, effective-date selection, tests | money uses exact decimal/currency; deterministic precedence; no cross-module ORM; scoped cache invalidation |
+| “Build product bundles with configurable components.” | App module + UMES catalog/order widgets and guards | `M+U+B` | bundle definition, compatibility rules, pricing calculation, catalog editor, order-line expansion | snapshot price/config on sale; prevent invalid/cyclic bundles; lock edits; absent sales module safe |
+| “Reserve limited stock during checkout.” | App reservation module + UMES catalog/checkout guards | `M+U` | read `catalog` and `checkout` facts; reservation entity, atomic reserve/release commands, availability hook, expiry worker | no oversell; scoped atomic writes; idempotent winner/retry/release; quantity never negative; designed conflict handling is not debugging |
+| “Receive purchase orders into catalog inventory.” | App purchasing/receipt module + UMES catalog posting | `M+U+B` | partial receipt, discrepancy reasons, atomic inventory posting, cumulative receiving UI | never over-receive; retry-safe scan/submission; receipt and stock commit together; scalar host IDs |
+| “Track expiring lots through fulfillment and recall.” | App lot ledger + UMES catalog/sales links | `M+U` | lot/receipt/movement records, allocation guard, shipment links, scoped recall query | earliest-safe-expiry allocation; immutable movement lineage; audited adjustments; no cross-scope recall leakage |
+| “Bulk-update product prices with progress and undo.” | App operation module + UMES catalog actions/UI | `M+U+B` | chunked command, progress page, failure ledger, cancellation boundary, compensating undo | exact money; scoped ACL; completed chunks are retry-safe; undo is authorized/audited |
+| “Add quote approval and convert approved quotes into orders.” | App module policy/workflow + UMES sales actions | `M+U+B+W` | approval rules, submit/approve/reject commands, task UI, guarded conversion, audit/events | aggregate optimistic lock; command-only state changes; approval ACL/separation; conversion exactly once |
+| “Create a returns and RMA management module.” | App module + UMES order/customer links | `M+U+B+W` | return request, item eligibility, approve/receive/disposition/refund states, order widgets, portal status | quantities never exceed fulfillment; scalar snapshots; idempotent state transitions; refund requires explicit guarded action |
+
+## Payments and Shipping
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Integrate a new payment gateway.” | Provider; small app glue only for app-specific policy/UI | `P+U+B` | credentials, health check, authorize/capture/refund adapter, webhook verification, payment UI/status mapping | encrypt credentials; verify signatures; idempotent external IDs; exact money/currency; no secret logging |
+| “Build payment reconciliation and dispute handling.” | App module + payment-provider/data-sync seams | `M+P+B+W` | statement import/sync, match engine, exception queue, dispute lifecycle, audit/export | deterministic re-runs; unmatched records retained; money totals reconcile; privileged writes and locked cases |
+| “Integrate a shipping carrier with labels and tracking.” | Provider + UMES sales/fulfillment glue | `P+U+B` | credentials/health, rate quote, shipment/label commands, tracking webhook/poll, order widget | encrypted credentials; webhook dedupe; label retry does not duplicate shipment; tracking state monotonic |
+| “Choose the cheapest valid carrier and track fulfillment.” | App orchestration module + carrier providers + UMES | `M+P+U+W+B` | read `shipping_carriers`, `sales`, and `progress` facts; shipment rules, rate comparison, guarded selection, booking workflow, progress/exceptions | provider-neutral domain; deterministic rule order; retry/idempotency; package/weight/address validation |
+
+## Portal and Notifications
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Let customers view quotes/orders and approve quotes in a portal.” | App portal module + UMES sales/customer links | `M+U+B` | `[orgSlug]/portal` pages, scoped list/detail, approval command, navigation injection, notifications | derive customer from portal principal; never trust route IDs alone; aggregate lock; mobile/loading/error states |
+| “Build a customer support case portal.” | App module with portal/admin surfaces + UMES customer context | `M+U+B+W` | cases/messages/attachments, portal create/reply, admin triage/SLA, notifications, search | portal ownership on every read/write; attachment policy; PII protection; idempotent SLA escalation |
+| “Notify deal owners before stale opportunities breach SLA.” | App module subscriber/scheduler + UMES deal link | `M+U+W` | SLA policy, due query, notification type/renderer, deep link, acknowledge/snooze action | ACL-filtered renderer; dedupe per deal/window; tenant time zone; optional deals module safe |
+| “Run customer renewals at each customer’s local time.” | App scheduler over customer IDs; load both `scheduler` and `customers` facts | `M` | annual renewal schedule, restart-safe claim, customer time-zone/DST policy, renewal command | trusted host scope (`host-scope-contract`); worker idempotency; no timer loop; retries cannot duplicate |
+| “Create an operations exception center for low stock and failed orders.” | App module + event subscribers/enrichers from catalog/sales | `M+U+B+W` | normalized exception record, inbox/filter/detail, resolution commands, source deep links | idempotent event projection; source IDs as scalars; scoped reads; resolved exceptions do not reopen without a new cause |
+
+## Workflows and Data Sync
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Require manager approval for discounts above a threshold.” | Workflow/policy app module + UMES sales mutation guard/UI | `M+U+W+B` | threshold policy, approval task, submit/approve/reject, guarded discount mutation, audit | server-side money comparison; separation of duties; stale document conflict; decision replay cannot double-apply |
+| “Automate customer onboarding across sales, tasks, and email.” | App module + durable workflow + optional providers/UMES | `M+W+U+P+B` | trigger, checklist/tasks, email steps, waits/escalations, progress UI, retry/recovery tests | idempotent steps; explicit compensation; no credentials in workflow state; missing optional provider yields actionable pause |
+| “Synchronize customers and products with our ERP.” | Data-sync provider + thin app mapping/UMES layer | `P+M+U+B` | credentials/health, cursors, inbound/outbound mappings, conflict policy, run UI/progress, retry/CLI | stable external mapping; scope every cursor; deterministic conflict ownership; resumable exactly-once effects |
+| “Add scheduled CSV/SFTP imports and exports with custom mappings.” | Provider for reusable SFTP/storage; app module owns format/mapping | `P+M+B` | format schema, preview/validate, batch job, row errors, export, schedule/progress | path/CSV hardening; encrypted credentials; resumable batches; no scope in untrusted file; formula-injection-safe export |
+
+## External Integrations
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Sync CRM segments and campaigns to an email marketing platform.” | Provider + UMES customer/consent reads | `P+U+B+W` | connection/health, segment mapping, incremental sync, suppression handling, run report | consent enforced before export; encrypted token; remote-ID uniqueness; delete/unsubscribe convergence |
+| “Export invoices to accounting and reconcile their status.” | Provider + UMES sales/document glue | `P+U+B+W` | account/tax mapping, guarded export, attachment/status import, exception/retry UI | immutable financial snapshots; exact currency/tax totals; idempotent document key; no silent mapping fallback |
+| “Expose signed webhooks for CRM lifecycle events and receive updates.” | Provider/webhook module + UMES events/interceptors | `P+U` | endpoint config, signed delivery/retry log, inbound verification/dedupe, mapping commands | rotate/encrypt secrets; standard signature verification; replay protection; post-commit outbound delivery |
+
+## Content, Onboarding, and Greenfield Apps
+
+| One-shot business brief | Mechanism | Routes | Smallest complete vertical slice | Key invariants |
+|---|---|---|---|---|
+| “Add localized privacy, terms, and help pages.” | App content module; UMES menu injection when linked in installed UI | `M+B+U` | versioned content, locale resolution, public routes, navigation/footer links, publish preview | safe rendering; explicit publication/version dates; locale fallback; legal history remains retrievable |
+| “Create a tenant onboarding wizard for CRM setup.” | App onboarding module + UMES setup hooks/widgets | `M+U+B+W` | resumable steps, defaults/import/invitations, completion state, welcome notification | setup hooks idempotent; scoped progress; safe retry; secrets never stored in wizard state |
+| “Build a library management system.” | New app module | `M+B+W` | books/copies/members, checkout/return/renew/reservation commands, admin UI/search, overdue jobs | copy availability is transactional; no double checkout; due dates use tenant zone; member PII protected |
+| “Build a field-service management app tied to CRM customers.” | App module + UMES customer links + optional mapping provider | `M+U+B+W+P` | work orders, technicians, schedule, visit notes/photos, customer panel, dispatch notifications | scalar customer IDs/snapshots; assignment conflicts prevented; mobile/error states; jobs retry idempotently |
+| “Build an equipment rental business app.” | New app module + optional payment/shipping providers | `M+B+W+P` | assets, availability, reservations, checkout/return, damage/deposit, calendar | overlapping reservations rejected atomically; money snapshots; asset condition audit; provider failures recoverable |
+| “Build appointment booking connected to CRM.” | App module + UMES customer handoff + notification provider | `M+U+B+W+P` | public availability, booking/reschedule/cancel, CRM match/create, reminders, admin calendar | public scope derived server-side; slot hold is atomic; time-zone/DST correctness; submission/reminder dedupe |
+| “Build membership and subscription management.” | App module + payment provider + customer portal | `M+B+P+W+U` | plans/memberships, enrollment, renewal/cancel, payment status, portal/admin views | explicit billing state machine; webhook idempotency; entitlement derived from paid periods; PII/money protection |
+| “Build purchasing and vendor approval management.” | New app module + optional accounting provider | `M+B+W` (`+P` only when an accounting provider is requested) | vendors/requests/POs/receipts, approval thresholds, budget view, export | separation of duties; exact money/currency; locked approvals; PO/export exactly once |
+
+## Completion Rule
+
+Before coding, turn the chosen row into concrete stable IDs, routes, actors, lifecycle states, optional-module behavior, and acceptance paths. A one-shot is complete only when its named API/UI path works through real commands, generation is refreshed, migrations are reviewed but not applied, and integration tests cover scope, denial, stale writes, failure/retry, and every external boundary used.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md

@@ -0,0 +1,12 @@
+# Module Data and Migrations
+
+Load this reference when the module persists data.
+
+1. Invoke `om-data-model-design`; place all entity classes in `data/entities.ts` and validators in `data/validators.ts`.
+2. Add UUID IDs, explicit tenant/org columns and indexes, timestamps, optional soft delete, and `updated_at` for every new editable record.
+3. Keep same-module relations explicit. For another module, store a scalar ID/snapshot or use an extension entity; never declare an ORM relation.
+4. Add encryption maps for PII/credentials and decryption reads for every code path that returns those values.
+5. Design commands and responses so optional fields can be intentionally cleared.
+6. Run `yarn db:generate`, review only the scoped SQL, and update the module snapshot. Ask before applying.
+
+Required regression coverage: two-scope isolation, create/read/update/clear/delete, current/stale version, and injected multi-phase failure rollback.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md

@@ -0,0 +1,83 @@
+# Module Discovery Surface Catalog
+
+Load this reference when deciding which convention files a complete module needs. It is a routing catalog, not a checklist: create only surfaces required by the brief, then run `yarn generate` after adding, removing, or renaming any discovered surface.
+
+## Ownership and Domain
+
+| Surface | Canonical path | Contract |
+|---|---|---|
+| Module metadata/dependencies | `index.ts` | Export stable module metadata; optional dependencies degrade safely. |
+| Entities | `data/entities.ts` | App-owned persistence, tenant/org scope, encrypted fields, and `updated_at`; generator-discovered. |
+| Validation support | `data/validators.ts` | Conventional app-owned schemas shared by APIs/commands; imported by call sites, not generator-discovered. |
+| Entity links/extensions | `data/extensions.ts` | `EntityExtension[]`; scalar cross-module IDs, never cross-module ORM relations. |
+| Custom entities/fields | `ce.ts` | Declare custom entities/field sets with generated entity IDs and DSL helpers. |
+| DI and lifecycle | `di.ts`, `setup.ts` | Register services; idempotent tenant hooks/default grants/seeds. |
+| ACL and encryption | `acl.ts`, `encryption.ts` | Stable feature IDs and entity encryption maps. |
+| Domain writes | `commands/**` | Commands own mutations, guards, transactions, side effects, undo/audit. |
+| Command interception | `commands/interceptors.ts` | Cross-cutting command hooks keyed by stable command IDs; preserve command safety. |
+
+## HTTP and Pages
+
+| Surface | Canonical path | Contract |
+|---|---|---|
+| API | `api/**/route.ts` | Export HTTP handlers, per-method `metadata`, and `openApi`; use factories/commands. |
+| API interception | `api/interceptors.ts` | Scoped route/method hooks; custom routes opt into their supported bridge. |
+| Backend pages | `backend/**/page.tsx` + `page.meta.ts` | `/backend/...`; root `backend/page.tsx` maps to `/backend/<module>`; staff features, navigation metadata, shared backend UI. |
+| Public pages | `frontend/**/page.tsx` + `page.meta.ts` | `/...`; explicit public/auth posture and safe server-derived scope. |
+| Customer portal | `frontend/[orgSlug]/portal/**/page.tsx` + `page.meta.ts` | `[orgSlug]` first; public login/signup/verify/landing pages are `navHidden` without customer auth, while guarded pages declare customer auth/features; optional portal `nav`. |
+| Page middleware | `backend/middleware.ts`, `frontend/middleware.ts` | Named `middleware` or default export of stable `{ id, mode?, target, priority?, run }` entries; never use UI visibility as authorization. |
+| UI locale messages | `i18n/<locale>.json` | Generator-discovered module messages using stable namespaced keys; distinct from translatable entity fields. |
+
+Do not use legacy HTTP-method directories or new flat page files. The installed generator's `page.tsx`/`route.ts` scanner and generated facts are authoritative if an older upstream guide shows a retired convention.
+
+Compatibility scanners may still read `data/entities.override.*`, `data/entities.*`, `data/schema.*`, legacy `db/*`, or `data/fields.ts`. Treat those as installed read-only/retired inputs, not new app authoring patterns; new entities stay in `data/entities.ts`, and new custom fields/entities use `ce.ts`.
+
+## Events, Async, and Data Presentation
+
+| Surface | Canonical path | Contract |
+|---|---|---|
+| Typed events | `events.ts` | Stable event IDs and typed payloads. |
+| Event subscribers | `subscribers/*.ts` | Default handler plus event metadata; choose persistent/idempotent behavior deliberately; sync lifecycle handlers declare `metadata.sync`/`priority`, including `*.querying`/`*.queried` when appropriate. |
+| Workers | `workers/*.ts` | Default handler plus queue/id/concurrency metadata; retry-safe and scoped. |
+| Workflows | `workflows.ts` | Stable workflow/activity IDs and durable output contracts. |
+| Search | `search.ts` | Entity indexing/presentation; cover reindex and convergence. |
+| Vector search | `vector.ts` | Vector entities with stable `buildSource`, presenter, and link contracts. |
+| Analytics | `analytics.ts` | Module analytics configuration with scoped aggregates. |
+| Translatable fields | `translations.ts` | Entity-field translation declarations; separate from UI locale messages. |
+| Response enrichment | `data/enrichers.ts` | Scoped `enrichOne` plus batched `enrichMany`, ACL and cache posture. |
+| Query enrichment | `data/enrichers.ts` with `queryEngine.enabled` | Query-lifecycle enrichment; preserve scoped query/result contracts. |
+| Mutation guards | `data/guards.ts` | Block/rewrite mutations without bypassing commands, scope, or locking. |
+| Cache | module service resolved through cache DI | Tenant-tagged keys and write-path invalidation; no raw provider client. |
+| Progress | module jobs/events plus progress APIs | Durable server progress or client-local event progress as appropriate. |
+
+## UI, Communication, and Automation
+
+| Surface | Canonical path | Contract |
+|---|---|---|
+| Injection widgets | `widgets/injection/**/widget.ts(x)` | Rendered or headless declarations with stable widget IDs. |
+| Injection mapping | `widgets/injection-table.ts` | Exact host spot and deterministic placement. |
+| Dashboard widgets | `widgets/dashboard/**/widget.ts(x)` | Stable widget ID, scoped data, shared dashboard primitives. |
+| Component overrides | `widgets/components.ts` | Stable handles; props/wrapper before replacement. |
+| Notification types | `notifications.ts` | Stable notification IDs and payload contracts. |
+| Notification UI | `notifications.client.ts`, `widgets/notifications/**` | Lightweight localized renderers. |
+| Reactive notification effects | `notifications.handlers.ts` | Feature-gated, wildcard-aware, idempotent browser reactions. |
+| Message types/objects | `message-types.ts`, `message-objects.ts` | Stable message/object definitions and supported UI renderers. |
+| Inbox actions | `inbox-actions.ts` | Stable action IDs with authorization and guarded execution. |
+| AI tools and agents | `ai-tools.ts`, `ai-agents.ts` | Typed IDs, ACL/scope, tool allowlists, approval-gated mutations. |
+| MFA provider contributions | `security.mfa-providers.ts` | Generator-plugin surface enabled by the installed security module; export provider setups with stable provider types and inspect the exact installed provider interface before authoring. |
+| Sudo target contributions | `security.sudo.ts` | Generator-plugin surface enabled by the installed security module; export stable target identifiers with explicit TTL/challenge policy and never treat elevation as a replacement for route/command authorization. |
+| CLI | `cli.ts` | Stable commands that work from compiled/published packages. |
+| Integration metadata | `integration.ts` | Provider/integration contribution when that subsystem requires it. |
+| Provider/domain registration | owning integration/module files | Payment, shipping, currency, workflow activity/signal, and other registries use their typed installed contract; route to the integration/workflow skill for exact paths. |
+| Generator plugins | `generators.ts` | Additional deterministic generated registries only when necessary. |
+
+Client-facing extension behavior may also use widget `eventHandlers.filter.operations`, typed events with `clientBroadcast: true`, `useAppEvent`/`useOperationProgress`, an integration wizard/status/detail-page widget, or an `<AiChat>` embed. These are capability branches, not additional generic discovery filenames; route them to UMES plus the UI, integration, events, or AI procedure that owns the contract.
+
+Provider-specific conventions live in the integration guide/skill. Payment renderer compatibility may use the installed `widgets/payments/client.ts(x)` contract; inspect the exact installed module before implementing it.
+
+## Completion Probe
+
+1. Map each requested capability to exactly one owning row; mark optional host behavior.
+2. Preserve stable IDs across metadata, ACL, entities, routes, events, widgets, messages, agents, and workflows.
+3. Run `yarn generate`; inspect the expected registry entry and structural warnings.
+4. Run focused unit tests plus self-contained API/UI integration paths for every selected surface.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md

@@ -0,0 +1,21 @@
+# Optional Module Surfaces
+
+Load only the rows the brief requires.
+
+| Capability | Required work |
+|---|---|
+| Registration | `index.ts`, `{ id, from: '@app' }` in `src/modules.ts`, generation. Treat the shipped `src/modules.ts` baseline as protected source: append exactly `enabledModules.push({ id: '<module>', from: '@app' })`; do not rewrite, compress, map, spread, sort, or reformat existing entries or the computed official-module registry. |
+| DI | `di.ts` registrations with stable tokens; resolve services, never instantiate infrastructure. |
+| ACL/setup | Declare stable resource features such as `<module>.<resources>.view`/`manage` and dependencies as the named `export const features = [...]` in `acl.ts`, followed by `export default features`; generated registry code expects both exports. Export `setup: ModuleSetupConfig = { defaultRoleFeatures, ... }` (plus default when useful) from `setup.ts`; do not rename the `features` export or export `defaultRoleFeatures` as a disconnected top-level map. Keep tenant/default/example seeds idempotent and run ACL sync. |
+| Events | `events.ts` imports `createModuleEvents` from `@open-mercato/shared/modules/events`, declares `const events = [{ id, label, category: 'crud' }] as const` (`category` is `crud`, `lifecycle`, `system`, or `custom`), then exports `createModuleEvents({ moduleId, events })`. It receives one options object, not positional module/event arguments. Use typed stable past-tense IDs before emission and idempotent subscribers; do not invent a shared `lib/events` entrypoint. |
+| Worker/progress | Load `runtime-cache-and-queues.md`; use discovered metadata, scoped/idempotent payloads, bounded concurrency/retry, command writes, and `ProgressJob`. |
+| Search | `search.ts` imports `SearchModuleConfig`/`SearchBuildContext`/`SearchIndexSource`/`SearchResultPresenter` from `@open-mercato/shared/modules/search` and exports `searchConfig`. Its stable colon-form entity uses the exact `entityId` key and declares `fieldPolicy: { searchable: [...], excluded: [...] }`; sensitive values remain excluded and only approved hash siblings support exact lookup. `buildSource(ctx)` returns `{ text: string[], presenter, checksumSource: { record: ctx.record, customFields: ctx.customFields } }`; `formatResult(ctx)` independently derives its presenter from `ctx.record`, and `resolveUrl(ctx)` reads the ID from `ctx.record.id`. `SearchResultPresenter` permits only `title`/`subtitle`/`icon`/`badge` and has no `metadata`; indexed structured values belong in `SearchIndexSource.fields`. CRUD uses `indexer: { entityType }`; bulk writes use the SearchIndexer reindex path. Do not invent `entityType` in `search.ts`, `ctx.presenter`, `ctx.id`, `convergenceKey`, `result`, per-field policy keys, `body`, or `href` aliases. Tests prove delete/reindex deterministic convergence without sleeps. |
+| Cache | Load `runtime-cache-and-queues.md`; use the DI cache, tenant/org/entity tags, and post-commit invalidation including undo/sub-resource paths. |
+| Notifications | type, renderer, subscriber/handler, ACL, client reactive behavior when needed. |
+| CLI | discovered command, scoped inputs, compiled-package test. |
+| Custom fields/entities | In `ce.ts`, use the generated-registry contract `export const entities = [{ id: '<module>:<entity>', fields: [...] }]` followed by `export default entities`; do not rename it to `customEntities` or use `entityId`. Include stable IDs, CRUD/UI normalization, and save/reload/clear tests. |
+| UI locale messages | Put generated module messages in `i18n/<locale>.json`, not `locales/<locale>.json`; use stable namespaced keys and rerun generation. This is distinct from translatable entity fields. |
+| Translatable fields | `translations.ts`; entity-field translation manager registration. |
+| AI/workflows | Invoke their dedicated skills; keep discovered root filenames. |
+
+Every added surface needs a real caller or acceptance path. Do not add speculative empty files.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/planning.md

@@ -0,0 +1,11 @@
+# Module Planning
+
+Load this reference for the first scaffold step.
+
+1. Extract actors, records, lifecycle/status invariants, actions, queries, pages, integrations, asynchronous work, and acceptance paths.
+2. Confirm app ownership. Use a new module for app domain behavior; use UMES for additive installed-module behavior; use a provider package for reusable external systems.
+3. Choose a plural snake-case module ID. List stable entity IDs (`module:entity`), API routes, command/event IDs, ACL features, DI tokens, page routes, DataTable/CrudForm host IDs, and optional dependencies before coding.
+4. Split phases by runnable vertical slice, not file type. Each phase leaves generation/typecheck/tests working.
+5. Check `.ai/specs/` for relevant contracts. Ask before public-contract/schema architecture changes not already authorized.
+
+For a one-shot module, the minimum complete slice is entity/validator/migration, command, scoped CRUD API/OpenAPI, ACL/setup, list/create/edit/detail UI, translations, generation, and integration coverage. Add search/events/workers/cache/notifications/CLI only when the brief requires them.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md

@@ -0,0 +1,22 @@
+# Runtime Cache and Queues
+
+Load only when the brief adds or changes server cache behavior or durable queued work.
+
+## Cache
+
+1. Resolve the configured cache through DI: `container.resolve<CacheStrategy>('cache')`, with `CacheStrategy` imported from `@open-mercato/cache`. Do not instantiate a strategy or depend on Redis directly inside a module.
+2. Use cache-aside reads (`get`, compute, then `set`) with a bounded millisecond TTL and stable tags. Keys/tags name the module, resource, organization, record/filter, and result version; never include plaintext secrets, tokens, encrypted values, or unbounded user input.
+3. The configured wrapper partitions keys and tags by the active cache tenant. Request containers establish that context. In workers, CLI, or subscribers where it is not guaranteed, import `runWithCacheTenant` from `@open-mercato/cache` and wrap both reads and `deleteByTags`; still put organization scope in the logical key/tag.
+4. Prefer tag invalidation with `deleteByTags` over key enumeration. CRUD routes/commands should reuse `invalidateCrudCache` from `@open-mercato/shared/lib/crud/cache` or the cache aliases already emitted by `emitCrudSideEffects`/`emitCrudUndoSideEffects`.
+5. Invalidate every affected collection, record, aggregate, and sub-resource only after commit. Create/update/delete/action and undo/compensation paths invalidate the same aliases. If invalidation can fail after a durable write, log structured scope-safe evidence and provide a recovery/rebuild path; never use stale cached data as authorization or mutation truth.
+6. Test miss/hit/TTL, two tenants and organizations, create/update/delete/sub-resource invalidation, undo, and an injected rollback proving no invalidation happened before commit.
+
+## Queues and discovered workers
+
+1. Import `createModuleQueue` and `Queue` from `@open-mercato/queue`. Keep one stable module-owned queue-name constant and a process-memoized typed getter; `createModuleQueue<T>(name, { concurrency })` selects local development storage or the configured async backend. Do not construct BullMQ/Redis clients in a module.
+2. Validate a JSON-serializable payload at enqueue and handler boundaries. Carry trusted `tenantId`, explicit `organizationId` (nullable only for an authorized tenant-wide contract), a job/domain type, stable operation/idempotency key, and scalar IDs. Never serialize request containers, ORM entities, credentials, decryption keys, or ambient auth state.
+3. Enqueue only after commit. When losing the enqueue after commit is unacceptable, persist an outbox/recovery marker in the transaction and drain it idempotently; never move the external enqueue inside the database transaction.
+4. Put each auto-discovered handler in `workers/<id>.ts`. Export `metadata: WorkerMeta = { queue, id: '<module>:<job>', concurrency }` and a default handler accepting `QueuedJob<T>` plus `JobContext` (extend it only with typed DI resolution). Run `yarn generate`; do not manually edit the generated worker registry.
+5. The stock local and async strategies make three attempts with exponential backoff; `JobContext.attemptNumber` is 1-based. A handler must be idempotent across every attempt, reuse the payload's operation key, dispatch commands/services for domain writes, advance cursors/checkpoints only after their unit commits, and throw retryable failures instead of swallowing them.
+6. Bound concurrency against database/provider capacity. Make terminal failure observable through structured logs and an app-owned status/progress/error record when users need visibility; operators can use `yarn mercato queue status <queue>` and run `yarn mercato queue worker <queue>` or `--all`.
+7. Test duplicate delivery, transient failure then success, exhausted retries, worker restart, scope isolation, enqueue failure/recovery, command rollback, and status/progress convergence without arbitrary sleeps.

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/verification.md

@@ -0,0 +1,13 @@
+# Module Verification
+
+Load this reference before claiming a scaffold is complete.
+
+1. Run `yarn generate`; inspect warnings and the affected module/API/page/entity/event/search/agent registrations.
+2. Standalone unit and command tests use the scaffold's Jest setup, never Vitest. When the standalone `tsconfig` does not declare Jest types, explicitly import `describe`, `it`/`test`, `expect`, and `jest` from `@jest/globals`; passing typecheck requires this, and a focused runner must discover and execute the file. Keep hooks void (`beforeEach(() => { jest.clearAllMocks() })`, not an expression callback that returns `Jest`), give framework mocks their complete callable signatures instead of relying on zero-argument `jest.fn()` inference, and pass the handler's full `{ input, logEntry, ctx }` object to `undo`. Put command behavior/undo tests under `commands/__tests__/`, run focused command/API/component tests, then `yarn typecheck`, `yarn lint`, and the smallest applicable build/test gate. Do not stop with a known TypeScript diagnostic in either implementation or test code.
+3. Create fixtures through APIs for two tenants/organizations and clean them in `finally`.
+4. Exercise list/detail/create/update/clear/delete, invalid input, denied/wildcard ACL, stale versions, and empty/error UI states.
+5. Exercise every optional surface actually added: search reindex, subscriber retry, worker restart/progress, cache invalidation, notification, CLI compiled path, portal/public auth.
+6. Disable optional peers in a test and verify defined degraded behavior.
+7. If package paths changed, pack/install into a disposable standalone consumer and rerun generation/build.
+
+Do not count generated files or screenshots alone as behavioral proof.