create-mercato-app 0.6.5-develop.4639.1.0416d895fa → 0.6.5-develop.4656.1.5b0d4fd8a6

package/agentic/shared/AGENTS.md.template

@@ -154,12 +154,35 @@ When the user asks to **create a new application** or a **new module**, do not i
 | **Multi-tenant scoping (default for every entity)** | Every tenant-scoped entity MUST include indexed `organization_id` and `tenant_id` columns and every read/write MUST filter by them. The CRUD factory injects scope automatically — do NOT bypass it. For ad-hoc queries use `withScopedPayload` from `@open-mercato/shared/lib/api/scoped` | `.ai/skills/om-data-model-design/SKILL.md`; <https://docs.open-mercato.dev/architecture/system-overview> |
 | **Encryption maps for sensitive data** | Declare a module-level `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` from `@open-mercato/shared/modules/encryption`. Read encrypted columns via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find`. NEVER hand-roll AES/KMS, NEVER use `em.find` on encrypted columns | `.ai/skills/om-data-model-design/SKILL.md` → Sensitive Data and Encryption Maps; <https://docs.open-mercato.dev/user-guide/encryption> |
 | **Cache** | Resolve the cache from DI (`container.resolve('cache')`) — never `new Redis(...)` or raw SQLite. Tag with `tenant:<id>` / `org:<id>` and the entity-type tag so invalidation stays tenant-scoped | `.ai/guides/cache.md`; <https://docs.open-mercato.dev/user-guide/cache-management> |
+| **Entity update safety** | Multi-phase scalar + relation mutations use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` — never interleave `em.find`/`em.findOne` between a scalar mutation and `em.flush()`. Keep `emitCrudSideEffects` + cache invalidation OUTSIDE it (they fire after commit) | See **Entity Update Safety** section below |
 | **Background workers** | `src/modules/<id>/workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues | `.ai/guides/queue.md`; <https://docs.open-mercato.dev/framework/events/queue-workers> |
 | **Events between modules** | `<module>/events.ts` with `createModuleEvents({ moduleId, events } as const)`. Subscribers in `subscribers/*.ts`. Never call other modules' services directly across module boundaries | `.ai/guides/events.md`; <https://docs.open-mercato.dev/framework/events/overview> |
 | **i18n (every user-facing string)** | `useT()` client-side from `@open-mercato/shared/lib/i18n/context`, `resolveTranslations()` server-side from `@open-mercato/shared/lib/i18n/server`; keys in `src/i18n/<locale>.json`. Never hard-code labels in components | `.ai/guides/shared.md` → i18n |
 
 > Rule of thumb: if you find yourself reaching for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual `m2m` join across modules, stop and check the row above — there is a canonical helper.
 
+## Entity Update Safety
+
+MikroORM v7 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()`. For any command in `{{PROJECT_NAME}}` that mutates entities across multiple phases:
+
+- MUST use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush`.
+- NEVER interleave `em.find`/`em.findOne`/sync helpers between a scalar mutation and `em.flush()` on the same `EntityManager` without `withAtomicFlush` — the UPDATE is dropped.
+- Keep `emitCrudSideEffects` (and `emitCrudUndoSideEffects`) AND cache invalidation OUTSIDE the `withAtomicFlush` block — they fire only AFTER the DB write commits.
+
+```typescript
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+
+await withAtomicFlush(em, [
+  () => { record.name = 'New Name'; record.status = 'active' },
+  () => syncEntityTags(em, record, tags),
+], { transaction: true, label: '<module>.<command>' })
+
+// Side effects + cache invalidation AFTER the atomic flush (post-commit)
+await emitCrudSideEffects({ /* ... */ })
+```
+
+Because invalidation runs post-commit and the query-index read-projection tail (search tokens, vectors, fulltext, coverage) converges asynchronously, reads can briefly see a convergence window after a write. An opt-in env flag, `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` (default OFF, backward compatible), is planned to make that tail converge synchronously on write at a write-latency cost — treat it as opt-in/forthcoming, not on by default.
+
 ## CRITICAL rules — always follow without exception
 
 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.

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

@@ -25,6 +25,8 @@
 - [ ] UUID primary keys with standard columns (`id`, `created_at`, `updated_at`)
 - [ ] Soft delete via `deleted_at` where applicable
 - [ ] Atomic transactions for multi-step writes
+- [ ] `withAtomicFlush(em, phases, { transaction: true })` used when mutating across phases that include queries on the same `EntityManager`
+- [ ] No `em.find`/`em.findOne`/sync helpers between a scalar mutation and `em.flush()` without `withAtomicFlush`
 
 ## 4. API Routes
 
@@ -42,6 +44,7 @@
 - [ ] Workers export `metadata` with `{ queue, id?, concurrency? }`
 - [ ] All mutations implemented as commands with undo logic
 - [ ] Side effects outside `withAtomicFlush`
+- [ ] Cache invalidation and side effects (`emitCrudSideEffects`) fire AFTER the DB write commits — never inside the `withAtomicFlush` block
 
 ## 6. UI & Backend Pages
 

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

@@ -443,6 +443,8 @@ const items = await em.find(Entity, {
 })
 ```
 
+> **Multi-phase or relation-syncing writes:** the bare `em.flush()` above is fine for a single scalar update. As soon as a write mutates across multiple phases or runs a query (`em.find`/`em.findOne`/sync helper) between a scalar mutation and the flush, switch to `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` — MikroORM v7 silently drops the scalar UPDATE otherwise. Never query between scalar mutations and flush; keep side effects + cache invalidation outside the flush (after commit).
+
 ### Audit/History Table
 
 For tracking changes to an entity:

package/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md

@@ -7,7 +7,7 @@
 | Module ID | plural, snake_case | `fleet_vehicles`, `loyalty_points` |
 | Module folder | same as module ID | `src/modules/fleet_vehicles/` |
 | Entity class | PascalCase, singular | `FleetVehicle`, `LoyaltyPoint` |
-| Entity file | PascalCase, singular | `entities/FleetVehicle.ts` |
+| Entity file | single `data/entities.ts` (one class per entity) | `data/entities.ts` → `class FleetVehicle` |
 | Table name | plural, snake_case | `fleet_vehicles`, `loyalty_points` |
 | Column name | snake_case | `vehicle_type`, `point_balance` |
 
@@ -17,7 +17,7 @@
 |---------|-----------|---------|
 | JS/TS fields | camelCase | `vehicleType`, `pointBalance` |
 | Event ID | `module.entity.action` (dots, singular entity, past tense) | `fleet_vehicles.vehicle.created` |
-| Feature ID | `module.action` | `fleet_vehicles.view`, `fleet_vehicles.create` |
+| Feature ID | `module.entity.action` (per-entity; use `view` / `manage`) | `fleet_vehicles.vehicle.view`, `fleet_vehicles.vehicle.manage` |
 | Enricher ID | `module.enricher-name` | `fleet_vehicles.maintenance-stats` |
 | Widget ID | `module.injection.widget-name` | `fleet_vehicles.injection.status-column` |
 | Interceptor ID | `module.interceptor-name` | `fleet_vehicles.validate-vin` |
@@ -39,12 +39,11 @@ deleted_at: Date | null // Soft delete timestamp
 
 ## API Routes
 
-| Method | File Path | URL |
-|--------|----------|-----|
-| GET | `api/get/<entities>.ts` | `GET /api/<module>/<entities>` |
-| POST | `api/post/<entities>.ts` | `POST /api/<module>/<entities>` |
-| PUT | `api/put/<entities>.ts` | `PUT /api/<module>/<entities>` |
-| DELETE | `api/delete/<entities>.ts` | `DELETE /api/<module>/<entities>` |
+All HTTP methods live in a **single** `api/<entities>/route.ts` that exports named handlers `{ GET, POST, PUT, DELETE }` + `metadata` + `openApi` (not separate `api/get/`, `api/post/` files).
+
+| File Path | Methods | URL |
+|-----------|---------|-----|
+| `api/<entities>/route.ts` | `GET` / `POST` / `PUT` / `DELETE` | `/api/<module>/<entities>` |
 
 ## Backend Pages
 

package/agentic/shared/ai/skills/om-prepare-issue/SKILL.md

@@ -0,0 +1,202 @@
+---
+name: om-prepare-issue
+description: Capture a feature the user wants built later without building it now. Researches and writes a spec via the om-spec-writing conventions, ships it as a docs-only spec PR against `develop` (reusing om-auto-create-pr mechanics; `skip-qa`, `documentation`), then opens a tracking GitHub issue that links the spec path and the spec PR so the work can be picked up later with om-auto-fix-github or om-implement-spec. Use for "park this idea", "write a spec and an issue for later", "prepare an issue to build X eventually", "spec it out but don't implement yet".
+---
+
+# Prepare Issue (deferred work)
+
+Turn a "we want this eventually" brief into durable, actionable backlog without implementing it. The deliverable is three linked artifacts:
+
+1. A **spec** under `.ai/specs/` written to `om-spec-writing` standards.
+2. A **docs-only spec PR** against `develop` that adds only that spec file (`documentation`, `skip-qa`).
+3. A **GitHub issue** to implement the spec, linking both the spec path and the spec PR.
+
+This skill is for **deferred** work. It does NOT implement the feature. If the user wants the feature built now, hand off to `om-auto-create-pr` (free-form task) or `om-implement-spec` (after the spec exists) instead.
+
+This skill reuses the worktree/branch/commit/label discipline of `.ai/skills/om-auto-create-pr/SKILL.md` for the PR, the spec methodology of `.ai/skills/om-spec-writing/SKILL.md` for the spec, and the issue-claim/linking conventions of `.ai/skills/om-auto-fix-github/SKILL.md` for the tracking issue. Read those before deviating.
+
+## Arguments
+
+- `{brief}` (required) — free-form description of the feature to capture. One sentence or several paragraphs.
+- `--slug <kebab-case>` (optional) — override the slug used in the spec filename and branch. Default: derived from the brief.
+- `--enterprise` (optional) — write the spec under `.ai/specs/enterprise/` instead of `.ai/specs/` (commercial scope). Default: OSS scope (`.ai/specs/`).
+- `--priority <low|medium|high|extreme>` (optional) — priority label for the tracking issue. Default: unset (treated as `priority-medium`).
+- `--no-issue` (optional) — write the spec and open the spec PR, but skip issue creation. Use when the user only wants the spec on record.
+- `--force` (optional) — bypass the claim-conflict check when a previous run left a branch or spec file behind.
+
+## Workflow
+
+### 0. Pre-flight and claim
+
+Follow `.ai/skills/om-auto-create-pr/SKILL.md` step 0 verbatim. This is new docs work, so the branch MUST use the `feat/` prefix.
+
+```bash
+CURRENT_USER=$(gh api user --jq '.login')
+DATE=$(date -u +%Y-%m-%d)
+SLUG="{slug-or-derived}"
+SPEC_DIR=".ai/specs"            # or .ai/specs/enterprise when --enterprise
+SPEC_PATH="${SPEC_DIR}/${DATE}-${SLUG}.md"
+BRANCH="feat/prepare-${SLUG}"
+```
+
+A run is **already in progress** when ANY of these is true (treat as re-entry if the current user owns it, otherwise STOP and ask via `AskUserQuestion` unless `--force`):
+
+- A file at `$SPEC_PATH` already exists on `origin/develop` or any remote branch.
+- A remote branch `origin/${BRANCH}` already exists.
+- An open PR already adds `$SPEC_PATH`.
+- An open issue already tracks the same feature (search before creating — see step 5).
+
+### 1. Triage the brief before writing
+
+Read enough context to write a credible spec, not to build it:
+
+- Match the brief to rows in the root `AGENTS.md` Task Router and read every matching guide (module, UI, search, events, etc.).
+- Check `.ai/specs/` and `.ai/specs/enterprise/` for an existing spec covering the same area. If one exists, extend or supersede it instead of duplicating — confirm the direction with the user via `AskUserQuestion`.
+- Skim `.ai/lessons.md`.
+
+Reduce the brief to: goal in one sentence, affected modules/packages, and the rough scope. If a wrong assumption would force a spec rewrite, surface it as an Open Question (see step 2) rather than guessing.
+
+### 2. Write the spec with om-spec-writing
+
+Follow `.ai/skills/om-spec-writing/SKILL.md` end to end. Key points for this skill:
+
+- Create the spec at `$SPEC_PATH` (`{YYYY-MM-DD}-{kebab-title}.md`, `date` UTC). Enterprise scope goes under `.ai/specs/enterprise/`.
+- Start with a **Skeleton Spec** (TLDR + 2-3 key sections). If critical unknowns exist, add a numbered **Open Questions** block right after the TLDR and **STOP** — ask the user before filling in the rest. This is a hard gate; do not invent answers to architecture-blocking questions.
+- After answers land, expand the spec: Problem Statement, Proposed Solution, Phasing (stories), Implementation Plan (testable Steps), and the architectural concerns the `om-spec-writing` lens requires (singular naming, FK-only cross-module links, `organization_id` scoping, undoability, zod validation, encryption maps for sensitive columns, canonical primitives, Design System tokens, Frontend Architecture Contract when UI is touched).
+- The spec MUST include an **integration coverage** section listing the affected API paths and key UI paths the implementer will need to test (root `AGENTS.md` → Documentation and Specifications requires this for every feature).
+- Apply the `om-spec-writing` Spec Checklist and Final Compliance Review before finalizing.
+
+Do NOT write any implementation code, migrations, or module files. The only file this run adds is the spec.
+
+### 3. Isolated worktree, branch, and first commit
+
+Follow `.ai/skills/om-auto-create-pr/SKILL.md` steps 4–5 verbatim. Base is always `develop`. Commit the spec as the first commit, then push.
+
+```bash
+git add "$SPEC_PATH"
+git commit -m "docs(spec): add ${SLUG} spec for deferred implementation"
+git push -u origin "$BRANCH"
+```
+
+If the Open Questions gate in step 2 is still unresolved, do not create the worktree or push — resolve the questions with the user first.
+
+### 4. Open the spec PR
+
+This is a docs-only / spec-only PR. The minimum validation gate is the docs-only gate from `.ai/skills/om-auto-create-pr/SKILL.md` step 7:
+
+- `yarn lint` if it catches markdown/YAML issues.
+- `git diff --check` — no trailing whitespace, no merge markers.
+- A manual re-read of the spec.
+
+Never run the full code gate (`yarn test` / `yarn typecheck` / `yarn build:app`) for a spec-only run.
+
+Open the PR against `develop`:
+
+```bash
+gh pr create --base develop \
+  --title "docs(spec): ${SLUG} — deferred implementation spec" \
+  --body-file <(cat <<'EOF'
+## Goal
+- {one-line feature summary from the brief}
+
+## What this PR adds
+- Spec only: `{SPEC_PATH}`. No implementation, no code, no migrations.
+
+## Why now
+- Captures deferred work as a reviewable spec so it can be implemented later via `om-implement-spec` / `om-auto-fix-github`.
+
+## Tracking issue
+- {issue URL — filled in after step 5, or "see follow-up comment"}
+
+## Backward Compatibility
+- No contract surface changes (spec document only).
+EOF
+)
+```
+
+Apply labels per root `AGENTS.md` PR workflow, each followed by a short explanatory comment (per the `om-auto-create-pr` label-comment rule):
+
+- `review` — "PR is ready for code review."
+- `documentation` — "spec-only deliverable under `.ai/specs/`."
+- `skip-qa` — "spec/docs-only; no customer-facing runtime behavior."
+
+Never add `needs-qa` to a prepare-issue PR — it adds no runtime behavior to exercise.
+
+### 5. Create the tracking issue
+
+Skip this step only when `--no-issue` was passed.
+
+First, avoid duplicates — search for an existing tracking issue:
+
+```bash
+gh issue list --state open --search "${SLUG} in:title,body" --json number,title,url
+```
+
+If a credible duplicate exists, link the spec/PR in a comment on that issue instead of opening a new one, and report which issue you reused.
+
+Otherwise create the issue. It MUST link the spec path and the spec PR, and name the recommended implementer skill so a future run can pick it up:
+
+```bash
+gh issue create \
+  --title "Implement: {feature title}" \
+  --label "feature" \
+  --body-file <(cat <<'EOF'
+## Summary
+- {one-line feature summary from the brief}
+
+## Spec
+- Implementation spec: `{SPEC_PATH}`
+- Spec PR: {spec PR URL}
+
+## How to implement
+- Once the spec PR merges, run `/om-implement-spec {SPEC_PATH}` (multi-phase) or `/om-auto-fix-github {thisIssueNumber}` (smaller scope).
+- Do not start implementation until the spec PR is merged into `develop`.
+
+## Scope notes
+- {affected modules/packages}
+- {non-goals captured in the spec}
+EOF
+)
+```
+
+Label rules for the issue:
+
+- Always add the `feature` category label (or `refactor` / `bug` when the brief is clearly one of those).
+- Add `enterprise` when `--enterprise` was passed.
+- Add a priority label only when `--priority` was passed (`priority-low` / `priority-medium` / `priority-high` / `priority-extreme`); otherwise leave priority unset (treated as `priority-medium`).
+- Do NOT add pipeline labels (`review`, `qa`, `merge-queue`, …) to the issue — those are PR-only.
+
+### 6. Cross-link the artifacts
+
+Make the three artifacts point at each other so the trail is navigable:
+
+- Edit the spec PR body (or post a comment) so the `Tracking issue` line resolves to the real issue URL.
+- The issue already links the spec path and spec PR from step 5.
+- Optionally add a one-line reference to the issue at the top of the spec (e.g. `Tracking issue: #{n}`), committed and pushed to the PR branch.
+
+### 7. Cleanup and report back
+
+Clean up any worktree you created (per `.ai/skills/om-auto-create-pr/SKILL.md` step 13). Then report:
+
+```text
+prepare-issue: {brief}
+Spec: {SPEC_PATH}
+Spec PR: {url}
+Tracking issue: {url | skipped (--no-issue) | reused #{n}}
+Branch: {branch}
+Status: {spec-and-issue ready | open-questions pending — answer to continue}
+```
+
+If the Open Questions gate is still pending, say so explicitly and list the unanswered questions — do not claim the spec is complete.
+
+## Rules
+
+- This skill captures deferred work only. NEVER implement the feature, write module code, or run migrations. The only file added is the spec.
+- Always write the spec with `om-spec-writing` standards, including the Open Questions hard gate and the integration-coverage section.
+- The spec PR is docs-only: run only the docs-only validation gate, never the full code gate.
+- Spec PR labels are `review`, `documentation`, `skip-qa` — never `needs-qa`. Post a short comment after each label.
+- Base branch is always `develop`. Branch uses the `feat/prepare-<slug>` prefix; never `codex/`.
+- The tracking issue MUST link the spec path and the spec PR, and name the recommended implementer skill (`om-implement-spec` / `om-auto-fix-github`).
+- Search for an existing tracking issue before creating a new one; reuse via comment if a credible duplicate exists.
+- Respect existing claims/locks per `om-auto-create-pr` step 0 and `om-auto-fix-github` step 0; never silently clobber another actor's branch, spec file, or issue.
+- Never paste secrets, tokens, or `.env` content into the spec, PR, or issue.

package/agentic/shared/ai/skills/om-spec-writing/references/spec-checklist.md

@@ -20,7 +20,7 @@ Every item must be answered in the spec or marked N/A with justification.
 ## 3. Data Integrity & Security
 
 - [ ] Entities include `id`, `organization_id`, `tenant_id`, `created_at`, `updated_at`, `deleted_at`, `is_active`
-- [ ] Write operations define transaction boundaries
+- [ ] Write operations define transaction boundaries — specs touching multi-phase scalar + relation writes MUST name `withAtomicFlush({ transaction: true })` and declare that cache invalidation / side effects (`emitCrudSideEffects`) fire AFTER commit (outside the flush block)
 - [ ] Input validation uses zod schemas
 - [ ] All user input validated before business logic/persistence
 - [ ] Auth guards declared per-method in `metadata` (`requireAuth`, `requireFeatures`) — never legacy top-level `export const requireAuth`

package/dist/agentic/guides/core.customers.md

@@ -135,4 +135,4 @@ await withAtomicFlush(em, [
 await emitCrudSideEffects({ ... })
 ```
 
-Never run `em.find`/`em.findOne` between scalar mutations and `em.flush()` without `withAtomicFlush` — changes will be silently lost.
+Never run `em.find`/`em.findOne` between scalar mutations and `em.flush()` without `withAtomicFlush` — changes will be silently lost. Cache invalidation must also stay outside `withAtomicFlush` and fire after commit, so the opt-in `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` mode (default OFF) never serves stale or partially-committed reads.

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

@@ -154,12 +154,35 @@ When the user asks to **create a new application** or a **new module**, do not i
 | **Multi-tenant scoping (default for every entity)** | Every tenant-scoped entity MUST include indexed `organization_id` and `tenant_id` columns and every read/write MUST filter by them. The CRUD factory injects scope automatically — do NOT bypass it. For ad-hoc queries use `withScopedPayload` from `@open-mercato/shared/lib/api/scoped` | `.ai/skills/om-data-model-design/SKILL.md`; <https://docs.open-mercato.dev/architecture/system-overview> |
 | **Encryption maps for sensitive data** | Declare a module-level `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` from `@open-mercato/shared/modules/encryption`. Read encrypted columns via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find`. NEVER hand-roll AES/KMS, NEVER use `em.find` on encrypted columns | `.ai/skills/om-data-model-design/SKILL.md` → Sensitive Data and Encryption Maps; <https://docs.open-mercato.dev/user-guide/encryption> |
 | **Cache** | Resolve the cache from DI (`container.resolve('cache')`) — never `new Redis(...)` or raw SQLite. Tag with `tenant:<id>` / `org:<id>` and the entity-type tag so invalidation stays tenant-scoped | `.ai/guides/cache.md`; <https://docs.open-mercato.dev/user-guide/cache-management> |
+| **Entity update safety** | Multi-phase scalar + relation mutations use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` — never interleave `em.find`/`em.findOne` between a scalar mutation and `em.flush()`. Keep `emitCrudSideEffects` + cache invalidation OUTSIDE it (they fire after commit) | See **Entity Update Safety** section below |
 | **Background workers** | `src/modules/<id>/workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues | `.ai/guides/queue.md`; <https://docs.open-mercato.dev/framework/events/queue-workers> |
 | **Events between modules** | `<module>/events.ts` with `createModuleEvents({ moduleId, events } as const)`. Subscribers in `subscribers/*.ts`. Never call other modules' services directly across module boundaries | `.ai/guides/events.md`; <https://docs.open-mercato.dev/framework/events/overview> |
 | **i18n (every user-facing string)** | `useT()` client-side from `@open-mercato/shared/lib/i18n/context`, `resolveTranslations()` server-side from `@open-mercato/shared/lib/i18n/server`; keys in `src/i18n/<locale>.json`. Never hard-code labels in components | `.ai/guides/shared.md` → i18n |
 
 > Rule of thumb: if you find yourself reaching for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual `m2m` join across modules, stop and check the row above — there is a canonical helper.
 
+## Entity Update Safety
+
+MikroORM v7 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()`. For any command in `{{PROJECT_NAME}}` that mutates entities across multiple phases:
+
+- MUST use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush`.
+- NEVER interleave `em.find`/`em.findOne`/sync helpers between a scalar mutation and `em.flush()` on the same `EntityManager` without `withAtomicFlush` — the UPDATE is dropped.
+- Keep `emitCrudSideEffects` (and `emitCrudUndoSideEffects`) AND cache invalidation OUTSIDE the `withAtomicFlush` block — they fire only AFTER the DB write commits.
+
+```typescript
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+
+await withAtomicFlush(em, [
+  () => { record.name = 'New Name'; record.status = 'active' },
+  () => syncEntityTags(em, record, tags),
+], { transaction: true, label: '<module>.<command>' })
+
+// Side effects + cache invalidation AFTER the atomic flush (post-commit)
+await emitCrudSideEffects({ /* ... */ })
+```
+
+Because invalidation runs post-commit and the query-index read-projection tail (search tokens, vectors, fulltext, coverage) converges asynchronously, reads can briefly see a convergence window after a write. An opt-in env flag, `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` (default OFF, backward compatible), is planned to make that tail converge synchronously on write at a write-latency cost — treat it as opt-in/forthcoming, not on by default.
+
 ## CRITICAL rules — always follow without exception
 
 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.

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

@@ -25,6 +25,8 @@
 - [ ] UUID primary keys with standard columns (`id`, `created_at`, `updated_at`)
 - [ ] Soft delete via `deleted_at` where applicable
 - [ ] Atomic transactions for multi-step writes
+- [ ] `withAtomicFlush(em, phases, { transaction: true })` used when mutating across phases that include queries on the same `EntityManager`
+- [ ] No `em.find`/`em.findOne`/sync helpers between a scalar mutation and `em.flush()` without `withAtomicFlush`
 
 ## 4. API Routes
 
@@ -42,6 +44,7 @@
 - [ ] Workers export `metadata` with `{ queue, id?, concurrency? }`
 - [ ] All mutations implemented as commands with undo logic
 - [ ] Side effects outside `withAtomicFlush`
+- [ ] Cache invalidation and side effects (`emitCrudSideEffects`) fire AFTER the DB write commits — never inside the `withAtomicFlush` block
 
 ## 6. UI & Backend Pages
 

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

@@ -443,6 +443,8 @@ const items = await em.find(Entity, {
 })
 ```
 
+> **Multi-phase or relation-syncing writes:** the bare `em.flush()` above is fine for a single scalar update. As soon as a write mutates across multiple phases or runs a query (`em.find`/`em.findOne`/sync helper) between a scalar mutation and the flush, switch to `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` — MikroORM v7 silently drops the scalar UPDATE otherwise. Never query between scalar mutations and flush; keep side effects + cache invalidation outside the flush (after commit).
+
 ### Audit/History Table
 
 For tracking changes to an entity:

package/dist/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md

@@ -7,7 +7,7 @@
 | Module ID | plural, snake_case | `fleet_vehicles`, `loyalty_points` |
 | Module folder | same as module ID | `src/modules/fleet_vehicles/` |
 | Entity class | PascalCase, singular | `FleetVehicle`, `LoyaltyPoint` |
-| Entity file | PascalCase, singular | `entities/FleetVehicle.ts` |
+| Entity file | single `data/entities.ts` (one class per entity) | `data/entities.ts` → `class FleetVehicle` |
 | Table name | plural, snake_case | `fleet_vehicles`, `loyalty_points` |
 | Column name | snake_case | `vehicle_type`, `point_balance` |
 
@@ -17,7 +17,7 @@
 |---------|-----------|---------|
 | JS/TS fields | camelCase | `vehicleType`, `pointBalance` |
 | Event ID | `module.entity.action` (dots, singular entity, past tense) | `fleet_vehicles.vehicle.created` |
-| Feature ID | `module.action` | `fleet_vehicles.view`, `fleet_vehicles.create` |
+| Feature ID | `module.entity.action` (per-entity; use `view` / `manage`) | `fleet_vehicles.vehicle.view`, `fleet_vehicles.vehicle.manage` |
 | Enricher ID | `module.enricher-name` | `fleet_vehicles.maintenance-stats` |
 | Widget ID | `module.injection.widget-name` | `fleet_vehicles.injection.status-column` |
 | Interceptor ID | `module.interceptor-name` | `fleet_vehicles.validate-vin` |
@@ -39,12 +39,11 @@ deleted_at: Date | null // Soft delete timestamp
 
 ## API Routes
 
-| Method | File Path | URL |
-|--------|----------|-----|
-| GET | `api/get/<entities>.ts` | `GET /api/<module>/<entities>` |
-| POST | `api/post/<entities>.ts` | `POST /api/<module>/<entities>` |
-| PUT | `api/put/<entities>.ts` | `PUT /api/<module>/<entities>` |
-| DELETE | `api/delete/<entities>.ts` | `DELETE /api/<module>/<entities>` |
+All HTTP methods live in a **single** `api/<entities>/route.ts` that exports named handlers `{ GET, POST, PUT, DELETE }` + `metadata` + `openApi` (not separate `api/get/`, `api/post/` files).
+
+| File Path | Methods | URL |
+|-----------|---------|-----|
+| `api/<entities>/route.ts` | `GET` / `POST` / `PUT` / `DELETE` | `/api/<module>/<entities>` |
 
 ## Backend Pages
 

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

@@ -0,0 +1,202 @@
+---
+name: om-prepare-issue
+description: Capture a feature the user wants built later without building it now. Researches and writes a spec via the om-spec-writing conventions, ships it as a docs-only spec PR against `develop` (reusing om-auto-create-pr mechanics; `skip-qa`, `documentation`), then opens a tracking GitHub issue that links the spec path and the spec PR so the work can be picked up later with om-auto-fix-github or om-implement-spec. Use for "park this idea", "write a spec and an issue for later", "prepare an issue to build X eventually", "spec it out but don't implement yet".
+---
+
+# Prepare Issue (deferred work)
+
+Turn a "we want this eventually" brief into durable, actionable backlog without implementing it. The deliverable is three linked artifacts:
+
+1. A **spec** under `.ai/specs/` written to `om-spec-writing` standards.
+2. A **docs-only spec PR** against `develop` that adds only that spec file (`documentation`, `skip-qa`).
+3. A **GitHub issue** to implement the spec, linking both the spec path and the spec PR.
+
+This skill is for **deferred** work. It does NOT implement the feature. If the user wants the feature built now, hand off to `om-auto-create-pr` (free-form task) or `om-implement-spec` (after the spec exists) instead.
+
+This skill reuses the worktree/branch/commit/label discipline of `.ai/skills/om-auto-create-pr/SKILL.md` for the PR, the spec methodology of `.ai/skills/om-spec-writing/SKILL.md` for the spec, and the issue-claim/linking conventions of `.ai/skills/om-auto-fix-github/SKILL.md` for the tracking issue. Read those before deviating.
+
+## Arguments
+
+- `{brief}` (required) — free-form description of the feature to capture. One sentence or several paragraphs.
+- `--slug <kebab-case>` (optional) — override the slug used in the spec filename and branch. Default: derived from the brief.
+- `--enterprise` (optional) — write the spec under `.ai/specs/enterprise/` instead of `.ai/specs/` (commercial scope). Default: OSS scope (`.ai/specs/`).
+- `--priority <low|medium|high|extreme>` (optional) — priority label for the tracking issue. Default: unset (treated as `priority-medium`).
+- `--no-issue` (optional) — write the spec and open the spec PR, but skip issue creation. Use when the user only wants the spec on record.
+- `--force` (optional) — bypass the claim-conflict check when a previous run left a branch or spec file behind.
+
+## Workflow
+
+### 0. Pre-flight and claim
+
+Follow `.ai/skills/om-auto-create-pr/SKILL.md` step 0 verbatim. This is new docs work, so the branch MUST use the `feat/` prefix.
+
+```bash
+CURRENT_USER=$(gh api user --jq '.login')
+DATE=$(date -u +%Y-%m-%d)
+SLUG="{slug-or-derived}"
+SPEC_DIR=".ai/specs"            # or .ai/specs/enterprise when --enterprise
+SPEC_PATH="${SPEC_DIR}/${DATE}-${SLUG}.md"
+BRANCH="feat/prepare-${SLUG}"
+```
+
+A run is **already in progress** when ANY of these is true (treat as re-entry if the current user owns it, otherwise STOP and ask via `AskUserQuestion` unless `--force`):
+
+- A file at `$SPEC_PATH` already exists on `origin/develop` or any remote branch.
+- A remote branch `origin/${BRANCH}` already exists.
+- An open PR already adds `$SPEC_PATH`.
+- An open issue already tracks the same feature (search before creating — see step 5).
+
+### 1. Triage the brief before writing
+
+Read enough context to write a credible spec, not to build it:
+
+- Match the brief to rows in the root `AGENTS.md` Task Router and read every matching guide (module, UI, search, events, etc.).
+- Check `.ai/specs/` and `.ai/specs/enterprise/` for an existing spec covering the same area. If one exists, extend or supersede it instead of duplicating — confirm the direction with the user via `AskUserQuestion`.
+- Skim `.ai/lessons.md`.
+
+Reduce the brief to: goal in one sentence, affected modules/packages, and the rough scope. If a wrong assumption would force a spec rewrite, surface it as an Open Question (see step 2) rather than guessing.
+
+### 2. Write the spec with om-spec-writing
+
+Follow `.ai/skills/om-spec-writing/SKILL.md` end to end. Key points for this skill:
+
+- Create the spec at `$SPEC_PATH` (`{YYYY-MM-DD}-{kebab-title}.md`, `date` UTC). Enterprise scope goes under `.ai/specs/enterprise/`.
+- Start with a **Skeleton Spec** (TLDR + 2-3 key sections). If critical unknowns exist, add a numbered **Open Questions** block right after the TLDR and **STOP** — ask the user before filling in the rest. This is a hard gate; do not invent answers to architecture-blocking questions.
+- After answers land, expand the spec: Problem Statement, Proposed Solution, Phasing (stories), Implementation Plan (testable Steps), and the architectural concerns the `om-spec-writing` lens requires (singular naming, FK-only cross-module links, `organization_id` scoping, undoability, zod validation, encryption maps for sensitive columns, canonical primitives, Design System tokens, Frontend Architecture Contract when UI is touched).
+- The spec MUST include an **integration coverage** section listing the affected API paths and key UI paths the implementer will need to test (root `AGENTS.md` → Documentation and Specifications requires this for every feature).
+- Apply the `om-spec-writing` Spec Checklist and Final Compliance Review before finalizing.
+
+Do NOT write any implementation code, migrations, or module files. The only file this run adds is the spec.
+
+### 3. Isolated worktree, branch, and first commit
+
+Follow `.ai/skills/om-auto-create-pr/SKILL.md` steps 4–5 verbatim. Base is always `develop`. Commit the spec as the first commit, then push.
+
+```bash
+git add "$SPEC_PATH"
+git commit -m "docs(spec): add ${SLUG} spec for deferred implementation"
+git push -u origin "$BRANCH"
+```
+
+If the Open Questions gate in step 2 is still unresolved, do not create the worktree or push — resolve the questions with the user first.
+
+### 4. Open the spec PR
+
+This is a docs-only / spec-only PR. The minimum validation gate is the docs-only gate from `.ai/skills/om-auto-create-pr/SKILL.md` step 7:
+
+- `yarn lint` if it catches markdown/YAML issues.
+- `git diff --check` — no trailing whitespace, no merge markers.
+- A manual re-read of the spec.
+
+Never run the full code gate (`yarn test` / `yarn typecheck` / `yarn build:app`) for a spec-only run.
+
+Open the PR against `develop`:
+
+```bash
+gh pr create --base develop \
+  --title "docs(spec): ${SLUG} — deferred implementation spec" \
+  --body-file <(cat <<'EOF'
+## Goal
+- {one-line feature summary from the brief}
+
+## What this PR adds
+- Spec only: `{SPEC_PATH}`. No implementation, no code, no migrations.
+
+## Why now
+- Captures deferred work as a reviewable spec so it can be implemented later via `om-implement-spec` / `om-auto-fix-github`.
+
+## Tracking issue
+- {issue URL — filled in after step 5, or "see follow-up comment"}
+
+## Backward Compatibility
+- No contract surface changes (spec document only).
+EOF
+)
+```
+
+Apply labels per root `AGENTS.md` PR workflow, each followed by a short explanatory comment (per the `om-auto-create-pr` label-comment rule):
+
+- `review` — "PR is ready for code review."
+- `documentation` — "spec-only deliverable under `.ai/specs/`."
+- `skip-qa` — "spec/docs-only; no customer-facing runtime behavior."
+
+Never add `needs-qa` to a prepare-issue PR — it adds no runtime behavior to exercise.
+
+### 5. Create the tracking issue
+
+Skip this step only when `--no-issue` was passed.
+
+First, avoid duplicates — search for an existing tracking issue:
+
+```bash
+gh issue list --state open --search "${SLUG} in:title,body" --json number,title,url
+```
+
+If a credible duplicate exists, link the spec/PR in a comment on that issue instead of opening a new one, and report which issue you reused.
+
+Otherwise create the issue. It MUST link the spec path and the spec PR, and name the recommended implementer skill so a future run can pick it up:
+
+```bash
+gh issue create \
+  --title "Implement: {feature title}" \
+  --label "feature" \
+  --body-file <(cat <<'EOF'
+## Summary
+- {one-line feature summary from the brief}
+
+## Spec
+- Implementation spec: `{SPEC_PATH}`
+- Spec PR: {spec PR URL}
+
+## How to implement
+- Once the spec PR merges, run `/om-implement-spec {SPEC_PATH}` (multi-phase) or `/om-auto-fix-github {thisIssueNumber}` (smaller scope).
+- Do not start implementation until the spec PR is merged into `develop`.
+
+## Scope notes
+- {affected modules/packages}
+- {non-goals captured in the spec}
+EOF
+)
+```
+
+Label rules for the issue:
+
+- Always add the `feature` category label (or `refactor` / `bug` when the brief is clearly one of those).
+- Add `enterprise` when `--enterprise` was passed.
+- Add a priority label only when `--priority` was passed (`priority-low` / `priority-medium` / `priority-high` / `priority-extreme`); otherwise leave priority unset (treated as `priority-medium`).
+- Do NOT add pipeline labels (`review`, `qa`, `merge-queue`, …) to the issue — those are PR-only.
+
+### 6. Cross-link the artifacts
+
+Make the three artifacts point at each other so the trail is navigable:
+
+- Edit the spec PR body (or post a comment) so the `Tracking issue` line resolves to the real issue URL.
+- The issue already links the spec path and spec PR from step 5.
+- Optionally add a one-line reference to the issue at the top of the spec (e.g. `Tracking issue: #{n}`), committed and pushed to the PR branch.
+
+### 7. Cleanup and report back
+
+Clean up any worktree you created (per `.ai/skills/om-auto-create-pr/SKILL.md` step 13). Then report:
+
+```text
+prepare-issue: {brief}
+Spec: {SPEC_PATH}
+Spec PR: {url}
+Tracking issue: {url | skipped (--no-issue) | reused #{n}}
+Branch: {branch}
+Status: {spec-and-issue ready | open-questions pending — answer to continue}
+```
+
+If the Open Questions gate is still pending, say so explicitly and list the unanswered questions — do not claim the spec is complete.
+
+## Rules
+
+- This skill captures deferred work only. NEVER implement the feature, write module code, or run migrations. The only file added is the spec.
+- Always write the spec with `om-spec-writing` standards, including the Open Questions hard gate and the integration-coverage section.
+- The spec PR is docs-only: run only the docs-only validation gate, never the full code gate.
+- Spec PR labels are `review`, `documentation`, `skip-qa` — never `needs-qa`. Post a short comment after each label.
+- Base branch is always `develop`. Branch uses the `feat/prepare-<slug>` prefix; never `codex/`.
+- The tracking issue MUST link the spec path and the spec PR, and name the recommended implementer skill (`om-implement-spec` / `om-auto-fix-github`).
+- Search for an existing tracking issue before creating a new one; reuse via comment if a credible duplicate exists.
+- Respect existing claims/locks per `om-auto-create-pr` step 0 and `om-auto-fix-github` step 0; never silently clobber another actor's branch, spec file, or issue.
+- Never paste secrets, tokens, or `.env` content into the spec, PR, or issue.

package/dist/agentic/shared/ai/skills/om-spec-writing/references/spec-checklist.md

@@ -20,7 +20,7 @@ Every item must be answered in the spec or marked N/A with justification.
 ## 3. Data Integrity & Security
 
 - [ ] Entities include `id`, `organization_id`, `tenant_id`, `created_at`, `updated_at`, `deleted_at`, `is_active`
-- [ ] Write operations define transaction boundaries
+- [ ] Write operations define transaction boundaries — specs touching multi-phase scalar + relation writes MUST name `withAtomicFlush({ transaction: true })` and declare that cache invalidation / side effects (`emitCrudSideEffects`) fire AFTER commit (outside the flush block)
 - [ ] Input validation uses zod schemas
 - [ ] All user input validated before business logic/persistence
 - [ ] Auth guards declared per-method in `metadata` (`requireAuth`, `requireFeatures`) — never legacy top-level `export const requireAuth`

package/dist/index.js

@@ -571,7 +571,8 @@ function generateShared(config) {
     "om-auto-create-pr-loop",
     "om-auto-continue-pr-loop",
     "om-auto-review-pr",
-    "om-auto-fix-github"
+    "om-auto-fix-github",
+    "om-prepare-issue"
   ]) {
     if (!existsSync2(join3(AGENTIC_DIR, "ai", "skills", autoSkill, "SKILL.md"))) {
       continue;
@@ -836,6 +837,7 @@ function printSummary(selectedIds) {
     console.log("      /om-auto-continue-pr <PR#>    \u2014 resume an in-progress agent PR");
     console.log("      /om-auto-review-pr   <PR#>    \u2014 automated code review (optional autofix)");
     console.log("      /om-auto-fix-github  <issue#> \u2014 fix a GitHub issue and open a PR");
+    console.log("      /om-prepare-issue    <idea>   \u2014 spec out deferred work + open a tracking issue (no build)");
     console.log("      /om-trim-unused-modules       \u2014 slim classic-mode defaults after adding your own module");
     console.log("      See .ai/skills/om-auto-create-pr/STANDALONE.md for portability notes");
     console.log("      (base-branch discovery, opt-in pipeline labels, script probing).");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.5-develop.4639.1.0416d895fa",
+  "version": "0.6.5-develop.4656.1.5b0d4fd8a6",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

package/template/AGENTS.md

@@ -268,6 +268,28 @@ Practical consequences:
   4. Re-apply (`yarn db:migrate`) and commit.
 - Never hand-edit historical migrations that have shipped; add a **new** migration that performs the correction instead.
 
+## Entity Update Safety / Transaction Safety
+
+MikroORM v7 can silently drop a pending scalar UPDATE when a query (`em.find`, `em.findOne`, or a sync helper) runs on the same `EntityManager` between the scalar mutation and `em.flush()`. For commands that mutate entities across multiple phases:
+
+- Use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` for multi-phase scalar + relation mutations.
+- Never interleave `em.find`/`em.findOne` between a scalar mutation and `em.flush()` without `withAtomicFlush`.
+- Keep `emitCrudSideEffects` and cache invalidation OUTSIDE the `withAtomicFlush` block — they run only AFTER the DB write commits.
+
+```ts
+import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
+
+await withAtomicFlush(em, [
+  () => { record.name = 'New Name'; record.status = 'active' },
+  () => syncEntityTags(em, record, tags),
+], { transaction: true })
+
+// Cache invalidation + side effects AFTER commit
+await emitCrudSideEffects({ /* ... */ })
+```
+
+Cache invalidation running post-commit means reads can briefly observe a query-index convergence window. The opt-in `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` env flag (default OFF, backward compatible) is planned to make the query-index read-projection tail converge synchronously on write, at a write-latency cost — opt-in/forthcoming, not on by default.
+
 ## AI Assistant — adding agents, tools, UI parts, and overrides
 
 Standalone apps consume the AI framework from `@open-mercato/ai-assistant` (in `node_modules/`). The same conventions used in the monorepo apply here: