arkgate 3.8.2 → 3.9.0

package/bin/ark-mcp-runtime.mjs

@@ -177,13 +177,90 @@ function isResolvedAnalysisInput(relativePath, args, compilerInputs = new Set())
   return /(?:^|\/)configs?\/[^/]+\.jsonc?$/i.test(relative);
 }
 
+/**
+ * Map Google Antigravity write tools (PascalCase args) onto Claude Write/Edit/MultiEdit.
+ * @returns {{ toolName: string, toolInput: object }|null}
+ */
+function mapAntigravityToolCall(toolCall) {
+  if (!toolCall || typeof toolCall !== 'object') return null;
+  const name = toolCall.name ?? '';
+  const args = toolCall.args && typeof toolCall.args === 'object' ? toolCall.args : {};
+  const filePath = args.TargetFile ?? args.targetFile ?? args.file_path ?? args.path;
+  if (name === 'write_to_file') {
+    return {
+      toolName: 'Write',
+      toolInput: {
+        file_path: filePath,
+        content: args.CodeContent ?? args.codeContent ?? args.content ?? '',
+      },
+      operation: 'write_to_file',
+    };
+  }
+  if (name === 'replace_file_content') {
+    return {
+      toolName: 'Edit',
+      toolInput: {
+        file_path: filePath,
+        old_string: args.TargetContent ?? args.targetContent ?? args.old_string ?? '',
+        new_string: args.ReplacementContent ?? args.replacementContent ?? args.new_string ?? '',
+        replace_all: Boolean(args.AllowMultiple ?? args.allowMultiple),
+      },
+      operation: 'replace_file_content',
+    };
+  }
+  if (name === 'multi_replace_file_content') {
+    const chunks = Array.isArray(args.ReplacementChunks)
+      ? args.ReplacementChunks
+      : Array.isArray(args.replacementChunks)
+        ? args.replacementChunks
+        : [];
+    return {
+      toolName: 'MultiEdit',
+      toolInput: {
+        file_path: filePath,
+        edits: chunks.map((chunk) => ({
+          old_string: chunk?.TargetContent ?? chunk?.targetContent ?? chunk?.old_string ?? '',
+          new_string:
+            chunk?.ReplacementContent ?? chunk?.replacementContent ?? chunk?.new_string ?? '',
+          replace_all: Boolean(chunk?.AllowMultiple ?? chunk?.allowMultiple),
+        })),
+      },
+      operation: 'multi_replace_file_content',
+    };
+  }
+  return {
+    toolName: name,
+    toolInput: { ...args, file_path: filePath },
+    operation: name,
+  };
+}
+
 /**
  * Normalize agent PreToolUse payloads.
  * Claude Code: { tool_name, tool_input: { file_path, content | old_string/new_string } }
  * Grok Build:  { toolName, toolInput:  { file_path, content | old_string/new_string } }
  *              (aliases Write/Edit/MultiEdit → write/search_replace; matcher keeps both)
+ * Antigravity: { toolCall: { name, args: { TargetFile, CodeContent, … } } }
  */
 function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_HOOK_EVENT)) {
+  const antigravityStyle =
+    payload != null && typeof payload === 'object' && 'toolCall' in payload;
+  if (antigravityStyle) {
+    const mapped = mapAntigravityToolCall(payload.toolCall);
+    const filePath =
+      mapped?.toolInput?.file_path ??
+      mapped?.toolInput?.filePath ??
+      mapped?.toolInput?.path ??
+      mapped?.toolInput?.target_file;
+    return {
+      toolName: mapped?.toolName ?? '',
+      toolInput: { ...(mapped?.toolInput ?? {}), file_path: filePath },
+      grokStyle: true, // decision JSON on stdout (deny)
+      antigravityStyle: true,
+      operation: mapped?.operation ?? mapped?.toolName ?? null,
+    };
+  }
+
   const rawName = payload?.tool_name ?? payload?.toolName ?? '';
   const toolInput = payload?.tool_input ?? payload?.toolInput ?? {};
   const nameMap = {
@@ -194,6 +271,9 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
     MultiEdit: 'MultiEdit',
     ApplyPatch: 'ApplyPatch',
     apply_patch: 'ApplyPatch',
+    write_to_file: 'Write',
+    replace_file_content: 'Edit',
+    multi_replace_file_content: 'MultiEdit',
   };
   const toolName = nameMap[rawName] ?? rawName;
   const filePath =
@@ -205,6 +285,8 @@ function normalizeHookPayload(payload, grokHookEvent = Boolean(process.env.GROK_
     grokStyle:
       grokHookEvent ||
       (payload != null && typeof payload === 'object' && 'toolName' in payload),
+    antigravityStyle: false,
+    operation: null,
   };
 }
 
@@ -409,8 +491,14 @@ function processHookOutput() {
   };
 }
 
+/** Antigravity PreToolUse requires stdout `decision` on every response (allow included). */
+function emitAntigravityAllow(output, antigravityStyle) {
+  if (!antigravityStyle) return;
+  output.stdout(`${JSON.stringify({ decision: 'allow' })}\n`);
+}
+
 function runHookPayload(payload, gate, config, args, ts, attemptContext, output = processHookOutput()) {
-  const { toolName, toolInput, grokStyle } = normalizeHookPayload(
+  const { toolName, toolInput, grokStyle, antigravityStyle, operation } = normalizeHookPayload(
     payload,
     attemptContext?.grokHookEvent ?? Boolean(process.env.GROK_HOOK_EVENT)
   );
@@ -419,7 +507,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     const parsedPatch = codexPatchWrites(patch, args.root);
     // Codex ApplyPatch is only preflighted when Ark can reconstruct every file operation.
     // An incomplete reconstruction must not be mislabeled as atomic or hard enforcement.
-    if (!parsedPatch.complete) return;
+    if (!parsedPatch.complete) {
+      emitAntigravityAllow(output, antigravityStyle);
+      return;
+    }
     const patchWrites = parsedPatch.writes;
     const sourceWrites = patchWrites.filter((change) =>
       isGovernableSourceFile(path.basename(String(change.path)))
@@ -482,7 +573,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
             .join(', ')}; source-only virtual preflight cannot model those contents.`
         );
       }
-      if (changes.length === 0) return;
+      if (changes.length === 0) {
+        emitAntigravityAllow(output, antigravityStyle);
+        return;
+      }
       result = prepareChangeFromRoot({
         root: args.root,
         config,
@@ -537,7 +631,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     const designDelta = args.failOnNewSmells
       ? evaluateWriteDesignDelta({ root: args.root, config, changes, ts })
       : null;
-    if (result.valid && (designDelta?.valid ?? true)) return;
+    if (result.valid && (designDelta?.valid ?? true)) {
+      emitAntigravityAllow(output, antigravityStyle);
+      return;
+    }
     const message = [
       `Ark architecture gate blocked this complete ${toolName} (${changes.length} governed file(s)):`,
       ...result.diagnostics.map(
@@ -567,16 +664,27 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     return;
   }
   const filePath = toolInput.file_path;
-  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) return;
+  if (!['Write', 'Edit', 'MultiEdit'].includes(toolName)) {
+    // Non-file tools: fail-open. Antigravity still needs an explicit allow decision.
+    emitAntigravityAllow(output, antigravityStyle);
+    return;
+  }
   if (typeof filePath !== 'string' || !SOURCE_FILE.test(filePath) || filePath.endsWith('.d.ts')) {
+    emitAntigravityAllow(output, antigravityStyle);
     return;
   }
   const rel = path.relative(args.root, path.resolve(filePath));
   const segments = rel.split(path.sep);
-  if (segments[0] === '..' || segments.includes('node_modules')) return;
+  if (segments[0] === '..' || segments.includes('node_modules')) {
+    emitAntigravityAllow(output, antigravityStyle);
+    return;
+  }
 
   const source = proposedSource(toolName, toolInput);
-  if (typeof source !== 'string') return;
+  if (typeof source !== 'string') {
+    emitAntigravityAllow(output, antigravityStyle);
+    return;
+  }
 
   const layer = inferLayer(filePath, config, args.root);
   const validateOnce = (src) =>
@@ -611,7 +719,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
         ts,
       })
     : null;
-  if (result.valid && (designDelta?.valid ?? true)) return;
+  if (result.valid && (designDelta?.valid ?? true)) {
+    emitAntigravityAllow(output, antigravityStyle);
+    return;
+  }
 
   // Ratchet semantics (same philosophy as ark-check --baseline): an edit is blocked only
   // when it ADDS violations relative to the file's current on-disk state. Otherwise a
@@ -639,7 +750,10 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
     existingCounts.set(key, remaining - 1);
     return false;
   });
-  if (newViolations.length === 0 && (designDelta?.valid ?? true)) return;
+  if (newViolations.length === 0 && (designDelta?.valid ?? true)) {
+    emitAntigravityAllow(output, antigravityStyle);
+    return;
+  }
   const combinedViolations = [...newViolations, ...designDeltaViolations(designDelta)];
   const adapterResult = createAdapterResult({
     valid: false,
@@ -698,9 +812,21 @@ function runHookPayload(payload, gate, config, args, ts, attemptContext, output
       filePath: normalizedRel,
       enforcement: hookEnforcement(
         args.root,
-        attemptContext?.host ?? (grokStyle ? 'grok' : 'claude'),
+        attemptContext?.host ??
+          (antigravityStyle ? 'antigravity' : grokStyle ? 'grok' : 'claude'),
         attemptContext?.operation ??
-          (grokStyle ? (toolName === 'Edit' ? 'search_replace' : 'write') : toolName),
+          operation ??
+          (antigravityStyle
+            ? toolName === 'Edit'
+              ? 'replace_file_content'
+              : toolName === 'MultiEdit'
+                ? 'multi_replace_file_content'
+                : 'write_to_file'
+            : grokStyle
+              ? toolName === 'Edit'
+                ? 'search_replace'
+                : 'write'
+              : toolName),
         toolName === 'Write' || Boolean(attemptContext?.completePatch)
       ),
       ...(layer ? { layer } : {}),

package/bin/ark-shared.mjs

@@ -618,11 +618,98 @@ export function execCommandParts(root, bin, binArgs = []) {
   return { command: 'npx', args: [bin, ...binArgs] };
 }
 
+/**
+ * True when this directory is a pnpm workspace root (needs `pnpm add -w` for root deps).
+ * Nested packages under the workspace are not roots.
+ */
+export function isPnpmWorkspaceRoot(root) {
+  return fs.existsSync(path.join(root, 'pnpm-workspace.yaml'));
+}
+
+/**
+ * True when package.json declares npm/yarn workspaces (yarn classic needs `-W` at root).
+ */
+export function isNpmYarnWorkspaceRoot(root) {
+  const pkg = readPackageJson(root);
+  if (!pkg) return false;
+  const ws = pkg.workspaces;
+  return Array.isArray(ws) || (ws && typeof ws === 'object' && Array.isArray(ws.packages));
+}
+
+/**
+ * Normalize a version/range/spec into an installable package argument for arkgate.
+ * Accepts `latest`, `^3.8.2`, `arkgate@latest`, or a full package name.
+ */
+export function normalizeArkgateInstallSpec(versionSpec) {
+  const raw = typeof versionSpec === 'string' && versionSpec.trim() ? versionSpec.trim() : 'latest';
+  if (raw.startsWith('arkgate@') || raw === 'arkgate') return raw === 'arkgate' ? 'arkgate@latest' : raw;
+  if (raw.includes('/') || raw.startsWith('file:') || raw.startsWith('link:')) return raw;
+  return `arkgate@${raw}`;
+}
+
+/**
+ * Package-manager argv to add a dev dependency (e.g. arkgate@latest).
+ * pnpm workspace roots get `-w`; yarn classic workspaces get `-W`.
+ *
+ * @param {string} root
+ * @param {string} [versionSpec]  package name or name@version (default arkgate@latest)
+ * @returns {[string, string[]]}
+ */
+export function packageInstallArgv(root, versionSpec = 'latest') {
+  const pkgSpec = normalizeArkgateInstallSpec(versionSpec);
+  const pm = detectPackageManager(root);
+  if (pm === 'pnpm') {
+    const args = ['add', '-D', pkgSpec];
+    if (isPnpmWorkspaceRoot(root)) args.push('-w');
+    return ['pnpm', args];
+  }
+  if (pm === 'yarn') {
+    const args = ['add', '-D', pkgSpec];
+    if (isNpmYarnWorkspaceRoot(root)) args.push('-W');
+    return ['yarn', args];
+  }
+  return ['npm', ['install', '-D', pkgSpec]];
+}
+
+/**
+ * Whether an install of arkgate@latest can be skipped because node_modules already
+ * resolves the same version as this CLI package.
+ *
+ * @param {string} root
+ * @param {string} [cliVersion]  this binary's package version
+ * @returns {{ skip: boolean, installedVersion: string|null, reason: string }}
+ */
+export function shouldSkipArkgateInstall(root, cliVersion) {
+  const pkgPath = path.join(root, 'node_modules', 'arkgate', 'package.json');
+  if (!fs.existsSync(pkgPath)) {
+    return { skip: false, installedVersion: null, reason: 'not-installed' };
+  }
+  let installedVersion = null;
+  try {
+    installedVersion = JSON.parse(fs.readFileSync(pkgPath, 'utf8')).version ?? null;
+  } catch {
+    return { skip: false, installedVersion: null, reason: 'unreadable' };
+  }
+  if (
+    typeof cliVersion === 'string' &&
+    cliVersion &&
+    installedVersion &&
+    installedVersion === cliVersion
+  ) {
+    return { skip: true, installedVersion, reason: 'already-current' };
+  }
+  return { skip: false, installedVersion, reason: 'version-differs' };
+}
+
 /** Package-manager aware "install a dev dependency" hint (e.g. for a missing typescript). */
 export function installDevHint(root, pkg) {
   const pm = detectPackageManager(root);
-  if (pm === 'pnpm') return `pnpm add -D ${pkg}`;
-  if (pm === 'yarn') return `yarn add -D ${pkg}`;
+  if (pm === 'pnpm') {
+    return isPnpmWorkspaceRoot(root) ? `pnpm add -D ${pkg} -w` : `pnpm add -D ${pkg}`;
+  }
+  if (pm === 'yarn') {
+    return isNpmYarnWorkspaceRoot(root) ? `yarn add -D ${pkg} -W` : `yarn add -D ${pkg}`;
+  }
   return `npm install -D ${pkg}`;
 }
 

package/bin/ark.mjs

@@ -14,8 +14,10 @@ import {
   INIT_WIZARD_CHOICES,
   isValidArchetypeId,
   mapWizardChoiceToArchetype,
+  packageInstallArgv,
   resolveArchetypePreset,
   resolveOperatingMode,
+  shouldSkipArkgateInstall,
 } from './ark-shared.mjs';
 import { pinArkgateDevDependency, FALSE_GREEN_GAP_ID } from './lib/field-install.mjs';
 import { validateHardWriteRequest } from './lib/enforcement-profiles.mjs';
@@ -155,9 +157,9 @@ Options:
                (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    Add arkgate to package.json explicitly before applying a start plan.
+  --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 with --no-install.
+  --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.
@@ -189,20 +191,7 @@ function cliVersion() {
   }
 }
 
-// The package-manager command that adds arkgate as a dev dependency.
-// Prefer an explicit version/range when pin already chose one (avoid pin=^2.9.0 then
-// `npm i arkgate@latest` rewriting package.json to a different range).
-function packageInstallArgv(root, versionSpec) {
-  const range =
-    typeof versionSpec === 'string' && versionSpec.trim()
-      ? versionSpec.trim()
-      : 'latest';
-  const spec = range.startsWith('arkgate@') ? range : `arkgate@${range}`;
-  const pm = detectPackageManager(root);
-  if (pm === 'pnpm') return ['pnpm', ['add', '-D', spec]];
-  if (pm === 'yarn') return ['yarn', ['add', '-D', spec]];
-  return ['npm', ['install', '-D', spec]];
-}
+// packageInstallArgv is imported from ark-shared (workspace-aware -w / -W).
 
 function runCommand(command, commandArgs, cwd) {
   const result = spawnSync(command, commandArgs, { cwd, stdio: 'inherit', encoding: 'utf8' });
@@ -438,6 +427,32 @@ async function start(args) {
     if (!args.apply) return 0;
     applyStartPreview(args.root, preview);
     if (!args.json) console.log(`Applied ${preview.changes.length} previewed mutation(s).`);
+    // After applying exact preview bytes, install the pinned package when requested
+    // (preview itself never runs the package manager — field: start left pin without node_modules).
+    if (
+      args.install &&
+      !args.skipPackageManager &&
+      fs.existsSync(path.join(args.root, 'package.json'))
+    ) {
+      const skip = shouldSkipArkgateInstall(args.root, cliVersion());
+      if (!skip.skip) {
+        const [command, commandArgs] = packageInstallArgv(args.root, `^${cliVersion()}`);
+        if (!args.json) console.log(`Installing package: ${command} ${commandArgs.join(' ')}`);
+        // Keep stdout clean for --json consumers (package managers are chatty on stdout).
+        const status = args.json
+          ? (spawnSync(command, commandArgs, {
+              cwd: args.root,
+              stdio: ['ignore', 'pipe', 'pipe'],
+              encoding: 'utf8',
+            }).status ?? 1)
+          : runCommand(command, commandArgs, args.root);
+        if (status !== 0 && !args.json) {
+          console.log(
+            `Package manager exited ${status}. package.json is pinned; run the install command when online.`
+          );
+        }
+      }
+    }
     return 0;
   }
   const root = args.root;
@@ -492,7 +507,8 @@ async function start(args) {
     }
 
     // 2b) Pin arkgate as a project devDependency so CI/npx do not depend on a stale global.
-    if (args.installExplicit && args.install && fs.existsSync(path.join(root, 'package.json'))) {
+    // Default install=true; only --no-install skips. (installExplicit tracks user override for copy.)
+    if (args.install && fs.existsSync(path.join(root, 'package.json'))) {
       const { pinned, installStatus } = ensureProjectArkgateDependency(root, {
         install: true,
         runPackageManager: !args.skipPackageManager,
@@ -507,7 +523,7 @@ async function start(args) {
       } else if (pinned.reason === 'already-present') {
         console.log(`  arkgate already in package.json (${pinned.version}).`);
       }
-    } else if (args.installExplicit && args.install === false) {
+    } else if (!args.install) {
       console.log('  Skipping arkgate package pin (--no-install).');
     }
 
@@ -789,7 +805,13 @@ async function main() {
 
   if (args.command === 'upgrade' || args.command === 'update') {
     try {
-      return runUpgradeCommand(args, { arkCheck, packageInstallArgv, runArkCheck });
+      return runUpgradeCommand(args, {
+        arkCheck,
+        packageInstallArgv,
+        runArkCheck,
+        cliVersion: cliVersion(),
+        shouldSkipArkgateInstall,
+      });
     } catch (error) {
       console.error(error instanceof Error ? error.message : String(error));
       return 2;

package/bin/lib/agent-gates.mjs

@@ -23,10 +23,14 @@ export {
 
 export {
   PREFERRED_MCP_BIN,
+  antigravityHooks,
   claudeSettings,
   codexProjectConfig,
   grokHooks,
   grokProjectConfig,
+  mergeAntigravityArkHook,
+  mergeOpencodeArkMcp,
+  opencodeProjectConfig,
 } from './hook-templates.mjs';
 
 export { detectWritePathCapabilities } from './write-path-detect.mjs';

package/bin/lib/ci-and-commands.mjs

@@ -128,16 +128,13 @@ export function agentInstructions(root) {
 
 ## Default agent flow (if unsure, do only this)
 
-1. If \`ark.config.json\` is missing: run \`${startCmd}\` once.
-2. For adoption / cleanup / “make architecture sound”: run the **\`/ark-autopilot\`** skill
-   (explore first → dual plan: remediation + pattern bets → safe fixes → gates). Day-zero
-   origin is frozen by \`ark start\`/\`ark init\` (or autopilot if missing) **before** agent docs.
-   Do **not** invent a second architecture curriculum outside the routing table below — when a
-   trigger matches, use that skill; when unsure, stay on autopilot.
-3. Status anytime: \`${doctorCmd}\` (status light + next action — not a mode picker).
-4. After ordinary feature edits: run \`${checkCmd}\`. On violations → **\`/ark-fix\`** (or
-   \`/ark-place\` for new files, \`/ark-contract\` only if the contract itself is wrong).
+1. Status anytime: \`${doctorCmd}\` — **control plane** (one status light, one next action; not a mode picker).
+2. If \`ark.config.json\` is missing: run \`${startCmd}\` once (preview), then \`${startCmd} --apply\`.
+3. Guided end-to-end work (“make architecture sound”): **\`/ark-autopilot\`** — explore → dual plan A (edges) + B (shape) → mechanical-safe fixes; B only with user OK. Day-zero origin is frozen by \`ark start\`/\`ark init\` (or autopilot if missing) **before** agent docs.
+4. After ordinary feature edits: run \`${checkCmd}\`. On violations → **\`/ark-fix\`** (or \`/ark-place\` for new files, \`/ark-contract\` only if the contract itself is wrong).
 
+Do **not** skill-shop the full table for routine work. When unsure, do doctor top action #1 only
+(re-run doctor after). Do **not** jump to \`/ark-autopilot\` unless #1 or a STOP handoff names it.
 Skills are **dual-engine**: deterministic CLI sensors + exploratory read of *this* repo — not JSON-only wrappers.
 When a skill says **STOP — do not continue this skill as complete**, stop and invoke the named handoff skill.
 
@@ -151,14 +148,16 @@ scouts (disjoint path scopes) and merge in the parent. If the host does **not**,
 **fall back to sequential** — one cluster/step at a time. Never parallel-write the same
 files; never weaken the gate via subagents.
 
-## Skill routing (triggers → skill)
+## Skill routing (expert depth — triggers → skill)
 
-Do **not** run overlapping skills for the same job. Pick **one** primary skill from the table.
+**Escapes, not a second curriculum.** Do **not** run overlapping skills for the same job.
+Pick **one** primary skill. Prefer doctor top action #1 when unsure.
 
 | When | Invoke | Not this |
 |------|--------|----------|
-| Unsure / make architecture sound (apply path) | **/ark-autopilot** (default) | explore-only, coverage-only |
-| **Messy / spaghetti / design-weak after green / clarify for AI** | **Single path:** \`/ark-explore\` shape-focus → dual-plan B, then \`/ark-autopilot\` only to apply B with OK | coverage, think, loop-as-done, skill-shopping |
+| Unsure what to do next | **Doctor top action #1** (\`${doctorCmd}\`), then re-run doctor | skill-shopping, defaulting to autopilot |
+| Make architecture sound (guided apply path) | **/ark-autopilot** | explore-only, coverage-only |
+| **Messy / spaghetti / design-weak after green / Shape residual** | **Single path:** \`/ark-explore\` shape-focus → dual-plan B, then \`/ark-autopilot\` only to apply B with OK | coverage, think, loop-as-done, skill-shopping |
 | Map / residual / dual-plan seed only (no apply, already know you want recon) | \`/ark-explore\` | coverage (fitness only) |
 | Greenfield shape / empty tree | \`/ark-architect\` | adopt |
 | Brownfield / wrong contract / false-green | \`/ark-adopt\` then \`/ark-contract\` if globs wrong | architect |
@@ -209,20 +208,28 @@ export function compactAgentInstructions(root, host = null) {
     'ark-check',
     `--install-agent-gates --skills-only --tools ${selectedHost === 'none' ? '<host>' : selectedHost}`
   );
+  // Progressive disclosure: primary path only. Full /ark-* catalog is expert depth
+  // (install via --skills-only). See docs/product-voice.md.
   return `# Ark Enforcement
 
 <!-- arkgate:compact-router host=${selectedHost} -->
 ## Compact router
 
-This project uses the ArkGate package and its \`ark\` MCP resources as its one
-agent router. Before editing TypeScript or JavaScript, read \`ark://manifest\`
-when available; use \`ark_place\` for new files and \`validate_code\` after edits.
-If MCP is unavailable, inspect \`ark.config.json\` and run \`${checkCmd}\`.
+**Primary path (do this):**
 
-For architecture status, run \`${doctorCmd}\`. The selected host is
-\`${selectedHost}\`; its host registration and CI gate are installed alongside
-this file. Full \`/ark-*\` guided workflows are optional and can be added later
-with \`${installSkills}\`.
+1. Status anytime: \`${doctorCmd}\` — one status light, one next action (control plane).
+2. Day to day: read \`ark://manifest\` when MCP is available; place new files with \`ark_place\`; validate after edits; run \`${checkCmd}\`. On a gate deny, fix the architecture — do not weaken the contract.
+3. If MCP is unavailable: inspect \`ark.config.json\` and run \`${checkCmd}\`.
+
+The selected host is \`${selectedHost}\`. Host registration and CI are installed with this file.
+This compact router is enough for normal feature work.
+
+## Expert depth (optional)
+
+Full \`/ark-*\` skills (including guided end-to-end \`/ark-autopilot\`) are **not** the default
+curriculum. Install them only when doctor top action #1 or a STOP handoff names a skill:
+
+\`${installSkills}\`
 `;
 }