@open-mercato/cli 0.6.7-develop.6677.1.beabb7ca12 → 0.6.7-develop.6686.1.bdda5ed397

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

@@ -0,0 +1,80 @@
+# 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 stable colon-form `entityId`, `apiPath`, and `extensionTableId`. These are host contracts, not cosmetic props.
+- 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.

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,104 @@
+# Unified Module Extensions and Overrides
+
+Use the smallest extension mechanism that preserves installed-module ownership. Resolve host IDs from generated facts or exact installed source; never invent spot, route, or entity IDs.
+
+## 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` |
+| 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.
+
+Common host families include `crud-form:<entityId>:fields`, `data-table:<tableId>:columns`, `:row-actions`, `:bulk-actions`, `:filters`, `:toolbar`, `:search-trailing`, and `menu:sidebar:*`/`menu:topbar:*`. Resolve the concrete IDs; do not derive them by guess.
+
+## 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.

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.