arkgate 2.5.0 → 2.6.1

package/bin/ark-check.mjs

@@ -25,11 +25,15 @@ import {
   writeAdoptionPlan,
   classifyRemediation,
   detectPackageManager,
+  detectWorkspaces,
+  detectTsPackageRoots,
+  resolveIncludeRoots,
   execCommandParts,
   execRunner,
   formatArchitectureRecommendationHuman,
   globToRegExp,
   installDevHint,
+  isScanExcludedRelative,
   presentLockfiles,
   layerForFile,
   looksLikeIntent,
@@ -41,6 +45,71 @@ import {
   typescriptUsabilityHint,
 } from './ark-shared.mjs';
 
+import {
+  runInstallAgentGates,
+  runMigrateCommands,
+  loadTypeScript,
+  collectAdoptionGaps,
+  detectSkillGaps,
+  detectCodexHomeGap,
+  missingGates,
+  staleRunnerGateFiles,
+  brokenMcpGateFiles,
+  readJson,
+  readPackageJson,
+  hasCheckArchitectureScript,
+  hasArkWorkflow,
+  checkArchitectureScriptSnippet,
+  arkCheckCommand,
+  arkPackageVersion,
+  agentInstructions,
+  packageManager,
+  REQUIRED_GATE_FILES,
+  codexPromptsDir,
+} from './lib/agent-gates.mjs';
+import {
+  detectEnforcement,
+  renderHtmlReport,
+  renderBeginnerHtmlReport,
+  archiveReportSnapshots,
+  buildReportSnapshot,
+  computeReportFitness,
+  reportsDir,
+  readJsonSafe,
+} from './lib/html-report.mjs';
+import {
+  computeCoverage,
+  runCoverage,
+  runPlan,
+  runDoctor,
+  buildRemediationPlan,
+} from './lib/doctor-plan.mjs';
+import {
+  baselineKey,
+  readBaseline,
+  summarizeViolations,
+  violationEdge,
+  writeBaseline,
+  printViolation,
+  printViolationBreakdown,
+  CONCENTRATION_MIN_VIOLATIONS,
+} from './lib/violations.mjs';
+import {
+  buildUnclassifiedSuggestions,
+  suggestLayerForDir,
+  suggestLayerForPath,
+  detectBestFitModel,
+  dirSegmentsFromGlob,
+} from './lib/suggestions.mjs';
+import {
+  ARCHITECTURE_PRESETS,
+  CANONICAL_LAYER_NAMES,
+  denyUpward,
+  presetWithOverlays,
+  FRAMEWORK_INTERNAL_EXCLUDE,
+} from './lib/presets.mjs';
+
+
 function parseArgs(argv) {
   const args = {
     root: process.cwd(),
@@ -69,6 +138,8 @@ function parseArgs(argv) {
     applyPolicyPack: undefined,
     watch: false,
     beginner: false,
+    version: false,
+    help: false,
   };
   for (let i = 2; i < argv.length; i += 1) {
     const arg = argv[i];
@@ -101,6 +172,9 @@ function parseArgs(argv) {
     else if (arg === '--write-plan') args.writePlan = true;
     else if (arg === '--list-policy-packs') args.listPolicyPacks = true;
     else if (arg === '--apply-policy-pack') args.applyPolicyPack = argv[++i];
+    else if (arg === '--suggest-include') args.suggestInclude = true;
+    else if (arg === '--adopt-contract') args.adoptContract = true;
+    else if (arg === '--write') args.write = true;
     else if (arg === '--watch') args.watch = true;
     else if (arg === '--beginner') args.beginner = true;
     else if (arg === '--codex-home') args.codexHome = true;
@@ -124,18 +198,32 @@ function parseArgs(argv) {
     else if (arg === '--print-config') args.printConfig = argv[++i];
     else if (arg === '--tsconfig') args.tsconfig = argv[++i];
     else if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--version' || arg === '-V') args.version = true;
   }
   return args;
 }
 
+/** Path shown to humans: project-relative when inside root, absolute otherwise (no `../../..`). */
+function displayPathFromRoot(root, absPath) {
+  const rel = path.relative(root, absPath);
+  if (!rel || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
+    return absPath;
+  }
+  return rel.split(path.sep).join('/');
+}
+
 function usage() {
   return [
-    'Usage: ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
+    '       ark-check --version',
+    '       ark-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-config] [--require-gates] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
     '       ark-check --coverage [--json]          per-layer file counts + full unclassified list (report only, exit 0)',
     '       ark-check --plan [--json]              classified remediation plan (mechanical-safe / judgment / deferred) + goal; report only',
     '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
-    '       ark-check --list-policy-packs            enthusiast preset configs (hexagonal, layered, feature-sliced, monorepo)',
+    '       ark-check --list-policy-packs            enthusiast preset configs (hexagonal, layered, feature-sliced, monorepo, ui-surface)',
     '       ark-check --apply-policy-pack <id> [--force]  write ark.config.json from templates/policy-packs/ (uses preset factory)',
+    '       ark-check --suggest-include [--json]   propose include roots (TS packages / workspaces)',
+    '       ark-check --adopt-contract [--write]   expand include + UI patterns from ungoverned dirs (contract adopt)',
     '       ark-check --watch                      re-run the check when governed files change (debounced)',
     '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive]',
     '           HTML report + snapshots under .ark/reports/ (origin once, latest each run, history JSON)',
@@ -170,6 +258,7 @@ function usage() {
     'Config shape:',
     '{',
     '  "include": ["src"],',
+    '  // optional: "exclude": ["**/vendor/**"], "excludeGenerated": false  (default skips *.gen.ts / *.generated.ts)',
     '  "layers": [',
     '    { "name": "DomainModel", "patterns": ["src/domain/**"], "intentPrefixes": ["Domain."],',
     '      "forbiddenGlobals": ["fetch", "process", "Date.now", "Math.random"] }',
@@ -210,57 +299,6 @@ function usage() {
   ].join('\n');
 }
 
-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',
-];
-const REQUIRED_GATE_WORKFLOW = '.github/workflows/*.yml running ark-check';
-
-function hasArkWorkflow(root) {
-  const workflowsDir = path.join(root, '.github', 'workflows');
-  if (!fs.existsSync(workflowsDir)) return false;
-  return fs
-    .readdirSync(workflowsDir)
-    .filter((file) => /\.ya?ml$/i.test(file))
-    .some((file) => {
-      try {
-        const content = fs.readFileSync(path.join(workflowsDir, file), 'utf8');
-        return /\bark-check\b/.test(content) || /\bcheck:architecture\b/.test(content);
-      } catch {
-        return false;
-      }
-    });
-}
-
-function missingGates(root) {
-  const missing = REQUIRED_GATE_FILES.filter(
-    (relativePath) => !fs.existsSync(path.join(root, relativePath))
-  );
-  if (!hasArkWorkflow(root)) missing.push(REQUIRED_GATE_WORKFLOW);
-  return missing;
-}
-
-function checkArchitectureScriptSnippet(root) {
-  // The package manager's runner resolves the installed binary; `node bin/ark-check.mjs`
-  // only works inside Ark's own repo. Package-manager aware so a pnpm/yarn repo isn't
-  // handed an `npx` alias that violates its "never npx" policy.
-  return `"check:architecture": "${arkCheckCommand(root)}"`;
-}
 
 function readConfig(root, configPath) {
   const fullPath = path.isAbsolute(configPath)
@@ -278,6 +316,9 @@ function readConfig(root, configPath) {
     include: raw.include ?? ['src'],
     layers: raw.layers ?? [],
     rules: raw.rules ?? DEFAULT_RULES,
+    ...(raw.exclude ? { exclude: raw.exclude } : {}),
+    ...(raw.excludeGenerated !== undefined ? { excludeGenerated: raw.excludeGenerated } : {}),
+    ...(raw.cyclePolicy ? { cyclePolicy: raw.cyclePolicy } : {}),
   };
 }
 
@@ -334,380 +375,13 @@ function uncoveredDirectories(root, srcDir, layers) {
     });
 }
 
-// Reads workspace globs from package.json (npm/yarn/bun `workspaces`, array or
-// `{ packages: [] }`) and pnpm-workspace.yaml, returning the distinct base directories
-// (the glob prefix before the first `*`), e.g. "packages/*" -> "packages". Empty when
-// the project declares no workspaces — the signal that says "this is a monorepo".
-function detectWorkspaces(root) {
-  const dirs = new Set();
-  const addGlob = (glob) => {
-    if (typeof glob !== 'string') return;
-    const beforeStar = glob.split('*')[0].replace(/\/+$/, '');
-    if (beforeStar && beforeStar !== '.') dirs.add(normalize(beforeStar));
-  };
-  const pkg = readPackageJson(root);
-  const ws = Array.isArray(pkg?.workspaces) ? pkg.workspaces : pkg?.workspaces?.packages;
-  if (Array.isArray(ws)) ws.forEach(addGlob);
-  const pnpmFile = path.join(root, 'pnpm-workspace.yaml');
-  if (fs.existsSync(pnpmFile)) {
-    // Minimal read (no YAML dep): collect list items under the top-level `packages:` key
-    // ONLY. pnpm files also carry other list-valued keys (onlyBuiltDependencies, catalog,
-    // …) whose items are NOT workspace globs — a key-agnostic scan would pull those in.
-    let inPackages = false;
-    for (const line of fs.readFileSync(pnpmFile, 'utf8').split('\n')) {
-      const keyMatch = line.match(/^([A-Za-z0-9_-]+):/); // top-level key (no indentation)
-      if (keyMatch) {
-        inPackages = keyMatch[1] === 'packages';
-        continue;
-      }
-      if (!inPackages) continue;
-      const item = line.match(/^\s+-\s*['"]?([^'"#]+?)['"]?\s*$/); // indented list item
-      if (item) addGlob(item[1].trim());
-    }
-  }
-  return [...dirs];
-}
+// detectWorkspaces: shared implementation in ark-shared.mjs (npm/pnpm/rush/lerna +
+// conventional multi-package roots).
 
 // Deny every "upward" edge for an ordered layer list (index 0 = outermost/top,
 // which may import everything below it). Inner/lower layers must not import outer
 // ones — the shared shape behind linear layered and feature-sliced layouts.
-function denyUpward(names) {
-  const rules = [];
-  for (let i = 0; i < names.length; i += 1) {
-    for (let j = i + 1; j < names.length; j += 1) {
-      rules.push({ from: names[j], to: names[i], allowed: false });
-    }
-  }
-  return rules;
-}
-
-// Named starter configs. Globs use `**` so they fit both flat (src/domain/**) and
-// modular (src/modules/x/domain/**) layouts. Every layer is optional, so the strict
-// check passes on a greenfield repo and each layer switches on as its dir gains files.
-//
-// Framework internals live under conventional names like `kernel/` and are NOT application
-// architecture — a broad `src/**/domain/**` would otherwise swallow `src/kernel/domain`
-// (DI/runtime wiring) and fire domain-purity rules on it, the false-positive class that
-// motivated `exclude`. Carve those out of every wildcard preset layer by default; a config
-// author who really does keep app code under kernel/ can drop the exclude.
-const FRAMEWORK_INTERNAL_EXCLUDE = ['**/kernel/**'];
-function presetWithOverlays(baseConfig, root) {
-  if (!root) return baseConfig;
-  return applyFrameworkLayoutOverlays(baseConfig, root);
-}
-
-const ARCHITECTURE_PRESETS = {
-  // Second arg `root` is optional — when provided (init/start on a real repo), framework
-  // filename conventions (Nest/Next/express) are overlaid so starters get real governed%.
-  hexagonal: (_workspaces, root) =>
-    presetWithOverlays(
-      {
-        include: ['src'],
-        layers: [
-          {
-            name: 'DomainModel',
-            description: 'Pure business rules and entities. No I/O, no framework, no ambient globals.',
-            patterns: ['src/**/domain/**'],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
-            optional: true,
-          },
-          {
-            name: 'ApplicationOrchestration',
-            description: 'Use cases that coordinate the domain through ports. No I/O of its own.',
-            patterns: ['src/**/application/**'],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            optional: true,
-          },
-          {
-            name: 'PresentationAdapters',
-            description: 'Entrypoints — HTTP routes, controllers, UI. Drives use cases.',
-            patterns: [
-              'src/**/presentation/**',
-              'src/**/controllers/**',
-              'src/**/interface-adapters/**',
-              'src/**/http/**',
-            ],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            optional: true,
-          },
-          {
-            name: 'PersistenceAdapters',
-            description: 'Implements ports with real infrastructure: DB, external APIs, filesystem.',
-            patterns: [
-              'src/**/infrastructure/**',
-              'src/**/adapters/**',
-              'src/**/persistence/**',
-              'src/**/repositories/**',
-            ],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            optional: true,
-          },
-        ],
-        rules: [
-          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'DomainModel', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'PersistenceAdapters', to: 'PresentationAdapters', allowed: false },
-        ],
-      },
-      root
-    ),
-  layered: (_workspaces, root) =>
-    presetWithOverlays(
-      {
-        include: ['src'],
-        layers: [
-          {
-            name: 'PresentationAdapters',
-            description: 'UI and API entrypoints.',
-            patterns: [
-              'src/**/presentation/**',
-              'src/**/controllers/**',
-              'src/**/ui/**',
-              'src/**/http/**',
-            ],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            optional: true,
-          },
-          {
-            name: 'ApplicationOrchestration',
-            description: 'Business services and use-case coordination.',
-            patterns: ['src/**/application/**', 'src/**/services/**'],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            optional: true,
-          },
-          {
-            name: 'DomainModel',
-            description: 'Pure business rules and entities. No I/O, no framework, no ambient globals.',
-            patterns: ['src/**/domain/**'],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
-            optional: true,
-          },
-          {
-            name: 'PersistenceAdapters',
-            description: 'Data access and infrastructure.',
-            patterns: [
-              'src/**/persistence/**',
-              'src/**/data/**',
-              'src/**/repositories/**',
-              'src/**/infrastructure/**',
-            ],
-            exclude: FRAMEWORK_INTERNAL_EXCLUDE,
-            optional: true,
-          },
-        ],
-        rules: denyUpward([
-          'PresentationAdapters',
-          'ApplicationOrchestration',
-          'DomainModel',
-          'PersistenceAdapters',
-        ]),
-      },
-      root
-    ),
-  'feature-sliced': (_workspaces, root) => {
-    const order = ['App', 'Pages', 'Widgets', 'Features', 'Entities', 'Shared'];
-    const purpose = {
-      App: 'App-wide setup, providers, and routing.',
-      Pages: 'Route-level compositions.',
-      Widgets: 'Self-contained UI blocks composed from features and entities.',
-      Features: 'User-facing feature units.',
-      Entities: 'Business entities with their UI and logic.',
-      Shared: 'Reusable primitives with no business knowledge.',
-    };
-    return presetWithOverlays(
-      {
-        include: ['src'],
-        layers: order.map((name) => ({
-          name,
-          description: purpose[name],
-          patterns: [`src/${name.toLowerCase()}/**`],
-          optional: true,
-        })),
-        rules: denyUpward(order),
-      },
-      root
-    );
-  },
-  // Cross-package profile for workspace monorepos. Patterns match by directory NAME
-  // anywhere in the tree (`**/domain/**` hits packages/x/domain AND apps/y/src/domain),
-  // so one profile governs every package. include defaults to the detected workspace
-  // roots (falls back to packages+apps). Naming varies by repo — adjust and re-check.
-  monorepo: (includeDirs, root) =>
-    presetWithOverlays(
-      {
-        include: includeDirs && includeDirs.length > 0 ? includeDirs : ['packages', 'apps'],
-        layers: [
-          {
-            name: 'DomainModel',
-            description:
-              'Pure business rules and entities, in any package. No I/O, no framework, no ambient globals.',
-            patterns: ['**/domain/**', '**/entities/**'],
-            forbiddenGlobals: DEFAULT_DOMAIN_FORBIDDEN_GLOBALS,
-            optional: true,
-          },
-          {
-            name: 'ApplicationOrchestration',
-            description: 'Use cases and services that coordinate the domain through ports.',
-            patterns: ['**/application/**', '**/use-cases/**', '**/services/**'],
-            optional: true,
-          },
-          {
-            name: 'PresentationAdapters',
-            description: 'Entrypoints — HTTP routes, controllers, UI, framework app/pages dirs.',
-            patterns: [
-              '**/app/**',
-              '**/pages/**',
-              '**/components/**',
-              '**/controllers/**',
-              '**/http/**',
-              '**/routes/**',
-            ],
-            optional: true,
-          },
-          {
-            name: 'PersistenceAdapters',
-            description: 'Implements ports with real infrastructure: DB, external APIs, filesystem.',
-            patterns: [
-              '**/infrastructure/**',
-              '**/adapters/**',
-              '**/persistence/**',
-              '**/repositories/**',
-            ],
-            optional: true,
-          },
-        ],
-        rules: [
-          { from: 'DomainModel', to: 'ApplicationOrchestration', allowed: false },
-          { from: 'DomainModel', to: 'PresentationAdapters', allowed: false },
-          { from: 'DomainModel', to: 'PersistenceAdapters', allowed: false },
-          { from: 'ApplicationOrchestration', to: 'PresentationAdapters', allowed: false },
-          { from: 'PresentationAdapters', to: 'PersistenceAdapters', allowed: false },
-          { from: 'PersistenceAdapters', to: 'ApplicationOrchestration', allowed: false },
-        ],
-      },
-      root
-    ),
-};
-
-// ── Layer suggestion engine ──────────────────────────────────────────────────
-// Everything here is HARVESTED from Ark's own canonical sources — the 11-layer defaults
-// (DEFAULT_LAYER_DIRECTORIES) and the named presets — so a suggestion can never drift from
-// what the gate actually enforces. No ad-hoc directory heuristics: a directory Ark doesn't
-// already know about is reported as "unrecognized — you classify", never guessed. This is
-// what lets `init`/`--coverage` PROPOSE where ungoverned code belongs instead of silently
-// leaving the majority of a repo ungoverned behind a false-green check.
-const CANONICAL_LAYER_NAMES = new Set(DEFAULT_INTENT_PREFIXES.map((entry) => entry.layer));
-
-function dirSegmentsFromGlob(pattern) {
-  return String(pattern)
-    .split('/')
-    .filter((segment) => segment && !segment.includes('*'));
-}
-
-let _layerByDir;
-// Map<dirBasename, string[] layers>. A basename mapping to >1 layer (e.g. `app` — Application
-// orchestration in the 11-layer defaults, but Presentation in the monorepo/Next preset) is
-// genuinely ambiguous; every candidate is surfaced rather than silently picked.
-function layerByDir() {
-  if (_layerByDir) return _layerByDir;
-  const map = new Map();
-  const add = (segment, layer) => {
-    if (!segment) return;
-    const existing = map.get(segment) ?? [];
-    if (!existing.includes(layer)) existing.push(layer);
-    map.set(segment, existing);
-  };
-  for (const [layer, dirs] of Object.entries(DEFAULT_LAYER_DIRECTORIES)) {
-    for (const dir of dirs) add(dirSegmentsFromGlob(dir).pop(), layer);
-  }
-  // The canonical-named presets reuse the 11 layer names, so their directory synonyms
-  // (services→Application, components/pages→Presentation, data/infrastructure→Persistence…)
-  // map cleanly onto the same taxonomy. feature-sliced uses a different vocabulary
-  // (Widgets/Entities/…) that doesn't reduce to the 11, so it's covered by model-fit, not here.
-  for (const preset of ['hexagonal', 'layered', 'monorepo']) {
-    for (const layer of ARCHITECTURE_PRESETS[preset]([]).layers) {
-      if (!CANONICAL_LAYER_NAMES.has(layer.name)) continue;
-      for (const pattern of layer.patterns ?? []) {
-        add(dirSegmentsFromGlob(pattern).pop(), layer.name);
-      }
-    }
-  }
-  _layerByDir = map;
-  return map;
-}
-
-// Suggest a canonical layer for a directory by its basename. null when Ark doesn't recognize
-// it (the honest "you classify this" case), else { layer, alternatives }.
-function suggestLayerForDir(name) {
-  const layers = layerByDir().get(name);
-  if (!layers || layers.length === 0) return null;
-  return { layer: layers[0], alternatives: layers.slice(1) };
-}
-
-// Suggest a layer for a directory PATH by finding the deepest segment Ark recognizes, so
-// `src/lib/repositories` proposes PersistenceAdapters even though `lib` itself is unknown.
-function suggestLayerForPath(relDir) {
-  const segments = relDir.split('/').filter(Boolean);
-  for (let i = segments.length - 1; i >= 0; i -= 1) {
-    const hit = suggestLayerForDir(segments[i]);
-    if (hit) return { ...hit, matchedDir: segments[i] };
-  }
-  return null;
-}
-
-// Which starter model does this set of directory basenames most resemble? Scored purely by
-// how many of the repo's directories each preset's patterns recognize — a hint toward
-// `ark init --preset <name>`. null when nothing lines up.
-function detectBestFitModel(dirBasenames) {
-  const present = new Set(dirBasenames);
-  const scored = ['hexagonal', 'layered', 'feature-sliced', 'monorepo'].map((name) => {
-    const segments = new Set();
-    for (const layer of ARCHITECTURE_PRESETS[name]([]).layers) {
-      for (const pattern of layer.patterns ?? []) {
-        const seg = dirSegmentsFromGlob(pattern).pop();
-        if (seg) segments.add(seg);
-      }
-    }
-    let hits = 0;
-    for (const dir of present) if (segments.has(dir)) hits += 1;
-    return { name, hits };
-  });
-  scored.sort((a, b) => b.hits - a.hits);
-  return scored[0].hits > 0 ? scored[0] : null;
-}
-
-// Group ungoverned files by their parent directory and attach a proposed layer (or the
-// honest "unrecognized"). The single source the coverage report and init both format.
-function buildUnclassifiedSuggestions(unclassifiedRelFiles) {
-  const byDir = new Map();
-  for (const rel of unclassifiedRelFiles) {
-    const dir = rel.split('/').slice(0, -1).join('/') || '.';
-    byDir.set(dir, (byDir.get(dir) ?? 0) + 1);
-  }
-  return [...byDir.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([dir, files]) => {
-    const hit = suggestLayerForPath(dir);
-    return hit
-      ? {
-          dir,
-          files,
-          layer: hit.layer,
-          ...(hit.alternatives.length > 0 ? { alternatives: hit.alternatives } : {}),
-        }
-      : { dir, files, unrecognized: true };
-  });
-}
 
-// For `init`: propose a layer for every ungoverned top-level directory, descending one level
-// into unrecognized ones so `lib/repositories`, `lib/db` etc. still get a concrete proposal
-// instead of a blanket "lib is ungoverned".
 function proposeForUncovered(root, srcDir, layers) {
   const proposals = [];
   for (const top of uncoveredDirectories(root, srcDir, layers)) {
@@ -763,7 +437,10 @@ function buildConfigFromPolicyPack(packId, root) {
       `Policy pack "${packId}" references unknown preset "${pack.preset}".`
     );
   }
-  const workspaces = pack.preset === 'monorepo' ? detectWorkspaces(root) : [];
+  const workspaces =
+    pack.preset === 'monorepo' || pack.preset === 'ui-surface'
+      ? resolveIncludeRoots(root)
+      : [];
   const config = factory(workspaces, root);
   if (pack.layerDescriptions) {
     for (const layer of config.layers) {
@@ -861,7 +538,7 @@ const THIN_COVERAGE_PERCENT = 50;
 function maybeWarnBrownfield(root, config) {
   let files;
   try {
-    files = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+    files = collectGovernedFiles(root, config);
   } catch {
     return false;
   }
@@ -885,6 +562,144 @@ function maybeWarnBrownfield(root, config) {
   return true;
 }
 
+/** Propose include roots (workspaces + nested TS packages) — contract-adopt primitive. */
+function runSuggestInclude(args) {
+  const root = args.root;
+  const workspaces = detectWorkspaces(root);
+  const tsPackages = detectTsPackageRoots(root);
+  const include = resolveIncludeRoots(root);
+  const payload = {
+    ok: true,
+    workspaces,
+    tsPackages,
+    suggestedInclude: include.length > 0 ? include : tsPackages.length > 0 ? tsPackages : ['src'],
+    note:
+      include.length === 0 && tsPackages.length === 0
+        ? 'No TS packages or workspaces found — default suggestion is src/ (create it or pass include by hand).'
+        : 'Use these paths as ark.config.json "include". Prefer --adopt-contract --write to expand patterns too.',
+  };
+  if (args.json) {
+    console.log(JSON.stringify(payload, null, 2));
+    return;
+  }
+  console.log(color.bold('Suggested include roots'));
+  console.log(`  workspaces: ${workspaces.join(', ') || '(none)'}`);
+  console.log(`  tsPackages: ${tsPackages.join(', ') || '(none)'}`);
+  console.log(`  suggestedInclude: ${payload.suggestedInclude.join(', ')}`);
+  console.log(color.dim(payload.note));
+}
+
+/**
+ * Contract-adopt: expand include + presentation patterns from ungoverned proposals.
+ * Read-only unless --write. Does not weaken rules or baseline violations.
+ */
+function runAdoptContract(args) {
+  const root = args.root;
+  const configPath = path.isAbsolute(args.config)
+    ? args.config
+    : path.join(root, args.config);
+  let config;
+  try {
+    config = fs.existsSync(configPath)
+      ? readConfig(root, args.config)
+      : {
+          include: ['src'],
+          layers: ARCHITECTURE_PRESETS['ui-surface']([], root).layers,
+          rules: ARCHITECTURE_PRESETS['ui-surface']([], root).rules,
+        };
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 2;
+    return;
+  }
+  const suggestedInclude = resolveIncludeRoots(root);
+  const tsPackages = detectTsPackageRoots(root);
+  const nextInclude = [
+    ...new Set([
+      ...(config.include || []),
+      ...(suggestedInclude.length > 0 ? suggestedInclude : tsPackages),
+    ]),
+  ].filter(Boolean);
+  const files = collectGovernedFiles(root, { ...config, include: nextInclude.length ? nextInclude : config.include });
+  const cov = computeCoverage(root, { ...config, include: nextInclude.length ? nextInclude : config.include }, files, config.rules || []);
+  const uiPatterns = [
+    '**/components/**',
+    '**/hooks/**',
+    '**/lib/**',
+    '**/routes/**',
+    '**/app/**',
+    '**/pages/**',
+  ];
+  const layers = (config.layers || []).map((layer) => {
+    if (layer.name !== 'PresentationAdapters') return layer;
+    const patterns = [...new Set([...(layer.patterns || []), ...uiPatterns])];
+    return { ...layer, patterns };
+  });
+  // If no PresentationAdapters layer, leave layers as-is (don't invent full profile).
+  const proposal = {
+    ok: true,
+    before: {
+      include: config.include || [],
+      governedPercent: null,
+      totalFiles: null,
+    },
+    after: {
+      include: nextInclude.length > 0 ? nextInclude : config.include,
+      presentationPatterns: uiPatterns,
+      totalFiles: cov.totalFiles,
+      governedPercent: cov.governed.percent,
+      unclassified: cov.unclassified.count,
+    },
+    wrote: false,
+  };
+  // Compute before coverage for honesty.
+  try {
+    const beforeFiles = collectGovernedFiles(root, config);
+    const beforeCov = computeCoverage(root, config, beforeFiles, config.rules || []);
+    proposal.before.totalFiles = beforeCov.totalFiles;
+    proposal.before.governedPercent = beforeCov.governed.percent;
+  } catch {
+    /* ignore */
+  }
+
+  if (args.write) {
+    const next = {
+      ...config,
+      include: proposal.after.include,
+      layers,
+    };
+    fs.writeFileSync(configPath, `${JSON.stringify(next, null, 2)}\n`);
+    proposal.wrote = true;
+  }
+
+  if (args.json) {
+    console.log(JSON.stringify(proposal, null, 2));
+    return;
+  }
+  console.log(color.bold('Contract adopt (coverage first)'));
+  console.log(
+    `  before: include=[${(proposal.before.include || []).join(', ')}] governed=${proposal.before.governedPercent ?? '?'}% files=${proposal.before.totalFiles ?? '?'}`
+  );
+  console.log(
+    `  after:  include=[${(proposal.after.include || []).join(', ')}] governed=${proposal.after.governedPercent}% files=${proposal.after.totalFiles} unclassified=${proposal.after.unclassified}`
+  );
+  console.log(`  presentation patterns += ${uiPatterns.join(', ')}`);
+  if (proposal.wrote) {
+    console.log(color.green(`  wrote ${path.relative(root, configPath) || args.config}`));
+    console.log(color.dim(`  Next: ${arkCommand(root, 'ark-check', '--coverage')} then --plan`));
+  } else {
+    console.log(color.dim('  Dry-run only. Re-run with --write to apply (does not weaken rules).'));
+  }
+  if ((proposal.after.totalFiles ?? 0) === 0) {
+    console.log(
+      color.yellow(
+        '  Empty scope remains — no TS packages found. Point include at your package roots manually.'
+      )
+    );
+    process.exitCode = 1;
+  }
+}
+
 function runInit(args) {
   const configPath = path.isAbsolute(args.config)
     ? args.config
@@ -905,7 +720,12 @@ function runInit(args) {
       process.exitCode = 2;
       return;
     }
-    const finalConfig = factory(detectWorkspaces(args.root), args.root);
+    const finalConfig = factory(
+      args.preset === 'monorepo' || args.preset === 'ui-surface'
+        ? resolveIncludeRoots(args.root)
+        : detectWorkspaces(args.root),
+      args.root
+    );
     fs.writeFileSync(configPath, `${JSON.stringify(finalConfig, null, 2)}\n`);
     console.log(`Wrote ${configPath} (${args.preset} preset)`);
     if (finalConfig.frameworkOverlay) {
@@ -933,8 +753,14 @@ function runInit(args) {
   // When no conventional src/ layout is found, a `workspaces` declaration means this is a
   // monorepo — the src/** 11-layer starter would match nothing there, so use the
   // cross-package monorepo profile anchored at the real workspace roots instead.
-  const workspaces = greenfield ? detectWorkspaces(args.root) : [];
-  const mode = !greenfield ? 'detected' : workspaces.length > 0 ? 'monorepo' : 'greenfield';
+  const includeRoots = greenfield ? resolveIncludeRoots(args.root) : [];
+  const tsPackages = greenfield ? detectTsPackageRoots(args.root) : [];
+  // Prefer monorepo/ui when nested TS packages exist without a conventional src layout.
+  const mode = !greenfield
+    ? 'detected'
+    : includeRoots.length > 0 || tsPackages.length > 0
+      ? 'monorepo'
+      : 'greenfield';
   // 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.
@@ -943,7 +769,10 @@ function runInit(args) {
     mode === 'detected'
       ? applyFrameworkLayoutOverlays(config, args.root)
       : mode === 'monorepo'
-        ? ARCHITECTURE_PRESETS.monorepo(workspaces, args.root)
+        ? ARCHITECTURE_PRESETS.monorepo(
+            includeRoots.length > 0 ? includeRoots : tsPackages,
+            args.root
+          )
         : createElevenLayerConfig({
             rootDir: srcDir === '.' ? 'src' : srcDir,
             root: args.root,
@@ -954,10 +783,11 @@ function runInit(args) {
   console.log(`Wrote ${configPath}`);
   console.log('');
   if (mode === 'monorepo') {
-    console.log(`Monorepo detected (workspaces: ${workspaces.join(', ')}). Generated a cross-package`);
-    console.log('profile matching domain/application/presentation/persistence directories in any');
-    console.log('package. Every layer is optional, so the strict check passes now and each switches');
-    console.log('on as matching directories gain files. Adjust patterns to your naming if they differ:');
+    const roots = finalConfig.include?.join(', ') || '(none)';
+    console.log(`Multi-package / TS package surface detected (include: ${roots}). Generated a`);
+    console.log('cross-package profile matching domain/application/presentation/persistence dirs');
+    console.log('in any package. Every layer is optional, so the strict check passes now and each');
+    console.log('switches on as matching directories gain files. Adjust patterns to your naming:');
     for (const layer of finalConfig.layers) {
       console.log(`  ${layer.name}: ${layer.patterns.join(', ')}`);
     }
@@ -986,1521 +816,55 @@ function runInit(args) {
     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 proposals = proposeForUncovered(args.root, srcDir, finalConfig.layers);
-    if (proposals.length > 0) {
-      const recognized = proposals.filter((p) => !p.unrecognized);
-      const unrecognized = proposals.filter((p) => p.unrecognized);
-      console.log('');
-      console.log('Ungoverned directories — Ark enforces NOTHING here until they are classified.');
-      console.log('A green check ignores this code; it is not "clean", it is unchecked.');
-      if (recognized.length > 0) {
-        console.log('');
-        console.log('Proposed layer for each (from the 11-layer profile + presets — apply via /ark-contract):');
-        for (const p of recognized) {
-          const alt = p.alternatives?.length ? ` (or ${p.alternatives.join(' / ')} — confirm)` : '';
-          console.log(`  ${p.dir}/ → ${p.layer}${alt}`);
-        }
-      }
-      if (unrecognized.length > 0) {
-        console.log('');
-        console.log(`Not recognized — you decide the layer: ${unrecognized.map((p) => p.dir).join(', ')}`);
-      }
-      const fit = detectBestFitModel(
-        [
-          ...finalConfig.layers.flatMap((l) => (l.patterns ?? []).map((p) => dirSegmentsFromGlob(p).pop())),
-          ...proposals.map((p) => p.dir.split('/').pop()),
-        ].filter(Boolean)
-      );
-      if (fit) {
-        console.log('');
-        console.log(`Closest starter model: ${fit.name} — \`ark init --preset ${fit.name} --force\` to start from its rule set.`);
-      }
-    }
-  }
-  maybeWarnBrownfield(args.root, finalConfig);
-  printInitNextSteps(args.root);
-}
-
-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' };
-  }
-}
-
-/**
- * Load a TypeScript module with a working JS API host (`sys` + AST + resolve).
- * Prefer the project's install when API-compatible (TS 5/6 + any TS 7 that still
- * exposes the classic JS host). TypeScript 7.0.x main entry is version-only
- * (`{ version, versionMajorMinor }`); programmatic APIs live under
- * `typescript/unstable/*` and are not yet the gate's host — we fall through to
- * ArkGate's own `typescript` dependency (JS-API 5.x) or a bare import.
- * Returns `{ ts, source, version, fallbackReason? }` or null.
- */
-async function loadTypeScript(root) {
-  const { createRequire } = await import('node:module');
-  const loaders = [];
-  try {
-    const req = createRequire(path.join(root, 'package.json'));
-    loaders.push({
-      label: 'project',
-      load: () => req('typescript'),
-      resolvePath: () => {
-        try {
-          return req.resolve('typescript');
-        } catch {
-          return null;
-        }
-      },
-    });
-  } catch {
-    /* project has no package.json resolvable tree */
-  }
-  // Nested under arkgate (production dependency) — must work when project has only TS7.
-  try {
-    const req = createRequire(__arkCheckCli);
-    loaders.push({
-      label: 'arkgate',
-      load: () => req('typescript'),
-      resolvePath: () => {
-        try {
-          return req.resolve('typescript');
-        } catch {
-          return null;
-        }
-      },
-    });
-  } catch {
-    /* ark install tree unavailable */
-  }
-  loaders.push({
-    label: 'import',
-    load: async () => {
-      const m = await import('typescript');
-      return m;
-    },
-    resolvePath: () => null,
-  });
-
-  let projectRejected = null;
-  const triedPaths = new Set();
-  for (const { label, load, resolvePath } of loaders) {
-    try {
-      const resolved = typeof resolvePath === 'function' ? resolvePath() : null;
-      if (resolved && triedPaths.has(resolved)) {
-        // Same physical package already rejected (e.g. project === hoisted arkgate path).
-        continue;
-      }
-      if (resolved) triedPaths.add(resolved);
-
-      const mod = await load();
-      const ts = usableTypescript(mod);
-      if (ts) {
-        const version =
-          typeof ts.version === 'string'
-            ? ts.version
-            : typeof mod?.version === 'string'
-              ? mod.version
-              : undefined;
-        return {
-          ts,
-          source: label,
-          version,
-          ...(projectRejected ? { fallbackReason: projectRejected } : {}),
-        };
-      }
-      if (label === 'project' && mod) {
-        projectRejected = `project typescript is not API-compatible (${typescriptUsabilityHint(mod)}); using ArkGate's JS-API TypeScript fallback (TypeScript 7.0 main export is version-only). See docs/typescript-support.md.`;
-      }
-    } catch {
-      /* try next loader */
-    }
-  }
-  return null;
-}
-
-function packageManager(root) {
-  // If the project already froze violations in a baseline, the generated CI must
-  // keep the ratchet — otherwise regenerating the workflow (especially with
-  // --force) silently drops --baseline and CI starts failing on frozen violations.
-  const baselineFlag = fs.existsSync(path.join(root, '.ark-baseline.json'))
-    ? ' --baseline .ark-baseline.json'
-    : '';
-  const checkArgs = `--root . --config ark.config.json --strict-config${baselineFlag} --require-gates`;
-  // Same detection as every emitted command (execRunner): honors the packageManager field and
-  // won't let a stray pnpm-lock.yaml hijack an npm project (package-lock.json wins the tie).
-  const pm = detectPackageManager(root);
-  if (pm === 'pnpm') {
-    return {
-      cache: 'pnpm',
-      setup: ['corepack enable'],
-      install: 'pnpm install --frozen-lockfile',
-      // Same runner as execRunner(): skip pnpm's verify-deps gate (ERR_PNPM_IGNORED_BUILDS).
-      run: `pnpm --config.verify-deps-before-run=false exec ark-check ${checkArgs}`,
-    };
-  }
-  if (pm === 'yarn') {
-    return {
-      cache: 'yarn',
-      setup: ['corepack enable'],
-      install: 'yarn install --frozen-lockfile',
-      run: `yarn ark-check ${checkArgs}`,
-    };
-  }
-  return {
-    cache: 'npm',
-    setup: [],
-    install: fs.existsSync(path.join(root, 'package-lock.json')) ? 'npm ci' : 'npm install',
-    run: `npx ark-check ${checkArgs}`,
-  };
-}
-
-// The args every emitted `ark-check` command carries. The runner prefix (npx / pnpm exec /
-// yarn) is added per project by arkCheckCommand so a pnpm-only repo never gets an `npx`
-// instruction — see execRunner() in ark-shared.mjs.
-const CHECK_ARGS = '--root . --config ark.config.json --strict-config';
-function arkCheckCommand(root) {
-  return arkCommand(root, 'ark-check', CHECK_ARGS);
-}
-
-// 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. `steps(checkCommand)`
-// is a builder because the check command's runner prefix varies with the package manager.
-const AGENT_CONTRACT = {
-  manifestResource: 'ark://manifest',
-  steps: (checkCommand) => [
-    `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 \`${checkCommand}\`.`,
-    `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(root) {
-  const steps = AGENT_CONTRACT.steps(arkCheckCommand(root))
-    .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(root) {
-  return `${JSON.stringify({
-    mcpServers: {
-      ark: {
-        type: 'stdio',
-        // Prefer arkgate-mcp; ark-mcp alias still works for one major.
-        ...execCommandParts(root, PREFERRED_MCP_BIN, ['--root', '.', '--config', 'ark.config.json']),
-      },
-    },
-  }, null, 2)}\n`;
-}
-
-// Sample for docs/ — `ark-check --install-agent-gates --tools codex` auto-merges the real
-// block (with absolute paths) into ~/.codex/config.toml. This copy is a reference only, so
-// it flags the two gotchas of hand-editing the global config: absolute paths (config.toml is
-// loaded without the project as cwd) and the required restart.
-function codexTomlSnippet(root) {
-  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
-    '--root',
-    '/absolute/path/to/project',
-    '--config',
-    '/absolute/path/to/project/ark.config.json',
-  ]);
-  const argsToml = args.map((value) => `"${value}"`).join(', ');
-  return `# Add to ~/.codex/config.toml (or $CODEX_HOME/config.toml), then RESTART Codex —
-# it does not hot-load MCP servers. Use ABSOLUTE paths: config.toml is global, so
-# "." would resolve against Codex's launch dir, not this project. Prefer:
-#   ark-check --install-agent-gates --tools codex   (auto-merges the absolute paths)
-[mcp_servers.ark]
-command = "${command}"
-args = [${argsToml}]
-`;
-}
-
-/**
- * Compact always-on rule for instruction-tier hosts (Windsurf, Cline, GitHub Copilot,
- * Kiro, ...): agents that read a project rule file but have no MCP tools or hooks.
- * Derived from the same AGENT_CONTRACT as AGENTS.md and the Cursor rule so the steps
- * can never drift; points at AGENTS.md for the full placement table.
- */
-function instructionRule(root) {
-  const steps = AGENT_CONTRACT.steps(arkCheckCommand(root))
-    .map((step, index) => `${index + 1}. ${step}`)
-    .join('\n');
-  return `# Ark architecture contract
-
-This project's architecture is governed by Ark (\`ark.config.json\` is authoritative).
-Before writing or editing TypeScript or JavaScript source files:
-
-${steps}
-
-See \`AGENTS.md\` for the full contract and the layer placement table.
-`;
-}
-
-function cursorRule(root) {
-  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
-${arkCheckCommand(root)}
-\`\`\`
-
-If Ark reports violations, fix the architecture instead of bypassing the gate.
-`;
-}
-
-// Default CI Node when the project declares nothing. A current LTS, NOT the
-// oldest supported: the npm-ci-lockfile-mismatch failure only happens when CI's
-// npm is OLDER than the npm that wrote the lockfile, so defaulting high is safer.
-const DEFAULT_CI_NODE_VERSION = '22';
-
-// Decide the Node the generated CI should use, preferring the project's own
-// declaration so CI's npm matches the dev's (a mismatch makes `npm ci` fail with
-// "missing from lock file" — a red gate unrelated to architecture). In order:
-//   1. .nvmrc / .node-version → setup-node's node-version-file (exact, best)
-//   2. package.json engines.node → its concrete major
-//   3. a current-LTS default
-function detectCiNode(root) {
-  for (const file of ['.nvmrc', '.node-version']) {
-    if (fs.existsSync(path.join(root, file))) return { kind: 'file', value: file };
-  }
-  const enginesNode = readPackageJson(root)?.engines?.node;
-  if (typeof enginesNode === 'string') {
-    const major = enginesNode.match(/\d+/)?.[0];
-    if (major) return { kind: 'version', value: major };
-  }
-  return { kind: 'default', value: DEFAULT_CI_NODE_VERSION };
-}
-
-function githubWorkflow(pm, ciNode) {
-  // pnpm/yarn setup (corepack enable) MUST run before actions/setup-node so the package
-  // manager is on PATH when setup-node's `cache: pnpm|yarn` tries to resolve the store —
-  // otherwise the cache step fails on a fresh runner ("Unable to locate executable file: pnpm").
-  const setupSteps = pm.setup.map((command) => `      - run: ${command}`).join('\n');
-  // node-version-file keeps CI locked to the dev's exact toolchain; an explicit
-  // version comes from engines.node; the default carries a hint for the mismatch
-  // symptom since we can't know which npm wrote the lockfile.
-  const nodeSetup =
-    ciNode.kind === 'file'
-      ? `          node-version-file: ${ciNode.value}`
-      : ciNode.kind === 'version'
-        ? `          node-version: '${ciNode.value}'`
-        : `          # If the install step fails with "missing from lock file" / lockfile out
-          # of sync, your local package manager is newer than this Node's — add a
-          # .nvmrc with your Node version so CI matches the dev environment.
-          node-version: '${ciNode.value}'`;
-  return `name: Ark architecture gate
-
-on:
-  pull_request:
-  push:
-    branches: [main, master]
-
-jobs:
-  ark-check:
-    runs-on: ubuntu-latest
-    steps:
-      - name: Checkout
-        uses: actions/checkout@v4
-${setupSteps ? `${setupSteps}\n` : ''}      - name: Setup Node
-        uses: actions/setup-node@v4
-        with:
-${nodeSetup}
-          cache: ${pm.cache}
-      - name: Install dependencies
-        run: ${pm.install}
-      - name: Ark architecture check
-        run: ${pm.run}
-`;
-}
-
-function claudeSettings(root) {
-  const runner = execRunner(root);
-  return `${JSON.stringify({
-    hooks: {
-      // Inject the contract at session start so the agent knows the architecture from
-      // the first token. Project-scoped by design; --session-context is also a silent
-      // no-op when no ark.config.json exists, so it can never leak into other projects.
-      SessionStart: [
-        {
-          hooks: [
-            {
-              type: 'command',
-              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-      PreToolUse: [
-        {
-          matcher: 'Write|Edit|MultiEdit',
-          hooks: [
-            {
-              type: 'command',
-              command: `${runner} ${PREFERRED_MCP_BIN} --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-    },
-  }, null, 2)}\n`;
-}
-
-// Grok Build project config: MCP registration (commit-friendly relative paths — unlike
-// Codex's global config.toml, Grok loads .grok/config.toml from the project).
-function grokProjectConfig(root) {
-  const { command, args } = execCommandParts(root, PREFERRED_MCP_BIN, [
-    '--root',
-    '.',
-    '--config',
-    'ark.config.json',
-  ]);
-  const argsToml = args.map((value) => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`).join(', ');
-  return `# Generated by ark-check --install-agent-gates (Grok Build project scope).
-# Restart Grok (or /mcps → refresh) after changes. Also loads repo-root .mcp.json.
-[mcp_servers.ark]
-command = "${command.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"
-args = [${argsToml}]
-`;
-}
-
-// Grok Build hooks: same arkgate-mcp contracts as Claude. Grok sets CLAUDE_PROJECT_DIR as
-// an alias for GROK_WORKSPACE_ROOT. Matcher keeps Claude names (Write|Edit|MultiEdit)
-// and Grok natives (write|search_replace) — Grok aliases both directions.
-function grokHooks(root) {
-  const runner = execRunner(root);
-  return `${JSON.stringify({
-    hooks: {
-      SessionStart: [
-        {
-          hooks: [
-            {
-              type: 'command',
-              timeout: 30,
-              command: `${runner} ${PREFERRED_MCP_BIN} --session-context --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-      PreToolUse: [
-        {
-          matcher: 'Write|Edit|MultiEdit|write|search_replace',
-          hooks: [
-            {
-              type: 'command',
-              timeout: 30,
-              command: `${runner} ${PREFERRED_MCP_BIN} --hook --root "$CLAUDE_PROJECT_DIR" --config ark.config.json`,
-            },
-          ],
-        },
-      ],
-    },
-  }, null, 2)}\n`;
-}
-
-function resolveTools(args) {
-  if (args.tools && args.tools.length > 0) {
-    return { tools: new Set(args.tools), source: 'explicit' };
-  }
-  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');
-  if (fs.existsSync(path.join(root, '.grok'))) detected.add('grok');
-  if (fs.existsSync(path.join(root, '.windsurf'))) detected.add('windsurf');
-  // .clinerules can also be a single FILE (older Cline convention); only a directory
-  // can receive .clinerules/ark.md, so a file must not trigger detection.
-  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
-    detected.add('cline');
-  }
-  if (fs.existsSync(path.join(root, '.kiro'))) detected.add('kiro');
-  if (fs.existsSync(path.join(root, '.roo'))) detected.add('roo');
-  if (fs.existsSync(path.join(root, '.continue'))) detected.add('continue');
-  if (fs.existsSync(path.join(root, '.gemini'))) detected.add('gemini');
-  // copilot has no reliable directory signal (.github exists in most repos),
-  // so it is explicit-only via --tools.
-  // No signal at all: fall back to writing the primary tools' templates so a fresh
-  // project still gets a complete, reviewable starter set.
-  if (detected.size === 0) {
-    return { tools: new Set(['claude', 'cursor', 'codex']), source: 'default' };
-  }
-  return { tools: detected, source: 'detected' };
-}
-
-const KNOWN_TOOLS = [
-  'claude',
-  'cursor',
-  'codex',
-  'grok',
-  'windsurf',
-  'cline',
-  'copilot',
-  'kiro',
-  'roo',
-  'continue',
-  'gemini',
-];
-
-// One canonical markdown per skill (templates/skills/*.md, shipped in the npm
-// package); installed into each tool's slash-command location. The YAML
-// frontmatter (name/description) is understood or harmlessly ignored by every
-// host. Kiro has no command mechanism — its steering rule file is the only gate.
-const SKILL_TOOL_TARGETS = {
-  claude: (name) => `.claude/skills/${name}/SKILL.md`,
-  cursor: (name) => `.cursor/commands/${name}.md`,
-  codex: (name) => `.codex/prompts/${name}.md`,
-  // Grok Build: project skills at .grok/skills/<name>/SKILL.md (slash-invocable).
-  grok: (name) => `.grok/skills/${name}/SKILL.md`,
-  windsurf: (name) => `.windsurf/workflows/${name}.md`,
-  cline: (name) => `.clinerules/workflows/${name}.md`,
-  copilot: (name) => `.github/prompts/${name}.prompt.md`,
-};
-
-// The version of the arkgate package these bins ship with. Used to
-// stamp installed skills so a normal ark-check can tell "outdated skill from an
-// older Ark" apart from "user-customized skill" — the stamp moves with the
-// package, editing the body doesn't.
-function arkPackageVersion() {
-  try {
-    const pkg = readJson(
-      path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json')
-    );
-    return typeof pkg.version === 'string' ? pkg.version : null;
-  } catch {
-    return null;
-  }
-}
-
-// Insert `arkVersion: <v>` into a skill's YAML frontmatter (before its closing
-// `---`). No frontmatter → returned unchanged. Idempotent for a given version.
-function stampSkill(content, version) {
-  if (!version) return content;
-  const lines = content.split('\n');
-  if (lines[0] !== '---') return content;
-  const closeIdx = lines.indexOf('---', 1);
-  if (closeIdx === -1) return content;
-  const existing = lines.findIndex(
-    (line, i) => i > 0 && i < closeIdx && /^arkVersion:/.test(line)
-  );
-  if (existing !== -1) {
-    lines[existing] = `arkVersion: ${version}`;
-  } else {
-    lines.splice(closeIdx, 0, `arkVersion: ${version}`);
-  }
-  return lines.join('\n');
-}
-
-// Read the `arkVersion:` stamp from an installed skill file. Returns null when
-// the file is absent or has no stamp (installed by a pre-stamp Ark, or hand-authored).
-function installedSkillVersion(filePath) {
-  let content;
-  try {
-    content = fs.readFileSync(filePath, 'utf8');
-  } catch {
-    return null;
-  }
-  const match = content.match(/^arkVersion:\s*(.+)$/m);
-  return match ? match[1].trim() : null;
-}
-
-// Numeric-tuple compare of dotted versions; true when `a` is strictly older than
-// `b`. Non-numeric/absent segments compare as 0, so "1.7" < "1.7.5".
-function isVersionOlder(a, b) {
-  const parse = (v) => String(v).split('.').map((n) => Number.parseInt(n, 10) || 0);
-  const av = parse(a);
-  const bv = parse(b);
-  const len = Math.max(av.length, bv.length);
-  for (let i = 0; i < len; i += 1) {
-    const x = av[i] ?? 0;
-    const y = bv[i] ?? 0;
-    if (x !== y) return x < y;
-  }
-  return false;
-}
-
-function skillTemplates() {
-  const dir = path.join(
-    path.dirname(fileURLToPath(import.meta.url)),
-    '..',
-    'templates',
-    'skills'
-  );
-  // A missing/mispackaged templates dir would otherwise install zero skills with
-  // exit 0 — warn so a packaging regression (e.g. "templates" dropped from the
-  // package.json files array) is visible instead of a silent no-op.
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    console.error(
-      `Warning: skill templates directory not found (${dir}); no /ark-* skills installed.`
-    );
-    return [];
-  }
-  return entries
-    .filter((entry) => entry.isFile() && /^[a-z0-9-]+\.md$/.test(entry.name))
-    .map((entry) => entry.name)
-    .sort()
-    .map((name) => [path.basename(name, '.md'), fs.readFileSync(path.join(dir, name), 'utf8')]);
-}
-
-// Skill names only, silent on a missing templates dir — for the freshness
-// advisory below, which must not print packaging warnings on every check run.
-function skillTemplateNames() {
-  const dir = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'templates', 'skills');
-  let entries;
-  try {
-    entries = fs.readdirSync(dir, { withFileTypes: true });
-  } catch {
-    return [];
-  }
-  return entries
-    .filter((entry) => entry.isFile() && /^[a-z0-9-]+\.md$/.test(entry.name))
-    .map((entry) => path.basename(entry.name, '.md'));
-}
-
-// A normal ark-check run is the reliable discovery point for new /ark-* skills.
-// Ark ships no install lifecycle script (a postinstall banner would be blocked by
-// modern package managers' script-approval policy anyway, so careful users never
-// saw it — and it broke hardened installs). When a project has adopted Ark agent
-// gates (AGENTS.md present) but a detected tool is missing
-// skills this version ships, surface it here so agents and CI actually notice.
-// Advisory only — never affects the exit code. Copilot has no reliable directory
-// signal, so it is not auto-detected (explicit --tools only), matching resolveTools.
-// Where Codex loads slash-command prompts from. Codex reads $CODEX_HOME/prompts
-// (defaulting to ~/.codex/prompts), NOT the repo — so home copies of the /ark-*
-// skills drift out of date when a repo refresh only touches in-repo tool dirs.
-function codexPromptsDir() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'prompts');
-}
-
-// Where Codex reads its MCP server registrations. Unlike Claude (.claude/settings.json)
-// and Cursor (.cursor/mcp.json), Codex loads MCP servers only from $CODEX_HOME/config.toml
-// (~/.codex/config.toml) — never from .mcp.json — so wiring Codex means editing the user's
-// home config, not a repo file.
-function codexConfigPath() {
-  const base = process.env.CODEX_HOME || path.join(os.homedir(), '.codex');
-  return path.join(base, 'config.toml');
-}
-
-// Merge the [mcp_servers.ark] table into Codex's config.toml so `ark://manifest` and the
-// AI write gate are live from the first edit — the piece that was previously only shipped as
-// a copy-me sample in docs/ark-codex-config.toml. Idempotent: an existing ark table is left
-// untouched unless `force` replaces it; other content in the file is preserved. Returns a
-// status for the install summary. The table match runs from the [mcp_servers.ark] header to
-// the line before the next top-level table header (a line starting with `[`) or EOF.
-//
-// Unlike .mcp.json / .cursor/mcp.json (loaded relative to the project), config.toml is a
-// GLOBAL file — Codex launches it without the project as cwd — so `--root .` would resolve
-// against the wrong directory. The paths must be absolute, and TOML string values need the
-// backslashes/quotes escaped (matters on Windows and for repo paths containing quotes).
-function wireCodexMcp(root, force) {
-  const file = codexConfigPath();
-  const esc = (s) => s.replace(/\\/g, '\\\\').replace(/"/g, '\\"');
-  const absRoot = path.resolve(root);
-  const absConfig = path.join(absRoot, 'ark.config.json');
-  // Preferred product bin; absolute --root so Codex (cwd ≠ project) resolves correctly.
-  const preferredBin = 'arkgate-mcp';
-  const { command, args } = execCommandParts(root, preferredBin, [
-    '--root',
-    esc(absRoot),
-    '--config',
-    esc(absConfig),
-  ]);
-  const argsToml = args.map((value) => `"${value}"`).join(', ');
-  const block = `[mcp_servers.ark]
-command = "${command}"
-args = [${argsToml}]`;
-  let existing = '';
-  try {
-    if (fs.existsSync(file)) existing = fs.readFileSync(file, 'utf8');
-  } catch (error) {
-    return { status: 'failed', file, message: error.message };
-  }
-  const tableRe = /(^|\n)\[mcp_servers\.ark\][^\n]*\n(?:(?!\[)[^\n]*\n?)*/;
-  const hasTable = tableRe.test(existing);
-  // Fail-closed: rewrite temp/upgrade roots and dual/wrong bins even without --force.
-  const mustRewrite = hasTable && codexArkBlockNeedsRewrite(existing, absRoot);
-  if (hasTable && !force && !mustRewrite) {
-    return { status: 'skipped', file };
-  }
-  let next;
-  if (hasTable) {
-    next = existing.replace(tableRe, (match) => `${match.startsWith('\n') ? '\n' : ''}${block}\n`);
-  } else {
-    const sep = existing.length === 0 ? '' : existing.endsWith('\n\n') ? '' : existing.endsWith('\n') ? '\n' : '\n\n';
-    next = `${existing}${sep}${block}\n`;
-  }
-  try {
-    fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, next);
-  } catch (error) {
-    return { status: 'failed', file, message: error.message };
-  }
-  return {
-    status: hasTable ? 'updated' : 'written',
-    file,
-    ...(mustRewrite && !force ? { reason: 'temp-or-stale-root' } : {}),
-  };
-}
-
-// Detects stale/missing /ark-* skills in the Codex home prompts dir. Only nags
-// when at least one ark-* prompt already lives there (evidence Codex was set up
-// for this user) — never introduces Codex to someone who doesn't use it. Same
-// guards as detectSkillGaps (adopted repo, not the Ark source tree).
-function detectCodexHomeGap(root) {
-  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return null;
-  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return null;
-  const skillNames = skillTemplateNames();
-  if (skillNames.length === 0) return null;
-  const dir = codexPromptsDir();
-  if (!fs.existsSync(dir)) return null;
-  const present = skillNames.filter((name) => fs.existsSync(path.join(dir, `${name}.md`)));
-  if (present.length === 0) return null; // Codex home never set up for Ark — don't nag.
-  const version = arkPackageVersion();
-  const missing = skillNames.length - present.length;
-  let stale = 0;
-  if (version) {
-    for (const name of present) {
-      const installed = installedSkillVersion(path.join(dir, `${name}.md`));
-      if (installed === null || isVersionOlder(installed, version)) stale += 1;
-    }
-  }
-  return missing > 0 || stale > 0 ? { missing, stale } : null;
-}
-
-function detectSkillGaps(root) {
-  if (!fs.existsSync(path.join(root, 'AGENTS.md'))) return [];
-  // The Ark source tree keeps the skill templates at templates/skills/ — it's the
-  // producer, not a consumer, so it must not nag itself to "install" its own skills.
-  if (fs.existsSync(path.join(root, 'templates', 'skills'))) return [];
-  const skillNames = skillTemplateNames();
-  if (skillNames.length === 0) return [];
-  const detected = [];
-  if (fs.existsSync(path.join(root, '.claude'))) detected.push('claude');
-  if (fs.existsSync(path.join(root, '.cursor'))) detected.push('cursor');
-  if (fs.existsSync(path.join(root, '.codex'))) detected.push('codex');
-  if (fs.existsSync(path.join(root, '.grok'))) detected.push('grok');
-  if (fs.existsSync(path.join(root, '.windsurf'))) detected.push('windsurf');
-  if (fs.statSync(path.join(root, '.clinerules'), { throwIfNoEntry: false })?.isDirectory()) {
-    detected.push('cline');
-  }
-  const version = arkPackageVersion();
-  const gaps = [];
-  for (const tool of detected) {
-    const target = SKILL_TOOL_TARGETS[tool];
-    if (!target) continue;
-    let missing = 0;
-    let stale = 0;
-    for (const name of skillNames) {
-      const file = path.join(root, target(name));
-      if (!fs.existsSync(file)) {
-        missing += 1;
-      } else if (version) {
-        // An installed skill with no stamp predates stamping (older Ark), or one
-        // stamped behind the current version is left over from an older install.
-        // Either way the shipped skill has moved on — offer a --force refresh.
-        const installed = installedSkillVersion(file);
-        if (installed === null || isVersionOlder(installed, version)) stale += 1;
-      }
-    }
-    if (missing > 0 || stale > 0) gaps.push({ tool, missing, stale });
-  }
-  return gaps;
-}
-
-// Files carrying an emitted Ark command whose runner (npx / pnpm exec / yarn) should match
-// the project's package manager. .mcp.json / .cursor/mcp.json hold it structurally
-// (command/args); the rest hold it as text ("npx ark-check …", incl. .claude/settings.json
-// hook strings and the package.json check:architecture script).
-const COMMAND_GATE_TEXT_FILES = [
-  '.claude/settings.json', 'AGENTS.md', '.cursor/rules/ark.mdc', '.windsurf/rules/ark.md',
-  '.clinerules/ark.md', '.github/copilot-instructions.md', '.kiro/steering/ark.md',
-  '.roo/rules/ark.md', '.continue/rules/ark.md', 'GEMINI.md', 'package.json',
-  '.grok/hooks/ark-write-gate.json', '.grok/config.toml',
-];
-const COMMAND_GATE_JSON_FILES = ['.mcp.json', '.cursor/mcp.json'];
-// Primary CLI names (product) + one-major aliases. migrate-commands must strip ALL of these
-// before re-emitting a single preferred bin — otherwise a partial rename leaves
-// args: ["ark-mcp", "arkgate-mcp", ...] which breaks stdio MCP hosts.
-const ARK_MCP_BINS = new Set(['arkgate-mcp', 'ark-mcp']);
-const ARK_CHECK_BINS = new Set(['arkgate-check', 'ark-check']);
-const ARK_CLI_BINS = new Set(['arkgate', 'ark']);
-const PREFERRED_MCP_BIN = 'arkgate-mcp';
-const PREFERRED_CHECK_BIN = 'arkgate-check';
-const PREFERRED_CLI_BIN = 'arkgate';
-// Runner argv noise that is not a bin argument (pnpm exec form).
-const MCP_RUNNER_ARGV = new Set(['exec', '--config.verify-deps-before-run=false']);
-// The runner token immediately before an ark command in a text command string.
-// Matches npm/yarn runners and both pnpm forms (legacy `pnpm exec` + verify-deps-safe form).
-// Longer bin names first so `arkgate-check` is not partially matched as `ark`.
-const RUNNER_BEFORE_ARK =
-  /\b(?:npx|pnpm --config\.verify-deps-before-run=false exec|pnpm exec|yarn)(?= (?:arkgate-check|arkgate-mcp|arkgate|ark-check|ark-mcp|ark)\b)/g;
-
-/** Keep only MCP server flags from existing args (drop runner tokens + any ark* bin names). */
-function stripMcpServerArgs(args) {
-  if (!Array.isArray(args) || args.length === 0) {
-    return ['--root', '.', '--config', 'ark.config.json'];
-  }
-  const kept = args.filter(
-    (entry) =>
-      typeof entry === 'string' &&
-      !MCP_RUNNER_ARGV.has(entry) &&
-      !ARK_MCP_BINS.has(entry) &&
-      !ARK_CHECK_BINS.has(entry) &&
-      !ARK_CLI_BINS.has(entry)
-  );
-  return kept.length > 0 ? kept : ['--root', '.', '--config', 'ark.config.json'];
-}
-
-/** True when mcpServers.ark.args list more than one Ark MCP bin (broken dual rename). */
-function mcpArgsHaveDuplicateBins(args) {
-  if (!Array.isArray(args)) return false;
-  const hits = args.filter((entry) => ARK_MCP_BINS.has(entry));
-  return hits.length > 1 || (hits.length === 1 && args.indexOf(hits[0]) !== args.lastIndexOf(hits[0]));
-}
-
-function brokenMcpGateFiles(root) {
-  const bad = [];
-  for (const rel of COMMAND_GATE_JSON_FILES) {
-    let json;
-    try {
-      json = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
-    } catch {
-      continue;
-    }
-    const ark = json?.mcpServers?.ark;
-    if (ark && mcpArgsHaveDuplicateBins(ark.args)) bad.push(rel);
-  }
-  return bad;
-}
-
-/** Core layers whose optionality matters once they match files (presets share these names). */
-const CORE_LAYER_NAMES = new Set([
-  'DomainModel',
-  'ApplicationOrchestration',
-  'PresentationAdapters',
-  'PersistenceAdapters',
-]);
-
-/** Temp / upgrade sandbox roots must never remain as Codex MCP --root. */
-function isTempOrUpgradeRoot(p) {
-  if (!p || typeof p !== 'string') return false;
-  const n = p.replace(/\\/g, '/');
-  return (
-    /\/var\/folders\//i.test(n) ||
-    /\/tmp\//i.test(n) ||
-    /\/Temp\//i.test(n) ||
-    /ark-upgrade/i.test(n) ||
-    /\/T\/(?:ark-|grok-)/i.test(n) ||
-    /[\\/]AppData[\\/]Local[\\/]Temp[\\/]/i.test(n)
-  );
-}
-
-/** Extract --root value from Codex [mcp_servers.ark] args array text. */
-function extractCodexArkRootFromToml(tomlText) {
-  if (!tomlText || typeof tomlText !== 'string') return null;
-  const start = tomlText.search(/(^|\n)\[mcp_servers\.ark\]/);
-  if (start < 0) return null;
-  const rest = tomlText.slice(start);
-  const endMatch = rest.slice(1).search(/\n\[/);
-  const block = endMatch >= 0 ? rest.slice(0, endMatch + 1) : rest;
-  // args = ["arkgate-mcp", "--root", "/abs/path", ...]
-  const rootIdx = block.search(/"--root"\s*,\s*"/);
-  if (rootIdx < 0) {
-    // alternate: --root as adjacent string after any bin
-    const m = block.match(/"--root"\s*,\s*"([^"]+)"/);
-    return m ? m[1] : null;
-  }
-  const m = block.slice(rootIdx).match(/"--root"\s*,\s*"([^"]+)"/);
-  return m ? m[1] : null;
-}
-
-function codexArkBlockHasPreferredBin(tomlText) {
-  if (!tomlText) return false;
-  const start = tomlText.search(/(^|\n)\[mcp_servers\.ark\]/);
-  if (start < 0) return false;
-  const rest = tomlText.slice(start);
-  const endMatch = rest.slice(1).search(/\n\[/);
-  const block = endMatch >= 0 ? rest.slice(0, endMatch + 1) : rest;
-  const bins = [...block.matchAll(/"(arkgate-mcp|ark-mcp)"/g)].map((m) => m[1]);
-  if (bins.length > 1) return false;
-  return bins.length === 1 && bins[0] === PREFERRED_MCP_BIN;
-}
-
-function codexArkBlockNeedsRewrite(tomlText, absRoot) {
-  if (!tomlText || !tomlText.includes('[mcp_servers.ark]')) return true;
-  const rootArg = extractCodexArkRootFromToml(tomlText);
-  if (!rootArg || isTempOrUpgradeRoot(rootArg)) return true;
-  try {
-    if (path.resolve(rootArg) !== path.resolve(absRoot)) return true;
-  } catch {
-    return true;
-  }
-  if (!codexArkBlockHasPreferredBin(tomlText)) return true;
-  return false;
-}
-
-/**
- * Adoption completeness (separate from 0–100 fitness). Pure-ish: filesystem + config.
- * @returns {{ gaps: object[], hosts: object[], mcp: object, codexHome: object|null, coreOptional: object[], originReport: object, baseline: object, layerBalance: object|null }}
- */
-function collectAdoptionGaps(root, config, coverage) {
-  const gaps = [];
-  const adopted = fs.existsSync(path.join(root, 'AGENTS.md'));
-  const isProducer = fs.existsSync(path.join(root, 'templates', 'skills'));
-
-  // --- Repo MCP dual-bin ---
-  const dualMcp = brokenMcpGateFiles(root);
-  const mcp = {
-    dualBinFiles: dualMcp,
-    ok: dualMcp.length === 0,
-  };
-  if (dualMcp.length > 0) {
-    gaps.push({
-      id: 'mcp-dual-bin',
-      severity: 'warn',
-      message: `Broken MCP argv in ${dualMcp.join(', ')}: more than one of ark-mcp/arkgate-mcp`,
-      fix: arkCommand(root, 'ark-check', '--install-agent-gates --migrate-commands'),
-    });
-  }
-
-  // --- Host completeness (only when project already adopted gates) ---
-  const hosts = [];
-  if (adopted && !isProducer) {
-    const skillNames = skillTemplateNames();
-    const hostChecks = [
-      {
-        host: 'grok',
-        dir: '.grok',
-        skill: (n) => path.join(root, '.grok', 'skills', n, 'SKILL.md'),
-        extras: [
-          ['.grok/hooks/ark-write-gate.json', 'write-gate hook'],
-          ['.grok/config.toml', 'project MCP config'],
-        ],
-        toolsFlag: 'grok',
-      },
-      {
-        host: 'claude',
-        dir: '.claude',
-        skill: (n) => path.join(root, '.claude', 'skills', n, 'SKILL.md'),
-        extras: [['.claude/settings.json', 'settings/hooks']],
-        toolsFlag: 'claude',
-      },
-      {
-        host: 'cursor',
-        dir: '.cursor',
-        skill: (n) => path.join(root, '.cursor', 'commands', `${n}.md`),
-        extras: [['.cursor/mcp.json', 'MCP config']],
-        toolsFlag: 'cursor',
-      },
-    ];
-    for (const h of hostChecks) {
-      if (!fs.existsSync(path.join(root, h.dir))) continue;
-      const missingSkills = skillNames.filter((n) => !fs.existsSync(h.skill(n)));
-      const missingExtras = h.extras.filter(([rel]) => !fs.existsSync(path.join(root, rel)));
-      const complete = missingSkills.length === 0 && missingExtras.length === 0;
-      hosts.push({
-        host: h.host,
-        present: true,
-        complete,
-        missingSkills: missingSkills.length,
-        missingExtras: missingExtras.map(([, label]) => label),
-      });
-      if (!complete) {
-        gaps.push({
-          id: `host-${h.host}-incomplete`,
-          severity: 'warn',
-          message: `${h.host} dir present but incomplete (${missingSkills.length} skill(s) missing${
-            missingExtras.length ? `; missing ${missingExtras.map(([, l]) => l).join(', ')}` : ''
-          })`,
-          fix: arkCommand(
-            root,
-            'ark-check',
-            `--install-agent-gates --tools ${h.toolsFlag} --force`
-          ),
-        });
-      }
-    }
-  }
-
-  // --- Codex home MCP (temp path / wrong root / dual bin) ---
-  let codexHome = null;
-  if (adopted && !isProducer) {
-    const codexFile = codexConfigPath();
-    let toml = '';
-    try {
-      if (fs.existsSync(codexFile)) toml = fs.readFileSync(codexFile, 'utf8');
-    } catch {
-      toml = '';
-    }
-    if (toml.includes('[mcp_servers.ark]')) {
-      const rootArg = extractCodexArkRootFromToml(toml);
-      const absRoot = path.resolve(root);
-      const temp = isTempOrUpgradeRoot(rootArg);
-      let wrongRoot = false;
-      try {
-        wrongRoot = rootArg ? path.resolve(rootArg) !== absRoot : true;
-      } catch {
-        wrongRoot = true;
-      }
-      const preferredBin = codexArkBlockHasPreferredBin(toml);
-      const needsRewrite = codexArkBlockNeedsRewrite(toml, absRoot);
-      codexHome = {
-        file: codexFile,
-        root: rootArg,
-        tempPath: temp,
-        wrongRoot,
-        preferredBin,
-        needsRewrite,
-      };
-      if (needsRewrite) {
-        gaps.push({
-          id: 'codex-home-mcp',
-          severity: temp || wrongRoot ? 'warn' : 'info',
-          message: temp
-            ? `Codex home MCP --root points at a temp/upgrade path (${rootArg})`
-            : wrongRoot
-              ? `Codex home MCP --root is not this project (${rootArg || 'missing'} ≠ ${absRoot})`
-              : `Codex home MCP should use a single ${PREFERRED_MCP_BIN} bin with absolute project paths`,
-          fix: arkCommand(
-            root,
-            'ark-check',
-            '--install-agent-gates --codex-home --force'
-          ),
-        });
-      }
-    }
-  }
-
-  // --- Core layers optional but populated ---
-  const coreOptional = [];
-  const layerRows = coverage?.layers ?? [];
-  const countByName = new Map(layerRows.map((r) => [r.name, r.files]));
-  for (const layer of config?.layers ?? []) {
-    if (!CORE_LAYER_NAMES.has(layer.name)) continue;
-    if (layer.optional !== true) continue;
-    const files = countByName.get(layer.name) ?? 0;
-    if (files > 0) {
-      coreOptional.push({ layer: layer.name, files });
-      gaps.push({
-        id: `core-optional-${layer.name}`,
-        severity: 'info',
-        message: `Core layer ${layer.name} has ${files} file(s) but is still optional: true — contract is weaker than the tree`,
-        fix: `Edit ark.config.json: remove optional on ${layer.name} (or set false), then ${arkCommand(root, 'ark-check', '--strict-config')}`,
-      });
-    }
-  }
-
-  // --- Origin report ---
-  const originJson = path.join(root, '.ark', 'reports', 'origin.json');
-  const originReport = {
-    present: fs.existsSync(originJson),
-    path: '.ark/reports/origin.json',
-  };
-  if (adopted && !originReport.present && (coverage?.governed?.percent ?? 0) >= 50) {
-    gaps.push({
-      id: 'origin-report-missing',
-      severity: 'info',
-      message: 'No origin architecture snapshot under .ark/reports/ yet',
-      fix: arkCommand(root, 'ark-check', '--report ark-report.html'),
-    });
-  }
-
-  // --- Baseline policy ---
-  const baselinePath = path.join(root, '.ark-baseline.json');
-  const baselineExists = fs.existsSync(baselinePath);
-  let frozenKeys = 0;
-  if (baselineExists) {
-    try {
-      const raw = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
-      frozenKeys = Array.isArray(raw.violations) ? raw.violations.length : 0;
-    } catch {
-      frozenKeys = 0;
-    }
-  }
-  let primaryPathUsesBaseline = false;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
-    const scripts = pkg.scripts && typeof pkg.scripts === 'object' ? pkg.scripts : {};
-    primaryPathUsesBaseline = Object.values(scripts).some(
-      (s) => typeof s === 'string' && s.includes('--baseline')
-    );
-  } catch {
-    /* no package.json */
-  }
-  if (!primaryPathUsesBaseline) {
-    try {
-      const wfDir = path.join(root, '.github', 'workflows');
-      if (fs.existsSync(wfDir)) {
-        for (const f of fs.readdirSync(wfDir)) {
-          if (!/\.ya?ml$/i.test(f)) continue;
-          const text = fs.readFileSync(path.join(wfDir, f), 'utf8');
-          if (text.includes('--baseline') && (text.includes('ark-check') || text.includes('arkgate-check'))) {
-            primaryPathUsesBaseline = true;
-            break;
-          }
-        }
-      }
-    } catch {
-      /* ignore */
-    }
-  }
-  const baseline = {
-    exists: baselineExists,
-    frozenKeys,
-    primaryPathUsesBaseline,
-    signal: baselineExists
-      ? frozenKeys === 0
-        ? 'keep-empty'
-        : 'active-ratchet'
-      : 'absent',
-  };
-  if (adopted && baselineExists && frozenKeys === 0 && !primaryPathUsesBaseline) {
-    gaps.push({
-      id: 'baseline-unused',
-      severity: 'info',
-      message:
-        'Empty .ark-baseline.json exists but primary scripts/CI do not pass --baseline (policy unclear)',
-      fix: 'Either add --baseline .ark-baseline.json to check:architecture / CI, or remove the unused baseline file',
-    });
-  }
-
-  // --- Educational layer balance (not a violation) ---
-  let layerBalance = null;
-  const total = layerRows.reduce((s, r) => s + (r.files || 0), 0);
-  if (total >= 20) {
-    const presentation = layerRows.find((r) => r.name === 'PresentationAdapters');
-    const domain = layerRows.find((r) => r.name === 'DomainModel');
-    if (presentation && domain) {
-      const pShare = presentation.files / total;
-      const dShare = domain.files / total;
-      if (pShare >= 0.5 && dShare < 0.1) {
-        layerBalance = {
-          kind: 'presentation-heavy-thin-domain',
-          presentationFiles: presentation.files,
-          domainFiles: domain.files,
-          totalFiles: total,
-          educational:
-            'Presentation holds most of the tree while DomainModel is thin — common for UI apps; consider extracting domain types/use-cases as the product grows. Educational only (not a gate failure).',
-        };
-      }
-    }
-  }
-
-  return {
-    gaps,
-    hosts,
-    mcp,
-    codexHome,
-    coreOptional,
-    originReport,
-    baseline,
-    layerBalance,
-  };
-}
-
-// Gate files whose Ark command runner doesn't match this project's package manager — the
-// advisory (and --migrate-commands) target. Returns [] for npm/unknown projects (npx is right)
-// so the check is silent unless there's a real mismatch.
-function staleRunnerGateFiles(root) {
-  const want = execRunner(root);
-  if (want === 'npx') return [];
-  const stale = [];
-  for (const rel of COMMAND_GATE_TEXT_FILES) {
-    let text;
-    try {
-      text = fs.readFileSync(path.join(root, rel), 'utf8');
-    } catch {
-      continue;
-    }
-    RUNNER_BEFORE_ARK.lastIndex = 0;
-    let match;
-    while ((match = RUNNER_BEFORE_ARK.exec(text))) {
-      if (match[0] !== want) {
-        stale.push(rel);
-        break;
-      }
-    }
-  }
-  for (const rel of COMMAND_GATE_JSON_FILES) {
-    let json;
-    try {
-      json = JSON.parse(fs.readFileSync(path.join(root, rel), 'utf8'));
-    } catch {
-      continue;
-    }
-    const ark = json?.mcpServers?.ark;
-    if (ark && ark.command && ark.command !== want.split(' ')[0]) stale.push(rel);
-  }
-  return stale;
-}
-
-// When more than one lockfile is present the project is ambiguous. detectPackageManager()
-// resolves it (package-lock.json wins so a stray pnpm-lock.yaml can't hijack an npm project),
-// but the user should know it happened and how to make it explicit — otherwise a leftover
-// lockfile silently steers which runner every emitted command uses.
-function warnLockfileConflict(root) {
-  const locks = presentLockfiles(root);
-  if (locks.length <= 1) return;
-  const chosen = detectPackageManager(root);
-  const files = { pnpm: 'pnpm-lock.yaml', yarn: 'yarn.lock', npm: 'package-lock.json' };
-  console.log('');
-  console.log(
-    `Note: multiple lockfiles present (${locks.map((pm) => files[pm]).join(', ')}). Treating this`
-  );
-  console.log(
-    `as a ${chosen} project — Ark commands use "${execRunner(root)}". If that's wrong, set`
-  );
-  console.log(
-    '"packageManager" in package.json (e.g. "pnpm@9") to declare it, or remove the stray lockfile.'
-  );
-}
-
-// --migrate-commands: rewrite ONLY the Ark command runner in existing gate files to the
-// project's package manager (no --force clobber). Closes the upgrade gap where a repo that
-// adopted before the package-manager-aware templates keeps a stale `npx`.
-// Also normalizes MCP JSON to a single preferred bin (arkgate-mcp), stripping any dual
-// ark-mcp + arkgate-mcp residue left by partial renames during package identity cutover.
-function runMigrateCommands(root) {
-  const runner = execRunner(root);
-  const changed = [];
-  for (const rel of COMMAND_GATE_TEXT_FILES) {
-    const full = path.join(root, rel);
-    let text;
-    try {
-      text = fs.readFileSync(full, 'utf8');
-    } catch {
-      continue;
-    }
-    let next = text.replace(RUNNER_BEFORE_ARK, runner);
-    // Prefer primary product bins in command strings (aliases still work if left alone).
-    next = next
-      .replace(/\bark-mcp\b/g, PREFERRED_MCP_BIN)
-      .replace(/\bark-check\b/g, PREFERRED_CHECK_BIN);
-    // Do not blanket-replace bare `ark` — it appears in prose ("Ark check", product name).
-    if (next !== text) {
-      fs.writeFileSync(full, next);
-      changed.push(rel);
-    }
-  }
-  for (const rel of COMMAND_GATE_JSON_FILES) {
-    const full = path.join(root, rel);
-    let json;
-    try {
-      json = JSON.parse(fs.readFileSync(full, 'utf8'));
-    } catch {
-      continue;
-    }
-    const ark = json?.mcpServers?.ark;
-    if (!ark) continue;
-    const binArgs = stripMcpServerArgs(ark.args);
-    const parts = execCommandParts(root, PREFERRED_MCP_BIN, binArgs);
-    if (ark.command !== parts.command || JSON.stringify(ark.args) !== JSON.stringify(parts.args)) {
-      json.mcpServers.ark = { ...ark, ...parts };
-      fs.writeFileSync(full, `${JSON.stringify(json, null, 2)}\n`);
-      changed.push(rel);
-    }
-  }
-  const pm = runner === 'pnpm exec' || runner.startsWith('pnpm ') ? 'pnpm' : runner;
-  console.log(`Migrated ArkGate command runners to "${pm}" and normalized MCP bins in gate files.`);
-  if (changed.length === 0) {
-    console.log('  Nothing to change — runners and MCP bins already look correct.');
-  } else {
-    for (const rel of changed) console.log(`  updated ${rel}`);
-    console.log(
-      `  (runner + single MCP bin \`${PREFERRED_MCP_BIN}\`; customized non-command content is untouched.)`
-    );
-  }
-  warnLockfileConflict(root);
-}
-
-function runInstallAgentGates(args) {
-  const root = args.root;
-  if (args.migrateCommands) {
-    runMigrateCommands(root);
-    return;
-  }
-  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, source } = resolveTools(args);
-  const toolSource =
-    source === 'explicit'
-      ? 'from --tools'
-      : source === 'detected'
-        ? 'auto-detected from config dirs'
-        : 'default set — no agent config dirs found';
-  console.log(`Agent gates for: ${[...tools].sort().join(', ')} (${toolSource})`);
-  const templates = [];
-  // --skills-only refreshes just the canonical /ark-* skills, which are safe to
-  // overwrite (they track the package). The gate/instruction files (AGENTS.md,
-  // settings.json, CI workflow, rules) are the ones users customize, so a plain
-  // `--force` clobbers them — this is the safe way to pick up new skill versions.
-  if (!args.skillsOnly) {
-    // Base gates: tool-agnostic contract + CI backstop, always written.
-    templates.push(['AGENTS.md', agentInstructions(root)]);
-    templates.push(['.mcp.json', mcpJson(root)]);
-    templates.push([
-      '.github/workflows/ark-check.yml',
-      githubWorkflow(pm, detectCiNode(root)),
-    ]);
-    if (tools.has('cursor')) {
-      templates.push(['.cursor/mcp.json', mcpJson(root)]);
-      templates.push(['.cursor/rules/ark.mdc', cursorRule(root)]);
-    }
-    if (tools.has('claude')) {
-      templates.push(['.claude/settings.json', claudeSettings(root)]);
-    }
-    if (tools.has('codex')) {
-      templates.push(['docs/ark-codex-config.toml', codexTomlSnippet(root)]);
-    }
-    if (tools.has('grok')) {
-      templates.push(['.grok/config.toml', grokProjectConfig(root)]);
-      templates.push(['.grok/hooks/ark-write-gate.json', grokHooks(root)]);
-    }
-    // Instruction-tier hosts: one shared rule text, host-specific path.
-    if (tools.has('windsurf')) {
-      templates.push(['.windsurf/rules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('cline')) {
-      templates.push(['.clinerules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('copilot')) {
-      templates.push(['.github/copilot-instructions.md', instructionRule(root)]);
-    }
-    if (tools.has('kiro')) {
-      templates.push(['.kiro/steering/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('roo')) {
-      templates.push(['.roo/rules/ark.md', instructionRule(root)]);
-    }
-    if (tools.has('continue')) {
-      templates.push(['.continue/rules/ark.md', instructionRule(root)]);
-    }
-    // Gemini CLI reads GEMINI.md as its primary project context (it also reads
-    // AGENTS.md, but GEMINI.md wins when both are present), so the rule lives there.
-    if (tools.has('gemini')) {
-      templates.push(['GEMINI.md', instructionRule(root)]);
-    }
-  }
-  // /ark-* skills for every detected tool that supports project-level commands.
-  // Stamp each with the shipping version so a later ark-check can flag skills
-  // left behind by an older Ark (see detectSkillGaps) without nagging about
-  // user edits to the body.
-  const version = arkPackageVersion();
-  const skills = skillTemplates().map(([name, content]) => [name, stampSkill(content, version)]);
-  const skillPaths = new Set();
-  for (const tool of tools) {
-    const target = SKILL_TOOL_TARGETS[tool];
-    if (!target) continue;
-    for (const [name, content] of skills) {
-      const relativePath = target(name);
-      skillPaths.add(relativePath);
-      templates.push([relativePath, content]);
-    }
-  }
-
-  const results = templates.map(([relativePath, content]) =>
-    writeTemplate(root, relativePath, content, args.force)
-  );
-
-  console.log('Ark agent gate templates:');
-  let staleSkipped = 0;
-  for (const result of results) {
-    const marker =
-      result.status === 'written' ? 'wrote' : result.status === 'failed' ? 'FAILED' : 'skipped';
-    // A skipped skill reads as "you're fine" — but it may be a version behind.
-    // Say which, so the user isn't left guessing (and knows the safe refresh cmd).
-    let note = '';
-    if (result.status === 'skipped' && skillPaths.has(result.relativePath) && version) {
-      const installed = installedSkillVersion(path.join(root, result.relativePath));
-      if (installed === null || isVersionOlder(installed, version)) {
-        staleSkipped += 1;
-        note = `  (stale: ${installed ?? 'no stamp'} < ${version})`;
-      } else {
-        note = '  (up to date)';
-      }
-    }
-    console.log(`  ${marker.padEnd(7)} ${result.relativePath}${note}`);
-  }
-  if (staleSkipped > 0 && !args.skillsOnly) {
-    console.log('');
-    console.log(
-      `  ${staleSkipped} skill(s) are outdated but were left untouched. Refresh them with:`
-    );
-    console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --skills-only --force')}`);
-  }
-
-  // --codex-home writes the canonical skills straight to $CODEX_HOME/prompts.
-  // Codex reads prompts from there (not the repo), so this is the only way to
-  // refresh them for a repo that isn't itself configured for Codex. It writes to
-  // the user's home dir, hence explicit opt-in rather than part of a normal run.
-  const homeResults = [];
-  if (args.codexHome) {
-    const dir = codexPromptsDir();
-    console.log('');
-    console.log(`Codex home skills (${dir}):`);
-    try {
-      fs.mkdirSync(dir, { recursive: true });
-    } catch (error) {
-      console.error(`  FAILED to create ${dir} (${error.message})`);
-      homeResults.push({ status: 'failed' });
+    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}`);
+      }
     }
-    if (homeResults.length === 0) {
-      for (const [name, content] of skills) {
-        const file = path.join(dir, `${name}.md`);
-        if (fs.existsSync(file) && !args.force) {
-          const installed = installedSkillVersion(file);
-          const behind = installed === null || (version && isVersionOlder(installed, version));
-          const note = behind
-            ? `  (stale: ${installed ?? 'no stamp'} < ${version}; use --force)`
-            : '  (up to date)';
-          console.log(`  ${'skipped'.padEnd(7)} ${name}.md${note}`);
-          homeResults.push({ status: 'skipped' });
-          continue;
-        }
-        try {
-          fs.writeFileSync(file, content);
-          console.log(`  ${'wrote'.padEnd(7)} ${name}.md`);
-          homeResults.push({ status: 'written' });
-        } catch (error) {
-          console.log(`  ${'FAILED'.padEnd(7)} ${name}.md (${error.message})`);
-          homeResults.push({ status: 'failed' });
+    const proposals = proposeForUncovered(args.root, srcDir, finalConfig.layers);
+    if (proposals.length > 0) {
+      const recognized = proposals.filter((p) => !p.unrecognized);
+      const unrecognized = proposals.filter((p) => p.unrecognized);
+      console.log('');
+      console.log('Ungoverned directories — Ark enforces NOTHING here until they are classified.');
+      console.log('A green check ignores this code; it is not "clean", it is unchecked.');
+      if (recognized.length > 0) {
+        console.log('');
+        console.log('Proposed layer for each (from the 11-layer profile + presets — apply via /ark-contract):');
+        for (const p of recognized) {
+          const alt = p.alternatives?.length ? ` (or ${p.alternatives.join(' / ')} — confirm)` : '';
+          console.log(`  ${p.dir}/ → ${p.layer}${alt}`);
         }
       }
+      if (unrecognized.length > 0) {
+        console.log('');
+        console.log(`Not recognized — you decide the layer: ${unrecognized.map((p) => p.dir).join(', ')}`);
+      }
+      const fit = detectBestFitModel(
+        [
+          ...finalConfig.layers.flatMap((l) => (l.patterns ?? []).map((p) => dirSegmentsFromGlob(p).pop())),
+          ...proposals.map((p) => p.dir.split('/').pop()),
+        ].filter(Boolean)
+      );
+      if (fit) {
+        console.log('');
+        console.log(`Closest starter model: ${fit.name} — \`ark init --preset ${fit.name} --force\` to start from its rule set.`);
+      }
     }
   }
-
-  // Auto-wire the ark MCP server into Codex's home config.toml. Claude and Cursor get
-  // machine-readable registrations (.claude/settings.json, .cursor/mcp.json) written as repo
-  // templates above; Codex reads MCP servers only from ~/.codex/config.toml, so it needs a
-  // home-dir merge instead. Fires whenever Codex is in play so `ark://manifest` is live
-  // without a manual copy step.
-  let codexMcp = null;
-  if (tools.has('codex') || args.codexHome) {
-    codexMcp = wireCodexMcp(root, args.force);
-    console.log('');
-    console.log(`Codex MCP registration (${codexMcp.file}):`);
-    if (codexMcp.status === 'skipped') {
-      console.log(`  ${'skipped'.padEnd(7)} [mcp_servers.ark] already present (use --force to overwrite)`);
-    } else if (codexMcp.status === 'failed') {
-      console.log(`  ${'FAILED'.padEnd(7)} [mcp_servers.ark] (${codexMcp.message})`);
-    } else {
-      const verb = codexMcp.status === 'updated' ? 'updated' : 'wrote';
-      console.log(`  ${verb.padEnd(7)} [mcp_servers.ark] with absolute paths`);
-      console.log('          RESTART Codex — it does not hot-load MCP servers.');
-      console.log('          Then expect: resource ark://manifest + tools validate_code, ark_check, ark_coverage, ark_place.');
-    }
-  }
-
-  const failed = [...results, ...homeResults, ...(codexMcp ? [codexMcp] : [])].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: ${arkCheckCommand(root)}`);
-  if (!hasCheckScript) {
-    console.log('  3. Add the package.json alias if you want `run check:architecture`:');
-    console.log(`     ${checkArchitectureScriptSnippet(root)}`);
-  }
-  if ((tools.has('codex') || args.codexHome)) {
-    console.log('');
-    if (codexMcp && codexMcp.status !== 'failed') {
-      console.log(`  Codex: ark MCP registered in ${codexMcp.file} — restart Codex so \`ark://manifest\` loads.`);
-    }
-    if (args.codexHome) {
-      console.log(`  Codex: refreshed the /ark-* skills in ${codexPromptsDir()} — Codex loads them from there.`);
-    } else if (skills.length > 0) {
-      console.log('  Codex loads slash-command prompts from $CODEX_HOME/prompts (~/.codex/prompts),');
-      console.log('  not the repo. Install the /ark-* skills there with:');
-      console.log(`    ${arkCommand(root, 'ark-check', '--install-agent-gates --codex-home')}`);
-      console.log('  (writes to your home dir; agents driving this setup should offer to run it).');
-    }
-  }
-  warnLockfileConflict(root);
+  maybeWarnBrownfield(args.root, finalConfig);
+  printInitNextSteps(args.root);
 }
 
+
 function readManifest(root, manifestPath) {
   if (!manifestPath) return undefined;
   const fullPath = path.isAbsolute(manifestPath)
@@ -2561,6 +925,15 @@ function walk(dir, files = []) {
   return files;
 }
 
+/** Walk include roots then drop codegen / config.exclude (universal scan filter). */
+function collectGovernedFiles(root, config) {
+  const raw = (config.include ?? []).flatMap((entry) => walk(path.join(root, entry)));
+  return raw.filter((abs) => {
+    const rel = normalize(path.relative(root, abs));
+    return !isScanExcludedRelative(rel, config);
+  });
+}
+
 function normalize(value) {
   return value.split(path.sep).join('/');
 }
@@ -2677,11 +1050,16 @@ function collectConfigWarnings(root, config, files, rules, manifest) {
         return re.test(rel);
       });
       if (!matched && !layer.optional) {
+        // Advisory only under --strict-config: monorepo/Next presets ship many optional-looking
+        // globs (e.g. src/layouts/**, app/**) that never match when include is ["frontend"].
+        // Failing the release gate on dead preset globs caused false CI red while architecture
+        // edges were clean (deer-flow host validation). Real safety is import violations +
+        // CONFIG_UNCLASSIFIED_FILES / invalid patterns.
         warnings.push(
           configWarning(
             'CONFIG_LAYER_PATTERN_NO_MATCHES',
             `Layer "${layer.name}" pattern "${pattern}" matched no included files.`,
-            { layer: layer.name, pattern }
+            { layer: layer.name, pattern, failsStrict: false }
           )
         );
       }
@@ -3142,1532 +1520,86 @@ function isArkPublishCandidate(ts, node) {
 function publishSourceLiteral(ts, node) {
   if (!ts.isCallExpression(node)) return undefined;
   const [firstArg, secondArg, thirdArg] = node.arguments;
-  const rawMetadata = objectPropertyValue(ts, firstArg, 'metadata');
-  return (
-    stringLiteralText(ts, objectPropertyValue(ts, rawMetadata, 'source')) ??
-    stringLiteralText(ts, objectPropertyValue(ts, secondArg, 'source')) ??
-    stringLiteralText(ts, objectPropertyValue(ts, thirdArg, 'source'))
-  );
-}
-
-function publishHasSource(ts, node) {
-  if (!ts.isCallExpression(node)) return false;
-  const [firstArg, secondArg, thirdArg] = node.arguments;
-  return (
-    objectHasMetadataSource(ts, firstArg) ||
-    objectHasProperty(ts, secondArg, 'source') ||
-    objectHasProperty(ts, thirdArg, 'source')
-  );
-}
-
-// Baseline keys exclude the line number so unrelated edits that shift lines
-// don't resurrect frozen violations; the trade-off is that N identical violations in one
-// file collapse to one key.
-function baselineKey(violation) {
-  return [
-    violation.ruleId,
-    violation.file,
-    violation.fromLayer ?? '',
-    violation.toLayer ?? '',
-    violation.target ?? '',
-  ].join('|');
-}
-
-function readBaseline(root, baselinePath) {
-  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
-  if (!fs.existsSync(fullPath)) return { keys: new Set(), fullPath, exists: false };
-  const raw = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-  return { keys: new Set(raw.violations ?? []), fullPath, exists: true };
-}
-
-function writeBaseline(root, baselinePath, violations) {
-  const fullPath = path.isAbsolute(baselinePath) ? baselinePath : path.join(root, baselinePath);
-  const keys = [...new Set(violations.map(baselineKey))].sort();
-  fs.writeFileSync(
-    fullPath,
-    `${JSON.stringify({ version: 1, note: 'Frozen ark-check violations. Only NEW violations fail --baseline runs. Regenerate with: ark-check --update-baseline', violations: keys }, null, 2)}\n`
-  );
-  return { fullPath, count: keys.length };
-}
-
-const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
-const color = {
-  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
-  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
-  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
-  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
-  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
-};
-
-const FIX_HINTS = {
-  LAYER_IMPORT_VIOLATION:
-    'Depend on a port/interface owned by an inner layer instead, or move this code to a layer allowed to make this import.',
-  LAYER_INTENT_REFERENCE_VIOLATION:
-    'Reference intents through a layer that owns them (e.g. subscribe from an adapter, not from the domain).',
-  RAW_EVENT_PUBLISH:
-    'Define the intent with ark.registry.define(...) and publish through the returned creator.',
-  PUBLISH_MISSING_SOURCE:
-    'Add metadata.source (the publishing intent name) to the publish call.',
-  PUBLISH_SOURCE_LAYER_MISMATCH:
-    'Use a source intent that belongs to the same layer as the publishing file, or move the file.',
-  FORBIDDEN_GLOBAL:
-    'Inject the capability through a port (e.g. a Clock, IdGenerator, or HttpPort) instead of reaching for the ambient global.',
-  CIRCULAR_DEPENDENCY:
-    'Break the cycle: extract the shared code into a module both sides import, invert one edge behind a port/interface, or merge the files if they are really one unit.',
-};
-
-function printViolation(violation) {
-  const location = `${violation.file}:${violation.line}`;
-  console.error(`${color.red('✖')} ${color.bold(violation.ruleId)}  ${location}`);
-  if (violation.fromLayer && violation.toLayer) {
-    const target = violation.target ? `  ${color.dim(`(${violation.target})`)}` : '';
-    console.error(`  ${violation.fromLayer} → ${violation.toLayer}${target}`);
-  }
-  console.error(`  ${violation.message}`);
-  const hint = FIX_HINTS[violation.ruleId];
-  if (hint) console.error(`  ${color.dim(`fix: ${hint}`)}`);
-  console.error('');
-}
-
-// ── Violation diagnosis ──────────────────────────────────────────────────────
-// Groups violations by their layer EDGE (and target subtree) so a wall of N violations reads
-// as "M distinct problems, ranked by size" — the burn-down order. The killer signal: when
-// one edge dominates, the CONTRACT is usually wrong, not the code (e.g. every API route
-// importing the kernel through a sanctioned entrypoint). Freezing that as "debt" buries a
-// config fix behind a baseline, so --update-baseline refuses a lopsided freeze (see guard).
-const CONCENTRATION_MIN_VIOLATIONS = 10;
-const CONCENTRATION_SHARE = 0.9;
-
-function violationEdge(violation) {
-  if (violation.ruleId === 'CIRCULAR_DEPENDENCY') return 'circular dependency';
-  if (violation.ruleId === 'FORBIDDEN_GLOBAL') return `${violation.fromLayer ?? '?'} → ambient global`;
-  if (violation.fromLayer && violation.toLayer) return `${violation.fromLayer} → ${violation.toLayer}`;
-  return violation.ruleId;
-}
-
-// The directory the offending import lands in — the signal for "where does this edge go?".
-// For a LAYER_IMPORT_VIOLATION the target is a resolved file path; cluster by its dir prefix
-// so `kernel/internal/x` and `kernel/internal/y` collapse to one "into kernel/internal/".
-function violationTargetSubtree(violation) {
-  if (!violation.target || typeof violation.target !== 'string' || !violation.target.includes('/')) {
-    return undefined;
-  }
-  const segments = violation.target.split('/');
-  return segments.slice(0, Math.min(3, segments.length - 1)).join('/');
-}
-
-function summarizeViolations(violations) {
-  const byEdge = new Map();
-  let typeOnly = 0;
-  for (const violation of violations) {
-    if (violation.typeOnly) typeOnly += 1;
-    const key = violationEdge(violation);
-    const entry = byEdge.get(key) ?? { edge: key, count: 0, typeOnly: 0, targets: new Map() };
-    entry.count += 1;
-    if (violation.typeOnly) entry.typeOnly += 1;
-    const subtree = violationTargetSubtree(violation);
-    if (subtree) entry.targets.set(subtree, (entry.targets.get(subtree) ?? 0) + 1);
-    byEdge.set(key, entry);
-  }
-  const edges = [...byEdge.values()]
-    .map((entry) => ({
-      edge: entry.edge,
-      count: entry.count,
-      typeOnly: entry.typeOnly,
-      topTargets: [...entry.targets.entries()]
-        .sort((a, b) => b[1] - a[1])
-        .slice(0, 4)
-        .map(([dir, count]) => ({ dir, count })),
-    }))
-    .sort((a, b) => b.count - a.count);
-  const total = violations.length;
-  const dominant = edges[0];
-  const dominantShare = total > 0 && dominant ? dominant.count / total : 0;
-  return {
-    total,
-    // Value edges are real runtime coupling; type-only edges (erased at compile time) are
-    // just type placement — fix the value ones first, the type-only ones move with the type.
-    valueCount: total - typeOnly,
-    typeOnlyCount: typeOnly,
-    edges,
-    dominant: dominant ? dominant.edge : undefined,
-    dominantShare,
-    concentrated: total >= CONCENTRATION_MIN_VIOLATIONS && dominantShare >= CONCENTRATION_SHARE,
-  };
-}
-
-function printViolationBreakdown(summary, { toStderr = false } = {}) {
-  const out = toStderr ? (line) => console.error(line) : (line) => console.log(line);
-  out('');
-  out(`Violation breakdown — ${summary.total} across ${summary.edges.length} edge(s), largest first:`);
-  if (summary.typeOnlyCount > 0) {
-    out(
-      `  ${summary.valueCount} value (runtime coupling — fix first) · ${summary.typeOnlyCount} type-only (type placement — moves with the type)`
-    );
-  }
-  for (const edge of summary.edges) {
-    const pct = Math.round((edge.count / summary.total) * 100);
-    const typeNote = edge.typeOnly > 0 ? `, ${edge.typeOnly} type-only` : '';
-    out(`  ${String(edge.count).padStart(5)}  ${edge.edge}  (${pct}%${typeNote})`);
-    for (const target of edge.topTargets) {
-      out(`         ↳ ${target.count}× into ${target.dir}/`);
-    }
-  }
-  if (summary.concentrated) {
-    out('');
-    out(`⚠ ${Math.round(summary.dominantShare * 100)}% of violations are a SINGLE edge: ${summary.dominant}.`);
-    out('  That usually means the CONTRACT is wrong, not the code — e.g. app-land reaching a');
-    out('  framework/kernel through a sanctioned entrypoint. Before treating it as debt:');
-    out('    • If the edge is intended, allow it — or split the target layer into a public');
-    out('      surface app-land may import + internals it may not (see the target dirs above');
-    out('      to find the surface). Do it via /ark-contract.');
-    out('    • Only the minority hitting real internals is genuine debt for /ark-fix.');
-    out(`  Fixing the contract clears ~${summary.edges[0].count} of ${summary.total} at once.`);
-  }
-}
-
-// Finds strongly-connected components in the resolved import graph. Any component
-// with more than one file is a set of files that transitively import each other —
-// a circular dependency. One violation per component keeps the output minimal and
-// the baseline key stable (anchored at the alphabetically-first member).
-function detectCycles(graph) {
-  let index = 0;
-  const indices = new Map();
-  const low = new Map();
-  const onStack = new Set();
-  const stack = [];
-  const components = [];
-
-  // ponytail: recursive Tarjan; make it iterative only if a real repo blows the stack.
-  const strongconnect = (v) => {
-    indices.set(v, index);
-    low.set(v, index);
-    index += 1;
-    stack.push(v);
-    onStack.add(v);
-    for (const w of [...(graph.get(v) ?? [])].sort()) {
-      if (!graph.has(w)) continue;
-      if (!indices.has(w)) {
-        strongconnect(w);
-        low.set(v, Math.min(low.get(v), low.get(w)));
-      } else if (onStack.has(w)) {
-        low.set(v, Math.min(low.get(v), indices.get(w)));
-      }
-    }
-    if (low.get(v) === indices.get(v)) {
-      const comp = [];
-      let w;
-      do {
-        w = stack.pop();
-        onStack.delete(w);
-        comp.push(w);
-      } while (w !== v);
-      if (comp.length > 1) components.push(comp.sort());
-    }
-  };
-
-  for (const v of [...graph.keys()].sort()) {
-    if (!indices.has(v)) strongconnect(v);
-  }
-
-  return components
-    .sort((a, b) => a[0].localeCompare(b[0]))
-    .map((members) => ({
-      ruleId: 'CIRCULAR_DEPENDENCY',
-      file: members[0],
-      line: 1,
-      target: members.join(' → '),
-      message: `Circular dependency among ${members.length} files: ${members.join(' → ')} → ${members[0]}.`,
-    }));
-}
-
-function detectEnforcement(root) {
-  const has = (rel) => fs.existsSync(path.join(root, rel));
-  const fileIncludes = (rel, needle) => {
-    try {
-      return fs.readFileSync(path.join(root, rel), 'utf8').includes(needle);
-    } catch {
-      return false;
-    }
-  };
-  const workflowsMentionArk = () => {
-    const dir = path.join(root, '.github', 'workflows');
-    if (!fs.existsSync(dir)) return null;
-    const hit = fs
-      .readdirSync(dir)
-      .filter((f) => /\.ya?ml$/.test(f))
-      .find((f) => fileIncludes(path.join('.github', 'workflows', f), 'ark-check'));
-    return hit ? `.github/workflows/${hit}` : null;
-  };
-  const eslintFile = ['eslint.config.mjs', 'eslint.config.js', 'eslint.config.cjs', '.eslintrc.json', '.eslintrc.cjs'].find(
-    (f) => has(f) && (fileIncludes(f, 'arkgate') || fileIncludes(f, 'ark-runtime-kernel'))
-  );
-  const writeGateFile =
-    ((fileIncludes('.claude/settings.json', 'arkgate-mcp') ||
-      fileIncludes('.claude/settings.json', 'ark-mcp')) &&
-      '.claude/settings.json') ||
-    (has('.cursor/mcp.json') && '.cursor/mcp.json') ||
-    (fileIncludes('.grok/hooks/ark-write-gate.json', 'arkgate-mcp') &&
-      '.grok/hooks/ark-write-gate.json') ||
-    null;
-  return [
-    { name: 'Write gate', where: writeGateFile, what: 'blocks a bad edit as you type (PreToolUse hook / MCP)' },
-    { name: 'ESLint', where: eslintFile || null, what: 'flags violations in your editor' },
-    { name: 'CI check', where: workflowsMentionArk(), what: 'blocks the merge if the architecture breaks' },
-    { name: 'Baseline', where: has('.ark-baseline.json') ? '.ark-baseline.json' : null, what: 'old violations frozen; new ones fail' },
-  ].map((e) => ({ ...e, on: !!e.where }));
-}
-
-function htmlEscape(value) {
-  return String(value)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;');
-}
-
-/** Directory for origin / latest / history architecture report snapshots. */
-const ARK_REPORTS_DIR = path.join('.ark', 'reports');
-const ARK_REPORT_HISTORY_MAX = 20;
-
-function reportsDir(root) {
-  return path.join(root, ARK_REPORTS_DIR);
-}
-
-/**
- * Compact metrics snapshot — machine-readable so future reports can diff against origin.
- * Intentionally small (not the full HTML). Layer file counts included for evolution.
- */
-function buildReportSnapshot({
-  root,
-  config,
-  coverage,
-  violations,
-  ok,
-  suppressed,
-  version,
-  fileCountByLayer,
-  enforcement,
-  score,
-  mode,
-}) {
-  const layers = Array.isArray(config?.layers) ? config.layers : [];
-  const rules = Array.isArray(config?.rules) ? config.rules : [];
-  const counts = {};
-  if (fileCountByLayer instanceof Map) {
-    for (const [name, n] of fileCountByLayer) counts[name] = n;
-  }
-  const gatesOn = (enforcement || []).filter((e) => e.on).length;
-  return {
-    version: 1,
-    kind: 'ark-architecture-snapshot',
-    generatedAt: new Date().toISOString(),
-    arkVersion: version ?? null,
-    project: (() => {
-      try {
-        return readJson(path.join(root, 'package.json')).name || path.basename(root);
-      } catch {
-        return path.basename(root);
-      }
-    })(),
-    ok: Boolean(ok),
-    mode: mode ?? null,
-    score: score ?? null,
-    governedPercent: coverage?.governed?.percent ?? null,
-    classifiedFiles: coverage?.governed?.classifiedFiles ?? 0,
-    totalFiles: coverage?.governed?.totalFiles ?? 0,
-    unclassifiedFiles: coverage?.unclassified?.count ?? 0,
-    layerCount: layers.length,
-    denyRules: rules.filter((r) => r.allowed === false).length,
-    allowRules: rules.filter((r) => r.allowed === true).length,
-    activeViolations: Array.isArray(violations) ? violations.length : 0,
-    typeOnlyViolations: Array.isArray(violations)
-      ? violations.filter((v) => v.typeOnly).length
-      : 0,
-    valueViolations: Array.isArray(violations)
-      ? violations.filter((v) => !v.typeOnly).length
-      : 0,
-    suppressed: suppressed ?? 0,
-    gatesOn,
-    gatesTotal: (enforcement || []).length,
-    layerFiles: counts,
-  };
-}
-
-function readJsonSafe(file) {
-  try {
-    return JSON.parse(fs.readFileSync(file, 'utf8'));
-  } catch {
-    return null;
-  }
-}
-
-function deltaField(current, origin, key) {
-  const a = current?.[key];
-  const b = origin?.[key];
-  if (typeof a !== 'number' || typeof b !== 'number') return null;
-  return a - b;
-}
-
-/**
- * Persist origin (once), latest, optional history; return { origin, createdOrigin }.
- */
-/** Shared fitness numbers for HTML report + machine-readable snapshots. */
-function computeReportFitness({ coverage, violations, ok, enforcement, config }) {
-  const layers = Array.isArray(config?.layers) ? config.layers : [];
-  const rules = Array.isArray(config?.rules) ? config.rules : [];
-  const deniedCount = rules.filter((r) => r.allowed === false).length;
-  const gatesOn = (enforcement || []).filter((e) => e.on).length;
-  const governedPercent = coverage?.governed?.percent ?? null;
-  const totalFiles = coverage?.governed?.totalFiles ?? 0;
-  const classifiedFiles = coverage?.governed?.classifiedFiles ?? 0;
-  const mode = resolveOperatingMode({
-    governedPercent: totalFiles === 0 ? 0 : governedPercent,
-    planMet:
-      ok &&
-      (violations?.length ?? 0) === 0 &&
-      totalFiles > 0 &&
-      (governedPercent == null || governedPercent >= 50),
-    mature: totalFiles >= 150,
-    totalFiles,
-  });
-  const modeLabel = { suggest: 'SUGGEST', adapt: 'ADAPT', enforce: 'ENFORCE' }[mode] || String(mode).toUpperCase();
-  const modeBlurb = {
-    suggest: 'Starter shape — expand layers as the codebase grows.',
-    adapt: 'Contract is live; raise governed coverage or match real folders.',
-    enforce: 'Contract governs the tree. Gates can honestly hold the line.',
-  }[mode];
-  const scoreCoverage = governedPercent == null ? 50 : governedPercent;
-  const scoreClean =
-    (violations?.length ?? 0) === 0
-      ? 100
-      : Math.max(0, 100 - Math.min(100, violations.length * 4));
-  const scoreGates = enforcement?.length
-    ? Math.round((gatesOn / enforcement.length) * 100)
-    : 40;
-  const scoreRules = layers.length
-    ? Math.min(
-        100,
-        Math.round((deniedCount / Math.max(1, layers.length * (layers.length - 1))) * 120)
-      )
-    : 0;
-  const score = Math.round(
-    scoreCoverage * 0.4 + scoreClean * 0.3 + scoreGates * 0.2 + scoreRules * 0.1
-  );
-  const scoreTone = score >= 90 ? 'elite' : score >= 70 ? 'strong' : score >= 50 ? 'ok' : 'weak';
-  const scoreCaption =
-    score >= 90
-      ? 'World-class architecture fitness'
-      : score >= 70
-        ? 'Solid architecture discipline'
-        : score >= 50
-          ? 'Useful guardrails — room to grow'
-          : 'Early stage — keep adopting layers';
-  return {
-    governedPercent,
-    totalFiles,
-    classifiedFiles,
-    mode,
-    modeLabel,
-    modeBlurb,
-    score,
-    scoreCoverage,
-    scoreClean,
-    scoreGates,
-    scoreRules,
-    scoreTone,
-    scoreCaption,
-    gatesOn,
-    deniedCount,
-  };
-}
-
-function formatDelta(n, opts = {}) {
-  if (n == null || Number.isNaN(n)) return '—';
-  if (n === 0) return '0';
-  const sign = n > 0 ? '+' : '';
-  const suffix = opts.suffix ?? '';
-  return `${sign}${n}${suffix}`;
-}
-
-function archiveReportSnapshots(root, { html, snapshot, resetOrigin = false, noArchive = false }) {
-  const dir = reportsDir(root);
-  const historyDir = path.join(dir, 'history');
-  fs.mkdirSync(historyDir, { recursive: true });
-
-  const originJson = path.join(dir, 'origin.json');
-  const originHtml = path.join(dir, 'origin.html');
-  const latestJson = path.join(dir, 'latest.json');
-  const latestHtml = path.join(dir, 'latest.html');
-
-  let origin = readJsonSafe(originJson);
-  let createdOrigin = false;
-  if (!origin || resetOrigin) {
-    fs.writeFileSync(originJson, `${JSON.stringify(snapshot, null, 2)}\n`);
-    fs.writeFileSync(originHtml, html);
-    origin = snapshot;
-    createdOrigin = true;
-  }
-
-  fs.writeFileSync(latestJson, `${JSON.stringify(snapshot, null, 2)}\n`);
-  fs.writeFileSync(latestHtml, html);
-
-  if (!noArchive) {
-    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
-    fs.writeFileSync(path.join(historyDir, `${stamp}.json`), `${JSON.stringify(snapshot, null, 2)}\n`);
-    // Cap history: keep newest ARK_REPORT_HISTORY_MAX JSON files.
-    try {
-      const files = fs
-        .readdirSync(historyDir)
-        .filter((f) => f.endsWith('.json'))
-        .map((f) => ({ f, t: fs.statSync(path.join(historyDir, f)).mtimeMs }))
-        .sort((a, b) => b.t - a.t);
-      for (const old of files.slice(ARK_REPORT_HISTORY_MAX)) {
-        fs.unlinkSync(path.join(historyDir, old.f));
-      }
-    } catch {
-      /* ignore prune errors */
-    }
-  }
-
-  // Ensure .ark/ is gitignored when a .gitignore exists.
-  const gitignore = path.join(root, '.gitignore');
-  if (fs.existsSync(gitignore)) {
-    const text = fs.readFileSync(gitignore, 'utf8');
-    const hasArk =
-      text.split('\n').some((line) => {
-        const t = line.trim();
-        return t === '.ark/' || t === '.ark' || t === '/.ark/' || t === '**/.ark/';
-      });
-    if (!hasArk) {
-      const suffix = text.endsWith('\n') || text.length === 0 ? '' : '\n';
-      fs.writeFileSync(
-        gitignore,
-        `${text}${suffix}\n# Ark generated reports / local state\n.ark/\n`
-      );
-    }
-  }
-
-  return { origin, createdOrigin, dir, originJson, latestHtml };
-}
-
-// Simplified onboarding report: compact diagram, placement table, short violation list.
-function renderBeginnerHtmlReport({ root, config, violations, ok, version, configPath, generatedAt }) {
-  const layers = Array.isArray(config.layers) ? config.layers : [];
-  const esc = htmlEscape;
-  const project = (() => {
-    try {
-      return readJson(path.join(root, 'package.json')).name || path.basename(root);
-    } catch {
-      return path.basename(root);
-    }
-  })();
-  const status = ok ? 'PASS' : 'FAIL';
-  const phase1 = layers.slice(0, 4);
-  const diagram = phase1
-    .map((layer, index) => `${index + 1}. ${layer.name}`)
-    .join('  →  ') || 'Add layers in ark.config.json';
-
-  const placementRows = layers
-    .map((layer) => {
-      const purpose = layer.description || 'See ark.config.json';
-      const folders = (layer.patterns || []).join(', ') || '—';
-      return `<tr><td><strong>${esc(layer.name)}</strong></td><td>${esc(purpose)}</td><td><code>${esc(folders)}</code></td></tr>`;
-    })
-    .join('\n');
-
-  const violationRows = violations.length
-    ? violations
-        .slice(0, 12)
-        .map((v) => {
-          const enriched = enrichViolationWithFixClass(v);
-          return `<li><code>${esc(v.file)}:${v.line}</code> — ${esc(enriched.enthusiastHint ?? v.message)}</li>`;
-        })
-        .join('\n')
-    : '<li class="dim">No active violations — architecture matches the contract.</li>';
-
-  const meta = [version ? `ark-check v${esc(version)}` : '', generatedAt ? esc(generatedAt) : '']
-    .filter(Boolean)
-    .join(' · ');
-
-  return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Ark beginner guide — ${esc(project)}</title>
-<style>
-  body { font-family: system-ui, sans-serif; margin: 2rem; line-height: 1.5; max-width: 720px; }
-  h1 { font-size: 1.4rem; }
-  .badge { padding: .2em .6em; border-radius: 999px; font-weight: 700; font-size: .85rem; }
-  .PASS { background: #dcfce7; color: #166534; }
-  .FAIL { background: #fee2e2; color: #991b1b; }
-  .diagram { background: #f4f4f5; padding: 1rem; border-radius: 8px; font-family: monospace; margin: 1rem 0; }
-  table { width: 100%; border-collapse: collapse; margin: 1rem 0; }
-  th, td { text-align: left; padding: .5rem; border-bottom: 1px solid #e4e4e7; vertical-align: top; }
-  th { font-size: .75rem; text-transform: uppercase; color: #71717a; }
-  ul { padding-left: 1.2rem; }
-  .dim { color: #71717a; }
-  footer { margin-top: 2rem; font-size: .85rem; color: #71717a; }
-</style></head>
-<body>
-  <h1>${esc(project)} <span class="badge ${status}">${status}</span></h1>
-  <p class="dim">Beginner architecture guide · ${meta}</p>
-  <h2>How layers flow (inner → outer)</h2>
-  <div class="diagram">${esc(diagram)}</div>
-  <p>Business rules live in inner layers; UI and databases live in outer adapter layers. Inner code must not import outer code.</p>
-  <h2>Where code goes</h2>
-  <table>
-    <tr><th>Layer</th><th>Purpose</th><th>Typical folders</th></tr>
-    ${placementRows || '<tr><td colspan="3">No layers configured.</td></tr>'}
-  </table>
-  <h2>What to fix first</h2>
-  <ul>${violationRows}</ul>
-  <h2>Next steps</h2>
-  <p><code>${arkCheckCommand(root)}</code></p>
-  <p><code>${arkCommand(root, 'ark-check', '--recommend')}</code></p>
-  <footer>Generated by ark-check --report --beginner. Config: ${esc(configPath)}</footer>
-</body></html>`;
-}
-
-/**
- * Showcase HTML architecture report — the visual product of `/ark-explain` + ark-check.
- * Self-contained (no CDN), print-friendly, works offline. Designed to look great on a
- * fully governed repo (100% coverage, clean gates) and still be useful when debt remains.
- */
-function renderHtmlReport({
-  root,
-  config,
-  exampleByLayer,
-  fileCountByLayer,
-  coverage,
-  violations,
-  ok,
-  suppressed,
-  version,
-  configPath,
-  generatedAt,
-  skillGaps = [],
-  originSnapshot = null,
-  currentSnapshot = null,
-  originJustCreated = false,
-  adoption = null,
-}) {
-  const layers = Array.isArray(config.layers) ? config.layers : [];
-  const rules = Array.isArray(config.rules) ? config.rules : [];
-  const esc = htmlEscape;
-  const project = (() => {
-    try {
-      return readJson(path.join(root, 'package.json')).name || path.basename(root);
-    } catch {
-      return path.basename(root);
-    }
-  })();
-
-  const findRule = (from, to) => rules.find((r) => r.from === from && r.to === to);
-  const deniedOut = (name) => rules.filter((r) => r.from === name && r.allowed === false).length;
-  // Innermost first: more outbound denies → deeper (pure core).
-  const ordered = [...layers].sort(
-    (a, b) => deniedOut(b.name) - deniedOut(a.name) || a.name.localeCompare(b.name)
+  const rawMetadata = objectPropertyValue(ts, firstArg, 'metadata');
+  return (
+    stringLiteralText(ts, objectPropertyValue(ts, rawMetadata, 'source')) ??
+    stringLiteralText(ts, objectPropertyValue(ts, secondArg, 'source')) ??
+    stringLiteralText(ts, objectPropertyValue(ts, thirdArg, 'source'))
   );
+}
 
-  const deniedCount = rules.filter((r) => r.allowed === false).length;
-  const allowedCount = rules.filter((r) => r.allowed === true).length;
-  const guarded = layers.filter(
-    (l) => Array.isArray(l.forbiddenGlobals) && l.forbiddenGlobals.length
-  ).length;
-  const enforcement = detectEnforcement(root);
-  const gatesOn = enforcement.filter((e) => e.on).length;
-  const status = ok ? 'PASS' : 'FAIL';
-
-  const fitness = computeReportFitness({
-    coverage,
-    violations,
-    ok,
-    enforcement,
-    config,
-  });
-  const {
-    governedPercent,
-    totalFiles,
-    classifiedFiles,
-    mode,
-    modeLabel,
-    modeBlurb,
-    score,
-    scoreCoverage,
-    scoreClean,
-    scoreGates,
-    scoreRules,
-    scoreTone,
-    scoreCaption,
-  } = fitness;
-
-  const adoptionView = adoption || collectAdoptionGaps(root, config, coverage);
-
-  // ── Senior diagnostics (coupling, purity, contract density) ──────────────
-  const layerNames = ordered.map((l) => l.name);
-  const pairCount = Math.max(1, layers.length * Math.max(0, layers.length - 1));
-  const denyRatio = Math.round((deniedCount / pairCount) * 1000) / 10;
-  const fanOut = new Map(layerNames.map((n) => [n, 0]));
-  const fanIn = new Map(layerNames.map((n) => [n, 0]));
-  for (const from of layerNames) {
-    for (const to of layerNames) {
-      if (from === to) continue;
-      const rule = findRule(from, to);
-      const denied = rule && rule.allowed === false;
-      if (!denied) {
-        fanOut.set(from, (fanOut.get(from) || 0) + 1);
-        fanIn.set(to, (fanIn.get(to) || 0) + 1);
-      }
-    }
-  }
-  const couplingRows = ordered
-    .map((layer) => {
-      const fo = fanOut.get(layer.name) || 0;
-      const fi = fanIn.get(layer.name) || 0;
-      const files = (fileCountByLayer instanceof Map ? fileCountByLayer.get(layer.name) : 0) || 0;
-      const density = files > 0 ? Math.round((fo / files) * 100) / 100 : fo;
-      return { name: layer.name, fo, fi, files, density, denyOut: deniedOut(layer.name) };
-    })
-    .sort((a, b) => b.fo - a.fo || b.fi - a.fi);
-
-  const purityLayers = ordered.filter(
-    (l) => Array.isArray(l.forbiddenGlobals) && l.forbiddenGlobals.length
+function publishHasSource(ts, node) {
+  if (!ts.isCallExpression(node)) return false;
+  const [firstArg, secondArg, thirdArg] = node.arguments;
+  return (
+    objectHasMetadataSource(ts, firstArg) ||
+    objectHasProperty(ts, secondArg, 'source') ||
+    objectHasProperty(ts, thirdArg, 'source')
   );
-  const infraLayers = ordered.filter((l) => l.mayImportInfrastructure);
-  const excludeLayers = ordered.filter((l) => Array.isArray(l.exclude) && l.exclude.length);
-  const intentMap = ordered
-    .filter((l) => Array.isArray(l.intentPrefixes) && l.intentPrefixes.length)
-    .map((l) => ({ name: l.name, prefixes: l.intentPrefixes }));
-
-  const emptyLayers = coverage?.emptyLayers ?? [];
-  const layersWithoutRules = coverage?.layersWithoutRules ?? [];
-  const unclassifiedCount = coverage?.unclassified?.count ?? 0;
-  const includeRoots = Array.isArray(config.include) ? config.include : [];
-
-  const typeOnlyN = violations.filter((v) => v.typeOnly).length;
-  const valueN = violations.length - typeOnlyN;
-  const byEdge = new Map();
-  for (const v of violations) {
-    if (!v.fromLayer || !v.toLayer) continue;
-    const key = `${v.fromLayer} → ${v.toLayer}`;
-    byEdge.set(key, (byEdge.get(key) || 0) + 1);
-  }
-  const topEdges = [...byEdge.entries()].sort((a, b) => b[1] - a[1]).slice(0, 8);
-
-  let packageManagerLabel = 'npm';
-  try {
-    packageManagerLabel = detectPackageManager(root);
-  } catch {
-    /* ignore */
-  }
+}
+const useColor = process.stderr.isTTY && !process.env.NO_COLOR;
+const color = {
+  red: (s) => (useColor ? `\x1b[31m${s}\x1b[0m` : s),
+  yellow: (s) => (useColor ? `\x1b[33m${s}\x1b[0m` : s),
+  green: (s) => (useColor ? `\x1b[32m${s}\x1b[0m` : s),
+  dim: (s) => (useColor ? `\x1b[2m${s}\x1b[0m` : s),
+  bold: (s) => (useColor ? `\x1b[1m${s}\x1b[0m` : s),
+};
 
-  const baselinePath = path.join(root, '.ark-baseline.json');
-  let baselineKeys = 0;
-  if (fs.existsSync(baselinePath)) {
-    try {
-      const raw = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
-      baselineKeys = Array.isArray(raw?.violations)
-        ? raw.violations.length
-        : Array.isArray(raw)
-          ? raw.length
-          : typeof raw === 'object' && raw
-            ? Object.keys(raw).length
-            : 0;
-    } catch {
-      baselineKeys = suppressed || 0;
-    }
-  }
+function detectCycles(graph) {
+  let index = 0;
+  const indices = new Map();
+  const low = new Map();
+  const onStack = new Set();
+  const stack = [];
+  const components = [];
 
-  // Pattern specificity hotspots: very broad globs (**/ or bare *) vs file-precise.
-  const broadPatterns = [];
-  const precisePatterns = [];
-  for (const layer of ordered) {
-    for (const pattern of layer.patterns || []) {
-      const p = String(pattern);
-      const scoreP = patternSpecificity(p);
-      if (p.includes('**') && p.split('/').filter(Boolean).length <= 2) {
-        broadPatterns.push({ layer: layer.name, pattern: p, score: scoreP });
-      }
-      if (!p.includes('*') || /\.[a-zA-Z0-9]+$/.test(p.replace(/\*$/, ''))) {
-        if (p.includes('.') && !p.endsWith('/**')) {
-          precisePatterns.push({ layer: layer.name, pattern: p, score: scoreP });
-        }
+  // ponytail: recursive Tarjan; make it iterative only if a real repo blows the stack.
+  const strongconnect = (v) => {
+    indices.set(v, index);
+    low.set(v, index);
+    index += 1;
+    stack.push(v);
+    onStack.add(v);
+    for (const w of [...(graph.get(v) ?? [])].sort()) {
+      if (!graph.has(w)) continue;
+      if (!indices.has(w)) {
+        strongconnect(w);
+        low.set(v, Math.min(low.get(v), low.get(w)));
+      } else if (onStack.has(w)) {
+        low.set(v, Math.min(low.get(v), indices.get(w)));
       }
     }
-  }
-  broadPatterns.sort((a, b) => a.score - b.score);
-  precisePatterns.sort((a, b) => b.score - a.score);
-
-  const counts = fileCountByLayer instanceof Map ? fileCountByLayer : new Map();
-  const maxFiles = Math.max(1, ...ordered.map((l) => counts.get(l.name) || 0));
-
-  // Concentric “onion” SVG — outer entrypoints, pure core in the center.
-  const palette = [
-    '#38bdf8',
-    '#818cf8',
-    '#a78bfa',
-    '#e879f9',
-    '#fb7185',
-    '#fb923c',
-    '#fbbf24',
-    '#a3e635',
-    '#34d399',
-    '#2dd4bf',
-    '#22d3ee',
-    '#60a5fa',
-  ];
-  // ordered is inner→outer; reverse for drawing outer rings first
-  const outerFirst = [...ordered].reverse();
-  const n = outerFirst.length || 1;
-  const cx = 200;
-  const cy = 200;
-  const rMax = 185;
-  const rMin = 28;
-  const rings = outerFirst
-    .map((layer, i) => {
-      const t0 = i / n;
-      const t1 = (i + 1) / n;
-      const rOuter = rMax - t0 * (rMax - rMin);
-      const rInner = rMax - t1 * (rMax - rMin);
-      const color = palette[i % palette.length];
-      const files = counts.get(layer.name) || 0;
-      // Donut sector as full ring (annulus) via two arcs
-      const ringPath = (() => {
-        if (rInner <= 0.5) {
-          return `<circle cx="${cx}" cy="${cy}" r="${rOuter}" fill="${color}" fill-opacity="0.22" stroke="${color}" stroke-width="1.2"/>`;
-        }
-        return `<circle cx="${cx}" cy="${cy}" r="${(rOuter + rInner) / 2}" fill="none" stroke="${color}" stroke-width="${Math.max(6, rOuter - rInner - 2)}" stroke-opacity="0.85"/>`;
-      })();
-      const labelR = (rOuter + rInner) / 2;
-      const labelY = cy - labelR + (i === n - 1 ? 0 : 0);
-      // Labels stacked on the right of the diagram for readability
-      return { layer, color, files, ringPath, labelR, i };
-    })
-    .map((item, idx, arr) => {
-      const legendY = 28 + idx * 22;
-      return `${item.ringPath}
-        <circle cx="430" cy="${legendY}" r="5" fill="${item.color}"/>
-        <text x="442" y="${legendY + 4}" class="svg-lbl">${esc(item.layer.name)} · ${item.files}</text>`;
-    })
-    .join('\n');
-  const coreLabel =
-    ordered.length > 0
-      ? `<text x="${cx}" y="${cy + 4}" text-anchor="middle" class="svg-core">${esc(ordered[0].name)}</text>`
-      : '';
-  const onionSvg = `<svg viewBox="0 0 560 400" class="onion" role="img" aria-label="Architecture layers from outer adapters to inner core">
-    <rect x="0" y="0" width="560" height="400" fill="transparent"/>
-    ${rings}
-    ${coreLabel}
-    <text x="${cx}" y="388" text-anchor="middle" class="svg-cap">outer adapters → pure core</text>
-  </svg>`;
-
-  // Coverage bars
-  const barRows = ordered
-    .map((layer) => {
-      const files = counts.get(layer.name) || 0;
-      const pct = Math.round((files / maxFiles) * 100);
-      const example = exampleByLayer?.get?.(layer.name);
-      return `<div class="bar-row">
-        <div class="bar-name">${esc(layer.name)}</div>
-        <div class="bar-track"><div class="bar-fill" style="width:${pct}%"></div></div>
-        <div class="bar-n">${files}</div>
-        <div class="bar-ex">${example ? `<code>${esc(example)}</code>` : '<span class="dim">—</span>'}</div>
-      </div>`;
-    })
-    .join('\n');
-
-  const layerRows = ordered
-    .map((layer) => {
-      const tags = [
-        Array.isArray(layer.forbiddenGlobals) && layer.forbiddenGlobals.length
-          ? `<span class="tag warn">no ${layer.forbiddenGlobals.map(esc).join(', ')}</span>`
-          : '',
-        layer.mayImportInfrastructure ? '<span class="tag">may import infra</span>' : '',
-        Array.isArray(layer.intentPrefixes) && layer.intentPrefixes.length
-          ? `<span class="tag">${layer.intentPrefixes.map(esc).join(' ')}</span>`
-          : '',
-        layer.optional ? '<span class="tag dim-tag">optional</span>' : '',
-      ].join(' ');
-      const example = exampleByLayer?.get?.(layer.name);
-      const files = counts.get(layer.name) || 0;
-      return `<tr>
-        <td class="ln">${esc(layer.name)}<div class="tags">${tags}</div></td>
-        <td>${layer.description ? esc(layer.description) : '<span class="dim">—</span>'}</td>
-        <td class="num">${files}</td>
-        <td><code class="pat">${(layer.patterns || []).map(esc).join('<br>') || '—'}</code></td>
-        <td>${example ? `<code>${esc(example)}</code>` : '<span class="dim">no files yet</span>'}</td>
-      </tr>`;
-    })
-    .join('\n');
-
-  const flowRows = ordered
-    .map((layer) => {
-      const targets = ordered
-        .filter((other) => other.name !== layer.name)
-        .filter((other) => {
-          const rule = findRule(layer.name, other.name);
-          return !(rule && rule.allowed === false);
-        })
-        .map((other) => `<span class="chip ok">${esc(other.name)}</span>`)
-        .join('');
-      return `<div class="flow"><span class="flow-name">${esc(layer.name)}</span>
-        <span class="flow-arrow">may import →</span>
-        <span class="flow-targets">${targets || '<span class="dim">nothing (pure core)</span>'}</span></div>`;
-    })
-    .join('\n');
-
-  const matrixHead = ordered.map((l) => `<th class="rot"><span>${esc(l.name)}</span></th>`).join('');
-  const matrixBody = ordered
-    .map((from) => {
-      const cells = ordered
-        .map((to) => {
-          if (from.name === to.name) return '<td class="self">·</td>';
-          const rule = findRule(from.name, to.name);
-          if (!rule) return '<td class="implicit" title="no rule (implicitly allowed)">·</td>';
-          return rule.allowed
-            ? '<td class="allow" title="allowed">✓</td>'
-            : `<td class="deny" title="${esc(rule.message || 'denied')}">✕</td>`;
-        })
-        .join('');
-      return `<tr><th class="rowlbl">${esc(from.name)}</th>${cells}</tr>`;
-    })
-    .join('\n');
-
-  const byRule = new Map();
-  for (const v of violations) {
-    if (!byRule.has(v.ruleId)) byRule.set(v.ruleId, []);
-    byRule.get(v.ruleId).push(v);
-  }
-  const violationBlocks = violations.length
-    ? [...byRule.entries()]
-        .map(([ruleId, items]) => {
-          const hint = FIX_HINTS[ruleId];
-          const rows = items
-            .map((v) => {
-              const edge =
-                v.fromLayer && v.toLayer ? `${esc(v.fromLayer)} → ${esc(v.toLayer)}` : '';
-              const enriched = enrichViolationWithFixClass(v);
-              return `<li>
-                <code>${esc(v.file)}:${v.line}</code>
-                ${edge ? `<span class="edge">${edge}${v.target ? ` <span class="dim">(${esc(v.target)})</span>` : ''}</span>` : ''}
-                <div class="msg">${esc(enriched.enthusiastHint || v.message)}</div>
-              </li>`;
-            })
-            .join('\n');
-          return `<div class="vgroup">
-            <div class="vghead"><span class="rule">${esc(ruleId)}</span> <span class="dim">${items.length}</span></div>
-            <ul class="vitems">${rows}</ul>
-            ${hint ? `<div class="fix">fix: ${esc(hint)}</div>` : ''}
-          </div>`;
-        })
-        .join('\n')
-    : `<div class="clean hero-clean">
-        <div class="clean-title">Architecture matches the contract</div>
-        <div class="clean-body">No active violations${suppressed ? ` · ${suppressed} frozen by baseline` : ''}. This is what “honest green” looks like when coverage is real.</div>
-      </div>`;
-
-  const enforcementRows = enforcement
-    .map(
-      (e) =>
-        `<div class="gate ${e.on ? 'on' : 'off'}">
-          <span class="dot"></span>
-          <div><b>${esc(e.name)}</b><div class="gdesc">${esc(e.what)}</div>
-          ${e.where ? `<code>${esc(e.where)}</code>` : '<span class="dim">not configured</span>'}</div>
-        </div>`
-    )
-    .join('\n');
-
-  const skillsNote =
-    skillGaps.length === 0
-      ? '<div class="pill good">Agent skills current for detected tools</div>'
-      : `<div class="pill warn">${skillGaps.length} skill gap(s) — run ark upgrade / --install-agent-gates</div>`;
-
-  const meta = [
-    version ? `ark-check v${esc(version)}` : '',
-    generatedAt ? esc(generatedAt) : '',
-    configPath ? `config: ${esc(configPath)}` : '',
-  ]
-    .filter(Boolean)
-    .join(' · ');
-
-  const govLabel =
-    governedPercent == null ? '—' : `${governedPercent}% (${classifiedFiles}/${totalFiles})`;
-
-  return `<!doctype html>
-<html lang="en"><head><meta charset="utf-8">
-<meta name="viewport" content="width=device-width, initial-scale=1">
-<title>Ark · ${esc(project)}</title>
-<style>
-  :root {
-    --bg: #07090d; --panel: #10141b; --panel2: #161b24; --ink: #eef1f5; --dim: #8b93a0;
-    --line: #243041; --green: #34d399; --red: #f87171; --accent: #38bdf8; --gold: #fbbf24;
-    --violet: #a78bfa; --radius: 14px;
-  }
-  @media (prefers-color-scheme: light) {
-    :root {
-      --bg: #f4f6f9; --panel: #fff; --panel2: #f8fafc; --ink: #0f172a; --dim: #64748b;
-      --line: #e2e8f0; --green: #059669; --red: #dc2626; --accent: #0284c7; --gold: #d97706;
-      --violet: #7c3aed;
-    }
-  }
-  * { box-sizing: border-box; }
-  body {
-    margin: 0; padding: 0 0 4rem;
-    background:
-      radial-gradient(1200px 600px at 10% -10%, color-mix(in srgb, var(--accent) 18%, transparent), transparent 60%),
-      radial-gradient(900px 500px at 100% 0%, color-mix(in srgb, var(--violet) 14%, transparent), transparent 55%),
-      var(--bg);
-    color: var(--ink);
-    font: 15px/1.55 ui-sans-serif, system-ui, -apple-system, Segoe UI, Roboto, sans-serif;
-  }
-  .wrap { max-width: 1080px; margin: 0 auto; padding: 2rem 1.25rem; }
-  .hero {
-    display: grid; grid-template-columns: 1.4fr 0.9fr; gap: 1.25rem; align-items: stretch;
-    margin-bottom: 1.5rem;
-  }
-  @media (max-width: 820px) { .hero { grid-template-columns: 1fr; } }
-  .card {
-    background: linear-gradient(180deg, color-mix(in srgb, var(--panel) 92%, #fff 4%), var(--panel));
-    border: 1px solid var(--line); border-radius: var(--radius);
-    padding: 1.15rem 1.25rem; box-shadow: 0 20px 50px rgba(0,0,0,.18);
-  }
-  h1 { font-size: 1.65rem; margin: 0 0 .35rem; letter-spacing: -0.02em; }
-  h2 { font-size: 1.05rem; margin: 0 0 .35rem; letter-spacing: -0.01em; }
-  h3 { font-size: .92rem; margin: 1rem 0 .4rem; color: var(--dim); text-transform: uppercase; letter-spacing: .06em; font-weight: 600; }
-  .lede { color: var(--dim); margin: 0 0 1rem; max-width: 42rem; }
-  .meta { color: var(--dim); font-size: .8rem; margin: .75rem 0 0; }
-  .badge, .pill {
-    display: inline-flex; align-items: center; gap: .35rem;
-    padding: .2em .65em; border-radius: 999px; font-weight: 700; font-size: .78rem;
-    letter-spacing: .03em; border: 1px solid transparent;
-  }
-  .PASS { background: color-mix(in srgb, var(--green) 18%, transparent); color: var(--green); border-color: color-mix(in srgb, var(--green) 35%, transparent); }
-  .FAIL { background: color-mix(in srgb, var(--red) 18%, transparent); color: var(--red); border-color: color-mix(in srgb, var(--red) 35%, transparent); }
-  .mode { background: color-mix(in srgb, var(--accent) 16%, transparent); color: var(--accent); border-color: color-mix(in srgb, var(--accent) 35%, transparent); }
-  .pill.good { background: color-mix(in srgb, var(--green) 14%, transparent); color: var(--green); }
-  .pill.warn { background: color-mix(in srgb, var(--gold) 16%, transparent); color: var(--gold); }
-  .score-card { display: flex; flex-direction: column; justify-content: center; text-align: center; min-height: 100%; }
-  .score-ring {
-    --p: ${score};
-    width: 148px; height: 148px; margin: .25rem auto 0.85rem;
-    border-radius: 50%;
-    background:
-      radial-gradient(var(--panel) 58%, transparent 59%),
-      conic-gradient(var(--accent) calc(var(--p) * 1%), var(--line) 0);
-    display: grid; place-items: center;
-  }
-  .score-ring.elite { background:
-      radial-gradient(var(--panel) 58%, transparent 59%),
-      conic-gradient(var(--green) calc(var(--p) * 1%), var(--line) 0); }
-  .score-ring.strong { background:
-      radial-gradient(var(--panel) 58%, transparent 59%),
-      conic-gradient(var(--accent) calc(var(--p) * 1%), var(--line) 0); }
-  .score-ring.ok { background:
-      radial-gradient(var(--panel) 58%, transparent 59%),
-      conic-gradient(var(--gold) calc(var(--p) * 1%), var(--line) 0); }
-  .score-ring.weak { background:
-      radial-gradient(var(--panel) 58%, transparent 59%),
-      conic-gradient(var(--red) calc(var(--p) * 1%), var(--line) 0); }
-  .score-n { font-size: 2.1rem; font-weight: 800; letter-spacing: -0.03em; line-height: 1; }
-  .score-cap { color: var(--dim); font-size: .85rem; margin: 0; }
-  .kpis { display: grid; grid-template-columns: repeat(4, 1fr); gap: .65rem; margin: 1rem 0 0; }
-  @media (max-width: 720px) { .kpis { grid-template-columns: repeat(2, 1fr); } }
-  .kpi { background: var(--panel2); border: 1px solid var(--line); border-radius: 12px; padding: .7rem .8rem; }
-  .kpi b { display: block; font-size: 1.25rem; letter-spacing: -0.02em; }
-  .kpi span { color: var(--dim); font-size: .75rem; text-transform: uppercase; letter-spacing: .05em; }
-  .section { margin-top: 1.35rem; }
-  .grid-2 { display: grid; grid-template-columns: 1.1fr 0.9fr; gap: 1rem; }
-  @media (max-width: 900px) { .grid-2 { grid-template-columns: 1fr; } }
-  .onion { width: 100%; height: auto; display: block; }
-  .svg-lbl { fill: var(--dim); font-size: 11px; font-family: ui-sans-serif, system-ui, sans-serif; }
-  .svg-core { fill: var(--ink); font-size: 11px; font-weight: 700; font-family: ui-sans-serif, system-ui, sans-serif; }
-  .svg-cap { fill: var(--dim); font-size: 11px; font-family: ui-sans-serif, system-ui, sans-serif; }
-  .bar-row { display: grid; grid-template-columns: 10.5rem 1fr 2.2rem minmax(0, 1fr); gap: .55rem; align-items: center; padding: .28rem 0; border-bottom: 1px solid var(--line); }
-  .bar-name { font-weight: 600; font-size: .86rem; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
-  .bar-track { height: 8px; background: var(--line); border-radius: 99px; overflow: hidden; }
-  .bar-fill { height: 100%; background: linear-gradient(90deg, var(--accent), var(--violet)); border-radius: 99px; }
-  .bar-n { text-align: right; font-variant-numeric: tabular-nums; color: var(--dim); font-size: .85rem; }
-  .bar-ex { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
-  .dim { color: var(--dim); }
-  code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .84em; }
-  code.pat { font-size: .78em; color: var(--dim); }
-  table { width: 100%; border-collapse: collapse; }
-  .layers td, .layers th { text-align: left; padding: .65rem .55rem; border-bottom: 1px solid var(--line); vertical-align: top; }
-  .layers th { color: var(--dim); font-weight: 600; font-size: .72rem; text-transform: uppercase; letter-spacing: .05em; }
-  .ln { font-weight: 650; }
-  .num { font-variant-numeric: tabular-nums; font-weight: 650; }
-  .tags { margin-top: .3rem; display: flex; flex-wrap: wrap; gap: .25rem; }
-  .tag { display: inline-block; padding: .08em .45em; border: 1px solid var(--line); border-radius: 6px; font-size: .68rem; color: var(--dim); }
-  .tag.warn { border-color: color-mix(in srgb, var(--gold) 40%, var(--line)); color: var(--gold); }
-  .dim-tag { opacity: .75; }
-  .flow { display: flex; gap: .5rem; align-items: baseline; padding: .45rem 0; border-bottom: 1px solid var(--line); flex-wrap: wrap; }
-  .flow-name { font-weight: 650; min-width: 12rem; }
-  .flow-arrow { color: var(--dim); font-size: .8rem; }
-  .flow-targets { display: flex; flex-wrap: wrap; gap: .3rem; }
-  .chip { display: inline-block; padding: .12em .5em; border: 1px solid var(--line); border-radius: 6px; font-size: .76rem; color: var(--dim); background: var(--panel2); }
-  .chip.ok { color: var(--ink); border-color: color-mix(in srgb, var(--accent) 30%, var(--line)); }
-  details { margin-top: .85rem; }
-  summary { cursor: pointer; color: var(--accent); font-size: .9rem; }
-  /* Matrix must NOT inherit global table{width:100%} — that bloated the label column
-     and shoved every cell to the right. Keep it compact and left-aligned. */
-  .matrix-scroll {
-    overflow-x: auto; margin-top: .75rem; max-width: 100%;
-    text-align: left; -webkit-overflow-scrolling: touch;
-  }
-  .matrix {
-    width: max-content; max-width: none; border-collapse: collapse;
-    font-size: .8rem; margin: 0; table-layout: fixed;
-  }
-  .matrix th, .matrix td { border: 1px solid var(--line); }
-  .matrix td {
-    width: 2.05rem; min-width: 2.05rem; max-width: 2.05rem;
-    height: 2.05rem; text-align: center; font-weight: 700; padding: 0;
-  }
-  .matrix .rowlbl {
-    text-align: left; padding: 0 .75rem 0 .35rem; color: var(--dim);
-    font-weight: 600; white-space: nowrap; width: auto; min-width: 9.5rem;
-    max-width: none; position: sticky; left: 0; z-index: 1;
-    background: var(--panel); box-shadow: 4px 0 8px -4px rgba(0,0,0,.25);
-  }
-  .matrix thead th:first-child,
-  .matrix tr th.rowlbl { background: var(--panel); }
-  .matrix .corner {
-    position: sticky; left: 0; z-index: 2; background: var(--panel);
-    min-width: 9.5rem; box-shadow: 4px 0 8px -4px rgba(0,0,0,.25);
-  }
-  .matrix .rot {
-    height: 9.5rem; vertical-align: bottom; padding: .2rem .15rem;
-    width: 2.05rem; min-width: 2.05rem; max-width: 2.05rem;
-  }
-  .matrix .rot span {
-    writing-mode: vertical-rl; transform: rotate(180deg); color: var(--dim);
-    font-weight: 600; white-space: nowrap; display: inline-block; max-height: 9rem;
-    overflow: hidden; text-overflow: ellipsis;
-  }
-  .allow { color: var(--green); background: color-mix(in srgb, var(--green) 12%, transparent); }
-  .deny { color: var(--red); background: color-mix(in srgb, var(--red) 12%, transparent); }
-  .implicit { color: var(--dim); }
-  .self { color: var(--line); }
-  .legend { color: var(--dim); font-size: .8rem; margin: .55rem 0 0; }
-  .gates { display: grid; grid-template-columns: repeat(2, 1fr); gap: .65rem; }
-  @media (max-width: 700px) { .gates { grid-template-columns: 1fr; } }
-  .gate { display: flex; gap: .65rem; align-items: flex-start; padding: .75rem .8rem; border-radius: 12px; border: 1px solid var(--line); background: var(--panel2); }
-  .gate .dot { width: .65rem; height: .65rem; border-radius: 50%; margin-top: .35rem; background: var(--line); flex: 0 0 auto; }
-  .gate.on .dot { background: var(--green); box-shadow: 0 0 0 4px color-mix(in srgb, var(--green) 20%, transparent); }
-  .gate.off { opacity: .72; }
-  .gdesc { color: var(--dim); font-size: .85rem; margin: .1rem 0 .25rem; }
-  .vgroup { background: var(--panel2); border: 1px solid var(--line); border-left: 3px solid var(--red); border-radius: 10px; padding: .75rem .9rem; margin-bottom: .6rem; }
-  .vghead { display: flex; gap: .5rem; align-items: baseline; }
-  .rule { font-weight: 700; font-size: .8rem; color: var(--red); }
-  .vitems { list-style: none; padding: 0; margin: .4rem 0 0; }
-  .vitems li { padding: .35rem 0; border-top: 1px solid var(--line); }
-  .vitems li:first-child { border-top: none; }
-  .edge { color: var(--accent); font-weight: 650; margin-left: .35rem; }
-  .fix { margin-top: .4rem; color: var(--dim); font-size: .86rem; }
-  .clean, .hero-clean { background: var(--panel2); border: 1px solid var(--line); border-left: 3px solid var(--green); border-radius: 12px; padding: 1rem 1.1rem; }
-  .clean-title { font-weight: 750; color: var(--green); margin-bottom: .25rem; }
-  .clean-body { color: var(--dim); }
-  .cmds { display: grid; gap: .35rem; background: var(--panel2); border: 1px solid var(--line); border-radius: 12px; padding: .9rem 1rem; }
-  .cmds code { display: block; padding: .15rem 0; overflow-x: auto; }
-  footer { margin-top: 2.25rem; padding-top: 1rem; border-top: 1px solid var(--line); color: var(--dim); font-size: .8rem; }
-  .brand { display: inline-flex; align-items: center; gap: .4rem; color: var(--dim); font-size: .78rem; font-weight: 650; letter-spacing: .08em; text-transform: uppercase; margin-bottom: .55rem; }
-  .brand i { width: .55rem; height: .55rem; border-radius: 2px; background: linear-gradient(135deg, var(--accent), var(--violet)); display: inline-block; }
-  .senior h3 { margin-top: 1.25rem; }
-  .senior-list { margin: .2rem 0 0; padding-left: 1.1rem; color: var(--ink); }
-  .senior-list li { margin: .2rem 0; }
-  .senior-list .edge { margin-left: 0; }
-  .delta.up { color: var(--green); font-weight: 700; }
-  .delta.down { color: var(--red); font-weight: 700; }
-  .delta.flat { color: var(--dim); }
-  .evolve { border-color: color-mix(in srgb, var(--accent) 35%, var(--line)); }
-  @media print {
-    body { background: #fff; color: #111; padding: 0; }
-    .card, .kpi, .gate, .cmds, .clean, .vgroup { box-shadow: none; break-inside: avoid; }
-    details { open: true; }
-  }
-</style></head>
-<body><div class="wrap">
-  <div class="hero">
-    <div class="card">
-      <div class="brand"><i></i> Ark architecture report</div>
-      <h1>${esc(project)} <span class="badge ${status}">${status}</span> <span class="badge mode">${esc(modeLabel)}</span></h1>
-      <p class="lede">${esc(modeBlurb)} One machine-readable contract · write gate · CI · optional runtime.</p>
-      <div class="kpis">
-        <div class="kpi"><b>${esc(govLabel)}</b><span>Governed</span></div>
-        <div class="kpi"><b>${layers.length}</b><span>Layers</span></div>
-        <div class="kpi"><b>${gatesOn}/${enforcement.length}</b><span>Gates live</span></div>
-        <div class="kpi"><b>${violations.length}${suppressed ? ` · ${suppressed}Δ` : ''}</b><span>Violations${suppressed ? ' · frozen' : ''}</span></div>
-      </div>
-      <p class="meta">${meta}</p>
-      ${skillsNote}
-    </div>
-    <div class="card score-card">
-      <div class="score-ring ${scoreTone}"><div><div class="score-n">${score}</div><div class="dim" style="font-size:.72rem;letter-spacing:.08em;text-transform:uppercase">Ark score</div></div></div>
-      <p class="score-cap">${esc(scoreCaption)}</p>
-      <p class="meta" style="margin-top:.65rem">Coverage ${scoreCoverage} · Clean ${scoreClean} · Gates ${scoreGates} · Rules ${scoreRules}</p>
-    </div>
-  </div>
-
-  <div class="section card" id="adoption">
-    <h2>Adoption</h2>
-    <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
-      Co-pilot completeness — separate from the 0–100 fitness score above. Hosts, MCP health, origin snapshot, core optionality, baseline policy.
-    </p>
-    <div class="kpis" style="margin-bottom:.75rem">
-      <div class="kpi"><b>${adoptionView.gaps.length === 0 ? 'OK' : adoptionView.gaps.length}</b><span>${adoptionView.gaps.length === 0 ? 'No adoption gaps' : 'Adoption gap(s)'}</span></div>
-      <div class="kpi"><b>${adoptionView.originReport.present ? 'yes' : 'no'}</b><span>Origin report</span></div>
-      <div class="kpi"><b>${esc(adoptionView.baseline.signal)}</b><span>Baseline policy</span></div>
-      <div class="kpi"><b>${adoptionView.mcp.ok ? 'ok' : 'fix'}</b><span>Repo MCP argv</span></div>
-    </div>
-    ${
-      adoptionView.gaps.length
-        ? `<ul class="senior-list">${adoptionView.gaps
-            .map(
-              (g) =>
-                `<li><b>${esc(g.id)}</b> — ${esc(g.message)}${
-                  g.fix ? `<br/><code>${esc(g.fix)}</code>` : ''
-                }</li>`
-            )
-            .join('')}</ul>`
-        : '<p class="clean-body">No adoption gaps detected for hosts, MCP, core optionality, or origin.</p>'
-    }
-    ${
-      adoptionView.coreOptional.length
-        ? `<p class="dim" style="margin-top:.65rem">Optional-but-populated cores: <code>${adoptionView.coreOptional
-            .map((c) => `${esc(c.layer)} (${c.files})`)
-            .join('</code>, <code>')}</code></p>`
-        : ''
-    }
-    ${
-      adoptionView.hosts.length
-        ? `<p class="dim" style="margin-top:.4rem">Hosts: ${adoptionView.hosts
-            .map((h) => `${esc(h.host)}${h.complete ? ' ✓' : ' incomplete'}`)
-            .join(' · ')}</p>`
-        : ''
-    }
-  </div>
-
-  <div class="section grid-2">
-    <div class="card">
-      <h2>Architecture map</h2>
-      <p class="dim" style="margin:.15rem 0 0.75rem;font-size:.88rem">Outer rings = entrypoints & adapters. Center = purest core.</p>
-      ${onionSvg}
-    </div>
-    <div class="card">
-      <h2>Files per layer</h2>
-      <p class="dim" style="margin:.15rem 0 0.75rem;font-size:.88rem">${classifiedFiles} classified · ${totalFiles} in scope${coverage?.unclassified?.count ? ` · ${coverage.unclassified.count} unclassified` : ''}</p>
-      ${barRows || '<p class="dim">No layer file counts.</p>'}
-    </div>
-  </div>
-
-  <div class="section card">
-    <h2>Layers</h2>
-    <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">Innermost (most restricted) → outermost (entrypoints). Forbidden globals protect pure cores.</p>
-    <table class="layers">
-      <tr><th>Layer</th><th>Purpose</th><th>Files</th><th>Patterns</th><th>Example</th></tr>
-      ${layerRows || '<tr><td colspan="5" class="dim">No layers configured.</td></tr>'}
-    </table>
-  </div>
-
-  <div class="section card">
-    <h2>Dependency direction</h2>
-    <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">Inner layers stay ignorant of outer ones. Each row lists what it may import.</p>
-    ${flowRows || '<p class="dim">No layers configured.</p>'}
-    <details open>
-      <summary>Full matrix (precise ✓ / ✕ grid)</summary>
-      <div class="matrix-scroll"><table class="matrix">
-        <thead><tr><th class="corner"></th>${matrixHead}</tr></thead>
-        <tbody>${matrixBody}</tbody>
-      </table></div>
-      <p class="legend">Row imports column (left → top). ✓ allowed · ✕ denied · · = no explicit rule / self. Denied edges: ${deniedCount} · explicit allows: ${allowedCount} · purity-guarded layers: ${guarded}</p>
-    </details>
-  </div>
-
-  <div class="section card">
-    <h2>Violations</h2>
-    ${violationBlocks}
-  </div>
-
-  <div class="section card">
-    <h2>Enforcement points</h2>
-    <p class="dim" style="margin:.15rem 0 .85rem;font-size:.88rem">Write-time · merge-time · editor · ratchet. Same contract everywhere.</p>
-    <div class="gates">${enforcementRows}</div>
-  </div>
-
-  ${(() => {
-    if (!currentSnapshot) return '';
-    // First report: originSnapshot is null at render time (written to disk just after).
-    if (originJustCreated || !originSnapshot) {
-      return `<div class="section card evolve">
-        <h2>Origin baseline captured</h2>
-        <p class="dim" style="margin:.2rem 0 0;font-size:.9rem">
-          This is the <b>first</b> architecture snapshot for this project
-          (<code>.ark/reports/origin.json</code> + <code>origin.html</code>).
-          Future reports will show deltas against this starting point so you can prove evolution.
-        </p>
-      </div>`;
-    }
-    const rows = [
-      ['Ark score', originSnapshot.score, currentSnapshot.score, ''],
-      ['Governed %', originSnapshot.governedPercent, currentSnapshot.governedPercent, 'pp'],
-      ['Files in scope', originSnapshot.totalFiles, currentSnapshot.totalFiles, ''],
-      ['Classified files', originSnapshot.classifiedFiles, currentSnapshot.classifiedFiles, ''],
-      ['Active violations', originSnapshot.activeViolations, currentSnapshot.activeViolations, ''],
-      ['Value violations', originSnapshot.valueViolations, currentSnapshot.valueViolations, ''],
-      ['Type-only violations', originSnapshot.typeOnlyViolations, currentSnapshot.typeOnlyViolations, ''],
-      ['Layers', originSnapshot.layerCount, currentSnapshot.layerCount, ''],
-      ['Deny rules', originSnapshot.denyRules, currentSnapshot.denyRules, ''],
-      ['Gates live', originSnapshot.gatesOn, currentSnapshot.gatesOn, ''],
-    ];
-    const originDate = (originSnapshot.generatedAt || '').slice(0, 10) || 'origin';
-    const nowDate = (currentSnapshot.generatedAt || '').slice(0, 10) || 'now';
-    const tr = rows
-      .map(([label, from, to, unit]) => {
-        const d =
-          typeof from === 'number' && typeof to === 'number' ? to - from : null;
-        const good =
-          label.includes('violation') || label.includes('Violation')
-            ? d != null && d <= 0
-            : label.includes('Governed') || label.includes('score') || label.includes('Classified') || label.includes('Gates')
-              ? d != null && d >= 0
-              : null;
-        const cls =
-          d == null || d === 0 ? 'flat' : good === true ? 'up' : good === false ? 'down' : 'flat';
-        const delta =
-          d == null
-            ? '—'
-            : unit === 'pp'
-              ? formatDelta(Math.round(d * 10) / 10, { suffix: ' pp' })
-              : formatDelta(d);
-        return `<tr>
-          <td>${esc(label)}</td>
-          <td class="num">${from ?? '—'}</td>
-          <td class="num">${to ?? '—'}</td>
-          <td class="num delta ${cls}">${esc(delta)}</td>
-        </tr>`;
-      })
-      .join('\n');
-    // Layer file deltas
-    const originLayers = originSnapshot.layerFiles || {};
-    const currentLayers = currentSnapshot.layerFiles || {};
-    const layerKeys = [...new Set([...Object.keys(originLayers), ...Object.keys(currentLayers)])].sort();
-    const layerTr = layerKeys
-      .map((name) => {
-        const from = originLayers[name] || 0;
-        const to = currentLayers[name] || 0;
-        const d = to - from;
-        const cls = d === 0 ? 'flat' : d > 0 ? 'up' : 'down';
-        return `<tr>
-          <td class="ln">${esc(name)}</td>
-          <td class="num">${from}</td>
-          <td class="num">${to}</td>
-          <td class="num delta ${cls}">${esc(formatDelta(d))}</td>
-        </tr>`;
-      })
-      .join('\n');
-    return `<div class="section card evolve">
-      <h2>Evolution vs origin</h2>
-      <p class="dim" style="margin:.15rem 0 .75rem;font-size:.88rem">
-        Origin snapshot <code>${esc(originDate)}</code> → this report <code>${esc(nowDate)}</code>
-        · frozen at <code>.ark/reports/origin.*</code> · reopen origin HTML anytime for the starting picture.
-      </p>
-      <table class="layers">
-        <tr><th>Metric</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${tr}
-      </table>
-      <h3>Files per layer</h3>
-      <table class="layers">
-        <tr><th>Layer</th><th>Origin</th><th>Now</th><th>Δ</th></tr>
-        ${layerTr || '<tr><td colspan="4" class="dim">No layer file data in snapshots.</td></tr>'}
-      </table>
-      <p class="legend">Green Δ = improvement for that metric (↑ coverage/score/gates, ↓ violations). History JSON under <code>.ark/reports/history/</code> (last ${ARK_REPORT_HISTORY_MAX}).</p>
-    </div>`;
-  })()}
-
-  <div class="section card senior">
-    <h2>Senior diagnostics</h2>
-    <p class="dim" style="margin:.15rem 0 .85rem;font-size:.88rem">
-      Coupling, purity surface, contract density, and config forensics — for tech leads reviewing the fitness of the gate itself.
-    </p>
-
-    <h3>Contract density</h3>
-    <div class="kpis" style="margin-top:.35rem">
-      <div class="kpi"><b>${denyRatio}%</b><span>Edges denied</span></div>
-      <div class="kpi"><b>${deniedCount}</b><span>Deny rules</span></div>
-      <div class="kpi"><b>${allowedCount}</b><span>Explicit allows</span></div>
-      <div class="kpi"><b>${pairCount}</b><span>Directed pairs</span></div>
-    </div>
-    <p class="dim" style="margin:.55rem 0 0;font-size:.84rem">
-      Deny ratio = denied ÷ (layers × (layers−1)). High ratio = strict inward architecture.
-      Package manager detected: <code>${esc(packageManagerLabel)}</code>
-      · include roots: <code>${includeRoots.map(esc).join('</code>, <code>') || '—'}</code>
-      ${emptyLayers.length ? ` · empty layers: <code>${emptyLayers.map(esc).join(', ')}</code>` : ''}
-      ${layersWithoutRules.length ? ` · layers with no rule edge: <code>${layersWithoutRules.map(esc).join(', ')}</code>` : ''}
-      ${unclassifiedCount ? ` · unclassified files: <b>${unclassifiedCount}</b>` : ''}
-    </p>
-
-    <h3>Layer coupling (allowed import graph)</h3>
-    <p class="dim" style="margin:.1rem 0 .55rem;font-size:.84rem">
-      Fan-out = layers this layer may import · Fan-in = layers that may import it · based on non-denied edges (implicit allow counts as open).
-    </p>
-    <table class="layers">
-      <tr><th>Layer</th><th>Files</th><th>Fan-out</th><th>Fan-in</th><th>Deny-out</th><th>FO/files</th></tr>
-      ${couplingRows
-        .map(
-          (r) => `<tr>
-          <td class="ln">${esc(r.name)}</td>
-          <td class="num">${r.files}</td>
-          <td class="num">${r.fo}</td>
-          <td class="num">${r.fi}</td>
-          <td class="num">${r.denyOut}</td>
-          <td class="num">${r.density}</td>
-        </tr>`
-        )
-        .join('\n')}
-    </table>
-    <p class="legend">High fan-out on a large presentation layer is normal. High fan-out on a “domain” layer is a smell — the core is leaking outward privileges.</p>
-
-    <h3>Purity &amp; infrastructure surface</h3>
-    <div class="grid-2" style="margin-top:.5rem">
-      <div>
-        <div class="pill ${purityLayers.length ? 'good' : 'warn'}" style="margin-bottom:.55rem">
-          ${purityLayers.length} purity-guarded layer(s)
-        </div>
-        ${
-          purityLayers.length
-            ? `<ul class="senior-list">${purityLayers
-                .map(
-                  (l) =>
-                    `<li><b>${esc(l.name)}</b> forbids <code>${(l.forbiddenGlobals || []).map(esc).join('</code>, <code>')}</code></li>`
-                )
-                .join('')}</ul>`
-            : '<p class="dim">No <code>forbiddenGlobals</code> — ambient I/O can still leak into pure cores.</p>'
-        }
-      </div>
-      <div>
-        <div class="pill ${infraLayers.length ? 'good' : 'warn'}" style="margin-bottom:.55rem">
-          ${infraLayers.length} infra-capable layer(s)
-        </div>
-        ${
-          infraLayers.length
-            ? `<ul class="senior-list">${infraLayers
-                .map((l) => `<li><b>${esc(l.name)}</b> <span class="tag">mayImportInfrastructure</span></li>`)
-                .join('')}</ul>`
-            : '<p class="dim">No layer opts into infrastructure imports via <code>mayImportInfrastructure</code> (write-gate heuristic still applies to ungoverned targets).</p>'
-        }
-        ${
-          excludeLayers.length
-            ? `<p class="dim" style="margin-top:.65rem">Exclude globs (facade / kernel carve-outs):</p>
-               <ul class="senior-list">${excludeLayers
-                 .map(
-                   (l) =>
-                     `<li><b>${esc(l.name)}</b> · <code>${(l.exclude || []).map(esc).join('</code>, <code>')}</code></li>`
-                 )
-                 .join('')}</ul>`
-            : ''
-        }
-      </div>
-    </div>
-
-    <h3>Intent prefixes</h3>
-    ${
-      intentMap.length
-        ? `<table class="layers"><tr><th>Layer</th><th>Prefixes</th></tr>
-          ${intentMap
-            .map(
-              (row) =>
-                `<tr><td class="ln">${esc(row.name)}</td><td><code>${row.prefixes.map(esc).join('</code> <code>')}</code></td></tr>`
-            )
-            .join('\n')}</table>`
-        : '<p class="dim">No <code>intentPrefixes</code> on layers — runtime intent governance and string-intent checks have less to bind to.</p>'
-    }
-
-    <h3>Layer balance (educational)</h3>
-    ${
-      adoptionView.layerBalance
-        ? `<p class="dim" style="margin:.1rem 0 .55rem;font-size:.88rem">${esc(adoptionView.layerBalance.educational)}</p>
-           <p class="meta">PresentationAdapters ${adoptionView.layerBalance.presentationFiles} · DomainModel ${adoptionView.layerBalance.domainFiles} · total ${adoptionView.layerBalance.totalFiles}</p>`
-        : '<p class="dim" style="margin:.1rem 0 .55rem;font-size:.88rem">No presentation-heavy / thin-domain imbalance flagged (educational only when Presentation ≥50% and Domain &lt;10% of files).</p>'
+    if (low.get(v) === indices.get(v)) {
+      const comp = [];
+      let w;
+      do {
+        w = stack.pop();
+        onStack.delete(w);
+        comp.push(w);
+      } while (w !== v);
+      if (comp.length > 1) components.push(comp.sort());
     }
+  };
 
-    <h3>Pattern forensics</h3>
-    <div class="grid-2" style="margin-top:.45rem">
-      <div>
-        <p class="dim" style="margin:0 0 .4rem;font-size:.84rem">Broadest globs (watch for over-governance / false layer hits)</p>
-        ${
-          broadPatterns.length
-            ? `<ul class="senior-list">${broadPatterns
-                .slice(0, 8)
-                .map(
-                  (p) =>
-                    `<li><b>${esc(p.layer)}</b> · <code>${esc(p.pattern)}</code> <span class="dim">spec ${p.score}</span></li>`
-                )
-                .join('')}</ul>`
-            : '<p class="dim">No ultra-broad patterns detected.</p>'
-        }
-      </div>
-      <div>
-        <p class="dim" style="margin:0 0 .4rem;font-size:.84rem">Most precise patterns (file-level overlays, facades)</p>
-        ${
-          precisePatterns.length
-            ? `<ul class="senior-list">${precisePatterns
-                .slice(0, 8)
-                .map(
-                  (p) =>
-                    `<li><b>${esc(p.layer)}</b> · <code>${esc(p.pattern)}</code> <span class="dim">spec ${p.score}</span></li>`
-                )
-                .join('')}</ul>`
-            : '<p class="dim">No file-level patterns — only directory globs.</p>'
-        }
-      </div>
-    </div>
-
-    <h3>Debt &amp; violation taxonomy</h3>
-    <div class="kpis" style="margin-top:.35rem">
-      <div class="kpi"><b>${violations.length}</b><span>Active</span></div>
-      <div class="kpi"><b>${valueN}</b><span>Value edges</span></div>
-      <div class="kpi"><b>${typeOnlyN}</b><span>Type-only</span></div>
-      <div class="kpi"><b>${suppressed || baselineKeys}</b><span>Baseline keys</span></div>
-    </div>
-    ${
-      topEdges.length
-        ? `<p class="dim" style="margin:.55rem 0 .35rem;font-size:.84rem">Hottest active edges</p>
-           <ul class="senior-list">${topEdges
-             .map(([edge, n]) => `<li><span class="edge">${esc(edge)}</span> · <b>${n}</b></li>`)
-             .join('')}</ul>`
-        : '<p class="dim" style="margin-top:.55rem">No active edge concentration — either clean or all debt is baselined.</p>'
-    }
+  for (const v of [...graph.keys()].sort()) {
+    if (!indices.has(v)) strongconnect(v);
+  }
 
-    <details style="margin-top:1rem">
-      <summary>Score model (transparent)</summary>
-      <p class="legend">
-        Ark score = 0.4×coverage + 0.3×clean + 0.2×gates + 0.1×rule-density.
-        Coverage=${scoreCoverage}, clean=${scoreClean}, gates=${scoreGates}, rules=${scoreRules} → <b>${score}</b>.
-        This is a fitness signal for humans, not a CI gate.
-      </p>
-    </details>
-  </div>
-
-  <div class="section card">
-    <h2>Commands worth memorizing</h2>
-    <div class="cmds">
-      <code>${arkCheckCommand(root)}</code>
-      <code>${arkCommand(root, 'ark-check', '--coverage')}</code>
-      <code>${arkCommand(root, 'ark-check', '--plan')}</code>
-      <code>${arkCommand(root, 'ark-check', '--doctor')}</code>
-      <code>${arkCommand(root, 'ark-check', '--report ark-report.html')}</code>
-      <code>/ark-place "&lt;what you're building&gt;"</code>
-      <code>/ark-explain</code>
-    </div>
-  </div>
-
-  <footer>
-    Generated by ${meta || 'ark-check'} · visual twin of <code>/ark-explain</code>.
-    Regenerate with <code>ark-check --report</code>; add the file to <code>.gitignore</code> rather than committing it.
-  </footer>
-</div></body></html>
-`;
+  return components
+    .sort((a, b) => a[0].localeCompare(b[0]))
+    .map((members) => ({
+      ruleId: 'CIRCULAR_DEPENDENCY',
+      file: members[0],
+      line: 1,
+      target: members.join(' → '),
+      message: `Circular dependency among ${members.length} files: ${members.join(' → ')} → ${members[0]}.`,
+      // Graph is value/runtime edges only (type-only imports omitted).
+      cycleKind: 'value',
+    }));
 }
 
+
 function moduleSpecifierFromCall(ts, node) {
   if (!ts.isCallExpression(node)) return undefined;
 
@@ -4692,463 +1624,13 @@ function moduleSpecifierFromCall(ts, node) {
 // Pure coverage computation (glob-only, no TypeScript): the object both `--coverage` and
 // `--doctor` render. `governed` is the headline honesty number — the share of in-scope code
 // Ark actually enforces rules on; `suggestions` proposes a layer for each ungoverned dir.
-function computeCoverage(root, config, files, rules) {
-  const layers = config.layers ?? [];
-  const counts = new Map(layers.map((layer) => [layer.name, 0]));
-  const unclassified = [];
-  for (const file of files) {
-    const layer = layerForFile(root, file, layers);
-    if (layer && counts.has(layer)) counts.set(layer, counts.get(layer) + 1);
-    else unclassified.push(normalize(path.relative(root, file)));
-  }
-  unclassified.sort();
-  const layerRows = layers.map((layer) => ({
-    name: layer.name,
-    patterns: layer.patterns ?? [],
-    files: counts.get(layer.name) ?? 0,
-  }));
-  // A layer whose patterns match zero files is dead config — it enforces nothing, usually a
-  // wrong glob (the #1 monorepo mistake). A layer with no rule edge can import anything.
-  const emptyLayers = layerRows.filter((row) => row.files === 0).map((row) => row.name);
-  const layersWithoutRules = layerRows
-    .map((row) => row.name)
-    .filter((name) => !rules.some((rule) => rule.from === name || rule.to === name));
-  const classifiedFiles = files.length - unclassified.length;
-  // Empty scope is NOT "100% governed" — that was a false-green for monorepos/mis-includes
-  // (0/0 → ENFORCE). Zero files means the contract is not checking anything yet.
-  const fraction = files.length > 0 ? classifiedFiles / files.length : 0;
-  return {
-    include: config.include ?? [],
-    totalFiles: files.length,
-    emptyScope: files.length === 0,
-    governed: { classifiedFiles, totalFiles: files.length, percent: Math.round(fraction * 100) },
-    layers: layerRows,
-    unclassified: { count: unclassified.length, files: unclassified },
-    suggestions: buildUnclassifiedSuggestions(unclassified),
-    emptyLayers,
-    layersWithoutRules,
-  };
-}
-
-function runCoverage(root, config, files, rules, asJson) {
-  const cov = computeCoverage(root, config, files, rules);
-  if (asJson) {
-    console.log(JSON.stringify({ ok: true, coverage: cov }, null, 2));
-    return;
-  }
-  const { governed, layers: layerRows, suggestions, layersWithoutRules } = cov;
-  const classifiedFiles = governed.classifiedFiles;
-  const unclassified = cov.unclassified.files;
-
-  const nameWidth = Math.max(
-    'Layer'.length,
-    '(unclassified)'.length,
-    ...layerRows.map((row) => row.name.length)
-  );
-  const pad = (value) => value.padEnd(nameWidth);
-  console.log(`Ark coverage (include: ${(config.include ?? []).join(', ') || '.'}):`);
-  console.log('');
-  console.log(`  ${pad('Layer')}  Files`);
-  for (const row of layerRows) {
-    const flag = row.files === 0 ? '   (pattern matches nothing)' : '';
-    console.log(`  ${pad(row.name)}  ${String(row.files).padStart(5)}${flag}`);
-  }
-  console.log(`  ${pad('(unclassified)')}  ${String(unclassified.length).padStart(5)}`);
-  console.log('');
-  console.log(
-    `${files.length} source file(s) in scope; ${unclassified.length} not matched by any layer.`
-  );
-  console.log(`Governed: ${governed.percent}% (${classifiedFiles}/${files.length} files).`);
-  if (files.length > 0 && governed.percent < 50) {
-    console.log('');
-    console.log(
-      `⚠ Ark governs a MINORITY of your code (${governed.percent}%). A green check here does NOT`
-    );
-    console.log('  mean the codebase is checked — the rest is ungoverned. Classify the directories');
-    console.log('  below to actually cover it.');
-  }
-  if (suggestions.length > 0) {
-    console.log('');
-    console.log('Ungoverned directories (proposed layer — from the 11-layer profile + presets):');
-    for (const s of suggestions) {
-      const count = `(${s.files})`.padStart(6);
-      if (s.unrecognized) {
-        console.log(`  ${count}  ${s.dir}/  — unrecognized, you classify`);
-      } else {
-        const alt = s.alternatives ? ` (or ${s.alternatives.join(' / ')})` : '';
-        console.log(`  ${count}  ${s.dir}/  → ${s.layer}${alt}`);
-      }
-    }
-    console.log('');
-    console.log('Apply these via /ark-contract (adds the layer patterns to ark.config.json).');
-  }
-  if (layersWithoutRules.length > 0) {
-    console.log('');
-    console.log(`Layers with no rule edge (can import anything): ${layersWithoutRules.join(', ')}`);
-  }
-}
-
-// --doctor: one consolidated health view — coverage, violations, gates, skills, baseline,
-// and command runners — each with the exact command to fix it. Folds the data the other
-// modes already produce so a team sees "what state is my Ark adoption in?" at a glance.
-// Co-pilot Phase F — turn active violations into a classified, ordered remediation PLAN with an
-// embedded GOAL. This is the `plan` primitive the future apply-loop (Phase H, `loop`) consumes
-// and the autopilot (Phase I) drives toward the `goal`. Read-only: it changes no files.
-function buildRemediationPlan(root, activeViolations, governedPercent = null, totalFiles = null) {
-  // A plan with 0 violations but ~0% governed (or ZERO files in scope) is a FALSE green:
-  // nothing is actually being checked. Treat as "not done — classify / fix include first."
-  const governedLow = governedPercent != null && governedPercent < 50;
-  const emptyScope = totalFiles === 0;
-  const notHonestlyEnforced = governedLow || emptyScope;
-  const steps = activeViolations.map((v, index) => {
-    const verdict = classifyRemediation(v);
-    return {
-      id: `${v.ruleId}:${v.file}:${v.line ?? 0}:${index}`,
-      class: verdict.class,
-      confidence: verdict.confidence,
-      rationale: verdict.rationale,
-      ruleId: v.ruleId,
-      edge: violationEdge(v),
-      file: v.file,
-      ...(v.line ? { line: v.line } : {}),
-      ...(v.target ? { target: v.target } : {}),
-      ...(v.typeOnly ? { typeOnly: true } : {}),
-      ...(v.targetTypeOnlyExports ? { targetTypeOnlyExports: true } : {}),
-      ...(v.sourcePureTypeModule ? { sourcePureTypeModule: true } : {}),
-      ...(verdict.remediationKind ? { remediationKind: verdict.remediationKind } : {}),
-    };
-  });
-  // Order: auto-applicable first (quick, safe wins), then human decisions, then deferred.
-  const rank = { 'mechanical-safe': 0, judgment: 1, deferred: 2 };
-  steps.sort((a, b) => rank[a.class] - rank[b.class]);
-  const countOf = (cls) => steps.filter((s) => s.class === cls).length;
-  const counts = {
-    mechanicalSafe: countOf('mechanical-safe'),
-    judgment: countOf('judgment'),
-    deferred: countOf('deferred'),
-  };
-  return {
-    version: '1',
-    goal: {
-      statement:
-        activeViolations.length > 0
-          ? `Resolve ${activeViolations.length} architecture violation(s) without weakening the contract.`
-          : emptyScope
-            ? 'No source files matched the contract include paths — this "clean" result checks nothing. Fix include/layers (monorepo → apps/packages, or /ark-adopt) so Ark has real code to govern.'
-            : governedLow
-              ? `No violations — but Ark governs only ${governedPercent}% of your code, so this "clean" result checks almost nothing. Classify the rest (ark-check --coverage, then /ark-adopt) so it's actually enforced.`
-              : 'No active violations — the architecture already meets its contract.',
-      // The loop's termination signal (Phase H): nothing left to remediate AND the contract
-      // actually governs real code. Empty scope or low coverage is not "met".
-      met: activeViolations.length === 0 && !notHonestlyEnforced,
-      ...(governedPercent != null ? { governedPercent } : {}),
-      ...(totalFiles != null ? { totalFiles } : {}),
-      ...(emptyScope ? { emptyScope: true } : {}),
-      activeViolations: activeViolations.length,
-      autoApplicable: counts.mechanicalSafe,
-      needsDecision: counts.judgment,
-      deferred: counts.deferred,
-    },
-    counts,
-    steps,
-  };
-}
-
-// `--plan`: print the classified remediation plan. Dual-focus output — a one-line headline
-// anyone can read, then the per-step detail a developer acts on. Read-only.
-function runPlan(root, activeViolations, asJson, governedPercent = null, totalFiles = null) {
-  const plan = buildRemediationPlan(root, activeViolations, governedPercent, totalFiles);
-  // Honesty: a zero-violation plan with almost nothing governed is NOT "ok".
-  const planOk = plan.goal.met === true;
-  if (asJson) {
-    console.log(JSON.stringify({ ok: planOk, plan }, null, 2));
-    return plan;
-  }
-  console.log(color.bold(`Ark plan — ${path.basename(path.resolve(root)) || '.'}`));
-  console.log('');
-  console.log(plan.goal.statement);
-  if (governedPercent != null) {
-    const pctLabel =
-      governedPercent < 50
-        ? color.yellow(`Governed: ${governedPercent}% of in-scope files`)
-        : color.dim(`Governed: ${governedPercent}% of in-scope files`);
-    console.log(pctLabel);
-  }
-  if (activeViolations.length === 0) return plan;
-  console.log('');
-  console.log(
-    `  ${color.green(`${plan.counts.mechanicalSafe} safe to auto-apply`)} · ` +
-      `${color.yellow(`${plan.counts.judgment} need your decision`)} · ` +
-      `${color.dim(`${plan.counts.deferred} deferred`)}`
-  );
-  console.log('');
-  const tag = {
-    'mechanical-safe': color.green('auto  '),
-    judgment: color.yellow('decide'),
-    deferred: color.dim('defer '),
-  };
-  for (const step of plan.steps) {
-    const where = `${step.file}${step.line ? `:${step.line}` : ''}`;
-    console.log(`  [${tag[step.class]}] ${step.edge}  ${color.dim(where)}`);
-    console.log(color.dim(`           ${step.rationale}`));
-  }
-  console.log('');
-  console.log(
-    color.dim(
-      'Plan only — no files changed. "auto" = an agent can safely apply it; "decide" = your call.'
-    )
-  );
-  return plan;
-}
-
-function runDoctor(root, config, files, rules, violations, asJson, options = {}) {
-  const cov = computeCoverage(root, config, files, rules);
-  const summary = summarizeViolations(violations);
-  const configPath = options.configPath ?? path.join(root, 'ark.config.json');
-  const configMissing = options.configMissing ?? !fs.existsSync(configPath);
-  const showNewHere = shouldShowNewHereNudge(root, configPath, cov.governed.percent, configMissing);
-  let recommendation;
-  if (showNewHere) {
-    try {
-      recommendation = buildArchitectureRecommendation(root);
-    } catch {
-      recommendation = undefined;
-    }
-  }
-  const gatesMissing = missingGates(root);
-  const skillGaps = detectSkillGaps(root);
-  const staleRunners = staleRunnerGateFiles(root);
-  const adoption = collectAdoptionGaps(root, config, cov);
-  const baseline = readBaseline(root, '.ark-baseline.json');
-  const currentKeys = new Set(violations.map(baselineKey));
-  const suppressed = baseline.exists
-    ? violations.filter((v) => baseline.keys.has(baselineKey(v))).length
-    : 0;
-  const staleBaseline = baseline.exists
-    ? [...baseline.keys].filter((key) => !currentKeys.has(key)).length
-    : 0;
-  const activeCount = violations.length - suppressed;
-  const missingSkills = skillGaps.reduce((sum, gap) => sum + gap.missing, 0);
-  const staleSkills = skillGaps.reduce((sum, gap) => sum + gap.stale, 0);
-
-  if (asJson) {
-    console.log(
-      JSON.stringify(
-        {
-          ok: true,
-          doctor: {
-            operatingMode: resolveOperatingMode({
-              governedPercent: cov.governed.percent,
-              planMet: activeCount === 0 && cov.governed.percent >= 50,
-              mature: cov.governed.totalFiles >= 150,
-            }),
-            governed: cov.governed,
-            emptyLayers: cov.emptyLayers,
-            layersWithoutRules: cov.layersWithoutRules,
-            ungovernedDirs: cov.suggestions.length,
-            violations: {
-              total: violations.length,
-              active: activeCount,
-              suppressed,
-              value: summary.valueCount,
-              typeOnly: summary.typeOnlyCount,
-              concentrated: summary.concentrated,
-              dominant: summary.dominant,
-              topEdges: summary.edges.slice(0, 5),
-            },
-            baseline: {
-              exists: baseline.exists,
-              frozen: baseline.exists ? baseline.keys.size : 0,
-              stale: staleBaseline,
-              policy: adoption.baseline,
-            },
-            gatesMissing,
-            skillGaps,
-            staleRunnerFiles: staleRunners,
-            adoption,
-            newHere: showNewHere
-              ? {
-                  show: true,
-                  archetype: recommendation?.archetype,
-                  label: recommendation?.label,
-                  preset: recommendation?.preset,
-                  recommendCommand: arkCommand(root, 'ark-check', '--recommend'),
-                  initCommand: recommendation?.archetype
-                    ? arkCommand(root, 'ark', `init --archetype ${recommendation.archetype} --yes`)
-                    : undefined,
-                }
-              : { show: false },
-          },
-        },
-        null,
-        2
-      )
-    );
-    return;
-  }
-
-  const ok = color.green('✓');
-  const warn = color.yellow('!');
-  const bad = color.red('✗');
-  const actions = [];
-  const line = (mark, text) => console.log(`  ${mark} ${text}`);
-
-  console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
-
-  const emptyScope = cov.governed.totalFiles === 0;
-  const mode = resolveOperatingMode({
-    governedPercent: emptyScope ? 0 : cov.governed.percent,
-    planMet:
-      activeCount === 0 && !emptyScope && cov.governed.percent >= 50,
-    mature: cov.governed.totalFiles >= 150,
-  });
-  console.log('');
-  console.log(color.bold('Operating mode'));
-  const modeMark = mode === 'enforce' ? ok : mode === 'adapt' ? warn : warn;
-  const modeHelp = {
-    suggest: 'starter shape / thin tree — expand layers as you grow',
-    adapt: 'contract still needs to match real layout or raise coverage',
-    enforce: 'contract governs enough code; gates can honestly hold the line',
-  };
-  line(modeMark, `${mode.toUpperCase()} — ${modeHelp[mode]}`);
-  if (emptyScope) {
-    line(
-      bad,
-      'Empty scope: include paths match 0 source files — a green check is meaningless until include/layers match the tree (monorepo → apps/packages, or /ark-adopt).'
-    );
-  }
-
-  console.log('');
-  console.log(color.bold('Coverage'));
-  const govMark =
-    emptyScope || cov.governed.percent < 50
-      ? bad
-      : cov.governed.percent >= 80
-        ? ok
-        : warn;
-  line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
-  if (cov.suggestions.length > 0) {
-    line(warn, `${cov.suggestions.length} ungoverned director(y/ies) — proposals: ${arkCommand(root, 'ark-check', '--coverage')}`);
-    actions.push('classify the ungoverned directories (/ark-contract)');
-  }
-  if (cov.emptyLayers.length > 0) line(warn, `Empty layers (pattern matches nothing): ${cov.emptyLayers.join(', ')}`);
-  if (cov.layersWithoutRules.length > 0) line(warn, `Layers with no rule edge: ${cov.layersWithoutRules.join(', ')}`);
-  if (cov.suggestions.length === 0 && cov.emptyLayers.length === 0) line(ok, 'Every layer classifies files; no empty layers');
-
-  if (showNewHere) {
-    console.log('');
-    console.log(color.bold('New here?'));
-    if (recommendation) {
-      line(warn, `Suggested application shape: ${recommendation.archetype} — ${recommendation.label} (preset ${recommendation.preset})`);
-    } else {
-      line(warn, 'Low governed coverage or fresh config — pick an application shape before adding code.');
-    }
-    line(ok, `See the plan: ${arkCommand(root, 'ark-check', '--recommend')}`);
-    if (recommendation?.archetype) {
-      line(ok, `Quick setup: ${arkCommand(root, 'ark', `init --archetype ${recommendation.archetype} --yes`)}`);
-    }
-    actions.unshift('run ark-check --recommend or /ark-architect to choose your application shape');
-  }
-
-  console.log('');
-  console.log(color.bold('Violations'));
-  if (violations.length === 0) {
-    line(ok, 'None — the code matches the contract');
-  } else {
-    const typeNote = summary.typeOnlyCount > 0 ? ` (${summary.valueCount} value · ${summary.typeOnlyCount} type-only)` : '';
-    const supNote = suppressed > 0 ? `, ${suppressed} frozen` : '';
-    line(
-      activeCount > 0 ? warn : ok,
-      `${violations.length} total${typeNote}${supNote}${activeCount > 0 ? ` — ${activeCount} NOT baselined` : ''}`
-    );
-    for (const edge of summary.edges.slice(0, 3)) line(' ', color.dim(`${edge.count}  ${edge.edge}`));
-    if (summary.concentrated) {
-      line(warn, color.dim(`${Math.round(summary.dominantShare * 100)}% on one edge (${summary.dominant}) — likely a contract fix, not debt`));
-    }
-    if (activeCount > 0) {
-      actions.push(
-        `resolve the non-baselined violations — see the classified plan (${arkCommand(root, 'ark-check', '--plan')}), then /ark-fix`
-      );
-    }
-  }
-
-  console.log('');
-  console.log(color.bold('Gates & skills'));
-  if (gatesMissing.length === 0) line(ok, 'Gate files present (AGENTS.md, .mcp.json, CI, write gate)');
-  else {
-    line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
-    actions.push(`install gates (${arkCommand(root, 'ark-check', '--install-agent-gates')})`);
-  }
-  if (missingSkills + staleSkills === 0) line(ok, '/ark-* skills current for detected tools');
-  else {
-    line(warn, `${missingSkills} missing / ${staleSkills} outdated /ark-* skill(s) for ${skillGaps.map((g) => g.tool).join(', ')}`);
-    actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
-  }
-
-  console.log('');
-  console.log(color.bold('Baseline'));
-  if (!baseline.exists) {
-    line(violations.length > 0 ? warn : ok, violations.length > 0 ? 'No baseline — adopting a dirty repo? freeze with --update-baseline' : 'No baseline (nothing to freeze)');
-  } else {
-    // Baseline keys are line-agnostic, so N keys can suppress ≥N violations — label as keys
-    // to avoid an apparent mismatch with the "frozen" violation count above.
-    line(ok, `${baseline.keys.size} frozen key(s)`);
-    if (staleBaseline > 0) {
-      line(warn, `${staleBaseline} stale entr(y/ies) no longer occur — tighten with --update-baseline`);
-      actions.push('tighten the baseline (--update-baseline)');
-    }
-  }
-
-  console.log('');
-  console.log(color.bold('Command runners'));
-  if (staleRunners.length === 0) line(ok, 'Emitted commands match the package manager');
-  else {
-    line(warn, `Stale runner in ${staleRunners.join(', ')}`);
-    actions.push(`migrate command runners (${arkCommand(root, 'ark-check', '--install-agent-gates --migrate-commands')})`);
-  }
-
-  // Adoption completeness (hosts, MCP health, codex home, core optionality, origin, baseline policy)
-  console.log('');
-  console.log(color.bold('Adoption (separate from fitness score)'));
-  if (adoption.gaps.length === 0 && !adoption.layerBalance) {
-    line(ok, 'Hosts, MCP argv, core optionality, origin report, and baseline policy look complete');
-  } else {
-    for (const gap of adoption.gaps) {
-      const mark = gap.severity === 'warn' ? warn : gap.severity === 'info' ? warn : bad;
-      line(mark, gap.message);
-      if (gap.fix) line(' ', color.dim(`Fix: ${gap.fix}`));
-      actions.push(gap.fix || gap.message);
-    }
-    if (adoption.layerBalance) {
-      line(warn, color.dim(adoption.layerBalance.educational));
-    }
-  }
-  if (adoption.baseline) {
-    line(
-      ' ',
-      color.dim(
-        `Baseline policy: ${adoption.baseline.signal}` +
-          (adoption.baseline.primaryPathUsesBaseline
-            ? ' · primary path uses --baseline'
-            : ' · primary path does not use --baseline')
-      )
-    );
-  }
-  if (adoption.originReport.present) {
-    line(ok, 'Origin architecture snapshot present (.ark/reports/origin.json)');
-  }
-
-  console.log('');
-  if (actions.length === 0) {
-    console.log(color.green('✔ Healthy — nothing to do.'));
-  } else {
-    console.log(color.bold(`Top actions (${actions.length}):`));
-    actions.forEach((action, index) => console.log(`  ${index + 1}. ${action}`));
-  }
-}
 
 async function main() {
   const args = parseArgs(process.argv);
+  if (args.version) {
+    console.log(arkPackageVersion());
+    process.exit(0);
+  }
   if (args.help) {
     console.log(usage());
     return;
@@ -5181,6 +1663,16 @@ async function main() {
     return;
   }
 
+  if (args.suggestInclude) {
+    runSuggestInclude(args);
+    return;
+  }
+
+  if (args.adoptContract) {
+    runAdoptContract(args);
+    return;
+  }
+
   if (args.recommend) {
     try {
       const recommendation = buildArchitectureRecommendation(args.root);
@@ -5254,7 +1746,7 @@ async function main() {
   const config = readConfig(root, args.config);
   const manifest = readManifest(root, args.manifest);
   const rules = manifest?.architecture?.rules ?? config.rules;
-  const files = config.include.flatMap((entry) => walk(path.join(root, entry)));
+  const files = collectGovernedFiles(root, config);
 
   // --coverage is a pure glob/report view (no TypeScript resolver), so serve it BEFORE the
   // TS import: the report must work — and exit 0 — even when typescript isn't installed.
@@ -5461,7 +1953,11 @@ async function main() {
       const targetLayer = target ? layerForFile(root, target, config.layers) : undefined;
       if (target && targetLayer) {
         const relTarget = normalize(path.relative(root, target));
-        if (relTarget !== relFile) importGraph.get(relFile).add(relTarget);
+        // Cycle graph is runtime coupling only. Type-only imports are erased by TS and
+        // must not form CIRCULAR_DEPENDENCY (e.g. codegen `import type` back-edges).
+        if (relTarget !== relFile && !edge.typeOnly) {
+          importGraph.get(relFile).add(relTarget);
+        }
       }
       const rule = targetLayer ? isBlocked(rules, sourceLayer, targetLayer) : undefined;
       if (rule) {
@@ -5495,7 +1991,26 @@ async function main() {
 
   if (cacheKey) saveScanCache(root, cacheKey, nextCacheFiles);
 
-  violations.push(...detectCycles(importGraph));
+  // cyclePolicy: strict (default) | soft (advisory only, never fails --strict-config) | off
+  const cyclePolicy = String(config.cyclePolicy || 'strict').toLowerCase();
+  if (cyclePolicy !== 'off') {
+    const cycles = detectCycles(importGraph);
+    if (cyclePolicy === 'soft' || cyclePolicy === 'framework-soft') {
+      for (const c of cycles) {
+        // failsStrict: false — soft cycles must NOT trip --strict-config / check:architecture.
+        // Only CONFIG_* (and similar) warnings fail under --strict-config.
+        warnings.push({
+          ruleId: 'CIRCULAR_DEPENDENCY',
+          message: `${c.message} (soft cycle policy — advisory only; set cyclePolicy: "strict" to fail the check)`,
+          file: c.file,
+          target: c.target,
+          failsStrict: false,
+        });
+      }
+    } else {
+      violations.push(...cycles);
+    }
+  }
 
   if (args.doctor) {
     runDoctor(root, config, files, rules, violations, args.json, {
@@ -5520,6 +2035,24 @@ async function main() {
       process.exitCode = 2;
       return;
     }
+    const baselineName = args.baseline || '.ark-baseline.json';
+    const fullBaselinePath = path.isAbsolute(baselineName)
+      ? baselineName
+      : path.join(root, baselineName);
+    // Zero debt: do not leave an empty baseline file (unclear policy — "is ratchet on?").
+    // Delete any existing empty/orphan baseline so doctor/CI stay honest.
+    if (violations.length === 0) {
+      if (fs.existsSync(fullBaselinePath)) {
+        fs.unlinkSync(fullBaselinePath);
+        console.log(
+          `No violations to freeze — removed empty baseline ${fullBaselinePath} (zero debt; no ratchet file needed).`
+        );
+      } else {
+        console.log('No violations to freeze — baseline not written (zero debt).');
+      }
+      console.log('Gate with: ark-check --root . --config ark.config.json --strict-config');
+      return;
+    }
     const { fullPath, count } = writeBaseline(root, args.baseline, violations);
     console.log(`Wrote ${fullPath} with ${count} frozen violation key(s).`);
     console.log('Commit it and gate CI with: ark-check --baseline (only NEW violations fail).');
@@ -5549,7 +2082,10 @@ async function main() {
     }
   }
 
-  const ok = activeViolations.length === 0 && (!args.strictConfig || warnings.length === 0);
+  // Soft/advisory warnings (failsStrict === false) never fail --strict-config.
+  const strictWarnings = warnings.filter((w) => w.failsStrict !== false);
+  const ok =
+    activeViolations.length === 0 && (!args.strictConfig || strictWarnings.length === 0);
 
   if (args.plan) {
     const cov = computeCoverage(root, config, files, rules);
@@ -5627,11 +2163,10 @@ async function main() {
       noArchive: Boolean(args.noArchive),
     });
     if (!args.json) {
-      const rel = path.relative(root, reportPath) || reportPath;
-      console.log(`${color.green('✎')} Wrote HTML report: ${rel}`);
+      console.log(`${color.green('✎')} Wrote HTML report: ${displayPathFromRoot(root, reportPath)}`);
       if (archive.createdOrigin) {
         console.log(
-          `${color.green('✎')} Origin snapshot saved (first report): ${path.relative(root, archive.originJson) || archive.originJson}`
+          `${color.green('✎')} Origin snapshot saved (first report): ${displayPathFromRoot(root, archive.originJson)}`
         );
         console.log(
           color.dim('  Future reports will show evolution vs this starting point (.ark/reports/).')
@@ -5696,11 +2231,16 @@ async function main() {
       );
     }
     if (activeViolations.length === 0) {
+      const advisoryOnly = warnings.length > 0 && strictWarnings.length === 0;
       if (warnings.length === 0) {
         console.log(`${color.green('✔')} Ark check passed.${baselineNote}`);
-      } else if (args.strictConfig) {
+      } else if (args.strictConfig && strictWarnings.length > 0) {
         console.error(
-          `${color.red('✖')} Ark check failed with ${warnings.length} config warning(s).${baselineNote}`
+          `${color.red('✖')} Ark check failed with ${strictWarnings.length} config warning(s).${baselineNote}`
+        );
+      } else if (advisoryOnly) {
+        console.log(
+          `${color.green('✔')} Ark check passed with ${warnings.length} advisory warning(s).${baselineNote}`
         );
       } else {
         console.log(