create-quiver 0.9.1 → 0.12.0

package/src/create-quiver/index.js

@@ -3,16 +3,39 @@ const os = require('os');
 const path = require('path');
 const { execFileSync } = require('child_process');
 const { checkHandoff, scaffoldHandoff } = require('./lib/handoff');
-const { collectDoctorWarnings } = require('./lib/doctor');
+const {
+  applyDoctorFixPlan,
+  buildDoctorFixPlan,
+  collectDoctorReport,
+  formatDoctorFixPlan,
+} = require('./lib/doctor');
+const { runAgent: runAiAgent, runApprovalStatus: runAiApprovalStatus, runApprove: runAiApprove, runDoctor: runAiDoctor, runExecutePlan: runAiExecutePlan, runExecuteSlice: runAiExecuteSlice, runOnboard, runPlan: runAiPlan, runPrepareContext: runAiPrepareContext, runPr: runAiPr, runPromptSlice: runAiPromptSlice, runReviewPlan: runAiReviewPlan } = require('./commands/ai');
+const { runDemo } = require('./commands/demo');
+const { runPrepare } = require('./commands/prepare');
+const { runEvidence } = require('./commands/evidence');
+const { runFlow } = require('./commands/flow');
 const { runGraph } = require('./commands/graph');
 const { runNext } = require('./commands/next');
 const { runPlan } = require('./commands/plan');
-const { initializeProjectDocs, installSelfAsDevDep } = require('./lib/init-docs');
+const { runCreateSpec } = require('./commands/spec');
+const { buildInitLayout, formatInitLayoutPlan } = require('./lib/init-layout');
+const { initializeProjectDocs, installSelfAsDevDep, refreshAiContextDoc } = require('./lib/init-docs');
 const { checkPrReadiness, checkScope, checkSliceReadiness } = require('./lib/readiness');
 const { cleanupSlice, refreshActiveSlicesBoard, startSlice } = require('./lib/lifecycle');
+const { buildSpecStatus, closeSpecWorktree, formatSpecCloseResult, formatSpecStartResult, formatSpecStatus, startSpecWorktree } = require('./lib/spec-worktrees');
+const { getContextPathExclusionReason } = require('./lib/ai/safety');
 const { relativePosixPath, resolveTargetRoot } = require('./lib/paths');
+const {
+  CURRENT_SCAN_RELATIVE_PATH,
+  PROJECT_MAP_RELATIVE_PATH,
+  hasProjectScanArtifact,
+  projectScanPaths,
+  writeProjectScanJson,
+} = require('./lib/project-scan');
+const { resolveTemplateRoot } = require('./lib/template-resolver');
 const {
   hasQuiverInitializationEvidence,
+  inspectLegacyMigrationLayout,
   readState,
   updateStateForAnalyze,
   updateStateForMigrate,
@@ -24,15 +47,74 @@ function formatError(message) {
   return `create-quiver: ${message}`;
 }
 
+const SUPPORTED_COMMAND_MODES = new Set([
+  'init',
+  'flow',
+  'plan',
+  'graph',
+  'next',
+  'doctor',
+  'prepare',
+  'analyze',
+  'migrate',
+  'start-slice',
+  'check-slice',
+  'check-pr',
+  'check-handoff',
+  'new-handoff',
+  'cleanup-slice',
+  'check-scope',
+  'refresh-active-slices',
+  'spec',
+  'evidence',
+  'demo',
+  'ai',
+]);
+
+const SUPPORTED_AI_COMMANDS = new Set([
+  'agent',
+  'approve',
+  'approval-status',
+  'approvals',
+  'doctor',
+  'execute-plan',
+  'execute-slice',
+  'executor-prompt',
+  'onboard',
+  'plan',
+  'prepare-context',
+  'pr',
+  'prompt-slice',
+  'review-plan',
+]);
+
+const SUPPORTED_SPEC_COMMANDS = new Set(['close', 'create', 'start', 'status']);
+const SUPPORTED_DEMO_COMMANDS = new Set(['create']);
+
+function unsupportedCommandMessage(commandName) {
+  return [
+    `unsupported command: ${commandName}`,
+    'Run: npx create-quiver --help',
+    `If you meant to initialize a project, use: npx create-quiver init --name "${commandName}"`,
+    'If this command exists in newer docs, update create-quiver and rerun the command.',
+  ].join('\n');
+}
+
 function printUsage() {
   console.log(`Usage:
   npx create-quiver [options]
+  npx create-quiver init [options]
   npx create-quiver analyze [options]
+  npx create-quiver flow [options]
   npx create-quiver plan [options]
+  npx create-quiver ai <task> [options]
+  npx create-quiver ai agent <set|list|show> [role] [options]
+  npx create-quiver ai prepare-context [options]
   npx create-quiver graph [options]
   npx create-quiver next [options]
   npx create-quiver migrate [options]
   npx create-quiver doctor [options]
+  npx create-quiver prepare [options]
   npx create-quiver start-slice [options] <slice.json>
   npx create-quiver check-slice [options] <slice.json>
   npx create-quiver check-pr <slice.json>
@@ -41,6 +123,12 @@ function printUsage() {
   npx create-quiver cleanup-slice [options] <slice.json>
   npx create-quiver check-scope [options] <slice.json>
   npx create-quiver refresh-active-slices
+  npx create-quiver spec create [options]
+  npx create-quiver spec start <spec-dir>
+  npx create-quiver spec status <spec-dir>
+  npx create-quiver spec close <spec-dir>
+  npx create-quiver evidence run [options] -- <command>
+  npx create-quiver demo create spec-viewer [options]
 
 Options:
   -n, --name <project-name>   Project name to generate
@@ -50,18 +138,63 @@ Options:
       --show-conflicts        Show shared file paths in graph output
       --level <n>             Restrict graph output to one level
       --json                  Emit machine-readable JSON
+      --include-completed     Include completed slices in plan, graph, or next history output
       --only-ready            Show only slices with no pending dependencies
       --all-ready             List every ready slice returned by next
       --auto-start            Prompt for confirmation and run start-slice on next
+      --local                 For check-slice, run structural validation without remote/base checks
       --unicode               Prefer Unicode output when supported
+      --minimal               Plan or run the minimal init profile
+      --full                  Plan or run the full compatibility init profile
+      --legacy-scripts        Include legacy Bash wrappers in init profile
+      --include-templates     Export packaged templates in init profile
+      --dry-run               Preview init, prepare, spec create, demo, or AI work without executing writes/providers
+      --fix                   For doctor, apply safe non-destructive repairs
+      --execute               For ai execute-plan, run the planned slices instead of printing commands
+      --create                For ai pr, create the PR after preflight instead of printing the plan only
+      --commit                For ai execute-slice, commit validated slice changes after provider, scope, and tests pass
+      --allow-dirty           For ai execute-slice, allow pre-existing dirty files and ignore them for scope diff
+      --mode <name>           Execution mode for ai execute-plan (auto, manual, delegated)
+      --provider <name>       Provider CLI to preflight for prepare or AI commands
+      --model <label>         Free-form model label for AI agent profiles
+      --version <n>           Draft version to approve for AI planner phases
+      --ssh-host-alias <name> SSH host alias to validate for prepare or AI commands
+      --identity-file <path>  SSH identity file to validate for prepare or AI commands
+      --remote <name>         Git remote name for check-slice or AI PR checks
+      --base <branch>         Base branch for check-slice, ai pr, or spec close (default: main)
+      --output <file>         Output file for evidence run
+      --max-output <n>        Maximum stdout/stderr chars per evidence section
+      --title <text>          Override PR title for ai pr create
   -y, --yes                   Skip prompts and use the provided inputs
   -h, --help                  Show this help message
 
 Examples:
+  npx create-quiver init --name "My Project"
+  npx create-quiver init --name "My Project" --dry-run
   npx create-quiver --name "My Project"
   npx create-quiver --name "My Project" --dir ./my-project
+  cd ./my-project && npx create-quiver flow
   cd ./my-project && npx create-quiver analyze
   cd ./my-project && npx create-quiver plan --json
+  cd ./my-project && npx create-quiver ai onboard --dry-run
+  cd ./my-project && npx create-quiver ai prepare-context --dry-run
+  cd ./my-project && npx create-quiver ai agent set planner --provider codex --model gpt-5.5
+  cd ./my-project && npx create-quiver ai agent list
+  cd ./my-project && npx create-quiver ai plan --phase acceptance --input requirements.md --dry-run
+  cd ./my-project && npx create-quiver ai approve --phase acceptance --input acceptance.md
+  cd ./my-project && npx create-quiver ai plan --phase technical-plan --dry-run
+  cd ./my-project && npx create-quiver ai review-plan --dry-run
+  cd ./my-project && npx create-quiver ai approve --phase technical-plan --version 1
+  cd ./my-project && npx create-quiver spec create --dry-run
+  cd ./my-project && npx create-quiver ai approvals
+  cd ./my-project && npx create-quiver ai prompt-slice --slice specs/my-project/slices/slice-01/slice.json --dry-run
+  cd ./my-project && npx create-quiver ai execute-slice --slice specs/my-project/slices/slice-01/slice.json --dry-run
+  cd ./my-project && npx create-quiver ai execute-slice --slice specs/my-project/slices/slice-01/slice.json --commit
+  cd ./my-project && npx create-quiver ai execute-plan --dry-run --commit
+  cd ./my-project && npx create-quiver ai doctor --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+  cd ./my-project && npx create-quiver ai pr --dry-run --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+  cd ./my-project && npx create-quiver ai pr --create --input specs/my-project/pr.md --ssh-host-alias github-work --identity-file ~/.ssh/github-work
+  cd ./my-project && npx create-quiver prepare --dry-run --provider codex --ssh-host-alias github-work --identity-file ~/.ssh/github-work
   cd ./my-project && npx create-quiver graph --show-conflicts
   cd ./my-project && npx create-quiver graph --format mermaid
   cd ./my-project && npx create-quiver graph --format dot
@@ -78,6 +211,11 @@ Examples:
   cd ./my-project && npx create-quiver cleanup-slice specs/my-project/slices/slice-01/slice.json
   cd ./my-project && npx create-quiver check-scope specs/my-project/slices/slice-01/slice.json
   cd ./my-project && npx create-quiver refresh-active-slices
+  cd ./my-project && npx create-quiver spec start specs/my-project
+  cd ./my-project && npx create-quiver spec status specs/my-project
+  cd ./my-project && npx create-quiver spec close specs/my-project --dry-run
+  cd ./my-project && npx create-quiver evidence run -- npm test
+  cd ./my-project && npx create-quiver demo create spec-viewer --dry-run
   node bin/create-quiver.js doctor --dir ./my-project
 `);
 }
@@ -86,17 +224,22 @@ function parseArgs(argv) {
   const result = {
     help: false,
     force: false,
+    explicitInit: false,
     mode: 'init',
     allowDraft: false,
+    checkSliceLocal: false,
     closeBaseline: false,
     discard: false,
+    doctorFix: false,
     dryRun: false,
     gate: 'execution',
     projectName: '',
     targetDir: '.',
+    targetDirExplicit: false,
     strict: false,
     strictOverlap: false,
     json: false,
+    includeCompleted: false,
     onlyReady: false,
     allReady: false,
     autoStart: false,
@@ -105,13 +248,60 @@ function parseArgs(argv) {
     showConflicts: false,
     level: null,
     unicode: false,
+    aiCommand: '',
+    aiAgentCommand: '',
+    aiAgentRole: '',
+    aiPhase: 'acceptance',
+    aiProvider: 'codex',
+    aiProviderExplicit: false,
+    aiModel: '',
+    aiLabel: '',
+    aiVersion: '',
+    prepareProvider: '',
+    aiRole: '',
+    aiContext: '',
+    aiInput: '',
+    aiSlice: '',
+    aiTimeout: null,
+    aiCommit: false,
+    aiAllowDirty: false,
+    aiExecute: false,
+    aiExecutionMode: 'auto',
+    aiCreate: false,
+    aiBaseBranch: 'main',
+    baseBranchExplicit: false,
+    aiTitle: '',
+    aiSshHostAlias: '',
+    aiIdentityFile: '',
+    aiRemote: 'origin',
+    initFull: false,
+    initIncludeTemplates: false,
+    initLegacyScripts: false,
+    initMinimal: false,
+    specCommand: '',
+    demoCommand: '',
+    demoName: '',
+    evidenceCommand: '',
+    evidenceArgs: [],
+    evidenceOutput: '',
+    evidenceMaxOutput: null,
   };
 
   const args = [...argv];
-  const commandModes = new Set(['plan', 'graph', 'next', 'doctor', 'analyze', 'migrate', 'start-slice', 'check-slice', 'check-pr', 'check-handoff', 'new-handoff', 'cleanup-slice', 'check-scope', 'refresh-active-slices']);
-  if (commandModes.has(args[0])) {
+  if (SUPPORTED_COMMAND_MODES.has(args[0])) {
     result.mode = args[0];
+    result.explicitInit = args[0] === 'init';
     args.shift();
+    if (result.mode === 'spec') {
+      result.specCommand = args.shift() || '';
+    }
+    if (result.mode === 'evidence') {
+      result.evidenceCommand = args.shift() || '';
+    }
+    if (result.mode === 'demo') {
+      result.demoCommand = args.shift() || '';
+      result.demoName = args.shift() || '';
+    }
   } else if (args[0] === '--analyze') {
     result.mode = 'analyze';
     args.shift();
@@ -127,6 +317,8 @@ function parseArgs(argv) {
   } else if (args[0] === '--new-handoff') {
     result.mode = 'new-handoff';
     args.shift();
+  } else if (args[0] && !args[0].startsWith('-')) {
+    throw new Error(formatError(unsupportedCommandMessage(args[0])));
   }
 
   const positional = [];
@@ -134,6 +326,11 @@ function parseArgs(argv) {
   for (let index = 0; index < args.length; index += 1) {
     const arg = args[index];
 
+    if (arg === '--') {
+      result.evidenceArgs = args.slice(index + 1);
+      break;
+    }
+
     if (arg === '-h' || arg === '--help') {
       result.help = true;
       continue;
@@ -174,6 +371,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--local') {
+      result.checkSliceLocal = true;
+      continue;
+    }
+
     if (arg === '--close-baseline') {
       result.closeBaseline = true;
       continue;
@@ -184,11 +386,65 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--fix') {
+      result.doctorFix = true;
+      continue;
+    }
+
     if (arg === '--dry-run') {
       result.dryRun = true;
       continue;
     }
 
+    if (arg === '--commit') {
+      result.aiCommit = true;
+      continue;
+    }
+
+    if (arg === '--execute') {
+      result.aiExecute = true;
+      continue;
+    }
+
+    if (arg === '--create') {
+      result.aiCreate = true;
+      continue;
+    }
+
+    if (arg === '--mode') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --mode'));
+      }
+      result.aiExecutionMode = value;
+      continue;
+    }
+
+    if (arg === '--allow-dirty') {
+      result.aiAllowDirty = true;
+      continue;
+    }
+
+    if (arg === '--minimal') {
+      result.initMinimal = true;
+      continue;
+    }
+
+    if (arg === '--full') {
+      result.initFull = true;
+      continue;
+    }
+
+    if (arg === '--legacy-scripts') {
+      result.initLegacyScripts = true;
+      continue;
+    }
+
+    if (arg === '--include-templates') {
+      result.initIncludeTemplates = true;
+      continue;
+    }
+
     if (arg === '--strict') {
       result.strict = true;
       continue;
@@ -204,6 +460,11 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--include-completed') {
+      result.includeCompleted = true;
+      continue;
+    }
+
     if (arg === '--show-conflicts') {
       result.showConflicts = true;
       continue;
@@ -251,6 +512,170 @@ function parseArgs(argv) {
       continue;
     }
 
+    if (arg === '--provider') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --provider'));
+      }
+      result.aiProvider = value;
+      result.prepareProvider = value;
+      result.aiProviderExplicit = true;
+      continue;
+    }
+
+    if (arg === '--model') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --model'));
+      }
+      result.aiModel = value;
+      continue;
+    }
+
+    if (arg === '--label') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --label'));
+      }
+      result.aiLabel = value;
+      continue;
+    }
+
+    if (arg === '--version') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --version'));
+      }
+      result.aiVersion = value;
+      continue;
+    }
+
+    if (arg === '--role') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --role'));
+      }
+      result.aiRole = value;
+      continue;
+    }
+
+    if (arg === '--context') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --context'));
+      }
+      result.aiContext = value;
+      continue;
+    }
+
+    if (arg === '--input') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --input'));
+      }
+      result.aiInput = value;
+      continue;
+    }
+
+    if (arg === '--slice') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --slice'));
+      }
+      result.aiSlice = value;
+      continue;
+    }
+
+    if (arg === '--timeout') {
+      const value = args[++index];
+      if (typeof value === 'undefined') {
+        throw new Error(formatError('missing value for --timeout'));
+      }
+      const parsed = Number.parseInt(value, 10);
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(formatError('invalid value for --timeout'));
+      }
+      result.aiTimeout = parsed;
+      continue;
+    }
+
+    if (arg === '--ssh-host-alias') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --ssh-host-alias'));
+      }
+      result.aiSshHostAlias = value;
+      continue;
+    }
+
+    if (arg === '--identity-file') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --identity-file'));
+      }
+      result.aiIdentityFile = value;
+      continue;
+    }
+
+    if (arg === '--remote') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --remote'));
+      }
+      result.aiRemote = value;
+      continue;
+    }
+
+    if (arg === '--base') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --base'));
+      }
+      result.aiBaseBranch = value;
+      result.baseBranchExplicit = true;
+      continue;
+    }
+
+    if (arg === '--output') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --output'));
+      }
+      result.evidenceOutput = value;
+      continue;
+    }
+
+    if (arg === '--max-output') {
+      const value = args[++index];
+      if (typeof value === 'undefined') {
+        throw new Error(formatError('missing value for --max-output'));
+      }
+      const parsed = Number.parseInt(value, 10);
+      if (!Number.isInteger(parsed) || parsed <= 0) {
+        throw new Error(formatError('invalid value for --max-output'));
+      }
+      result.evidenceMaxOutput = parsed;
+      continue;
+    }
+
+    if (arg === '--title') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --title'));
+      }
+      result.aiTitle = value;
+      continue;
+    }
+
+    if (arg === '--phase') {
+      const value = args[++index];
+      if (!value) {
+        throw new Error(formatError('missing value for --phase'));
+      }
+      result.aiPhase = value;
+      continue;
+    }
+
     if (arg === '--spec') {
       const value = args[++index];
       if (!value) {
@@ -284,6 +709,7 @@ function parseArgs(argv) {
         throw new Error(formatError('missing value for --dir'));
       }
       result.targetDir = value;
+      result.targetDirExplicit = true;
       continue;
     }
 
@@ -306,10 +732,78 @@ function parseArgs(argv) {
     if (positional.length > 0) {
       throw new Error(formatError('plan does not accept positional arguments; use --spec <slug>'));
     }
+  } else if (result.mode === 'flow') {
+    if (positional.length > 0) {
+      throw new Error(formatError('flow does not accept positional arguments'));
+    }
+  } else if (result.mode === 'ai') {
+    if (!result.aiCommand && positional.length > 0) {
+      result.aiCommand = positional.shift();
+    }
+    if (result.aiCommand === 'agent') {
+      if (!result.aiAgentCommand && positional.length > 0) {
+        result.aiAgentCommand = positional.shift();
+      }
+      if (!result.aiAgentRole && positional.length > 0) {
+        result.aiAgentRole = positional.shift();
+      }
+    }
+    if (positional.length > 0) {
+      throw new Error(formatError('ai does not accept extra positional arguments'));
+    }
+  } else if (result.mode === 'prepare') {
+    if (positional.length > 0) {
+      throw new Error(formatError('prepare does not accept positional arguments'));
+    }
   } else if (result.mode === 'refresh-active-slices') {
     if (positional.length > 0) {
       throw new Error(formatError('refresh-active-slices does not accept positional arguments'));
     }
+  } else if (result.mode === 'spec') {
+    if (!result.specCommand && positional.length > 0) {
+      result.specCommand = positional.shift();
+    }
+    if (!result.specCommand) {
+      throw new Error(formatError('missing spec subcommand. Use: npx create-quiver spec <create|start|status|close>'));
+    }
+    if (result.specCommand !== 'create' && positional.length > 0) {
+      result.targetDir = positional.shift();
+    }
+    if (result.specCommand === 'create' && positional.length > 0) {
+      throw new Error(formatError('spec create does not accept positional arguments; use --input <file> or --spec <slug>'));
+    }
+  } else if (result.mode === 'evidence') {
+    if (!result.evidenceCommand && positional.length > 0) {
+      result.evidenceCommand = positional.shift();
+    }
+    if (!result.evidenceCommand) {
+      throw new Error(formatError('missing evidence subcommand. Use: npx create-quiver evidence run -- <command>'));
+    }
+    if (result.evidenceCommand !== 'run') {
+      throw new Error(formatError(`unsupported evidence subcommand: ${result.evidenceCommand}. Supported tasks: run`));
+    }
+    if (positional.length > 0) {
+      throw new Error(formatError('evidence run does not accept positional arguments before --'));
+    }
+  } else if (result.mode === 'demo') {
+    if (!result.demoCommand && positional.length > 0) {
+      result.demoCommand = positional.shift();
+    }
+    if (!result.demoName && positional.length > 0) {
+      result.demoName = positional.shift();
+    }
+    if (!result.demoCommand) {
+      throw new Error(formatError('missing demo subcommand. Use: npx create-quiver demo create spec-viewer'));
+    }
+    if (!SUPPORTED_DEMO_COMMANDS.has(result.demoCommand)) {
+      throw new Error(formatError(`unsupported demo subcommand: ${result.demoCommand}. Supported tasks: create`));
+    }
+    if (result.demoName !== 'spec-viewer') {
+      throw new Error(formatError(`unsupported demo: ${result.demoName || '(missing)'}. Supported demos: spec-viewer`));
+    }
+    if (positional.length > 0) {
+      throw new Error(formatError('demo create spec-viewer does not accept positional target paths; use --dir <target-dir>'));
+    }
   } else {
     if (positional.length > 0) {
       result.targetDir = positional.shift();
@@ -340,6 +834,43 @@ function runCommand(command, args, options = {}) {
   });
 }
 
+function copyPackageFallback(packageRoot, tempRoot) {
+  const fallbackDir = path.join(tempRoot, 'package-fallback');
+  const ignoredRoots = new Set([
+    '.git',
+    '.worktrees',
+    'examples',
+    'package-lock.json',
+    'tests',
+  ]);
+  const ignoredPrefixes = [
+    'scripts/ci',
+    'specs/quiver-v01',
+    'specs/quiver-v02-bootstrap-hardening',
+    'specs/quiver-v03-adoption-verification',
+    'specs/quiver-v04-zero-friction-installation',
+  ];
+
+  fs.cpSync(packageRoot, fallbackDir, {
+    recursive: true,
+    filter: (sourcePath) => {
+      const relativePath = relativePosixPath(packageRoot, sourcePath);
+      if (!relativePath || relativePath === '.') {
+        return true;
+      }
+
+      const firstSegment = relativePath.split('/')[0];
+      if (ignoredRoots.has(firstSegment) || ignoredRoots.has(relativePath)) {
+        return false;
+      }
+
+      return !ignoredPrefixes.some((prefix) => relativePath === prefix || relativePath.startsWith(`${prefix}/`));
+    },
+  });
+
+  return fallbackDir;
+}
+
 function packTemplate(packageRoot, tempRoot) {
   const packDir = path.join(tempRoot, 'pack');
   const extractDir = path.join(tempRoot, 'extract');
@@ -349,24 +880,32 @@ function packTemplate(packageRoot, tempRoot) {
   fs.mkdirSync(extractDir, { recursive: true });
   fs.mkdirSync(npmCache, { recursive: true });
 
-  const packOutput = runCommand('npm', ['pack', '--json', '--pack-destination', packDir], {
-    cwd: packageRoot,
-    env: {
-      ...process.env,
-      npm_config_cache: npmCache,
-    },
-  });
+  try {
+    const packOutput = runCommand('npm', ['pack', '--json', '--pack-destination', packDir], {
+      cwd: packageRoot,
+      env: {
+        ...process.env,
+        npm_config_cache: npmCache,
+      },
+    });
 
-  const packInfo = JSON.parse(packOutput.trim());
-  const tarballPath = path.join(packDir, packInfo[0].filename);
+    const packInfo = JSON.parse(packOutput.trim());
+    const tarballPath = path.join(packDir, packInfo[0].filename);
 
-  if (!fs.existsSync(tarballPath)) {
-    throw new Error(formatError(`pack output not found at ${tarballPath}`));
-  }
+    if (!fs.existsSync(tarballPath)) {
+      throw new Error(formatError(`pack output not found at ${tarballPath}`));
+    }
+
+    runCommand('tar', ['-xzf', tarballPath, '-C', extractDir]);
 
-  runCommand('tar', ['-xzf', tarballPath, '-C', extractDir]);
+    return path.join(extractDir, 'package');
+  } catch (error) {
+    if (error && error.code === 'ENOENT') {
+      return copyPackageFallback(packageRoot, tempRoot);
+    }
 
-  return path.join(extractDir, 'package');
+    throw error;
+  }
 }
 
 function ensureDir(dirPath) {
@@ -385,6 +924,10 @@ function copyTemplate(templateRoot, targetDir) {
   return docsTemplateDir;
 }
 
+function exportTemplatesToLegacyRoot(templateRoot, targetDir) {
+  return copyTemplate(templateRoot, targetDir);
+}
+
 function mergeDirectoryTree(sourceDir, targetDir) {
   if (!fs.existsSync(sourceDir)) {
     return;
@@ -399,12 +942,22 @@ function mergeDirectoryTree(sourceDir, targetDir) {
   });
 }
 
-function runInitDocs(repoRoot, projectName) {
+function runInitDocs(repoRoot, projectName, options = {}) {
+  const templateRoot = options.templateRoot
+    ? { path: options.templateRoot }
+    : resolveTemplateRoot(repoRoot, {
+      packageRoot: path.resolve(__dirname, '../..'),
+    });
+
   initializeProjectDocs({
     projectRoot: repoRoot,
     projectName,
     cliVersion: CLI_VERSION,
+    includeTemplates: options.includeTemplates === true,
+    legacyScripts: options.legacyScripts === true,
     migrateMode: false,
+    profile: options.profile || 'default',
+    templateRoot: templateRoot.path,
   });
 }
 
@@ -426,6 +979,10 @@ function assertFilesExist(root, relativePaths) {
 }
 
 function assertExecutablesExist(root, relativePaths) {
+  if (process.platform === 'win32') {
+    return [];
+  }
+
   return relativePaths.filter((relativePath) => {
     const absolutePath = path.join(root, relativePath);
 
@@ -472,6 +1029,43 @@ function escapeMarkdownCell(value) {
   return String(value).replace(/\|/g, '\\|');
 }
 
+function summarizeSkippedPaths(scan) {
+  const details = Array.isArray(scan.skipped_path_details) && scan.skipped_path_details.length > 0
+    ? scan.skipped_path_details
+    : (Array.isArray(scan.skipped_paths) ? scan.skipped_paths.map((item) => ({ reason: 'excluded path', path: item })) : []);
+  const counts = new Map();
+  const dependencySegments = new Set(['node_modules', '.pnpm-store', '.npm', '.yarn']);
+  const outputSegments = new Set(['dist', 'build', 'coverage', 'out', 'tmp', 'temp', 'cache', '.cache', '.turbo', '.next', '.nuxt', '.parcel-cache', 'generated', 'gen', 'artifacts', 'reports', 'vendor', 'target']);
+
+  for (const item of details) {
+    const reason = item.reason || 'excluded path';
+    let label = reason;
+    if (reason === 'env-file') {
+      label = 'env files';
+    } else if (reason === 'git-metadata') {
+      label = 'git metadata';
+    } else if (reason === 'hidden-directory') {
+      label = 'hidden directories';
+    } else if (reason.startsWith('secret-file:')) {
+      label = 'secret files';
+    } else if (reason.startsWith('unsafe-segment:')) {
+      const segment = reason.slice('unsafe-segment:'.length);
+      if (segment === '.quiver') {
+        label = 'local AI state';
+      } else if (dependencySegments.has(segment)) {
+        label = 'dependency folders';
+      } else if (outputSegments.has(segment)) {
+        label = 'generated/output/cache folders';
+      } else {
+        label = segment;
+      }
+    }
+    counts.set(label, (counts.get(label) || 0) + 1);
+  }
+
+  return Array.from(counts.entries()).map(([reason, count]) => ({ reason, count }));
+}
+
 function collectPackageManagers(projectRoot) {
   const packageManagerField = readJsonIfExists(path.join(projectRoot, 'package.json'))?.packageManager;
 
@@ -499,6 +1093,7 @@ function collectPackageManagers(projectRoot) {
 function collectProjectFiles(projectRoot, maxDepth = 2) {
   const files = [];
   const skippedPaths = [];
+  const skippedPathDetails = [];
   const ignoredDirs = new Set([
     '.git',
     'node_modules',
@@ -515,6 +1110,12 @@ function collectProjectFiles(projectRoot, maxDepth = 2) {
   ]);
   const allowedHiddenDirs = new Set(['.github', '.vscode', '.devcontainer']);
 
+  function skipPath(relativePath, reason) {
+    const normalized = relativePath.split(path.sep).join('/');
+    skippedPaths.push(normalized);
+    skippedPathDetails.push({ path: normalized, reason });
+  }
+
   function walk(currentDir, depth, relativeDir = '') {
     const entries = fs.readdirSync(currentDir, { withFileTypes: true });
 
@@ -524,12 +1125,18 @@ function collectProjectFiles(projectRoot, maxDepth = 2) {
 
       if (entry.isDirectory()) {
         if (ignoredDirs.has(entry.name)) {
-          skippedPaths.push(entryRelativePath);
+          skipPath(entryRelativePath, `unsafe-segment:${entry.name}`);
+          continue;
+        }
+
+        const directoryReason = getContextPathExclusionReason(entryRelativePath);
+        if (directoryReason) {
+          skipPath(entryRelativePath, directoryReason);
           continue;
         }
 
         if (entry.name.startsWith('.') && !allowedHiddenDirs.has(entry.name)) {
-          skippedPaths.push(entryRelativePath);
+          skipPath(entryRelativePath, 'hidden-directory');
           continue;
         }
 
@@ -540,13 +1147,19 @@ function collectProjectFiles(projectRoot, maxDepth = 2) {
         continue;
       }
 
+      const fileReason = getContextPathExclusionReason(entryRelativePath);
+      if (fileReason) {
+        skipPath(entryRelativePath, fileReason);
+        continue;
+      }
+
       files.push(entryRelativePath);
     }
   }
 
   walk(projectRoot, 0);
 
-  return { files, skippedPaths };
+  return { files, skipped_path_details: skippedPathDetails, skippedPaths };
 }
 
 function collectRootEntries(projectRoot) {
@@ -594,6 +1207,7 @@ function collectLanguageSignals(files) {
   }
 
   const languages = [];
+  const seenLanguages = new Set();
   const extToLanguage = new Map([
     ['.ts', 'typescript'],
     ['.tsx', 'typescript'],
@@ -619,14 +1233,90 @@ function collectLanguageSignals(files) {
   ]);
 
   for (const [ext, language] of extToLanguage.entries()) {
-    if (extensions.has(ext)) {
+    if (extensions.has(ext) && !seenLanguages.has(language)) {
       languages.push(language);
+      seenLanguages.add(language);
     }
   }
 
   return languages;
 }
 
+function parseCreateQuiverScriptCommand(command) {
+  const normalized = String(command || '').trim();
+  const match = normalized.match(/^npx\s+create-quiver(?:@[^\s]+)?\s+(.+)$/);
+  if (!match) {
+    return null;
+  }
+
+  const tokens = match[1].split(/\s+/).filter(Boolean);
+  if (tokens.length === 0) {
+    return null;
+  }
+
+  return {
+    commandName: tokens[0],
+    subcommand: tokens[1] || '',
+  };
+}
+
+function findUnsupportedCreateQuiverScripts(scripts = {}) {
+  const unsupported = [];
+
+  for (const [scriptName, command] of Object.entries(scripts)) {
+    const parsed = parseCreateQuiverScriptCommand(command);
+    if (!parsed) {
+      continue;
+    }
+
+    if (!SUPPORTED_COMMAND_MODES.has(parsed.commandName)) {
+      unsupported.push({
+        command,
+        reason: `unsupported command "${parsed.commandName}"`,
+        scriptName,
+      });
+      continue;
+    }
+
+    if (parsed.commandName === 'ai' && !SUPPORTED_AI_COMMANDS.has(parsed.subcommand)) {
+      unsupported.push({
+        command,
+        reason: `unsupported ai subcommand "${parsed.subcommand || '(missing)'}"`,
+        scriptName,
+      });
+      continue;
+    }
+
+    if (parsed.commandName === 'spec' && !SUPPORTED_SPEC_COMMANDS.has(parsed.subcommand)) {
+      unsupported.push({
+        command,
+        reason: `unsupported spec subcommand "${parsed.subcommand || '(missing)'}"`,
+        scriptName,
+      });
+      continue;
+    }
+
+    if (parsed.commandName === 'demo' && !SUPPORTED_DEMO_COMMANDS.has(parsed.subcommand)) {
+      unsupported.push({
+        command,
+        reason: `unsupported demo subcommand "${parsed.subcommand || '(missing)'}"`,
+        scriptName,
+      });
+    }
+  }
+
+  return unsupported;
+}
+
+function detectNodeProject(files, rootEntries, packageJson, languages) {
+  const hasPackageJson = Boolean(packageJson);
+  const hasJavaScriptSignals = languages.some((language) => language === 'javascript' || language === 'typescript');
+  const hasSourceDirectories = detectSourceDirectories(rootEntries).length > 0;
+  const hasSourceFiles = files.some((file) => /\.(?:c|m)?jsx?$/i.test(file) || /\.(?:c|m)?tsx?$/i.test(file));
+
+  return hasJavaScriptSignals && (hasPackageJson || hasSourceDirectories || hasSourceFiles);
+}
+
 function collectWorkspaces(packageJson) {
   if (!packageJson) {
     return [];
@@ -756,6 +1446,11 @@ function detectFrameworks(projectRoot, files, rootEntries, packageJson) {
     evidence.push({ framework: 'react', signals: ['react', 'typescript files'] });
   }
 
+  if (frameworks.length === 0 && detectNodeProject(files, rootEntries, packageJson, languages)) {
+    frameworks.push('node');
+    evidence.push({ framework: 'node', signals: ['package.json', 'javascript or typescript source files'] });
+  }
+
   const primary = frameworks[0] || 'unknown';
 
   return {
@@ -850,7 +1545,7 @@ function detectRisks(projectRoot, scan) {
 function buildProjectScan(projectRoot) {
   const packageJson = readJsonIfExists(path.join(projectRoot, 'package.json'));
   const rootEntries = collectRootEntries(projectRoot);
-  const { files, skippedPaths } = collectProjectFiles(projectRoot);
+  const { files, skippedPaths, skipped_path_details } = collectProjectFiles(projectRoot);
   const topLevelDirectories = rootEntries.filter((entry) => entry.type === 'directory' && !entry.name.startsWith('.')).map((entry) => entry.name);
   const sourceDirectories = detectSourceDirectories(rootEntries);
   const configFiles = detectConfigFiles(rootEntries);
@@ -908,6 +1603,7 @@ function buildProjectScan(projectRoot) {
     },
     risks: [],
     skipped_paths: skippedPaths,
+    skipped_path_details,
   };
 
   scan.risks = detectRisks(projectRoot, scan);
@@ -931,8 +1627,8 @@ function renderProjectMap(scan) {
     'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
     'docs/DECISIONS.md',
-    'docs/PROJECT_SCAN.json',
-    'docs/PROJECT_MAP.md',
+    CURRENT_SCAN_RELATIVE_PATH,
+    PROJECT_MAP_RELATIVE_PATH,
     'docs/AI_ONBOARDING_PROMPT.md',
     'docs/CONTEXTO.md',
     'docs/WORKFLOW.md',
@@ -952,8 +1648,7 @@ function renderProjectMap(scan) {
     'README.md',
     'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
-    'docs/PROJECT_SCAN.json',
-    'docs/PROJECT_MAP.md',
+    PROJECT_MAP_RELATIVE_PATH,
     hasDecisionLog ? 'docs/DECISIONS.md' : 'docs/DECISIONS.md (create with migrate if missing)',
     'docs/CONTEXTO.md',
     'docs/WORKFLOW.md',
@@ -993,7 +1688,7 @@ function renderProjectMap(scan) {
   lines.push('## Entry Points');
   lines.push(`- Project overview: ${scan.docs.has_readme ? 'README.md' : 'docs/CONTEXTO.md'}`);
   lines.push(`- AI context: ${hasDecisionLog ? 'docs/AI_CONTEXT.md + docs/DECISIONS.md' : 'docs/AI_CONTEXT.md'}`);
-  lines.push('- Analysis outputs: docs/PROJECT_SCAN.json, docs/PROJECT_MAP.md');
+  lines.push(`- Analysis outputs: ${CURRENT_SCAN_RELATIVE_PATH}, ${PROJECT_MAP_RELATIVE_PATH}`);
   lines.push(`- Workflow contract: docs/WORKFLOW.md`);
   lines.push(`- Spec contract: specs/${projectSlug}/SPEC.md`);
   if (sourceDirs.length > 0) {
@@ -1025,7 +1720,7 @@ function renderProjectMap(scan) {
   }
 
   const relevantScripts = Object.entries(scan.commands.scripts)
-    .filter(([name]) => /(^|:)(analyze|doctor|migrate|test|build|lint|dev|start|check)(:|$)|analyze|doctor|migrate|test|build|lint|dev|start|check/i.test(name))
+    .filter(([name]) => /(^|:)(analyze|doctor|migrate|validate|test|build|lint|dev|start|check)(:|$)|analyze|doctor|migrate|validate|test|build|lint|dev|start|check/i.test(name))
     .slice(0, 12);
 
   if (relevantScripts.length > 0) {
@@ -1085,9 +1780,10 @@ function renderProjectMap(scan) {
 
   lines.push('');
   lines.push('## Skipped Paths');
-  if (scan.skipped_paths.length > 0) {
-    for (const skippedPath of scan.skipped_paths) {
-      lines.push(`- ${skippedPath}`);
+  const skippedSummaries = summarizeSkippedPaths(scan);
+  if (skippedSummaries.length > 0) {
+    for (const skippedPath of skippedSummaries) {
+      lines.push(`- ${skippedPath.reason}: ${skippedPath.count}`);
     }
   } else {
     lines.push('- None');
@@ -1095,10 +1791,8 @@ function renderProjectMap(scan) {
 
   lines.push('');
   lines.push('## Do Not Read First');
-  if (scan.skipped_paths.length > 0) {
-    for (const skippedPath of scan.skipped_paths) {
-      lines.push(`- ${skippedPath}`);
-    }
+  if (skippedSummaries.length > 0) {
+    lines.push('- Hidden, generated, secret, and cache paths are excluded from the analysis scan.');
   } else {
     lines.push('- None detected, but still prioritize docs and config files before source trees.');
   }
@@ -1108,16 +1802,13 @@ function renderProjectMap(scan) {
 }
 
 function writeProjectScanArtifacts(projectRoot, scan) {
-  const docsDir = path.join(projectRoot, 'docs');
-  ensureDir(docsDir);
+  const scanPaths = projectScanPaths(projectRoot);
+  ensureDir(path.dirname(scanPaths.projectMapPath));
 
-  const jsonPath = path.join(docsDir, 'PROJECT_SCAN.json');
-  const mdPath = path.join(docsDir, 'PROJECT_MAP.md');
+  const jsonPath = writeProjectScanJson(projectRoot, scan);
+  fs.writeFileSync(scanPaths.projectMapPath, `${renderProjectMap(scan)}\n`);
 
-  fs.writeFileSync(jsonPath, `${JSON.stringify(scan, null, 2)}\n`);
-  fs.writeFileSync(mdPath, `${renderProjectMap(scan)}\n`);
-
-  return { jsonPath, mdPath };
+  return { jsonPath, mdPath: scanPaths.projectMapPath };
 }
 
 function runAnalyze(targetDir) {
@@ -1129,11 +1820,13 @@ function runAnalyze(targetDir) {
 
   const scan = buildProjectScan(projectRoot);
   const artifacts = writeProjectScanArtifacts(projectRoot, scan);
+  const aiContextPath = refreshAiContextDoc(projectRoot, scan);
   updateStateForAnalyze(projectRoot, CLI_VERSION);
 
   console.log(`Project analysis completed for ${projectRoot}`);
   console.log(`Wrote ${relativePosixPath(projectRoot, artifacts.jsonPath)}`);
   console.log(`Wrote ${relativePosixPath(projectRoot, artifacts.mdPath)}`);
+  console.log(`Wrote ${relativePosixPath(projectRoot, aiContextPath)}`);
   console.log(`Detected primary stack: ${scan.stack.primary}`);
   console.log(`Detected package manager: ${scan.project.package_manager}`);
 }
@@ -1153,6 +1846,7 @@ function runMigrate(targetDir, options = {}) {
   const projectName = packageJson.name || path.basename(projectRoot) || 'Quiver Project';
   const packageRoot = path.resolve(__dirname, '../..');
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-migrate-'));
+  const legacyLayout = inspectLegacyMigrationLayout(projectRoot);
 
   try {
     const templateRoot = packTemplate(packageRoot, tempRoot);
@@ -1161,7 +1855,10 @@ function runMigrate(targetDir, options = {}) {
       projectRoot,
       projectName,
       cliVersion: CLI_VERSION,
+      legacyScripts: true,
       migrateMode: true,
+      profile: 'full',
+      templateRoot,
     });
     updateStateForMigrate(projectRoot, projectName, CLI_VERSION);
 
@@ -1176,12 +1873,15 @@ function runMigrate(targetDir, options = {}) {
 
     console.log(`Quiver migration completed for ${projectRoot}`);
     console.log('Missing workflow files were restored without overwriting existing project files.');
+    if (legacyLayout.hasLegacyLayout) {
+      console.log(`Legacy layout detected and preserved: ${legacyLayout.legacyPaths.join(', ')}`);
+    }
   } finally {
     fs.rmSync(tempRoot, { recursive: true, force: true });
   }
 }
 
-function runDoctor(targetDir) {
+function runDoctor(targetDir, options = {}) {
   const projectRoot = resolveTargetRoot(process.cwd(), targetDir);
 
   if (!fs.existsSync(projectRoot)) {
@@ -1192,47 +1892,53 @@ function runDoctor(targetDir) {
     throw new Error(formatError('doctor requires a project previously initialized by Quiver.\nRun init first: npx create-quiver --name "Project Name"'));
   }
 
-  const generatedSpecs = listGeneratedSpecDirs(projectRoot);
-  if (generatedSpecs.length !== 1) {
-    throw new Error(formatError(`expected exactly one generated spec directory, found ${generatedSpecs.length || 0}`));
+  const fixPlan = buildDoctorFixPlan(projectRoot);
+  if (options.fix) {
+    if (options.dryRun) {
+      console.log(formatDoctorFixPlan(fixPlan, { dryRun: true }));
+      return;
+    }
+
+    applyDoctorFixPlan(projectRoot, fixPlan);
+    console.log(formatDoctorFixPlan(fixPlan));
   }
 
-  const projectSlug = generatedSpecs[0];
-  const requiredFiles = [
+  const doctorReport = collectDoctorReport(projectRoot);
+  const specSlugs = doctorReport.specSlugs;
+  const specRequiredFiles = specSlugs.flatMap((projectSlug) => [
+    `specs/${projectSlug}/SPEC.md`,
+    `specs/${projectSlug}/STATUS.md`,
+    `specs/${projectSlug}/EVIDENCE_REPORT.md`,
+  ]);
+  const newLayoutRequiredFiles = [
     'AGENTS.md',
     'README.md',
-    'docs/INDEX.md',
     'docs/AI_CONTEXT.md',
     'docs/AI_ONBOARDING_PROMPT.md',
-    'docs/CONTEXTO.md',
+    'docs/COMMANDS.md',
     'docs/WORKFLOW.md',
-    'docs/SUPPORT_MATRIX.md',
-    'docs/TROUBLESHOOTING.md',
-    'docs/TESTING_GUIDE_FOR_AI.md',
-    'docs/ai/PRINCIPLES.md',
-    'docs/ai/RULES.yaml',
-    'docs/ai/LESSONS.md',
-    `specs/${projectSlug}/SPEC.md`,
-    `specs/${projectSlug}/STATUS.md`,
-    `specs/${projectSlug}/EVIDENCE_REPORT.md`,
     'package.json',
-    '.github/pull_request_template.md',
-    '.github/ISSUE_TEMPLATE/bug_report.md',
-    '.github/ISSUE_TEMPLATE/feature_request.md',
-    '.github/workflows/ci.yml',
-  ];
-
-  const requiredExecutables = [
-    'tools/scripts/start-slice.sh',
-    'tools/scripts/check-slice-readiness.sh',
-    'tools/scripts/check-pr-readiness.sh',
-    'tools/scripts/cleanup-slice.sh',
-    'tools/scripts/check-scope.sh',
+    '.quiver/state.json',
+    '.quiver/config.json',
+    '.quiver/.gitignore',
+    ...specRequiredFiles,
   ];
-
+  const requiredFiles = doctorReport.layout === 'legacy'
+    ? ['package.json', ...specRequiredFiles]
+    : newLayoutRequiredFiles;
+  const legacyScriptsDir = path.join(projectRoot, 'tools', 'scripts');
+  const requiredExecutables = fs.existsSync(legacyScriptsDir)
+    ? [
+        'tools/scripts/start-slice.sh',
+        'tools/scripts/check-slice-readiness.sh',
+        'tools/scripts/check-pr-readiness.sh',
+        'tools/scripts/cleanup-slice.sh',
+        'tools/scripts/check-scope.sh',
+      ]
+    : [];
   const missingFiles = assertFilesExist(projectRoot, requiredFiles);
   const nonExecutableScripts = assertExecutablesExist(projectRoot, requiredExecutables);
-  const pkg = loadPackageJson(projectRoot);
+  const pkg = fs.existsSync(path.join(projectRoot, 'package.json')) ? loadPackageJson(projectRoot) : {};
   const workflowScriptGroups = [
     { label: 'migrate', node: 'quiver:migrate', legacy: 'migrate' },
     { label: 'start-slice', node: 'quiver:start-slice', legacy: 'start:slice' },
@@ -1250,8 +1956,21 @@ function runDoctor(targetDir) {
     .map((group) => group.label);
   const missingNodeNativeScripts = ['quiver:migrate', 'quiver:analyze', 'quiver:doctor']
     .filter((name) => typeof pkg.scripts?.[name] !== 'string');
-  const hasScanArtifacts = fs.existsSync(path.join(projectRoot, 'docs', 'PROJECT_SCAN.json'))
-    && fs.existsSync(path.join(projectRoot, 'docs', 'PROJECT_MAP.md'));
+  const missingAiScripts = [
+    'quiver:ai:agent',
+    'quiver:ai:onboard',
+    'quiver:ai:plan',
+    'quiver:ai:review-plan',
+    'quiver:ai:approve',
+    'quiver:ai:prompt-slice',
+    'quiver:ai:execute-slice',
+    'quiver:ai:execute-plan',
+    'quiver:ai:pr',
+    'quiver:ai:doctor',
+  ].filter((name) => typeof pkg.scripts?.[name] !== 'string');
+  const unsupportedCreateQuiverScripts = findUnsupportedCreateQuiverScripts(pkg.scripts || {});
+  const hasScanArtifacts = hasProjectScanArtifact(projectRoot)
+    && fs.existsSync(path.join(projectRoot, PROJECT_MAP_RELATIVE_PATH));
   const quiverState = readState(projectRoot);
   const hasQuiverState = Boolean(quiverState);
   const stateWarnings = hasQuiverState ? [] : ['missing Quiver state metadata: .quiver/state.json'];
@@ -1260,24 +1979,41 @@ function runDoctor(targetDir) {
     ...nonExecutableScripts.map((file) => `missing executable bit: ${file}`),
     ...missingScripts.map((name) => `missing package.json script: ${name}`),
   ];
-  const softWarnings = collectDoctorWarnings(projectRoot);
+  const softWarnings = doctorReport.warnings;
 
   if (migrationProblems.length > 0) {
     throw new Error(formatError(`doctor failed:\n- ${migrationProblems.join('\n- ')}\n- Run migration first: npx create-quiver migrate`));
   }
 
   console.log(`Quiver doctor passed for ${projectRoot}`);
-  console.log(`Generated project slug: ${projectSlug}`);
+  console.log(`Layout: ${doctorReport.layout}`);
+  if (specSlugs.length > 0) {
+    console.log(`Specs: ${specSlugs.join(', ')}`);
+  } else {
+    console.log('Specs: none yet');
+  }
+  if (doctorReport.legacySignals.length > 0) {
+    console.log(`Legacy signals: ${doctorReport.legacySignals.join(', ')}`);
+  }
   console.log('Next steps:');
+  for (const recommendation of doctorReport.recommendations) {
+    console.log(`- ${recommendation}`);
+  }
   for (const warning of stateWarnings) {
     console.log(`- Warning: ${warning}`);
   }
   for (const scriptName of missingNodeNativeScripts) {
     console.log(`- Warning: missing Node-native script: ${scriptName}`);
   }
+  for (const scriptName of missingAiScripts) {
+    console.log(`- Warning: missing AI orchestration script: ${scriptName}`);
+  }
   if (legacyOnlyScripts.length > 0) {
     console.log(`- Warning: legacy Bash workflow scripts detected for ${legacyOnlyScripts.join(', ')}. Run npx create-quiver migrate to add quiver:* npm scripts.`);
   }
+  for (const script of unsupportedCreateQuiverScripts) {
+    console.log(`- Warning: package.json script ${script.scriptName} targets ${script.reason}: \`${script.command}\`. Update create-quiver or regenerate scripts with npx create-quiver migrate.`);
+  }
   for (const warning of softWarnings) {
     console.log(`- Warning: ${warning}`);
   }
@@ -1289,20 +2025,23 @@ function runDoctor(targetDir) {
     console.log('- Ask your AI agent: Read AGENTS.md, then docs/AI_ONBOARDING_PROMPT.md and execute it.');
   }
   console.log('- Check the next ready slice: npx create-quiver next');
-  console.log(`- Start a slice: npx create-quiver start-slice specs/${projectSlug}/slices/slice-template/slice.json`);
-  console.log(`- Validate a slice: npx create-quiver check-slice specs/${projectSlug}/slices/slice-template/slice.json`);
-  console.log(`- Validate the PR gate: npx create-quiver check-pr specs/${projectSlug}/slices/slice-template/slice.json`);
+  if (specSlugs.length > 0) {
+    const projectSlug = specSlugs[0];
+    console.log(`- Start a slice: npx create-quiver start-slice specs/${projectSlug}/slices/<slice-id>/slice.json`);
+    console.log(`- Validate a slice: npx create-quiver check-slice specs/${projectSlug}/slices/<slice-id>/slice.json`);
+    console.log(`- Validate the PR gate: npx create-quiver check-pr specs/${projectSlug}/slices/<slice-id>/slice.json`);
+  } else {
+    console.log('- Create real specs and slices only after acceptance criteria are approved and the technical plan is reviewed and approved.');
+  }
 }
 
 function printInitNextSteps(targetDir, projectName) {
-  const projectSlug = toProjectSlug(projectName);
-
   console.log('');
   console.log('Next steps:');
-  console.log(`- Review AGENTS.md, then ${path.join(targetDir, 'docs', 'INDEX.md')}`);
+  console.log(`- Review AGENTS.md, then ${path.join(targetDir, 'docs', 'AI_ONBOARDING_PROMPT.md')}`);
   console.log(`- Review ${path.join(targetDir, 'docs', 'WORKFLOW.md')}`);
-  console.log(`- Create your first slice from ${path.join(targetDir, 'specs', projectSlug, 'slices', 'slice-template', 'slice.json')}`);
-  console.log(`- Launch slice work with npx create-quiver start-slice specs/${projectSlug}/slices/slice-template/slice.json`);
+  console.log('- Analyze the project with npx create-quiver analyze');
+  console.log('- Create real specs and slices after acceptance criteria are approved and the technical plan is reviewed and approved.');
 }
 
 async function run(argv) {
@@ -1318,8 +2057,16 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'flow') {
+    await runFlow(process.cwd(), {
+      json: args.json,
+    });
+    return;
+  }
+
   if (args.mode === 'plan') {
     runPlan(process.cwd(), {
+      includeCompleted: args.includeCompleted,
       json: args.json,
       onlyReady: args.onlyReady,
       specSlug: args.specSlug,
@@ -1328,12 +2075,170 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'prepare') {
+    await runPrepare(process.cwd(), {
+      dryRun: args.dryRun,
+      identityFile: args.aiIdentityFile || undefined,
+      provider: args.prepareProvider || undefined,
+      sshHostAlias: args.aiSshHostAlias || undefined,
+    });
+    return;
+  }
+
+  if (args.mode === 'ai') {
+    if (!args.aiCommand) {
+      throw new Error(formatError('missing ai subcommand. Use: npx create-quiver ai onboard | prepare-context | plan | review-plan | approve | approvals | agent | prompt-slice | execute-slice | execute-plan | doctor | pr'));
+    }
+
+    if (args.aiCommand === 'agent') {
+      runAiAgent(process.cwd(), {
+        command: args.aiAgentCommand,
+        context: args.aiContext || undefined,
+        label: args.aiLabel || undefined,
+        model: args.aiModel || undefined,
+        provider: args.aiProviderExplicit ? args.aiProvider : undefined,
+        role: args.aiAgentRole || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'onboard') {
+      await runOnboard(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        role: args.aiRole,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'prepare-context') {
+      await runAiPrepareContext(process.cwd(), {
+        dryRun: args.dryRun,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'plan') {
+      await runAiPlan(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        phase: args.aiPhase,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        role: args.aiRole,
+        specSlug: args.specSlug || undefined,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'review-plan') {
+      await runAiReviewPlan(process.cwd(), {
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'approve') {
+      await runAiApprove(process.cwd(), {
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        phase: args.aiPhase,
+        version: args.aiVersion || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'approvals' || args.aiCommand === 'approval-status') {
+      await runAiApprovalStatus(process.cwd());
+      return;
+    }
+
+    if (args.aiCommand === 'execute-slice') {
+      await runAiExecuteSlice(process.cwd(), {
+        allowDirty: args.aiAllowDirty,
+        commit: args.aiCommit,
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        role: args.aiRole,
+        slice: args.aiSlice || undefined,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'prompt-slice' || args.aiCommand === 'executor-prompt') {
+      runAiPromptSlice(process.cwd(), {
+        slice: args.aiSlice || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'execute-plan') {
+      await runAiExecutePlan(process.cwd(), {
+        allowDirty: args.aiAllowDirty,
+        commit: args.aiCommit,
+        context: args.aiContext || undefined,
+        dryRun: args.dryRun,
+        execute: args.aiExecute,
+        json: args.json,
+        mode: args.aiExecutionMode,
+        provider: args.aiProvider,
+        providerExplicit: args.aiProviderExplicit,
+        role: args.aiRole,
+        specSlug: args.specSlug || undefined,
+        timeout: args.aiTimeout,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'doctor') {
+      await runAiDoctor(process.cwd(), {
+        dryRun: args.dryRun,
+        remote: args.aiRemote || undefined,
+        sshHostAlias: args.aiSshHostAlias || undefined,
+        identityFile: args.aiIdentityFile || undefined,
+      });
+      return;
+    }
+
+    if (args.aiCommand === 'pr') {
+      await runAiPr(process.cwd(), {
+        baseBranch: args.aiBaseBranch,
+        create: args.aiCreate,
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        remote: args.aiRemote || undefined,
+        sshHostAlias: args.aiSshHostAlias || undefined,
+        identityFile: args.aiIdentityFile || undefined,
+        title: args.aiTitle || undefined,
+      });
+      return;
+    }
+
+    throw new Error(formatError(`unsupported ai subcommand: ${args.aiCommand}. Supported tasks: onboard, plan, review-plan, approve, approvals, agent, prompt-slice, execute-slice, execute-plan, doctor, pr`));
+  }
+
   if (args.mode === 'graph') {
     runGraph(process.cwd(), {
       format: args.format,
+      includeCompleted: args.includeCompleted,
       json: args.json,
       level: args.level,
       showConflicts: args.showConflicts,
+      specSlug: args.specSlug,
       unicode: args.unicode,
     });
     return;
@@ -1343,37 +2248,66 @@ async function run(argv) {
     await runNext(process.cwd(), {
       allReady: args.allReady,
       autoStart: args.autoStart,
+      includeCompleted: args.includeCompleted,
       json: args.json,
       specSlug: args.specSlug,
     });
     return;
   }
 
+  if (args.mode === 'evidence') {
+    const result = runEvidence(process.cwd(), {
+      command: args.evidenceArgs,
+      maxOutput: args.evidenceMaxOutput || undefined,
+      output: args.evidenceOutput || undefined,
+      subcommand: args.evidenceCommand,
+    });
+    process.exitCode = result.exitCode;
+    return;
+  }
+
+  if (args.mode === 'demo') {
+    const demoTarget = resolveTargetRoot(process.cwd(), args.targetDirExplicit ? args.targetDir : 'quiver-spec-viewer');
+    runDemo({
+      command: args.demoCommand,
+      demo: args.demoName,
+      dryRun: args.dryRun,
+      targetRoot: demoTarget,
+    });
+    return;
+  }
+
   if (args.mode === 'migrate') {
     runMigrate(args.targetDir, { skipInstall: args.skipInstall });
     return;
   }
 
   if (args.mode === 'doctor') {
-    runDoctor(args.targetDir);
+    runDoctor(args.targetDir, {
+      dryRun: args.dryRun,
+      fix: args.doctorFix,
+    });
     return;
   }
 
   if (args.mode === 'start-slice') {
-    startSlice(path.resolve(process.cwd(), args.targetDir), { allowDraft: args.allowDraft });
+    startSlice(args.targetDir, { allowDraft: args.allowDraft });
     return;
   }
 
   if (args.mode === 'check-slice') {
-    checkSliceReadiness(path.resolve(process.cwd(), args.targetDir), {
+    checkSliceReadiness(args.targetDir, {
+      baseBranch: args.baseBranchExplicit ? args.aiBaseBranch : '',
       gate: args.gate,
+      local: args.checkSliceLocal,
+      remote: args.aiRemote,
       strictOverlap: args.strictOverlap,
     });
     return;
   }
 
   if (args.mode === 'check-pr') {
-    checkPrReadiness(path.resolve(process.cwd(), args.targetDir));
+    checkPrReadiness(args.targetDir);
     return;
   }
 
@@ -1397,7 +2331,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'cleanup-slice') {
-    cleanupSlice(path.resolve(process.cwd(), args.targetDir), {
+    cleanupSlice(args.targetDir, {
       closeBaseline: args.closeBaseline,
       discard: args.discard,
       dryRun: args.dryRun,
@@ -1407,7 +2341,7 @@ async function run(argv) {
   }
 
   if (args.mode === 'check-scope') {
-    checkScope(path.resolve(process.cwd(), args.targetDir), { strict: args.strict });
+    checkScope(args.targetDir, { strict: args.strict });
     return;
   }
 
@@ -1417,17 +2351,81 @@ async function run(argv) {
     return;
   }
 
+  if (args.mode === 'spec') {
+    if (args.specCommand === 'create') {
+      runCreateSpec(process.cwd(), {
+        dryRun: args.dryRun,
+        input: args.aiInput || undefined,
+        specSlug: args.specSlug || undefined,
+      });
+      return;
+    }
+
+    if (!args.targetDir || args.targetDir === '.') {
+      throw new Error(formatError('missing spec directory. Use: npx create-quiver spec <start|status|close> <spec-dir>'));
+    }
+
+    if (args.specCommand === 'start') {
+      const report = startSpecWorktree(process.cwd(), args.targetDir);
+      process.stdout.write(formatSpecStartResult(report));
+      return;
+    }
+
+    if (args.specCommand === 'status') {
+      const report = buildSpecStatus(process.cwd(), args.targetDir);
+      process.stdout.write(formatSpecStatus(report));
+      return;
+    }
+
+    if (args.specCommand === 'close') {
+      const report = closeSpecWorktree(process.cwd(), args.targetDir, {
+        baseBranch: args.aiBaseBranch,
+        discard: args.discard,
+        dryRun: args.dryRun,
+        force: args.force,
+        remote: args.aiRemote,
+      });
+      process.stdout.write(formatSpecCloseResult(report));
+      return;
+    }
+
+    throw new Error(formatError(`unsupported spec subcommand: ${args.specCommand}. Supported tasks: create, start, status, close`));
+  }
+
   const packageRoot = path.resolve(__dirname, '../..');
   const targetDir = resolveTargetRoot(process.cwd(), args.targetDir);
   const projectName = args.projectName || path.basename(targetDir) || 'Quiver Project';
+  const initLayout = buildInitLayout(targetDir, {
+    compatibilityAlias: !args.explicitInit,
+    dryRun: args.dryRun,
+    full: args.initFull,
+    includeTemplates: args.initIncludeTemplates,
+    legacyScripts: args.initLegacyScripts,
+    minimal: args.initMinimal,
+    projectName,
+    skipInstall: args.skipInstall,
+  });
+
+  if (args.dryRun) {
+    console.log(formatInitLayoutPlan(initLayout));
+    return;
+  }
+
   const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'quiver-create-'));
 
   try {
     ensureDir(targetDir);
 
     const templateRoot = packTemplate(packageRoot, tempRoot);
-    copyTemplate(templateRoot, targetDir);
-    runInitDocs(targetDir, projectName);
+    if (initLayout.profile === 'full') {
+      exportTemplatesToLegacyRoot(templateRoot, targetDir);
+    }
+    runInitDocs(targetDir, projectName, {
+      includeTemplates: args.initIncludeTemplates,
+      legacyScripts: args.initLegacyScripts,
+      profile: initLayout.profile,
+      templateRoot,
+    });
 
     if (!args.skipInstall) {
       const installResult = installSelfAsDevDep(targetDir, CLI_VERSION);
@@ -1448,6 +2446,8 @@ async function run(argv) {
 module.exports = {
   runAnalyze,
   runDoctor,
+  runFlow,
   runMigrate,
+  runPrepare,
   run,
 };