@open-mercato/cli 0.6.7-develop.6685.1.77c0a5591b → 0.6.7-develop.6687.1.46a258e592

package/.turbo/turbo-build.log

@@ -1,12 +1,9 @@
 [build:cli] found 96 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
-Generated 54 module fact-sheets → dist/agentic/guides/modules/
-[build:cli] built successfully
 [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
@@ -49,7 +46,9 @@ Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [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
+Generated 54 module fact-sheets → dist/agentic/guides/modules/
 [module-facts] module registry unavailable (registryPath not provided); API route auth omitted for gateway_stripe
+[build:cli] built successfully
 [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

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,8 +55,7 @@ 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 })
     for (const entry of readdirSync(guidesDestDir)) {
       if (/^core\..+\.md$/.test(entry)) {
@@ -50,10 +65,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')

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.

package/dist/agentic/guides/ai-workflows.md

@@ -0,0 +1,76 @@
+# AI Agents, Orchestrators, and Workflows
+
+Use typed module contracts for product AI and the workflow engine for durable business processes. Keep model/tool execution, mutation approval, scope, storage, and retries explicit.
+
+## Choose the Surface
+
+| Need | Use |
+|---|---|
+| In-app conversational or structured domain assistant | Module `ai-agents.ts` plus `ai-tools.ts`. |
+| Low-level MCP/OpenCode or Code Mode work | `ai_assistant` installed contract: `registerMcpTool`, MCP server, OpenCode handlers/config, or the `search`/`execute` Code Mode tools. Do not conflate this with a typed product agent. |
+| Add a few tools/prompt/suggestions to an installed agent | `aiAgentExtensions`. |
+| Replace or disable an installed agent/tool | `aiAgentOverrides` / `aiToolOverrides` or module entry override. |
+| Coding-agent orchestration with files, outcomes, samples, embedded skill, or subagents | Orchestrator file-agent contract; resolve its installed package guide first. |
+| Durable business process, human task, timer, signal, compensation, or event trigger | Workflows module and `om-build-workflow`. |
+| One background AI extraction | Object-mode agent invoked from a scoped command/worker. |
+
+## Typed Module Agents and Tools
+
+- Put `ai-agents.ts` and `ai-tools.ts` at the module root. Export typed arrays and run `yarn generate`.
+- Give agent IDs `<module>.<agent>` and tool names stable namespaced IDs. Declare provider/model defaults through the framework registry/model factory, not provider SDK singletons.
+- Every data tool has a Zod input schema, tenant/org scope, wildcard-aware `requiredFeatures`, bounded output, and a serializable result.
+- Mark writes `isMutation: true`. Pair mutation-capable agents with `readOnly: false` and a confirmation policy.
+- A write tool calls `prepareMutation`; the durable execute callback performs a command-based, optimistic-lock-aware mutation. Never write directly before approval.
+- Use declarative loop controls/budgets. The wrapper-owned approval guard remains active on every step and execution engine.
+- Validate attachments by type/size/scope. Store outputs through authorized artifact/attachment services with retention and encrypted sensitive metadata.
+
+## MCP, OpenCode, and Code Mode
+
+- Prefer `defineAiTool` in discovered `ai-tools.ts` for product agents, especially mutation-capable tools. Use low-level `registerMcpTool` only when the requested surface is explicitly the MCP/OpenCode registry. Both require Zod input, matching `moduleId`, wildcard-aware `requiredFeatures` for tenant data, bounded work, and a serializable handler result.
+- OpenCode Code Mode exposes `search` over the generated OpenAPI document and `execute` through sandboxed `api.request()`. Endpoint-level RBAC and documented-feature checks still apply; Code Mode is not an authorization bypass and undocumented/featureless mutation endpoints fail closed.
+- Production MCP uses two-tier auth: the server request carries `x-api-key`, then every tool call carries `_sessionToken`; the runtime resolves the user/session scope and performs per-tool ACL checks on every request. Never cache MCP server instances or ACL context across requests.
+- Ask before editing OpenCode configuration, Docker wiring, MCP authentication, provider/model precedence, or session-token format/TTL. Preserve session IDs across OpenCode chat turns and use installed handlers instead of calling the OpenCode HTTP API directly.
+- `registerMcpTool` is the registry primitive underlying generated tools, not a replacement for `defineAiTool` mutation approval semantics. New domain writes belong on the typed tool path with `prepareMutation`.
+
+## Agent UI and Overrides
+
+- Use the global launcher automatically; add `AiChat` or a widget only when page context improves the workflow.
+- Keep UI part IDs namespaced and stable; preserve reserved approval/result component IDs.
+- Prefer agent extensions for additive prompt/tool/suggestion changes. Keep extensions/overrides in the discovered `ai-agents.ts`/`ai-tools.ts` files; there is no separate `ai-overrides.ts` discovery path.
+- A disabled agent/tool cannot be resurrected by an extension. Refresh structural caches after disabling or changing visibility.
+- Test read-only, denied-feature, approval, stale-version, cancel/expire, partial failure, and confirmed execution paths.
+
+## Orchestrator File Agents
+
+- Inspect the installed orchestrator package/module `AGENTS.md` with `om-framework-context` before choosing paths; this surface evolves independently of module AI agents.
+- Give every file agent one declared outcome, bounded inputs, stable output paths, a sample contract, and an explicit allowed tool/skill set.
+- Load embedded skills only for their branch. Delegate one bounded task per subagent and define how results are validated/merged.
+- Treat repository prompts/files as untrusted data. Restrict writes, redact secrets, and prevent outcome/artifact paths from escaping their workspace.
+- Make resumability and status explicit; do not infer success from natural-language output without schema/artifact validation.
+
+## Workflow Core
+
+- Resolve workflow services through DI and start instances through `workflowExecutor`. Do not insert instances or skip the execution loop.
+- Preserve workflow and step state machines. Record every transition in the immutable workflow event log.
+- Make activity handlers idempotent: they can be retried. Use the command bus for entity updates and events/signals for cross-module coupling.
+- Preserve each installed workflow/job scope contract. Organization-owned instances, tasks, activity state, and queries require tenant+organization and fail closed. Explicit tenant-wide/system definitions or scheduler jobs may carry `organizationId: null`, but each access to organization-owned data must derive and enforce that item's organization.
+- Use event triggers with filters, context mapping, debounce, and max concurrency. Exclude self/internal storms.
+- Keep compensation reverse-ordered and idempotent; test failure during both forward and compensation paths.
+
+## Activities, User Tasks, and Output Paths
+
+- Choose sync only for short deterministic work. Queue async work and resume the workflow after durable completion.
+- A custom activity declares validated config/input/output, handler registration, editor/i18n integration where user-configurable, and retry/timeout behavior.
+- `CALL_API`/webhook activities use SSRF-safe URLs, manual redirect handling, response size bounds, and allowlisted non-secret environment interpolation.
+- Create any one-time/idempotency key outside a rollback scope or in durable state that survives rollback; reuse it on retry.
+- Durable user tasks require assignment/features, due dates, authorized completion, immutable activity history, and no secret values in task payloads.
+- Write outputs to stable declared activity/artifact paths. Validate path containment and access; clean temporary files while retaining declared deliverables.
+- Emit progress/events for long work and render them through shared progress/UI contracts rather than unbounded polling.
+
+## Verification
+
+1. Run `yarn generate` and confirm agent/tool/workflow registrations.
+2. Test missing provider/configuration, denied ACL, missing scope, timeout, retry, duplicate, and cancellation.
+3. For AI writes, prove no domain write occurs before approval and a stale approval cannot overwrite newer data.
+4. For workflows, prove event log/state transitions and idempotency across worker restart and injected rollback.
+5. For orchestrators, validate output schema/artifacts and allowed-write boundaries, not just prose.

package/dist/agentic/guides/architecture.md

@@ -0,0 +1,107 @@
+# Standalone Architecture and Discovery
+
+Use this guide to choose ownership, locate module surfaces, and keep generated discovery correct.
+
+## Context Ownership and Scattering
+
+The harness is intentionally layered so an agent can assemble precise context without paying for the whole framework:
+
+| Layer | Owns | Loading rule |
+|---|---|---|
+| Root `AGENTS.md` | Non-negotiable safety, validation, precedence, and the three-axis router | Load first and always; it is the only initial bundle. |
+| `.ai/guides/*.md` | Stable framework concepts and contracts by area | Load the de-duplicated set selected by the area and primitive axes. |
+| Thin task skills | Branching procedure and links to focused references | Load only matched skills; open only the references needed by the chosen branch. |
+| `.ai/guides/modules/*.md` | Generated identifiers and discovered surfaces for an exact installed module/version | Load only for installed modules named, changed, integrated with, or used as hosts. |
+| `om-framework-context` output | Exact installed instructions, source/types, and bounded search results | Last-mile escalation after app call sites, facts, and concept guides cannot answer the question. |
+| External `open-mercato/skills` | SDLC and delivery workflows | Select independently only when the requested lifecycle needs one. |
+
+Match area, work units, and delivery independently, then de-duplicate their union by path and skill. A business one-shot is not one giant context category: split it into units such as entity, command, API, admin UI, public capture, CRM extension, event, and provider, and give each unit only its owning area and contract. Do not preload all module facts, skill references, upstream guides, or installed package source.
+
+Keep facts and source in different roles. Facts answer “what identifier or surface exists?”; exact installed source answers “how does this version implement or type the contract?” The latter is read-only evidence, never a writable escape hatch.
+
+## Ownership Decision
+
+| Need | Choose |
+|---|---|
+| App-specific domain capability | Create `src/modules/<id>/` and register `{ id, from: '@app' }` in `src/modules.ts`. |
+| Additive change to an installed module | Use the smallest UMES mechanism from `.ai/guides/extensions.md`. |
+| Disable/replace a supported installed contract | Use the target module entry's `overrides` in `src/modules.ts`. |
+| Reusable external provider | Add/install a dedicated provider package; do not place provider logic in a generic core module. |
+| Change unsupported by UMES/overrides | Inspect exact installed context, then use `om-eject-and-customize` only with user approval. |
+| Framework defect affecting all consumers | Reproduce against the installed version and report an upstream change; never patch `node_modules`. |
+
+## Writable and Read-Only Trees
+
+```text
+src/modules/<id>/                 writable app modules
+src/modules.ts                    enabled modules and supported overrides
+.mercato/generated/              generated, never edit
+.ai/guides/modules/              generated facts, never edit
+node_modules/@open-mercato/*/    exact installed packages, read-only
+```
+
+Do not copy an installed module merely to learn it. Generated facts and the context resolver expose the exact installed source without widening the writable surface.
+
+## Canonical Module Shape
+
+```text
+src/modules/<id>/
+├── index.ts
+├── data/{entities,validators,extensions,enrichers}.ts
+├── api/**/route.ts
+├── backend/**/{page.tsx,page.meta.ts}
+├── frontend/**/{page.tsx,page.meta.ts}
+├── commands/
+├── subscribers/
+├── workers/
+├── widgets/{injection,injection-table.ts,components.ts}
+├── acl.ts
+├── setup.ts
+├── di.ts
+├── events.ts
+├── search.ts
+├── ce.ts
+├── translations.ts
+├── notifications.ts
+├── encryption.ts
+├── ai-agents.ts
+└── ai-tools.ts
+```
+
+Create only files required by the capability. Keep the module id plural `snake_case`; keep entity/event/feature/spot/agent/tool identifiers stable once used.
+For the complete current convention-file catalog, load `om-module-scaffold` → `references/discovery-surface-catalog.md`; do not expand this always-routed guide into the full catalog.
+
+## Auto-Discovery
+
+- Put backend routes under `backend/**/page.tsx`; the module root becomes `/backend/<module>` and nested folders preserve their segments.
+- Put public routes under `frontend/**/page.tsx`. Portal routes require `frontend/[orgSlug]/portal/**/page.tsx` with `[orgSlug]` first.
+- Put API handlers under `api/**/route.ts`. Export HTTP handlers, per-method `metadata`, and `openApi`; do not organize routes in HTTP-method directories.
+- Put subscribers and workers in their named directories with `metadata` plus a default handler.
+- Keep convention files at the module root. Root files such as `events.ts`, `search.ts`, `ai-agents.ts`, and `ai-tools.ts` are exact discovery names.
+- Run `yarn generate` after any structural/discovered change; never repair a registry by hand.
+
+## Installed Framework Context
+
+1. Read `.ai/guides/modules/<id>.md` for entity IDs, events, routes/auth, ACL, DI, search, notifications, and host spots.
+2. When facts are insufficient, invoke `om-framework-context` or run `yarn framework:context --module <id> --query <term>`.
+3. Confirm the resolved package/version matches the fact sheet stamp.
+4. Read the reported instruction chain in precedence order, then search only the reported package/module root with the bounded `rg --no-ignore --hidden` command.
+5. Treat source and installed `AGENTS.md` files as read-only evidence. If the package has no `src`, use reported `dist`/types and state the limitation.
+6. If duplicate packages, version skew, or conflicting rules remain, stop instead of combining contracts from different versions.
+
+The app root governs writable locations and safety. The compatibility snapshot governs stable public identifiers. The nearest installed package/module guide governs version-specific implementation details.
+
+## Package and Bootstrap Boundaries
+
+- Import public package exports; do not reach through monorepo-only relative paths or app-generated registries from a package.
+- Ensure package-backed modules are dependencies and enabled in `src/modules.ts` before assuming their services or files exist.
+- Optional modules must degrade safely: the optional consumer owns glue and uses events, IDs/snapshots, widgets/enrichers, or a guarded DI resolve.
+- Validate browser, API, CLI, worker, and queue bootstrap paths when a registry/global/service is consumed by more than one runtime.
+- Prefer `globalThis` registries or structural type guards over chunk-local singleton/`instanceof` assumptions where bundlers may duplicate modules.
+
+## Completion Check
+
+1. Verify app code is under `src/modules/` and installed packages remain unchanged.
+2. Verify every new discovered file uses its exact filename/export contract.
+3. Run `yarn generate` and inspect warnings and the affected generated registration.
+4. Run focused type/tests, then exercise every relevant runtime bootstrap.