create-mercato-app 0.6.7-develop.6677.1.beabb7ca12 → 0.6.7-develop.6686.1.bdda5ed397

package/README.md

@@ -35,6 +35,8 @@ npx create-mercato-app <app-name> [options]
 |--------|-------------|
 | `--app <name>` | Bootstrap an official Open Mercato ready app from `open-mercato/ready-app-<name>` |
 | `--app-url <url>` | Bootstrap a ready app from a GitHub repository URL |
+| `--preset <id>` | Select the `classic`, `empty`, or `crm` starter without prompting |
+| `--agents <list>` | Set up `claude-code`, `codex`, `cursor`, a comma-separated subset, `all`, or `none` without prompting |
 | `--skip-agentic-setup` | Skip the interactive agentic setup wizard |
 | `--init-git` | Initialize a local Git repository after scaffolding |
 | `--no-init-git` | Do not prompt for or initialize a local Git repository |
@@ -64,6 +66,12 @@ npx create-mercato-app my-store --registry http://localhost:4873
 # Create a new app without the agentic setup wizard
 npx create-mercato-app my-store --skip-agentic-setup
 
+# Create a classic app with every supported AI coding-tool configuration
+npx create-mercato-app my-store --preset classic --agents all
+
+# Set up only Claude Code and Codex
+npx create-mercato-app my-store --agents claude-code,codex
+
 # Create a new app and initialize a local Git repository
 npx create-mercato-app my-store --init-git
 ```
@@ -76,8 +84,72 @@ npx create-mercato-app my-store --init-git
 - `--skip-agentic-setup` skips only the interactive agentic setup wizard
 - Imported ready apps are copied as raw source snapshots: the CLI does not rewrite dependency versions, package names, or application source files
 - Imported ready apps skip the interactive agentic setup wizard; if you want agentic tooling later, run `yarn mercato agentic:init` inside the generated app
+- `--agents` is only supported for bare scaffolds; use `yarn mercato agentic:init` after importing a ready app
 - Imported ready apps must not contain `.template` files; the scaffold fails closed if template files are found
 
+## Standalone AI Harness
+
+A bare scaffold can install a standalone-specific AI development harness for Claude Code, Codex, Cursor, or any selected subset. It combines a compact task router, module/task guides, local skills, an integrity-pinned subset of `open-mercato/skills`, exact installed-framework context, and a reproducible evaluation catalog.
+
+### Install or refresh skills
+
+Agentic setup attempts installation automatically. Re-run it after cloning, after an offline setup, or when selecting another tier:
+
+```bash
+yarn install-skills --list
+yarn install-skills
+yarn install-skills --with automation # opt in to loop/issue/release-maintenance workflows
+```
+
+The default is the 13 local core skills plus the 15-skill dependency-closed daily external tier. Advanced loop engines, issue authoring, and upgrade-note maintenance stay opt-in through `--with automation` (or `--all`). `.agents/skills/` is canonical; Claude Code receives compatibility links. The installer downloads the exact pinned `open-mercato/skills` archive, copies only individually hash-attested skill directories, and never executes archive or package-runner code. It activates the selected external set as one transaction: any failure restores the complete previous set before local installation continues. It preserves unknown user-owned skills and quarantines stale or modified installer-owned content.
+
+### Upgrade an existing generated harness
+
+After upgrading Open Mercato, refresh generated harness assets without overwriting local context:
+
+```bash
+yarn mercato agentic:init --update-harness
+```
+
+The ownership-aware update replaces unchanged generated files, recreates missing owned files, and refreshes the manifest atomically. Modified or unknown files remain in place; exact generated-path conflicts get an adjacent `.incoming` candidate. Managed paths are resolved below the canonical app root and a symlinked ancestor is rejected before publication. Use `--force` only when intentionally replacing known generated targets. External skill installation is a separate retryable phase, so offline installation does not roll back the harness update.
+
+### Resolve installed framework context
+
+Use the escape hatch when the routed guides do not contain an exact contract. It resolves the package versions selected by the app and their source/`AGENTS.md` chain without bulk-loading dependencies:
+
+```bash
+yarn framework:context --module customers --query makeCrudRoute
+yarn framework:context --package @open-mercato/ui --query CrudForm
+yarn framework:context --root
+```
+
+Bounded snapshots are written under ignored `.ai/framework-context/`; warnings make degraded dist/type-only context explicit.
+
+### Evaluate and maintain the harness
+
+Use deterministic checks during development:
+
+```bash
+yarn harness:validate --case OMH-009
+yarn harness:validate --family testing
+yarn harness:validate --all
+```
+
+`harness:validate --all` is the deterministic catalog gate, not the full release suite. Authenticated `--runner codex` / `--runner claude` live routing uses host filesystem containment on macOS (`sandbox-exec`) and Linux (Bubblewrap). The model gets no shell, process, environment, discovery, browser, or network tool: both CLIs receive only an evaluator-owned, `env -i` MCP server for exact-path reads and case-allowlisted writes. The selected app is intentionally readable through that narrow tool, so use a fresh or otherwise non-sensitive generated app. macOS `sandbox-exec` can enforce network-free lanes but cannot isolate loopback from the host; native macOS and Windows must use a contained Linux VM/container with Bubblewrap for the complete release gate.
+
+Run the full matrix once per Open Mercato release from a fresh scaffold:
+
+```bash
+yarn install-skills
+yarn harness:release --runner codex --prepare-targets /absolute/empty-release-targets --acknowledge-writes
+```
+
+The target directory must be absolute, new or empty, and outside the controller app. Select one blocking primary runner with `--runner codex` or `--runner claude`; it owns all 192 routing cases and every writable/review lane, with no per-case fallback. Optionally add the different authenticated runner through `--portability-runner` for the exact 45-case representative read-only lane. Omitting it is valid and recorded as not requested; once requested, its failures are blocking. Use a fresh, sanitized controller: automatic preparation fails before copying `.env`/`.env.*` local configuration (safe example/sample/template files remain allowed), credential files, or private-key files. The complete gate requires Linux with trusted system Bubblewrap (`bwrap`) and user namespaces because its Playwright API/browser lanes need a loopback namespace isolated from the host. Preflight rejects untrusted/no-op/pass-through executables and proves isolated loopback plus a capability-free payload before target preparation, provider invocation, or writes; native macOS and Windows therefore fail closed. The command also fails closed when a required runner, browser, or test runtime is unavailable. The 192-case catalog includes 92 framework-neutral business prompts and 45 writable implementation/regression cases (23.4%). The release command runs live routing, writable trusted oracles, per-target `generate`/`typecheck`/`lint`/`build`, any declared generated test, and isolated generated-code review for every writable result. Foundation and target validation—including `yarn build`—receive a minimal environment with network access denied, and persisted diagnostics redact sensitive environment values and URL userinfo. Test-authoring coverage executes a Jest unit test plus Linux/Bubblewrap loopback-only Playwright API and browser tests through fixed controller-owned commands against a read-only target; runtime reports must attest at least one passed test and zero skipped, todo, focused, flaky, or expected-failure tests. The suite then writes a schema-valid sanitized mode-`0600` report under `.ai/harness/results/` with the selected primary and optional portability runner policy.
+
+Use the bundled `om-evolve-harness` skill to add a real case: reproduce failure first, select one smallest knowledge owner, run any generated unit/integration tests plus target checks, require code review, and finish with the full release suite. Open Mercato framework maintainers use the monorepo-only `$om-refresh-standalone-harness --from <ref> --to <ref>` workflow for every release range and retain its sanitized maintenance report.
+
+For normal app changes, describe the business outcome directly or use the installed spec workflow for multi-phase work. Before handoff, run `yarn generate`, the smallest affected unit/integration tests, `yarn typecheck`, `yarn lint`, and `yarn build` as appropriate; applying migrations still requires explicit approval.
+
 ## Git And GitHub
 
 Interactive scaffolds ask whether to initialize a local Git repository after the app is created. Non-interactive scaffolds skip Git initialization unless `--init-git` is passed.

package/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/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/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/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/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/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/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/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.