@open-mercato/cli 0.6.5 → 0.6.6-canary.315.1.g6673635216

package/.turbo/turbo-build.log

@@ -1,4 +1,59 @@
-[build:cli] found 89 entry points
+[build:cli] found 93 entry points
 Copied create-app/agentic/ → dist/agentic/
-Discovered 16 standalone guides → dist/agentic/guides/
+Discovered 7 standalone guides → dist/agentic/guides/
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for ai_assistant
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_gmail
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for checkout
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for content
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_docs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_keys
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for attachments
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for audit_logs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for auth
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for business_rules
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for catalog
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for communication_channels
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for configs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for currencies
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customer_accounts
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customers
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dashboards
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for data_sync
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dictionaries
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for directory
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for entities
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for feature_toggles
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for inbox_ops
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for integrations
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for messages
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for notifications
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for payment_gateways
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for perspectives
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for planner
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for portal
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for progress
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for query_index
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for resources
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sales
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for shipping_carriers
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for staff
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_excel
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for translations
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for workflows
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for record_locks
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for security
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sso
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for system_status_overlays
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for events
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for gateway_stripe
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for onboarding
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for scheduler
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for search
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for generators
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for storage_s3
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_akeneo
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for webhooks
+Generated 53 module fact-sheets → dist/agentic/guides/modules/
+Wrote 9 legacy core.<module>.md redirect stubs → dist/agentic/guides/
 [build:cli] built successfully

package/build.mjs

@@ -1,6 +1,6 @@
-import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync } from 'node:fs'
+import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
-import { fileURLToPath } from 'node:url'
+import { fileURLToPath, pathToFileURL } from 'node:url'
 import { atomicWriteFileSync } from '../../scripts/lib/add-js-extension.mjs'
 import { buildPackage } from '../../scripts/build-package.mjs'
 
@@ -35,6 +35,18 @@ await buildPackage(packageDir, {
     const guidesDestDir = join(outdir, 'agentic', 'guides')
     mkdirSync(guidesDestDir, { recursive: true })
 
+    // Clean stale per-module artifacts before regenerating so an incremental dist never
+    // retains a removed module's full guide or fact-sheet — a removed `core.<module>.md`
+    // (two-dot, per-module) must come back as a redirect stub, not linger as a full guide.
+    // Mirrors packages/create-app/build.mjs; the conceptual `module-system.md` and the
+    // single-dot package guides are re-copied/re-discovered below.
+    rmSync(join(guidesDestDir, 'modules'), { recursive: true, force: true })
+    for (const entry of readdirSync(guidesDestDir)) {
+      if (/^core\..+\.md$/.test(entry)) {
+        rmSync(join(guidesDestDir, entry))
+      }
+    }
+
     let guidesFound = 0
     for (const pkg of readdirSync(packagesDir)) {
       const guideSource = join(packagesDir, pkg, 'agentic', 'standalone-guide.md')
@@ -58,5 +70,71 @@ await buildPackage(packageDir, {
     if (guidesFound > 0) {
       console.log(`Discovered ${guidesFound} standalone guides → dist/agentic/guides/`)
     }
+
+    // Generate per-module fact-sheets (Layer 2) for every package-provided module via
+    // the freshly built ts-morph extractor + resolver-routed discovery, so
+    // `mercato agentic:init` bundles the same guides as a create-mercato-app scaffold
+    // (packages/create-app/build.mjs). Discovery goes through the resolver, never a
+    // hardcoded packages/* path (.ai/lessons.md §161-169).
+    const { extractAllModuleFacts, renderModuleFactsJson, MODULE_FACTS_ALLOWLIST } = await import(
+      pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href
+    )
+    const { discoverPackageModuleSources } = await import(
+      pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts-discovery.js')).href
+    )
+    const { createResolver } = await import(pathToFileURL(join(outdir, 'lib', 'resolver.js')).href)
+
+    const sources = discoverPackageModuleSources(createResolver(join(packagesDir, '..')))
+    if (sources.length > 0) {
+      const registryPath = join(packagesDir, '..', 'apps', 'mercato', '.mercato', 'generated', 'modules.runtime.generated.ts')
+      let coreVersion = null
+      try {
+        coreVersion = JSON.parse(readFileSync(join(packagesDir, 'core', 'package.json'), 'utf8')).version ?? null
+      } catch {
+        coreVersion = null
+      }
+
+      const { factsByModule, markdownByModule, warnings } = extractAllModuleFacts({
+        sources,
+        registryPath: existsSync(registryPath) ? registryPath : null,
+        coreVersion,
+      })
+
+      const modulesGuidesDir = join(guidesDestDir, 'modules')
+      mkdirSync(modulesGuidesDir, { recursive: true })
+      for (const [moduleId, markdown] of Object.entries(markdownByModule)) {
+        writeFileSync(join(modulesGuidesDir, `${moduleId}.md`), markdown)
+      }
+      writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(factsByModule))
+
+      for (const warning of warnings) console.warn(warning)
+      console.log(`Generated ${Object.keys(markdownByModule).length} module fact-sheets → dist/agentic/guides/modules/`)
+
+      // BC bridge (spec §7 generated-file contract): the legacy hand-written guides
+      // existed only for the historical allowlisted modules, so redirect stubs are
+      // emitted for that set alone — never for auto-discovered modules that never had a
+      // `core.<module>.md`. Fresh scaffolds never link these names; they exist only for
+      // apps upgrading in place.
+      const bundled = new Set(Object.keys(markdownByModule))
+      let stubsWritten = 0
+      for (const moduleId of MODULE_FACTS_ALLOWLIST) {
+        if (!bundled.has(moduleId)) continue
+        const legacyGuidePath = join(guidesDestDir, `core.${moduleId}.md`)
+        if (!existsSync(legacyGuidePath)) {
+          writeFileSync(
+            legacyGuidePath,
+            `# core.${moduleId} — moved\n\n` +
+              `> This guide has moved. See [\`modules/${moduleId}.md\`](modules/${moduleId}.md) for the generated ` +
+              `\`${moduleId}\` fact-sheet, and [\`module-system.md\`](module-system.md) for conceptual module guidance.\n`,
+          )
+          stubsWritten++
+        }
+      }
+      if (stubsWritten > 0) {
+        console.log(`Wrote ${stubsWritten} legacy core.<module>.md redirect stubs → dist/agentic/guides/`)
+      }
+    } else {
+      console.warn('[module-facts] no package modules discovered; skipping fact-sheet generation')
+    }
   },
 })

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.