@open-mercato/core 0.6.3-develop.3810.1.ad92c339f5 → 0.6.3-develop.3811.1.be22750402

package/AGENTS.md

@@ -2,6 +2,42 @@
 
 `@open-mercato/core` contains all core business modules (auth, catalog, customers, sales, etc.). This guide covers the full extensibility contract and module development patterns.
 
+## Always
+
+- Preserve auto-discovery contracts for module files, API routes, pages, subscribers, workers, widgets, and generated registries.
+- Export `openApi` from every API route file.
+- Use `makeCrudRoute` with `indexer: { entityType }` for CRUD routes that should participate in query indexing.
+- Wire custom write routes through the mutation guard contract.
+- Use declarative feature guards and add new `acl.ts` features to `setup.ts` `defaultRoleFeatures`.
+- Use `findWithDecryption` / `findOneWithDecryption` for encrypted entities.
+- Implement domain writes through commands so audit, undo, cache, events, and indexing stay consistent.
+- Run `yarn generate` after changing module files discovered by the generator.
+
+## Ask First
+
+- Ask before changing any contract surface from `BACKWARD_COMPATIBILITY.md`: auto-discovery, public types, import paths, event IDs, widget spot IDs, API URLs, DB schema, DI names, ACL features, notification IDs, CLI commands, or generated file contracts.
+- Ask before moving versioned generated files or changing where generated registries live.
+- Ask before applying migrations with `yarn db:migrate`; normal PRs should include migration files and snapshots.
+
+## Never
+
+- Never create direct ORM relationships between modules; use foreign key IDs and fetch separately.
+- Never expose cross-tenant data or omit tenant/organization scoping.
+- Never hand-edit generated files.
+- Never import generated app bootstrap files from packages.
+- Never run raw `em.find` / `em.findOne` between scalar mutations and `em.flush()` on the same `EntityManager` without `withAtomicFlush`.
+- Never hand-roll AES/KMS encryption or bypass `TenantDataEncryptionService`.
+- Never compare raw feature arrays with exact string checks when wildcard grants apply.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+yarn workspace @open-mercato/core test
+```
+
 ## Core Modules
 
 | Module | Path | Description |
@@ -593,7 +629,7 @@ const crud = makeCrudRoute({
 })
 ```
 
-### Key Rules
+### Response Enricher Rules
 
 - MUST implement `enrichMany()` for batch endpoints (prevents N+1 queries)
 - MUST namespace enriched fields with `_moduleName` prefix (e.g. `_example.todoCount`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.6.3-develop.3810.1.ad92c339f5",
+  "version": "0.6.3-develop.3811.1.be22750402",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -243,16 +243,16 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@open-mercato/ai-assistant": "0.6.3-develop.3810.1.ad92c339f5",
-    "@open-mercato/shared": "0.6.3-develop.3810.1.ad92c339f5",
-    "@open-mercato/ui": "0.6.3-develop.3810.1.ad92c339f5",
+    "@open-mercato/ai-assistant": "0.6.3-develop.3811.1.be22750402",
+    "@open-mercato/shared": "0.6.3-develop.3811.1.be22750402",
+    "@open-mercato/ui": "0.6.3-develop.3811.1.be22750402",
     "react": "^19.0.0",
     "react-dom": "^19.0.0"
   },
   "devDependencies": {
-    "@open-mercato/ai-assistant": "0.6.3-develop.3810.1.ad92c339f5",
-    "@open-mercato/shared": "0.6.3-develop.3810.1.ad92c339f5",
-    "@open-mercato/ui": "0.6.3-develop.3810.1.ad92c339f5",
+    "@open-mercato/ai-assistant": "0.6.3-develop.3811.1.be22750402",
+    "@open-mercato/shared": "0.6.3-develop.3811.1.be22750402",
+    "@open-mercato/ui": "0.6.3-develop.3811.1.be22750402",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/modules/auth/AGENTS.md

@@ -2,6 +2,33 @@
 
 The auth module handles authentication, authorization, users, roles, and RBAC.
 
+## Always
+
+1. Hash passwords with `bcryptjs` using cost >= 10.
+2. Use `findWithDecryption` / `findOneWithDecryption` for user queries.
+3. Prefer `requireFeatures` in page/API metadata for access control.
+4. Declare every module feature in `acl.ts` and seed role grants through `setup.ts`.
+5. Use wildcard-aware helpers such as `matchFeature`, `hasFeature`, and `hasAllFeatures` when inspecting raw granted features.
+
+## Ask First
+
+- Ask before changing session token format, RBAC semantics, wildcard matching, super-admin behavior, or tenant provisioning outputs.
+- Ask before changing login/reset/invitation error messages because auth messages can leak account existence.
+
+## Never
+
+- Never log credentials, password reset tokens, session tokens, or decrypted user secrets.
+- Never reveal whether an email exists through auth error messages.
+- Never check raw ACL arrays with `includes(...)`, `Set.has(...)`, or ad hoc wildcard logic.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn workspace @open-mercato/core build
+yarn workspace @open-mercato/core test
+```
+
 ## Data Model
 
 - **Users** — system users with credentials, profile, preferences

package/src/modules/catalog/AGENTS.md

@@ -2,14 +2,33 @@
 
 Use the catalog module for products, categories, pricing, variants, and offers.
 
-## MUST Rules
+## Always
 
-1. **MUST NOT reimplement pricing logic** — use `selectBestPrice` and the resolver pipeline from `lib/pricing.ts`
+1. **MUST use `selectBestPrice` and the resolver pipeline from `lib/pricing.ts`** for pricing logic.
 2. **MUST use the DI token `catalogPricingService`** when resolving prices — ensures overrides take effect
 3. **MUST register custom pricing resolvers** with explicit priority (`registerCatalogPricingResolver(resolver, { priority })`)
 4. **MUST declare widget injections** in `widgets/injection/` and map via `injection-table.ts`
 5. **MUST follow the standard event pattern** in `events.ts` for all CRUD and lifecycle events
 
+## Ask First
+
+- Ask before changing price-layer precedence, resolver priority semantics, event IDs, or released widget spot IDs.
+- Ask before deleting or changing option schemas that existing variants may reference.
+
+## Never
+
+- Never reimplement catalog pricing inline.
+- Never delete option schemas while variants reference them.
+- Never bypass `prepareMutation` for catalog AI tools that mutate products, prices, or media.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+```
+
 ## When You Need Pricing Logic
 
 1. Resolve `catalogPricingService` from DI

package/src/modules/currencies/AGENTS.md

@@ -2,13 +2,32 @@
 
 Use the currencies module for multi-currency support, exchange rates, and currency conversion.
 
-## MUST Rules
+## Always
 
 1. **MUST store currency amounts with 4 decimal precision** — never truncate to 2 decimals internally
 2. **MUST use date-based exchange rates** — always resolve rates for the transaction date, not "current" rate
 3. **MUST record both transaction currency and base currency amounts** — dual recording is mandatory for reporting
 4. **MUST calculate realized gains/losses** on payment: `(payment rate - invoice rate) × foreign amount`
-5. **MUST NOT hard-delete exchange rate records** — rates are historical reference data
+5. **MUST keep financial postings atomic** — full transaction rollback on error
+
+## Ask First
+
+- Ask before changing precision, exchange-rate lookup semantics, realized gain/loss formulas, or financial reporting fields.
+- Ask before changing historical exchange-rate retention behavior.
+
+## Never
+
+- Never truncate internal currency amounts to 2 decimals.
+- Never hard-delete exchange rate records — rates are historical reference data.
+- Never delete posted transactions or audit-trail entries.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+```
 
 ## Key Files
 

package/src/modules/customer_accounts/AGENTS.md

@@ -2,7 +2,7 @@
 
 Customer-facing identity and portal authentication with a two-tier RBAC model. This module manages customer user accounts, sessions, roles, invitations, and the authentication flow for the customer portal. It is separate from the internal `auth` module, which handles staff authentication.
 
-## MUST Rules
+## Always
 
 1. **MUST hash passwords with `bcryptjs` (cost >= 10)** — never store plaintext passwords
 2. **MUST return minimal error messages on auth endpoints** — never reveal whether an email exists (use generic "Invalid email or password")
@@ -10,11 +10,31 @@ Customer-facing identity and portal authentication with a two-tier RBAC model. T
 4. **MUST validate all inputs with zod** — schemas live in `data/validators.ts`
 5. **MUST export `openApi`** from every API route file
 6. **MUST scope all queries by `tenantId`** and filter `deletedAt: null` for soft-deleted records
-7. **MUST NOT expose cross-tenant data** — session validation checks tenant match
-8. **MUST use `hashForLookup` for email-based lookups** — emails are stored with a deterministic hash for indexed queries
-9. **MUST use `hashToken` for storing session/verification/reset tokens** — raw tokens are never persisted
-10. **MUST emit events via `emitCustomerAccountsEvent`** for all state changes (login, signup, lock, password reset)
-11. **MUST NOT import staff auth services** — customer auth is a fully separate identity system
+7. **MUST use `hashForLookup` for email-based lookups** — emails are stored with a deterministic hash for indexed queries
+8. **MUST use `hashToken` for storing session/verification/reset tokens** — raw tokens are never persisted
+9. **MUST emit events via `emitCustomerAccountsEvent`** for all state changes (login, signup, lock, password reset)
+
+## Ask First
+
+- Ask before changing cookie names, token TTLs, JWT claim shape, rate limits, lockout thresholds, or portal RBAC semantics.
+- Ask before moving customer portal navigation into a different staff IA group.
+- Ask before changing CRM auto-linking behavior.
+
+## Never
+
+- Never store plaintext passwords or raw tokens.
+- Never reveal whether an email exists.
+- Never expose cross-tenant data — session validation checks tenant match.
+- Never import staff auth services; customer auth is a fully separate identity system.
+- Never use exact `includes(...)` checks for portal wildcard ACL matching.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+```
 
 ## Data Model
 

package/src/modules/customers/AGENTS.md

@@ -2,7 +2,7 @@
 
 **This is the reference CRUD module.** When building new modules, copy patterns from here first.
 
-## MUST Rules
+## Always
 
 1. **MUST use this module as the template** for new CRUD modules — copy file structure and patterns
 2. **MUST include all standard module files** — use the list below as a checklist
@@ -11,6 +11,25 @@
 5. **MUST capture custom field snapshots** in command `before`/`after` payloads for undo support
 6. **MUST use `useGuardedMutation` for non-`CrudForm` backend writes** (`POST`/`PUT`/`PATCH`/`DELETE`) and pass `retryLastMutation` in injection context
 
+## Ask First
+
+- Ask before changing this module's reference patterns, standard module-file checklist, or AI mutation policies.
+- Ask before changing customer data model relationships that downstream modules may copy.
+
+## Never
+
+- Never bypass custom field normalization in CRUD create/update/read responses.
+- Never omit undo snapshots for custom field mutations.
+- Never write backend `POST`/`PUT`/`PATCH`/`DELETE` actions outside `CrudForm` without `useGuardedMutation`.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+```
+
 ## Key Reference Files — Copy From Here
 
 | When you need | Copy from |

package/src/modules/data_sync/AGENTS.md

@@ -6,6 +6,36 @@ The `data_sync` module provides a streaming data synchronization hub for import/
 
 ---
 
+## Always
+
+- **Always scope by organizationId + tenantId** — every entity query
+- **Use the queue system** — never run syncs inline in API handlers
+- **New sync providers MUST support provider-owned env preconfiguration** when fresh installs need credentials or default mappings/locales/channels from deployment env
+- **Persist cursor after each batch** — enables resume on failure
+- **Log item-level errors** — don't stop the sync for individual item failures
+- **Check for overlap** before starting a new run (same integration + entityType + direction)
+- **API routes must export `openApi`** for documentation generation
+
+## Ask First
+
+- Ask before changing adapter contracts, run lifecycle states, cursor semantics, queue names, or overlap detection.
+- Ask before adding provider-specific logic to this generic module.
+- Ask before changing progress delivery or cancellation behavior.
+
+## Never
+
+- Never import from provider adapter modules — `data_sync` is generic.
+- Never run syncs inline in API handlers.
+- Never add frontend polling loops for sync progress beyond initial hydration or reconnect recovery.
+- Never special-case provider credentials, mappings, or state in `data_sync`.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn workspace @open-mercato/core build
+```
+
 ## Module Structure
 
 ```
@@ -152,14 +182,3 @@ Data sync providers can leverage the **Unified Module Extension System (UMES)**
 - Use helpers from `@open-mercato/core/modules/core/__integration__/helpers/*`
 - Tests must create prerequisites via API and clean up in `finally`
 - Avoid hard dependency on late-phase modules; keep tests scoped to implemented contracts
-
-## MUST Rules
-
-- **Always scope by organizationId + tenantId** — every entity query
-- **Never import from provider adapter modules** — data_sync is generic
-- **Use the queue system** — never run syncs inline in API handlers
-- **New sync providers MUST support provider-owned env preconfiguration** when fresh installs need credentials or default mappings/locales/channels from deployment env
-- **Persist cursor after each batch** — enables resume on failure
-- **Log item-level errors** — don't stop the sync for individual item failures
-- **Check for overlap** before starting a new run (same integration + entityType + direction)
-- **API routes must export `openApi`** for documentation generation

package/src/modules/integrations/AGENTS.md

@@ -6,6 +6,37 @@ The `integrations` module is the foundation layer for all external connectors (p
 
 ---
 
+## Always
+
+- **Always scope by organizationId + tenantId** — every entity query and service call
+- **Use `findWithDecryption`/`findOneWithDecryption`** for credential reads
+- **New providers MUST support provider-owned env preconfiguration** when credentials/settings are deployment-managed; implement it in the provider package, not in core
+- **Health check services** must be registered in DI by the provider module, not by integrations
+- **API routes must export `openApi`** for documentation generation
+- **All user-facing strings** via i18n keys in `i18n/en.json`
+- **Keep ACL default export shape** consistent: `export const features = [...]; export default features`
+- **Registry/type contracts** live in `@open-mercato/shared/modules/integrations/types`
+
+## Ask First
+
+- Ask before changing credential resolution order, registry type contracts, canonical API routes, or compatibility surfaces.
+- Ask before moving provider-specific logic into this module.
+- Ask before changing health-check timeouts, log retention semantics, or credential redaction behavior.
+
+## Never
+
+- Never import from provider modules — integrations module is generic; providers import from integrations, not vice versa.
+- Never log credential values — log service strips secret fields from payload.
+- Never special-case provider env presets, credentials, mappings, or enabled state in core.
+- Never remove legacy `integrations.detail:tabs` fallback without a compatibility plan.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn workspace @open-mercato/core build
+```
+
 ## Module Structure
 
 ```
@@ -192,16 +223,3 @@ The integrations module itself uses UMES to inject external ID displays on any e
 - Module-local integration tests go under `__integration__/`
 - Use helpers from `@open-mercato/core/modules/core/__integration__/helpers/*`
 - Tests must create prerequisites via API and clean up in `finally`
-
-## MUST Rules
-
-- **Never import from provider modules** — integrations module is generic; providers import from integrations, not vice versa
-- **Always scope by organizationId + tenantId** — every entity query and service call
-- **Use `findWithDecryption`/`findOneWithDecryption`** for credential reads
-- **New providers MUST support provider-owned env preconfiguration** when credentials/settings are deployment-managed; implement it in the provider package, not in core
-- **Never log credential values** — log service strips secret fields from payload
-- **Health check services** must be registered in DI by the provider module, not by integrations
-- **API routes must export `openApi`** for documentation generation
-- **All user-facing strings** via i18n keys in `i18n/en.json`
-- **Keep ACL default export shape** consistent: `export const features = [...]; export default features`
-- **Registry/type contracts** live in `@open-mercato/shared/modules/integrations/types`

package/src/modules/progress/AGENTS.md

@@ -2,7 +2,7 @@
 
 Use the progress module for every user-visible bulk operation and every long-running operation. Keep `ProgressTopBar` the single shared progress surface.
 
-## MUST Rules
+## Always
 
 1. **MUST create `ProgressJob` for durable work** — imports, exports, bulk mutations, reindexing, external sync, and queued work must persist progress server-side.
 2. **MUST return `progressJobId` to the UI** — DataTable bulk actions and start-operation APIs must expose the job id so the top bar can track it.
@@ -11,7 +11,25 @@ Use the progress module for every user-visible bulk operation and every long-run
 5. **MUST use queue workers for durable work** — use `@open-mercato/queue`; do not implement custom queues, timers, or page polling loops.
 6. **MUST run mutations through commands** — workers must use `commandBus.execute(...)` for domain writes so audit, undo, cache, events, and index invalidation stay intact.
 7. **MUST use client-local progress only for browser-bound loops** — local `client:*` progress events are best-effort and must not represent work that should survive navigation.
-8. **MUST NOT build per-module progress bars for global operations** — use `ProgressTopBar` and shared progress hooks.
+
+## Ask First
+
+- Ask before adding a new progress mode, changing job terminal states, or changing cancellation semantics.
+- Ask before creating a module-specific progress UI for work that could use the shared top bar.
+
+## Never
+
+- Never leave running jobs without heartbeat/progress updates.
+- Never implement custom queues, timers, or page polling loops for durable work.
+- Never represent durable server work with client-local `client:*` progress events.
+- Never build per-module progress bars for global operations — use `ProgressTopBar` and shared progress hooks.
+
+## Validation Commands
+
+```bash
+yarn generate
+yarn workspace @open-mercato/core build
+```
 
 ## Choosing Progress Mode
 

package/src/modules/sales/AGENTS.md

@@ -2,13 +2,32 @@
 
 Use the sales module for orders, quotes, invoices, shipments, and payments. This module has the most complex business logic in the system.
 
-## MUST Rules
+## Always
 
-1. **MUST NOT reimplement document math inline** — use `salesCalculationService` from DI
+1. **MUST use `salesCalculationService` from DI** for document math.
 2. **MUST follow document flow**: Quote → Order → Invoice — no skipping steps
-3. **MUST NOT modify configuration entities directly** (statuses, methods, channels) — use the admin UI or setup hooks
-4. **MUST use `selectBestPrice`** from catalog pricing helpers — never inline price calculations
-5. **MUST scope all documents to a channel** — channel selection affects pricing, numbering, and visibility
+3. **MUST use `selectBestPrice`** from catalog pricing helpers.
+4. **MUST scope all documents to a channel** — channel selection affects pricing, numbering, and visibility
+
+## Ask First
+
+- Ask before changing the Quote → Order → Invoice flow, workflow states, numbering rules, or channel scoping behavior.
+- Ask before changing configuration entity semantics for statuses, methods, channels, price kinds, adjustment kinds, or document numbers.
+
+## Never
+
+- Never reimplement document math inline.
+- Never skip configured document workflow states.
+- Never modify configuration entities directly; use the admin UI or setup hooks.
+- Never inline price calculations.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+```
 
 ## Document Flow
 

package/src/modules/workflows/AGENTS.md

@@ -2,19 +2,41 @@
 
 Use the workflows module for business process automation: defining step-based workflows, executing instances, handling user tasks, processing async activities, and triggering workflows from domain events.
 
-## MUST Rules
+## Always
 
 1. **MUST resolve services via DI** — use `container.resolve('workflowExecutor')`, never import and call lib functions directly
-2. **MUST NOT skip the execution loop** — always use `workflowExecutor.startWorkflow()` to create and run instances; never insert `WorkflowInstance` rows directly
+2. **MUST use `workflowExecutor.startWorkflow()`** to create and run instances.
 3. **MUST follow the step state machine** — steps transition `PENDING → ACTIVE → COMPLETED|FAILED|SKIPPED|CANCELLED`; never set status out of order
 4. **MUST follow the instance state machine** — instances transition `RUNNING → COMPLETED|FAILED|CANCELLED`; intermediate states include `PAUSED`, `WAITING_FOR_ACTIVITIES`, `COMPENSATING`
 5. **MUST keep activity handlers idempotent** — check state before mutating; activities may be retried on failure
 6. **MUST use event sourcing** — log all workflow events via `eventLogger.logWorkflowEvent()`; never mutate instance state without a corresponding event
 7. **MUST use variable interpolation** for dynamic activity config — use `{{context.*}}`, `{{workflow.*}}`, `{{env.*}}`, `{{now}}`; never hardcode values
-8. **MUST NOT couple other modules to workflow internals** — use event triggers and signals for cross-module integration; widget injection for UI
+8. **MUST use event triggers, signals, and widget injection** for cross-module integration.
 9. **MUST declare new events in `events.ts`** with `as const` — undeclared events trigger TypeScript errors and runtime warnings
 10. **MUST scope all queries by `organization_id`** — workflow data is tenant-scoped; never expose cross-tenant instances or tasks
 
+## Ask First
+
+- Ask before changing workflow, step, or activity state machines.
+- Ask before changing SSRF guard behavior, private URL allowances, compensation semantics, or trigger storm controls.
+- Ask before coupling another module directly to workflow internals.
+
+## Never
+
+- Never import and call workflow lib functions directly instead of resolving DI services.
+- Never skip the execution loop or insert `WorkflowInstance` rows directly.
+- Never mutate instance state without a corresponding workflow event.
+- Never expose cross-tenant workflow instances or tasks.
+- Never leave `OM_WORKFLOWS_ALLOW_PRIVATE_URLS` enabled in production.
+
+## Validation Commands
+
+```bash
+yarn db:generate
+yarn generate
+yarn workspace @open-mercato/core build
+```
+
 ## Execution Architecture
 
 ```