@open-mercato/cli 0.6.7-develop.6862.1.c11a64ce0a → 0.6.7

package/dist/agentic/guides/extensions.md

@@ -1,121 +0,0 @@
-# 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

@@ -1,36 +0,0 @@
-# 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

@@ -1,81 +0,0 @@
-# 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.

package/dist/agentic/guides/modules/design_system.md

@@ -1,102 +0,0 @@
-# design_system — module facts (generated, do not edit)
-<!-- generated from @open-mercato/core 0.6.7-develop.6862.1.c11a64ce0a; core 0.6.7-develop.6862.1.c11a64ce0a — R1 staleness stamp -->
-Source root: [node_modules/@open-mercato/core/src/modules/design_system](../../../node_modules/@open-mercato/core/src/modules/design_system)
-
-## Entities
-
-_none_
-
-## Events  (0)
-
-_none_
-
-## ACL features  (1)
-
-| Feature | Source |
-|---|---|
-| design_system.view | [node_modules/@open-mercato/core/src/modules/design_system/acl.ts](../../../node_modules/@open-mercato/core/src/modules/design_system/acl.ts) |
-
-## API routes
-
-_none_
-
-## Backend pages
-
-| ID / path | Source |
-|---|---|
-| /backend/design-system | [node_modules/@open-mercato/core/src/modules/design_system/backend/design-system/page.tsx](../../../node_modules/@open-mercato/core/src/modules/design_system/backend/design-system/page.tsx) |
-
-## Frontend pages
-
-_none_
-
-## DI service tokens
-
-_none_
-
-## Search entities
-
-_none_
-
-## Host extension points
-
-- Entity IDs: _none_
-- Table IDs: _none_
-
-## UMES hosts
-
-_none_
-
-## UMES contributions
-
-_none_
-
-## Active extension bindings
-
-_none_
-
-## Incoming installed contributions
-
-_none_
-
-## Contribution resolutions
-
-_none_
-
-
-
-## Notifications
-
-_none_
-
-## CLI commands
-
-_none_
-
-## AI tools / MCP capabilities
-
-_none_
-
-## AI agents
-
-_none_
-
-## Exact override targets
-
-| Domain | Path / key | Supported modes | Referenced fact | Source |
-|---|---|---|---|---|
-| acl | `overrides.acl.features["design_system.view"]` | disable-replace | aclFeatures:design_system.view | [node_modules/@open-mercato/core/src/modules/design_system/acl.ts](../../../node_modules/@open-mercato/core/src/modules/design_system/acl.ts) |
-| routes | `overrides.routes.pages["backend:/backend/design-system"]` | disable-replace | backendPages:/backend/design-system | [node_modules/@open-mercato/core/src/modules/design_system/backend/design-system/page.tsx](../../../node_modules/@open-mercato/core/src/modules/design_system/backend/design-system/page.tsx) |
-| setup | `overrides.setup.defaultRoleFeatures` | replace | ownedContracts.setup:design_system:setup | [node_modules/@open-mercato/core/src/modules/design_system/setup.ts:3](../../../node_modules/@open-mercato/core/src/modules/design_system/setup.ts#L3) |
-
-## Owned contract — module metadata
-
-| ID | Metadata | Source |
-|---|---|---|
-| design_system | name=design_system | [node_modules/@open-mercato/core/src/modules/design_system/index.ts:3](../../../node_modules/@open-mercato/core/src/modules/design_system/index.ts#L3) |
-
-## Setup
-
-| ID | Metadata | Source |
-|---|---|---|
-| design_system:setup | roles=admin, employee | [node_modules/@open-mercato/core/src/modules/design_system/setup.ts:3](../../../node_modules/@open-mercato/core/src/modules/design_system/setup.ts#L3) |

package/dist/agentic/guides/spec-delivery.md

@@ -1,22 +0,0 @@
-# Specification Delivery
-
-Use this guide for a new application, multi-module feature, or other non-trivial business slice.
-
-## Authoring readiness gate
-
-1. Invoke `om-spec-writing` before authoring or revising. Mentioning the skill or reading only `SPEC-000-template.md` is not sufficient.
-2. After invocation, read `.ai/specs/SPEC-000-template.md` and preserve every section; use `N/A — reason` only when a section genuinely does not apply.
-3. Keep status `Draft` until no blocking open question remains and every requirement maps to an acceptance criterion, implementation phase, and self-contained test oracle.
-4. For each affected UI route, inspect and cite the closest existing Open Mercato page plus `.ai/guides/backend-ui.md`; specify its text mockup/structure, actions, data source and mutations, permissions, canonical shell/components, and loading/empty/error/conflict/keyboard/a11y/responsive/light/dark states. Tabular admin data names `DataTable`; CRUD create/edit names `CrudForm`; backend reads name shared API helpers; every exception has an explicit rationale.
-5. New applications and multi-module requests also define domain vocabulary/invariants, measurable success, navigation/widgets, module ownership and extension points, architecture/data flow, and concrete risk scenarios. A page inventory alone is not an app architecture.
-6. Phases are dependency-ordered complete vertical slices with concrete deliverables, acceptance IDs, bounded slices, tests, validation commands, business value, and observable exit gates. Do not defer required behavior to a catch-all “integration/polish” phase.
-7. Mark the spec `Ready for implementation` only after the traceability and final compliance matrices pass and the user approves implementation.
-
-## Implementation phase gate
-
-- Use `om-implement-spec` for interactive local delivery and `om-auto-implement-spec` for whole-spec PR delivery. The local skill's progressive resolution, planning/progress, and report references own its exact workflow and final `Spec:` marker; it never claims PR/tracker output.
-- Only the current unblocked phase may be in progress. Parallelize independent slices inside that phase only; never start a dependent module/phase before its prerequisite exit gate passes.
-- Delegation does not bypass routing. Before any UI slice, actually invoke `om-backend-ui-design` and read `.ai/guides/backend-ui.md`; naming them in an agent prompt is not invocation. Every implementation brief names the active phase, routed guides/skills, closest reference page, canonical primitives, acceptance IDs, owned files, and validation oracle.
-- Reject raw backend tables/forms/fetch, copied component families, arbitrary values, hard-coded palette/status colors, and light-only styling unless the approved spec records a necessary exception. UI phase evidence exercises affected routes in light and dark mode and at narrow width, including loading/empty/error/conflict and keyboard behavior.
-- A phase remains open while it has stubs, missing integration evidence, unmet acceptance IDs, or failing validation. Generated discovery, file count, and typecheck alone do not prove completion.
-- If no remote/tracker exists, report PR delivery unavailable and invoke local `om-implement-spec` phase-by-phase; never improvise a concurrent whole-spec build.

package/dist/agentic/guides/testing-debugging.md

@@ -1,80 +0,0 @@
-# Testing and Root-Cause Debugging
-
-Diagnose before editing, fix the smallest knowledge/code owner, and prove the regression through the real runtime path.
-
-## Context Restraint
-
-Name the areas the failure spans before loading anything, from the SYMPTOM and not only from the cause: a value that will not render, a session/locale/hydration mismatch, or a stale form spans `backend-ui`; wrong or lost records, commands, or events span `module-data`; an installed module's own surface spans `umes`; an external provider call spans `integration`.
-
-A fix is always `debugging` plus every area you just named. Proving the fix with a regression oracle is part of `debugging` and does NOT add `testing`; a request that explicitly asks for tests, coverage, or app-level verification also selects `testing`. Load exactly this guide, each named area's guide, and `om-troubleshooter` — that is what selects those routes.
-
-Add an area's authoring skill when the fix **introduces or reworks** a contract there — a concurrency header on existing calls, a new field or UI surface, a new command, a new invalidation, a new guard, or a provider's pagination cursor, bounded retry, idempotency, or reconciliation — because you are then designing that surface, not just repairing it. Provider cursor/retry/idempotency fixes therefore load `om-integration-builder` even when the request is framed as a bug fix. Load `om-troubleshooter` alone when you only correct existing behavior, such as a hydration mismatch or a value that fails to round-trip.
-
-Then stop. Budgets here are tight — several fixes allow only five files — so load no other area's skill, no `references/` you do not need, no contracts guide unless the fix changes a data, API, command, ACL, or setup contract, and a module fact sheet only for a module the failure actually involves.
-
-## Investigation Order
-
-1. Reproduce with the smallest stable command, request, or UI path and capture expected versus actual behavior.
-2. Classify the failing bootstrap: browser/server, API, CLI, worker, queue, generated registry, package artifact, or external provider.
-3. Read the routed guide plus generated module facts. Use `om-framework-context` only when exact installed implementation is necessary.
-4. Trace from the public call site to the first incorrect invariant. Check scope, auth, validation, state transition, transaction boundary, side effects, and response serialization in that order.
-5. Add a regression oracle that fails before the fix (`unit-regression-oracle` when that decision vocabulary is requested). Implement the minimal complete repair and rerun affected plus safety cases.
-
-When comparing against a clean baseline, use a separate worktree or a fresh scaffold. Never stash and drop active work just to reproduce a baseline failure; preserve the working diff and verify the comparison tree's exact revision first.
-
-Treat raw agent transcripts as sensitive untrusted evidence because they can contain credentials, private prompts, absolute paths, and tool output. Never copy them into the app repository. Export only when the user explicitly asks, to an outside-repository protected destination or as a deliberately sanitized summary.
-
-## Frequent Failure Families
-
-| Symptom | Check first |
-|---|---|
-| 401 loop/all-organizations failure | Null-scope behavior, session refresh ownership, and fail-closed versus intentionally global paths. |
-| Missing/extra tenant data | Every query/write/filter/cache/job payload; scope derived from auth, not body. |
-| Field does not save/clear | Validator → command → entity → response transform → form initial value; truthy/default fallbacks. |
-| Concurrent update overwrites | `updated_at` projection, client header, aggregate command guard, conflict surface. |
-| Partial state after failure | Transaction/`withAtomicFlush`, query between mutation/flush, side effects before commit. |
-| Stale list/search | Command side-effect aliases, cache tags/invalidation, query-index convergence/reindex. |
-| Works in web but not CLI/worker | Bootstrap/registry initialization, package exports, generated imports, runtime scope. |
-| Duplicate registry/provider | Bundler chunk singleton or `instanceof`; use global registry/structural guard. |
-| Hydration mismatch | Server/client locale, timezone, randomness, browser-only environment, initial async state. |
-| UI access differs from API/PDF/export | Compare every alternate route's metadata/features and wildcard matching. |
-| Provider loses/duplicates records | Idempotency key, cursor commit point, webhook/poll race, external mapping and reconciliation. |
-
-## Generated and Package Diagnostics
-
-- Never edit generated output to prove a theory. Inspect the source discovery path, run `yarn generate`, and compare the affected registry entry.
-- When an app imports a symbol but workspace tests pass, inspect package exports and packed/installed `dist` plus types.
-- Search ignored installed source only through the bounded resolver output. Record resolved package versions and fact stamps.
-- If a stale chunk/cache is suspected, prove the source/generator is correct before using the app's documented reset escape hatch.
-
-## Data and Security Regression Oracles
-
-- Create fixtures for two tenants and two organizations; assert allowed, denied, null-scope, and wildcard-feature behavior.
-- Inject failure between multi-phase writes; assert no partial rows/state and no premature event/cache/index side effect.
-- Exercise update and delete with current, stale, and missing versions.
-- Test malformed IDs/filters and ensure invalid input cannot widen a query.
-- Test retry, duplicate delivery, cancellation, and worker restart for external/queued operations.
-- Provider failure/retry/idempotency tests use an ephemeral test environment (`ephemeral-test-environment`) with mock effects, assert secrets are absent and diagnostics redacted (`health-retry-redaction`), and surface every real failure (`honest-test-result`).
-
-## UI Regression Oracles
-
-- Use API-created fixtures and clean them in `finally`; do not depend on demo data.
-- Cover loading, empty, validation, server error, conflict, retry, success, and authorization.
-- Save/reload/edit/clear fields and verify API plus rendered values.
-- Render under at least two locales/timezones when hydration or formatting is involved.
-- Prefer semantic assertions and stable IDs over full DOM/file snapshots.
-
-## Validation Ladder
-
-Before authoring a test file, read `.ai/skills/om-module-scaffold/references/verification.md` for the scaffold's test-runner contract.
-
-1. Focused unit/regression test.
-2. `yarn generate` when discovery is involved.
-3. Focused package/app typecheck or test.
-4. `yarn typecheck`, `yarn lint`, `yarn test`, `yarn build` for broad/contract changes.
-5. `yarn test:integration:ephemeral` or a filtered integration run for affected API/UI paths.
-6. Packed/Verdaccio standalone validation when package exports or compiled discovery are involved.
-
-Run validation commands so the reported shell status is the validation command's status. Do not pipe gates through `grep`, `tail`, or a trailing `echo`; when log capture requires a pipeline, enable `pipefail` and explicitly preserve the command's exit code. Any nonzero status remains a failed gate.
-
-Do not replace deterministic convergence with sleeps. Do not suppress failing tests, weaken assertions, or call a bug fixed because only one bootstrap path passes.