worclaude 2.6.3 → 2.7.1

package/CHANGELOG.md

@@ -4,6 +4,62 @@ All notable changes to worclaude are documented in this file. Format loosely fol
 
 ## [Unreleased]
 
+## [2.7.1] — 2026-04-24
+
+Three `/setup` UX follow-ups from v2.7.0 confirmation testing, shipped as a single patch PR. The `?` / `help` trigger introduced in v2.7.0 turned out to collide with Claude Code's built-in keyboard-shortcut overlay (pressing `?` opens the shortcut panel before /setup's parser sees the keystroke); switched to the `help` keyword only. `worclaude init`'s `runOptionalExtras` was the only place in the init flow still using `inquirer type: 'confirm'` (rendered as `(y/N)`) — converted to `type: 'list'` arrow-key menus so every yes/no in init behaves consistently. CONFIRM_MEDIUM now invokes `AskUserQuestion` directly when the per-item option count fits the tool's `maxItems: 4` schema cap, with the consequence info ("Will be saved as") carried inside each option's `description` field; falls back to the verbatim text prompt (using `help` instead of `?`) when the count exceeds 4. CONFIRM_HIGH stays text-parse — detection lists routinely exceed 4 items. No consumer-visible schema or CLI surface additions.
+
+### Fixed
+
+- **`/setup` `?` help trigger → `help` keyword** (PR #119) — 9 occurrences across CONFIRM_HIGH + CONFIRM_MEDIUM prompt templates, response-parsing bullets, error restates, and the Field-help table intro. Explanatory notes added so future maintainers don't re-add `?`.
+- **`worclaude init` prompt-type consistency** (PR #119) — `runOptionalExtras` (src/commands/init.js:77-93) converted the plugin.json and gtd-memory prompts from `type: 'confirm'` (the only `(y/N)` text inputs in init) to `type: 'list'` with boolean-valued Yes/No choices. Regression test inspects `inquirer.prompt.mock.calls` directly.
+
+### Changed
+
+- **`/setup` CONFIRM_MEDIUM (≤4 options) uses `AskUserQuestion`** (PR #119) — State 3 split into Path 1 (AskUserQuestion path) and Path 2 (verbatim text fallback, >4 options). Rule #5 widens the AskUserQuestion permit to include CONFIRM_MEDIUM. Rule #7 picks up an explicit EXCEPTION paragraph. Storage rule from v2.6.5 (`mediumResolved[field]` must be a string) applies uniformly across both paths.
+
+### Docs
+
+- **`docs/spec/SPEC.md` `/setup` section** (this /sync) — reflects the `help`-keyword-only trigger and the CONFIRM_MEDIUM ≤4-option AskUserQuestion path.
+- **`docs/spec/PROGRESS.md`** (this /sync) — new v2.7.1 release entry; Stats refreshed (782 → 788 tests).
+
+## [2.7.0] — 2026-04-23
+
+`/setup` hardening + UX revamp release. PR #115 closes 8 backend bug clusters surfaced by the v2.6.3 manual test matrix (upgrade-flow correctness, downgrade guard, doctor ghost detection, scaffolder exec bits, Commander routing). PR #116 fixes four `/setup` template failure modes — missing `schemaVersion` in SCAN state, `readme` object-shape mismatch in CONFIRM_MEDIUM, all-22-questions-asked despite detection, accept-off-topic-as-answer — and adds a `--from-file` flag to `worclaude setup-state save` plus `Bash(worclaude:*)` permissions so `/setup` runs without approval-prompt interruption. PR #117 adopts Claude Code's `AskUserQuestion` tool for 10 enumerable interview questions (arrow-key selection instead of free-text), redesigns CONFIRM prompts with a "Will be saved as" consequence sub-line and `?` / `help` command, and drops the 80-char readme truncation so users can read the full description before accepting. Dogfood-relevant: `.claude/commands/setup.md` auto-updates on `worclaude upgrade` to pick up the new template.
+
+### Added
+
+- **`worclaude setup-state save --from-file <path>`** (PR #116) — new CLI flag reading JSON state from a file path, mutually exclusive with `--stdin`. `/setup` now uses `Write` → `.claude/cache/setup-state.draft.json` → `--from-file` instead of heredoc-piped `--stdin`, eliminating the shell-interpolation safety prompts that interrupted every state transition.
+- **`Bash(worclaude:*)` permission entries in `templates/settings/base.json`** (PR #116) — scoped for `worclaude`, `worclaude scan`, and `worclaude setup-state`. Freshly init'd projects run `/setup` end-to-end without approval prompts.
+- **`/setup` Interaction mode contract** (PR #117) — four modes: `selectable` (`AskUserQuestion` single-choice), `multi-selectable` (`AskUserQuestion` multi-choice with `None` + `Other`), `hybrid` (detection pre-fill + accept/edit/replace), and `free-text`. Ten interview questions get non-default modes: `arch.classification`, `conventions.errors` / `logging` / `api_format`, `verification.staging` (selectable); `arch.external_apis`, `verification.required_checks` (multi-selectable); `features.core` / `nice_to_have` / `non_goals` (hybrid). Fallback to numbered-list parsing for Claude Code versions without `AskUserQuestion`.
+- **`/setup` Field-help table** (PR #117) — single-source-of-truth reference listing all 14 detection fields + 22 questionIds with plain-English description, target output file/section, and example answer. Drives both the CONFIRM "→ Will be saved as: <target>" consequence line and the `?` / `help` command output.
+- **`/setup` Detection-skip matrix** (PR #116) — auto-fills four questionIds with `"[auto-filled from <field>]"` when the scanner already answered them: `story.problem` (via readme), `arch.classification` (via monorepo), `arch.external_apis` (via externalApis), `workflow.new_dev_steps` (via scripts + readme).
+
+### Changed
+
+- **`/setup` CONFIRM prompts** (PR #117) — `readme` render is no longer truncated to 80 chars + `…` (verbatim, 100-char soft-wrap); every detected item shows `→ Will be saved as: <target>` sub-line; `?` / `help` response produces the Field-help block without advancing state.
+- **`/setup` INTERVIEW reply handling** (PR #116) — explicit classifier step with Answer / Skip / Cancel / Back / OFF-TOPIC buckets. OFF-TOPIC MUST restate, MUST NOT record, MUST NOT advance, MUST NOT persist. "Prefer off-topic when uncertain" guidance makes the rule less discretionary.
+- **`/setup` SCAN state** (PR #116) — explicit `schemaVersion: 1` in a worked JSON example. Persist step uses `--from-file` with a `.claude/cache/setup-state.draft.json` staging path.
+- **`/setup` CONFIRM_MEDIUM Storage rule** (PR #116) — `mediumResolved[field]` MUST be a string (never the raw `item.value` object). Applies to `readme` specifically, where the detector returns `{projectDescription, setupInstructions, fullPath}`.
+- **`worclaude setup-state` validator error** (PR #116) — `mediumResolved.<field> must be a string` message now includes the received type and points at the CONFIRM_MEDIUM Storage rule.
+- **`worclaude upgrade` preview** (PR #115) — new "Deleted (removed in current version)" section shows phantom hash entries (`categories.missingUntracked`) that the upgrade will prune. Previously silent.
+- **`scaffoldAgentsMd` helper** (PR #115) — shared between `init.js scaffoldFresh` and `merger.js mergeAgentsMd`. Both call sites preserve pre-existing AGENTS.md and write the template alongside under `.claude/workflow-ref/AGENTS.md`.
+- **`.claude/settings.json`** (PR #116, dogfood) — this repo's own install merges in `Bash(worclaude:*)` permissions so the dev-repo's Claude Code session doesn't hit approval prompts.
+
+### Fixed
+
+- **Legacy `*.workflow-ref.md` siblings stranded on version match** (PR #115) — `migrateWorkflowRefLocation` is now called before `upgrade.js`'s version-match early-exit and inside `runRepairOnlyFlow`. Projects with leftover siblings on the current version self-heal on the next `worclaude upgrade`.
+- **Silent future-version downgrade via `worclaude upgrade --yes`** (PR #115) — new `semverGreaterThan` helper refuses downgrades with an actionable message (`Refusing to downgrade: installed vX.Y.Z is newer than CLI vA.B.C`) instead of rewriting meta to an older version with a success banner.
+- **`doctor` missed ghost learnings files** (PR #115) — the `.claude/learnings/` check now warns on `.md` files present on disk but missing from `index.json`. Orphan detection (reverse direction) was already working.
+- **`worclaude upgrade --yes` crashed on hook-conflict prompt** (PR #115) — discovered while scripting real-old-CLI upgrades during the v2.6.3 test cycle. `--yes` now threads into `promptHookConflict` and returns `'keep'` (safest default: never clobbers user customizations). Scripted upgrades across hook-template boundaries no longer require manual answers.
+- **Fresh `worclaude init` silently overwrote existing AGENTS.md** (PR #115) — `scaffoldFresh` gates the write on `fileExists(AGENTS.md)` just like the merge path does. User-authored Cursor/Codex AGENTS.md is preserved byte-for-byte; template goes to `.claude/workflow-ref/AGENTS.md`.
+- **Hook `.cjs` files had inconsistent exec bits post-scaffold** (PR #115) — `scaffoldHooks` now runs `fs.chmod(destPath, 0o755)` after each copy (POSIX-guarded). Previously dependent on template source mode; some files landed as `755`, some as `644`.
+- **`worclaude setup-state <unknown>` exited with Commander's default code 1** (PR #115) — `setupState.on('command:*', ...)` listener emits the spec-matching `Error: unknown setup-state subcommand: <x> (expected one of show, save, reset, resume-info)` and sets `process.exitCode = 2`, aligning with the exit-2 convention `setup-state.js` already uses for bad arguments.
+
+### Docs
+
+- **`docs/spec/SPEC.md` `/setup` section** (this /sync) — rewritten to reflect the v2.7.0 surface: `--from-file` persistence path, Detection-skip matrix, Interaction mode contract, Field-help table, OFF-TOPIC classifier, `?` / `help` command, `AskUserQuestion` whitelisted at INTERVIEW states only.
+- **`docs/spec/PROGRESS.md`** (this /sync) — new v2.6.3 and v2.7.0 release entries; Stats refreshed (729 → 782 tests, 53 → 57 test files).
+
 ## [2.6.3] — 2026-04-22
 
 Second supply-chain scanner mirrored after Socket. Adds a `.snyk` policy file at the repo root with `exclude.global: [tests/fixtures/**]` so Snyk Open Source — whether invoked via the Snyk CLI, the `snyk/actions/node` GitHub Action, or any future integration — skips the intentionally-outdated fixture manifests under `tests/fixtures/scanner/**` that exist solely as deterministic inputs to the Part A project-scanner detectors (`next@14.2.3`, `vitest@1.4.0`, `prisma@5.10.0`, etc.). The fixtures are never installed (not referenced from root `package.json`), never shipped (excluded from the npm tarball by the `files` whitelist), and never executed. `SECURITY.md` is updated to name `.snyk` alongside `socket.yml` in the fixture-exclusion paragraph. The installed Snyk GitHub App only imports root `package.json` today, so the most immediate effect is keeping local `snyk test` runs honest; the file is also load-bearing for any future workflow that fails the build on high-severity findings. No runtime change for worclaude consumers.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "worclaude",
-  "version": "2.6.3",
+  "version": "2.7.1",
   "description": "The Workflow Layer for Claude Code — scaffold agents, commands, skills, hooks, and memory into any project",
   "type": "module",
   "bin": {

package/src/commands/doctor.js

@@ -770,11 +770,27 @@ async function checkLearnings(projectRoot) {
       orphans.push(entry.file);
     }
   }
-  if (orphans.length > 0) {
-    return orphans.map((f) =>
-      result(WARN, `Learnings entry: ${f}`, `Entry references missing file '${f}'`)
+
+  const indexedFiles = new Set(entries.map((e) => e?.file).filter(Boolean));
+  const diskFiles = (await fs.readdir(learningsDir)).filter(
+    (f) => f.endsWith('.md') && f !== '.gitkeep'
+  );
+  const ghosts = diskFiles.filter((f) => !indexedFiles.has(f));
+
+  const findings = [];
+  for (const f of orphans) {
+    findings.push(result(WARN, `Learnings entry: ${f}`, `Entry references missing file '${f}'`));
+  }
+  for (const f of ghosts) {
+    findings.push(
+      result(
+        WARN,
+        `Learnings ghost file: ${f}`,
+        `File exists but not referenced by index.json — run /learn to capture or delete manually`
+      )
     );
   }
+  if (findings.length > 0) return findings;
   return [result(PASS, `Learnings: ${entries.length} entries captured`, null)];
 }
 

package/src/commands/init.js

@@ -3,6 +3,7 @@ import inquirer from 'inquirer';
 import ora from 'ora';
 import {
   scaffoldFile,
+  scaffoldAgentsMd,
   updateGitignore,
   scaffoldHooks,
   scaffoldPluginJson,
@@ -76,16 +77,24 @@ async function runAgents(selections) {
 async function runOptionalExtras(selections) {
   const { generatePluginJson, scaffoldGtdMemory } = await inquirer.prompt([
     {
-      type: 'confirm',
+      type: 'list',
       name: 'generatePluginJson',
       message: 'Generate .claude-plugin/plugin.json for marketplace compatibility?',
-      default: selections.generatePluginJson || false,
+      choices: [
+        { name: 'Yes', value: true },
+        { name: 'No', value: false },
+      ],
+      default: selections.generatePluginJson === true ? 0 : 1,
     },
     {
-      type: 'confirm',
+      type: 'list',
       name: 'scaffoldGtdMemory',
       message: 'Scaffold structured memory files (decisions.md, preferences.md)?',
-      default: selections.scaffoldGtdMemory || false,
+      choices: [
+        { name: 'Yes', value: true },
+        { name: 'No', value: false },
+      ],
+      default: selections.scaffoldGtdMemory === true ? 0 : 1,
     },
   ]);
   return { ...selections, generatePluginJson, scaffoldGtdMemory };
@@ -297,8 +306,13 @@ async function scaffoldFresh(projectRoot, selections, variables, settingsStr, ve
     await scaffoldFile('core/claude-md.md', 'CLAUDE.md', variables, projectRoot);
     spinner.text = 'Created CLAUDE.md';
 
-    await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
-    spinner.text = 'Created AGENTS.md';
+    // "Fresh" means no .claude/workflow-meta.json, but the user may still have
+    // an AGENTS.md from Cursor/Codex/another tool. The helper preserves it.
+    const agentsMdResult = await scaffoldAgentsMd(projectRoot, variables);
+    spinner.text =
+      agentsMdResult === 'preserved-with-ref'
+        ? 'Preserved existing AGENTS.md (template saved to workflow-ref)'
+        : 'Created AGENTS.md';
 
     await writeFile(path.join(projectRoot, '.claude', 'settings.json'), settingsStr);
     spinner.text = 'Created .claude/settings.json';

package/src/commands/setup-state.js

@@ -1,4 +1,5 @@
 import path from 'node:path';
+import { readFile } from 'node:fs/promises';
 import { text } from 'node:stream/consumers';
 import {
   loadSetupState,
@@ -42,27 +43,47 @@ async function showSubcommand(projectRoot) {
 }
 
 async function saveSubcommand(projectRoot, options) {
-  if (!options.stdin) {
-    console.error('Error: save requires --stdin');
+  const hasStdin = Boolean(options.stdin);
+  const hasFromFile = Boolean(options.fromFile);
+
+  if (hasStdin && hasFromFile) {
+    console.error('Error: --stdin and --from-file are mutually exclusive');
+    process.exitCode = 2;
+    return;
+  }
+  if (!hasStdin && !hasFromFile) {
+    console.error('Error: save requires --stdin or --from-file <path>');
     process.exitCode = 2;
     return;
   }
 
-  const inputStream = options.inputStream || process.stdin;
   let raw;
-  try {
-    raw = await text(inputStream);
-  } catch (err) {
-    console.error(`Error reading stdin: ${err.message}`);
-    process.exitCode = 1;
-    return;
+  if (hasFromFile) {
+    const filePath = path.resolve(options.fromFile);
+    try {
+      raw = await readFile(filePath, 'utf-8');
+    } catch (err) {
+      console.error(`Error reading ${filePath}: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
+  } else {
+    const inputStream = options.inputStream || process.stdin;
+    try {
+      raw = await text(inputStream);
+    } catch (err) {
+      console.error(`Error reading stdin: ${err.message}`);
+      process.exitCode = 1;
+      return;
+    }
   }
 
   let parsed;
   try {
     parsed = JSON.parse(raw);
   } catch (err) {
-    console.error(`Error: invalid JSON on stdin: ${err.message}`);
+    const source = hasFromFile ? options.fromFile : 'stdin';
+    console.error(`Error: invalid JSON on ${source}: ${err.message}`);
     process.exitCode = 1;
     return;
   }

package/src/commands/upgrade.js

@@ -21,6 +21,7 @@ import { getLatestNpmVersion } from '../utils/npm.js';
 import * as display from '../utils/display.js';
 import {
   semverLessThan,
+  semverGreaterThan,
   migrateSkillFormat,
   patchAgentDescriptions,
   migrateWorkflowRefLocation,
@@ -161,6 +162,13 @@ function renderTemplatePreview(categories, plan) {
     }
     display.newline();
   }
+  if (categories.missingUntracked.length > 0) {
+    display.barLine(`${display.red('−')} Deleted (removed in current version):`);
+    for (const { key } of categories.missingUntracked) {
+      display.barLine(`  ${display.red('−')} ${key}`);
+    }
+    display.newline();
+  }
   if (categories.unchanged.length > 0) {
     display.barLine(
       `${display.dimColor('=')} Unchanged: ${display.dimColor(`${categories.unchanged.length} files`)}`
@@ -235,11 +243,25 @@ async function promptProceed(message) {
   return proceed;
 }
 
-async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, yes }) {
+async function runRepairOnlyFlow({
+  projectRoot,
+  meta,
+  plan,
+  variables,
+  dryRun,
+  yes,
+  refRelocationReport = { moved: 0, names: [], skipped: [] },
+}) {
   display.sectionHeader(`WORCLAUDE REPAIR (v${meta.version})`);
   display.newline();
   display.barLine('Drift detected:');
   renderRepairPreview(plan);
+  if (refRelocationReport.moved > 0) {
+    display.barLine(
+      `${display.green('→')} Relocated ${refRelocationReport.moved} legacy ref file(s) ${display.dimColor('→ .claude/workflow-ref/')}`
+    );
+    display.newline();
+  }
 
   if (dryRun) {
     display.info('Dry run — no changes written.');
@@ -290,6 +312,11 @@ async function runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, y
     if (result.sidecars.length > 0) {
       display.barLine(`Sidecar:     ${result.sidecars.length} suggestion files`);
     }
+    if (refRelocationReport.moved > 0) {
+      display.barLine(
+        `Relocated:   ${refRelocationReport.moved} legacy ref file(s) ${display.dimColor('→ .claude/workflow-ref/')}`
+      );
+    }
     display.barLine(display.dimColor(`Backup: ${path.basename(backupDir)}/`));
 
     if (result.migrationConflicts.length > 0 || result.sidecars.length > 0) {
@@ -352,16 +379,29 @@ export async function upgradeCommand(options = {}) {
   const installedVersion = meta.version;
   const versionMatch = installedVersion === currentVersion;
 
+  if (semverGreaterThan(installedVersion, currentVersion)) {
+    display.error(
+      `Refusing to downgrade: installed v${installedVersion} is newer than CLI v${currentVersion}.`
+    );
+    display.info('Upgrade the CLI with `npm install -g worclaude@latest`.');
+    return;
+  }
+
+  // v2.5.1 migration: relocate legacy ref files. Runs before any early-exit
+  // so version-match projects with leftover legacy siblings still self-heal.
+  // Idempotent (skips already-migrated files).
+  const refRelocationReport = await migrateWorkflowRefLocation(projectRoot);
+
   const categories = await categorizeFiles(projectRoot, meta);
   const claudeMdContent = await readClaudeMd(projectRoot);
   const plan = await buildRepairPlan(projectRoot, categories, claudeMdContent);
 
   const repairWork = hasRepairWork(plan);
   const templateWork = hasTemplateWork(categories, plan);
+  const refWork = refRelocationReport.moved > 0;
 
-  // Version match + no repair + no template work → up to date.
-  // Early return keeps the clean-install fast path free of package.json I/O.
-  if (versionMatch && !repairWork && !templateWork) {
+  // Version match + no repair + no template work + no ref relocation → up to date.
+  if (versionMatch && !repairWork && !templateWork && !refWork) {
     display.success(`Already up to date (v${currentVersion}).`);
     return;
   }
@@ -370,7 +410,15 @@ export async function upgradeCommand(options = {}) {
 
   // Version match + repair only OR explicit --repair-only → repair-only flow
   if ((versionMatch && !templateWork) || repairOnly) {
-    await runRepairOnlyFlow({ projectRoot, meta, plan, variables, dryRun, yes });
+    await runRepairOnlyFlow({
+      projectRoot,
+      meta,
+      plan,
+      variables,
+      dryRun,
+      yes,
+      refRelocationReport,
+    });
     return;
   }
 
@@ -439,10 +487,7 @@ export async function upgradeCommand(options = {}) {
       spinner.start('Applying updates...');
     }
 
-    // v2.5.1 migration: relocate legacy ref files out of Claude-Code-scanned
-    // dirs. Runs unconditionally since it's idempotent and the fix applies
-    // to any project with legacy refs, regardless of source version.
-    const refRelocationReport = await migrateWorkflowRefLocation(projectRoot);
+    // v2.5.1 migration already ran before the early-exit check (above).
     if (refRelocationReport.moved > 0) {
       spinner.text = `Relocated ${refRelocationReport.moved} legacy ref file(s)...`;
     }
@@ -474,7 +519,9 @@ export async function upgradeCommand(options = {}) {
       const useDocker = meta.useDocker || false;
       const { settingsObject: workflowSettings } = await buildSettingsJson(techStack, useDocker);
       const settingsReport = { added: { permissions: 0, hooks: 0 }, hookConflicts: [] };
-      await mergeSettingsPermissionsAndHooks(projectRoot, workflowSettings, settingsReport);
+      await mergeSettingsPermissionsAndHooks(projectRoot, workflowSettings, settingsReport, {
+        yes,
+      });
       spinner.text = 'Settings merged...';
     }
 

package/src/core/merger.js

@@ -5,6 +5,7 @@ import {
   readTemplate,
   substituteVariables,
   scaffoldFile,
+  scaffoldAgentsMd,
   mergeSettings,
   scaffoldHooks,
   scaffoldPluginJson,
@@ -230,7 +231,12 @@ async function mergeCommands(projectRoot, existingScan, report) {
   }
 }
 
-export async function mergeSettingsPermissionsAndHooks(projectRoot, workflowSettings, report) {
+export async function mergeSettingsPermissionsAndHooks(
+  projectRoot,
+  workflowSettings,
+  report,
+  options = {}
+) {
   const existingRaw = await readFile(path.join(projectRoot, '.claude', 'settings.json'));
   const existing = parseUserJson(existingRaw, '.claude/settings.json');
 
@@ -277,8 +283,10 @@ export async function mergeSettingsPermissionsAndHooks(projectRoot, workflowSett
       if (conflictCandidate) {
         matched.add(conflictCandidate);
 
-        // Tier 3: conflict — ask user
-        const resolution = await promptHookConflict(category, conflictCandidate, workflowEntry);
+        // Tier 3: conflict — ask user (or auto-keep if --yes)
+        const resolution = await promptHookConflict(category, conflictCandidate, workflowEntry, {
+          yes: options.yes,
+        });
 
         if (resolution === 'replace') {
           const idx = existingEntries.indexOf(conflictCandidate);
@@ -428,19 +436,10 @@ async function handleClaudeMd(projectRoot, existingScan, variables, selections,
   }
 }
 
-async function mergeAgentsMd(projectRoot, existingScan, variables, report) {
-  if (!existingScan.hasAgentsMd) {
-    await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
-    report.agentsMdHandling = 'created';
-  } else {
-    await scaffoldFile(
-      'core/agents-md.md',
-      workflowRefRelPath('root/AGENTS.md'),
-      variables,
-      projectRoot
-    );
-    report.agentsMdHandling = 'saved-alongside';
-  }
+async function mergeAgentsMd(projectRoot, variables, report) {
+  const result = await scaffoldAgentsMd(projectRoot, variables);
+  // Preserve the existing report-field vocabulary for downstream observability.
+  report.agentsMdHandling = result === 'created' ? 'created' : 'saved-alongside';
 }
 
 // --- Main merge function ---
@@ -498,7 +497,7 @@ export async function performMerge(
   // Stop spinner before CLAUDE.md merge — interactive prompts for section selection
   if (spinner) spinner.stop();
   await handleClaudeMd(projectRoot, existingScan, variables, selections, report);
-  await mergeAgentsMd(projectRoot, existingScan, variables, report);
+  await mergeAgentsMd(projectRoot, variables, report);
   if (spinner) spinner.start();
 
   return report;

package/src/core/migration.js

@@ -24,6 +24,10 @@ export function semverLessThan(a, b) {
   return false;
 }
 
+export function semverGreaterThan(a, b) {
+  return semverLessThan(b, a);
+}
+
 // --- Agent description lookup ---
 
 const UNIVERSAL_AGENT_DESCRIPTIONS = {

package/src/core/scaffolder.js

@@ -2,6 +2,7 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import fs from 'fs-extra';
 import { fileExists, readFile, writeFile } from '../utils/file.js';
+import { workflowRefRelPath } from './file-categorizer.js';
 import { UNIVERSAL_AGENTS } from '../data/agents.js';
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
@@ -29,6 +30,25 @@ export async function scaffoldFile(templateRelativePath, destRelativePath, varia
   await writeFile(destPath, content);
 }
 
+// Scaffold AGENTS.md at the project root, preserving any pre-existing file.
+// When AGENTS.md exists (user-authored, Cursor/Codex/etc.), the template lands
+// under .claude/workflow-ref/AGENTS.md so the user can diff + merge.
+// Returns 'created' on fresh write or 'preserved-with-ref' when skipping.
+export async function scaffoldAgentsMd(projectRoot, variables) {
+  const agentsMdPath = path.join(projectRoot, 'AGENTS.md');
+  if (await fileExists(agentsMdPath)) {
+    await scaffoldFile(
+      'core/agents-md.md',
+      workflowRefRelPath('root/AGENTS.md'),
+      variables,
+      projectRoot
+    );
+    return 'preserved-with-ref';
+  }
+  await scaffoldFile('core/agents-md.md', 'AGENTS.md', variables, projectRoot);
+  return 'created';
+}
+
 export async function scaffoldDirectory(templateDir, destDir, variables, projectRoot) {
   const root = projectRoot || process.cwd();
   const fs = await import('fs-extra');
@@ -98,10 +118,21 @@ export async function scaffoldHooks(projectRoot) {
   const entries = await fs.readdir(hooksTemplateDir);
   for (const entry of entries) {
     if (!entry.endsWith('.cjs') && !entry.endsWith('.js')) continue;
-    await fs.copy(path.join(hooksTemplateDir, entry), path.join(destDir, entry), {
+    const destPath = path.join(destDir, entry);
+    await fs.copy(path.join(hooksTemplateDir, entry), destPath, {
       overwrite: false,
       errorOnExist: false,
     });
+    // Ensure consistent exec bits on POSIX. Windows has no chmod semantics
+    // worth enforcing; node+fs-extra no-ops there anyway, but guard to keep
+    // the intent obvious.
+    if (process.platform !== 'win32') {
+      try {
+        await fs.chmod(destPath, 0o755);
+      } catch (err) {
+        if (err.code !== 'ENOENT') throw err;
+      }
+    }
   }
 }
 

package/src/core/setup-state.js

@@ -114,7 +114,10 @@ function validateState(state) {
   }
   for (const [k, v] of Object.entries(state.mediumResolved)) {
     if (typeof v !== 'string') {
-      throw new Error(`state.mediumResolved.${k} must be a string`);
+      throw new Error(
+        `state.mediumResolved.${k} must be a string (got ${typeof v}; ` +
+          `stringify the rendered value per the CONFIRM_MEDIUM Storage rule)`
+      );
     }
   }
   if (!state.interviewAnswers || typeof state.interviewAnswers !== 'object') {

package/src/index.js

@@ -84,8 +84,9 @@ setupState
 
 setupState
   .command('save')
-  .description('Read a JSON state from stdin, validate, and persist')
-  .option('--stdin', 'Read JSON from stdin (required)')
+  .description('Read a JSON state from stdin or a file, validate, and persist')
+  .option('--stdin', 'Read JSON from stdin')
+  .option('--from-file <path>', 'Read JSON from a file path')
   .option('--path <dir>', 'Project root', process.cwd())
   .action((options) => setupStateCommand('save', options));
 
@@ -101,4 +102,14 @@ setupState
   .option('--path <dir>', 'Project root', process.cwd())
   .action((options) => setupStateCommand('resume-info', options));
 
+// Catch unknown setup-state subcommands with the spec-matching exit code 2.
+// Commander's default would exit 1, but setup-state's own arg-error contract
+// (see src/commands/setup-state.js) is exit 2 for bad inputs.
+setupState.on('command:*', (operands) => {
+  console.error(
+    `Error: unknown setup-state subcommand: ${operands[0]} (expected one of show, save, reset, resume-info)`
+  );
+  process.exitCode = 2;
+});
+
 program.parse();

package/src/prompts/conflict-resolution.js

@@ -1,12 +1,19 @@
 import inquirer from 'inquirer';
 import * as display from '../utils/display.js';
 
-export async function promptHookConflict(hookCategory, existingHook, workflowHook) {
+export async function promptHookConflict(hookCategory, existingHook, workflowHook, options = {}) {
   display.newline();
   display.warn(`Hook conflict: ${hookCategory} matcher "${existingHook.matcher}"`);
   display.dim(`  Existing: ${existingHook.hooks[0].command}`);
   display.dim(`  Workflow: ${workflowHook.hooks[0].command}`);
 
+  // Non-interactive: preserve the user's existing hook. Safer than "replace"
+  // during scripted upgrades — never silently clobbers customizations.
+  if (options.yes) {
+    display.dim('  --yes: kept existing hook (non-interactive default).');
+    return 'keep';
+  }
+
   const { resolution } = await inquirer.prompt([
     {
       type: 'list',

package/templates/commands/setup.md

@@ -54,12 +54,27 @@ normally apply.
 
    - Shell: `worclaude scan --path .` (SCAN only)
    - Shell: `worclaude setup-state show --path .`
-   - Shell: `worclaude setup-state save --stdin --path .` (pipe the
-     updated state JSON via stdin — the ONLY way state is persisted)
+   - Shell: `worclaude setup-state save --from-file .claude/cache/setup-state.draft.json --path .`
+     — the ONLY way state is persisted. Use `Write` to produce the
+     draft JSON first, then invoke the CLI against that path. This
+     avoids Claude Code's shell-interpolation safety layer that
+     triggers on heredoc-with-variable-expansion patterns.
    - Shell: `worclaude setup-state reset --path .`
    - Shell: `worclaude setup-state resume-info --path .`
    - Read: `.claude/cache/detection-report.json`
    - Read: `.claude/cache/setup-state.json`
+   - Write: `.claude/cache/setup-state.draft.json` (state-save staging
+     only — overwritten each save).
+   - Tool: `AskUserQuestion` permitted at:
+     - INTERVIEW states, per the Interaction mode contract
+       (`selectable` / `multi-selectable` / `hybrid` questions).
+     - CONFIRM_MEDIUM when the per-item option count (candidates + 1
+       for "Other") is ≤ 4 — AskUserQuestion's own `maxItems: 4`
+       schema cap. When the count exceeds 4, fall back to the verbatim
+       text-parse rendering defined in State 3 below.
+     Not permitted at CONFIRM_HIGH: the detection list routinely has
+     12+ items in real projects, which exceeds the 4-option schema cap.
+     CONFIRM_HIGH renders VERBATIM per rule #7.
 
    At WRITE state the whitelist RELAXES to additionally permit:
 
@@ -82,15 +97,23 @@ normally apply.
    project only. Only use information the user provides during THIS
    interview and the detection report for THIS project.
 
-7. **RENDER PROMPTS VERBATIM.** Where a state specifies a prompt format
-   with `[x] 1. ...` syntax or other structured output, render it
-   EXACTLY as specified AND wrap it in a triple-backtick fenced code
-   block so Markdown rendering does not reformat checkboxes or
-   renumber lines. The format is part of the contract with the
+7. **RENDER PROMPTS VERBATIM.** Where a state specifies a text-parse
+   prompt format with `[x] 1. ...` syntax or other structured output,
+   render it EXACTLY as specified AND wrap it in a triple-backtick
+   fenced code block so Markdown rendering does not reformat checkboxes
+   or renumber lines. The format is part of the contract with the
    user-response parser — paraphrasing or reformatting breaks parsing.
    You MAY add a brief conversational sentence before or after a
    verbatim prompt, but NOT within it.
 
+   EXCEPTION — CONFIRM_MEDIUM via AskUserQuestion: when the per-item
+   option count is ≤ 4 (candidates + "Other"), State 3 uses the
+   `AskUserQuestion` tool path instead of the verbatim text prompt
+   (see rule #5 and State 3). The verbatim-rendering requirement does
+   not apply to tool invocations. When the count exceeds 4, the text
+   fallback kicks in and this rule applies as written. CONFIRM_HIGH
+   never uses AskUserQuestion (detection lists routinely exceed 4).
+
    KNOWN FAILURE MODES: reformatting `[x] 1. X: Y` as `- [x] X: Y`
    (loses numbering); paraphrasing labels; collapsing items onto one
    line; rendering outside a fenced block (Markdown may convert `[x]`
@@ -183,10 +206,27 @@ ENTRY:
     - ...
   ```
 
-- State file mutation: write a fresh state with `currentState: "SCAN"`,
-  `startedAt` and `updatedAt` set to now, `detectionReportPath:
-".claude/cache/detection-report.json"`, empty arrays/objects for the
-  remaining fields. Persist via `worclaude setup-state save --stdin`.
+- State file mutation: write a fresh state with EXACTLY these fields.
+  `schemaVersion: 1` is REQUIRED — the validator rejects anything else
+  with `Unsupported schemaVersion: undefined`.
+
+  ```json
+  {
+    "schemaVersion": 1,
+    "currentState": "SCAN",
+    "startedAt": "<ISO timestamp, now>",
+    "updatedAt": "<ISO timestamp, now>",
+    "detectionReportPath": ".claude/cache/detection-report.json",
+    "highConfirmedAccepted": [],
+    "highConfirmedRejected": [],
+    "mediumResolved": {},
+    "interviewAnswers": {}
+  }
+  ```
+
+  Persist via `Write` → `.claude/cache/setup-state.draft.json` →
+  `worclaude setup-state save --from-file .claude/cache/setup-state.draft.json --path .`
+  (see rule #5).
 
 EXIT: advance to CONFIRM_HIGH.
 
@@ -201,21 +241,26 @@ ENTRY:
   `highConfirmedRejected: []`, and transition to CONFIRM_MEDIUM
   (trivial exit per rule #1).
 - Otherwise render VERBATIM (wrapped in a triple-backtick fenced code
-  block):
+  block). Below every item add a dim "→ Will be saved as: `<target>`"
+  line pulled from the **Field-help table** so the user knows what
+  accepting means:
 
   ```
   I scanned your project. Please confirm the high-confidence
   detections below. Reply with the numbers of any items that are
-  WRONG (e.g., "2, 5"), or reply "ok" to accept all.
+  WRONG (e.g., "2, 5"), or reply "ok" to accept all, or type "help".
 
     [x] 1. <formatField(item1.field)>: <renderValue(item1)> (from <item1.source>)
+           → Will be saved as: <target1>
     [x] 2. ...
+           → Will be saved as: <target2>
 
   Your response:
   ```
 
   `<formatField>` and `<renderValue>` are defined in the **Field
-  rendering table** below.
+  rendering table** below. `<target>` is pulled from the **Field-help
+  table** (also below) and must be included verbatim per the table.
 
 Response parsing (case-insensitive, whitespace trimmed):
 
@@ -225,12 +270,20 @@ Response parsing (case-insensitive, whitespace trimmed):
 - One or more integers (comma or space separated) in range 1..N →
   those items are rejected; split fields into accepted/rejected
   accordingly (in rendered order).
+- `help` → render the **Field-help** block for EACH displayed field
+  (description + target + example) without advancing state. Then
+  restate the prompt above (same text, same items). Do NOT persist a
+  mutation for the help render. (`?` is intentionally NOT a trigger —
+  Claude Code binds it to a keyboard-shortcut overlay that intercepts
+  the keystroke before /setup sees it.)
 - Anything else (including integers out of range) → rule #3 fires:
-  restate with "I need either 'ok' or numbers from 1 to `<N>` matching
-  the items above (e.g., '2, 5'). To cancel, type `cancel setup`."
+  restate with "I need either 'ok', numbers from 1 to `<N>` matching
+  the items above (e.g., '2, 5'), or type `help`. To cancel, type
+  `cancel setup`."
 
 State file mutation: persist the updated arrays via
-`worclaude setup-state save --stdin`.
+`worclaude setup-state save --from-file .claude/cache/setup-state.draft.json --path .`
+(see rule #5).
 
 EXIT: advance to CONFIRM_MEDIUM.
 
@@ -242,48 +295,116 @@ ENTRY:
   report.
 - If there are zero medium-confidence items: persist
   `mediumResolved: {}`, transition to INTERVIEW_STORY.
-- Otherwise iterate in report order. For each medium item, render ONE
-  prompt VERBATIM in a fenced code block. The prompt shape depends on
-  `item.candidates`:
-
-  **Shape A — `candidates === null`** (emitted by `readme`):
-
-  ```
-  <formatField(field)> (detected from <source>):
-
-    1. <renderValue(item)>
-    2. Other (I'll type my own)
-
-  Reply with the number of your choice (default: 1):
-  ```
-
-  **Shape B — `candidates` is a non-empty array** (emitted by
-  `package-manager` when multiple lockfile groups disagree):
-
-  ```
-  <formatField(field)> (detected from <source>):
-
-    1. <candidates[0]>
-    2. <candidates[1]>
-    ...
-    N. <candidates[N-1]>
-    N+1. Other (I'll type my own)
-
-  Reply with the number of your choice (default: 1):
-  ```
-
-  `candidates[0]` equals `item.value` — default-1 accepts the detected
-  value.
-
-Response parsing (per item):
-
-- `""` | `1` | `default` → accept item 1 (the detected value).
+- Otherwise iterate in report order. For each medium item, compute the
+  total option count:
+  - Shape A (`candidates === null`, emitted by `readme`):
+    `1 + 1` = 2 (detected value + "Other").
+  - Shape B (`candidates` is a non-empty array): `candidates.length + 1`.
+  If the total is ≤ 4, use the **AskUserQuestion path** (Path 1).
+  Otherwise fall back to the **verbatim text-parse path** (Path 2).
+  The threshold is the `maxItems: 4` schema cap of AskUserQuestion.
+
+#### Path 1 — AskUserQuestion (option count ≤ 4)
+
+Invoke the `AskUserQuestion` tool once per medium item with exactly
+this shape:
+
+- `question`: `<formatField(field)> — detected from <source>. Which
+  should I use?`
+- `header`: short label for the sidebar (≤ 12 chars) — typically
+  `formatField(field)` truncated.
+- `multiSelect`: `false`
+- `options`: built from the Shape above:
+  - Shape A: `[{ label: <renderValue(item)>, description: "Will be
+    saved as <target>. Accept the detected value." },
+    { label: "Other (I'll type my own)", description: "Supply a
+    custom value via free-text follow-up." }]`
+  - Shape B: one option per `candidates[k]` with
+    `description: "Will be saved as <target>."`; append
+    `{ label: "Other (I'll type my own)", description: "Supply a
+    custom value via free-text follow-up." }` as the final option.
+
+`<target>` comes from the **Field-help table** below. Render it
+verbatim per the table.
+
+On response:
+- User selects a candidate label → store that label string in
+  `mediumResolved[field]` (Storage rule applies).
+- User selects "Other (I'll type my own)" → follow up with a free-text
+  prompt: "Go ahead — what's the value you'd like to use?". Store the
+  trimmed reply.
+
+`AskUserQuestion` does not expose a `help` trigger; the per-option
+`description` text carries the equivalent content inline. The text
+fallback's `help` keyword is scoped to Path 2 only.
+
+#### Path 2 — Verbatim text prompt (option count > 4)
+
+Render ONE prompt VERBATIM in a fenced code block. The prompt shape
+depends on `item.candidates`:
+
+**Shape A — `candidates === null`** (rare in this path — only 2
+options, typically handled by Path 1 above; included here for
+completeness in case AskUserQuestion is unavailable):
+
+```
+<formatField(field)> (detected from <source>):
+
+  1. <renderValue(item)>
+     → Will be saved as: <target>
+  2. Other (I'll type my own)
+
+Reply with the number of your choice (default: 1), or type `help`:
+```
+
+**Shape B — `candidates` is a non-empty array** (e.g.,
+`package-manager` when multiple lockfile groups disagree and produce
+4+ candidates):
+
+```
+<formatField(field)> (detected from <source>):
+→ Will be saved as: <target>
+
+  1. <candidates[0]>
+  2. <candidates[1]>
+  ...
+  N. <candidates[N-1]>
+  N+1. Other (I'll type my own)
+
+Reply with the number of your choice (default: 1), or type `help`:
+```
+
+`<target>` comes from the **Field-help table** below. Render it
+verbatim per the table. `candidates[0]` equals `item.value` —
+default-1 accepts the detected value.
+
+Response parsing (Path 2 only):
+
+- `""` | `1` | `default` → accept item 1; store `renderValue(item)`
+  as a string per the Storage rule.
 - The final "Other" number (`2` in shape A, `N+1` in shape B) →
   follow-up free-text prompt: "Go ahead — what's the value you'd like
-  to use?". Record the trimmed reply as the answer.
-- Integer in range `2..N` (shape B only) → accept `candidates[k-1]`.
-- Anything else → restate with "I need a number from 1 to `<max>`, or
-  empty for the default. To cancel, type `cancel setup`."
+  to use?". Store the trimmed reply.
+- Integer in range `2..N` (shape B only) → store `candidates[k-1]`.
+- `help` → render the **Field-help** block for this field
+  (description + target + example) without advancing state. Then
+  restate the prompt above. Do NOT persist a mutation for the help
+  render. (`?` is intentionally NOT a trigger — Claude Code binds it
+  to a keyboard-shortcut overlay that intercepts the keystroke.)
+- Anything else → restate with "I need a number from 1 to `<max>`,
+  empty for the default, or type `help`. To cancel, type
+  `cancel setup`."
+
+#### Storage rule (both paths)
+
+`mediumResolved[field]` MUST be a string. Store the exact label that
+was shown to the user (Path 1: `AskUserQuestion` `label`; Path 2:
+`renderValue(item)` or `candidates[k-1]`), or the user's trimmed
+free-text on "Other". **NEVER store the raw `item.value` object** —
+for fields like `readme` whose detected value is an object
+(`{projectDescription, setupInstructions, fullPath}`) the validator
+will reject the mutation with `state.mediumResolved.<field> must be a
+string`.
 
 State file mutation: after EACH item is resolved (not batched),
 append to `mediumResolved` and persist.
@@ -298,14 +419,49 @@ Shared ENTRY protocol for each INTERVIEW state:
   **QuestionId enumeration** below plus any rejected fields routed to
   this state from CONFIRM_HIGH (per the **Rejected-field re-ask
   routing** table).
-- Skip any `questionId` already present in `interviewAnswers`.
+- Apply the **Detection-skip matrix** (below the enumeration): for
+  each `questionId` whose skip-field is present in
+  `highConfirmedAccepted`, record
+  `interviewAnswers[<questionId>] = "[auto-filled from <field>]"` and
+  persist (same Storage rule applies — the value is always a string)
+  BEFORE evaluating the already-answered skip-list.
+- Skip any `questionId` already present in `interviewAnswers`
+  (including auto-filled ones).
 - Resume preamble (only if ANY questionId is already answered AND at
   least one remains): "Resuming `<STATE_NAME>`. Already have:
   `<comma-list>`. Next: `<next questionId>`."
 - If ALL `questionId`s for this state are present, trivially-exit:
   persist a state update (only `currentState` and `updatedAt` change)
   and advance.
-- Ask remaining questions conversationally, in enumeration order.
+- Ask remaining questions in enumeration order. For each question,
+  look up its `interactionMode` in the **Per-question interaction
+  table** below and use the matching tool:
+  - `selectable` / `multi-selectable` → `AskUserQuestion`
+  - `hybrid` → pre-fill from the listed detection source, then offer
+    accept / edit / replace
+  - `free-text` → ordinary text prompt
+  The Storage rule (`interviewAnswers[<questionId>]` must be a string)
+  applies uniformly — no object shapes regardless of mode.
+- **Reply classification** — before recording a reply as
+  `interviewAnswers[<questionId>]`, classify it:
+  - **Answer**: a response that plausibly fits the semantic scope of
+    `<questionId>` (e.g., `arch.classification` expects one of the
+    enum values or a short phrase about system shape; `story.audience`
+    expects a description of people/roles). Record and advance.
+  - **Skip trigger**: `skip` or `skip all` — rules below apply.
+  - **Cancel trigger**: matches rule #4's regex — rule #4 applies.
+  - **Back trigger**: starts with `back` — rule below applies.
+  - **Everything else → OFF-TOPIC.** Apply rule #3: restate the
+    pending question with the off-topic prefix. You MUST NOT record
+    the reply in `interviewAnswers`. You MUST NOT advance
+    `currentState` or the question pointer. Do NOT persist a mutation
+    for this exchange. A topic-mismatched reply is not an answer just
+    because it is a sentence — if the reply would land in a different
+    section of SPEC.md than the one tied to this `<questionId>`, it is
+    off-topic.
+
+  Prefer off-topic when uncertain. An unnecessary restate costs one
+  turn; a mis-filed answer corrupts the state file.
 - `skip` on a question → record `interviewAnswers[<questionId>] =
 "[skipped]"`, advance to the next question in this state.
 - `skip all` → record every remaining `questionId` as `[skipped]`,
@@ -313,13 +469,11 @@ Shared ENTRY protocol for each INTERVIEW state:
 - `back` → restate the current question with the prefix "I can't go
   back within a single setup run. Finish this run and edit the output
   files afterward." (rule #2).
-- Rule #3 applies within interview states: off-topic replies trigger
-  a restatement of the pending question, not an answer to the
-  off-topic question.
 
 State file mutation: after EACH question is answered or skipped,
-persist via `worclaude setup-state save --stdin` BEFORE rendering the
-next prompt. Resume granularity is per-question.
+persist via `worclaude setup-state save --from-file .claude/cache/setup-state.draft.json --path .`
+(see rule #5) BEFORE rendering the next prompt. Resume granularity is
+per-question.
 
 EXIT: advance to the next state; INTERVIEW_VERIFICATION exits to
 WRITE.
@@ -430,6 +584,78 @@ detection):
 - `verification.staging` — staging/preview environment.
 - `verification.required_checks` — CI required checks.
 
+### Interaction mode
+
+Each interview question is asked in ONE of four modes. The mode lives
+next to the question in the table below. This controls which tool you
+use to collect the answer — text input, menu, checklist, or hybrid.
+
+- `selectable` — invoke the `AskUserQuestion` tool with the listed
+  choices, `multiSelect: false`. The user gets arrow-key navigation.
+  If the user picks "Other (I'll type my own)", follow up with a
+  free-text prompt: "Go ahead — what's the value you'd like to use?".
+- `multi-selectable` — invoke `AskUserQuestion` with `multiSelect:
+  true` and the listed choices. Always prepend `None` as the first
+  choice and append "Other (I'll type my own)" as the last. On
+  "Other", follow up with free-text. The stored value joins selections
+  with `, ` (e.g. `"REST, GraphQL"`). Selecting `None` alone stores
+  `"none"`.
+- `hybrid` — pre-fill a bullet list from detection (see the question
+  row for which detection field feeds it) and ask: "I pre-filled this
+  from your README/scan. Accept, edit, or replace?". `accept` stores
+  the pre-filled text verbatim; `edit` offers free-text with the
+  pre-fill visible; `replace` starts from empty.
+- `free-text` — ordinary text prompt (default). No `AskUserQuestion`.
+
+Regardless of mode, `interviewAnswers[<questionId>]` MUST be a string
+per the Storage rule. For `multi-selectable`, join with `, `. For
+`hybrid`, store the final accepted or edited text.
+
+**Fallback.** If `AskUserQuestion` is unavailable in the current
+Claude Code version (or the tool call fails), degrade to a
+numbered-list free-text prompt using CONFIRM_HIGH-style parsing:
+
+```
+<question-label>:
+
+  1. <choice 1>
+  2. <choice 2>
+  ...
+  N+1. Other (I'll type my own)
+
+Reply with the number of your choice, or type your own answer:
+```
+
+### Per-question interaction table
+
+| questionId                     | Mode             | Choices (or pre-fill source)                                              |
+| ------------------------------ | ---------------- | ------------------------------------------------------------------------- |
+| `story.audience`               | free-text        | —                                                                         |
+| `story.problem`                | free-text        | —                                                                         |
+| `story.analogs`                | free-text        | —                                                                         |
+| `arch.classification`          | selectable       | monolith, modular monolith, microservices, serverless, library, CLI, other |
+| `arch.modules`                 | free-text        | —                                                                         |
+| `arch.entities`                | free-text        | —                                                                         |
+| `arch.external_apis`           | multi-selectable | `<detected externalApis>` + None + Other                                  |
+| `arch.stack_rationale`         | free-text        | —                                                                         |
+| `features.core`                | hybrid           | pre-fill from readme bullets (projectDescription / headings)              |
+| `features.nice_to_have`        | hybrid           | pre-fill from readme bullets                                              |
+| `features.non_goals`           | hybrid           | empty pre-fill (always edit from scratch unless user picks `accept`)      |
+| `workflow.new_dev_steps`       | free-text        | —                                                                         |
+| `workflow.env_values`          | free-text        | —                                                                         |
+| `conventions.patterns`         | free-text        | —                                                                         |
+| `conventions.errors`           | selectable       | throw, Result<T,E>, null, silent catch, mixed, other                      |
+| `conventions.logging`          | selectable       | console, structured JSON, dedicated logger, none, other                   |
+| `conventions.api_format`       | selectable       | REST, GraphQL, gRPC, none, other                                          |
+| `conventions.naming`           | free-text        | —                                                                         |
+| `conventions.rules`            | free-text        | —                                                                         |
+| `verification.manual`          | free-text        | —                                                                         |
+| `verification.staging`         | selectable       | yes, no                                                                   |
+| `verification.required_checks` | multi-selectable | `<detected ci.workflows>` + None + Other                                  |
+
+10 non-default entries: 5 `selectable`, 2 `multi-selectable`, 3
+`hybrid`. The other 12 questions stay `free-text`.
+
 ### Rejected-field re-ask routing
 
 Fields in `highConfirmedRejected` are re-asked as one sub-question
@@ -450,6 +676,94 @@ enumeration that `saveSetupState` accepts, matched by prefix. The
 `<field>` segment must exactly match a known detector field name AND
 the routing table must map that field to that state prefix.
 
+### Detection-skip matrix
+
+A question in this table is **auto-skipped** when the listed detection
+field is in `highConfirmedAccepted` (i.e., accepted at CONFIRM_HIGH
+and not rejected). Record the skipped answer in `interviewAnswers` as
+`"[auto-filled from <field>]"` BEFORE evaluating the already-answered
+skip-list. This prevents the interview from re-asking questions the
+scanner already answered.
+
+| questionId              | Skip when in `highConfirmedAccepted`           | Notes                                    |
+| ----------------------- | ---------------------------------------------- | ---------------------------------------- |
+| `story.problem`         | `readme` (medium) with non-empty description  | README already describes the problem.    |
+| `arch.classification`   | `monorepo` (high)                              | Pre-fill `"monorepo"`.                   |
+| `arch.external_apis`    | `externalApis` (high)                          | Direct mapping.                          |
+| `workflow.new_dev_steps`| `scripts` (high) AND `readme` (medium)         | Both must be present.                    |
+
+All OTHER `questionId`s are always asked — the scanner cannot infer
+them (audience, rationale, conventions, features, etc. are user
+knowledge the detector has no access to).
+
+### Field-help table
+
+Drives the `help` command (CONFIRM_HIGH, CONFIRM_MEDIUM, and
+INTERVIEW states) AND the "→ Will be saved as: `<target>`" line on
+every CONFIRM prompt. Keep the `<target>` column stable — parsers
+downstream don't match on it, but users read it for orientation.
+
+Detection fields (used at CONFIRM_HIGH and CONFIRM_MEDIUM):
+
+| Field            | Plain-English description                                     | `<target>` (where accepting lands)                          | Example answer                            |
+| ---------------- | ------------------------------------------------------------- | ----------------------------------------------------------- | ----------------------------------------- |
+| `ci`             | Which CI provider + workflow files run on push/PR             | `## Verification` section of `docs/spec/SPEC.md`            | `GitHub Actions, 2 workflows`             |
+| `deployment`     | Where the app gets deployed                                   | `## Architecture` section of `docs/spec/SPEC.md`            | `Vercel`                                  |
+| `envVariables`   | Names of env variables the project reads                      | `## Workflow` section of `docs/spec/SPEC.md`                | `DATABASE_URL, STRIPE_SECRET_KEY`         |
+| `externalApis`   | Third-party APIs / SDKs the project integrates with           | `backend-conventions/SKILL.md` External APIs section        | `Stripe, Sentry`                          |
+| `frameworks`     | Application frameworks the project uses                       | `## Tech Stack` section of `CLAUDE.md`                      | `Next.js 14.2.3, React 18.2.0`            |
+| `language`       | Primary source language                                       | `## Tech Stack` section of `CLAUDE.md`                      | `TypeScript`                              |
+| `linting`        | Linters + formatters the project runs                         | `## Tech Stack` section of `CLAUDE.md`                      | `ESLint, Prettier`                        |
+| `monorepo`       | Whether the repo is a monorepo + which tool                   | `## Architecture` section of `docs/spec/SPEC.md`            | `pnpm (3 packages)`                       |
+| `orm`            | Database ORM / schema driver                                  | `## Tech Stack` of `CLAUDE.md` + backend-conventions/SKILL  | `Prisma`                                  |
+| `packageManager` | How you install dependencies                                  | `## Tech Stack` of `CLAUDE.md` + `## Commands`              | `pnpm`                                    |
+| `readme`         | Project description pulled from `README.md`                   | `## Overview` section of `docs/spec/SPEC.md`                | a paragraph of text                       |
+| `scripts`        | dev / test / build / lint script names                        | `## Commands` section of `CLAUDE.md`                        | `dev=dev test=test build=build lint=lint` |
+| `specDocs`       | Spec / design docs already present in the repo                | `## Overview` of `docs/spec/SPEC.md` (referenced, not copied) | `2 docs`                                  |
+| `testing`        | Test framework + config file                                  | `## Verification` of `docs/spec/SPEC.md`                    | `vitest (vitest.config.ts)`               |
+
+Interview questions (used at INTERVIEW states):
+
+| `questionId`                   | Plain-English description                                 | `<target>`                                                     | Example answer                                |
+| ------------------------------ | --------------------------------------------------------- | -------------------------------------------------------------- | --------------------------------------------- |
+| `story.audience`               | Who is this project for?                                  | `## Overview` of `docs/spec/SPEC.md`                           | `internal developers maintaining our CLI`     |
+| `story.problem`                | What problem does it solve?                               | `## Overview` of `docs/spec/SPEC.md`                           | `scaffolds a worclaude workflow into any repo` |
+| `story.analogs`                | Similar products / projects you're modeling after         | `## Overview` of `docs/spec/SPEC.md`                           | `create-react-app, but for Claude workflows`  |
+| `arch.classification`          | System shape: monolith / services / library / CLI / etc.  | `## Architecture` of `docs/spec/SPEC.md`                       | `modular monolith`                            |
+| `arch.modules`                 | Directory purposes and in-house packages                  | `## Architecture` of `docs/spec/SPEC.md`                       | `src/commands — CLI entry points`             |
+| `arch.entities`                | Core database entities (if applicable)                    | `## Architecture` of `docs/spec/SPEC.md`                       | `User, Project, Session`                      |
+| `arch.external_apis`           | External APIs beyond SDK detection                        | `## Architecture` of `docs/spec/SPEC.md`                       | `Stripe, Sentry`                              |
+| `arch.stack_rationale`         | Why these framework/stack choices                         | `## Architecture` of `docs/spec/SPEC.md`                       | `pnpm for workspace perf`                     |
+| `features.core`                | Must-have features                                        | `## Features` of `docs/spec/SPEC.md`                           | `init / upgrade / doctor / scan`              |
+| `features.nice_to_have`        | Nice-to-have features                                     | `## Features` of `docs/spec/SPEC.md`                           | `plugin.json generation`                      |
+| `features.non_goals`           | Explicit non-goals                                        | `## Features` of `docs/spec/SPEC.md`                           | `no Windows-specific path handling`           |
+| `workflow.new_dev_steps`       | Dev setup steps beyond README                             | `## Workflow` of `docs/spec/SPEC.md`                           | `copy .env.example → .env then fill secrets`  |
+| `workflow.env_values`          | Guidance for env var values                               | `## Workflow` of `docs/spec/SPEC.md`                           | `DATABASE_URL: local Postgres on :5432`       |
+| `conventions.patterns`         | Code patterns the project uses                            | `project-patterns/SKILL.md`                                    | `Result<T, E> for fallible ops`               |
+| `conventions.errors`           | Error-handling approach                                   | `backend-conventions/SKILL.md`                                 | `throw / Result<T,E> / silent catch`          |
+| `conventions.logging`          | Logging approach                                          | `backend-conventions/SKILL.md`                                 | `pino structured logger`                      |
+| `conventions.api_format`       | API response shape                                        | `backend-conventions/SKILL.md`                                 | `REST JSON: {data, error}`                    |
+| `conventions.naming`           | Naming conventions (vars, files, branches)                | `project-patterns/SKILL.md`                                    | `camelCase TS / snake_case Python / kebab branches` |
+| `conventions.rules`            | Never / always project rules                              | `project-patterns/SKILL.md`                                    | `never push to main`                          |
+| `verification.manual`          | Manual verification steps                                 | `## Verification` of `docs/spec/SPEC.md`                       | `run /init against tmp/ and eyeball output`   |
+| `verification.staging`         | Whether there's a staging / preview env                   | `## Verification` of `docs/spec/SPEC.md`                       | `yes — Vercel preview per PR`                 |
+| `verification.required_checks` | CI required checks gating merge                           | `## Verification` of `docs/spec/SPEC.md`                       | `tests, lint, type-check`                     |
+
+Help-render format when the user types `help` at a CONFIRM or INTERVIEW
+prompt — render in a fenced code block:
+
+```
+Help — <formatField(field) or questionId>
+
+  What it is: <description>
+  Will be saved as: <target>
+  Example answer: <example>
+```
+
+For CONFIRM_HIGH (multiple fields on one prompt), render one Help
+block per item. After rendering help, restate the original prompt
+verbatim without advancing.
+
 ---
 
 ## Field rendering table
@@ -470,7 +784,7 @@ CONFIRM_HIGH and CONFIRM_MEDIUM to render `<renderValue(item)>`.
 | `scripts`        | `{dev, test, build, lint, ...}`                | `dev=<dev.key> test=<test.key> build=<build.key> lint=<lint.key>` — omit null slots; all null → `(no standard scripts)` |
 | `envVariables`   | `{names: string[], inferredServices: [...]}`   | `<N> variable(s)` (singular when `N === 1`; 0 → omit)                |
 | `externalApis`   | `string[]`                                     | joined by `, ` (empty → omit)                                        |
-| `readme`         | `{projectDescription, ...}`                    | `<projectDescription>` truncated to 80 chars with `…` suffix          |
+| `readme`         | `{projectDescription, ...}`                    | `<projectDescription>` rendered verbatim; soft-wrap at 100 chars per line for display only (no `…` truncation — user needs the full text to decide whether to accept) |
 | `specDocs`       | `[{path, firstHeading}, ...]`                  | `<N> doc(s)` (empty → omit)                                          |
 | `monorepo`       | `{tool, packagePaths, ...}`                    | `<tool> (<N> packages)`                                              |
 | fallback scalar  | string / number / boolean                      | `String(value)`                                                      |

package/templates/settings/base.json

@@ -14,6 +14,11 @@
       "Bash(git:*)",
       "Bash(gh:*)",
 
+      "// -- Worclaude Self --",
+      "Bash(worclaude:*)",
+      "Bash(worclaude scan:*)",
+      "Bash(worclaude setup-state:*)",
+
       "// -- Common Dev Tools --",
       "Bash(echo:*)", "Bash(mkdir:*)", "Bash(touch:*)",
       "Bash(cp:*)", "Bash(mv:*)",