failproofai 0.0.2-beta.1 → 0.0.2-beta.3

package/README.md

@@ -15,21 +15,21 @@
 [![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
 [![Discord](https://img.shields.io/discord/1234567890?style=flat-square&label=Discord&color=5865F2)](https://discord.com/invite/zT92CAgvkj)
 
-Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
+The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code** & the **Agents SDK**.
 
-- **Hooks & Policies** — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
-- **Custom Policies** — Write your own policies in JavaScript. Same `allow`/`deny`/`instruct` API as built-in policies, with full async support.
-- **Policy Parameters** — Tune built-in policies without writing code: configure allowlists, protected branches, thresholds, and custom patterns.
-- **Session Viewer** — Browse Claude Code projects and sessions locally. Inspect tool calls, messages, and per-session hook activity side-by-side.
+- **30 Built-in Policies** - Catch common agent failure modes out of the box. Block destructive commands, prevent secret leakage, keep agents inside project boundaries, detect loops, and more.
+- **Custom Policies** - Write your own reliability rules in JavaScript. Use the `allow`/`deny`/`instruct` API to enforce conventions, prevent drift, gate operations, or integrate with external systems.
+- **Easy Configuration** - Tune any policy without writing code. Set allowlists, protected branches, thresholds per-project or globally. Three-scope config merges automatically.
+- **Agent Monitor** - See what your agents did while you were away. Browse sessions, inspect every tool call, and review exactly where policies fired.
 
-Everything runs locally — no data leaves your machine.
+Everything runs locally - no data leaves your machine.
 
 ---
 
 ## Requirements
 
 - Node.js >= 20.9.0
-- Bun >= 1.3.0 (optional — only needed for development / building from source)
+- Bun >= 1.3.0 (optional - only needed for development / building from source)
 
 ---
 
@@ -48,7 +48,7 @@ bun add -g failproofai
 ### 1. Enable policies globally
 
 ```bash
-failproofai --install-policies
+failproofai policies --install
 ```
 
 Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke failproofai before and after each tool call.
@@ -59,12 +59,12 @@ Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke
 failproofai
 ```
 
-Opens `http://localhost:8020` — browse sessions, inspect logs, manage policies.
+Opens `http://localhost:8020` - browse sessions, inspect logs, manage policies.
 
 ### 3. Check what's active
 
 ```bash
-failproofai --list-policies
+failproofai policies
 ```
 
 ---
@@ -75,22 +75,22 @@ failproofai --list-policies
 
 | Scope | Command | Where it writes |
 |-------|---------|-----------------|
-| Global (default) | `failproofai --install-policies` | `~/.claude/settings.json` |
-| Project | `failproofai --install-policies --scope project` | `.claude/settings.json` |
-| Local | `failproofai --install-policies --scope local` | `.claude/settings.local.json` |
+| Global (default) | `failproofai policies --install` | `~/.claude/settings.json` |
+| Project | `failproofai policies --install --scope project` | `.claude/settings.json` |
+| Local | `failproofai policies --install --scope local` | `.claude/settings.local.json` |
 
 ### Install specific policies
 
 ```bash
-failproofai --install-policies block-sudo block-rm-rf sanitize-api-keys
+failproofai policies --install block-sudo block-rm-rf sanitize-api-keys
 ```
 
 ### Remove policies
 
 ```bash
-failproofai --remove-policies
+failproofai policies --uninstall
 # or for a specific scope:
-failproofai --remove-policies --scope project
+failproofai policies --uninstall --scope project
 ```
 
 ---
@@ -128,7 +128,7 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
 }
 ```
 
-**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.md](docs/configuration.md) for full merge rules.
+**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.mdx](docs/configuration.mdx) for full merge rules.
 
 ---
 
@@ -136,40 +136,40 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
 
 | Policy | Description | Configurable |
 |--------|-------------|:---:|
-| `block-sudo` | Block sudo commands | `allowPatterns` |
-| `block-rm-rf` | Block recursive deletions | `allowPaths` |
-| `block-curl-pipe-sh` | Block curl\|bash and wget\|bash | |
+| `block-sudo` | Prevent agents from running privileged system commands | `allowPatterns` |
+| `block-rm-rf` | Prevent accidental recursive file deletion | `allowPaths` |
+| `block-curl-pipe-sh` | Prevent agents from piping untrusted scripts to shell | |
 | `block-failproofai-commands` | Prevent self-uninstallation | |
-| `sanitize-jwt` | Redact JWT tokens from tool output | |
-| `sanitize-api-keys` | Redact API keys from tool output | `additionalPatterns` |
-| `sanitize-connection-strings` | Redact database credentials from tool output | |
-| `sanitize-private-key-content` | Redact PEM private key blocks | |
-| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens | |
-| `block-env-files` | Block access to .env files | |
-| `protect-env-vars` | Block commands that print environment variables | |
-| `block-read-outside-cwd` | Block reading files outside the project | `allowPaths` |
-| `block-secrets-write` | Block writes to private key and certificate files | `additionalPatterns` |
-| `block-push-master` | Block pushing to main/master | `protectedBranches` |
-| `block-work-on-main` | Block checking out main/master | `protectedBranches` |
-| `block-force-push` | Block `git push --force` | |
-| `warn-git-amend` | Warn on `git commit --amend` | |
-| `warn-git-stash-drop` | Warn on `git stash drop` | |
-| `warn-all-files-staged` | Warn on `git add -A` | |
-| `warn-destructive-sql` | Warn on DROP/DELETE SQL statements | |
-| `warn-schema-alteration` | Warn on ALTER TABLE statements | |
-| `warn-large-file-write` | Warn on large file writes | `thresholdKb` |
-| `warn-package-publish` | Warn on `npm publish` | |
-| `warn-background-process` | Warn on background process launches | |
-| `warn-global-package-install` | Warn on global package installs | |
+| `sanitize-jwt` | Stop JWT tokens from leaking into agent context | |
+| `sanitize-api-keys` | Stop API keys from leaking into agent context | `additionalPatterns` |
+| `sanitize-connection-strings` | Stop database credentials from leaking into agent context | |
+| `sanitize-private-key-content` | Redact PEM private key blocks from output | |
+| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens from output | |
+| `block-env-files` | Keep agents from reading .env files | |
+| `protect-env-vars` | Prevent agents from printing environment variables | |
+| `block-read-outside-cwd` | Keep agents inside project boundaries | `allowPaths` |
+| `block-secrets-write` | Prevent writes to private key and certificate files | `additionalPatterns` |
+| `block-push-master` | Prevent accidental pushes to main/master | `protectedBranches` |
+| `block-work-on-main` | Keep agents off protected branches | `protectedBranches` |
+| `block-force-push` | Prevent `git push --force` | |
+| `warn-git-amend` | Remind agents before amending commits | |
+| `warn-git-stash-drop` | Remind agents before dropping stashes | |
+| `warn-all-files-staged` | Catch accidental `git add -A` | |
+| `warn-destructive-sql` | Catch DROP/DELETE SQL before execution | |
+| `warn-schema-alteration` | Catch ALTER TABLE before execution | |
+| `warn-large-file-write` | Catch unexpectedly large file writes | `thresholdKb` |
+| `warn-package-publish` | Catch accidental `npm publish` | |
+| `warn-background-process` | Catch unintended background process launches | |
+| `warn-global-package-install` | Catch unintended global package installs | |
 | …and more | | |
 
-Full policy details and parameter reference: [docs/built-in-policies.md](docs/built-in-policies.md)
+Full policy details and parameter reference: [docs/built-in-policies.mdx](docs/built-in-policies.mdx)
 
 ---
 
 ## Custom policies
 
-Create a `.js` file with your own policies:
+Write your own policies to keep agents reliable and on-task:
 
 ```js
 import { customPolicies, allow, deny, instruct } from "failproofai";
@@ -190,15 +190,16 @@ customPolicies.add({
 Install with:
 
 ```bash
-failproofai --install-policies --custom ./my-policies.js
+failproofai policies --install --custom ./my-policies.js
 ```
 
 ### Decision helpers
 
 | Function | Effect |
 |----------|--------|
-| `allow()` | Permit the tool call |
-| `deny(message)` | Block the tool call; message shown to Claude |
+| `allow()` | Permit the operation |
+| `allow(message)` | Permit and send informational context to Claude *(beta)* |
+| `deny(message)` | Block the operation; message shown to Claude |
 | `instruct(message)` | Add context to Claude's prompt; does not block |
 
 ### Context object (`ctx`)
@@ -213,7 +214,7 @@ failproofai --install-policies --custom ./my-policies.js
 | `session.sessionId` | `string` | Session identifier |
 | `session.transcriptPath` | `string` | Path to the session transcript file |
 
-Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors in custom hooks are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.md](docs/custom-hooks.md) for the full guide.
+Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.mdx](docs/custom-hooks.mdx) for the full guide.
 
 ---
 
@@ -233,14 +234,26 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai
 
 | Guide | Description |
 |-------|-------------|
-| [Getting Started](docs/getting-started.md) | Installation and first steps |
-| [CLI Reference](docs/cli-reference.md) | All commands and flags |
-| [Configuration](docs/configuration.md) | Config file format and scope merging |
-| [Built-in Policies](docs/built-in-policies.md) | All 35+ policies with parameters |
-| [Custom Hooks](docs/custom-hooks.md) | Write your own policies |
-| [Dashboard](docs/dashboard.md) | Session viewer and policy management |
-| [Architecture](docs/architecture.md) | How the hook system works |
-| [Testing](docs/testing.md) | Running tests and writing new ones |
+| [Getting Started](docs/getting-started.mdx) | Installation and first steps |
+| [Built-in Policies](docs/built-in-policies.mdx) | All 30 built-in policies with parameters |
+| [Custom Policies](docs/custom-policies.mdx) | Write your own policies |
+| [Configuration](docs/configuration.mdx) | Config file format and scope merging |
+| [Dashboard](docs/dashboard.mdx) | Monitor sessions and review policy activity |
+| [Architecture](docs/architecture.mdx) | How the hook system works |
+| [Testing](docs/testing.mdx) | Running tests and writing new ones |
+
+### Run docs locally
+
+```bash
+docker build -f Dockerfile.docs -t failproofai-docs .
+docker run --rm -p 3000:3000 failproofai-docs
+```
+
+Opens the Mintlify docs site at `http://localhost:3000`. The container watches for changes if you mount the docs directory:
+
+```bash
+docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs
+```
 
 ---
 

package/bin/failproofai.mjs

@@ -37,10 +37,40 @@ const args = process.argv.slice(2);
 // Normalize 'p' → 'policies' (shorthand alias)
 if (args[0] === "p") args[0] = "policies";
 
-// --help / -h  (only when not inside a subcommand that handles its own --help)
-const SUBCOMMANDS = ["policies"];
-if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
-  console.log(`
+// --hook <event> — called by Claude Code hooks; fast path, outside runCli()
+// because it has its own exit code contract with Claude Code.
+const hookIdx = args.indexOf("--hook");
+if (hookIdx >= 0) {
+  if (!args[hookIdx + 1]) {
+    console.error("Error: Missing event type after --hook");
+    console.error("Usage: failproofai --hook <event>  (e.g. PreToolUse, PostToolUse)");
+    process.exit(1);
+  }
+  try {
+    const { handleHookEvent } = await import("../src/hooks/handler");
+    const exitCode = await handleHookEvent(args[hookIdx + 1]);
+    process.exit(exitCode);
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.error(`Unexpected error: ${msg}`);
+    process.exit(2);
+  }
+}
+
+/**
+ * Centralised error handler for all CLI subcommands.
+ * CliError  → clean message, no stack trace, exit exitCode (1 or 2)
+ * Error     → unexpected; shows message only, exits 2
+ */
+async function runCli() {
+  // --help / -h  (only when not inside a subcommand that handles its own --help)
+  const SUBCOMMANDS = ["policies"];
+  if ((args.includes("--help") || args.includes("-h")) && !SUBCOMMANDS.includes(args[0])) {
+    const extraArgs = args.filter((a) => a !== "--help" && a !== "-h");
+    if (extraArgs.length > 0) {
+      throw new CliError(`Unexpected argument: ${extraArgs[0]}\nRun \`failproofai --help\` for usage.`);
+    }
+    console.log(`
 failproofai v${version}
 
 USAGE
@@ -80,33 +110,29 @@ LINKS
   ⭐ Star us:      https://github.com/exospherehost/failproofai
   📖 Docs:         https://befailproof.ai
 `.trimStart());
-  process.exit(0);
-}
-
-// --version / -v
-if (args.includes("--version") || args.includes("-v")) {
-  console.log(version);
-  process.exit(0);
-}
+    process.exit(0);
+  }
 
-// --hook <event> — called by Claude Code hooks; fast path, no dashboard startup
-const hookIdx = args.indexOf("--hook");
-if (hookIdx >= 0 && args[hookIdx + 1]) {
-  const { handleHookEvent } = await import("../src/hooks/handler");
-  const exitCode = await handleHookEvent(args[hookIdx + 1]);
-  process.exit(exitCode);
-}
+  // --version / -v
+  if ((args.includes("--version") || args.includes("-v")) && !SUBCOMMANDS.includes(args[0])) {
+    const extraArgs = args.filter((a) => a !== "--version" && a !== "-v");
+    if (extraArgs.length > 0) {
+      throw new CliError(`Unexpected argument: ${extraArgs[0]}\nRun \`failproofai --help\` for usage.`);
+    }
+    console.log(version);
+    process.exit(0);
+  }
 
-// policies [--install|-i|--uninstall|-u|--help|-h] [names...] [--scope] [--beta] [--custom|-c <path>]
-if (args[0] === "policies") {
-  const subArgs = args.slice(1);
+  // policies [--install|-i|--uninstall|-u|--help|-h] [names...] [--scope] [--beta] [--custom|-c <path>]
+  if (args[0] === "policies") {
+    const subArgs = args.slice(1);
 
-  const isInstall   = subArgs.includes("--install")   || subArgs.includes("-i");
-  const isUninstall = subArgs.includes("--uninstall")  || subArgs.includes("-u");
-  const isHelp      = subArgs.includes("--help")       || subArgs.includes("-h");
+    const isInstall   = subArgs.includes("--install")   || subArgs.includes("-i");
+    const isUninstall = subArgs.includes("--uninstall")  || subArgs.includes("-u");
+    const isHelp      = subArgs.includes("--help")       || subArgs.includes("-h");
 
-  if (isHelp) {
-    console.log(`
+    if (isHelp) {
+      console.log(`
 failproofai policies — manage Failproof AI policies
 
 USAGE
@@ -137,118 +163,185 @@ EXAMPLES
   failproofai policies -u
   failproofai policies --uninstall --custom
 `.trimStart());
+      process.exit(0);
+    }
+
+    if (isInstall) {
+      const { installHooks } = await import("../src/hooks/manager");
+
+      const scopeIdx = subArgs.indexOf("--scope");
+      const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
+      if (scopeIdx >= 0 && (!scope || scope.startsWith("-"))) {
+        throw new CliError("Missing value for --scope. Valid values: user, project, local");
+      }
+      if (scopeIdx >= 0 && !["user", "project", "local"].includes(scope)) {
+        throw new CliError(`Invalid scope: ${scope}. Valid values: user, project, local`);
+      }
+
+      const customIdx = subArgs.includes("--custom") ? subArgs.indexOf("--custom")
+                      : subArgs.includes("-c")        ? subArgs.indexOf("-c")
+                      : -1;
+      const customPoliciesPath = customIdx >= 0 ? subArgs[customIdx + 1] : undefined;
+      if (customIdx >= 0 && (!customPoliciesPath || customPoliciesPath.startsWith("-"))) {
+        throw new CliError("Missing path after --custom/-c\nUsage: --custom <path>  (e.g. --custom ./my-policies.js)");
+      }
+
+      const includeBeta = subArgs.includes("--beta");
+
+      // Collect positional policy names — args that don't start with - and aren't
+      // values consumed by --scope or --custom/-c (tracked by index, not value,
+      // so a policy named "user" isn't incorrectly dropped by the default scope).
+      const consumedIdxs = new Set();
+      if (scopeIdx >= 0) consumedIdxs.add(scopeIdx + 1);
+      if (customIdx >= 0) consumedIdxs.add(customIdx + 1);
+      const flags = new Set(["--install", "-i", "--scope", "--beta", "--custom", "-c"]);
+      const unknownInstallFlag = subArgs.find((a) => a.startsWith("-") && !flags.has(a));
+      if (unknownInstallFlag) {
+        throw new CliError(`Unknown flag: ${unknownInstallFlag}\nRun \`failproofai policies --help\` for usage.`);
+      }
+
+      const explicitPolicyNames = subArgs.filter(
+        (a, idx) => !a.startsWith("-") && !consumedIdxs.has(idx)
+      );
+
+      // When --custom/-c is present but no explicit policy names, pass [] so
+      // installHooks uses the existing enabled policies and skips the interactive
+      // prompt — validation of the custom file happens inside installHooks.
+      const policyNames =
+        explicitPolicyNames.length > 0 ? explicitPolicyNames
+        : customPoliciesPath !== undefined ? []
+        : undefined;
+
+      await installHooks(
+        policyNames,
+        scope,
+        undefined,
+        includeBeta,
+        undefined,
+        customPoliciesPath,
+      );
+      process.exit(0);
+    }
+
+    if (isUninstall) {
+      const { removeHooks } = await import("../src/hooks/manager");
+
+      const scopeIdx = subArgs.indexOf("--scope");
+      const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
+      if (scopeIdx >= 0 && (!scope || scope.startsWith("-"))) {
+        throw new CliError("Missing value for --scope. Valid values: user, project, local, all");
+      }
+      if (scopeIdx >= 0 && !["user", "project", "local", "all"].includes(scope)) {
+        throw new CliError(`Invalid scope: ${scope}. Valid values: user, project, local, all`);
+      }
+
+      const betaOnly = subArgs.includes("--beta");
+      const removeCustomHooks = subArgs.includes("--custom") || subArgs.includes("-c");
+
+      const consumedIdxs = new Set();
+      if (scopeIdx >= 0) consumedIdxs.add(scopeIdx + 1);
+      const flags = new Set(["--uninstall", "-u", "--scope", "--beta", "--custom", "-c"]);
+      const unknownUninstallFlag = subArgs.find((a) => a.startsWith("-") && !flags.has(a));
+      if (unknownUninstallFlag) {
+        throw new CliError(`Unknown flag: ${unknownUninstallFlag}\nRun \`failproofai policies --help\` for usage.`);
+      }
+
+      const policyNames = subArgs.filter(
+        (a, idx) => !a.startsWith("-") && !consumedIdxs.has(idx)
+      );
+
+      await removeHooks(
+        policyNames.length > 0 ? policyNames : undefined,
+        scope,
+        undefined,
+        { betaOnly, removeCustomHooks },
+      );
+      process.exit(0);
+    }
+
+    // Default: list policies
+    // Accept --list as a no-op alias (common intuition), reject all other unknown flags
+    // and unexpected positional args (e.g. "hi").
+    const knownListFlags = new Set(["--install", "-i", "--uninstall", "-u", "--help", "-h", "--list"]);
+    const unknownListArg = subArgs.find((a) => a.startsWith("-") && !knownListFlags.has(a));
+    if (unknownListArg) {
+      throw new CliError(
+        `Unknown flag: ${unknownListArg}\n` +
+        `Run \`failproofai policies --help\` for usage.`
+      );
+    }
+    const positionalArgs = subArgs.filter((a) => !a.startsWith("-"));
+    if (positionalArgs.length > 0) {
+      throw new CliError(
+        `Unexpected argument: ${positionalArgs[0]}\n` +
+        `Run \`failproofai policies --help\` for usage.`
+      );
+    }
+
+    const { listHooks } = await import("../src/hooks/manager");
+    await listHooks();
     process.exit(0);
   }
 
-  if (isInstall) {
-    const { installHooks } = await import("../src/hooks/manager");
-
-    const scopeIdx = subArgs.indexOf("--scope");
-    const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
-
-    const customIdx = subArgs.includes("--custom") ? subArgs.indexOf("--custom")
-                    : subArgs.includes("-c")        ? subArgs.indexOf("-c")
-                    : -1;
-    const customPoliciesPath = customIdx >= 0 ? subArgs[customIdx + 1] : undefined;
-
-    const includeBeta = subArgs.includes("--beta");
-
-    // Collect positional policy names — args that don't start with - and aren't
-    // values consumed by --scope or --custom/-c.
-    const consumed = new Set([scope, customPoliciesPath].filter(Boolean));
-    const flags = new Set(["--install", "-i", "--scope", "--beta", "--custom", "-c"]);
-    const explicitPolicyNames = subArgs.filter(
-      (a) => !a.startsWith("-") && !flags.has(a) && !consumed.has(a)
-    );
-
-    // When --custom/-c is present but no explicit policy names, pass [] so
-    // installHooks uses the existing enabled policies and skips the interactive
-    // prompt — validation of the custom file happens inside installHooks.
-    const policyNames =
-      explicitPolicyNames.length > 0 ? explicitPolicyNames
-      : customPoliciesPath !== undefined ? []
-      : undefined;
-
-    await installHooks(
-      policyNames,
-      scope,
-      undefined,
-      includeBeta,
-      undefined,
-      customPoliciesPath,
+  // Unknown flag guard — must appear after all known-flag branches
+  const knownFlags = ["--version", "-v", "--help", "-h", "--hook"];
+  const unknownFlag = args.find(a => a.startsWith("-") && !knownFlags.includes(a));
+
+  if (unknownFlag) {
+    function levenshtein(a, b) {
+      const m = a.length, n = b.length;
+      const dp = Array.from({ length: m + 1 }, (_, i) =>
+        Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
+      );
+      for (let i = 1; i <= m; i++)
+        for (let j = 1; j <= n; j++)
+          dp[i][j] = a[i - 1] === b[j - 1]
+            ? dp[i - 1][j - 1]
+            : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
+      return dp[m][n];
+    }
+
+    const primary = ["--version", "--help", "--hook", "policies"];
+    const closest = primary.reduce((best, flag) => {
+      const dist = levenshtein(unknownFlag, flag);
+      return dist < best.dist ? { flag, dist } : best;
+    }, { flag: primary[0], dist: Infinity });
+
+    throw new CliError(
+      `Unknown flag: ${unknownFlag}\n` +
+      `Did you mean: ${closest.flag}?\n` +
+      `Run \`failproofai --help\` for usage details.`
     );
-    process.exit(0);
   }
 
-  if (isUninstall) {
-    const { removeHooks } = await import("../src/hooks/manager");
-
-    const scopeIdx = subArgs.indexOf("--scope");
-    const scope = scopeIdx >= 0 ? subArgs[scopeIdx + 1] : "user";
-
-    const betaOnly = subArgs.includes("--beta");
-    const removeCustomHooks = subArgs.includes("--custom") || subArgs.includes("-c");
-
-    const consumed = new Set([scope].filter(Boolean));
-    const flags = new Set(["--uninstall", "-u", "--scope", "--beta", "--custom", "-c"]);
-    const policyNames = subArgs.filter(
-      (a) => !a.startsWith("-") && !flags.has(a) && !consumed.has(a)
+  // Unknown subcommand guard (non-flag args that aren't "policies")
+  const unknownSubcommand = args.find(a => !a.startsWith("-") && a !== "policies");
+  if (unknownSubcommand) {
+    throw new CliError(
+      `Unknown command: ${unknownSubcommand}\n` +
+      `Did you mean: failproofai policies?\n` +
+      `Run \`failproofai --help\` for usage details.`
     );
-
-    await removeHooks(
-      policyNames.length > 0 ? policyNames : undefined,
-      scope,
-      undefined,
-      { betaOnly, removeCustomHooks },
-    );
-    process.exit(0);
   }
 
-  // Default: list policies
-  const { listHooks } = await import("../src/hooks/manager");
-  await listHooks();
-  process.exit(0);
+  // Dashboard launch — always production mode
+  const { launch } = await import("../scripts/launch");
+  launch("start");
 }
 
-// Unknown flag guard — must appear after all known-flag branches
-const knownFlags = ["--version", "-v", "--help", "-h", "--hook"];
-const unknownFlag = args.find(a => a.startsWith("-") && !knownFlags.includes(a));
+// ── Import CliError for use in the guard above ────────────────────────────────
+const { CliError } = await import("../src/cli-error");
 
-if (unknownFlag) {
-  function levenshtein(a, b) {
-    const m = a.length, n = b.length;
-    const dp = Array.from({ length: m + 1 }, (_, i) =>
-      Array.from({ length: n + 1 }, (_, j) => (i === 0 ? j : j === 0 ? i : 0))
-    );
-    for (let i = 1; i <= m; i++)
-      for (let j = 1; j <= n; j++)
-        dp[i][j] = a[i - 1] === b[j - 1]
-          ? dp[i - 1][j - 1]
-          : 1 + Math.min(dp[i - 1][j], dp[i][j - 1], dp[i - 1][j - 1]);
-    return dp[m][n];
+// ── Run ───────────────────────────────────────────────────────────────────────
+try {
+  await runCli();
+} catch (err) {
+  if (err instanceof CliError) {
+    console.error(`Error: ${err.message}`);
+    process.exit(err.exitCode);
   }
-
-  const primary = ["--version", "--help", "--hook", "policies"];
-  const closest = primary.reduce((best, flag) => {
-    const dist = levenshtein(unknownFlag, flag);
-    return dist < best.dist ? { flag, dist } : best;
-  }, { flag: primary[0], dist: Infinity });
-
-  console.error(`Unknown flag: ${unknownFlag}`);
-  console.error(`Did you mean: ${closest.flag}?`);
-  console.error(`Run \`failproofai --help\` for usage details.`);
-  process.exit(1);
-}
-
-// Unknown subcommand guard (non-flag args that aren't "policies")
-const unknownSubcommand = args.find(a => !a.startsWith("-") && a !== "policies");
-if (unknownSubcommand) {
-  console.error(`Unknown command: ${unknownSubcommand}`);
-  console.error(`Did you mean: failproofai policies?`);
-  console.error(`Run \`failproofai --help\` for usage details.`);
-  process.exit(1);
+  // Unexpected internal error — show message only, no stack trace
+  const msg = err instanceof Error ? err.message : String(err);
+  console.error(`Unexpected error: ${msg}`);
+  process.exit(2);
 }
-
-// Dashboard launch — always production mode
-const { launch } = await import("../scripts/launch");
-launch("start");