create-mercato-app 0.6.2-develop.3461.1.605f31c2c9 → 0.6.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.2-develop.3461.1.605f31c2c9",
+  "version": "0.6.2",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",
@@ -13,7 +13,7 @@
   ],
   "scripts": {
     "build": "node build.mjs",
-    "test": "node --import tsx --test src/**/*.test.ts",
+    "test": "node --import tsx --test --test-timeout=120000 src/**/*.test.ts",
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
@@ -21,10 +21,10 @@
     "tar": "^7.5.15"
   },
   "devDependencies": {
-    "@types/node": "^25.6.2",
+    "@types/node": "^25.9.0",
     "esbuild": "^0.28.0",
-    "tsx": "^4.21.0",
-    "typescript": "^5.9.3"
+    "tsx": "^4.22.2",
+    "typescript": "^6.0.3"
   },
   "publishConfig": {
     "access": "public"
@@ -41,6 +41,5 @@
     "scaffolding",
     "cli"
   ],
-  "license": "MIT",
-  "stableVersion": "0.6.1"
+  "license": "MIT"
 }

package/template/.env.example

@@ -55,6 +55,13 @@ OM_ENABLE_ENTERPRISE_MODULES_SSO=false
 # Requires OM_ENABLE_ENTERPRISE_MODULES=true
 OM_ENABLE_ENTERPRISE_MODULES_SECURITY=false
 
+# Enable the S3-compatible storage provider module (default: false).
+# When true, `storage_s3` is added to enabledModules in modules.ts and the
+# Integration Marketplace exposes the "S3 Object Storage" card.
+# The provider can also be preconfigured from env vars — see the
+# "S3 Storage Preconfiguration" block at the bottom of this file.
+OM_ENABLE_STORAGE_S3=false
+
 # OM_SECURITY_MFA_SETUP_SECRET=change-me-mfa-setup-secret
 OM_SECURITY_TOTP_ISSUER=Open Mercato
 OM_SECURITY_TOTP_WINDOW=1
@@ -451,6 +458,52 @@ OCR_MODEL=gpt-4o
 # OM_INTEGRATION_AKENEO_CATEGORIES_SETTINGS_JSON=
 # OM_INTEGRATION_AKENEO_ATTRIBUTES_SETTINGS_JSON=
 
+# ============================================================================
+# S3 Storage Preconfiguration
+# ============================================================================
+# If these credentials are set, the storage_s3 provider preconfigures itself
+# during tenant setup and can be rerun later (for existing tenants) with:
+# yarn mercato storage_s3 configure-from-env --tenant <tenantId> --org <organizationId>
+#
+# For unattended deploys (Dokploy, Coolify, Kamal, etc.), use --all-tenants
+# as a post-deploy hook to apply the preset to every active organization
+# without tracking UUIDs in your deploy config:
+# yarn mercato storage_s3 configure-from-env --all-tenants
+#
+# The CLI exits non-zero on an incomplete preset so CI/automation can detect
+# misconfiguration. Pass --force (or set OM_INTEGRATION_STORAGE_S3_FORCE_PRECONFIGURE=true)
+# to overwrite credentials that have already been stored for the tenant.
+#
+# The module itself is only loaded when OM_ENABLE_STORAGE_S3=true (see above)
+# — without that flag the preconfiguration block below is ignored.
+#
+# Required for auto-preconfiguration:
+# OM_INTEGRATION_STORAGE_S3_ACCESS_KEY_ID=AKIAIOSFODNN7EXAMPLE
+# OM_INTEGRATION_STORAGE_S3_SECRET_ACCESS_KEY=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
+# OM_INTEGRATION_STORAGE_S3_REGION=eu-central-1
+# OM_INTEGRATION_STORAGE_S3_BUCKET=my-mercato-attachments
+#
+# Optional behavior:
+# OM_INTEGRATION_STORAGE_S3_SESSION_TOKEN=
+# OM_INTEGRATION_STORAGE_S3_ENDPOINT=https://fra1.digitaloceanspaces.com
+# OM_INTEGRATION_STORAGE_S3_FORCE_PATH_STYLE=false
+# OM_INTEGRATION_STORAGE_S3_FORCE_PRECONFIGURE=false
+#
+# Notes:
+# - SESSION_TOKEN is only needed for short-lived STS credentials.
+# - Leave ENDPOINT blank for AWS S3. Set it for MinIO, DigitalOcean Spaces,
+#   Cloudflare R2, Backblaze B2, etc.
+# - FORCE_PATH_STYLE must be true for MinIO and most self-hosted S3 services.
+# - Leave the block commented out when S3 should not be preconfigured.
+# OM_INTEGRATION_STORAGE_S3_ACCESS_KEY_ID=
+# OM_INTEGRATION_STORAGE_S3_SECRET_ACCESS_KEY=
+# OM_INTEGRATION_STORAGE_S3_REGION=
+# OM_INTEGRATION_STORAGE_S3_BUCKET=
+# OM_INTEGRATION_STORAGE_S3_SESSION_TOKEN=
+# OM_INTEGRATION_STORAGE_S3_ENDPOINT=
+# OM_INTEGRATION_STORAGE_S3_FORCE_PATH_STYLE=false
+# OM_INTEGRATION_STORAGE_S3_FORCE_PRECONFIGURE=false
+
 # ============================================================================
 # InboxOps Configuration (email-to-ERP agent)
 # ============================================================================

package/template/AGENTS.md

@@ -147,6 +147,17 @@ This is a Next.js 16 application built on the **Open Mercato** modular ERP frame
 - `src/bootstrap.ts` - Application initialization (imports generated files, registers i18n)
 - `.mercato/generated/` - Auto-generated files from `yarn generate` (do not edit manually)
 
+### Module Overrides
+
+Use the unified `entry.overrides` field in `src/modules.ts` when this app needs to replace or disable a contract from a package-backed module without forking it. The template ships a non-applied `moduleOverrideExamples` object covering AI, routes, events, workers, widgets, notifications, interceptors, setup, ACL, DI, and encryption. Copy only the specific domains you need into the target module entry's `overrides` field.
+
+Rules:
+
+- `null` disables a matching contract; an object/function definition replaces it.
+- API route keys are `'METHOD /api/path'`; page route keys are `'/backend/path'` or `'/frontend/path'`.
+- `setup` overrides apply to the module entry carrying them, not to a separate setup id map.
+- The standard `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` before registries load.
+
 ### Routing Structure
 
 - `/backend/*` - Admin panel routes (AppShell with sidebar navigation)
@@ -248,7 +259,7 @@ export const aiAgentOverrides: AiAgentOverridesMap = {
 }
 ```
 
-Example `modules.ts` inline override (preferred for app-level decisions that don't deserve a fake module). AI lives at `overrides.ai.*`; other domains (routes, events, workers, widgets, …) reuse the same `entry.overrides` umbrella per the [unified spec](https://github.com/open-mercato/open-mercato/blob/main/.ai/specs/2026-05-04-modules-ts-unified-overrides.md) — AI is Phase 1, other domains roll out as separate PRs:
+Example `modules.ts` inline override (preferred for app-level decisions that do not deserve a fake module). All module contract domains live under the same `entry.overrides` umbrella per the [unified spec](https://github.com/open-mercato/open-mercato/blob/main/.ai/specs/2026-05-04-modules-ts-unified-overrides.md):
 
 ```ts
 // src/modules.ts
@@ -260,6 +271,17 @@ Example `modules.ts` inline override (preferred for app-level decisions that don
       agents: { 'catalog.catalog_assistant': null },
       tools:  { 'inbox_ops_accept_action': null },
     },
+    routes: {
+      api: {
+        'GET /api/example/override-probe': {
+          handler: async () => Response.json({ ok: true, source: 'override' }),
+          metadata: { requireAuth: false },
+        },
+      },
+      pages: {
+        '/backend/example/reports': null,
+      },
+    },
   },
 },
 ```
@@ -290,6 +312,108 @@ yarn mercato configs cache structural --all-tenants
 
 Refer to the `create-ai-agent` skill (`.ai/skills/create-ai-agent/SKILL.md`) and the public docs at `framework/ai-assistant/overrides` for the full contract, MUST rules, and the resolution order.
 
+### Unified module contract overrides
+
+The same `entry.overrides` surface that disables/replaces AI agents also wires routes, subscribers, workers, widgets, notifications, interceptors, enrichers, guards, CLI commands, setup hooks, ACL features, DI bindings, and encryption maps. Use it when you want to replace a contract shipped by an upstream module without forking the source.
+
+```ts
+// src/modules.ts — representative examples across override phases
+{
+  id: 'example',
+  from: '@app',
+  overrides: {
+    routes: {
+      api: {
+        // disable
+        'DELETE /api/example/items': null,
+        // replace
+        'POST /api/example/items': {
+          handler: async (req) => new Response(JSON.stringify({ ok: true }), { status: 200 }),
+          metadata: { requireAuth: true, requireFeatures: ['example.manage'] },
+        },
+      },
+      pages: {
+        '/backend/example/items': null,
+      },
+    },
+    events: {
+      subscribers: {
+        'example.todo.created.notify': null,
+      },
+    },
+    workers: {
+      'example:sync': null,
+    },
+    widgets: {
+      injection: { 'example.toolbar': null },
+      dashboard: { 'example.kpi': null },
+      components: {
+        'page:/backend/example': {
+          target: { componentId: 'page:/backend/example' },
+          priority: 10,
+          propsTransform: (props) => props,
+        },
+      },
+    },
+    notifications: {
+      types: { 'example.notice': null },
+      handlers: { 'example.notice.toast': null },
+    },
+    interceptors: { 'example.items.audit': null },
+    commandInterceptors: { 'example.command.audit': null },
+    enrichers: { 'example.items.enricher': null },
+    guards: { 'example.backend.guard': null },
+    cli: { 'example seed': null },
+    setup: {
+      defaultRoleFeatures: { admin: ['example.view'] },
+      seedExamples: false,
+    },
+    acl: {
+      features: { 'example.manage': null },
+    },
+    di: {
+      exampleService: {
+        register: (container, key) => container.register({ [key]: { mode: 'replacement' } }),
+      },
+    },
+    encryption: {
+      maps: { 'example:item': null },
+    },
+  },
+},
+```
+
+Programmatic equivalent (boot-time, env-driven, or test scaffold):
+
+```ts
+// src/bootstrap.ts (extra)
+import {
+  applyApiRouteOverrides,
+  applyPageRouteOverrides,
+  applyWorkerOverrides,
+} from '@open-mercato/shared/modules/overrides'
+
+applyApiRouteOverrides({
+  'GET /api/example/items': null,
+})
+applyPageRouteOverrides({
+  '/backend/example/items': null,
+})
+applyWorkerOverrides({
+  'example:sync': null,
+})
+```
+
+Key rules:
+
+- Keys are `'METHOD /api/path'`; method is normalized, path leading slash optional, trailing slashes stripped.
+- Page route keys are `'/backend/path'` or `'/frontend/path'`.
+- `null` disables the matching contract; a definition replaces it.
+- Programmatic > `modules.ts` > file-based where supported > base. The dispatcher MUST run before registries first-load — the template's `bootstrap.ts` already does this.
+- Stale override keys log a warning so operators notice renamed or removed upstream contracts.
+
+Full reference: `framework/modules/overrides` and `framework/modules/routes-and-pages`.
+
 ## Disabling the Dashboards Module: Update /backend
 
 The default `/backend` page (`src/app/(backend)/backend/page.tsx`) renders `<DashboardScreen />` from `@open-mercato/ui/backend/dashboard`. That component's data flow depends on the `dashboards` module being enabled — widgets, layouts, and the dashboard API routes all live there.

package/template/package.json.template

@@ -78,7 +78,7 @@
     "@uiw/react-markdown-preview": "^5.2.0",
     "@uiw/react-md-editor": "^4.1.0",
     "@xyflow/react": "^12.6.0",
-    "ai": "^6.0.177",
+    "ai": "^6.0.185",
     "awilix": "^12.0.5",
     "bcryptjs": "^3.0.3",
     "class-variance-authority": "^0.7.1",
@@ -90,7 +90,7 @@
     "mammoth": "^1.9.0",
     "newrelic": "^13.19.1",
     "next": "16.2.6",
-    "pg": "8.20.0",
+    "pg": "8.21.0",
     "pdfjs-dist": "^5.4.149",
     "react": "19.2.5",
     "react-big-calendar": "^1.19.4",
@@ -103,8 +103,8 @@
     "semver": "^7.7.4",
     "tailwind-merge": "^3.5.0",
     "zod": "4.3.6",
-    "@stripe/react-stripe-js": "^6.3.0",
-    "@stripe/stripe-js": "^9.3.1",
+    "@stripe/react-stripe-js": "^6.4.0",
+    "@stripe/stripe-js": "^9.6.0",
     "@open-mercato/gateway-stripe": "{{PACKAGE_VERSION}}",
     "@open-mercato/sync-akeneo": "{{PACKAGE_VERSION}}"
   },

package/template/scripts/dev-cache-purge.mjs

@@ -0,0 +1,33 @@
+import fs from 'node:fs'
+import path from 'node:path'
+
+// Greenfield must not inherit the prior run's compiler state. Wiping the
+// configured Next.js distDir (`.mercato/next`) plus the legacy `.next` location guarantees Turbopack rebuilds the route table
+// and middleware manifest from scratch on the next launch.
+export const GREENFIELD_PURGE_TARGETS = Object.freeze([
+  Object.freeze(['.mercato', 'next']),
+  Object.freeze(['.next']),
+])
+
+export function purgeAppBuildCaches({
+  rootDir = process.cwd(),
+  fsImpl = fs,
+  logger = console,
+  targets = GREENFIELD_PURGE_TARGETS,
+} = {}) {
+  const removed = []
+  for (const segments of targets) {
+    const target = path.join(rootDir, ...segments)
+    if (!fsImpl.existsSync(target)) continue
+    fsImpl.rmSync(target, { recursive: true, force: true })
+    removed.push(segments.join('/'))
+  }
+  if (removed.length === 0) {
+    logger.log('🧹 [dev:greenfield] no stale Next/Turbopack build directories to purge')
+  } else {
+    for (const relPath of removed) {
+      logger.log(`🧹 [dev:greenfield] removed ${relPath}`)
+    }
+  }
+  return { removed }
+}

package/template/scripts/dev.mjs

@@ -22,6 +22,7 @@ import {
   resolveProgressPercent,
   stripAnsi,
 } from './dev-splash-helpers.mjs'
+import { purgeAppBuildCaches } from './dev-cache-purge.mjs'
 import { resolveSpawnCommand } from './dev-spawn-utils.mjs'
 import { createDevSplashCodingFlow } from './dev-splash-coding-flow.mjs'
 import { createDevSplashGitRepoFlow } from './dev-splash-git-repo-flow.mjs'
@@ -1647,6 +1648,7 @@ async function runClassicStandardDev() {
 }
 
 async function runGreenfieldDev() {
+  purgeAppBuildCaches()
   await runStage('🧱 Greenfield build packages', ['build:packages'], { stageCurrent: 1, stageTotal: 5 })
   await runStage('🧬 Greenfield generate artifacts', ['generate'], { stageCurrent: 2, stageTotal: 5 })
   await runStage('🧱 Greenfield rebuild packages', ['build:packages'], { stageCurrent: 3, stageTotal: 5 })
@@ -1657,6 +1659,7 @@ async function runGreenfieldDev() {
 }
 
 async function runClassicGreenfieldDev() {
+  purgeAppBuildCaches()
   await runRawYarnCommand(['build:packages'])
   await runRawYarnCommand(['generate'])
   await runRawYarnCommand(['build:packages'])

package/template/src/app/(backend)/backend/[...slug]/page.tsx

@@ -1,8 +1,9 @@
 import { notFound, redirect } from 'next/navigation'
 import { cookies } from 'next/headers'
 import Link from 'next/link'
-import { findRouteManifestMatch } from '@open-mercato/shared/modules/registry'
+import { findRouteManifestMatch, getBackendRouteManifests, registerBackendRouteManifests } from '@open-mercato/shared/modules/registry'
 import { backendRoutes } from '@/.mercato/generated/backend-routes.generated'
+import { bootstrap } from '@/bootstrap'
 import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 import { ApplyBreadcrumb } from '@open-mercato/ui/backend/AppShell'
@@ -17,6 +18,9 @@ import { resolveLocalizedTitleMetadata } from '@/lib/metadata'
 import { resolvePageMiddlewareRedirect } from '@open-mercato/shared/lib/middleware/page-executor'
 import { backendMiddlewareEntries } from '@/.mercato/generated/backend-middleware.generated'
 
+bootstrap()
+registerBackendRouteManifests(backendRoutes)
+
 type Awaitable<T> = T | Promise<T>
 
 type BackendParams = { params: Awaitable<{ slug?: string[] }> }
@@ -39,7 +43,7 @@ async function renderAccessDenied() {
 export async function generateMetadata(props: BackendParams): Promise<Metadata> {
   const params = await props.params
   const pathname = '/backend/' + (params.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(backendRoutes, pathname)
+  const match = findRouteManifestMatch(getBackendRouteManifests(), pathname)
   if (!match) {
     return {}
   }
@@ -53,7 +57,7 @@ export async function generateMetadata(props: BackendParams): Promise<Metadata>
 export default async function BackendCatchAll(props: BackendParams) {
   const params = await props.params
   const pathname = '/backend/' + (params.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(backendRoutes, pathname)
+  const match = findRouteManifestMatch(getBackendRouteManifests(), pathname)
   if (!match) return notFound()
   let auth: AuthContext = null
   let container: Awaited<ReturnType<typeof createRequestContainer>> | null = null

package/template/src/app/(backend)/backend/__tests__/backend-require-features.test.tsx

@@ -8,6 +8,11 @@ jest.mock('@/.mercato/generated/backend-routes.generated', () => ({
   backendRoutes: [],
 }))
 
+jest.mock('@/bootstrap', () => ({
+  bootstrap: jest.fn(),
+  isBootstrapped: jest.fn(() => true),
+}))
+
 import BackendCatchAll from '@/app/(backend)/backend/[...slug]/page'
 
 // Mock UI breadcrumb component to avoid UI package dependency
@@ -39,6 +44,8 @@ jest.mock('@open-mercato/shared/modules/registry', () => ({
     },
     params: {},
   })),
+  getBackendRouteManifests: jest.fn(() => []),
+  registerBackendRouteManifests: jest.fn(),
 }))
 
 jest.mock('@/.mercato/generated/backend-middleware.generated', () => ({

package/template/src/app/(backend)/backend/layout.tsx

@@ -106,6 +106,7 @@ export default async function BackendLayout({
         rightHeaderSlot={(
           <BackendHeaderChrome
             email={auth?.email}
+            userId={auth?.sub ?? null}
             embeddingConfigured={embeddingConfigured}
             missingConfigMessage={missingConfigMessage}
             tenantId={auth?.tenantId ?? null}

package/template/src/app/(frontend)/[...slug]/page.tsx

@@ -1,9 +1,8 @@
 import { notFound, redirect } from 'next/navigation'
 import Link from 'next/link'
-import { findRouteManifestMatch, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'
+import { findRouteManifestMatch, getFrontendRouteManifests, registerFrontendRouteManifests } from '@open-mercato/shared/modules/registry'
+import { bootstrap } from '@/bootstrap'
 import { frontendRoutes } from '@/.mercato/generated/frontend-routes.generated'
-
-registerFrontendRouteManifests(frontendRoutes)
 import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
 import { AccessDeniedMessage } from '@open-mercato/ui/backend/detail'
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
@@ -16,6 +15,9 @@ import { resolveLocalizedTitleMetadata } from '@/lib/metadata'
 import { resolvePageMiddlewareRedirect } from '@open-mercato/shared/lib/middleware/page-executor'
 import { frontendMiddlewareEntries } from '@/.mercato/generated/frontend-middleware.generated'
 
+bootstrap()
+registerFrontendRouteManifests(frontendRoutes)
+
 type FrontendParams = { params: Promise<{ slug: string[] }> }
 
 async function renderAccessDenied() {
@@ -36,7 +38,7 @@ async function renderAccessDenied() {
 export async function generateMetadata({ params }: FrontendParams): Promise<Metadata> {
   const p = await params
   const pathname = '/' + (p.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(frontendRoutes, pathname)
+  const match = findRouteManifestMatch(getFrontendRouteManifests(), pathname)
   if (!match) {
     return {}
   }
@@ -50,7 +52,7 @@ export async function generateMetadata({ params }: FrontendParams): Promise<Meta
 export default async function SiteCatchAll({ params }: FrontendParams) {
   const p = await params
   const pathname = '/' + (p.slug?.join('/') ?? '')
-  const match = findRouteManifestMatch(frontendRoutes, pathname)
+  const match = findRouteManifestMatch(getFrontendRouteManifests(), pathname)
   if (!match) return notFound()
 
   // Customer portal auth gate — separate from staff auth

package/template/src/app/api/[...slug]/route.ts

@@ -1,17 +1,9 @@
 import { NextResponse, type NextRequest } from 'next/server'
-import { findApiRouteManifestMatch, registerApiRouteManifests, registerBackendRouteManifests, registerFrontendRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
+import { findApiRouteManifestMatch, getApiRouteManifests, registerApiRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
 import { isCrudHttpError } from '@open-mercato/shared/lib/crud/errors'
 import { apiRoutes } from '@/.mercato/generated/api-routes.generated'
-import { backendRoutes } from '@/.mercato/generated/backend-routes.generated'
-import { frontendRoutes } from '@/.mercato/generated/frontend-routes.generated'
 import { resolveAuthFromRequestDetailed } from '@open-mercato/shared/lib/auth/server'
 import { bootstrap } from '@/bootstrap'
-
-// Ensure all package registrations are initialized for API routes
-bootstrap()
-registerBackendRouteManifests(backendRoutes)
-registerFrontendRouteManifests(frontendRoutes)
-registerApiRouteManifests(apiRoutes)
 import type { AuthContext } from '@open-mercato/shared/lib/auth/server'
 import { createRequestContainer } from '@open-mercato/shared/lib/di/container'
 import { RbacService } from '@open-mercato/core/modules/auth/services/rbacService'
@@ -25,6 +17,10 @@ import { checkRateLimit, getClientIp, RATE_LIMIT_ERROR_KEY, RATE_LIMIT_ERROR_FAL
 import { getGlobalEventBus } from '@open-mercato/shared/modules/events'
 import { applicationLifecycleEvents, type ApplicationLifecycleEventId } from '@open-mercato/shared/lib/runtime/events'
 
+// Ensure all package registrations are initialized for API routes.
+bootstrap()
+registerApiRouteManifests(apiRoutes)
+
 type MethodMetadata = {
   requireAuth?: boolean
   /** @deprecated Use `requireFeatures` instead — role names are mutable and can be spoofed */
@@ -293,7 +289,7 @@ async function handleRequest(
     receivedAt: new Date().toISOString(),
   }
   await emitLifecycleEvent(applicationLifecycleEvents.requestReceived, receivedPayload)
-  const match = findApiRouteManifestMatch(apiRoutes, method, pathname)
+  const match = findApiRouteManifestMatch(getApiRouteManifests(), method, pathname)
   if (!match) {
     const response = NextResponse.json({ error: t('api.errors.notFound', 'Not Found') }, { status: 404 })
     await emitLifecycleEvent(applicationLifecycleEvents.requestNotFound, {

package/template/src/bootstrap.ts

@@ -29,7 +29,7 @@ registerAppDictionaryLoader(async (locale: Locale): Promise<Record<string, unkno
 })
 
 // modules.ts inline overrides (replace/disable any contract a module
-// presents — AI today, other domains rolling out per the unified spec).
+// presents through the unified modules.ts override surface).
 // Importing @open-mercato/ai-assistant here also runs the side-effect
 // that registers the AI domain applier with the umbrella dispatcher.
 import { enabledModules } from '@/modules'

package/template/src/components/BackendHeaderChrome.tsx

@@ -5,6 +5,7 @@ import Link from 'next/link'
 import * as React from 'react'
 import { MoreHorizontal, PlugZap, Settings, Mail } from 'lucide-react'
 import { hasFeature } from '@open-mercato/shared/security/features'
+import { AuthSessionGuard } from '@open-mercato/ui/backend/AuthSessionGuard'
 import { IconButton } from '@open-mercato/ui/primitives/icon-button'
 import { Popover, PopoverContent, PopoverTrigger } from '@open-mercato/ui/primitives/popover'
 import { IntegrationsButton } from '@open-mercato/ui/backend/IntegrationsButton'
@@ -37,6 +38,7 @@ const LazyMessagesIcon = dynamic(
 
 type BackendHeaderChromeProps = {
   email?: string
+  userId: string | null
   embeddingConfigured: boolean
   missingConfigMessage: string
   tenantId: string | null
@@ -102,6 +104,7 @@ function MobileMoreMenu({ items }: { items: MobileMoreItem[] }) {
 
 export function BackendHeaderChrome({
   email,
+  userId,
   embeddingConfigured,
   missingConfigMessage,
   tenantId,
@@ -160,6 +163,7 @@ export function BackendHeaderChrome({
 
   return (
     <>
+      <AuthSessionGuard serverUserId={userId} />
       {isReady && showAiAssistant ? (
         <AiAssistantShellIntegration tenantId={tenantId} organizationId={organizationId}>
           <LazyAiChatHeaderButton />

package/template/src/components/__tests__/BackendHeaderChrome.test.tsx

@@ -39,6 +39,10 @@ jest.mock('@open-mercato/ui/backend/SettingsButton', () => ({
   SettingsButton: () => <div data-testid="settings-button" />,
 }))
 
+jest.mock('@open-mercato/ui/backend/AuthSessionGuard', () => ({
+  AuthSessionGuard: () => <div data-testid="auth-session-guard" />,
+}))
+
 jest.mock('@/components/AiAssistantShellIntegration', () => ({
   AiAssistantShellIntegration: ({ children }: { children: React.ReactNode }) => <>{children}</>,
 }))
@@ -48,6 +52,7 @@ describe('BackendHeaderChrome', () => {
     const { container } = render(
       <BackendHeaderChrome
         email="demo@example.com"
+        userId="user-1"
         embeddingConfigured={false}
         missingConfigMessage=""
         tenantId={null}

package/template/src/modules/example/__integration__/TC-UMES-022-overrides.spec.ts

@@ -0,0 +1,21 @@
+import { test, expect } from '@playwright/test'
+
+function resolveUrl(path: string): string {
+  const baseUrl = process.env.BASE_URL?.trim()
+  return baseUrl ? `${baseUrl}${path}` : path
+}
+
+test.describe('TC-UMES-022: modules.ts overrides', () => {
+  test('routes.api override replaces the example override probe handler', async ({ request }) => {
+    const response = await request.get(resolveUrl('/api/example/override-probe'))
+
+    expect(response.ok(), `GET /api/example/override-probe returned ${response.status()}`).toBeTruthy()
+    const body = await response.json()
+    expect(body).toMatchObject({
+      ok: true,
+      source: 'modules.ts override',
+      route: 'example.override-probe',
+    })
+  })
+})
+

package/template/src/modules/example/api/override-probe/route.ts

@@ -0,0 +1,38 @@
+import { z } from 'zod'
+import type { OpenApiRouteDoc } from '@open-mercato/shared/lib/openapi'
+import { exampleTag } from '../openapi'
+
+export const metadata = {
+  GET: { requireAuth: false },
+}
+
+export async function GET() {
+  return Response.json({
+    ok: true,
+    source: 'base',
+    route: 'example.override-probe',
+  })
+}
+
+export const openApi: OpenApiRouteDoc = {
+  tag: exampleTag,
+  methods: {
+    GET: {
+      summary: 'Example override probe',
+      description: 'Returns a small payload used by integration tests to verify modules.ts API route overrides.',
+      tags: [exampleTag],
+      responses: [
+        {
+          status: 200,
+          description: 'Probe payload',
+          schema: z.object({
+            ok: z.boolean(),
+            source: z.string(),
+            route: z.string(),
+          }),
+        },
+      ],
+    },
+  },
+}
+

package/template/src/modules.ts

@@ -2,12 +2,13 @@
 // - id: module id (plural snake_case; special cases: 'auth')
 // - from: '@open-mercato/core' | '@app' | custom alias/path in future
 // - overrides: optional unified per-app override surface — replace or
-//   disable any contract a module presents. AI is wired today (Phase 1);
-//   other domains are stubbed and emit a one-shot warning if used.
+//   disable any contract a module presents: AI, routes, events, workers,
+//   widgets, notifications, interceptors, setup, ACL, DI, encryption, etc.
 //   See `.ai/specs/2026-05-04-modules-ts-unified-overrides.md` and
-//   `apps/docs/docs/framework/ai-assistant/overrides.mdx`.
+//   `apps/docs/docs/framework/modules/overrides.mdx`.
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import type { ModuleOverrides } from '@open-mercato/shared/modules/overrides'
+import { officialModuleEntries } from './official-modules.generated'
 
 export type ModuleEntry = {
   id: string
@@ -15,6 +16,52 @@ export type ModuleEntry = {
   overrides?: ModuleOverrides
 }
 
+/**
+ * Copyable examples for every wired `entry.overrides` domain.
+ *
+ * This object is intentionally not assigned to any enabled module. Use it as
+ * a reference when a downstream app needs to disable or replace contracts
+ * from a package-backed module without editing that module's source.
+ */
+export const moduleOverrideExamples: ModuleOverrides = {
+  ai: {
+    agents: { 'catalog.catalog_assistant': null },
+    tools: { inbox_ops_accept_action: null },
+  },
+  routes: {
+    api: { 'DELETE /api/example/items': null },
+    pages: { '/backend/example/reports': null },
+  },
+  events: {
+    subscribers: { 'example.todo.audit': null },
+  },
+  workers: { 'example:sync': null },
+  widgets: {
+    injection: { 'example.sidebar': null },
+    components: { 'page:/backend/example': null },
+    dashboard: { 'example.kpi': null },
+  },
+  notifications: {
+    types: { 'example.notice': null },
+    handlers: { 'example.notice.toast': null },
+  },
+  interceptors: { 'example.items.interceptor': null },
+  commandInterceptors: { 'example.command.interceptor': null },
+  enrichers: { 'example.items.enricher': null },
+  guards: { 'example.backend.guard': null },
+  cli: { 'example seed': null },
+  setup: {
+    seedExamples: false,
+  },
+  acl: {
+    features: { 'example.manage': null },
+  },
+  di: { exampleService: null },
+  encryption: {
+    maps: { 'example:item': null },
+  },
+}
+
 export const enabledModules: ModuleEntry[] = [
   { id: 'dashboards', from: '@open-mercato/core' },
   { id: 'auth', from: '@open-mercato/core' },
@@ -60,10 +107,33 @@ export const enabledModules: ModuleEntry[] = [
   { id: 'webhooks', from: '@open-mercato/webhooks' },
   { id: 'customer_accounts', from: '@open-mercato/core' },
   { id: 'portal', from: '@open-mercato/core' },
-  { id: 'example', from: '@app' },
+  {
+    id: 'example',
+    from: '@app',
+    overrides: {
+      routes: {
+        api: {
+          'GET /api/example/override-probe': {
+            handler: async () => Response.json({
+              ok: true,
+              source: 'modules.ts override',
+              route: 'example.override-probe',
+            }),
+            metadata: { requireAuth: false },
+          },
+        },
+      },
+    },
+  },
   { id: 'ratelimit_probe', from: '@app' },
 ]
 
+// Official modules activated via official-modules.json / official-modules.local.json
+// (managed by `yarn official-modules`; backed by the external/official-modules submodule).
+for (const entry of officialModuleEntries) {
+  if (!enabledModules.some((existing) => existing.id === entry.id)) enabledModules.push(entry)
+}
+
 if (enabledModules.some((entry) => entry.id === 'example')) {
   enabledModules.push({ id: 'example_customers_sync', from: '@app' })
 }

package/template/src/official-modules.generated.ts

@@ -0,0 +1,14 @@
+// AUTO-GENERATED — do not edit by hand.
+// Source: official-modules.json (+ official-modules.local.json override).
+// Regenerate with: yarn official-modules
+//
+// Why is this file in src/ and not under .mercato/generated/?
+// It is a *versioned* generated registry — the activation set must travel
+// with the repo and survive `yarn clean-generated`. Moving it under any
+// `generated/` folder would gitignore-and-wipe it. See
+// .ai/specs/2026-05-19-official-modules-generated-location-decision.md
+// and the "Generated Files: versioned vs ephemeral" section in AGENTS.md.
+import type { ModuleEntry } from './modules'
+
+export const officialModuleEntries: ModuleEntry[] = [
+]