@cruxy/cli 0.3.0 → 0.4.0

package/README.md

@@ -70,6 +70,27 @@ Add a skill by creating `<name>/SKILL.md` under `.cruxy/skills/` (project) or
 `~/.cruxy/skills/` (user); shipped builtins are the lowest layer. See the
 built-in `using-skills` skill for the authoring rules.
 
+## Errors & exit codes
+
+Every user-facing error prints a title, the cause (when known), concrete next
+steps, and a stable code (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`). Pass `--verbose`
+(or `--log-level debug` / `DEBUG=1`) to see the underlying error and stack;
+`NO_COLOR` disables color. Exit codes are stable per category, so scripts can
+branch on them:
+
+| Exit | Category   | Example codes                                                                                   |
+| ---- | ---------- | ----------------------------------------------------------------------------------------------- |
+| `0`  | success    | —                                                                                               |
+| `1`  | internal   | `CRUXY_E_INTERNAL`                                                                              |
+| `2`  | usage      | `CRUXY_E_USAGE`, `CRUXY_E_CONFIG_KEY_UNKNOWN`, `CRUXY_E_PROVIDER_UNSUPPORTED`                   |
+| `3`  | config     | `CRUXY_E_CONFIG_PARSE`, `CRUXY_E_CONFIG_INVALID`                                                |
+| `4`  | auth       | `CRUXY_E_AUTH_MISSING_KEY`, `CRUXY_E_AUTH_INVALID`                                              |
+| `5`  | network    | `CRUXY_E_GATEWAY_UNREACHABLE`                                                                   |
+| `6`  | api        | `CRUXY_E_API`, `CRUXY_E_API_RATE_LIMIT`, `CRUXY_E_API_OVERLOADED`, `CRUXY_E_BUDGET_EXHAUSTED`   |
+| `7`  | filesystem | `CRUXY_E_FILE_NOT_FOUND`, `CRUXY_E_PERMISSION_DENIED`, `CRUXY_E_PATH_ESCAPE`                    |
+| `8`  | index      | `CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE`, `CRUXY_E_INDEX_STORE_UNAVAILABLE`, `CRUXY_E_INDEX_FAILED` |
+| `9`  | skill      | `CRUXY_E_SKILL_INVALID`, `CRUXY_E_SKILL_NOT_FOUND`                                              |
+
 The LLM client is [`@cruxy/sdk`](https://www.npmjs.com/package/@cruxy/sdk) —
 provider-agnostic, built over `fetch`, with no vendor SDKs.
 

package/dist/agent/loop.js

@@ -1,3 +1,4 @@
+import { providerUnsupported } from "../errors/index.js";
 import { buildSystemPrompt } from "./prompts.js";
 /**
  * Drive the model/tool loop over an existing conversation. Streams each turn,
@@ -11,7 +12,7 @@ import { buildSystemPrompt } from "./prompts.js";
 export async function runAgent(args) {
     const { provider, registry, config, ctx } = args;
     if (!provider.supportsTools) {
-        throw new Error(`provider ${config.model.provider} does not support tool use; cruxy run requires a tool-capable provider`);
+        throw providerUnsupported(config.model.provider);
     }
     const { logger } = ctx;
     // Work on a copy so we never mutate the caller's array as a side effect; the

package/dist/cli/commands/config.js

@@ -1,5 +1,6 @@
 import { Command } from "commander";
 import pc from "picocolors";
+import { configKeyUnknown } from "../../errors/index.js";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, getPath, setValue, initConfig, globalConfigPath, findProjectConfig, } from "../../config/index.js";
 export function configCommand() {
@@ -19,9 +20,7 @@ export function configCommand() {
         const { config } = loadConfig();
         const value = getPath(config, key);
         if (value === undefined) {
-            logger.error(`no such config key: ${pc.bold(key)}`);
-            process.exitCode = 1;
-            return;
+            throw configKeyUnknown(key);
         }
         logger.print(typeof value === "object"
             ? JSON.stringify(value, null, 2)

package/dist/cli/commands/index.js

@@ -2,6 +2,7 @@ import { existsSync } from "node:fs";
 import { Command } from "commander";
 import pc from "picocolors";
 import { loadConfig } from "../../config/index.js";
+import { CruxyError, indexFailed } from "../../errors/index.js";
 import { getIndexService, indexDbPath, resetIndexServices, } from "../../indexing/index.js";
 import { logger } from "../../utils/logger.js";
 /**
@@ -41,8 +42,10 @@ export function indexCommand() {
                 pc.dim(`(${stats.filesSkipped} unchanged, ${stats.filesPurged} purged, ${stats.durationMs}ms)`));
         }
         catch (err) {
-            logger.error(`indexing failed: ${err.message}`);
-            process.exitCode = 1;
+            // Typed index failures (embedder/store unavailable) already carry a
+            // code; anything else becomes CRUXY_E_INDEX_FAILED. The boundary formats
+            // and sets the exit code.
+            throw err instanceof CruxyError ? err : indexFailed(err);
         }
         finally {
             await resetIndexServices();

package/dist/cli/commands/run.js

@@ -3,6 +3,7 @@ import pc from "picocolors";
 import { createProvider } from "@cruxy/sdk";
 import { logger } from "../../utils/logger.js";
 import { loadConfig, resolveApiKey, loadProjectInstructions, } from "../../config/index.js";
+import { authMissingKey, usageError } from "../../errors/index.js";
 import { buildDefaultRegistry } from "../../tools/index.js";
 import { Session, createApprover } from "../../agent/index.js";
 import { runInteractive } from "../repl.js";
@@ -20,16 +21,14 @@ export function runCommand() {
         // No prompt and stdin isn't a terminal: there's no way to read input and
         // nothing to do — fail fast instead of hanging on a line that never comes.
         if (interactive && !process.stdin.isTTY) {
-            logger.error('cruxy run needs a prompt when stdin is not a terminal — try: cruxy run "<task>"');
-            return;
+            throw usageError("cruxy run needs a prompt when stdin is not a terminal", ['provide a task, e.g. cruxy run "fix the failing test"']);
         }
         const { config, sources } = loadConfig();
         const apiKey = resolveApiKey(config.model.provider);
         logger.info(pc.dim(`model:   ${config.model.provider}/${config.model.model}`));
         logger.info(pc.dim(`config:  ${sources.project ?? sources.global ?? "defaults"}`));
         if (!apiKey) {
-            logger.warn(`no API key for provider ${pc.bold(config.model.provider)} — set it in the environment before running.`);
-            return;
+            throw authMissingKey(config.model.provider, apiKeyEnvVar(config.model.provider));
         }
         const provider = createProvider({
             provider: config.model.provider,
@@ -72,14 +71,23 @@ export function runCommand() {
         // through a printer that trims the model's leading blank lines; the agent
         // loop terminates the line.
         logger.print(`${pc.cyan("cruxy")} ${pc.dim("›")} ${prompt}\n`);
-        try {
-            const print = createStreamPrinter((text) => process.stdout.write(text));
-            const result = await session.send(prompt, print);
-            logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
-                `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
-        }
-        catch (err) {
-            logger.error(err.message);
-        }
+        // Provider/network/auth failures propagate to the top-level boundary,
+        // which classifies them (e.g. CRUXY_E_GATEWAY_UNREACHABLE) and exits with
+        // the matching code — a one-shot run must fail non-zero on error.
+        const print = createStreamPrinter((text) => process.stdout.write(text));
+        const result = await session.send(prompt, print);
+        logger.debug(`agent finished: ${result.stop} after ${result.iterations} turn(s); ` +
+            `tokens in/out ${result.usage.input_tokens}/${result.usage.output_tokens}`);
     });
 }
+/** Environment variable that holds the API key for a provider. */
+function apiKeyEnvVar(provider) {
+    switch (provider) {
+        case "anthropic":
+            return "ANTHROPIC_API_KEY";
+        case "openai":
+            return "OPENAI_API_KEY";
+        default:
+            return "CRUXY_API_KEY";
+    }
+}

package/dist/cli/program.js

@@ -2,6 +2,7 @@ import { Command } from "commander";
 import pc from "picocolors";
 import { APP_NAME, APP_VERSION, APP_DESCRIPTION } from "../constants.js";
 import { logger } from "../utils/logger.js";
+import { usageError } from "../errors/index.js";
 import { runCommand } from "./commands/run.js";
 import { configCommand } from "./commands/config.js";
 import { indexCommand } from "./commands/index.js";
@@ -14,8 +15,7 @@ export function buildProgram() {
         .version(APP_VERSION, "-v, --version", "print the cruxy version")
         .option("-c, --config <path>", "use a specific config file")
         .option("--log-level <level>", "debug | info | warn | error | silent")
-        .option("--verbose", "shorthand for --log-level debug")
-        .showHelpAfterError("(run `cruxy --help` for usage)");
+        .option("--verbose", "shorthand for --log-level debug");
     // Apply global options as early as possible.
     program.hook("preAction", (thisCommand) => {
         const opts = thisCommand.opts();
@@ -28,13 +28,33 @@ export function buildProgram() {
     program.addCommand(configCommand());
     program.addCommand(indexCommand());
     program.addCommand(skillsCommand());
-    // Default action: no subcommand -> interactive entrypoint (stub for now).
-    program.action(() => {
+    // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
+    // means an unknown command (Commander runs the default action with it as an
+    // operand rather than erroring), so reject it as a usage error.
+    program.action((_opts, command) => {
+        if (command.args.length > 0) {
+            throw usageError(`unknown command: ${command.args[0]}`, [
+                "run `cruxy --help` to see available commands",
+            ]);
+        }
         logger.print(pc.cyan(`${APP_NAME} v${APP_VERSION}`));
         logger.print(pc.dim("an agentic coding CLI\n"));
         logger.print("The interactive REPL lands in C.3 (terminal UI).");
         logger.print(`For now try:  ${pc.bold('cruxy run "<task>"')}  or  ${pc.bold("cruxy config path")}`);
         logger.print(`See all commands:  ${pc.bold("cruxy --help")}`);
     });
+    // Throw CommanderError instead of calling process.exit, and suppress
+    // Commander's own "error:" line — so parse errors (unknown command/option,
+    // missing argument) at *any* level route through the single error boundary as
+    // CRUXY_E_USAGE, sharing one exit code (2) and format. Applied recursively
+    // because these settings are not inherited by subcommands.
+    routeErrorsToBoundary(program);
     return program;
 }
+/** Recursively make a command (and its subcommands) throw on error, silently. */
+function routeErrorsToBoundary(command) {
+    command.exitOverride();
+    command.configureOutput({ outputError: () => { } });
+    for (const sub of command.commands)
+        routeErrorsToBoundary(sub);
+}

package/dist/cli/repl.js

@@ -1,5 +1,6 @@
 import readline from "node:readline";
 import pc from "picocolors";
+import { formatError, fromUnknown, isVerbose, shouldUseColor, } from "../errors/index.js";
 import { logger } from "../utils/logger.js";
 import { createStreamPrinter } from "./stream-print.js";
 const PROMPT = `${pc.cyan("cruxy")} ${pc.dim("›")} `;
@@ -49,6 +50,18 @@ function readLine(io, prompt) {
         });
     });
 }
+/**
+ * Render a non-fatal error inline (classified + formatted, the same 4-part
+ * shape as the fatal boundary) and return to the prompt — the REPL must survive
+ * a failed turn rather than exit.
+ */
+function printReplError(err) {
+    const cruxy = fromUnknown(err);
+    logger.print(formatError(cruxy, {
+        verbose: isVerbose(),
+        color: shouldUseColor(process.stdout),
+    }));
+}
 /**
  * Drive an interactive multi-turn session: prompt, read a line, dispatch slash
  * commands or run a turn, repeat. Assistant text streams to stdout from within
@@ -83,7 +96,7 @@ export async function runInteractive(session, io = defaultIO()) {
                 logger.print(pc.dim(n ? `compacted ${n} older messages` : "nothing to compact yet"));
             }
             catch (err) {
-                logger.error(err.message);
+                printReplError(err);
             }
             continue;
         }

package/dist/config/manager.js

@@ -1,5 +1,6 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
+import { configInvalid, configParse } from "../errors/index.js";
 import { CruxyConfigSchema } from "./schema.js";
 import { globalConfigPath, findProjectConfig } from "./paths.js";
 function isPlainObject(v) {
@@ -23,13 +24,13 @@ function readJsonFile(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
         if (!isPlainObject(parsed)) {
-            throw new Error(`config at ${path} must be a JSON object`);
+            throw configParse(path, new Error("top-level value is not a JSON object"));
         }
         return parsed;
     }
     catch (err) {
         if (err instanceof SyntaxError) {
-            throw new Error(`config at ${path} is not valid JSON: ${err.message}`);
+            throw configParse(path, err);
         }
         throw err;
     }
@@ -81,7 +82,7 @@ export function loadConfig(opts = {}) {
         const issues = result.error.issues
             .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
             .join("\n");
-        throw new Error(`invalid configuration:\n${issues}`);
+        throw configInvalid(issues, sources.project ?? sources.global ?? undefined);
     }
     return { config: result.data, sources };
 }
@@ -121,7 +122,7 @@ export function setValue(path, rawValue, file) {
         const issues = check.error.issues
             .map((i) => `  - ${i.path.join(".") || "(root)"}: ${i.message}`)
             .join("\n");
-        throw new Error(`refusing to write invalid config:\n${issues}`);
+        throw configInvalid(issues, file);
     }
     mkdirSync(dirname(file), { recursive: true });
     writeFileSync(file, JSON.stringify(current, null, 2) + "\n", "utf8");

package/dist/errors/boundary.d.ts

@@ -0,0 +1,43 @@
+import { type Formatter } from "./format.js";
+import { CruxyError } from "./types.js";
+/**
+ * The single top-level error boundary. {@link handleFatal} classifies any thrown
+ * value into a {@link CruxyError}, formats it, writes it to stderr, and exits
+ * with the error's stable exit code. Nothing escapes to a raw Node stack trace:
+ * an unknown error becomes {@link internal} (CRUXY_E_INTERNAL) with a
+ * bug-report hint, and the underlying stack is shown only under `--verbose`.
+ */
+/**
+ * Normalize any thrown value into a {@link CruxyError}:
+ * - already a CruxyError → returned as-is;
+ * - a Commander parse error → a usage error (CRUXY_E_USAGE);
+ * - a known provider/transport error → its mapped code;
+ * - anything else → CRUXY_E_INTERNAL, preserving the original as `underlying`.
+ */
+export declare function fromUnknown(err: unknown): CruxyError;
+/** A Commander "error" that's actually success (`--help`, `--version`). */
+export declare function isCommanderSuccess(err: unknown): boolean;
+export interface HandleFatalOptions {
+    /** Show the underlying error/stack. Defaults to {@link isVerbose}(). */
+    verbose?: boolean;
+    /** Override the formatter (e.g. a future JSON formatter). */
+    formatter?: Formatter;
+    /** Force color on/off. Defaults to {@link shouldUseColor}(). */
+    color?: boolean;
+    /** Sink for the formatted output (default: stderr). For tests. */
+    write?: (text: string) => void;
+    /** Process exit (default: process.exit). For tests. */
+    exit?: (code: number) => never;
+}
+/**
+ * Classify → format → print → exit. Install this as the *only* catch at the CLI
+ * entry. `write`/`exit` are injectable so the boundary is testable without
+ * touching the real process.
+ */
+export declare function handleFatal(err: unknown, opts?: HandleFatalOptions): never;
+/**
+ * Whether the invocation requested verbose output: `--verbose`,
+ * `--log-level debug`, `DEBUG`, or `CRUXY_LOG_LEVEL=debug`. Read from argv/env so
+ * it works even when a failure happens before the CLI finishes parsing flags.
+ */
+export declare function isVerbose(argv?: string[], env?: NodeJS.ProcessEnv): boolean;

package/dist/errors/boundary.js

@@ -0,0 +1,73 @@
+import { CommanderError } from "commander";
+import { classifyProviderError, internal, usageError } from "./constructors.js";
+import { shouldUseColor, terminalFormatter } from "./format.js";
+import { CruxyError } from "./types.js";
+/**
+ * The single top-level error boundary. {@link handleFatal} classifies any thrown
+ * value into a {@link CruxyError}, formats it, writes it to stderr, and exits
+ * with the error's stable exit code. Nothing escapes to a raw Node stack trace:
+ * an unknown error becomes {@link internal} (CRUXY_E_INTERNAL) with a
+ * bug-report hint, and the underlying stack is shown only under `--verbose`.
+ */
+/**
+ * Normalize any thrown value into a {@link CruxyError}:
+ * - already a CruxyError → returned as-is;
+ * - a Commander parse error → a usage error (CRUXY_E_USAGE);
+ * - a known provider/transport error → its mapped code;
+ * - anything else → CRUXY_E_INTERNAL, preserving the original as `underlying`.
+ */
+export function fromUnknown(err) {
+    if (err instanceof CruxyError)
+        return err;
+    if (err instanceof CommanderError) {
+        return usageError(stripErrorPrefix(err.message));
+    }
+    return classifyProviderError(err) ?? internal(err);
+}
+/** A Commander "error" that's actually success (`--help`, `--version`). */
+export function isCommanderSuccess(err) {
+    return err instanceof CommanderError && err.exitCode === 0;
+}
+/**
+ * Classify → format → print → exit. Install this as the *only* catch at the CLI
+ * entry. `write`/`exit` are injectable so the boundary is testable without
+ * touching the real process.
+ */
+export function handleFatal(err, opts = {}) {
+    const cruxy = fromUnknown(err);
+    const verbose = opts.verbose ?? isVerbose();
+    const color = opts.color ?? shouldUseColor();
+    const formatter = opts.formatter ?? terminalFormatter;
+    const write = opts.write ?? ((text) => void process.stderr.write(text));
+    const exit = opts.exit ?? ((code) => process.exit(code));
+    write(`${formatter.format(cruxy, { verbose, color })}\n`);
+    return exit(cruxy.exitCode);
+}
+/**
+ * Whether the invocation requested verbose output: `--verbose`,
+ * `--log-level debug`, `DEBUG`, or `CRUXY_LOG_LEVEL=debug`. Read from argv/env so
+ * it works even when a failure happens before the CLI finishes parsing flags.
+ */
+export function isVerbose(argv = process.argv, env = process.env) {
+    if (argv.includes("--verbose"))
+        return true;
+    if (argv.includes("--log-level=debug"))
+        return true;
+    const idx = argv.indexOf("--log-level");
+    if (idx !== -1 && argv[idx + 1] === "debug")
+        return true;
+    if (env.CRUXY_LOG_LEVEL === "debug")
+        return true;
+    const debug = env.DEBUG;
+    if (debug !== undefined &&
+        debug !== "" &&
+        debug !== "0" &&
+        debug !== "false") {
+        return true;
+    }
+    return false;
+}
+/** Strip Commander's leading "error: " so the title reads cleanly. */
+function stripErrorPrefix(message) {
+    return message.replace(/^error:\s*/i, "");
+}

package/dist/errors/constructors.d.ts

@@ -0,0 +1,27 @@
+import { CruxyError } from "./types.js";
+/** Best-effort human message for an arbitrary thrown value. */
+export declare function messageOf(underlying: unknown): string | undefined;
+export declare function usageError(title: string, nextSteps?: string[]): CruxyError;
+export declare function configKeyUnknown(key: string): CruxyError;
+export declare function providerUnsupported(provider: string): CruxyError;
+export declare function configParse(path: string, underlying?: unknown): CruxyError;
+export declare function configInvalid(issues: string, path?: string): CruxyError;
+export declare function authMissingKey(provider: string, envVar: string): CruxyError;
+export declare function authInvalid(underlying?: unknown): CruxyError;
+export declare function gatewayUnreachable(underlying?: unknown): CruxyError;
+export declare function apiError(underlying?: unknown): CruxyError;
+export declare function apiRateLimit(underlying?: unknown): CruxyError;
+export declare function apiOverloaded(underlying?: unknown): CruxyError;
+export declare function budgetExhausted(underlying?: unknown): CruxyError;
+export declare function fileNotFound(path: string, underlying?: unknown): CruxyError;
+export declare function permissionDenied(path: string, underlying?: unknown): CruxyError;
+export declare function indexEmbedderUnavailable(underlying?: unknown): CruxyError;
+export declare function indexStoreUnavailable(underlying?: unknown): CruxyError;
+export declare function indexFailed(underlying?: unknown): CruxyError;
+export declare function internal(underlying?: unknown): CruxyError;
+/**
+ * Map a known provider/transport error (from `@cruxy/sdk`) to a typed
+ * {@link CruxyError}, or `null` if it isn't one. Order matters: specific
+ * subclasses before the `ApiError` base.
+ */
+export declare function classifyProviderError(underlying: unknown): CruxyError | null;

package/dist/errors/constructors.js

@@ -0,0 +1,246 @@
+import { ApiError, AuthError, NetworkError, OverloadedError, RateLimitError, } from "@cruxy/sdk";
+import { CruxyError, ErrorCode } from "./types.js";
+/**
+ * Helper constructors for {@link CruxyError}. Each encodes the title, the human
+ * cause, and the concrete next steps for one failure mode, so call sites stay a
+ * one-liner and the wording lives in one place. Lower-level errors are passed as
+ * `underlying` (preserved, shown only under `--verbose`).
+ */
+const ISSUE_URL = "https://github.com/cruxy-ai/cli/issues";
+/** Best-effort human message for an arbitrary thrown value. */
+export function messageOf(underlying) {
+    if (underlying instanceof Error)
+        return underlying.message;
+    if (underlying === undefined || underlying === null)
+        return undefined;
+    return String(underlying);
+}
+// ── usage (exit 2) ────────────────────────────────────────────────────────────
+export function usageError(title, nextSteps) {
+    return new CruxyError({
+        code: ErrorCode.Usage,
+        title,
+        nextSteps: nextSteps ?? ["run `cruxy --help` for usage"],
+    });
+}
+export function configKeyUnknown(key) {
+    return new CruxyError({
+        code: ErrorCode.ConfigKeyUnknown,
+        title: `no such config key: ${key}`,
+        nextSteps: ["run `cruxy config list` to see all available keys"],
+        meta: { key },
+    });
+}
+export function providerUnsupported(provider) {
+    return new CruxyError({
+        code: ErrorCode.ProviderUnsupported,
+        title: `provider "${provider}" does not support tool use`,
+        cause: "cruxy run drives an agent loop, which requires a tool-capable provider",
+        nextSteps: [
+            "switch to a tool-capable provider, e.g. `cruxy config set model.provider anthropic`",
+        ],
+        meta: { provider },
+    });
+}
+// ── config (exit 3) ───────────────────────────────────────────────────────────
+export function configParse(path, underlying) {
+    return new CruxyError({
+        code: ErrorCode.ConfigParse,
+        title: `could not parse config file: ${path}`,
+        cause: messageOf(underlying),
+        nextSteps: [
+            "fix the JSON syntax, or delete the file to fall back to defaults",
+        ],
+        underlying,
+        meta: { path },
+    });
+}
+export function configInvalid(issues, path) {
+    return new CruxyError({
+        code: ErrorCode.ConfigInvalid,
+        title: "the configuration is invalid",
+        cause: issues,
+        nextSteps: [
+            "correct the reported field(s)",
+            "see valid keys with `cruxy config list`",
+        ],
+        meta: path ? { path } : undefined,
+    });
+}
+// ── auth (exit 4) ─────────────────────────────────────────────────────────────
+export function authMissingKey(provider, envVar) {
+    return new CruxyError({
+        code: ErrorCode.AuthMissingKey,
+        title: `no API key for provider "${provider}"`,
+        cause: `the ${envVar} environment variable is not set`,
+        nextSteps: [
+            `export ${envVar}=… in your shell (keys are read from the environment, never from config)`,
+        ],
+        meta: { provider, envVar },
+    });
+}
+export function authInvalid(underlying) {
+    return new CruxyError({
+        code: ErrorCode.AuthInvalid,
+        title: "the provider rejected your credentials",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "verify your API key is correct and active",
+            "re-export the key and try again",
+        ],
+        underlying,
+    });
+}
+// ── network (exit 5) ──────────────────────────────────────────────────────────
+export function gatewayUnreachable(underlying) {
+    return new CruxyError({
+        code: ErrorCode.GatewayUnreachable,
+        title: "could not reach the model gateway",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "check your internet connection",
+            "verify the gateway URL with `cruxy config get cruxy.gatewayUrl`",
+            "retry in a moment",
+        ],
+        underlying,
+    });
+}
+// ── api (exit 6) ──────────────────────────────────────────────────────────────
+export function apiError(underlying) {
+    const status = underlying instanceof ApiError ? underlying.status : undefined;
+    return new CruxyError({
+        code: ErrorCode.Api,
+        title: status
+            ? `the model provider returned an error (HTTP ${status})`
+            : "the model provider returned an error",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "retry in a moment; if it persists, check the provider's status",
+        ],
+        underlying,
+        meta: status ? { status } : undefined,
+    });
+}
+export function apiRateLimit(underlying) {
+    const retryAfterMs = underlying instanceof RateLimitError ? underlying.retryAfterMs : undefined;
+    return new CruxyError({
+        code: ErrorCode.ApiRateLimit,
+        title: "rate limited by the model provider",
+        cause: messageOf(underlying),
+        nextSteps: [
+            retryAfterMs
+                ? `wait ~${Math.ceil(retryAfterMs / 1000)}s and retry`
+                : "wait a moment and retry",
+        ],
+        underlying,
+        meta: retryAfterMs ? { retryAfterMs } : undefined,
+    });
+}
+export function apiOverloaded(underlying) {
+    return new CruxyError({
+        code: ErrorCode.ApiOverloaded,
+        title: "the model provider is overloaded",
+        cause: messageOf(underlying),
+        nextSteps: ["retry in a few moments"],
+        underlying,
+    });
+}
+export function budgetExhausted(underlying) {
+    return new CruxyError({
+        code: ErrorCode.BudgetExhausted,
+        title: "your Cruxy budget is exhausted",
+        cause: messageOf(underlying),
+        nextSteps: ["top up or raise your budget, then retry"],
+        underlying,
+    });
+}
+// ── filesystem (exit 7) ───────────────────────────────────────────────────────
+export function fileNotFound(path, underlying) {
+    return new CruxyError({
+        code: ErrorCode.FileNotFound,
+        title: `file not found: ${path}`,
+        cause: messageOf(underlying),
+        nextSteps: ["check the path and try again"],
+        underlying,
+        meta: { path },
+    });
+}
+export function permissionDenied(path, underlying) {
+    return new CruxyError({
+        code: ErrorCode.PermissionDenied,
+        title: `permission denied: ${path}`,
+        cause: messageOf(underlying),
+        nextSteps: ["check the file's permissions, or run with the right user"],
+        underlying,
+        meta: { path },
+    });
+}
+// ── index (exit 8) ────────────────────────────────────────────────────────────
+export function indexEmbedderUnavailable(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexEmbedderUnavailable,
+        title: "the local embedding model (fastembed) could not be loaded",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "reinstall dependencies with `pnpm install`",
+            "ensure the native onnxruntime-node addon built for your platform",
+        ],
+        underlying,
+    });
+}
+export function indexStoreUnavailable(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexStoreUnavailable,
+        title: "the codebase index store (SQLite) is unavailable",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "reinstall dependencies with `pnpm install` (better-sqlite3 must build), or set index.store = memory",
+        ],
+        underlying,
+    });
+}
+export function indexFailed(underlying) {
+    return new CruxyError({
+        code: ErrorCode.IndexFailed,
+        title: "building the codebase index failed",
+        cause: messageOf(underlying),
+        nextSteps: ["re-run with --verbose for details"],
+        underlying,
+    });
+}
+// ── internal (exit 1) ─────────────────────────────────────────────────────────
+export function internal(underlying) {
+    return new CruxyError({
+        code: ErrorCode.Internal,
+        title: "an unexpected internal error occurred",
+        cause: messageOf(underlying),
+        nextSteps: [
+            "re-run with --verbose (or --log-level debug) to see the underlying error",
+            `report it at ${ISSUE_URL} with the error code and details`,
+        ],
+        underlying,
+    });
+}
+/**
+ * Map a known provider/transport error (from `@cruxy/sdk`) to a typed
+ * {@link CruxyError}, or `null` if it isn't one. Order matters: specific
+ * subclasses before the `ApiError` base.
+ */
+export function classifyProviderError(underlying) {
+    if (underlying instanceof AuthError)
+        return authInvalid(underlying);
+    if (underlying instanceof RateLimitError)
+        return apiRateLimit(underlying);
+    if (underlying instanceof OverloadedError)
+        return apiOverloaded(underlying);
+    if (underlying instanceof NetworkError)
+        return gatewayUnreachable(underlying);
+    if (underlying instanceof ApiError) {
+        // BudgetExhaustedError isn't exported by the SDK; match by name.
+        if (underlying.name === "BudgetExhaustedError") {
+            return budgetExhausted(underlying);
+        }
+        return apiError(underlying);
+    }
+    return null;
+}

package/dist/errors/format.d.ts

@@ -0,0 +1,31 @@
+import { CruxyError } from "./types.js";
+/**
+ * Rendering for {@link CruxyError}, kept separate from the data so it's testable
+ * and swappable. {@link TerminalFormatter} renders the human, 4-part terminal
+ * form; a `JsonFormatter` for headless output can drop in behind the same
+ * {@link Formatter} interface later (out of scope here — this is the seam).
+ */
+export interface FormatOptions {
+    /** Append the underlying error's stack/message (hidden by default). */
+    verbose: boolean;
+    /** Emit ANSI color. Resolve with {@link shouldUseColor}. */
+    color: boolean;
+}
+export interface Formatter {
+    format(err: CruxyError, opts: FormatOptions): string;
+}
+/**
+ * Decide whether to colorize: honor `NO_COLOR` (disable) and `FORCE_COLOR`
+ * (enable), otherwise color only when writing to a TTY.
+ */
+export declare function shouldUseColor(stream?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;
+/** The default terminal formatter: title, cause, next steps, code (+ verbose). */
+export declare class TerminalFormatter implements Formatter {
+    format(err: CruxyError, opts: FormatOptions): string;
+}
+/** The shared default instance. */
+export declare const terminalFormatter: TerminalFormatter;
+/** Convenience: render with the default terminal formatter. */
+export declare function formatError(err: CruxyError, opts: FormatOptions): string;

package/dist/errors/format.js

@@ -0,0 +1,60 @@
+import pc from "picocolors";
+/**
+ * Decide whether to colorize: honor `NO_COLOR` (disable) and `FORCE_COLOR`
+ * (enable), otherwise color only when writing to a TTY.
+ */
+export function shouldUseColor(stream = process.stderr, env = process.env) {
+    if (env.NO_COLOR !== undefined && env.NO_COLOR !== "")
+        return false;
+    if (env.FORCE_COLOR !== undefined && env.FORCE_COLOR !== "")
+        return true;
+    return Boolean(stream.isTTY);
+}
+/** The default terminal formatter: title, cause, next steps, code (+ verbose). */
+export class TerminalFormatter {
+    format(err, opts) {
+        const c = pc.createColors(opts.color);
+        const lines = [];
+        // 1. Title — one plain line, what failed.
+        lines.push(c.red(c.bold(err.title)));
+        // 2. Cause — the specific reason, when known.
+        if (err.cause)
+            lines.push(`${c.dim("Cause:")} ${err.cause}`);
+        // 3. Next step(s) — the concrete action(s) to take.
+        if (err.nextSteps.length > 0) {
+            lines.push("");
+            lines.push(c.bold("Next steps:"));
+            for (const step of err.nextSteps)
+                lines.push(`  ${c.cyan("→")} ${step}`);
+        }
+        // 4. Code — the stable, greppable id.
+        lines.push("");
+        lines.push(c.dim(`[${err.code}]`));
+        // Verbose-only: the preserved underlying error.
+        if (opts.verbose && err.underlying !== undefined) {
+            lines.push("");
+            lines.push(c.dim("Underlying error:"));
+            lines.push(indent(stackOf(err.underlying)));
+        }
+        return lines.join("\n");
+    }
+}
+/** The shared default instance. */
+export const terminalFormatter = new TerminalFormatter();
+/** Convenience: render with the default terminal formatter. */
+export function formatError(err, opts) {
+    return terminalFormatter.format(err, opts);
+}
+/** The stack (preferred) or message of an underlying error, as a string. */
+function stackOf(underlying) {
+    if (underlying instanceof Error) {
+        return underlying.stack ?? `${underlying.name}: ${underlying.message}`;
+    }
+    return String(underlying);
+}
+function indent(text, by = "  ") {
+    return text
+        .split("\n")
+        .map((line) => by + line)
+        .join("\n");
+}

package/dist/errors/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./format.js";
+export * from "./constructors.js";
+export * from "./boundary.js";

package/dist/errors/index.js

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./format.js";
+export * from "./constructors.js";
+export * from "./boundary.js";

package/dist/errors/types.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The one error type for every user-facing failure (U.5). A {@link CruxyError}
+ * carries structured fields — title, optional human cause, next steps, a stable
+ * greppable {@link ErrorCode}, and a process exit code — while *formatting* lives
+ * separately (see `format.ts`). The raw underlying error is preserved but shown
+ * only under `--verbose`; no Node stack trace ever reaches the user by default.
+ */
+/**
+ * Stable, greppable error identifiers. The string value *is* the id that appears
+ * in output (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`) — grep for it in logs/issues.
+ * Grouped by category; each category maps to a distinct process exit code
+ * (see {@link exitCodeFor}).
+ */
+export declare const ErrorCode: {
+    readonly Internal: "CRUXY_E_INTERNAL";
+    readonly Usage: "CRUXY_E_USAGE";
+    readonly ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN";
+    readonly ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED";
+    readonly ConfigParse: "CRUXY_E_CONFIG_PARSE";
+    readonly ConfigInvalid: "CRUXY_E_CONFIG_INVALID";
+    readonly AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY";
+    readonly AuthInvalid: "CRUXY_E_AUTH_INVALID";
+    readonly GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE";
+    readonly Api: "CRUXY_E_API";
+    readonly ApiRateLimit: "CRUXY_E_API_RATE_LIMIT";
+    readonly ApiOverloaded: "CRUXY_E_API_OVERLOADED";
+    readonly BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED";
+    readonly FileNotFound: "CRUXY_E_FILE_NOT_FOUND";
+    readonly PermissionDenied: "CRUXY_E_PERMISSION_DENIED";
+    readonly PathEscape: "CRUXY_E_PATH_ESCAPE";
+    readonly IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE";
+    readonly IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE";
+    readonly IndexFailed: "CRUXY_E_INDEX_FAILED";
+    readonly SkillInvalid: "CRUXY_E_SKILL_INVALID";
+    readonly SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND";
+};
+export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
+/** The process exit code for an error code (defaults to 1 for safety). */
+export declare function exitCodeFor(code: ErrorCode): number;
+export interface CruxyErrorInit {
+    /** Stable error id (drives the exit code and appears in output). */
+    code: ErrorCode;
+    /** One plain line: what failed. */
+    title: string;
+    /** The specific reason, when known. Always shown (part 2 of the standard). */
+    cause?: string;
+    /** Concrete actions the user can take. */
+    nextSteps?: string[];
+    /** Structured context (not rendered; for future JSON output / telemetry). */
+    meta?: Record<string, unknown>;
+    /** The original thrown error, preserved and shown only under `--verbose`. */
+    underlying?: unknown;
+    /** Override the exit code; defaults to {@link exitCodeFor}(code). */
+    exitCode?: number;
+}
+/**
+ * Every user-facing failure is (or becomes) one of these. Extends `Error` so it
+ * flows through normal throw/catch; `.message` mirrors `title` so logs and
+ * `instanceof Error` consumers stay useful.
+ */
+export declare class CruxyError extends Error {
+    readonly code: ErrorCode;
+    readonly title: string;
+    /** Human-readable reason (part 2). Narrows the inherited `Error.cause`. */
+    readonly cause?: string;
+    readonly nextSteps: string[];
+    readonly exitCode: number;
+    readonly meta?: Record<string, unknown>;
+    /** The wrapped lower-level error — rendered only under `--verbose`. */
+    readonly underlying?: unknown;
+    constructor(init: CruxyErrorInit);
+    /** Type guard — true for any CruxyError (across realms, via the brand). */
+    static is(err: unknown): err is CruxyError;
+}

package/dist/errors/types.js

@@ -0,0 +1,107 @@
+/**
+ * The one error type for every user-facing failure (U.5). A {@link CruxyError}
+ * carries structured fields — title, optional human cause, next steps, a stable
+ * greppable {@link ErrorCode}, and a process exit code — while *formatting* lives
+ * separately (see `format.ts`). The raw underlying error is preserved but shown
+ * only under `--verbose`; no Node stack trace ever reaches the user by default.
+ */
+/**
+ * Stable, greppable error identifiers. The string value *is* the id that appears
+ * in output (e.g. `CRUXY_E_GATEWAY_UNREACHABLE`) — grep for it in logs/issues.
+ * Grouped by category; each category maps to a distinct process exit code
+ * (see {@link exitCodeFor}).
+ */
+export const ErrorCode = {
+    // internal (exit 1)
+    Internal: "CRUXY_E_INTERNAL",
+    // usage (exit 2)
+    Usage: "CRUXY_E_USAGE",
+    ConfigKeyUnknown: "CRUXY_E_CONFIG_KEY_UNKNOWN",
+    ProviderUnsupported: "CRUXY_E_PROVIDER_UNSUPPORTED",
+    // config (exit 3)
+    ConfigParse: "CRUXY_E_CONFIG_PARSE",
+    ConfigInvalid: "CRUXY_E_CONFIG_INVALID",
+    // auth (exit 4)
+    AuthMissingKey: "CRUXY_E_AUTH_MISSING_KEY",
+    AuthInvalid: "CRUXY_E_AUTH_INVALID",
+    // network (exit 5)
+    GatewayUnreachable: "CRUXY_E_GATEWAY_UNREACHABLE",
+    // api (exit 6)
+    Api: "CRUXY_E_API",
+    ApiRateLimit: "CRUXY_E_API_RATE_LIMIT",
+    ApiOverloaded: "CRUXY_E_API_OVERLOADED",
+    BudgetExhausted: "CRUXY_E_BUDGET_EXHAUSTED",
+    // filesystem (exit 7)
+    FileNotFound: "CRUXY_E_FILE_NOT_FOUND",
+    PermissionDenied: "CRUXY_E_PERMISSION_DENIED",
+    PathEscape: "CRUXY_E_PATH_ESCAPE",
+    // index (exit 8)
+    IndexEmbedderUnavailable: "CRUXY_E_INDEX_EMBEDDER_UNAVAILABLE",
+    IndexStoreUnavailable: "CRUXY_E_INDEX_STORE_UNAVAILABLE",
+    IndexFailed: "CRUXY_E_INDEX_FAILED",
+    // skill (exit 9)
+    SkillInvalid: "CRUXY_E_SKILL_INVALID",
+    SkillNotFound: "CRUXY_E_SKILL_NOT_FOUND",
+};
+/**
+ * Category exit codes. Distinct per category so a caller (CI, a script) can
+ * branch on *why* cruxy failed. Documented in the README error table.
+ */
+const EXIT_CODES = {
+    [ErrorCode.Internal]: 1,
+    [ErrorCode.Usage]: 2,
+    [ErrorCode.ConfigKeyUnknown]: 2,
+    [ErrorCode.ProviderUnsupported]: 2,
+    [ErrorCode.ConfigParse]: 3,
+    [ErrorCode.ConfigInvalid]: 3,
+    [ErrorCode.AuthMissingKey]: 4,
+    [ErrorCode.AuthInvalid]: 4,
+    [ErrorCode.GatewayUnreachable]: 5,
+    [ErrorCode.Api]: 6,
+    [ErrorCode.ApiRateLimit]: 6,
+    [ErrorCode.ApiOverloaded]: 6,
+    [ErrorCode.BudgetExhausted]: 6,
+    [ErrorCode.FileNotFound]: 7,
+    [ErrorCode.PermissionDenied]: 7,
+    [ErrorCode.PathEscape]: 7,
+    [ErrorCode.IndexEmbedderUnavailable]: 8,
+    [ErrorCode.IndexStoreUnavailable]: 8,
+    [ErrorCode.IndexFailed]: 8,
+    [ErrorCode.SkillInvalid]: 9,
+    [ErrorCode.SkillNotFound]: 9,
+};
+/** The process exit code for an error code (defaults to 1 for safety). */
+export function exitCodeFor(code) {
+    return EXIT_CODES[code] ?? 1;
+}
+/**
+ * Every user-facing failure is (or becomes) one of these. Extends `Error` so it
+ * flows through normal throw/catch; `.message` mirrors `title` so logs and
+ * `instanceof Error` consumers stay useful.
+ */
+export class CruxyError extends Error {
+    code;
+    title;
+    /** Human-readable reason (part 2). Narrows the inherited `Error.cause`. */
+    cause;
+    nextSteps;
+    exitCode;
+    meta;
+    /** The wrapped lower-level error — rendered only under `--verbose`. */
+    underlying;
+    constructor(init) {
+        super(init.title);
+        this.name = "CruxyError";
+        this.code = init.code;
+        this.title = init.title;
+        this.cause = init.cause;
+        this.nextSteps = init.nextSteps ?? [];
+        this.meta = init.meta;
+        this.underlying = init.underlying;
+        this.exitCode = init.exitCode ?? exitCodeFor(init.code);
+    }
+    /** Type guard — true for any CruxyError (across realms, via the brand). */
+    static is(err) {
+        return err instanceof CruxyError;
+    }
+}

package/dist/index.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
-import pc from "picocolors";
 import { buildProgram } from "./cli/program.js";
-import { logger } from "./utils/logger.js";
+import { handleFatal, isCommanderSuccess, isVerbose } from "./errors/index.js";
 async function main() {
     const program = buildProgram();
     await program.parseAsync(process.argv);
 }
 main().catch((err) => {
-    const message = err instanceof Error ? err.message : String(err);
-    logger.error(pc.red(message));
-    process.exit(1);
+    // Commander signals `--help` / `--version` by throwing with exit code 0 — that
+    // is success, not a failure. Everything else goes through the one boundary:
+    // CruxyError → formatted output + its exit code; unknown → CRUXY_E_INTERNAL,
+    // with the raw stack shown only under --verbose.
+    if (isCommanderSuccess(err))
+        process.exit(0);
+    handleFatal(err, { verbose: isVerbose() });
 });

package/dist/indexing/embedder.js

@@ -1,4 +1,5 @@
 import { promises as fs } from "node:fs";
+import { indexEmbedderUnavailable } from "../errors/index.js";
 import { l2normalize } from "./util.js";
 /**
  * Output dimensionality of bge-small-en-v1.5, and the default size of the
@@ -132,9 +133,8 @@ export async function createEmbedder(opts = {}) {
         await import("fastembed");
     }
     catch (err) {
-        throw new Error(`the local embedding model (fastembed) could not be loaded: ${err.message}. ` +
-            "It requires the onnxruntime-node native addon — reinstall with `pnpm install` and " +
-            "ensure the native build completed. The codebase index is unavailable until this is fixed.");
+        // Fail loud (the C.17 guarantee), now with a stable code + next steps.
+        throw indexEmbedderUnavailable(err);
     }
     return new FastEmbedEmbedder({ cacheDir: opts.cacheDir });
 }

package/dist/indexing/service.js

@@ -1,6 +1,7 @@
 import { promises as fsp } from "node:fs";
 import path from "node:path";
 import { globalDir } from "../config/index.js";
+import { indexStoreUnavailable } from "../errors/index.js";
 import { GLOBAL_DIR_NAME } from "../constants.js";
 import { createEmbedder } from "./embedder.js";
 import { Indexer } from "./indexer.js";
@@ -124,8 +125,10 @@ async function openStore(root, kind, logger) {
         return { store, storePath: dbPath };
     }
     catch (err) {
+        // store=sqlite is explicit: fail loud with a code. store=auto degrades to
+        // an in-memory index with a warning (no quality loss, just no persistence).
         if (kind === "sqlite")
-            throw err;
+            throw indexStoreUnavailable(err);
         logger.warn(`sqlite index unavailable (${err.message}); using an in-memory index`);
         return { store: new InMemoryVectorStore(), storePath: null };
     }

package/dist/skills/loader.d.ts

@@ -1,3 +1,4 @@
+import { CruxyError } from "../errors/index.js";
 import { type Skill, type SkillCatalog, type SkillError, type SkillSource } from "./types.js";
 /** The three source directories the loader scans. */
 export interface LoaderSources {
@@ -16,7 +17,7 @@ interface SkillCandidate {
     dir: string;
 }
 /** Thrown by `getSkill` when no catalog entry matches the requested name. */
-export declare class SkillNotFoundError extends Error {
+export declare class SkillNotFoundError extends CruxyError {
     constructor(message: string);
 }
 /**

package/dist/skills/parser.d.ts

@@ -1,10 +1,12 @@
+import { CruxyError } from "../errors/index.js";
 import { type SkillFrontmatter } from "./types.js";
 /**
- * Thrown when a SKILL.md is malformed or fails validation. The message is
- * actionable (it names the problem) and is caught by the loader, which records
- * it as a `SkillError` and excludes the skill — loud, never silently skipped.
+ * Thrown when a SKILL.md is malformed or fails validation. A {@link CruxyError}
+ * (code CRUXY_E_SKILL_INVALID) so it carries a stable code if it reaches the
+ * boundary; the loader still catches it to record a `SkillError` and exclude the
+ * skill — loud, never silently skipped.
  */
-export declare class SkillValidationError extends Error {
+export declare class SkillValidationError extends CruxyError {
     constructor(message: string);
 }
 /** The validated frontmatter plus the markdown body that followed it. */

package/dist/skills/parser.js

@@ -1,12 +1,20 @@
+import { CruxyError, ErrorCode } from "../errors/index.js";
 import { SkillFrontmatterSchema } from "./types.js";
 /**
- * Thrown when a SKILL.md is malformed or fails validation. The message is
- * actionable (it names the problem) and is caught by the loader, which records
- * it as a `SkillError` and excludes the skill — loud, never silently skipped.
+ * Thrown when a SKILL.md is malformed or fails validation. A {@link CruxyError}
+ * (code CRUXY_E_SKILL_INVALID) so it carries a stable code if it reaches the
+ * boundary; the loader still catches it to record a `SkillError` and exclude the
+ * skill — loud, never silently skipped.
  */
-export class SkillValidationError extends Error {
+export class SkillValidationError extends CruxyError {
     constructor(message) {
-        super(message);
+        super({
+            code: ErrorCode.SkillInvalid,
+            title: message,
+            nextSteps: [
+                "see the built-in `using-skills` skill for the SKILL.md rules",
+            ],
+        });
         this.name = "SkillValidationError";
     }
 }

package/dist/tools/file/paths.d.ts

@@ -1,10 +1,12 @@
+import { CruxyError } from "../../errors/index.js";
 import type { ToolContext } from "../types.js";
 /**
  * Thrown when a tool argument resolves to a path outside the project root —
  * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * Tools catch this and surface it as `{ ok:false }` rather than letting it throw.
+ * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
+ * reaches the boundary; tools still catch it and surface `{ ok:false }`.
  */
-export declare class PathEscapeError extends Error {
+export declare class PathEscapeError extends CruxyError {
     constructor(message: string);
 }
 /**

package/dist/tools/file/paths.js

@@ -1,13 +1,15 @@
 import { promises as fs } from "node:fs";
 import path from "node:path";
+import { CruxyError, ErrorCode } from "../../errors/index.js";
 /**
  * Thrown when a tool argument resolves to a path outside the project root —
  * whether via `../` traversal, an absolute path, or a symlink pointing outward.
- * Tools catch this and surface it as `{ ok:false }` rather than letting it throw.
+ * A {@link CruxyError} (code CRUXY_E_PATH_ESCAPE) so it carries a code if it
+ * reaches the boundary; tools still catch it and surface `{ ok:false }`.
  */
-export class PathEscapeError extends Error {
+export class PathEscapeError extends CruxyError {
     constructor(message) {
-        super(message);
+        super({ code: ErrorCode.PathEscape, title: message });
         this.name = "PathEscapeError";
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cruxy/cli",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "an agentic coding CLI",
   "type": "module",
   "bin": {