create-mercato-app 0.6.5-develop.5337.1.534b781eac → 0.6.5

package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md

@@ -39,7 +39,7 @@ When the developer reports a problem, follow this order:
 
 ### Step 2: Check Generated Files
 
-Run these commands first — they fix 60%+ of issues:
+These commands fix 60%+ of issues, so they are usually the first fix to propose (they are mutating — propose, then run after confirmation per [Step 4](#step-4-propose-before-fixing)):
 
 ```bash
 yarn generate          # Regenerate module discovery files
@@ -61,6 +61,28 @@ ls .mercato/generated/
 yarn typecheck
 ```
 
+### Step 4: Propose Before Fixing
+
+Once you have diagnosed the root cause, **do not apply the fix immediately**. First present:
+
+1. The **root cause** — what is actually broken and why.
+2. The **proposed fix** — the exact commands and/or code changes you intend to apply.
+
+Then **wait for explicit user confirmation** before applying any **mutating** change. This keeps the developer in control and avoids surprise edits, migrations, or restarts.
+
+**Read-only diagnostics may run without asking** — they only gather information and change nothing:
+
+| Allowed without confirmation (read-only) | Requires confirmation (mutating) |
+|------------------------------------------|----------------------------------|
+| `yarn typecheck` | `yarn generate` |
+| `grep` / file reads / `ls` | `yarn db:generate` |
+| log / browser-console inspection | `yarn db:migrate` |
+| `docker compose ps` | editing files |
+| `curl` against a running endpoint (GET) | restarting the dev server (`yarn dev`) |
+| | `docker compose up` |
+
+When in doubt about whether an action mutates state, treat it as mutating and ask first. Once the user confirms, apply the fix and verify it.
+
 ---
 
 ## 2. Module Issues
@@ -76,24 +98,24 @@ yarn typecheck
    // Must have this entry:
    { id: '<module_id>', from: '@app' }
    ```
-   Fix: Add the entry and run `yarn generate`.
+   Proposed fix: Add the entry and run `yarn generate`.
 
 2. **Did you run `yarn generate`?**
    Check if `.mercato/generated/` contains your module's entries.
-   Fix: Run `yarn generate`.
+   Proposed fix: Run `yarn generate`.
 
 3. **Is the module folder named correctly?**
    Must be plural, snake_case: `src/modules/<module_id>/`
-   Fix: Rename folder to match module ID.
+   Proposed fix: Rename folder to match module ID.
 
 4. **Does `index.ts` export `metadata`?**
    ```typescript
    export const metadata: ModuleInfo = { name: '<module_id>', ... }
    ```
-   Fix: Add the metadata export.
+   Proposed fix: Add the metadata export.
 
 5. **Is the dev server running with latest changes?**
-   Fix: Restart with `yarn dev`.
+   Proposed fix: Restart with `yarn dev`.
 
 ### Module loads but pages 404
 
@@ -104,17 +126,17 @@ yarn typecheck
 1. **Are backend page files in the right location?**
    - List page: `backend/page.tsx` (not `backend/index.tsx`)
    - Detail page: `backend/<entities>/[id].tsx` (bracket notation)
-   Fix: Rename to match auto-discovery convention.
+   Proposed fix: Rename to match auto-discovery convention.
 
 2. **Do pages export `metadata` with `requireAuth`?**
    ```typescript
    export const metadata = { requireAuth: true, features: ['<module_id>.view'] }
    ```
-   Fix: Add metadata export.
+   Proposed fix: Add metadata export.
 
 3. **Does the user have the required ACL features?**
    Check `setup.ts` has `defaultRoleFeatures` for the user's role.
-   Fix: Add features to role defaults, re-run setup.
+   Proposed fix: Add features to role defaults, re-run setup.
 
 ---
 
@@ -130,22 +152,22 @@ yarn typecheck
    ```bash
    yarn db:generate     # Probes/creates migration file
    ```
-   Fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
+   Proposed fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
 
 2. **Is the entity declared in the right file with the right imports?**
    Entity classes belong in `src/modules/<module_id>/data/entities.ts` and decorators must come from `@mikro-orm/decorators/legacy`.
-   Fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
+   Proposed fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
 
 3. **Did you apply the migration?**
    ```bash
    yarn db:migrate      # Applies pending migrations
    ```
-   Fix: Run `yarn db:migrate`.
+   Proposed fix: Run `yarn db:migrate`.
 
 4. **Is the migration file correct?**
    Check `src/modules/<module_id>/migrations/` for the latest migration.
    Verify it has the expected columns and types.
-   Fix: If wrong, delete the migration file, fix the entity, and regenerate.
+   Proposed fix: If wrong, delete the migration file, fix the entity, and regenerate.
 
 ### Migration generation creates unexpected changes
 
@@ -160,11 +182,11 @@ yarn typecheck
 
 2. **Did you modify a core module entity without ejecting?**
    Never edit `node_modules/@open-mercato/*`.
-   Fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
+   Proposed fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
 
 3. **Is a module snapshot stale?**
    Check whether the generated SQL recreates a table or column that already has a committed migration.
-   Fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
+   Proposed fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
 
 ### Entity changes not reflected
 
@@ -443,9 +465,10 @@ yarn dev               # 5. Restart dev server
 
 ## Rules
 
-- **ALWAYS** run `yarn generate` as first diagnostic step
+- **ALWAYS** present the diagnosed root cause and the proposed fix (commands/code), then **wait for explicit user confirmation before applying any mutating change** (see [Step 4](#step-4-propose-before-fixing)). Only read-only diagnostics may run without asking.
 - **ALWAYS** check server logs / browser console for actual error messages
 - **NEVER** edit files in `.mercato/generated/` or `node_modules/`
 - **NEVER** assume the issue — verify with actual error output
+- Treat `yarn generate` as the most likely first fix, but propose it before running — it regenerates files and is a mutating action
 - Fix the root cause, not the symptom — temporary workarounds become permanent bugs
-- When suggesting a fix, include the exact command or code change needed
+- When proposing a fix, include the exact command or code change needed

package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md

@@ -39,7 +39,7 @@ When the developer reports a problem, follow this order:
 
 ### Step 2: Check Generated Files
 
-Run these commands first — they fix 60%+ of issues:
+These commands fix 60%+ of issues, so they are usually the first fix to propose (they are mutating — propose, then run after confirmation per [Step 4](#step-4-propose-before-fixing)):
 
 ```bash
 yarn generate          # Regenerate module discovery files
@@ -61,6 +61,28 @@ ls .mercato/generated/
 yarn typecheck
 ```
 
+### Step 4: Propose Before Fixing
+
+Once you have diagnosed the root cause, **do not apply the fix immediately**. First present:
+
+1. The **root cause** — what is actually broken and why.
+2. The **proposed fix** — the exact commands and/or code changes you intend to apply.
+
+Then **wait for explicit user confirmation** before applying any **mutating** change. This keeps the developer in control and avoids surprise edits, migrations, or restarts.
+
+**Read-only diagnostics may run without asking** — they only gather information and change nothing:
+
+| Allowed without confirmation (read-only) | Requires confirmation (mutating) |
+|------------------------------------------|----------------------------------|
+| `yarn typecheck` | `yarn generate` |
+| `grep` / file reads / `ls` | `yarn db:generate` |
+| log / browser-console inspection | `yarn db:migrate` |
+| `docker compose ps` | editing files |
+| `curl` against a running endpoint (GET) | restarting the dev server (`yarn dev`) |
+| | `docker compose up` |
+
+When in doubt about whether an action mutates state, treat it as mutating and ask first. Once the user confirms, apply the fix and verify it.
+
 ---
 
 ## 2. Module Issues
@@ -76,24 +98,24 @@ yarn typecheck
    // Must have this entry:
    { id: '<module_id>', from: '@app' }
    ```
-   Fix: Add the entry and run `yarn generate`.
+   Proposed fix: Add the entry and run `yarn generate`.
 
 2. **Did you run `yarn generate`?**
    Check if `.mercato/generated/` contains your module's entries.
-   Fix: Run `yarn generate`.
+   Proposed fix: Run `yarn generate`.
 
 3. **Is the module folder named correctly?**
    Must be plural, snake_case: `src/modules/<module_id>/`
-   Fix: Rename folder to match module ID.
+   Proposed fix: Rename folder to match module ID.
 
 4. **Does `index.ts` export `metadata`?**
    ```typescript
    export const metadata: ModuleInfo = { name: '<module_id>', ... }
    ```
-   Fix: Add the metadata export.
+   Proposed fix: Add the metadata export.
 
 5. **Is the dev server running with latest changes?**
-   Fix: Restart with `yarn dev`.
+   Proposed fix: Restart with `yarn dev`.
 
 ### Module loads but pages 404
 
@@ -104,17 +126,17 @@ yarn typecheck
 1. **Are backend page files in the right location?**
    - List page: `backend/page.tsx` (not `backend/index.tsx`)
    - Detail page: `backend/<entities>/[id].tsx` (bracket notation)
-   Fix: Rename to match auto-discovery convention.
+   Proposed fix: Rename to match auto-discovery convention.
 
 2. **Do pages export `metadata` with `requireAuth`?**
    ```typescript
    export const metadata = { requireAuth: true, features: ['<module_id>.view'] }
    ```
-   Fix: Add metadata export.
+   Proposed fix: Add metadata export.
 
 3. **Does the user have the required ACL features?**
    Check `setup.ts` has `defaultRoleFeatures` for the user's role.
-   Fix: Add features to role defaults, re-run setup.
+   Proposed fix: Add features to role defaults, re-run setup.
 
 ---
 
@@ -130,22 +152,22 @@ yarn typecheck
    ```bash
    yarn db:generate     # Probes/creates migration file
    ```
-   Fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
+   Proposed fix: Run `yarn db:generate` to inspect the required migration, then keep only the scoped SQL for your module and update `src/modules/<module_id>/migrations/.snapshot-open-mercato.json`.
 
 2. **Is the entity declared in the right file with the right imports?**
    Entity classes belong in `src/modules/<module_id>/data/entities.ts` and decorators must come from `@mikro-orm/decorators/legacy`.
-   Fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
+   Proposed fix: move stale `entities/<Entity>.ts` patterns into `data/entities.ts` and fix the imports before regenerating the migration.
 
 3. **Did you apply the migration?**
    ```bash
    yarn db:migrate      # Applies pending migrations
    ```
-   Fix: Run `yarn db:migrate`.
+   Proposed fix: Run `yarn db:migrate`.
 
 4. **Is the migration file correct?**
    Check `src/modules/<module_id>/migrations/` for the latest migration.
    Verify it has the expected columns and types.
-   Fix: If wrong, delete the migration file, fix the entity, and regenerate.
+   Proposed fix: If wrong, delete the migration file, fix the entity, and regenerate.
 
 ### Migration generation creates unexpected changes
 
@@ -160,11 +182,11 @@ yarn typecheck
 
 2. **Did you modify a core module entity without ejecting?**
    Never edit `node_modules/@open-mercato/*`.
-   Fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
+   Proposed fix: Revert changes to node_modules. Use UMES extensions instead, or eject the module.
 
 3. **Is a module snapshot stale?**
    Check whether the generated SQL recreates a table or column that already has a committed migration.
-   Fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
+   Proposed fix: update that module's `migrations/.snapshot-open-mercato.json` to include the already-migrated schema, then re-run `yarn db:generate` and expect `no changes`.
 
 ### Entity changes not reflected
 
@@ -443,9 +465,10 @@ yarn dev               # 5. Restart dev server
 
 ## Rules
 
-- **ALWAYS** run `yarn generate` as first diagnostic step
+- **ALWAYS** present the diagnosed root cause and the proposed fix (commands/code), then **wait for explicit user confirmation before applying any mutating change** (see [Step 4](#step-4-propose-before-fixing)). Only read-only diagnostics may run without asking.
 - **ALWAYS** check server logs / browser console for actual error messages
 - **NEVER** edit files in `.mercato/generated/` or `node_modules/`
 - **NEVER** assume the issue — verify with actual error output
+- Treat `yarn generate` as the most likely first fix, but propose it before running — it regenerates files and is a mutating action
 - Fix the root cause, not the symptom — temporary workarounds become permanent bugs
-- When suggesting a fix, include the exact command or code change needed
+- When proposing a fix, include the exact command or code change needed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.5-develop.5337.1.534b781eac",
+  "version": "0.6.5",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",
@@ -21,8 +21,8 @@
     "tar": "^7.5.16"
   },
   "devDependencies": {
-    "@types/node": "^25.9.2",
-    "esbuild": "^0.28.0",
+    "@types/node": "^25.9.3",
+    "esbuild": "^0.28.1",
     "tsx": "^4.22.4",
     "typescript": "^6.0.3"
   },
@@ -41,6 +41,5 @@
     "scaffolding",
     "cli"
   ],
-  "license": "MIT",
-  "stableVersion": "0.6.4"
+  "license": "MIT"
 }

package/template/.env.example

@@ -30,6 +30,10 @@ NEXTAUTH_SECRET=
 APP_URL=http://localhost:3000
 # Additional trusted origins for app requests that must pass host validation.
 # APP_URL is required in production for security-sensitive email links.
+# In dev mode these values also govern the HMR WebSocket (/_next/webpack-hmr):
+# add your public/reverse-proxy/Tailscale host here so remote dev access works,
+# then restart the dev server. Non-allowlisted origins are still rejected.
+# In Docker dev, the value must also be forwarded into the app container.
 # Example: APP_ALLOWED_ORIGINS=https://admin.example.com,https://ops.example.com
 # APP_ALLOWED_ORIGINS=
 
@@ -190,6 +194,16 @@ CACHE_STRATEGY=sqlite
 # Default TTL in milliseconds (optional)
 CACHE_TTL=300000
 
+# Max entries retained by the in-memory cache strategy before LRU eviction
+# (default: 50000). Bounds memory for the process-wide cache singleton. A
+# non-positive value disables the cap (unbounded — not recommended).
+#CACHE_MEMORY_MAX_ENTRIES=50000
+
+# The cache service is shared process-wide (a singleton) so cross-request
+# caches actually hit. Set to off/false to fall back to a per-request cache
+# instance (legacy behavior). Default: on.
+#OM_CACHE_SINGLETON=on
+
 # Redis Configuration
 #REDIS_PORT=6379
 
@@ -208,12 +222,21 @@ DB_POOL_MIN=5
 DB_POOL_MAX=20
 DB_POOL_IDLE_TIMEOUT=30000
 DB_POOL_ACQUIRE_TIMEOUT=60000
+# Connection-pinning guards (milliseconds). idle_in_transaction defaults to 120000 in every
+# environment so a leaked open transaction cannot pin a pool connection forever; set to 0 to disable.
+#DB_IDLE_IN_TRANSACTION_TIMEOUT_MS=120000
+# Opt-in server-side timeouts. Unset = no timeout (legacy behavior). Set to cap runaway
+# queries / lock waits so they cannot exhaust the pool. Recommended in production.
+#DB_STATEMENT_TIMEOUT_MS=30000
+#DB_LOCK_TIMEOUT_MS=10000
 
 # Audit log retention windows
 # Core resources (users, roles) keep access history longer to support investigations.
 AUDIT_LOGS_CORE_RETENTION_DAYS=7
 # Non-core reads rotate aggressively to limit storage.
 AUDIT_LOGS_NON_CORE_RETENTION_HOURS=8
+# Minimum gap between retention sweeps per process. 0 rotates on every write.
+AUDIT_LOGS_ROTATE_INTERVAL_MS=60000
 
 # Tenant data encryption (enabled by default)
 TENANT_DATA_ENCRYPTION=yes
@@ -549,7 +572,7 @@ OCR_MODEL=gpt-4o
 # ============================================================================
 # Customer Portal Custom Domain (Phase 1–3)
 # ============================================================================
-# See .ai/specs/2026-04-08-portal-custom-domain-routing.md and
+# See .ai/specs/implemented/2026-04-08-portal-custom-domain-routing.md and
 # docker/traefik/README.md. Required when custom-domain mappings are in use.
 
 # Primary platform host — excluded from the Traefik domain-check middleware

package/template/.railwayignore

@@ -9,8 +9,8 @@ node_modules/
 coverage/
 test-results/
 playwright-report/
-storage/
-data/
+/storage/
+/data/
 *.db
 *.db-shm
 *.db-wal

package/template/AGENTS.md

@@ -316,7 +316,7 @@ export const aiAgentOverrides: AiAgentOverridesMap = {
 }
 ```
 
-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):
+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/implemented/2026-05-04-modules-ts-unified-overrides.md):
 
 ```ts
 // src/modules.ts

package/template/docker-compose.fullapp.dev.yml

@@ -38,6 +38,8 @@ services:
       DATABASE_URL: postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/${POSTGRES_DB:-open-mercato}
       JWT_SECRET: ${JWT_SECRET:-JWT}
       APP_URL: ${APP_URL:-http://localhost:3000}
+      # Additional trusted app/dev origins for the Open Mercato origin allowlist (resolveAllowedDevOrigins)
+      APP_ALLOWED_ORIGINS: ${APP_ALLOWED_ORIGINS:-}
       CACHE_REDIS_URL: redis://redis:6379
       CACHE_STRATEGY: ${CACHE_STRATEGY:-redis}
       ENABLE_CRUD_API_CACHE: ${ENABLE_CRUD_API_CACHE:-true}

package/template/docker-compose.fullapp.yml

@@ -40,6 +40,8 @@ services:
       DATABASE_URL: postgres://${POSTGRES_USER:-postgres}:${POSTGRES_PASSWORD:-postgres}@postgres:5432/${POSTGRES_DB:-open-mercato}
       JWT_SECRET: ${JWT_SECRET:-JWT}
       APP_URL: ${APP_URL:-http://localhost:3000}
+      # Additional trusted app/dev origins for the Open Mercato origin allowlist (resolveAllowedDevOrigins)
+      APP_ALLOWED_ORIGINS: ${APP_ALLOWED_ORIGINS:-}
       CACHE_REDIS_URL: redis://redis:6379
       CACHE_STRATEGY: ${CACHE_STRATEGY:-redis}
       ENABLE_CRUD_API_CACHE: ${ENABLE_CRUD_API_CACHE:-true}

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

@@ -139,7 +139,7 @@ function normalizeLoadedMetadata(
   return { [method]: metadata }
 }
 
-async function checkAuthorization(
+export async function checkAuthorization(
   methodMetadata: MethodMetadata | null,
   auth: AuthContext,
   req: NextRequest
@@ -167,24 +167,31 @@ async function checkAuthorization(
   }
 
   if (auth && requiresAuthentication) {
-    const rawTenantCandidate = await extractTenantCandidate(req)
-    if (rawTenantCandidate !== undefined) {
+    // HTTP parameter pollution hardening (issue #2665): a request can carry `tenantId`
+    // more than once — repeated `?tenantId=` query params, or in both the query string
+    // and the body. The dispatcher and downstream handlers may disagree on which
+    // occurrence wins (here historically `getAll().last`, handlers use `get()` first),
+    // so the authorization gate must validate EVERY distinct candidate. If any one
+    // targets a tenant the actor may not select, the request is rejected — making this
+    // decision binding regardless of how a handler later parses the same request.
+    const rawTenantCandidates = await extractTenantCandidates(req)
+    const actorTenant = normalizeTenantId(auth.tenantId ?? null) ?? null
+    const enforcedCandidates = new Set<string | null>()
+    for (const rawTenantCandidate of rawTenantCandidates) {
       const tenantCandidate = sanitizeTenantCandidate(rawTenantCandidate)
-      if (tenantCandidate !== undefined) {
-        const normalizedCandidate = normalizeTenantId(tenantCandidate) ?? null
-        const actorTenant = normalizeTenantId(auth.tenantId ?? null) ?? null
-        const tenantDiffers = normalizedCandidate !== actorTenant
-        if (tenantDiffers) {
-          try {
-            const guardContainer = await ensureContainer()
-            await enforceTenantSelection({ auth, container: guardContainer }, tenantCandidate)
-          } catch (error) {
-            if (isCrudHttpError(error)) {
-              return NextResponse.json(error.body ?? { error: t('api.errors.forbidden', 'Forbidden') }, { status: error.status })
-            }
-            throw error
-          }
+      if (tenantCandidate === undefined) continue
+      const normalizedCandidate = normalizeTenantId(tenantCandidate) ?? null
+      if (normalizedCandidate === actorTenant) continue
+      if (enforcedCandidates.has(normalizedCandidate)) continue
+      enforcedCandidates.add(normalizedCandidate)
+      try {
+        const guardContainer = await ensureContainer()
+        await enforceTenantSelection({ auth, container: guardContainer }, tenantCandidate)
+      } catch (error) {
+        if (isCrudHttpError(error)) {
+          return NextResponse.json(error.body ?? { error: t('api.errors.forbidden', 'Forbidden') }, { status: error.status })
         }
+        throw error
       }
     }
   }
@@ -248,17 +255,12 @@ function sanitizeTenantCandidate(candidate: unknown): unknown {
   return candidate
 }
 
-export async function extractTenantCandidate(req: NextRequest): Promise<unknown> {
-  const tenantParams = req.nextUrl?.searchParams?.getAll?.('tenantId') ?? []
-  if (tenantParams.length > 0) {
-    return tenantParams[tenantParams.length - 1]
-  }
-
+function bodyCarriesTenantId(req: NextRequest): boolean {
   const method = (req.method || 'GET').toUpperCase()
-  if (method === 'GET' || method === 'HEAD' || method === 'OPTIONS') {
-    return undefined
-  }
+  return method !== 'GET' && method !== 'HEAD' && method !== 'OPTIONS'
+}
 
+async function extractBodyTenantCandidate(req: NextRequest): Promise<unknown> {
   const rawContentType = req.headers.get('content-type')
   if (!rawContentType) return undefined
   const contentType = rawContentType.split(';')[0].trim().toLowerCase()
@@ -284,6 +286,35 @@ export async function extractTenantCandidate(req: NextRequest): Promise<unknown>
   return undefined
 }
 
+export async function extractTenantCandidate(req: NextRequest): Promise<unknown> {
+  const tenantParams = req.nextUrl?.searchParams?.getAll?.('tenantId') ?? []
+  if (tenantParams.length > 0) {
+    return tenantParams[tenantParams.length - 1]
+  }
+
+  if (!bodyCarriesTenantId(req)) {
+    return undefined
+  }
+
+  return extractBodyTenantCandidate(req)
+}
+
+// Returns every `tenantId` candidate the request carries — each repeated `?tenantId=`
+// query param plus any body-level value. The dispatcher enforces tenant selection
+// against all of them so a downstream handler that reads a different occurrence
+// (e.g. `searchParams.get()` first vs. `getAll()` last) cannot be tricked into using a
+// candidate that was never authorized (issue #2665).
+export async function extractTenantCandidates(req: NextRequest): Promise<unknown[]> {
+  const candidates: unknown[] = [...(req.nextUrl?.searchParams?.getAll?.('tenantId') ?? [])]
+
+  if (bodyCarriesTenantId(req)) {
+    const bodyCandidate = await extractBodyTenantCandidate(req)
+    if (bodyCandidate !== undefined) candidates.push(bodyCandidate)
+  }
+
+  return candidates
+}
+
 async function handleRequest(
   method: HttpMethod,
   req: NextRequest,

package/template/src/modules/example/api/todos/route.ts

@@ -1,6 +1,7 @@
 /* eslint-disable @typescript-eslint/no-explicit-any */
 import { z } from 'zod'
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
+import { escapeLikePattern } from '@open-mercato/shared/lib/db/escapeLikePattern'
 import { Todo } from '../../data/entities'
 
 const ENTITY_ID = 'example:todo' as const
@@ -105,7 +106,7 @@ export const { metadata, GET, POST, PUT, DELETE } = makeCrudRoute({
         if (ids.length > 0) F.id = { $in: ids }
       }
       if (q.id) F.id = q.id
-      if (q.title) F.title = { $ilike: `%${q.title}%` }
+      if (q.title) F.title = { $ilike: `%${escapeLikePattern(q.title)}%` }
       if (q.isDone !== undefined) F.is_done = q.isDone as any
       if (q.organizationId) F.organization_id = q.organizationId
       if (q.createdFrom || q.createdTo) {

package/template/src/modules/example/backend/payments/page.tsx

@@ -20,8 +20,6 @@ import {
   Ban,
   ArrowDownToLine,
   Undo2,
-  CheckCircle2,
-  AlertCircle,
   Info,
   Zap,
 } from 'lucide-react'
@@ -433,7 +431,6 @@ export default function PaymentGatewayDemoPage() {
           {/* Error Display */}
           {error && (
             <Alert variant="destructive">
-              <AlertCircle className="size-4" />
               <AlertTitle>{t('example.payments.error.title', 'Error')}</AlertTitle>
               <AlertDescription>{error}</AlertDescription>
             </Alert>
@@ -442,7 +439,6 @@ export default function PaymentGatewayDemoPage() {
           {/* Action Result */}
           {actionResult && (
             <Alert variant="success">
-              <CheckCircle2 className="size-4" />
               <AlertTitle>{t('example.payments.success.title', 'Success')}</AlertTitle>
               <AlertDescription>{actionResult}</AlertDescription>
             </Alert>

package/template/src/modules.ts

@@ -4,7 +4,7 @@
 // - overrides: optional unified per-app override surface — replace or
 //   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
+//   See `.ai/specs/implemented/2026-05-04-modules-ts-unified-overrides.md` and
 //   `apps/docs/docs/framework/modules/overrides.mdx`.
 import { parseBooleanWithDefault } from '@open-mercato/shared/lib/boolean'
 import type { ModuleOverrides } from '@open-mercato/shared/modules/overrides'