create-mercato-app 0.6.7-develop.6863.1.61001cf9a8 → 0.6.7

package/README.md

@@ -35,8 +35,6 @@ 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 |
-| `--preset <id>` | Select the `classic`, `empty`, or `crm` starter without prompting |
-| `--agents <list>` | Set up `claude-code`, `codex`, `cursor`, a comma-separated subset, `all`, or `none` without prompting |
 | `--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 |
@@ -66,12 +64,6 @@ 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 classic app with every supported AI coding-tool configuration
-npx create-mercato-app my-store --preset classic --agents all
-
-# Set up only Claude Code and Codex
-npx create-mercato-app my-store --agents claude-code,codex
-
 # Create a new app and initialize a local Git repository
 npx create-mercato-app my-store --init-git
 ```
@@ -84,72 +76,8 @@ npx create-mercato-app my-store --init-git
 - `--skip-agentic-setup` skips only the interactive agentic setup wizard
 - Imported ready apps are copied as raw source snapshots: the CLI does not rewrite dependency versions, package names, or application source files
 - Imported ready apps skip the interactive agentic setup wizard; if you want agentic tooling later, run `yarn mercato agentic:init` inside the generated app
-- `--agents` is only supported for bare scaffolds; use `yarn mercato agentic:init` after importing a ready app
 - Imported ready apps must not contain `.template` files; the scaffold fails closed if template files are found
 
-## Standalone AI Harness
-
-A bare scaffold can install a standalone-specific AI development harness for Claude Code, Codex, Cursor, or any selected subset. It combines a compact task router, module/task guides, local skills, an integrity-pinned subset of `open-mercato/skills`, exact installed-framework context, and a reproducible evaluation catalog.
-
-### Install or refresh skills
-
-Agentic setup attempts installation automatically. Re-run it after cloning, after an offline setup, or when selecting another tier:
-
-```bash
-yarn install-skills --list
-yarn install-skills
-yarn install-skills --with automation # opt in to loop/issue/release-maintenance workflows
-```
-
-The default is the 13 local core skills plus the 15-skill dependency-closed daily external tier. Advanced loop engines, issue authoring, and upgrade-note maintenance stay opt-in through `--with automation` (or `--all`). `.agents/skills/` is canonical; Claude Code receives compatibility links. The installer downloads the exact pinned `open-mercato/skills` archive, copies only individually hash-attested skill directories, and never executes archive or package-runner code. It activates the selected external set as one transaction: any failure restores the complete previous set before local installation continues. It preserves unknown user-owned skills and quarantines stale or modified installer-owned content.
-
-### Upgrade an existing generated harness
-
-After upgrading Open Mercato, refresh generated harness assets without overwriting local context:
-
-```bash
-yarn mercato agentic:init --update-harness
-```
-
-The ownership-aware update replaces unchanged generated files, recreates missing owned files, and refreshes the manifest atomically. Modified or unknown files remain in place; exact generated-path conflicts get an adjacent `.incoming` candidate. Managed paths are resolved below the canonical app root and a symlinked ancestor is rejected before publication. Use `--force` only when intentionally replacing known generated targets. External skill installation is a separate retryable phase, so offline installation does not roll back the harness update.
-
-### Resolve installed framework context
-
-Use the escape hatch when the routed guides do not contain an exact contract. It resolves the package versions selected by the app and their source/`AGENTS.md` chain without bulk-loading dependencies:
-
-```bash
-yarn framework:context --module customers --query makeCrudRoute
-yarn framework:context --package @open-mercato/ui --query CrudForm
-yarn framework:context --root
-```
-
-Bounded snapshots are written under ignored `.ai/framework-context/`; warnings make degraded dist/type-only context explicit.
-
-### Evaluate and maintain the harness
-
-Use deterministic checks during development:
-
-```bash
-yarn harness:validate --case OMH-009
-yarn harness:validate --family testing
-yarn harness:validate --all
-```
-
-`harness:validate --all` is the deterministic catalog gate, not the full release suite. Authenticated `--runner codex` / `--runner claude` live routing uses host filesystem containment on macOS (`sandbox-exec`) and Linux (Bubblewrap). The model gets no shell, process, environment, discovery, browser, or network tool: both CLIs receive only an evaluator-owned, `env -i` MCP server for exact-path reads and case-allowlisted writes. The selected app is intentionally readable through that narrow tool, so use a fresh or otherwise non-sensitive generated app. macOS `sandbox-exec` can enforce network-free lanes but cannot isolate loopback from the host; native macOS and Windows must use a contained Linux VM/container with Bubblewrap for the complete release gate.
-
-Run the full matrix once per Open Mercato release from a fresh scaffold:
-
-```bash
-yarn install-skills
-yarn harness:release --runner codex --prepare-targets /absolute/empty-release-targets --acknowledge-writes
-```
-
-The target directory must be absolute, new or empty, and outside the controller app. Select one blocking primary runner with `--runner codex` or `--runner claude`; it owns all 203 routing cases and every writable/review lane, with no per-case fallback. Optionally add the different authenticated runner through `--portability-runner` for the exact 46-case representative read-only lane. Omitting it is valid and recorded as not requested; once requested, its failures are blocking. Use a fresh, sanitized controller: automatic preparation fails before copying `.env`/`.env.*` local configuration (safe example/sample/template files remain allowed), credential files, or private-key files. The complete gate requires Linux with trusted system Bubblewrap (`bwrap`) and user namespaces because its Playwright API/browser lanes need a loopback namespace isolated from the host. Preflight rejects untrusted/no-op/pass-through executables and proves isolated loopback plus a capability-free payload before target preparation, provider invocation, or writes; native macOS and Windows therefore fail closed. The command also fails closed when a required runner, browser, or test runtime is unavailable. The 203-case catalog includes 93 framework-neutral business prompts and 46 writable implementation/regression cases (22.7%). The release command runs live routing, writable trusted oracles, per-target `generate`/`typecheck`/`lint`/`build`, any declared generated test, and isolated generated-code review for every writable result. Foundation and target validation—including `yarn build`—receive a minimal environment with network access denied, and persisted diagnostics redact sensitive environment values and URL userinfo. Test-authoring coverage executes a Jest unit test plus Linux/Bubblewrap loopback-only Playwright API and browser tests through fixed controller-owned commands against a read-only target; runtime reports must attest at least one passed test and zero skipped, todo, focused, flaky, or expected-failure tests. The suite then writes a schema-valid sanitized mode-`0600` report under `.ai/harness/results/` with the selected primary and optional portability runner policy.
-
-Use the bundled `om-evolve-harness` skill to add a real case: reproduce failure first, select one smallest knowledge owner, run any generated unit/integration tests plus target checks, require code review, and finish with the full release suite. Open Mercato framework maintainers use the monorepo-only `$om-refresh-standalone-harness --from <ref> --to <ref>` workflow for every release range and retain its sanitized maintenance report.
-
-For normal app changes, describe the business outcome directly or use the installed spec workflow for multi-phase work. Before handoff, run `yarn generate`, the smallest affected unit/integration tests, `yarn typecheck`, `yarn lint`, and `yarn build` as appropriate; applying migrations still requires explicit approval.
-
 ## 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.

package/agentic/claude-code/hooks/entity-migration-check.ts

@@ -1,65 +1,121 @@
-/** Remind Claude Code to generate and review a schema diff after entity edits. */
+/**
+ * Claude Code PostToolUse hook: entity-migration-check
+ *
+ * Fires after Write/Edit/MultiEdit. Detects entity file modifications
+ * without an accompanying migration and blocks the agent with a reminder.
+ *
+ * Three-state logic:
+ * 1. Migration file was written → exit 0 (agent is already on it)
+ * 2. Not an entity file → exit 0 (not relevant)
+ * 3. Entity written, no fresh migration → block with migration instructions
+ */
+
 import { readdirSync, statSync } from 'node:fs'
 import { join, relative } from 'node:path'
 
-const ENTITY_PATTERN = /^src\/modules\/([^/]+)\/data\/entities\.ts$/
-const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/[^/]+\.ts$/
+const ENTITY_PATTERN = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
+const MIGRATION_PATTERN = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
 
 interface PostToolUseInput {
-  tool_input?: { file_path?: string }
-}
-
-function projectDir(): string {
-  return process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  tool_input?: {
+    file_path?: string
+    content?: string
+  }
+  tool_name?: string
 }
 
-function normalizedRelative(filePath: string): string {
-  const value = filePath.startsWith('/') ? relative(projectDir(), filePath) : filePath
-  return value.replaceAll('\\', '/')
+function getRelativePath(filePath: string): string {
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  if (filePath.startsWith('/')) {
+    return relative(projectDir, filePath)
+  }
+  return filePath
 }
 
 function hasFreshMigration(moduleId: string): boolean {
-  const migrationsDir = join(projectDir(), 'src', 'modules', moduleId, 'migrations')
+  const projectDir = process.env.CLAUDE_PROJECT_DIR || process.cwd()
+  const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
+
   try {
-    const cutoff = Date.now() - 30_000
-    return readdirSync(migrationsDir).some((file) =>
-      file.endsWith('.ts') && statSync(join(migrationsDir, file)).mtimeMs > cutoff,
-    )
+    const files = readdirSync(migrationsDir)
+    const now = Date.now()
+    const thirtySecondsAgo = now - 30_000
+
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue
+      const stat = statSync(join(migrationsDir, file))
+      if (stat.mtimeMs > thirtySecondsAgo) {
+        return true
+      }
+    }
   } catch {
-    return false
+    // migrations directory doesn't exist yet — that's fine
   }
+
+  return false
 }
 
 async function main(): Promise<void> {
   let input = ''
-  for await (const chunk of process.stdin) input += chunk
-  if (!input.trim()) return
+  for await (const chunk of process.stdin) {
+    input += chunk
+  }
+
+  if (!input.trim()) {
+    process.exit(0)
+  }
 
   let data: PostToolUseInput
   try {
     data = JSON.parse(input)
   } catch {
-    return
+    process.exit(0)
   }
 
   const filePath = data.tool_input?.file_path
-  if (!filePath) return
-  const rel = normalizedRelative(filePath)
-  if (MIGRATION_PATTERN.test(rel)) return
+  if (!filePath) {
+    process.exit(0)
+  }
 
-  const match = rel.match(ENTITY_PATTERN)
-  if (!match || hasFreshMigration(match[1])) return
+  const rel = getRelativePath(filePath)
 
-  process.stdout.write(JSON.stringify({
+  // State 1: Migration file was written → agent is already handling it
+  if (MIGRATION_PATTERN.test(rel)) {
+    process.exit(0)
+  }
+
+  // State 2: Not an entity file → not relevant
+  const entityMatch = rel.match(ENTITY_PATTERN)
+  if (!entityMatch) {
+    process.exit(0)
+  }
+
+  const moduleId = entityMatch[1]
+
+  // State 3: Entity written — check for fresh migration
+  if (hasFreshMigration(moduleId)) {
+    process.exit(0)
+  }
+
+  // Block: entity modified without migration
+  const result = {
     decision: 'block',
     reason: [
-      `Entity contract changed: ${rel}`,
+      `Entity file modified: ${rel}`,
+      '',
+      `Affected module: ${moduleId}`,
+      '',
+      'A database migration is likely needed. Ask the user whether to run:',
+      '  yarn db:generate',
       '',
-      'Run `yarn db:generate` as a schema-diff probe and review only the scoped migration plus module snapshot.',
-      'Run `yarn generate` when discovery changed.',
-      'Do not apply the migration with `yarn db:migrate` without explicit user approval.',
+      'Then regenerate registries:',
+      '  yarn generate',
+      '',
+      'Do NOT run migrations automatically — always confirm with the user first.',
     ].join('\n'),
-  }))
+  }
+
+  process.stdout.write(JSON.stringify(result))
 }
 
-void main()
+main()

package/agentic/codex/enforcement-rules.md

@@ -1,6 +1,20 @@
 <!-- CODEX_ENFORCEMENT_RULES_START -->
-## Codex enforcement
+## CRITICAL rules — always follow without exception
 
-Read and route through the rest of this file; its `Always`, `Never`, and Task Router sections are the authority for Codex too. They are stated once below rather than duplicated here, so this prelude costs the router no budget.
+1. **After editing any entity file** (`src/modules/<id>/entities/*.ts`):
+   - STOP immediately before any further action
+   - Tell the user: "I modified an entity in module <id>. Should I create a migration?"
+   - If yes: run `yarn mercato db generate`
+   - Show the generated migration to the user before applying
+   - Ask for confirmation, then run `yarn mercato db migrate`
+   - Run `yarn generate` after migration is applied
 
+2. **After editing `src/modules.ts`**: immediately run `yarn generate`
+
+3. **Never edit `.mercato/generated/*`**: edit the source and run `yarn generate` instead
+
+4. **Before significant features**: check `.ai/specs/` for an existing spec.
+   If none exists, ask the user whether to create one first.
+
+---
 <!-- CODEX_ENFORCEMENT_RULES_END -->

package/agentic/cursor/hooks/entity-migration-check.mjs

@@ -1,38 +1,69 @@
-/** Remind Cursor to generate and review a schema diff after entity edits. */
+/**
+ * Cursor afterFileEdit hook: entity-migration-check
+ *
+ * Detects entity file modifications without an accompanying migration
+ * and exits non-zero to block the agent with a reminder.
+ *
+ * Three-state logic:
+ * 1. Migration file was written → exit 0 (agent is already on it)
+ * 2. Not an entity file → exit 0 (not relevant)
+ * 3. Entity written, no fresh migration → exit 1 with warning
+ */
+
 import { readdirSync, statSync } from 'node:fs'
-import { join, relative, resolve } from 'node:path'
+import { join, resolve } from 'node:path'
 
-const ENTITY_RE = /^src\/modules\/([^/]+)\/data\/entities\.ts$/
-const MIGRATION_RE = /^src\/modules\/([^/]+)\/migrations\/[^/]+\.ts$/
+const ENTITY_RE = /^src\/modules\/([^/]+)\/entities\/.*\.ts$/
+const MIGRATION_RE = /^src\/modules\/([^/]+)\/migrations\/.*\.ts$/
 
 function hasFreshMigration(projectDir, moduleId) {
   const migrationsDir = join(projectDir, 'src', 'modules', moduleId, 'migrations')
   try {
+    const files = readdirSync(migrationsDir)
     const cutoff = Date.now() - 30_000
-    return readdirSync(migrationsDir).some((file) =>
-      file.endsWith('.ts') && statSync(join(migrationsDir, file)).mtimeMs > cutoff,
-    )
+    for (const file of files) {
+      if (!file.endsWith('.ts')) continue
+      const stat = statSync(join(migrationsDir, file))
+      if (stat.mtimeMs > cutoff) return true
+    }
   } catch {
-    return false
+    // migrations directory doesn't exist yet
   }
+  return false
 }
 
 const filePath = process.argv[2]
 if (!filePath) process.exit(0)
 
 const projectDir = resolve('.')
-const rel = (filePath.startsWith('/') ? relative(projectDir, filePath) : filePath).replaceAll('\\', '/')
+const rel = filePath.startsWith('/') ? filePath.slice(projectDir.length + 1) : filePath
+
+// State 1: Migration file written
 if (MIGRATION_RE.test(rel)) process.exit(0)
 
+// State 2: Not an entity file
 const match = rel.match(ENTITY_RE)
-if (!match || hasFreshMigration(projectDir, match[1])) process.exit(0)
-
-process.stderr.write([
-  `Entity contract changed: ${rel}`,
-  '',
-  'Run `yarn db:generate` as a schema-diff probe and review only the scoped migration plus module snapshot.',
-  'Run `yarn generate` when discovery changed.',
-  'Do not apply the migration with `yarn db:migrate` without explicit user approval.',
-  '',
-].join('\n'))
+if (!match) process.exit(0)
+
+const moduleId = match[1]
+
+// State 3: Entity file without fresh migration
+if (hasFreshMigration(projectDir, moduleId)) process.exit(0)
+
+process.stderr.write(
+  [
+    `Entity file modified: ${rel}`,
+    '',
+    `Affected module: ${moduleId}`,
+    '',
+    'A database migration is likely needed. Ask the user whether to run:',
+    '  yarn db:generate',
+    '',
+    'Then regenerate registries:',
+    '  yarn generate',
+    '',
+    'Do NOT run migrations automatically — always confirm with the user first.',
+    '',
+  ].join('\n'),
+)
 process.exit(1)

package/agentic/cursor/rules/entity-guard.mdc

@@ -1,17 +1,29 @@
 ---
-description: Entity schema-diff guard for the canonical standalone entity file
+description: Entity modification guard — triggers migration workflow
 globs:
-  - src/modules/*/data/entities.ts
+  - src/modules/*/entities/**/*.ts
 alwaysApply: false
 ---
 
-# Entity Schema Change
+# Entity Modification — Migration Required
 
-Follow root `AGENTS.md` and `om-data-model-design`:
+You are editing an entity file. After saving, you MUST:
 
-1. Run `yarn db:generate` as a schema-diff probe.
-2. Review and keep only scoped migration SQL plus the touched module snapshot.
-3. Run `yarn generate` when discovery changed.
-4. Ask before applying with `yarn db:migrate`.
+1. **Create a migration** — ask the user before running:
+   ```
+   yarn db:generate
+   ```
 
-Never edit a shipped migration or generated registry.
+2. **Show the migration** to the user and wait for confirmation before applying
+
+3. **Apply the migration** (only after user confirms):
+   ```
+   yarn db:migrate
+   ```
+
+4. **Regenerate registries**:
+   ```
+   yarn generate
+   ```
+
+Do NOT skip any step. Do NOT run migrations without user confirmation.

package/agentic/cursor/rules/generated-guard.mdc

@@ -1,10 +1,12 @@
 ---
-description: Prevent edits to generated application registries
+description: Prevent editing auto-generated files
 globs:
   - .mercato/generated/**
 alwaysApply: false
 ---
 
-# Generated File
+# NEVER Edit Generated Files
 
-Do not edit this file. Change the app module source and run `yarn generate`; follow root `AGENTS.md` for the routed contract.
+This file is auto-generated by `yarn generate`. Any manual edits will be overwritten.
+
+To change generated output, edit the source modules in `src/modules/` and run `yarn generate`.

package/agentic/cursor/rules/open-mercato.mdc

@@ -1,8 +1,34 @@
 ---
-description: Route every standalone app task through the root agent rules
+description: Core Open Mercato conventions for standalone app development
 alwaysApply: true
 ---
 
-# {{PROJECT_NAME}} — Cursor Entry Point
+# {{PROJECT_NAME}} — Project Rules
 
-Read `AGENTS.md`, match every applicable Task Router row, and load only the routed guides, skills, and module facts. The root file owns architecture, safety, writable paths, migrations, generation, and validation; do not duplicate or override it here.
+## What this project is
+
+A standalone Open Mercato application. Build domain features ON TOP of the framework.
+To customise a core module beyond the extension system: `yarn mercato eject <module>`.
+Never edit node_modules/@open-mercato/* directly.
+
+## Task routing
+
+Read AGENTS.md before starting any task — it maps task types to the minimum files to load.
+
+## Module system
+
+Modules in `src/modules/<id>/`. Register with `from: '@app'` in `src/modules.ts`.
+Run `yarn generate` after any module or entity change. Never edit `.mercato/generated/*`.
+
+## Entity and migration rule
+
+After editing any entity in `src/modules/<id>/entities/`:
+1. Create migration: `yarn db:generate`
+2. Show migration to user, confirm before applying
+3. Apply: `yarn db:migrate`
+4. Regenerate: `yarn generate`
+
+## Spec-driven development
+
+Check `.ai/specs/` before any significant feature. If no spec exists, ask the user
+whether to create one first.

package/agentic/guides/module-system.md

@@ -1,15 +1,130 @@
-# Module System Compatibility Router
+# Open Mercato Module System — Conceptual Guide
 
-Use the concern guides below. This path remains only so older prompts and links do not load a stale module tutorial.
+This is the **hand-written, conceptual** layer of the module guides. It explains how an Open Mercato module is structured and how to build or extend one — the timeless concepts that rarely change. It is framework-wide; it does **not** describe any single module's data.
 
-| When you need | Load |
+## How the guides are layered
+
+- **Layer 1 — this file (`.ai/guides/module-system.md`):** conceptual and framework-wide. Module anatomy, auto-discovery, naming, the mandatory mechanisms, data-integrity rules, and the generate/migration workflow.
+- **Layer 2 — generated per-module fact-sheets (`.ai/guides/modules/<module>.md` + `.ai/guides/module-facts.json`):** the concrete **facts** for one module, extracted from its source — entity IDs, events, ACL features, API routes with per-method auth, DI service tokens, searchable entities, host extension tokens, notifications, and CLI commands. These are generated; never hand-write them here.
+- **Package guides (`.ai/guides/core.md`, `ui.md`, `shared.md`, …):** package-specific depth (patterns, helpers, deeper APIs).
+
+When you need a concrete fact about a specific module — which events it emits, its entity IDs, which feature gates a route — open that module's fact-sheet. Do not infer module facts from this conceptual guide.
+
+## Module anatomy
+
+Each module lives in `src/modules/<id>/` and is **auto-discovered**. The only registration is one entry in `src/modules.ts` (`{ id: '<id>', from: '@app' }`). Run `yarn generate` after adding or changing any auto-discovered file.
+
+```
+src/modules/<id>/
+├── index.ts                # Module metadata
+├── data/
+│   ├── entities.ts         # MikroORM entity classes (decorators from @mikro-orm/decorators/legacy)
+│   ├── validators.ts       # Zod validation schemas
+│   ├── extensions.ts       # Cross-module entity links (export `extensions`)
+│   └── enrichers.ts        # Response enrichers (export `enrichers`)
+├── api/
+│   ├── <resource>/route.ts # REST handlers (auto-discovered by method) + `metadata` + `openApi`
+│   └── interceptors.ts     # API route interception hooks (export `interceptors`)
+├── backend/                # Admin UI pages (auto-discovered) + paired `page.meta.ts`
+├── frontend/               # Public pages (auto-discovered); customer portal under `[orgSlug]/portal/`
+├── subscribers/            # Event handlers (export `metadata` + default handler)
+├── workers/                # Background jobs (export `metadata` + default handler)
+├── widgets/
+│   ├── injection/          # UI widgets injected into other modules
+│   ├── injection-table.ts  # Widget-to-slot mappings
+│   └── components.ts        # Component replacement/wrapper definitions (export `componentOverrides`)
+├── di.ts                   # Awilix DI registrations (export `register(container)`)
+├── acl.ts                  # Permission features (export `features`)
+├── setup.ts                # Tenant init, role features, seed data (export `setup`)
+├── events.ts               # Typed event declarations (export `eventsConfig`)
+├── search.ts               # Search indexing configuration (export `searchConfig`)
+├── ce.ts                   # Custom entities / custom field sets (export `entities`)
+├── translations.ts         # Translatable fields per entity
+├── notifications.ts        # Notification type definitions (export `notificationTypes`)
+└── encryption.ts           # Tenant data encryption maps for sensitive / GDPR fields
+```
+
+### Auto-discovery paths
+
+| Path pattern | Becomes |
+|---|---|
+| `frontend/<path>.tsx` | `/<path>` (public page) |
+| `frontend/[orgSlug]/portal/<path>/page.tsx` | `/{orgSlug}/portal/<path>` (customer portal page; `[orgSlug]` MUST be first) |
+| `backend/<path>.tsx` | `/backend/<path>` (admin page) |
+| `backend/page.tsx` | `/backend/<module>` (module root page) |
+| `api/<method>/<path>.ts` | `/api/<path>` dispatched by HTTP method |
+| `subscribers/*.ts` | event subscriber (export `metadata` + default handler) |
+| `workers/*.ts` | background worker (export `metadata` + default handler) |
+
+### Convention-file reference
+
+| File | Export | Purpose |
+|------|--------|---------|
+| `index.ts` | `metadata` | Module metadata |
+| `di.ts` | `register(container)` | DI registrations (Awilix) |
+| `acl.ts` | `features` | Permission features (`['mod.view', 'mod.manage', …]`) |
+| `setup.ts` | `setup` | Tenant init, default role features, seed data |
+| `ce.ts` | `entities` | Custom entities / custom field sets |
+| `events.ts` | `eventsConfig` | Typed event declarations (`createModuleEvents`) |
+| `search.ts` | `searchConfig` | Search indexing config |
+| `translations.ts` | `translatableFields` | Translatable fields per entity |
+| `notifications.ts` | `notificationTypes` | Notification type definitions |
+| `data/entities.ts` | — | MikroORM entity classes |
+| `data/validators.ts` | — | Zod validation schemas |
+| `data/extensions.ts` | `extensions` | Entity extensions (cross-module links) |
+| `data/enrichers.ts` | `enrichers` | Response enrichers |
+| `api/interceptors.ts` | `interceptors` | API route interception hooks |
+| `widgets/components.ts` | `componentOverrides` | Component replacement/wrapper definitions |
+
+## Naming conventions
+
+- **Module IDs:** plural, snake_case (`order_items`). Special cases: `auth`, `example`.
+- **Event IDs:** `module.entity.action` (singular entity, past-tense action, e.g. `sales.order.created`).
+- **Entity IDs:** colon form `module:entity` (e.g. `customers:customer_person_profile`) — the canonical interop token, **not** the raw class name and **not** the dotted friendly alias some enrichers use.
+- **DB tables:** plural, snake_case with a module prefix (`catalog_products`).
+- **DB columns:** snake_case (`created_at`, `organization_id`). Common columns: `id`, `created_at`, `updated_at`, `deleted_at`, `is_active`, `organization_id`, `tenant_id`.
+- **Feature IDs:** `<module>.<action>` (`my_module.view`, `my_module.manage`). FROZEN once shipped — rename by adding the new ID alongside and keeping the old as a deprecated alias.
+- **JS/TS identifiers:** camelCase. UUID primary keys, explicit foreign keys, junction tables for M2M.
+
+## Mandatory module mechanisms
+
+The framework provides **one canonical primitive per concern**. Do not invent your own routing, auth, persistence, forms, caching, or cross-module calls. If a feature is not listed here, ask before rolling your own.
+
+| Concern | Canonical mechanism |
 |---|---|
-| Module ownership, layout, discovery, registration, or installed source | `.ai/guides/architecture.md` |
-| Entities, CRUD/API, commands, scoping, ACL, setup, events, workers, search, cache, or migrations | `.ai/guides/contracts.md` |
-| Forms, tables, pages, navigation, portal, translations, or design-system behavior | `.ai/guides/backend-ui.md` |
-| Enrichers, interceptors, guards, widgets, extensions, menus, replacements, or overrides | `.ai/guides/extensions.md` |
-| Provider packages, data sync, webhooks, import/export, shipping, payment, or email | `.ai/guides/integrations.md` |
-| AI agents/tools/orchestrators or workflows | `.ai/guides/ai-workflows.md` |
-| Diagnosis and regression verification | `.ai/guides/testing-debugging.md` |
-
-For a complete new module, invoke `om-module-scaffold`; it loads the relevant branches. For a concrete installed-module fact, read its generated `.ai/guides/modules/<id>.md` first. Invoke `om-framework-context` only when generated facts cannot answer the implementation question.
+| Module structure & auto-discovery | `src/modules/<id>/{api,backend,frontend,data,subscribers,workers,widgets}` + `index.ts` + one line in `src/modules.ts` — discovered by `yarn generate` |
+| API routes | Files under `api/**/route.ts` exporting handlers + per-method `metadata` (`requireAuth` / `requireFeatures`) + `openApi`. NEVER a top-level `export const requireAuth` — the registry ignores it |
+| CRUD APIs | `makeCrudRoute({ orm, list, create, update, del, indexer })` from `@open-mercato/shared/lib/crud/factory`. Always set `indexer` for query-index coverage. Custom (non-factory) write routes MUST run the mutation guard registry (`runMutationGuards`) |
+| CRUD forms | `<CrudForm />` from `@open-mercato/ui/backend/CrudForm` + `createCrud`/`updateCrud`/`deleteCrud`. Never raw `<form>`, never raw `fetch` |
+| Data tables | `<DataTable entityId apiPath … />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` / `extensionTableId` stable so widget injection keeps working |
+| HTTP from the client | `apiCall` / `apiCallOrThrow` from `@open-mercato/ui/backend/utils/apiCall` — never raw `fetch` |
+| Authorization (RBAC) | Declare features in `acl.ts`, grant in `setup.ts` `defaultRoleFeatures`, gate with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER `requireRoles` (role names mutate). Treat `module.*` / `*` wildcard grants as part of the contract |
+| Multi-tenant scoping | Every tenant-scoped entity has indexed `organization_id` + `tenant_id`; every read/write filters by them. The CRUD factory injects scope — do not bypass it. Ad-hoc queries use `withScopedPayload` |
+| Encryption for sensitive data | Declare `encryption.ts` `defaultEncryptionMaps`; read via `findWithDecryption` / `findOneWithDecryption`. NEVER hand-roll AES/KMS, NEVER `em.find` on encrypted columns |
+| Cache | Resolve from DI (`container.resolve('cache')`) — never `new Redis(...)`. Tag with `tenant:<id>` / `org:<id>` so invalidation stays tenant-scoped |
+| Background workers | `workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues |
+| Events between modules | `events.ts` with `createModuleEvents({ moduleId, events } as const)`; subscribe in `subscribers/`. Never call another module's services directly across boundaries |
+| Domain writes | Implement through the Command pattern so audit, undo, cache, events, and indexing stay consistent — do not mutate domain state directly in route handlers |
+| i18n | `useT()` client-side, `resolveTranslations()` server-side; keys in `src/i18n/<locale>.json`. Never hard-code user-facing strings |
+
+> Rule of thumb: if you reach for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual cross-module join, stop and check the row above — there is a canonical helper.
+
+## Entity-update safety & data integrity
+
+- **`withAtomicFlush`.** MikroORM can silently discard pending scalar changes when a query (`em.find`/`em.findOne`/sync helper) runs on the same `EntityManager` between a scalar mutation and `em.flush()`. Multi-phase mutations MUST use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush`. Keep `emitCrudSideEffects` and cache invalidation **outside** the block — they fire only after the DB write commits. For entity + custom fields + side effects in one write, prefer `runCrudCommandWrite`.
+- **Optimistic locking (default ON).** Every **new user-editable entity** MUST carry an `updated_at` column and return `updatedAt` in its list/detail responses, so the OSS optimistic lock can detect concurrent edits. `CrudForm` auto-derives the lock header from `initialValues.updatedAt` (covers update and delete). Append-only logs, junction/assignment tables, session/token rows, and parent-guarded sub-resource lines are exempt.
+- **Encryption.** Sensitive / GDPR fields go through the encryption-maps mechanism (`encryption.ts` + `findWithDecryption`), never hand-rolled crypto. Always pass `tenantId` and `organizationId` to the decryption helpers.
+- **Tenant isolation.** Never expose cross-tenant data; always filter by `organization_id` (and `tenant_id`). Never create direct ORM relationships between modules — reference by FK id and fetch separately.
+
+## Generate & migration workflow
+
+- **After editing `src/modules.ts` or any structural module file:** run `yarn generate`. Never hand-edit anything under `.mercato/generated/*`.
+- **After editing `data/entities.ts`:** run `yarn db:generate` as a schema-diff probe. Default to the generated SQL; if it emits unrelated churn from another module's stale snapshot, keep only the SQL for your change and update that module's `migrations/.snapshot-open-mercato.json` in the same commit.
+- **Do not run `yarn db:migrate`** unless the user explicitly asks. A PR should normally include the migration file plus snapshot, not local DB state. Never hand-edit a migration that has already shipped — add a new one.
+- **New ACL features must be visible immediately:** add the feature to `acl.ts` **and** to `setup.ts` `defaultRoleFeatures`, then run `yarn mercato auth sync-role-acls` so existing tenants pick it up.
+
+## Where to go next
+
+- A specific module's surface (entities, events, routes, auth, search, CLI): its **fact-sheet** at `.ai/guides/modules/<module>.md`.
+- Deeper package patterns: the matching **package guide** (`core.md`, `ui.md`, `shared.md`, `events.md`, `queue.md`, `cache.md`, `search.md`).
+- Scaffolding a module end-to-end: the `om-module-scaffold` skill.