arkgate 4.6.1 → 4.6.2

package/CHANGELOG.md

@@ -5,6 +5,33 @@ in the immutable pre-2.0 archive linked below.
 
 ## Unreleased
 
+## 4.6.2 — 2026-08-16
+
+**Patch** over **4.6.1**. First-contact copy: a newcomer (human or coding agent) sees what
+to do in a few lines — `arkgate` / `arkgate-check --help`, start wrap-up, doctor light +
+#1, write-gate deny, SessionStart, MCP tool order, and the five doors. Same 13 skill names.
+**No required config migration.**
+
+**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.2.md`).
+
+### Changed
+
+- **First-run help:** `arkgate --help` and `arkgate-check --help` are short; encyclopedia
+  text is `--help --all`. `arkgate upgrade --help` is preview vs apply.
+- **Start wrap-up:** doctor → `/ark-adopt` session 0 (not `/ark-autopilot` as step 1).
+- **Doctor:** operating-mode light + primary next action #1 print first.
+- **Write-gate deny:** `blocked {file} — {reason}` then `Next:` (move the import / `/ark-place`).
+  Rule id on a following line. No “call ark_manifest”.
+- **Agents:** SessionStart points at `/ark-adopt` or `arkgate-check --doctor`. `ark_identity`
+  is first. `ark_check` is a scan (pass/fail/incomplete), not a yes/no architecture score.
+  `server.json` first sentence is the layers definition.
+- **Skills:** five doors open with when + steps. Shortcuts are not the first-run menu.
+- **Status:** `nextAction` is `map-leftover-design` when leftover design work remains
+  (never `stay-enforced`).
+- **npm `description`:** `One architecture config. One check. One coach.` (not “co-pilot”).
+- **`docs/use.md`:** Cursor hard-blocks Write/StrReplace when hooks are trusted;
+  Codex/OpenCode stay advisory.
+
 ## 4.6.1 — 2026-08-14
 
 **Patch** over **4.6.0**. Five-door autonomy (skills write or map in-turn; CLI is sensor +
@@ -12,7 +39,7 @@ gate) plus team parliament (law vs feature: stewards, mixed-PR deny, ratchet vs
 base, cheap `--changed` check). Same 13 skill names. Steward identity is a GitHub handle or
 email, not git `user.name`. **No required config migration.**
 
-**Status: prepared** (not yet on npm `latest`; see `docs/releases/4.6.1.md`).
+**Status: published** (on npm `latest`; see `docs/releases/4.6.1.md`).
 
 ### Added
 
@@ -28,6 +55,8 @@ email, not git `user.name`. **No required config migration.**
 
 - Doctor, compact router, and public lanes prefer the five doors. Historical changelogs stay
   as shipped.
+- Published 4.6.1 tarball `README.md` still banners 4.6.0 (packed at `1eadc96` before the
+  pointer flip). Tree README on `main` is current. No 4.6.2 for that banner.
 
 ## 4.6.0 — 2026-08-12
 

package/README.md

@@ -16,8 +16,9 @@ and makes sure a “green” check means something real.
 
 </div>
 
-> **ArkGate 4.6.0** is on npm `latest` — clearer language + shared agent home skills.
-> [4.6.0 notes](docs/releases/4.6.0.md) · [4.5.7](docs/releases/4.5.7.md) · [4.5.6](docs/releases/4.5.6.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
+> **ArkGate 4.6.1** is on npm `latest` — five doors + a lock on the constitution.
+> **4.6.2** is prepared on this tree (first-contact copy; not yet `latest`).
+> [4.6.2 notes](docs/releases/4.6.2.md) · [4.6.1](docs/releases/4.6.1.md) · [4.6.0](docs/releases/4.6.0.md) · [Docs hub](docs/README.md) · [Product voice](docs/product-voice.md)
 
 ---
 
@@ -213,7 +214,8 @@ for real systems. Details: [docs/production-hardening.md](docs/production-harden
 | Config · package surface · TS | [configuration](docs/configuration.md) · [package-surface](docs/package-surface.md) · [typescript-support](docs/typescript-support.md) |
 | Brownfield | [docs/brownfield-adoption.md](docs/brownfield-adoption.md) |
 | Security | [SECURITY.md](SECURITY.md) |
-| Current release (4.6.0 on npm `latest`) | [docs/releases/4.6.0.md](docs/releases/4.6.0.md) · [CHANGELOG](CHANGELOG.md) |
+| Current release (4.6.1 on npm `latest`) | [docs/releases/4.6.1.md](docs/releases/4.6.1.md) · [CHANGELOG](CHANGELOG.md) |
+| Prepared (4.6.2 — not yet `latest`) | [docs/releases/4.6.2.md](docs/releases/4.6.2.md) |
 | Prior (4.5.7) | [docs/releases/4.5.7.md](docs/releases/4.5.7.md) |
 | Prior (4.5.0) | [docs/releases/4.5.0.md](docs/releases/4.5.0.md) |
 | Prior (4.4.0) | [docs/releases/4.4.0.md](docs/releases/4.4.0.md) |

package/bin/ark-check-runtime.mjs

@@ -95,6 +95,7 @@ import {
   writeArkRulesTemplates,
 } from './lib/presets.mjs';
 import { loadArkConfigContract, parseArkConfigJson } from './lib/config-contract.mjs';
+import { checkUsage, checkUsageAll } from './lib/first-run-help.mjs';
 import { createAdapterResult } from './lib/adapter-contract.mjs';
 import { collectGovernedFiles, normalize, walk } from './lib/scan-files.mjs';
 import { configWarning } from './lib/config-warnings.mjs';
@@ -166,12 +167,13 @@ function parseArgs(argv) {
     noOpenReport: false,
     version: false,
     help: false,
+    all: false,
     followConfigRoot: false,
   };
   const requireValue = (flag, index) => {
     const value = argv[index + 1];
     if (value === undefined || value.startsWith('-')) {
-      throw new Error(`Missing value for ${flag}. Run ark-check --help for usage.`);
+      throw new Error(`Missing value for ${flag}. Run arkgate-check --help for usage.`);
     }
     return value;
   };
@@ -269,8 +271,9 @@ function parseArgs(argv) {
     else if (arg === '--print-config') args.printConfig = requireValue(arg, i++);
     else if (arg === '--tsconfig') args.tsconfig = requireValue(arg, i++);
     else if (arg === '--help' || arg === '-h') args.help = true;
+    else if (arg === '--all') args.all = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
-    else throw new Error(`Unknown argument: ${arg}. Run ark-check --help for usage.`);
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate-check --help for usage.`);
   }
   return args;
 }
@@ -283,116 +286,6 @@ function displayPathFromRoot(root, absPath) {
   }
   return rel.split(path.sep).join('/');
 }
-function usage() {
-  return [
-    '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-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');
-}
 
 function readConfig(root, configPath) {
   const fullPath = path.isAbsolute(configPath)
@@ -1148,7 +1041,7 @@ async function main() {
     process.exit(0);
   }
   if (args.help) {
-    console.log(usage());
+    console.log(args.all ? checkUsageAll() : checkUsage());
     return;
   }
   if (args.init) {
@@ -1706,20 +1599,23 @@ async function main() {
                 }),
           }
         : null;
-    const currentSnapshot = buildReportSnapshot({
-      root,
-      config,
-      coverage,
-      violations: activeViolations,
-      ok,
-      suppressed: suppressed.length,
-      version: arkPackageVersion(),
-      fileCountByLayer,
-      enforcement: enforcementForReport,
-      score: fitness.score,
-      mode: fitness.mode,
-      improvementCompass: reportCompass,
-    });
+    const currentSnapshot = {
+      ...buildReportSnapshot({
+        root,
+        config,
+        coverage,
+        violations: activeViolations,
+        ok,
+        suppressed: suppressed.length,
+        version: arkPackageVersion(),
+        fileCountByLayer,
+        enforcement: enforcementForReport,
+        score: fitness.score,
+        mode: fitness.mode,
+        improvementCompass: reportCompass,
+      }),
+      leftoverDesignWork: designDepth?.designFitness?.designWeak === true,
+    };
     const reportPayload = {
       root,
       config,

package/bin/ark-mcp-runtime.mjs

@@ -643,6 +643,25 @@ function emitHostAllow(output, { antigravityStyle, cursorStyle }) {
   emitCursorAllow(output, cursorStyle);
 }
 
+/**
+ * Socket-style write-gate deny: two lines first. Pass/fail, no score.
+ * Rule id stays on a following line, not the first sentence.
+ */
+function formatWriteGateDeny({ file, reason, ruleId, nextAction, extraLines = [] }) {
+  const target = file || 'this write';
+  const why = String(reason || 'this change breaks the architecture layers').replace(/\s+/g, ' ').trim();
+  const next =
+    nextAction && /place|move|import|port/i.test(nextAction)
+      ? nextAction
+      : 'Move the import or run /ark-place. Do not weaken ark.config.json.';
+  const lines = [`blocked ${target} — ${why}`, `Next: ${next}`];
+  if (ruleId) lines.push(`[${ruleId}]`);
+  for (const extra of extraLines) {
+    if (extra) lines.push(extra);
+  }
+  return lines.join('\n');
+}
+
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
   const { toolName, toolInput, grokStyle, antigravityStyle, cursorStyle, operation } =
     normalizeHookPayload(
@@ -796,17 +815,20 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       emitHostAllow(output, { antigravityStyle, cursorStyle });
       return;
     }
-    const message = [
-      `Ark architecture gate blocked this complete ${toolName} (${changes.length} governed file(s)):`,
-      ...result.diagnostics.map(
-        (diagnostic) =>
-          `- [${diagnostic.ruleId}] ${diagnostic.message}\n  Next action: ${diagnostic.nextAction}`
-      ),
-      ...(designDelta && !designDelta.valid
-        ? formatDesignDeltaBlock(designDelta).split('\n').slice(1)
-        : []),
-      'No project file was written. Fix the complete patch and retry.',
-    ].join('\n');
+    const first = result.diagnostics[0];
+    const message = formatWriteGateDeny({
+      file: `${changes.length} file(s)`,
+      reason: first?.message || `this ${toolName} breaks the architecture layers`,
+      ruleId: first?.ruleId,
+      nextAction: first?.nextAction,
+      extraLines: [
+        ...result.diagnostics.slice(1).map((d) => `[${d.ruleId}] ${d.message}`),
+        ...(designDelta && !designDelta.valid
+          ? formatDesignDeltaBlock(designDelta).split('\n').slice(1)
+          : []),
+        'No project file was written. Fix the complete patch and retry.',
+      ],
+    });
     output.stderr(`${message}\n`);
     if (args.hookRepair) {
       output.stderr(
@@ -926,13 +948,7 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     })),
   });
 
-  const lines = adapterResult.diagnostics.map(
-    (diagnostic) =>
-      `- [${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}\n  Next action: ${diagnostic.nextAction}`
-  );
-  // Surface the per-violation fix hints (the gate carries them in `suggestion`,
-  // but the hook was dropping them). Dedupe so two infra violations sharing one
-  // hint — e.g. the mayImportInfrastructure escape hatch — print it once.
+  const firstDiagnostic = adapterResult.diagnostics[0];
   const suggestions = [
     ...new Set(combinedViolations.map((violation) => violation.suggestion).filter(Boolean)),
   ];
@@ -940,27 +956,34 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
   // W4: structured repair payload is opt-in (--hook-repair / ARK_HOOK_REPAIR).
   // Default remains hard block with prose only — hosts that cannot re-inject stay clean.
   const repair = Boolean(args.hookRepair);
-  const message = [
-    `Ark architecture gate blocked this write to ${rel}${layer ? ` (layer: ${layer})` : ''}:`,
-    ...lines,
-    ...(suggestions.length > 0 ? ['Fix:', ...suggestions.map((s) => `  ${s}`)] : []),
-    ...(autoPatch && repair
-      ? [
-          `autoPatch available (${autoPatch.remediationKind}, confidence ${autoPatch.confidence}): ` +
-            'apply the patched source from ARK_AUTOPATCH_JSON / ARK_REPAIR_JSON on stderr' +
-            (grokStyle ? ' (or autoPatch in the deny JSON on stdout)' : '') +
-            ' instead of re-drafting. Gate still denies this write (never silent apply).',
-        ]
-      : []),
-    ...(autoPatch && !repair
-      ? [
-          `Mechanical-safe autoPatch is available (${autoPatch.remediationKind}). ` +
-            'Enable repair payload with ARK_HOOK_REPAIR=1 or --hook-repair to receive ' +
-            'machine-readable source (still hard-blocks; host re-injects).',
-        ]
-      : []),
-    'Fix the violations and retry. Call the project-bound ark_manifest MCP tool for the architecture contract.',
-  ].join('\n');
+  const message = formatWriteGateDeny({
+    file: rel,
+    reason: firstDiagnostic?.message || (layer ? `${layer} write breaks the layers` : 'this write breaks the layers'),
+    ruleId: firstDiagnostic?.ruleId,
+    nextAction: firstDiagnostic?.nextAction,
+    extraLines: [
+      ...adapterResult.diagnostics.slice(1).map(
+        (diagnostic) =>
+          `[${diagnostic.ruleId}] ${diagnostic.message}${diagnostic.location.line ? ` (line ${diagnostic.location.line})` : ''}`
+      ),
+      ...(suggestions.length > 0 ? suggestions.map((s) => `Fix: ${s}`) : []),
+      ...(autoPatch && repair
+        ? [
+            `autoPatch available (${autoPatch.remediationKind}, confidence ${autoPatch.confidence}): ` +
+              'apply the patched source from ARK_AUTOPATCH_JSON / ARK_REPAIR_JSON on stderr' +
+              (grokStyle ? ' (or autoPatch in the deny JSON on stdout)' : '') +
+              ' instead of re-drafting. Gate still denies this write (never silent apply).',
+          ]
+        : []),
+      ...(autoPatch && !repair
+        ? [
+            `Mechanical-safe autoPatch is available (${autoPatch.remediationKind}). ` +
+              'Enable repair payload with ARK_HOOK_REPAIR=1 or --hook-repair to receive ' +
+              'machine-readable source (still hard-blocks; host re-injects).',
+          ]
+        : []),
+    ],
+  });
   output.stderr(message + '\n');
 
   if (repair) {
@@ -1403,7 +1426,7 @@ function printSessionContext(config, profile, forbiddenGlobals, args, configPath
   const governedPercent = coverage?.coverage?.governed?.percent ?? coverage?.governed?.percent;
   if (shouldShowNewHereNudge(args.root, configPath, governedPercent, false)) {
     lines.push('');
-    lines.push('New to Ark? Run /ark-adopt (or /ark-architect) or: ark-check --recommend');
+    lines.push('New to Ark? /ark-adopt or: arkgate-check --doctor');
   }
 
   process.stdout.write(`${lines.join('\n')}\n`);
@@ -2018,9 +2041,9 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_identity',
       description:
-        'Return the canonical ArkGate project, config, contract, and live MCP runtime identity. ' +
-        'Pass project.expectedRoot and/or expectedProjectId to verify this process before ' +
-        'trusting any architecture evidence.',
+        'First call. Prove this MCP process is the right project: pass project.expectedRoot ' +
+        '(exact absolute root) and reuse the returned projectId. Do this before any other Ark tool. ' +
+        'A missing, unmatched, or different root means restart the host and use the local CLI.',
       inputSchema: { type: 'object', properties: {} },
     },
     {
@@ -2063,11 +2086,10 @@ export async function runArkMcp({ hookInput } = {}) {
     {
       name: 'ark_check',
       description:
-        'Run the full Ark architecture check on the project and return structured results ' +
-        '(layer-import violations, forbidden globals, circular deps, config warnings). Use ' +
-        'this to answer "is the architecture currently valid?" instead of shelling out to ' +
-        'ark-check. Preserves legacy ok and adds identity/completeness/graph/coverage/gates/' +
-        'overall verdicts. Applies the baseline automatically when one exists. isError when not ok.',
+        'Scan the project for architecture findings (layer-import violations, forbidden globals, ' +
+        'cycles, config warnings). Returns pass/fail/incomplete plus evidence — not a yes/no ' +
+        'architecture score. Same engine as arkgate-check. Applies the baseline when one exists. ' +
+        'isError when the scan fails. Prefer after ark_identity.',
       inputSchema: {
         type: 'object',
         properties: {

package/bin/ark.mjs

@@ -35,6 +35,7 @@ import {
 } from './lib/prepare-change.mjs';
 import { runStatusCommand } from './lib/status-command.mjs';
 import { runAgentProjectionCommand } from './lib/agent-projection-command.mjs';
+import { setupUsage, setupUsageAll, upgradeUsage } from './lib/first-run-help.mjs';
 
 const here = path.dirname(fileURLToPath(import.meta.url));
 const arkCheck = path.join(here, 'ark-check.mjs');
@@ -90,13 +91,14 @@ function parseArgs(argv) {
     check: false,
     stdout: false,
     help: false,
+    all: false,
     version: false,
   };
 
   const requireValue = (flag, index) => {
     const value = argv[index + 1];
     if (value === undefined || value.startsWith('-')) {
-      throw new Error(`Missing value for ${flag}. Run ark --help for usage.`);
+      throw new Error(`Missing value for ${flag}. Run arkgate --help for usage.`);
     }
     return value;
   };
@@ -143,79 +145,15 @@ function parseArgs(argv) {
     else if (arg === '--check') args.check = true;
     else if (arg === '--stdout') args.stdout = true;
     else if (arg === '--help' || arg === '-h' || arg === 'help') args.help = true;
+    else if (arg === '--all') args.all = true;
     else if (arg === '--version' || arg === '-V') args.version = true;
     else if (!arg.startsWith('-') && args.command === undefined) args.command = arg;
-    else throw new Error(`Unknown argument: ${arg}. Run ark --help for usage.`);
+    else throw new Error(`Unknown argument: ${arg}. Run arkgate --help for usage.`);
   }
 
   return args;
 }
 
-function usage() {
-  return `Usage:
-  ark start   [--root <project>] [--tools <host>] [--require-write-hook <host>] [--install] [--apply] [--json]
-  ark 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]
-  ark upgrade [--root <project>] [--tools <list>] [--apply] [--plan-digest <sha256>] [--accept-conflicts] [--refresh-skills] [--json] [--no-install] [--no-strict]
-  ark preflight --changes <change-set.json> [--change-map <map.json>] [--root <project>] [--config ark.config.json] [--manifest <manifest.json>] [--tsconfig <tsconfig.json>] [--json]
-  ark status  [--root <project>] [--config ark.config.json] [--json] [--vs <git-ref>]
-              [--expected-root <abs>] [--expected-project-id sha256:…] [--tools <host>]
-  ark 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.
-`;
-}
-
 function cliVersion() {
   try {
     const pkg = JSON.parse(fs.readFileSync(path.join(here, '..', 'package.json'), 'utf8'));
@@ -796,23 +734,22 @@ async function start(args) {
     }
     console.log('');
     console.log('Next (the only flow you need):');
+    console.log(`  1. Status: ${arkCommand(root, 'arkgate-check', '--doctor')} — do primary next action #1`);
     if (falseGreenGap) {
-      console.log('  1. In your agent:  /ark-adopt — fix the architecture config first');
-      console.log('     → reclassify I/O dirs out of Application; then /ark-autopilot for residual debt.');
+      console.log('  2. Session 0 in your agent:  /ark-adopt — fix the architecture config first');
+      console.log('     → reclassify I/O dirs out of Application; leftover design later via /ark-explore then /ark-autopilot.');
     } else {
-      console.log('  1. In your agent:  /ark-autopilot');
-      console.log('     → explore first, dual plan (remediation + pattern bets), safe fixes, leave gates on.');
+      console.log('  2. Session 0 in your agent:  /ark-adopt');
+      console.log('     → mark the path (greenfield or brownfield). Day-to-day new files: /ark-place.');
     }
-    console.log(`  2. Status anytime: ${arkCommand(root, 'ark-check', '--doctor')}`);
-    console.log(`  3. After edits:    ${arkCommand(root, 'ark-check', '--root . --config ark.config.json --strict-merge')}`);
+    console.log(`  3. After edits:    ${arkCommand(root, 'arkgate-check', '--root . --config ark.config.json --strict-merge')}`);
     if (mode === 'adapt' && planOk && !falseGreenGap) {
       console.log(
-        `  4. When green but cores still optional: ${arkCommand(root, 'ark-check', '--ratchet-cores')} → honest ENFORCE`
+        `  4. When green but cores still optional: ${arkCommand(root, 'arkgate-check', '--ratchet-cores')} → honest ENFORCE`
       );
     }
     console.log('');
-    console.log('Optional later: ark-check --report ark-report.html (captures a day-zero/evolution report).');
-    console.log('Optional later: --plan · --coverage · /ark-explore · /ark-autopilot · /ark-place · ark upgrade');
+    console.log('Optional later: leftover design → /ark-explore then /ark-autopilot; bump → arkgate upgrade.');
     return 0;
   } finally {
     rl?.close();
@@ -831,8 +768,12 @@ async function main() {
     console.log(cliVersion());
     return 0;
   }
+  if (args.help && (args.command === 'upgrade' || args.command === 'update')) {
+    console.log(upgradeUsage());
+    return 0;
+  }
   if (args.help || !args.command) {
-    console.log(usage());
+    console.log(args.all ? setupUsageAll() : setupUsage());
     return 0;
   }
 
@@ -961,7 +902,7 @@ async function main() {
   }
 
   console.error(`Unknown command: ${args.command}`);
-  console.error(usage());
+  console.error(setupUsage());
   return 2;
 }