create-mercato-app 0.6.6-develop.6381.1.042df302c3 → 0.6.6-develop.6383.1.27fcc83455

package/agentic/guides/module-system.md

@@ -0,0 +1,130 @@
+# Open Mercato Module System — Conceptual Guide
+
+This is the **hand-written, conceptual** layer of the module guides. It explains how an Open Mercato module is structured and how to build or extend one — the timeless concepts that rarely change. It is framework-wide; it does **not** describe any single module's data.
+
+## How the guides are layered
+
+- **Layer 1 — this file (`.ai/guides/module-system.md`):** conceptual and framework-wide. Module anatomy, auto-discovery, naming, the mandatory mechanisms, data-integrity rules, and the generate/migration workflow.
+- **Layer 2 — generated per-module fact-sheets (`.ai/guides/modules/<module>.md` + `.ai/guides/module-facts.json`):** the concrete **facts** for one module, extracted from its source — entity IDs, events, ACL features, API routes with per-method auth, DI service tokens, searchable entities, host extension tokens, notifications, and CLI commands. These are generated; never hand-write them here.
+- **Package guides (`.ai/guides/core.md`, `ui.md`, `shared.md`, …):** package-specific depth (patterns, helpers, deeper APIs).
+
+When you need a concrete fact about a specific module — which events it emits, its entity IDs, which feature gates a route — open that module's fact-sheet. Do not infer module facts from this conceptual guide.
+
+## Module anatomy
+
+Each module lives in `src/modules/<id>/` and is **auto-discovered**. The only registration is one entry in `src/modules.ts` (`{ id: '<id>', from: '@app' }`). Run `yarn generate` after adding or changing any auto-discovered file.
+
+```
+src/modules/<id>/
+├── index.ts                # Module metadata
+├── data/
+│   ├── entities.ts         # MikroORM entity classes (decorators from @mikro-orm/decorators/legacy)
+│   ├── validators.ts       # Zod validation schemas
+│   ├── extensions.ts       # Cross-module entity links (export `extensions`)
+│   └── enrichers.ts        # Response enrichers (export `enrichers`)
+├── api/
+│   ├── <resource>/route.ts # REST handlers (auto-discovered by method) + `metadata` + `openApi`
+│   └── interceptors.ts     # API route interception hooks (export `interceptors`)
+├── backend/                # Admin UI pages (auto-discovered) + paired `page.meta.ts`
+├── frontend/               # Public pages (auto-discovered); customer portal under `[orgSlug]/portal/`
+├── subscribers/            # Event handlers (export `metadata` + default handler)
+├── workers/                # Background jobs (export `metadata` + default handler)
+├── widgets/
+│   ├── injection/          # UI widgets injected into other modules
+│   ├── injection-table.ts  # Widget-to-slot mappings
+│   └── components.ts        # Component replacement/wrapper definitions (export `componentOverrides`)
+├── di.ts                   # Awilix DI registrations (export `register(container)`)
+├── acl.ts                  # Permission features (export `features`)
+├── setup.ts                # Tenant init, role features, seed data (export `setup`)
+├── events.ts               # Typed event declarations (export `eventsConfig`)
+├── search.ts               # Search indexing configuration (export `searchConfig`)
+├── ce.ts                   # Custom entities / custom field sets (export `entities`)
+├── translations.ts         # Translatable fields per entity
+├── notifications.ts        # Notification type definitions (export `notificationTypes`)
+└── encryption.ts           # Tenant data encryption maps for sensitive / GDPR fields
+```
+
+### Auto-discovery paths
+
+| Path pattern | Becomes |
+|---|---|
+| `frontend/<path>.tsx` | `/<path>` (public page) |
+| `frontend/[orgSlug]/portal/<path>/page.tsx` | `/{orgSlug}/portal/<path>` (customer portal page; `[orgSlug]` MUST be first) |
+| `backend/<path>.tsx` | `/backend/<path>` (admin page) |
+| `backend/page.tsx` | `/backend/<module>` (module root page) |
+| `api/<method>/<path>.ts` | `/api/<path>` dispatched by HTTP method |
+| `subscribers/*.ts` | event subscriber (export `metadata` + default handler) |
+| `workers/*.ts` | background worker (export `metadata` + default handler) |
+
+### Convention-file reference
+
+| File | Export | Purpose |
+|------|--------|---------|
+| `index.ts` | `metadata` | Module metadata |
+| `di.ts` | `register(container)` | DI registrations (Awilix) |
+| `acl.ts` | `features` | Permission features (`['mod.view', 'mod.manage', …]`) |
+| `setup.ts` | `setup` | Tenant init, default role features, seed data |
+| `ce.ts` | `entities` | Custom entities / custom field sets |
+| `events.ts` | `eventsConfig` | Typed event declarations (`createModuleEvents`) |
+| `search.ts` | `searchConfig` | Search indexing config |
+| `translations.ts` | `translatableFields` | Translatable fields per entity |
+| `notifications.ts` | `notificationTypes` | Notification type definitions |
+| `data/entities.ts` | — | MikroORM entity classes |
+| `data/validators.ts` | — | Zod validation schemas |
+| `data/extensions.ts` | `extensions` | Entity extensions (cross-module links) |
+| `data/enrichers.ts` | `enrichers` | Response enrichers |
+| `api/interceptors.ts` | `interceptors` | API route interception hooks |
+| `widgets/components.ts` | `componentOverrides` | Component replacement/wrapper definitions |
+
+## Naming conventions
+
+- **Module IDs:** plural, snake_case (`order_items`). Special cases: `auth`, `example`.
+- **Event IDs:** `module.entity.action` (singular entity, past-tense action, e.g. `sales.order.created`).
+- **Entity IDs:** colon form `module:entity` (e.g. `customers:customer_person_profile`) — the canonical interop token, **not** the raw class name and **not** the dotted friendly alias some enrichers use.
+- **DB tables:** plural, snake_case with a module prefix (`catalog_products`).
+- **DB columns:** snake_case (`created_at`, `organization_id`). Common columns: `id`, `created_at`, `updated_at`, `deleted_at`, `is_active`, `organization_id`, `tenant_id`.
+- **Feature IDs:** `<module>.<action>` (`my_module.view`, `my_module.manage`). FROZEN once shipped — rename by adding the new ID alongside and keeping the old as a deprecated alias.
+- **JS/TS identifiers:** camelCase. UUID primary keys, explicit foreign keys, junction tables for M2M.
+
+## Mandatory module mechanisms
+
+The framework provides **one canonical primitive per concern**. Do not invent your own routing, auth, persistence, forms, caching, or cross-module calls. If a feature is not listed here, ask before rolling your own.
+
+| Concern | Canonical mechanism |
+|---|---|
+| Module structure & auto-discovery | `src/modules/<id>/{api,backend,frontend,data,subscribers,workers,widgets}` + `index.ts` + one line in `src/modules.ts` — discovered by `yarn generate` |
+| API routes | Files under `api/**/route.ts` exporting handlers + per-method `metadata` (`requireAuth` / `requireFeatures`) + `openApi`. NEVER a top-level `export const requireAuth` — the registry ignores it |
+| CRUD APIs | `makeCrudRoute({ orm, list, create, update, del, indexer })` from `@open-mercato/shared/lib/crud/factory`. Always set `indexer` for query-index coverage. Custom (non-factory) write routes MUST run the mutation guard registry (`runMutationGuards`) |
+| CRUD forms | `<CrudForm />` from `@open-mercato/ui/backend/CrudForm` + `createCrud`/`updateCrud`/`deleteCrud`. Never raw `<form>`, never raw `fetch` |
+| Data tables | `<DataTable entityId apiPath … />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` / `extensionTableId` stable so widget injection keeps working |
+| HTTP from the client | `apiCall` / `apiCallOrThrow` from `@open-mercato/ui/backend/utils/apiCall` — never raw `fetch` |
+| Authorization (RBAC) | Declare features in `acl.ts`, grant in `setup.ts` `defaultRoleFeatures`, gate with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER `requireRoles` (role names mutate). Treat `module.*` / `*` wildcard grants as part of the contract |
+| Multi-tenant scoping | Every tenant-scoped entity has indexed `organization_id` + `tenant_id`; every read/write filters by them. The CRUD factory injects scope — do not bypass it. Ad-hoc queries use `withScopedPayload` |
+| Encryption for sensitive data | Declare `encryption.ts` `defaultEncryptionMaps`; read via `findWithDecryption` / `findOneWithDecryption`. NEVER hand-roll AES/KMS, NEVER `em.find` on encrypted columns |
+| Cache | Resolve from DI (`container.resolve('cache')`) — never `new Redis(...)`. Tag with `tenant:<id>` / `org:<id>` so invalidation stays tenant-scoped |
+| Background workers | `workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues |
+| Events between modules | `events.ts` with `createModuleEvents({ moduleId, events } as const)`; subscribe in `subscribers/`. Never call another module's services directly across boundaries |
+| Domain writes | Implement through the Command pattern so audit, undo, cache, events, and indexing stay consistent — do not mutate domain state directly in route handlers |
+| i18n | `useT()` client-side, `resolveTranslations()` server-side; keys in `src/i18n/<locale>.json`. Never hard-code user-facing strings |
+
+> Rule of thumb: if you reach for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual cross-module join, stop and check the row above — there is a canonical helper.
+
+## Entity-update safety & data integrity
+
+- **`withAtomicFlush`.** MikroORM can silently discard pending scalar changes when a query (`em.find`/`em.findOne`/sync helper) runs on the same `EntityManager` between a scalar mutation and `em.flush()`. Multi-phase mutations MUST use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush`. Keep `emitCrudSideEffects` and cache invalidation **outside** the block — they fire only after the DB write commits. For entity + custom fields + side effects in one write, prefer `runCrudCommandWrite`.
+- **Optimistic locking (default ON).** Every **new user-editable entity** MUST carry an `updated_at` column and return `updatedAt` in its list/detail responses, so the OSS optimistic lock can detect concurrent edits. `CrudForm` auto-derives the lock header from `initialValues.updatedAt` (covers update and delete). Append-only logs, junction/assignment tables, session/token rows, and parent-guarded sub-resource lines are exempt.
+- **Encryption.** Sensitive / GDPR fields go through the encryption-maps mechanism (`encryption.ts` + `findWithDecryption`), never hand-rolled crypto. Always pass `tenantId` and `organizationId` to the decryption helpers.
+- **Tenant isolation.** Never expose cross-tenant data; always filter by `organization_id` (and `tenant_id`). Never create direct ORM relationships between modules — reference by FK id and fetch separately.
+
+## Generate & migration workflow
+
+- **After editing `src/modules.ts` or any structural module file:** run `yarn generate`. Never hand-edit anything under `.mercato/generated/*`.
+- **After editing `data/entities.ts`:** run `yarn db:generate` as a schema-diff probe. Default to the generated SQL; if it emits unrelated churn from another module's stale snapshot, keep only the SQL for your change and update that module's `migrations/.snapshot-open-mercato.json` in the same commit.
+- **Do not run `yarn db:migrate`** unless the user explicitly asks. A PR should normally include the migration file plus snapshot, not local DB state. Never hand-edit a migration that has already shipped — add a new one.
+- **New ACL features must be visible immediately:** add the feature to `acl.ts` **and** to `setup.ts` `defaultRoleFeatures`, then run `yarn mercato auth sync-role-acls` so existing tenants pick it up.
+
+## Where to go next
+
+- A specific module's surface (entities, events, routes, auth, search, CLI): its **fact-sheet** at `.ai/guides/modules/<module>.md`.
+- Deeper package patterns: the matching **package guide** (`core.md`, `ui.md`, `shared.md`, `events.md`, `queue.md`, `cache.md`, `search.md`).
+- Scaffolding a module end-to-end: the `om-module-scaffold` skill.

package/agentic/shared/AGENTS.md.template

@@ -21,6 +21,7 @@ step, you WILL produce incorrect imports and miss required patterns.
 
 | Task | Load |
 |---|---|
+| Understand the module system (anatomy, auto-discovery, naming, mandatory mechanisms, data integrity, migrations) | `.ai/guides/module-system.md` |
 | Scaffold a new module from scratch | `.ai/skills/om-module-scaffold/SKILL.md` |
 | Design entities and relationships | `.ai/skills/om-data-model-design/SKILL.md` |
 | Build backend UI (forms, tables, pages) | `.ai/skills/om-backend-ui-design/SKILL.md` |
@@ -60,19 +61,10 @@ step, you WILL produce incorrect imports and miss required patterns.
 
 ### Module-Specific Guides
 
-These guides ship automatically when the corresponding module is installed.
+These per-module fact-sheets are **generated from source** and bundled for the modules enabled in this app. The list below is regenerated on scaffold from your enabled module set — do not edit between the markers.
 
-| Task | Load |
-|---|---|
-| Build CRUD modules — reference patterns, commands, custom fields, search | `.ai/guides/core.customers.md` (if available) |
-| Use workflow automation, triggers, user tasks, signals | `.ai/guides/core.workflows.md` (if available) |
-| Use product catalog, pricing engine, variants, offers | `.ai/guides/core.catalog.md` (if available) |
-| Use sales orders, quotes, invoices, shipments, payments | `.ai/guides/core.sales.md` (if available) |
-| Use staff authentication, RBAC, roles, feature guards | `.ai/guides/core.auth.md` (if available) |
-| Use multi-currency, exchange rates, dual recording | `.ai/guides/core.currencies.md` (if available) |
-| Build integration providers, credentials, health checks | `.ai/guides/core.integrations.md` (if available) |
-| Build data sync adapters, import/export connectors | `.ai/guides/core.data_sync.md` (if available) |
-| Use customer portal auth, customer RBAC, portal pages | `.ai/guides/core.customer_accounts.md` (if available) |
+<!-- om:module-guides:start -->
+<!-- om:module-guides:end -->
 
 ### Quality & Process
 

package/dist/agentic/guides/core.auth.md

@@ -1,101 +1,3 @@
-# Auth Module — Standalone App Guide
+# core.auth — moved
 
-The auth module handles staff authentication, authorization, users, roles, and RBAC. For customer portal authentication, see the `customer_accounts` module guide.
-
-## RBAC Implementation
-
-### Two-Layer Model
-
-1. **Role ACLs** — features assigned to roles (admin, employee, etc.)
-2. **User ACLs** — per-user overrides (additional features or restrictions)
-
-Effective permissions = Role features + User-specific features.
-
-### Declaring Features
-
-Every module MUST declare features in `acl.ts` and wire them in `setup.ts`:
-
-```typescript
-// src/modules/<your_module>/acl.ts
-export const features = [
-  'your_module.view',
-  'your_module.create',
-  'your_module.update',
-  'your_module.delete',
-]
-
-// src/modules/<your_module>/setup.ts
-import type { ModuleSetupConfig } from '@open-mercato/shared/modules/setup'
-
-export const setup: ModuleSetupConfig = {
-  defaultRoleFeatures: {
-    superadmin: ['your_module.*'],
-    admin: ['your_module.*'],
-    user: ['your_module.view'],
-  },
-}
-```
-
-### Feature Naming Convention
-
-Features follow the `<module>.<action>` pattern (e.g., `users.view`, `users.edit`).
-
-### Declarative Guards
-
-Prefer declarative guards in page and API metadata:
-
-```typescript
-export const metadata = {
-  requireAuth: true,
-  requireRoles: ['admin'],
-  requireFeatures: ['users.manage'],
-}
-```
-
-### Server-Side Checks
-
-```typescript
-const rbacService = container.resolve('rbacService')
-const hasAccess = await rbacService.userHasAllFeatures(
-  userId,
-  ['your_module.view'],
-  { tenantId, organizationId }
-)
-```
-
-### Wildcards
-
-Wildcards are first-class ACL grants: `module.*` and `*` satisfy matching concrete features. When your code inspects raw granted feature arrays (instead of calling `rbacService`), use the shared wildcard-aware matchers (`matchFeature`, `hasFeature`, `hasAllFeatures`) — never use `includes(...)`.
-
-### Special Flags
-
-- `isSuperAdmin` — bypasses all feature checks
-- Organization visibility list — restricts which organizations a user can access
-
-## Security Rules
-
-- Hash passwords with `bcryptjs` (cost >= 10)
-- Never log credentials
-- Return minimal auth error messages — never reveal whether an email exists
-- Use `findWithDecryption` / `findOneWithDecryption` for user queries
-
-## Authentication Flow
-
-1. User submits credentials via `POST /api/auth/session`
-2. Password verified with bcryptjs
-3. JWT session token issued
-4. Session attached to requests via middleware
-
-## Subscribing to Auth Events
-
-```typescript
-export const metadata = {
-  event: 'auth.user.created',
-  persistent: true,
-  id: 'your-module-user-created',
-}
-
-export default async function handler(payload, ctx) {
-  // React to new user registration
-}
-```
+> This guide has moved. See [`modules/auth.md`](modules/auth.md) for the generated `auth` fact-sheet, and [`module-system.md`](module-system.md) for conceptual module guidance.

package/dist/agentic/guides/core.catalog.md

@@ -1,79 +1,3 @@
-# Catalog Module — Standalone App Guide
+# core.catalog — moved
 
-Use the catalog module for products, categories, pricing, variants, and offers.
-
-## Pricing System
-
-Never reimplement pricing logic. Use the catalog pricing service via DI:
-
-```typescript
-const pricingService = container.resolve('catalogPricingService')
-```
-
-- `selectBestPrice` — finds the best price for a given context (customer, channel, quantity)
-- `resolvePriceVariantId` — resolves variant-level prices
-- Register custom pricing resolvers with priority (higher = checked first):
-
-```typescript
-import { registerCatalogPricingResolver } from '@open-mercato/core/modules/catalog/lib/pricing'
-registerCatalogPricingResolver(myResolver, { priority: 10 })
-```
-
-Price layers compose in order: base price → channel override → customer-specific → promotional.
-
-The pipeline emits `catalog.pricing.resolve.before` and `catalog.pricing.resolve.after` events that your module can subscribe to.
-
-## Data Model
-
-| Entity | Purpose | Key Constraints |
-|--------|---------|----------------|
-| **Products** | Core items with media and descriptions | MUST have at least a name |
-| **Categories** | Hierarchical product grouping | No circular parent-child references |
-| **Variants** | Product variations (size, color) | MUST reference valid option schemas |
-| **Prices** | Multi-tier with channel scoping | Use `selectBestPrice` for resolution |
-| **Offers** | Time-limited promotions | MUST have valid date ranges |
-| **Option Schemas** | Variant option type definitions | Cannot delete while variants reference them |
-
-## Subscribing to Catalog Events
-
-React to product lifecycle events in your module:
-
-```typescript
-// src/modules/<your_module>/subscribers/product-updated.ts
-export const metadata = {
-  event: 'catalog.product.updated',
-  persistent: true,
-  id: 'your-module-product-updated',
-}
-
-export default async function handler(payload, ctx) {
-  // payload.resourceId = product ID
-}
-```
-
-Key events:
-- `catalog.product.created` / `updated` / `deleted`
-- `catalog.pricing.resolve.before` / `after` (excluded from workflow triggers)
-
-## Extending Catalog UI
-
-Use widget injection to add your module's UI into catalog pages:
-
-```typescript
-// src/modules/<your_module>/widgets/injection-table.ts
-export const widgetInjections = {
-  'crud-form:catalog.catalog_product:fields': {
-    widgetId: 'your-module-product-fields',
-    priority: 100,
-  },
-}
-```
-
-Common injection spots:
-- `crud-form:catalog.catalog_product:fields` — product edit form
-- `data-table:catalog.products:columns` — product list columns
-- `data-table:catalog.products:row-actions` — product row actions
-
-## Using Catalog in Sales
-
-When building sales-related features, use the catalog pricing service to resolve prices rather than reading price entities directly. This ensures channel scoping, customer-specific pricing, and promotional offers are applied correctly.
+> This guide has moved. See [`modules/catalog.md`](modules/catalog.md) for the generated `catalog` fact-sheet, and [`module-system.md`](module-system.md) for conceptual module guidance.

package/dist/agentic/guides/core.currencies.md

@@ -1,43 +1,3 @@
-# Currencies Module — Standalone App Guide
+# core.currencies — moved
 
-Use the currencies module for multi-currency support, exchange rates, and currency conversion.
-
-## Key Rules
-
-1. **Store amounts with 4 decimal precision** — never truncate to 2 decimals internally
-2. **Use date-based exchange rates** — always resolve rates for the transaction date, not the "current" rate
-3. **Record both currencies** — dual recording (transaction currency + base currency) is mandatory for reporting
-4. **Calculate realized gains/losses** on payment: `(payment rate - invoice rate) × foreign amount`
-5. **Never hard-delete exchange rates** — they are historical reference data
-
-## Multi-Currency Transaction Pattern
-
-When processing multi-currency transactions (e.g., sales invoice in EUR with USD base):
-
-1. Retrieve the exchange rate for the transaction date
-2. Generate the document in the transaction currency
-3. Calculate the base currency equivalent: `foreign amount × rate`
-4. Store both amounts on the document
-5. On payment: calculate realized gain/loss from rate difference
-6. Report in both transaction and base currencies
-
-## Data Model
-
-| Entity | Table | Purpose |
-|--------|-------|---------|
-| **Currency** | `currency` | Currency master data (code, name, symbol) |
-| **Exchange Rate** | `exchange_rate` | Daily exchange rates per currency pair |
-
-## Adding a New Currency
-
-1. Add the currency record via the admin UI or `seedDefaults` hook in your `setup.ts`
-2. Ensure exchange rates exist for the currency pair at required dates
-3. Verify all sales/pricing logic resolves the new currency correctly
-
-## Using Currencies in Your Module
-
-When your module deals with monetary amounts:
-- Store the currency code alongside the amount
-- Reference the currencies module for exchange rate lookups
-- Use the transaction date for rate resolution, not the current date
-- Store both foreign and base amounts for reporting
+> This guide has moved. See [`modules/currencies.md`](modules/currencies.md) for the generated `currencies` fact-sheet, and [`module-system.md`](module-system.md) for conceptual module guidance.

package/dist/agentic/guides/core.customer_accounts.md

@@ -1,129 +1,3 @@
-# Customer Accounts Module — Standalone App Guide
+# core.customer_accounts — moved
 
-Customer-facing identity and portal authentication. This module manages customer user accounts, sessions, roles, and the authentication flow for the customer portal. It is separate from the staff `auth` module.
-
-## Portal Authentication
-
-### Login Flow
-1. Customer submits credentials via `POST /api/login`
-2. Password verified with bcryptjs, lockout checked (5 attempts → 15 min lock)
-3. JWT issued with customer claims (`type: 'customer'`, features, CRM links)
-4. Two cookies set: `customer_auth_token` (JWT, 8h) + `customer_session_token` (raw, 30d)
-
-### Other Auth Methods
-- **Signup**: `POST /api/signup` — self-registration with email verification
-- **Magic Link**: `POST /api/magic-link/request` + `/verify` — passwordless login (15 min TTL)
-- **Password Reset**: `POST /api/password/reset-request` + `/reset-confirm` (60 min TTL)
-- **Invitation**: Admin invites user → `POST /api/invitations/accept` (72h TTL)
-
-## Customer RBAC
-
-### Two-Layer Model (mirrors staff RBAC)
-1. **Role ACLs** — features assigned to roles
-2. **User ACLs** — per-user overrides (takes precedence if present)
-
-### Default Roles (seeded on tenant creation)
-| Role | Features | Portal Admin |
-|------|----------|-------------|
-| Portal Admin | `portal.*` | Yes |
-| Buyer | Orders, quotes, catalog, account | No |
-| Viewer | Read-only orders, invoices, catalog | No |
-
-### Feature Convention
-Portal features use `portal.<area>.<action>` naming (e.g., `portal.orders.view`, `portal.catalog.view`).
-
-### Cross-Module Feature Merging
-Your module can declare `defaultCustomerRoleFeatures` in `setup.ts`. During tenant setup, these are merged into the corresponding customer role ACLs:
-
-```typescript
-// src/modules/<your_module>/setup.ts
-export const setup: ModuleSetupConfig = {
-  defaultCustomerRoleFeatures: {
-    portal_admin: ['portal.your_feature.*'],
-    buyer: ['portal.your_feature.view'],
-  },
-}
-```
-
-## Using Customer Auth in Your Module
-
-### Server Components (pages)
-```typescript
-import { getCustomerAuthFromCookies } from '@open-mercato/core/modules/customer_accounts/lib/customerAuthServer'
-
-const auth = await getCustomerAuthFromCookies()
-if (!auth) redirect('/login')
-```
-
-### API Routes
-```typescript
-import { requireCustomerAuth, requireCustomerFeature } from '@open-mercato/core/modules/customer_accounts/lib/customerAuth'
-import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
-import type { CustomerRbacService } from '@open-mercato/core/modules/customer_accounts/services/customerRbacService'
-
-// In your API handler:
-const auth = await requireCustomerAuth(request)  // throws 401 if not authenticated
-const container = await createRequestContainer()
-const customerRbacService = container.resolve('customerRbacService') as CustomerRbacService
-// Re-resolves ACL on every request so role/feature revocation is immediate
-await requireCustomerFeature(auth, ['portal.orders.view'], customerRbacService)  // throws 403 if missing
-```
-
-### RBAC Service
-```typescript
-const rbacService = container.resolve('customerRbacService')
-const hasAccess = await rbacService.userHasAllFeatures(
-  userId, ['portal.orders.view'], { tenantId, organizationId }
-)
-```
-
-## Portal Page Guards
-
-Use declarative metadata for portal pages:
-
-```typescript
-export const metadata = {
-  requireCustomerAuth: true,
-  requireCustomerFeatures: ['portal.orders.view'],
-}
-```
-
-## Subscribing to Customer Events
-
-| Event | When |
-|-------|------|
-| `customer_accounts.user.created` | New customer signup |
-| `customer_accounts.user.updated` | Profile updated |
-| `customer_accounts.user.locked` | Account locked after failed logins |
-| `customer_accounts.login.success` | Successful login |
-| `customer_accounts.invitation.accepted` | Invitation accepted |
-
-```typescript
-export const metadata = {
-  event: 'customer_accounts.user.created',
-  persistent: true,
-  id: 'your-module-customer-signup',
-}
-
-export default async function handler(payload, ctx) {
-  // React to customer signup — e.g., create default preferences
-}
-```
-
-## CRM Auto-Linking
-
-When a customer signs up, the module automatically searches for a matching CRM person by email and links them (`personEntityId`). The reverse also works — creating a CRM person auto-links to an existing customer user.
-
-## Widget Injection Spots
-
-| Spot | Widget | Purpose |
-|------|--------|---------|
-| `crud-form:customers:customer_person_profile:fields` | Account status | Shows portal account status on CRM person detail |
-| `crud-form:customers:customer_company_profile:fields` | Company users | Shows portal users linked to a CRM company |
-
-## Security Notes
-
-- All public endpoints are rate-limited (per-email + per-IP)
-- Tokens stored as SHA-256 hashes — raw tokens never persisted
-- Emails use deterministic hash for lookups (`hashForLookup`)
-- Error messages never confirm whether an email is registered
+> This guide has moved. See [`modules/customer_accounts.md`](modules/customer_accounts.md) for the generated `customer_accounts` fact-sheet, and [`module-system.md`](module-system.md) for conceptual module guidance.

package/dist/agentic/guides/core.customers.md

@@ -1,138 +1,3 @@
-# Customers Module — Reference CRUD Patterns
+# core.customers — moved
 
-This is the **reference CRUD module**. When building new modules in your standalone app, follow these patterns.
-
-## CRUD API Pattern
-
-Use `makeCrudRoute` with `indexer: { entityType }` for query index coverage:
-
-```typescript
-// src/modules/<your_module>/api/get/<entities>.ts
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
-import { YourEntity } from '../../entities/YourEntity'
-
-const handler = makeCrudRoute({
-  entity: YourEntity,
-  entityId: 'your_module.your_entity',
-  operations: ['list', 'detail'],
-  indexer: { entityType: 'your_module.your_entity' },
-})
-
-export default handler
-export const openApi = { summary: 'List and retrieve entities', tags: ['Your Module'] }
-```
-
-Key points:
-- Always set `indexer: { entityType }` — keeps custom entities indexed
-- Wire custom field helpers for create/update if your module supports custom fields
-- Export `openApi` on every API route file
-
-## Undoable Commands Pattern
-
-All write operations should use the Command pattern with undo support:
-
-```typescript
-import { registerCommand } from '@open-mercato/shared/lib/commands'
-import { extractUndoPayload } from '@open-mercato/shared/lib/commands/undo'
-
-registerCommand('your_module.entity.create', {
-  async execute(payload, ctx) {
-    // 1. Create entity
-    // 2. Capture snapshot for undo: extractUndoPayload(entity)
-    // 3. Side effects: emitCrudSideEffects({ indexer: { entityType, cacheAliases } })
-  },
-  async undo(payload, ctx) {
-    // 1. Restore from snapshot
-    // 2. Side effects: emitCrudUndoSideEffects({ indexer: { entityType, cacheAliases } })
-  },
-})
-```
-
-Key points:
-- Include `indexer: { entityType, cacheAliases }` in both `emitCrudSideEffects` and `emitCrudUndoSideEffects`
-- Capture custom field snapshots in `before`/`after` payloads (`snapshot.custom`)
-- Restore custom fields via `buildCustomFieldResetMap(before.custom, after.custom)` in undo
-
-## Custom Field Integration
-
-```typescript
-import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customFieldValues'
-```
-
-- Pass `{ transform }` to normalize values (e.g., `normalizeCustomFieldSubmitValue`)
-- Works for both `cf_` and `cf:` prefixed keys
-- Pass `entityIds` to form helpers so correct custom-field sets are loaded
-- If your module ships default custom fields, declare them in `ce.ts` via `entities[].fields`
-
-## Search Configuration
-
-Declare in `search.ts` with all three strategies:
-
-```typescript
-import type { SearchModuleConfig } from '@open-mercato/shared/modules/search'
-
-export const searchConfig: SearchModuleConfig = {
-  entities: {
-    'your_module.your_entity': {
-      fields: ['name', 'description'],  // Fulltext indexing
-      // fieldPolicy for sensitive field handling
-      // buildSource for vector embeddings
-      // formatResult for search result display
-    },
-  },
-}
-```
-
-Key points:
-- Use `fieldPolicy.excluded` for sensitive fields (passwords, tokens)
-- Use `fieldPolicy.hashOnly` for PII needing exact-match only (email, phone)
-- Always define `formatResult` for human-friendly search results
-
-## Backend Page Structure
-
-Follow this pattern for each page type:
-
-| Page | Pattern | Key Features |
-|------|---------|-------------|
-| **List** | `DataTable` | Filters, search, export, row actions, pagination |
-| **Create** | `CrudForm` mode=create | Fields, groups, custom fields, back link |
-| **Detail/Edit** | `CrudForm` mode=edit or tabbed layout | Entity data, related entities, activities |
-
-## Module Files Checklist
-
-When scaffolding a new CRUD module, ensure all these files are present:
-
-| File | Purpose |
-|------|---------|
-| `index.ts` | Module metadata |
-| `acl.ts` | Feature-based permissions |
-| `setup.ts` | Tenant init, default role features |
-| `di.ts` | Awilix DI registrations |
-| `events.ts` | Typed event declarations |
-| `data/entities.ts` | MikroORM entity classes |
-| `data/validators.ts` | Zod validation schemas |
-| `search.ts` | Search indexing configuration |
-| `ce.ts` | Custom entities / custom field sets |
-
-Optional:
-- `translations.ts` — translatable fields per entity
-- `notifications.ts` — notification type definitions
-- `cli.ts` — module CLI commands
-
-## Entity Update Safety
-
-When mutating entities across multiple phases that include queries:
-
-```typescript
-import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
-
-await withAtomicFlush(em, [
-  () => { record.name = 'New'; record.status = 'active' },
-  () => syncEntityTags(em, record, tags),
-], { transaction: true })
-
-// Side effects AFTER the atomic flush
-await emitCrudSideEffects({ ... })
-```
-
-Never run `em.find`/`em.findOne` between scalar mutations and `em.flush()` without `withAtomicFlush` — changes will be silently lost. Cache invalidation must also stay outside `withAtomicFlush` and fire after commit, so the opt-in `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` mode (default OFF) never serves stale or partially-committed reads.
+> This guide has moved. See [`modules/customers.md`](modules/customers.md) for the generated `customers` fact-sheet, and [`module-system.md`](module-system.md) for conceptual module guidance.