forge-workflow 0.0.10 → 0.1.0-beta.3

package/lib/commands/setup.js

@@ -13,30 +13,51 @@ const fs = require('node:fs');
 const os = require('node:os');
 const path = require('node:path');
 const readline = require('node:readline');
-const { execSync, execFileSync } = require('node:child_process');
+const { execSync } = require('node:child_process');
 
-// Compute packageDir relative to this file (lib/commands/setup.js -> project root)
+// Compute packageDir relative to this file (lib/commands/setup.js -> project root).
+// packageDir stays a runtime value for asset copying; requires use static
+// relative paths so `bun build --compile` can bundle the module graph.
 const packageDir = path.resolve(__dirname, '..', '..');
-const packageJson = require(path.join(packageDir, 'package.json'));
+const packageJson = require('../../package.json');
 const VERSION = packageJson.version;
 
+// Dual-channel asset root. Under npm/npx this returns `packageDir` unchanged;
+// inside a `bun build --compile` binary it lazily extracts the embedded runtime
+// assets (skills/rules/docs/hooks/scripts) to a temp dir and returns that. Every
+// packaged-ASSET read below goes through `getPackageRoot(packageDir)`; the
+// module-`require` paths above keep `packageDir` (bundler handles those).
+const { getPackageRoot } = require('../package-root');
+
 // Load PluginManager for discoverable agent architecture
 const PluginManager = require('../plugin-manager');
-const { scaffoldGithubBeadsSync } = require('../setup');
+const { populateAgentSkills, listCanonicalSkills, listFilesRecursive } = require('../skills-sync');
+const { renderMcpConfig } = require('../mcp-config-renderer');
+const { renderClaudePermissions, renderCursorIgnore } = require('../safety-config-renderer');
+const { renderHookConfig } = require('../hook-renderer');
 const { copyEssentialDocs } = require('../docs-copy');
+
+// Baseline MCP server Forge ships. Uses the generic descriptor contract consumed
+// by lib/mcp-config-renderer.js (envRefs are '${VAR}' references, never secrets).
+const CONTEXT7_MCP_DESCRIPTOR = {
+  name: 'context7',
+  transport: 'stdio',
+  command: 'npx',
+  args: ['-y', '@upstash/context7-mcp@latest'],
+  envRefs: {},
+};
 const { secureExecFileSync } = require('../shell-utils');
 const { askYesNo: _askYesNoBase } = require('../ui-utils');
 
-// Load enhanced onboarding modules
-const contextMerge = require(path.join(packageDir, 'lib', 'context-merge'));
-const projectDiscovery = require(path.join(packageDir, 'lib', 'project-discovery'));
+// Load enhanced onboarding modules (static relative requires — bundleable)
+const contextMerge = require('../context-merge');
+const projectDiscovery = require('../project-discovery');
 
 // Load lib modules for symlink, beads, and PAT setup
-const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require(path.join(packageDir, 'lib', 'symlink-utils'));
-const beadsSetupLib = require(path.join(packageDir, 'lib', 'beads-setup'));
-const { beadsHealthCheck } = require(path.join(packageDir, 'lib', 'beads-health-check'));
-const { setupPAT } = require(path.join(packageDir, 'lib', 'pat-setup'));
-const { DEFAULT_BEADS_VERSION, detectDefaultBranch, templateWorkflows, scaffoldBeadsSync } = require(path.join(packageDir, 'lib', 'beads-sync-scaffold'));
+const { createSymlinkOrCopy: libCreateSymlinkOrCopy } = require('../symlink-utils');
+const { scaffoldBeadsSync } = require('../beads-sync-scaffold');
+const { resolveSyncBackend } = require('../sync-backend');
+const { buildMigratedKernelIssueDeps } = require('../kernel/cli-broker-factory');
 
 // Load incremental setup modules
 const { detectEnvironment } = require('../detect-agent');
@@ -46,18 +67,25 @@ const { ActionCollector } = require('../setup-utils');
 const { renderSetupSummary } = require('../setup-summary-renderer');
 const { smartMergeAgentsMd } = require('../smart-merge');
 const { checkLefthookStatus } = require('../lefthook-check');
+const {
+  FORGE_USER_LEFTHOOK_YML,
+  forgeShouldWriteLefthookConfig,
+  installNativeGitHooks,
+  verifyHooksActive,
+  resolveGitHooksDir,
+} = require('../lefthook-wiring');
 const { resolveShellRuntime } = require('../runtime-health');
 const {
   buildCodexSkillInstallPlan,
   formatCodexSkillsInstallDir,
   listCodexSkillEntries,
+  populateCodexRepoSkills,
+  CODEX_REPO_SKILLS_DIR,
 } = require('../codex-skills');
 const {
-  generateCopilotConfig,
   generateCursorConfig,
-  generateKiloConfig,
-  generateOpenCodeConfig,
 } = require('../agents-config');
+const initCommand = require('./init');
 const fileUtils = require('../file-utils');
 const detectionUtils = require('../detection-utils');
 const { detectHusky, migrateHusky } = require('../husky-migration');
@@ -76,6 +104,11 @@ let actionLog = new SetupActionLog();
 let PKG_MANAGER = 'npm';
 let SETUP_NOTES = [];
 let CODEX_SETUP_REPORT = null;
+// Tracks whether the last ensureKernelIssueStore() run provisioned the store.
+// The setup summary reads this so a provisioning failure isn't masked by a
+// hardcoded "✓ Kernel issue store" line. Defaults true: when the ensure step
+// never ran, the kernel still auto-provisions on first use.
+let KERNEL_STORE_READY = true;
 
 /**
  * Load agent definitions from plugin architecture
@@ -96,7 +129,8 @@ function loadAgentsFromPlugins() {
       supportStatus: plugin.support?.status || 'supported',
       needsConversion: plugin.setup?.needsConversion || false,
       copyCommands: plugin.setup?.copyCommands || false,
-      promptFormat: plugin.setup?.promptFormat || false
+      promptFormat: plugin.setup?.promptFormat || false,
+      skillsDir: plugin.directories?.skills || null
     };
   });
   return agents;
@@ -138,29 +172,6 @@ function detectPackageManager() {
   return 'npm';
 }
 
-/**
- * Reads workflow command names from commands/*.md in the package directory.
- * Falls back to .claude/commands/ if commands/ does not exist (backwards compat).
- * @returns {string[]} Command names (filenames without .md extension)
- */
-function getWorkflowCommands() {
-  const canonicalDir = path.join(packageDir, 'commands');
-  const commandsDir = fs.existsSync(canonicalDir)
-    ? canonicalDir
-    : path.join(packageDir, '.claude', 'commands');
-  try {
-    return fs.readdirSync(commandsDir)
-      .filter(f => f.endsWith('.md'))
-      .map(f => f.replace(/\.md$/, ''));
-  } catch (err) {
-    if (err.code === 'ENOENT') {
-      console.warn(`Warning: commands directory not found at ${commandsDir}`);
-    } else {
-      console.warn(`Warning: failed to read commands — ${err.code}: ${err.message}`);
-    }
-    return [];
-  }
-}
 
 const WORKFLOW_RUNTIME_ASSETS = Object.freeze([
   'scripts/beads-context.sh',
@@ -184,7 +195,7 @@ const WORKFLOW_RUNTIME_ASSETS = Object.freeze([
   'scripts/forge-team/lib/sync-github.sh',
   'scripts/forge-team/lib/verify.sh',
   'scripts/forge-team/lib/workload.sh',
-  '.claude/scripts/greptile-resolve.sh'
+  '.claude/scripts/review-resolve.sh'
 ]);
 
 /**
@@ -205,112 +216,11 @@ function validateAgents(agentList) {
   return valid;
 }
 
-function parseDoltRemoteNames(remoteListOutput) {
-  const output = String(remoteListOutput || '').trim();
-  if (!output || /^No remotes configured\.?$/i.test(output)) {
-    return [];
-  }
-
-  return output
-    .split(/\r?\n/)
-    .map(line => line.trim())
-    .filter(Boolean)
-    .map(line => line.split(/\s+/)[0])
-    .filter(Boolean);
-}
-
-function readBeadsSyncRemoteConfig(projectDir = projectRoot) {
-  const jsonConfigPath = path.join(projectDir, '.beads', 'config.json');
-  if (fs.existsSync(jsonConfigPath)) {
-    try {
-      const parsed = JSON.parse(fs.readFileSync(jsonConfigPath, 'utf8'));
-      if (typeof parsed.sync_remote === 'string' && parsed.sync_remote.trim()) {
-        return parsed.sync_remote.trim();
-      }
-    } catch (_error) {
-      // Ignore malformed config and fall back to other sources.
-    }
-  }
-
-  const yamlConfigPath = path.join(projectDir, '.beads', 'config.yaml');
-  if (fs.existsSync(yamlConfigPath)) {
-    const configuredRemote = parseBeadsYamlSyncRemote(fs.readFileSync(yamlConfigPath, 'utf8'));
-    if (configuredRemote) {
-      return configuredRemote;
-    }
-  }
-
-  return '';
-}
-
-function parseBeadsYamlSyncRemote(content) {
-  for (const rawLine of String(content || '').split(/\r?\n/)) {
-    const trimmedLine = rawLine.trimStart();
-    if (!trimmedLine.startsWith('sync-remote:')) {
-      continue;
-    }
-
-    const rawValue = trimmedLine.slice('sync-remote:'.length).trim();
-    if (!rawValue) {
-      return '';
-    }
-
-    const quote = rawValue[0];
-    if ((quote === '"' || quote === '\'') && rawValue.length > 1) {
-      const closingQuoteIndex = rawValue.indexOf(quote, 1);
-      if (closingQuoteIndex > 1) {
-        return rawValue.slice(1, closingQuoteIndex).trim();
-      }
-    }
-
-    const commentIndex = rawValue.indexOf('#');
-    const unquotedValue = commentIndex === -1 ? rawValue : rawValue.slice(0, commentIndex);
-    return unquotedValue.trim();
-  }
-
-  return '';
-}
-
-function resolveExpectedBeadsRemote(options = {}) {
-  const projectDir = options.projectDir || projectRoot;
-  const env = options.env || process.env;
-  const configuredRemote = readBeadsSyncRemoteConfig(projectDir);
-  if (configuredRemote) {
-    return configuredRemote;
-  }
-
-  if (typeof env.BD_SYNC_REMOTE === 'string' && env.BD_SYNC_REMOTE.trim()) {
-    return env.BD_SYNC_REMOTE.trim();
-  }
-
-  const gitRemoteProbe = options.gitRemoteProbe
-    || ((remoteName) => safeExec(`git -C "${projectDir}" remote get-url ${remoteName}`));
-  if (gitRemoteProbe('upstream')) {
-    return 'upstream';
-  }
-
-  return 'origin';
-}
-
-function hasBeadsDoltRemote(commandRunner, remoteName = 'origin') {
-  const output = commandRunner('bd dolt remote list');
-  if (!output) {
-    return null;
-  }
-
-  return parseDoltRemoteNames(output).includes(remoteName);
-}
-
 // Prerequisite check function
 function checkPrerequisites(options = {}) {
   const requireGithubCli = options.requireGithubCli !== false;
   const requireBeadsCli = options.requireBeadsCli === true;
   const requireJq = options.requireJq === true;
-  const expectedBeadsRemote = options.expectedBeadsRemote || resolveExpectedBeadsRemote({
-    env: options.env,
-    gitRemoteProbe: options.gitRemoteProbe,
-    projectDir: options.projectDir,
-  });
   const commandRunner = options.commandRunner || safeExec;
   const errors = [];
   const warnings = [];
@@ -346,25 +256,15 @@ function checkPrerequisites(options = {}) {
     }
   }
 
-  const bdVersion = commandRunner('bd --version');
-  if (bdVersion) {
-    console.log(`  ✓ ${bdVersion.split('\n')[0]}`);
-    if (requireBeadsCli) {
-      const hasRemote = hasBeadsDoltRemote(commandRunner, expectedBeadsRemote);
-      if (hasRemote === false) {
-        warnings.push(
-          `Beads Dolt remote '${expectedBeadsRemote}' is not configured. ` +
-          `Sync will remain local until you run: bd dolt remote add ${expectedBeadsRemote} <url>`
-        );
-      } else if (hasRemote === null) {
-        warnings.push(
-          `Unable to inspect Beads Dolt remotes. ` +
-          `Sync may remain local until '${expectedBeadsRemote}' is configured and bd dolt remote list succeeds.`
-        );
-      }
+  if (requireBeadsCli) {
+    // Issue tracking runs on the local Forge Kernel store, which auto-provisions
+    // on first use — there is no external CLI to install. Surface only whether
+    // team sync is wired up yet.
+    if (resolveSyncBackend({ projectRoot, env: options.env }) === 'local-noop') {
+      console.log('  ✓ Kernel issue store (local-noop sync: single-machine until a sync server is configured)');
+    } else {
+      console.log('  ✓ Kernel issue store');
     }
-  } else if (requireBeadsCli) {
-    errors.push('bd (Beads CLI) - Install from https://github.com/steveyegge/beads');
   }
 
   // Check Node.js version
@@ -379,7 +279,11 @@ function checkPrerequisites(options = {}) {
   if (jqVersion) {
     console.log(`  ✓ ${jqVersion.split('\n')[0]}`);
   } else if (requireJq) {
-    errors.push('jq - Install from https://jqlang.org/download/');
+    // jq is optional at setup time. Some workflow helper scripts shell out to jq,
+    // but they degrade or defer when it is absent — a clean box (esp. Windows)
+    // must not abort setup just because jq is not installed yet. Surface a
+    // warning instead of a fatal error (kernel issue 01468e44).
+    warnings.push('jq not found - some workflow helper scripts will be skipped until you install it (https://jqlang.org/download/)');
   }
 
   // Detect package manager
@@ -405,60 +309,121 @@ function checkPrerequisites(options = {}) {
   console.log('');
   console.log(`  Package manager: ${PKG_MANAGER}`);
 
-  return { errors, warnings };
+  // Return a structured result so embedding agents can inspect prerequisite
+  // state instead of only observing a process exit. Genuinely-fatal prereqs
+  // (git, node version, required gh) still hard-exit above; soft prereqs like
+  // jq surface via `warnings` while `ok` stays true.
+  return { errors, warnings, ok: errors.length === 0 };
 }
 
-function requiresGithubCliForSetup(selectedAgents, options = {}) {
-  return needsWorkflowRuntimeAssets(selectedAgents) || options.syncEnabled === true;
+function requiresGithubCliForSetup(selectedAgents) {
+  return needsWorkflowRuntimeAssets(selectedAgents);
 }
 
-// Universal SKILL.md content
-const SKILL_CONTENT = `---
-name: forge-workflow
-description: 7-stage TDD-first workflow for feature development. Use when building features, fixing bugs, or shipping PRs.
-category: Development Workflow
-tags: [tdd, workflow, pr, git, testing]
-tools: [Bash, Read, Write, Edit, Grep, Glob]
----
-
-# Forge Workflow Skill
-
-A TDD-first workflow for AI coding agents. Ship features with confidence.
-
-## When to Use
-
-Automatically invoke this skill when the user wants to:
-- Build a new feature
-- Fix a bug
-- Create a pull request
-- Run the development workflow
-
-## 7 Stages
-
-| Stage | Command | Description |
-|-------|---------|-------------|
-| utility | \`/status\` | Check current context, active work, recent completions |
-| 1 | \`/plan\` | Design intent -> research -> branch + worktree + task list |
-| 2 | \`/dev\` | TDD development (implementer -> spec review -> quality review) |
-| 3 | \`/validate\` | Type check, lint, security, tests - all fresh output |
-| 4 | \`/ship\` | Push branch and create PR with full documentation |
-| 5 | \`/review\` | Address ALL PR feedback (GitHub Actions, Greptile, SonarCloud) |
-| 6 | \`/premerge\` | Update docs, hand off PR to user |
-| 7 | \`/verify\` | Post-merge health check (CI on main, close Beads) |
+/**
+ * After agent setup, `.forge/config.yaml` may not exist yet — only the
+ * --minimal/--standard/--full routes run `forge init`. Point the user at
+ * `forge init` so first-run always ends with a clear next step that creates
+ * the workflow config (gates + change classification). No-op when the config
+ * already exists (kernel issue 5bdc91d3).
+ */
+function printForgeInitNextStep() {
+  const configPath = path.join(projectRoot, '.forge', 'config.yaml');
+  if (fs.existsSync(configPath)) {
+    return;
+  }
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('▶  NEXT: run `forge init` to configure your workflow');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log('  forge init   # creates .forge/config.yaml');
+  console.log('');
+  console.log('  Sets up workflow gates and change classification.');
+  console.log('  Safe to re-run (existing config is preserved).');
+  console.log('');
+}
 
-## Workflow Flow
+/**
+ * One-step onboarding (kernel issue ac0b38c7): a fresh `forge setup` used to end
+ * by telling the user to ALSO run `forge init`. Instead, run init's real handler
+ * here (standard profile, non-interactive) so setup finishes with a working
+ * `.forge/config.yaml` in one command. No-op when config already exists; on any
+ * init failure fall back to the printed `forge init` guidance so setup never
+ * hard-fails. `forge init` stays fully usable standalone. Inject `runInit` for
+ * tests.
+ */
+async function finalizeWorkflowConfig(options = {}) {
+  const configPath = path.join(projectRoot, '.forge', 'config.yaml');
+  if (fs.existsSync(configPath)) {
+    return;
+  }
+  const skipSideEffects = options.hooksAlreadyInstalled === true;
+  const runInit = options.runInit || defaultRunInit;
+  try {
+    const result = await runInit(projectRoot, skipSideEffects);
+    if (!result || result.success === false) {
+      printForgeInitNextStep();
+      return;
+    }
+    console.log('');
+    console.log('✓ Workflow configured: .forge/config.yaml (standard profile)');
+    console.log('  Change it anytime: forge init --profile <minimal|standard|full> --force');
+    console.log('');
+  } catch (err) {
+    console.warn(`Warning: automatic workflow init skipped: ${err.message}`);
+    printForgeInitNextStep();
+  }
+}
 
-\`\`\`
-/status -> /plan -> /dev -> /validate -> /ship -> /review -> /premerge -> /verify
-\`\`\`
+/**
+ * Default init runner for finalizeWorkflowConfig. When `skipSideEffects` is set
+ * (setup paths that already installed git hooks), pass no-op deps so init only
+ * writes `.forge/config.yaml` instead of re-doing that work — avoids duplicate
+ * side effects and warning noise (CodeRabbit on PR #368).
+ */
+function defaultRunInit(root, skipSideEffects) {
+  const deps = skipSideEffects
+    ? { installHooks: () => {} }
+    : {};
+  return initCommand.handler(['--yes'], {}, root, deps);
+}
 
-## Core Principles
+/**
+ * Guard against silent data loss when a non-interactive setup path overwrites
+ * an existing AGENTS.md that predates Forge's USER/FORGE merge markers. Old
+ * hand-edited files have no markers, so a plain copy would clobber them with no
+ * way to recover. Before that happens, snapshot the file to AGENTS.md.bak and
+ * warn (kernel issue a5399f3d). Returns true when a backup was written.
+ */
+function backupMarkerlessAgentsMd() {
+  const agentsPath = path.join(projectRoot, 'AGENTS.md');
+  if (!fs.existsSync(agentsPath)) {
+    return false;
+  }
+  const existingContent = fs.readFileSync(agentsPath, 'utf8');
+  const hasUserMarkers = existingContent.includes('<!-- USER:START');
+  const hasForgeMarkers = existingContent.includes('<!-- FORGE:START');
+  if (hasUserMarkers || hasForgeMarkers) {
+    return false;
+  }
+  // Never clobber an earlier snapshot: keep the original AGENTS.md.bak stable
+  // and fall back to numbered AGENTS.md.bak.1, .2, ... so a repeated markerless
+  // overwrite (e.g. re-running --quick after markers were stripped) preserves
+  // every prior backup instead of losing it (CodeRabbit review on PR #300).
+  let backupPath = path.join(projectRoot, 'AGENTS.md.bak');
+  if (fs.existsSync(backupPath)) {
+    let suffix = 1;
+    while (fs.existsSync(path.join(projectRoot, `AGENTS.md.bak.${suffix}`))) {
+      suffix += 1;
+    }
+    backupPath = path.join(projectRoot, `AGENTS.md.bak.${suffix}`);
+  }
+  fs.writeFileSync(backupPath, existingContent, 'utf8');
+  console.log(`  ⚠ Existing AGENTS.md has no Forge markers - backed up to ${path.basename(backupPath)} before overwrite`);
+  return true;
+}
 
-- **TDD-First**: Write tests BEFORE implementation (RED-GREEN-REFACTOR)
-- **Research-First**: Understand before building, document decisions
-- **Security Built-In**: OWASP Top 10 analysis for every feature
-- **Documentation Progressive**: Update at each stage, verify at end
-`;
 
 // Helper functions
 
@@ -472,10 +437,6 @@ function ensureDir(dir) {
 
 
 
-function writeFile(filePath, content) {
-  return fileUtils.writeFile(filePath, content, projectRoot);
-}
-
 function writeManagedAbsoluteFile(absolutePath, content, displayPath) {
   try {
     if (!FORCE_MODE && fileMatchesContent(absolutePath, content)) {
@@ -500,13 +461,10 @@ function writeManagedAbsoluteFile(absolutePath, content, displayPath) {
 
 
 
-function readFile(filePath) {
-  return fileUtils.readFile(filePath);
-}
-
 function resetSetupNotes() {
   SETUP_NOTES = [];
   CODEX_SETUP_REPORT = null;
+  KERNEL_STORE_READY = true;
 }
 
 function addSetupNote(message) {
@@ -579,7 +537,7 @@ function copyFile(src, dest) { // NOSONAR — Extracted as-is from bin/forge.js;
 function needsWorkflowRuntimeAssets(selectedAgents) {
   return selectedAgents.some((agentKey) => {
     const agent = AGENTS[agentKey];
-    return Boolean(agent && (agent.hasCommands || agent.needsConversion || agent.copyCommands || agent.promptFormat));
+    return Boolean(agent && (agent.hasCommands || agent.hasSkill || agent.needsConversion || agent.copyCommands || agent.promptFormat));
   });
 }
 
@@ -618,7 +576,7 @@ function scaffoldWorkflowRuntimeAssets(selectedAgents) {
   }
 
   for (const relativePath of WORKFLOW_RUNTIME_ASSETS) {
-    const sourcePath = path.join(packageDir, relativePath);
+    const sourcePath = path.join(getPackageRoot(packageDir), relativePath);
     copyFile(sourcePath, relativePath);
   }
 
@@ -722,13 +680,40 @@ function resolveWorkflowShellPolicy(selectedAgents, options = {}) {
   };
 }
 
+/**
+ * Print install guidance when Git Bash is absent on Windows. Kept separate so
+ * the graceful-degrade branch in ensureWorkflowShellPolicy stays trivial.
+ */
+function printGitBashGuidance(shellPolicy) {
+  console.log('');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('⚠  Git Bash not found — continuing in reduced-capability mode');
+  console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+  console.log('');
+  console.log(`  ${shellPolicy.message || 'Git Bash is required on Windows for helper-backed flows.'}`);
+  console.log('');
+  console.log('  Core setup will finish. The shell scripts behind some /plan, /ship,');
+  console.log('  and /review helper steps are UNAVAILABLE until Git Bash is installed.');
+  console.log('  Agent slash-skills and typeable `forge` CLI verbs keep working.');
+  console.log('');
+  console.log('  Install Git Bash: https://git-scm.com/download/win');
+  console.log('  Then re-run `forge setup` to re-enable helper-backed flows.');
+  console.log('');
+}
+
 function ensureWorkflowShellPolicy(selectedAgents, options = {}) {
   const shellPolicy = resolveWorkflowShellPolicy(selectedAgents, options);
 
-  if (shellPolicy.required && shellPolicy.platform === 'win32' && !shellPolicy.available) {
-    throw new Error(
-      shellPolicy.message || 'Git Bash is required on Windows for Forge workflow helper scripts.'
-    );
+  const gitBashMissing = shellPolicy.required
+    && shellPolicy.platform === 'win32'
+    && !shellPolicy.available;
+
+  if (gitBashMissing) {
+    // Graceful degrade (kernel issue 048c1e6d): a Windows newcomer without Git
+    // Bash must not be dead on arrival. Print install guidance and continue in a
+    // reduced-capability mode instead of hard-throwing and aborting all of setup.
+    printGitBashGuidance(shellPolicy);
+    return { ...shellPolicy, available: false, degraded: true };
   }
 
   return shellPolicy;
@@ -756,16 +741,11 @@ function createSymlinkOrCopy(source, target, options = {}) {
 }
 
 function shouldLinkAgentsMd(agent) {
-  if (!agent?.linkFile) return false;
-  return !['copilot', 'opencode'].includes(agent.customSetup);
+  return Boolean(agent?.linkFile);
 }
 
 
 
-function stripFrontmatter(content) {
-  return fileUtils.stripFrontmatter(content);
-}
-
 // Read existing .env.local
 
 
@@ -813,17 +793,17 @@ async function detectProjectStatus() {
     type: 'fresh', // 'fresh', 'upgrade', or 'partial'
     hasAgentsMd: fs.existsSync(path.join(projectRoot, 'AGENTS.md')),
     hasClaudeMd: fs.existsSync(path.join(projectRoot, 'CLAUDE.md')),
-    hasClaudeCommands: fs.existsSync(path.join(projectRoot, '.claude/commands')),
     hasEnvLocal: fs.existsSync(path.join(projectRoot, '.env.local')),
     existingEnvVars: {},
     agentsMdSize: 0,
     claudeMdSize: 0,
     agentsMdLines: 0,
     claudeMdLines: 0,
-    // Project tools status
-    hasBeads: isBeadsInitialized(),
+    // Project tools status — the Kernel issue store is always present (it
+    // auto-provisions on first use), so issue tracking needs no install probe.
+    hasBeads: true,
     hasSkills: isSkillsInitialized(),
-    beadsInstallType: checkForBeads(),
+    beadsInstallType: 'kernel',
     skillsInstallType: checkForSkills(),
     // Enhanced: Auto-detected project context
     autoDetected: null
@@ -847,9 +827,9 @@ async function detectProjectStatus() {
   }
 
   // Determine installation type
-  if (status.hasAgentsMd && status.hasClaudeCommands) {
+  if (status.hasAgentsMd) {
     status.type = 'upgrade'; // Full forge installation exists
-  } else if (status.hasClaudeCommands || status.hasEnvLocal) {
+  } else if (status.hasEnvLocal) {
     status.type = 'partial'; // Agent-specific files exist (not just base files from postinstall)
   }
   // else: 'fresh' - new installation (or just postinstall baseline with AGENTS.md)
@@ -1544,24 +1524,13 @@ function displayMcpStatus(selectedAgents) {
   console.log('Provides up-to-date library docs for AI coding agents.');
   console.log('');
 
-  // Show what was/will be auto-installed
+  // Show what was/will be auto-installed. Both Claude and Cursor read a
+  // project-local MCP config, so Forge auto-wires both (no manual step needed).
   if (selectedAgents.includes('claude')) {
     console.log('  ✓ Auto-installed for Claude Code (.mcp.json)');
   }
-  // Show manual setup instructions for GUI-based agents
-  const manualMcpMap = {
-    cursor: 'Cursor: Configure via Cursor Settings > MCP',
-    cline: 'Cline: Install via MCP Marketplace',
-  };
-  const needsManualMcp = Object.entries(manualMcpMap)
-    .filter(([key]) => selectedAgents.includes(key))
-    .map(([, msg]) => msg);
-
-  if (needsManualMcp.length > 0) {
-    needsManualMcp.forEach(msg => console.log(`  ! ${msg}`));
-    console.log('');
-    console.log('  Package: @upstash/context7-mcp@latest');
-    console.log('  Docs: https://github.com/upstash/context7-mcp');
+  if (selectedAgents.includes('cursor')) {
+    console.log('  ✓ Auto-installed for Cursor (.cursor/mcp.json)');
   }
 }
 
@@ -1640,39 +1609,6 @@ async function configureExternalServices(rl, question, selectedAgents = [], proj
   const { added, preserved } = writeEnvTokens(tokens, true);
   displayEnvTokenResults(added, preserved);
 
-  // GitHub-Beads issue sync setup
-  console.log('');
-  const enableSync = await askYesNo(question, 'Enable GitHub ↔ Beads issue sync?', true);
-  if (enableSync) {
-    try {
-      const result = await scaffoldGithubBeadsSync(projectRoot, packageDir);
-      for (const f of result.created) {
-        console.log(`  Created: ${f}`);
-      }
-      for (const f of result.skipped) {
-        console.log(`  Skipped: ${f} (already exists)`);
-      }
-
-      // PAT setup guidance for Beads sync (non-fatal)
-      // Skip if --sync flag is set — handleSyncScaffold will handle PAT setup
-      if (!SYNC_ENABLED) {
-        try {
-          const patResult = setupPAT(projectRoot, { interactive: !NON_INTERACTIVE });
-          if (patResult.success) {
-            console.log('  ✓ Beads sync PAT configured');
-          } else if (patResult.reminder) {
-            console.log(`  ℹ ${patResult.reminder}`);
-          } else if (patResult.instructions) {
-            console.log(`  ℹ ${patResult.instructions.split('\n')[0]}`);
-          }
-        } catch (_patErr) { // NOSONAR — best-effort PAT setup, non-fatal
-          // PAT setup is best-effort — don't block sync scaffold
-        }
-      }
-    } catch (err) {
-      console.error(`  Error scaffolding GitHub-Beads sync: ${err.message}`);
-    }
-  }
 }
 
 // Display the Forge banner
@@ -1724,7 +1660,7 @@ function setupCoreDocs() {
   // TEMPLATE.md and PROGRESS.md are also deferred to first use.
 
   // Copy essential docs (TOOLCHAIN.md, VALIDATION.md) to consumer's docs/forge/
-  const result = copyEssentialDocs(projectRoot, packageDir);
+  const result = copyEssentialDocs(projectRoot, getPackageRoot(packageDir));
   for (const f of result.created) {
     console.log(`  Created: ${f}`);
   }
@@ -1768,7 +1704,7 @@ function minimalInstall() {
   if (fs.existsSync(agentsPath)) {
     console.log('  Skipped: AGENTS.md (already exists)');
   } else {
-    const agentsSrc = path.join(packageDir, 'AGENTS.md');
+    const agentsSrc = path.join(getPackageRoot(packageDir), 'AGENTS.md');
     if (copyFile(agentsSrc, 'AGENTS.md')) {
       console.log('  Created: AGENTS.md (universal standard)');
 
@@ -1799,26 +1735,19 @@ function minimalInstall() {
 
 
 // Helper: Setup Claude agent
-function setupClaudeAgent(skipFiles = {}) {
-  // Copy commands from package (unless skipped)
-  if (skipFiles.claudeCommands) {
-    console.log('  Skipped: .claude/commands/ (keeping existing)');
-  } else {
-    const cmds = getWorkflowCommands();
-    let copied = 0;
-    cmds.forEach(cmd => {
-      const src = path.join(packageDir, `.claude/commands/${cmd}.md`);
-      if (copyFile(src, `.claude/commands/${cmd}.md`)) copied++;
-    });
-    console.log(`  Copied: ${copied} workflow commands`);
-  }
-
-  // Copy rules
-  const rulesSrc = path.join(packageDir, '.claude/rules/workflow.md');
-  copyFile(rulesSrc, '.claude/rules/workflow.md');
+function setupClaudeAgent(_skipFiles) {
+  // _skipFiles is accepted for call-site arity parity only; it is unused because
+  // this skills-only surface writes scripts unconditionally (no skip prompts).
+  // Skills-only surface: per-skill SKILL.md dirs are populated by createAgentSkill.
+  //
+  // Claude receives workflow/TDD/security/documentation policy through the
+  // CLAUDE.md → AGENTS.md instruction projection, NOT always-on `.claude/rules/*`
+  // files — those would triple-deliver the same policy into every session as
+  // token bloat. See lib/rules-sync.js and lib/harness-capability-matrix.js.
+  // Only Cursor has a first-class native rule surface (rendered by setupCursorAgent).
 
   // Copy scripts
-  const scriptSrc = path.join(packageDir, '.claude/scripts/load-env.sh');
+  const scriptSrc = path.join(getPackageRoot(packageDir), '.claude/scripts/load-env.sh');
   copyFile(scriptSrc, '.claude/scripts/load-env.sh');
 }
 
@@ -1827,78 +1756,38 @@ function setupClaudeAgent(skipFiles = {}) {
 
 // Helper: Setup Cursor agent
 async function setupCursorAgent() {
+  // Drop the deprecated root config, but NEVER destroy a user's hand-authored
+  // `.cursorrules` — it predates AGENTS.md, so real users have curated ones.
+  const { removed, backupPath } = backupAndRemoveLegacyCursorRules(projectRoot);
+  if (removed) {
+    console.log(
+      `  Removed: .cursorrules (deprecated — Cursor reads AGENTS.md + .cursor/rules/*.mdc); ` +
+      `backed up to ${path.basename(backupPath)}`,
+    );
+  }
   await generateCursorConfig(projectRoot, { overwrite: false });
   console.log('  Created: Cursor native rules');
 }
 
-async function setupKiloAgent() {
-  await generateKiloConfig(projectRoot, { overwrite: false });
-  console.log('  Created: Kilo native workflow files');
-}
-
-async function setupCopilotAgent() {
-  await generateCopilotConfig(projectRoot, { overwrite: false });
-  console.log('  Created: Copilot native config');
-}
-
-async function setupOpenCodeAgent() {
-  await generateOpenCodeConfig(projectRoot, { overwrite: false });
-  console.log('  Created: OpenCode native config');
-}
-
-// Helper: Convert command to agent-specific format
-
-
-// Helper: Convert command to agent-specific format
-function convertCommandToAgentFormat(cmd, content, agent) {
-  let targetContent = content;
-  let targetFile = cmd;
-
-  if (agent.needsConversion) {
-    targetContent = stripFrontmatter(content);
-  }
-
-  if (agent.promptFormat) {
-    targetFile = cmd.replace('.md', '.prompt.md');
-    targetContent = stripFrontmatter(content);
-  }
-
-  return { targetFile, targetContent };
-}
-
-// Helper: Copy commands for agent
-
+// Helper: back up + remove a deprecated `.cursorrules` without data loss.
+// Copies to `.cursorrules.bak` (then numbered `.bak.1`, `.2`, … so a repeat never
+// clobbers an earlier snapshot) before deleting. Mirrors the markerless AGENTS.md
+// backup above. Exported for direct testing.
+function backupAndRemoveLegacyCursorRules(root) {
+  const legacy = path.join(root, '.cursorrules');
+  if (!fs.existsSync(legacy)) return { removed: false };
 
-// Helper: Copy commands for agent
-function copyAgentCommands(agent, claudeCommands) {
-  if (!claudeCommands) return;
-  if (!agent.needsConversion && !agent.copyCommands && !agent.promptFormat) return;
-
-  Object.entries(claudeCommands).forEach(([cmd, content]) => {
-    const { targetFile, targetContent } = convertCommandToAgentFormat(cmd, content, agent);
-    const targetDir = agent.dirs[0]; // First dir is commands/workflows
-    writeFile(`${targetDir}/${targetFile}`, targetContent);
-  });
-  console.log(`  Converted: ${Object.keys(claudeCommands).length} workflow commands`);
-}
-
-// Helper: Copy rules for agent
-
-
-// Helper: Copy rules for agent
-function copyAgentRules(agent) {
-  if (!agent.needsConversion) return;
-
-  const workflowMdPath = path.join(projectRoot, '.claude/rules/workflow.md');
-  if (!fs.existsSync(workflowMdPath)) return;
-
-  const rulesDir = agent.dirs.find(d => d.includes('/rules'));
-  if (!rulesDir) return;
-
-  const ruleContent = readFile(workflowMdPath);
-  if (ruleContent) {
-    writeFile(`${rulesDir}/workflow.md`, ruleContent);
+  let backupPath = path.join(root, '.cursorrules.bak');
+  if (fs.existsSync(backupPath)) {
+    let suffix = 1;
+    while (fs.existsSync(path.join(root, `.cursorrules.bak.${suffix}`))) {
+      suffix += 1;
+    }
+    backupPath = path.join(root, `.cursorrules.bak.${suffix}`);
   }
+  fs.copyFileSync(legacy, backupPath);
+  fs.rmSync(legacy, { force: true });
+  return { removed: true, backupPath };
 }
 
 // Helper: Create skill file for agent
@@ -1911,27 +1800,57 @@ function createAgentSkill(agent, agentKey) {
     return;
   }
 
-  if (!agent.hasSkill) return;
+  if (!agent.hasSkill || !agent.skillsDir) return;
 
-  const skillDir = agent.dirs.find(d => d.includes('/skills/'));
-  if (skillDir) {
-    writeFile(`${skillDir}/SKILL.md`, SKILL_CONTENT);
-    console.log('  Created: forge-workflow skill');
-  }
+  // Skills-only surface: populate every canonical skill into the agent skills dir
+  // (.claude/skills, .cursor/skills) from the packaged canonical `skills/` source.
+  // clean:false so a rerun/upgrade overwrites Forge's skills without deleting
+  // user-authored or third-party skills that share these shared agent dirs.
+  const { written } = populateAgentSkills({
+    sourceRoot: getPackageRoot(packageDir),
+    targetSkillsDir: path.join(projectRoot, agent.skillsDir),
+    clean: false,
+  });
+  console.log(`  Created: ${written.length} skills in ${agent.skillsDir}/`);
 }
 
 // Helper: Create Codex per-stage skills from canonical commands
 function createCodexSkills() {
-  const installPlan = buildCodexSkillInstallPlan(packageDir, { env: process.env, homeDir: os.homedir() });
+  const installPlan = buildCodexSkillInstallPlan(getPackageRoot(packageDir), { env: process.env, homeDir: os.homedir() });
   const installRoot = formatCodexSkillsInstallDir({ env: process.env, homeDir: os.homedir() });
 
   CODEX_SETUP_REPORT = {
     installRoot,
     skillCount: installPlan.length,
+    repoSkillsDir: CODEX_REPO_SKILLS_DIR,
+    repoSkillCount: 0,
     status: 'complete',
     message: '',
   };
 
+  // Repo-local discovery mirror: generate `.agents/skills/<name>/SKILL.md` from
+  // the canonical skills/ source. This is Codex's documented repo-scope discovery
+  // path (scanned cwd → repo root) and is committed, so a teammate who clones the
+  // repo WITHOUT running `forge setup` still gets Forge skills/stages discovered.
+  // Independent of the GLOBAL $CODEX_HOME install below (which needs canonical
+  // packaging templates) — so it runs before the install-plan early return.
+  try {
+    const { written } = populateCodexRepoSkills({ sourceRoot: getPackageRoot(packageDir), projectRoot });
+    CODEX_SETUP_REPORT.repoSkillCount = written.length;
+    console.log(`  Created: ${written.length} repo-local Codex skills in ${CODEX_REPO_SKILLS_DIR}/ (commit for teammate discovery)`);
+  } catch (error) {
+    addSetupNote(`Codex repo-local skill generation failed for ${CODEX_REPO_SKILLS_DIR}: ${error.message}`);
+    console.log(`  Warning: could not generate repo-local Codex skills in ${CODEX_REPO_SKILLS_DIR} (${error.message})`);
+  }
+
+  // Codex is NOT given a committed project-local `.codex/skills` mirror. Its
+  // repo-scope discovery path is the committed `.agents/skills` (generated above),
+  // and its stage skills install GLOBALLY into `$CODEX_HOME/skills` (below). A
+  // committed `.codex/skills` copy would feed nothing at runtime, so setup does
+  // not create one and it stays gitignored (#342). See the long-standing invariant
+  // in test/setup-runtime-flags.test.js ("setup installs Codex stage skills into
+  // CODEX_HOME/skills/<stage>/SKILL.md").
+
   if (installPlan.length === 0) {
     CODEX_SETUP_REPORT.status = 'partial';
     CODEX_SETUP_REPORT.message = 'Codex setup could not find the packaged stage skill templates.';
@@ -1960,27 +1879,178 @@ function createCodexSkills() {
   return CODEX_SETUP_REPORT;
 }
 
-// Helper: Setup MCP config for Claude
-
+// Helper: opt-in Graphiti memory MCP descriptor(s).
+//
+// Included ONLY when the memory backend resolves to `graphiti` (same precedence
+// as the memory router: deps > FORGE_MEMORY_BACKEND > .forge/config.yaml) AND
+// the config passes the same strict validity check `forge doctor` uses
+// (assertMemoryConfigValid). Local backend — the default — returns [] so the
+// rendered MCP config stays byte-identical to the Context7-only output. An
+// invalid/incomplete graphiti config prints a one-line notice and is skipped;
+// it never crashes setup.
+function graphitiMcpDescriptors() {
+  const { assertMemoryConfigValid } = require('../memory/router');
+  try {
+    const { backend, graphiti } = assertMemoryConfigValid({ projectRoot });
+    if (backend !== 'graphiti') return [];
+    const { buildGraphitiServerDescriptor } = require('../memory/graphiti-mcp');
+    return [buildGraphitiServerDescriptor(graphiti)];
+  } catch (err) {
+    // Surface the validator's specific message (it names the missing key and
+    // where to configure it) instead of a generic notice that hides the cause.
+    console.log(
+      `  Notice: Graphiti MCP server not wired — ${err && err.message ? err.message : 'memory config invalid'}`
+      + ' Run `forge doctor` for details.',
+    );
+    return [];
+  }
+}
 
 // Helper: Setup MCP config for Claude
+//
+// Read → merge → write (idempotent). A pre-existing `.mcp.json` is MERGED, not
+// skipped: the old skip-if-exists behavior silently refused to add the Context7
+// server whenever any config already existed. User/other servers are preserved.
 function setupClaudeMcpConfig() {
-  const mcpPath = path.join(projectRoot, '.mcp.json');
-  if (fs.existsSync(mcpPath)) {
-    console.log('  Skipped: .mcp.json already exists');
+  const { existed, skipped, backup } = renderMcpConfig({
+    harness: 'claude',
+    targetRoot: projectRoot,
+    descriptors: [CONTEXT7_MCP_DESCRIPTOR, ...graphitiMcpDescriptors()],
+  });
+  if (skipped) {
+    // Existing .mcp.json was unparseable (JSONC/trailing comma): renderMcpConfig
+    // left it untouched and backed it up rather than clobber the user's servers.
+    // Report that honestly instead of a false "merged" success.
+    console.log(
+      `  Skipped: .mcp.json is not valid JSON — left untouched to avoid data loss`
+      + `${backup ? ` (backed up to ${backup})` : ''}. Add the Context7 MCP server manually.`,
+    );
+    return;
+  }
+  console.log(
+    existed
+      ? '  Updated: .mcp.json (merged Context7 MCP, preserved existing servers)'
+      : '  Created: .mcp.json with Context7 MCP',
+  );
+}
+
+// Helper: Setup MCP config for Cursor (project-local .cursor/mcp.json).
+// Cursor reads a project-local MCP config, so this is a real native delivery
+// (mirrors setupClaudeMcpConfig). Read → merge → write, preserving user servers.
+function setupCursorMcpConfig() {
+  const { existed, skipped, backup } = renderMcpConfig({
+    harness: 'cursor',
+    targetRoot: projectRoot,
+    descriptors: [CONTEXT7_MCP_DESCRIPTOR, ...graphitiMcpDescriptors()],
+  });
+  if (skipped) {
+    console.log(
+      `  Skipped: .cursor/mcp.json is not valid JSON — left untouched to avoid data loss`
+      + `${backup ? ` (backed up to ${backup})` : ''}. Add the Context7 MCP server manually.`,
+    );
     return;
   }
+  console.log(
+    existed
+      ? '  Updated: .cursor/mcp.json (merged Context7 MCP, preserved existing servers)'
+      : '  Created: .cursor/mcp.json with Context7 MCP',
+  );
+}
 
-  const mcpConfig = {
-    mcpServers: {
-      context7: {
-        command: 'npx',
-        args: ['-y', '@upstash/context7-mcp@latest']
-      }
-    }
-  };
-  writeFile('.mcp.json', JSON.stringify(mcpConfig, null, 2));
-  console.log('  Created: .mcp.json with Context7 MCP');
+// Safe SAFETY defaults are ON by default (non-surprising) but fully opt-out-able.
+// Set FORGE_SKIP_SAFETY_DEFAULTS=1 (or `true`) to skip rendering the permission /
+// ignore defaults — Forge then leaves those surfaces entirely to the user.
+function safetyDefaultsEnabled() {
+  const flag = String(process.env.FORGE_SKIP_SAFETY_DEFAULTS || '').trim().toLowerCase();
+  return !(flag === '1' || flag === 'true' || flag === 'yes');
+}
+
+// Helper: Render safe Claude tool-permission defaults into .claude/settings.json.
+// Read -> merge -> write (idempotent). Preserves the user's existing settings and
+// allow/deny/ask entries; an unparseable file is backed up and left untouched.
+function setupClaudePermissions() {
+  if (!safetyDefaultsEnabled()) {
+    console.log('  Skipped: .claude/settings.json permissions (FORGE_SKIP_SAFETY_DEFAULTS set)');
+    return;
+  }
+  const { existed, skipped, backup } = renderClaudePermissions({ targetRoot: projectRoot });
+  if (skipped) {
+    console.log(
+      '  Skipped: .claude/settings.json is not valid JSON — left untouched to avoid data loss'
+      + `${backup ? ` (backed up to ${backup})` : ''}. Add safe permissions manually.`,
+    );
+    return;
+  }
+  console.log(
+    existed
+      ? '  Updated: .claude/settings.json (merged safe permission defaults, preserved your entries)'
+      : '  Created: .claude/settings.json with safe permission defaults',
+  );
+}
+
+// Helper: Render safe .cursorignore defaults (AI read/index boundary).
+// Read -> merge -> write (idempotent). Preserves user lines; only appends missing
+// default patterns (secrets/.env/node_modules/build artifacts).
+function setupCursorIgnore() {
+  if (!safetyDefaultsEnabled()) {
+    console.log('  Skipped: .cursorignore defaults (FORGE_SKIP_SAFETY_DEFAULTS set)');
+    return;
+  }
+  const { existed } = renderCursorIgnore({ targetRoot: projectRoot });
+  console.log(
+    existed
+      ? '  Updated: .cursorignore (appended safe defaults, preserved your entries)'
+      : '  Created: .cursorignore with safe defaults',
+  );
+}
+
+// Helper: Setup native HOOK config for Claude (project-local .claude/settings.json).
+// Projects Forge's TDD-gate + protected-path enforcement onto Claude's native hook
+// surface (a `hooks` block). Read → merge → write, preserving user hooks; an
+// unparseable settings.json is backed up and left untouched (data-loss safe).
+function setupClaudeHooksConfig() {
+  const { existed, skipped, backup, wrote } = renderHookConfig({
+    harness: 'claude',
+    targetRoot: projectRoot,
+  });
+  if (skipped) {
+    console.log(
+      `  Skipped: .claude/settings.json is not valid JSON — left untouched to avoid data loss`
+      + `${backup ? ` (backed up to ${backup})` : ''}. Add the Forge hooks block manually.`,
+    );
+    return;
+  }
+  if (wrote) {
+    console.log(
+      existed
+        ? '  Updated: .claude/settings.json (merged Forge hooks, preserved existing hooks)'
+        : '  Created: .claude/settings.json with Forge hooks',
+    );
+  }
+}
+
+// Helper: Setup native HOOK config for Cursor (project-local .cursor/hooks.json,
+// Cursor 1.7+). Mirrors setupClaudeHooksConfig. Read → merge → write, preserving
+// user hooks; unparseable config is backed up and left untouched.
+function setupCursorHooksConfig() {
+  const { existed, skipped, backup, wrote } = renderHookConfig({
+    harness: 'cursor',
+    targetRoot: projectRoot,
+  });
+  if (skipped) {
+    console.log(
+      `  Skipped: .cursor/hooks.json is not valid JSON — left untouched to avoid data loss`
+      + `${backup ? ` (backed up to ${backup})` : ''}. Add the Forge hooks manually.`,
+    );
+    return;
+  }
+  if (wrote) {
+    console.log(
+      existed
+        ? '  Updated: .cursor/hooks.json (merged Forge hooks, preserved existing hooks)'
+        : '  Created: .cursor/hooks.json with Forge hooks',
+    );
+  }
 }
 
 // Helper: Create agent link file
@@ -2002,13 +2072,13 @@ function createAgentLinkFile(agent, symlinkOnly = false) {
 
 
 // Setup specific agent
-async function setupAgent(agentKey, claudeCommands, skipFiles = {}) {
+async function setupAgent(agentKey, skipFiles = {}) {
   const agent = AGENTS[agentKey];
   if (!agent) return;
 
   console.log(`\nSetting up ${agent.name}...`);
   if (agent.supportStatus === 'deprecated') {
-    console.log(`  Warning: ${agent.name} is in deprecated compatibility mode; Forge will scaffold converted workflow files only.`);
+    console.log(`  Warning: ${agent.name} is in deprecated compatibility mode; Forge will scaffold skill files only.`);
   }
 
   // Create directories
@@ -2023,30 +2093,30 @@ async function setupAgent(agentKey, claudeCommands, skipFiles = {}) {
     await setupCursorAgent();
   }
 
-  if (agentKey === 'kilocode') {
-    await setupKiloAgent();
-  }
-
-  if (agentKey === 'copilot') {
-    await setupCopilotAgent();
-  }
-
-  if (agentKey === 'opencode') {
-    await setupOpenCodeAgent();
-  }
-
-  // Convert/copy commands
-  copyAgentCommands(agent, claudeCommands);
-
-  // Copy rules if needed
-  copyAgentRules(agent);
-
   // Create SKILL.md or Codex stage skills
   createAgentSkill(agent, agentKey);
 
-  // Setup MCP configs
+  // Setup MCP configs (project-local, native for both harnesses)
   if (agentKey === 'claude') {
     setupClaudeMcpConfig();
+    // Native safety surface: declarative tool-permission allowlist.
+    setupClaudePermissions();
+  }
+  if (agent.customSetup === 'cursor') {
+    setupCursorMcpConfig();
+    // Native safety surface: AI read/index ignore boundary.
+    setupCursorIgnore();
+  }
+
+  // Setup native HOOK configs (project-local, native for both harnesses).
+  // Projects Forge's TDD-gate + protected-path enforcement onto each harness's
+  // native hook surface. Codex hooks are GLOBAL-config scope and intentionally
+  // not written at project setup (see lib/hook-renderer.js).
+  if (agentKey === 'claude') {
+    setupClaudeHooksConfig();
+  }
+  if (agent.customSetup === 'cursor') {
+    setupCursorHooksConfig();
   }
 
   // Create link file (SYMLINK_ONLY = --symlink flag disables copy fallback)
@@ -2086,7 +2156,6 @@ function displayInstallationStatus(projectStatus) {
   }
 
   if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
-  if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
   if (projectStatus.hasEnvLocal) console.log('  - .env.local');
   console.log('');
 }
@@ -2162,7 +2231,6 @@ async function promptForFileOverwrite(question, fileType, exists, skipFiles) {
 
   const fileLabels = {
     agentsMd: { prompt: 'Found existing AGENTS.md. Overwrite?', message: 'AGENTS.md', key: 'agentsMd' },
-    claudeCommands: { prompt: 'Found existing .claude/commands/. Overwrite?', message: '.claude/commands/', key: 'claudeCommands' }
   };
 
   const config = fileLabels[fileType];
@@ -2182,7 +2250,7 @@ async function promptForFileOverwrite(question, fileType, exists, skipFiles) {
     }
   }
 
-  // Default behavior: Binary y/n for files with markers or .claude/commands
+  // Default behavior: Binary y/n for files with markers
   const overwrite = await askYesNo(question, config.prompt, true);
   if (overwrite) {
     console.log(`  Will overwrite ${config.message}`);
@@ -2334,7 +2402,7 @@ async function installAgentsMd(skipFiles) {
     return;
   }
 
-  const agentsSrc = path.join(packageDir, 'AGENTS.md');
+  const agentsSrc = path.join(getPackageRoot(packageDir), 'AGENTS.md');
   const agentsDest = path.join(projectRoot, 'AGENTS.md');
 
   // Try smart merge if file exists
@@ -2372,28 +2440,6 @@ async function installAgentsMd(skipFiles) {
  */
 
 
-/**
- * Load Claude commands for conversion
- */
-function loadClaudeCommands(selectedAgents) {
-  const claudeCommands = {};
-  const needsClaudeCommands = selectedAgents.includes('claude') ||
-    selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands);
-
-  if (!needsClaudeCommands) {
-    return claudeCommands;
-  }
-
-  getWorkflowCommands().forEach(cmd => {
-    const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
-    const content = readFile(cmdPath);
-    if (content) {
-      claudeCommands[`${cmd}.md`] = content;
-    }
-  });
-
-  return claudeCommands;
-}
 
 /**
  * Setup agents with progress indication
@@ -2405,8 +2451,8 @@ function loadClaudeCommands(selectedAgents) {
  * Setup agents with progress indication
  * Delegates to setupSelectedAgents to avoid duplicate implementations (S4144)
  */
-async function setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles) {
-  await setupSelectedAgents(selectedAgents, claudeCommands, skipFiles);
+async function setupAgentsWithProgress(selectedAgents, skipFiles) {
+  await setupSelectedAgents(selectedAgents, skipFiles);
 }
 
 /**
@@ -2427,26 +2473,19 @@ function displaySetupSummary(selectedAgents) {
   console.log('What\'s installed:');
   console.log('  - AGENTS.md (universal instructions)');
 
-  const workflowCount = getWorkflowCommands().length;
   selectedAgents.forEach(key => {
     const agent = AGENTS[key];
     if (agent.linkFile) {
       console.log(`  - ${agent.linkFile} (${agent.name})`);
     }
-    if (agent.hasCommands && key === 'claude') {
-      console.log(`  - .claude/commands/ (${workflowCount} workflow commands)`);
-    } else if (agent.hasCommands && key !== 'codex' && agent.dirs[0]) {
-      console.log(`  - ${agent.dirs[0]}/ (${workflowCount} workflow commands)`);
-    }
     if (key === 'codex') {
-      const skillCount = CODEX_SETUP_REPORT?.skillCount ?? listCodexSkillEntries(packageDir).length;
+      const skillCount = CODEX_SETUP_REPORT?.skillCount ?? listCodexSkillEntries(getPackageRoot(packageDir)).length;
       const codexRoot = CODEX_SETUP_REPORT?.installRoot || formatCodexSkillsInstallDir({ env: process.env, homeDir: os.homedir() });
       console.log(`  - ${codexRoot}/<stage>/SKILL.md (${skillCount} stage skills)`);
-    } else if (agent.hasSkill) {
-      const skillDir = agent.dirs.find(d => d.includes('/skills/'));
-      if (skillDir) {
-        console.log(`  - ${skillDir}/SKILL.md`);
-      }
+      const repoSkillCount = CODEX_SETUP_REPORT?.repoSkillCount ?? 0;
+      console.log(`  - ${CODEX_REPO_SKILLS_DIR}/<skill>/SKILL.md (${repoSkillCount} repo-local skills — commit for teammate discovery)`);
+    } else if (agent.hasSkill && agent.skillsDir) {
+      console.log(`  - ${agent.skillsDir}/<skill>/SKILL.md`);
     }
   });
 
@@ -2475,13 +2514,11 @@ function displaySetupSummary(selectedAgents) {
   console.log('');
   printSetupNotes();
 
-  // Beads status
-  if (isBeadsInitialized()) {
-    console.log('  ✓ Beads initialized - Track work: forge ready');
-  } else if (checkForBeads()) {
-    console.log('  ! Beads available - Run: bd init');
+  // Issue store status — the Kernel store is always present (auto-provisioned)
+  if (KERNEL_STORE_READY) {
+    console.log('  ✓ Kernel issue store - Track work: forge ready');
   } else {
-    console.log(`  - Beads not installed - Run: ${PKG_MANAGER} install -g @beads/bd && bd init`);
+    console.log('  ⚠ Kernel issue store - not provisioned; run: forge doctor');
   }
 
   // Skills status
@@ -2552,12 +2589,10 @@ async function _interactiveSetup() {
   // Track which files to skip based on user choices
   const skipFiles = {
     agentsMd: false,
-    claudeCommands: false
   };
 
   // Ask about overwriting existing files
   await promptForFileOverwrite(question, 'agentsMd', projectStatus.hasAgentsMd, skipFiles);
-  await promptForFileOverwrite(question, 'claudeCommands', projectStatus.hasClaudeCommands, skipFiles);
 
   if (projectStatus.type !== 'fresh') {
     console.log('');
@@ -2580,19 +2615,13 @@ async function _interactiveSetup() {
   setupCoreDocs();
   console.log('');
 
-  // Load Claude commands if needed
-  let claudeCommands = {};
-  if (selectedAgents.includes('claude') || selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands)) {
-    // First ensure Claude is set up
-    if (selectedAgents.includes('claude')) {
-      await setupAgent('claude', null, skipFiles);
-    }
-    // Then load the commands
-    claudeCommands = loadClaudeCommands(selectedAgents);
+  // Setup Claude first if selected, then setup remaining agents
+  if (selectedAgents.includes('claude')) {
+    await setupAgent('claude', skipFiles);
   }
 
   // Setup each selected agent with progress indication
-  await setupAgentsWithProgress(selectedAgents, claudeCommands, skipFiles);
+  await setupAgentsWithProgress(selectedAgents, skipFiles);
 
   // =============================================
   // STEP 2: Project Tools Setup
@@ -2615,6 +2644,9 @@ async function _interactiveSetup() {
   // Final Summary
   // =============================================
   displaySetupSummary(selectedAgents);
+
+  // One-step onboarding: run `forge init` when config is still absent (ac0b38c7).
+  await finalizeWorkflowConfig();
 }
 
 // Parse CLI flags
@@ -2671,55 +2703,188 @@ async function handleHuskyMigration() {
 
 // Install git hooks via lefthook
 // SECURITY: Uses execSync with HARDCODED strings only (no user input)
-function installGitHooks() { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
-  console.log('Installing git hooks (TDD enforcement)...');
-
-  // Skip lefthook.yml creation if binary is not available
-  const lefthookStatus = checkLefthookStatus(projectRoot);
-  if (!lefthookStatus.binaryAvailable) {
-    if (lefthookStatus.message) {
-      console.warn(`  \u26A0 Skipping lefthook setup: ${lefthookStatus.message}`);
-    } else {
-      console.warn('  \u26A0 Skipping lefthook setup: binary not available');
+// Copy the Forge hook scripts (check-tdd.js + the native-hook adapter) into the
+// project's .forge/hooks/. Runs UNCONDITIONALLY — independent of the lefthook binary.
+// The native harness hooks rendered by lib/hook-renderer.js invoke forge-native-hook.js,
+// which delegates the TDD gate to check-tdd.js, so BOTH must always be installed; if we
+// only copied them on the lefthook path, a machine without lefthook would get native
+// hooks pointing at an adapter that was never installed.
+function installForgeHookScripts() {
+  const targetHooks = path.join(projectRoot, '.forge/hooks');
+  for (const name of ['check-tdd.js', 'forge-native-hook.js']) {
+    const src = path.join(getPackageRoot(packageDir), '.forge/hooks', name);
+    if (!fs.existsSync(src)) continue;
+    if (!fs.existsSync(targetHooks)) fs.mkdirSync(targetHooks, { recursive: true });
+    const dest = path.join(targetHooks, name);
+    if (copyFile(src, dest)) {
+      console.log(`  ✓ Created .forge/hooks/${name}`);
+      try {
+        fs.chmodSync(dest, 0o755); // NOSONAR — 755 is intentional: hook scripts must be executable
+      } catch (err) {
+        console.warn('chmod not available (Windows):', err.message);
+      }
     }
-    return;
   }
+}
 
-  // Check if lefthook.yml exists (it should, as it's in the package)
-  const lefthookConfig = path.join(packageDir, 'lefthook.yml');
-  const targetHooks = path.join(projectRoot, '.forge/hooks');
-
+// FORGE_USER_LEFTHOOK_YML and forgeShouldWriteLefthookConfig are the single source of
+// truth in lib/lefthook-wiring.js, shared with bin/forge.js so the live `forge setup`
+// path and this repair path can never drift again — that drift is exactly what let the
+// stub-shadow fix (kernel e452422c / c713fce7) live in this module while `forge setup`
+// kept shipping the broken behaviour. They are imported at the top of this file and
+// re-exported below for the existing test surface.
+
+// Honest, resolved-config description of what the installed hooks will actually
+// enforce (issue eda6d866). The hook scripts are installed unconditionally but are
+// INERT when their gate/rail is disabled in .forge/config.yaml, so setup must not
+// claim "enforcement active" when the resolved config says otherwise.
+// Resolve — from the SAME .forge/config.yaml the hooks read at run time — whether the TDD
+// gate is active and how many protected paths are guarded. The reporting/exit layer gates
+// its verdict on this so setup never claims (or fails over) a state the user deliberately
+// disabled (issue eda6d866). On resolver THROW (missing/corrupt config), fail TOWARD
+// enforcement (tddActive:true, resolved:false) so a broken config can never silently
+// downgrade the human-facing verdict.
+function resolveHookEnforcementState(root = projectRoot) {
   try {
-    // Copy lefthook.yml to project root
-    const lefthookTarget = path.join(projectRoot, 'lefthook.yml');
-    if (!fs.existsSync(lefthookTarget)) {
-      if (copyFile(lefthookConfig, 'lefthook.yml')) {
-        console.log('  ✓ Created lefthook.yml');
-      }
+    const { getResolvedRuntimeGraph } = require('../core/runtime-graph');
+    const graph = getResolvedRuntimeGraph({ projectRoot: root });
+    const tddRail = (graph.rails || []).find(rail => rail.id === 'rail.tdd_intent');
+    const tddActive = !tddRail || tddRail.enabled !== false;
+    const protectedCount = Array.isArray(graph.protectedPaths) ? graph.protectedPaths.length : 0;
+    return { tddActive, protectedCount, resolved: true };
+  } catch {
+    return { tddActive: true, protectedCount: 0, resolved: false };
+  }
+}
+
+function describeHookEnforcement(root = projectRoot) {
+  const state = resolveHookEnforcementState(root);
+  if (!state.resolved) {
+    return null; // never let an honest-status line block setup (resolver threw)
+  }
+  const tdd = state.tddActive ? 'active' : 'disabled in config (hook inert)';
+  const pp = state.protectedCount > 0
+    ? `active (${state.protectedCount} path${state.protectedCount === 1 ? '' : 's'})`
+    : 'disabled in config (hook inert)';
+  return `TDD gate: ${tdd}; protected-path: ${pp}`;
+}
+
+// Pure reporting/exit-layer verdict (issue eda6d866): fold the file-presence hook check
+// (verifyHooksActive) and the resolved config state (resolveHookEnforcementState) into the
+// message/level and whether setup should exit non-zero. Kept pure + exported so the four
+// honesty cases are unit-testable without spawning setup. The caller folds "are we in a git
+// repo" into `loud`, so a non-git dir (nothing to hook into) only ever warns.
+function buildHookVerdict(verdict, state, options = {}) {
+  const loud = options.loud === true;
+  const tddActive = !state || state.tddActive !== false;
+  if (verdict.active) {
+    if (tddActive) {
+      return {
+        message: `  ✓ Git hook enforcement active (${verdict.method}).`,
+        level: 'log',
+        exitFailure: false,
+      };
     }
+    // Hooks installed but the TDD gate is OFF in config → the scripts are inert by the
+    // user's own choice. Say so honestly instead of over-claiming "enforcement active".
+    return {
+      message: `  ✓ Git hooks installed (${verdict.method}) — TDD gate disabled in .forge/config.yaml, hooks are inert. Re-enable: forge gate enable rail.tdd_intent`,
+      level: 'log',
+      exitFailure: false,
+    };
+  }
+  if (!tddActive) {
+    // Hooks not active AND the user disabled enforcement — this is the CHOSEN state (e.g.
+    // `init --profile minimal`), so never banner or exit non-zero for it, even under loud.
+    return {
+      message: '  ℹ Git hooks not active — enforcement is disabled in .forge/config.yaml anyway.',
+      level: 'info',
+      exitFailure: false,
+    };
+  }
+  // TDD is ON but hooks are inert — the silent-inert bug B3. Loud setup in a git repo fails
+  // LOUDLY + non-zero; otherwise (init/repair path, or non-git dir folded into !loud) warn.
+  if (loud) {
+    const addCmd = PKG_MANAGER === 'bun'
+      ? 'bun add -d'
+      : PKG_MANAGER === 'npm'
+        ? 'npm install --save-dev'
+        : `${PKG_MANAGER} add -D`;
+    const message = [
+      '',
+      '  ============================================================',
+      '  ⚠ TDD ENFORCEMENT IS NOT ACTIVE',
+      `     ${verdict.reason || 'no pre-commit hook is installed'}.`,
+      '     `forge ship` will block until hooks are active. To fix:',
+      `       ${addCmd} lefthook  &&  npx lefthook install`,
+      '     (or re-run `forge setup` in the repo root).',
+      '  ============================================================',
+      '',
+    ].join('\n');
+    return { message, level: 'error', exitFailure: true };
+  }
+  return {
+    message: `  ⚠ TDD enforcement is NOT active: ${verdict.reason || 'no pre-commit hook installed'}.`,
+    level: 'warn',
+    exitFailure: false,
+  };
+}
 
-    // Copy check-tdd.js hook script
-    const hookSource = path.join(packageDir, '.forge/hooks/check-tdd.js');
-    if (fs.existsSync(hookSource)) {
-      // Ensure .forge/hooks directory exists
-      if (!fs.existsSync(targetHooks)) {
-        fs.mkdirSync(targetHooks, { recursive: true });
-      }
-
-      const hookTarget = path.join(targetHooks, 'check-tdd.js');
-      if (copyFile(hookSource, hookTarget)) {
-        console.log('  ✓ Created .forge/hooks/check-tdd.js');
+function installGitHooks(options = {}) { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
+  // loud=true (the `forge setup` handlers — quickSetup + executeSetup) surfaces an
+  // inert-hooks result as a HARD failure — a banner + non-zero exit — so setup never ends
+  // green with TDD enforcement silently off (B3). loud=false (the default: mid-stage
+  // repairRuntimeReadiness AND `forge init` via ensureGitHooksInstalled) only warns, since
+  // init deliberately degrades to a warning rather than failing, and repair runs inside
+  // another command's flow.
+  const loud = options.loud === true;
+  // Honest header: when the TDD gate is disabled in config the hooks install but are inert,
+  // so don't announce "(TDD enforcement)" for a state the user turned off (issue eda6d866).
+  console.log(
+    resolveHookEnforcementState(projectRoot).tddActive
+      ? 'Installing git hooks (TDD enforcement)...'
+      : 'Installing git hooks (TDD gate disabled in config — hooks will be inert)...'
+  );
+
+  // Install the Forge hook SCRIPTS first, unconditionally: they back BOTH the lefthook
+  // pre-commit gate AND the native harness hooks that forge setup renders regardless of
+  // whether the lefthook binary is present.
+  installForgeHookScripts();
+
+  // Report what the hooks will ACTUALLY enforce given the resolved config — a
+  // disabled gate/rail installs an inert hook, so say so instead of over-claiming.
+  const enforcementStatus = describeHookEnforcement();
+  if (enforcementStatus) {
+    console.log(`  Enforcement (from .forge/config.yaml): ${enforcementStatus}`);
+  }
 
-        // Make hook executable (Unix systems)
-        try {
-          fs.chmodSync(hookTarget, 0o755); // NOSONAR — 755 is intentional: git hooks must be executable
-        } catch (err) {
-          // Windows doesn't need chmod
-          console.warn('chmod not available (Windows):', err.message);
-        }
-      }
+  // Skip lefthook.yml creation if binary is not available
+  const lefthookStatus = checkLefthookStatus(projectRoot);
+  let lefthookInstalled = false;
+  if (!lefthookStatus.binaryAvailable && lefthookStatus.message) {
+    console.warn(`  \u26A0 lefthook binary unavailable: ${lefthookStatus.message}`);
+  }
+
+  // Only drive lefthook when its binary is actually present. When it is not, fall
+  // straight through to the native .git/hooks fallback below rather than triggering an
+  // on-demand `npx lefthook` fetch \u2014 that is network-dependent and can hang on Windows,
+  // and it keeps this repair path byte-for-byte consistent with bin/forge.js.
+  if (lefthookStatus.binaryAvailable) {
+   try {
+    // Write the user-facing lefthook.yml (references only .forge/hooks/check-tdd.js and
+    // the project's own tests — never the repo's internal scripts/). Overwrite lefthook's
+    // own disposable stub so Forge's pre-commit/pre-push wiring actually lands; never
+    // clobber a config that already has active jobs (kernel c713fce7).
+    const lefthookTarget = path.join(projectRoot, 'lefthook.yml');
+    if (forgeShouldWriteLefthookConfig(lefthookTarget)) {
+      fs.writeFileSync(lefthookTarget, FORGE_USER_LEFTHOOK_YML, 'utf8');
+      actionLog.add('lefthook.yml', 'created');
+      console.log('  ✓ Created lefthook.yml');
     }
 
+    // (The Forge hook scripts — check-tdd.js + forge-native-hook.js — are installed
+    // unconditionally by installForgeHookScripts() above, before this lefthook path.)
+
     // Try to install lefthook hooks
     // SECURITY: Using execFileSync with hardcoded commands (no user input)
     try {
@@ -2727,12 +2892,14 @@ function installGitHooks() { // NOSONAR — Extracted as-is from bin/forge.js; c
       try {
         secureExecFileSync('npx', ['lefthook', 'install'], { stdio: 'inherit', cwd: projectRoot });
         console.log('  ✓ Lefthook hooks installed (local)');
+        lefthookInstalled = true;
       } catch (error_) {
         // Fallback to global lefthook
         console.warn('npx lefthook failed, trying global:', error_.message);
-        execFileSync('lefthook', ['version'], { stdio: 'ignore' });
-        execFileSync('lefthook', ['install'], { stdio: 'inherit', cwd: projectRoot });
+        secureExecFileSync('lefthook', ['version'], { stdio: 'ignore' });
+        secureExecFileSync('lefthook', ['install'], { stdio: 'inherit', cwd: projectRoot });
         console.log('  ✓ Lefthook hooks installed (global)');
+        lefthookInstalled = true;
       }
   } catch (err) {
     console.warn('Lefthook installation failed:', err.message);
@@ -2751,6 +2918,43 @@ function installGitHooks() { // NOSONAR — Extracted as-is from bin/forge.js; c
     console.log('  You can install manually later with: lefthook install');
     console.log('');
   }
+  }
+
+  // Native fallback: when lefthook could not be installed, wire native .git/hooks so
+  // raw git commit / git push still enforce the TDD gate — enforcement is never silently
+  // inert (B3). This repair path only warns (never sets a failure exit code) since it can
+  // run mid-stage under enforce-stage's repairWorkflowRuntimeAssets().
+  if (!lefthookInstalled) {
+    const native = installNativeGitHooks(projectRoot);
+    if (native.installed) {
+      console.log(`  ✓ Native git hooks installed (${native.written.join(', ')}) - lefthook fallback`);
+    } else if (native.skipped && native.skipped.length > 0) {
+      console.warn(`  ⚠ Native hook(s) skipped to preserve existing hooks: ${native.skipped.join(', ')}`);
+    } else {
+      console.warn(`  ⚠ Could not install native git hooks: ${native.reason || 'unknown'}`);
+    }
+  }
+
+  const verdict = verifyHooksActive(projectRoot);
+  const state = resolveHookEnforcementState(projectRoot);
+  // A non-git dir has nothing to hook into, so it must only ever WARN (never banner/exit).
+  // Fold that into `loud` before building the verdict so buildHookVerdict stays pure. When
+  // the TDD gate is disabled in config, the verdict is info-level with no failure exit even
+  // under loud setup — enforcement honestly follows the resolved config (issue eda6d866).
+  const inGitRepo = Boolean(resolveGitHooksDir(projectRoot));
+  const built = buildHookVerdict(verdict, state, { loud: loud && inGitRepo });
+  if (built.level === 'error') {
+    console.error(built.message);
+  } else if (built.level === 'warn') {
+    console.warn(built.message);
+  } else if (built.level === 'info') {
+    console.info(built.message);
+  } else {
+    console.log(built.message);
+  }
+  if (built.exitFailure) {
+    process.exitCode = 1;
+  }
 }
 
 // Check if lefthook is already installed in project (delegates to lib/lefthook-check)
@@ -2795,130 +2999,34 @@ function repairDeclaredLefthookDependency(selectedAgents) {
   }
 }
 
-// Check if Beads is installed (global, local, or bunx-capable)
-
-
-// Check if Beads is installed (global, local, or bunx-capable)
-function checkForBeads() {
-  // Try global install first
+// Ensure the local Forge Kernel issue store exists and is migrated.
+//
+// The Kernel is a single-machine SQLite store in the git common dir; building
+// the migrated deps runs broker.initialize() (idempotent), so the DB + schema
+// exist before first use. There is no external CLI to install — issue tracking
+// ships with Forge. Best-effort: never throws, so setup proceeds even if the
+// SQLite runtime is unavailable (the first kernel command would migrate it
+// later anyway).
+async function ensureKernelIssueStore() {
   try {
-    secureExecFileSync('bd', ['version'], { stdio: 'ignore' });
-    return 'global';
-  } catch (err) {
-    // Not global
-    console.warn('Beads not found globally:', err.message);
-  }
-
-  // Check if bunx can run it
-  try {
-    secureExecFileSync('bunx', ['@beads/bd', 'version'], { stdio: 'ignore' });
-    return 'bunx';
-  } catch (err) {
-    // Not bunx-capable
-    console.warn('Beads not available via bunx:', err.message);
-  }
-
-  // Check local project installation
-  const pkgPath = path.join(projectRoot, 'package.json');
-  if (!fs.existsSync(pkgPath)) return null;
-
-  try {
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf8'));
-    const isInstalled = pkg.devDependencies?.['@beads/bd'] || pkg.dependencies?.['@beads/bd'];
-    return isInstalled ? 'local' : null;
-  } catch (err) {
-    console.warn('Failed to check Beads in package.json:', err.message);
-    return null;
-  }
-}
-// Check if Beads is initialized in project — delegates to lib/beads-setup
-
-// Check if Beads is initialized in project — delegates to lib/beads-setup
-function isBeadsInitialized() {
-  return beadsSetupLib.isBeadsInitialized(projectRoot);
-}
-
-// Initialize Beads in the project using the defensive safeBeadsInit wrapper
-// Handles config/gitignore writes, hook snapshot/restore, and JSONL pre-seeding
-
-
-// Initialize Beads in the project using the defensive safeBeadsInit wrapper
-// Handles config/gitignore writes, hook snapshot/restore, and JSONL pre-seeding
-function initializeBeads(installType) {
-  console.log('Initializing Beads in project...');
-
-  // Build the execBdInit function based on installType
-  const execBdInit = (root) => {
-    // SECURITY: execFileSync with hardcoded commands
-    if (installType === 'global') {
-      secureExecFileSync('bd', ['init'], { stdio: 'inherit', cwd: root });
-    } else if (installType === 'bunx') {
-      secureExecFileSync('bunx', ['@beads/bd', 'init'], { stdio: 'inherit', cwd: root });
-    } else if (installType === 'local') {
-      secureExecFileSync('npx', ['bd', 'init'], { stdio: 'inherit', cwd: root });
-    }
-  };
-
-  // Derive prefix from package.json name or directory name
-  let prefix;
-  try {
-    const pkg = JSON.parse(fs.readFileSync(path.join(projectRoot, 'package.json'), 'utf8'));
-    prefix = pkg.name || path.basename(projectRoot);
-  } catch (_e) { // NOSONAR — fallback to directory name if package.json unreadable
-    prefix = path.basename(projectRoot);
-  }
-
-  try {
-    const result = beadsSetupLib.safeBeadsInit(projectRoot, {
-      prefix,
-      execBdInit,
-      restoreLefthook: (root) => {
-        try {
-          secureExecFileSync('lefthook', ['install'], { stdio: 'ignore', cwd: root });
-        } catch (_e) { // NOSONAR — lefthook may not be installed yet, non-fatal
-          // lefthook may not be installed yet — non-fatal
-        }
-      }
-    });
-
-    if (result.skipped) {
-      console.log('  ✓ Beads already initialized');
-      return true;
-    }
-
-    if (!result.success) {
-      for (const e of result.errors) {
-        console.log(`  ⚠ ${e}`);
-      }
-      console.log('  Run manually: bd init');
-      return false;
-    }
-
-    for (const w of result.warnings) {
-      console.warn(`  ⚠ ${w}`);
-    }
-    console.log('  ✓ Beads initialized');
-
-    // Run post-init health check (non-fatal)
-    try {
-      const health = beadsHealthCheck(projectRoot);
-      if (health.healthy) {
-        console.log('  ✓ Beads health check passed');
-      } else {
-        console.log(`  ⚠ Beads health check failed at ${health.failedStep}: ${health.error}`);
+    const deps = await buildMigratedKernelIssueDeps({ projectRoot });
+    const handle = deps.kernelBroker || deps.kernelDriver;
+    if (handle && typeof handle.close === 'function') {
+      try {
+        await handle.close();
+      } catch (_closeErr) { // NOSONAR — best-effort cleanup of the migration handle
+        // Closing the migration handle is best-effort; the process is short-lived.
       }
-    } catch (_healthErr) { // NOSONAR — health check is best-effort, non-fatal
-      // Health check is best-effort — don't block setup
     }
-
+    KERNEL_STORE_READY = true;
     return true;
   } catch (err) {
-    console.log('  ⚠ Failed to initialize Beads:', err.message);
-    console.log('  Run manually: bd init');
+    KERNEL_STORE_READY = false;
+    console.log(`  ⚠ Could not provision the Kernel issue store: ${err.message}`);
+    addSetupNote(`Kernel issue store not provisioned: ${err.message}. Run \`forge doctor\` to inspect.`);
     return false;
   }
 }
-
 // Check if Skills CLI is installed
 
 
@@ -2984,59 +3092,18 @@ function initializeSkills(installType) {
   }
 }
 
-// Prompt for Beads setup - extracted to reduce cognitive complexity
-
-
-// Prompt for Beads setup - extracted to reduce cognitive complexity
-async function promptBeadsSetup(question) {
+// Ensure the issue store during interactive setup. No prompt: the Forge Kernel
+// ships with Forge and auto-provisions, so there is nothing to install or pick.
+async function promptBeadsSetup(_question) {
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
-  console.log('Beads Setup (Recommended)');
+  console.log('Issue Store (Forge Kernel)');
   console.log('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
   console.log('');
 
-  const beadsInitialized = isBeadsInitialized();
-  const beadsStatus = checkForBeads();
-
-  if (beadsInitialized) {
-    console.log('✓ Beads is already initialized in this project');
-    console.log('');
-    return;
-  }
-
-  if (beadsStatus) {
-    // Already installed, just need to initialize
-    console.log(`ℹ Beads is installed (${beadsStatus}), but not initialized`);
-    const initBeads = await question('Initialize Beads in this project? (y/n): ');
-
-    if (initBeads.toLowerCase() === 'y') {
-      initializeBeads(beadsStatus);
-    } else {
-      console.log('Skipped Beads initialization. Run manually: bd init');
-    }
-    console.log('');
-    return;
+  const ready = await ensureKernelIssueStore();
+  if (ready) {
+    console.log('✓ Kernel issue store ready (single-machine; team sync not configured)');
   }
-
-  // Not installed
-  console.log('ℹ Beads is not installed');
-  const installBeads = await question('Install Beads? (y/n): ');
-
-  if (installBeads.toLowerCase() !== 'y') {
-    console.log('Skipped Beads installation');
-    console.log('');
-    return;
-  }
-
-  console.log('');
-  console.log('Choose installation method:');
-  console.log('  1. Global (recommended) - Available system-wide');
-  console.log('  2. Local - Project-specific devDependency');
-  console.log('  3. Bunx - Use via bunx (requires bun)');
-  console.log('');
-  const method = await question('Choose method (1-3): ');
-
-  console.log('');
-  installBeadsWithMethod(method);
   console.log('');
 }
 
@@ -3056,72 +3123,6 @@ function installViaBunx(packageName, versionArgs, initFn, toolName) {
   }
 }
 
-// Helper: Install Beads with chosen method - extracted to reduce cognitive complexity
-// SECURITY NOTE: Downloads and executes a remote PowerShell script.
-// The npm @beads/bd package is broken on Windows (GitHub Issue #1031, closed "not planned"),
-// so the official PowerShell installer is the only supported path.
-// Mitigations: HTTPS transport (prevents MITM), official beads repo, user-visible URL.
-// Follow-up: pin to a versioned release tag once beads publishes tagged releases (for example v0.49.1).
-const BEADS_INSTALL_PS1_URL = 'https://raw.githubusercontent.com/steveyegge/beads/main/install.ps1';
-
-
-
-function installBeadsOnWindows() {
-  console.log('  (Windows detected: using PowerShell installer)');
-  console.log(`  Downloading: ${BEADS_INSTALL_PS1_URL}`);
-  secureExecFileSync('powershell.exe', [
-    '-NoProfile', '-NonInteractive', '-Command',
-    `irm ${BEADS_INSTALL_PS1_URL} | iex`
-  ], { stdio: 'inherit' });
-}
-
-
-
-function installBeadsWithMethod(method) { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
-  try {
-    // SECURITY: secureExecFileSync with hardcoded commands
-    if (method === '1') {
-      console.log('Installing Beads globally...');
-      if (process.platform === 'win32') {
-        installBeadsOnWindows();
-      } else {
-        const pkgManager = PKG_MANAGER === 'bun' ? 'bun' : 'npm';
-        secureExecFileSync(pkgManager, ['install', '-g', '@beads/bd'], { stdio: 'inherit' });
-      }
-      console.log('  ✓ Beads installed globally');
-      initializeBeads('global');
-    } else if (method === '2') {
-      console.log('Installing Beads locally...');
-      // On Windows, npm postinstall for @beads/bd runs Expand-Archive which has EPERM file-locking
-      // (GitHub Issue #1031, closed "not planned") — same root cause as global install.
-      // Redirect Windows users to the global PowerShell installer instead.
-      if (process.platform === 'win32') {
-        console.log('  ⚠ Local install not supported on Windows (npm @beads/bd EPERM issue).');
-        console.log('  Falling back to global PowerShell installer...');
-        installBeadsOnWindows();
-      } else {
-        const pkgManager = PKG_MANAGER === 'bun' ? 'bun' : 'npm';
-        secureExecFileSync(pkgManager, ['install', '-D', '@beads/bd'], { stdio: 'inherit', cwd: projectRoot });
-      }
-      console.log('  ✓ Beads installed');
-      // On Windows the fallback was global (PowerShell installer), so init as 'global'
-      initializeBeads(process.platform === 'win32' ? 'global' : 'local');
-    } else if (method === '3') {
-      installViaBunx('@beads/bd', ['version'], initializeBeads, 'Beads');
-    } else {
-      console.log('Invalid choice. Skipping Beads installation.');
-    }
-  } catch (err) {
-    console.warn('Beads installation failed:', err.message);
-    console.log('  ⚠ Failed to install Beads:', err.message);
-    if (process.platform === 'win32') {
-      console.log(`  Run manually: irm ${BEADS_INSTALL_PS1_URL} | iex`);
-    } else {
-      console.log(`  Run manually: ${PKG_MANAGER === 'bun' ? 'bun add -g' : 'npm install -g'} @beads/bd && bd init`);
-    }
-  }
-}
-
 // Helper: Get package-manager-specific install args for Skills
 
 
@@ -3231,7 +3232,7 @@ async function setupProjectTools(rl, question) {
   console.log('');
   console.log('Forge recommends three tools for enhanced workflows:');
   console.log('');
-  console.log('• Beads - Git-backed issue tracking');
+  console.log('• Issue tracking (Forge Kernel) - zero-install, git-backed');
   console.log('  Persists tasks across sessions, tracks dependencies.');
   console.log('  Command: forge ready, forge create, forge close');
   console.log('');
@@ -3245,44 +3246,6 @@ async function setupProjectTools(rl, question) {
   await promptSkillsSetup(question);
 }
 
-// Auto-setup Beads in quick mode - extracted to reduce cognitive complexity
-
-
-// Auto-setup Beads in quick mode - extracted to reduce cognitive complexity
-function autoSetupBeadsInQuickMode() { // NOSONAR — Extracted as-is from bin/forge.js; complexity reduction deferred
-  const beadsStatus = checkForBeads();
-  const beadsInitialized = isBeadsInitialized();
-
-  if (!beadsInitialized && beadsStatus) {
-    console.log('📦 Initializing Beads...');
-    initializeBeads(beadsStatus);
-    console.log('');
-  } else if (!beadsInitialized && !beadsStatus) {
-    console.log('📦 Installing Beads globally...');
-    try {
-      // SECURITY: use PowerShell on Windows (npm @beads/bd is broken on Windows - Issue #1031)
-      if (process.platform === 'win32') {
-        installBeadsOnWindows();
-      } else {
-        const pkgManager = PKG_MANAGER === 'bun' ? 'bun' : 'npm';
-        secureExecFileSync(pkgManager, ['install', '-g', '@beads/bd'], { stdio: 'inherit' });
-      }
-      console.log('  ✓ Beads installed globally');
-      initializeBeads('global');
-    } catch (err) {
-      // Installation failed - provide manual instructions
-      console.log('  ⚠ Could not install Beads automatically');
-      console.log(`    Error: ${err.message}`);
-      if (process.platform === 'win32') {
-        console.log(`  Run manually: irm ${BEADS_INSTALL_PS1_URL} | iex`);
-      } else {
-        console.log(`  Run manually: ${PKG_MANAGER === 'bun' ? 'bun add -g' : 'npm install -g'} @beads/bd && bd init`);
-      }
-    }
-    console.log('');
-  }
-}
-
 // Helper: Auto-install lefthook if not present - extracted to reduce cognitive complexity
 
 
@@ -3326,6 +3289,16 @@ function autoInstallLefthook() { // NOSONAR — Extracted as-is from bin/forge.j
     return;
   }
 
+  // Not in package.json at all. GUARD (kernel 22e33dbf): with no package.json in
+  // projectRoot, `<pkg-mgr> install lefthook` resolves against the nearest ANCESTOR
+  // package.json and installs into the WRONG project (or fails). Skip it — installGitHooks
+  // then wires native .git/hooks, which need no package.json, so enforcement is still live.
+  if (!fs.existsSync(path.join(projectRoot, 'package.json'))) {
+    console.log('  ℹ No package.json here — skipping lefthook install (would target an ancestor); native hooks will back enforcement.');
+    console.log('');
+    return;
+  }
+
   // Not in package.json at all — full install
   console.log('📦 Installing lefthook for git hooks...');
   try {
@@ -3341,32 +3314,13 @@ function autoInstallLefthook() { // NOSONAR — Extracted as-is from bin/forge.j
   console.log('');
 }
 
-// Helper: Verify a tool is callable after install - extracted to reduce cognitive complexity
-
-
-// Helper: Verify a tool is callable after install - extracted to reduce cognitive complexity
-function verifyToolInstall(command, args, toolName) {
-  try {
-    secureExecFileSync(command, args, { stdio: 'ignore' });
-    return true;
-  } catch (_err) { // NOSONAR - S2486: Intentionally ignored; verification failure is handled by caller
-    console.log(`  ⚠ ${toolName} installed but not callable. Check your PATH.`);
-    return false;
-  }
-}
-
 // Helper: Auto-setup tools (Skills) in quick mode - extracted to reduce cognitive complexity
 
 
 // Helper: Auto-setup tools (Skills) in quick mode - extracted to reduce cognitive complexity
-function autoSetupToolsInQuickMode() {
-  // Beads: auto-install or initialize
-  autoSetupBeadsInQuickMode();
-
-  // Post-install verification for Beads
-  if (isBeadsInitialized()) {
-    verifyToolInstall('bd', ['version'], 'Beads');
-  }
+async function autoSetupToolsInQuickMode() {
+  // Issue store: ensure the Forge Kernel store exists (auto-provisioned, no CLI)
+  await ensureKernelIssueStore();
 
   // Skills: only initialize if already installed (recommended tool)
   const skillsStatus = checkForSkills();
@@ -3374,11 +3328,10 @@ function autoSetupToolsInQuickMode() {
     console.log('📦 Initializing Skills...');
     initializeSkills(skillsStatus);
     console.log('');
-  } else if (!skillsStatus) {
-    const installCmd = PKG_MANAGER === 'bun' ? 'bun add -g' : 'npm install -g';
-    console.log(`  ℹ Skills not found — install with: ${installCmd} @forge/skills`);
-    console.log('');
   }
+  // No hint when the optional Skills CLI is absent: setup bundles and renders
+  // Forge's skills itself, and the previously advertised "@forge/skills"
+  // package does not exist on npm (kernel issue 6e554b41).
 }
 
 // Helper: Configure default external services in quick mode - extracted to reduce cognitive complexity
@@ -3410,6 +3363,35 @@ function configureDefaultExternalServices(skipExternal) {
   console.log('Configuration saved to .env.local');
 }
 
+// Install git hooks for a target project root without a full setup run.
+// Reuses the same lefthook install path setup performs so `forge init` can
+// reach a hook-active state (closing the init → HOOKS_NOT_ACTIVE catch-22).
+// Skips silently when there is no package.json to attach hooks to — keeps
+// `forge init` lightweight for bare/non-node repos and avoids surprise installs.
+// Restores mutated module state afterward.
+async function ensureGitHooksInstalled(targetRoot = projectRoot) {
+  // No early bail on a missing package.json (kernel 22e33dbf / B3): the native
+  // .git/hooks fallback needs no package.json, so `forge init` on a bare repo must
+  // still wire enforcement instead of silently skipping it. autoInstallLefthook
+  // guards the package-manager install itself for the no-package.json case.
+  const previousRoot = projectRoot;
+  const previousInteractive = NON_INTERACTIVE;
+  const previousPkgManager = PKG_MANAGER;
+  projectRoot = targetRoot;
+  NON_INTERACTIVE = true;
+  PKG_MANAGER = detectPackageManager();
+  try {
+    autoInstallLefthook();
+    await handleHuskyMigration();
+    installGitHooks();
+    return { installed: true };
+  } finally {
+    projectRoot = previousRoot;
+    NON_INTERACTIVE = previousInteractive;
+    PKG_MANAGER = previousPkgManager;
+  }
+}
+
 // Quick setup with defaults
 
 
@@ -3428,8 +3410,11 @@ async function quickSetup(selectedAgents, skipExternal) {
   });
   console.log('');
 
-  // Copy AGENTS.md (actionLog tracks it via copyFile)
-  const agentsSrc = path.join(packageDir, 'AGENTS.md');
+  // Copy AGENTS.md (actionLog tracks it via copyFile). Quick mode is
+  // non-interactive and overwrites unconditionally, so back up a markerless
+  // (pre-Forge) AGENTS.md first to avoid silent data loss (kernel issue a5399f3d).
+  const agentsSrc = path.join(getPackageRoot(packageDir), 'AGENTS.md');
+  backupMarkerlessAgentsMd();
   copyFile(agentsSrc, 'AGENTS.md');
   console.log('');
 
@@ -3442,20 +3427,23 @@ async function quickSetup(selectedAgents, skipExternal) {
   // Auto-install lefthook if missing
   autoInstallLefthook();
 
-  // Auto-setup project tools (Beads, Skills)
-  autoSetupToolsInQuickMode();
+  // Auto-setup project tools (Kernel issue store, Skills)
+  await autoSetupToolsInQuickMode();
 
-  // Load canonical commands and setup agents (reuse existing helpers)
-  const claudeCommands = await loadAndSetupCanonicalCommands(selectedAgents);
-  await setupSelectedAgents(selectedAgents, claudeCommands);
+  // Setup Claude first if selected, then setup remaining agents
+  if (selectedAgents.includes('claude')) {
+    await setupAgent('claude');
+  }
+  await setupSelectedAgents(selectedAgents);
   ensureWorkflowRuntimeAssets(selectedAgents);
 
   // Detect Husky and migrate before installing Lefthook hooks
   await handleHuskyMigration();
 
-  // Install git hooks for TDD enforcement
+  // Install git hooks for TDD enforcement. LOUD: this is the `forge setup` handler,
+  // so an inert-hooks result must fail non-zero (B3), not end green.
   console.log('');
-  installGitHooks();
+  installGitHooks({ loud: true });
 
   // Configure external services with defaults (unless skipped)
   configureDefaultExternalServices(skipExternal);
@@ -3469,6 +3457,9 @@ async function quickSetup(selectedAgents, skipExternal) {
   console.log('');
   console.log(renderSetupSummary(actionLog, selectedAgents, VERBOSE_MODE, { status: getSetupSummaryStatus() }));
   printSetupNotes();
+  // One-step onboarding: run `forge init` when config is still absent (ac0b38c7).
+  // Hooks + Beads already handled above, so init skips those side effects.
+  await finalizeWorkflowConfig({ hooksAlreadyInstalled: true });
   console.log('');
 }
 
@@ -3509,7 +3500,7 @@ function setupAgentsMdFile(flags, skipFiles) {
     return;
   }
 
-  const agentsSrc = path.join(packageDir, 'AGENTS.md');
+  const agentsSrc = path.join(getPackageRoot(packageDir), 'AGENTS.md');
   const agentsDest = path.join(projectRoot, 'AGENTS.md');
   const mergeStrategy = flags.merge || 'smart';
 
@@ -3589,7 +3580,6 @@ function displayExistingInstallation(projectStatus) {
     : 'Found partial installation:');
 
   if (projectStatus.hasAgentsMd) console.log('  - AGENTS.md');
-  if (projectStatus.hasClaudeCommands) console.log('  - .claude/commands/');
   if (projectStatus.hasEnvLocal) console.log('  - .env.local');
   console.log('');
 }
@@ -3601,7 +3591,6 @@ function displayExistingInstallation(projectStatus) {
 async function promptForOverwriteDecisions(question, projectStatus, flags = {}) {
   const skipFiles = {
     agentsMd: false,
-    claudeCommands: false
   };
 
   if (flags.keep) {
@@ -3609,10 +3598,6 @@ async function promptForOverwriteDecisions(question, projectStatus, flags = {})
       skipFiles.agentsMd = true;
       console.log('  Keeping existing AGENTS.md (--keep)');
     }
-    if (projectStatus.hasClaudeCommands) {
-      skipFiles.claudeCommands = true;
-      console.log('  Keeping existing .claude/commands/ (--keep)');
-    }
     return skipFiles;
   }
 
@@ -3622,12 +3607,6 @@ async function promptForOverwriteDecisions(question, projectStatus, flags = {})
     console.log(overwriteAgents ? '  Will overwrite AGENTS.md' : '  Keeping existing AGENTS.md');
   }
 
-  if (projectStatus.hasClaudeCommands) {
-    const overwriteCommands = await askYesNo(question, 'Found existing .claude/commands/. Overwrite?', true);
-    skipFiles.claudeCommands = !overwriteCommands;
-    console.log(overwriteCommands ? '  Will overwrite .claude/commands/' : '  Keeping existing .claude/commands/');
-  }
-
   if (projectStatus.type !== 'fresh') {
     console.log('');
   }
@@ -3635,47 +3614,17 @@ async function promptForOverwriteDecisions(question, projectStatus, flags = {})
   return skipFiles;
 }
 
-// Helper: Load and setup canonical commands - extracted to reduce cognitive complexity
-
-
-// Helper: Load and setup canonical commands - extracted to reduce cognitive complexity
-async function loadAndSetupCanonicalCommands(selectedAgents, skipFiles) {
-  const claudeCommands = {};
-  const needsClaudeCommands = selectedAgents.includes('claude') ||
-    selectedAgents.some(a => AGENTS[a].needsConversion || AGENTS[a].copyCommands);
-
-  if (!needsClaudeCommands) {
-    return claudeCommands;
-  }
-
-  // First ensure Claude is set up
-  if (selectedAgents.includes('claude')) {
-    await setupAgent('claude', null, skipFiles);
-  }
-
-  // Then load the commands (from existing or newly created)
-  getWorkflowCommands().forEach(cmd => {
-    const cmdPath = path.join(projectRoot, `.claude/commands/${cmd}.md`);
-    const content = readFile(cmdPath);
-    if (content) {
-      claudeCommands[`${cmd}.md`] = content;
-    }
-  });
-
-  return claudeCommands;
-}
-
 // Helper: Setup all selected agents - extracted to reduce cognitive complexity
 
 
 // Helper: Setup all selected agents - extracted to reduce cognitive complexity
-async function setupSelectedAgents(selectedAgents, claudeCommands, skipFiles) {
+async function setupSelectedAgents(selectedAgents, skipFiles) {
   const totalAgents = selectedAgents.length;
   for (const [index, agentKey] of selectedAgents.entries()) {
     const agent = AGENTS[agentKey];
     console.log(`\n[${index + 1}/${totalAgents}] Setting up ${agent.name}...`);
     if (agentKey !== 'claude') { // Claude already done above
-      await setupAgent(agentKey, claudeCommands, skipFiles);
+      await setupAgent(agentKey, skipFiles);
     }
   }
 
@@ -3775,7 +3724,7 @@ async function interactiveSetupWithFlags(flags) {
   const selectedAgents = await promptForAgentSelection(question, agentKeys);
 
   // Check GitHub CLI prerequisite now that selectedAgents is known
-  if (requiresGithubCliForSetup(selectedAgents, { syncEnabled: SYNC_ENABLED })) {
+  if (requiresGithubCliForSetup(selectedAgents)) {
     checkPrerequisites({ requireGithubCli: true });
   }
 
@@ -3790,11 +3739,13 @@ async function interactiveSetupWithFlags(flags) {
   setupCoreDocs();
   console.log('');
 
-  // Load Claude commands if needed (delegated to helper)
-  const claudeCommands = await loadAndSetupCanonicalCommands(selectedAgents, skipFiles);
+  // Setup Claude first if selected (delegated to helper), then remaining agents
+  if (selectedAgents.includes('claude')) {
+    await setupAgent('claude', skipFiles);
+  }
 
   // Setup each selected agent with progress indication (delegated to helper)
-  await setupSelectedAgents(selectedAgents, claudeCommands, skipFiles);
+  await setupSelectedAgents(selectedAgents, skipFiles);
   ensureWorkflowRuntimeAssets(selectedAgents);
 
   // Handle external services step (delegated to helper)
@@ -3805,6 +3756,10 @@ async function interactiveSetupWithFlags(flags) {
 
   // Display final summary (delegated to helper)
   displaySetupSummary(selectedAgents);
+
+  // One-step onboarding: this path never writes .forge/config.yaml itself, so
+  // run `forge init` when the config is still absent (ac0b38c7).
+  await finalizeWorkflowConfig();
 }
 
 // Main
@@ -3903,15 +3858,10 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
       addFileAction(dir + '/', 'Create agent directory');
     }
 
-    // Claude-specific files
+    // Claude-specific files (skills are listed by the per-skill block below).
+    // Claude gets policy via CLAUDE.md → AGENTS.md, not always-on .claude/rules/* files.
     if (agentKey === 'claude') {
-      const cmds = getWorkflowCommands();
-      for (const cmd of cmds) {
-        addFileAction(`.claude/commands/${cmd}.md`, 'Workflow command');
-      }
-      addFileAction('.claude/rules/workflow.md', 'Workflow rules');
       addFileAction('.claude/scripts/load-env.sh', 'Environment loader script');
-      addFileAction('.claude/skills/forge-workflow/SKILL.md', 'Forge workflow skill');
       addFileAction('.mcp.json', 'MCP server configuration');
       addFileAction('CLAUDE.md', 'Claude root config (links to AGENTS.md)');
     }
@@ -3922,7 +3872,7 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
       }
     }
 
-    // Cursor-specific files
+    // Cursor-specific files (rendered from the canonical rules/ source)
     if (agent.customSetup === 'cursor') {
       addFileAction('.cursor/rules/forge-workflow.mdc', 'Cursor workflow rule');
       addFileAction('.cursor/rules/tdd-enforcement.mdc', 'Cursor TDD rule');
@@ -3930,54 +3880,19 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
       addFileAction('.cursor/rules/documentation.mdc', 'Cursor documentation rule');
     }
 
-    if (agentKey === 'kilocode') {
-      addFileAction('.kilocode/workflows/forge-workflow.md', 'Kilo native workflow');
-      addFileAction('.kilocode/rules/workflow.md', 'Kilo native rules');
-      addFileAction('.kilocode/skills/forge-workflow/SKILL.md', 'Kilo native skill');
-    }
-
-    if (agent.customSetup === 'copilot') {
-      addFileAction('.github/copilot-instructions.md', 'Copilot root instructions');
-      addFileAction('.github/instructions/typescript.instructions.md', 'Copilot TypeScript instructions');
-      addFileAction('.github/instructions/testing.instructions.md', 'Copilot testing instructions');
-      addFileAction('.github/prompts/red.prompt.md', 'Copilot RED prompt');
-      addFileAction('.github/prompts/green.prompt.md', 'Copilot GREEN prompt');
-    }
-
-    if (agent.customSetup === 'opencode') {
-      addFileAction('opencode.json', 'OpenCode root config');
-      addFileAction('.opencode/agents/plan-review.md', 'OpenCode plan-review agent');
-      addFileAction('.opencode/agents/tdd-build.md', 'OpenCode tdd-build agent');
-    }
-
-    // Agent commands (converted from Claude format)
-    if (agent.needsConversion || agent.copyCommands || agent.promptFormat) {
-      const cmds = getWorkflowCommands();
-      const targetDir = agent.dirs[0];
-      for (const cmd of cmds) {
-        const ext = agent.promptFormat ? '.prompt.md' : '.md';
-        addFileAction(`${targetDir}/${cmd}${ext}`, 'Converted workflow command');
-      }
-    }
-
-    // Agent rules (copied from Claude)
-    if (agent.needsConversion) {
-      const rulesDir = agent.dirs.find(d => d.includes('/rules'));
-      if (rulesDir) {
-        addFileAction(`${rulesDir}/workflow.md`, 'Workflow rules');
-      }
-    }
-
     // Agent skill
     if (agentKey === 'codex') {
-      const skillEntries = buildCodexSkillInstallPlan(packageDir, { env: process.env, homeDir: os.homedir() });
+      const skillEntries = buildCodexSkillInstallPlan(getPackageRoot(packageDir), { env: process.env, homeDir: os.homedir() });
       for (const entry of skillEntries) {
         addFileAction(entry.displayPath, 'Codex stage skill');
       }
-    } else if (agent.hasSkill) {
-      const skillDir = agent.dirs.find(d => d.includes('/skills/'));
-      if (skillDir) {
-        addFileAction(`${skillDir}/SKILL.md`, 'Forge workflow skill');
+    } else if (agent.hasSkill && agent.skillsDir) {
+      // Skills ship whole directories (SKILL.md + any nested assets); list every
+      // file so --dry-run reflects the real filesystem changes, not just SKILL.md.
+      for (const skill of listCanonicalSkills(getPackageRoot(packageDir))) {
+        for (const rel of listFilesRecursive(skill.sourcePath)) {
+          addFileAction(`${agent.skillsDir}/${skill.name}/${rel}`, 'Forge skill');
+        }
       }
     }
 
@@ -3990,6 +3905,7 @@ function dryRunSetup(agents) { // NOSONAR — Extracted as-is from bin/forge.js;
   // Git hooks
   addFileAction('lefthook.yml', 'Git hook configuration');
   addFileAction('.forge/hooks/check-tdd.js', 'TDD enforcement hook');
+  addFileAction('.forge/hooks/forge-native-hook.js', 'Native-hook enforcement adapter (Claude/Cursor)');
 
   // Print dry-run summary
   console.log('');
@@ -4012,7 +3928,7 @@ async function executeSetup(config) {
   // Check prerequisites
   checkPrerequisites({
     requireBeadsCli: true,
-    requireGithubCli: requiresGithubCliForSetup(agents, { syncEnabled: SYNC_ENABLED }),
+    requireGithubCli: requiresGithubCliForSetup(agents),
     requireJq: true,
     commandRunner,
   });
@@ -4023,7 +3939,7 @@ async function executeSetup(config) {
   if (fs.existsSync(agentsDest)) {
     actionLog.add('AGENTS.md', 'skipped', 'already exists');
   } else {
-    const agentsSrc = path.join(packageDir, 'AGENTS.md');
+    const agentsSrc = path.join(getPackageRoot(packageDir), 'AGENTS.md');
     copyFile(agentsSrc, 'AGENTS.md');
   }
   console.log('');
@@ -4034,22 +3950,13 @@ async function executeSetup(config) {
 
   const skipFiles = {
     agentsMd: keepExisting && fs.existsSync(path.join(projectRoot, 'AGENTS.md')),
-    claudeCommands: keepExisting && fs.existsSync(path.join(projectRoot, '.claude', 'commands'))
   };
 
-  if (skipFiles.claudeCommands) {
-    console.log('  Keeping existing .claude/commands/ (--keep)');
+  // Setup Claude first if selected, then remaining agents
+  if (agents.includes('claude')) {
+    await setupAgent('claude', skipFiles);
   }
-
-  // Load canonical commands — use loadAndSetupCanonicalCommands when claude is selected
-  // so that .claude/commands/ are seeded before reading them
-  const claudeCommands = agents.includes('claude')
-    ? await loadAndSetupCanonicalCommands(agents, skipFiles)
-    : loadClaudeCommands(agents);
-
-  // Setup agents with progress output (setupSelectedAgents skips claude internally
-  // since loadAndSetupCanonicalCommands already handled it above)
-  await setupSelectedAgents(agents, claudeCommands, skipFiles);
+  await setupSelectedAgents(agents, skipFiles);
   ensureWorkflowRuntimeAssets(agents);
   ensureWorkflowShellPolicy(agents);
   repairDeclaredLefthookDependency(agents);
@@ -4057,9 +3964,10 @@ async function executeSetup(config) {
   // Detect Husky and migrate before installing Lefthook hooks
   await handleHuskyMigration();
 
-  // Install git hooks for TDD enforcement
+  // Install git hooks for TDD enforcement. LOUD: this is the `forge setup` handler,
+  // so an inert-hooks result must fail non-zero (B3), not end green.
   console.log('');
-  installGitHooks();
+  installGitHooks({ loud: true });
 
   // External services (unless skipped)
   await handleExternalServices(skipExternal, agents);
@@ -4073,6 +3981,9 @@ async function executeSetup(config) {
   console.log('');
   console.log(renderSetupSummary(actionLog, agents, VERBOSE_MODE, { status: getSetupSummaryStatus() }));
   printSetupNotes();
+  // One-step onboarding: run `forge init` when config is still absent (ac0b38c7).
+  // Hooks + Beads already handled above, so init skips those side effects.
+  await finalizeWorkflowConfig({ hooksAlreadyInstalled: true });
   console.log('');
 }
 
@@ -4082,36 +3993,12 @@ async function executeSetup(config) {
 // Helper: Scaffold Beads GitHub sync when --sync flag is provided
 async function handleSyncScaffold() {
   console.log('');
-  console.log('Scaffolding Beads GitHub sync workflows (--sync)...');
+  console.log('Beads GitHub sync scaffolding is deprecated (--sync).');
   try {
-    // Scaffold sync files using the new lib module
-    const result = scaffoldBeadsSync(projectRoot, packageDir);
-    for (const f of (result.filesCreated || [])) {
-      console.log(`  Created: ${f}`);
-    }
-    for (const f of (result.filesSkipped || [])) {
-      console.log(`  Skipped: ${f} (already exists)`);
-    }
-
-    // Detect default branch and pin forge-managed workflows to the repo baseline Beads version.
-    const branch = detectDefaultBranch(projectRoot);
-    const beadsVersion = DEFAULT_BEADS_VERSION;
-    const workflowDir = path.join(projectRoot, '.github', 'workflows');
-    templateWorkflows(workflowDir, branch, beadsVersion, result.filesCreated || []);
-    console.log(`  Branch: ${branch}, Beads version: ${beadsVersion}`);
-
-    // PAT setup: interactive when possible, reminder otherwise
-    try {
-      const patResult = setupPAT(projectRoot, { interactive: !NON_INTERACTIVE });
-      if (patResult.success) {
-        console.log('  PAT configured for Beads sync');
-      } else if (patResult.reminder) {
-        console.log(`  ${patResult.reminder}`);
-      } else if (patResult.instructions) {
-        console.log(`  ${patResult.instructions.split('\n')[0]}`);
-      }
-    } catch (_patErr) { // NOSONAR — best-effort PAT setup, non-fatal
-      // PAT setup is best-effort — don't block sync scaffold
+    const result = scaffoldBeadsSync(projectRoot, getPackageRoot(packageDir));
+    console.log(`  ${result.message}`);
+    for (const f of result.filesRemoved || []) {
+      console.log(`  Removed deprecated sync file: ${f}`);
     }
   } catch (err) {
     console.error(`  Error scaffolding GitHub-Beads sync: ${err.message}`);
@@ -4124,7 +4011,7 @@ async function handleSyncScaffold() {
 // Helper: Handle setup command in non-quick mode
 async function handleSetupCommand(selectedAgents, flags) {
   if (!Array.isArray(selectedAgents) || selectedAgents.length === 0) {
-    return interactiveSetupWithFlags(flags);
+    return runInteractiveSetupFallback(flags);
   }
 
   // Allow callers (e.g. reinstall) to override projectRoot without process.chdir()
@@ -4144,6 +4031,10 @@ async function handleSetupCommand(selectedAgents, flags) {
   }
 }
 
+async function runInteractiveSetupFallback(flags, interactiveSetup = interactiveSetupWithFlags) {
+  return interactiveSetup(flags);
+}
+
 // Helper: Handle external services configuration
 
 
@@ -4179,7 +4070,7 @@ async function handleExternalServices(skipExternal, selectedAgents) {
  * Detect which agents are already configured in a project directory.
  * Checks for the presence of each agent's configured directories/files.
  * Returns the external-facing setup IDs used by the setup UX, including
- * legacy aliases such as `claude-code`, `github-copilot`, and `roo-code`.
+ * legacy aliases such as `claude-code`.
  * Callers that need raw plugin IDs for internal lookup must normalize first.
  *
  * @param {string} dir - Project directory to scan
@@ -4190,8 +4081,6 @@ function detectConfiguredAgents(dir) {
   const detected = [];
   const legacyAgentIds = {
     claude: 'claude-code',
-    copilot: 'github-copilot',
-    roo: 'roo-code',
   };
 
   pluginManager.getAllPlugins().forEach((plugin, id) => {
@@ -4213,7 +4102,7 @@ function detectConfiguredAgents(dir) {
  * Used during setup --clean or reset flows.
  *
  * @param {string} dir - Project directory
- * @param {string} agentName - Agent slug (e.g. 'cursor', 'cline')
+ * @param {string} agentName - Agent slug (e.g. 'cursor', 'codex')
  * @param {object} [manifest] - Optional sync manifest with file paths to remove
  * @returns {{ removed: string[], errors: string[] }}
  */
@@ -4273,6 +4162,9 @@ const SETUP_FLAG_DEFAULTS = Object.freeze({
   verbose: false,
   dryRun: false,
   quick: false,
+  minimal: false,
+  standard: false,
+  full: false,
   skipExternal: false,
   sync: false,
   symlink: false,
@@ -4287,6 +4179,9 @@ const SIMPLE_SETUP_FLAG_UPDATES = Object.freeze({
   '--verbose': { verbose: true },
   '--dry-run': { dryRun: true },
   '--quick': { quick: true },
+  '--minimal': { minimal: true },
+  '--standard': { standard: true },
+  '--full': { full: true },
   '--skip-external': { skipExternal: true },
   '--sync': { sync: true },
   '--symlink': { symlink: true },
@@ -4364,6 +4259,9 @@ function mergeSetupFlags(flags, argv) {
     verbose: Boolean(flags.verbose || setupFlags.verbose),
     dryRun: Boolean(flags.dryRun || setupFlags.dryRun),
     quick: Boolean(flags.quick || setupFlags.quick),
+    minimal: Boolean(flags.minimal || setupFlags.minimal),
+    standard: Boolean(flags.standard || setupFlags.standard),
+    full: Boolean(flags.full || setupFlags.full),
     skipExternal: Boolean(flags.skipExternal || setupFlags.skipExternal),
     sync: Boolean(flags.sync || setupFlags.sync),
     symlink: Boolean(flags.symlink || setupFlags.symlink),
@@ -4374,9 +4272,6 @@ function mergeSetupFlags(flags, argv) {
 function normalizeDetectedAgent(agentName) {
   const aliases = {
     'claude-code': 'claude',
-    'github-copilot': 'copilot',
-    'kilo-code': 'kilocode',
-    'roo-code': 'roo',
   };
   return aliases[agentName] || agentName;
 }
@@ -4420,6 +4315,22 @@ module.exports = {
     resetSetupNotes();
     PKG_MANAGER = detectPackageManager();
 
+    if (flags.minimal || flags.standard || flags.full) {
+      const selectedProfiles = [];
+      if (flags.minimal) selectedProfiles.push('minimal');
+      if (flags.standard) selectedProfiles.push('standard');
+      if (flags.full) selectedProfiles.push('full');
+      if (selectedProfiles.length > 1) {
+        return {
+          success: false,
+          error: `Conflicting profile flags: ${selectedProfiles.join(', ')}. Choose exactly one of --minimal, --standard, or --full.`,
+        };
+      }
+
+      const [profile] = selectedProfiles;
+      return initCommand.handler([`--profile=${profile}`, '--yes', ...(flags.force ? ['--force'] : [])], flags, projectRoot);
+    }
+
     // Determine agents to install
     let selectedAgents = determineSelectedAgents(flags);
 
@@ -4454,22 +4365,34 @@ module.exports = {
       return { success: true };
     }
 
+    if (flags.sync && selectedAgents.length === 0) {
+      await handleSyncScaffold();
+      return { success: true };
+    }
+
     if (selectedAgents.length > 0) {
       await handleSetupCommand(selectedAgents, flags);
       return { success: true };
     }
 
-    await interactiveSetupWithFlags(flags);
+    await runInteractiveSetupFallback(flags);
     return { success: true };
   },
 
   // Expose internals for testing and cross-command use
+  describeHookEnforcement,
+  resolveHookEnforcementState,
+  buildHookVerdict,
   checkPrerequisites,
   setupCoreDocs,
   displaySetupSummary,
+  printForgeInitNextStep,
+  finalizeWorkflowConfig,
+  backupMarkerlessAgentsMd,
   setupAgent,
   quickSetup,
   interactiveSetupWithFlags,
+  _runInteractiveSetupFallback: runInteractiveSetupFallback,
   dryRunSetup,
   handleSetupCommand,
   executeSetup,
@@ -4477,29 +4400,35 @@ module.exports = {
   _interactiveSetup,
   configureExternalServices,
   configureDefaultExternalServices,
-  installBeadsWithMethod,
   installSkillsWithMethod,
   installViaBunx,
   autoInstallLefthook,
   autoSetupToolsInQuickMode,
+  ensureGitHooksInstalled,
+  forgeShouldWriteLefthookConfig,
+  FORGE_USER_LEFTHOOK_YML,
   setupClaudeMcpConfig,
+  setupCursorMcpConfig,
+  setupClaudePermissions,
+  setupCursorIgnore,
+  setupClaudeHooksConfig,
+  setupCursorHooksConfig,
   displayMcpStatus,
   displayEnvTokenResults,
   minimalInstall,
   determineSelectedAgents,
   handlePathSetup,
-  loadAndSetupCanonicalCommands,
   detectConfiguredAgents,
   removeAgentFiles,
   parseSetupFlags,
   mergeSetupFlags,
-  getWorkflowCommands,
   getWorkflowRuntimeAssets,
   findMissingWorkflowRuntimeAssets,
   ensureWorkflowShellPolicy,
   repairWorkflowRuntimeAssets,
   repairRuntimeReadiness,
   _showBanner: showBanner,
+  backupAndRemoveLegacyCursorRules,
 
   // State accessors for testing
   _getState: () => ({ projectRoot, FORCE_MODE, VERBOSE_MODE, NON_INTERACTIVE, SYMLINK_ONLY, SYNC_ENABLED, PKG_MANAGER }),