dravoice 0.1.2 → 0.1.3

package/src/index.js

@@ -1,226 +1,903 @@
-import fs from "node:fs";
-import path from "node:path";
-import {
-  prepareVoiceBenchmark,
-  renderBenchmarkReport,
-  scoreVoiceBenchmark,
-} from "./v2/benchmark.js";
-import { renderVoiceBriefV2, voiceArticleBriefV2 } from "./v2/brief.js";
-import { renderInspectV2 } from "./v2/inspect.js";
+import fs from "node:fs";
+import path from "node:path";
+import readline from "node:readline";
+import {
+  prepareVoiceBenchmark,
+  renderBenchmarkReport,
+  scoreVoiceBenchmark,
+} from "./v2/benchmark.js";
+import { renderVoiceBriefV2, voiceArticleBriefV2 } from "./v2/brief.js";
+import { renderInspectV2 } from "./v2/inspect.js";
 import { learnVoicePackV2, loadVoicePackV2 } from "./v2/profile.js";
 import { voicePromptPackV2 } from "./v2/prompt.js";
 import { renderVoiceReviewV2, reviewVoiceDraftV2 } from "./v2/review.js";
 import { renderRevisePlanV2, revisePlanDraftV2 } from "./v2/revise-plan.js";
-
-export {
-  learnVoicePackV2 as learnVoicePack,
+import { VOICE_EXTENSIONS } from "./v2/document-model.js";
+import { writeUtf8FileSafely } from "./v2/io-utils.js";
+import {
+  DEFAULT_EXAMPLES_DIR,
+  DEFAULT_PROMPT_FORMAT,
+  DEFAULT_VOICE_DIR,
+  displayPath,
+  loadProjectConfig,
+  resolveConfiguredPath,
+  writeProjectConfig,
+} from "./v2/config.js";
+
+export {
+  learnVoicePackV2 as learnVoicePack,
   loadVoicePackV2 as loadVoicePack,
   revisePlanDraftV2 as revisePlanDraft,
   reviewVoiceDraftV2 as reviewVoiceDraft,
   voicePromptPackV2 as voicePromptPack,
 };
 export { renderInspectV2, renderRevisePlanV2 as renderRevisePlan, renderVoiceReviewV2 as renderVoiceReview };
-export { renderVoiceBriefV2 as renderVoiceBrief, voiceArticleBriefV2 as voiceArticleBrief };
-export { prepareVoiceBenchmark, renderBenchmarkReport, scoreVoiceBenchmark };
-
-export async function runCli(args, io) {
-  try {
-    const [command, ...rest] = args;
-    if (!command || command === "--help" || command === "-h") {
-      io.stdout.write(helpText());
-      return 0;
-    }
-
-    if (command === "learn") {
-      const { options } = parseArgs(rest, ["examples", "out"]);
-      const profile = learnVoicePackV2({
-        examplesDir: resolvePath(io.cwd, requiredOption(options, "examples")),
-        outDir: resolvePath(io.cwd, requiredOption(options, "out")),
-      });
-      io.stdout.write(`Generated V2 voice pack from ${profile.source.documentCount} document(s). Corpus confidence: ${profile.source.confidence.band}.\n`);
-      return 0;
-    }
-
+export { renderVoiceBriefV2 as renderVoiceBrief, voiceArticleBriefV2 as voiceArticleBrief };
+export { prepareVoiceBenchmark, renderBenchmarkReport, scoreVoiceBenchmark };
+
+const INIT_DISCOVERY_DIRS = [
+  "./articles",
+  "./content",
+  "./posts",
+  "./blog",
+  "./essays",
+  "./writing",
+  "./drafts",
+  "./docs",
+];
+const SKIP_SOURCE_DIRS = new Set([".git", "node_modules", "dist", "build", "__pycache__", "prompts", "voice-pack", "dravoice-voice"]);
+
+export async function runCli(args, io) {
+  try {
+    const [command, ...rest] = args;
+    if (!command || command === "--help" || command === "-h") {
+      io.stdout.write(helpText());
+      return 0;
+    }
+
+    if (command === "help") {
+      if (rest.length === 0 || isHelpFlag(rest[0])) {
+        io.stdout.write(helpText());
+        return 0;
+      }
+      io.stdout.write(helpForTopic(rest.join(" ")));
+      return 0;
+    }
+
+    if (isHelpFlag(rest[0])) {
+      io.stdout.write(helpForTopic(command));
+      return 0;
+    }
+
+    if (command === "init") {
+      const { options, positional } = parseArgs(rest, ["examples", "out", "no-interactive"], "init", ["no-interactive"]);
+      rejectPositionals(positional, "init");
+      const config = loadProjectConfig(io.cwd);
+      const examples = options.examples ?? config.examples ?? DEFAULT_EXAMPLES_DIR;
+      const out = options.out ?? config.voice ?? DEFAULT_VOICE_DIR;
+      const interactive = shouldRunInteractiveInit(io, options);
+      if (interactive) {
+        const guided = await runInitWizard({ io, examples, out });
+        if (guided.code !== undefined) {
+          return guided.code;
+        }
+        const profile = learnWithUsageExample({
+          examplesDir: guided.resolvedExamples,
+          outDir: resolvePath(io.cwd, out),
+        }, "init");
+        writeProjectConfig(io.cwd, { voice: displayPath(out), examples: displayPath(guided.examples) });
+        writeProfileSuccess(io, {
+          action: "Initialized Dravoice voice profile",
+          profile,
+          examples: guided.examples,
+          out,
+        });
+        return 0;
+      }
+      const profile = learnWithUsageExample({
+        examplesDir: resolvePath(io.cwd, examples),
+        outDir: resolvePath(io.cwd, out),
+      }, "init");
+      writeProjectConfig(io.cwd, { voice: displayPath(out), examples: displayPath(examples) });
+      writeProfileSuccess(io, {
+        action: "Initialized Dravoice voice profile",
+        profile,
+        examples,
+        out,
+      });
+      return 0;
+    }
+
+    if (command === "learn") {
+      const { options, positional } = parseArgs(rest, ["examples", "out"], "learn");
+      rejectPositionals(positional, "learn");
+      const config = loadProjectConfig(io.cwd);
+      const examples = options.examples ?? config.examples ?? DEFAULT_EXAMPLES_DIR;
+      const out = options.out ?? config.voice ?? DEFAULT_VOICE_DIR;
+      const profile = learnWithUsageExample({
+        examplesDir: resolvePath(io.cwd, examples),
+        outDir: resolvePath(io.cwd, out),
+      }, "learn");
+      writeProjectConfig(io.cwd, { voice: displayPath(out), examples: displayPath(examples) });
+      writeProfileSuccess(io, {
+        action: "Generated V2 voice pack",
+        profile,
+        examples,
+        out,
+      });
+      return 0;
+    }
+
     if (command === "review") {
-      const { options, positional } = parseArgs(rest, ["voice", "mode", "format"]);
-      const file = positional[0];
-      if (!file) {
-        throw new Error("Missing draft file path for review");
-      }
-      const result = reviewVoiceDraftV2({
-        file: resolvePath(io.cwd, file),
-        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
-        cwd: io.cwd,
-        mode: options.mode ?? "balanced",
-      });
-      if (options.format === "json") {
-        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-      } else {
-        io.stdout.write(renderVoiceReviewV2(result));
-      }
+      const { options, positional } = parseArgs(rest, ["voice", "mode", "format"], "review");
+      rejectUnexpectedPositionals(positional, 1, "review positional");
+      const format = formatOption(options.format, ["text", "json"], "review");
+      const mode = modeOption(options.mode, "review");
+      const file = positional[0];
+      if (!file) {
+        throw usageError("Missing draft file path for review", "review");
+      }
+      const result = reviewVoiceDraftV2({
+        file: resolvePath(io.cwd, file),
+        voice: loadVoicePackV2(resolveVoicePath(io.cwd, options.voice)),
+        cwd: io.cwd,
+        mode,
+      });
+      if (format === "json") {
+        io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+      } else {
+        io.stdout.write(renderVoiceReviewV2(result));
+        io.stdout.write("Next: revise only the findings that fit the article's intent.\n");
+      }
       return result.exitCode;
     }
 
     if (command === "revise-plan") {
-      const { options, positional } = parseArgs(rest, ["voice", "format"]);
+      const { options, positional } = parseArgs(rest, ["voice", "format"], "revise-plan");
+      rejectUnexpectedPositionals(positional, 1, "revise-plan");
+      const format = formatOption(options.format, ["text", "json"], "revise-plan");
       const file = positional[0];
       if (!file) {
-        throw new Error("Missing draft file path for revise-plan");
+        throw usageError("Missing draft file path for revise-plan", "revise-plan");
       }
       const result = revisePlanDraftV2({
         file: resolvePath(io.cwd, file),
-        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
+        voice: loadVoicePackV2(resolveVoicePath(io.cwd, options.voice)),
         cwd: io.cwd,
       });
-      if (options.format === "json") {
+      if (format === "json") {
         io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
       } else {
         io.stdout.write(renderRevisePlanV2(result));
+        io.stdout.write(`Next: drav review ${file}\n`);
       }
       return 0;
     }
 
-    if (command === "prompt") {
-      const { options } = parseArgs(rest, ["voice", "format", "out"]);
-      const rendered = voicePromptPackV2({
-        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
-        format: options.format ?? "agents",
-        outPath: options.out ? resolvePath(io.cwd, options.out) : undefined,
-      });
-      if (!options.out) {
-        io.stdout.write(rendered);
-      }
-      return 0;
-    }
-
-    if (command === "brief") {
-      const { options } = parseArgs(rest, ["voice", "topic", "evidence", "format", "out"]);
-      const result = voiceArticleBriefV2({
-        voice: loadVoicePackV2(resolvePath(io.cwd, options.voice ?? ".")),
-        topic: requiredOption(options, "topic"),
-        evidence: options.evidence ? resolvePath(io.cwd, options.evidence) : undefined,
-        cwd: io.cwd,
-      });
-      const rendered = options.format === "json" ? `${JSON.stringify(result, null, 2)}\n` : renderVoiceBriefV2(result);
-      if (options.out) {
-        const outPath = resolvePath(io.cwd, options.out);
-        fs.mkdirSync(path.dirname(outPath), { recursive: true });
-        fs.writeFileSync(outPath, rendered, "utf8");
-      } else {
-        io.stdout.write(rendered);
-      }
-      return 0;
-    }
-
-    if (command === "inspect") {
-      const { options } = parseArgs(rest, ["voice"]);
-      const profile = loadVoicePackV2(resolvePath(io.cwd, options.voice ?? "."));
-      io.stdout.write(renderInspectV2(profile));
-      return 0;
-    }
-
-    if (command === "benchmark") {
-      return runBenchmarkCli(rest, io);
-    }
-
-    io.stderr.write(`Unknown command: ${command}\n`);
-    return 2;
-  } catch (error) {
-    io.stderr.write(`${error.message}\n`);
-    return 2;
-  }
-}
-
-function runBenchmarkCli(args, io) {
-  const [benchmarkCommand, ...rest] = args;
-  if (benchmarkCommand === "prepare") {
-    const { options } = parseArgs(rest, ["examples", "topic", "out", "seed"]);
-    const benchmark = prepareVoiceBenchmark({
-      examplesDir: resolvePath(io.cwd, requiredOption(options, "examples")),
-      topic: requiredOption(options, "topic"),
-      outDir: resolvePath(io.cwd, requiredOption(options, "out")),
-      seed: options.seed ?? "1",
-    });
-    io.stdout.write(`Prepared benchmark at ${resolvePath(io.cwd, requiredOption(options, "out"))} with ${benchmark.corpus.fileCount} source article(s).\n`);
-    return 0;
-  }
-
-  if (benchmarkCommand === "score") {
-    const { options } = parseArgs(rest, ["run", "judge", "format"]);
-    const result = scoreVoiceBenchmark({
-      runDir: resolvePath(io.cwd, requiredOption(options, "run")),
-      judgePath: options.judge ? resolvePath(io.cwd, options.judge) : undefined,
-    });
-    if (options.format === "json") {
-      io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
-    } else {
-      io.stdout.write(renderBenchmarkReport(result));
-    }
-    return result.exitCode;
-  }
-
-  throw new Error(`Unknown benchmark command: ${benchmarkCommand ?? ""}`.trim());
-}
-
-function parseArgs(args, allowedOptionNames) {
-  const allowed = new Set(allowedOptionNames);
-  const options = {};
-  const positional = [];
-  let parseOptions = true;
-
-  for (let index = 0; index < args.length; index += 1) {
-    const arg = args[index];
-
-    if (parseOptions && arg === "--") {
-      parseOptions = false;
-      continue;
-    }
-
-    if (!parseOptions || !arg.startsWith("--")) {
-      positional.push(arg);
-      continue;
-    }
-
-    const equalsIndex = arg.indexOf("=");
-    const key = equalsIndex === -1 ? arg.slice(2) : arg.slice(2, equalsIndex);
-    if (!allowed.has(key)) {
-      throw new Error(`Unknown option --${key}`);
-    }
-
-    const inlineValue = equalsIndex === -1 ? null : arg.slice(equalsIndex + 1);
-    const value = inlineValue ?? args[index + 1];
-    if (value === undefined || value === "" || (inlineValue === null && value.startsWith("--"))) {
-      throw new Error(`Missing value for --${key}`);
-    }
-    options[key] = value;
-    if (inlineValue === null) {
-      index += 1;
-    }
-  }
-  return { options, positional };
-}
-
-function requiredOption(options, name) {
-  if (!options[name]) {
-    throw new Error(`Missing required option --${name}`);
-  }
-  return options[name];
-}
-
-function resolvePath(cwd, value) {
-  return path.isAbsolute(value) ? value : path.join(cwd, value);
-}
-
-function helpText() {
-  return [
-    "drav learn --examples ./articles --out ./dravoice-voice",
-    "drav inspect --voice ./dravoice-voice",
-    "drav prompt --voice ./dravoice-voice --format agents --out AGENTS.md",
-    "drav brief --voice ./dravoice-voice --topic \"New topic\" --evidence notes.md --out brief.md",
-    "drav review draft.md --voice ./dravoice-voice --mode balanced --format text",
-    "drav revise-plan draft.md --voice ./dravoice-voice --format text",
-    "drav benchmark prepare --examples ./articles --topic \"New topic\" --out ./bench-run --seed 42",
-    "drav benchmark score --run ./bench-run --judge ./bench-run/judge/judgment.json",
-    "",
-  ].join("\n");
-}
+    if (command === "prompt") {
+      const { options, positional } = parseArgs(rest, ["voice", "format", "out"], "prompt");
+      rejectPositionals(positional, "prompt");
+      const promptOptions = resolvePromptOptions(io.cwd, options);
+      const format = formatOption(promptOptions.format, ["agents", "claude", "system"], "prompt");
+      const rendered = voicePromptPackV2({
+        voice: loadVoicePackV2(resolveVoicePath(io.cwd, options.voice)),
+        format,
+        outPath: promptOptions.out ? resolvePath(io.cwd, promptOptions.out) : undefined,
+      });
+      if (!promptOptions.out) {
+        io.stdout.write(rendered);
+      } else {
+        io.stdout.write(`Wrote prompt guidance to ${promptOptions.out}\n`);
+        io.stdout.write("Next: drav brief \"New topic\" --evidence notes.md --out brief.md\n");
+      }
+      return 0;
+    }
+
+    if (command === "brief") {
+      const { options, positional } = parseArgs(rest, ["voice", "topic", "evidence", "format", "out"], "brief");
+      const format = formatOption(options.format, ["text", "json"], "brief");
+      const result = voiceArticleBriefV2({
+        voice: loadVoicePackV2(resolveVoicePath(io.cwd, options.voice)),
+        topic: topicOption(options, positional, "brief"),
+        evidence: options.evidence ? resolvePath(io.cwd, options.evidence) : undefined,
+        cwd: io.cwd,
+      });
+      const rendered = format === "json" ? `${JSON.stringify(result, null, 2)}\n` : renderVoiceBriefV2(result);
+      if (options.out) {
+        const outPath = resolvePath(io.cwd, options.out);
+        fs.mkdirSync(path.dirname(outPath), { recursive: true });
+        writeUtf8FileSafely(outPath, rendered);
+        if (format !== "json") {
+          io.stdout.write(`Wrote article brief to ${options.out}\n`);
+          io.stdout.write("Next: draft from the brief, then run drav revise-plan draft.md\n");
+        }
+      } else {
+        io.stdout.write(rendered);
+      }
+      return 0;
+    }
+
+    if (command === "inspect") {
+      const { options, positional } = parseArgs(rest, ["voice"], "inspect");
+      rejectPositionals(positional, "inspect");
+      const profile = loadVoicePackV2(resolveVoicePath(io.cwd, options.voice));
+      io.stdout.write(renderInspectV2(profile));
+      io.stdout.write("Next: drav prompt --out AGENTS.md\n");
+      return 0;
+    }
+
+    if (command === "benchmark") {
+      return runBenchmarkCli(rest, io);
+    }
+
+    io.stderr.write(`${usageErrorMessage(`Unknown command: ${command}`, "help")}\n`);
+    return 2;
+  } catch (error) {
+    io.stderr.write(`${error.message}\n`);
+    return 2;
+  }
+}
+
+function runBenchmarkCli(args, io) {
+  const [benchmarkCommand, ...rest] = args;
+  if (!benchmarkCommand || isHelpFlag(benchmarkCommand)) {
+    io.stdout.write(helpForTopic("benchmark"));
+    return 0;
+  }
+
+  if (isHelpFlag(rest[0])) {
+    io.stdout.write(helpForTopic(`benchmark ${benchmarkCommand}`));
+    return 0;
+  }
+
+  if (benchmarkCommand === "prepare") {
+    const { options, positional } = parseArgs(rest, ["examples", "topic", "out", "seed"], "benchmark prepare");
+    rejectPositionals(positional, "benchmark prepare");
+    const benchmark = prepareVoiceBenchmark({
+      examplesDir: resolvePath(io.cwd, requiredOption(options, "examples", "benchmark prepare")),
+      topic: requiredOption(options, "topic", "benchmark prepare"),
+      outDir: resolvePath(io.cwd, requiredOption(options, "out", "benchmark prepare")),
+      seed: options.seed ?? "1",
+    });
+    io.stdout.write(`Prepared benchmark at ${resolvePath(io.cwd, requiredOption(options, "out", "benchmark prepare"))} with ${benchmark.corpus.fileCount} source article(s).\n`);
+    return 0;
+  }
+
+  if (benchmarkCommand === "score") {
+    const { options, positional } = parseArgs(rest, ["run", "judge", "format"], "benchmark score");
+    rejectPositionals(positional, "benchmark score");
+    const format = formatOption(options.format, ["text", "json"], "benchmark score");
+    const result = scoreVoiceBenchmark({
+      runDir: resolvePath(io.cwd, requiredOption(options, "run", "benchmark score")),
+      judgePath: options.judge ? resolvePath(io.cwd, options.judge) : undefined,
+    });
+    if (format === "json") {
+      io.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    } else {
+      io.stdout.write(renderBenchmarkReport(result));
+    }
+    return result.exitCode;
+  }
+
+  throw usageError(`Unknown benchmark command: ${benchmarkCommand ?? ""}`.trim(), "benchmark");
+}
+
+function shouldRunInteractiveInit(io, options) {
+  return !options["no-interactive"] && !options.examples && !options.out && Boolean(io.stdin?.isTTY);
+}
+
+async function runInitWizard({ io, examples, out }) {
+  const defaultExamples = examples ?? DEFAULT_EXAMPLES_DIR;
+  const defaultDisplay = displayPath(defaultExamples);
+  const defaultResolved = resolvePath(io.cwd, defaultExamples);
+  io.stdout.write([
+    "Dravoice needs your own writing before it can build a voice profile.",
+    `Current directory: ${io.cwd}`,
+    "`./articles` means an `articles` directory inside this folder.",
+    `Dravoice will write the learned profile to ${displayChildPath(out, "profile.json")} after it finds source writing.`,
+    "",
+  ].join("\n"));
+
+  const rl = readline.createInterface({
+    input: io.stdin,
+    terminal: Boolean(io.stdin?.isTTY),
+  });
+  try {
+    const defaultFiles = voiceFilesInDirectory(defaultResolved);
+    if (defaultFiles.length > 0) {
+      return await confirmSourceFiles({ io, rl, examples: defaultExamples, resolvedExamples: defaultResolved, files: defaultFiles });
+    }
+
+    const candidates = discoverLikelySourceDirectories(io.cwd, defaultExamples);
+    if (candidates.length > 0) {
+      io.stdout.write("\nFound possible writing folders:\n");
+      candidates.slice(0, 5).forEach((candidate, index) => {
+        io.stdout.write(`${index + 1}. ${displayPath(candidate.examples)} (${candidate.files.length} supported files)\n`);
+      });
+      const first = candidates[0];
+      const useCandidate = await askLine(rl, io, `Use ${displayPath(first.examples)}? [Y/n] `);
+      if (!/^n/i.test(useCandidate.trim())) {
+        return await confirmSourceFiles({
+          io,
+          rl,
+          examples: first.examples,
+          resolvedExamples: first.resolvedExamples,
+          files: first.files,
+        });
+      }
+      io.stdout.write("\n");
+    }
+
+    const answer = await askLine(rl, io, `Where is your existing writing? [${defaultDisplay}] `);
+    const selectedExamples = answer.trim() || defaultExamples;
+    const resolvedExamples = resolvePath(io.cwd, selectedExamples);
+    const selectedFiles = voiceFilesInDirectory(resolvedExamples);
+
+    if (selectedFiles.length > 0) {
+      return await confirmSourceFiles({ io, rl, examples: selectedExamples, resolvedExamples, files: selectedFiles });
+    }
+
+    if (!fs.existsSync(resolvedExamples)) {
+      const createAnswer = await askLine(rl, io, `Create ${displayPath(selectedExamples)} now? [Y/n] `);
+      if (!/^n/i.test(createAnswer.trim())) {
+        fs.mkdirSync(resolvedExamples, { recursive: true });
+        io.stdout.write(`\nCreated ${displayPath(selectedExamples)}\n`);
+        writeEmptyCorpusNextSteps(io, selectedExamples, "drav init");
+        return { code: 2 };
+      }
+    }
+
+    if (directoryHasAnyFiles(resolvedExamples)) {
+      io.stdout.write(`\n${unsupportedExamplesMessage(resolvedExamples)}\n`);
+      writeUnsupportedCorpusNextSteps(io, selectedExamples, "drav init");
+      return { code: 2 };
+    }
+
+    io.stdout.write(`\nNo Markdown, MDX, or text examples found at ${displayPath(selectedExamples)}\n`);
+    writeEmptyCorpusNextSteps(io, selectedExamples, "drav init");
+    return { code: 2 };
+  } finally {
+    rl.close();
+  }
+}
+
+async function confirmSourceFiles({ io, rl, examples, resolvedExamples, files }) {
+  io.stdout.write(`\nFound ${files.length} supported source file(s) in ${displayPath(examples)}:\n`);
+  for (const file of files.slice(0, 8)) {
+    io.stdout.write(`  - ${displayPath(path.relative(resolvedExamples, file))}\n`);
+  }
+  if (files.length > 8) {
+    io.stdout.write(`  - ...and ${files.length - 8} more\n`);
+  }
+  const confirm = await askLine(rl, io, "Build the profile from these files? [Y/n] ");
+  if (/^n/i.test(confirm.trim())) {
+    io.stdout.write(`\nNo profile written. Next: drav init --examples <directory>\n`);
+    return { code: 2 };
+  }
+  io.stdout.write("\n");
+  return { examples, resolvedExamples };
+}
+
+function askLine(rl, io, prompt) {
+  io.stdout.write(prompt);
+  return new Promise((resolve) => {
+    rl.question("", resolve);
+  });
+}
+
+function discoverLikelySourceDirectories(cwd, defaultExamples) {
+  const defaultResolved = resolvePath(cwd, defaultExamples);
+  const seen = new Set([path.resolve(defaultResolved)]);
+  const candidates = [];
+  for (const candidate of INIT_DISCOVERY_DIRS) {
+    const resolvedExamples = resolvePath(cwd, candidate);
+    const normalized = path.resolve(resolvedExamples);
+    if (seen.has(normalized)) {
+      continue;
+    }
+    seen.add(normalized);
+    const files = voiceFilesInDirectory(resolvedExamples);
+    if (files.length > 0) {
+      candidates.push({ examples: candidate, resolvedExamples, files });
+    }
+  }
+  return candidates;
+}
+
+function voiceFilesInDirectory(rootDir) {
+  if (!fs.existsSync(rootDir)) {
+    return [];
+  }
+  const rootStats = fs.statSync(rootDir);
+  if (!rootStats.isDirectory()) {
+    return [];
+  }
+  const result = [];
+  const stack = [rootDir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name));
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_SOURCE_DIRS.has(entry.name)) {
+          stack.push(fullPath);
+        }
+      } else if (entry.isFile() && VOICE_EXTENSIONS.has(path.extname(entry.name).toLowerCase())) {
+        result.push(fullPath);
+      }
+    }
+  }
+  return result.sort((left, right) => left.localeCompare(right));
+}
+
+function directoryHasAnyFiles(rootDir) {
+  if (!fs.existsSync(rootDir)) {
+    return false;
+  }
+  const rootStats = fs.statSync(rootDir);
+  if (!rootStats.isDirectory()) {
+    return false;
+  }
+  const stack = [rootDir];
+  while (stack.length) {
+    const current = stack.pop();
+    const entries = fs.readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = path.join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (!SKIP_SOURCE_DIRS.has(entry.name)) {
+          stack.push(fullPath);
+        }
+      } else if (entry.isFile()) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+function writeEmptyCorpusNextSteps(io, examples, command) {
+  const target = displayPath(examples);
+  io.stdout.write([
+    "Dravoice did not learn a profile yet.",
+    `Add at least 3 representative long-form .md, .mdx, or .txt pieces to ${target}.`,
+    `For example, copy your existing writing into \`${copyDirectoryLabel(examples)}\`.`,
+    "Five to ten pieces is better when you have them.",
+    `Next: ${command}`,
+    "",
+  ].join("\n"));
+}
+
+function writeUnsupportedCorpusNextSteps(io, examples, command) {
+  io.stdout.write([
+    "Dravoice did not learn a profile yet.",
+    "Supported extensions: .md, .mdx, .txt.",
+    `Convert or copy your writing into Markdown, MDX, or plain text in ${displayPath(examples)}.`,
+    `Next: ${command}`,
+    "",
+  ].join("\n"));
+}
+
+function writeProfileSuccess(io, { action, profile, examples, out }) {
+  io.stdout.write(`${action}.\n`);
+  io.stdout.write(`Source: ${displayPath(examples)}\n`);
+  io.stdout.write(`Profile: ${displayChildPath(out, "profile.json")}\n`);
+  io.stdout.write("Config: .dravoice.yml\n");
+  io.stdout.write(`Documents: ${profile.source.documentCount}\n`);
+  io.stdout.write(`Words: ${profile.source.wordCount}\n`);
+  io.stdout.write(`Confidence: ${profile.source.confidence.band} - ${profile.source.confidence.message}\n`);
+  if (profile.source.documentCount < 3) {
+    const remaining = 3 - profile.source.documentCount;
+    io.stdout.write(`Warning: add at least ${remaining} more representative long-form piece(s) when you can.\n`);
+  }
+  io.stdout.write("Next: drav inspect\n");
+}
+
+function displayChildPath(base, child) {
+  const normalized = displayPath(base).replace(/\/+$/, "");
+  return `${normalized}/${child}`;
+}
+
+function copyDirectoryLabel(value) {
+  const normalized = displayPath(value).replace(/\/+$/, "");
+  if (normalized === "./articles" || normalized === "articles") {
+    return "articles/";
+  }
+  return `${normalized}/`;
+}
+
+function parseArgs(args, allowedOptionNames, topic, booleanOptionNames = []) {
+  const allowed = new Set(allowedOptionNames);
+  const booleans = new Set(booleanOptionNames);
+  const options = {};
+  const positional = [];
+  let parseOptions = true;
+
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+
+    if (parseOptions && arg === "--") {
+      parseOptions = false;
+      continue;
+    }
+
+    if (!parseOptions || !arg.startsWith("--")) {
+      positional.push(arg);
+      continue;
+    }
+
+    const equalsIndex = arg.indexOf("=");
+    const key = equalsIndex === -1 ? arg.slice(2) : arg.slice(2, equalsIndex);
+    if (!allowed.has(key)) {
+      throw usageError(`Unknown option --${key}`, topic);
+    }
+
+    const inlineValue = equalsIndex === -1 ? null : arg.slice(equalsIndex + 1);
+    if (booleans.has(key)) {
+      if (inlineValue !== null) {
+        throw usageError(`Option --${key} does not take a value`, topic);
+      }
+      options[key] = true;
+      continue;
+    }
+
+    const value = inlineValue ?? args[index + 1];
+    if (value === undefined || value === "" || (inlineValue === null && value.startsWith("--"))) {
+      throw usageError(`Missing value for --${key}`, topic);
+    }
+    options[key] = value;
+    if (inlineValue === null) {
+      index += 1;
+    }
+  }
+  return { options, positional };
+}
+
+function requiredOption(options, name, topic) {
+  if (!options[name]) {
+    throw usageError(`Missing required option --${name}`, topic);
+  }
+  return options[name];
+}
+
+function learnWithUsageExample(settings, topic) {
+  try {
+    return learnVoicePackV2(settings);
+  } catch (error) {
+    throw usageError(actionableCorpusError(error.message, topic, settings.examplesDir), topic);
+  }
+}
+
+function actionableCorpusError(message, topic, examplesDir) {
+  if (!/^No Markdown, MDX, or text examples found/.test(message)) {
+    return message;
+  }
+  const command = topic === "learn" ? "drav learn" : "drav init";
+  const elsewhereCommand = topic === "learn"
+    ? "drav learn --examples ~/path/to/writing --out ./dravoice-voice"
+    : "drav init --examples ~/path/to/writing";
+  if (directoryHasAnyFiles(examplesDir)) {
+    return [
+      unsupportedExamplesMessage(examplesDir),
+      "",
+      "Supported extensions: .md, .mdx, .txt.",
+      "Convert or copy your writing into Markdown, MDX, or plain text.",
+      "",
+      "If your writing already lives somewhere else:",
+      `  ${elsewhereCommand}`,
+      "",
+      `Next: ${command}`,
+    ].join("\n");
+  }
+  return [
+    message,
+    "",
+    "Start here:",
+    "  mkdir -p articles",
+    "  # copy your existing writing into `articles/`",
+    `  ${command}`,
+    "",
+    "If your writing already lives somewhere else:",
+    `  ${elsewhereCommand}`,
+    "",
+    `Next: ${command}`,
+  ].join("\n");
+}
+
+function unsupportedExamplesMessage(examplesDir) {
+  return `Found files in ${displayPath(examplesDir)}, but none are supported voice examples.`;
+}
+
+function topicOption(options, positional, topic) {
+  if (positional.length > 1) {
+    throw usageError(`Unexpected positional argument: ${positional[1]}`, topic);
+  }
+  if (options.topic && positional[0]) {
+    throw usageError("Use either positional topic or --topic, not both", topic);
+  }
+  return options.topic ?? positional[0] ?? requiredOption(options, "topic", topic);
+}
+
+function formatOption(value, allowed, topic) {
+  const format = value ?? "text";
+  if (!allowed.includes(format)) {
+    throw usageError(`Unsupported --format ${format}. Expected ${allowed.join(" or ")}.`, topic);
+  }
+  return format;
+}
+
+function modeOption(value, topic) {
+  const mode = value ?? "balanced";
+  if (!["loose", "balanced", "strict"].includes(mode)) {
+    throw usageError(`Unsupported --mode ${mode}. Expected loose, balanced, or strict.`, topic);
+  }
+  return mode;
+}
+
+function rejectUnexpectedPositionals(positional, count, topic) {
+  if (positional.length > count) {
+    throw usageError(`Unexpected positional argument: ${positional[count]}`, topic);
+  }
+}
+
+function rejectPositionals(positional, topic) {
+  rejectUnexpectedPositionals(positional, 0, topic);
+}
+
+function resolvePath(cwd, value) {
+  return path.isAbsolute(value) ? value : path.join(cwd, value);
+}
+
+function resolveVoicePath(cwd, optionValue) {
+  if (optionValue) {
+    return resolvePath(cwd, optionValue);
+  }
+  const config = loadProjectConfig(cwd);
+  const configured = resolveConfiguredPath(cwd, config.voice);
+  if (configured) {
+    return configured;
+  }
+  const conventional = path.join(cwd, DEFAULT_VOICE_DIR);
+  if (fs.existsSync(path.join(conventional, "profile.json"))) {
+    return conventional;
+  }
+  return cwd;
+}
+
+function resolvePromptOptions(cwd, options) {
+  const config = loadProjectConfig(cwd);
+  return {
+    format: options.format ?? config.promptFormat ?? DEFAULT_PROMPT_FORMAT,
+    out: options.out ?? (options.voice ? undefined : config.promptOut) ?? undefined,
+  };
+}
+
+function isHelpFlag(value) {
+  return value === "--help" || value === "-h";
+}
+
+function usageError(message, topic) {
+  return new Error(usageErrorMessage(message, topic));
+}
+
+function usageErrorMessage(message, topic) {
+  const example = {
+    init: "drav init --examples ./articles --out ./dravoice-voice",
+    "review positional": "drav review draft.md",
+  }[topic] ?? EXAMPLES[topic];
+  return example ? `${message}\nExample: ${example}` : message;
+}
+
+function helpText() {
+  return [
+    "Dravoice - local-first voice guidance for writers",
+    "",
+    "First run:",
+    "1. Initialize your voice profile",
+    "   drav init",
+    "2. Inspect the profile before trusting it",
+    "   drav inspect",
+    "3. Generate reusable drafting guidance",
+    "   drav prompt --out AGENTS.md",
+    "4. Plan a grounded draft from evidence",
+    "   drav brief \"New topic\" --evidence notes.md --out brief.md",
+    "5. Revise, then review",
+    "   drav revise-plan draft.md",
+    "   drav review draft.md",
+    "",
+    "Commands:",
+    "  init           Learn a profile and save project defaults in one first-run command.",
+    "  learn          Build a local voice profile from Markdown, MDX, or text examples.",
+    "  inspect        Show the learned profile in plain language.",
+    "  prompt         Render reusable LLM drafting guidance.",
+    "  brief          Create an evidence-first article brief.",
+    "  revise-plan    Rank human-editable revision actions.",
+    "  review         Compare a draft against the voice profile.",
+    "",
+    "Advanced:",
+    "  drav review draft.md --mode strict --format json",
+    "  drav benchmark prepare --examples ./articles --topic \"New topic\" --out ./bench-run --seed 42",
+    "",
+    "Run `drav help init` for command-specific help.",
+    "",
+  ].join("\n");
+}
+
+function helpForTopic(topic) {
+  const normalized = String(topic ?? "").trim();
+  const text = HELP_TOPICS[normalized];
+  if (!text) {
+    throw usageError(`Unknown command: ${normalized}`, "help");
+  }
+  return text;
+}
+
+const EXAMPLES = {
+  help: "drav help init",
+  init: "drav init",
+  learn: "drav learn --examples ./articles --out ./dravoice-voice",
+  inspect: "drav inspect",
+  prompt: "drav prompt --out AGENTS.md",
+  brief: "drav brief \"New topic\" --evidence notes.md --out brief.md",
+  "revise-plan": "drav revise-plan draft.md",
+  review: "drav review draft.md --format json",
+  benchmark: "drav benchmark prepare --examples ./articles --topic \"New topic\" --out ./bench-run --seed 42",
+  "benchmark prepare": "drav benchmark prepare --examples ./articles --topic \"New topic\" --out ./bench-run --seed 42",
+  "benchmark score": "drav benchmark score --run ./bench-run --judge ./bench-run/judge/judgment.json",
+};
+
+const HELP_TOPICS = {
+  init: [
+    "Usage: drav init [--examples ./articles] [--out ./dravoice-voice] [--no-interactive]",
+    "",
+    "What it does:",
+    "Guides first-time setup, builds a voice profile, and writes .dravoice.yml project defaults.",
+    "",
+    "Options:",
+    "  --examples <dir>   Directory with representative long-form pieces. Defaults to ./articles.",
+    "  --out <dir>        Directory where Dravoice writes profile.json and metadata. Defaults to ./dravoice-voice.",
+    "  --no-interactive   Do not prompt when ./articles is missing.",
+    "",
+    "First run:",
+    "  mkdir -p articles",
+    "  # copy at least 3 .md, .mdx, or .txt pieces into articles/",
+    "  drav init",
+    "",
+    "Interactive init previews supported files before learning. If ./articles",
+    "is missing, it can suggest ./content, ./posts, ./blog, ./essays, and other common folders.",
+    "",
+    `Example: ${EXAMPLES.init}`,
+    "Next: drav inspect",
+    "",
+  ].join("\n"),
+  learn: [
+    "Usage: drav learn [--examples ./articles] [--out ./dravoice-voice]",
+    "",
+    "What it does:",
+    "Builds a local schemaVersion 2 voice profile from Markdown, MDX, and plain-text examples.",
+    "",
+    "Options:",
+    "  --examples <dir>   Directory with at least 3 representative long-form pieces.",
+    "  --out <dir>        Directory where Dravoice writes profile.json and metadata.",
+    "",
+    `Example: ${EXAMPLES.learn}`,
+    "Next: drav inspect",
+    "",
+  ].join("\n"),
+  inspect: [
+    "Usage: drav inspect [--voice ./dravoice-voice]",
+    "",
+    "What it does:",
+    "Shows corpus confidence, feature families, revision handles, and drafting guidance in plain language.",
+    "",
+    "Options:",
+    "  --voice <dir>   Voice profile directory. Defaults to .dravoice.yml,",
+    "                  ./dravoice-voice, then current directory.",
+    "",
+    `Example: ${EXAMPLES.inspect}`,
+    "Next: drav prompt --out AGENTS.md",
+    "",
+  ].join("\n"),
+  prompt: [
+    "Usage: drav prompt [--voice ./dravoice-voice] [--format agents] [--out AGENTS.md]",
+    "",
+    "What it does:",
+    "Turns high-confidence profile observations into reusable drafting guidance for an LLM or writing agent.",
+    "",
+    "Options:",
+    "  --voice <dir>       Voice profile directory. Defaults to .dravoice.yml,",
+    "                      ./dravoice-voice, then current directory.",
+    "  --format <format>   agents, claude, or system. Defaults to agents.",
+    "  --out <file>        Write guidance to a file instead of stdout.",
+    "",
+    `Example: ${EXAMPLES.prompt}`,
+    "Next: drav brief \"New topic\" --evidence notes.md --out brief.md",
+    "",
+  ].join("\n"),
+  brief: [
+    "Usage: drav brief \"New topic\" [--voice ./dravoice-voice] [--evidence notes.md] [--out brief.md]",
+    "",
+    "What it does:",
+    "Creates an evidence-first article brief that keeps broad claims close to supplied notes, dates, quotes, and examples.",
+    "",
+    "Required input:",
+    "  topic               Target article topic, passed positionally or with --topic.",
+    "",
+    "Options:",
+    "  --voice <dir>       Voice profile directory. Defaults to .dravoice.yml,",
+    "                      ./dravoice-voice, then current directory.",
+    "  --topic <text>      Alternative to positional topic.",
+    "  --evidence <file>   Notes file used to extract concrete evidence anchors.",
+    "  --format <format>   text or json. Defaults to text.",
+    "  --out <file>        Write the brief to a file instead of stdout.",
+    "",
+    `Example: ${EXAMPLES.brief}`,
+    "Next: draft from the brief, then run drav revise-plan draft.md",
+    "",
+  ].join("\n"),
+  "revise-plan": [
+    "Usage: drav revise-plan draft.md [--voice ./dravoice-voice]",
+    "",
+    "What it does:",
+    "Ranks calibrated, human-editable revision actions. It does not rewrite the draft or claim AI detection.",
+    "",
+    "Options:",
+    "  --voice <dir>       Voice profile directory. Defaults to .dravoice.yml,",
+    "                      ./dravoice-voice, then current directory.",
+    "  --format <format>   text or json. Defaults to text.",
+    "",
+    `Example: ${EXAMPLES["revise-plan"]}`,
+    "Next: drav review draft.md",
+    "",
+  ].join("\n"),
+  review: [
+    "Usage: drav review draft.md [--voice ./dravoice-voice]",
+    "",
+    "What it does:",
+    "Compares a draft with the profile and reports family-level drift. It is revision guidance, not AI detection.",
+    "",
+    "Options:",
+    "  --voice <dir>       Voice profile directory. Defaults to .dravoice.yml,",
+    "                      ./dravoice-voice, then current directory.",
+    "  --mode <mode>       loose, balanced, or strict. Defaults to balanced.",
+    "  --format <format>   text or json. Defaults to text.",
+    "",
+    "Automation example:",
+    "  drav review draft.md --voice ./dravoice-voice --mode strict --format json",
+    "",
+    `Example: ${EXAMPLES.review}`,
+    "Next: revise only the findings that fit the article's intent.",
+    "",
+  ].join("\n"),
+  benchmark: [
+    "Usage: drav benchmark <prepare|score> ...",
+    "",
+    "What it does:",
+    "Runs validation workflows for Dravoice development. Most writers do not need this for first use.",
+    "",
+    "Examples:",
+    `  ${EXAMPLES["benchmark prepare"]}`,
+    `  ${EXAMPLES["benchmark score"]}`,
+    "",
+  ].join("\n"),
+  "benchmark prepare": [
+    "Usage: drav benchmark prepare --examples ./articles --topic \"New topic\" --out ./bench-run --seed 42",
+    "",
+    "What it does:",
+    "Creates a local benchmark run directory from a source corpus and topic.",
+    "",
+    `Example: ${EXAMPLES["benchmark prepare"]}`,
+    "Next: fill benchmark drafts, then run drav benchmark score --run ./bench-run --judge ./bench-run/judge/judgment.json",
+    "",
+  ].join("\n"),
+  "benchmark score": [
+    "Usage: drav benchmark score --run ./bench-run --judge ./bench-run/judge/judgment.json",
+    "",
+    "What it does:",
+    "Scores a prepared benchmark run using the V2 profile and review diagnostics.",
+    "",
+    `Example: ${EXAMPLES["benchmark score"]}`,
+    "",
+  ].join("\n"),
+};