failproofai 0.0.2-beta.2 → 0.0.2-beta.4

package/.next/standalone/docs/{custom-hooks.md → custom-policies.mdx}

@@ -1,10 +1,10 @@
 ---
-title: Custom Hooks
-description: "Write your own policies in JavaScript with allow, deny, and instruct decisions"
+title: Custom Policies
+description: "Write your own policies in JavaScript - enforce conventions, prevent drift, detect failures, integrate with external systems"
 icon: code
 ---
 
-Custom hooks let you write your own policies in JavaScript. They integrate with the same hook event system as built-in policies and support the same `allow`, `deny`, and `instruct` decisions.
+Custom policies let you write rules for any agent behavior: enforce project conventions, prevent drift, gate destructive operations, detect stuck agents, or integrate with Slack, approval workflows, and more. They use the same hook event system and `allow`, `deny`, `instruct` decisions as built-in policies.
 
 ---
 
@@ -32,7 +32,7 @@ customPolicies.add({
 Install it:
 
 ```bash
-failproofai --install-policies --custom ./my-policies.js
+failproofai policies --install --custom ./my-policies.js
 ```
 
 ---
@@ -40,17 +40,17 @@ failproofai --install-policies --custom ./my-policies.js
 ## Installing and updating
 
 ```bash
-# Install with a custom hooks file
-failproofai --install-policies --custom ./my-policies.js
+# Install with a custom policies file
+failproofai policies --install --custom ./my-policies.js
 
-# Replace the hooks file path
-failproofai --install-policies --custom ./new-policies.js
+# Replace the policies file path
+failproofai policies --install --custom ./new-policies.js
 
-# Remove the custom hooks path from config
-failproofai --remove-policies --custom
+# Remove the custom policies path from config
+failproofai policies --uninstall --custom
 ```
 
-The resolved absolute path is stored in `policies-config.json` as `customPoliciesPath`. The file is loaded fresh on every hook event — there is no caching between events.
+The resolved absolute path is stored in `policies-config.json` as `customPoliciesPath`. The file is loaded fresh on every hook event - there is no caching between events.
 
 ---
 
@@ -64,12 +64,12 @@ import { customPolicies, allow, deny, instruct } from "failproofai";
 
 ### `customPolicies.add(hook)`
 
-Registers a hook. Call this as many times as needed for multiple hooks in the same file.
+Registers a policy. Call this as many times as needed for multiple policies in the same file.
 
 ```ts
 customPolicies.add({
-  name: string;                         // required — unique identifier
-  description?: string;                 // shown in --list-policies output
+  name: string;                         // required - unique identifier
+  description?: string;                 // shown in `failproofai policies` output
   match?: { events?: HookEventType[] }; // filter by event type; omit to match all
   fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
 });
@@ -79,13 +79,47 @@ customPolicies.add({
 
 | Function | Effect | Use when |
 |----------|--------|----------|
-| `allow()` | Permit the tool call | Nothing to block or warn about |
-| `deny(message)` | Block the tool call | The action should not proceed |
-| `instruct(message)` | Add context to Claude's prompt | You want Claude to be careful but not stopped |
+| `allow()` | Permit the operation silently | The action is safe, no message needed |
+| `deny(message)` | Block the operation | The agent should not take this action |
+| `instruct(message)` | Add context without blocking | Give the agent extra context to stay on track |
 
-`deny(message)` — the message appears to Claude prefixed with `"Blocked by failproofai:"`.
+`deny(message)` - the message appears to Claude prefixed with `"Blocked by failproofai:"`. A single `deny` short-circuits all further evaluation.
 
-`instruct(message)` — the message is appended to Claude's context for the current tool call. Multiple `instruct` returns from different hooks accumulate; a single `deny` short-circuits all further evaluation.
+`instruct(message)` - the message is appended to Claude's context for the current tool call. The first `instruct` wins — subsequent `instruct` returns from other policies are ignored.
+
+### Informational allow messages (beta)
+
+<Note>
+`allow(message)` is a beta feature available since v0.0.2-beta.3. The API may change in future releases. Earlier versions only support `allow()` without arguments.
+</Note>
+
+`allow(message)` permits the operation **and** sends an informational message back to Claude. The message is delivered as `additionalContext` in the hook handler's stdout response — the same mechanism used by `instruct`, but semantically different: it's a status update, not a warning.
+
+| Function | Effect | Use when |
+|----------|--------|----------|
+| `allow(message)` | Permit and send context to Claude | Confirm a check passed, or explain why a check was skipped |
+
+Use cases:
+- **Status confirmations:** `allow("All CI checks passed.")` — tells Claude everything is green
+- **Fail-open explanations:** `allow("GitHub CLI not installed, skipping CI check.")` — tells Claude why a check was skipped so it has full context
+- **Multiple messages accumulate:** if several policies each return `allow(message)`, all messages are joined with newlines and delivered together
+
+```js
+customPolicies.add({
+  name: "confirm-branch-status",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    const cwd = ctx.session?.cwd;
+    if (!cwd) return allow("No working directory, skipping branch check.");
+
+    // ... check branch status ...
+    if (allPushed) {
+      return allow("Branch is up to date with remote.");
+    }
+    return deny("Unpushed changes detected.");
+  },
+});
+```
 
 ### `PolicyContext` fields
 
@@ -111,25 +145,27 @@ customPolicies.add({
 |-------|--------------|----------------------|
 | `PreToolUse` | Before Claude runs a tool | The tool's input (e.g. `{ command: "..." }` for Bash) |
 | `PostToolUse` | After a tool completes | The tool's input + `tool_result` (the output) |
-| `Notification` | When Claude sends a notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` — hooks must always return `allow()`, they cannot block notifications |
+| `Notification` | When Claude sends a notification | `{ message: "...", notification_type: "idle" \| "permission_prompt" \| ... }` - hooks must always return `allow()`, they cannot block notifications |
 | `Stop` | When the Claude session ends | Empty |
 
 ---
 
 ## Evaluation order
 
-Hooks are evaluated in this order:
+Policies are evaluated in this order:
 
 1. Built-in policies (in definition order)
-2. Custom hooks (in `.add()` order)
+2. Custom policies (in `.add()` order)
 
-The first `deny` short-circuits all subsequent hooks. All `instruct` returns accumulate into a single message regardless of which hook produced them.
+<Note>
+The first `deny` short-circuits all subsequent policies. The first `instruct` wins — subsequent `instruct` returns are ignored.
+</Note>
 
 ---
 
 ## Transitive imports
 
-Custom hook files can import local modules using relative paths:
+Custom policy files can import local modules using relative paths:
 
 ```js
 // my-policies.js
@@ -150,9 +186,9 @@ All relative imports reachable from the entry file are resolved. This is impleme
 
 ---
 
-## Hook event type filtering
+## Event type filtering
 
-Use `match.events` to limit when a hook fires:
+Use `match.events` to limit when a policy fires:
 
 ```js
 customPolicies.add({
@@ -172,34 +208,36 @@ Omit `match` entirely to fire on every event type.
 
 ## Error handling and failure modes
 
-Custom hooks are **fail-open**: errors never block built-in policies or crash the hook handler.
+Custom policies are **fail-open**: errors never block built-in policies or crash the hook handler.
 
 | Failure | Behavior |
 |---------|----------|
-| `customPoliciesPath` not set | No custom hooks run; built-ins continue normally |
+| `customPoliciesPath` not set | No custom policies run; built-ins continue normally |
 | File not found | Warning logged to `~/.failproofai/hook.log`; built-ins continue |
-| Syntax/import error | Error logged to `~/.failproofai/hook.log`; all custom hooks skipped |
+| Syntax/import error | Error logged to `~/.failproofai/hook.log`; all custom policies skipped |
 | `fn` throws at runtime | Error logged; that hook treated as `allow`; other hooks continue |
 | `fn` takes longer than 10s | Timeout logged; treated as `allow` |
 
-To debug custom hook errors:
+<Tip>
+To debug custom policy errors, watch the log file:
 
 ```bash
 tail -f ~/.failproofai/hook.log
 ```
+</Tip>
 
 ---
 
-## Full example: multiple hooks
+## Full example: multiple policies
 
 ```js
 // my-policies.js
 import { customPolicies, allow, deny, instruct } from "failproofai";
 
-// Block any write to a path containing "secrets/"
+// Prevent agent from writing to secrets/ directory
 customPolicies.add({
   name: "block-secrets-dir",
-  description: "Block writes to secrets/ directory",
+  description: "Prevent agent from writing to secrets/ directory",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
@@ -209,10 +247,10 @@ customPolicies.add({
   },
 });
 
-// Remind Claude to check test results before committing
+// Keep the agent on track: verify tests before committing
 customPolicies.add({
   name: "remind-test-before-commit",
-  description: "Remind Claude to verify tests pass before committing",
+  description: "Keep the agent on track: verify tests pass before committing",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (ctx.toolName !== "Bash") return allow();
@@ -224,10 +262,10 @@ customPolicies.add({
   },
 });
 
-// Block npm install during a freeze period
+// Prevent unplanned dependency changes during freeze
 customPolicies.add({
   name: "dependency-freeze",
-  description: "Block new package installs during freeze period",
+  description: "Prevent unplanned dependency changes during freeze period",
   match: { events: ["PreToolUse"] },
   fn: async (ctx) => {
     if (ctx.toolName !== "Bash") return allow();
@@ -245,17 +283,17 @@ export { customPolicies };
 
 ---
 
-## Examples in the repository
+## Examples
 
-The `examples/` directory contains ready-to-run hook files:
+The `examples/` directory contains ready-to-run policy files:
 
 | File | Contents |
 |------|----------|
-| `examples/policies-basic.js` | Five starter policies covering common use cases |
-| `examples/policies-advanced/index.js` | Advanced patterns including transitive imports, async calls, and `Stop` event hooks |
+| `examples/policies-basic.js` | Five starter policies covering common agent failure modes |
+| `examples/policies-advanced/index.js` | Advanced patterns: transitive imports, async calls, output scrubbing, and session-end hooks |
 
 Install the basic examples:
 
 ```bash
-failproofai --install-policies --custom ./examples/policies-basic.js
+failproofai policies --install --custom ./examples/policies-basic.js
 ```

package/.next/standalone/docs/{dashboard.md → dashboard.mdx}

@@ -1,10 +1,10 @@
 ---
 title: Dashboard
-description: "Session viewer, policy management, and activity log"
+description: "Monitor agent sessions, review tool calls, and manage policies"
 icon: chart-line
 ---
 
-The failproofai dashboard is a local web application for browsing Claude Code sessions and managing security policies.
+The failproofai dashboard is a local web application for monitoring your AI agent sessions and managing policies. See what your agents did while you were away.
 
 ---
 
@@ -16,13 +16,7 @@ failproofai
 
 Opens at `http://localhost:8020`.
 
-For production mode (faster startup, no file watching):
-
-```bash
-failproofai --start
-```
-
-The dashboard reads directly from the filesystem — your Claude Code project folders and the failproofai config files. Nothing is written to a remote service.
+The dashboard reads directly from the filesystem - your Claude Code project folders and the failproofai config files. Nothing is written to a remote service.
 
 ---
 
@@ -53,11 +47,11 @@ Click a session to open the session viewer.
 
 ### Session viewer
 
-A timeline of everything that happened in a session:
+The session viewer answers the key question for autonomous agents: what did the agent do, and did it stay on track? It shows a timeline of everything that happened in a session:
 
-- **Messages** — Claude's text responses and user prompts
-- **Tool calls** — Every tool Claude invoked, with its input and output
-- **Hook activity** — For each tool call, which policies fired and what decision they returned
+- **Messages** - Claude's text responses and user prompts
+- **Tool calls** - Every tool Claude invoked, with its input and output
+- **Policy activity** - For each tool call, which policies fired and what decision they returned
 
 The stats bar at the top shows session duration, total tool calls, and a summary of hook decisions (allow / deny / instruct counts).
 
@@ -67,24 +61,25 @@ You can export the session as a ZIP or JSONL file using the download button.
 
 A two-tab page for managing policies and reviewing activity.
 
-**Policies tab:**
-
-- Toggle individual policies on or off with a single click (writes to `~/.failproofai/policies-config.json`)
-- Expand a policy to configure its parameters (for policies that support `policyParams`)
-- Install or remove hooks for a given scope
-- Set a custom hooks file path
-
-**Activity tab:**
-
-- Full paginated history of every hook event that has fired across all sessions
-- Search by policy name, session ID, tool name, or decision
-- Each row shows: timestamp, policy name, decision, tool name, session ID, and the reason for deny/instruct decisions
+<Tabs>
+  <Tab title="Policies tab">
+  - Toggle individual policies on or off with a single click (writes to `~/.failproofai/policies-config.json`)
+  - Expand a policy to configure its parameters (for policies that support `policyParams`)
+  - Install or remove hooks for a given scope
+  - Set a custom policies file path
+  </Tab>
+  <Tab title="Activity tab">
+  - Full paginated history of every hook event that has fired across all sessions
+  - Search by policy name, session ID, tool name, or decision
+  - Each row shows: timestamp, policy name, decision, tool name, session ID, and the reason for deny/instruct decisions
+  </Tab>
+</Tabs>
 
 ---
 
 ## Auto-refresh
 
-The dashboard has an auto-refresh toggle in the top navigation. When enabled, the current page refreshes periodically to show new sessions and hook activity as they appear. Useful when you have an active Claude Code session running in parallel.
+The dashboard has an auto-refresh toggle in the top navigation. When enabled, the current page refreshes periodically to show new sessions and policy activity as they appear. Essential for monitoring long-running autonomous agent sessions.
 
 ---
 
@@ -118,9 +113,9 @@ CLAUDE_PROJECTS_PATH=/custom/path/to/projects failproofai
 
 ## Accessing from a non-localhost host
 
-When running the dashboard in **dev mode** (`npm run dev`) and accessing it from a hostname other than `localhost` — for example, a custom domain, a remote IP, or a tunneled URL — you may see a warning like:
+When running the dashboard in **dev mode** (`npm run dev`) and accessing it from a hostname other than `localhost` - for example, a custom domain, a remote IP, or a tunneled URL - you may see a warning like:
 
-```
+```text
 ⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
 ```
 
@@ -142,4 +137,6 @@ You can also set the `FAILPROOFAI_ALLOWED_DEV_ORIGINS` environment variable inst
 FAILPROOFAI_ALLOWED_DEV_ORIGINS=dashboard.example.com npm run dev
 ```
 
-> **Note:** This only applies to dev mode. When running `failproofai` (production mode), there is no HMR websocket and no cross-origin dev resource issue.
+<Note>
+This only applies to dev mode. When running `failproofai` (production mode), there is no HMR websocket and no cross-origin dev resource issue.
+</Note>

package/.next/standalone/docs/docs.json

@@ -7,6 +7,10 @@
     "light": "#e4587d",
     "dark": "#002CA7"
   },
+  "logo": {
+    "light": "/logo/exosphere-light.png",
+    "dark": "/logo/exosphere-dark.png"
+  },
   "favicon": "/favicon.ico",
   "navigation": {
     "tabs": [
@@ -23,15 +27,26 @@
           {
             "group": "Core Concepts",
             "pages": [
-              "configuration",
               "built-in-policies",
-              "custom-hooks"
+              "custom-policies",
+              "configuration"
+            ]
+          },
+          {
+            "group": "CLI",
+            "pages": [
+              "cli/dashboard",
+              "cli/install-policies",
+              "cli/remove-policies",
+              "cli/list-policies",
+              "cli/hook",
+              "cli/version",
+              "cli/environment-variables"
             ]
           },
           {
             "group": "Tools",
             "pages": [
-              "cli-reference",
               "dashboard"
             ]
           },
@@ -40,7 +55,19 @@
             "pages": [
               "architecture",
               "testing",
-              "package-aliases"
+              "package-aliases",
+              "for-agents"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Examples",
+        "groups": [
+          {
+            "group": "Examples",
+            "pages": [
+              "examples"
             ]
           }
         ]

package/.next/standalone/docs/examples.mdx

@@ -0,0 +1,253 @@
+---
+title: Examples
+description: "How to set up hooks for Claude Code and the Agents SDK"
+icon: book-open
+---
+
+Ready-to-use examples for common scenarios. Each one shows how to install and what to expect.
+
+---
+
+## Setting up hooks for Claude Code
+
+Failproof AI integrates with Claude Code via its [hooks system](https://docs.anthropic.com/en/docs/claude-code/hooks). When you run `failproofai policies --install`, it registers hook commands in Claude Code's `settings.json` that fire on every tool call.
+
+<Steps>
+  <Step title="Install failproofai">
+    ```bash
+    npm install -g failproofai
+    ```
+  </Step>
+  <Step title="Enable all built-in policies">
+    ```bash
+    failproofai policies --install
+    ```
+  </Step>
+  <Step title="Verify hooks are registered">
+    ```bash
+    cat ~/.claude/settings.json | grep failproofai
+    ```
+
+    You should see hook entries for `PreToolUse`, `PostToolUse`, `Notification`, and `Stop` events.
+  </Step>
+  <Step title="Run Claude Code">
+    ```bash
+    claude
+    ```
+
+    Policies now run automatically on every tool call. Try asking Claude to run `sudo rm -rf /` - it will be blocked.
+  </Step>
+</Steps>
+
+---
+
+## Setting up hooks for the Agents SDK
+
+If you're building with the [Agents SDK](https://docs.anthropic.com/en/docs/agents-sdk), you can use the same hook system programmatically.
+
+<Steps>
+  <Step title="Install failproofai in your project">
+    ```bash
+    npm install failproofai
+    ```
+  </Step>
+  <Step title="Configure hooks in your agent">
+    Pass hook commands when creating your agent process. The hooks fire the same way as in Claude Code - via stdin/stdout JSON:
+
+    ```bash
+    failproofai --hook PreToolUse   # called before each tool
+    failproofai --hook PostToolUse  # called after each tool
+    ```
+  </Step>
+  <Step title="Write a custom policy for your agent">
+    ```javascript
+    import { customPolicies, allow, deny } from "failproofai";
+
+    customPolicies.add({
+      name: "limit-to-project-dir",
+      description: "Keep the agent inside the project directory",
+      match: { events: ["PreToolUse"] },
+      fn: async (ctx) => {
+        const path = String(ctx.toolInput?.file_path ?? "");
+        if (path.startsWith("/") && !path.startsWith(ctx.session?.cwd ?? "")) {
+          return deny("Agent is restricted to the project directory");
+        }
+        return allow();
+      },
+    });
+    ```
+  </Step>
+  <Step title="Install the custom policy">
+    ```bash
+    failproofai policies --install --custom ./my-agent-policies.js
+    ```
+  </Step>
+</Steps>
+
+---
+
+## Block destructive commands
+
+The most common setup - prevent agents from doing irreversible damage.
+
+```bash
+failproofai policies --install block-sudo block-rm-rf block-force-push block-curl-pipe-sh
+```
+
+What this does:
+- `block-sudo` - blocks all `sudo` commands
+- `block-rm-rf` - blocks recursive file deletion
+- `block-force-push` - blocks `git push --force`
+- `block-curl-pipe-sh` - blocks piping remote scripts to shell
+
+---
+
+## Prevent secret leakage
+
+Stop agents from seeing or leaking credentials in tool output.
+
+```bash
+failproofai policies --install sanitize-api-keys sanitize-jwt sanitize-connection-strings sanitize-bearer-tokens
+```
+
+These fire on `PostToolUse` - after a tool runs, they scrub the output before the agent sees it.
+
+---
+
+## Get Slack alerts when agents need attention
+
+Use the notification hook to forward idle alerts to Slack.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "slack-on-idle",
+  description: "Alert Slack when the agent is waiting for input",
+  match: { events: ["Notification"] },
+  fn: async (ctx) => {
+    const webhookUrl = process.env.SLACK_WEBHOOK_URL;
+    if (!webhookUrl) return allow();
+
+    const message = String(ctx.payload?.message ?? "Agent is waiting");
+    const project = ctx.session?.cwd ?? "unknown";
+
+    try {
+      await fetch(webhookUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+          text: `*${message}*\nProject: \`${project}\``,
+        }),
+        signal: AbortSignal.timeout(5000),
+      });
+    } catch {
+      // never block the agent if Slack is unreachable
+    }
+
+    return allow();
+  },
+});
+```
+
+Install it:
+
+```bash
+SLACK_WEBHOOK_URL=https://hooks.slack.com/... failproofai policies --install --custom ./slack-alerts.js
+```
+
+---
+
+## Keep agents on a branch
+
+Prevent agents from switching branches or pushing to protected ones.
+
+```javascript
+import { customPolicies, allow, deny } from "failproofai";
+
+customPolicies.add({
+  name: "stay-on-branch",
+  description: "Prevent the agent from checking out other branches",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+checkout\s+(?!-b)/.test(cmd)) {
+      return deny("Stay on the current branch. Create a new branch with -b if needed.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Require tests before commits
+
+Remind agents to run tests before committing.
+
+```javascript
+import { customPolicies, allow, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "test-before-commit",
+  description: "Remind the agent to run tests before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = String(ctx.toolInput?.command ?? "");
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Run tests before committing. Use `npm test` or `bun test` first.");
+    }
+    return allow();
+  },
+});
+```
+
+---
+
+## Lock down a production repo
+
+Commit a project-level config so every developer on your team gets the same policies.
+
+Create `.failproofai/policies-config.json` in your repo:
+
+```json
+{
+  "enabledPolicies": [
+    "block-sudo",
+    "block-rm-rf",
+    "block-force-push",
+    "block-push-master",
+    "block-env-files",
+    "sanitize-api-keys",
+    "sanitize-jwt"
+  ],
+  "policyParams": {
+    "block-push-master": {
+      "protectedBranches": ["main", "release", "production"]
+    }
+  }
+}
+```
+
+Then commit it:
+
+```bash
+git add .failproofai/policies-config.json
+git commit -m "Add failproofai team policies"
+```
+
+Every team member who has failproofai installed will automatically pick up these rules.
+
+---
+
+## More examples
+
+The [`examples/`](https://github.com/exospherehost/failproofai/tree/main/examples) directory in the repo contains:
+
+| File | What it shows |
+|------|---------------|
+| `policies-basic.js` | Starter policies - block production writes, force-push, piped scripts |
+| `policies-notification.js` | Slack alerts for idle notifications and session end |
+| `policies-advanced/index.js` | Transitive imports, async hooks, PostToolUse output scrubbing, Stop event handling |