@open-mercato/cli 0.5.1-develop.2972.6c5cd4a1c3 → 0.5.1-develop.2975.ccbadc8198

package/AGENTS.md

@@ -49,7 +49,11 @@ yarn db:generate   # Generate migrations for all modules (writes to src/modules/
 yarn db:migrate    # Apply all pending migrations (ordered, directory first)
 ```
 
-**Never hand-write migration files.** Update ORM entities in `data/entities.ts`, then run `yarn db:generate` to emit SQL and keep snapshots in sync.
+Default workflow: update ORM entities in `data/entities.ts`, then run `yarn db:generate` to emit SQL and keep `.snapshot-open-mercato.json` in sync.
+
+Coding-agent exception: if `yarn db:generate` emits unrelated migrations because another module's snapshot is stale, do not commit the noise. Delete unrelated generated files, keep or write only the SQL for the intended entity change, and update the affected module's `migrations/.snapshot-open-mercato.json` to the post-change schema. The snapshot update is mandatory; without it, standalone apps will regenerate already-committed migrations.
+
+Do not run `yarn db:migrate` as part of generation unless the user explicitly asks to apply migrations. A PR should normally include the migration file plus snapshot, not depend on local DB state.
 
 ## Standalone App Considerations
 

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

@@ -41,7 +41,7 @@ step, you WILL produce incorrect imports and miss required patterns.
 
 | Task | Load |
 |---|---|
-| Add/modify an entity, create migration | `.ai/guides/core.md` → Module Files, then `yarn mercato db generate` |
+| Add/modify an entity, create migration | `.ai/skills/data-model-design/SKILL.md`, `.ai/guides/core.md` → Module Files, then `yarn db:generate` |
 | Add a REST API endpoint | `.ai/guides/core.md` → API Routes |
 | Add a backend page | `.ai/guides/ui.md` → CrudForm / DataTable |
 | Configure sidebar navigation, page groups, settings pages | `.ai/skills/module-scaffold/references/navigation-patterns.md` |
@@ -135,11 +135,12 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 
 ## CRITICAL rules — always follow without exception
 
-1. **After editing any entity file**: run `yarn mercato db generate` (never hand-write migrations)
+1. **Entity classes live in `src/modules/<module>/data/entities.ts` and MUST import decorators from `@mikro-orm/decorators/legacy`.** Start there for every schema change.
 2. **After editing `src/modules.ts`** or any structural module file: run `yarn generate`
 3. **Never edit `.mercato/generated/*`** — auto-generated. Never edit `node_modules/@open-mercato/*` — eject instead.
-4. **Confirm migrations with user** before running `yarn mercato db migrate`
-5. **API route files MUST export `metadata`.** Every `src/modules/<module>/api/**/route.ts` that exports an HTTP handler (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) MUST also export a `metadata` object describing per-method auth, otherwise the generator emits the warning `[generate] ⚠ Route file exports handlers but no metadata — auth will default to required` and every method silently falls back to "authentication required". Use the per-method shape:
+4. **After editing `src/modules/<module>/data/entities.ts`**: run `yarn db:generate` as a schema-diff probe. Default to the generated SQL, but if it emits unrelated churn, keep or write only the scoped SQL for your module and update `src/modules/<module>/migrations/.snapshot-open-mercato.json` in the same change.
+5. **Confirm migrations with user** before running `yarn db:migrate`
+6. **API route files MUST export `metadata`.** Every `src/modules/<module>/api/**/route.ts` that exports an HTTP handler (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) MUST also export a `metadata` object describing per-method auth, otherwise the generator emits the warning `[generate] ⚠ Route file exports handlers but no metadata — auth will default to required` and every method silently falls back to "authentication required". Use the per-method shape:
    ```ts
    export const metadata = {
      GET: { requireAuth: true, requireFeatures: ['mymodule.view'] },
@@ -147,13 +148,13 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
    }
    ```
    For public endpoints, opt out explicitly with `{ requireAuth: false }`. Do not use the legacy top-level `export const requireAuth` / `export const requireFeatures` — they are no longer recognised.
-6. **Write migrations in one shot.** `yarn dev` auto-applies pending migrations at startup by default (`OM_DEV_AUTO_MIGRATE=1`). Once a generated migration has been run, editing the same migration file has no effect — the next migrate pass skips it as already-applied. If you truly need to iterate, either (a) disable auto-migrate (`OM_DEV_AUTO_MIGRATE=0`) and roll back with `yarn db:migrate --down` between edits, or (b) ship the correction as a **new** migration file. Never hand-edit a historical migration that has already been applied in any environment.
-7. **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.
+7. **Write migrations in one shot.** `yarn dev` auto-applies pending migrations at startup by default (`OM_DEV_AUTO_MIGRATE=1`). Once a migration has been applied, editing the same file usually has no effect — the next migrate pass skips it as already-applied. If `yarn db:generate` shows unrelated churn, manual SQL for the intended module is allowed, but you MUST also update that module's `.snapshot-open-mercato.json`. Never hand-edit a historical migration that has already shipped; add a **new** migration instead.
+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.
-8. **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. **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>`); but in `page.meta.ts` files specifically, the `icon` field MUST be built with `React.createElement('svg', { width: 16, height: 16, viewBox: '0 0 24 24', fill: 'none', stroke: 'currentColor', strokeWidth: 2 }, React.createElement('path', { d: '...' }))` — see the reference pattern in `node_modules/@open-mercato/core/dist/modules/customers/backend/customers/people/page.meta.js` or mirror `packages/core/src/modules/customers/backend/customers/people/page.meta.ts` in the monorepo. Do NOT `import { IconName } from 'lucide-react'` inside meta files — after the lucide-react major upgrade, direct imports in meta files break page-metadata serialization. Grab the `d="..."` from the lucide icon you want and inline it via `React.createElement`. 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. 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.
-7. **BEFORE writing ANY code**, you MUST:
+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.
+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
    - `Read` every file listed in the "Load" column for your task type
    - Only then proceed to implementation
@@ -163,6 +164,7 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 ## Additional Conventions
 
 - Custom modules use `from: '@app'` in `src/modules.ts`
+- Entity classes belong in `src/modules/<module>/data/entities.ts` and use decorators from `@mikro-orm/decorators/legacy`
 - Standalone apps expose `yarn mercato configs cache ...` because the template enables the `configs` module from `@open-mercato/core`
 - `yarn generate` automatically runs a best-effort structural cache purge (`yarn mercato configs cache structural --all-tenants`) after successful generation; if the cache command is unavailable, generation still succeeds
 - Detail/read-model APIs that expose `customFields` MUST return bare field keys via `normalizeCustomFieldResponse()` (for example `{ priority: 3 }`). Keep `cf_` / `cf:` prefixes for request payloads, filters, and form field IDs only.
@@ -170,7 +172,7 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 - `page.meta.ts` MUST include `pageGroup`, `pageGroupKey`, and `pageOrder` for sidebar grouping
 - Settings pages MUST use `pageContext: 'settings' as const` with `navHidden: true`
 - All related pages within a module MUST share the same `pageGroupKey`
-- DataTable MUST wire pagination props (`page`, `pageSize`, `totalCount`, `onPageChange`)
+- DataTable hosts MUST keep `extensionTableId` stable; when you own pagination state, wire `page`, `pageSize`, `totalCount`, and `onPageChange`
 
 ## Naming Conventions
 
@@ -227,8 +229,8 @@ import type { ApiInterceptor } from '@open-mercato/shared/lib/crud/api-intercept
 | `yarn generate` | Regenerate `.mercato/generated/` |
 | `yarn mercato configs cache structural --all-tenants` | Manually purge structural navigation/sidebar cache entries |
 | `yarn mercato module add <package>` | Install and enable an official module package |
-| `yarn mercato db generate` | Create migration for entity changes |
-| `yarn mercato db migrate` | Apply pending migrations |
+| `yarn db:generate` | Probe/create migration SQL for entity changes |
+| `yarn db:migrate` | Apply pending migrations after user confirmation |
 | `yarn initialize` | Bootstrap DB + first admin account |
 | `yarn build` | Build for production |
 | `yarn mercato eject <module>` | Copy a core module into `src/modules/` |

package/dist/agentic/shared/ai/skills/auto-continue-pr/STANDALONE.md

@@ -53,7 +53,7 @@ gh label create in-progress       --color c5def5 --description "Auto-skill is wo
 
 ## 3. Validation gate probes `package.json` scripts
 
-SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. Standalone apps typically have `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build`, but not the monorepo-specific `:packages` / `:app` splits.
+SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. The current standalone template ships `yarn build`, `yarn typecheck`, `yarn test`, `yarn generate`, `yarn db:generate`, and `yarn db:migrate`; monorepo-specific `build:packages`, `build:app`, and `i18n:*` scripts usually do not exist.
 
 Before running each step, probe:
 

package/dist/agentic/shared/ai/skills/auto-create-pr/STANDALONE.md

@@ -53,7 +53,7 @@ gh label create in-progress       --color c5def5 --description "Auto-skill is wo
 
 ## 3. Validation gate probes `package.json` scripts
 
-SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. Standalone apps typically have `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build`, but not the monorepo-specific `:packages` / `:app` splits.
+SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. The current standalone template ships `yarn build`, `yarn typecheck`, `yarn test`, `yarn generate`, `yarn db:generate`, and `yarn db:migrate`; monorepo-specific `build:packages`, `build:app`, and `i18n:*` scripts usually do not exist.
 
 Before running each step, probe:
 

package/dist/agentic/shared/ai/skills/auto-fix-github/STANDALONE.md

@@ -53,7 +53,7 @@ gh label create in-progress       --color c5def5 --description "Auto-skill is wo
 
 ## 3. Validation gate probes `package.json` scripts
 
-SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. Standalone apps typically have `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build`, but not the monorepo-specific `:packages` / `:app` splits.
+SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. The current standalone template ships `yarn build`, `yarn typecheck`, `yarn test`, `yarn generate`, `yarn db:generate`, and `yarn db:migrate`; monorepo-specific `build:packages`, `build:app`, and `i18n:*` scripts usually do not exist.
 
 Before running each step, probe:
 

package/dist/agentic/shared/ai/skills/auto-review-pr/SKILL.md

@@ -282,8 +282,8 @@ Record findings from the patterns below. These are mandatory findings, not optio
 | Hardcoded user-facing string in API errors or UI labels | Medium: must use i18n |
 | New `any` type annotation outside tests | Medium: use zod plus `z.infer` |
 | `alert(` or custom toast instead of `flash()` | Medium: use `flash()` |
-| Hand-written migration SQL file | Medium: never hand-write migrations |
-| Entity schema changed but no migration file in the diff | Medium: run `yarn db:generate` |
+| Hand-written migration SQL file without snapshot update or scope rationale | Medium: prefer generated migrations; manual SQL must be scoped and update `.snapshot-open-mercato.json` |
+| Entity schema changed but no migration file or no-op rationale in the diff | Medium: create a scoped migration and update the snapshot |
 | Missing explicit tenant scoping in sub-entity queries | Medium: defense in depth |
 | New or modified i18n locale JSON keys not in alphabetical order | Medium: CI i18n-check-sync requires sorted keys — run `yarn i18n:check-sync --fix` or sort manually |
 

package/dist/agentic/shared/ai/skills/auto-review-pr/STANDALONE.md

@@ -53,7 +53,7 @@ gh label create in-progress       --color c5def5 --description "Auto-skill is wo
 
 ## 3. Validation gate probes `package.json` scripts
 
-SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. Standalone apps typically have `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build`, but not the monorepo-specific `:packages` / `:app` splits.
+SKILL.md lists commands like `yarn typecheck`, `yarn test`, `yarn generate`, `yarn build:packages`, `yarn build:app`, `yarn i18n:check-sync`, `yarn i18n:check-usage`. The current standalone template ships `yarn build`, `yarn typecheck`, `yarn test`, `yarn generate`, `yarn db:generate`, and `yarn db:migrate`; monorepo-specific `build:packages`, `build:app`, and `i18n:*` scripts usually do not exist.
 
 Before running each step, probe:
 

package/dist/agentic/shared/ai/skills/backend-ui-design/SKILL.md

@@ -7,7 +7,7 @@ description: Design and implement consistent backend/backoffice interfaces using
 
 Guide for creating consistent, production-grade backend interfaces using the `@open-mercato/ui` component library. All implementations must use existing components for visual and behavioral consistency.
 
-For complete component API reference, see `references/ui-components.md`.
+For complete component API reference, see `references/ui-components.md`. Pair this skill with `.ai/guides/ui.md` when present and with the standalone `AGENTS.md` rules for DataTable hosts, design-system primitives, and backend page conventions.
 
 ## Design Principles
 
@@ -16,6 +16,7 @@ For complete component API reference, see `references/ui-components.md`.
 3. **Data Density**: Admin users need information-rich interfaces. Optimize for scanning.
 4. **Keyboard Navigation**: `Cmd/Ctrl+Enter` for primary actions, `Escape` to cancel.
 5. **Clear Hierarchy**: Page → Section → Content. Use `PageHeader`, `PageBody`, consistent spacing.
+6. **Design System Discipline**: Use semantic status tokens plus shared primitives like `StatusBadge`, `Alert`, `FormField`, `SectionHeader`, `CollapsibleSection`, and `EmptyState`. No hardcoded status colors or arbitrary text sizes.
 
 ## Required Component Library
 
@@ -50,6 +51,26 @@ Column patterns:
 - Status/enum: `EnumBadge` with severity presets
 - Actions: `RowActions` for context menus
 
+### Preferred DataTable Host Pattern
+
+For standard CRUD lists, prefer the built-in host pattern instead of manually fetching and shaping rows:
+
+```tsx
+<DataTable
+  entityId="tickets.ticket"
+  apiPath="tickets/tickets"
+  extensionTableId="tickets.ticket"
+  columns={columns}
+  createHref="/backend/tickets/tickets/new"
+  emptyState={{
+    title: t('tickets.list.empty.title'),
+    description: t('tickets.list.empty.description'),
+  }}
+/>
+```
+
+Keep `extensionTableId` stable so DataTable injections remain backward-compatible.
+
 ### DataTable Pagination
 
 DataTable MUST be configured with pagination props to display all data correctly. Without these, the table only shows the first page with no way to navigate:
@@ -182,6 +203,8 @@ import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customF
 - [ ] Loading states use `LoadingMessage` or `DataLoader`
 - [ ] Error states use `ErrorMessage`, `ErrorNotice`, or `Notice variant="error"`
 - [ ] Empty states use `EmptyState`
+- [ ] Status displays use `StatusBadge` or `EnumBadge`, not hardcoded colors
+- [ ] Standalone inputs use `FormField`; detail sections use `SectionHeader` / `CollapsibleSection` when applicable
 - [ ] Column truncation uses `meta.truncate` and `meta.maxWidth`
 - [ ] Boolean values use `BooleanIcon`
 - [ ] Status/enum values use `EnumBadge`
@@ -194,7 +217,7 @@ import { collectCustomFieldValues } from '@open-mercato/ui/backend/utils/customF
 2. Manual table markup — use `DataTable`
 3. Custom toast/notification — use `flash()`
 4. Inline styles — use Tailwind classes
-5. Hardcoded colors — use theme variables
+5. Hardcoded colors or status classes — use theme variables and semantic status tokens
 6. Missing loading states — every async operation needs feedback
 7. Missing error handling — every failure needs messaging
 8. Missing keyboard shortcuts — all dialogs need `Cmd+Enter` and `Escape`

package/dist/agentic/shared/ai/skills/backend-ui-design/references/ui-components.md

@@ -47,7 +47,7 @@ Complete reference of all available UI components in `@open-mercato/ui`.
 
 | Component | Import Path | Purpose | Key Props |
 |-----------|-------------|---------|-----------|
-| **DataTable** | `@open-mercato/ui/backend/DataTable` | Feature-rich table with sorting, filtering, pagination, export, perspectives | `columns`, `data`, `filters`, `pagination`, `perspective`, `onRowClick` |
+| **DataTable** | `@open-mercato/ui/backend/DataTable` | Feature-rich table with sorting, filtering, pagination, export, perspectives | `entityId`, `apiPath`, `extensionTableId`, `columns`, `data`, `page`, `pageSize`, `totalCount`, `onPageChange`, `onRowClick` |
 | **TruncatedCell** | `@open-mercato/ui/backend/TruncatedCell` | Table cell with text truncation and tooltip | `value`, `maxWidth` |
 | **EmptyState** | `@open-mercato/ui/backend/EmptyState` | Empty state placeholder | `title`, `description`, `action`, `icon` |
 | **RowActions** | `@open-mercato/ui/backend/RowActions` | Context menu for row actions | `items: {label, href?, onSelect?, destructive?}[]` |
@@ -127,14 +127,18 @@ const filters: FilterDef[] = [
 ]
 
 <DataTable
-  title="Items"
+  entityId="inventory.item"
+  apiPath="inventory/items"
+  extensionTableId="inventory.item"
   columns={columns}
-  data={data}
   filters={filters}
   filterValues={filterValues}
   onFiltersApply={handleFiltersApply}
   onFiltersClear={handleFiltersClear}
-  pagination={{ page, pageSize, total, totalPages, onPageChange }}
+  page={page}
+  pageSize={pageSize}
+  totalCount={totalCount}
+  onPageChange={setPage}
   onRowClick={(row) => router.push(`/items/${row.id}`)}
 />
 ```
@@ -228,6 +232,7 @@ const deleted = await deleteCrud('module/items', id)
 1. **Always use `flash()` for notifications** - Don't use `alert()` or custom toast implementations
 2. **Use `CrudForm` for forms** - Provides consistent validation, field rendering, and keyboard shortcuts
 3. **Use `DataTable` for lists** - Includes filtering, sorting, pagination, export, and perspectives
-4. **Use `JsonBuilder` for JSON editing** - Provides both raw JSON and visual builder modes
-5. **Dialog forms need `embedded={true}`** - And add `[&_.grid]:!grid-cols-1` to DialogContent for single-column layout
-6. **Support Cmd/Ctrl+Enter and Escape** - All dialogs should support these keyboard shortcuts
+4. **Keep `extensionTableId` stable** - Injection spots must remain backward-compatible
+5. **Use `JsonBuilder` for JSON editing** - Provides both raw JSON and visual builder modes
+6. **Dialog forms need `embedded={true}`** - And add `[&_.grid]:!grid-cols-1` to DialogContent for single-column layout
+7. **Support Cmd/Ctrl+Enter and Escape** - All dialogs should support these keyboard shortcuts

package/dist/agentic/shared/ai/skills/code-review/SKILL.md

@@ -98,7 +98,7 @@ Omit empty severity sections.
 
 ### Data Integrity
 
-- **Never hand-write migrations** — update entities, run `yarn db:generate`
+- **Migration files and snapshots must match entity intent** — prefer `yarn db:generate`; scoped manual SQL is allowed only to avoid unrelated generated churn and must include `.snapshot-open-mercato.json`
 - **Validate migration scope** — autogenerated doesn't mean correct
 - **Workers/subscribers MUST be idempotent**
 - **Commands MUST be undoable** — include before/after snapshots
@@ -130,8 +130,8 @@ Omit empty severity sections.
 ## Review Heuristics
 
 1. **New files**: Check if `yarn generate` is needed. Verify auto-discovery paths.
-2. **Entity changes**: Check if `yarn db:generate` is needed. Look for missing tenant columns.
-3. **Migration sanity**: Inspect SQL content. Reject unrelated schema churn.
+2. **Entity changes**: Check if migration and snapshot updates are needed. Look for missing tenant columns.
+3. **Migration sanity**: Inspect SQL content and `.snapshot-open-mercato.json`. Reject unrelated schema churn.
 4. **New API routes**: Verify `openApi` export, auth guards, zod validation, tenant filtering.
 5. **Event emitters**: Verify event is declared in `events.ts` with `as const`.
 6. **Commands**: Verify undoable, before/after snapshots.

package/dist/agentic/shared/ai/skills/code-review/references/review-checklist.md

@@ -20,7 +20,7 @@
 
 ## 3. Data Integrity & ORM
 
-- [ ] No hand-written migrations — entities updated, `yarn db:generate` run
+- [ ] Migration workflow is coherent — `yarn db:generate` was used as the default probe, or scoped manual SQL is justified and paired with a matching `.snapshot-open-mercato.json` update
 - [ ] Migration scope matches PR intent (no unrelated schema churn)
 - [ ] UUID primary keys with standard columns (`id`, `created_at`, `updated_at`)
 - [ ] Soft delete via `deleted_at` where applicable

package/dist/agentic/shared/ai/skills/data-model-design/SKILL.md

@@ -37,8 +37,10 @@ When the developer describes data requirements:
 
 ### Standard Entity Template
 
+Define entities in `src/modules/<module_id>/data/entities.ts`. Standalone apps keep the module's entity classes together there unless the file becomes large enough that a split is justified.
+
 ```typescript
-import { Entity, Property, PrimaryKey, Index, Enum } from '@mikro-orm/core'
+import { Entity, Enum, Index, PrimaryKey, Property } from '@mikro-orm/decorators/legacy'
 import { v4 } from 'uuid'
 
 @Entity({ tableName: '<entities>' })
@@ -322,14 +324,15 @@ const enricher: ResponseEnricher = {
 ### Creating a Migration
 
 ```bash
-# 1. Modify or create entity files
-# 2. Generate migration
+# 1. Modify src/modules/<module_id>/data/entities.ts
+# 2. Probe/generate migration
 yarn db:generate
 
-# 3. Review the generated migration
+# 3. Review the generated migration or use it as the baseline for scoped manual SQL
 # Check src/modules/<module_id>/migrations/Migration_YYYYMMDD_HHMMSS.ts
 
-# 4. Apply migration (confirm with user first)
+# 4. Update src/modules/<module_id>/migrations/.snapshot-open-mercato.json
+# 5. Apply migration only after explicit user confirmation
 yarn db:migrate
 ```
 
@@ -337,9 +340,12 @@ yarn db:migrate
 
 1. **Review every migration** — auto-generated doesn't mean correct
 2. **Check for unintended changes** — sometimes generators pick up unrelated diffs
-3. **New columns should have defaults** — prevents breaking existing rows
-4. **Never rename columns** — add new column, migrate data, remove old column (across releases)
-5. **Never drop tables** — soft delete or archive first
+3. **Do not commit unrelated generated migrations** — delete them from the diff
+4. **Scoped manual SQL is allowed** when generator churn is unrelated, but the migration and `.snapshot-open-mercato.json` must still describe the same post-change schema
+5. **Update `.snapshot-open-mercato.json`** — it is the baseline that prevents duplicate future migrations
+6. **New columns should have defaults** — prevents breaking existing rows
+7. **Never rename columns** — add new column, migrate data, remove old column (across releases)
+8. **Never drop tables** — soft delete or archive first
 
 ### Adding a Column to Existing Entity
 
@@ -355,8 +361,8 @@ new_field: string | null = null
 
 Then:
 ```bash
-yarn db:generate   # Creates ALTER TABLE ADD COLUMN migration
-yarn db:migrate    # Applies it
+yarn db:generate   # Probes/creates ALTER TABLE ADD COLUMN migration
+yarn db:migrate    # Applies it only after explicit user confirmation
 ```
 
 ### Removing a Column
@@ -484,7 +490,8 @@ export class TicketHistory {
 | `@ManyToOne` across modules | Tight coupling, breaks module isolation | Store FK as `uuid` column, use enrichers |
 | Storing computed values | Stale data, maintenance burden | Compute on read via enrichers or queries |
 | Using `any` for JSONB fields | No type safety | Define a Zod schema, use `z.infer` |
-| Manual migration SQL | Fragile, version-dependent | Use `yarn db:generate` |
+| Blindly committing all generated migrations | Captures unrelated snapshot drift | Keep only scoped SQL and update the matching snapshot |
+| Manual migration SQL without snapshot update | Future `yarn db:generate` recreates the same migration | Update `.snapshot-open-mercato.json` in the same change |
 | Renaming columns | Breaks existing data/queries | Add new column, migrate data, drop old |
 | Missing `organization_id` | Cross-tenant data leaks | Always include and index |
 | Using `varchar` without `length` | Defaults vary by DB | Always specify `length` |
@@ -500,8 +507,10 @@ export class TicketHistory {
 - **MUST** include standard columns (`id`, `created_at`, `updated_at`, `deleted_at`, `is_active`)
 - **MUST** use UUID v4 for primary keys
 - **MUST** index all FK columns and `organization_id` / `tenant_id`
-- **MUST** run `yarn db:generate` after entity changes, never hand-write migrations
+- **MUST** create or keep a scoped migration after entity changes and update `.snapshot-open-mercato.json`
 - **MUST** review generated migration before applying
+- **MUST NOT** commit unrelated migrations emitted by `yarn db:generate`
+- **MUST NOT** run `yarn db:migrate` without explicit user confirmation
 - **MUST** use `nullable: true` with `= null` default for optional fields
 - **MUST** specify `length` on all `varchar` columns
 - **MUST NOT** use ORM relationship decorators across module boundaries

package/dist/agentic/shared/ai/skills/implement-spec/SKILL.md

@@ -129,7 +129,7 @@ After all targeted phases are complete:
 3. **Build check**: `yarn build` — must pass
 4. **Unit test check**: `yarn test` — must pass
 5. **Integration test check**: run any new integration tests — must pass
-6. **Migration check**: `yarn mercato db generate` — if any entities changed (verify generated migration is scoped correctly)
+6. **Migration check**: `yarn db:generate` — if any entities changed (verify the resulting SQL is scoped correctly; manual SQL is acceptable only when avoiding unrelated churn, and the touched `.snapshot-open-mercato.json` must match)
 
 Report results to the user. If any check fails, fix and re-verify.
 
@@ -159,4 +159,4 @@ Report results to the user. If any check fails, fix and re-verify.
 - MUST keep subagents focused — one task per subagent, clear boundaries
 - MUST report blockers to the user immediately rather than working around them silently
 - MUST run `yarn generate` after creating or modifying module convention files
-- MUST run `yarn mercato db generate` after creating or modifying entities (and confirm migration with user before applying)
+- MUST run `yarn db:generate` after creating or modifying entities (and confirm migration with user before applying)

package/dist/agentic/shared/ai/skills/module-scaffold/SKILL.md

@@ -57,9 +57,8 @@ src/modules/<module_id>/
 ├── setup.ts                    # Tenant init, role features
 ├── di.ts                       # Awilix DI registrations
 ├── events.ts                   # Typed event declarations (if needed)
-├── entities/
-│   └── <Entity>.ts             # MikroORM entity class
 ├── data/
+│   ├── entities.ts             # MikroORM entity classes
 │   └── validators.ts           # Zod validation schemas
 ├── api/
 │   ├── get/
@@ -81,12 +80,12 @@ src/modules/<module_id>/
 
 ## 3. Create Entity
 
-**File**: `src/modules/<module_id>/entities/<Entity>.ts`
+**File**: `src/modules/<module_id>/data/entities.ts`
 
 ### Template
 
 ```typescript
-import { Entity, Property, PrimaryKey, Index } from '@mikro-orm/core'
+import { Entity, Index, PrimaryKey, Property } from '@mikro-orm/decorators/legacy'
 import { v4 } from 'uuid'
 
 @Entity({ tableName: '<entities>' })  // plural, snake_case
@@ -132,6 +131,7 @@ export class <Entity> {
 - PK: always `uuid` with `v4()` default
 - MUST include `organization_id` + `tenant_id` with `@Index()`
 - MUST include `created_at`, `updated_at`, `deleted_at`, `is_active`
+- Entity decorators MUST come from `@mikro-orm/decorators/legacy`
 - Cross-module references: store FK as `uuid` field (e.g., `customer_id`) — never use ORM `@ManyToOne`
 - Use `@Property({ type: 'jsonb' })` for flexible/nested data
 - Use `@Property({ type: 'varchar', length: N })` for bounded strings
@@ -179,7 +179,7 @@ Use `makeCrudRoute` for standard CRUD. Each HTTP method lives in its own file.
 
 ```typescript
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
-import { <Entity> } from '../../entities/<Entity>'
+import { <Entity> } from '../../data/entities'
 
 const handler = makeCrudRoute({
   entity: <Entity>,
@@ -202,7 +202,7 @@ export const openApi = {
 
 ```typescript
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
-import { <Entity> } from '../../entities/<Entity>'
+import { <Entity> } from '../../data/entities'
 import { create<Entity>Schema } from '../../data/validators'
 
 const handler = makeCrudRoute({
@@ -226,7 +226,7 @@ export const openApi = {
 
 ```typescript
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
-import { <Entity> } from '../../entities/<Entity>'
+import { <Entity> } from '../../data/entities'
 import { update<Entity>Schema } from '../../data/validators'
 
 const handler = makeCrudRoute({
@@ -250,7 +250,7 @@ export const openApi = {
 
 ```typescript
 import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
-import { <Entity> } from '../../entities/<Entity>'
+import { <Entity> } from '../../data/entities'
 
 const handler = makeCrudRoute({
   entity: <Entity>,
@@ -589,7 +589,7 @@ Add to `src/modules.ts`:
 
 ```bash
 yarn generate          # Discover module files, update .mercato/generated/
-yarn db:generate       # Create migration for new entity
+yarn db:generate       # Probe/create migration for the new entity
 ```
 
 ### Step 3: Review Migration
@@ -599,11 +599,13 @@ Check the generated migration file in `src/modules/<module_id>/migrations/`. Ver
 - All columns present with correct types
 - Indexes on `organization_id`, `tenant_id`
 - No unexpected changes
+- `migrations/.snapshot-open-mercato.json` was updated to the post-change schema
+- Unrelated generated migrations were deleted from the diff
 
 ### Step 4: Apply & Test
 
 ```bash
-yarn db:migrate        # Apply migration (confirm with user first)
+yarn db:migrate        # Apply migration only after explicit user confirmation
 yarn dev               # Start dev server
 ```
 
@@ -631,7 +633,7 @@ yarn dev               # Start dev server
 - [ ] ACL features declared and wired in `setup.ts`
 - [ ] Module registered in `src/modules.ts` with `from: '@app'`
 - [ ] `yarn generate` run after creating files
-- [ ] `yarn db:generate` run after creating entity
+- [ ] Migration SQL is scoped to this entity and `.snapshot-open-mercato.json` is updated
 - [ ] No `any` types
 - [ ] No hardcoded user-facing strings
 - [ ] No direct ORM relationships to other modules
@@ -651,6 +653,8 @@ yarn dev               # Start dev server
 - **MUST** declare ACL features and wire them in `setup.ts` `defaultRoleFeatures`
 - **MUST** register module in `src/modules.ts` with `from: '@app'`
 - **MUST** run `yarn generate` after creating module files
-- **MUST** run `yarn db:generate` after creating/modifying entities
+- **MUST** create or keep a scoped migration after creating/modifying entities and update `.snapshot-open-mercato.json`
+- **MUST NOT** commit unrelated migrations emitted by `yarn db:generate`
+- **MUST NOT** run `yarn db:migrate` without explicit user confirmation
 - **MUST NOT** create ORM relationships (`@ManyToOne`, `@OneToMany`) to entities in other modules
 - **MUST NOT** edit `.mercato/generated/*` files manually

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

@@ -128,17 +128,21 @@ yarn typecheck
 
 1. **Did you create a migration after adding/changing the entity?**
    ```bash
-   yarn db:generate     # Creates migration file
+   yarn db:generate     # Probes/creates migration file
    ```
-   Fix: Run `yarn db:generate` to create the migration.
+   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. **Did you apply the migration?**
+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.
+
+3. **Did you apply the migration?**
    ```bash
    yarn db:migrate      # Applies pending migrations
    ```
    Fix: Run `yarn db:migrate`.
 
-3. **Is the migration file correct?**
+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.
@@ -158,16 +162,21 @@ yarn typecheck
    Never edit `node_modules/@open-mercato/*`.
    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`.
+
 ### Entity changes not reflected
 
 **Symptoms**: Changed entity file but API still returns old schema
 
 **Checklist**:
 
-1. Run `yarn generate` — entity discovery is cached
-2. Run `yarn db:generate` — schema needs a migration
-3. Run `yarn db:migrate` — migration needs to be applied
-4. Restart `yarn dev` — server caches entity metadata
+1. Verify the entity lives in `src/modules/<module_id>/data/entities.ts` and imports decorators from `@mikro-orm/decorators/legacy`
+2. Run `yarn generate` — entity discovery is cached
+3. Run `yarn db:generate` — schema needs a migration
+4. Run `yarn db:migrate` — migration needs to be applied
+5. Restart `yarn dev` — server caches entity metadata
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@open-mercato/cli",
-  "version": "0.5.1-develop.2972.6c5cd4a1c3",
+  "version": "0.5.1-develop.2975.ccbadc8198",
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -59,8 +59,8 @@
     "@mikro-orm/decorators": "^7.0.10",
     "@mikro-orm/migrations": "^7.0.10",
     "@mikro-orm/postgresql": "^7.0.10",
-    "@open-mercato/queue": "0.5.1-develop.2972.6c5cd4a1c3",
-    "@open-mercato/shared": "0.5.1-develop.2972.6c5cd4a1c3",
+    "@open-mercato/queue": "0.5.1-develop.2975.ccbadc8198",
+    "@open-mercato/shared": "0.5.1-develop.2975.ccbadc8198",
     "cross-spawn": "^7.0.6",
     "pg": "8.20.0",
     "semver": "^7.7.4",
@@ -70,10 +70,10 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.2972.6c5cd4a1c3"
+    "@open-mercato/shared": "0.5.1-develop.2975.ccbadc8198"
   },
   "devDependencies": {
-    "@open-mercato/shared": "0.5.1-develop.2972.6c5cd4a1c3",
+    "@open-mercato/shared": "0.5.1-develop.2975.ccbadc8198",
     "@types/jest": "^30.0.0",
     "jest": "^30.3.0",
     "ts-jest": "^29.4.9"