arkgate 2.6.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,
@@ -168,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;
@@ -213,8 +220,10 @@ function usage() {
     '       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)',
@@ -249,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"] }',
@@ -306,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 } : {}),
   };
 }
 
@@ -362,39 +375,8 @@ 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
@@ -455,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) {
@@ -553,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;
   }
@@ -577,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
@@ -597,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) {
@@ -625,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.
@@ -635,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,
@@ -646,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(', ')}`);
     }
@@ -787,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('/');
 }
@@ -903,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 }
           )
         );
       }
@@ -1442,6 +1594,8 @@ function detectCycles(graph) {
       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',
     }));
 }
 
@@ -1509,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);
@@ -1582,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.
@@ -1789,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) {
@@ -1823,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, {
@@ -1848,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).');
@@ -1877,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);
@@ -2023,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(

package/bin/ark-layer-match.mjs

@@ -166,3 +166,32 @@ export function isEdgeDenied(rules, from, to) {
   const hit = (rules ?? []).find((r) => r.from === from && r.to === to);
   return hit?.allowed === false;
 }
+
+/**
+ * Codegen / generated source globs skipped by the default scan.
+ * Universal (TanStack Router routeTree.gen, many `*.generated.ts` tools, etc.).
+ * Opt out with `excludeGenerated: false` in ark.config.json; add more via top-level `exclude`.
+ */
+export const DEFAULT_GENERATED_FILE_GLOBS = [
+  '**/*.gen.ts',
+  '**/*.gen.tsx',
+  '**/*.generated.ts',
+  '**/*.generated.tsx',
+];
+
+/**
+ * Globs that remove files from ark-check scan (cycles, layers, coverage).
+ * @param {{ exclude?: string[], excludeGenerated?: boolean } | null | undefined} config
+ */
+export function scanExcludePatterns(config) {
+  const custom = Array.isArray(config?.exclude) ? config.exclude.filter((p) => typeof p === 'string') : [];
+  const generated =
+    config?.excludeGenerated === false ? [] : DEFAULT_GENERATED_FILE_GLOBS;
+  return [...generated, ...custom];
+}
+
+/** Relative path (posix) matches any scan-exclude glob. */
+export function isScanExcludedRelative(relPath, config) {
+  const rel = String(relPath).split(path.sep).join('/');
+  return scanExcludePatterns(config).some((pattern) => globToRegExp(pattern).test(rel));
+}

package/bin/ark-mcp.mjs

@@ -41,6 +41,9 @@ import {
   arkCommand,
   layerForFile,
   shouldShowNewHereNudge,
+  detectWorkspaces,
+  detectTsPackageRoots,
+  resolveIncludeRoots,
 } from './ark-shared.mjs';
 
 const arkCheckBin = fileURLToPath(new URL('./ark-check.mjs', import.meta.url));
@@ -576,9 +579,9 @@ async function main() {
     {
       name: 'ark_place',
       description:
-        'Given a target file path, return which layer it belongs to, which layers it may and ' +
-        'must NOT import, and its forbidden globals — so generated code lands in a governed ' +
-        'location with the right dependencies. Call this BEFORE writing a new file.',
+        'Place a file in the architecture: pass filePath (preferred) and/or description. ' +
+        'Returns layer, mayImport / mustNotImport, forbiddenGlobals. Call BEFORE writing a new file. ' +
+        'If only description is given, returns a conventional path proposal under a governed layer.',
       inputSchema: {
         type: 'object',
         properties: {
@@ -586,8 +589,12 @@ async function main() {
             type: 'string',
             description: 'Path (relative to project root or absolute) of the file to place.',
           },
+          description: {
+            type: 'string',
+            description:
+              'What you are building (e.g. "Remotion caption overlay"). Used when filePath is omitted to propose a path.',
+          },
         },
-        required: ['filePath'],
       },
     },
     {
@@ -599,6 +606,14 @@ async function main() {
         'Call BEFORE generating project structure on greenfield or early-adoption repos.',
       inputSchema: { type: 'object', properties: {} },
     },
+    {
+      name: 'ark_suggest_include',
+      description:
+        'Propose ark.config.json include roots from workspaces and nested TypeScript packages ' +
+        '(polyglot-safe). Same idea as ark-check --suggest-include. Use when coverage is empty ' +
+        'or the contract misses package roots.',
+      inputSchema: { type: 'object', properties: {} },
+    },
   ];
 
   const RESOURCES = [
@@ -741,8 +756,52 @@ async function main() {
   // `allowed:false` denies) — which layers it may and must not import.
   function runPlace(params) {
     const filePath = params?.arguments?.filePath;
+    const description = params?.arguments?.description;
+    if ((typeof filePath !== 'string' || !filePath) && typeof description === 'string' && description.trim()) {
+      // Description-only: propose a governed path under PresentationAdapters (UI default).
+      const slug = description
+        .trim()
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-|-$/g, '')
+        .slice(0, 48) || 'component';
+      const proposedPath = `src/components/${slug}.tsx`;
+      const layerName = inferLayer(proposedPath, config, args.root) || 'PresentationAdapters';
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                filePath: proposedPath,
+                proposed: true,
+                description: description.trim(),
+                layer: layerName,
+                governed: Boolean(inferLayer(proposedPath, config, args.root)),
+                note:
+                  'filePath was omitted — proposed a conventional path from description. ' +
+                  'Pass filePath explicitly for authoritative placement. Then validate_code the snippet.',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+        isError: false,
+      };
+    }
     if (typeof filePath !== 'string' || !filePath) {
-      return { content: [{ type: 'text', text: 'Missing required "filePath" argument.' }], isError: true };
+      return {
+        content: [
+          {
+            type: 'text',
+            text:
+              'ark_place needs filePath and/or description. ' +
+              'Example: { "filePath": "src/components/Foo.tsx" } or { "description": "caption overlay UI component" }.',
+          },
+        ],
+        isError: true,
+      };
     }
     const layerName = inferLayer(filePath, config, args.root);
     if (!layerName) {
@@ -814,12 +873,50 @@ async function main() {
     };
   }
 
+  function runSuggestIncludeTool() {
+    try {
+      const workspaces = detectWorkspaces(args.root);
+      const tsPackages = detectTsPackageRoots(args.root);
+      const suggestedInclude = resolveIncludeRoots(args.root);
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify(
+              {
+                ok: true,
+                workspaces,
+                tsPackages,
+                suggestedInclude:
+                  suggestedInclude.length > 0
+                    ? suggestedInclude
+                    : tsPackages.length > 0
+                      ? tsPackages
+                      : ['src'],
+                next: 'npx ark-check --adopt-contract --write',
+              },
+              null,
+              2
+            ),
+          },
+        ],
+        isError: false,
+      };
+    } catch (error) {
+      return {
+        content: [{ type: 'text', text: error instanceof Error ? error.message : String(error) }],
+        isError: true,
+      };
+    }
+  }
+
   const TOOL_HANDLERS = {
     validate_code: runValidate,
     ark_check: runCheckTool,
     ark_coverage: runCoverageTool,
     ark_place: runPlace,
     ark_recommend: runRecommendTool,
+    ark_suggest_include: runSuggestIncludeTool,
   };
 
   const send = (msg) => process.stdout.write(`${JSON.stringify(msg)}\n`);