create-mercato-app 0.6.1-develop.3090.06ab462170 → 0.6.1-develop.3102.d6e7e6d57a

package/agentic/shared/AGENTS.md.template

@@ -1,6 +1,6 @@
 # Agent Context Routing — {{PROJECT_NAME}}
 
-**MANDATORY CONTEXT LOADING** — see Critical Rule #5 below.
+**MANDATORY CONTEXT LOADING** — see the "BEFORE writing ANY code" Critical Rule below.
 Before writing code, find your task below and `Read` the listed files.
 Do NOT load the entire src/ tree — Open Mercato apps can have many modules.
 
@@ -51,7 +51,8 @@ step, you WILL produce incorrect imports and miss required patterns.
 | Add caching | `.ai/guides/cache.md` |
 | Add background workers | `.ai/guides/queue.md` |
 | Use i18n (translations) | `.ai/guides/shared.md` → i18n |
-| Use encrypted queries | `.ai/guides/shared.md` → Encryption |
+| Use encrypted queries (read sensitive columns that already have an encryption map; for authoring a NEW sensitive column see the row below first) | `.ai/guides/shared.md` → Encryption |
+| **Encrypt sensitive / GDPR-relevant fields** ("we need this column encrypted", "store this securely", "this is PII", "GDPR", "encryption at rest", addresses, contact info, free-text notes about people, integration credentials, secrets) — declare them in the framework's encryption-maps mechanism, never hand-rolled AES/KMS | `.ai/skills/data-model-design/SKILL.md` → Sensitive Data and Encryption Maps, then `.ai/skills/module-scaffold/SKILL.md` → Encryption maps. Reference: <https://docs.open-mercato.dev/user-guide/encryption> |
 | Use apiCall / UI components | `.ai/guides/ui.md` |
 | Add permissions (RBAC) | `.ai/guides/core.md` → Access Control |
 | Add notifications | `.ai/guides/core.md` → Notifications |
@@ -130,11 +131,35 @@ src/modules/<id>/
 ├── ce.ts                 # Custom entities / custom field sets
 ├── translations.ts       # Translatable fields per entity
 ├── notifications.ts      # Notification type definitions
-└── notifications.client.ts  # Client-side notification renderers
+├── notifications.client.ts  # Client-side notification renderers
+└── encryption.ts         # Tenant data encryption maps (defaultEncryptionMaps) for sensitive / GDPR fields
 ```
 
 Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 
+## Mandatory Module Mechanisms (every module MUST use these — no DIY substitutes)
+
+When the user asks to **create a new application** or a **new module**, do not invent your own routing, auth, persistence, forms, or caching. The framework provides one canonical primitive for each concern. If a feature is not on this list and not in the Task → Context Map, ask before adding it — do not roll your own.
+
+| Concern | Canonical mechanism | Where to learn it |
+|---|---|---|
+| Module structure & auto-discovery | `src/modules/<id>/{api,backend,frontend,data,subscribers,workers,widgets}` + `index.ts` + `src/modules.ts` (`from: '@app'`) — discovered by `yarn generate` | `.ai/skills/module-scaffold/SKILL.md`, `.ai/guides/core.md` → Module Files; <https://docs.open-mercato.dev/framework/modules/overview> |
+| **Backend admin pages** | Auto-discovered files under `src/modules/<id>/backend/**`, paired `page.meta.ts` with `requireAuth` + `requireFeatures` + `pageGroup`/`pageGroupKey`/`pageOrder` | `.ai/skills/backend-ui-design/SKILL.md`, `.ai/skills/module-scaffold/references/navigation-patterns.md`; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
+| **Frontend public pages** | Auto-discovered files under `src/modules/<id>/frontend/**`. Customer portal pages live under `frontend/[orgSlug]/portal/<path>/page.tsx` with `requireCustomerAuth` / `requireCustomerFeatures` in `page.meta.ts` | `.ai/guides/ui.md` → Portal Extension; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
+| **API routes** | Files under `src/modules/<id>/api/**/route.ts` exporting handlers + `metadata` (per-method `requireAuth` / `requireFeatures`) + `openApi`. NEVER write a top-level `export const requireAuth` — the registry no longer recognises it | `.ai/guides/core.md` → API Routes; <https://docs.open-mercato.dev/framework/api/api-development-guide> |
+| **CRUD APIs (factory)** | `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory`. Always set `indexer` so query-index coverage stays correct. Custom (non-`makeCrudRoute`) write routes MUST call `validateCrudMutationGuard` before the mutation and `runCrudMutationGuardAfterSuccess` after success | `.ai/skills/module-scaffold/SKILL.md` → Create API Routes; <https://docs.open-mercato.dev/framework/api/crud-factory> |
+| **CRUD forms in admin** | `<CrudForm entityId apiPath mode fields />` from `@open-mercato/ui/backend/CrudForm`; helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never raw `<form>`, never raw `fetch` | `.ai/skills/backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
+| **DataTables in admin** | `<DataTable entityId apiPath title columns />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` and `extensionTableId` stable so widget injection (columns, row actions, bulk actions, filters, toolbar) keeps working | `.ai/skills/backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
+| **Authorization (RBAC)** | Declare features in `<module>/acl.ts`, grant them in `<module>/setup.ts` `defaultRoleFeatures`, gate pages and routes with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER use `requireRoles` (role names mutate). Run `yarn mercato auth sync-role-acls` after adding new features | `.ai/guides/core.md` → Access Control; <https://docs.open-mercato.dev/framework/rbac/overview> |
+| **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/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/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> |
+| **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.
+
 ## 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.
@@ -156,9 +181,16 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
    **Dashboards fallback rule.** When the user (or the `trim-unused-modules` skill) disables the `dashboards` module, you MUST update `src/app/(backend)/backend/page.tsx` so it no longer renders `<DashboardScreen />`. Replace the dashboard render with a `redirect(...)` to the first enabled backend page for the current user — preferring pages already registered in the main sidebar group and respecting the admin/superadmin role of the caller. Otherwise `/backend` will crash at build or request time because the removed module no longer ships `DashboardScreen`. Always fall back to `/backend/profile` only if no other backend page is available.
 9. **New features MUST be visible to default roles immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin role and any other appropriate default roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls` so existing tenants pick up the new feature without a reinstall. Use `--tenant <tenantId>` only when the user asks to target one tenant. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
 10. **Strict Design System alignment for every UI change.** Any UI you add or edit MUST use the Open Mercato design system components and tokens. No hardcoded Tailwind status colors (`text-red-500`, `bg-green-100`, etc.) — use semantic tokens (`text-status-error-text`, `bg-status-success-bg`, …). No arbitrary text sizes (`text-[11px]`, `text-[13px]`) — use the Tailwind scale (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`) or the `text-overline` token for 11px uppercase labels. In PAGE BODY UI, use `lucide-react` icons (never inline `<svg>`). Use `StatusBadge` for entity status, `Alert` for inline feedback, `FormField` for standalone form inputs, `SectionHeader` for detail-page section headings, `CollapsibleSection` for collapsible regions, `LoadingMessage`/`Spinner`/`DataLoader` for async states, and `EmptyState` (or DataTable's `emptyState` prop) for empty lists. For list pages, follow `.ai/skills/backend-ui-design/SKILL.md` and prefer the `DataTable` host pattern shown there (`entityId`, `apiPath`, stable `extensionTableId`, and explicit pagination props when you own the data source). Every dialog MUST support `Cmd/Ctrl+Enter` to submit and `Escape` to cancel. Every icon-only button MUST have an `aria-label`. These rules apply to `src/modules/<module>/backend/**` and `src/modules/<module>/frontend/**` alike.
-11. **BEFORE writing ANY code**, you MUST:
+11. **Sensitive / GDPR fields MUST go through the encryption-maps mechanism — never hand-rolled.** The framework provides per-tenant DEKs, KMS-backed key resolution, and a declarative field-level map. Whenever the user asks for "this field encrypted", "store this securely", "this is PII", "GDPR", "encryption at rest", or you are designing a column that will hold names, addresses, contacts, free-text notes about people, integration secrets/credentials, or any data subject to a data-processing agreement, you MUST:
+   - Declare the entity + field list in `src/modules/<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` (type imported from `@open-mercato/shared/modules/encryption`).
+   - Read those columns via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find` (passing `tenantId` and `organizationId`). Never use raw `em.find` on encrypted columns.
+   - For deterministic-lookup fields (e.g., login email), declare a sibling `hashField` in the map so equality lookups still work.
+   - Run `yarn mercato entities seed-encryption --tenant <tenantId>` after adding maps so existing tenants pick them up; new tenants get them automatically during `auth:setup`.
+   - Treat hand-rolled AES, raw `crypto.subtle`, custom KMS calls, or storing plaintext "for now" as broken — rewrite via the maps. See `.ai/skills/data-model-design/SKILL.md` → Sensitive Data and Encryption Maps and <https://docs.open-mercato.dev/user-guide/encryption>.
+12. **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
+   - Read the **Mandatory Module Mechanisms** section above to confirm which canonical primitives apply (CRUD factory, CrudForm, DataTable, RBAC, multi-tenant scoping, encryption maps, cache, events) — do not invent your own substitutes
    - Only then proceed to implementation
    - If your task matches multiple rows, load ALL listed files
    - **Do NOT skip this step.** The guides contain canonical import paths, required patterns, and conventions that CANNOT be reliably inferred from existing code alone. Skipping leads to wrong imports, missing conventions, and rework.
@@ -197,7 +229,8 @@ import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 
 // CRUD forms
-import { CrudForm, createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/crud'
+import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
+import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 
 // UI components (MUST use — never raw <button>)

package/agentic/shared/ai/qa/tests/playwright.config.ts

@@ -1,9 +1,14 @@
 import { defineConfig } from '@playwright/test'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { discoverIntegrationSpecFiles } from '@open-mercato/cli/lib/testing/integration-discovery'
 
 const captureScreenshots = process.env.PW_CAPTURE_SCREENSHOTS === '1'
 const isGitHubActions = process.env.GITHUB_ACTIONS === 'true'
+// Standalone apps generated from this template declare `"type": "module"`,
+// so the CommonJS `__dirname` is undefined when Playwright loads this config
+// under the Node ESM loader. Reconstruct it from `import.meta.url`.
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const projectRoot = path.resolve(__dirname, '..', '..', '..')
 const qaTestResultsRoot = path.join(projectRoot, '.ai', 'qa', 'test-results')
 const normalizePath = (value: string) => value.split(path.sep).join('/')

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

@@ -16,7 +16,8 @@ Design entities, relationships, and manage the migration lifecycle following Ope
 5. [Cross-Module References](#5-cross-module-references)
 6. [Migration Lifecycle](#6-migration-lifecycle)
 7. [Advanced Patterns](#7-advanced-patterns)
-8. [Anti-Patterns](#8-anti-patterns)
+8. [Sensitive Data and Encryption Maps](#8-sensitive-data-and-encryption-maps)
+9. [Anti-Patterns](#9-anti-patterns)
 
 ---
 
@@ -483,7 +484,89 @@ export class TicketHistory {
 
 ---
 
-## 8. Anti-Patterns
+## 8. Sensitive Data and Encryption Maps
+
+When the developer asks for "we need this column encrypted", "store this securely", "this is PII", "GDPR", or "encryption at rest" — and whenever you are designing a column that will hold names, addresses, contact information, free-text notes about people, integration credentials, secrets, or any data subject to a data-processing agreement — use the framework's **encryption-maps mechanism**. Do NOT hand-roll AES, raw `crypto.subtle`, custom KMS calls, or "TODO encrypt later" stubs.
+
+The mechanism gives you:
+
+- Per-tenant Data Encryption Keys (DEKs) resolved through the configured KMS (Vault by default, env-fallback in dev).
+- Declarative, per-entity, per-field encryption with optional deterministic-hash sibling columns for equality lookups (for example login by email).
+- Boot-time auto-application: every enabled module's `defaultEncryptionMaps` is collected during `auth:setup` and applied when `TENANT_DATA_ENCRYPTION=yes`.
+- A `findWithDecryption` / `findOneWithDecryption` read API that transparently decrypts on read.
+
+### When encryption is mandatory
+
+| Field example | Encrypt? |
+|---|---|
+| First name, last name, preferred name | Yes |
+| Email, phone | Yes — usually with a `hashField` for lookups |
+| Postal address (line 1/2, city, region, postal code, country) | Yes |
+| Free-text comments / notes / activity bodies that mention people | Yes |
+| Integration secrets, API keys, OAuth tokens, webhook signing keys | Yes |
+| Document numbers (tax IDs, national IDs) | Yes |
+| Status enums, counters, timestamps, FKs, currency codes | No |
+| Public catalog metadata (product titles for a public storefront) | Usually no |
+
+If you are unsure, default to encrypting and confirm with the user — re-introducing encryption later requires a backfill, but turning it off later is a single map edit.
+
+### Declare the map in `<module>/encryption.ts`
+
+```typescript
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: '<module_id>:<entity>',  // matches the entity's table id (colon-separated)
+    fields: [
+      { field: 'first_name' },
+      { field: 'last_name' },
+      { field: 'phone' },
+      // Sibling deterministic hash for equality lookups (e.g. login by email).
+      // Add a matching `<field>_hash varchar` column to the entity.
+      { field: 'email', hashField: 'email_hash' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps
+```
+
+### Read with decryption — never raw `em.find`
+
+```typescript
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+// Signature: (em, entityName, where, options?, scope?). MikroORM FindOptions go in slot 4
+// (pass `undefined` if you have none), the decryption scope `{ tenantId, organizationId }` in slot 5.
+const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
+const single  = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
+```
+
+Calling `em.find` on an encrypted column returns ciphertext, breaks search, and silently leaks bug surface. The `findWithDecryption` family is the one entry point.
+
+### Apply maps to existing tenants
+
+```bash
+yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
+```
+
+New tenants pick up the maps automatically during `auth:setup`. Toggling the **Encrypted** flag on a custom field via the admin UI also only applies to data written **after** the change — backfill historical plaintext rows by running `yarn mercato entities rotate-encryption-key --tenant <tenantId> --org <organizationId>` (without `--old-key` it skips already-encrypted fields and just encrypts plaintext). Use `yarn mercato entities decrypt-database` to roll back. For full UI flows and CLI options see <https://docs.open-mercato.dev/user-guide/encryption>.
+
+### Vector search caveat
+
+The `vector` module stores raw embeddings unencrypted in the vector store (e.g. pgvector). Even though the source text is decrypted only transiently to compute embeddings, treat the embeddings as sensitive: avoid embedding raw high-sensitivity text and rely on disk-level / managed-database encryption-at-rest for the vector column.
+
+### Environment switches
+
+- `TENANT_DATA_ENCRYPTION=yes|no` (default `yes`) — set to `no` to run the hooks as no-op (validation still applies).
+- `TENANT_DATA_ENCRYPTION_DEBUG=yes` — log map evaluation, KMS calls, cache hits.
+- `VAULT_ADDR` / `VAULT_TOKEN` / `VAULT_KV_PATH` — HashiCorp Vault KMS configuration.
+- `TENANT_DATA_ENCRYPTION_FALLBACK_KEY` — local/dev fallback key when Vault is unavailable. In dev, `AUTH_SECRET` / `NEXTAUTH_SECRET` is used as a last resort; production falls back to noop KMS.
+
+---
+
+## 9. Anti-Patterns
 
 | Anti-Pattern | Problem | Correct Pattern |
 |-------------|---------|-----------------|
@@ -498,6 +581,10 @@ export class TicketHistory {
 | Storing arrays as comma-separated strings | Can't query, no integrity | Use `jsonb` arrays or junction tables |
 | UUID FK without index | Slow joins | Always `@Index()` on FK columns |
 | Nullable required fields | Data integrity issues | Use `!` assertion for required, `null` for optional |
+| Hand-rolled AES / `crypto.subtle` / custom KMS for sensitive columns | Per-tenant key isolation, hash lookups, key rotation, and admin UI all break | Declare `<module>/encryption.ts` with `defaultEncryptionMaps`; let the framework manage DEKs and Vault |
+| Reading encrypted columns with raw `em.find` / `em.findOne` | Returns ciphertext, breaks search, silent data corruption | Use `findWithDecryption` / `findOneWithDecryption` with `{ tenantId, organizationId }` |
+| Storing PII as plaintext "for now" / TODO comments | GDPR violation, leaks at rest, expensive backfill later | Encrypt from day one; toggling later only protects new writes |
+| Encrypting an `email` column without a `hashField` | Login / equality lookups stop working | Declare a sibling `hashField` (e.g. `email_hash`) in the encryption map and add the matching `varchar` column |
 
 ---
 
@@ -515,7 +602,8 @@ export class TicketHistory {
 - **MUST** specify `length` on all `varchar` columns
 - **MUST NOT** use ORM relationship decorators across module boundaries
 - **MUST NOT** rename or drop columns in a single release
-- **MUST NOT** store sensitive data without encryption (use `findWithDecryption`)
+- **MUST** declare encrypted columns in `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]`, and read them via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find` — see section 8
+- **MUST NOT** hand-roll AES / KMS calls or store sensitive columns as plaintext "for now" — use the encryption-maps mechanism in section 8
 - Use `jsonb` for flexible/nested data, proper columns for queryable/sortable data
 - Use junction tables for many-to-many relationships
 - Derive TypeScript types from Zod schemas, never duplicate type definitions

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

@@ -40,14 +40,18 @@ For every piece of code, enforce these code-review rules inline:
 | Area | Rule |
 |------|------|
 | Types | No `any` — use zod + `z.infer` |
-| API routes | Export `openApi` and `metadata` with auth guards |
-| Entities | Standard columns, snake_case, UUID PKs, `organization_id` + `tenant_id` |
+| API routes | Export `openApi` and per-method `metadata` with `requireAuth` / `requireFeatures` (no top-level `export const requireAuth`) |
+| **CRUD APIs** | **Use `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory`. Custom write routes MUST call `validateCrudMutationGuard` before the mutation and `runCrudMutationGuardAfterSuccess` after success. See `AGENTS.md` → Mandatory Module Mechanisms.** |
+| Entities | Standard columns, snake_case, UUID PKs, indexed `organization_id` + `tenant_id` |
 | Security | `findWithDecryption`, tenant scoping, zod validation |
-| UI | `CrudForm`/`DataTable`, `apiCall`, `flash()`, `LoadingMessage`/`ErrorMessage` |
-| Events | `createModuleEvents()` with `as const`, subscribers export `metadata` |
+| **Encryption maps** | **For every PII / GDPR-relevant column the phase touches, declare in `<module>/encryption.ts` exporting `defaultEncryptionMaps` (type from `@open-mercato/shared/modules/encryption`). Reads via `findWithDecryption` / `findOneWithDecryption` (5-arg `(em, entity, where, options?, scope?)`). Equality-lookup columns declare a sibling `hashField`. NEVER hand-rolled AES/KMS, `crypto.subtle`, or "encrypt later" stubs. See `AGENTS.md` → CRITICAL Rule #11 (Encryption maps) + the "Encryption maps" row of the Mandatory Module Mechanisms table; `.ai/skills/data-model-design/SKILL.md` § Sensitive Data and Encryption Maps; `.ai/skills/module-scaffold/SKILL.md` § Encryption maps.** |
+| UI | `<CrudForm>`/`<DataTable>` (with stable `entityId` + `extensionTableId`), `apiCall` (never raw `fetch`), `flash()`, `<LoadingMessage>`/`<ErrorMessage>` |
+| **Design System** | **Semantic status tokens (no `text-red-*` / `bg-green-*`); Tailwind text scale (no `text-[13px]` / `text-[11px]`); shared primitives `StatusBadge` / `Alert` / `FormField` / `SectionHeader` / `CollapsibleSection` / `LoadingMessage` / `Spinner` / `DataLoader` / `EmptyState`; lucide-react icons in PAGE BODY (never inline `<svg>`); `aria-label` on every icon-only button; Boy Scout rule on touched lines. See `AGENTS.md` → CRITICAL Rule #10 (Strict Design System alignment) + `.ai/skills/backend-ui-design/SKILL.md`.** |
+| **Cache** | **Resolve via DI (`container.resolve('cache')`); tag with `tenant:<id>` / `org:<id>`; declare invalidation per write path. NEVER `new Redis(...)` or raw SQLite.** |
+| Events | `createModuleEvents()` with `as const`, subscribers export `metadata`; cross-module side effects via subscribers, never direct imports |
 | i18n | `useT()` client, `resolveTranslations()` server, no hardcoded strings |
 | Imports | Package-level `@open-mercato/<pkg>/...` for framework imports |
-| Mutations | `useGuardedMutation` when not using CrudForm |
+| Mutations | `useGuardedMutation` when not using CrudForm; pass `retryLastMutation` in injection context |
 | Keyboard | `Cmd/Ctrl+Enter` submit, `Escape` cancel on dialogs |
 | Naming | Modules plural snake_case, events `module.entity.past_tense`, features `module.action` |
 

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

@@ -41,8 +41,9 @@ Before writing any code, ask the developer:
    - [ ] Background workers
    - [ ] CLI commands
    - [ ] Custom fields support
+   - [ ] **Sensitive / GDPR-relevant fields** (PII, contact info, addresses, free-text notes about people, integration credentials, secrets) — if yes, an `encryption.ts` declaring `defaultEncryptionMaps` is mandatory; see section 11 → Encryption maps
 
-If the developer provides a brief description, infer reasonable defaults and confirm.
+If the developer provides a brief description, infer reasonable defaults and confirm. When key fields include names, emails, phones, addresses, free-text comments, or external API keys, treat the encryption checkbox as `yes` by default and confirm with the user rather than skipping it silently.
 
 ---
 
@@ -57,6 +58,7 @@ src/modules/<module_id>/
 ├── setup.ts                    # Tenant init, role features
 ├── di.ts                       # Awilix DI registrations
 ├── events.ts                   # Typed event declarations (if needed)
+├── encryption.ts               # Tenant data encryption maps (only if entity has sensitive/GDPR fields)
 ├── data/
 │   ├── entities.ts             # MikroORM entity classes
 │   └── validators.ts           # Zod validation schemas
@@ -178,7 +180,7 @@ Use `makeCrudRoute` for standard CRUD. Each HTTP method lives in its own file.
 **File**: `src/modules/<module_id>/api/get/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 
 const handler = makeCrudRoute({
@@ -201,7 +203,7 @@ export const openApi = {
 **File**: `src/modules/<module_id>/api/post/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 import { create<Entity>Schema } from '../../data/validators'
 
@@ -225,7 +227,7 @@ export const openApi = {
 **File**: `src/modules/<module_id>/api/put/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 import { update<Entity>Schema } from '../../data/validators'
 
@@ -249,7 +251,7 @@ export const openApi = {
 **File**: `src/modules/<module_id>/api/delete/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 
 const handler = makeCrudRoute({
@@ -346,7 +348,7 @@ export const metadata = {
 
 ```tsx
 'use client'
-import { CrudForm } from '@open-mercato/ui/backend/crud'
+import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 
 export default function Create<Entity>Page() {
@@ -384,7 +386,7 @@ export const metadata = {
 
 ```tsx
 'use client'
-import { CrudForm } from '@open-mercato/ui/backend/crud'
+import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 
 export default function Edit<Entity>Page({ params }: { params: { id: string } }) {
@@ -573,6 +575,52 @@ export default function registerCli(program: any) {
 }
 ```
 
+### Encryption maps (sensitive / GDPR-relevant fields)
+
+**Mandatory** when the entity stores PII, contact info, addresses, free-text notes about people, integration credentials, secrets, or anything subject to a data-processing agreement. Do NOT hand-roll AES, KMS calls, or "TODO encrypt later" stubs — the framework provides per-tenant DEKs and a declarative field-level map.
+
+**File**: `src/modules/<module_id>/encryption.ts`
+
+```typescript
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: '<module_id>:<entity>',  // matches data/entities.ts table id, colon-separated
+    fields: [
+      { field: 'first_name' },
+      { field: 'last_name' },
+      { field: 'phone' },
+      // Add a hashField for deterministic equality lookups (e.g. login by email):
+      { field: 'email', hashField: 'email_hash' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps
+```
+
+**Read paths** — never `em.find` an encrypted column directly:
+
+```typescript
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+// Signature: (em, entityName, where, options?, scope?) — MikroORM FindOptions in slot 4
+// (pass `undefined` when none), decryption scope in slot 5.
+const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
+const single  = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
+```
+
+**Apply to existing tenants** after declaring or updating maps:
+
+```bash
+yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
+```
+
+New tenants pick up `defaultEncryptionMaps` automatically during `auth:setup`. Toggling the **Encrypted** flag for a field only applies to data written **after** the change — historical plaintext rows stay as they were until backfilled via `yarn mercato entities rotate-encryption-key --tenant <tenantId> --org <organizationId>` (without `--old-key` the command only encrypts plaintext and skips already-encrypted fields). Use `yarn mercato entities decrypt-database` to roll back. For end-to-end usage and admin UI flows see <https://docs.open-mercato.dev/user-guide/encryption>.
+
+> Tip: when `email` (or any other column) needs deterministic lookups while encrypted, declare a sibling `hashField` in the map and add a matching `varchar` column to the entity. The framework keeps the hash in sync on writes; queries can target the hash instead of the cleartext column.
+
 ---
 
 ## 12. Wire & Verify
@@ -658,3 +706,5 @@ yarn dev               # Start dev server
 - **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
+- **MUST** declare `<module>/encryption.ts` exporting `defaultEncryptionMaps` whenever the entity stores sensitive / GDPR-relevant fields (PII, contact info, addresses, free-text notes about people, integration credentials, secrets) — and read those columns via `findWithDecryption` / `findOneWithDecryption`
+- **MUST NOT** hand-roll AES/KMS calls or store "we'll encrypt this later" plaintext for sensitive columns — use the encryption-maps mechanism described in section 11 → Encryption maps

package/agentic/shared/ai/skills/spec-writing/SKILL.md

@@ -60,6 +60,9 @@ Use the [Specification Template](references/spec-template.md). Adapt if needed,
 3. **Singularity Law**: Singular naming for entities, commands, events, feature IDs.
 4. **Undo Contract**: Is the "Undo" logic as detailed as the "Execute"?
 5. **Module Isolation**: Using Event Bus for side effects or cheating with direct imports?
+6. **Canonical Mechanisms**: Does the spec reach for the framework primitives (`makeCrudRoute`, `<CrudForm>`, `<DataTable>`, `apiCall` / `useGuardedMutation`, DI-resolved cache, `createModuleEvents`) or invent its own substitute? See `AGENTS.md` → **Mandatory Module Mechanisms** for the full canon and links. No raw `fetch`, no raw `<form>`, no `new Redis(...)`, no manual cross-module ORM joins.
+7. **Sensitive Data**: For every PII / GDPR / address / contact / free-text-about-people / integration-credential column the spec proposes, does it declare an `encryption.ts` `defaultEncryptionMaps` entry and route reads through `findWithDecryption`? See `AGENTS.md` → CRITICAL Rule #11 (Encryption maps) + the "Encryption maps for sensitive data" row of the Mandatory Module Mechanisms table and `.ai/skills/data-model-design/SKILL.md` § Sensitive Data and Encryption Maps. No hand-rolled AES, no `crypto.subtle`, no "TODO encrypt later".
+8. **Design System**: Does every UI mock / className snippet in the spec match the DS canon — semantic status tokens (no `text-red-*` / `bg-green-*`), Tailwind text scale (no `text-[11px]` / `text-[13px]`), shared primitives (`StatusBadge`, `Alert`, `FormField`, `SectionHeader`, `CollapsibleSection`, `LoadingMessage` / `Spinner` / `DataLoader`, `EmptyState`), lucide-react icons in page body (never inline `<svg>`), dialog `Cmd/Ctrl+Enter` submit + `Escape` cancel, `aria-label` on every icon-only button? See `AGENTS.md` → CRITICAL Rule #10 (Strict Design System alignment for every UI change) and `.ai/skills/backend-ui-design/SKILL.md`. Specs that touch existing pages MUST honour the Boy Scout rule.
 
 ## Quick Rule Reference
 
@@ -68,9 +71,15 @@ Use the [Specification Template](references/spec-template.md). Adapt if needed,
 - **`organization_id`** is mandatory for all tenant-scoped entities.
 - **Undoability** is the default for state changes.
 - **Zod validation** for all API inputs.
+- **Encryption maps** for every sensitive / GDPR-relevant column (declare in `<module>/encryption.ts`, read via `findWithDecryption`) — see `AGENTS.md` → Data Encryption.
+- **Canonical primitives** for CRUD APIs (`makeCrudRoute`), backend forms (`CrudForm`), tables (`DataTable`), HTTP (`apiCall` — never raw `fetch`), non-`CrudForm` writes (`useGuardedMutation`), cache (DI-resolved `@open-mercato/cache`), events (`createModuleEvents`) — see `AGENTS.md` → Mandatory Module Mechanisms.
+- **Design System** tokens and shared UI primitives — no hardcoded status colors, no arbitrary text sizes, no inline `<svg>` in page-body UI. See `AGENTS.md` → Design System.
 
 ## Reference Materials
 
 - [Spec Template](references/spec-template.md)
-- [Spec Checklist](references/spec-checklist.md)
-- [AGENTS.md](../../../AGENTS.md)
+- [Spec Checklist](references/spec-checklist.md) — § 3 covers encryption maps; § 5 covers canonical mechanisms + DS
+- [AGENTS.md](../../../AGENTS.md) — Mandatory Module Mechanisms table; CRITICAL Rule #10 (Design System); CRITICAL Rule #11 (Encryption maps)
+- [`.ai/skills/data-model-design/SKILL.md`](../data-model-design/SKILL.md) → Sensitive Data and Encryption Maps
+- [`.ai/skills/module-scaffold/SKILL.md`](../module-scaffold/SKILL.md) → Encryption maps
+- [`.ai/skills/backend-ui-design/SKILL.md`](../backend-ui-design/SKILL.md) — DS-compliant pages

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

@@ -19,26 +19,42 @@ Every item must be answered in the spec or marked N/A with justification.
 
 ## 3. Data Integrity & Security
 
-- [ ] Entities include `id`, `organization_id`, `created_at`, `updated_at`
+- [ ] Entities include `id`, `organization_id`, `tenant_id`, `created_at`, `updated_at`, `deleted_at`, `is_active`
 - [ ] Write operations define transaction boundaries
 - [ ] Input validation uses zod schemas
 - [ ] All user input validated before business logic/persistence
-- [ ] Auth guards are declared (`requireAuth`, `requireRoles`, `requireFeatures`)
-- [ ] Tenant isolation: every scoped query filters by `organization_id`
+- [ ] Auth guards declared per-method in `metadata` (`requireAuth`, `requireFeatures`) — never legacy top-level `export const requireAuth`
+- [ ] Tenant isolation: every scoped query filters by `organization_id` (and `tenant_id` where applicable)
+- [ ] **Encryption maps mechanism is used (no hand-rolled crypto).** For every PII / GDPR-relevant column the spec proposes — names, addresses, contacts, free-text notes about people, integration credentials, secrets, document numbers — the spec MUST declare them in a module-level `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` (type from `@open-mercato/shared/modules/encryption`). Reads MUST go through `findWithDecryption` / `findOneWithDecryption` (5-arg `(em, entity, where, options?, scope?)`) from `@open-mercato/shared/lib/encryption/find`. Equality-lookup columns (e.g. login email) declare a sibling `hashField`. No `crypto.subtle`, no custom KMS calls, no "TODO encrypt later". See `AGENTS.md` → CRITICAL Rule #11 (Encryption maps) + the "Encryption maps for sensitive data" row of the Mandatory Module Mechanisms table; `.ai/skills/data-model-design/SKILL.md` § Sensitive Data and Encryption Maps.
 
 ## 4. Commands, Events & Naming
 
 - [ ] Naming is singular and consistent
 - [ ] All mutations are commands with undo logic
-- [ ] Events declared in `events.ts` before emitting
+- [ ] Events declared in `<module>/events.ts` via `createModuleEvents({ moduleId, events } as const)` before emitting; cross-module side effects use `subscribers/*.ts`, never direct cross-module imports
 - [ ] Side-effect reversibility is documented
 
-## 5. API & UI
+## 5. API & UI — Canonical Mechanisms
 
 - [ ] API contracts are complete (request/response/errors)
 - [ ] Routes include `openApi` expectations
-- [ ] UI uses `CrudForm`, `DataTable`, and shared primitives
-- [ ] i18n keys are planned for user-facing strings
+- [ ] **Canonical mechanisms — no DIY substitutes.** The spec MUST reach for the framework primitives, not invent its own. See `AGENTS.md` → **Mandatory Module Mechanisms**.
+  - [ ] **CRUD APIs** use `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory`. Custom write routes call `validateCrudMutationGuard` before mutation and `runCrudMutationGuardAfterSuccess` after.
+  - [ ] **API route files export `metadata`** with per-method `requireAuth` / `requireFeatures` (no top-level `export const requireAuth`).
+  - [ ] **Backend forms** use `<CrudForm>` from `@open-mercato/ui/backend/CrudForm` with helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`, throwing `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors` for field-level errors. No raw `<form>`, no raw `fetch`.
+  - [ ] **Lists** use `<DataTable entityId apiPath columns />` from `@open-mercato/ui/backend/DataTable` with stable `entityId` / `extensionTableId` so widget injection (columns / row actions / bulk actions / filters / toolbar) keeps working.
+  - [ ] **HTTP clients** use `apiCall` / `apiCallOrThrow` / `readApiResultOrThrow` from `@open-mercato/ui/backend/utils/apiCall` — never raw `fetch`.
+  - [ ] **Non-`CrudForm` writes** are wrapped in `useGuardedMutation(...).runMutation(...)` and pass `retryLastMutation` in the injection context.
+  - [ ] **Cache** is resolved via DI (`container.resolve('cache')`) — never `new Redis(...)` or raw SQLite. Tags include `tenant:<id>` / `org:<id>`.
+- [ ] **Design System compliance for every UI mock and className snippet in the spec.** See `AGENTS.md` → CRITICAL Rule #10 (Strict Design System alignment) and `.ai/skills/backend-ui-design/SKILL.md`.
+  - [ ] Use semantic status tokens (`text-status-error-text`, `bg-status-success-bg`, `border-status-warning-border`, `text-status-info-icon`, `text-destructive`, `bg-destructive`) — NEVER hardcoded shades like `text-red-500`, `bg-green-100`, `text-amber-*`, `text-emerald-*`, `bg-blue-*`. Status tokens already cover dark mode; no `dark:` overrides.
+  - [ ] Use the Tailwind text scale (`text-xs` 12, `text-sm` 14, `text-base` 16, `text-lg` 18, `text-xl` 20, `text-2xl` 24) or `text-overline` for 11px uppercase labels — NEVER arbitrary sizes (`text-[11px]`, `text-[13px]`, `text-[15px]`, `p-[13px]`, `rounded-[24px]`, `z-[9999]`).
+  - [ ] Use shared primitives instead of raw HTML: `<Alert variant=...>` for inline status, `flash('msg', 'success|error|warning|info')` for toasts, `useConfirmDialog()` for destructive confirmations, `<StatusBadge>` for entity status, `<FormField label error>` to wrap form inputs, `<SectionHeader title count action>` for section headers, `<CollapsibleSection>` for collapsible regions, `<LoadingMessage>` / `<Spinner>` / `<DataLoader>` for async states, `<EmptyState>` (or DataTable `emptyState` prop) for empty lists.
+  - [ ] Use lucide-react icons in PAGE BODY UI (`Page`, `DataTable`, `CrudForm`, cards, buttons) — never inline `<svg>`. Sizes from the `size-{3|4|5|6}` scale; `strokeWidth` is not overridden per-instance. `page.meta.ts` icons follow the `React.createElement('svg', …)` pattern.
+  - [ ] Every dialog supports `Cmd/Ctrl+Enter` to submit and `Escape` to cancel.
+  - [ ] Every icon-only button has an `aria-label`.
+  - [ ] Boy Scout rule: when the spec edits an existing page, any line touched gets migrated to semantic tokens / DS scale.
+- [ ] i18n keys are planned for user-facing strings (`useT()` client-side, `resolveTranslations()` server-side; never hard-coded labels)
 - [ ] Pagination limits defined (`pageSize <= 100`)
 
 ## 6. Risks & Anti-Patterns
@@ -48,3 +64,4 @@ Every item must be answered in the spec or marked N/A with justification.
 - [ ] Does not introduce cross-module ORM links
 - [ ] Does not skip undoability for state changes
 - [ ] Does not mix MVP with speculative future phases
+- [ ] Does not introduce hand-rolled AES, raw `fetch`, raw `<form>`, `new Redis(...)`, or arbitrary Tailwind sizes / status colors

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

@@ -1,6 +1,6 @@
 # Agent Context Routing — {{PROJECT_NAME}}
 
-**MANDATORY CONTEXT LOADING** — see Critical Rule #5 below.
+**MANDATORY CONTEXT LOADING** — see the "BEFORE writing ANY code" Critical Rule below.
 Before writing code, find your task below and `Read` the listed files.
 Do NOT load the entire src/ tree — Open Mercato apps can have many modules.
 
@@ -51,7 +51,8 @@ step, you WILL produce incorrect imports and miss required patterns.
 | Add caching | `.ai/guides/cache.md` |
 | Add background workers | `.ai/guides/queue.md` |
 | Use i18n (translations) | `.ai/guides/shared.md` → i18n |
-| Use encrypted queries | `.ai/guides/shared.md` → Encryption |
+| Use encrypted queries (read sensitive columns that already have an encryption map; for authoring a NEW sensitive column see the row below first) | `.ai/guides/shared.md` → Encryption |
+| **Encrypt sensitive / GDPR-relevant fields** ("we need this column encrypted", "store this securely", "this is PII", "GDPR", "encryption at rest", addresses, contact info, free-text notes about people, integration credentials, secrets) — declare them in the framework's encryption-maps mechanism, never hand-rolled AES/KMS | `.ai/skills/data-model-design/SKILL.md` → Sensitive Data and Encryption Maps, then `.ai/skills/module-scaffold/SKILL.md` → Encryption maps. Reference: <https://docs.open-mercato.dev/user-guide/encryption> |
 | Use apiCall / UI components | `.ai/guides/ui.md` |
 | Add permissions (RBAC) | `.ai/guides/core.md` → Access Control |
 | Add notifications | `.ai/guides/core.md` → Notifications |
@@ -130,11 +131,35 @@ src/modules/<id>/
 ├── ce.ts                 # Custom entities / custom field sets
 ├── translations.ts       # Translatable fields per entity
 ├── notifications.ts      # Notification type definitions
-└── notifications.client.ts  # Client-side notification renderers
+├── notifications.client.ts  # Client-side notification renderers
+└── encryption.ts         # Tenant data encryption maps (defaultEncryptionMaps) for sensitive / GDPR fields
 ```
 
 Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
 
+## Mandatory Module Mechanisms (every module MUST use these — no DIY substitutes)
+
+When the user asks to **create a new application** or a **new module**, do not invent your own routing, auth, persistence, forms, or caching. The framework provides one canonical primitive for each concern. If a feature is not on this list and not in the Task → Context Map, ask before adding it — do not roll your own.
+
+| Concern | Canonical mechanism | Where to learn it |
+|---|---|---|
+| Module structure & auto-discovery | `src/modules/<id>/{api,backend,frontend,data,subscribers,workers,widgets}` + `index.ts` + `src/modules.ts` (`from: '@app'`) — discovered by `yarn generate` | `.ai/skills/module-scaffold/SKILL.md`, `.ai/guides/core.md` → Module Files; <https://docs.open-mercato.dev/framework/modules/overview> |
+| **Backend admin pages** | Auto-discovered files under `src/modules/<id>/backend/**`, paired `page.meta.ts` with `requireAuth` + `requireFeatures` + `pageGroup`/`pageGroupKey`/`pageOrder` | `.ai/skills/backend-ui-design/SKILL.md`, `.ai/skills/module-scaffold/references/navigation-patterns.md`; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
+| **Frontend public pages** | Auto-discovered files under `src/modules/<id>/frontend/**`. Customer portal pages live under `frontend/[orgSlug]/portal/<path>/page.tsx` with `requireCustomerAuth` / `requireCustomerFeatures` in `page.meta.ts` | `.ai/guides/ui.md` → Portal Extension; <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
+| **API routes** | Files under `src/modules/<id>/api/**/route.ts` exporting handlers + `metadata` (per-method `requireAuth` / `requireFeatures`) + `openApi`. NEVER write a top-level `export const requireAuth` — the registry no longer recognises it | `.ai/guides/core.md` → API Routes; <https://docs.open-mercato.dev/framework/api/api-development-guide> |
+| **CRUD APIs (factory)** | `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory`. Always set `indexer` so query-index coverage stays correct. Custom (non-`makeCrudRoute`) write routes MUST call `validateCrudMutationGuard` before the mutation and `runCrudMutationGuardAfterSuccess` after success | `.ai/skills/module-scaffold/SKILL.md` → Create API Routes; <https://docs.open-mercato.dev/framework/api/crud-factory> |
+| **CRUD forms in admin** | `<CrudForm entityId apiPath mode fields />` from `@open-mercato/ui/backend/CrudForm`; helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never raw `<form>`, never raw `fetch` | `.ai/skills/backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
+| **DataTables in admin** | `<DataTable entityId apiPath title columns />` from `@open-mercato/ui/backend/DataTable`. Keep `entityId` and `extensionTableId` stable so widget injection (columns, row actions, bulk actions, filters, toolbar) keeps working | `.ai/skills/backend-ui-design/SKILL.md`; <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
+| **Authorization (RBAC)** | Declare features in `<module>/acl.ts`, grant them in `<module>/setup.ts` `defaultRoleFeatures`, gate pages and routes with `requireFeatures` in `metadata` / `page.meta.ts`. NEVER use `requireRoles` (role names mutate). Run `yarn mercato auth sync-role-acls` after adding new features | `.ai/guides/core.md` → Access Control; <https://docs.open-mercato.dev/framework/rbac/overview> |
+| **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/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/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> |
+| **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.
+
 ## 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.
@@ -156,9 +181,16 @@ Register in `src/modules.ts`: `{ id: '<id>', from: '@app' }`
    **Dashboards fallback rule.** When the user (or the `trim-unused-modules` skill) disables the `dashboards` module, you MUST update `src/app/(backend)/backend/page.tsx` so it no longer renders `<DashboardScreen />`. Replace the dashboard render with a `redirect(...)` to the first enabled backend page for the current user — preferring pages already registered in the main sidebar group and respecting the admin/superadmin role of the caller. Otherwise `/backend` will crash at build or request time because the removed module no longer ships `DashboardScreen`. Always fall back to `/backend/profile` only if no other backend page is available.
 9. **New features MUST be visible to default roles immediately.** Every time you add a new feature ID (e.g. `my_module.view`, `my_module.manage`) to `src/modules/<module>/acl.ts`, you MUST also (a) add that feature to `defaultRoleFeatures` in the same module's `setup.ts` so the admin role and any other appropriate default roles get it on every tenant setup; and (b) run `yarn mercato auth sync-role-acls` so existing tenants pick up the new feature without a reinstall. Use `--tenant <tenantId>` only when the user asks to target one tenant. Do this automatically unless the user has explicitly said otherwise — the user should see the features you are building, not stare at a blank admin because their role is missing a grant. Feature IDs are FROZEN once shipped; if a rename is required, add the new ID alongside, grant it, and keep the old one as a deprecated alias.
 10. **Strict Design System alignment for every UI change.** Any UI you add or edit MUST use the Open Mercato design system components and tokens. No hardcoded Tailwind status colors (`text-red-500`, `bg-green-100`, etc.) — use semantic tokens (`text-status-error-text`, `bg-status-success-bg`, …). No arbitrary text sizes (`text-[11px]`, `text-[13px]`) — use the Tailwind scale (`text-xs`, `text-sm`, `text-base`, `text-lg`, `text-xl`, `text-2xl`) or the `text-overline` token for 11px uppercase labels. In PAGE BODY UI, use `lucide-react` icons (never inline `<svg>`). Use `StatusBadge` for entity status, `Alert` for inline feedback, `FormField` for standalone form inputs, `SectionHeader` for detail-page section headings, `CollapsibleSection` for collapsible regions, `LoadingMessage`/`Spinner`/`DataLoader` for async states, and `EmptyState` (or DataTable's `emptyState` prop) for empty lists. For list pages, follow `.ai/skills/backend-ui-design/SKILL.md` and prefer the `DataTable` host pattern shown there (`entityId`, `apiPath`, stable `extensionTableId`, and explicit pagination props when you own the data source). Every dialog MUST support `Cmd/Ctrl+Enter` to submit and `Escape` to cancel. Every icon-only button MUST have an `aria-label`. These rules apply to `src/modules/<module>/backend/**` and `src/modules/<module>/frontend/**` alike.
-11. **BEFORE writing ANY code**, you MUST:
+11. **Sensitive / GDPR fields MUST go through the encryption-maps mechanism — never hand-rolled.** The framework provides per-tenant DEKs, KMS-backed key resolution, and a declarative field-level map. Whenever the user asks for "this field encrypted", "store this securely", "this is PII", "GDPR", "encryption at rest", or you are designing a column that will hold names, addresses, contacts, free-text notes about people, integration secrets/credentials, or any data subject to a data-processing agreement, you MUST:
+   - Declare the entity + field list in `src/modules/<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` (type imported from `@open-mercato/shared/modules/encryption`).
+   - Read those columns via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find` (passing `tenantId` and `organizationId`). Never use raw `em.find` on encrypted columns.
+   - For deterministic-lookup fields (e.g., login email), declare a sibling `hashField` in the map so equality lookups still work.
+   - Run `yarn mercato entities seed-encryption --tenant <tenantId>` after adding maps so existing tenants pick them up; new tenants get them automatically during `auth:setup`.
+   - Treat hand-rolled AES, raw `crypto.subtle`, custom KMS calls, or storing plaintext "for now" as broken — rewrite via the maps. See `.ai/skills/data-model-design/SKILL.md` → Sensitive Data and Encryption Maps and <https://docs.open-mercato.dev/user-guide/encryption>.
+12. **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
+   - Read the **Mandatory Module Mechanisms** section above to confirm which canonical primitives apply (CRUD factory, CrudForm, DataTable, RBAC, multi-tenant scoping, encryption maps, cache, events) — do not invent your own substitutes
    - Only then proceed to implementation
    - If your task matches multiple rows, load ALL listed files
    - **Do NOT skip this step.** The guides contain canonical import paths, required patterns, and conventions that CANNOT be reliably inferred from existing code alone. Skipping leads to wrong imports, missing conventions, and rework.
@@ -197,7 +229,8 @@ import { resolveTranslations } from '@open-mercato/shared/lib/i18n/server'
 import { apiCall, apiCallOrThrow } from '@open-mercato/ui/backend/utils/apiCall'
 
 // CRUD forms
-import { CrudForm, createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/crud'
+import { CrudForm, type CrudField, type CrudFormGroup } from '@open-mercato/ui/backend/CrudForm'
+import { createCrud, updateCrud, deleteCrud } from '@open-mercato/ui/backend/utils/crud'
 import { createCrudFormError } from '@open-mercato/ui/backend/utils/serverErrors'
 
 // UI components (MUST use — never raw <button>)

package/dist/agentic/shared/ai/qa/tests/playwright.config.ts

@@ -1,9 +1,14 @@
 import { defineConfig } from '@playwright/test'
 import path from 'node:path'
+import { fileURLToPath } from 'node:url'
 import { discoverIntegrationSpecFiles } from '@open-mercato/cli/lib/testing/integration-discovery'
 
 const captureScreenshots = process.env.PW_CAPTURE_SCREENSHOTS === '1'
 const isGitHubActions = process.env.GITHUB_ACTIONS === 'true'
+// Standalone apps generated from this template declare `"type": "module"`,
+// so the CommonJS `__dirname` is undefined when Playwright loads this config
+// under the Node ESM loader. Reconstruct it from `import.meta.url`.
+const __dirname = path.dirname(fileURLToPath(import.meta.url))
 const projectRoot = path.resolve(__dirname, '..', '..', '..')
 const qaTestResultsRoot = path.join(projectRoot, '.ai', 'qa', 'test-results')
 const normalizePath = (value: string) => value.split(path.sep).join('/')

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

@@ -16,7 +16,8 @@ Design entities, relationships, and manage the migration lifecycle following Ope
 5. [Cross-Module References](#5-cross-module-references)
 6. [Migration Lifecycle](#6-migration-lifecycle)
 7. [Advanced Patterns](#7-advanced-patterns)
-8. [Anti-Patterns](#8-anti-patterns)
+8. [Sensitive Data and Encryption Maps](#8-sensitive-data-and-encryption-maps)
+9. [Anti-Patterns](#9-anti-patterns)
 
 ---
 
@@ -483,7 +484,89 @@ export class TicketHistory {
 
 ---
 
-## 8. Anti-Patterns
+## 8. Sensitive Data and Encryption Maps
+
+When the developer asks for "we need this column encrypted", "store this securely", "this is PII", "GDPR", or "encryption at rest" — and whenever you are designing a column that will hold names, addresses, contact information, free-text notes about people, integration credentials, secrets, or any data subject to a data-processing agreement — use the framework's **encryption-maps mechanism**. Do NOT hand-roll AES, raw `crypto.subtle`, custom KMS calls, or "TODO encrypt later" stubs.
+
+The mechanism gives you:
+
+- Per-tenant Data Encryption Keys (DEKs) resolved through the configured KMS (Vault by default, env-fallback in dev).
+- Declarative, per-entity, per-field encryption with optional deterministic-hash sibling columns for equality lookups (for example login by email).
+- Boot-time auto-application: every enabled module's `defaultEncryptionMaps` is collected during `auth:setup` and applied when `TENANT_DATA_ENCRYPTION=yes`.
+- A `findWithDecryption` / `findOneWithDecryption` read API that transparently decrypts on read.
+
+### When encryption is mandatory
+
+| Field example | Encrypt? |
+|---|---|
+| First name, last name, preferred name | Yes |
+| Email, phone | Yes — usually with a `hashField` for lookups |
+| Postal address (line 1/2, city, region, postal code, country) | Yes |
+| Free-text comments / notes / activity bodies that mention people | Yes |
+| Integration secrets, API keys, OAuth tokens, webhook signing keys | Yes |
+| Document numbers (tax IDs, national IDs) | Yes |
+| Status enums, counters, timestamps, FKs, currency codes | No |
+| Public catalog metadata (product titles for a public storefront) | Usually no |
+
+If you are unsure, default to encrypting and confirm with the user — re-introducing encryption later requires a backfill, but turning it off later is a single map edit.
+
+### Declare the map in `<module>/encryption.ts`
+
+```typescript
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: '<module_id>:<entity>',  // matches the entity's table id (colon-separated)
+    fields: [
+      { field: 'first_name' },
+      { field: 'last_name' },
+      { field: 'phone' },
+      // Sibling deterministic hash for equality lookups (e.g. login by email).
+      // Add a matching `<field>_hash varchar` column to the entity.
+      { field: 'email', hashField: 'email_hash' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps
+```
+
+### Read with decryption — never raw `em.find`
+
+```typescript
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+// Signature: (em, entityName, where, options?, scope?). MikroORM FindOptions go in slot 4
+// (pass `undefined` if you have none), the decryption scope `{ tenantId, organizationId }` in slot 5.
+const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
+const single  = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
+```
+
+Calling `em.find` on an encrypted column returns ciphertext, breaks search, and silently leaks bug surface. The `findWithDecryption` family is the one entry point.
+
+### Apply maps to existing tenants
+
+```bash
+yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
+```
+
+New tenants pick up the maps automatically during `auth:setup`. Toggling the **Encrypted** flag on a custom field via the admin UI also only applies to data written **after** the change — backfill historical plaintext rows by running `yarn mercato entities rotate-encryption-key --tenant <tenantId> --org <organizationId>` (without `--old-key` it skips already-encrypted fields and just encrypts plaintext). Use `yarn mercato entities decrypt-database` to roll back. For full UI flows and CLI options see <https://docs.open-mercato.dev/user-guide/encryption>.
+
+### Vector search caveat
+
+The `vector` module stores raw embeddings unencrypted in the vector store (e.g. pgvector). Even though the source text is decrypted only transiently to compute embeddings, treat the embeddings as sensitive: avoid embedding raw high-sensitivity text and rely on disk-level / managed-database encryption-at-rest for the vector column.
+
+### Environment switches
+
+- `TENANT_DATA_ENCRYPTION=yes|no` (default `yes`) — set to `no` to run the hooks as no-op (validation still applies).
+- `TENANT_DATA_ENCRYPTION_DEBUG=yes` — log map evaluation, KMS calls, cache hits.
+- `VAULT_ADDR` / `VAULT_TOKEN` / `VAULT_KV_PATH` — HashiCorp Vault KMS configuration.
+- `TENANT_DATA_ENCRYPTION_FALLBACK_KEY` — local/dev fallback key when Vault is unavailable. In dev, `AUTH_SECRET` / `NEXTAUTH_SECRET` is used as a last resort; production falls back to noop KMS.
+
+---
+
+## 9. Anti-Patterns
 
 | Anti-Pattern | Problem | Correct Pattern |
 |-------------|---------|-----------------|
@@ -498,6 +581,10 @@ export class TicketHistory {
 | Storing arrays as comma-separated strings | Can't query, no integrity | Use `jsonb` arrays or junction tables |
 | UUID FK without index | Slow joins | Always `@Index()` on FK columns |
 | Nullable required fields | Data integrity issues | Use `!` assertion for required, `null` for optional |
+| Hand-rolled AES / `crypto.subtle` / custom KMS for sensitive columns | Per-tenant key isolation, hash lookups, key rotation, and admin UI all break | Declare `<module>/encryption.ts` with `defaultEncryptionMaps`; let the framework manage DEKs and Vault |
+| Reading encrypted columns with raw `em.find` / `em.findOne` | Returns ciphertext, breaks search, silent data corruption | Use `findWithDecryption` / `findOneWithDecryption` with `{ tenantId, organizationId }` |
+| Storing PII as plaintext "for now" / TODO comments | GDPR violation, leaks at rest, expensive backfill later | Encrypt from day one; toggling later only protects new writes |
+| Encrypting an `email` column without a `hashField` | Login / equality lookups stop working | Declare a sibling `hashField` (e.g. `email_hash`) in the encryption map and add the matching `varchar` column |
 
 ---
 
@@ -515,7 +602,8 @@ export class TicketHistory {
 - **MUST** specify `length` on all `varchar` columns
 - **MUST NOT** use ORM relationship decorators across module boundaries
 - **MUST NOT** rename or drop columns in a single release
-- **MUST NOT** store sensitive data without encryption (use `findWithDecryption`)
+- **MUST** declare encrypted columns in `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]`, and read them via `findWithDecryption` / `findOneWithDecryption` from `@open-mercato/shared/lib/encryption/find` — see section 8
+- **MUST NOT** hand-roll AES / KMS calls or store sensitive columns as plaintext "for now" — use the encryption-maps mechanism in section 8
 - Use `jsonb` for flexible/nested data, proper columns for queryable/sortable data
 - Use junction tables for many-to-many relationships
 - Derive TypeScript types from Zod schemas, never duplicate type definitions

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

@@ -40,14 +40,18 @@ For every piece of code, enforce these code-review rules inline:
 | Area | Rule |
 |------|------|
 | Types | No `any` — use zod + `z.infer` |
-| API routes | Export `openApi` and `metadata` with auth guards |
-| Entities | Standard columns, snake_case, UUID PKs, `organization_id` + `tenant_id` |
+| API routes | Export `openApi` and per-method `metadata` with `requireAuth` / `requireFeatures` (no top-level `export const requireAuth`) |
+| **CRUD APIs** | **Use `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory`. Custom write routes MUST call `validateCrudMutationGuard` before the mutation and `runCrudMutationGuardAfterSuccess` after success. See `AGENTS.md` → Mandatory Module Mechanisms.** |
+| Entities | Standard columns, snake_case, UUID PKs, indexed `organization_id` + `tenant_id` |
 | Security | `findWithDecryption`, tenant scoping, zod validation |
-| UI | `CrudForm`/`DataTable`, `apiCall`, `flash()`, `LoadingMessage`/`ErrorMessage` |
-| Events | `createModuleEvents()` with `as const`, subscribers export `metadata` |
+| **Encryption maps** | **For every PII / GDPR-relevant column the phase touches, declare in `<module>/encryption.ts` exporting `defaultEncryptionMaps` (type from `@open-mercato/shared/modules/encryption`). Reads via `findWithDecryption` / `findOneWithDecryption` (5-arg `(em, entity, where, options?, scope?)`). Equality-lookup columns declare a sibling `hashField`. NEVER hand-rolled AES/KMS, `crypto.subtle`, or "encrypt later" stubs. See `AGENTS.md` → CRITICAL Rule #11 (Encryption maps) + the "Encryption maps" row of the Mandatory Module Mechanisms table; `.ai/skills/data-model-design/SKILL.md` § Sensitive Data and Encryption Maps; `.ai/skills/module-scaffold/SKILL.md` § Encryption maps.** |
+| UI | `<CrudForm>`/`<DataTable>` (with stable `entityId` + `extensionTableId`), `apiCall` (never raw `fetch`), `flash()`, `<LoadingMessage>`/`<ErrorMessage>` |
+| **Design System** | **Semantic status tokens (no `text-red-*` / `bg-green-*`); Tailwind text scale (no `text-[13px]` / `text-[11px]`); shared primitives `StatusBadge` / `Alert` / `FormField` / `SectionHeader` / `CollapsibleSection` / `LoadingMessage` / `Spinner` / `DataLoader` / `EmptyState`; lucide-react icons in PAGE BODY (never inline `<svg>`); `aria-label` on every icon-only button; Boy Scout rule on touched lines. See `AGENTS.md` → CRITICAL Rule #10 (Strict Design System alignment) + `.ai/skills/backend-ui-design/SKILL.md`.** |
+| **Cache** | **Resolve via DI (`container.resolve('cache')`); tag with `tenant:<id>` / `org:<id>`; declare invalidation per write path. NEVER `new Redis(...)` or raw SQLite.** |
+| Events | `createModuleEvents()` with `as const`, subscribers export `metadata`; cross-module side effects via subscribers, never direct imports |
 | i18n | `useT()` client, `resolveTranslations()` server, no hardcoded strings |
 | Imports | Package-level `@open-mercato/<pkg>/...` for framework imports |
-| Mutations | `useGuardedMutation` when not using CrudForm |
+| Mutations | `useGuardedMutation` when not using CrudForm; pass `retryLastMutation` in injection context |
 | Keyboard | `Cmd/Ctrl+Enter` submit, `Escape` cancel on dialogs |
 | Naming | Modules plural snake_case, events `module.entity.past_tense`, features `module.action` |
 

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

@@ -41,8 +41,9 @@ Before writing any code, ask the developer:
    - [ ] Background workers
    - [ ] CLI commands
    - [ ] Custom fields support
+   - [ ] **Sensitive / GDPR-relevant fields** (PII, contact info, addresses, free-text notes about people, integration credentials, secrets) — if yes, an `encryption.ts` declaring `defaultEncryptionMaps` is mandatory; see section 11 → Encryption maps
 
-If the developer provides a brief description, infer reasonable defaults and confirm.
+If the developer provides a brief description, infer reasonable defaults and confirm. When key fields include names, emails, phones, addresses, free-text comments, or external API keys, treat the encryption checkbox as `yes` by default and confirm with the user rather than skipping it silently.
 
 ---
 
@@ -57,6 +58,7 @@ src/modules/<module_id>/
 ├── setup.ts                    # Tenant init, role features
 ├── di.ts                       # Awilix DI registrations
 ├── events.ts                   # Typed event declarations (if needed)
+├── encryption.ts               # Tenant data encryption maps (only if entity has sensitive/GDPR fields)
 ├── data/
 │   ├── entities.ts             # MikroORM entity classes
 │   └── validators.ts           # Zod validation schemas
@@ -178,7 +180,7 @@ Use `makeCrudRoute` for standard CRUD. Each HTTP method lives in its own file.
 **File**: `src/modules/<module_id>/api/get/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 
 const handler = makeCrudRoute({
@@ -201,7 +203,7 @@ export const openApi = {
 **File**: `src/modules/<module_id>/api/post/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 import { create<Entity>Schema } from '../../data/validators'
 
@@ -225,7 +227,7 @@ export const openApi = {
 **File**: `src/modules/<module_id>/api/put/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 import { update<Entity>Schema } from '../../data/validators'
 
@@ -249,7 +251,7 @@ export const openApi = {
 **File**: `src/modules/<module_id>/api/delete/<entities>.ts`
 
 ```typescript
-import { makeCrudRoute } from '@open-mercato/shared/lib/crud/make-crud-route'
+import { makeCrudRoute } from '@open-mercato/shared/lib/crud/factory'
 import { <Entity> } from '../../data/entities'
 
 const handler = makeCrudRoute({
@@ -346,7 +348,7 @@ export const metadata = {
 
 ```tsx
 'use client'
-import { CrudForm } from '@open-mercato/ui/backend/crud'
+import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 
 export default function Create<Entity>Page() {
@@ -384,7 +386,7 @@ export const metadata = {
 
 ```tsx
 'use client'
-import { CrudForm } from '@open-mercato/ui/backend/crud'
+import { CrudForm } from '@open-mercato/ui/backend/CrudForm'
 import { useT } from '@open-mercato/shared/lib/i18n/context'
 
 export default function Edit<Entity>Page({ params }: { params: { id: string } }) {
@@ -573,6 +575,52 @@ export default function registerCli(program: any) {
 }
 ```
 
+### Encryption maps (sensitive / GDPR-relevant fields)
+
+**Mandatory** when the entity stores PII, contact info, addresses, free-text notes about people, integration credentials, secrets, or anything subject to a data-processing agreement. Do NOT hand-roll AES, KMS calls, or "TODO encrypt later" stubs — the framework provides per-tenant DEKs and a declarative field-level map.
+
+**File**: `src/modules/<module_id>/encryption.ts`
+
+```typescript
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: '<module_id>:<entity>',  // matches data/entities.ts table id, colon-separated
+    fields: [
+      { field: 'first_name' },
+      { field: 'last_name' },
+      { field: 'phone' },
+      // Add a hashField for deterministic equality lookups (e.g. login by email):
+      { field: 'email', hashField: 'email_hash' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps
+```
+
+**Read paths** — never `em.find` an encrypted column directly:
+
+```typescript
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+// Signature: (em, entityName, where, options?, scope?) — MikroORM FindOptions in slot 4
+// (pass `undefined` when none), decryption scope in slot 5.
+const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
+const single  = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
+```
+
+**Apply to existing tenants** after declaring or updating maps:
+
+```bash
+yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
+```
+
+New tenants pick up `defaultEncryptionMaps` automatically during `auth:setup`. Toggling the **Encrypted** flag for a field only applies to data written **after** the change — historical plaintext rows stay as they were until backfilled via `yarn mercato entities rotate-encryption-key --tenant <tenantId> --org <organizationId>` (without `--old-key` the command only encrypts plaintext and skips already-encrypted fields). Use `yarn mercato entities decrypt-database` to roll back. For end-to-end usage and admin UI flows see <https://docs.open-mercato.dev/user-guide/encryption>.
+
+> Tip: when `email` (or any other column) needs deterministic lookups while encrypted, declare a sibling `hashField` in the map and add a matching `varchar` column to the entity. The framework keeps the hash in sync on writes; queries can target the hash instead of the cleartext column.
+
 ---
 
 ## 12. Wire & Verify
@@ -658,3 +706,5 @@ yarn dev               # Start dev server
 - **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
+- **MUST** declare `<module>/encryption.ts` exporting `defaultEncryptionMaps` whenever the entity stores sensitive / GDPR-relevant fields (PII, contact info, addresses, free-text notes about people, integration credentials, secrets) — and read those columns via `findWithDecryption` / `findOneWithDecryption`
+- **MUST NOT** hand-roll AES/KMS calls or store "we'll encrypt this later" plaintext for sensitive columns — use the encryption-maps mechanism described in section 11 → Encryption maps

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

@@ -60,6 +60,9 @@ Use the [Specification Template](references/spec-template.md). Adapt if needed,
 3. **Singularity Law**: Singular naming for entities, commands, events, feature IDs.
 4. **Undo Contract**: Is the "Undo" logic as detailed as the "Execute"?
 5. **Module Isolation**: Using Event Bus for side effects or cheating with direct imports?
+6. **Canonical Mechanisms**: Does the spec reach for the framework primitives (`makeCrudRoute`, `<CrudForm>`, `<DataTable>`, `apiCall` / `useGuardedMutation`, DI-resolved cache, `createModuleEvents`) or invent its own substitute? See `AGENTS.md` → **Mandatory Module Mechanisms** for the full canon and links. No raw `fetch`, no raw `<form>`, no `new Redis(...)`, no manual cross-module ORM joins.
+7. **Sensitive Data**: For every PII / GDPR / address / contact / free-text-about-people / integration-credential column the spec proposes, does it declare an `encryption.ts` `defaultEncryptionMaps` entry and route reads through `findWithDecryption`? See `AGENTS.md` → CRITICAL Rule #11 (Encryption maps) + the "Encryption maps for sensitive data" row of the Mandatory Module Mechanisms table and `.ai/skills/data-model-design/SKILL.md` § Sensitive Data and Encryption Maps. No hand-rolled AES, no `crypto.subtle`, no "TODO encrypt later".
+8. **Design System**: Does every UI mock / className snippet in the spec match the DS canon — semantic status tokens (no `text-red-*` / `bg-green-*`), Tailwind text scale (no `text-[11px]` / `text-[13px]`), shared primitives (`StatusBadge`, `Alert`, `FormField`, `SectionHeader`, `CollapsibleSection`, `LoadingMessage` / `Spinner` / `DataLoader`, `EmptyState`), lucide-react icons in page body (never inline `<svg>`), dialog `Cmd/Ctrl+Enter` submit + `Escape` cancel, `aria-label` on every icon-only button? See `AGENTS.md` → CRITICAL Rule #10 (Strict Design System alignment for every UI change) and `.ai/skills/backend-ui-design/SKILL.md`. Specs that touch existing pages MUST honour the Boy Scout rule.
 
 ## Quick Rule Reference
 
@@ -68,9 +71,15 @@ Use the [Specification Template](references/spec-template.md). Adapt if needed,
 - **`organization_id`** is mandatory for all tenant-scoped entities.
 - **Undoability** is the default for state changes.
 - **Zod validation** for all API inputs.
+- **Encryption maps** for every sensitive / GDPR-relevant column (declare in `<module>/encryption.ts`, read via `findWithDecryption`) — see `AGENTS.md` → Data Encryption.
+- **Canonical primitives** for CRUD APIs (`makeCrudRoute`), backend forms (`CrudForm`), tables (`DataTable`), HTTP (`apiCall` — never raw `fetch`), non-`CrudForm` writes (`useGuardedMutation`), cache (DI-resolved `@open-mercato/cache`), events (`createModuleEvents`) — see `AGENTS.md` → Mandatory Module Mechanisms.
+- **Design System** tokens and shared UI primitives — no hardcoded status colors, no arbitrary text sizes, no inline `<svg>` in page-body UI. See `AGENTS.md` → Design System.
 
 ## Reference Materials
 
 - [Spec Template](references/spec-template.md)
-- [Spec Checklist](references/spec-checklist.md)
-- [AGENTS.md](../../../AGENTS.md)
+- [Spec Checklist](references/spec-checklist.md) — § 3 covers encryption maps; § 5 covers canonical mechanisms + DS
+- [AGENTS.md](../../../AGENTS.md) — Mandatory Module Mechanisms table; CRITICAL Rule #10 (Design System); CRITICAL Rule #11 (Encryption maps)
+- [`.ai/skills/data-model-design/SKILL.md`](../data-model-design/SKILL.md) → Sensitive Data and Encryption Maps
+- [`.ai/skills/module-scaffold/SKILL.md`](../module-scaffold/SKILL.md) → Encryption maps
+- [`.ai/skills/backend-ui-design/SKILL.md`](../backend-ui-design/SKILL.md) — DS-compliant pages

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

@@ -19,26 +19,42 @@ Every item must be answered in the spec or marked N/A with justification.
 
 ## 3. Data Integrity & Security
 
-- [ ] Entities include `id`, `organization_id`, `created_at`, `updated_at`
+- [ ] Entities include `id`, `organization_id`, `tenant_id`, `created_at`, `updated_at`, `deleted_at`, `is_active`
 - [ ] Write operations define transaction boundaries
 - [ ] Input validation uses zod schemas
 - [ ] All user input validated before business logic/persistence
-- [ ] Auth guards are declared (`requireAuth`, `requireRoles`, `requireFeatures`)
-- [ ] Tenant isolation: every scoped query filters by `organization_id`
+- [ ] Auth guards declared per-method in `metadata` (`requireAuth`, `requireFeatures`) — never legacy top-level `export const requireAuth`
+- [ ] Tenant isolation: every scoped query filters by `organization_id` (and `tenant_id` where applicable)
+- [ ] **Encryption maps mechanism is used (no hand-rolled crypto).** For every PII / GDPR-relevant column the spec proposes — names, addresses, contacts, free-text notes about people, integration credentials, secrets, document numbers — the spec MUST declare them in a module-level `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]` (type from `@open-mercato/shared/modules/encryption`). Reads MUST go through `findWithDecryption` / `findOneWithDecryption` (5-arg `(em, entity, where, options?, scope?)`) from `@open-mercato/shared/lib/encryption/find`. Equality-lookup columns (e.g. login email) declare a sibling `hashField`. No `crypto.subtle`, no custom KMS calls, no "TODO encrypt later". See `AGENTS.md` → CRITICAL Rule #11 (Encryption maps) + the "Encryption maps for sensitive data" row of the Mandatory Module Mechanisms table; `.ai/skills/data-model-design/SKILL.md` § Sensitive Data and Encryption Maps.
 
 ## 4. Commands, Events & Naming
 
 - [ ] Naming is singular and consistent
 - [ ] All mutations are commands with undo logic
-- [ ] Events declared in `events.ts` before emitting
+- [ ] Events declared in `<module>/events.ts` via `createModuleEvents({ moduleId, events } as const)` before emitting; cross-module side effects use `subscribers/*.ts`, never direct cross-module imports
 - [ ] Side-effect reversibility is documented
 
-## 5. API & UI
+## 5. API & UI — Canonical Mechanisms
 
 - [ ] API contracts are complete (request/response/errors)
 - [ ] Routes include `openApi` expectations
-- [ ] UI uses `CrudForm`, `DataTable`, and shared primitives
-- [ ] i18n keys are planned for user-facing strings
+- [ ] **Canonical mechanisms — no DIY substitutes.** The spec MUST reach for the framework primitives, not invent its own. See `AGENTS.md` → **Mandatory Module Mechanisms**.
+  - [ ] **CRUD APIs** use `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory`. Custom write routes call `validateCrudMutationGuard` before mutation and `runCrudMutationGuardAfterSuccess` after.
+  - [ ] **API route files export `metadata`** with per-method `requireAuth` / `requireFeatures` (no top-level `export const requireAuth`).
+  - [ ] **Backend forms** use `<CrudForm>` from `@open-mercato/ui/backend/CrudForm` with helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`, throwing `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors` for field-level errors. No raw `<form>`, no raw `fetch`.
+  - [ ] **Lists** use `<DataTable entityId apiPath columns />` from `@open-mercato/ui/backend/DataTable` with stable `entityId` / `extensionTableId` so widget injection (columns / row actions / bulk actions / filters / toolbar) keeps working.
+  - [ ] **HTTP clients** use `apiCall` / `apiCallOrThrow` / `readApiResultOrThrow` from `@open-mercato/ui/backend/utils/apiCall` — never raw `fetch`.
+  - [ ] **Non-`CrudForm` writes** are wrapped in `useGuardedMutation(...).runMutation(...)` and pass `retryLastMutation` in the injection context.
+  - [ ] **Cache** is resolved via DI (`container.resolve('cache')`) — never `new Redis(...)` or raw SQLite. Tags include `tenant:<id>` / `org:<id>`.
+- [ ] **Design System compliance for every UI mock and className snippet in the spec.** See `AGENTS.md` → CRITICAL Rule #10 (Strict Design System alignment) and `.ai/skills/backend-ui-design/SKILL.md`.
+  - [ ] Use semantic status tokens (`text-status-error-text`, `bg-status-success-bg`, `border-status-warning-border`, `text-status-info-icon`, `text-destructive`, `bg-destructive`) — NEVER hardcoded shades like `text-red-500`, `bg-green-100`, `text-amber-*`, `text-emerald-*`, `bg-blue-*`. Status tokens already cover dark mode; no `dark:` overrides.
+  - [ ] Use the Tailwind text scale (`text-xs` 12, `text-sm` 14, `text-base` 16, `text-lg` 18, `text-xl` 20, `text-2xl` 24) or `text-overline` for 11px uppercase labels — NEVER arbitrary sizes (`text-[11px]`, `text-[13px]`, `text-[15px]`, `p-[13px]`, `rounded-[24px]`, `z-[9999]`).
+  - [ ] Use shared primitives instead of raw HTML: `<Alert variant=...>` for inline status, `flash('msg', 'success|error|warning|info')` for toasts, `useConfirmDialog()` for destructive confirmations, `<StatusBadge>` for entity status, `<FormField label error>` to wrap form inputs, `<SectionHeader title count action>` for section headers, `<CollapsibleSection>` for collapsible regions, `<LoadingMessage>` / `<Spinner>` / `<DataLoader>` for async states, `<EmptyState>` (or DataTable `emptyState` prop) for empty lists.
+  - [ ] Use lucide-react icons in PAGE BODY UI (`Page`, `DataTable`, `CrudForm`, cards, buttons) — never inline `<svg>`. Sizes from the `size-{3|4|5|6}` scale; `strokeWidth` is not overridden per-instance. `page.meta.ts` icons follow the `React.createElement('svg', …)` pattern.
+  - [ ] Every dialog supports `Cmd/Ctrl+Enter` to submit and `Escape` to cancel.
+  - [ ] Every icon-only button has an `aria-label`.
+  - [ ] Boy Scout rule: when the spec edits an existing page, any line touched gets migrated to semantic tokens / DS scale.
+- [ ] i18n keys are planned for user-facing strings (`useT()` client-side, `resolveTranslations()` server-side; never hard-coded labels)
 - [ ] Pagination limits defined (`pageSize <= 100`)
 
 ## 6. Risks & Anti-Patterns
@@ -48,3 +64,4 @@ Every item must be answered in the spec or marked N/A with justification.
 - [ ] Does not introduce cross-module ORM links
 - [ ] Does not skip undoability for state changes
 - [ ] Does not mix MVP with speculative future phases
+- [ ] Does not introduce hand-rolled AES, raw `fetch`, raw `<form>`, `new Redis(...)`, or arbitrary Tailwind sizes / status colors

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-mercato-app",
-  "version": "0.6.1-develop.3090.06ab462170",
+  "version": "0.6.1-develop.3102.d6e7e6d57a",
   "type": "module",
   "description": "Create a new Open Mercato application",
   "main": "./dist/index.js",

package/template/AGENTS.md

@@ -62,9 +62,12 @@ mercato test coverage
 # Generate code from modules
 yarn generate
 
-# Manually purge structural navigation/sidebar caches when needed
+# Manually purge structural caches when needed (Redis nav:* + Turbopack barrel mtimes)
 yarn mercato configs cache structural --all-tenants
 
+# Escape hatch: clear .next/cache/turbopack when Turbopack still serves a stale chunk
+yarn dev:reset
+
 # Database operations
 yarn db:generate    # Generate/probe migrations; keep or write only scoped SQL and update the touched snapshot
 yarn db:migrate     # Run migrations
@@ -210,7 +213,7 @@ Practical consequences:
 Standalone apps consume the AI framework from `@open-mercato/ai-assistant` (in `node_modules/`). The same conventions used in the monorepo apply here:
 
 - Add a typed agent for a new module by creating `<module>/ai-agents.ts` + `<module>/ai-tools.ts` at the **module root**. Run `yarn generate` after.
-- Add inline UI widgets (record cards, custom server-emitted parts) per the [UI Parts guide](https://docs.openmercato.dev/framework/ai-assistant/ui-parts).
+- Add inline UI widgets (record cards, custom server-emitted parts) per the [UI Parts guide](https://docs.open-mercato.dev/framework/ai-assistant/ui-parts).
 - Replace or disable an agent / tool that another module shipped through three paths: extra `aiAgentOverrides` / `aiToolOverrides` exports on the existing `<module>/ai-agents.ts` / `<module>/ai-tools.ts` (per-module), inline on a `ModuleEntry` in `src/modules.ts` (per-app), or programmatically via `applyAiAgentOverrides({...})` / `applyAiToolOverrides({...})` from `@open-mercato/ai-assistant`. `null` disables; a definition replaces. Resolution order is **programmatic → modules.ts → file-based → base**.
 
 Example per-module override (preferred when the override should ship with a module):
@@ -320,6 +323,80 @@ Do this automatically unless the user has explicitly said otherwise. If the curr
 
 Feature IDs are FROZEN once shipped (they are stored in the DB as `role_features.feature_id`). If a rename is required, add the new ID, grant it, and keep the old one alongside as a deprecated alias until downstream data can be migrated.
 
+## Mandatory Module Mechanisms (no DIY substitutes)
+
+When building a new application or a new module under `src/modules/<id>/`, do not invent custom routing, auth, persistence, forms, or caching. The framework provides one canonical primitive for each concern. If a feature is not on this list, ask before adding it.
+
+| Concern | Canonical mechanism | Reference |
+|---|---|---|
+| Module structure & auto-discovery | `src/modules/<id>/{api,backend,frontend,data,subscribers,workers,widgets}` + `index.ts` + `src/modules.ts` (`from: '@app'`); discovered by `yarn generate` | <https://docs.open-mercato.dev/framework/modules/overview> |
+| Backend admin pages | Auto-discovered files under `backend/**` with paired `page.meta.ts` (`requireAuth`, `requireFeatures`, `pageGroup`, `pageGroupKey`, `pageOrder`) | <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
+| Frontend public pages and customer portal | Auto-discovered files under `frontend/**`. Portal pages live at `frontend/[orgSlug]/portal/<path>/page.tsx` with `requireCustomerAuth` / `requireCustomerFeatures` | <https://docs.open-mercato.dev/framework/modules/routes-and-pages> |
+| API routes (auth + OpenAPI) | `src/modules/<id>/api/**/route.ts` exporting handlers + `metadata` (per-method `requireAuth` / `requireFeatures`) + `openApi` | <https://docs.open-mercato.dev/framework/api/api-development-guide> |
+| CRUD APIs (factory) | `makeCrudRoute({ entity, entityId, operations, schema, indexer: { entityType } })` from `@open-mercato/shared/lib/crud/factory` | <https://docs.open-mercato.dev/framework/api/crud-factory> |
+| CRUD forms in admin | `<CrudForm entityId apiPath mode fields />` from `@open-mercato/ui/backend/CrudForm`; helpers `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud`; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never raw `<form>` or raw `fetch` | <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
+| DataTables in admin | `<DataTable entityId apiPath columns />` from `@open-mercato/ui/backend/DataTable`; keep `entityId` and `extensionTableId` stable so widget injection (columns, row actions, filters, toolbar) keeps working | <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
+| Authorization (RBAC) | Declare features in `<module>/acl.ts`, grant in `<module>/setup.ts` `defaultRoleFeatures`, gate routes/pages with `requireFeatures` in `metadata`. NEVER use `requireRoles`. Run `yarn mercato auth sync-role-acls` after adding features | <https://docs.open-mercato.dev/framework/rbac/overview> |
+| Multi-tenant scoping (default) | Every tenant-scoped entity MUST include indexed `organization_id` and `tenant_id`; every read/write filters by them. The CRUD factory injects the scope automatically — do not bypass it | <https://docs.open-mercato.dev/architecture/system-overview> |
+| **Encryption maps for sensitive data** | Declare `<module>/encryption.ts` exporting `defaultEncryptionMaps: ModuleEncryptionMap[]`; read via `findWithDecryption` / `findOneWithDecryption`. NEVER hand-roll AES/KMS — see the next section | <https://docs.open-mercato.dev/user-guide/encryption> |
+| Cache | Resolve from DI (`container.resolve('cache')`); never `new Redis(...)` or raw SQLite. Tag with `tenant:<id>` / `org:<id>` for tenant-scoped invalidation | <https://docs.open-mercato.dev/user-guide/cache-management> |
+| Background workers | `src/modules/<id>/workers/*.ts` exporting `metadata: { queue, id?, concurrency? }` + default handler. Never spin up custom queues | <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` | <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` | The `@open-mercato/shared` package (`node_modules/@open-mercato/shared/lib/i18n/`) |
+
+> Rule of thumb: if you reach for raw `fetch`, raw `<form>`, ad-hoc `crypto`, ad-hoc `Redis`, or a manual cross-module ORM join, stop and check the row above first.
+
+## Data Encryption (sensitive / GDPR-relevant fields)
+
+The framework ships a tenant-data-encryption mechanism with per-tenant DEKs, KMS-backed key resolution (Vault by default), declarative field-level maps per module, and deterministic-hash sibling columns for equality lookups. **Use it. Never hand-roll AES, `crypto.subtle`, or custom KMS calls. Never store sensitive columns as plaintext "for now".**
+
+When the user asks for "we need this column encrypted", "store this securely", "this is PII", "GDPR", or "encryption at rest" — and whenever you are designing a column that holds names, addresses, contact info, free-text notes about people, integration credentials, secrets, or anything subject to a data-processing agreement — declare an `encryption.ts` at the module root.
+
+```ts
+// src/modules/<module>/encryption.ts
+import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
+
+export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
+  {
+    entityId: '<module>:<entity>',
+    fields: [
+      { field: 'first_name' },
+      { field: 'last_name' },
+      { field: 'phone' },
+      // For deterministic equality lookups (e.g. login by email), add a sibling hash column.
+      { field: 'email', hashField: 'email_hash' },
+    ],
+  },
+]
+
+export default defaultEncryptionMaps
+```
+
+Read with decryption — never raw `em.find` / `em.findOne` on encrypted columns:
+
+```ts
+import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
+
+// Signature: (em, entityName, where, options?, scope?). Pass MikroORM FindOptions in slot 4
+// (or `undefined`), and the decryption scope in slot 5.
+const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
+const single  = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
+```
+
+Apply maps to existing tenants after declaring them (new tenants pick them up automatically during `auth:setup`):
+
+```bash
+yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
+```
+
+Notes:
+
+- Toggling the **Encrypted** flag on a custom field via the admin UI only applies to data written *after* the change. Backfill historical plaintext rows with `yarn mercato entities rotate-encryption-key --tenant <tenantId> --org <organizationId>` (without `--old-key` it only encrypts plaintext and skips already-encrypted fields). Use `yarn mercato entities decrypt-database` to roll back.
+- The `vector` module stores raw embeddings unencrypted in the vector store — treat embeddings as sensitive even when the source text is encrypted.
+- Env switches: `TENANT_DATA_ENCRYPTION` (default `yes`), `TENANT_DATA_ENCRYPTION_DEBUG`, Vault (`VAULT_ADDR` / `VAULT_TOKEN` / `VAULT_KV_PATH`), and dev fallback (`TENANT_DATA_ENCRYPTION_FALLBACK_KEY`).
+
+Full guide: <https://docs.open-mercato.dev/user-guide/encryption>.
+
 ## Design System (Strict — applies to every UI change)
 
 All UI added or edited in `src/modules/<module>/backend/**` or `src/modules/<module>/frontend/**` MUST follow the Open Mercato design system. Non-compliant code will be blocked in `auto-review-pr`.
@@ -401,6 +478,8 @@ Notes:
 
 The standalone template enables the `configs` module from `@open-mercato/core`, so `yarn mercato configs cache ...` is available here after installation. After structural changes such as enabling or disabling modules, adding or removing backend/frontend pages, or changing sidebar/navigation injections, run `yarn generate`. The generator now performs a best-effort structural cache purge automatically after successful generation; if the cache command is unavailable, generation still succeeds.
 
+The structural cache purge invalidates two layers: Redis `nav:*` cache keys and Turbopack's module-graph fingerprints (it bumps mtimes on every file in `.mercato/generated/` without changing content). When Turbopack still serves a stale compiled chunk after a structural change — typically because its own internal cache pinned a previous compile error — run `yarn dev:reset` to clear `.next/cache/turbopack` and restart `yarn dev`.
+
 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.
 
 ### Path Aliases

package/template/package.json.template

@@ -12,6 +12,7 @@
     "dev": "node ./scripts/dev.mjs",
     "dev:classic": "node ./scripts/dev.mjs --classic",
     "dev:verbose": "node ./scripts/dev.mjs --verbose",
+    "dev:reset": "node ./scripts/dev-reset.mjs",
     "build": "yarn generate && next build",
     "start": "mercato server start",
     "lint": "next lint",

package/template/scripts/dev-reset.mjs

@@ -0,0 +1,27 @@
+#!/usr/bin/env node
+import { fileURLToPath } from 'node:url'
+import path from 'node:path'
+import fs from 'node:fs'
+
+const here = path.dirname(fileURLToPath(import.meta.url))
+const appDir = path.resolve(here, '..')
+const targets = [
+  path.join(appDir, '.next', 'cache', 'turbopack'),
+  path.join(appDir, '.next', 'cache', 'webpack'),
+]
+
+let removed = 0
+for (const target of targets) {
+  if (!fs.existsSync(target)) continue
+  fs.rmSync(target, { recursive: true, force: true })
+  console.log(`🧹 [dev:reset] removed ${path.relative(appDir, target)}`)
+  removed += 1
+}
+
+if (removed === 0) {
+  console.log('🧹 [dev:reset] nothing to clean — .next/cache subdirectories already absent')
+}
+
+console.log('')
+console.log('✅ Turbopack/webpack cache cleared.')
+console.log('   Stop any running `yarn dev` and start it again to pick up fresh module output.')