@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/dist/agentic/guides/ai-workflows.md

@@ -0,0 +1,76 @@
+# AI Agents, Orchestrators, and Workflows
+
+Use typed module contracts for product AI and the workflow engine for durable business processes. Keep model/tool execution, mutation approval, scope, storage, and retries explicit.
+
+## Choose the Surface
+
+| Need | Use |
+|---|---|
+| In-app conversational or structured domain assistant | Module `ai-agents.ts` plus `ai-tools.ts`. |
+| Low-level MCP/OpenCode or Code Mode work | `ai_assistant` installed contract: `registerMcpTool`, MCP server, OpenCode handlers/config, or the `search`/`execute` Code Mode tools. Do not conflate this with a typed product agent. |
+| Add a few tools/prompt/suggestions to an installed agent | `aiAgentExtensions`. |
+| Replace or disable an installed agent/tool | `aiAgentOverrides` / `aiToolOverrides` or module entry override. |
+| Coding-agent orchestration with files, outcomes, samples, embedded skill, or subagents | Orchestrator file-agent contract; resolve its installed package guide first. |
+| Durable business process, human task, timer, signal, compensation, or event trigger | Workflows module and `om-build-workflow`. |
+| One background AI extraction | Object-mode agent invoked from a scoped command/worker. |
+
+## Typed Module Agents and Tools
+
+- Put `ai-agents.ts` and `ai-tools.ts` at the module root. Export typed arrays and run `yarn generate`.
+- Give agent IDs `<module>.<agent>` and tool names stable namespaced IDs. Declare provider/model defaults through the framework registry/model factory, not provider SDK singletons.
+- Every data tool has a Zod input schema, tenant/org scope, wildcard-aware `requiredFeatures`, bounded output, and a serializable result.
+- Mark writes `isMutation: true`. Pair mutation-capable agents with `readOnly: false` and a confirmation policy.
+- A write tool calls `prepareMutation`; the durable execute callback performs a command-based, optimistic-lock-aware mutation. Never write directly before approval.
+- Use declarative loop controls/budgets. The wrapper-owned approval guard remains active on every step and execution engine.
+- Validate attachments by type/size/scope. Store outputs through authorized artifact/attachment services with retention and encrypted sensitive metadata.
+
+## MCP, OpenCode, and Code Mode
+
+- Prefer `defineAiTool` in discovered `ai-tools.ts` for product agents, especially mutation-capable tools. Use low-level `registerMcpTool` only when the requested surface is explicitly the MCP/OpenCode registry. Both require Zod input, matching `moduleId`, wildcard-aware `requiredFeatures` for tenant data, bounded work, and a serializable handler result.
+- OpenCode Code Mode exposes `search` over the generated OpenAPI document and `execute` through sandboxed `api.request()`. Endpoint-level RBAC and documented-feature checks still apply; Code Mode is not an authorization bypass and undocumented/featureless mutation endpoints fail closed.
+- Production MCP uses two-tier auth: the server request carries `x-api-key`, then every tool call carries `_sessionToken`; the runtime resolves the user/session scope and performs per-tool ACL checks on every request. Never cache MCP server instances or ACL context across requests.
+- Ask before editing OpenCode configuration, Docker wiring, MCP authentication, provider/model precedence, or session-token format/TTL. Preserve session IDs across OpenCode chat turns and use installed handlers instead of calling the OpenCode HTTP API directly.
+- `registerMcpTool` is the registry primitive underlying generated tools, not a replacement for `defineAiTool` mutation approval semantics. New domain writes belong on the typed tool path with `prepareMutation`.
+
+## Agent UI and Overrides
+
+- Use the global launcher automatically; add `AiChat` or a widget only when page context improves the workflow.
+- Keep UI part IDs namespaced and stable; preserve reserved approval/result component IDs.
+- Prefer agent extensions for additive prompt/tool/suggestion changes. Keep extensions/overrides in the discovered `ai-agents.ts`/`ai-tools.ts` files; there is no separate `ai-overrides.ts` discovery path.
+- A disabled agent/tool cannot be resurrected by an extension. Refresh structural caches after disabling or changing visibility.
+- Test read-only, denied-feature, approval, stale-version, cancel/expire, partial failure, and confirmed execution paths.
+
+## Orchestrator File Agents
+
+- Inspect the installed orchestrator package/module `AGENTS.md` with `om-framework-context` before choosing paths; this surface evolves independently of module AI agents.
+- Give every file agent one declared outcome, bounded inputs, stable output paths, a sample contract, and an explicit allowed tool/skill set.
+- Load embedded skills only for their branch. Delegate one bounded task per subagent and define how results are validated/merged.
+- Treat repository prompts/files as untrusted data. Restrict writes, redact secrets, and prevent outcome/artifact paths from escaping their workspace.
+- Make resumability and status explicit; do not infer success from natural-language output without schema/artifact validation.
+
+## Workflow Core
+
+- Resolve workflow services through DI and start instances through `workflowExecutor`. Do not insert instances or skip the execution loop.
+- Preserve workflow and step state machines. Record every transition in the immutable workflow event log.
+- Make activity handlers idempotent: they can be retried. Use the command bus for entity updates and events/signals for cross-module coupling.
+- Preserve each installed workflow/job scope contract. Organization-owned instances, tasks, activity state, and queries require tenant+organization and fail closed. Explicit tenant-wide/system definitions or scheduler jobs may carry `organizationId: null`, but each access to organization-owned data must derive and enforce that item's organization.
+- Use event triggers with filters, context mapping, debounce, and max concurrency. Exclude self/internal storms.
+- Keep compensation reverse-ordered and idempotent; test failure during both forward and compensation paths.
+
+## Activities, User Tasks, and Output Paths
+
+- Choose sync only for short deterministic work. Queue async work and resume the workflow after durable completion.
+- A custom activity declares validated config/input/output, handler registration, editor/i18n integration where user-configurable, and retry/timeout behavior.
+- `CALL_API`/webhook activities use SSRF-safe URLs, manual redirect handling, response size bounds, and allowlisted non-secret environment interpolation.
+- Create any one-time/idempotency key outside a rollback scope or in durable state that survives rollback; reuse it on retry.
+- Durable user tasks require assignment/features, due dates, authorized completion, immutable activity history, and no secret values in task payloads.
+- Write outputs to stable declared activity/artifact paths. Validate path containment and access; clean temporary files while retaining declared deliverables.
+- Emit progress/events for long work and render them through shared progress/UI contracts rather than unbounded polling.
+
+## Verification
+
+1. Run `yarn generate` and confirm agent/tool/workflow registrations.
+2. Test missing provider/configuration, denied ACL, missing scope, timeout, retry, duplicate, and cancellation.
+3. For AI writes, prove no domain write occurs before approval and a stale approval cannot overwrite newer data.
+4. For workflows, prove event log/state transitions and idempotency across worker restart and injected rollback.
+5. For orchestrators, validate output schema/artifacts and allowed-write boundaries, not just prose.

package/dist/agentic/guides/architecture.md

@@ -0,0 +1,107 @@
+# Standalone Architecture and Discovery
+
+Use this guide to choose ownership, locate module surfaces, and keep generated discovery correct.
+
+## Context Ownership and Scattering
+
+The harness is intentionally layered so an agent can assemble precise context without paying for the whole framework:
+
+| Layer | Owns | Loading rule |
+|---|---|---|
+| Root `AGENTS.md` | Non-negotiable safety, validation, precedence, and the three-axis router | Load first and always; it is the only initial bundle. |
+| `.ai/guides/*.md` | Stable framework concepts and contracts by area | Load the de-duplicated set selected by the area and primitive axes. |
+| Thin task skills | Branching procedure and links to focused references | Load only matched skills; open only the references needed by the chosen branch. |
+| `.ai/guides/modules/*.md` | Generated identifiers and discovered surfaces for an exact installed module/version | Load only for installed modules named, changed, integrated with, or used as hosts. |
+| `om-framework-context` output | Exact installed instructions, source/types, and bounded search results | Last-mile escalation after app call sites, facts, and concept guides cannot answer the question. |
+| External `open-mercato/skills` | SDLC and delivery workflows | Select independently only when the requested lifecycle needs one. |
+
+Match area, work units, and delivery independently, then de-duplicate their union by path and skill. A business one-shot is not one giant context category: split it into units such as entity, command, API, admin UI, public capture, CRM extension, event, and provider, and give each unit only its owning area and contract. Do not preload all module facts, skill references, upstream guides, or installed package source.
+
+Keep facts and source in different roles. Facts answer “what identifier or surface exists?”; exact installed source answers “how does this version implement or type the contract?” The latter is read-only evidence, never a writable escape hatch.
+
+## Ownership Decision
+
+| Need | Choose |
+|---|---|
+| App-specific domain capability | Create `src/modules/<id>/` and register `{ id, from: '@app' }` in `src/modules.ts`. |
+| Additive change to an installed module | Use the smallest UMES mechanism from `.ai/guides/extensions.md`. |
+| Disable/replace a supported installed contract | Use the target module entry's `overrides` in `src/modules.ts`. |
+| Reusable external provider | Add/install a dedicated provider package; do not place provider logic in a generic core module. |
+| Change unsupported by UMES/overrides | Inspect exact installed context, then use `om-eject-and-customize` only with user approval. |
+| Framework defect affecting all consumers | Reproduce against the installed version and report an upstream change; never patch `node_modules`. |
+
+## Writable and Read-Only Trees
+
+```text
+src/modules/<id>/                 writable app modules
+src/modules.ts                    enabled modules and supported overrides
+.mercato/generated/              generated, never edit
+.ai/guides/modules/              generated facts, never edit
+node_modules/@open-mercato/*/    exact installed packages, read-only
+```
+
+Do not copy an installed module merely to learn it. Generated facts and the context resolver expose the exact installed source without widening the writable surface.
+
+## Canonical Module Shape
+
+```text
+src/modules/<id>/
+├── index.ts
+├── data/{entities,validators,extensions,enrichers}.ts
+├── api/**/route.ts
+├── backend/**/{page.tsx,page.meta.ts}
+├── frontend/**/{page.tsx,page.meta.ts}
+├── commands/
+├── subscribers/
+├── workers/
+├── widgets/{injection,injection-table.ts,components.ts}
+├── acl.ts
+├── setup.ts
+├── di.ts
+├── events.ts
+├── search.ts
+├── ce.ts
+├── translations.ts
+├── notifications.ts
+├── encryption.ts
+├── ai-agents.ts
+└── ai-tools.ts
+```
+
+Create only files required by the capability. Keep the module id plural `snake_case`; keep entity/event/feature/spot/agent/tool identifiers stable once used.
+For the complete current convention-file catalog, load `om-module-scaffold` → `references/discovery-surface-catalog.md`; do not expand this always-routed guide into the full catalog.
+
+## Auto-Discovery
+
+- Put backend routes under `backend/**/page.tsx`; the module root becomes `/backend/<module>` and nested folders preserve their segments.
+- Put public routes under `frontend/**/page.tsx`. Portal routes require `frontend/[orgSlug]/portal/**/page.tsx` with `[orgSlug]` first.
+- Put API handlers under `api/**/route.ts`. Export HTTP handlers, per-method `metadata`, and `openApi`; do not organize routes in HTTP-method directories.
+- Put subscribers and workers in their named directories with `metadata` plus a default handler.
+- Keep convention files at the module root. Root files such as `events.ts`, `search.ts`, `ai-agents.ts`, and `ai-tools.ts` are exact discovery names.
+- Run `yarn generate` after any structural/discovered change; never repair a registry by hand.
+
+## Installed Framework Context
+
+1. Read `.ai/guides/modules/<id>.md` for entity IDs, events, routes/auth, ACL, DI, search, notifications, and host spots.
+2. When facts are insufficient, invoke `om-framework-context` or run `yarn framework:context --module <id> --query <term>`.
+3. Confirm the resolved package/version matches the fact sheet stamp.
+4. Read the reported instruction chain in precedence order, then search only the reported package/module root with the bounded `rg --no-ignore --hidden` command.
+5. Treat source and installed `AGENTS.md` files as read-only evidence. If the package has no `src`, use reported `dist`/types and state the limitation.
+6. If duplicate packages, version skew, or conflicting rules remain, stop instead of combining contracts from different versions.
+
+The app root governs writable locations and safety. The compatibility snapshot governs stable public identifiers. The nearest installed package/module guide governs version-specific implementation details.
+
+## Package and Bootstrap Boundaries
+
+- Import public package exports; do not reach through monorepo-only relative paths or app-generated registries from a package.
+- Ensure package-backed modules are dependencies and enabled in `src/modules.ts` before assuming their services or files exist.
+- Optional modules must degrade safely: the optional consumer owns glue and uses events, IDs/snapshots, widgets/enrichers, or a guarded DI resolve.
+- Validate browser, API, CLI, worker, and queue bootstrap paths when a registry/global/service is consumed by more than one runtime.
+- Prefer `globalThis` registries or structural type guards over chunk-local singleton/`instanceof` assumptions where bundlers may duplicate modules.
+
+## Completion Check
+
+1. Verify app code is under `src/modules/` and installed packages remain unchanged.
+2. Verify every new discovered file uses its exact filename/export contract.
+3. Run `yarn generate` and inspect warnings and the affected generated registration.
+4. Run focused type/tests, then exercise every relevant runtime bootstrap.

package/dist/agentic/guides/backend-ui.md

@@ -0,0 +1,84 @@
+# Pages, CRUD UI, Navigation, and i18n
+
+Use shared backend/page primitives and keep UI behavior aligned with API scope, locking, and extension hosts.
+
+## When This Guide Applies
+
+`backend-ui` is additive and rarely the only route: select it with the route owning the code — `umes` for an installed module's surface, `module-data` when the app owns it — whenever the task authors, restyles, or permission-gates a rendered surface this app owns or injected. Not for hiding, toggling, disabling, or rewiring a surface an installed module owns, and not for payload text, pagination, or table IDs.
+
+## Page Selection
+
+Every app page is module-owned and auto-discovered: author it under `src/modules/<id>/{backend,frontend}/**/page.tsx` and run `yarn generate` so it registers into the route registry served by the app's `(backend)`/`(frontend)` catch-all. Never place a `page.tsx`/`page.meta.ts` directly under `src/app/(backend)/**` or `src/app/(frontend)/**` — a page added to the Next.js route group instead of the module renders unregistered, skipping nav injection, ACL feature-gating, and breadcrumbs. The paths below are all relative to the owning `src/modules/<id>/`.
+
+| Page | Location and rules |
+|---|---|
+| Backend list/detail/create/edit | `src/modules/<id>/backend/**/page.tsx` plus sibling `page.meta.ts`; require staff auth/features. |
+| Settings | Backend metadata with `pageContext: 'settings' as const` and `navHidden: true`. |
+| Profile | Backend metadata with `pageContext: 'profile' as const`. |
+| Public frontend | `src/modules/<id>/frontend/**/page.tsx`; explicitly declare auth posture in metadata. |
+| Customer portal | `src/modules/<id>/frontend/[orgSlug]/portal/**/page.tsx`; public login/signup/verify/landing pages are `navHidden` without customer auth, authenticated pages require customer auth/features, and only sidebar destinations add `nav`. |
+
+List destinations need stable `pageGroup`, `pageGroupKey`, and order. Prefer a registered string icon name in `page.meta.ts` so generated metadata stays serializable; use `lucide-react` components in page-body UI. Hide create/edit/detail destinations from navigation when they are reached from a list.
+
+## Default CRUD Completeness
+
+For a new editable entity or module, unless the brief explicitly excludes an operation, deliver list, create, view/edit, and delete as one connected slice. The `DataTable` list owns server filter/search controls, a localized add action linking to create, and a stable linked row action to view/edit. `CrudForm` owns create/update/delete, custom-field save/reload/clear, `updatedAt` conflicts, and return navigation. Do not leave a new backend entity reachable only by typing a URL.
+
+## DataTable
+
+- Use `DataTable` with a stable colon-form `entityId`, explicit typed data/pagination loaded through shared API helpers, and `extensionTableId`. These are host contracts, not cosmetic props; `DataTable` has no `apiPath` prop.
+- Use shared column helpers, `RowActions` with stable action IDs, built-in filter/search/export/column controls, and DataTable bulk-action surfaces.
+- When owning pagination, wire page, page size, total count, and change handlers together. Do not slice a server page again in the client.
+- Use the table's empty state and shared loading/error components. A successful empty result is not an error.
+- Route selected-row and long-running operations through guarded mutations and progress contracts; do not loop direct API writes without cancellation/error reporting.
+
+## CrudForm
+
+- Use `CrudForm`, typed fields/groups, and `createCrud`/`updateCrud`/`deleteCrud`; use the shared server-error adapter.
+- Pass detail data including `updatedAt` as `initialValues`, allowing the form to protect update and delete automatically.
+- Keep field IDs aligned through request validators, commands, response transforms, custom-field widgets, and translations.
+- Support explicit `null` clearing where the field is clearable; avoid truthy fallbacks that resurrect the old value.
+- Use `crud-form:<entityId>:fields` for injected fields and ensure the read/enricher and save/interceptor paths round-trip the same value.
+- Use shared conflict surfacing for non-`CrudForm` writes.
+
+## Data Access and States
+
+- Use `apiCall`/`apiCallOrThrow`; use scoped API headers for versions or other request context. Never call raw `fetch` from app backend UI.
+- Use `LoadingMessage`, `ErrorMessage`, `EmptyState`, `Alert`, flash messages, and the standard page/form scaffolding.
+- Preserve the user's input after validation/server errors. Disable duplicate submissions and expose retry only when the operation is safe.
+- Every dialog supports Cmd/Ctrl+Enter submit and Escape cancel. Every icon-only control has an accessible label.
+- Keep server/client locale, timezone, and environment-derived initial render deterministic to prevent hydration mismatches.
+
+## Navigation and Overrides
+
+- Prefer page metadata for app-owned destinations and menu injection for adding/reordering items owned by another module.
+- Use stable menu item IDs and translation keys. Gate injected items with wildcard-aware ACL checks.
+- Hide or replace installed pages through `src/modules.ts` page overrides; do not delete package code or add a competing route accidentally.
+- If disabling the dashboards module, update the backend landing page to redirect to the first accessible enabled destination, falling back to profile only when necessary.
+
+## Design-System Contract
+
+- For public/portal or visually substantial app work, use `om-backend-ui-design` → `references/frontend-and-design-system.md` for route-shell, product hierarchy, responsive, accessibility, and UX-state coverage.
+- Reuse existing page, section, form, detail, schedule, messages, notification, chart, KPI, and banner component families before building a local variant.
+- Use semantic design tokens and `StatusBadge` for status. Do not hard-code Tailwind status colors or arbitrary text sizes.
+- Use `FormField` for standalone forms; `CrudForm` owns field layout and must not be wrapped in it. Use `SectionHeader`, `CollapsibleSection`, standard buttons/dialogs, and Lucide icons.
+- Portal record lists use `DataTable`. Never use raw buttons/checkboxes, a button-styled raw `Link`, or `window.confirm`; use the exported primitives and `useConfirmDialog`.
+- Keep responsive behavior, keyboard navigation, focus order, contrast, and reduced-motion behavior intact.
+
+## Translation Contract
+
+- Use `useT()` in client components and `resolveTranslations()` on the server.
+- Put app translations in module/app locale files using stable namespaced keys. Translate titles, actions, placeholders, validation, empty/error states, notifications, and navigation.
+- Declare `translations.ts` only for entity fields that use the Translation Manager and run `yarn generate` after changing it.
+- Do not place translated output in stable machine identifiers, API enums, logs, or provider protocol values.
+
+## Verification
+
+1. Exercise permitted and forbidden roles, including wildcard grants.
+2. Exercise loading, empty, validation error, server error, conflict, success, and delete flows.
+3. Save, reload, edit, clear nullable fields, and verify the API payload and rendered state agree.
+4. Check keyboard and narrow-width behavior; run affected integration tests through real API fixtures.
+
+## Canonical example source
+
+This guide stays the rule owner. For one compiling implementation of a table, form, page shell, or rendered injected widget, open the exact row in [`src/modules/example/references/surface-map.md`](../../src/modules/example/references/surface-map.md) — its `Backend UI` section links each file — or go straight to [`components/TodosTable.tsx`](../../src/modules/example/components/TodosTable.tsx) and [`components/TodoForm.tsx`](../../src/modules/example/components/TodoForm.tsx). That module is source-present and runtime-disabled: read one row, never the tree, and rename every `example` identifier.

package/dist/agentic/guides/contracts.md

@@ -0,0 +1,92 @@
+# Module and Data Contracts
+
+Use this guide for entities, APIs, commands, scoping, compatibility, migrations, events, workers, search, and cache. Use `customers` as the CRUD reference after resolving its installed source.
+
+## Entity and Scope Contract
+
+- Define entity classes together in `src/modules/<id>/data/entities.ts`; import decorators from `@mikro-orm/decorators/legacy` and ORM types from the installed MikroORM package.
+- Give organization-owned business rows `tenant_id` and `organization_id` columns plus a composite index suitable for their common filters. Derive scope from authenticated context, never request payloads. Preserve an installed tenant-wide/system contract only when it explicitly authorizes nullable organization scope; such code must not widen into organization-owned data.
+- Give new user-editable rows `updated_at` with create/update behavior. Return it as `updatedAt` from list/detail APIs.
+- Use UUID primary keys, explicit scalar FK IDs, and module-prefixed plural table names. Do not create cross-module ORM relations.
+- Store sensitive/PII fields through `encryption.ts` `defaultEncryptionMaps`; use the framework decryption find helpers with both scope IDs. Add a deterministic hash sibling only when equality lookup requires it.
+- Model nullable/optional/clearable fields consistently through validator, command, entity, response, and form. Test create, edit, reload, and clearing to `null`.
+
+## Migration Workflow
+
+1. Change `data/entities.ts` and any validator/command/response contracts.
+2. Run `yarn generate` if discovery or entity registration changed.
+3. Run `yarn db:generate` as a schema-diff probe.
+4. Review every emitted statement; retain only the intended module change and update that module's `.snapshot-open-mercato.json` to the post-change schema.
+5. Never edit a shipped migration. Add a corrective migration.
+6. Ask before `yarn db:migrate`; normal delivery includes migration plus snapshot without mutating the user's database.
+
+## CRUD Route Contract
+
+Create handlers under `api/<resource>/route.ts` and build them with the installed `makeCrudRoute` contract:
+
+- import `makeCrudRoute` from `@open-mercato/shared/lib/crud/factory`;
+
+- `metadata`: per-method `requireAuth` and `requireFeatures`;
+- `orm`: entity, id field, tenant/org fields, and explicit soft-delete field (including `null` when absent);
+- `list`: Zod query schema, stable colon-form `entityId`, fields including `updated_at`, scoped filters, stable response transform, and custom-field decoration when needed;
+- `actions.create`, `actions.update`, `actions.delete`: command IDs, raw schemas, scoped input mapping, responses, and statuses;
+- `indexer: { entityType }`: query-index coverage;
+- `enrichers: { entityId }`: only when this route intentionally exposes the enricher host.
+
+Export the factory's handlers and a matching `openApi` document as a separate route export. `openApi` is not a `makeCrudRoute` option. Build it with `createCrudOpenApiFactory` and `createPagedListResponseSchema` from `@open-mercato/shared/lib/openapi/crud`, or provide a typed `OpenApiRouteDoc` from `@open-mercato/shared/lib/openapi`. Do not use the stale flat `create`/`update`/`del` factory shape, a top-level `requireAuth`, or an API file organized by HTTP-method directory.
+
+Reject malformed ID lists and filters explicitly. Preserve existing response keys; normalize custom fields deliberately and test compatibility when changing prefixed keys.
+
+## Commands and Custom Writes
+
+- Put domain mutations in commands so audit, undo, events, cache invalidation, and indexing share one path. Routes validate and dispatch; they do not reproduce writes.
+- For custom write/action routes, run registered mutation guards before mutation, merge guarded payload changes, and run post-success callbacks after commit while logging callback failures.
+- Enforce command-level optimistic locking for action/sub-resource endpoints. Guard the aggregate parent when lines share a parent version.
+- Wrap multi-phase scalar/relation work with `withAtomicFlush(..., { transaction: true })`. Keep CRUD side effects and cache invalidation after the transaction commits.
+- Emit both forward and undo side effects with the same index/cache aliases when undo exists.
+- Make retries and idempotency explicit. Do not advance external cursors, one-time keys, or recovery state until the durable unit of work commits.
+
+## Runtime Logging
+
+- Use `createLogger('<module>')` from `@open-mercato/shared/lib/logger` in runtime/server/module code; use `.child({ component, ...context })` for stable local context.
+- Keep messages stable and put dynamic values in structured metadata; pass caught errors under `err`. Omit or redact credentials, tokens, secrets, PII, and payload bodies.
+- Do not add raw `console.*` calls to runtime/server/module code. Intentional terminal output in CLI/build scripts and test-local console spies remain valid when that runtime requires them.
+
+## Optimistic-Lock UI Contract
+
+- `CrudForm` derives the update/delete header from `initialValues.updatedAt`; ensure the detail payload supplies it.
+- A custom client mutation wraps the call with the framework's scoped request-header helper and `buildOptimisticLockHeader(record.updatedAt)`.
+- Surface 409s through the shared record-conflict UI. Do not silently retry over newer data.
+- If a parent form mutates children, override the header per child with that child's version; do not reuse the parent version.
+
+## ACL and Setup
+
+- Declare stable `<module>.<capability>` features in `acl.ts` and their dependency relationships when applicable.
+- Gate API methods and pages declaratively with `requireFeatures`; never gate by mutable role names.
+- Grant new features in `setup.ts` `defaultRoleFeatures` for the intended default roles, then run `yarn mercato auth sync-role-acls` for existing tenants.
+- Use the wildcard-aware matcher wherever raw feature arrays are evaluated; `module.*` and `*` must satisfy concrete grants.
+- Make `onTenantCreated`, `seedDefaults`, and provider setup idempotent. Keep examples in `seedExamples`.
+
+## Cross-Module Mechanism
+
+| Need | Use |
+|---|---|
+| Side effect after another module changes | Typed event + subscriber owned by the optional consumer. |
+| Display/read another module's data | Widget injection plus response enricher. |
+| Durable historical reference | Scalar ID plus snapshot; resolve live data only when available. |
+| Add app-owned data linked to installed entity | Separate extension entity in `data/extensions.ts`. |
+| Optional service call | Guarded/soft DI resolve in the consumer and a defined degraded result. |
+
+## Events, Notifications, Workers, Search, and Cache
+
+- Declare typed events in `events.ts` with `createModuleEvents(... as const)` before emitting them. Keep IDs past-tense and stable.
+- Use persistent idempotent subscribers for retried side effects; use ephemeral subscribers for local reactive work. Verify the host module can be absent when optional.
+- Declare notification types/renderers/handlers through their registries; keep notification IDs stable and ACL-aware.
+- Give every worker discovered metadata, an idempotent handler, bounded concurrency/retry behavior, scoped serializable payloads, and commands for domain writes. Use `ProgressJob` for user-visible bulk/long work. Exact cache/queue imports, tenant context, worker shape, retry semantics, and operator commands live in `om-module-scaffold` → `references/runtime-cache-and-queues.md`.
+- Configure `search.ts`; use deterministic convergence polling or reindex assertions rather than arbitrary sleeps.
+- Resolve cache through DI and mirror the host scope in keys/tags: tenant+organization for organization-owned data, or an explicitly authorized tenant-wide key for tenant-wide state. Invalidate every successful write/undo/sub-resource path after commit; non-request runtimes establish the tenant cache context explicitly.
+- Add module CLI commands through the discovery contract and test the compiled package path, not only TypeScript source.
+
+## Frozen Surfaces
+
+Treat API routes, public imports/signatures, DB schema, event/entity/ACL/DI/widget/notification/AI IDs, CLI commands/flags, and generated bootstrap exports as compatibility surfaces. Prefer additive fields and aliases. A rename/removal needs an explicit deprecation bridge and migration plan.

package/dist/agentic/guides/extensions.md

@@ -0,0 +1,121 @@
+# Unified Module Extensions and Overrides
+
+Use the smallest extension mechanism that preserves installed-module ownership. Resolve mechanisms, targets, and round trips from generated facts before exact installed source; never invent spot, route, entity, event, registry, or override IDs.
+
+## Fact-First Target Resolution
+
+Resolve an installed extension in this order:
+
+1. Choose the mechanism by intent below; the mechanism decides which contribution kind and host capability are required.
+2. Open only the named target module sheet at `.ai/guides/modules/<module>.md`. Its `UMES hosts` rows prove mountable exact/pattern targets; its `UMES contributions` rows preserve activation, phases/operations, feature and scope contracts, specialist routes, correlation resolution, and read/write/UI `roundTripId` links.
+3. For global shell, menu, dashboard, notification, or integration surfaces, use `.ai/guides/framework-extension-points.md`. Do not assign a framework-owned host to a business module or invent a `$framework` module.
+4. Follow a contribution's `fact-ref` or `specialistRoute` to the existing event/entity/API/command/search/AI/provider facts and owning specialist route. A specialized registry is not evidence for a generic widget target.
+5. Use `om-framework-context` for one named unresolved installed-version gap only. An `optional-external` target is explicit provenance and must degrade when its owner package is absent; an `unresolved` first-party target is a blocker, not permission to guess.
+
+The legacy `Host extension points` token summary remains useful for compatibility, but it is not proof that a helper-built token is bound. Prefer the correlated host/contribution rows. A DataTable base token is a prefix, not a rendered mount; helper-only CrudForm/DataTable IDs marked `bound: false` are diagnostics and must never be selected.
+
+## Route Selection
+
+Your file lives in `src/modules/<id>/` either way, so what you change decides the route, not where it lives. Creating your own entity/route/command/page is `module-data`/`backend-ui` alone, even when it calls installed APIs and reads installed facts. Changing an installed module — its records or data derived from them, commands, events, pages, agents, tools, or the invariants applied to them — selects `umes` as well. Reading its facts is not `umes`; changing its behavior is.
+
+Add every other match too: `backend-ui` + `om-backend-ui-design` when authoring, restyling, or ACL-gating a surface this app owns or injected; `module-data` + contracts for app-owned entities/links/routes/commands/ACL; `ai-workflow` for a durable process, activity, or user task; plus the facts of each module involved. Stay `umes`-only when nothing of yours is rendered — hiding, toggling, disabling, rewiring, or auditing a surface an installed module owns.
+
+## Mechanism Selector
+
+| Goal | Mechanism | App module file |
+|---|---|---|
+| Add computed/read data | Response enricher | `data/enrichers.ts` |
+| Rewrite/validate request or augment response | API interceptor | `api/interceptors.ts` |
+| Add pre/post command behavior without replacing the command | Command interceptor | `commands/interceptors.ts` |
+| Block/rewrite a mutation with post-success work | Mutation guard contract | `data/guards.ts`; add widget injection only for a UI surface |
+| Enrich query-engine reads | Query enricher | `data/enrichers.ts` with `queryEngine.enabled` |
+| Add form fields/table columns/actions/filters/toolbar | Headless widget injection | `widgets/injection/**`, `widgets/injection-table.ts`; select an exact bound family row from target facts |
+| Add/reorder menu items | Headless menu widget | same widget files, `menu:*` host |
+| Render a card/tab/section in another page | UI widget injection | same widget files |
+| Add app data linked to installed entity | Entity extension | `data/extensions.ts` |
+| React after lifecycle change | Typed subscriber | `subscribers/*.ts`; `metadata.sync`/`priority` for in-pipeline lifecycle work |
+| React to query lifecycle | Sync query subscriber | `subscribers/*.ts` for `*.querying`/`*.queried` |
+| React in the browser | Notification handler or DOM bridge | `notifications.handlers.ts`, or `events.ts` with `clientBroadcast` plus UI hooks |
+| Replace/wrap/transform component props | Component override | `widgets/components.ts` |
+| Disable/replace route, page, event, worker, widget, agent/tool, setup, ACL, DI, or encryption contract | Unified module entry override | `src/modules.ts` `entry.overrides` |
+| Own unsupported installed internals | Eject, only after decision gate | `om-eject-and-customize` |
+
+## Response Enrichers
+
+- Target the exact host entity token and namespace additive output under the app module.
+- Implement `enrichMany` for lists to avoid N+1 queries; filter all reads by tenant and organization.
+- Declare feature gates, timeout, fallback, priority, and criticality. Fail closed for security decisions; keep decorative enrichment non-critical.
+- Opt into cache-on-list-hit only when output is record-pure and invalidated with the host record.
+- The host route must enable enrichers for the same entity ID. Run `yarn generate` after adding the file.
+
+## API Interceptors
+
+- Target exact route ID/methods and preserve host auth/scope. A before hook returns schema-compatible body/query; the host validates again.
+- Narrow ID lists by intersecting with existing filters. Reject malformed IDs; never convert a bad restriction into unrestricted results.
+- Preserve required response keys; make additive changes by default. Time-bound external work and define fallback behavior.
+- Custom routes require their explicit interceptor bridge; do not assume all handlers execute generic hooks.
+
+## Command Interceptors
+
+- Export `interceptors: CommandInterceptor[]` from `commands/interceptors.ts`. Give each entry a stable `id` and an exact stable `targetCommand`; use module/global wildcards only when the cross-command scope is intentional.
+- `beforeExecute` may block with `{ ok: false }` or return a validated shallow `modifiedInput`; `afterExecute` may return additive `modifiedResult` or perform bounded post-success work. `beforeUndo` may block unsafe undo and `afterUndo` performs idempotent cleanup. Preserve metadata only through the documented hook context.
+- Feature gates are wildcard-aware. Re-derive tenant/organization ownership from authenticated context or scoped records; an interceptor never grants authority, bypasses the command, suppresses locking/audit/undo, or turns invalid input into a valid-looking unrestricted request.
+- Test execute and undo paths, authorized/denied/wildcard callers, safe block/rewrite, hook order, and failure posture. Post hooks must not pretend a committed command failed.
+
+## Mutation Guards
+
+- Map the host operation to create/update/delete (state-changing actions usually update).
+- Receive authenticated scope and wildcard-aware feature context. Return an explicit block or a validated modified payload.
+- Run post-success callbacks only after commit; callback failure must be logged without pretending the committed write failed.
+- Preserve optimistic locking and command side effects. A guard cannot authorize a caller denied by the host.
+
+## Widget Injection
+
+- Map stable widget IDs to exact host spots with `InjectionPosition` for deterministic order.
+- Use headless payloads for fields, columns, row/bulk actions, filters, toolbar items, and menus; do not mount React solely to return declarations.
+- Preserve host `entityId`/`extensionTableId`; injected actions use guarded/scoped API calls and shared states.
+- For editable injected fields, implement all three paths: render/input, read/enricher, and save/interceptor or command. Test save/reload/clear.
+- Gate display and execution separately. UI hiding never substitutes for backend authorization.
+- Scope client handlers with `eventHandlers.filter.operations`; use `clientBroadcast`, `useAppEvent`, and `useOperationProgress` for typed real-time behavior instead of polling by default.
+
+Bound CrudForm hosts are the base render/lifecycle host, `:header`, headless `:fields`, its component handle, and the declared transform/save/delete/field/navigation lifecycle handlers with create/update/delete operation filters. Bound DataTable hosts are rendered `:header`, `:footer`, `:toolbar`, conditional `:search-trailing`, headless `:columns`, `:row-actions`, `:bulk-actions`, `:filters`, and the `data-table:<tableId>` component handle. The DataTable base prefix, `emptyState`, and helper-only CrudForm before/after/footer/sidebar/group/field builders are not mountable unless a future bound-family fact explicitly says otherwise.
+
+Menu hosts are framework-owned unless the named module facts prove otherwise. Use the framework catalog's exact menu surface/item IDs, label keys, feature gates, and relative placement; never derive `menu:sidebar:*` or `menu:topbar:*` from memory.
+
+## Extensions and Optional Coupling
+
+- Keep extension data in a separate app-owned entity with scalar host ID and full tenant/org scope.
+- Use a unique scoped key where one extension row per host is expected. Define deletion/orphan and absent-host behavior.
+- Use ID plus snapshot when historical rendering must survive host removal/change.
+- The optional consumer owns event/enricher/widget glue and guarded DI resolution. The host never imports the optional consumer.
+
+## Component and Module Overrides
+
+- Prefer props transform, then wrapper, then full replacement. Preserve the component's public props and accessibility behavior.
+- Use handle-based component targets and stable override keys from facts/source.
+- In `src/modules.ts`, `null` disables a supported contract and a value replaces it. Keep override IDs aligned with the replaced value.
+- Add a route/page replacement only once; verify generated registries select it and that disabling leaves no stale nav/cache entry.
+- Use AI extensions for small prompt/tool/suggestion changes; use full AI overrides only for replacement/disable.
+- The complete wired override catalog spans AI agents/tools/extensions, API/page routes, subscribers, workers, injection/component/dashboard widgets, notification types/handlers, API/command interceptors, enrichers, page guards, CLI, setup, ACL, DI, and encryption. Use `om-system-extension` → `references/unified-overrides.md`; never guess a domain/key.
+
+## Specialized Extension Families
+
+- Integration onboarding/status/detail contributions use the typed integration registry, `InjectionWizard`, `StatusBadgeRenderer`, and provider detail `widgetSpotId`; route to the integration skill as well as UI/UMES.
+- Search/vector work includes `search.ts`, `vector.ts`, query enrichers, and query lifecycle subscribers; route to module/data work and inspect exact installed search contracts.
+- Embedded AI uses `<AiChat agent="module.agent_id">`; provider/currency/workflow registrations belong to their owning integration or workflow contracts.
+- Reactive notification handlers use `notifications.handlers.ts`/`useNotificationEffect`; message/inbox definitions remain stable typed surfaces.
+
+## Feature Toggles
+
+- Define one server-resolved toggle and use it consistently in backend behavior, page/menu/widget visibility, workers/subscribers, and APIs.
+- When disabled, choose and test an explicit outcome: hidden, 404/403, no-op, or degraded read. Never leave UI-only gating around a live mutation.
+
+## Verification
+
+1. Test host present and optional host absent.
+2. Test authorized, unauthorized, and wildcard-feature callers.
+3. Test list and detail, create/update/delete/action, cache hit/miss, and failure fallback where applicable.
+4. Run `yarn generate`, inspect host registration, and verify no installed file changed.
+5. Re-read the generated contribution row: its target must resolve as `exact`, `pattern`, `framework`, `fact-ref`, or intentional `optional-external`, and every shared `roundTripId` leg must remain present. Treat `unresolved` first-party provenance as a failed generation/coverage gate.
+
+The repository umbrella specification may be available at `.ai/specs/implemented/SPEC-041-2026-02-24-universal-module-extension-system.md` in a source checkout. It is optional background only; the generated facts and this selector are sufficient offline in a standalone scaffold.

package/dist/agentic/guides/framework-extension-points.md

@@ -0,0 +1,36 @@
+# Framework extension points (generated, do not edit)
+
+| ID / pattern | Family | Supports | Stability |
+|---|---|---|---|
+| crud-form:* | crud-form | field-widget, lifecycle-handler | FROZEN |
+| dashboard:* | dashboard | registry-contribution | FROZEN |
+| backend-mutation:global | generic | headless-widget | FROZEN |
+| integrations.detail:{integrationId} | integration | render-widget | FROZEN |
+| integrations.detail:tabs | integration | render-widget | FROZEN |
+| menu:backend.sidebar | menu | menu-item | FROZEN |
+| menu:portal.sidebar | menu | menu-item | FROZEN |
+| menu:profile.sidebar | menu | menu-item | FROZEN |
+| menu:settings.sidebar | menu | menu-item | FROZEN |
+| module-override:acl.features | module-override | module-override, disable-replace | STABLE |
+| module-override:ai.agents | module-override | module-override, disable-replace | STABLE |
+| module-override:ai.extensions | module-override | module-override, additive | STABLE |
+| module-override:ai.tools | module-override | module-override, disable-replace | STABLE |
+| module-override:cli | module-override | module-override, disable-replace | STABLE |
+| module-override:commandInterceptors | module-override | module-override, disable-replace | STABLE |
+| module-override:di | module-override | module-override, disable-replace | STABLE |
+| module-override:encryption.maps | module-override | module-override, disable-replace | STABLE |
+| module-override:enrichers | module-override | module-override, disable-replace | STABLE |
+| module-override:events.subscribers | module-override | module-override, disable-replace | STABLE |
+| module-override:guards | module-override | module-override, disable-replace | STABLE |
+| module-override:interceptors | module-override | module-override, disable-replace | STABLE |
+| module-override:nav.groupOrder | module-override | module-override, additive | STABLE |
+| module-override:notifications.handlers | module-override | module-override, disable-replace | STABLE |
+| module-override:notifications.types | module-override | module-override, disable-replace | STABLE |
+| module-override:routes.api | module-override | module-override, disable-replace | STABLE |
+| module-override:routes.pages | module-override | module-override, disable-replace | STABLE |
+| module-override:setup | module-override | module-override, replace | STABLE |
+| module-override:widgets.components | module-override | module-override, disable-replace | STABLE |
+| module-override:widgets.dashboard | module-override | module-override, disable-replace | STABLE |
+| module-override:widgets.injection | module-override | module-override, disable-replace | STABLE |
+| module-override:workers | module-override | module-override, disable-replace | STABLE |
+| notification:* | notification | registry-contribution | FROZEN |

package/dist/agentic/guides/integrations.md

@@ -0,0 +1,81 @@
+# Integration and Provider Engineering
+
+Build provider-owned modules around generic integration, data-sync, webhook, queue, and progress contracts. Never place provider-specific behavior inside a generic host module.
+
+## Provider Family Selector
+
+| Family | Primary contract |
+|---|---|
+| Transactional email | `IntegrationDefinition`, tenant credentials, DI sender + health services, retry/redaction, and app activation. There is no installed generic transactional-email adapter contract. |
+| Mailbox/email channel | Installed `communication_channels` hub plus its `ChannelAdapter`, per-user credentials, inbound/outbound conversion, polling/push, health, DI/setup registration. Follow the Gmail/IMAP precedent. |
+| Shipping/carrier | Provider package, service/quote/label/tracking adapter, webhook mapping, idempotent fulfillment updates. |
+| Payment gateway | Installed `GatewayAdapter`; `registerGatewayAdapter`, `registerWebhookHandler`, and `registerPaymentGatewayDescriptor`; idempotency keys, signed webhooks, concurrency-safe state machine. |
+| Commerce/ERP sync | `DataSyncAdapter`, mappings/presets, external IDs, cursors, reconciliation, progress. |
+| Generic webhook | Standard signing/verification, replay protection, delivery queue/log/status, scoped configuration. |
+| File import/export | Streaming parser/writer, format adapter, progress, cleanup, row errors, formula neutralization. |
+| Storage/media | Provider adapter, scoped object keys, signed access, metadata, cleanup and lifecycle. |
+
+## Package and Activation
+
+- In this standalone repository, put an app-specific provider under `src/modules/<provider>/` and activate it through `src/modules.ts`. Do not invent a `packages/*` workspace: the scaffold has no workspace topology.
+- When the user explicitly needs reuse across applications, build a separately published provider package/repository with compatible peer/runtime dependencies, public exports, build/prepack output, and module discovery files; install its packed artifact as an app dependency.
+- Ask before changing repository topology or adding the production dependency. Keep packed-consumer validation on the reusable-package branch only.
+- Register provider services through DI and use an `integration.ts` definition for credentials, health, versions, bundle membership, and detail-page extension spot.
+- A provider implementation is not complete when only a transport/client exists. The production path includes `index.ts`, `integration.ts`, `di.ts`, the typed host adapter where one exists, `setup.ts`/`acl.ts` when bootstrap or features are needed, and `src/modules.ts` activation.
+- Enable the local module or installed package in `src/modules.ts`. For the reusable branch, test the published/packed artifact, not only package source.
+- Keep provider env names prefixed and stable. Apply optional deployment presets from provider-owned `setup.ts` through normal services, with an idempotent rerun CLI when practical.
+- Do not preconfigure a provider from core/app bootstrap unless the provider package owns that code.
+
+## Credentials and Security
+
+- Store credentials through the integrations credential service/encryption maps; never log raw values or return secrets to list/detail APIs.
+- Declare the host credential/mapping scope. Thread `userId` on every per-user read/write. Tenant-wide credentials or scheduled jobs may use the installed contract's explicit tenant scope (including `organizationId: null`), but must never read or mutate organization-owned rows without deriving and checking an organization for that item.
+- Validate external base URLs against SSRF rules, including redirects and DNS/private ranges. Permit private endpoints only through an explicit development setting.
+- Redact authorization headers, tokens, signed URLs, provider payload secrets, and sensitive response bodies from errors and logs.
+- Use `createLogger` from `@open-mercato/shared/lib/logger` with structured fields; never use raw `console.*` or place credentials/provider payload bodies in log fields.
+- Verify inbound signatures against the raw body, enforce timestamp/replay bounds, and atomically claim each inbox delivery before side effects so duplicate callbacks have one winner (`atomic-inbox-claim`).
+
+## Reliability Contract
+
+- Define timeouts, bounded retries with jitter, provider rate-limit handling, circuit/health behavior, and structured logs with correlation IDs.
+- Give every remote mutation a durable idempotency key tied to the local operation. Preserve it across transaction rollback/retry.
+- Separate transport success from domain reconciliation. Persist external IDs and snapshots only after the relevant durable local/remote boundary succeeds.
+- Treat provider variants (site/store/currency/price scope, API version, feature availability) as explicit capability/config branches; do not infer one global shape.
+- Keep webhook, poll, manual retry, and scheduled sync paths convergent and safe when they race.
+
+## Data Sync and Cursor Safety
+
+- Implement/register a `DataSyncAdapter` with direction, supported entities, streaming import/export, connection validation, mappings, and cursor support.
+- Run sync through queue workers and `ProgressJob`; prevent overlapping runs for the same scoped provider/entity/direction unless explicitly supported.
+- Isolate item errors and continue safe batches; report row/item outcomes. A batch transport failure must not advance its cursor.
+- Persist a cursor only after the page/batch and its external-ID mappings commit. Retry resumes from the last successful cursor.
+- Make reruns idempotent and add reconciliation for provider-side totals/status that may differ from event payloads.
+- Preserve nested snapshots/variants required for later mapping; avoid stale payload assumptions by validating versioned contracts.
+
+## Import and Export
+
+- Stream large inputs/outputs; bound memory and file sizes. Validate content type, extension, encoding, column mapping, and row schemas.
+- Neutralize spreadsheet formulas in exported untrusted values. Avoid zip/path traversal and clean temporary/artifact files in `finally`/retention jobs.
+- Use deterministic locale/timezone/decimal/date handling and return row-level errors without exposing secrets.
+- Support cancellation and progress; perform domain writes through commands.
+
+## Provider UI and UMES
+
+- Use integrations/settings pages and provider detail widget spots rather than cloning the marketplace UI.
+- Gate credential, health, mapping, sync, and log actions with their own features. Use shared guarded mutations and states.
+- Add external IDs/status to domain pages through enrichers/widgets, keeping host modules unaware of the provider.
+- Use typed events and notifications for completion/failure; use DOM Event Bridge/progress for live status instead of aggressive polling.
+
+## Email Routing
+
+- First decide whether the request is **transactional delivery** or a **connected mailbox**. SMTP used only for application-generated mail is a transactional provider: register its `IntegrationDefinition`, encrypted credentials, DI sender/health services, and app module, but do not claim it implements a mailbox contract that the installed framework does not expose.
+- Gmail, IMAP/SMTP mailboxes, inbox sync, threading, history, or per-user send/receive belong to the installed `communication_channels` module. Implement `ChannelAdapter` from `@open-mercato/core/modules/communication_channels/lib/adapter`, set `integration.hub: 'communication_channels'`, register the adapter and exact `healthCheck.service` in `di.ts`, ensure idempotent adapter registration/default grants in `setup.ts`, and activate both the hub and provider in `src/modules.ts`.
+- Use the installed `channel_gmail` and `channel_imap` facts/source as precedent. Thread `userId` on every mailbox credential read/write; tenant-wide transactional credentials must not read per-user rows.
+
+## Testing
+
+1. Use a contract server/mock for normal, timeout, rate-limit, malformed, partial, retry, duplicate, signature, and pagination responses.
+2. Verify credential redaction, SSRF rejection, scope isolation, per-user separation, and webhook replay behavior.
+3. Verify a rerun produces no duplicate remote/local records and concurrent callbacks converge.
+4. Inject a page/batch failure and prove the cursor did not advance or lose data.
+5. Pack/build the provider and run generation/typecheck/tests from a standalone consumer.