@open-mercato/cli 0.6.7 → 0.6.8-canary.319.1.5b4be4bc52

package/.turbo/turbo-build.log

@@ -1,10 +1,12 @@
-[build:cli] found 96 entry points
+[build:cli] found 101 entry points
 Copied create-app/agentic/ → dist/agentic/
-Discovered 7 standalone guides → dist/agentic/guides/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for ai_assistant
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_gmail
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for checkout
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:11
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:30
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:56
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for content
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_docs
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_keys
@@ -20,14 +22,72 @@ Discovered 7 standalone guides → dist/agentic/guides/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customers
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dashboards
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for data_sync
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for design_system
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dictionaries
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for directory
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for entities
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for feature_toggles
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for inbox_ops
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for integrations
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for messages
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for notifications
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for payment_gateways
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for perspectives
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for planner
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for portal
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for progress
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for query_index
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for resources
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sales
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for shipping_carriers
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for staff
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_excel
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for translations
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for wms
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for workflows
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for record_locks
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for security
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sso
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for system_status_overlays
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for events
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for gateway_stripe
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for onboarding
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for scheduler
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for search
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for generators
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for storage_s3
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_akeneo
+Generated 55 module fact-sheets → dist/agentic/guides/modules/
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for webhooks
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for ai_assistant
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_gmail
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for channel_imap
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for checkout
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:11
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:30
+[module-facts] searchConfig entityId is not statically resolvable: /home/runner/work/open-mercato/open-mercato/packages/checkout/src/modules/checkout/search.ts:56
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for content
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_docs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for api_keys
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for attachments
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for audit_logs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for auth
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for business_rules
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for catalog
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for communication_channels
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for configs
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for currencies
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customer_accounts
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for customers
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dashboards
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for data_sync
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for design_system
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for dictionaries
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for directory
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for entities
-Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for feature_toggles
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for inbox_ops
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for integrations
-[build:cli] built successfully
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for messages
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for notifications
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for payment_gateways
@@ -57,3 +117,16 @@ Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for storage_s3
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for sync_akeneo
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for webhooks
+[module-facts] module registry unavailable (registryPath not provided); API route auth omitted for example
+[module-facts] example unresolved-first-party-target: example:auto-default-priority:example.todo.creating (src/modules/example/subscribers/auto-default-priority.ts)
+[module-facts] example unresolved-first-party-target: example:example-event:example.ping (src/modules/example/subscribers/example-event.ts)
+[module-facts] example unresolved-first-party-target: example:prevent-uncomplete:example.todo.updating (src/modules/example/subscribers/prevent-uncomplete.ts)
+[module-facts] example unresolved-first-party-target: example.injection.crud-validation@example:phase-c-handlers:example:phase-c-handlers (src/modules/example/widgets/injection-table.ts)
+[module-facts] example unresolved-first-party-target: example.todo-limit:example.todo (src/modules/example/data/guards.ts)
+[module-facts][reference] unresolved first-party target: example:example:auto-default-priority:example.todo.creating
+[module-facts][reference] unresolved first-party target: example:example:example-event:example.ping
+[module-facts][reference] unresolved first-party target: example:example:prevent-uncomplete:example.todo.updating
+[module-facts][reference] unresolved first-party target: example:example.injection.crud-validation@example:phase-c-handlers:example:phase-c-handlers
+[module-facts][reference] unresolved first-party target: example:example.todo-limit:example.todo
+Generated 1 local reference projection(s) → dist/agentic/guides/reference-modules/
+[build:cli] built successfully

package/build.mjs

@@ -1,4 +1,5 @@
 import { chmodSync, cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createHash } from 'node:crypto'
 import { dirname, join } from 'node:path'
 import { fileURLToPath, pathToFileURL } from 'node:url'
 import { atomicWriteFileSync } from '../../scripts/lib/add-js-extension.mjs'
@@ -26,11 +27,26 @@ await buildPackage(packageDir, {
     // Copy agentic source files from create-app so generators can read them at runtime.
     const agenticSrc = join(packageDir, '..', 'create-app', 'agentic')
     if (existsSync(agenticSrc)) {
+      rmSync(join(outdir, 'agentic'), { recursive: true, force: true })
       cpSync(agenticSrc, join(outdir, 'agentic'), { recursive: true })
       console.log('Copied create-app/agentic/ → dist/agentic/')
     }
 
-    // Discover standalone guides across sibling packages.
+    const repositoryRoot = join(packageDir, '..', '..')
+    const upstreamDir = join(outdir, 'agentic', 'guides', 'upstream')
+    mkdirSync(upstreamDir, { recursive: true })
+    const cliVersion = JSON.parse(readFileSync(join(packageDir, 'package.json'), 'utf8')).version ?? null
+    const upstreamManifest = { version: 1, generator: `@open-mercato/cli@${cliVersion ?? 'unknown'}`, files: {} }
+    for (const file of ['AGENTS.md', 'BACKWARD_COMPATIBILITY.md']) {
+      const source = join(repositoryRoot, file)
+      const destination = join(upstreamDir, file)
+      cpSync(source, destination)
+      upstreamManifest.files[file] = createHash('sha256').update(readFileSync(source)).digest('hex')
+    }
+    writeFileSync(join(upstreamDir, 'manifest.json'), `${JSON.stringify(upstreamManifest, null, 2)}\n`)
+
+    // Discover module-specific standalone guides across sibling packages. Package-level
+    // guides are intentionally not shipped because they duplicate routed conceptual guides.
     const packagesDir = join(packageDir, '..')
     const guidesDestDir = join(outdir, 'agentic', 'guides')
     mkdirSync(guidesDestDir, { recursive: true })
@@ -39,9 +55,10 @@ await buildPackage(packageDir, {
     // retains a removed module's full guide or fact-sheet. The legacy `core.<module>.md`
     // redirect stubs are no longer emitted (#3754); this purge also deletes any that linger
     // in an incremental `dist/` from an older build. Mirrors packages/create-app/build.mjs;
-    // the conceptual `module-system.md` and the single-dot package guides are
-    // re-copied/re-discovered below.
+    // conceptual guides remain while stale single-dot package guides are removed below.
     rmSync(join(guidesDestDir, 'modules'), { recursive: true, force: true })
+    rmSync(join(guidesDestDir, 'reference-modules'), { recursive: true, force: true })
+    rmSync(join(guidesDestDir, 'reference-module-facts.json'), { force: true })
     for (const entry of readdirSync(guidesDestDir)) {
       if (/^core\..+\.md$/.test(entry)) {
         rmSync(join(guidesDestDir, entry))
@@ -50,10 +67,11 @@ await buildPackage(packageDir, {
 
     let guidesFound = 0
     for (const pkg of readdirSync(packagesDir)) {
+      // Package-level source guides remain for monorepo context, but standalone apps route
+      // through conceptual and module-level guides, so remove their stale emitted copies.
       const guideSource = join(packagesDir, pkg, 'agentic', 'standalone-guide.md')
       if (existsSync(guideSource)) {
-        cpSync(guideSource, join(guidesDestDir, `${pkg}.md`))
-        guidesFound++
+        rmSync(join(guidesDestDir, `${pkg}.md`), { force: true })
       }
 
       const modulesDir = join(packagesDir, pkg, 'src', 'modules')
@@ -76,15 +94,24 @@ await buildPackage(packageDir, {
     // the freshly built ts-morph extractor + resolver-routed discovery, so
     // `mercato agentic:init` bundles the same guides as a create-mercato-app scaffold
     // (packages/create-app/build.mjs). Discovery goes through the resolver, never a
-    // hardcoded packages/* path (.ai/lessons.md §161-169).
-    const { extractAllModuleFacts, renderModuleFactsJson } = await import(
-      pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href
-    )
-    const { discoverPackageModuleSources } = await import(
+    // hardcoded packages/* path (.ai/lessons/standalone-scaffolding-and-generators-must-not-assume.md).
+    const {
+      assertPackageModuleFactsOnly,
+      extractAllModuleFacts,
+      extractLocalReferenceModuleFacts,
+      renderModuleFactsJson,
+      renderReferenceModuleFactsJson,
+    } = await import(pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts.js')).href)
+    const { discoverLocalReferenceModuleSource, discoverPackageModuleSources } = await import(
       pathToFileURL(join(outdir, 'lib', 'generators', 'module-facts-discovery.js')).href
     )
     const { createResolver } = await import(pathToFileURL(join(outdir, 'lib', 'resolver.js')).href)
 
+    // Mirrors packages/create-app/build.mjs: the disabled app-local example never enters
+    // the normal package outputs and is projected into its own reference bundle so
+    // `mercato agentic:init` bundles exactly what a create-mercato-app scaffold does.
+    const REFERENCE_MODULE_IDS = ['example']
+
     const sources = discoverPackageModuleSources(createResolver(join(packagesDir, '..')))
     if (sources.length > 0) {
       const registryPath = join(packagesDir, '..', 'apps', 'mercato', '.mercato', 'generated', 'modules.runtime.generated.ts')
@@ -95,21 +122,51 @@ await buildPackage(packageDir, {
         coreVersion = null
       }
 
-      const { factsByModule, markdownByModule, warnings } = extractAllModuleFacts({
+      const { factsByModule, markdownByModule, frameworkMarkdown, warnings } = extractAllModuleFacts({
         sources,
         registryPath: existsSync(registryPath) ? registryPath : null,
         coreVersion,
       })
 
+      assertPackageModuleFactsOnly(factsByModule)
+
       const modulesGuidesDir = join(guidesDestDir, 'modules')
       mkdirSync(modulesGuidesDir, { recursive: true })
       for (const [moduleId, markdown] of Object.entries(markdownByModule)) {
         writeFileSync(join(modulesGuidesDir, `${moduleId}.md`), markdown)
       }
       writeFileSync(join(guidesDestDir, 'module-facts.json'), renderModuleFactsJson(factsByModule))
+      writeFileSync(join(guidesDestDir, 'framework-extension-points.md'), frameworkMarkdown)
 
       for (const warning of warnings) console.warn(warning)
       console.log(`Generated ${Object.keys(markdownByModule).length} module fact-sheets → dist/agentic/guides/modules/`)
+
+      const referenceBundle = {}
+      const referenceGuidesDir = join(guidesDestDir, 'reference-modules')
+      const templateRoot = join(packagesDir, 'create-app', 'template')
+      for (const moduleId of REFERENCE_MODULE_IDS) {
+        const reference = discoverLocalReferenceModuleSource({ appRoot: templateRoot, moduleId })
+        if (!reference) {
+          throw new Error(`[module-facts] reference module "${moduleId}" is missing from the create-app template`)
+        }
+        const { entry, markdown, warnings: referenceWarnings, unresolvedTargets } = extractLocalReferenceModuleFacts({
+          packageSources: sources,
+          reference,
+          registryPath: existsSync(registryPath) ? registryPath : null,
+          coreVersion,
+        })
+        referenceBundle[moduleId] = entry
+        mkdirSync(referenceGuidesDir, { recursive: true })
+        writeFileSync(join(referenceGuidesDir, `${moduleId}.md`), markdown)
+        for (const warning of referenceWarnings) console.warn(warning)
+        for (const target of unresolvedTargets) {
+          console.warn(`[module-facts][reference] unresolved first-party target: ${target}`)
+        }
+      }
+      writeFileSync(join(guidesDestDir, 'reference-module-facts.json'), renderReferenceModuleFactsJson(referenceBundle))
+      console.log(
+        `Generated ${REFERENCE_MODULE_IDS.length} local reference projection(s) → dist/agentic/guides/reference-modules/`,
+      )
     } else {
       console.warn('[module-facts] no package modules discovered; skipping fact-sheet generation')
     }

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

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

package/dist/agentic/codex/enforcement-rules.md

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

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

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

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

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

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

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

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

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