open-classify 0.6.0 → 0.8.0

package/dist/src/classifiers.js

@@ -4,9 +4,11 @@ import { fileURLToPath } from "node:url";
 import { buildClassifierPrompt } from "./stock-prompt.js";
 import { validateJsonClassifierManifest, validateOutputForManifest, } from "./stock-validation.js";
 const __dirname = dirname(fileURLToPath(import.meta.url));
-const CLASSIFIERS_DIR = join(__dirname, "classifiers");
+export const BUILTIN_CLASSIFIERS_DIR = join(__dirname, "classifiers");
 // Directories whose names start with "_" are reserved for shared assets
-// (e.g. `_prompts/`) and are not loaded as classifiers.
+// (e.g. `_prompts/`) and are not loaded as classifiers. Consumers can use
+// the same convention in their own classifier directories: rename a
+// classifier to `_<name>/` to deactivate it without deleting it.
 const SHARED_DIRECTORY_PREFIX = "_";
 export class ClassifierManifestError extends Error {
     constructor(message) {
@@ -14,7 +16,10 @@ export class ClassifierManifestError extends Error {
         this.name = "ClassifierManifestError";
     }
 }
-export function loadClassifierRegistry(classifiersDir = CLASSIFIERS_DIR) {
+// Load all classifier manifests under a single directory. Used internally to
+// load the built-ins and each extra directory; callers wanting the merged
+// registry should use `buildClassifierRegistry()` instead.
+export function loadClassifierRegistry(classifiersDir = BUILTIN_CLASSIFIERS_DIR) {
     if (!existsSync(classifiersDir)) {
         throw new ClassifierManifestError(`classifier directory not found: ${classifiersDir}`);
     }
@@ -26,11 +31,29 @@ export function loadClassifierRegistry(classifiersDir = CLASSIFIERS_DIR) {
             continue;
         manifests.push(loadClassifierManifest(join(classifiersDir, entry.name)));
     }
-    // Lower dispatch_order runs first. Classifiers without dispatch_order sort
-    // last (treated as +Infinity) — useful for "run me whenever there's a slot".
+    return manifests;
+}
+// Build a complete classifier registry from the bundled built-ins plus any
+// extra directories supplied by the caller. Sorts by dispatch_order
+// ascending (manifests without dispatch_order sort last). Rejects duplicate
+// names.
+//
+// Mandatory built-ins (preflight, model_tier, model_specialization,
+// prompt_injection) always load. Extras with the same name as a built-in
+// throw — there's no override mechanism. Customise by editing the bundled
+// manifest in your own fork, or replace behaviour entirely with a custom
+// `runClassifier`.
+export function buildClassifierRegistry(options = {}) {
+    const manifests = [
+        ...loadClassifierRegistry(BUILTIN_CLASSIFIERS_DIR),
+        ...(options.extraDirs ?? []).flatMap((dir) => loadClassifierRegistry(dir)),
+    ];
     manifests.sort((a, b) => (a.dispatch_order ?? Infinity) - (b.dispatch_order ?? Infinity));
     validateRegistry(manifests);
-    return manifests;
+    const registry = manifests;
+    const modulesByName = Object.fromEntries(manifests.map((m) => [m.name, m]));
+    const names = manifests.map((m) => m.name);
+    return { registry, modulesByName, names };
 }
 function loadClassifierManifest(classifierDir) {
     const manifestPath = join(classifierDir, "manifest.json");
@@ -69,18 +92,11 @@ function validateRegistry(manifests) {
     const names = new Set();
     for (const manifest of manifests) {
         if (names.has(manifest.name)) {
-            throw new ClassifierManifestError(`duplicate classifier name: ${manifest.name}`);
+            throw new ClassifierManifestError(`duplicate classifier name: ${manifest.name} — extras cannot override built-ins or other extras. Rename your classifier or run it under a different name.`);
         }
         names.add(manifest.name);
     }
 }
-export const REGISTRY = loadClassifierRegistry();
-export const CLASSIFIER_NAMES = REGISTRY.map((m) => m.name);
-export const MODULES_BY_NAME = Object.fromEntries(REGISTRY.map((m) => [m.name, m]));
-export function validateClassifierOutput(name, value, model) {
-    const manifest = MODULES_BY_NAME[name];
-    if (!manifest) {
-        throw new ClassifierManifestError(`unknown classifier: ${name}`);
-    }
-    return validateOutputForManifest(manifest, value, { classifier: name, model });
+export function validateClassifierOutput(manifest, value, model) {
+    return validateOutputForManifest(manifest, value, { classifier: manifest.name, model });
 }

package/dist/src/classify.d.ts

@@ -1,4 +1,4 @@
-import { type RunClassifier } from "./classifiers.js";
+import { ClassifierManifestError, type ClassifierRegistryBundle, type RunClassifier } from "./classifiers.js";
 import { type OpenClassifyConfig } from "./config.js";
 import type { Catalog, InspectResult, PipelineResult } from "./manifest.js";
 import type { OpenClassifyInput } from "./types.js";
@@ -11,10 +11,12 @@ export type Inspector = (input: OpenClassifyInput, options?: {
 export interface OpenClassify {
     readonly classify: Classifier;
     readonly inspect: Inspector;
+    readonly registry: ClassifierRegistryBundle;
 }
 export interface CreateClassifierOptions {
     runClassifier?: RunClassifier;
     catalog?: Catalog;
+    extraClassifierDirs?: ReadonlyArray<string>;
     config?: OpenClassifyConfig;
     configPath?: string;
     catalogPath?: string;
@@ -27,3 +29,4 @@ export interface CreateClassifierOptions {
     maxConcurrency?: number;
 }
 export declare function createClassifier(options?: CreateClassifierOptions): OpenClassify;
+export { ClassifierManifestError };

package/dist/src/classify.js

@@ -1,9 +1,11 @@
-// High-level facade for the pipeline. Builds the runner and catalog once,
-// then returns two functions — classify() for the 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.
+// High-level facade for the pipeline. Builds the runner, registry, and
+// catalog once, then returns two functions — classify() for the
+// 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 { loadCatalog } from "./catalog.js";
-import { classifierModelsFromConfig, loadOpenClassifyConfig, } from "./config.js";
+import { buildClassifierRegistry, ClassifierManifestError, } from "./classifiers.js";
+import { classifierModelsFromConfig, loadOpenClassifyConfig, OpenClassifyConfigError, } from "./config.js";
 import { assertOllamaResources, createOllamaClassifierRunner, OLLAMA_DEFAULT_CATALOG_PATH, } from "./ollama.js";
 import { classifyOpenClassifyInput, inspectOpenClassifyInput, } from "./pipeline.js";
 export function createClassifier(options = {}) {
@@ -12,6 +14,20 @@ export function createClassifier(options = {}) {
             optional: options.configPath === undefined &&
                 process.env.OPEN_CLASSIFY_CONFIG === undefined,
         });
+    const registryBundle = buildClassifierRegistry({
+        extraDirs: options.extraClassifierDirs,
+    });
+    // Cross-check `runner.models` keys against the loaded registry so a typo
+    // or stale reference fails fast at construction time instead of being
+    // silently ignored by the runner.
+    if (fileConfig?.runner?.models !== undefined) {
+        const known = new Set(registryBundle.names);
+        for (const name of Object.keys(fileConfig.runner.models)) {
+            if (!known.has(name)) {
+                throw new OpenClassifyConfigError(`runner.models.${name} is not a loaded classifier (loaded: ${registryBundle.names.join(", ")})`);
+            }
+        }
+    }
     // When we own the runner, hoist the resource check to the wrapper so a
     // failure surfaces as a top-level rejection — the per-classifier fallback
     // path would otherwise mask it as five "classifier failed" entries.
@@ -19,6 +35,7 @@ export function createClassifier(options = {}) {
     const needsResourceCheck = ownsRunner && !options.skipResourceCheck;
     const runClassifier = options.runClassifier ??
         createOllamaClassifierRunner({
+            modulesByName: registryBundle.modulesByName,
             host: fileConfig?.runner?.host,
             defaultModel: fileConfig?.runner?.defaultModel,
             models: classifierModelsFromConfig(fileConfig),
@@ -43,6 +60,7 @@ export function createClassifier(options = {}) {
         return classifyOpenClassifyInput(input, {
             runClassifier,
             catalog,
+            registry: registryBundle.registry,
             classifierTimeoutMs: options.classifierTimeoutMs,
             classifierRetryCount: options.classifierRetryCount,
             maxConcurrency: options.maxConcurrency,
@@ -53,11 +71,15 @@ export function createClassifier(options = {}) {
         await ensureResources();
         return inspectOpenClassifyInput(input, {
             runClassifier,
+            registry: registryBundle.registry,
             classifierTimeoutMs: options.classifierTimeoutMs,
             classifierRetryCount: options.classifierRetryCount,
             maxConcurrency: options.maxConcurrency,
             signal: callOptions?.signal,
         });
     };
-    return { classify, inspect };
+    return { classify, inspect, registry: registryBundle };
 }
+// 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,4 +1,4 @@
-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;

package/dist/src/config.js

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from "node:fs";
-import { 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 {
@@ -81,12 +80,8 @@ function validateModels(value, path) {
     if (!isRecord(value)) {
         throwConfig(path, "runner.models must be an object");
     }
-    const allowed = new Set(CLASSIFIER_NAMES);
     const out = {};
     for (const [name, model] of Object.entries(value)) {
-        if (!allowed.has(name)) {
-            throwConfig(path, `runner.models.${name} is not a known classifier`);
-        }
         out[name] = requireString(model, path, `runner.models.${name}`);
     }
     return out;

package/dist/src/ollama.d.ts

@@ -1,13 +1,11 @@
-import { type ClassifierName, type RunClassifier } from "./classifiers.js";
+import { type ClassifierModuleMap, type ClassifierName, type RunClassifier } from "./classifiers.js";
 export declare const OLLAMA_DEFAULT_HOST = "http://localhost:11434";
 export declare const OLLAMA_BASE_MODEL = "gemma4:e4b-it-q4_K_M";
 export declare const OLLAMA_BASE_MODEL_NATIVE_CONTEXT_LENGTH = 131072;
-export declare const OLLAMA_REQUIRED_PARALLELISM: number;
 export declare const OLLAMA_DEFAULT_CATALOG_PATH = "downstream-models.json";
 export declare const OLLAMA_CONTEXT_LENGTH = 4096;
 export declare const OLLAMA_MIN_TOTAL_MEMORY_BYTES: number;
 export declare const OLLAMA_MIN_AVAILABLE_MEMORY_BYTES: number;
-export declare const OLLAMA_CLASSIFIER_MODELS: Record<ClassifierName, string | null>;
 export interface OllamaOptions {
     temperature?: number;
     top_p?: number;
@@ -15,14 +13,15 @@ export interface OllamaOptions {
     num_ctx?: number;
 }
 export interface OllamaClassifierRunnerConfig {
+    modulesByName: ClassifierModuleMap;
+    minTotalMemoryBytes?: number;
+    minAvailableMemoryBytes?: number;
     host?: string;
     defaultModel?: string;
     models?: Partial<Record<ClassifierName, string | null>>;
     options?: OllamaOptions;
     fetch?: typeof fetch;
     skipResourceCheck?: boolean;
-    minAvailableMemoryBytes?: number;
-    minTotalMemoryBytes?: number;
 }
 export declare class OllamaClassifierError extends Error {
     readonly classifier: ClassifierName;
@@ -36,7 +35,7 @@ export declare class OllamaResourceError extends Error {
     readonly minAvailableMemoryBytes: number;
     constructor(totalMemoryBytes: number, availableMemoryBytes: number, minTotalMemoryBytes: number, minAvailableMemoryBytes: number);
 }
-export declare function createOllamaClassifierRunner(config?: OllamaClassifierRunnerConfig): RunClassifier;
+export declare function createOllamaClassifierRunner(config: OllamaClassifierRunnerConfig): RunClassifier;
 export declare function assertOllamaResources(options?: {
     minTotalMemoryBytes?: number;
     minAvailableMemoryBytes?: number;

package/dist/src/ollama.js

@@ -10,12 +10,11 @@
 // `classifyOpenClassifyInput` — you don't have to use this module at all.
 import { execFile } from "node:child_process";
 import { promisify } from "node:util";
-import { CLASSIFIER_NAMES, MODULES_BY_NAME, validateClassifierOutput, } from "./classifiers.js";
+import { validateClassifierOutput, } from "./classifiers.js";
 import { ClassifierValidationError, isRecord, } from "./validation.js";
 export const OLLAMA_DEFAULT_HOST = "http://localhost:11434";
 export const OLLAMA_BASE_MODEL = "gemma4:e4b-it-q4_K_M";
 export const OLLAMA_BASE_MODEL_NATIVE_CONTEXT_LENGTH = 131_072;
-export const OLLAMA_REQUIRED_PARALLELISM = CLASSIFIER_NAMES.length;
 export const OLLAMA_DEFAULT_CATALOG_PATH = "downstream-models.json";
 /*
  * Gemma 4 E4B's native context is 131,072 tokens (128K). The reference local
@@ -28,7 +27,6 @@ export const OLLAMA_MIN_TOTAL_MEMORY_BYTES = 16 * 1024 * 1024 * 1024;
 export const OLLAMA_MIN_AVAILABLE_MEMORY_BYTES = 16 * 1024 * 1024 * 1024;
 const ESTIMATED_CHARS_PER_TOKEN = 3;
 const execFileAsync = promisify(execFile);
-export const OLLAMA_CLASSIFIER_MODELS = Object.fromEntries(CLASSIFIER_NAMES.map((name) => [name, null]));
 export class OllamaClassifierError extends Error {
     classifier;
     model;
@@ -45,7 +43,7 @@ export class OllamaResourceError extends Error {
     minTotalMemoryBytes;
     minAvailableMemoryBytes;
     constructor(totalMemoryBytes, availableMemoryBytes, minTotalMemoryBytes, minAvailableMemoryBytes) {
-        super(`Ollama resource check failed: ${formatBytes(totalMemoryBytes)} total and ${formatBytes(availableMemoryBytes)} available; ${formatBytes(minTotalMemoryBytes)} total and ${formatBytes(minAvailableMemoryBytes)} available required for ${OLLAMA_REQUIRED_PARALLELISM} parallel classifiers`);
+        super(`Ollama resource check failed: ${formatBytes(totalMemoryBytes)} total and ${formatBytes(availableMemoryBytes)} available; ${formatBytes(minTotalMemoryBytes)} total and ${formatBytes(minAvailableMemoryBytes)} available required to run classifiers in parallel`);
         this.name = "OllamaResourceError";
         this.totalMemoryBytes = totalMemoryBytes;
         this.availableMemoryBytes = availableMemoryBytes;
@@ -56,7 +54,11 @@ export class OllamaResourceError extends Error {
 // Build a `RunClassifier` bound to a specific Ollama host + model selection.
 // The resource check is lazy and runs once per runner — the first classifier
 // invocation pays for it; subsequent ones reuse the same promise.
-export function createOllamaClassifierRunner(config = {}) {
+export function createOllamaClassifierRunner(config) {
+    if (!config?.modulesByName) {
+        throw new Error("createOllamaClassifierRunner requires `modulesByName` from buildClassifierRegistry()");
+    }
+    const modulesByName = config.modulesByName;
     const host = trimTrailingSlash(config.host ?? OLLAMA_DEFAULT_HOST);
     const fetchImpl = config.fetch ?? fetch;
     const models = config.models ?? {};
@@ -76,9 +78,13 @@ export function createOllamaClassifierRunner(config = {}) {
             });
             await resourceCheck;
         }
+        const manifest = modulesByName[name];
+        if (manifest === undefined) {
+            throw new OllamaClassifierError(name, defaultModel, `unknown classifier "${name}" — not present in registry`);
+        }
         const configuredModel = models[name];
         const model = configuredModel ?? defaultModel;
-        return runOllamaClassifier(name, input, signal, fetchImpl, host, model, options, configuredModel === undefined && !hasDefaultModelOverride);
+        return runOllamaClassifier(manifest, input, signal, fetchImpl, host, model, options, configuredModel === undefined && !hasDefaultModelOverride);
     };
 }
 export async function assertOllamaResources(options = {}) {
@@ -90,10 +96,10 @@ export async function assertOllamaResources(options = {}) {
         throw new OllamaResourceError(totalMemoryBytes, availableMemoryBytes, minTotalMemoryBytes, minAvailableMemoryBytes);
     }
 }
-async function runOllamaClassifier(name, input, signal, fetchImpl, host, model, options, allowManifestModel) {
-    const module_ = MODULES_BY_NAME[name];
-    const systemPrompt = module_.systemPrompt;
-    const configuredBaseModel = module_.backend?.ollama?.base_model;
+async function runOllamaClassifier(manifest, input, signal, fetchImpl, host, model, options, allowManifestModel) {
+    const name = manifest.name;
+    const systemPrompt = manifest.systemPrompt;
+    const configuredBaseModel = manifest.backend?.ollama?.base_model;
     if (allowManifestModel && configuredBaseModel) {
         model = configuredBaseModel;
     }
@@ -137,7 +143,7 @@ async function runOllamaClassifier(name, input, signal, fetchImpl, host, model,
     }
     const parsed = parseJsonObject(content, name, model);
     try {
-        return validateClassifierOutput(name, parsed, model);
+        return validateClassifierOutput(manifest, parsed, model);
     }
     catch (error) {
         if (error instanceof ClassifierValidationError) {

package/dist/src/pipeline.d.ts

@@ -1,5 +1,5 @@
 import { type RunClassifier } from "./classifiers.js";
-import type { Catalog, InspectResult, PipelineResult } from "./manifest.js";
+import type { Catalog, ClassifierRegistry, InspectResult, PipelineResult } from "./manifest.js";
 import type { OpenClassifyInput } from "./types.js";
 export declare const DEFAULT_CLASSIFIER_TIMEOUT_MS = 15000;
 export declare const DEFAULT_CLASSIFIER_RETRY_COUNT = 1;
@@ -10,6 +10,7 @@ export declare class OpenClassifyNormalizationError extends Error {
 export interface ClassifyOptions {
     runClassifier: RunClassifier;
     catalog: Catalog;
+    registry: ClassifierRegistry;
     classifierTimeoutMs?: number;
     classifierRetryCount?: number;
     maxConcurrency?: number;
@@ -17,6 +18,7 @@ export interface ClassifyOptions {
 }
 export interface InspectOptions {
     runClassifier: RunClassifier;
+    registry: ClassifierRegistry;
     classifierTimeoutMs?: number;
     classifierRetryCount?: number;
     maxConcurrency?: number;

package/dist/src/pipeline.js

@@ -1,5 +1,4 @@
 import { assembleResult, buildPublicOutputs } from "./aggregator.js";
-import { MODULES_BY_NAME, REGISTRY, } from "./classifiers.js";
 import { normalizeOpenClassifyInput, toClassifierInput } from "./input.js";
 export const DEFAULT_CLASSIFIER_TIMEOUT_MS = 15_000;
 export const DEFAULT_CLASSIFIER_RETRY_COUNT = 1;
@@ -12,7 +11,7 @@ export class OpenClassifyNormalizationError extends Error {
 }
 export async function classifyOpenClassifyInput(input, options) {
     const { request, results, failedClassifiers } = await runPipeline(input, "user", options);
-    const reg = filteredRegistry("user");
+    const reg = filteredRegistry(options.registry, "user");
     const assembled = assembleResult({
         registry: reg,
         results,
@@ -26,7 +25,7 @@ export async function classifyOpenClassifyInput(input, options) {
 }
 export async function inspectOpenClassifyInput(input, options) {
     const { request, results } = await runPipeline(input, "assistant", options);
-    const reg = filteredRegistry("assistant");
+    const reg = filteredRegistry(options.registry, "assistant");
     const lastMsg = request.messages[request.messages.length - 1];
     return {
         target_message_hash: request.target_message_hash,
@@ -56,19 +55,19 @@ async function runPipeline(input, role, options) {
     const classifierTimeoutMs = options.classifierTimeoutMs ?? DEFAULT_CLASSIFIER_TIMEOUT_MS;
     const classifierRetryCount = options.classifierRetryCount ?? DEFAULT_CLASSIFIER_RETRY_COUNT;
     const maxConcurrency = resolveMaxConcurrency(options.maxConcurrency);
-    const registry = filteredRegistry(role);
+    const registry = filteredRegistry(options.registry, role);
     const queue = registry.map((m) => m.name);
     try {
         const settled = await runWithConcurrency(queue, maxConcurrency, controller.signal, (name) => runClassifierWithRetry(name, classifierInput, options.runClassifier, controller.signal, classifierTimeoutMs, classifierRetryCount));
-        const { results, failedClassifiers } = collectResults(settled);
+        const { results, failedClassifiers } = collectResults(registry, settled);
         return { request, results, failedClassifiers };
     }
     finally {
         options.signal?.removeEventListener("abort", abortFromOptions);
     }
 }
-function filteredRegistry(role) {
-    return REGISTRY.filter((m) => roleAppliesTo(m.appliesTo, role));
+function filteredRegistry(registry, role) {
+    return registry.filter((m) => roleAppliesTo(m.appliesTo, role));
 }
 function roleAppliesTo(appliesTo, role) {
     return appliesTo === "both" || appliesTo === role;
@@ -107,12 +106,18 @@ async function runWithConcurrency(names, maxConcurrency, signal, start) {
     await Promise.all(Array.from({ length: workerCount }, () => worker()));
     return results;
 }
-function collectResults(settled) {
+function collectResults(registry, settled) {
+    const fallbackByName = new Map();
+    for (const m of registry)
+        fallbackByName.set(m.name, m.fallback);
     const results = {};
     const failedClassifiers = [];
     for (const s of settled) {
-        const manifest = MODULES_BY_NAME[s.name];
-        results[s.name] = s.ok ? s.value : manifest.fallback;
+        const fallback = fallbackByName.get(s.name);
+        if (fallback === undefined) {
+            throw new Error(`pipeline: classifier "${s.name}" missing from registry`);
+        }
+        results[s.name] = s.ok ? s.value : fallback;
         if (!s.ok)
             failedClassifiers.push(s.name);
     }

package/docs/adding-a-classifier.md

@@ -1,20 +1,27 @@
 # Adding a classifier
 
-Every classifier — reserved-field-bearing or pure custom — 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 — 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.
+
+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 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.
 
 ## 1. Create the directory
 
 ```
-src/classifiers/<name>/
+classifiers/<name>/
 ├── manifest.json
 └── prompt.md
 ```
 
-The directory name must match `manifest.json`'s `name` field. Top-level directories starting with `_` (like `_prompts/`) are reserved for shared assets and skipped by the loader.
+The directory name must match `manifest.json`'s `name` field. Directories starting with `_` are skipped by the loader — that's the deactivation mechanism (`_topic_tags/` is inert; rename to `topic_tags/` to activate).
 
 ## 2. Write the manifest
 
-Minimal example — a pure-custom classifier that emits tags. You don't need to provide JSON examples; the runtime synthesizes one from your schema and shows it to the model.
+Minimal example — a pure-custom classifier that emits tags. The runtime synthesizes a JSON example from your schema, so you don't need to write one.
 
 ```json
 {
@@ -39,8 +46,6 @@ Minimal example — a pure-custom classifier that emits tags. You don't need to
 }
 ```
 
-If your classifier's behavior is nuanced enough that hand-picked examples would help the model (preflight is one), add an `output_schema.examples` array. The runtime validates each example against the composed schema at load time, so a broken example fails the build.
-
 To also influence routing, opt into a reserved field:
 
 ```json
@@ -73,6 +78,7 @@ Rules:
 - `reason` and `certainty` are added to the composed schema by the runtime — don't declare them.
 - `fallback` must validate against the composed schema. Only `reason` and `certainty` are required in fallback; reserved fields and `output_schema.required` fields are exempt (a "no signal" fallback usually omits them).
 - `output_schema.examples` (JSON Schema standard) must validate against the composed schema at load time, so a broken example fails the build, not the model call.
+- **Name collisions throw.** Extras cannot override the mandatory built-ins (`preflight`, `model_tier`, `model_specialization`, `prompt_injection`). To customize one of those, use a custom `RunClassifier` to intercept it (see "Replacing the backend" below).
 
 See [manifests.md](manifests.md) for the full field list.
 
@@ -90,24 +96,37 @@ Do not invent tags for vague or ambiguous messages.
 
 Don't paste enum values for reserved fields — the runtime injects them with canonical wording so they never drift from `src/enums.ts`.
 
-## 4. Build and test
+## 4. Use it
 
-```sh
-npm run build   # validates the manifest, composes the schema, copies assets
-npm test
-```
+After `npx open-classify init`, your `classifiers/` directory already exists. Drop your folder in and point `createClassifier` at the parent dir:
 
-If the manifest is malformed, the loader throws `ClassifierManifestError` with the path and a specific reason.
+```ts
+import { createClassifier } from "open-classify";
 
-## 5. Consume the output
+const { classify } = createClassifier({
+  extraClassifierDirs: ["./classifiers"],
+});
+
+const result = await classify({
+  messages: [{ role: "user", text: "Can you review the attached contract?" }],
+});
 
-```ts
-const { classify } = createClassifier({ catalog });
-const result = await classify(input);
 const tags = result.classifier_outputs.topic_tags?.tags ?? [];
 ```
 
-`classifier_outputs[name]` includes all payload fields plus `reason` (string) and `certainty` (float).
+> 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(...)`.
+
+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
+
+`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:
+
+```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.
 
 ## Targeting the assistant response
 
@@ -134,7 +153,7 @@ The built-in `prompt_injection` ships tagged `"both"` so it runs on both sides.
 
 ## Choosing the classifier model
 
-For apps and OSS installs, prefer `open-classify.config.json`:
+In `open-classify.config.json`:
 
 ```json
 {
@@ -148,9 +167,9 @@ For apps and OSS installs, prefer `open-classify.config.json`:
 }
 ```
 
-`runner.defaultModel` applies to every classifier without an override. `runner.models` is a flat map keyed by classifier name — there is no separate stock/custom split.
+`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.
 
-Classifier manifests may also carry an Ollama hint for packaged classifiers:
+Classifier manifests may also carry an Ollama hint:
 
 ```json
 {
@@ -162,15 +181,17 @@ Config file and function options take precedence over manifest hints.
 
 ## Replacing the backend
 
-For full backend control, implement your own `RunClassifier` and pass it to `classifyOpenClassifyInput`:
+For full backend control — including replacing a mandatory built-in like `preflight` — implement your own `RunClassifier` and pass it to `createClassifier`:
 
 ```ts
-import { classifyOpenClassifyInput, loadCatalog } from "open-classify";
+import { createClassifier, type RunClassifier } from "open-classify";
 
 const runClassifier: RunClassifier = async (name, input, signal) => {
-  // call OpenAI, Anthropic, a remote service, etc.
-  // return a ClassifierOutput matching the classifier's composed schema.
+  if (name === "preflight") {
+    // call OpenAI / Anthropic / your own logic; return a ClassifierOutput.
+  }
+  // …handle other classifiers, or delegate to the Ollama runner you imported.
 };
 
-await classifyOpenClassifyInput(input, { runClassifier, catalog: loadCatalog(...) });
+const { classify } = createClassifier({ runClassifier });
 ```

package/open-classify.config.example.json

@@ -13,9 +13,7 @@
       "preflight": "gemma4:e4b-it-q4_K_M",
       "model_tier": "gemma4:e4b-it-q4_K_M",
       "model_specialization": "gemma4:e4b-it-q4_K_M",
-      "tools": "gemma4:e4b-it-q4_K_M",
-      "prompt_injection": "gemma4:e4b-it-q4_K_M",
-      "memory_retrieval_queries": "gemma4:e4b-it-q4_K_M"
+      "prompt_injection": "gemma4:e4b-it-q4_K_M"
     }
   },
   "catalog": "downstream-models.json"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-classify",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "description": "Manifest-driven classifier runtime for routing user messages to downstream AI models",
   "license": "MIT",
   "author": "Taylor Bayouth",
@@ -29,11 +29,16 @@
       "default": "./dist/src/index.js"
     }
   },
+  "bin": {
+    "open-classify": "./bin/open-classify.mjs"
+  },
   "files": [
+    "bin",
     "dist/src",
     "docs",
     "downstream-models.json",
     "open-classify.config.example.json",
+    "templates",
     "LICENSE",
     "README.md"
   ],