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

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

@@ -4,7 +4,7 @@ description: "Config file format, three-scope system, and merge rules"
 icon: gear
 ---
 
-failproofai uses JSON configuration files to control which policies are active, how they behave, and where custom hooks are loaded from.
+failproofai uses JSON configuration files to control which policies are active, how they behave, and where custom policies are loaded from. Configuration is designed to be easy to share with your team - commit it to your repo and every developer gets the same agent safety net.
 
 ---
 
@@ -22,9 +22,9 @@ When failproofai receives a hook event, it loads and merges all three files that
 
 ### Merge rules
 
-**`enabledPolicies`** — the union of all three scopes. A policy enabled at any level is active.
+**`enabledPolicies`** - the union of all three scopes. A policy enabled at any level is active.
 
-```
+```text
 project:  ["block-sudo"]
 local:    ["block-rm-rf"]
 global:   ["block-sudo", "sanitize-api-keys"]
@@ -32,16 +32,16 @@ global:   ["block-sudo", "sanitize-api-keys"]
 resolved: ["block-sudo", "block-rm-rf", "sanitize-api-keys"]  ← deduplicated union
 ```
 
-**`policyParams`** — first scope that defines params for a given policy wins entirely. There is no deep merging of values within a policy's params.
+**`policyParams`** - first scope that defines params for a given policy wins entirely. There is no deep merging of values within a policy's params.
 
-```
+```text
 project:  block-sudo → { allowPatterns: ["sudo apt-get update"] }
 global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 
 resolved: { allowPatterns: ["sudo apt-get update"] }   ← project wins, global ignored
 ```
 
-```
+```text
 project:  (no block-sudo entry)
 local:    (no block-sudo entry)
 global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
@@ -49,9 +49,9 @@ global:   block-sudo → { allowPatterns: ["sudo systemctl status"] }
 resolved: { allowPatterns: ["sudo systemctl status"] }  ← falls through to global
 ```
 
-**`customPoliciesPath`** — first scope that defines it wins.
+**`customPoliciesPath`** - first scope that defines it wins.
 
-**`llm`** — first scope that defines it wins.
+**`llm`** - first scope that defines it wins.
 
 ---
 
@@ -102,7 +102,7 @@ resolved: { allowPatterns: ["sudo systemctl status"] }  ← falls through to glo
 
 Type: `string[]`
 
-List of policy names to enable. Names must match exactly the policy identifiers shown in `failproofai --list-policies`. See [Built-in Policies](./built-in-policies.md) for the full list.
+List of policy names to enable. Names must match exactly the policy identifiers shown by `failproofai policies`. See [Built-in Policies](/built-in-policies) for the full list.
 
 Policies not in `enabledPolicies` are inactive, even if they have entries in `policyParams`.
 
@@ -110,19 +110,19 @@ Policies not in `enabledPolicies` are inactive, even if they have entries in `po
 
 Type: `Record<string, Record<string, unknown>>`
 
-Per-policy parameter overrides. The outer key is the policy name; the inner keys are policy-specific. Each policy documents its available parameters in [Built-in Policies](./built-in-policies.md).
+Per-policy parameter overrides. The outer key is the policy name; the inner keys are policy-specific. Each policy documents its available parameters in [Built-in Policies](/built-in-policies).
 
 If a policy has parameters but you don't specify them, the policy's built-in defaults are used. Users who do not configure `policyParams` at all get identical behavior to previous versions.
 
-Unknown keys inside a policy's params block are silently ignored at hook-fire time but flagged as warnings when you run `failproofai --list-policies`.
+Unknown keys inside a policy's params block are silently ignored at hook-fire time but flagged as warnings when you run `failproofai policies`.
 
 ### `customPoliciesPath`
 
 Type: `string` (absolute path)
 
-Path to a JavaScript file containing custom hook policies. This is set automatically by `failproofai --install-policies --custom <path>` (the path is resolved to absolute before being stored).
+Path to a JavaScript file containing custom hook policies. This is set automatically by `failproofai policies --install --custom <path>` (the path is resolved to absolute before being stored).
 
-The file is loaded fresh on every hook event — there is no caching. See [Custom Hooks](./custom-hooks.md) for authoring details.
+The file is loaded fresh on every hook event - there is no caching. See [Custom Policies](/custom-policies) for authoring details.
 
 ### `llm`
 
@@ -143,10 +143,10 @@ LLM client configuration for policies that make AI calls. Not required for most
 
 ## Managing configuration from the CLI
 
-The `--install-policies` and `--remove-policies` commands write to Claude Code's `settings.json` (the hook entry points), while `policies-config.json` is the file you manage directly. The two are separate:
+The `policies --install` and `policies --uninstall` commands write to Claude Code's `settings.json` (the hook entry points), while `policies-config.json` is the file you manage directly. The two are separate:
 
-- **`settings.json`** — tells Claude Code to call `failproofai --hook <event>` on each tool use
-- **`policies-config.json`** — tells failproofai which policies to evaluate and with what params
+- **`settings.json`** - tells Claude Code to call `failproofai --hook <event>` on each tool use
+- **`policies-config.json`** - tells failproofai which policies to evaluate and with what params
 
 You can edit `policies-config.json` directly at any time; changes take effect immediately on the next hook event with no restart needed.
 

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"
             ]
           }
         ]