ark-runtime-kernel 1.1.0 → 1.3.0

package/README.md

@@ -30,10 +30,19 @@ No code changes. No new runtime. Just a config and a CI line.
 
 ```bash
 npm install -D ark-runtime-kernel typescript
-npx ark-check --init          # infers layers from your existing folders → ark.config.json
+npx ark init                  # asks before generating config, agent gates, and CI templates
 npx ark-check                 # done: cross-layer imports now fail the check
 ```
 
+`ark init` detects your existing layer directories and suggests the missing ones from
+Ark's default 11-layer profile (with their conventional directories), so you see the
+full division before deciding what to adopt. On an empty project it generates the
+complete profile with every layer optional: the check passes immediately, and each
+layer starts being enforced as soon as its directory gains source files. Agents get
+the same guidance — the `ark://manifest` resource includes `suggestedLayers`, and the
+generated `AGENTS.md` carries the placement table, so an agent asked for a saga or a
+background job knows where it belongs before writing it.
+
 Adopting on a codebase that already has violations? Freeze them and ratchet down:
 
 ```bash
@@ -41,7 +50,9 @@ npx ark-check --update-baseline   # writes .ark-baseline.json — commit it
 npx ark-check --baseline          # only NEW violations fail from now on
 ```
 
-Then gate your agents (Claude Code shown; [Cursor / Codex / others](docs/ai-gates.md)):
+Then gate your agents (Claude Code shown; [Cursor / Codex / others](docs/ai-gates.md)). If you use
+Codex in an Ark project, register the MCP server early so `ark://manifest` is available during
+generation:
 
 ```json
 // .claude/settings.json
@@ -58,6 +69,52 @@ Then gate your agents (Claude Code shown; [Cursor / Codex / others](docs/ai-gate
 
 > The same `ark.config.json` powers every gate.
 
+Or generate the starter agent and CI gate files:
+
+```bash
+npx ark-check --install-agent-gates
+```
+
+This writes opt-in templates for MCP discovery, Claude/Cursor rules, Codex config notes,
+GitHub Actions, and agent instructions. Existing files are skipped unless you pass
+`--force`.
+
+The package `postinstall` only prints the next command; it never prompts or writes files
+during `npm install`. Use `npx ark init --yes` for non-interactive setup.
+
+### Updating Ark
+
+For projects that already use Ark:
+
+```bash
+npm install -D ark-runtime-kernel@latest
+npx ark-check --root . --config ark.config.json --strict-config
+npm run check:architecture
+```
+
+This updates the local `ark`, `ark-check`, and `ark-mcp` binaries used by npm scripts
+and CI. `npm run check:architecture` is the recommended alias, but it is optional:
+the direct `npx ark-check --root . --config ark.config.json --strict-config` command
+is the real check and works even if the alias has not been added yet.
+
+The lockfile controls the version CI gets, so commit the updated `package-lock.json`,
+`pnpm-lock.yaml`, or `yarn.lock`.
+
+Generated setup files are intentionally not rewritten during package updates:
+`AGENTS.md`, MCP config, Claude/Cursor settings, Codex notes, and GitHub Actions
+templates stay under your project's control. To add any new starter templates:
+
+```bash
+npx ark-check --install-agent-gates
+```
+
+Existing files are skipped. To regenerate them from the latest templates, review
+your local changes first, then run:
+
+```bash
+npx ark-check --install-agent-gates --force
+```
+
 ## Why Ark (and not just a linter)?
 
 If you only need import-boundary linting in CI, [dependency-cruiser](https://github.com/sverweij/dependency-cruiser), [eslint-plugin-boundaries](https://github.com/javierbrea/eslint-plugin-boundaries), and Nx module boundaries are solid tools. Ark's reason to exist is the **write-time, agent-native half** they don't cover:

package/bin/ark-check.mjs

@@ -21,7 +21,10 @@ function parseArgs(argv) {
     tsconfig: undefined,
     json: false,
     strictConfig: false,
+    requireGates: false,
     init: false,
+    installAgentGates: false,
+    tools: undefined,
     force: false,
     baseline: undefined,
     updateBaseline: false,
@@ -30,7 +33,23 @@ function parseArgs(argv) {
     const arg = argv[i];
     if (arg === '--json') args.json = true;
     else if (arg === '--strict-config') args.strictConfig = true;
+    else if (arg === '--require-gates') args.requireGates = true;
     else if (arg === '--init') args.init = true;
+    else if (arg === '--install-agent-gates') args.installAgentGates = true;
+    else if (arg === '--tools') {
+      // Consume the next arg only when it isn't another flag (same rule as --baseline),
+      // so `--tools --force` can't silently eat --force as a "tool name".
+      const next = argv[i + 1];
+      if (next !== undefined && !next.startsWith('-')) {
+        i += 1;
+        args.tools = next
+          .split(',')
+          .map((tool) => tool.trim().toLowerCase())
+          .filter(Boolean);
+      } else {
+        args.tools = []; // flag without a value — rejected in runInstallAgentGates
+      }
+    }
     else if (arg === '--force') args.force = true;
     else if (arg === '--baseline' || arg === '--update-baseline') {
       if (arg === '--update-baseline') args.updateBaseline = true;
@@ -50,8 +69,9 @@ function parseArgs(argv) {
 
 function usage() {
   return [
-    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--json] [--baseline [file]]',
+    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]]',
     '       ark-check --init [--force]',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex] [--force]',
     '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
     '       ark-check --print-config eleven-layer',
     '',
@@ -62,6 +82,10 @@ function usage() {
     '--init scans the project for the built-in layer directory conventions (src/domain,',
     'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
     'only the layers that actually exist, with the default rules filtered to those layers.',
+    'Undetected profile layers are printed as suggestions with their conventional',
+    'directories. When nothing is detected, the full 11-layer starter profile is written',
+    'instead (all layers optional, anchored at src/), so the strict check passes today and',
+    'each layer starts being enforced as soon as its directory gains source files.',
     '',
     'Resolves relative, tsconfig path-alias, and package imports via the TypeScript',
     'module resolver, then checks each resolved cross-layer import against the rules.',
@@ -80,8 +104,20 @@ function usage() {
     'Config warnings are advisory by default and are included in JSON output.',
     'Use --strict-config to make config warnings fail the check.',
     '',
+    '--require-gates fails the check when AGENTS.md, .mcp.json, or the generated CI',
+    'workflow is missing, so "installed but never configured" is a red CI. Combine it',
+    'with --strict-config to enforce gate presence and architecture in one run.',
+    '',
+    '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
+    'project, plus tool-specific templates. Pass --tools claude,cursor,codex to pick',
+    'which tool configs to write; otherwise they are auto-detected from .claude/, .cursor/,',
+    'and .codex/ (all are written when nothing is detected).',
+    '',
     'Generate a starter 11-layer config:',
     '  ark-check --print-config eleven-layer > ark.config.json',
+    '',
+    'Install agent + CI enforcement templates:',
+    '  ark-check --install-agent-gates',
   ].join('\n');
 }
 
@@ -89,6 +125,35 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, 'utf8'));
 }
 
+function readPackageJson(root) {
+  const file = path.join(root, 'package.json');
+  if (!fs.existsSync(file)) return null;
+  return readJson(file);
+}
+
+function hasCheckArchitectureScript(root) {
+  const pkg = readPackageJson(root);
+  return Boolean(pkg?.scripts?.['check:architecture']);
+}
+
+const REQUIRED_GATE_FILES = [
+  'AGENTS.md',
+  '.mcp.json',
+  '.github/workflows/ark-check.yml',
+];
+
+function missingGates(root) {
+  return REQUIRED_GATE_FILES.filter(
+    (relativePath) => !fs.existsSync(path.join(root, relativePath))
+  );
+}
+
+function checkArchitectureScriptSnippet() {
+  // npx resolves the installed package binary; `node bin/ark-check.mjs` only works
+  // inside Ark's own repo.
+  return '"check:architecture": "npx ark-check --root . --config ark.config.json --strict-config"';
+}
+
 function readConfig(root, configPath) {
   const fullPath = path.isAbsolute(configPath)
     ? configPath
@@ -170,39 +235,328 @@ function runInit(args) {
   }
 
   const { srcDir, config } = detectConfig(args.root);
-  if (config.layers.length === 0) {
-    console.error(
-      [
-        'No conventional layer directories found (looked for src/domain, src/application,',
-        'src/adapters/persistence, ...). Generate the full template instead and adapt the',
-        'patterns to your layout:',
-        '  ark-check --print-config eleven-layer > ark.config.json',
-      ].join('\n')
-    );
-    process.exitCode = 1;
-    return;
-  }
+  const greenfield = config.layers.length === 0;
+  // Greenfield: anchor the starter profile at src/ (the convention a fresh project will
+  // scaffold under) even when src/ doesn't exist yet — the layers are optional, so the
+  // check passes today and governance switches on the moment src/domain/ etc. appear.
+  const finalConfig = greenfield
+    ? createElevenLayerConfig({ rootDir: srcDir === '.' ? 'src' : srcDir })
+    : config;
 
-  fs.writeFileSync(configPath, `${JSON.stringify(config, null, 2)}\n`);
+  fs.writeFileSync(configPath, `${JSON.stringify(finalConfig, null, 2)}\n`);
 
   console.log(`Wrote ${configPath}`);
   console.log('');
-  console.log('Detected layers:');
-  for (const layer of config.layers) {
-    console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
-  }
-  const uncovered = uncoveredDirectories(args.root, srcDir, config.layers);
-  if (uncovered.length > 0) {
-    console.log('');
-    console.log(
-      `Not covered by any layer (add patterns for these or they stay ungoverned): ${uncovered.join(', ')}`
-    );
+  if (greenfield) {
+    console.log('No conventional layer directories found — generated the full 11-layer starter');
+    console.log('profile instead. Every layer is marked optional, so the strict check passes now');
+    console.log('and each layer starts being enforced as soon as its directory gains source files:');
+    for (const layer of finalConfig.layers) {
+      console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
+    }
+    // The starter profile only governs src/. Existing source elsewhere would make the
+    // gate silently green, so surface it instead of pretending the project is covered.
+    const outside = walk(args.root)
+      .map((file) => normalize(path.relative(args.root, file)))
+      .filter((rel) => !rel.startsWith('src/') && !rel.split('/').some((s) => s.startsWith('.')));
+    if (outside.length > 0) {
+      console.log('');
+      console.log(`WARNING: ${outside.length} source file(s) live outside src/ and are NOT governed`);
+      console.log(`by this config (e.g. ${outside.slice(0, 3).join(', ')}).`);
+      console.log('Move them under src/, or edit the "include" and layer patterns to match your layout.');
+    }
+  } else {
+    console.log('Detected layers:');
+    for (const layer of finalConfig.layers) {
+      console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
+    }
+    const detected = new Set(finalConfig.layers.map((layer) => layer.name));
+    const suggested = DEFAULT_INTENT_PREFIXES.filter((entry) => !detected.has(entry.layer));
+    if (suggested.length > 0) {
+      console.log('');
+      console.log('Suggested layers from the 11-layer profile (not detected — conventional');
+      console.log('directories shown; create one and re-run --init, or add the layer by hand):');
+      for (const entry of suggested) {
+        const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
+          .map((directory) => `${srcDir}/${directory}`)
+          .join(', ');
+        console.log(`  ${entry.layer}: ${dirs}`);
+      }
+    }
+    const uncovered = uncoveredDirectories(args.root, srcDir, finalConfig.layers);
+    if (uncovered.length > 0) {
+      console.log('');
+      console.log(
+        `Not covered by any layer (add patterns for these or they stay ungoverned): ${uncovered.join(', ')}`
+      );
+    }
   }
   console.log('');
   console.log('Next steps:');
   console.log('  1. CI gate:        npx ark-check --root . --config ark.config.json --strict-config');
   console.log('  2. AI write gate:  npx ark-mcp --root . --config ark.config.json');
   console.log('     (bind its validate_code tool to your agent\'s pre-write hook — see README)');
+  if (!hasCheckArchitectureScript(args.root)) {
+    console.log('  3. Add the npm alias if you want `npm run check:architecture`:');
+    console.log(`     ${checkArchitectureScriptSnippet()}`);
+  }
+}
+
+function ensureDirForFile(file) {
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+}
+
+function writeTemplate(root, relativePath, content, force) {
+  const fullPath = path.join(root, relativePath);
+  if (fs.existsSync(fullPath) && !force) {
+    return { relativePath, status: 'skipped' };
+  }
+  try {
+    ensureDirForFile(fullPath);
+    fs.writeFileSync(fullPath, content);
+    return { relativePath, status: 'written' };
+  } catch {
+    return { relativePath, status: 'failed' };
+  }
+}
+
+function packageManager(root) {
+  if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) {
+    return {
+      cache: 'pnpm',
+      setup: ['corepack enable'],
+      install: 'pnpm install --frozen-lockfile',
+      run: 'pnpm exec ark-check --root . --config ark.config.json --strict-config --require-gates',
+    };
+  }
+  if (fs.existsSync(path.join(root, 'yarn.lock'))) {
+    return {
+      cache: 'yarn',
+      setup: ['corepack enable'],
+      install: 'yarn install --frozen-lockfile',
+      run: 'yarn ark-check --root . --config ark.config.json --strict-config --require-gates',
+    };
+  }
+  return {
+    cache: 'npm',
+    setup: [],
+    install: fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install',
+    run: 'npx ark-check --root . --config ark.config.json --strict-config --require-gates',
+  };
+}
+
+const ARK_CHECK_COMMAND = 'npx ark-check --root . --config ark.config.json --strict-config';
+
+// Canonical agent contract. AGENTS.md and the Cursor rule both derive from this
+// single source so the steps can never drift out of sync between the two files.
+const AGENT_CONTRACT = {
+  manifestResource: 'ark://manifest',
+  steps: [
+    `Read the Ark contract from \`ark://manifest\` when the MCP server is available.`,
+    `Keep source files inside the layer boundaries declared in \`ark.config.json\`.`,
+    `Do not bypass Ark publishers, event contracts, or source metadata for runtime mutations.`,
+    `After edits, run \`${ARK_CHECK_COMMAND}\`.`,
+    `If Ark reports violations, fix the architecture instead of weakening the gate.`,
+  ],
+  // Cursor-only guidance: the write-time validate_code tool is available in
+  // Cursor's runtime but has no equivalent in a plain AGENTS.md read.
+  cursorValidateStep: `Validate the full post-edit file content with the \`validate_code\` tool before writing whenever your runtime supports it.`,
+};
+
+function layerPlacementTable() {
+  const rows = DEFAULT_INTENT_PREFIXES.map((entry) => {
+    const dirs = (DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [])
+      .map((directory) => `\`${directory}/\``)
+      .join(', ');
+    return `| ${entry.layer} | ${dirs} | ${entry.prefixes.map((p) => `\`${p}\``).join(', ')} |`;
+  }).join('\n');
+  return `| Layer | Conventional directories (under the source root) | Intent prefixes |
+|-------|---------------------------------------------------|-----------------|
+${rows}`;
+}
+
+function agentInstructions() {
+  const steps = AGENT_CONTRACT.steps.map((step, index) => `${index + 1}. ${step}`).join('\n');
+  return `# Ark Enforcement
+
+Before editing TypeScript or JavaScript source files:
+
+${steps}
+
+## Where new code belongs
+
+\`ark.config.json\` is authoritative for this project. When creating a NEW kind of code
+that no existing layer covers (a saga, a background job, a read model, ...), use the
+default 11-layer placement below and add the layer to \`ark.config.json\` — do not invent
+an ungoverned location:
+
+${layerPlacementTable()}
+
+The project is only considered Ark-enforced when the write gate, CI gate, and runtime path all pass.
+`;
+}
+
+function mcpJson() {
+  return `${JSON.stringify({
+    mcpServers: {
+      ark: {
+        type: 'stdio',
+        command: 'npx',
+        args: ['ark-mcp', '--root', '.', '--config', 'ark.config.json'],
+      },
+    },
+  }, null, 2)}\n`;
+}
+
+function codexTomlSnippet() {
+  return `[mcp_servers.ark]
+command = "npx"
+args = ["ark-mcp", "--root", ".", "--config", "ark.config.json"]
+`;
+}
+
+function cursorRule() {
+  return `---
+description: Ark architecture contract
+alwaysApply: true
+---
+
+Before writing or editing TypeScript or JavaScript source files, read the
+\`${AGENT_CONTRACT.manifestResource}\` resource from the \`ark\` MCP server when available.
+
+${AGENT_CONTRACT.cursorValidateStep} After edits, run:
+
+\`\`\`bash
+${ARK_CHECK_COMMAND}
+\`\`\`
+
+If Ark reports violations, fix the architecture instead of bypassing the gate.
+`;
+}
+
+function githubWorkflow(pm) {
+  const setupSteps = pm.setup.map((command) => `      - run: ${command}`).join('\n');
+  return `name: Ark architecture gate
+
+on:
+  pull_request:
+  push:
+    branches: [main, master]
+
+jobs:
+  ark-check:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: ${pm.cache}
+${setupSteps ? `${setupSteps}\n` : ''}      - run: ${pm.install}
+      - run: ${pm.run}
+`;
+}
+
+function claudeSettings() {
+  return `${JSON.stringify({
+    hooks: {
+      PreToolUse: [
+        {
+          matcher: 'Write|Edit|MultiEdit',
+          hooks: [
+            {
+              type: 'command',
+              command:
+                'npx ark-mcp --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json',
+            },
+          ],
+        },
+      ],
+    },
+  }, null, 2)}\n`;
+}
+
+function resolveTools(args) {
+  if (args.tools && args.tools.length > 0) {
+    return new Set(args.tools);
+  }
+  const root = args.root;
+  const detected = new Set();
+  if (fs.existsSync(path.join(root, '.claude'))) detected.add('claude');
+  if (fs.existsSync(path.join(root, '.cursor'))) detected.add('cursor');
+  if (fs.existsSync(path.join(root, '.codex'))) {
+    detected.add('codex');
+  }
+  // No signal at all: fall back to writing every tool's templates so a fresh
+  // project still gets a complete, reviewable starter set.
+  if (detected.size === 0) {
+    return new Set(['claude', 'cursor', 'codex']);
+  }
+  return detected;
+}
+
+const KNOWN_TOOLS = ['claude', 'cursor', 'codex'];
+
+function runInstallAgentGates(args) {
+  const root = args.root;
+  if (args.tools) {
+    const unknown = args.tools.filter((tool) => !KNOWN_TOOLS.includes(tool));
+    if (args.tools.length === 0 || unknown.length > 0) {
+      console.error(
+        `--tools expects a comma-separated subset of: ${KNOWN_TOOLS.join(', ')}` +
+          (unknown.length > 0 ? ` (unknown: ${unknown.join(', ')})` : '')
+      );
+      process.exitCode = 2;
+      return;
+    }
+  }
+  const pm = packageManager(root);
+  const hasCheckScript = hasCheckArchitectureScript(root);
+  const tools = resolveTools(args);
+  const templates = [
+    // Base gates: tool-agnostic contract + CI backstop, always written.
+    ['AGENTS.md', agentInstructions()],
+    ['.mcp.json', mcpJson()],
+    ['.github/workflows/ark-check.yml', githubWorkflow(pm)],
+  ];
+  if (tools.has('cursor')) {
+    templates.push(['.cursor/mcp.json', mcpJson()]);
+    templates.push(['.cursor/rules/ark.mdc', cursorRule()]);
+  }
+  if (tools.has('claude')) {
+    templates.push(['.claude/settings.json', claudeSettings()]);
+  }
+  if (tools.has('codex')) {
+    templates.push(['docs/ark-codex-config.toml', codexTomlSnippet()]);
+  }
+
+  const results = templates.map(([relativePath, content]) =>
+    writeTemplate(root, relativePath, content, args.force)
+  );
+
+  console.log('Ark agent gate templates:');
+  for (const result of results) {
+    const marker =
+      result.status === 'written' ? 'wrote' : result.status === 'failed' ? 'FAILED' : 'skipped';
+    console.log(`  ${marker.padEnd(7)} ${result.relativePath}`);
+  }
+  const failed = results.filter((result) => result.status === 'failed');
+  if (failed.length > 0) {
+    console.error(`\nFailed to write ${failed.length} template(s).`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log('');
+  console.log('Next steps:');
+  console.log('  1. Review the generated files and commit the ones that match your tools.');
+  console.log('  2. Run: npx ark-check --root . --config ark.config.json --strict-config');
+  if (!hasCheckScript) {
+    console.log('  3. Add the npm alias if you want `npm run check:architecture`:');
+    console.log(`     ${checkArchitectureScriptSnippet()}`);
+    console.log('  4. If you use Codex in this project, wire it now so `ark://manifest` is available from the first edit.');
+  } else {
+    console.log('  3. If you use Codex in this project, wire it now so `ark://manifest` is available from the first edit.');
+  }
 }
 
 function readManifest(root, manifestPath) {
@@ -670,6 +1024,10 @@ async function main() {
     runInit(args);
     return;
   }
+  if (args.installAgentGates) {
+    runInstallAgentGates(args);
+    return;
+  }
   if (args.printConfig) {
     if (args.printConfig !== 'eleven-layer') {
       console.error(`Unknown config profile: ${args.printConfig}`);
@@ -680,6 +1038,35 @@ async function main() {
     return;
   }
 
+  if (args.requireGates) {
+    const missing = missingGates(args.root);
+    if (missing.length > 0) {
+      const payload = {
+        ok: false,
+        error: 'missing-gates',
+        missing,
+      };
+      if (args.json) {
+        console.log(JSON.stringify(payload, null, 2));
+      } else {
+        console.error('Ark gates are not installed. Missing:');
+        for (const relativePath of missing) {
+          console.error(`  - ${relativePath}`);
+        }
+        console.error('\nRun `npx ark init` (or `ark-check --install-agent-gates`) to configure enforcement.');
+      }
+      process.exitCode = 1;
+      return;
+    }
+    // Gates present. This is a precondition, not a standalone report: stay quiet
+    // in --json mode so the architecture check below owns the single JSON output.
+    // When --require-gates is the only intent (no config/architecture run needed),
+    // callers still get a clear signal from the exit code and the human-mode line.
+    if (!args.json) {
+      console.log('Ark gates present: ' + REQUIRED_GATE_FILES.join(', '));
+    }
+  }
+
   let ts;
   try {
     ts = await import('typescript');

package/bin/ark-mcp.mjs

@@ -25,7 +25,12 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import readline from 'node:readline';
-import { DEFAULT_INTENT_PREFIXES, DEFAULT_RULES, layerForFile } from './ark-shared.mjs';
+import {
+  DEFAULT_INTENT_PREFIXES,
+  DEFAULT_LAYER_DIRECTORIES,
+  DEFAULT_RULES,
+  layerForFile,
+} from './ark-shared.mjs';
 
 function parseArgs(argv) {
   const args = {
@@ -297,6 +302,31 @@ async function main() {
     },
   ];
 
+  // Layers from the 11-layer profile that this project has NOT declared, with their
+  // conventional directories: tells the agent where a new kind of code (a saga, a job,
+  // a read model, ...) belongs BEFORE it improvises a location the gate can't govern.
+  // A default layer is dropped when the project already claims any of its intent
+  // prefixes under another name (e.g. a `core` layer owning `Domain.`) — suggesting
+  // DomainModel there would tell the agent to create a second layer for the same
+  // prefix, making longest-prefix resolution ambiguous.
+  function suggestedLayers() {
+    const activeNames = new Set(profile.layers.map((layer) => layer.name));
+    const claimedPrefixes = new Set(
+      profile.layers.flatMap((layer) =>
+        (layer.prefixes ?? []).map((p) => (p.endsWith('.') ? p : `${p}.`))
+      )
+    );
+    return DEFAULT_INTENT_PREFIXES.filter(
+      (entry) =>
+        !activeNames.has(entry.layer) &&
+        !entry.prefixes.some((p) => claimedPrefixes.has(p.endsWith('.') ? p : `${p}.`))
+    ).map((entry) => ({
+      layer: entry.layer,
+      intentPrefixes: entry.prefixes,
+      conventionalDirectories: DEFAULT_LAYER_DIRECTORIES[entry.layer] ?? [],
+    }));
+  }
+
   function manifestText() {
     if (projectManifest) {
       return JSON.stringify(
@@ -305,12 +335,23 @@ async function main() {
         2
       );
     }
+    const suggestions = suggestedLayers();
     return JSON.stringify(
       {
         source: profile === ark.elevenLayerProfile ? 'strictDefaultElevenLayerProfile' : 'project',
         name: profile.name,
         layers: profile.layers,
         rules: profile.rules,
+        ...(suggestions.length > 0
+          ? {
+              suggestedLayers: suggestions,
+              suggestedLayersNote:
+                'Layers from the default 11-layer profile this project has not declared. ' +
+                'When creating a NEW kind of code that fits one of these, place it in a ' +
+                'conventional directory and add the layer to ark.config.json instead of ' +
+                'inventing an ungoverned location.',
+            }
+          : {}),
       },
       null,
       2

package/bin/ark-postinstall.mjs

@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+
+if (process.env.ARK_POSTINSTALL_SILENT === '1') {
+  process.exit(0);
+}
+
+console.log(`Ark installed, but not enforced yet.
+Run: npx ark init
+
+For non-interactive setup:
+Run: npx ark init --yes
+`);