open-classify 0.9.2 → 1.0.0

package/bin/open-classify.mjs

@@ -1,177 +1,69 @@
 #!/usr/bin/env node
-// open-classify CLI. Subcommands: init, uninstall, doctor, try.
+// open-classify CLI.
 //
-// init: scaffold the standard project layout for a consumer.
-// uninstall: remove the files created by init.
-// doctor: verify the install, config, Ollama, and classifiers are all working.
-// try: run the pipeline against a single message and print the result.
+//   init               Copy the scaffold (open-classify/) into the current directory.
+//   eject <name>       Copy a stock classifier into open-classify/classifiers/<name>/.
+//   doctor             Verify install, config, Ollama, and classifiers.
+//   try <message>      Run the pipeline against a single message.
+//
+// Removal is intentionally not a subcommand — `rm -rf open-classify/` and
+// `npm uninstall open-classify` cover it, and bundling them creates more
+// confusion than convenience (notably the npx "needs to install" prompt
+// when the package isn't a dep yet).
 
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs";
 import { createInterface } from "node:readline";
-import { basename, dirname, join, relative, resolve } from "node:path";
+import { dirname, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-import { spawnSync } from "node:child_process";
 
 const SCRIPT_DIR = dirname(fileURLToPath(import.meta.url));
 const PACKAGE_ROOT = resolve(SCRIPT_DIR, "..");
-const TEMPLATES_DIR = join(PACKAGE_ROOT, "templates");
-const DOWNSTREAM_MODELS_FILENAME = "downstream-models.json";
-const DOWNSTREAM_MODELS_PATH = join(PACKAGE_ROOT, DOWNSTREAM_MODELS_FILENAME);
-
-const TEMPLATE_NAMES = ["conversation_digest", "context_shift", "memory_retrieval_queries", "tools"];
-const STOCK_CONFIG = {
-  tools: false,
-  memory_retrieval_queries: false,
-  conversation_digest: false,
-  context_shift: false,
-};
-
-const TEMPLATE_DESCRIPTIONS = {
-  conversation_digest: "rolling summary of recent turns",
-  context_shift: "detects topic changes",
-  memory_retrieval_queries: "generates queries for a memory store",
-  tools: "tool-call routing",
-};
-
-const CLASSIFIERS_README = `# classifiers/
-
-Each classifier is a folder with two files:
-
-- \`manifest.json\` — declares the output shape and fallback
-- \`prompt.md\` — the classification instructions
-
-The loader skips any folder whose name starts with \`_\`. That's how the
-four \`_<name>/\` templates here stay inactive until you opt in: drop the
-underscore (\`mv _tools tools\`) and the classifier runs on the next start.
-
-Each template mirrors a package-owned stock classifier. You have two ways
-to use them:
-
-1. **Enable in place** — set \`classifiers.stock.<name>: true\` in
-   \`open-classify.config.json\`. The package-owned version runs and is
-   updated by \`npm update open-classify\`.
-2. **Customize a local copy** — keep the stock toggle off, drop the
-   underscore on the template here, and edit \`prompt.md\` /
-   \`manifest.json\` to taste.
-
-To write your own classifier, drop a new \`<name>/\` folder here with its
-own \`manifest.json\` and \`prompt.md\`. The folder name must match the
-manifest's \`name\` field. See the
-[author guide](https://github.com/taylorbayouth/open-classify/blob/main/docs/adding-a-classifier.md).
-`;
-
-const DEFAULT_CONFIG = {
-  runner: {
-    provider: "ollama",
-    host: "http://127.0.0.1:11434",
-    defaultModel: "gemma4:e4b-it-q4_K_M",
-  },
-  catalog: DOWNSTREAM_MODELS_FILENAME,
-  classifiers: {
-    dirs: ["classifiers"],
-    stock: STOCK_CONFIG,
-  },
-};
-
-function configForInit({ minimal }) {
-  if (!minimal) return DEFAULT_CONFIG;
-  return {
-    ...DEFAULT_CONFIG,
-    classifiers: {
-      stock: STOCK_CONFIG,
-    },
-  };
-}
+const SCAFFOLD_DIR = join(PACKAGE_ROOT, "templates", "scaffold", "open-classify");
+const STOCK_DIR = join(PACKAGE_ROOT, "templates", "stock");
+const PROJECT_DIRNAME = "open-classify";
+const STOCK_NAMES = ["tools", "memory_retrieval_queries", "conversation_digest", "context_shift"];
 
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
 
 async function main() {
-  const args = process.argv.slice(2);
-  const subcommand = args[0];
+  const [subcommand, ...rest] = process.argv.slice(2);
 
   if (!subcommand || subcommand === "-h" || subcommand === "--help") {
     printHelp();
     process.exit(subcommand ? 0 : 1);
   }
 
-  if (subcommand === "init") {
-    const flags = parseInitFlags(args.slice(1));
-    await runInit({ cwd: process.cwd(), ...flags });
-    return;
-  }
-
-  if (subcommand === "uninstall") {
-    const flags = parseUninstallFlags(args.slice(1));
-    await runUninstall({ cwd: process.cwd(), ...flags });
-    return;
-  }
-
-  if (subcommand === "doctor") {
-    await runDoctor({ cwd: process.cwd() });
-    return;
-  }
-
-  if (subcommand === "try") {
-    const message = args.slice(1).join(" ");
-    await runTry({ cwd: process.cwd(), message });
-    return;
+  switch (subcommand) {
+    case "init":
+      await runInit({ cwd: process.cwd(), ...parseFlags(rest) });
+      return;
+    case "eject":
+      await runEject({ cwd: process.cwd(), name: rest[0], ...parseFlags(rest.slice(1)) });
+      return;
+    case "doctor":
+      await runDoctor({ cwd: process.cwd() });
+      return;
+    case "try": {
+      const message = rest.join(" ");
+      await runTry({ cwd: process.cwd(), message });
+      return;
+    }
+    default:
+      process.stderr.write(`Unknown subcommand: ${subcommand}\n\n`);
+      printHelp();
+      process.exit(1);
   }
-
-  console.error(`Unknown subcommand: ${subcommand}`);
-  printHelp();
-  process.exit(1);
 }
 
-// ---------------------------------------------------------------------------
-// Shared helpers
-// ---------------------------------------------------------------------------
-
-function parseInitFlags(args) {
-  const flags = {
-    yes: false,
-    minimal: false,
-    dryRun: false,
-    force: false,
-    noInstall: false,
-    packageManager: null,
-    classifierDir: "classifiers",
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
+function parseFlags(args) {
+  const flags = { yes: false, force: false, dryRun: false };
+  for (const arg of args) {
     if (arg === "--yes" || arg === "-y") flags.yes = true;
-    else if (arg === "--minimal") flags.minimal = true;
-    else if (arg === "--dry-run") flags.dryRun = true;
     else if (arg === "--force") flags.force = true;
-    else if (arg === "--no-install") flags.noInstall = true;
-    else if (arg === "--package-manager" && args[i + 1]) flags.packageManager = args[++i];
-    else if (arg.startsWith("--package-manager=")) flags.packageManager = arg.split("=")[1];
-    else if (arg === "--classifier-dir" && args[i + 1]) flags.classifierDir = args[++i];
-    else if (arg.startsWith("--classifier-dir=")) flags.classifierDir = arg.split("=")[1];
-  }
-
-  return flags;
-}
-
-function parseUninstallFlags(args) {
-  const flags = {
-    yes: false,
-    dryRun: false,
-    force: false,
-    classifierDir: "classifiers",
-  };
-
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "--yes" || arg === "-y") flags.yes = true;
     else if (arg === "--dry-run") flags.dryRun = true;
-    else if (arg === "--force") flags.force = true;
-    else if (arg === "--classifier-dir" && args[i + 1]) flags.classifierDir = args[++i];
-    else if (arg.startsWith("--classifier-dir=")) flags.classifierDir = arg.split("=")[1];
   }
-
   return flags;
 }
 
@@ -179,161 +71,69 @@ function printHelp() {
   process.stdout.write(`open-classify — runtime CLI
 
 Commands:
-  init [options]    Scaffold open-classify.config.json and classifiers/ in the
-                    current directory. Re-run safe: existing files are skipped.
-
-  uninstall         Remove open-classify scaffold files from the current
-                    directory. Use --force to remove the whole classifiers/
-                    directory, including active/custom classifiers.
-
-  doctor            Check that the install, config, Ollama, and classifiers are
-                    all working. Exits non-zero on failure.
-
-  try <message>     Run the pipeline against a single message and print the
-                    result. Useful for verifying your setup without touching
-                    application code.
-
-Options for init:
-  --minimal              Write runtime config/catalog only; skip classifiers/
-  --dry-run              Preview what would be created; don't write anything
-  --force                Overwrite existing files without prompting
-  --no-install           Skip the "add to package.json" prompt
-  --package-manager <m>  npm | pnpm | yarn | bun  (default: auto-detect)
-  --classifier-dir <p>   Directory for classifiers  (default: ./classifiers)
-  --yes, -y              Accept all prompts (CI mode)
-
-Options for uninstall:
-  --dry-run              Preview what would be removed; don't delete anything
-  --force                Remove the whole classifiers/ directory
-  --classifier-dir <p>   Directory for classifiers  (default: ./classifiers)
-  --yes, -y              Accept all prompts (CI mode)
+  init                Scaffold ./open-classify/ in the current directory.
+                      Re-run safe: existing files are skipped unless --force.
 
-`);
-}
+  eject <name>        Copy a stock classifier into ./open-classify/classifiers/<name>/
+                      so you can edit it. Stock classifiers:
+                      ${STOCK_NAMES.join(", ")}
 
-function detectPackageManager(cwd) {
-  if (existsSync(join(cwd, "pnpm-lock.yaml"))) return "pnpm";
-  if (existsSync(join(cwd, "yarn.lock"))) return "yarn";
-  if (existsSync(join(cwd, "bun.lockb"))) return "bun";
-  return "npm";
-}
+  doctor              Verify install, config, Ollama, and classifiers.
+                      Exits non-zero on failure.
 
-function isOpenClassifyDep(pkg) {
-  return ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"].some(
-    (f) => pkg[f]?.["open-classify"],
-  );
-}
+  try <message>       Run the pipeline against a single message and print
+                      the result.
 
-function getCliVersion() {
-  try {
-    return JSON.parse(readFileSync(join(PACKAGE_ROOT, "package.json"), "utf8")).version;
-  } catch {
-    return null;
-  }
+Options:
+  --yes, -y           Accept all prompts (CI mode)
+  --force             Overwrite existing files
+  --dry-run           Preview what would change; don't write anything
+
+Setup:
+  npm install open-classify
+  npx open-classify init
+
+Removal:
+  rm -rf open-classify/
+  npm uninstall open-classify
+
+Docs:  https://github.com/taylorbayouth/open-classify#readme
+`);
 }
 
 // ---------------------------------------------------------------------------
 // init
 // ---------------------------------------------------------------------------
 
-async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageManager, classifierDir }) {
-  // 1. Preflight: require a host project.
-  const pkgPath = join(cwd, "package.json");
-  if (!existsSync(pkgPath)) {
-    process.stderr.write(
-      `✖  No package.json found in ${cwd}.\n` +
-      `   open-classify scaffolds code that imports the library, so it needs a\n` +
-      `   Node project to live in.\n\n` +
-      `   Create one first:  npm init -y\n`,
-    );
-    process.exit(1);
-  }
+async function runInit({ cwd, yes, force, dryRun }) {
+  requireHostProject(cwd);
+  warnIfPackageMissing(cwd);
 
-  let pkg;
-  try {
-    pkg = JSON.parse(readFileSync(pkgPath, "utf8"));
-  } catch {
-    process.stderr.write(`✖  Could not parse package.json at ${pkgPath}\n`);
-    process.exit(1);
-  }
+  const destRoot = join(cwd, PROJECT_DIRNAME);
+  const plan = planScaffoldCopy(SCAFFOLD_DIR, destRoot, cwd, force);
 
-  // 2. Offer to install if not yet a dependency (skip in --yes / --no-install mode).
-  let installedNow = false;
-  if (!isOpenClassifyDep(pkg) && !noInstall && !yes) {
-    process.stdout.write(`ℹ  open-classify is not yet a dependency of this project.\n\n`);
-    const doInstall = await confirm("? Add open-classify to package.json and install it now? (Y/n) ", true);
-    if (doInstall) {
-      const pm = packageManager || detectPackageManager(cwd);
-      const installCmd = pm === "npm" ? ["install", "open-classify"] : ["add", "open-classify"];
-      process.stdout.write(`\n  Running: ${pm} ${installCmd.join(" ")}\n\n`);
-      const result = spawnSync(pm, installCmd, { cwd, stdio: "inherit" });
-      if (result.status !== 0) {
-        process.stderr.write(`\n✖  Install failed. Run manually: ${pm} ${installCmd.join(" ")}\n`);
-        process.exit(1);
-      }
-      installedNow = true;
-      process.stdout.write("\n");
-    } else {
-      process.stdout.write(
-        `  Skipped. You'll need to run \`npm install open-classify\` before importing.\n\n`,
-      );
-    }
-  }
-
-  // 3. Plan.
-  const resolvedClassifierDir = resolve(cwd, classifierDir);
-  const config = configForInit({ minimal });
-  const wrote = { config: false, catalog: false, readme: false, templateCount: 0 };
-  let plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force, wrote, config });
-
-  // Nothing to do.
-  if (plan.toCreate.length === 0) {
-    process.stdout.write("Nothing to do — your project already has all the scaffolded files.\n");
-    if (plan.toSkip.length > 0) {
-      process.stdout.write("\nAlready in place:\n");
-      for (const p of plan.toSkip) process.stdout.write(`  ${p}\n`);
+  if (plan.actions.length === 0) {
+    process.stdout.write(`Nothing to do — ./${PROJECT_DIRNAME}/ already has every scaffold file.\n`);
+    if (plan.skipped.length > 0) {
+      process.stdout.write("\nAlready present (use --force to overwrite):\n");
+      for (const p of plan.skipped) process.stdout.write(`  ${p}\n`);
     }
     return;
   }
 
-  // 4. Preview.
   process.stdout.write(`\nThe following will be created in ${cwd}:\n\n`);
-  for (const item of plan.preview) {
-    if (item.isGroupHeader) {
-      process.stdout.write(`  ${item.label}\n`);
-    } else if (item.indent) {
-      process.stdout.write(`    ${item.label.padEnd(32)}  ${item.description}\n`);
-    } else {
-      process.stdout.write(`  ${item.label.padEnd(34)}  ${item.description}\n`);
-    }
-  }
+  for (const item of plan.preview) process.stdout.write(`  ${item}\n`);
 
-  if (plan.toSkip.length > 0) {
-    process.stdout.write(`\n⚠  These files already exist and will be skipped:\n`);
-    for (const p of plan.toSkip) process.stdout.write(`     ${p}\n`);
+  if (plan.skipped.length > 0) {
+    process.stdout.write(`\nAlready present (use --force to overwrite):\n`);
+    for (const p of plan.skipped) process.stdout.write(`  ${p}\n`);
   }
 
-  // 5. Stop here on --dry-run.
   if (dryRun) {
     process.stdout.write("\n(dry run — nothing written)\n");
     return;
   }
 
-  // 6. Conflict handling: interactive only (not --yes, not --force).
-  if (plan.toSkip.length > 0 && !yes && !force) {
-    const choice = await promptConflict();
-    if (choice === "diff") {
-      showDiffs(plan.toSkip, cwd, resolvedClassifierDir, config);
-      const choice2 = await promptConflict();
-      if (choice2 === "y") {
-        plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force: true, wrote, config });
-      }
-    } else if (choice === "y") {
-      plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force: true, wrote, config });
-    }
-  }
-
-  // 7. Confirm (skip in --yes mode).
   if (!yes) {
     const proceed = await confirm("\n? Continue? (Y/n) ", true);
     if (!proceed) {
@@ -342,235 +142,116 @@ async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageMan
     }
   }
 
-  // 8. Execute.
   process.stdout.write("\n");
   for (const action of plan.actions) action();
 
-  // 9. Summary + next steps.
-  process.stdout.write("\n");
-  if (installedNow) {
-    const v = getCliVersion();
-    process.stdout.write(`✓ open-classify installed${v ? ` (v${v})` : ""}\n`);
-  }
-  if (wrote.config) process.stdout.write("✓ wrote open-classify.config.json\n");
-  if (wrote.catalog) process.stdout.write(`✓ wrote ${DOWNSTREAM_MODELS_FILENAME}\n`);
-  if (wrote.readme || wrote.templateCount > 0) {
-    const classifierDirRel = relative(cwd, resolvedClassifierDir);
-    if (wrote.templateCount > 0) {
-      process.stdout.write(`✓ scaffolded ${wrote.templateCount} classifier(s) in ./${classifierDirRel}/\n`);
-    } else {
-      process.stdout.write(`✓ wrote ./${classifierDirRel}/README.md\n`);
-    }
-  }
-
+  const cfg = readScaffoldConfig();
   process.stdout.write(`
 Next steps:
 
   1. Pull the default classifier model:
-
-       ollama pull ${config.runner.defaultModel}
+       ollama pull ${cfg.runner.defaultModel}
 
   2. Verify everything is wired up:
-
        npx open-classify doctor
 
-  3. Try it without writing any code:
-
+  3. Try it without writing code:
        npx open-classify try "hello"
 
   4. Use it from your code:
-
        import { createClassifier } from "open-classify";
        const { classify } = createClassifier();
-       const result = await classify({
-         messages: [{ role: "user", text: "hello" }],
-       });
 
-     The factory finds open-classify.config.json in your working
-     directory and wires in the classifiers/ folder automatically.
+     createClassifier() finds ./${PROJECT_DIRNAME}/config.json and wires
+     in ./${PROJECT_DIRNAME}/classifiers/ automatically.
 
 Docs:  https://github.com/taylorbayouth/open-classify#readme
 `);
 }
 
-function planInit(cwd, { minimal = false, classifierDir, force = false, wrote, config }) {
-  const toCreate = [];
-  const toSkip = [];
+// Recursively plan a directory copy from source → dest, relative to projectCwd
+// for display. Returns { actions, preview, skipped }.
+function planScaffoldCopy(sourceDir, destDir, projectCwd, force) {
   const actions = [];
   const preview = [];
+  const skipped = [];
 
-  // Config file.
-  const configPath = join(cwd, "open-classify.config.json");
-  const configRel = relative(cwd, configPath);
-  if (existsSync(configPath) && !force) {
-    toSkip.push(configRel);
-  } else {
-    toCreate.push(configRel);
-    preview.push({ label: configRel, description: `(default Ollama setup, ${config.runner.defaultModel})` });
-    actions.push(() => {
-      writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-      process.stdout.write(`  wrote ${configRel}\n`);
-      wrote.config = true;
-    });
-  }
-
-  // Downstream model catalog.
-  const catalogPath = join(cwd, DOWNSTREAM_MODELS_FILENAME);
-  const catalogRel = relative(cwd, catalogPath);
-  if (existsSync(catalogPath) && !force) {
-    toSkip.push(catalogRel);
-  } else {
-    toCreate.push(catalogRel);
-    preview.push({ label: catalogRel, description: "default downstream model catalog" });
-    actions.push(() => {
-      cpSync(DOWNSTREAM_MODELS_PATH, catalogPath);
-      process.stdout.write(`  wrote ${catalogRel}\n`);
-      wrote.catalog = true;
-    });
-  }
+  walk(sourceDir, destDir);
 
-  if (!minimal) {
-    const classifierPreviewItems = [];
+  return { actions, preview, skipped };
 
-    // Ensure the directory exists (prerequisite for all classifier actions).
-    if (!existsSync(classifierDir)) {
-      toCreate.push(`${relative(cwd, classifierDir)}/`);
+  function walk(src, dst) {
+    if (!existsSync(dst)) {
       actions.push(() => {
-        mkdirSync(classifierDir, { recursive: true });
+        mkdirSync(dst, { recursive: true });
+        process.stdout.write(`  created ${relative(projectCwd, dst)}/\n`);
       });
+      preview.push(`${relative(projectCwd, dst)}/`);
     }
 
-    // README.md.
-    const readmePath = join(classifierDir, "README.md");
-    const readmeRel = relative(cwd, readmePath);
-    if (existsSync(readmePath) && !force) {
-      toSkip.push(readmeRel);
-    } else {
-      toCreate.push(readmeRel);
-      classifierPreviewItems.push({ label: "README.md", indent: true, description: "how to author your own classifier" });
-      actions.push(() => {
-        mkdirSync(classifierDir, { recursive: true });
-        writeFileSync(readmePath, CLASSIFIERS_README);
-        process.stdout.write(`  wrote ${readmeRel}\n`);
-        wrote.readme = true;
-      });
-    }
-
-    // Template classifier directories.
-    for (const name of TEMPLATE_NAMES) {
-      const inactivePath = join(classifierDir, `_${name}`);
-      const activePath = join(classifierDir, name);
-      const inactiveRel = relative(cwd, inactivePath);
-      const activeRel = relative(cwd, activePath);
-
-      // Never overwrite an activated (user-renamed) template.
-      if (existsSync(activePath)) {
-        toSkip.push(`${activeRel}/`);
-        continue;
-      }
-
-      if (existsSync(inactivePath) && !force) {
-        toSkip.push(`${inactiveRel}/`);
-        continue;
-      }
-
-      toCreate.push(`${inactiveRel}/`);
-      classifierPreviewItems.push({
-        label: `_${name}/`,
-        indent: true,
-        description: TEMPLATE_DESCRIPTIONS[name],
-      });
-      actions.push(() => {
-        mkdirSync(classifierDir, { recursive: true });
-        if (force && existsSync(inactivePath)) {
-          rmSync(inactivePath, { recursive: true, force: true });
+    for (const entry of readdirSync(src, { withFileTypes: true })) {
+      const srcChild = join(src, entry.name);
+      const dstChild = join(dst, entry.name);
+      if (entry.isDirectory()) {
+        walk(srcChild, dstChild);
+      } else {
+        const exists = existsSync(dstChild);
+        if (exists && !force) {
+          skipped.push(relative(projectCwd, dstChild));
+          continue;
         }
-        cpSync(join(TEMPLATES_DIR, name), inactivePath, { recursive: true });
-        process.stdout.write(`  wrote ${inactiveRel}/\n`);
-        wrote.templateCount++;
-      });
-    }
-
-    if (classifierPreviewItems.length > 0) {
-      preview.push({ label: `${relative(cwd, classifierDir)}/`, isGroupHeader: true });
-      preview.push(...classifierPreviewItems);
-    }
-  }
-
-  return { toCreate, toSkip, actions, preview };
-}
-
-function showDiffs(conflicts, cwd, classifierDir, config = DEFAULT_CONFIG) {
-  for (const p of conflicts) {
-    const isDir = p.endsWith("/");
-    const relPath = isDir ? p.slice(0, -1) : p;
-    const fullPath = join(cwd, relPath);
-
-    process.stdout.write(`\n--- ${p} ---\n`);
-
-    if (!isDir) {
-      process.stdout.write("\n  current:\n");
-      try {
-        const lines = readFileSync(fullPath, "utf8").split("\n");
-        for (const line of lines) process.stdout.write(`    ${line}\n`);
-      } catch {
-        process.stdout.write("    (could not read)\n");
-      }
-      process.stdout.write("\n  would become:\n");
-      const replacement =
-        basename(relPath) === DOWNSTREAM_MODELS_FILENAME
-          ? readFileSync(DOWNSTREAM_MODELS_PATH, "utf8")
-          : JSON.stringify(config, null, 2);
-      for (const line of replacement.split("\n")) {
-        process.stdout.write(`    ${line}\n`);
-      }
-    } else {
-      process.stdout.write("\n  current files:\n");
-      try {
-        for (const f of readdirSync(fullPath)) process.stdout.write(`    ${f}\n`);
-      } catch {
-        process.stdout.write("    (could not read)\n");
-      }
-      const templateName = basename(relPath).replace(/^_/, "");
-      const templatePath = join(TEMPLATES_DIR, templateName);
-      if (existsSync(templatePath)) {
-        process.stdout.write("\n  template files:\n");
-        for (const f of readdirSync(templatePath)) process.stdout.write(`    ${f}\n`);
+        actions.push(() => {
+          cpSync(srcChild, dstChild);
+          process.stdout.write(`  wrote ${relative(projectCwd, dstChild)}\n`);
+        });
+        preview.push(relative(projectCwd, dstChild));
       }
     }
   }
-  process.stdout.write("\n");
 }
 
 // ---------------------------------------------------------------------------
-// uninstall
+// eject
 // ---------------------------------------------------------------------------
 
-async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
-  const resolvedClassifierDir = resolve(cwd, classifierDir);
-  const plan = planUninstall(cwd, { classifierDir: resolvedClassifierDir, force });
+async function runEject({ cwd, name, yes, force, dryRun }) {
+  if (!name) {
+    process.stderr.write(`Usage: open-classify eject <name>\n\nAvailable: ${STOCK_NAMES.join(", ")}\n`);
+    process.exit(1);
+  }
+  if (!STOCK_NAMES.includes(name)) {
+    process.stderr.write(`✖  "${name}" is not a stock classifier.\n\nAvailable: ${STOCK_NAMES.join(", ")}\n`);
+    process.exit(1);
+  }
 
-  if (plan.toRemove.length === 0) {
-    process.stdout.write("Nothing to remove — no open-classify scaffold found.\n");
-    if (plan.toSkip.length > 0) {
-      process.stdout.write("\nSkipped active/custom classifier dirs:\n");
-      for (const p of plan.toSkip) process.stdout.write(`  ${p}\n`);
-      process.stdout.write("\nUse --force to remove the whole classifiers/ directory.\n");
-    }
-    return;
+  const projectDir = join(cwd, PROJECT_DIRNAME);
+  if (!existsSync(projectDir)) {
+    process.stderr.write(
+      `✖  ./${PROJECT_DIRNAME}/ not found. Run \`npx open-classify init\` first.\n`,
+    );
+    process.exit(1);
   }
 
-  process.stdout.write(`\nThe following open-classify scaffold will be removed from ${cwd}:\n\n`);
-  for (const p of plan.toRemove) process.stdout.write(`  ${p}\n`);
+  const source = join(STOCK_DIR, name);
+  const dest = join(projectDir, "classifiers", name);
+  const destRel = relative(cwd, dest);
+
+  if (existsSync(dest) && !force) {
+    process.stderr.write(
+      `✖  ${destRel}/ already exists. Use --force to overwrite, or delete it first.\n`,
+    );
+    process.exit(1);
+  }
 
-  if (plan.toSkip.length > 0) {
-    process.stdout.write("\nSkipped active/custom classifier dirs:\n");
-    for (const p of plan.toSkip) process.stdout.write(`  ${p}\n`);
-    process.stdout.write("\nUse --force to remove the whole classifiers/ directory.\n");
+  process.stdout.write(`\nEjecting "${name}" → ${destRel}/\n\n`);
+  for (const filename of ["manifest.json", "prompt.md"]) {
+    const srcFile = join(source, filename);
+    const dstFile = join(dest, filename);
+    process.stdout.write(`  ${relative(cwd, dstFile)}\n`);
   }
 
   if (dryRun) {
-    process.stdout.write("\n(dry run — nothing removed)\n");
+    process.stdout.write("\n(dry run — nothing written)\n");
     return;
   }
 
@@ -582,80 +263,18 @@ async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
     }
   }
 
-  process.stdout.write("\n");
-  for (const action of plan.actions) action();
-  process.stdout.write("\n✓ removed open-classify scaffold\n");
-  process.stdout.write("To remove the package dependency too, run: npm uninstall open-classify\n");
-}
-
-function planUninstall(cwd, { classifierDir, force }) {
-  const toRemove = [];
-  const toSkip = [];
-  const actions = [];
+  mkdirSync(dest, { recursive: true });
+  cpSync(source, dest, { recursive: true });
 
-  for (const filename of ["open-classify.config.json", DOWNSTREAM_MODELS_FILENAME]) {
-    const path = join(cwd, filename);
-    if (!existsSync(path)) continue;
-    toRemove.push(filename);
-    actions.push(() => {
-      rmSync(path, { force: true });
-      process.stdout.write(`  removed ${filename}\n`);
-    });
-  }
-
-  const classifierRel = relative(cwd, classifierDir);
-  if (!existsSync(classifierDir)) {
-    return { toRemove, toSkip, actions };
-  }
-
-  if (force) {
-    toRemove.push(`${classifierRel}/`);
-    actions.push(() => {
-      rmSync(classifierDir, { recursive: true, force: true });
-      process.stdout.write(`  removed ${classifierRel}/\n`);
-    });
-    return { toRemove, toSkip, actions };
-  }
-
-  const readmePath = join(classifierDir, "README.md");
-  const readmeRel = relative(cwd, readmePath);
-  if (existsSync(readmePath)) {
-    toRemove.push(readmeRel);
-    actions.push(() => {
-      rmSync(readmePath, { force: true });
-      process.stdout.write(`  removed ${readmeRel}\n`);
-    });
-  }
-
-  for (const name of TEMPLATE_NAMES) {
-    const inactivePath = join(classifierDir, `_${name}`);
-    const inactiveRel = relative(cwd, inactivePath);
-    if (existsSync(inactivePath)) {
-      toRemove.push(`${inactiveRel}/`);
-      actions.push(() => {
-        rmSync(inactivePath, { recursive: true, force: true });
-        process.stdout.write(`  removed ${inactiveRel}/\n`);
-      });
-    }
-
-    const activePath = join(classifierDir, name);
-    if (existsSync(activePath)) {
-      toSkip.push(`${relative(cwd, activePath)}/`);
-    }
-  }
-
-  actions.push(() => {
-    try {
-      if (readdirSync(classifierDir).length === 0) {
-        rmSync(classifierDir, { recursive: true, force: true });
-        process.stdout.write(`  removed ${classifierRel}/\n`);
-      }
-    } catch {
-      // Non-empty: custom/active classifiers remain, which is intentional.
-    }
-  });
+  process.stdout.write(`
+✓ ejected ${name}
 
-  return { toRemove, toSkip, actions };
+The runtime now uses your local copy at ${destRel}/. Edit prompt.md or
+manifest.json to taste. \`npm update open-classify\` won't touch these
+files. To revert: delete the folder. If you want the package-owned
+version to take over after that, add "${name}" to classifiers.stock in
+${PROJECT_DIRNAME}/config.json.
+`);
 }
 
 // ---------------------------------------------------------------------------
@@ -666,123 +285,111 @@ async function runDoctor({ cwd }) {
   let allGood = true;
 
   // 1. package.json + open-classify dep.
-  const pkgPath = join(cwd, "package.json");
-  if (!existsSync(pkgPath)) {
+  const pkg = readJsonIfExists(join(cwd, "package.json"));
+  if (pkg === null) {
     process.stdout.write("✖  No package.json — not a Node project\n");
     allGood = false;
+  } else if (isOpenClassifyDep(pkg)) {
+    process.stdout.write("✓  open-classify found in package.json\n");
   } else {
-    let pkg;
-    try { pkg = JSON.parse(readFileSync(pkgPath, "utf8")); } catch { pkg = {}; }
-    if (isOpenClassifyDep(pkg)) {
-      process.stdout.write("✓  open-classify found in package.json\n");
-    } else {
-      process.stdout.write("⚠  open-classify not listed as a dependency\n");
-      allGood = false;
-    }
+    process.stdout.write("⚠  open-classify not listed as a dependency — run: npm install open-classify\n");
+    allGood = false;
   }
 
-  // 2. Config parses.
-  const configPath = join(cwd, "open-classify.config.json");
+  // 2. Config parses + catalog present.
+  const projectDir = join(cwd, PROJECT_DIRNAME);
+  const configPath = join(projectDir, "config.json");
+  let config = null;
   if (!existsSync(configPath)) {
-    process.stdout.write("✖  No open-classify.config.json — run: npx open-classify init\n");
+    process.stdout.write(`✖  ./${PROJECT_DIRNAME}/config.json not found — run: npx open-classify init\n`);
     allGood = false;
   } else {
-    let config;
-    try {
-      config = JSON.parse(readFileSync(configPath, "utf8"));
-      process.stdout.write("✓  open-classify.config.json parses OK\n");
-
-      // 3. Catalog exists.
-      const catalog = config.catalog || DEFAULT_CONFIG.catalog;
-      const catalogPath = resolve(cwd, catalog);
+    config = readJsonIfExists(configPath);
+    if (config === null) {
+      process.stdout.write(`✖  ./${PROJECT_DIRNAME}/config.json is not valid JSON\n`);
+      allGood = false;
+    } else {
+      process.stdout.write(`✓  ./${PROJECT_DIRNAME}/config.json parses OK\n`);
+      const catalogRel = config.catalog ?? "downstream-models.json";
+      const catalogPath = resolve(projectDir, catalogRel);
       if (existsSync(catalogPath)) {
-        process.stdout.write(`✓  ${catalog} found\n`);
+        process.stdout.write(`✓  catalog found at ${relative(cwd, catalogPath)}\n`);
       } else {
-        process.stdout.write(`✖  ${catalog} not found — run: npx open-classify init\n`);
+        process.stdout.write(`✖  catalog not found at ${relative(cwd, catalogPath)}\n`);
         allGood = false;
       }
+    }
+  }
 
-      // 4. Ollama reachable.
-      const host = config.runner?.host || DEFAULT_CONFIG.runner.host;
-      try {
-        const res = await fetch(`${host}/api/tags`, { signal: AbortSignal.timeout(3000) });
-        if (res.ok) {
-          process.stdout.write(`✓  Ollama reachable at ${host}\n`);
-
-          // 5. Default model pulled.
-          const data = await res.json();
-          const model = config.runner?.defaultModel || DEFAULT_CONFIG.runner.defaultModel;
-          const pulled = data.models?.some((m) => m.name === model || m.model === model);
-          if (pulled) {
-            process.stdout.write(`✓  Model ${model} is available\n`);
-          } else {
-            process.stdout.write(`✖  Model ${model} not found — run: ollama pull ${model}\n`);
-            allGood = false;
-          }
+  // 3. Ollama reachable + default model pulled.
+  if (config !== null) {
+    const host = config.runner?.host ?? "http://127.0.0.1:11434";
+    const defaultModel = config.runner?.defaultModel ?? "gemma4:e4b-it-q4_K_M";
+    try {
+      const res = await fetch(`${host}/api/tags`, { signal: AbortSignal.timeout(3000) });
+      if (res.ok) {
+        process.stdout.write(`✓  Ollama reachable at ${host}\n`);
+        const data = await res.json();
+        const pulled = data.models?.some((m) => m.name === defaultModel || m.model === defaultModel);
+        if (pulled) {
+          process.stdout.write(`✓  Model ${defaultModel} is available\n`);
         } else {
-          process.stdout.write(`✖  Ollama responded ${res.status} at ${host}\n`);
+          process.stdout.write(`✖  Model ${defaultModel} not found — run: ollama pull ${defaultModel}\n`);
           allGood = false;
         }
-      } catch {
-        process.stdout.write(`✖  Ollama not reachable at ${host} — is it running?\n`);
+      } else {
+        process.stdout.write(`✖  Ollama responded ${res.status} at ${host}\n`);
         allGood = false;
       }
     } catch {
-      process.stdout.write("✖  open-classify.config.json is not valid JSON\n");
+      process.stdout.write(`✖  Ollama not reachable at ${host} — is it running?\n`);
       allGood = false;
     }
   }
 
-  // 6. Classifiers directories.
-  const doctorConfig = configFromFile(cwd);
-  const configuredClassifierDirs =
-    doctorConfig?.classifiers === undefined
-      ? ["classifiers"]
-      : doctorConfig.classifiers.dirs ?? [];
-  for (const configuredDir of configuredClassifierDirs) {
-    const classifiersDir = resolve(cwd, configuredDir);
-    const classifiersRel = relative(cwd, classifiersDir);
-    if (!existsSync(classifiersDir)) {
-      process.stdout.write(`ℹ  No ${classifiersRel}/ directory — run: npx open-classify init\n`);
-      continue;
-    }
-
-    let active = 0;
-    let bad = 0;
-    try {
-      for (const entry of readdirSync(classifiersDir, { withFileTypes: true })) {
-        if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
-        const dir = join(classifiersDir, entry.name);
-        const ok =
-          existsSync(join(dir, "manifest.json")) && existsSync(join(dir, "prompt.md"));
-        if (ok) active++;
-        else {
-          process.stdout.write(`✖  ${classifiersRel}/${entry.name}/ is missing manifest.json or prompt.md\n`);
-          bad++;
-          allGood = false;
+  // 4. Classifier directories.
+  if (config !== null) {
+    const dirs = config.classifiers?.dirs ?? ["classifiers"];
+    for (const dirRel of dirs) {
+      const dir = resolve(projectDir, dirRel);
+      const displayRel = relative(cwd, dir);
+      if (!existsSync(dir)) {
+        process.stdout.write(`ℹ  No ${displayRel}/ — run: npx open-classify init\n`);
+        continue;
+      }
+      let active = 0;
+      let bad = 0;
+      try {
+        for (const entry of readdirSync(dir, { withFileTypes: true })) {
+          if (!entry.isDirectory() || entry.name.startsWith("_")) continue;
+          const sub = join(dir, entry.name);
+          const ok = existsSync(join(sub, "manifest.json")) && existsSync(join(sub, "prompt.md"));
+          if (ok) {
+            active++;
+          } else {
+            process.stdout.write(`✖  ${displayRel}/${entry.name}/ is missing manifest.json or prompt.md\n`);
+            bad++;
+            allGood = false;
+          }
+        }
+      } catch {/* skip */}
+      if (bad === 0) {
+        const stockEnabled = (config.classifiers?.stock ?? []).length;
+        process.stdout.write(
+          active > 0
+            ? `✓  ${active} user classifier(s) in ${displayRel}/\n`
+            : `ℹ  No user classifiers in ${displayRel}/${stockEnabled > 0 ? "" : " (use `npx open-classify eject <name>` to customize a stock classifier)"}\n`,
+        );
+        if (stockEnabled > 0) {
+          process.stdout.write(`✓  ${stockEnabled} stock classifier(s) enabled in config\n`);
         }
       }
-    } catch { /* skip */ }
-    if (bad === 0) {
-      process.stdout.write(
-        active > 0
-          ? `✓  ${active} active classifier(s) in ${classifiersRel}/\n`
-          : `ℹ  No active classifiers in ${classifiersRel}/ (enable stock in config or customize a _name template)\n`,
-      );
     }
   }
 
   if (!allGood) process.exit(1);
 }
 
-function configFromFile(cwd) {
-  try {
-    return JSON.parse(readFileSync(join(cwd, "open-classify.config.json"), "utf8"));
-  } catch {
-    return null;
-  }
-}
-
 // ---------------------------------------------------------------------------
 // try
 // ---------------------------------------------------------------------------
@@ -793,14 +400,12 @@ async function runTry({ cwd, message }) {
     process.exit(1);
   }
 
-  const configPath = join(cwd, "open-classify.config.json");
+  const configPath = join(cwd, PROJECT_DIRNAME, "config.json");
   if (!existsSync(configPath)) {
-    process.stderr.write("✖  No open-classify.config.json — run: npx open-classify init\n");
+    process.stderr.write(`✖  ./${PROJECT_DIRNAME}/config.json not found — run: npx open-classify init\n`);
     process.exit(1);
   }
 
-  // Try loading from the consumer's node_modules first, then fall back to the
-  // package root (useful when running from the development checkout).
   let createClassifier;
   const candidates = [
     join(cwd, "node_modules", "open-classify", "dist", "src", "index.js"),
@@ -809,10 +414,9 @@ async function runTry({ cwd, message }) {
   for (const candidate of candidates) {
     if (!existsSync(candidate)) continue;
     try {
-      const mod = await import(candidate);
-      createClassifier = mod.createClassifier;
+      ({ createClassifier } = await import(candidate));
       break;
-    } catch { /* try next */ }
+    } catch {/* try next */}
   }
 
   if (!createClassifier) {
@@ -823,17 +427,9 @@ async function runTry({ cwd, message }) {
     process.exit(1);
   }
 
-  const classifiersDir = join(cwd, "classifiers");
   let classifier;
   try {
-    const config = configFromFile(cwd);
-    const hasConfiguredClassifierDirs = Array.isArray(config?.classifiers?.dirs);
-    classifier = createClassifier({
-      configPath,
-      extraClassifierDirs:
-        hasConfiguredClassifierDirs || !existsSync(classifiersDir) ? [] : [classifiersDir],
-      skipResourceCheck: false,
-    });
+    classifier = createClassifier({ configPath });
   } catch (err) {
     process.stderr.write(`✖  Failed to initialise classifier: ${err.message}\n`);
     process.exit(1);
@@ -851,30 +447,52 @@ async function runTry({ cwd, message }) {
 }
 
 // ---------------------------------------------------------------------------
-// Prompt helpers
+// Shared helpers
 // ---------------------------------------------------------------------------
 
-function confirm(prompt, defaultYes = false) {
-  return new Promise((resolve) => {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    rl.question(prompt, (answer) => {
-      rl.close();
-      const v = (answer || "").trim().toLowerCase();
-      resolve(defaultYes ? (v === "" || v === "y" || v === "yes") : (v === "y" || v === "yes"));
-    });
-  });
+function requireHostProject(cwd) {
+  if (!existsSync(join(cwd, "package.json"))) {
+    process.stderr.write(
+      `✖  No package.json found in ${cwd}.\n` +
+      `   open-classify scaffolds into a Node project, so it needs one to live in.\n\n` +
+      `   Create one first:  npm init -y\n`,
+    );
+    process.exit(1);
+  }
 }
 
-function promptConflict() {
-  return new Promise((resolve) => {
-    process.stdout.write("\n? Overwrite them?\n   y      overwrite all\n   N      keep existing (default)\n   diff   show what would change\n\n");
+function warnIfPackageMissing(cwd) {
+  const pkg = readJsonIfExists(join(cwd, "package.json"));
+  if (pkg === null || isOpenClassifyDep(pkg)) return;
+  process.stdout.write(
+    `\n⚠  open-classify is not yet a dependency of this project.\n` +
+    `   Install it before importing from your code:\n\n` +
+    `       npm install open-classify\n`,
+  );
+}
+
+function readJsonIfExists(path) {
+  if (!existsSync(path)) return null;
+  try { return JSON.parse(readFileSync(path, "utf8")); } catch { return null; }
+}
+
+function isOpenClassifyDep(pkg) {
+  return ["dependencies", "devDependencies", "peerDependencies", "optionalDependencies"].some(
+    (f) => pkg[f]?.["open-classify"],
+  );
+}
+
+function readScaffoldConfig() {
+  return JSON.parse(readFileSync(join(SCAFFOLD_DIR, "config.json"), "utf8"));
+}
+
+function confirm(prompt, defaultYes = false) {
+  return new Promise((resolveAnswer) => {
     const rl = createInterface({ input: process.stdin, output: process.stdout });
-    rl.question("  Choice (y/N/diff): ", (answer) => {
+    rl.question(prompt, (answer) => {
       rl.close();
       const v = (answer || "").trim().toLowerCase();
-      if (v === "y" || v === "yes") resolve("y");
-      else if (v === "diff") resolve("diff");
-      else resolve("N");
+      resolveAnswer(defaultYes ? (v === "" || v === "y" || v === "yes") : (v === "y" || v === "yes"));
     });
   });
 }