create-mercato-app 0.6.7 → 0.6.8-develop.6874.1.982d6097d8

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (419) hide show
  1. package/README.md +72 -0
  2. package/agentic/claude-code/hooks/entity-migration-check.ts +32 -88
  3. package/agentic/codex/enforcement-rules.md +2 -16
  4. package/agentic/cursor/hooks/entity-migration-check.mjs +19 -50
  5. package/agentic/cursor/rules/entity-guard.mdc +9 -21
  6. package/agentic/cursor/rules/generated-guard.mdc +3 -5
  7. package/agentic/cursor/rules/open-mercato.mdc +3 -29
  8. package/agentic/guides/ai-workflows.md +76 -0
  9. package/agentic/guides/architecture.md +107 -0
  10. package/agentic/guides/backend-ui.md +80 -0
  11. package/agentic/guides/contracts.md +92 -0
  12. package/agentic/guides/extensions.md +121 -0
  13. package/agentic/guides/integrations.md +81 -0
  14. package/agentic/guides/module-system.md +12 -127
  15. package/agentic/guides/spec-delivery.md +22 -0
  16. package/agentic/guides/testing-debugging.md +80 -0
  17. package/agentic/shared/AGENTS.md.template +124 -311
  18. package/agentic/shared/ai/agentic.config.json +2 -0
  19. package/agentic/shared/ai/harness/README.md +50 -0
  20. package/agentic/shared/ai/harness/RELEASE.md +57 -0
  21. package/agentic/shared/ai/harness/cases.json +13680 -0
  22. package/agentic/shared/ai/harness/cases.schema.json +133 -0
  23. package/agentic/shared/ai/harness/fixtures/index.json +49 -0
  24. package/agentic/shared/ai/harness/fixtures/seeds.json +162 -0
  25. package/agentic/shared/ai/harness/generated-code-review-policy.md +21 -0
  26. package/agentic/shared/ai/harness/generated-code-review-response.schema.json +96 -0
  27. package/agentic/shared/ai/harness/generated-code-review-result.schema.json +172 -0
  28. package/agentic/shared/ai/harness/release-matrix.json +158 -0
  29. package/agentic/shared/ai/harness/release-result.schema.json +219 -0
  30. package/agentic/shared/ai/harness/result.schema.json +76 -0
  31. package/agentic/shared/ai/harness/routing-response.schema.json +12 -0
  32. package/agentic/shared/ai/harness/target-validation-result.schema.json +73 -0
  33. package/agentic/shared/ai/harness/validators.json +78 -0
  34. package/agentic/shared/ai/harness/writable-ast-oracles.mjs +2121 -0
  35. package/agentic/shared/ai/harness/writable-behavior-oracles.mjs +1096 -0
  36. package/agentic/shared/ai/lessons/_template.md +16 -0
  37. package/agentic/shared/ai/lessons.md +26 -3
  38. package/agentic/shared/ai/review-checklist.md +36 -0
  39. package/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md +21 -0
  40. package/agentic/shared/ai/skills/om-auto-review-pr/SKILL.md +4 -0
  41. package/agentic/shared/ai/skills/om-auto-upgrade-0.6.6-to-0.6.7/SKILL.md +98 -0
  42. package/agentic/shared/ai/skills/om-backend-ui-design/SKILL.md +20 -241
  43. package/agentic/shared/ai/skills/om-backend-ui-design/references/crud-surfaces.md +16 -0
  44. package/agentic/shared/ai/skills/om-backend-ui-design/references/frontend-and-design-system.md +53 -0
  45. package/agentic/shared/ai/skills/om-backend-ui-design/references/page-and-navigation.md +13 -0
  46. package/agentic/shared/ai/skills/om-backend-ui-design/references/quality-states.md +11 -0
  47. package/agentic/shared/ai/skills/om-build-workflow/SKILL.md +30 -0
  48. package/agentic/shared/ai/skills/om-build-workflow/references/activity-contracts.md +12 -0
  49. package/agentic/shared/ai/skills/om-build-workflow/references/durability-and-progress.md +13 -0
  50. package/agentic/shared/ai/skills/om-build-workflow/references/workflow-design.md +14 -0
  51. package/agentic/shared/ai/skills/om-create-ai-agent/SKILL.md +28 -0
  52. package/agentic/shared/ai/skills/om-create-ai-agent/references/attachments-and-overrides.md +12 -0
  53. package/agentic/shared/ai/skills/om-create-ai-agent/references/module-agents-and-tools.md +22 -0
  54. package/agentic/shared/ai/skills/om-create-ai-agent/references/orchestrator-agents.md +12 -0
  55. package/agentic/shared/ai/skills/om-create-ai-agent/references/surface-selector.md +19 -0
  56. package/agentic/shared/ai/skills/om-data-model-design/SKILL.md +16 -601
  57. package/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +19 -0
  58. package/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md +13 -0
  59. package/agentic/shared/ai/skills/om-data-model-design/references/schema-design.md +14 -0
  60. package/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md +10 -0
  61. package/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md +14 -310
  62. package/agentic/shared/ai/skills/om-eject-and-customize/references/decision-and-procedure.md +17 -0
  63. package/agentic/shared/ai/skills/om-evolve-harness/SKILL.md +29 -0
  64. package/agentic/shared/ai/skills/om-evolve-harness/references/case-template.md +100 -0
  65. package/agentic/shared/ai/skills/om-evolve-harness/references/case-workflow.md +16 -0
  66. package/agentic/shared/ai/skills/om-evolve-harness/references/owner-selection.md +17 -0
  67. package/agentic/shared/ai/skills/om-framework-context/SKILL.md +25 -0
  68. package/agentic/shared/ai/skills/om-framework-context/references/resolver-procedure.md +11 -0
  69. package/agentic/shared/ai/skills/om-framework-context/references/skew-and-escalation.md +13 -0
  70. package/agentic/shared/ai/skills/om-help/SKILL.md +15 -97
  71. package/agentic/shared/ai/skills/om-help/references/delivery-workflows.md +18 -0
  72. package/agentic/shared/ai/skills/om-help/references/task-families.md +20 -0
  73. package/agentic/shared/ai/skills/om-implement-spec/SKILL.md +33 -152
  74. package/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md +33 -0
  75. package/agentic/shared/ai/skills/om-implement-spec/references/planning-and-progress.md +40 -0
  76. package/agentic/shared/ai/skills/om-implement-spec/references/report-templates.md +27 -0
  77. package/agentic/shared/ai/skills/om-implement-spec/references/spec-resolution.md +24 -0
  78. package/agentic/shared/ai/skills/om-integration-builder/SKILL.md +24 -708
  79. package/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md +16 -0
  80. package/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md +14 -0
  81. package/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md +15 -0
  82. package/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md +12 -0
  83. package/agentic/shared/ai/skills/om-judge-agent-session/SKILL.md +34 -0
  84. package/agentic/shared/ai/skills/om-judge-agent-session/agents/openai.yaml +4 -0
  85. package/agentic/shared/ai/skills/om-judge-agent-session/references/agentic-setup.md +11 -0
  86. package/agentic/shared/ai/skills/om-judge-agent-session/references/input-normalization.md +31 -0
  87. package/agentic/shared/ai/skills/om-judge-agent-session/references/judge-workflow.md +39 -0
  88. package/agentic/shared/ai/skills/om-judge-agent-session/references/report-template.md +43 -0
  89. package/agentic/shared/ai/skills/om-judge-agent-session/references/rules.md +11 -0
  90. package/agentic/shared/ai/skills/om-module-scaffold/SKILL.md +20 -820
  91. package/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +19 -0
  92. package/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md +172 -0
  93. package/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md +12 -0
  94. package/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md +83 -0
  95. package/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md +21 -0
  96. package/agentic/shared/ai/skills/om-module-scaffold/references/planning.md +11 -0
  97. package/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md +22 -0
  98. package/agentic/shared/ai/skills/om-module-scaffold/references/verification.md +13 -0
  99. package/agentic/shared/ai/skills/om-share-this-session/SKILL.md +41 -0
  100. package/agentic/shared/ai/skills/om-share-this-session/references/agentic-setup.md +19 -0
  101. package/agentic/shared/ai/skills/om-share-this-session/references/bundle-preparation.md +44 -0
  102. package/agentic/shared/ai/skills/om-share-this-session/references/consent-and-review.md +39 -0
  103. package/agentic/shared/ai/skills/om-share-this-session/references/publication.md +20 -0
  104. package/agentic/shared/ai/skills/om-share-this-session/references/report-templates.md +57 -0
  105. package/agentic/shared/ai/skills/om-share-this-session/references/rules.md +11 -0
  106. package/agentic/shared/ai/skills/om-share-this-session/scripts/prepare-share-bundle.mjs +486 -0
  107. package/agentic/shared/ai/skills/om-system-extension/SKILL.md +19 -843
  108. package/agentic/shared/ai/skills/om-system-extension/references/extension-branches.md +18 -0
  109. package/agentic/shared/ai/skills/om-system-extension/references/mechanism-selector.md +27 -0
  110. package/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md +13 -0
  111. package/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md +41 -0
  112. package/agentic/shared/ai/skills/om-system-extension/references/verification.md +11 -0
  113. package/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md +15 -63
  114. package/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md +15 -0
  115. package/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +16 -467
  116. package/agentic/shared/ai/skills/om-troubleshooter/references/diagnosis-map.md +16 -0
  117. package/agentic/shared/ai/skills/om-troubleshooter/references/regression-oracles.md +14 -0
  118. package/agentic/shared/ai/skills/tiers.json +143 -21
  119. package/agentic/shared/ai/skills/tiers.schema.json +52 -40
  120. package/agentic/shared/ai/specs/README.md +4 -3
  121. package/agentic/shared/ai/specs/SPEC-000-template.md +226 -10
  122. package/agentic/shared/ai/trackers/github.md +108 -4
  123. package/agentic/shared/scripts/agent-harness-tool-server.mjs +187 -0
  124. package/agentic/shared/scripts/check-lessons.mjs +178 -0
  125. package/agentic/shared/scripts/evaluate-agent-harness.mjs +2958 -0
  126. package/agentic/shared/scripts/execution-sandbox.mjs +329 -0
  127. package/agentic/shared/scripts/framework-context.mjs +888 -0
  128. package/agentic/shared/scripts/install-skills.mjs +1029 -0
  129. package/agentic/shared/scripts/install-skills.sh +4 -694
  130. package/agentic/shared/scripts/prepare-agent-harness-fixture.mjs +222 -0
  131. package/agentic/shared/scripts/run-agent-harness-release.mjs +1774 -0
  132. package/dist/agentic/claude-code/hooks/entity-migration-check.ts +32 -88
  133. package/dist/agentic/codex/enforcement-rules.md +2 -16
  134. package/dist/agentic/cursor/hooks/entity-migration-check.mjs +19 -50
  135. package/dist/agentic/cursor/rules/entity-guard.mdc +9 -21
  136. package/dist/agentic/cursor/rules/generated-guard.mdc +3 -5
  137. package/dist/agentic/cursor/rules/open-mercato.mdc +3 -29
  138. package/dist/agentic/guides/ai-workflows.md +76 -0
  139. package/dist/agentic/guides/architecture.md +107 -0
  140. package/dist/agentic/guides/backend-ui.md +80 -0
  141. package/dist/agentic/guides/contracts.md +92 -0
  142. package/dist/agentic/guides/extensions.md +121 -0
  143. package/dist/agentic/guides/framework-extension-points.md +36 -0
  144. package/dist/agentic/guides/integrations.md +81 -0
  145. package/dist/agentic/guides/module-facts.json +115537 -3951
  146. package/dist/agentic/guides/module-system.md +12 -127
  147. package/dist/agentic/guides/modules/ai_assistant.md +227 -28
  148. package/dist/agentic/guides/modules/api_docs.md +58 -2
  149. package/dist/agentic/guides/modules/api_keys.md +92 -7
  150. package/dist/agentic/guides/modules/attachments.md +119 -14
  151. package/dist/agentic/guides/modules/audit_logs.md +131 -10
  152. package/dist/agentic/guides/modules/auth.md +276 -33
  153. package/dist/agentic/guides/modules/business_rules.md +149 -14
  154. package/dist/agentic/guides/modules/catalog.md +475 -43
  155. package/dist/agentic/guides/modules/channel_gmail.md +82 -3
  156. package/dist/agentic/guides/modules/channel_imap.md +82 -3
  157. package/dist/agentic/guides/modules/checkout.md +299 -27
  158. package/dist/agentic/guides/modules/communication_channels.md +315 -33
  159. package/dist/agentic/guides/modules/configs.md +104 -8
  160. package/dist/agentic/guides/modules/content.md +57 -2
  161. package/dist/agentic/guides/modules/currencies.md +152 -17
  162. package/dist/agentic/guides/modules/customer_accounts.md +387 -45
  163. package/dist/agentic/guides/modules/customers.md +746 -85
  164. package/dist/agentic/guides/modules/dashboards.md +155 -10
  165. package/dist/agentic/guides/modules/data_sync.md +149 -16
  166. package/dist/agentic/guides/modules/design_system.md +102 -0
  167. package/dist/agentic/guides/modules/dictionaries.md +107 -12
  168. package/dist/agentic/guides/modules/directory.md +148 -15
  169. package/dist/agentic/guides/modules/entities.md +145 -13
  170. package/dist/agentic/guides/modules/events.md +59 -2
  171. package/dist/agentic/guides/modules/feature_toggles.md +119 -9
  172. package/dist/agentic/guides/modules/gateway_stripe.md +92 -4
  173. package/dist/agentic/guides/modules/generators.md +45 -2
  174. package/dist/agentic/guides/modules/inbox_ops.md +207 -27
  175. package/dist/agentic/guides/modules/integrations.md +146 -16
  176. package/dist/agentic/guides/modules/messages.md +223 -24
  177. package/dist/agentic/guides/modules/notifications.md +96 -8
  178. package/dist/agentic/guides/modules/onboarding.md +77 -6
  179. package/dist/agentic/guides/modules/payment_gateways.md +164 -21
  180. package/dist/agentic/guides/modules/perspectives.md +77 -7
  181. package/dist/agentic/guides/modules/planner.md +136 -18
  182. package/dist/agentic/guides/modules/portal.md +93 -2
  183. package/dist/agentic/guides/modules/progress.md +104 -14
  184. package/dist/agentic/guides/modules/query_index.md +154 -15
  185. package/dist/agentic/guides/modules/record_locks.md +206 -21
  186. package/dist/agentic/guides/modules/resources.md +197 -30
  187. package/dist/agentic/guides/modules/sales.md +678 -84
  188. package/dist/agentic/guides/modules/scheduler.md +133 -14
  189. package/dist/agentic/guides/modules/search.md +170 -6
  190. package/dist/agentic/guides/modules/security.md +294 -35
  191. package/dist/agentic/guides/modules/shipping_carriers.md +134 -18
  192. package/dist/agentic/guides/modules/sso.md +151 -26
  193. package/dist/agentic/guides/modules/staff.md +369 -57
  194. package/dist/agentic/guides/modules/storage_s3.md +95 -5
  195. package/dist/agentic/guides/modules/sync_akeneo.md +85 -3
  196. package/dist/agentic/guides/modules/sync_excel.md +75 -6
  197. package/dist/agentic/guides/modules/system_status_overlays.md +60 -2
  198. package/dist/agentic/guides/modules/translations.md +104 -10
  199. package/dist/agentic/guides/modules/webhooks.md +203 -24
  200. package/dist/agentic/guides/modules/wms.md +441 -46
  201. package/dist/agentic/guides/modules/workflows.md +302 -43
  202. package/dist/agentic/guides/spec-delivery.md +22 -0
  203. package/dist/agentic/guides/testing-debugging.md +80 -0
  204. package/dist/agentic/guides/upstream/AGENTS.md +299 -0
  205. package/dist/agentic/guides/upstream/BACKWARD_COMPATIBILITY.md +316 -0
  206. package/dist/agentic/guides/upstream/manifest.json +8 -0
  207. package/dist/agentic/shared/AGENTS.md.template +124 -311
  208. package/dist/agentic/shared/ai/agentic.config.json +2 -0
  209. package/dist/agentic/shared/ai/harness/README.md +50 -0
  210. package/dist/agentic/shared/ai/harness/RELEASE.md +57 -0
  211. package/dist/agentic/shared/ai/harness/cases.json +13680 -0
  212. package/dist/agentic/shared/ai/harness/cases.schema.json +133 -0
  213. package/dist/agentic/shared/ai/harness/fixtures/index.json +49 -0
  214. package/dist/agentic/shared/ai/harness/fixtures/seeds.json +162 -0
  215. package/dist/agentic/shared/ai/harness/generated-code-review-policy.md +21 -0
  216. package/dist/agentic/shared/ai/harness/generated-code-review-response.schema.json +96 -0
  217. package/dist/agentic/shared/ai/harness/generated-code-review-result.schema.json +172 -0
  218. package/dist/agentic/shared/ai/harness/release-matrix.json +158 -0
  219. package/dist/agentic/shared/ai/harness/release-result.schema.json +219 -0
  220. package/dist/agentic/shared/ai/harness/result.schema.json +76 -0
  221. package/dist/agentic/shared/ai/harness/routing-response.schema.json +12 -0
  222. package/dist/agentic/shared/ai/harness/target-validation-result.schema.json +73 -0
  223. package/dist/agentic/shared/ai/harness/validators.json +78 -0
  224. package/dist/agentic/shared/ai/harness/writable-ast-oracles.mjs +2121 -0
  225. package/dist/agentic/shared/ai/harness/writable-behavior-oracles.mjs +1096 -0
  226. package/dist/agentic/shared/ai/lessons/_template.md +16 -0
  227. package/dist/agentic/shared/ai/lessons.md +26 -3
  228. package/dist/agentic/shared/ai/review-checklist.md +36 -0
  229. package/dist/agentic/shared/ai/skills/om-auto-implement-spec/SKILL.md +21 -0
  230. package/dist/agentic/shared/ai/skills/om-auto-review-pr/SKILL.md +4 -0
  231. package/dist/agentic/shared/ai/skills/om-auto-upgrade-0.6.6-to-0.6.7/SKILL.md +98 -0
  232. package/dist/agentic/shared/ai/skills/om-backend-ui-design/SKILL.md +20 -241
  233. package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/crud-surfaces.md +16 -0
  234. package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/frontend-and-design-system.md +53 -0
  235. package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/page-and-navigation.md +13 -0
  236. package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/quality-states.md +11 -0
  237. package/dist/agentic/shared/ai/skills/om-build-workflow/SKILL.md +30 -0
  238. package/dist/agentic/shared/ai/skills/om-build-workflow/references/activity-contracts.md +12 -0
  239. package/dist/agentic/shared/ai/skills/om-build-workflow/references/durability-and-progress.md +13 -0
  240. package/dist/agentic/shared/ai/skills/om-build-workflow/references/workflow-design.md +14 -0
  241. package/dist/agentic/shared/ai/skills/om-create-ai-agent/SKILL.md +28 -0
  242. package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/attachments-and-overrides.md +12 -0
  243. package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/module-agents-and-tools.md +22 -0
  244. package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/orchestrator-agents.md +12 -0
  245. package/dist/agentic/shared/ai/skills/om-create-ai-agent/references/surface-selector.md +19 -0
  246. package/dist/agentic/shared/ai/skills/om-data-model-design/SKILL.md +16 -601
  247. package/dist/agentic/shared/ai/skills/om-data-model-design/references/integrity-and-concurrency.md +19 -0
  248. package/dist/agentic/shared/ai/skills/om-data-model-design/references/migration-workflow.md +13 -0
  249. package/dist/agentic/shared/ai/skills/om-data-model-design/references/schema-design.md +14 -0
  250. package/dist/agentic/shared/ai/skills/om-data-model-design/references/sensitive-data.md +10 -0
  251. package/dist/agentic/shared/ai/skills/om-eject-and-customize/SKILL.md +14 -310
  252. package/dist/agentic/shared/ai/skills/om-eject-and-customize/references/decision-and-procedure.md +17 -0
  253. package/dist/agentic/shared/ai/skills/om-evolve-harness/SKILL.md +29 -0
  254. package/dist/agentic/shared/ai/skills/om-evolve-harness/references/case-template.md +100 -0
  255. package/dist/agentic/shared/ai/skills/om-evolve-harness/references/case-workflow.md +16 -0
  256. package/dist/agentic/shared/ai/skills/om-evolve-harness/references/owner-selection.md +17 -0
  257. package/dist/agentic/shared/ai/skills/om-framework-context/SKILL.md +25 -0
  258. package/dist/agentic/shared/ai/skills/om-framework-context/references/resolver-procedure.md +11 -0
  259. package/dist/agentic/shared/ai/skills/om-framework-context/references/skew-and-escalation.md +13 -0
  260. package/dist/agentic/shared/ai/skills/om-help/SKILL.md +15 -97
  261. package/dist/agentic/shared/ai/skills/om-help/references/delivery-workflows.md +18 -0
  262. package/dist/agentic/shared/ai/skills/om-help/references/task-families.md +20 -0
  263. package/dist/agentic/shared/ai/skills/om-implement-spec/SKILL.md +33 -152
  264. package/dist/agentic/shared/ai/skills/om-implement-spec/references/phases-and-gates.md +33 -0
  265. package/dist/agentic/shared/ai/skills/om-implement-spec/references/planning-and-progress.md +40 -0
  266. package/dist/agentic/shared/ai/skills/om-implement-spec/references/report-templates.md +27 -0
  267. package/dist/agentic/shared/ai/skills/om-implement-spec/references/spec-resolution.md +24 -0
  268. package/dist/agentic/shared/ai/skills/om-integration-builder/SKILL.md +24 -708
  269. package/dist/agentic/shared/ai/skills/om-integration-builder/references/package-and-activation.md +16 -0
  270. package/dist/agentic/shared/ai/skills/om-integration-builder/references/provider-families.md +14 -0
  271. package/dist/agentic/shared/ai/skills/om-integration-builder/references/security-and-reliability.md +15 -0
  272. package/dist/agentic/shared/ai/skills/om-integration-builder/references/sync-and-files.md +12 -0
  273. package/dist/agentic/shared/ai/skills/om-judge-agent-session/SKILL.md +34 -0
  274. package/dist/agentic/shared/ai/skills/om-judge-agent-session/agents/openai.yaml +4 -0
  275. package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/agentic-setup.md +11 -0
  276. package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/input-normalization.md +31 -0
  277. package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/judge-workflow.md +39 -0
  278. package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/report-template.md +43 -0
  279. package/dist/agentic/shared/ai/skills/om-judge-agent-session/references/rules.md +11 -0
  280. package/dist/agentic/shared/ai/skills/om-module-scaffold/SKILL.md +20 -820
  281. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/api-and-domain.md +19 -0
  282. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md +172 -0
  283. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/data-and-migrations.md +12 -0
  284. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/discovery-surface-catalog.md +83 -0
  285. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/module-surfaces.md +21 -0
  286. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/planning.md +11 -0
  287. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/runtime-cache-and-queues.md +22 -0
  288. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/verification.md +13 -0
  289. package/dist/agentic/shared/ai/skills/om-share-this-session/SKILL.md +41 -0
  290. package/dist/agentic/shared/ai/skills/om-share-this-session/references/agentic-setup.md +19 -0
  291. package/dist/agentic/shared/ai/skills/om-share-this-session/references/bundle-preparation.md +44 -0
  292. package/dist/agentic/shared/ai/skills/om-share-this-session/references/consent-and-review.md +39 -0
  293. package/dist/agentic/shared/ai/skills/om-share-this-session/references/publication.md +20 -0
  294. package/dist/agentic/shared/ai/skills/om-share-this-session/references/report-templates.md +57 -0
  295. package/dist/agentic/shared/ai/skills/om-share-this-session/references/rules.md +11 -0
  296. package/dist/agentic/shared/ai/skills/om-share-this-session/scripts/prepare-share-bundle.mjs +486 -0
  297. package/dist/agentic/shared/ai/skills/om-system-extension/SKILL.md +19 -843
  298. package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-branches.md +18 -0
  299. package/dist/agentic/shared/ai/skills/om-system-extension/references/mechanism-selector.md +27 -0
  300. package/dist/agentic/shared/ai/skills/om-system-extension/references/read-write-roundtrip.md +13 -0
  301. package/dist/agentic/shared/ai/skills/om-system-extension/references/unified-overrides.md +41 -0
  302. package/dist/agentic/shared/ai/skills/om-system-extension/references/verification.md +11 -0
  303. package/dist/agentic/shared/ai/skills/om-trim-unused-modules/SKILL.md +15 -63
  304. package/dist/agentic/shared/ai/skills/om-trim-unused-modules/references/dependency-and-redirect.md +15 -0
  305. package/dist/agentic/shared/ai/skills/om-troubleshooter/SKILL.md +16 -467
  306. package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnosis-map.md +16 -0
  307. package/dist/agentic/shared/ai/skills/om-troubleshooter/references/regression-oracles.md +14 -0
  308. package/dist/agentic/shared/ai/skills/tiers.json +143 -21
  309. package/dist/agentic/shared/ai/skills/tiers.schema.json +52 -40
  310. package/dist/agentic/shared/ai/specs/README.md +4 -3
  311. package/dist/agentic/shared/ai/specs/SPEC-000-template.md +226 -10
  312. package/dist/agentic/shared/ai/trackers/github.md +108 -4
  313. package/dist/agentic/shared/scripts/agent-harness-tool-server.mjs +187 -0
  314. package/dist/agentic/shared/scripts/check-lessons.mjs +178 -0
  315. package/dist/agentic/shared/scripts/evaluate-agent-harness.mjs +2958 -0
  316. package/dist/agentic/shared/scripts/execution-sandbox.mjs +329 -0
  317. package/dist/agentic/shared/scripts/framework-context.mjs +888 -0
  318. package/dist/agentic/shared/scripts/install-skills.mjs +1029 -0
  319. package/dist/agentic/shared/scripts/install-skills.sh +4 -694
  320. package/dist/agentic/shared/scripts/prepare-agent-harness-fixture.mjs +222 -0
  321. package/dist/agentic/shared/scripts/run-agent-harness-release.mjs +1774 -0
  322. package/dist/index.js +175 -184
  323. package/package.json +9 -7
  324. package/template/.env.example +59 -2
  325. package/template/.yarnrc.yml.template +9 -0
  326. package/template/AGENTS.md +93 -663
  327. package/template/eslint.config.mjs +1 -0
  328. package/template/gitignore +8 -0
  329. package/template/jest.config.cjs +2 -1
  330. package/template/jest.setup.ts +29 -0
  331. package/template/next.config.ts +55 -0
  332. package/template/package.json.template +31 -25
  333. package/template/scripts/dev-memory-monitor.mjs +92 -0
  334. package/template/scripts/dev-memory-sampler.mjs +464 -0
  335. package/template/scripts/dev-runtime-log-policy.mjs +33 -0
  336. package/template/scripts/dev-runtime.mjs +142 -76
  337. package/template/scripts/dev.mjs +129 -7
  338. package/template/scripts/evaluate-agent-harness.mjs +4 -0
  339. package/template/scripts/framework-context.mjs +4 -0
  340. package/template/scripts/install-skills.mjs +10 -0
  341. package/template/scripts/install-skills.sh +2 -19
  342. package/template/scripts/prepare-agent-harness-fixture.mjs +4 -0
  343. package/template/scripts/run-agent-harness-release.mjs +4 -0
  344. package/template/src/app/(backend)/backend/__tests__/layout-route-registry.test.tsx +1 -0
  345. package/template/src/app/(backend)/backend/layout.tsx +5 -3
  346. package/template/src/app/(frontend)/layout.tsx +1 -1
  347. package/template/src/app/api/[...slug]/route.ts +9 -0
  348. package/template/src/app/globals.css +61 -3
  349. package/template/src/app/layout.tsx +2 -18
  350. package/template/src/app/page.tsx +4 -1
  351. package/template/src/components/AppProviders.tsx +4 -1
  352. package/template/src/components/DemoFeedbackWidget.tsx +1 -1
  353. package/template/src/components/__tests__/AppProviders.test.tsx +11 -2
  354. package/template/src/components/__tests__/StartPageContent.test.tsx +69 -0
  355. package/template/src/components/__tests__/starter-chrome-ds.test.ts +35 -0
  356. package/template/src/i18n/de.json +21 -1
  357. package/template/src/i18n/en.json +21 -1
  358. package/template/src/i18n/es.json +21 -1
  359. package/template/src/i18n/ko.json +970 -0
  360. package/template/src/i18n/pl.json +21 -1
  361. package/template/src/instrumentation.ts +14 -1
  362. package/template/src/lib/i18n/register-dictionary-loader.ts +2 -0
  363. package/template/src/modules/example/__integration__/TC-EXAMPLE-001-todo-label-edit.spec.ts +123 -0
  364. package/template/src/modules/example/__integration__/TC-EXAMPLE-002-query-index-failure.spec.ts +155 -0
  365. package/template/src/modules/example/__integration__/TC-UMES-003.spec.ts +7 -3
  366. package/template/src/modules/example/__integration__/TC-UMES-005.spec.ts +7 -1
  367. package/template/src/modules/example/__integration__/TC-UMES-009.spec.ts +11 -10
  368. package/template/src/modules/example/__integration__/todo-priority-validation.spec.ts +31 -1
  369. package/template/src/modules/example/acl.ts +6 -0
  370. package/template/src/modules/example/backend/mutation-lifecycle/page.meta.ts +1 -9
  371. package/template/src/modules/example/backend/page.meta.ts +1 -10
  372. package/template/src/modules/example/backend/payments/page.meta.ts +1 -10
  373. package/template/src/modules/example/backend/payments/page.tsx +2 -2
  374. package/template/src/modules/example/backend/todos/create/page.meta.ts +1 -11
  375. package/template/src/modules/example/backend/todos/page.meta.ts +1 -10
  376. package/template/src/modules/example/backend/umes-extensions/page.meta.ts +1 -9
  377. package/template/src/modules/example/backend/umes-handlers/page.meta.ts +1 -10
  378. package/template/src/modules/example/backend/umes-integrations/page.meta.ts +1 -10
  379. package/template/src/modules/example/backend/umes-next-phases/page.meta.ts +1 -11
  380. package/template/src/modules/example/backend/umes-query-extensions/page.meta.ts +1 -11
  381. package/template/src/modules/example/commands/__tests__/todos.prepare-scope.test.ts +77 -0
  382. package/template/src/modules/example/commands/todos.ts +47 -2
  383. package/template/src/modules/example/i18n/ko.json +481 -0
  384. package/template/src/modules/example/i18n/pl.json +68 -68
  385. package/template/src/modules/example/lib/__tests__/mock-webhook-endpoint-adapter.test.ts +14 -0
  386. package/template/src/modules/example_customers_sync/i18n/ko.json +11 -0
  387. package/template/src/modules.ts +17 -0
  388. package/template/tsconfig.json +3 -2
  389. package/agentic/shared/ai/skills/om-auto-continue-pr-loop/SKILL.md +0 -27
  390. package/agentic/shared/ai/skills/om-auto-create-pr-loop/SKILL.md +0 -27
  391. package/agentic/shared/ai/skills/om-backend-ui-design/references/ui-components.md +0 -260
  392. package/agentic/shared/ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md +0 -146
  393. package/agentic/shared/ai/skills/om-help/references/skills-catalog.md +0 -84
  394. package/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +0 -193
  395. package/agentic/shared/ai/skills/om-integration-builder/STANDALONE.md +0 -34
  396. package/agentic/shared/ai/skills/om-integration-builder/references/adapter-contracts.md +0 -762
  397. package/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +0 -50
  398. package/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md +0 -97
  399. package/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md +0 -271
  400. package/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md +0 -101
  401. package/dist/agentic/guides/cache.md +0 -45
  402. package/dist/agentic/guides/core.md +0 -453
  403. package/dist/agentic/guides/events.md +0 -117
  404. package/dist/agentic/guides/queue.md +0 -53
  405. package/dist/agentic/guides/search.md +0 -115
  406. package/dist/agentic/guides/shared.md +0 -108
  407. package/dist/agentic/guides/ui.md +0 -347
  408. package/dist/agentic/shared/ai/skills/om-auto-continue-pr-loop/SKILL.md +0 -27
  409. package/dist/agentic/shared/ai/skills/om-auto-create-pr-loop/SKILL.md +0 -27
  410. package/dist/agentic/shared/ai/skills/om-backend-ui-design/references/ui-components.md +0 -260
  411. package/dist/agentic/shared/ai/skills/om-data-model-design/references/mikro-orm-cheatsheet.md +0 -146
  412. package/dist/agentic/shared/ai/skills/om-help/references/skills-catalog.md +0 -84
  413. package/dist/agentic/shared/ai/skills/om-help/references/workflow-sequences.md +0 -193
  414. package/dist/agentic/shared/ai/skills/om-integration-builder/STANDALONE.md +0 -34
  415. package/dist/agentic/shared/ai/skills/om-integration-builder/references/adapter-contracts.md +0 -762
  416. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/naming-conventions.md +0 -50
  417. package/dist/agentic/shared/ai/skills/om-module-scaffold/references/navigation-patterns.md +0 -97
  418. package/dist/agentic/shared/ai/skills/om-system-extension/references/extension-contracts.md +0 -271
  419. package/dist/agentic/shared/ai/skills/om-troubleshooter/references/diagnostic-commands.md +0 -101
@@ -1,698 +1,128 @@
1
- # Standalone Open Mercato Application
1
+ # Standalone Open Mercato App — Agent Rules
2
2
 
3
- This is a **standalone application** that consumes Open Mercato packages from the npm registry. Unlike the monorepo development environment, packages here are pre-compiled and installed as dependencies.
3
+ Route first; never probe unmatched context.
4
4
 
5
5
  ## Always
6
6
 
7
- - Treat this app as a package consumer: inspect `node_modules/@open-mercato/*/dist/` when framework behavior is unclear.
8
- - Put custom modules in `src/modules/<module>/` and add them to `src/modules.ts` with `from: '@app'`.
9
- - Run `yarn generate` after changing modules, overrides, pages, widgets, AI agents, AI tools, or structural navigation.
10
- - Declare API route `metadata` per HTTP method, including explicit unauthenticated public routes.
11
- - Keep generated files under `.mercato/generated/` as generated output only.
7
+ - Route all axes; missing context: `yarn mercato agentic:init --update-harness`.
8
+ - Lessons: scan `.ai/lessons.md` tags; open/update one matching record + row.
9
+ - App code: `src/modules/<id>/`; framework context only for named gaps.
10
+ - Derive trusted `tenantId` + `organizationId` and fail closed. Only an installed contract may use system scope (`organizationId: null`).
11
+ - Use commands/`makeCrudRoute`/`CrudForm`/`DataTable`, DI/events/UMES; effects stay post-commit.
12
+ - Put entities in `src/modules/<id>/data/entities.ts`; API routes need per-method `metadata` + `openApi`.
13
+ - Editable records expose `updated_at`/`updatedAt`; custom update/delete clients send the version and surface 409s.
14
+ - Run `yarn db:generate`, review scoped SQL/snapshot, and ask before applying it.
15
+ - Run `yarn generate` after discovery files, `src/modules.ts`, routes, pages, events, widgets, agents, tools, or workflows change.
16
+ - Contract-surface changes (route/schema/ID/export/seam/signature/event payload/CLI) MUST read `.ai/guides/upstream/BACKWARD_COMPATIBILITY.md`; tenant/org scope alone is not a contract.
17
+ - Localize strings; use shared UI/tokens and cover loading/empty/error/conflict/keyboard/a11y.
12
18
 
13
19
  ## Ask First
14
20
 
15
- - Ask before applying migrations, resetting local databases, or changing `.env` database targets.
16
- - Ask before using manual SQL instead of the generated migration path.
17
- - Ask before adding a new framework primitive when a canonical mechanism is not listed below.
18
- - Ask before enabling live external services, secrets, or provider credentials in tests.
21
+ - Ask before scope/architecture/public contracts/dependencies/ejection/canonical primitives; migrations/resets/DB targets; live credentials/providers; or weakening security/concurrency/retries/idempotency/audit/undo.
19
22
 
20
23
  ## Never
21
24
 
22
- - Never use raw `fetch`, raw `<form>`, ad hoc crypto, ad hoc Redis, custom queues, or manual cross-module ORM joins when a framework primitive exists.
23
- - Never use `requireRoles`; use feature-based RBAC and grant features in module setup.
24
- - Never store sensitive data as plaintext "for now" or hand-roll encryption.
25
- - Never hardcode user-facing strings or Tailwind status colors in UI changes.
26
- - Never edit already-shipped historical migrations; add a new corrective migration.
25
+ - Never leak tenants, trust payload scope, or treat missing scope as unrestricted.
26
+ - Never edit `node_modules`, `.mercato/generated/**`, generated facts, or shipped migrations.
27
+ - Never use cross-module ORM relations; use IDs/snapshots, events, enrichers, extensions, or optional DI.
28
+ - Never use raw admin `fetch`/`<form>`, ad hoc crypto/cache/queues, role-name guards, or direct mutations when helpers exist.
29
+ - Never hard-code user strings/status colors; expose secrets/transcripts; or guess answerable contracts.
27
30
 
28
- ## Validation Commands
31
+ ## Validation
29
32
 
30
- ```bash
31
- yarn generate
32
- yarn typecheck
33
- yarn lint
34
- yarn test
35
- yarn build
36
- yarn test:integration:ephemeral
37
- ```
33
+ Use the smallest relevant set. Broad: `yarn generate && yarn typecheck && yarn lint && yarn test && yarn build`; integration: `yarn test:integration:ephemeral`. Report failures; never migrate to validate.
38
34
 
39
- ## Package Source Files
35
+ ## Three-Axis Context Assembler
40
36
 
41
- To explore or understand the Open Mercato framework code:
37
+ Routes are additive: ownership says WHO; other axes say WHAT. Select every match.
42
38
 
43
- - **Location**: `node_modules/@open-mercato/*/dist/` contains compiled JavaScript
44
- - **Source exploration**: Search `node_modules/@open-mercato/` for module implementations
45
- - **Key packages**:
46
- - `@open-mercato/core` - Core business modules (auth, customers, catalog, sales, etc.)
47
- - `@open-mercato/shared` - Shared utilities, types, DSL helpers, i18n
48
- - `@open-mercato/ui` - UI components and primitives
49
- - `@open-mercato/cli` - CLI tooling (mercato command)
50
- - `@open-mercato/search` - Search module (fulltext, vector, tokens)
39
+ `debugging` is additive. A scalar-ID/snapshot fix to persisted records or commands linked to an installed record MUST use `module-data` + `umes` and load `om-data-model-design` + `om-system-extension`.
51
40
 
52
- **Note**: When debugging or extending functionality, reference the compiled code in `node_modules/@open-mercato/` to understand the framework's implementation details.
41
+ `debugging` = reported bug/security/drift, not designed failure UI. Specs use `spec-pr`; implementation owns domain guides. Custom fields/entities = `umes` + `module-data` + `om-data-model-design`; editable round trips add `backend-ui`, requested coverage adds `testing`. Never infer work from specs/PRs.
53
42
 
54
- ## Development Commands
43
+ Unified-override audits = `umes` only; add `architecture`/`framework-context` only for unresolved ownership or installed keys. Durable process/activity/user task = `module-data` + `ai-workflow`. Multi-stage waits/cancel/restart are durable; reminders and renewal/batch schedules are `module-data`.
55
44
 
56
- ```bash
57
- # Start compact dev runtime (press `d` to toggle raw logs)
58
- yarn dev
45
+ `backend-ui`: replacing/wrapping, prop-transforming, menu-editing, or adding visible feedback adds `backend-ui`; merely hiding/toggling/rewiring installed UI does not.
46
+ Staff UI preview/report/bulk = `backend-ui`.
47
+ Existing installed form/table fields, filters, row/bulk actions without app persistence = `umes` + `backend-ui` only: read `crud-surfaces` + `quality-states`; do not load contracts, module-scaffold, or page/navigation.
59
48
 
60
- # Start dev runtime with full raw passthrough logs
61
- yarn dev:verbose
49
+ `backend-ui`: UI skill `references/quality-states.md`; public/portal/responsive/a11y adds `frontend-and-design-system.md`.
62
50
 
63
- # Start the backward-compatible raw runtime with no splash screen
64
- yarn dev:classic
51
+ ### Axis 1 — Area/Ownership
65
52
 
66
- # Run standalone bootstrap + startup in backward-compatible raw mode
67
- yarn setup:classic
68
-
69
- # Build for production
70
- yarn build
71
-
72
- # Run production server
73
- yarn start
74
-
75
- # Type checking
76
- yarn typecheck
77
-
78
- # Linting
79
- yarn lint
80
-
81
- # Run unit tests
82
- yarn test
83
-
84
- # Run a single unit test
85
- yarn test path/to/test.spec.ts
86
-
87
- # Run integration tests (preferred: provisions/reuses an ephemeral app + DB, runs Playwright)
88
- yarn test:integration:ephemeral
89
-
90
- # Start ephemeral app only (manual QA exploration or iterative test loops; admin@acme.com / secret)
91
- yarn test:integration:ephemeral:start
92
-
93
- # Iterate against the running ephemeral env with small filtered batches
94
- yarn mercato test:integration <filter>
95
-
96
- # View HTML integration test report
97
- npx playwright show-report .ai/qa/test-results/html
98
-
99
- # Generate code from modules
100
- yarn generate
101
-
102
- # Manually purge structural caches when needed (Redis nav:* + Turbopack barrel mtimes)
103
- yarn mercato configs cache structural --all-tenants
104
-
105
- # Escape hatch: clear .mercato/next/dev and legacy .next caches when Turbopack still serves a stale chunk
106
- yarn dev:reset
107
-
108
- # Database operations
109
- yarn db:generate # Generate/probe migrations; keep or write only scoped SQL and update the touched snapshot
110
- yarn db:migrate # Run migrations
111
- yarn db:greenfield # Reset and recreate database
112
-
113
- # Initialize/reinstall project
114
- yarn initialize
115
- yarn reinstall
116
- ```
117
-
118
- ## Dev Splash Features
119
-
120
- - `yarn dev` serves the compact splash screen on `http://localhost:4000` by default and auto-opens it on supported local runs.
121
- - When enabled, the splash can launch detected coding tools from the `Start coding with AI` menu.
122
- - In standalone apps, the splash can also create or publish a GitHub repository through `gh` once the app is ready.
123
-
124
- ## Recommended Local Tooling
125
-
126
- - GitHub CLI (`gh`) is recommended for the splash GitHub publish flow: <https://cli.github.com/>
127
- - Codex CLI is recommended for the OpenAI terminal workflow surfaced by the splash: <https://developers.openai.com/codex/cli>
128
- - Claude Code is recommended for the Anthropic terminal workflow surfaced by the splash: <https://code.claude.com/docs/en/setup>
129
- - Visual Studio Code is the recommended general-purpose editor: <https://code.visualstudio.com/Download>
130
- - Cursor is a recommended AI-first editor: <https://cursor.com/download>
131
-
132
- ## Dev Splash Environment Variables
133
-
134
- | Variable | Default | Description |
135
- |----------|---------|-------------|
136
- | `OM_DEV_SPLASH_PORT` | `4000` | Override the splash port. Use `random` or `0` for an ephemeral free port. |
137
- | `OM_DEV_AUTO_OPEN` | `1` | Set to `0` to disable browser auto-open for the splash. |
138
- | `OM_DEV_CREATE_GIT_REPO_FLOW` | `true` | Set to `false` to hide the standalone GitHub publish panel from the splash. |
139
- | `OM_ENABLE_CODING_FLOW_FROM_SPLASH` | `true` | Set to `false` to hide the coding tools menu from the splash. |
140
- | `OM_DEV_SPLASH_VSCODE_PATH` | auto-detect | Optional path override for the VS Code CLI. |
141
- | `OM_DEV_SPLASH_CURSOR_PATH` | auto-detect | Optional path override for the Cursor CLI. |
142
- | `OM_DEV_SPLASH_CLAUDE_CODE_PATH` | auto-detect | Optional path override for the Claude Code CLI. |
143
- | `OM_DEV_SPLASH_CODEX_PATH` | auto-detect | Optional path override for the Codex CLI. |
144
- | `OM_DEV_AUTO_MIGRATE` | `1` | When set to `1` (default), `yarn dev` runs `yarn db:migrate` once at startup before Next.js boots. Set to `0` to disable. See "Single-shot Database Migrations" below. |
145
- | `OM_DEV_DATABASE_NAME` | unset | Same as passing `--database-name=<value>` to `yarn dev` / `yarn setup`. CLI flag wins. |
146
- | `OM_DEV_DATABASE_UPDATE_ENV` | unset | Non-interactive answer for the `.env` update prompt (`true`/`false`). Equivalent to `--update-env` / `--no-update-env`. |
147
-
148
- ### Persistent Parallel Local Databases
149
-
150
- Add `--database-name[=<name>]` to `yarn dev`, `yarn dev:greenfield`, or `yarn setup` to point this app at an isolated PostgreSQL database without manually editing `.env` first. Behavior:
151
-
152
- - `yarn dev` (no flag) is unchanged — no prompt, no `.env` mutation.
153
- - `yarn setup --database-name=client_a` rewrites the `DATABASE_URL` database segment in `./.env` after a confirmation prompt (default yes).
154
- - `yarn dev --database-name` (bare flag) derives the database name from the current directory.
155
- - `yarn dev --database-name=review_1720 --no-update-env` injects the rewritten URL into the current child process only and leaves `.env` untouched.
156
- - Non-interactive runs (`CI=true` or piped stdin) default to updating `.env`; pass `--no-update-env` to opt out.
157
-
158
- The override only changes the database segment of `DATABASE_URL`. Credentials, host, port, query strings (`?schema=…`, `?sslmode=…`), and other env variables are preserved verbatim.
159
-
160
- ## Infrastructure
161
-
162
- Start required services via Docker Compose:
163
- ```bash
164
- docker compose up -d
165
- ```
166
-
167
- Services: PostgreSQL (pgvector), Redis, Meilisearch
168
-
169
- ## Architecture
170
-
171
- ### Open Mercato Framework
172
-
173
- This is a Next.js 16 application built on the **Open Mercato** modular ERP framework. The framework provides:
174
-
175
- - **Module system**: Business modules (auth, customers, catalog, sales, etc.) from `@open-mercato/*` packages
176
- - **Entity system**: MikroORM entities with code generation
177
- - **DI container**: Awilix-based dependency injection
178
- - **RBAC**: Role-based access control with feature flags
179
-
180
- ### Key Files
181
-
182
- - `src/modules.ts` - Declares enabled modules and their sources (`@open-mercato/core`, `@open-mercato/*`, or `@app`)
183
- - `src/di.ts` - App-level DI overrides (runs after core/module registrations)
184
- - `src/bootstrap.ts` - Application initialization (imports generated files, registers i18n)
185
- - `.mercato/generated/` - Auto-generated files from `yarn generate` (do not edit manually)
186
-
187
- ### Module Overrides
188
-
189
- Use the unified `entry.overrides` field in `src/modules.ts` when this app needs to replace or disable a contract from a package-backed module without forking it. The template ships a non-applied `moduleOverrideExamples` object covering AI, routes, events, workers, widgets, notifications, interceptors, setup, ACL, DI, and encryption. Copy only the specific domains you need into the target module entry's `overrides` field.
190
-
191
- Rules:
192
-
193
- - `null` disables a matching contract; an object/function definition replaces it.
194
- - API route keys are `'METHOD /api/path'`; page route keys are `'/backend/path'` or `'/frontend/path'`.
195
- - `setup` overrides apply to the module entry carrying them, not to a separate setup id map.
196
- - The standard `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` before registries load.
197
-
198
- ### Routing Structure
199
-
200
- - `/backend/*` - Admin panel routes (AppShell with sidebar navigation)
201
- - `/(frontend)/*` - Public-facing routes
202
- - `/api/*` - API routes with automatic module routing via `findApi()`
203
-
204
- ### Module Development
205
-
206
- Custom modules go in `src/modules/`. Each module can define:
207
- - Entities (MikroORM)
208
- - API routes
209
- - Backend/frontend pages
210
- - DI registrations
211
- - Navigation entries
212
-
213
- Add new modules to `src/modules.ts` with `from: '@app'`.
214
- Install official package-backed modules with `yarn mercato module add @open-mercato/<package>`.
215
-
216
- ### Data Entities
217
-
218
- - Define module entities in `src/modules/<module>/data/entities.ts`.
219
- - Import entity decorators from `@mikro-orm/decorators/legacy`, not `@mikro-orm/core`.
220
- - User-editable entities MUST carry an `updated_at` column (onCreate+onUpdate) — it backs OSS **optimistic locking** (default ON). Return `updatedAt` from CRUD list/detail responses, and on edit/delete UI let `CrudForm` auto-derive the version header from `initialValues.updatedAt`, or for custom handlers wrap with `withScopedApiRequestHeaders(buildOptimisticLockHeader(record.updatedAt), …)` + `surfaceRecordConflict(err, t)`. Without it, concurrent edits silently overwrite.
221
- - Treat `yarn db:generate` as a schema-diff probe. Default to the generated SQL, but if it emits unrelated churn, keep or write only the scoped SQL for the module you are changing and update `src/modules/<module>/migrations/.snapshot-open-mercato.json` in the same change.
222
-
223
- ### API Route Files MUST Export `metadata`
224
-
225
- Every `src/modules/<module>/api/**/route.ts` file that exports an HTTP handler (`GET`, `POST`, `PUT`, `PATCH`, `DELETE`) MUST also export a `metadata` object describing per-method auth requirements. Omitting it triggers the generator warning:
226
-
227
- ```
228
- [generate] ⚠ Route file exports handlers but no metadata — auth will default to required: <file>
229
- ```
230
-
231
- …and the generated registry falls back to "authentication required" for every method, which hides misconfigurations rather than surfacing them. Always be explicit.
232
-
233
- Correct shape — per-method, with `requireAuth` and optional `requireFeatures`:
234
-
235
- ```ts
236
- // src/modules/<module>/api/<path>/route.ts
237
- export const metadata = {
238
- GET: { requireAuth: true, requireFeatures: ['mymodule.view'] },
239
- POST: { requireAuth: true, requireFeatures: ['mymodule.manage'] },
240
- }
241
-
242
- export async function GET(request: Request) { /* ... */ }
243
- export async function POST(request: Request) { /* ... */ }
244
- ```
245
-
246
- Public (unauthenticated) endpoints must opt out explicitly:
247
-
248
- ```ts
249
- export const metadata = {
250
- GET: { requireAuth: false },
251
- }
252
- ```
253
-
254
- Legacy top-level `export const requireAuth` / `export const requireFeatures` exports are NOT recognized by the registry generator — migrate any stragglers to the `metadata` object shape above.
255
-
256
- ### Single-shot Database Migrations
257
-
258
- `yarn dev` auto-applies pending migrations at startup by default (see `OM_DEV_AUTO_MIGRATE` in the environment variables table). That means once a migration file has been committed to `src/modules/<module>/migrations/` and picked up by the dev server, it has likely already been applied to your local database.
259
-
260
- Practical consequences:
261
-
262
- - Prefer writing migration files in **one shot** — generate them with `yarn db:generate`, review, commit, move on.
263
- - Treat `yarn db:generate` as a schema-diff probe. If it creates migrations for unrelated modules, delete that unrelated output and fix the stale snapshot instead of committing noise.
264
- - Manual SQL is allowed when it is the only clean way to avoid unrelated churn, but the touched module's `.snapshot-open-mercato.json` MUST be updated to the post-change schema in the same change.
265
- - For the specific entity change you are making, keep or write only the intended SQL migration and update `src/modules/<module>/migrations/.snapshot-open-mercato.json` to the post-change schema in the same change.
266
- - Do not run `yarn db:migrate` unless the user explicitly asks you to apply migrations. A code change should carry migration files and snapshots; applying them is local database state.
267
- - Editing an already-applied migration is risky: the next `yarn dev` / `yarn db:migrate` will skip the file (it is already marked applied), so your edits will not land in the database. If iteration is truly unavoidable:
268
- 1. Set `OM_DEV_AUTO_MIGRATE=0` in `.env.local` to stop auto-apply.
269
- 2. Roll back the migration (`yarn db:migrate --down` or reset the dev DB).
270
- 3. Edit the migration file.
271
- 4. Re-apply (`yarn db:migrate`) and commit.
272
- - Never hand-edit historical migrations that have shipped; add a **new** migration that performs the correction instead.
273
-
274
- ## Entity Update Safety / Transaction Safety
275
-
276
- MikroORM v7 can silently drop a pending scalar UPDATE when a query (`em.find`, `em.findOne`, or a sync helper) runs on the same `EntityManager` between the scalar mutation and `em.flush()`. For commands that mutate entities across multiple phases:
277
-
278
- - Use `withAtomicFlush(em, phases, { transaction: true })` from `@open-mercato/shared/lib/commands/flush` for multi-phase scalar + relation mutations.
279
- - Never interleave `em.find`/`em.findOne` between a scalar mutation and `em.flush()` without `withAtomicFlush`.
280
- - Keep `emitCrudSideEffects` and cache invalidation OUTSIDE the `withAtomicFlush` block — they run only AFTER the DB write commits.
281
-
282
- ```ts
283
- import { withAtomicFlush } from '@open-mercato/shared/lib/commands/flush'
284
-
285
- await withAtomicFlush(em, [
286
- () => { record.name = 'New Name'; record.status = 'active' },
287
- () => syncEntityTags(em, record, tags),
288
- ], { transaction: true })
289
-
290
- // Cache invalidation + side effects AFTER commit
291
- await emitCrudSideEffects({ /* ... */ })
292
- ```
293
-
294
- Cache invalidation running post-commit means reads can briefly observe a query-index convergence window. The opt-in `OM_CACHE_SAFETY_ALWAYS_CONSISTENT` env flag (default OFF, backward compatible) is planned to make the query-index read-projection tail converge synchronously on write, at a write-latency cost — opt-in/forthcoming, not on by default.
295
-
296
- ## AI Assistant — adding agents, tools, UI parts, and overrides
297
-
298
- Standalone apps consume the AI framework from `@open-mercato/ai-assistant` (in `node_modules/`). The same conventions used in the monorepo apply here:
299
-
300
- - 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.
301
- - 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).
302
- - 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**.
303
-
304
- Example per-module override (preferred when the override should ship with a module):
305
-
306
- ```ts
307
- // src/modules/<my_module>/ai-agents.ts
308
- import type {
309
- AiAgentDefinition,
310
- AiAgentOverridesMap,
311
- } from '@open-mercato/ai-assistant'
312
- import myAgent from './agents/my-merchandising-agent'
313
-
314
- export const aiAgents: AiAgentDefinition[] = [/* ...your module's own agents */]
315
-
316
- export const aiAgentOverrides: AiAgentOverridesMap = {
317
- 'catalog.merchandising_assistant': myAgent, // replace
318
- 'catalog.catalog_assistant': null, // disable
319
- }
320
- ```
321
-
322
- Example `modules.ts` inline override (preferred for app-level decisions that do not deserve a fake module). All module contract domains live under the same `entry.overrides` umbrella per the [unified spec](https://github.com/open-mercato/open-mercato/blob/main/.ai/specs/implemented/2026-05-04-modules-ts-unified-overrides.md):
323
-
324
- ```ts
325
- // src/modules.ts
326
- {
327
- id: 'example',
328
- from: '@app',
329
- overrides: {
330
- ai: {
331
- agents: { 'catalog.catalog_assistant': null },
332
- tools: { 'inbox_ops_accept_action': null },
333
- },
334
- routes: {
335
- api: {
336
- 'GET /api/example/override-probe': {
337
- handler: async () => Response.json({ ok: true, source: 'override' }),
338
- metadata: { requireAuth: false },
339
- },
340
- },
341
- pages: {
342
- '/backend/example/reports': null,
343
- },
344
- },
345
- },
346
- },
347
- ```
348
-
349
- The template's `src/bootstrap.ts` already calls `applyModuleOverridesFromEnabledModules(enabledModules)` from `@open-mercato/shared/modules/overrides` for you. Importing `@open-mercato/ai-assistant` (also in bootstrap) runs the side-effect that registers the AI domain applier with the dispatcher.
350
-
351
- Example programmatic override at boot (env-driven or test-only):
352
-
353
- ```ts
354
- // src/bootstrap.ts (extra)
355
- import {
356
- applyAiAgentOverrides,
357
- applyAiToolOverrides,
358
- } from '@open-mercato/ai-assistant'
359
-
360
- // Disable an agent provided by the assistant module by default.
361
- applyAiAgentOverrides({ 'catalog.catalog_assistant': null })
362
- // Disable a default tool we do not use.
363
- applyAiToolOverrides({ 'inbox_ops_accept_action': null })
364
- ```
365
-
366
- After editing any `aiAgentOverrides` / `aiToolOverrides` export:
367
-
368
- ```bash
369
- yarn generate
370
- yarn mercato configs cache structural --all-tenants
371
- ```
372
-
373
- Refer to the `om-create-ai-agent` skill (`.ai/skills/om-create-ai-agent/SKILL.md`) and the public docs at `framework/ai-assistant/overrides` for the full contract, MUST rules, and the resolution order.
374
-
375
- ### Unified module contract overrides
376
-
377
- The same `entry.overrides` surface that disables/replaces AI agents also wires routes, subscribers, workers, widgets, notifications, interceptors, enrichers, guards, CLI commands, setup hooks, ACL features, DI bindings, and encryption maps. Use it when you want to replace a contract shipped by an upstream module without forking the source.
378
-
379
- ```ts
380
- // src/modules.ts — representative examples across override phases
381
- {
382
- id: 'example',
383
- from: '@app',
384
- overrides: {
385
- routes: {
386
- api: {
387
- // disable
388
- 'DELETE /api/example/items': null,
389
- // replace
390
- 'POST /api/example/items': {
391
- handler: async (req) => new Response(JSON.stringify({ ok: true }), { status: 200 }),
392
- metadata: { requireAuth: true, requireFeatures: ['example.manage'] },
393
- },
394
- },
395
- pages: {
396
- '/backend/example/items': null,
397
- },
398
- },
399
- events: {
400
- subscribers: {
401
- 'example.todo.created.notify': null,
402
- },
403
- },
404
- workers: {
405
- 'example:sync': null,
406
- },
407
- widgets: {
408
- injection: { 'example.toolbar': null },
409
- dashboard: { 'example.kpi': null },
410
- components: {
411
- 'page:/backend/example': {
412
- target: { componentId: 'page:/backend/example' },
413
- priority: 10,
414
- propsTransform: (props) => props,
415
- },
416
- },
417
- },
418
- notifications: {
419
- types: { 'example.notice': null },
420
- handlers: { 'example.notice.toast': null },
421
- },
422
- interceptors: { 'example.items.audit': null },
423
- commandInterceptors: { 'example.command.audit': null },
424
- enrichers: { 'example.items.enricher': null },
425
- guards: { 'example.backend.guard': null },
426
- cli: { 'example seed': null },
427
- setup: {
428
- defaultRoleFeatures: { admin: ['example.view'] },
429
- seedExamples: false,
430
- },
431
- acl: {
432
- features: { 'example.manage': null },
433
- },
434
- di: {
435
- exampleService: {
436
- register: (container, key) => container.register({ [key]: { mode: 'replacement' } }),
437
- },
438
- },
439
- encryption: {
440
- maps: { 'example:item': null },
441
- },
442
- },
443
- },
444
- ```
445
-
446
- Programmatic equivalent (boot-time, env-driven, or test scaffold):
447
-
448
- ```ts
449
- // src/bootstrap.ts (extra)
450
- import {
451
- applyApiRouteOverrides,
452
- applyPageRouteOverrides,
453
- applyWorkerOverrides,
454
- } from '@open-mercato/shared/modules/overrides'
455
-
456
- applyApiRouteOverrides({
457
- 'GET /api/example/items': null,
458
- })
459
- applyPageRouteOverrides({
460
- '/backend/example/items': null,
461
- })
462
- applyWorkerOverrides({
463
- 'example:sync': null,
464
- })
465
- ```
466
-
467
- Key rules:
468
-
469
- - Keys are `'METHOD /api/path'`; method is normalized, path leading slash optional, trailing slashes stripped.
470
- - Page route keys are `'/backend/path'` or `'/frontend/path'`.
471
- - `null` disables the matching contract; a definition replaces it.
472
- - Programmatic > `modules.ts` > file-based where supported > base. The dispatcher MUST run before registries first-load — the template's `bootstrap.ts` already does this.
473
- - Stale override keys log a warning so operators notice renamed or removed upstream contracts.
474
-
475
- Full reference: `framework/modules/overrides` and `framework/modules/routes-and-pages`.
476
-
477
- ## Disabling the Dashboards Module: Update /backend
478
-
479
- The default `/backend` page (`src/app/(backend)/backend/page.tsx`) renders `<DashboardScreen />` from `@open-mercato/ui/backend/dashboard`. That component's data flow depends on the `dashboards` module being enabled — widgets, layouts, and the dashboard API routes all live there.
480
-
481
- If you or the `om-trim-unused-modules` skill removes `dashboards` from `src/modules.ts`, you MUST also update `src/app/(backend)/backend/page.tsx` so it no longer renders `<DashboardScreen />`. Replace the body with a `redirect(...)` to the first backend page the current user can see — pick from the main sidebar group, fall back to `/backend/profile` when nothing else is enabled. Example:
482
-
483
- ```tsx
484
- import { getAuthFromCookies } from '@open-mercato/shared/lib/auth/server'
485
- import { redirect } from 'next/navigation'
486
-
487
- export default async function BackendIndex() {
488
- const auth = await getAuthFromCookies()
489
- if (!auth) redirect('/api/auth/session/refresh?redirect=/backend')
490
- // dashboards disabled — pick the first enabled backend page the user can reach
491
- redirect('/backend/customers/people') // replace with your project's landing page
492
- }
493
- ```
494
-
495
- Do this in the same change where you disable the module — otherwise `/backend` will crash at request time because `DashboardScreen` will be missing from the bundle (or, worse, will render but fail to load widgets).
496
-
497
- ## Feature Grants: New Features MUST Be Visible Immediately
498
-
499
- 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:
500
-
501
- 1. **Add it to `defaultRoleFeatures`** in the same module's `setup.ts` so the admin role and any other appropriate default roles receive it on every new tenant setup:
502
-
503
- ```ts
504
- // src/modules/<module>/setup.ts
505
- export const setup = {
506
- defaultRoleFeatures: {
507
- admin: ['my_module.view', 'my_module.manage'],
508
- employee: ['my_module.view'],
509
- },
510
- // ...
511
- }
512
- ```
513
-
514
- 2. **Reconcile existing tenants** by running the ACL sync command so existing installs pick up the new feature without a reinstall:
515
-
516
- ```bash
517
- yarn mercato auth sync-role-acls
518
- ```
519
-
520
- Do this automatically unless the user has explicitly said otherwise. If the current user has a default role that should access the module, they should see the feature you just built — not stare at a blank admin because their role is missing the grant. Use `--tenant <tenantId>` only when the user asks to target one tenant.
521
-
522
- 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.
523
-
524
- ## Mandatory Module Mechanisms (no DIY substitutes)
525
-
526
- 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.
527
-
528
- | Concern | Canonical mechanism | Reference |
53
+ | Route | Match | Context |
529
54
  |---|---|---|
530
- | 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> |
531
- | 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> |
532
- | 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> |
533
- | 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> |
534
- | CRUD APIs (factory) | `makeCrudRoute({ metadata, orm, list, create, update, del, indexer })` from `@open-mercato/shared/lib/crud/factory` — all methods in one `api/<entities>/route.ts`, export named `{ GET, POST, PUT, DELETE }` and `metadata` | <https://docs.open-mercato.dev/framework/api/crud-factory> |
535
- | CRUD forms in admin | `<CrudForm fields onSubmit onDelete />` from `@open-mercato/ui/backend/CrudForm`; use `createCrud` / `updateCrud` / `deleteCrud` from `@open-mercato/ui/backend/utils/crud` in the handlers; `createCrudFormError` from `@open-mercato/ui/backend/utils/serverErrors`. Never `apiPath`, `mode`, or `resourceId` props. Never raw `<form>` or raw `fetch` | <https://docs.open-mercato.dev/framework/admin-ui/crud-form> |
536
- | DataTables in admin | `<DataTable columns data isLoading error pagination />` from `@open-mercato/ui/backend/DataTable`; fetch data with `apiCall` + `useQuery` and pass it explicitly — no built-in `apiPath` data-fetching prop. Use optional `entityId` only for widget injection slot targeting | <https://docs.open-mercato.dev/framework/admin-ui/data-grids> |
537
- | 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> |
538
- | 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> |
539
- | **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> |
540
- | 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> |
541
- | 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> |
542
- | Events between modules | `<module>/events.ts` with `createModuleEvents({ moduleId, events } as const)`; subscribers in `subscribers/*.ts` | <https://docs.open-mercato.dev/framework/events/overview> |
543
- | 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/`) |
544
-
545
- > 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.
546
-
547
- ## Data Encryption (sensitive / GDPR-relevant fields)
548
-
549
- 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".**
550
-
551
- 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.
552
-
553
- ```ts
554
- // src/modules/<module>/encryption.ts
555
- import type { ModuleEncryptionMap } from '@open-mercato/shared/modules/encryption'
556
-
557
- export const defaultEncryptionMaps: ModuleEncryptionMap[] = [
558
- {
559
- entityId: '<module>:<entity>',
560
- fields: [
561
- { field: 'first_name' },
562
- { field: 'last_name' },
563
- { field: 'phone' },
564
- // For deterministic equality lookups (e.g. login by email), add a sibling hash column.
565
- { field: 'email', hashField: 'email_hash' },
566
- ],
567
- },
568
- ]
569
-
570
- export default defaultEncryptionMaps
571
- ```
572
-
573
- Read with decryption — never raw `em.find` / `em.findOne` on encrypted columns:
574
-
575
- ```ts
576
- import { findWithDecryption, findOneWithDecryption } from '@open-mercato/shared/lib/encryption/find'
577
-
578
- // Signature: (em, entityName, where, options?, scope?). Pass MikroORM FindOptions in slot 4
579
- // (or `undefined`), and the decryption scope in slot 5.
580
- const records = await findWithDecryption(em, '<Entity>', filter, undefined, { tenantId, organizationId })
581
- const single = await findOneWithDecryption(em, '<Entity>', { id }, undefined, { tenantId, organizationId })
582
- ```
583
-
584
- Apply maps to existing tenants after declaring them (new tenants pick them up automatically during `auth:setup`):
585
-
586
- ```bash
587
- yarn mercato entities seed-encryption --tenant <tenantId> [--organization <orgId>]
588
- ```
589
-
590
- Notes:
591
-
592
- - 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.
593
- - The `vector` module stores raw embeddings unencrypted in the vector store — treat embeddings as sensitive even when the source text is encrypted.
594
- - 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`).
595
-
596
- Full guide: <https://docs.open-mercato.dev/user-guide/encryption>.
597
-
598
- ## Design System (Strict — applies to every UI change)
599
-
600
- 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 `om-auto-review-pr`.
601
-
602
- **Colors.** NEVER hardcode Tailwind status colors (`text-red-500`, `bg-green-100`, `text-amber-*`, `text-emerald-*`, `bg-blue-*`). Use semantic tokens: `text-status-error-text`, `bg-status-success-bg`, `border-status-warning-border`, `text-status-info-icon`. For destructive actions (buttons) use the `destructive` token (`text-destructive`, `bg-destructive`). All status tokens have dedicated dark-mode values — no `dark:` overrides needed.
603
-
604
- **Typography.** NEVER use arbitrary text sizes (`text-[11px]`, `text-[13px]`, `text-[15px]`). Use the Tailwind scale: `text-xs` (12), `text-sm` (14), `text-base` (16), `text-lg` (18), `text-xl` (20), `text-2xl` (24). For 11px uppercase labels use the `text-overline` token.
605
-
606
- **Components to use instead of raw HTML.**
607
-
608
- | I need to… | Use |
609
- |---|---|
610
- | Show inline error / success / warning / info | `<Alert variant="destructive\|success\|warning\|info">` |
611
- | Show a toast | `flash('message', 'success\|error\|warning\|info')` |
612
- | Confirm a destructive action | `useConfirmDialog()` |
613
- | Display entity status (active / draft / archived) | `<StatusBadge variant={statusMap[status]} dot>` |
614
- | Wrap a form input with label + error | `<FormField label="…" error={…}>` |
615
- | Section header with count + action | `<SectionHeader title="…" count={n} action={…}>` |
616
- | Collapsible section | `<CollapsibleSection title="…">…</CollapsibleSection>` |
617
- | Loading state | `<LoadingMessage />`, `<Spinner />`, or `<DataLoader />` |
618
- | Empty state | `<EmptyState>` (or `emptyState` prop on `DataTable`) |
619
-
620
- **Icons (page body).** Use `lucide-react` for every icon inside page body UI (`Page`, `DataTable`, `CrudForm`, cards, buttons, etc.) — never inline `<svg>`. Sizes: `size-3`, `size-4` (default), `size-5`, `size-6`. Do not override `strokeWidth` per-instance. Icon-only buttons MUST have `aria-label`.
55
+ | `architecture` | Capability/ownership/field-vs-history choice, boundary, upgrade, override, or registry failure; routine discovery stays in its area | `.ai/guides/architecture.md` + named facts |
56
+ | `module-data` | App-owned domain/data/API | `src/modules/<id>/` + `.ai/guides/contracts.md`; add architecture only when ownership is unresolved |
57
+ | `umes` | Extend/replace installed behavior | `.ai/guides/extensions.md` + named facts |
58
+ | `backend-ui` | Authored/restyled rendered surface or browser UI state/session bootstrap | `.ai/guides/backend-ui.md` + host facts; host-provided integration credentials/health UI alone does not match |
59
+ | `integration` | Provider, spreadsheet/CSV/file I/O, sync/webhook/storage | `.ai/guides/integrations.md`; imports = `integration`; AI consuming files = `ai-workflow`, NEVER `integration` unless transport/storage changes |
60
+ | `ai-workflow` | Agent/tool/MCP/orchestrator/durable workflow | `.ai/guides/ai-workflows.md` + facts; schedules/queues/workers/retries/progress alone are `module-data` |
61
+ | `debugging` | Bug/security/drift/runtime inconsistency | `.ai/guides/testing-debugging.md` + affected areas |
621
62
 
622
- **Icons (`page.meta.ts`).** In `src/modules/<module>/backend/**/page.meta.ts` files, the `icon` field has a stricter contract — it is consumed by the sidebar renderer and must be a plain `React.createElement('svg', …)` tree, NOT a direct `lucide-react` import. After the lucide-react major upgrade, importing `{ IconName } from 'lucide-react'` inside a meta file can break page-metadata serialization and cause the sidebar to drop the icon. Use this pattern — which is the one currently used by `customers/people/page.meta.ts` and every other shipping module:
63
+ API/command/record/status/event/UI changes/guards = `umes`; app persistence = `module-data`; installed guard without app persistence = `umes` only, so do not load contracts; read-only behavior/auth/dependents/customization = `framework-context` (alone: no extensions guide; report `installed-version`). Facts do not. Providers are published, never `packages/*`.
623
64
 
624
- ```ts
625
- import React from 'react'
65
+ ### Axis 2 — Work Units
626
66
 
627
- const myIcon = React.createElement(
628
- 'svg',
629
- {
630
- width: 16,
631
- height: 16,
632
- viewBox: '0 0 24 24',
633
- fill: 'none',
634
- stroke: 'currentColor',
635
- strokeWidth: 2,
636
- strokeLinecap: 'round',
637
- strokeLinejoin: 'round',
638
- },
639
- React.createElement('path', { d: 'M17 21v-2a4 4 0 0 0-4-4H7a4 4 0 0 0-4 4v2' }),
640
- React.createElement('circle', { cx: 9, cy: 7, r: 4 }),
641
- )
67
+ Match every work-unit row; OPEN its skill before selection.
642
68
 
643
- export const metadata = {
644
- requireAuth: true,
645
- requireFeatures: ['my_module.view'],
646
- pageTitle: 'My Page',
647
- pageTitleKey: 'my_module.nav.title',
648
- icon: myIcon,
649
- // ...
650
- }
651
- ```
652
-
653
- Grab the `d="..."` path values from the lucide icon you want — for example by searching `lucide.dev/icons/<name>` — and inline them via `React.createElement('path', { d: '…' })`. This keeps the meta file free of runtime imports while preserving a consistent visual language.
654
-
655
- **Dialogs.** Every dialog MUST submit on `Cmd/Ctrl+Enter` and cancel on `Escape`.
656
-
657
- **Boy Scout rule.** When modifying a file that still has hardcoded status colors or arbitrary text sizes, migrate at minimum the lines you touched to semantic tokens.
658
-
659
- ## Agent Automation / Auto-Skills
660
-
661
- These auto-* agent skills let you delegate whole units of work to an autonomous agent. They are maintained in the shared [open-mercato/skills](https://github.com/open-mercato/skills) collection — `create-mercato-app` installs them automatically during agentic setup; run **`yarn install-skills`** to refresh them or to install them later if scaffolding skipped the step (`npx skills add`; re-runs refresh via `npx skills update`). They install into the canonical cross-agent directory `.agents/skills/` — read natively by Codex and Cursor, and mirrored into `.claude/skills/<name>` for Claude Code, which cannot read it — and are invoked by name; the matching `.ai/skills/<name>/` folder holds the standalone override the skill reads on top of its built-in workflow (any default branch name, optional pipeline labels, and a validation gate that probes `package.json` for available scripts). Repo-specific settings live in `.ai/agentic.config.json`. The `claude "…"` invocations below are examples for Claude Code — other harnesses invoke the same skills by name with their own slash-command syntax.
662
-
663
- | Skill | When to use | Invocation |
664
- |-------|-------------|------------|
665
- | `om-auto-create-pr` | Delegate an arbitrary task end-to-end and receive it as a PR against your default branch | `claude "/om-auto-create-pr <task description>"` |
666
- | `om-auto-continue-pr` | Resume an in-progress agent PR that wasn't finished in one run | `claude "/om-auto-continue-pr <PR#>"` |
667
- | `om-auto-review-pr` | Run a thorough automated code review on a PR (with optional autofix) | `claude "/om-auto-review-pr <PR#>"` |
668
- | `om-auto-fix-issue` | Fix a GitHub issue by number and open a PR linked to it (drives the installed chain `om-verify-in-repo` → `om-root-cause` → `om-fix` → `om-open-pr` → `om-auto-review-pr`) | `claude "/om-auto-fix-issue <issue#>"` |
669
- | `om-setup-agent-pipeline` | Tailor the agent PR pipeline — the scaffold ships a working `.ai/agentic.config.json` (GitHub tracker, labels off), so run this only to enable the label pipeline + QA gate, switch tracker, or change validation commands | `claude "/om-setup-agent-pipeline"` |
670
- | `om-apply-upgrade-notes` | Re-sync the installed pipeline artifacts (tracker descriptor, config) after `yarn install-skills` refreshed the external collection | `claude "/om-apply-upgrade-notes"` |
671
- | `om-trim-unused-modules` | Propose disabling built-in modules you don't use (classic-mode slimdown after adding your own module) — ships locally, installed by tier | `claude "/om-trim-unused-modules"` |
672
-
673
- Notes:
674
-
675
- - The external skills install automatically when the app is scaffolded, including the chain steps the skills above invoke (`om-prepare-test-env` for integration tests, the autofix chain steps); run `yarn install-skills` to refresh them or if that step was skipped (and `yarn install-skills --list` to see the local tier catalog). It is offline-safe: pass `--no-external` to skip the network step.
676
- - The skills probe `gh repo view --json defaultBranchRef` for your repo's default branch; no assumption that it's `main` or `develop`.
677
- - Pipeline labels (`review`, `qa`, `merge-queue`, etc.) are opt-in — the skills detect which labels exist in your repo via `gh label list` and skip gracefully when they're missing. If you want the full workflow, the skill README in each skill folder has a `gh label create` snippet you can paste in once.
678
- - The validation gate runs `yarn typecheck`, `yarn test`, `yarn generate`, and `yarn build` only when the corresponding `package.json` script exists.
69
+ | Route | Work unit | Skill/context |
70
+ |---|---|---|
71
+ | `architecture` | Explain/choose module, UMES, package, eject | architecture; `om-help` for an unresolved or comparative choice across these mechanisms |
72
+ | `module-data` | Business slice or multi-seam domain/API/command fix | MUST load `om-module-scaffold` + its exact `.ai/skills/om-module-scaffold/references/business-one-shot-blueprints.md` key, which resolves units inside the slice, not ownership — an ownership/capability outline adds `architecture` |
73
+ | `spec-pr` | Spec/plan | Axis 3; phases+integration coverage (`integration-coverage`); no domain routes |
74
+ | `architecture` | Upgrade audit or disable built-in | troubleshooter + framework context, or trim skill + exact `src/modules.ts`/`package.json` |
75
+ | `architecture` + `integration` + `framework-context` | Provider superseded by installed capability | integration builder + exact framework context |
76
+ | `module-data` | Entity/link/validator/migration/encryption/lock/transaction | `om-data-model-design` + contracts |
77
+ | `module-data` | CRUD/API/command/OpenAPI/ACL/setup/mutation | `om-module-scaffold` + contracts |
78
+ | `backend-ui` | Form/table/page/renderer/middleware/nav/i18n/UI states | `om-backend-ui-design` + backend UI |
79
+ | `module-data` | Search/analytics/event/notification/message/worker/progress/cache/CLI | scaffold + contracts |
80
+ | `umes` | Fields/extension entities/links/enrichers/injection/interceptors/guards/subscribers/DOM/widgets/toggles/overrides | `om-system-extension` + extensions; choices load `mechanism-selector` + `extension-branches` |
81
+ | `integration` | Provider/credentials/health/webhook/files/client/reconciliation/package | `om-integration-builder` + integrations |
82
+ | `ai-workflow` | Agent/tool/MCP/OpenCode/Code Mode/orchestrator/AI file or content drafting/attachment/override | `om-create-ai-agent` + AI/workflows; MCP/OpenCode loads `surface-selector` + `ai_assistant` facts |
83
+ | `ai-workflow` | Workflow/activity/user task/idempotency/output/progress | `om-build-workflow` + AI/workflows |
84
+ | `testing` | REQUEST says test/coverage/prove, or verify by exercising API/browser/screen sizes/keyboard/screen-reader—not a fix's implicit regression duty or review/audit/config check | MUST read `.ai/guides/testing-debugging.md` + external `om-integration-tests` for integration/E2E/app tests |
85
+ | `debugging` | Reproduce/root-cause/minimal fix/regression oracle | `om-troubleshooter` + testing/debugging |
86
+ | `framework-context` | Exact installed contract still unknown | bounded `om-framework-context`, last |
87
+ | `debugging` + `testing` | Add/fix recurring harness case/test | `om-evolve-harness` |
88
+
89
+ `framework-context`: resolve one named module/framework fact first. Use bounded source only for an unresolved exact contract, current behavior, authorization, dependents, or safest customization seam; never for “installed contracts” alone.
90
+
91
+ ### Axis 3 — SDLC and Delivery
92
+
93
+ Pinned delivery skills: `yarn install-skills` (refresh: `--update`). Read BOTH `.agents/skills/<id>/SKILL.md` and a matching `.ai/skills/<id>/SKILL.md` override. Commit+ready PR MUST add `spec-pr`, read `.ai/skills/om-auto-create-pr/SKILL.md`, and keep task routes (`delivery-route-preserves-task-routes`).
94
+
95
+ | Route ID | Delivery need | Skill |
96
+ |---|---|---|
97
+ | `spec-pr` | Write/revise spec | MUST invoke `om-spec-writing` (OMH-005) + `.ai/guides/spec-delivery.md` + config specs path |
98
+ | `spec-pr` | Implement approved phases locally | `om-implement-spec` (OMH-006) |
99
+ | `spec-pr` | Whole-spec / commit+ready PR / issue / review | `om-auto-implement-spec` / `om-auto-create-pr` / `om-auto-fix-issue` / `om-auto-review-pr` |
100
+ | `testing` | Integration/E2E/UI QA | `om-integration-tests` / `om-auto-qa-pr` |
101
+ | — | No PR/spec workflow requested | Do not load delivery skills |
679
102
 
680
- 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.
103
+ Absent skill: run `yarn install-skills` once; never substitute.
681
104
 
682
- 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 `.mercato/next/dev` plus legacy `.next` caches and restart `yarn dev`.
105
+ ### Token-Efficient Assembly Policy
683
106
 
684
- 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.
107
+ - Load matched guides once, then only needed references/facts.
108
+ - Hard budgets: guide > skill > references; open a reference only for its named subject.
109
+ - Specs: open one match; `spec-pr` reads template via spec-delivery.
110
+ - Inspect app call sites before bounded `framework-context`.
111
+ - Additive page/form/table/conflict UI skips it.
112
+ - Never bulk-read guide, skill, fact, or source trees.
685
113
 
686
- ### Path Aliases
114
+ ## Module-Specific Facts
687
115
 
688
- - `@/*` → `./src/*`
689
- - `@/.mercato/*` → `./.mercato/*`
116
+ Load facts for every named/targeted module, not incidental use. Mechanisms: events/subscribers→events; long operation/progress→progress; provider settings/health/OAuth→integrations; sync/import→data_sync. Hosts: session/auth→auth; customer/contact/deal/pipeline→customers; product/price/stock/inventory→catalog; currency/money→currencies; cart/checkout/shopper→checkout; portal→portal + customer_accounts; quote/order/invoice/sales assistant→sales; notification→notifications; webhook/callback→webhooks; schedule/reminder→scheduler; workflow/activity/user task→workflows; assistant→ai_assistant; maintained query index/reindex→query_index; search convergence→search. staff/employee≠optional staff; audit/record-who≠audit_logs unless extended. App primitives skip api_docs/search/query_index unless changed.
690
117
 
691
- ### i18n
118
+ <!-- om:module-guides:start -->
119
+ <!-- om:module-guides:end -->
692
120
 
693
- Translation files in `src/i18n/{locale}.json`. Supported locales: en, pl, es, de.
121
+ ## Working Sequence
694
122
 
695
- ## Requirements
123
+ 1. `spec-pr`: list `.ai/specs` once; open one match; plan-only skips specs.
124
+ 2. Route; load only matched guides/skills/facts.
125
+ 3. Implement the smallest complete slice through real call sites.
126
+ 4. Discovery change: run `yarn generate`; then the smallest gate/integration paths.
696
127
 
697
- - Node.js >= 24
698
- - Yarn (via corepack)
128
+ Precedence: root → BC → installed `AGENTS.md` → facts; stop on skew/conflict; never guess.