failproofai 1.0.1-beta.0 → 1.0.1

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

@@ -0,0 +1,362 @@
+---
+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)
+
+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 build a quality standard for your org. Commit `.failproofai/policies/` to git and every team member gets the same rules automatically — no per-developer setup needed. As your team discovers new failure modes, add a policy and push. Over time these become a living quality standard that keeps improving with every contribution.
+</Tip>
+
+### Option 2: Explicit file path
+
+```bash
+# Install with a custom policies file
+failproofai policies --install --custom ./my-policies.js
+
+# Replace the custom policy paths
+failproofai policies --install --custom ./new-policies.js
+
+# Configure multiple explicit files (loaded in flag order)
+failproofai policies --install --custom ./security.js --custom ./workflow.js
+
+# Remove all explicit custom policy paths from config
+failproofai policies --uninstall --custom
+```
+
+Resolved absolute paths are stored in `policies-config.json` as `customPoliciesPaths`. Repeat `--custom` to configure multiple files. Existing configs using the legacy `customPoliciesPath` field continue to work. Files are loaded fresh on every hook event - there is no caching between events.
+
+Each registered policy appears with its own toggle in the dashboard. Switching
+a policy off records its source-qualified ID in `disabledCustomPolicies`; the
+file and its other policies continue to load, while the disabled policy is
+excluded before event matching. Policy names duplicated across files have
+independent toggles.
+
+### Using both together
+
+Convention policies and the explicit `--custom` files can coexist. Load order:
+
+1. Explicit `customPoliciesPaths` files (in configured order)
+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
+
+`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-old/dashboard.mdx

@@ -0,0 +1,176 @@
+---
+title: Dashboard
+description: "Monitor agent sessions, review tool calls, and manage policies"
+icon: chart-line
+---
+
+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.
+
+---
+
+## Starting the dashboard
+
+```bash
+failproofai
+```
+
+Opens at `http://localhost:8020`.
+
+The dashboard reads local project, session, and failproofai configuration data directly from the filesystem. Optional authenticated features — invitations, and the [emailed harm digest](/cli/audit#what-a-digest-sends) from a scheduled audit — send the information needed for those requests (including email addresses) to remote APIs. Nothing else leaves the machine.
+
+---
+
+## Pages
+
+### Projects
+
+Lists all Claude Code, OpenAI Codex, GitHub Copilot CLI _(beta)_, Cursor Agent _(beta)_, OpenCode _(beta)_, Pi _(beta)_, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, and Goose projects found on your machine. Claude projects are discovered from `~/.claude/projects/` (or the path set by `CLAUDE_PROJECTS_PATH`); Codex projects are discovered by scanning every transcript under `~/.codex/sessions/<YYYY>/<MM>/<DD>/*.jsonl` and grouping by the `cwd` recorded in each session's first record; Copilot CLI projects are discovered by scanning each `~/.copilot/session-state/<sessionId>/workspace.yaml` (configurable via `COPILOT_HOME`) and grouping by its `cwd` field; Cursor Agent projects are discovered by scanning per-session metadata under `~/.cursor/agent-sessions/<sessionId>/` (configurable via `CURSOR_HOME`, with `conversations/` and `sessions/` probed as fallbacks) for a `cwd` scalar in `meta.json` / `session.json` / `workspace.yaml`; OpenCode projects are discovered by querying its SQLite DB at `~/.local/share/opencode/opencode.db` via `opencode db --format json` (we read the `session` and `project` tables and group by `project_id`); Pi projects are discovered by scanning per-session JSONL transcripts under `~/.pi/agent/sessions/<encoded-cwd>/<timestamp>_<uuid>.jsonl` (configurable via `PI_SESSIONS_DIR`) and pulling the `cwd` from each session's first record; Hermes gateway sessions are read directly from the SQLite store of every profile — `~/.hermes/state.db` plus `~/.hermes/profiles/<name>/state.db` (overridable via `HERMES_HOME`, or `HERMES_DB_PATH` for a single database) — and grouped into `hermes-<profile>-<source>` projects by profile and `source` (Slack/Telegram/cli/cron — gateway sessions have no cwd); OpenClaw gateway sessions are read from `~/.openclaw/agents/<agentId>/sessions/*.jsonl` and grouped into `openclaw-<agentId>-<channel>` projects by agent and channel (also cwd-less); Factory Droid projects are discovered from the JSONL transcripts at `~/.factory/sessions/<encoded-cwd>/*.jsonl` and grouped by cwd; Devin projects from its SQLite DB at `~/.local/share/devin/cli/sessions.db` (grouped by each session's `working_directory`); Antigravity projects from the JSONL transcripts at `~/.gemini/antigravity-cli/brain/<conversationId>/…/transcript_full.jsonl` and grouped by cwd; and Goose projects from its SQLite DB at `~/.local/share/goose/sessions/sessions.db` (grouped by each session's `working_dir`). A project that has been used by multiple CLIs renders as a single row with all matching badges. Use the **CLI** dropdown above the table to filter by a specific agent CLI; the URL preserves your selection as `?cli=claude|codex|copilot|cursor|opencode|pi|hermes|openclaw|factory|devin|antigravity|goose`.
+
+Hermes and OpenClaw are user-scoped and have no working directory to group by, so they render as a **collapsible folder tree** — profile (or agent) at the top level, its channels beneath — while every cwd-based CLI stays a flat row. Folder rows roll up the session count and most recent activity of everything under them, collapsed folders are remembered between visits, and a keyword search expands whatever it matches.
+
+Each project shows:
+- Project name (derived from the folder path)
+- A CLI badge — `Claude Code` (orange), `OpenAI Codex` (purple), `GitHub Copilot` (blue), `Cursor Agent` (emerald), `OpenCode` (amber), `Pi` (pink), and/or `Hermes` (indigo)
+- Date of most recent session activity
+
+Click a project to see its sessions.
+
+### Sessions
+
+Lists all sessions within a project. Each session shows:
+- Session ID
+- Start and end timestamps
+- Number of tool calls
+- Hook activity count (policies that fired)
+
+Use the date range filter and session ID search to narrow the list. Sessions are paginated.
+
+Click a session to open the session viewer.
+
+### Session viewer
+
+The session viewer answers the key question for autonomous agents: what did the agent do, and did it stay on track? A CLI badge beside the header indicates whether the session is a Claude Code, OpenAI Codex, GitHub Copilot CLI, Cursor Agent, OpenCode, Pi, Hermes, OpenClaw, Factory Droid, Devin, Antigravity, or Goose transcript. 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
+- **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).
+
+Click the **Download Logs** button to export the session. For Claude Code, Codex, Copilot, Cursor, and Pi sessions you get the original on-disk JSONL transcript byte-for-byte; for OpenCode (whose sessions live in SQLite, not on disk) you get a JSON document mirroring the underlying `session` / `messages` / `parts` tables.
+
+### Audit
+
+A personality-driven report of how your agent has actually been behaving across past sessions. Runs the same scan as the `failproofai audit` CLI but renders it as a single-screen shareable poster + four below-the-fold sections:
+
+1. **Poster** — fills the first viewport. Self-contained PNG-capture region with the failproof_ai wordmark + audit label · archetype index (`№ NN of 08`) + audit date · numeric score (0–100) + percentile rank pill (`top 15%`) · the archetype name (one of `the optimist`, `the cowboy`, `the explorer`, `the goldfish`, `the paranoid architect`, `the precision builder`, `the hammer`, `the ghost`) + 3-keyword strip · `// only N% of agents are this archetype` rarity line · 8×8 pixel sigil tile · `audit yours → failproof.ai` footer. Three share buttons sit just outside the capture box: `post your archetype` (X intent), `share on linkedin`, `download poster`. Capture runs through `html-to-image` so the PNG matches the on-screen render pixel-for-pixel (dashed borders, SVG logo mask, gradients, font metrics — all preserved).
+2. **Strengths** — calm ✓ row list of behaviors your agent already does right, derived from the live audit data (clean tool-call rate, no direct pushes to main, zero credential leaks, zero retry storms) — each surfaced only when the relevant policy has a clean record across the audit window.
+3. **Quirks** — table of what slipped through, ranked by severity: `when · what slipped + the policy that would've caught it · severity pill · seen`, where the recurrence reads `new` (once), `N× seen` (2–9 times), or `recurring` (10+).
+4. **How to improve** — calm row list, one per prescribed policy: policy name in white, one-line description, install command + copy button on the right side. The section header reads `enable all N → projected <score> · <tier>` (the score you'd reach with every fix applied), and its `[install all]` button copies the combined `failproofai policy add a b c …` command for every prescribed policy.
+5. **Spread the audit** — `invite a friend` opens a modal that takes a comma/space/newline-separated list of friend emails (max 10 per send), POSTs them to `/api/audit/invite`, which forwards to the api-server's `POST /v0/invite`. The api-server sends one email per recipient from `invite@failproof.ai` with the sender Cc'd and `Reply-To` set, so the recipient sees who invited them and the sender gets a copy in their inbox. Anonymous users get routed through the `AuthDialog` first so the sender's email is known before invites go out. Entitlement / perks fulfillment is a follow-up.
+
+   The re-audit **reminder** cadence picker that used to sit beside it is gone, along with its `/api/auth/reminder` route. Recurring scans are a machine setting rather than the end of a report, so they live on **[/settings](#settings)** (the gear in the header) and in `failproofai audit --schedule` — where the same control also runs the scan, rather than only mailing you a nudge to run it yourself. See [scheduled audits](/cli/audit#scheduled-audits).
+
+Driven by the `failproofai audit` runtime — see [Audit CLI](/cli/audit) for the underlying scan engine, supported flags, and per-transcript cache invariants. The dashboard caches the latest result at `~/.failproofai/audit-dashboard.json` (mode `0600`, single slot, new runs overwrite) so revisits are instant; **both the per-transcript and whole-result caches are rejected on read once they're older than 7 days** so the dashboard never silently serves a week-old result — past the TTL `/audit` falls through to its empty state and prompts a fresh run. Clicking `[ re-audit now ]` near the bottom of the report POSTs `/api/audit/run` with `noCache: true` — re-audit bypasses the per-transcript cache and re-scans every transcript from scratch rather than silently returning the cached result — and the dashboard polls `/api/audit/status` at 1Hz until the run finishes; a sticky pink progress strip pins to the top of the viewport during the run with an elapsed timer, and the fresh result swaps in place on success (no full-page reload; a failed re-audit leaves the prior report intact). On failure the strip turns red with copy keyed off the `RerunError.kind` (`timeout` / `network` / `post_failed`). Empty state (no cache or expired) and zero-sessions state (cache exists but the scan found no transcripts) are surfaced separately.
+
+### Policies
+
+A two-tab page for managing policies and reviewing activity.
+
+<Tabs>
+  <Tab title="Policies tab">
+  - Multi-select which agent CLIs failproofai protects from a single panel — Claude Code, OpenAI Codex, GitHub Copilot, Cursor Agent, OpenCode, Pi, and Hermes all have a row with install status (`Active` / `Detected` / `Inactive`), the user-scope settings path, and a brand-colored accent. Check or uncheck the CLIs you want and click `Apply changes` to install/uninstall the diff in one step. CLIs whose binary is detected on PATH are pre-checked.
+  - Toggle individual policies on or off with a single click (writes to `~/.failproofai/policies-config.json` — shared across every installed CLI)
+  - Expand a policy to configure its parameters (for policies that support `policyParams`)
+  - Set a custom policies file path
+  </Tab>
+  <Tab title="Activity tab">
+  - Full paginated history of every hook event that has fired across all sessions
+  - Filter by decision, event type, CLI (Claude Code / OpenAI Codex / GitHub Copilot _(beta)_ / Cursor Agent _(beta)_ / OpenCode _(beta)_ / Pi _(beta)_ / Hermes / OpenClaw / Factory Droid / Devin / Antigravity / Goose), policy name, or session ID
+  - Each row shows: timestamp, policy name, decision, CLI badge (orange = Claude Code, purple = OpenAI Codex, blue = GitHub Copilot, emerald = Cursor Agent, amber = OpenCode, pink = Pi, indigo = Hermes, teal = OpenClaw, rose = Factory Droid, violet = Devin, cyan = Antigravity, lime = Goose), tool name, session ID, and the reason for deny/instruct decisions
+  - Click a session ID to open its transcript — the viewer auto-detects which CLI fired the hook (Claude `~/.claude/projects/…`, Codex `~/.codex/sessions/…`, Copilot CLI `~/.copilot/session-state/<id>/events.jsonl`, Cursor Agent `~/.cursor/agent-sessions/<id>/events.jsonl`, OpenCode `~/.local/share/opencode/opencode.db`, Pi `~/.pi/agent/sessions/<encoded-cwd>/<id>.jsonl`, Hermes `~/.hermes/state.db`, OpenClaw `~/.openclaw/agents/<id>/sessions/*.jsonl`, Factory Droid `~/.factory/sessions/<encoded-cwd>/<id>.jsonl`, Devin `~/.local/share/devin/cli/sessions.db`, Antigravity `~/.gemini/antigravity-cli/brain/<id>/…/transcript_full.jsonl`, Goose `~/.local/share/goose/sessions/sessions.db`) and renders the matching CLI badge in the header
+  </Tab>
+</Tabs>
+
+### Settings
+
+Reached from the **gear** in the header, at `/settings`. A console for the
+background service rather than a preferences page — it opens with a stat row
+reading the daemon's state, when the next scan is due, when the last one ran,
+and how many findings it turned up, over the controls that change them.
+
+- **Scheduled audits** — turn the timer on or off and set the interval. Turning
+  it on requires a signed-in session, because the digest needs a destination;
+  the panel enumerates exactly what a digest sends before you enable it.
+- The countdown reads the daemon's own `next_due_at_ms` rather than deriving one
+  from the interval, so changing the cadence mid-cycle does not leave the page
+  reporting a due time the daemon does not agree with.
+- Every write goes through the same `updateConfig` that
+  [`failproofai audit --schedule`](/cli/audit#scheduled-audits) calls, so the
+  terminal and the dashboard are always in step. Use whichever is in front of
+  you — the CLI is the one that works on a headless box.
+
+---
+
+## 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 policy activity as they appear. Essential for monitoring long-running autonomous agent sessions.
+
+---
+
+## Disabling pages
+
+If you only need some parts of the dashboard, set `FAILPROOFAI_DISABLE_PAGES` to a comma-separated list of page names:
+
+```bash
+FAILPROOFAI_DISABLE_PAGES=policies failproofai
+```
+
+Valid values: `policies`, `projects`, `audit`, `settings`.
+
+Disabling `settings` also removes the gear from the header, so the page is
+neither reachable nor advertised. Worth doing on a dashboard you have exposed
+beyond localhost: that page shows the address digests are mailed to and can
+sign the machine out.
+
+---
+
+## Configuring the projects path
+
+By default, the dashboard reads from the standard Claude Code projects directory. Override it for custom setups:
+
+```bash
+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:
+
+```text
+⚠ Blocked cross-origin request to Next.js dev resource /_next/webpack-hmr from "dashboard.example.com".
+```
+
+This is Next.js blocking cross-origin access to its HMR (hot module reload) websocket, which is a dev-only feature. To allow your host, use the `--allowed-origins` flag:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com
+```
+
+For multiple hosts or IPs, pass a comma-separated list:
+
+```bash
+npm run dev -- --allowed-origins dashboard.example.com,192.168.1.5
+```
+
+You can also set the `FAILPROOFAI_ALLOWED_DEV_ORIGINS` environment variable instead:
+
+```bash
+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>

package/.next/standalone/docs-old/de/agenteye/alerts.mdx

@@ -0,0 +1,63 @@
+---
+title: "Alerts"
+description: "Erfahre sofort, wenn etwas deine Grenze überschreitet – auf dem Kanal, den dein Team bereits nutzt, statt es von einem Kunden zu hören."
+---
+
+
+Erfahre sofort, wenn etwas deine Grenze überschreitet – auf dem Kanal, den dein Team bereits nutzt, statt es von einem Kunden zu hören. Lege eine Regel einmal fest, und Failproof AI Observability prüft sie nach einem Zeitplan und benachrichtigt dich per E-Mail, Slack, Webhook oder direkt im Dashboard.
+
+![Die Alerts-Seite: ein Raster mit Alert-Regelkarten, jede mit ihrem Auslöser, dem Auswertungsfenster, den Kanälen und einem Info-, Warn- oder Kritisch-Schweregrad-Badge](/agenteye/images/alerts.png)
+*Alle Alert-Regeln auf einen Blick: was überwacht wird, wie oft, wohin benachrichtigt wird und wie dringend.*
+
+## Erfahre von Problemen, bevor deine Nutzer es tun
+
+Höre auf, ein Dashboard zu aktualisieren und auf eine Regression zu hoffen. Richte einen Alert ein, wann immer es ein Signal gibt, über das du informiert werden möchtest – auch wenn niemand hinschaut –, und lass ihn dort ankommen, wo du sowieso bist:
+
+- **E-Mail**, an alle, die es wissen sollten.
+- **Slack**, eine aussagekräftige Nachricht mit einer Schaltfläche, die direkt zum Vorfall führt.
+- **Webhook**, ein JSON-POST für PagerDuty, Opsgenie oder deinen eigenen Endpunkt, optional mit Signatur, damit der Empfänger die Echtheit prüfen kann.
+- **Im Dashboard**, von Haus aus dezent – für den Fall, dass du eine Regel feinjustierst und noch niemanden benachrichtigen möchtest.
+
+Kombiniere beliebige dieser Optionen für eine einzige Regel. Der Schweregrad (Info, Warnung oder Kritisch) wird dabei immer mitgeliefert, damit dringende Meldungen auch dringend wirken.
+
+## Regeln per Formular erstellen, nicht per JSON
+
+Du beschreibst, was „kaputt" bedeutet, in einem Formular, und Failproof AI Observability erstellt die zugrundeliegende Regel für dich. Die JSON-Spezifikation ist lediglich das, was dieses Formular intern erzeugt – du kannst sie lesen, um eine Regel zu verstehen, aber tippst sie selten manuell ein.
+
+![Das Formular für neue Alerts: Name und Beschreibung, ein Aktivierungsschalter und eine Auslöserauswahl mit Metrikschwellenwert, benutzerdefiniertem SQL, Auswertungsscore, zusammengesetzter Auswertung und ereignisbezogenen Bedingungen](/agenteye/images/alert-new.png)
+*Wähle einen Auslöser und das Formular zeigt die richtigen Felder an; Speichern schreibt die Regel.*
+
+Der Standardablauf geht schnell: Name vergeben, einen **Auslöser** wählen (was überwacht werden soll), **Schwellenwert und Zeitfenster** festlegen (wie schlimm, über welchen Zeitraum), mindestens einen **Kanal** anhängen, dann **Speichern** und auf **Test** klicken, um eine synthetische Benachrichtigung auszulösen und zu bestätigen, dass jedes Ziel richtig verdrahtet ist. Intern entsteht dabei eine kleine Spezifikation wie:
+
+```json
+{ "metric": "p95_latency_ms", "op": ">", "value": 5000, "window_secs": 900 }
+```
+
+Du bist nicht auf eine einzige Art von Signal beschränkt. Wähle den Auslöser, der dazu passt, wie du über den Fehler nachdenkst:
+
+| Auslöser | Löst aus, wenn |
+|---|---|
+| **Metrikschwellenwert** | eine voreingestellte Metrik (Fehlerrate, p95- oder p99-Latenz, Ereignis- oder Fehlerzähler, Token-Verbrauch) über ein Zeitfenster deine Grenze überschreitet |
+| **Benutzerdefiniertes SQL** | deine eigene schreibgeschützte Abfrage eine Zeile zurückgibt oder ein berechneter Wert einen Schwellenwert überschreitet |
+| **Auswertungsscore** | der Durchschnittswert eines Evaluators (z. B. Halluzinierung) einen Schwellenwert überschreitet |
+| **Zusammengesetzte Auswertung** | mehrere Score-Prüfungen mit Beliebig-, Alle- oder Mindestens-N-Logik kombiniert werden, um eine Regression zu erkennen, die sich erst über mehrere Scores hinweg zeigt |
+| **Pro Ereignis** | ein einzelnes passendes Ereignis eintrifft: ein bestimmter Agent, ein bestimmter Fehlertyp oder ein Nachrichten-Substring |
+
+Schaust du gerade auf der [Errors-Seite](/de/agenteye/error-tracking) auf einen Fehler? Jede Zeile dort hat eine **+ Alert**-Schaltfläche, die dieses Formular vorausgefüllt öffnet, um genau diesen Fehler beim nächsten Auftreten abzufangen – damit der Vorfall, den du gerade triagiert hast, beim nächsten Mal direkt eine Benachrichtigung auslöst.
+
+**Wo du es findest:** Alerts befinden sich unter `/<org-slug>/alerts`. Zum Erstellen, Bearbeiten, Löschen und Testen von Regeln wird **`alerts:write`** benötigt; `alerts:read` reicht zum Anschauen. Die Empfängerauswahl listet die Mitglieder deiner Organisation namentlich auf, sodass du eine Person benachrichtigen kannst, ohne das Formular zu verlassen.
+
+## Benachrichtigungen nur bei echten Problemen
+
+Eine einzelne fehlerhafte Messung sollte dich nicht aufwecken. Der **M von N**-Rauschfilter legt fest, wie viele der letzten Prüfungen fehlschlagen müssen, bevor der Alert tatsächlich ausgelöst wird. Stelle ihn auf **3 von 5** ein, und die Regel löst erst aus, nachdem drei der letzten fünf Prüfungen die Grenze überschritten haben – damit ein unstetes Signal aufhört, falschen Alarm zu schlagen. Belasse ihn beim Standardwert **1 von 1**, um beim ersten Verstoß sofort auszulösen. Du wählst außerdem, wie oft die Regel ausgeführt wird – aus Voreinstellungen von 1m, 5m, 15m und 1h, abgestimmt auf die tatsächliche Dynamik des Signals.
+
+## Was passiert, wenn ein Alert ausgelöst wird
+
+Ein Verstoß öffnet einen **Incident** und benachrichtigt deine Kanäle einmalig. Von dort aus bestätigt dein Team den Vorfall, weist einen Verantwortlichen zu, bespricht ihn und löst ihn auf – alles in einem übersichtlichen, zugeordneten Protokoll. Dieser Triage-Workflow hat seine eigene Seite: siehe [Incidents](/de/agenteye/incidents).
+
+## Verwandte Themen
+
+- [Incidents](/de/agenteye/incidents): verfolge einen ausgelösten Alert von offen über bestätigt bis gelöst.
+- [Error tracking](/de/agenteye/error-tracking): gruppiere Agent-Fehler und wandle einen mit einem Klick in einen Alert um.
+- [Dashboards](/de/agenteye/dashboards): beobachte die gemeinsamen Boards, aus denen die überwachten Schwellenwerte stammen.
+- [CLI and agents](/de/agenteye/cli-and-agents): erstelle Alerts und bestätige Incidents über dein Terminal oder integriere sie per Skript in CI.