open-classify 0.8.2 → 0.9.1

package/README.md

@@ -64,9 +64,7 @@ This creates `open-classify.config.json` and a `classifiers/` directory in your
 ```ts
 import { createClassifier } from "open-classify";
 
-const { classify } = createClassifier({
-  extraClassifierDirs: ["./classifiers"],
-});
+const { classify } = createClassifier();
 
 const result = await classify({
   messages: [{ role: "user", text: "Can you review the attached contract?" }],
@@ -77,15 +75,29 @@ else if (result.action === "block") handleBlock(result.block_reason);     // inj
 else callDownstream(result.model_id, result.tools, result.reply?.text);   // route the real request
 ```
 
-**4. Activate or customize a classifier**
+**4. Enable or customize optional classifiers**
+
+`init` writes `open-classify.config.json`, which enables package-owned stock classifiers without copying them into your project. They default to `false` so the four mandatory base classifiers run automatically:
+
+```json
+{
+  "classifiers": {
+    "stock": {
+      "tools": false
+    }
+  }
+}
+```
+
+Set `"tools": true` to run the package-owned stock `tools` classifier. Because it stays in `node_modules/open-classify`, `npm update open-classify` can improve its prompt later without touching your project files.
 
-Inside `classifiers/` you'll find four `_<name>/` directories — templates copied from the package, inactive because of the underscore prefix. To turn one on, drop the underscore:
+Inside `classifiers/` you'll also find four `_<name>/` directories — editable copies of the stock classifiers, inactive because of the underscore prefix. To customize one, keep the matching `classifiers.stock.<name>` value `false`, edit the copy, then drop the underscore:
 
 ```sh
 mv classifiers/_tools classifiers/tools
 ```
 
-Edit `manifest.json` first if you need to (e.g. trim `allowed_tools` for your app). The same underscore convention works the other way too: rename `my_classifier/` → `_my_classifier/` to take any classifier out of the active set without deleting it.
+Edit `manifest.json` first if you need to (e.g. trim `allowed_tools` for your app). The same underscore convention works the other way too: rename `my_classifier/` → `_my_classifier/` to take any copied/custom classifier out of the active set without deleting it.
 
 To write a new classifier from scratch, drop a `<name>/manifest.json` + `<name>/prompt.md` in `classifiers/`. See [docs/adding-a-classifier.md](docs/adding-a-classifier.md).
 
@@ -152,7 +164,7 @@ Example result:
 
 Every classifier — bundled or your own — uses the same two-file shape (`manifest.json` + `prompt.md`) and emits the same envelope: `{ reason, certainty, ...payload }`. Some payload fields are **reserved** (like `model_tier`, `final_reply`, `risk_level`); the aggregator knows how to consume them into the routing decision. Everything else passes through to the caller.
 
-Open Classify ships eight built-in classifiers. **Four are mandatory** — they always load, they can't be turned off, and extras can't override them. The other four ship as **templates** that `init` copies into your project as inactive (`_<name>/`); rename to activate.
+Open Classify ships four mandatory base classifiers and four optional stock classifiers. The mandatory base classifiers always load from the package, can't be turned off, and are updated by `npm update open-classify`. Optional stock classifiers also live in the package, but are enabled by `open-classify.config.json`.
 
 | Name | dispatch_order | Reserved fields | Bundled as | What the aggregator does with it |
 |---|---|---|---|---|
@@ -160,12 +172,27 @@ Open Classify ships eight built-in classifiers. **Four are mandatory** — they
 | `model_tier` | 20 | `model_tier` | mandatory | Feeds the catalog resolver as a soft constraint |
 | `model_specialization` | 30 | `model_specialization` | mandatory | Feeds the catalog resolver as a soft constraint |
 | `prompt_injection` | 50 | `risk_level` | mandatory | High-risk/unknown → `action: "block"`; suspicious → advisory |
-| `tools` | 40 | `tools` | template | Sets `result.tools` |
-| `memory_retrieval_queries` | 60 | — | template | Passes through to `classifier_outputs` |
-| `conversation_digest` | 70 | — | template | Passes through |
-| `context_shift` | 80 | — | template | Passes through |
+| `tools` | 40 | `tools` | optional stock | Sets `result.tools` |
+| `memory_retrieval_queries` | 60 | — | optional stock | Passes through to `classifier_outputs` |
+| `conversation_digest` | 70 | — | optional stock | Passes through |
+| `context_shift` | 80 | — | optional stock | Passes through |
 
-The directory-naming convention (`_<name>/` = inactive) is the only on/off mechanism, and it applies equally to bundled templates and your own classifiers. No `disabled` config, no allow-lists, no flags. If a folder is in `classifiers/` without a leading underscore, it runs.
+For package-owned stock classifiers, `open-classify.config.json` is the on/off switch:
+
+```json
+{
+  "classifiers": {
+    "stock": {
+      "tools": true,
+      "memory_retrieval_queries": false,
+      "conversation_digest": false,
+      "context_shift": false
+    }
+  }
+}
+```
+
+For copied/custom classifiers in `classifiers/`, the directory-naming convention still applies: `_<name>/` is inactive; `<name>/` runs. Root project files are user-owned, so `init` skips existing config/classifier files unless you pass `--force`.
 
 > Need to customize `preflight`'s prompt or any other mandatory built-in? Use a custom `RunClassifier` (see [Bring your own backend](#bring-your-own-backend)) to intercept it, or fork the package.
 
@@ -308,11 +335,20 @@ cp open-classify.config.example.json open-classify.config.json
       "memory_retrieval_queries": "qwen2.5:7b-instruct-q4_K_M"
     }
   },
-  "catalog": "downstream-models.json"
+  "catalog": "downstream-models.json",
+  "classifiers": {
+    "dirs": ["classifiers"],
+    "stock": {
+      "tools": false,
+      "memory_retrieval_queries": false,
+      "conversation_digest": false,
+      "context_shift": false
+    }
+  }
 }
 ```
 
-`runner.provider` currently supports `"ollama"` only. `runner.defaultModel` applies to any classifier without an explicit `runner.models` entry. `runner.models` is a flat map keyed by classifier name.
+`runner.provider` currently supports `"ollama"` only. `runner.defaultModel` applies to any classifier without an explicit `runner.models` entry. `runner.models` is a flat map keyed by classifier name. `classifiers.dirs` is for user-owned copied/custom classifiers; `classifiers.stock` toggles package-owned optional classifiers.
 
 ## Bring your own backend
 

package/bin/open-classify.mjs

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
-// open-classify CLI. Subcommands: init, doctor, try.
+// open-classify CLI. Subcommands: init, uninstall, doctor, try.
 //
 // 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.
 
@@ -14,8 +15,16 @@ 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",
@@ -36,17 +45,35 @@ Drop a folder here per classifier. Each folder needs:
 \`\`\`js
 import { createClassifier } from "open-classify";
 
-const { classify } = createClassifier({
-  extraClassifierDirs: ["./classifiers"],
-});
+const { classify } = createClassifier();
 \`\`\`
 
 Place this in your server entry point. Call \`classify(input)\` for each user message.
-\`extraClassifierDirs\` is resolved relative to the current working directory.
+\`open-classify.config.json\` wires in \`./classifiers\` automatically.
+
+## Stock classifiers
+
+\`tools\`, \`memory_retrieval_queries\`, \`conversation_digest\`, and \`context_shift\`
+ship with the package but are disabled by default in \`open-classify.config.json\`.
+Enable a package-owned stock classifier by setting it to \`true\`:
+
+\`\`\`json
+{
+  "classifiers": {
+    "stock": {
+      "tools": true
+    }
+  }
+}
+\`\`\`
+
+Package-owned stock classifiers are updated by \`npm update open-classify\`.
 
-## Activating templates
+## Customizing a stock classifier
 
-The four \`_<name>/\` directories below are templates copied from the package — they ship inactive (the loader skips any folder starting with \`_\`). Activate one by dropping the underscore:
+The four \`_<name>/\` directories below are editable copies of the stock classifiers.
+They are inactive because the loader skips any folder starting with \`_\`. To customize one,
+keep the matching \`classifiers.stock.<name>\` value \`false\`, edit the files, then drop the underscore:
 
 \`\`\`sh
 mv _tools tools
@@ -65,9 +92,23 @@ const DEFAULT_CONFIG = {
     host: "http://127.0.0.1:11434",
     defaultModel: "gemma4:e4b-it-q4_K_M",
   },
-  catalog: "downstream-models.json",
+  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,
+    },
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
@@ -87,6 +128,12 @@ async function main() {
     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;
@@ -134,6 +181,26 @@ function parseInitFlags(args) {
   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;
+}
+
 function printHelp() {
   process.stdout.write(`open-classify — runtime CLI
 
@@ -141,6 +208,10 @@ 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.
 
@@ -149,7 +220,7 @@ Commands:
                     application code.
 
 Options for init:
-  --minimal              Write only open-classify.config.json; skip classifiers/
+  --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
@@ -157,6 +228,12 @@ Options for init:
   --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)
+
 `);
 }
 
@@ -231,8 +308,9 @@ async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageMan
 
   // 3. Plan.
   const resolvedClassifierDir = resolve(cwd, classifierDir);
-  const wrote = { config: false, readme: false, templateCount: 0 };
-  let plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force, wrote });
+  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) {
@@ -271,13 +349,13 @@ async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageMan
   if (plan.toSkip.length > 0 && !yes && !force) {
     const choice = await promptConflict();
     if (choice === "diff") {
-      showDiffs(plan.toSkip, cwd, resolvedClassifierDir);
+      showDiffs(plan.toSkip, cwd, resolvedClassifierDir, config);
       const choice2 = await promptConflict();
       if (choice2 === "y") {
-        plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force: true, wrote });
+        plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force: true, wrote, config });
       }
     } else if (choice === "y") {
-      plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force: true, wrote });
+      plan = planInit(cwd, { minimal, classifierDir: resolvedClassifierDir, force: true, wrote, config });
     }
   }
 
@@ -301,6 +379,7 @@ async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageMan
     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) {
@@ -315,7 +394,7 @@ async function runInit({ cwd, yes, minimal, dryRun, force, noInstall, packageMan
 Next steps:
 
   1. Pull the default model:
-       ollama pull ${DEFAULT_CONFIG.runner.defaultModel}
+       ollama pull ${config.runner.defaultModel}
 
   2. Wire it into your server (example for a Node entrypoint):
        see  ./${classifierDirRel}/README.md  →  "Quickstart"
@@ -330,7 +409,7 @@ Docs:  https://github.com/taylorbayouth/open-classify#readme
 `);
 }
 
-function planInit(cwd, { minimal = false, classifierDir, force = false, wrote }) {
+function planInit(cwd, { minimal = false, classifierDir, force = false, wrote, config }) {
   const toCreate = [];
   const toSkip = [];
   const actions = [];
@@ -343,14 +422,29 @@ function planInit(cwd, { minimal = false, classifierDir, force = false, wrote })
     toSkip.push(configRel);
   } else {
     toCreate.push(configRel);
-    preview.push({ label: configRel, description: `(default Ollama setup, ${DEFAULT_CONFIG.runner.defaultModel})` });
+    preview.push({ label: configRel, description: `(default Ollama setup, ${config.runner.defaultModel})` });
     actions.push(() => {
-      writeFileSync(configPath, JSON.stringify(DEFAULT_CONFIG, null, 2) + "\n");
+      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;
+    });
+  }
+
   if (!minimal) {
     const classifierPreviewItems = [];
 
@@ -422,7 +516,7 @@ function planInit(cwd, { minimal = false, classifierDir, force = false, wrote })
   return { toCreate, toSkip, actions, preview };
 }
 
-function showDiffs(conflicts, cwd, classifierDir) {
+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;
@@ -439,7 +533,11 @@ function showDiffs(conflicts, cwd, classifierDir) {
         process.stdout.write("    (could not read)\n");
       }
       process.stdout.write("\n  would become:\n");
-      for (const line of JSON.stringify(DEFAULT_CONFIG, null, 2).split("\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 {
@@ -460,6 +558,122 @@ function showDiffs(conflicts, cwd, classifierDir) {
   process.stdout.write("\n");
 }
 
+// ---------------------------------------------------------------------------
+// uninstall
+// ---------------------------------------------------------------------------
+
+async function runUninstall({ cwd, yes, dryRun, force, classifierDir }) {
+  const resolvedClassifierDir = resolve(cwd, classifierDir);
+  const plan = planUninstall(cwd, { classifierDir: resolvedClassifierDir, force });
+
+  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;
+  }
+
+  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`);
+
+  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");
+  }
+
+  if (dryRun) {
+    process.stdout.write("\n(dry run — nothing removed)\n");
+    return;
+  }
+
+  if (!yes) {
+    const proceed = await confirm("\n? Continue? (Y/n) ", true);
+    if (!proceed) {
+      process.stdout.write("Aborted.\n");
+      process.exit(1);
+    }
+  }
+
+  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 = [];
+
+  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.
+    }
+  });
+
+  return { toRemove, toSkip, actions };
+}
+
 // ---------------------------------------------------------------------------
 // doctor
 // ---------------------------------------------------------------------------
@@ -494,14 +708,24 @@ async function runDoctor({ cwd }) {
       config = JSON.parse(readFileSync(configPath, "utf8"));
       process.stdout.write("✓  open-classify.config.json parses OK\n");
 
-      // 3. Ollama reachable.
+      // 3. Catalog exists.
+      const catalog = config.catalog || DEFAULT_CONFIG.catalog;
+      const catalogPath = resolve(cwd, catalog);
+      if (existsSync(catalogPath)) {
+        process.stdout.write(`✓  ${catalog} found\n`);
+      } else {
+        process.stdout.write(`✖  ${catalog} not found — run: npx open-classify init\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`);
 
-          // 4. Default model pulled.
+          // 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);
@@ -525,9 +749,20 @@ async function runDoctor({ cwd }) {
     }
   }
 
-  // 5. Classifiers directory.
-  const classifiersDir = join(cwd, "classifiers");
-  if (existsSync(classifiersDir)) {
+  // 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 {
@@ -538,7 +773,7 @@ async function runDoctor({ cwd }) {
           existsSync(join(dir, "manifest.json")) && existsSync(join(dir, "prompt.md"));
         if (ok) active++;
         else {
-          process.stdout.write(`✖  classifiers/${entry.name}/ is missing manifest.json or prompt.md\n`);
+          process.stdout.write(`✖  ${classifiersRel}/${entry.name}/ is missing manifest.json or prompt.md\n`);
           bad++;
           allGood = false;
         }
@@ -547,17 +782,23 @@ async function runDoctor({ cwd }) {
     if (bad === 0) {
       process.stdout.write(
         active > 0
-          ? `✓  ${active} active classifier(s) in classifiers/\n`
-          : "ℹ  No active classifiers in classifiers/ (activate a template with: mv _name name)\n",
+          ? `✓  ${active} active classifier(s) in ${classifiersRel}/\n`
+          : `ℹ  No active classifiers in ${classifiersRel}/ (enable stock in config or customize a _name template)\n`,
       );
     }
-  } else {
-    process.stdout.write("ℹ  No classifiers/ directory — run: npx open-classify init\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
 // ---------------------------------------------------------------------------
@@ -601,9 +842,12 @@ async function runTry({ cwd, message }) {
   const classifiersDir = join(cwd, "classifiers");
   let classifier;
   try {
+    const config = configFromFile(cwd);
+    const hasConfiguredClassifierDirs = Array.isArray(config?.classifiers?.dirs);
     classifier = createClassifier({
       configPath,
-      extraClassifierDirs: existsSync(classifiersDir) ? [classifiersDir] : [],
+      extraClassifierDirs:
+        hasConfiguredClassifierDirs || !existsSync(classifiersDir) ? [] : [classifiersDir],
       skipResourceCheck: false,
     });
   } catch (err) {

package/dist/src/classifiers.d.ts

@@ -2,6 +2,9 @@ import type { ClassifierInput } from "./types.js";
 import type { ClassifierName, ClassifierRegistry, RunClassifier } from "./manifest.js";
 import type { ClassifierOutput, RuntimeClassifierManifest } from "./stock.js";
 export declare const BUILTIN_CLASSIFIERS_DIR: string;
+export declare const STOCK_CLASSIFIER_NAMES: readonly ["tools", "memory_retrieval_queries", "conversation_digest", "context_shift"];
+export type StockClassifierName = (typeof STOCK_CLASSIFIER_NAMES)[number];
+export declare const STOCK_CLASSIFIERS_DIR: string;
 export declare class ClassifierManifestError extends Error {
     constructor(message: string);
 }
@@ -12,6 +15,7 @@ export interface ClassifierRegistryBundle {
     readonly names: ReadonlyArray<string>;
 }
 export interface BuildRegistryOptions {
+    readonly stockClassifierNames?: ReadonlyArray<string>;
     readonly extraDirs?: ReadonlyArray<string>;
 }
 export declare function loadClassifierRegistry(classifiersDir?: string): RuntimeClassifierManifest[];

package/dist/src/classifiers.js

@@ -5,6 +5,22 @@ import { buildClassifierPrompt } from "./stock-prompt.js";
 import { validateJsonClassifierManifest, validateOutputForManifest, } from "./stock-validation.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
 export const BUILTIN_CLASSIFIERS_DIR = join(__dirname, "classifiers");
+export const STOCK_CLASSIFIER_NAMES = [
+    "tools",
+    "memory_retrieval_queries",
+    "conversation_digest",
+    "context_shift",
+];
+export const STOCK_CLASSIFIERS_DIR = findStockClassifiersDir();
+function findStockClassifiersDir() {
+    // Source runs use ../templates; built package runs use ../../templates from
+    // dist/src. Keep both so tests and the published package agree.
+    const candidates = [
+        join(__dirname, "..", "templates"),
+        join(__dirname, "..", "..", "templates"),
+    ];
+    return candidates.find((dir) => existsSync(dir)) ?? candidates[0];
+}
 // Directories whose names start with "_" are reserved for shared assets
 // (e.g. `_prompts/`) and are not loaded as classifiers. Consumers can use
 // the same convention in their own classifier directories: rename a
@@ -46,6 +62,7 @@ export function loadClassifierRegistry(classifiersDir = BUILTIN_CLASSIFIERS_DIR)
 export function buildClassifierRegistry(options = {}) {
     const manifests = [
         ...loadClassifierRegistry(BUILTIN_CLASSIFIERS_DIR),
+        ...(options.stockClassifierNames ?? []).map((name) => loadStockClassifier(name)),
         ...(options.extraDirs ?? []).flatMap((dir) => loadClassifierRegistry(dir)),
     ];
     manifests.sort((a, b) => (a.dispatch_order ?? Infinity) - (b.dispatch_order ?? Infinity));
@@ -55,6 +72,12 @@ export function buildClassifierRegistry(options = {}) {
     const names = manifests.map((m) => m.name);
     return { registry, modulesByName, names };
 }
+function loadStockClassifier(name) {
+    if (!STOCK_CLASSIFIER_NAMES.includes(name)) {
+        throw new ClassifierManifestError(`unknown stock classifier: ${name} (available: ${STOCK_CLASSIFIER_NAMES.join(", ")})`);
+    }
+    return loadClassifierManifest(join(STOCK_CLASSIFIERS_DIR, name));
+}
 function loadClassifierManifest(classifierDir) {
     const manifestPath = join(classifierDir, "manifest.json");
     const promptPath = join(classifierDir, "prompt.md");

package/dist/src/classify.d.ts

@@ -17,6 +17,7 @@ export interface CreateClassifierOptions {
     runClassifier?: RunClassifier;
     catalog?: Catalog;
     extraClassifierDirs?: ReadonlyArray<string>;
+    stockClassifierNames?: ReadonlyArray<string>;
     config?: OpenClassifyConfig;
     configPath?: string;
     catalogPath?: string;

package/dist/src/classify.js

@@ -3,19 +3,31 @@
 // user-input/routing pass and inspect() for the assistant-output lean pass.
 // Backend-agnostic: pass a custom `runClassifier` to bypass the bundled
 // Ollama runner entirely.
+import { dirname, isAbsolute, resolve } from "node:path";
 import { loadCatalog } from "./catalog.js";
 import { buildClassifierRegistry, ClassifierManifestError, } from "./classifiers.js";
-import { classifierModelsFromConfig, loadOpenClassifyConfig, OpenClassifyConfigError, } from "./config.js";
+import { classifierDirsFromConfig, classifierModelsFromConfig, DEFAULT_OPEN_CLASSIFY_CONFIG_PATH, loadOpenClassifyConfig, OpenClassifyConfigError, stockClassifierNamesFromConfig, } from "./config.js";
 import { assertOllamaResources, createOllamaClassifierRunner, OLLAMA_DEFAULT_CATALOG_PATH, } from "./ollama.js";
 import { classifyOpenClassifyInput, inspectOpenClassifyInput, } from "./pipeline.js";
 export function createClassifier(options = {}) {
+    const configPath = options.config === undefined
+        ? options.configPath ?? process.env.OPEN_CLASSIFY_CONFIG ?? DEFAULT_OPEN_CLASSIFY_CONFIG_PATH
+        : undefined;
+    const configBaseDir = configPath === undefined ? process.cwd() : dirname(resolve(configPath));
     const fileConfig = options.config ??
         loadOpenClassifyConfig(options.configPath, {
             optional: options.configPath === undefined &&
                 process.env.OPEN_CLASSIFY_CONFIG === undefined,
         });
     const registryBundle = buildClassifierRegistry({
-        extraDirs: options.extraClassifierDirs,
+        extraDirs: uniqueStrings([
+            ...classifierDirsFromConfig(fileConfig).map((dir) => resolveFromConfigBase(dir, configBaseDir)),
+            ...(options.extraClassifierDirs ?? []),
+        ]),
+        stockClassifierNames: uniqueStrings([
+            ...stockClassifierNamesFromConfig(fileConfig),
+            ...(options.stockClassifierNames ?? []),
+        ]),
     });
     // Cross-check `runner.models` keys against the loaded registry so a typo
     // or stale reference fails fast at construction time instead of being
@@ -44,7 +56,10 @@ export function createClassifier(options = {}) {
             fetch: options.fetch,
         });
     const catalog = options.catalog ??
-        loadCatalog(options.catalogPath ?? fileConfig?.catalog ?? OLLAMA_DEFAULT_CATALOG_PATH);
+        loadCatalog(options.catalogPath ??
+            (fileConfig?.catalog === undefined
+                ? OLLAMA_DEFAULT_CATALOG_PATH
+                : resolveFromConfigBase(fileConfig.catalog, configBaseDir)));
     let resourceCheck;
     const ensureResources = async () => {
         if (!needsResourceCheck)
@@ -80,6 +95,12 @@ export function createClassifier(options = {}) {
     };
     return { classify, inspect, registry: registryBundle };
 }
+function uniqueStrings(values) {
+    return [...new Set(values)];
+}
+function resolveFromConfigBase(path, configBaseDir) {
+    return isAbsolute(path) ? path : resolve(configBaseDir, path);
+}
 // Re-export so callers can `import { ClassifierManifestError } from "open-classify"`
 // and catch directory/name collision errors from createClassifier().
 export { ClassifierManifestError };

package/dist/src/config.d.ts

@@ -1,8 +1,13 @@
-import type { ClassifierName } from "./classifiers.js";
+import { type ClassifierName } from "./classifiers.js";
 export declare const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify.config.json";
 export interface OpenClassifyConfig {
     readonly runner?: OllamaRunnerConfig;
     readonly catalog?: string;
+    readonly classifiers?: OpenClassifyClassifierConfig;
+}
+export interface OpenClassifyClassifierConfig {
+    readonly dirs?: ReadonlyArray<string>;
+    readonly stock?: Readonly<Record<string, boolean>>;
 }
 export interface OllamaRunnerConfig {
     readonly provider: "ollama";
@@ -23,4 +28,6 @@ export declare function loadOpenClassifyConfig(path?: string, options?: {
     optional?: boolean;
 }): OpenClassifyConfig | undefined;
 export declare function classifierModelsFromConfig(config: OpenClassifyConfig | undefined): Partial<Record<ClassifierName, string>>;
+export declare function classifierDirsFromConfig(config: OpenClassifyConfig | undefined): ReadonlyArray<string>;
+export declare function stockClassifierNamesFromConfig(config: OpenClassifyConfig | undefined): ReadonlyArray<string>;
 export declare function validateOpenClassifyConfig(value: unknown, path?: string): OpenClassifyConfig;

package/dist/src/config.js

@@ -1,4 +1,5 @@
 import { existsSync, readFileSync } from "node:fs";
+import { STOCK_CLASSIFIER_NAMES } from "./classifiers.js";
 import { isRecord } from "./validation.js";
 export const DEFAULT_OPEN_CLASSIFY_CONFIG_PATH = "open-classify.config.json";
 export class OpenClassifyConfigError extends Error {
@@ -25,14 +26,37 @@ export function loadOpenClassifyConfig(path = process.env.OPEN_CLASSIFY_CONFIG ?
 export function classifierModelsFromConfig(config) {
     return { ...config?.runner?.models };
 }
+export function classifierDirsFromConfig(config) {
+    return config?.classifiers?.dirs ?? [];
+}
+export function stockClassifierNamesFromConfig(config) {
+    return Object.entries(config?.classifiers?.stock ?? {})
+        .filter(([, enabled]) => enabled)
+        .map(([name]) => name);
+}
 export function validateOpenClassifyConfig(value, path = "open-classify config") {
     if (!isRecord(value)) {
         throwConfig(path, "config must be a JSON object");
     }
-    ensureAllowedKeys(value, ["runner", "catalog"], path, "<root>");
+    ensureAllowedKeys(value, ["runner", "catalog", "classifiers"], path, "<root>");
     return {
         ...(value.runner === undefined ? {} : { runner: validateRunner(value.runner, path) }),
         ...(value.catalog === undefined ? {} : { catalog: requireString(value.catalog, path, "catalog") }),
+        ...(value.classifiers === undefined
+            ? {}
+            : { classifiers: validateClassifiers(value.classifiers, path) }),
+    };
+}
+function validateClassifiers(value, path) {
+    if (!isRecord(value)) {
+        throwConfig(path, "classifiers must be an object");
+    }
+    ensureAllowedKeys(value, ["dirs", "stock"], path, "classifiers");
+    return {
+        ...(value.dirs === undefined ? {} : { dirs: validateStringArray(value.dirs, path, "classifiers.dirs") }),
+        ...(value.stock === undefined
+            ? {}
+            : { stock: validateBooleanMap(value.stock, path, "classifiers.stock", STOCK_CLASSIFIER_NAMES) }),
     };
 }
 function validateRunner(value, path) {
@@ -86,6 +110,29 @@ function validateModels(value, path) {
     }
     return out;
 }
+function validateStringArray(value, path, field) {
+    if (!Array.isArray(value)) {
+        throwConfig(path, `${field} must be an array`);
+    }
+    return value.map((item, index) => requireString(item, path, `${field}[${index}]`));
+}
+function validateBooleanMap(value, path, field, allowedKeys) {
+    if (!isRecord(value)) {
+        throwConfig(path, `${field} must be an object`);
+    }
+    const allowed = allowedKeys === undefined ? undefined : new Set(allowedKeys);
+    const out = {};
+    for (const [name, enabled] of Object.entries(value)) {
+        if (allowed !== undefined && !allowed.has(name)) {
+            throwConfig(path, `${field}.${name} is not supported (available: ${[...allowed].join(", ")})`);
+        }
+        if (typeof enabled !== "boolean") {
+            throwConfig(path, `${field}.${name} must be a boolean`);
+        }
+        out[name] = enabled;
+    }
+    return out;
+}
 function requireString(value, path, field) {
     if (typeof value !== "string" || value.trim().length === 0) {
         throwConfig(path, `${field} must be a non-empty string`);

package/docs/adding-a-classifier.md

@@ -1,10 +1,10 @@
 # Adding a classifier
 
-Every classifier — bundled or your own — uses the same two-file layout. There is no separate "stock" vs "custom" distinction; the runtime only cares about which reserved fields a classifier opts into.
+Every classifier — package-owned or your own — uses the same two-file layout. The runtime only cares about which reserved fields a classifier opts into; ownership just decides whether `npm update open-classify` can replace the prompt.
 
 There are two places a classifier can live:
 
-- **In your own app**, in a directory you pass to `extraClassifierDirs` (almost always `./classifiers/` after `npx open-classify init`). This is the right path when you've installed Open Classify as a dependency.
+- **In your own app**, in a directory listed in `open-classify.config.json` under `classifiers.dirs` (almost always `./classifiers/` after `npx open-classify init`). This is the right path when you've installed Open Classify as a dependency.
 - **In this repo**, under `src/classifiers/<name>/`. Only do this when you're contributing a new mandatory built-in back to Open Classify.
 
 Either way, the layout and contract are identical.
@@ -98,14 +98,12 @@ Don't paste enum values for reserved fields — the runtime injects them with ca
 
 ## 4. Use it
 
-After `npx open-classify init`, your `classifiers/` directory already exists. Drop your folder in and point `createClassifier` at the parent dir:
+After `npx open-classify init`, your `classifiers/` directory already exists and `open-classify.config.json` points at it. Drop your folder there and call `createClassifier()`:
 
 ```ts
 import { createClassifier } from "open-classify";
 
-const { classify } = createClassifier({
-  extraClassifierDirs: ["./classifiers"],
-});
+const { classify } = createClassifier();
 
 const result = await classify({
   messages: [{ role: "user", text: "Can you review the attached contract?" }],
@@ -114,19 +112,31 @@ const result = await classify({
 const tags = result.classifier_outputs.topic_tags?.tags ?? [];
 ```
 
-> Production tip: `"./classifiers"` resolves against `process.cwd()`, which is fine for `npm start` but breaks if the process launches from a different directory. For long-running services, resolve absolutely via `fileURLToPath(import.meta.url) + path.resolve(...)`.
+`classifiers.dirs` entries resolve relative to the config file, so the scaffold keeps working even if your server starts from a different current working directory.
 
 If the manifest is malformed, `createClassifier` throws `ClassifierManifestError` at startup with the path and a specific reason — typos fail loud.
 
-## Activating one of the bundled templates
+## Enabling or customizing optional stock classifiers
+
+`tools`, `memory_retrieval_queries`, `conversation_digest`, and `context_shift` ship as package-owned optional stock classifiers. Enable one in `open-classify.config.json` if you want package updates to keep improving its prompt:
+
+```json
+{
+  "classifiers": {
+    "stock": {
+      "tools": true
+    }
+  }
+}
+```
 
-`npx open-classify init` copies four templates (`tools`, `memory_retrieval_queries`, `conversation_digest`, `context_shift`) into your `classifiers/` directory as `_<name>/` — inactive because of the underscore prefix. To turn one on:
+`npx open-classify init` also copies editable templates into your `classifiers/` directory as `_<name>/` — inactive because of the underscore prefix. To customize one, keep the matching `classifiers.stock.<name>` value `false`, edit the copy, then turn it on:
 
 ```sh
 mv classifiers/_tools classifiers/tools
 ```
 
-Edit `manifest.json` first if you need to (`tools` in particular ships with an opinionated `allowed_tools` list you'll almost certainly want to tailor). The reverse works on any classifier: rename `<name>/` → `_<name>/` to deactivate without deleting.
+Edit `manifest.json` first if you need to (`tools` in particular ships with an opinionated `allowed_tools` list you'll almost certainly want to tailor). The reverse works on any copied/custom classifier: rename `<name>/` → `_<name>/` to deactivate without deleting.
 
 ## Targeting the assistant response
 
@@ -167,7 +177,7 @@ In `open-classify.config.json`:
 }
 ```
 
-`runner.defaultModel` applies to every classifier without an override. `runner.models` is a flat map keyed by classifier name — works for built-ins, templates, and your own.
+`runner.defaultModel` applies to every classifier without an override. `runner.models` is a flat map keyed by classifier name — works for mandatory base classifiers, optional stock classifiers, and your own.
 
 Classifier manifests may also carry an Ollama hint:
 

package/open-classify.config.example.json

@@ -16,5 +16,14 @@
       "prompt_injection": "gemma4:e4b-it-q4_K_M"
     }
   },
-  "catalog": "downstream-models.json"
+  "catalog": "downstream-models.json",
+  "classifiers": {
+    "dirs": ["classifiers"],
+    "stock": {
+      "tools": false,
+      "memory_retrieval_queries": false,
+      "conversation_digest": false,
+      "context_shift": false
+    }
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-classify",
-  "version": "0.8.2",
+  "version": "0.9.1",
   "description": "Manifest-driven classifier runtime for routing user messages to downstream AI models",
   "license": "MIT",
   "author": "Taylor Bayouth",