@open-mercato/core 0.4.11-develop.1347.c693e6dfee → 0.4.11-develop.1354.54d40d164a

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/core",
-  "version": "0.4.11-develop.1347.c693e6dfee",
+  "version": "0.4.11-develop.1354.54d40d164a",
   "type": "module",
   "main": "./dist/index.js",
   "scripts": {
@@ -230,10 +230,10 @@
     "ts-pattern": "^5.0.0"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.4.11-develop.1347.c693e6dfee"
+    "@open-mercato/shared": "0.4.11-develop.1354.54d40d164a"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.4.11-develop.1347.c693e6dfee",
+    "@open-mercato/shared": "0.4.11-develop.1354.54d40d164a",
     "@testing-library/dom": "^10.4.1",
     "@testing-library/jest-dom": "^6.9.1",
     "@testing-library/react": "^16.3.1",

package/src/modules/auth/agentic/standalone-guide.md

@@ -0,0 +1,101 @@
+# Auth Module — Standalone App Guide
+
+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
+}
+```

package/src/modules/catalog/agentic/standalone-guide.md

@@ -0,0 +1,79 @@
+# Catalog Module — Standalone App Guide
+
+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.

package/src/modules/currencies/agentic/standalone-guide.md

@@ -0,0 +1,43 @@
+# Currencies Module — Standalone App Guide
+
+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

package/src/modules/customer_accounts/agentic/standalone-guide.md

@@ -0,0 +1,124 @@
+# Customer Accounts Module — Standalone App Guide
+
+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'
+
+// In your API handler:
+const auth = requireCustomerAuth(request)  // throws 401 if not authenticated
+requireCustomerFeature(auth, ['portal.orders.view'])  // 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

package/src/modules/customers/agentic/standalone-guide.md

@@ -0,0 +1,138 @@
+# Customers Module — Reference CRUD Patterns
+
+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.

package/src/modules/data_sync/agentic/standalone-guide.md

@@ -0,0 +1,107 @@
+# Data Sync Module — Standalone App Guide
+
+The data sync module provides a streaming synchronization hub for import/export operations with external systems. Provider modules register `DataSyncAdapter` implementations.
+
+## Creating a Sync Adapter
+
+Implement the `DataSyncAdapter` interface in your provider module:
+
+```typescript
+import type { DataSyncAdapter } from '@open-mercato/core/modules/data_sync/lib/adapter'
+
+const myAdapter: DataSyncAdapter = {
+  providerKey: 'my_provider',
+  direction: 'import',  // 'import' | 'export' | 'bidirectional'
+  supportedEntities: ['catalog.product', 'customers.person'],
+
+  async *streamImport(entityType, cursor, config) {
+    // Yield ImportBatch objects with records
+    yield { records: [...], cursor: 'next-page-token' }
+  },
+
+  async validateConnection(credentials) {
+    // Verify external system is reachable
+    return { valid: true }
+  },
+
+  async getInitialCursor(entityType) {
+    return null  // Start from beginning
+  },
+}
+```
+
+Register in your module's `di.ts`:
+```typescript
+import { registerDataSyncAdapter } from '@open-mercato/core/modules/data_sync/lib/adapter-registry'
+registerDataSyncAdapter(myAdapter)
+```
+
+## Run Lifecycle
+
+```
+pending → running → completed | failed | cancelled
+```
+
+- **Cursor persistence**: After each batch, cursor is saved — enables resume on failure
+- **Progress**: Linked to `ProgressJob` for live progress display via `ProgressTopBar`
+- **Cancellation**: Via `progressService.isCancellationRequested()`
+- **Overlap protection**: Only one sync per integration + entityType + direction at a time
+
+## Key Services (DI)
+
+| Service | Purpose |
+|---------|---------|
+| `dataSyncRunService` | CRUD for sync runs, cursor management, overlap detection |
+| `dataSyncEngine` | Orchestrates streaming import/export with batch processing and progress |
+| `externalIdMappingService` | Maps local entity IDs to/from external system IDs |
+
+## Starting a Sync
+
+Via API:
+```
+POST /api/data_sync/run
+{ "integrationId": "my_provider", "entityType": "catalog.product", "direction": "import" }
+```
+
+Syncs run asynchronously via the queue system — never run inline in API handlers.
+
+## Queue Workers
+
+| Queue | Worker | Concurrency |
+|-------|--------|-------------|
+| `data-sync-import` | Import handler | 5 |
+| `data-sync-export` | Export handler | 5 |
+| `data-sync-scheduled` | Scheduled sync dispatch | 3 |
+
+## Events
+
+| Event | When |
+|-------|------|
+| `data_sync.run.started` | Sync begins processing |
+| `data_sync.run.completed` | Sync finishes successfully |
+| `data_sync.run.failed` | Sync fails |
+| `data_sync.run.cancelled` | Sync is cancelled |
+
+Subscribe to these events to trigger post-sync side effects in your module.
+
+## UMES Extension Points
+
+Sync providers can extend the platform UI:
+
+| Extension | Use Case |
+|-----------|----------|
+| **Widget Injection** | Sync status badges, mapping previews on entity pages |
+| **Event Subscribers** | React to sync lifecycle events |
+| **Entity Extensions** | Link sync metadata to core entities |
+| **Response Enrichers** | Attach external ID data to API responses |
+| **Notifications** | Alerts on sync completion/failure |
+| **DOM Event Bridge** | Real-time sync progress via SSE |
+| **Menu Injection** | Provider-specific sync dashboards in sidebar |
+
+## Key Rules
+
+- Always scope queries by `organizationId` + `tenantId`
+- Use the queue system — never run syncs inline
+- Persist cursor after each batch — enables resume on failure
+- Log item-level errors — don't stop the sync for individual failures
+- Check for overlap before starting a new run

package/src/modules/integrations/agentic/standalone-guide.md

@@ -0,0 +1,113 @@
+# Integrations Module — Standalone App Guide
+
+The integrations module provides the foundation for all external connectors (payment gateways, shipping carriers, data sync providers, etc.). It offers three shared mechanisms: **Integration Registry**, **Credentials API**, and **Operation Logs**.
+
+## Creating an Integration Provider
+
+Create a new module in your app for each provider:
+
+1. Create `src/modules/<provider_id>/` with standard module files
+2. Add `integration.ts` at the module root exporting an `IntegrationDefinition`:
+
+```typescript
+import type { IntegrationDefinition } from '@open-mercato/shared/modules/integrations/types'
+
+export const integration: IntegrationDefinition = {
+  id: 'my_provider',
+  name: 'My Provider',
+  description: 'Integration with My Provider',
+  category: 'payment',
+  credentials: {
+    fields: [
+      { key: 'apiKey', label: 'API Key', type: 'password', required: true },
+      { key: 'environment', label: 'Environment', type: 'select', options: ['sandbox', 'production'] },
+    ],
+  },
+  healthCheck: { service: 'myProviderHealthCheck' },  // optional
+  apiVersions: ['v1', 'v2'],                          // optional
+}
+```
+
+3. Register the health check service in `di.ts` (if declared)
+4. Run `yarn generate` to auto-discover the integration
+
+## Key Services (DI)
+
+| Service | Purpose |
+|---------|---------|
+| `integrationCredentialsService` | Encrypted credential CRUD with bundle fallthrough |
+| `integrationStateService` | Enable/disable, API version, reauth, health state |
+| `integrationLogService` | Structured logging with scoped loggers |
+| `integrationHealthService` | Resolves and runs provider health checks |
+
+## Credential Resolution
+
+1. Direct credentials for the integration ID
+2. If `bundleId` is set, fallback to bundle's credentials
+3. Returns `null` if neither exists
+
+## Bundle Integrations
+
+For platform connectors with multiple integrations (e.g., an ERP with products + orders sync):
+
+```typescript
+export const bundle: IntegrationBundle = {
+  id: 'my_erp',
+  name: 'My ERP',
+  integrations: ['my_erp_products', 'my_erp_orders'],
+}
+```
+
+- Set `bundleId` on each child integration
+- Bundle credentials are shared via fallthrough
+
+## Events
+
+| Event | When |
+|-------|------|
+| `integrations.credentials.updated` | Credentials saved |
+| `integrations.state.updated` | Integration enabled/disabled |
+| `integrations.version.changed` | API version changed |
+| `integrations.log.created` | Log entry written |
+
+## Extending the Integration Detail Page
+
+Provider modules can add tabs, cards, or sections to the integration detail page:
+
+```typescript
+// integration.ts
+import { buildIntegrationDetailWidgetSpotId } from '@open-mercato/shared/modules/integrations/types'
+
+export const integration = {
+  id: 'my_provider',
+  detailPage: {
+    widgetSpotId: buildIntegrationDetailWidgetSpotId('my_provider'),
+  },
+} satisfies IntegrationDefinition
+```
+
+Register widgets for that spot in `widgets/injection-table.ts`. Use `placement.kind: 'tab'` for additional tabs, `'group'` for card panels, `'stack'` for inline sections.
+
+## UMES Extension Points
+
+Integration providers can leverage the full extension system:
+
+| Extension | Use Case |
+|-----------|----------|
+| **Widget Injection** | Inject status badges, config panels into other modules |
+| **Event Subscribers** | React to integration events for side-effects |
+| **Entity Extensions** | Link provider data to core entities (e.g., external IDs) |
+| **Response Enrichers** | Attach provider data to API responses |
+| **API Interceptors** | Intercept routes with before/after hooks |
+| **Notifications** | In-app alerts on integration events |
+| **DOM Event Bridge** | Real-time updates via SSE (`clientBroadcast: true`) |
+
+## Provider-Owned Env Preconfiguration
+
+If your provider needs credentials or settings after a fresh install:
+
+- Read env vars in a provider-local helper (e.g., `lib/preset.ts`)
+- Apply from your module's `setup.ts` for automatic tenant bootstrap
+- Expose a CLI command for rerunning the bootstrap
+- Use provider-prefixed env names (e.g., `OM_INTEGRATION_MYPROVIDER_*`)
+- Persist through normal integration services — never special-case in core

package/src/modules/sales/agentic/standalone-guide.md

@@ -0,0 +1,84 @@
+# Sales Module — Standalone App Guide
+
+Use the sales module for orders, quotes, invoices, shipments, and payments. This module has the most complex business logic in the system.
+
+## Document Flow
+
+```
+Quote → Order → Invoice
+         ↓
+    Shipments + Payments
+```
+
+- Quotes convert to orders — do not create orders without a source quote (unless configured)
+- Orders track shipments and payments independently
+- Each entity has its own status workflow — do not skip states
+- Returns create line-level adjustments and update `returned_quantity`
+
+## Pricing Calculations
+
+Always use the sales calculation service — never inline price math:
+
+```typescript
+const calcService = container.resolve('salesCalculationService')
+```
+
+- Dispatches `sales.line.calculate.*` and `sales.document.calculate.*` events
+- For catalog pricing: use `selectBestPrice` from the catalog module
+- Register custom line/totals calculators or override via DI
+
+## Channel Scoping
+
+All sales documents are scoped to channels. Channel selection affects:
+- Available pricing tiers
+- Document numbering sequences
+- Visibility in admin UI
+
+## Data Model
+
+### Core Entities
+| Entity | Purpose | Key Constraint |
+|--------|---------|---------------|
+| **Sales Orders** | Confirmed customer orders | MUST have a channel and at least one line |
+| **Sales Quotes** | Proposed orders | MUST track conversion status |
+| **Order/Quote Lines** | Individual items | MUST reference valid products |
+| **Adjustments** | Discounts/surcharges | MUST use registered `AdjustmentKind` |
+
+### Fulfillment
+| Entity | Purpose |
+|--------|---------|
+| **Shipments** | Delivery tracking with status workflow |
+| **Payments** | Payment recording with status workflow |
+| **Returns** | Order returns with line selection and automatic adjustments |
+
+### Configuration (do not modify directly)
+Channels, statuses, payment/shipping methods, price kinds, adjustment kinds, and document numbers — configure via admin UI or `setup.ts` hooks.
+
+## Subscribing to Sales Events
+
+```typescript
+// src/modules/<your_module>/subscribers/order-created.ts
+export const metadata = {
+  event: 'sales.order.created',
+  persistent: true,
+  id: 'your-module-order-created',
+}
+
+export default async function handler(payload, ctx) {
+  // React to new orders
+}
+```
+
+Key events: `sales.order.created` / `updated` / `deleted`, `sales.quote.created` / `updated`, `sales.payment.created`, `sales.shipment.created`
+
+## Extending Sales UI
+
+Common widget injection spots:
+- `crud-form:sales.sales_order:fields` — order detail form
+- `data-table:sales.orders:columns` — order list columns
+- `data-table:sales.orders:row-actions` — order row actions
+- `sales.document.detail.order:details` — order detail page sections
+
+## Frontend Pages
+
+- `frontend/quote/` — public-facing quote view for customer acceptance

package/src/modules/workflows/agentic/standalone-guide.md

@@ -0,0 +1,152 @@
+# Workflows Module — Standalone App Guide
+
+Use the workflows module for business process automation: defining step-based workflows, executing instances, handling user tasks, and triggering workflows from domain events.
+
+## Using Workflows in Your App
+
+The workflow engine is provided by `@open-mercato/core`. Your standalone app can:
+
+1. **Create workflow definitions** via the visual editor at `/backend/workflows`
+2. **Trigger workflows** from domain events emitted by your modules
+3. **Subscribe to workflow events** for side effects in your modules
+4. **Inject UI widgets** into workflow pages or inject workflow widgets into your pages
+5. **Define user tasks** that require human approval or data entry
+
+## Starting Workflows Programmatically
+
+Resolve the workflow executor via DI — never import lib functions directly:
+
+```typescript
+// In your module's DI-aware context (API route, subscriber, worker)
+const executor = container.resolve('workflowExecutor')
+
+await executor.startWorkflow({
+  workflowId: 'order-approval',  // matches a WorkflowDefinition.workflowId
+  context: {
+    orderId: order.id,
+    orderTotal: order.totalGross,
+    customerName: order.customerName,
+  },
+  organizationId,
+  tenantId,
+})
+```
+
+## Event Triggers
+
+Configure automatic workflow starts from your module's domain events:
+
+1. Create a workflow definition with a `triggers[]` entry in the visual editor or via API
+2. The workflow engine's wildcard subscriber evaluates all non-internal events
+3. Use `filterConditions` to narrow which events match (e.g., only orders above a threshold)
+4. Use `contextMapping` to extract event payload fields into workflow context variables
+5. Use `debounceMs` and `maxConcurrentInstances` to prevent trigger storms
+
+Excluded event prefixes (never trigger workflows): `query_index`, `search`, `workflows`, `cache`, `queue`.
+
+## Subscribing to Workflow Events
+
+React to workflow lifecycle events in your module:
+
+```typescript
+// src/modules/<your_module>/subscribers/workflow-completed.ts
+export const metadata = {
+  event: 'workflows.instance.completed',
+  persistent: true,
+  id: 'your-module-workflow-completed',
+}
+
+export default async function handler(payload, ctx) {
+  // payload.resourceId = instance ID
+  // payload.workflowId = definition ID
+  // payload.context = workflow context variables
+}
+```
+
+Key workflow events your module can subscribe to:
+
+| Event | When it fires |
+|-------|--------------|
+| `workflows.instance.created` | New workflow instance started |
+| `workflows.instance.completed` | Workflow finished successfully |
+| `workflows.instance.failed` | Workflow failed |
+| `workflows.instance.cancelled` | Workflow was cancelled |
+| `workflows.task.created` | User task assigned |
+| `workflows.task.completed` | User task completed |
+| `workflows.step.completed` | Individual step finished |
+
+## Step Types
+
+| Step type | Use case |
+|-----------|----------|
+| `START` | Entry point — every definition has exactly one |
+| `END` | Terminal step — marks workflow as COMPLETED |
+| `USER_TASK` | Human approval or data entry — pauses until task completion |
+| `AUTOMATED` | Executes transition activities immediately and advances |
+| `SUB_WORKFLOW` | Invokes a nested workflow definition |
+| `WAIT_FOR_SIGNAL` | Pauses for an external signal (e.g., payment confirmed) |
+| `WAIT_FOR_TIMER` | Pauses for a configured duration |
+| `PARALLEL_FORK` / `PARALLEL_JOIN` | Splits/merges parallel execution paths |
+
+## Activity Types
+
+Activities execute on transitions between steps:
+
+| Activity type | Use case |
+|---------------|----------|
+| `SEND_EMAIL` | Send templated email |
+| `CALL_API` | Call an internal API endpoint |
+| `CALL_WEBHOOK` | Call an external HTTP endpoint |
+| `UPDATE_ENTITY` | Mutate an entity via the command bus |
+| `EMIT_EVENT` | Emit a domain event |
+| `EXECUTE_FUNCTION` | Run a registered custom function |
+| `WAIT` | Delay execution for a configured duration |
+
+Use `{{context.*}}`, `{{workflow.*}}`, `{{env.*}}`, `{{now}}` for variable interpolation in activity config — never hardcode values.
+
+## Sending Signals
+
+Resume a workflow waiting for an external signal:
+
+```typescript
+const executor = container.resolve('workflowExecutor')
+
+await executor.sendSignal({
+  instanceId: workflowInstanceId,
+  signalName: 'payment_confirmed',
+  payload: { transactionId: '...' },
+  organizationId,
+  tenantId,
+})
+```
+
+## Widget Injection
+
+Inject workflow-related UI into your module's pages, or inject your module's widgets into workflow pages:
+
+```typescript
+// src/modules/<your_module>/widgets/injection-table.ts
+export const widgetInjections = {
+  // Inject into workflow task detail page
+  'workflows.task.detail:after': {
+    widgetId: 'your-module-task-context',
+    priority: 50,
+  },
+}
+```
+
+## Compensation (Saga Pattern)
+
+When a workflow step fails, compensation activities execute in reverse order to undo previous steps. This follows the saga pattern:
+
+- **Sync activities** execute inline and advance immediately
+- **Async activities** enqueue to the `workflow-activities` queue; workflow pauses until completion
+- On failure, compensation runs in reverse — keep activity handlers **idempotent** (check state before mutating)
+
+## Key Rules
+
+- MUST resolve services via DI (`container.resolve('workflowExecutor')`) — never import lib functions directly
+- MUST use `workflowExecutor.startWorkflow()` to create instances — never insert rows directly
+- MUST keep activity handlers idempotent — they may be retried on failure
+- MUST scope all queries by `organization_id` — workflow data is tenant-scoped
+- MUST NOT couple your module to workflow internals — use event triggers and signals for integration