failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/custom-policies.mdx

@@ -0,0 +1,357 @@
+---
+title: Custom Policies
+description: "Write your own policies in JavaScript - enforce conventions, prevent drift, detect failures, integrate with external systems"
+icon: code
+---
+
+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.
+
+---
+
+## Quick example
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+customPolicies.add({
+  name: "no-production-writes",
+  description: "Block writes to paths containing 'production'",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Write" && ctx.toolName !== "Edit") return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("production")) {
+      return deny("Writes to production paths are blocked");
+    }
+    return allow();
+  },
+});
+```
+
+Install it:
+
+```bash
+failproofai policies --install --custom ./my-policies.js
+```
+
+---
+
+## Two ways to load custom policies
+
+### Option 1: Convention-based (recommended, v0.0.2-beta.7+)
+
+Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're automatically loaded — no flags or config changes needed. This works like git hooks: drop a file, it just works.
+
+```
+# Project level — committed to git, shared with the team
+.failproofai/policies/security-policies.mjs
+.failproofai/policies/workflow-policies.mjs
+
+# User level — personal, applies to all projects
+~/.failproofai/policies/my-policies.mjs
+```
+
+**How it works:**
+- Both project and user directories are scanned (union — not first-scope-wins)
+- Files are loaded alphabetically within each directory. Prefix with `01-`, `02-` to control order
+- Only files matching `*policies.{js,mjs,ts}` are loaded; other files are ignored
+- Each file is loaded independently (fail-open per file)
+- Works alongside explicit `--custom` and built-in policies
+
+<Tip>
+Convention policies are the easiest way to share policies across a team. Commit `.failproofai/policies/` to git and every team member gets them automatically.
+</Tip>
+
+### Option 2: Explicit file path
+
+```bash
+# Install with a custom policies file
+failproofai policies --install --custom ./my-policies.js
+
+# Replace the policies file path
+failproofai policies --install --custom ./new-policies.js
+
+# 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.
+
+### Using both together
+
+Convention policies and the explicit `--custom` file can coexist. Load order:
+
+1. Explicit `customPoliciesPath` file (if configured)
+2. Project convention files (`{cwd}/.failproofai/policies/`, alphabetical)
+3. User convention files (`~/.failproofai/policies/`, alphabetical)
+
+---
+
+## API
+
+### Import
+
+```js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+```
+
+### `customPolicies.add(hook)`
+
+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 `failproofai policies` output
+  match?: { events?: HookEventType[] }; // filter by event type; omit to match all
+  fn: (ctx: PolicyContext) => PolicyResult | Promise<PolicyResult>;
+});
+```
+
+### Decision helpers
+
+| Function | Effect | Use when |
+|----------|--------|----------|
+| `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:"`. A single `deny` short-circuits all further evaluation.
+
+`instruct(message)` - the message is appended to Claude's context for the current tool call. All `instruct` messages are accumulated and delivered together.
+
+<Tip>
+You can append extra guidance to any `deny` or `instruct` message by adding a `hint` field in `policyParams` — no code change needed. This works for custom (`custom/`), project convention (`.failproofai-project/`), and user convention (`.failproofai-user/`) policies too. See [Configuration → hint](/configuration#hint-cross-cutting) for details.
+</Tip>
+
+### 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
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `eventType` | `string` | `"PreToolUse"`, `"PostToolUse"`, `"Notification"`, `"Stop"` |
+| `toolName` | `string \| undefined` | The tool being called (e.g. `"Bash"`, `"Write"`, `"Read"`) |
+| `toolInput` | `Record<string, unknown> \| undefined` | The tool's input parameters |
+| `payload` | `Record<string, unknown>` | Full raw event payload from Claude Code |
+| `session` | `SessionMetadata \| undefined` | Session context (see below) |
+
+### `SessionMetadata` fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sessionId` | `string` | Claude Code session identifier |
+| `cwd` | `string` | Working directory of the Claude Code session |
+| `transcriptPath` | `string` | Path to the session's JSONL transcript file |
+
+### Event types
+
+| Event | When it fires | `toolInput` contents |
+|-------|--------------|----------------------|
+| `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 |
+| `Stop` | When the Claude session ends | Empty |
+
+---
+
+## Evaluation order
+
+Policies are evaluated in this order:
+
+1. Built-in policies (in definition order)
+2. Explicit custom policies from `customPoliciesPath` (in `.add()` order)
+3. Convention policies from project `.failproofai/policies/` (files alphabetical, `.add()` order within)
+4. Convention policies from user `~/.failproofai/policies/` (files alphabetical, `.add()` order within)
+
+<Note>
+The first `deny` short-circuits all subsequent policies. All `instruct` messages are accumulated and delivered together.
+</Note>
+
+---
+
+## Transitive imports
+
+Custom policy files can import local modules using relative paths:
+
+```js
+// my-policies.js
+import { isBlockedPath } from "./utils.js";
+import { checkApproval } from "./approval-client.js";
+
+customPolicies.add({
+  name: "approval-gate",
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const approved = await checkApproval(ctx.toolInput?.command, ctx.session?.sessionId);
+    return approved ? allow() : deny("Approval required for this command");
+  },
+});
+```
+
+All relative imports reachable from the entry file are resolved. This is implemented by rewriting `from "failproofai"` imports to the actual dist path and creating temporary `.mjs` files to ensure ESM compatibility.
+
+---
+
+## Event type filtering
+
+Use `match.events` to limit when a policy fires:
+
+```js
+customPolicies.add({
+  name: "require-summary-on-stop",
+  match: { events: ["Stop"] },
+  fn: async (ctx) => {
+    // Only fires when the session ends
+    // ctx.session.transcriptPath contains the full session log
+    return allow();
+  },
+});
+```
+
+Omit `match` entirely to fire on every event type.
+
+---
+
+## Error handling and failure modes
+
+Custom policies are **fail-open**: errors never block built-in policies or crash the hook handler.
+
+| Failure | Behavior |
+|---------|----------|
+| `customPoliciesPath` not set | No explicit custom policies run; convention policies and built-ins continue normally |
+| File not found | Warning logged to `~/.failproofai/hook.log`; built-ins continue |
+| Syntax/import error (explicit) | Error logged to `~/.failproofai/hook.log`; explicit custom policies skipped |
+| Syntax/import error (convention) | Error logged; that file skipped, other convention files still load |
+| `fn` throws at runtime | Error logged; that hook treated as `allow`; other hooks continue |
+| `fn` takes longer than 10s | Timeout logged; treated as `allow` |
+| Convention directory missing | No convention policies run; no error |
+
+<Tip>
+To debug custom policy errors, watch the log file:
+
+```bash
+tail -f ~/.failproofai/hook.log
+```
+</Tip>
+
+---
+
+## Full example: multiple policies
+
+```js
+// my-policies.js
+import { customPolicies, allow, deny, instruct } from "failproofai";
+
+// Prevent agent from writing to secrets/ directory
+customPolicies.add({
+  name: "block-secrets-dir",
+  description: "Prevent agent from writing to secrets/ directory",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (!["Write", "Edit"].includes(ctx.toolName ?? "")) return allow();
+    const path = ctx.toolInput?.file_path ?? "";
+    if (path.includes("secrets/")) return deny("Writing to secrets/ is not permitted");
+    return allow();
+  },
+});
+
+// Keep the agent on track: verify tests before committing
+customPolicies.add({
+  name: "remind-test-before-commit",
+  description: "Keep the agent on track: verify tests pass before committing",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    if (/git\s+commit/.test(cmd)) {
+      return instruct("Verify all tests pass before committing. Run `bun test` if you haven't already.");
+    }
+    return allow();
+  },
+});
+
+// Prevent unplanned dependency changes during freeze
+customPolicies.add({
+  name: "dependency-freeze",
+  description: "Prevent unplanned dependency changes during freeze period",
+  match: { events: ["PreToolUse"] },
+  fn: async (ctx) => {
+    if (ctx.toolName !== "Bash") return allow();
+    const cmd = ctx.toolInput?.command ?? "";
+    const isInstall = /^(npm install|yarn add|bun add|pnpm add)\s+\S/.test(cmd);
+    if (isInstall && process.env.DEPENDENCY_FREEZE === "1") {
+      return deny("Package installs are frozen. Unset DEPENDENCY_FREEZE to allow.");
+    }
+    return allow();
+  },
+});
+
+export { customPolicies };
+```
+
+---
+
+## Examples
+
+The `examples/` directory contains ready-to-run policy files:
+
+| File | Contents |
+|------|----------|
+| `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 |
+| `examples/convention-policies/security-policies.mjs` | Convention-based security policies (block .env writes, prevent git history rewriting) |
+| `examples/convention-policies/workflow-policies.mjs` | Convention-based workflow policies (test reminders, audit file writes) |
+
+### Using explicit file examples
+
+```bash
+failproofai policies --install --custom ./examples/policies-basic.js
+```
+
+### Using convention-based examples
+
+```bash
+# Copy to project level
+mkdir -p .failproofai/policies
+cp examples/convention-policies/*.mjs .failproofai/policies/
+
+# Or copy to user level
+mkdir -p ~/.failproofai/policies
+cp examples/convention-policies/*.mjs ~/.failproofai/policies/
+```
+
+No install command needed — the files are picked up automatically on the next hook event.

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>