arkgate 4.6.0 → 4.6.2

package/bin/lib/doctor-advisories.mjs

@@ -19,6 +19,7 @@ import {
 import { printParseHealthSection, summarizeParseHealth } from './parse-health.mjs';
 import { detectGraphBlindSpots, printGraphBlindSection } from './graph-blind.mjs';
 import { summarizeRulesUnderContract } from './rules-under-contract.mjs';
+import { collectStewardNudge } from './team-parliament-io.mjs';
 
 export function computeDoctorAdvisories(root, config, cov, rules, files, ts, parseHealth, facts) {
   const physicalCohesion = computePhysicalCohesion(root, files);
@@ -49,6 +50,7 @@ export function computeDoctorAdvisories(root, config, cov, rules, files, ts, par
     graphBlindSpots: detectGraphBlindSpots(ts, root, files),
     // AR12 — Rules under contract (honest counts; real test I/O, never empty-fileContents stub).
     // P1M: pass classification so extraMergeTeeth cannot arm at 0% governed.
+    stewardNudge: collectStewardNudge(root, config),
     rulesUnderContract: summarizeRulesUnderContract(root, config, factPaths, {
       governedPercent: cov?.governed?.percent ?? null,
       populatedLayerCount: Array.isArray(cov?.layers)
@@ -70,4 +72,11 @@ export function printDoctorAdvisories(advisories, io) {
   printReshapeDecisionsSection(advisories.physicalCohesion?.reshapeDecisions, io);
   printParseHealthSection(advisories.parseHealth, io);
   printGraphBlindSection(advisories.graphBlindSpots, io);
+  const nudge = advisories.stewardNudge;
+  if ((nudge?.needsStewards || nudge?.drift) && nudge.ask) {
+    console.log('');
+    console.log(io.color.bold('Stewards (advisory)'));
+    io.line(io.warn, nudge.ask);
+    if (nudge.nextAction) io.line(' ', io.color.dim(`Next: ${nudge.nextAction}`));
+  }
 }

package/bin/lib/doctor-next-actions.mjs

@@ -0,0 +1,92 @@
+/**
+ * Rank doctor next actions from already-computed facts (no I/O).
+ * Lets the human printer show light + #1 before honesty/compass sections.
+ */
+import { arkCommand } from '../ark-shared.mjs';
+import { skillGapsForActiveHost } from './agent-gates.mjs';
+import { agentHomeConcernIsActive, agentHomeRefreshCommand } from './agent-homes.mjs';
+import { mergePostGreenTopActions } from './post-green-path.mjs';
+
+export function collectDoctorNextActions(ctx) {
+  const actions = [];
+  if (!ctx.analysisComplete) actions.push('restore complete analysis, then rerun ark-check --doctor');
+  if (ctx.designSmells.length > 0 && ctx.postGreenPath) actions.push(ctx.postGreenPath.action);
+  if (ctx.coverageHonesty.greenIsNotEnforcement && ctx.coverageHonesty.worseThanNoGate) {
+    actions.push('raise governed coverage above a minority slice before treating green as enforcement');
+  }
+  if (ctx.cov.suggestions.length > 0) actions.push('classify the ungoverned directories (/ark-adopt)');
+  if (ctx.packageVersionTruth?.dualTruth) {
+    actions.push(
+      ctx.dualTruthNext ||
+        'bump package.json arkgate pin to match this CLI (or install without --no-install)'
+    );
+  } else if (ctx.packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT') {
+    actions.push(
+      ctx.dualTruthNext ||
+        'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
+    );
+  }
+  if (ctx.activeCount > 0) {
+    actions.push(
+      `resolve the non-baselined violations — see the classified plan (${arkCommand(ctx.root, 'ark-check', '--plan')}), then /ark-autopilot`
+    );
+  }
+  if (ctx.writePath?.gap?.fix) actions.push(ctx.writePath.gap.fix);
+  if (ctx.gatesMissing.length > 0) {
+    actions.push(`install gates (${arkCommand(ctx.root, 'ark-check', '--install-agent-gates')})`);
+  }
+  const humanSkillGaps = skillGapsForActiveHost(ctx.skillGaps);
+  const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
+  const remainingGaps = humanSkillGaps.filter(
+    (g) => !(g.tool === 'codex' && (g.legacyPromptsOnly || g.legacyAdvisory))
+  );
+  const remMiss = remainingGaps.reduce((s, g) => s + g.missing, 0);
+  const remStale = remainingGaps.reduce((s, g) => s + g.stale, 0);
+  if (legacyCodex) {
+    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
+  }
+  if (remMiss + remStale > 0) {
+    actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
+  }
+  if (ctx.codexHomeGap && ctx.codexConcernActive) {
+    actions.push(
+      ctx.codexHomeGap.catalogMetadataInvalid
+        ? 'repair invalid Codex home catalog metadata after verifying the newest installed version'
+        : 'refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)'
+    );
+  }
+  for (const gap of ctx.agentHomeGaps) {
+    if (agentHomeConcernIsActive(gap.host)) {
+      actions.push(
+        gap.catalogMetadataInvalid
+          ? `repair invalid ${gap.label} home catalog metadata after verifying the newest installed version`
+          : `refresh ${gap.label} shared agent skills (${agentHomeRefreshCommand(ctx.root, gap)})`
+      );
+    }
+  }
+  if (ctx.analysisComplete && ctx.baselineHonesty?.dirtyBaselineRisk) {
+    actions.push('review dirty baseline freezes — fix the contract before trusting green-via-freeze');
+  }
+  if (ctx.analysisComplete && ctx.staleBaseline > 0) {
+    actions.push('tighten the baseline (--update-baseline)');
+  }
+  if (ctx.staleRunners.length > 0) {
+    actions.push(
+      `migrate command runners (${arkCommand(ctx.root, 'ark-check', '--install-agent-gates --migrate-commands')})`
+    );
+  }
+  for (const gap of ctx.adoption.gaps) {
+    if (!gap.deferred) actions.push(gap.fix || gap.message);
+  }
+  if (ctx.safety && ctx.safetyHasEntries) {
+    actions.push('resolve strict safety diagnostics before treating CI as enforcement');
+  }
+  if (ctx.showNewHere) {
+    actions.unshift('finish ark start (preview + --apply), then re-run --doctor');
+  }
+  const unique = mergePostGreenTopActions(actions, ctx.postGreenPath);
+  if (ctx.designFitness.designWeak && unique.length === 0 && ctx.postGreenPath) {
+    unique.push(ctx.postGreenPath.action);
+  }
+  return unique;
+}

package/bin/lib/doctor-plan.mjs

@@ -15,9 +15,9 @@ import { describePackageVersionDualTruth } from './field-install.mjs';
 import {
   detectAgentHomeGaps,
   agentHomeConcernIsActive,
-  agentHomeRefreshCommand,
 } from './agent-homes.mjs';
 import { operatingModeTitle } from './product-copy.mjs';
+import { collectDoctorNextActions } from './doctor-next-actions.mjs';
 export { summarizeRulesUnderContract };
 
 /** Optional S3 dual-match classifier when ark-shared exports it (soft dep for S5 landing). */
@@ -50,7 +50,6 @@ import {
 } from './design-smells.mjs';
 import {
   buildPostGreenNextAction,
-  mergePostGreenTopActions,
   isDoctorHealthyNothingToDo,
   DESIGN_WEAK_HONESTY_FLAGS,
 } from './post-green-path.mjs';
@@ -208,7 +207,7 @@ export function runCoverage(root, config, files, rules, asJson) {
       }
     }
     console.log('');
-    console.log('Apply these via /ark-contract (adds the layer patterns to ark.config.json).');
+    console.log('Apply these via /ark-adopt (adds the layer patterns to ark.config.json).');
   }
   if (layersWithoutRules.length > 0) {
     console.log('');
@@ -825,9 +824,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   const ok = color.green('✓');
   const warn = color.yellow('!');
   const bad = color.red('✗');
-  const actions = [];
   const line = (mark, text) => console.log(`  ${mark} ${text}`);
-  if (!analysisComplete) actions.push('restore complete analysis, then rerun ark-check --doctor');
   console.log(color.bold(`Ark doctor — ${path.basename(path.resolve(root)) || '.'}`));
   if (!analysisComplete) line(warn, analysisIncompleteStatement(completeness));
 
@@ -846,7 +843,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     suggest:
       'thin or new tree; architecture config is not yet in charge. You do not pick this light. Next: ark start (preview), then ark start --apply; re-check with --doctor.',
     adapt:
-      'config and tree still disagree, or debt is open. The write path does not fully protect you yet. You do not pick this light. Next: do doctor top action #1 (often /ark-adopt, /ark-contract, or /ark-autopilot).',
+      'config and tree still disagree, or debt is open. The write path does not fully protect you yet. You do not pick this light. Next: do doctor top action #1 (often /ark-adopt or /ark-autopilot).',
     enforce:
       'honest coverage and clean checked imports. You arrived here; you never turn Enforce on. Next: keep the host write path and CI check; only NEW violations should fail.',
   };
@@ -866,6 +863,63 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     );
   }
 
+  const safetyHasEntries = Boolean(
+    options.safety &&
+      [
+        options.safety.nonLiteralDynamicImports,
+        options.safety.tsSuppressions,
+        options.safety.anyCasts,
+        options.safety.inMemoryProductionStores,
+        options.safety.disabledPeerIsolationRules,
+      ].some((entries) => Array.isArray(entries) && entries.length > 0)
+  );
+  const uniqueActions = collectDoctorNextActions({
+    root,
+    analysisComplete,
+    designSmells,
+    postGreenPath,
+    coverageHonesty,
+    cov,
+    packageVersionTruth,
+    dualTruthNext,
+    activeCount,
+    writePath,
+    gatesMissing,
+    skillGaps,
+    codexHomeGap: detectCodexHomeGap(root),
+    codexConcernActive: codexConcernIsActive(),
+    agentHomeGaps,
+    baselineHonesty,
+    staleBaseline,
+    staleRunners,
+    adoption,
+    safety: options.safety,
+    safetyHasEntries,
+    showNewHere,
+    designFitness,
+  });
+  console.log('');
+  if (isDoctorHealthyNothingToDo(designFitness, uniqueActions)) {
+    console.log(color.green('✔ Healthy — nothing to do.'));
+    console.log(color.dim('  Contract edges and design residual are clear. Keep write path + CI.'));
+  } else {
+    console.log(color.bold('Primary next action'));
+    console.log(`  1. ${uniqueActions[0]}`);
+    if (uniqueActions.length > 1) {
+      console.log(color.bold(`Also (${uniqueActions.length - 1}):`));
+      uniqueActions.slice(1).forEach((action, index) => console.log(`  ${index + 2}. ${action}`));
+    }
+    if (postGreenPath) {
+      console.log(
+        color.dim(
+          `  Shape residual is the primary door under ${modeTitle} — do not skill-shop explore vs coverage vs think.`
+        )
+      );
+    } else {
+      console.log(color.dim('  Doctor is the control plane: do #1 first, then re-run --doctor.'));
+    }
+  }
+
   // P0-B — single honesty surface (never a score; never "all good" when residual remains).
   if (productHonesty) {
     console.log('');
@@ -907,11 +961,7 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
         line(' ', color.dim(`evidence: ${smell.evidence.slice(0, 4).join(', ')}`));
       }
     }
-    if (postGreenPath) {
-      // Rank first via mergePostGreenTopActions at the end (Q01 single door).
-      actions.push(postGreenPath.action);
-    }
-    // Q04 — surface one next pilot under design-weak.
+    // Q04 — surface one next pilot under leftover design work.
     if (pilotLoop?.active && pilotLoop.nextPilot) {
       const np = pilotLoop.nextPilot;
       line(
@@ -967,13 +1017,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   line(govMark, `Governed: ${cov.governed.percent}% (${cov.governed.classifiedFiles}/${cov.governed.totalFiles} files)`);
   if (coverageHonesty.greenIsNotEnforcement) {
     line(coverageHonesty.worseThanNoGate ? bad : warn, coverageHonesty.message);
-    if (coverageHonesty.worseThanNoGate) {
-      actions.push('raise governed coverage above a minority slice before treating green as enforcement');
-    }
   }
   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(', ')}`);
@@ -989,18 +1035,10 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     console.log('');
     console.log(color.bold('Package pin (dual-truth)'));
     line(warn, packageVersionTruth.note);
-    actions.push(
-      dualTruthNext ||
-        'bump package.json arkgate pin to match this CLI (or install without --no-install)'
-    );
   } else if (packageVersionTruth?.code === 'PACKAGE_PIN_ABSENT') {
     console.log('');
     console.log(color.bold('Package pin'));
     line(warn, packageVersionTruth.note);
-    actions.push(
-      dualTruthNext ||
-        'Add arkgate to package.json and install so CI/npx resolve this CLI (PACKAGE_PIN_ABSENT)'
-    );
   }
   if (options.configWalkedUp && options.configRoot) {
     line(
@@ -1030,7 +1068,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       line(warn, 'Low governed coverage or fresh config — finish start, then re-run doctor before adding layers of code.');
     }
     line(ok, `Optional sensor detail: ${arkCommand(root, 'ark-check', '--recommend')}`);
-    actions.unshift('finish ark start (preview + --apply), then re-run --doctor');
   }
 
   console.log('');
@@ -1058,11 +1095,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     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('');
@@ -1105,7 +1137,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(writePath.gap.severity === 'warn' ? warn : warn, writePath.gap.message);
     if (writePath.gap.fix) {
       line(' ', color.dim(`Fix: ${writePath.gap.fix}`));
-      actions.push(writePath.gap.fix);
     }
   }
 
@@ -1114,7 +1145,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   if (gatesMissing.length === 0) line(ok, 'Shared gate artifacts found on disk (AGENTS.md, .mcp.json, CI); runtime activation is reported separately');
   else {
     line(bad, `Missing gates: ${gatesMissing.join(', ')}`);
-    actions.push(`install gates (${arkCommand(root, 'ark-check', '--install-agent-gates')})`);
   }
   const humanSkillGaps = skillGapsForActiveHost(skillGaps);
   const legacyCodex = humanSkillGaps.some((g) => g.tool === 'codex' && g.legacyPromptsOnly);
@@ -1129,7 +1159,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   if (remMiss + remStale === 0 && !legacyCodex) line(ok, '/ark-* skills current for detected tools');
   if (legacyCodex) {
     line(warn, 'Codex: legacy flat .codex/prompts only (not a loadable skill catalog)');
-    actions.push('install Codex SKILL.md catalog (--install-agent-gates --skills-only --tools codex --force)');
   }
   if (codexLegacySafeDelete) {
     line(
@@ -1144,7 +1173,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       warn,
       `${remMiss} missing / ${remStale} content-behind-package /ark-* skill(s) for ${remainingGaps.map((g) => g.tool).join(', ')}`
     );
-    actions.push('refresh /ark-* skills (--install-agent-gates --skills-only --force)');
   }
   const codexHomeGap = detectCodexHomeGap(root);
   if (codexHomeGap) {
@@ -1159,7 +1187,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       line(color.dim('·'), color.dim(`Codex home skills ${parts.join(', ')} (deferred — not on Codex session)`));
     } else {
       line(warn, `Codex home skills ${parts.join(', ')}`);
-      actions.push(codexHomeGap.catalogMetadataInvalid ? 'repair invalid Codex home catalog metadata after verifying the newest installed version' : 'refresh Codex home skills (--install-agent-gates --skills-only --codex-home --force)');
     }
   }
   for (const gap of agentHomeGaps) {
@@ -1174,11 +1201,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       line(color.dim('·'), color.dim(`${summary} (deferred — not this session)`));
     } else {
       line(warn, summary);
-      actions.push(
-        gap.catalogMetadataInvalid
-          ? `repair invalid ${gap.label} home catalog metadata after verifying the newest installed version`
-          : `refresh ${gap.label} shared agent skills (${agentHomeRefreshCommand(root, gap)})`
-      );
     }
   }
 
@@ -1193,11 +1215,9 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     line(baseMark, `${baseline.keys.size} frozen key(s)${analysisComplete ? '' : ' — stale comparison not verified'}`);
     if (analysisComplete && baselineHonesty.dirtyBaselineRisk) {
       line(warn, baselineHonesty.message);
-      actions.push('review dirty baseline freezes — fix the contract before trusting green-via-freeze');
     }
     if (analysisComplete && staleBaseline > 0) {
       line(warn, `${staleBaseline} stale entr(y/ies) no longer occur — tighten with --update-baseline`);
-      actions.push('tighten the baseline (--update-baseline)');
     }
   }
 
@@ -1206,7 +1226,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
   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)
@@ -1232,7 +1251,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
       if (gap.fix) {
         line(' ', color.dim(gap.deferred ? `When using Codex: ${gap.fix}` : `Fix: ${gap.fix}`));
       }
-      if (!gap.deferred) actions.push(gap.fix || gap.message);
     }
     if (adoption.layerBalance) {
       line(warn, color.dim(adoption.layerBalance.educational));
@@ -1269,34 +1287,6 @@ export function runDoctor(root, config, files, rules, violations, asJson, option
     for (const [label, entries] of rows) {
       line(entries.length === 0 ? ok : warn, `${label}: ${entries.length}`);
     }
-    if (rows.some(([, entries]) => entries.length > 0)) {
-      actions.push('resolve strict safety diagnostics before treating CI as enforcement');
-    }
   }
 
-  console.log('');
-  const uniqueActions = mergePostGreenTopActions(actions, postGreenPath);
-  if (isDoctorHealthyNothingToDo(designFitness, uniqueActions)) {
-    console.log(color.green('✔ Healthy — nothing to do.'));
-    console.log(color.dim('  Contract edges and design residual are clear. Keep write path + CI.'));
-  } else {
-    if (designFitness.designWeak && uniqueActions.length === 0 && postGreenPath) {
-      uniqueActions.push(postGreenPath.action);
-    }
-    console.log(color.bold(`Primary next action`));
-    console.log(`  1. ${uniqueActions[0]}`);
-    if (uniqueActions.length > 1) {
-      console.log(color.bold(`Also (${uniqueActions.length - 1}):`));
-      uniqueActions.slice(1).forEach((action, index) => console.log(`  ${index + 2}. ${action}`));
-    }
-    if (postGreenPath) {
-      console.log(
-        color.dim(
-          `  Shape residual is the primary door under ${modeTitle} — do not skill-shop explore vs coverage vs think.`
-        )
-      );
-    } else {
-      console.log(color.dim('  Doctor is the control plane: do #1 first, then re-run --doctor.'));
-    }
-  }
 }

package/bin/lib/field-install.mjs

@@ -506,7 +506,7 @@ export function detectContractFalseGreenRisk(root, config, coverage) {
       `Contract may be a false green: empty core layer(s) [${emptyCores.join(', ')}] while ` +
       `Application-class globs still cover I/O paths (${ioPaths.slice(0, 5).join(', ')}` +
       `${ioPaths.length > 5 ? ', …' : ''}). A clean check can miss real coupling.`,
-    fix: 'Run /ark-adopt or /ark-contract — reclassify persistence/auth dirs out of Application before claiming ENFORCE.',
+    fix: 'Run /ark-adopt — reclassify persistence/auth dirs out of Application before claiming ENFORCE.',
   };
 }
 

package/bin/lib/first-run-help.mjs

@@ -0,0 +1,221 @@
+/**
+ * First-run CLI help (setup + check). Encyclopedia text stays behind --help --all.
+ */
+
+export function setupUsage() {
+  return `arkgate (alias ark) — One architecture config. One check. One coach.
+
+  arkgate start              preview what will change (no writes)
+  arkgate start --apply      write the compact contract + host router + CI
+  arkgate-check --doctor     status light + primary next action
+
+Then session 0 in your agent: /ark-adopt
+Stuck? Run doctor. Do #1.
+
+More commands and flags: arkgate --help --all
+`;
+}
+
+export function upgradeUsage() {
+  return `arkgate upgrade (alias ark upgrade) — preview vs apply.
+
+  arkgate upgrade            preview managed updates (no writes)
+  arkgate upgrade --apply    apply the previewed bytes (needs --plan-digest when applying managed files)
+
+Customized files stay unless you pass --accept-conflicts or --refresh-skills.
+Then: arkgate-check --doctor
+
+Every flag: arkgate --help --all
+`;
+}
+
+export function setupUsageAll() {
+  return `arkgate (alias ark) — One architecture config. One check. One coach.
+
+Usage:
+  arkgate start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
+  arkgate init    [--root <project>] [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|clean-architecture|onion-architecture]
+              [--archetype <playbook-id>] [--tools <list>] [--require-write-hook <host>] [--yes] [--force] [--no-strict]
+  arkgate upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--refresh-skills] [--json] [--no-install] [--no-strict]
+  arkgate preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
+  arkgate status  [--root <project>] [--config ark.config.json] [--json] [--vs <git-ref>]
+              [--expected-root <abs>] [--expected-project-id sha256:…] [--tools <host>]
+  arkgate agents-md [--root <project>] [--config ark.config.json] [--write] [--check] [--stdout] [--json]
+                [--tools <host>]
+
+Commands:
+  start     New here? Analyze and preview the complete setup. Read-only unless --apply.
+  init      Configure Ark project enforcement with explicit prompts.
+  upgrade   Preview identity-proven Ark-managed asset updates. With package install,
+            --apply bumps toward registry latest when behind (not only when CLI ≠ pin)
+            and recomputes the preview; a second explicit --apply --no-install applies
+            those exact bytes and verifies them. --refresh-skills opts in to rewrite
+            customized managed skills to package templates (never silent default).
+            (alias: ark update)
+  preflight Validate one atomic create/update/delete set without writing project files.
+  status    Unified session/project manifest (identity, activation, last check, rules).
+            Never prompts. Prefer --json for agents; CI=1 forces JSON.
+  agents-md Version-matched agent contract projection (ACS04). Stamps package version +
+            contract summary into a managed AGENTS.md block. Non-authoritative — not a
+            gate input. Preview by default; --write merges without clobbering outside
+            regions; --check fails on version drift; --stdout prints the block only.
+            (aliases: agents-md, agent-projection)
+
+Options:
+  --yes        Non-interactive defaults: create config if needed, install gate templates, run strict check.
+               (Also the implicit default when stdin/stdout are not a TTY — agents never hang on prompts.)
+  --force      Allow generated files to overwrite existing files.
+  --no-strict  Skip the final strict ark-check run.
+  --install    Pin and install arkgate as a project devDependency (default for start).
+  --no-install Skip adding/installing arkgate as a project devDependency (start/upgrade).
+  --apply       Apply a start plan; for upgrade, update/repreview or apply managed bytes.
+  --accept-conflicts
+                Allow upgrade to recreate deleted managed assets or replace recorded conflicts.
+  --plan-digest Digest emitted by an upgrade preview; required to apply managed bytes.
+  --json        Emit the start/upgrade/status/agents-md preview as deterministic machine-readable JSON.
+  --write       For agents-md: merge the version-matched projection into AGENTS.md.
+  --check       For agents-md: exit 1 when projection stamp drifts from package version.
+  --stdout      For agents-md: print the projection block only (no file write).
+  --expected-root / --expected-project-id
+                Optional project expectation for status (MCP-compatible binding check).
+  --preset     Start from a named architecture preset instead of detection.
+  --archetype  Application shape from templates/architecture-playbook.json (maps to the matching preset).
+               Valid ids: crud-product, api-backend, frontend-surface, library-sdk, cli-utility,
+               worker-pipeline, event-coordinator, integration-bridge, multi-app-workspace, prototype-spike,
+               vertical-slice-product, ddd-bounded-contexts.
+  --tools      One active agent host for start (claude,cursor,codex,grok,windsurf,cline,copilot,kiro,roo,continue,gemini).
+               Omit to use the active host; an unknown host creates only the shared compact router.
+  --remove-host <host>
+               Preview or apply removal of that compact host integration; re-add it with --tools <host>.
+  --require-write-hook <host>
+               Require and verify a hard local write hook for Claude, Grok, Antigravity, or Cursor.
+               Codex/OpenCode are advisory-write plus hard CI merge only; impossible requests fail before any write.
+
+Interactive mode (TTY, no --yes): asks what application shape you are building and maps it to a preset.
+Non-interactive (no TTY): uses the same defaults as --yes — never calls readline on a null interface.
+`;
+}
+
+export function checkUsage() {
+  return [
+    'arkgate-check (alias ark-check) — the architecture check.',
+    '',
+    '  arkgate-check --doctor         where you are: one status light, one next action',
+    '  arkgate-check --strict-merge   CI / merge gate (required GitHub status)',
+    '',
+    'Every flag and command: arkgate-check --help --all',
+  ].join('\n');
+}
+
+export function checkUsageAll() {
+  return [
+    'arkgate-check (alias ark-check) — the architecture check.',
+    '',
+    'Usage: arkgate-check | ark-check  (identical bins; product name ArkGate)',
+    '       arkgate-check --version',
+    '       arkgate-check --root <project> --config <ark.config.json> [--manifest <ark.manifest.json>] [--tsconfig <tsconfig.json>] [--strict-merge | --strict | --strict-config] [--policy-base <file> | --policy-base-ref <git-ref>] [--policy-ack <file>] [--fail-on-new-smells --base-ref <git-ref>] [--contract-diff] [--contract-session] [--changed] [--against <git-ref>] [--base <git-ref>] [--persona touch|contributor|agent|steward] [--author <id>] [--require-gates] [--require-write-hook <host>] [--json] [--baseline [file]] [--report [file.html]] [--no-cache]',
+    '       ark-check --doctor [--json] [--resident] [--fail-on-new-smells --base-ref <git-ref>]  read-only diagnosis; resident JSON falls back cold',
+    '       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 --rules-inventory [--json]   brownfield rules inventory (AR13; deterministic candidates, not a score)',
+    '       ark-check --recommend [--json] [--write-plan]  application-shape plan; --write-plan emits ark-adoption-plan.json',
+    '       ark-check --list-policy-packs            enthusiast packs (hexagonal, layered, feature-sliced, monorepo, ui-surface, vertical-slice, ddd-bounded-contexts)',
+    '       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 + layer patterns from ungoverned dirs (never bare lib→Presentation)',
+    '       ark-check --migrate-contract [--write] additive P0-A retrofit: inject app/api/** → Application when missing',
+    '       ark-check --ratchet-cores              when raw graph is green (0 violations; baseline ignored), set optional:false on populated cores only (writes ark.config.json)',
+    '       ark-check --watch                      re-run the check when governed files change (debounced)',
+    '       ark-check --report [file.html] [--beginner] [--reset-origin] [--no-archive] [--open|--no-open]',
+    '           HTML report + snapshots under .ark/reports/ (origin once, latest each run, history JSON)',
+    '           Best-effort open in browser (local TTY). No-op if open fails. --no-open / ARK_NO_OPEN_REPORT=1 to skip; --open forces open.',
+    '       ark-check --init [--preset hexagonal|layered|feature-sliced|monorepo|ui-surface|vertical-slice|ddd-bounded-contexts|vite-vercel-spa|clean-architecture|onion-architecture] [--force] [--follow-config-root]',
+    '       --follow-config-root  On writes (init/install-agent-gates/migrate --write/…), adopt walked-up monorepo config root (default: keep explicit --root)',
+    '       ark-check --install-agent-gates [--tools claude,cursor,codex,grok] [--require-write-hook <host>] [--skills-only] [--codex-home] [--claude-home] [--grok-home] [--agent-homes] [--force]',
+    '       ark-check --update-baseline [file]     freeze current violations (default .ark-baseline.json)',
+    '       ark-check --print-config eleven-layer',
+    '',
+    'Adopting Ark in an existing codebase? Run --update-baseline once to freeze existing',
+    'violations, commit the baseline file, and gate CI with --baseline: only NEW violations',
+    'fail the check, so the ratchet only moves toward zero.',
+    '',
+    'Team parliament: law files (ark.config / arkrules / .ark-baseline.json) cannot ship in',
+    'the same diff as product source. --changed --base <ref> checks touched files only.',
+    '--against <ref> ratchets new keys vs that ref\'s baseline. --contract-session is a',
+    'steward law-only PR. Loosen / baseline-grow need stewards[] + --author when set.',
+    '',
+    '--init scans the project for the built-in layer directory conventions (src/domain,',
+    'src/application, src/adapters/persistence, ...) and writes an ark.config.json covering',
+    'only the layers that actually exist, with the default rules filtered to those layers.',
+    'Undetected profile layers are printed as suggestions with their conventional',
+    'directories. When nothing is detected, the full 11-layer starter profile is written',
+    'instead (all layers optional, anchored at src/), so the strict check passes today and',
+    'each layer starts being enforced as soon as its directory gains source files.',
+    '',
+    'Resolves relative, tsconfig path-alias, and package imports via the TypeScript',
+    'module resolver, then checks each resolved cross-layer import against the rules.',
+    'Path aliases resolve against the NEAREST tsconfig.json above each source file, so',
+    'monorepo packages with per-package configs work under a single --root. Pass',
+    '--tsconfig to force one config for every file. If no tsconfig is found, path',
+    'aliases are unavailable but relative/package imports still resolve.',
+    '',
+    'The correctness path resolves and parses one complete candidate on every invocation.',
+    'Legacy node_modules/.cache/ark-check.json files are ignored. --no-cache remains an',
+    'accepted compatibility no-op; the identity-keyed warm snapshot is introduced in Z07.',
+    '',
+    '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"] }',
+    '  ],',
+    '  "rules": [{ "from": "DomainModel", "to": "PersistenceAdapters", "allowed": false }]',
+    '}',
+    '',
+    'Config warnings are advisory by default and are included in JSON output.',
+    'Use --strict-config to make config warnings fail the check.',
+    'Use --strict-merge for the fail-closed CI profile: --strict-config + --require-gates',
+    'plus the security diagnostics surfaced by doctor. --strict is a compatibility alias.',
+    'This merge profile never depends on an editor/agent hook.',
+    'When a Git merge base is available, --strict-merge classifies the ark.config.json',
+    'transition. Weakening or judgment-required findings fail unless --policy-ack names',
+    'every finding and is bound to both policy hashes. Use --policy-base/--policy-base-ref',
+    'for an explicit comparison; ARK_POLICY_BASE_REF is the CI environment equivalent.',
+    'Add --require-write-hook claude|grok|antigravity|cursor to validate a hard local write',
+    'boundary for that specific host. Codex and OpenCode expose advisory MCP (plus best-effort',
+    'hooks where applicable) and the shared CI check; merge blocking requires repository policy',
+    'to make that status required.',
+    '',
+    '--require-gates implies --strict-config and fails when the Ark contract in AGENTS.md,',
+    'the project-rooted Ark server in .mcp.json, or fail-closed CI is missing/invalid.',
+    'Included but unclassified source files therefore stay red instead of false-green.',
+    '',
+    '--install-agent-gates writes AGENTS.md, .mcp.json, and the CI workflow for every',
+    'project, plus tool-specific templates. Known tools: claude, cursor, codex, grok',
+    '(Claude/Grok/Antigravity/Cursor hard-write hooks when covered; Codex advisory MCP;',
+    'shared CI check for all) and',
+    'windsurf, cline, copilot, kiro, roo, continue, gemini',
+    '(instruction-tier rule files derived from the same contract).',
+    'It also installs the /ark-* skills shipped in templates/skills/ into each',
+    'detected tool\'s command location (.claude/skills/, .cursor/commands/,',
+    '.agents/skills/ (Codex REPO catalog), .grok/skills/, .windsurf/workflows/,',
+    '.clinerules/workflows/, .github/prompts/).',
+    'Kiro, Roo, Continue, and Gemini have no command mechanism and receive only their',
+    'rule file. Existing files are never overwritten without --force, so re-running',
+    'after an update only adds what is missing. --skills-only restricts the write to',
+    'just the /ark-* skills (safe to --force-refresh — it leaves a customized AGENTS.md,',
+    'settings, and CI workflow untouched).',
+    'Pass --tools to pick which tool configs to write; otherwise they are auto-detected',
+    'from their config directories (.claude/, .cursor/, .codex/, .grok/, .windsurf/,',
+    '.clinerules/, .kiro/, .roo/, .continue/, .gemini/; copilot is explicit-only).',
+    'claude+cursor+codex+grok are written when nothing is detected.',
+    '',
+    'Generate a starter 11-layer config:',
+    '  ark-check --print-config eleven-layer > ark.config.json',
+    '',
+    'Install agent + CI enforcement templates:',
+    '  ark-check --install-agent-gates',
+  ].join('\n');
+}