@open-mercato/cli 0.6.7-develop.6758.1.697eade236 → 0.6.7-develop.6768.1.9d2c4efc43

package/.turbo/turbo-build.log

@@ -1,6 +1,8 @@
-[build:cli] found 96 entry points
+[build:cli] found 97 entry points
 Copied create-app/agentic/ → dist/agentic/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for ai_assistant
+Generated 54 module fact-sheets → dist/agentic/guides/modules/
+[build:cli] built successfully
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_gmail
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for checkout
@@ -25,9 +27,7 @@ Copied create-app/agentic/ → dist/agentic/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for feature_toggles
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for inbox_ops
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for integrations
-Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for messages
-[build:cli] built successfully
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for notifications
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for payment_gateways
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for perspectives

package/build.mjs

@@ -111,7 +111,7 @@ await buildPackage(packageDir, {
         coreVersion = null
       }
 
-      const { factsByModule, markdownByModule, warnings } = extractAllModuleFacts({
+      const { factsByModule, markdownByModule, frameworkMarkdown, warnings } = extractAllModuleFacts({
         sources,
         registryPath: existsSync(registryPath) ? registryPath : null,
         coreVersion,
@@ -123,6 +123,7 @@ await buildPackage(packageDir, {
         writeFileSync(join(modulesGuidesDir, `${moduleId}.md`), markdown)
       }
       writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(factsByModule))
+      writeFileSync(join(guidesDestDir, 'framework-extension-points.md'), frameworkMarkdown)
 
       for (const warning of warnings) console.warn(warning)
       console.log(`Generated ${Object.keys(markdownByModule).length} module fact-sheets → dist/agentic/guides/modules/`)

package/dist/agentic/guides/extensions.md

@@ -1,6 +1,18 @@
 # 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.
+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
 
@@ -17,7 +29,7 @@ Add every other match too: `backend-ui` + `om-backend-ui-design` when authoring,
 | 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 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` |
@@ -66,7 +78,9 @@ Add every other match too: `backend-ui` + `om-backend-ui-design` when authoring,
 - 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.
+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
 
@@ -102,3 +116,6 @@ Common host families include `crud-form:<entityId>:fields`, `data-table:<tableId
 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 |