create-mercato-app 0.5.1-develop.3036.f02c281f23 → 0.5.1-develop.3045.b4b3320cc2

package/README.md

@@ -36,6 +36,8 @@ npx create-mercato-app <app-name> [options]
 | `--app <name>` | Bootstrap an official Open Mercato ready app from `open-mercato/ready-app-<name>` |
 | `--app-url <url>` | Bootstrap a ready app from a GitHub repository URL |
 | `--skip-agentic-setup` | Skip the interactive agentic setup wizard |
+| `--init-git` | Initialize a local Git repository after scaffolding |
+| `--no-init-git` | Do not prompt for or initialize a local Git repository |
 | `--registry <url>` | Custom npm registry URL |
 | `--verdaccio` | Use local Verdaccio registry (http://localhost:4873) |
 | `--help`, `-h` | Show help |
@@ -61,6 +63,9 @@ npx create-mercato-app my-store --registry http://localhost:4873
 
 # Create a new app without the agentic setup wizard
 npx create-mercato-app my-store --skip-agentic-setup
+
+# Create a new app and initialize a local Git repository
+npx create-mercato-app my-store --init-git
 ```
 
 ## Ready App Behavior
@@ -73,6 +78,34 @@ npx create-mercato-app my-store --skip-agentic-setup
 - Imported ready apps skip the interactive agentic setup wizard; if you want agentic tooling later, run `yarn mercato agentic:init` inside the generated app
 - Imported ready apps must not contain `.template` files; the scaffold fails closed if template files are found
 
+## Git And GitHub
+
+Interactive scaffolds ask whether to initialize a local Git repository after the app is created. Non-interactive scaffolds skip Git initialization unless `--init-git` is passed.
+
+To publish the generated app to GitHub after creation:
+
+```bash
+cd my-app
+git add -A
+git commit -m "Initial commit"
+gh repo create --source=. --remote=origin --push
+```
+
+If you did not initialize Git during scaffolding, run this first:
+
+```bash
+git init -b main
+```
+
+Without GitHub CLI, create an empty repository on GitHub and connect it manually:
+
+```bash
+git remote add origin https://github.com/<owner>/<repo>.git
+git push -u origin main
+```
+
+The standalone dev splash also exposes a GitHub publishing panel after `yarn dev` when `gh` is installed.
+
 ## After Creating A Bare Scaffold
 
 1. Navigate to your app directory:

package/agentic/shared/AGENTS.md.template

@@ -152,7 +152,7 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 8. **After the user adds a new module, offer to trim classic mode.** A fresh `create-mercato-app` scaffold enables every built-in module (classic mode). Once the user has added their own custom module, the defaults are usually dead weight. **Ask the user** (via a short `AskUserQuestion`) whether they want to disable built-in modules that are not needed for their project. If they say yes, invoke the `trim-unused-modules` skill — do NOT hand-craft the slimdown inside the AGENTS.md reading flow. If they say no, preserve classic mode silently.
 
    **Dashboards fallback rule.** When the user (or the `trim-unused-modules` skill) disables the `dashboards` module, you MUST update `src/app/(backend)/backend/page.tsx` so it no longer renders `<DashboardScreen />`. Replace the dashboard render with a `redirect(...)` to the first enabled backend page for the current user — preferring pages already registered in the main sidebar group and respecting the admin/superadmin role of the caller. Otherwise `/backend` will crash at build or request time because the removed module no longer ships `DashboardScreen`. Always fall back to `/backend/profile` only if no other backend page is available.
-9. **New features MUST be visible to admin/superadmin immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin and superadmin roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls --all-tenants` so existing tenants pick up the new feature without a reinstall. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
+9. **New features MUST be visible to default roles immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin role and any other appropriate default roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls` so existing tenants pick up the new feature without a reinstall. Use `--tenant <tenantId>` only when the user asks to target one tenant. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
 10. **Strict Design System alignment for every UI change.** Any UI you add or edit MUST use the Open Mercato design system components and tokens. No hardcoded Tailwind status colors (`text-red-500`, `bg-green-100`, etc.) — use semantic tokens (`text-status-error-text`, `bg-status-success-bg`, …). No arbitrary text sizes (`text-[11px]`, `text-[13px]`) — use the Tailwind scale (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`) or the `text-overline` token for 11px uppercase labels. In PAGE BODY UI, use `lucide-react` icons (never inline `<svg>`). Use `StatusBadge` for entity status, `Alert` for inline feedback, `FormField` for standalone form inputs, `SectionHeader` for detail-page section headings, `CollapsibleSection` for collapsible regions, `LoadingMessage`/`Spinner`/`DataLoader` for async states, and `EmptyState` (or DataTable's `emptyState` prop) for empty lists. For list pages, follow `.ai/skills/backend-ui-design/SKILL.md` and prefer the `DataTable` host pattern shown there (`entityId`, `apiPath`, stable `extensionTableId`, and explicit pagination props when you own the data source). Every dialog MUST support `Cmd/Ctrl+Enter` to submit and `Escape` to cancel. Every icon-only button MUST have an `aria-label`. These rules apply to `src/modules/<module>/backend/**` and `src/modules/<module>/frontend/**` alike.
 11. **BEFORE writing ANY code**, you MUST:
    - Match your task against the **Task → Context Map** above

package/dist/agentic/shared/AGENTS.md.template

@@ -152,7 +152,7 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 8. **After the user adds a new module, offer to trim classic mode.** A fresh `create-mercato-app` scaffold enables every built-in module (classic mode). Once the user has added their own custom module, the defaults are usually dead weight. **Ask the user** (via a short `AskUserQuestion`) whether they want to disable built-in modules that are not needed for their project. If they say yes, invoke the `trim-unused-modules` skill — do NOT hand-craft the slimdown inside the AGENTS.md reading flow. If they say no, preserve classic mode silently.
 
    **Dashboards fallback rule.** When the user (or the `trim-unused-modules` skill) disables the `dashboards` module, you MUST update `src/app/(backend)/backend/page.tsx` so it no longer renders `<DashboardScreen />`. Replace the dashboard render with a `redirect(...)` to the first enabled backend page for the current user — preferring pages already registered in the main sidebar group and respecting the admin/superadmin role of the caller. Otherwise `/backend` will crash at build or request time because the removed module no longer ships `DashboardScreen`. Always fall back to `/backend/profile` only if no other backend page is available.
-9. **New features MUST be visible to admin/superadmin immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin and superadmin roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls --all-tenants` so existing tenants pick up the new feature without a reinstall. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
+9. **New features MUST be visible to default roles immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin role and any other appropriate default roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls` so existing tenants pick up the new feature without a reinstall. Use `--tenant <tenantId>` only when the user asks to target one tenant. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
 10. **Strict Design System alignment for every UI change.** Any UI you add or edit MUST use the Open Mercato design system components and tokens. No hardcoded Tailwind status colors (`text-red-500`, `bg-green-100`, etc.) — use semantic tokens (`text-status-error-text`, `bg-status-success-bg`, …). No arbitrary text sizes (`text-[11px]`, `text-[13px]`) — use the Tailwind scale (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`) or the `text-overline` token for 11px uppercase labels. In PAGE BODY UI, use `lucide-react` icons (never inline `<svg>`). Use `StatusBadge` for entity status, `Alert` for inline feedback, `FormField` for standalone form inputs, `SectionHeader` for detail-page section headings, `CollapsibleSection` for collapsible regions, `LoadingMessage`/`Spinner`/`DataLoader` for async states, and `EmptyState` (or DataTable's `emptyState` prop) for empty lists. For list pages, follow `.ai/skills/backend-ui-design/SKILL.md` and prefer the `DataTable` host pattern shown there (`entityId`, `apiPath`, stable `extensionTableId`, and explicit pagination props when you own the data source). Every dialog MUST support `Cmd/Ctrl+Enter` to submit and `Escape` to cancel. Every icon-only button MUST have an `aria-label`. These rules apply to `src/modules/<module>/backend/**` and `src/modules/<module>/frontend/**` alike.
 11. **BEFORE writing ANY code**, you MUST:
    - Match your task against the **Task → Context Map** above

package/dist/index.js

@@ -3,6 +3,7 @@
 
 // src/index.ts
 import { createInterface } from "node:readline";
+import { spawnSync } from "node:child_process";
 import { basename as basename2, dirname as dirname6, join as join7, resolve } from "node:path";
 import { existsSync as existsSync6, mkdirSync as mkdirSync6, readdirSync as readdirSync3, readFileSync as readFileSync6, statSync as statSync2, writeFileSync as writeFileSync7, copyFileSync as copyFileSync5 } from "node:fs";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
@@ -322,7 +323,11 @@ var EMPTY_MODULES = [
   { id: "configs", from: CORE },
   { id: "entities", from: CORE },
   { id: "query_index", from: CORE },
-  { id: "api_docs", from: CORE }
+  { id: "api_docs", from: CORE },
+  { id: "audit_logs", from: CORE },
+  { id: "notifications", from: CORE },
+  { id: "dashboards", from: CORE },
+  { id: "events", from: EVENTS }
 ];
 var STARTER_PRESETS = {
   classic: {
@@ -352,10 +357,7 @@ var STARTER_PRESETS = {
       add: [
         { id: "customers", from: CORE },
         { id: "dictionaries", from: CORE },
-        { id: "feature_toggles", from: CORE },
-        { id: "notifications", from: CORE },
-        { id: "dashboards", from: CORE },
-        { id: "events", from: EVENTS }
+        { id: "feature_toggles", from: CORE }
       ]
     },
     ui: { startPageVariant: "crm", hideDemoLinks: true },
@@ -845,7 +847,9 @@ ${pc.bold("Arguments:")}
 ${pc.bold("Options:")}
   --app <name>       Bootstrap an official ready app from open-mercato/ready-app-<name>
   --app-url <url>    Bootstrap a ready app from a GitHub repository URL
-  --preset <id>      Starter preset: classic (default), empty, or crm
+  --preset <id>      Starter preset: classic, empty, or crm (omit to choose interactively)
+  --init-git         Initialize a local Git repository after scaffolding
+  --no-init-git      Do not prompt for or initialize a local Git repository
   --skip-agentic-setup  Skip the interactive agentic setup wizard
   --registry <url>   Custom npm registry URL
   --verdaccio        Use local Verdaccio registry (http://localhost:4873)
@@ -854,8 +858,10 @@ ${pc.bold("Options:")}
 
 ${pc.bold("Examples:")}
   npx create-mercato-app my-store
+  npx create-mercato-app my-store --preset classic
   npx create-mercato-app my-store --preset empty
   npx create-mercato-app my-store --preset crm
+  npx create-mercato-app my-store --init-git
   npx create-mercato-app my-prm --app prm
   npx create-mercato-app my-marketplace --app-url https://github.com/some-agency/ready-app-marketplace
   npx create-mercato-app my-store --verdaccio
@@ -878,6 +884,7 @@ function parseArgs(args) {
     appUrl: void 0,
     preset: void 0,
     registry: void 0,
+    initGit: void 0,
     skipAgenticSetup: false,
     verdaccio: false,
     help: false,
@@ -892,6 +899,10 @@ function parseArgs(args) {
       options.version = true;
     } else if (arg === "--skip-agentic-setup") {
       options.skipAgenticSetup = true;
+    } else if (arg === "--init-git") {
+      options.initGit = true;
+    } else if (arg === "--no-init-git") {
+      options.initGit = false;
     } else if (arg === "--verdaccio") {
       options.verdaccio = true;
     } else if (arg === "--registry") {
@@ -912,6 +923,143 @@ function parseArgs(args) {
   }
   return { appName, options };
 }
+var PRESET_PROMPT_OPTIONS = [
+  { number: "1", id: "classic", label: "Classic     (default)", hint: "full demo-ready starter" },
+  { number: "2", id: "empty", label: "Empty", hint: "minimal builder-ready baseline" },
+  { number: "3", id: "crm", label: "CRM", hint: "minimal CRM starter" }
+];
+function normalizePresetAnswer(answer) {
+  const normalized = answer.trim().toLowerCase();
+  if (!normalized) return DEFAULT_PRESET_ID;
+  const selected = PRESET_PROMPT_OPTIONS.find((option) => option.number === normalized || option.id === normalized);
+  if (!selected) {
+    throw new Error(`Unknown preset "${answer}". Choose classic, empty, or crm.`);
+  }
+  return selected.id;
+}
+async function promptForStarterPreset(ask) {
+  console.log("");
+  console.log("\u{1F9E9}  Starter module setup");
+  console.log("");
+  console.log("   Which starter module set do you want?");
+  console.log("");
+  for (const option of PRESET_PROMPT_OPTIONS) {
+    console.log(`   ${option.number}. ${option.label} - ${option.hint}`);
+  }
+  console.log("");
+  while (true) {
+    const answer = await ask("   Enter number [1]: ");
+    try {
+      return normalizePresetAnswer(answer);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.log(pc.yellow(`   ${message}`));
+    }
+  }
+}
+async function resolveStarterPresetId(options, readyAppSource) {
+  if (options.preset) {
+    if (!VALID_PRESET_IDS.includes(options.preset)) {
+      throw new Error(`Unknown preset "${options.preset}". Valid presets: ${VALID_PRESET_IDS.join(", ")}`);
+    }
+    if (options.preset !== DEFAULT_PRESET_ID && readyAppSource) {
+      throw new Error(
+        `--preset ${options.preset} cannot be combined with --app or --app-url. Presets apply only to the built-in template.`
+      );
+    }
+    return options.preset;
+  }
+  if (readyAppSource) return DEFAULT_PRESET_ID;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    console.log(pc.dim(`No starter preset selected; using ${DEFAULT_PRESET_ID}.`));
+    console.log("");
+    return DEFAULT_PRESET_ID;
+  }
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (question) => new Promise((resolveAnswer) => rl.question(question, (answer) => resolveAnswer(answer.trim())));
+  try {
+    return await promptForStarterPreset(ask);
+  } finally {
+    rl.close();
+  }
+}
+function normalizeGitInitAnswer(answer) {
+  const normalized = answer.trim().toLowerCase();
+  if (!normalized) return true;
+  if (["y", "yes"].includes(normalized)) return true;
+  if (["n", "no"].includes(normalized)) return false;
+  throw new Error(`Unknown answer "${answer}". Choose yes or no.`);
+}
+async function promptForGitInitialization(ask) {
+  console.log("");
+  console.log("\u{1F331}  Git repository setup");
+  console.log("");
+  console.log("   Initialize a local Git repository now?");
+  console.log(pc.dim("   You can publish it to GitHub later with `gh repo create --source=. --remote=origin --push`."));
+  console.log("");
+  while (true) {
+    const answer = await ask("   Initialize Git repository? [Y/n]: ");
+    try {
+      return normalizeGitInitAnswer(answer);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.log(pc.yellow(`   ${message}`));
+    }
+  }
+}
+async function resolveGitInitialization(options) {
+  if (typeof options.initGit === "boolean") return options.initGit;
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (question) => new Promise((resolveAnswer) => rl.question(question, (answer) => resolveAnswer(answer.trim())));
+  try {
+    return await promptForGitInitialization(ask);
+  } finally {
+    rl.close();
+  }
+}
+function runGitCommand(targetDir, args) {
+  return spawnSync("git", args, {
+    cwd: targetDir,
+    encoding: "utf8",
+    stdio: ["ignore", "pipe", "pipe"],
+    shell: process.platform === "win32"
+  });
+}
+function initializeGitRepository(targetDir) {
+  if (existsSync6(join7(targetDir, ".git"))) {
+    return { status: "already-initialized" };
+  }
+  const initWithBranch = runGitCommand(targetDir, ["init", "-b", "main"]);
+  if (initWithBranch.status === 0) {
+    return { status: "initialized" };
+  }
+  const fallbackInit = runGitCommand(targetDir, ["init"]);
+  if (fallbackInit.status !== 0) {
+    const message = fallbackInit.stderr || initWithBranch.stderr || fallbackInit.stdout || initWithBranch.stdout;
+    return { status: "failed", message: message.trim() || "git init failed" };
+  }
+  const branchRename = runGitCommand(targetDir, ["branch", "-M", "main"]);
+  if (branchRename.status !== 0) {
+    const message = branchRename.stderr || branchRename.stdout;
+    return { status: "failed", message: message.trim() || "git branch -M main failed" };
+  }
+  return { status: "initialized" };
+}
+async function maybeInitializeGitRepository(targetDir, options) {
+  const shouldInitialize = await resolveGitInitialization(options);
+  if (!shouldInitialize) return { status: "skipped" };
+  const result = initializeGitRepository(targetDir);
+  if (result.status === "initialized") {
+    console.log(pc.green("Initialized local Git repository."));
+  } else if (result.status === "already-initialized") {
+    console.log(pc.dim("Git repository already initialized."));
+  } else if (result.status === "failed") {
+    console.log(pc.yellow(`Could not initialize Git repository: ${result.message}`));
+  }
+  console.log("");
+  return result;
+}
 function buildRegistryConfig(registryUrl) {
   let parsedRegistryUrl;
   try {
@@ -1047,6 +1195,22 @@ function printImportedReadyAppNextSteps(appName) {
   console.log(pc.dim("If you want agentic tooling in the imported app later, run `yarn mercato agentic:init` inside it."));
   console.log("");
 }
+function printGitHubSyncInstructions(gitResult) {
+  console.log("Optional GitHub publish:");
+  console.log("");
+  if (gitResult.status === "skipped" || gitResult.status === "failed") {
+    console.log(pc.cyan("  git init -b main"));
+  }
+  console.log(pc.cyan("  git add -A"));
+  console.log(pc.cyan('  git commit -m "Initial commit"'));
+  console.log(pc.dim("  # With GitHub CLI:"));
+  console.log(pc.cyan("  gh repo create --source=. --remote=origin --push"));
+  console.log(pc.dim("  # Or create an empty GitHub repo in the browser, then:"));
+  console.log(pc.cyan("  git remote add origin https://github.com/<owner>/<repo>.git"));
+  console.log(pc.cyan("  git push -u origin main"));
+  console.log(pc.dim("  # You can also publish from the standalone dev splash after `yarn dev`."));
+  console.log("");
+}
 async function main(argv = process.argv.slice(2)) {
   const { appName: appNameArg, options } = parseArgs(argv);
   if (options.help) {
@@ -1070,15 +1234,7 @@ async function main(argv = process.argv.slice(2)) {
     throw new Error(`Directory "${appName}" already exists`);
   }
   const readyAppSource = resolveReadyAppSource(options, PACKAGE_VERSION);
-  const presetId = options.preset ?? DEFAULT_PRESET_ID;
-  if (!VALID_PRESET_IDS.includes(presetId)) {
-    throw new Error(`Unknown preset "${presetId}". Valid presets: ${VALID_PRESET_IDS.join(", ")}`);
-  }
-  if (presetId !== DEFAULT_PRESET_ID && readyAppSource) {
-    throw new Error(
-      `--preset ${presetId} cannot be combined with --app or --app-url. Presets apply only to the built-in template.`
-    );
-  }
+  const presetId = await resolveStarterPresetId(options, readyAppSource);
   const registryConfig = options.verdaccio ? buildRegistryConfig("http://localhost:4873") : options.registry ? buildRegistryConfig(options.registry) : "";
   console.log("");
   console.log(pc.bold(`Creating a new Open Mercato app in ${pc.cyan(targetDir)}`));
@@ -1098,12 +1254,16 @@ async function main(argv = process.argv.slice(2)) {
   }
   console.log(pc.green("Success!") + ` Created ${pc.bold(appName)}`);
   console.log("");
+  if (!readyAppSource) {
+    await maybeRunAgenticSetup(targetDir, options.skipAgenticSetup);
+  }
+  const gitResult = await maybeInitializeGitRepository(targetDir, options);
   if (readyAppSource) {
     printImportedReadyAppNextSteps(appName);
   } else {
-    await maybeRunAgenticSetup(targetDir, options.skipAgenticSetup);
     printTemplateNextSteps(appName);
   }
+  printGitHubSyncInstructions(gitResult);
   console.log(pc.dim("For more information, visit https://github.com/open-mercato/open-mercato"));
   console.log("");
 }
@@ -1116,5 +1276,6 @@ if (isEntrypoint) {
   });
 }
 export {
-  main
+  main,
+  normalizePresetAnswer
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.5.1-develop.3036.f02c281f23",
+  "version": "0.5.1-develop.3045.b4b3320cc2",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

package/template/.ai/qa/tests/playwright.config.ts

@@ -13,7 +13,10 @@ const STATIC_TEST_IGNORES = [
   `${normalizePath(path.join(projectRoot, '.claude'))}/**`,
   `${normalizePath(path.join(projectRoot, '.codex'))}/**`,
 ];
-const discoveredSpecs = discoverIntegrationSpecFiles(projectRoot, path.join(projectRoot, '.ai', 'qa', 'tests'));
+// `.ai/qa/tests` is retained for the shared Playwright config only.
+// Executable specs must live in module-local `__integration__` folders.
+const disabledLegacyIntegrationRoot = path.join(projectRoot, '.ai', 'qa', 'tests', '__legacy_disabled__');
+const discoveredSpecs = discoverIntegrationSpecFiles(projectRoot, disabledLegacyIntegrationRoot);
 const discoveredSpecPaths = discoveredSpecs.map((entry) => entry.path);
 
 export default defineConfig({

package/template/.env.example

@@ -218,58 +218,81 @@ TENANT_DATA_ENCRYPTION_KEY=
 # VAULT_REQUEST_TIMEOUT_MS=1000
 
 # ============================================================================
-# Embedding Provider Configuration (for vector search)
+# AI Providers, OCR, and Vector Search
 # ============================================================================
-# Vector search requires ONE embedding provider to be configured.
-# Automatic vector indexing ships disabled by default in this example env.
-# Enable it by setting OM_DISABLE_VECTOR_SEARCH_AUTOINDEXING=false or removing this line,
-# then trigger a vector reindex from Settings > Search or the CLI.
+# New apps ship with AI providers disabled. Set the provider id plus its API
+# key below before using AI assistants, AI OCR, or vector embeddings.
+# Docs:
+# - AI Assistant: https://docs.openmercato.com/framework/ai-assistant/overview
+# - AI settings: https://docs.openmercato.com/framework/ai-assistant/settings
+# - Search/vector embeddings: https://docs.openmercato.com/user-guide/search
+
+# AI Assistant provider selection. Built-in ids: anthropic, google, openai,
+# deepinfra, groq, together, fireworks, azure, litellm, ollama.
+OPENCODE_PROVIDER=
+
+# Optional: override the selected assistant model.
+# Examples:
+#   anthropic/claude-sonnet-4-6-20260107
+#   openai/gpt-5-mini
+#   deepinfra/zai-org/GLM-5.1
+# OPENCODE_MODEL=
+
+# Native LLM providers. Leave blank until you intentionally configure one.
+# anthropic: set OPENCODE_PROVIDER=anthropic + ANTHROPIC_API_KEY
+ANTHROPIC_API_KEY=
+OPENCODE_ANTHROPIC_API_KEY=
+# openai: set OPENCODE_PROVIDER=openai + OPENAI_API_KEY
+OPENAI_API_KEY=
+OPENCODE_OPENAI_API_KEY=
+# google: set OPENCODE_PROVIDER=google + GOOGLE_GENERATIVE_AI_API_KEY
+GOOGLE_GENERATIVE_AI_API_KEY=
+OPENCODE_GOOGLE_API_KEY=
+
+# OpenAI-compatible LLM providers.
+# deepinfra/groq/together/fireworks: set OPENCODE_PROVIDER to the provider id
+# and fill the matching *_API_KEY below.
+DEEPINFRA_API_KEY=
+GROQ_API_KEY=
+TOGETHER_API_KEY=
+FIREWORKS_API_KEY=
+# azure/litellm/ollama: set OPENCODE_PROVIDER to the provider id and fill
+# the API key plus base URL when that backend requires one.
+AZURE_OPENAI_API_KEY=
+AZURE_OPENAI_BASE_URL=
+LITELLM_API_KEY=
+LITELLM_BASE_URL=
+OLLAMA_API_KEY=
+OLLAMA_BASE_URL=
+
+# Embedding-only providers for vector search.
+MISTRAL_API_KEY=
+COHERE_API_KEY=
+AWS_ACCESS_KEY_ID=
+AWS_SECRET_ACCESS_KEY=
+AWS_REGION=
+
+# Vector search automatic indexing ships disabled by default. After setting an
+# embedding provider key above, enable this and trigger a vector reindex from
+# Settings > Search or the CLI.
 OM_DISABLE_VECTOR_SEARCH_AUTOINDEXING=true
 # Legacy alias still supported: DISABLE_VECTOR_SEARCH_AUTOINDEXING=1
-# OpenAI is the default provider if no explicit configuration is set.
+# Optional request cap for embedding providers (default: 3000 ms).
+# VECTOR_EMBEDDING_TIMEOUT_MS=3000
 
-# OpenAI (default embedding provider)
-# Models: text-embedding-3-small (1536 dim), text-embedding-3-large (3072 dim)
-OPENAI_API_KEY=your_openai_api_key_here
-
-# Google Generative AI
-# Models: text-embedding-004 (768 dim), embedding-001 (768 dim)
-# GOOGLE_GENERATIVE_AI_API_KEY=
-
-# Mistral AI
-# Models: mistral-embed (1024 dim)
-# MISTRAL_API_KEY=
-
-# Cohere
-# Models: embed-english-v3.0 (1024 dim), embed-multilingual-v3.0 (1024 dim)
-# COHERE_API_KEY=
-
-# Amazon Bedrock
-# Models: amazon.titan-embed-text-v2:0 (1024 dim), cohere.embed-english-v3 (1024 dim)
-# AWS_ACCESS_KEY_ID=
-# AWS_SECRET_ACCESS_KEY=
-# AWS_REGION=us-east-1
-
-# Ollama (Local/Self-hosted)
-# Models: nomic-embed-text (768 dim), mxbai-embed-large (1024 dim), all-minilm (384 dim)
-# Default: http://localhost:11434 (no /api suffix needed)
-# OLLAMA_BASE_URL=http://localhost:11434
-
-# ============================================================================
-# OCR (Optical Character Recognition) Configuration
-# ============================================================================
-# Default OCR model for image and PDF text extraction (optional)
-# Falls back to 'gpt-4o' if not specified. Can be overridden per partition.
-# Supported models: gpt-4o, gpt-4o-mini
+# OCR model for image and PDF text extraction. OCR currently requires
+# OPENAI_API_KEY to be set above.
 OCR_MODEL=gpt-4o
-
-# Custom OCR prompt (optional, advanced)
-# Override the default prompt sent to the LLM for text extraction
 # OCR_DEFAULT_PROMPT="Extract all text content from this image..."
-
-# Enable/disable OCR for new partitions by default (default: true)
 # OPENMERCATO_DEFAULT_ATTACHMENT_OCR_ENABLED=true
 
+# Outbound request timeouts for the AI Assistant / OpenCode stack.
+# OPENCODE_REQUEST_TIMEOUT_MS=30000
+# OPENCODE_SSE_CONNECT_TIMEOUT_MS=15000
+# OPENCODE_SEND_MESSAGE_TIMEOUT_MS=
+# AI_API_REQUEST_TIMEOUT_MS=30000
+# AI_OPENAPI_FETCH_TIMEOUT_MS=10000
+
 # ============================================================================
 # Stripe Integration Preconfiguration
 # ============================================================================
@@ -360,28 +383,6 @@ OCR_MODEL=gpt-4o
 # OM_INTEGRATION_AKENEO_CATEGORIES_SETTINGS_JSON=
 # OM_INTEGRATION_AKENEO_ATTRIBUTES_SETTINGS_JSON=
 
-# ============================================================================
-# OpenCode AI Assistant Configuration
-# ============================================================================
-# OpenCode handles AI requests for the AI Assistant feature.
-# Configure the provider and set the corresponding API key.
-
-# Provider selection: anthropic, openai, or google (default: anthropic)
-OPENCODE_PROVIDER=anthropic
-
-# Optional: Override the default model for the selected provider
-# Default models by provider:
-#   - anthropic: claude-haiku-4-5-20251001
-#   - openai: gpt-4o-mini
-#   - google: gemini-2.0-flash
-# OPENCODE_MODEL=anthropic/claude-sonnet-4-20250514
-
-# Provider API keys (set the one matching OPENCODE_PROVIDER)
-# Both ANTHROPIC_API_KEY and OPENCODE_ANTHROPIC_API_KEY are accepted (same for other providers)
-ANTHROPIC_API_KEY=your_anthropic_api_key_here
-# OPENAI_API_KEY=your_openai_api_key_here
-# GOOGLE_GENERATIVE_AI_API_KEY=your_google_api_key_here
-
 # ============================================================================
 # InboxOps Configuration (email-to-ERP agent)
 # ============================================================================

package/template/AGENTS.md

@@ -205,6 +205,74 @@ Practical consequences:
   4. Re-apply (`yarn db:migrate`) and commit.
 - Never hand-edit historical migrations that have shipped; add a **new** migration that performs the correction instead.
 
+## AI Assistant — adding agents, tools, UI parts, and overrides
+
+Standalone apps consume the AI framework from `@open-mercato/ai-assistant` (in `node_modules/`). The same conventions used in the monorepo apply here:
+
+- Add a typed agent for a new module by creating `<module>/ai-agents.ts` + `<module>/ai-tools.ts` at the **module root**. Run `yarn generate` after.
+- Add inline UI widgets (record cards, custom server-emitted parts) per the [UI Parts guide](https://docs.openmercato.dev/framework/ai-assistant/ui-parts).
+- Replace or disable an agent / tool that another module shipped through three paths: extra `aiAgentOverrides` / `aiToolOverrides` exports on the existing `<module>/ai-agents.ts` / `<module>/ai-tools.ts` (per-module), inline on a `ModuleEntry` in `src/modules.ts` (per-app), or programmatically via `applyAiAgentOverrides({...})` / `applyAiToolOverrides({...})` from `@open-mercato/ai-assistant`. `null` disables; a definition replaces. Resolution order is **programmatic → modules.ts → file-based → base**.
+
+Example per-module override (preferred when the override should ship with a module):
+
+```ts
+// src/modules/<my_module>/ai-agents.ts
+import type {
+  AiAgentDefinition,
+  AiAgentOverridesMap,
+} from '@open-mercato/ai-assistant'
+import myAgent from './agents/my-merchandising-agent'
+
+export const aiAgents: AiAgentDefinition[] = [/* ...your module's own agents */]
+
+export const aiAgentOverrides: AiAgentOverridesMap = {
+  'catalog.merchandising_assistant': myAgent,  // replace
+  'catalog.catalog_assistant': null,           // disable
+}
+```
+
+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:
+
+```ts
+// src/modules.ts
+{
+  id: 'example',
+  from: '@app',
+  overrides: {
+    ai: {
+      agents: { 'catalog.catalog_assistant': null },
+      tools:  { 'inbox_ops_accept_action': null },
+    },
+  },
+},
+```
+
+The template's `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` from `@open-mercato/shared/modules/overrides` for you. Importing `@open-mercato/ai-assistant` (also in bootstrap) runs the side-effect that registers the AI domain applier with the dispatcher.
+
+Example programmatic override at boot (env-driven or test-only):
+
+```ts
+// src/bootstrap.ts (extra)
+import {
+  applyAiAgentOverrides,
+  applyAiToolOverrides,
+} from '@open-mercato/ai-assistant'
+
+// Disable an agent provided by the assistant module by default.
+applyAiAgentOverrides({ 'catalog.catalog_assistant': null })
+// Disable a default tool we do not use.
+applyAiToolOverrides({ 'inbox_ops_accept_action': null })
+```
+
+After editing any `aiAgentOverrides` / `aiToolOverrides` export:
+
+```bash
+yarn generate
+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.
+
 ## 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.
@@ -229,14 +297,14 @@ Do this in the same change where you disable the module — otherwise `/backend`
 
 Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also:
 
-1. **Add it to `defaultRoleFeatures`** in the same module's `setup.ts` so admin and superadmin roles receive it on every new tenant setup:
+1. **Add it to `defaultRoleFeatures`** in the same module's `setup.ts` so the admin role and any other appropriate default roles receive it on every new tenant setup:
 
    ```ts
    // src/modules/<module>/setup.ts
    export const setup = {
      defaultRoleFeatures: {
-       admin:      ['my_module.view', 'my_module.manage'],
-       superadmin: ['my_module.view', 'my_module.manage'],
+       admin: ['my_module.view', 'my_module.manage'],
+       employee: ['my_module.view'],
      },
      // ...
    }
@@ -245,10 +313,10 @@ Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`)
 2. **Reconcile existing tenants** by running the ACL sync command so existing installs pick up the new feature without a reinstall:
 
    ```bash
-   yarn mercato auth sync-role-acls --all-tenants
+   yarn mercato auth sync-role-acls
    ```
 
-Do this automatically unless the user has explicitly said otherwise. If the current user is an admin or superadmin, they should see the feature you just built — not stare at a blank admin because their role is missing the grant.
+Do this automatically unless the user has explicitly said otherwise. If the current user has a default role that should access the module, they should see the feature you just built — not stare at a blank admin because their role is missing the grant. Use `--tenant <tenantId>` only when the user asks to target one tenant.
 
 Feature IDs are FROZEN once shipped (they are stored in the DB as `role_features.feature_id`). If a rename is required, add the new ID, grant it, and keep the old one alongside as a deprecated alias until downstream data can be migrated.
 

package/template/package.json.template

@@ -101,7 +101,7 @@
     "tailwind-merge": "^3.4.0",
     "zod": "^4.1.13",
     "@stripe/react-stripe-js": "^6.2.0",
-    "@stripe/stripe-js": "^9.2.0",
+    "@stripe/stripe-js": "^9.3.1",
     "@open-mercato/gateway-stripe": "{{PACKAGE_VERSION}}",
     "@open-mercato/sync-akeneo": "{{PACKAGE_VERSION}}"
   },

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

@@ -10,7 +10,6 @@ import { APP_VERSION } from '@open-mercato/shared/lib/version'
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import { PageInjectionBoundary } from '@open-mercato/ui/backend/injection/PageInjectionBoundary'
 import { DemoFeedbackWidget } from '@/components/DemoFeedbackWidget'
-import OrganizationSwitcher from '@/components/OrganizationSwitcher'
 import { BackendHeaderChrome } from '@/components/BackendHeaderChrome'
 
 registerBackendRouteManifests(backendRoutes)
@@ -98,7 +97,6 @@ export default async function BackendLayout({
   return (
     <I18nProvider locale={locale} dict={dict}>
       <AppShell
-        key={path}
         productName={productName}
         email={auth?.email}
         groups={[]}
@@ -114,7 +112,6 @@ export default async function BackendLayout({
             organizationId={auth?.orgId ?? null}
           />
         )}
-        mobileSidebarSlot={<OrganizationSwitcher compact />}
         adminNavApi="/api/auth/admin/nav"
         version={APP_VERSION}
         settingsPathPrefixes={collectStaticSettingsPathPrefixes()}

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

@@ -1,5 +1,5 @@
 import { NextResponse, type NextRequest } from 'next/server'
-import { findApiRouteManifestMatch, registerBackendRouteManifests, registerFrontendRouteManifests, type HttpMethod } from '@open-mercato/shared/modules/registry'
+import { findApiRouteManifestMatch, registerApiRouteManifests, registerBackendRouteManifests, registerFrontendRouteManifests, 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'
@@ -11,6 +11,7 @@ import { bootstrap } from '@/bootstrap'
 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'

package/template/src/app/globals.css

@@ -545,6 +545,14 @@ body[data-column-chooser-open="true"] .om-demo-feedback-floating {
   display: none !important;
 }
 
+/* Hide floating demo feedback button while an AI chat (e.g. the merchandising
+   assistant sheet) is open — the FAB sits at z-[60] and otherwise overlaps
+   the chat composer's send button. The data attribute is set/cleared by the
+   shared <AiChat> component. */
+body[data-ai-chat-open="true"] .om-demo-feedback-floating {
+  display: none !important;
+}
+
 /* Hide native scrollbar while keeping scroll behavior — used by sticky sidebars */
 .scrollbar-hide {
   scrollbar-width: none;

package/template/src/bootstrap.ts

@@ -28,6 +28,16 @@ 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).
+// 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'
+import { applyModuleOverridesFromEnabledModules } from '@open-mercato/shared/modules/overrides'
+import '@open-mercato/ai-assistant'
+
+applyModuleOverridesFromEnabledModules(enabledModules)
+
 // Generated imports (static - works with bundlers)
 import { modules } from '@/.mercato/generated/modules.app.generated'
 import { entities } from '@/.mercato/generated/entities.generated'

package/template/src/components/BackendHeaderChrome.tsx

@@ -75,6 +75,10 @@ export function BackendHeaderChrome({
     () => hasVisibleRoute(payload?.groups, '/backend/messages'),
     [payload?.groups],
   )
+  const showNotifications = React.useMemo(
+    () => hasFeature(grantedFeatures, 'notifications.view'),
+    [grantedFeatures],
+  )
 
   return (
     <>
@@ -89,13 +93,11 @@ export function BackendHeaderChrome({
           missingConfigMessage={missingConfigMessage}
         />
       ) : null}
-      <div className="hidden lg:contents">
-        {isReady ? <LazyOrganizationSwitcher /> : null}
-      </div>
+      {isReady ? <LazyOrganizationSwitcher /> : null}
       {showIntegrationsButton ? <IntegrationsButton /> : null}
       <SettingsButton />
       <ProfileDropdown email={email} />
-      {isReady ? <LazyNotificationBellWrapper /> : null}
+      {isReady && showNotifications ? <LazyNotificationBellWrapper /> : null}
       {isReady && showMessages ? <LazyMessagesIcon /> : null}
     </>
   )

package/template/src/components/DemoFeedbackWidget.tsx

@@ -10,6 +10,7 @@ import { Input } from '@open-mercato/ui/primitives/input'
 import { Textarea } from '@open-mercato/ui/primitives/textarea'
 import { Checkbox } from '@open-mercato/ui/primitives/checkbox'
 import { Spinner } from '@open-mercato/ui/primitives/spinner'
+import { useAiDock } from '@open-mercato/ui/ai'
 import { apiCall } from '@open-mercato/ui/backend/utils/apiCall'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 
@@ -41,6 +42,8 @@ type SubmitState = 'idle' | 'sending' | 'sent' | 'error'
 
 export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boolean }) {
   const t = useT()
+  const aiDock = useAiDock()
+  const aiDockActive = Boolean(aiDock.state.assistant)
   const [open, setOpen] = useState(false)
   const [captionIndex, setCaptionIndex] = useState(0)
   const [mounted, setMounted] = useState(false)
@@ -91,9 +94,13 @@ export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boole
     return () => clearInterval(interval)
   }, [])
 
-  // Auto-popup after 30s inactivity (once per day, unless suppressed)
+  // Auto-popup after 30s inactivity (once per day, unless suppressed).
+  // Skip the inactivity prompt entirely while the AI dock is open — the
+  // operator is mid-conversation with an assistant and a popup would be
+  // disruptive on top of (or competing with) the dock surface.
   useEffect(() => {
     if (!demoModeEnabled || !mounted) return
+    if (aiDockActive) return
     if (getCookie(SUPPRESS_COOKIE) === '1') return
     if (getCookie(SHOWN_TODAY_COOKIE) === todayKey()) return
 
@@ -126,7 +133,7 @@ export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boole
       events.forEach((ev) => window.removeEventListener(ev, resetTimer))
       if (inactivityTimer.current) clearTimeout(inactivityTimer.current)
     }
-  }, [demoModeEnabled, mounted])
+  }, [demoModeEnabled, mounted, aiDockActive])
 
   const handleSubmit = useCallback(async () => {
     setFieldErrors({})
@@ -208,15 +215,22 @@ export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boole
   if (otherModalOpen && !open) return null
 
   // Brand-gradient floating CTA. Uses brand CSS vars (no hardcoded hex) +
-  // z-banner token (no z-[60]) so it stays DS-compliant while keeping the
-  // bespoke 135deg / 0-50-100 gradient that the marketing visual depends on
-  // (FancyButton's primary variant uses 161.7deg / 0-35.36-70.72 which
-  // truncates the violet-to-end transition and looks banded).
-  const floatingButton = (
+  // z-banner so it stays DS-compliant while keeping the bespoke 135deg /
+  // 0-50-100 gradient that the marketing visual depends on. The text is
+  // pinned to `text-black` because the gradient (lime → yellow → violet)
+  // is a fixed light surface in BOTH themes — `text-foreground` flips to
+  // near-white in dark mode and disappears against the pale gradient.
+  // Mirrors the `FancyButton` primitive's `text-white` precedent on its
+  // fixed dark gradient. The `om-demo-feedback-floating` class hooks into
+  // `body[data-ai-chat-open="true"] .om-demo-feedback-floating` in
+  // globals.css so the FAB hides while the AI dock surface is open
+  // (anchored on the right edge of the viewport); the same `aiDockActive`
+  // gate hides the FAB outright when the dock is mounted in this app shell.
+  const floatingButton = aiDockActive ? null : (
     <button
       type="button"
       onClick={() => { setOpen(true); if (submitState === 'sent') resetForm() }}
-      className="fixed bottom-6 right-6 z-banner flex items-center gap-2 rounded-full px-5 py-3 text-sm font-semibold text-foreground shadow-xl transition-all hover:scale-105 hover:shadow-2xl active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 animate-[subtle-bounce_2s_ease-in-out_infinite]"
+      className="om-demo-feedback-floating fixed bottom-6 right-6 z-banner flex items-center gap-2 rounded-full px-5 py-3 text-sm font-semibold text-black shadow-xl transition-all hover:scale-105 hover:shadow-2xl active:scale-95 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 animate-[subtle-bounce_2s_ease-in-out_infinite]"
       style={{
         backgroundImage: 'linear-gradient(135deg, var(--brand-lime, #B4F372) 0%, #EEFB63 50%, var(--brand-violet, #BC9AFF) 100%)',
       }}
@@ -234,7 +248,7 @@ export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boole
 
   return (
     <>
-      {createPortal(floatingButton, document.body)}
+      {floatingButton ? createPortal(floatingButton, document.body) : null}
       <Dialog open={open} onOpenChange={handleOpenChange}>
         <DialogContent className="sm:max-w-md" onKeyDown={handleKeyDown}>
           <DialogHeader className="items-center gap-3">
@@ -365,12 +379,15 @@ export function DemoFeedbackWidget({ demoModeEnabled }: { demoModeEnabled: boole
 
               <Button
                 type="button"
-                className="mt-1 w-full gap-2 text-foreground"
+                className="mt-1 w-full gap-2 text-black"
                 disabled={submitState === 'sending'}
                 onClick={handleSubmit}
                 style={{
                   // Same brand-gradient as the floating CTA (135deg / 0-50-100,
                   // brand vars instead of hex literals to satisfy DS rules).
+                  // Pin text to `text-black` — the gradient is a fixed light
+                  // surface in both themes; `text-foreground` would flip white
+                  // in dark mode and vanish against the pale gradient.
                   backgroundImage: 'linear-gradient(135deg, var(--brand-lime, #B4F372) 0%, #EEFB63 50%, var(--brand-violet, #BC9AFF) 100%)',
                 }}
               >

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

@@ -0,0 +1,66 @@
+/**
+ * @jest-environment jsdom
+ */
+
+import '@testing-library/jest-dom'
+import { render, screen } from '@testing-library/react'
+import { BackendHeaderChrome } from '../BackendHeaderChrome'
+
+jest.mock('next/dynamic', () => (loader: () => Promise<unknown>) => {
+  const source = loader.toString()
+  const isOrganizationSwitcher = source.includes('OrganizationSwitcher')
+  const Lazy = () =>
+    isOrganizationSwitcher ? (
+      <div data-testid="lazy-organization-switcher" />
+    ) : (
+      <div data-testid="lazy-other" />
+    )
+  return Lazy
+})
+
+jest.mock('@open-mercato/ui/backend/BackendChromeProvider', () => ({
+  useBackendChrome: () => ({ payload: { groups: [], grantedFeatures: [] }, isReady: true }),
+}))
+
+jest.mock('@open-mercato/ui/backend/IntegrationsButton', () => ({
+  IntegrationsButton: () => <div data-testid="integrations-button" />,
+}))
+
+jest.mock('@open-mercato/ui/backend/ProfileDropdown', () => ({
+  ProfileDropdown: () => <div data-testid="profile-dropdown" />,
+}))
+
+jest.mock('@open-mercato/ui/backend/SettingsButton', () => ({
+  SettingsButton: () => <div data-testid="settings-button" />,
+}))
+
+jest.mock('@/components/AiAssistantShellIntegration', () => ({
+  AiAssistantShellIntegration: ({ children }: { children: React.ReactNode }) => <>{children}</>,
+}))
+
+describe('BackendHeaderChrome', () => {
+  it('renders the organization switcher in the topbar without a viewport-gated wrapper', () => {
+    const { container } = render(
+      <BackendHeaderChrome
+        email="demo@example.com"
+        embeddingConfigured={false}
+        missingConfigMessage=""
+        tenantId={null}
+        organizationId={null}
+      />,
+    )
+
+    const switcher = screen.getByTestId('lazy-organization-switcher')
+    expect(switcher).toBeInTheDocument()
+
+    // Regression for issue #1795: the topbar OrganizationSwitcher must not be
+    // wrapped in a viewport-gated container that hides it at narrow widths.
+    // Previously `<div className="hidden lg:contents">` removed it below 1024px,
+    // which combined with `mobileSidebarSlot={<OrganizationSwitcher compact />}`
+    // caused the dropdown to reappear inside the mobile sidebar drawer.
+    const hiddenWrappers = container.querySelectorAll('.hidden')
+    for (const wrapper of Array.from(hiddenWrappers)) {
+      expect(wrapper.contains(switcher)).toBe(false)
+    }
+  })
+})

package/template/src/i18n/de.json

@@ -194,6 +194,8 @@
   "dashboard.action.done": "Fertig",
   "dashboard.addWidget": "Widget hinzufügen",
   "dashboard.empty.configurable": "Noch keine Widgets ausgewählt. Verwende \"Widget hinzufügen\", um dein Dashboard zu gestalten.",
+  "dashboard.empty.noWidgets.description": "Dashboard-Widgets erscheinen hier, sobald du das erste Modul hinzufügst, das sie bereitstellt.",
+  "dashboard.empty.noWidgets.title": "Noch keine Dashboard-Widgets",
   "dashboard.empty.readonly": "Für dein Konto sind noch keine Widgets verfügbar.",
   "dashboard.error.partial": "Einige Änderungen wurden nicht gespeichert",
   "dashboard.error.reload": "Daten neu laden",

package/template/src/i18n/en.json

@@ -194,6 +194,8 @@
   "dashboard.action.done": "Done",
   "dashboard.addWidget": "Add a widget",
   "dashboard.empty.configurable": "No widgets selected yet. Use \"Add a widget\" to start building your dashboard.",
+  "dashboard.empty.noWidgets.description": "Dashboard widgets will appear here after you add the first module that exposes them.",
+  "dashboard.empty.noWidgets.title": "No dashboard widgets yet",
   "dashboard.empty.readonly": "No widgets are available for your account yet.",
   "dashboard.error.partial": "Some changes were not saved",
   "dashboard.error.reload": "Reload data",

package/template/src/i18n/es.json

@@ -194,6 +194,8 @@
   "dashboard.action.done": "Listo",
   "dashboard.addWidget": "Agregar widget",
   "dashboard.empty.configurable": "Aún no has seleccionado widgets. Usa \"Agregar widget\" para construir tu panel.",
+  "dashboard.empty.noWidgets.description": "Los widgets del panel aparecerán aquí cuando agregues el primer módulo que los exponga.",
+  "dashboard.empty.noWidgets.title": "Aún no hay widgets del panel",
   "dashboard.empty.readonly": "Todavía no hay widgets disponibles para tu cuenta.",
   "dashboard.error.partial": "Algunos cambios no se guardaron",
   "dashboard.error.reload": "Recargar datos",

package/template/src/i18n/pl.json

@@ -194,6 +194,8 @@
   "dashboard.action.done": "Gotowe",
   "dashboard.addWidget": "Dodaj widżet",
   "dashboard.empty.configurable": "Nie wybrano jeszcze żadnych widżetów. Użyj \"Dodaj widżet\", aby zbudować pulpit.",
+  "dashboard.empty.noWidgets.description": "Widżety pulpitu pojawią się tutaj po dodaniu pierwszego modułu, który je udostępnia.",
+  "dashboard.empty.noWidgets.title": "Brak widżetów pulpitu",
   "dashboard.empty.readonly": "Brak dostępnych widżetów dla Twojego konta.",
   "dashboard.error.partial": "Niektóre zmiany nie zostały zapisane",
   "dashboard.error.reload": "Ponownie wczytaj dane",

package/template/src/modules.ts

@@ -1,9 +1,19 @@
 // Central place to enable modules and their source.
 // - 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.
+//   See `.ai/specs/2026-05-04-modules-ts-unified-overrides.md` and
+//   `apps/docs/docs/framework/ai-assistant/overrides.mdx`.
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
+import type { ModuleOverrides } from '@open-mercato/shared/modules/overrides'
 
-export type ModuleEntry = { id: string; from?: '@open-mercato/core' | '@app' | string }
+export type ModuleEntry = {
+  id: string
+  from?: '@open-mercato/core' | '@app' | string
+  overrides?: ModuleOverrides
+}
 
 export const enabledModules: ModuleEntry[] = [
   { id: 'dashboards', from: '@open-mercato/core' },