failproofai 0.0.2 → 0.0.3

package/.next/standalone/docs/{built-in-policies.md → built-in-policies.mdx}

@@ -1,10 +1,10 @@
 ---
 title: Built-in Policies
-description: "All 35+ security policies with descriptions and parameters"
+description: "All 30 built-in policies that catch common agent failure modes"
 icon: shield
 ---
 
-failproofai ships with 35+ built-in security policies. Each policy fires on a specific hook event type and tool name. Eight policies accept parameters that let you tune their behavior without writing code.
+failproofai ships with 30 built-in policies that catch common agent failure modes. Each policy fires on a specific hook event type and tool name. Nine policies accept parameters that let you tune their behavior without writing code. Four beta workflow policies enforce a commit → push → PR → CI pipeline before Claude stops.
 
 ---
 
@@ -21,13 +21,25 @@ Policies are grouped into categories:
 | [Git](#git) | block-push-master, block-work-on-main, block-force-push, warn-git-amend, warn-git-stash-drop, warn-all-files-staged | PreToolUse |
 | [Database](#database) | warn-destructive-sql, warn-schema-alteration | PreToolUse |
 | [Warnings](#warnings) | warn-large-file-write, warn-package-publish, warn-background-process, warn-global-package-install | PreToolUse |
+| [Workflow (beta)](#workflow-beta) | require-commit-before-stop, require-push-before-stop, require-pr-before-stop, require-ci-green-before-stop | Stop |
 
-Policies that start with `block-` return a **deny** decision (Claude cannot proceed). Policies that start with `warn-` return an **instruct** decision (Claude gets extra context but can proceed). Policies that start with `sanitize-` also return deny but fire after tool execution to redact secrets from output before Claude sees it.
+- **`block-`** — stop the agent from proceeding.
+- **`warn-`** — give the agent additional context so it can self-correct.
+- **`sanitize-`** — scrub sensitive data from tool output before the agent sees it.
+- **`require-`** — block the Stop event until conditions are met.
+
+---
+
+<Tip>
+Every policy supports an optional `hint` field in `policyParams`. The hint is appended to the deny or instruct message Claude sees, giving actionable guidance without modifying policy code. Works with built-in, custom, and convention policies. See [Configuration → hint](/configuration#hint-cross-cutting) for details.
+</Tip>
 
 ---
 
 ## Dangerous commands
 
+Prevent agents from running operations that are hard to undo or that could damage the host system.
+
 ### `block-sudo`
 
 **Event:** PreToolUse (Bash)  
@@ -55,7 +67,9 @@ Blocks invocations that include the `sudo` keyword. Pattern matching is done on
 
 With this config, `sudo systemctl status nginx` is allowed, but `sudo rm /etc/hosts` is denied.
 
-> **Security note:** Patterns are matched against parsed tokens, not the raw command string. This prevents bypass via appended shell operators (e.g. `sudo systemctl status x; rm -rf /` does not match `sudo systemctl status *`).
+<Note>
+Patterns are matched against parsed tokens, not the raw command string. This prevents bypass via appended shell operators (e.g. `sudo systemctl status x; rm -rf /` does not match `sudo systemctl status *`).
+</Note>
 
 ---
 
@@ -96,7 +110,7 @@ No parameters.
 ### `block-failproofai-commands`
 
 **Event:** PreToolUse (Bash)  
-**Default:** Denies commands that would uninstall or disable failproofai itself (e.g. `npm uninstall failproofai`, `failproofai --remove-policies`).
+**Default:** Denies commands that would uninstall or disable failproofai itself (e.g. `npm uninstall failproofai`, `failproofai policies --uninstall`).
 
 No parameters.
 
@@ -104,7 +118,7 @@ No parameters.
 
 ## Secrets (sanitizers)
 
-Sanitizer policies fire on **PostToolUse** events. When Claude runs a Bash command, reads a file, or calls any tool, these policies inspect the output before it is returned to Claude. If a secret pattern is detected, the policy returns a deny decision that prevents the output from being passed back.
+Stop agents from leaking credentials into their context or output. Sanitizer policies fire on **PostToolUse** events. When Claude runs a Bash command, reads a file, or calls any tool, these policies inspect the output before it is returned to Claude. If a secret pattern is detected, the policy returns a deny decision that prevents the output from being passed back.
 
 ### `sanitize-jwt`
 
@@ -172,12 +186,14 @@ No parameters.
 
 ## Environment
 
+Protect sensitive environment configuration from being read or exposed by agents.
+
 ### `block-env-files`
 
 **Event:** PreToolUse (Bash, Read)  
 **Default:** Denies reading `.env` files via `cat .env`, `Read` tool calls with `.env` as the file path, etc.
 
-Does not block `.envrc` or other environment-adjacent files — only files named exactly `.env`.
+Does not block `.envrc` or other environment-adjacent files - only files named exactly `.env`.
 
 No parameters.
 
@@ -194,6 +210,8 @@ No parameters.
 
 ## File access
 
+Keep agents working inside project boundaries and away from sensitive files.
+
 ### `block-read-outside-cwd`
 
 **Event:** PreToolUse (Read, Bash)  
@@ -246,6 +264,8 @@ No parameters.
 
 ## Git
 
+Prevent accidental pushes, force-pushes, and branch mistakes that are hard to undo.
+
 ### `block-push-master`
 
 **Event:** PreToolUse (Bash)  
@@ -269,7 +289,9 @@ No parameters.
 }
 ```
 
-> To allow pushing to all branches (effectively disabling this policy without removing it from `enabledPolicies`), set `protectedBranches: []`.
+<Tip>
+To allow pushing to all branches (effectively disabling this policy without removing it from `enabledPolicies`), set `protectedBranches: []`.
+</Tip>
 
 ---
 
@@ -291,7 +313,17 @@ No parameters.
 **Event:** PreToolUse (Bash)  
 **Default:** Denies `git push --force` and `git push -f`.
 
-No parameters.
+No policy-specific parameters. Use the cross-cutting [`hint`](/configuration#hint-cross-cutting) to suggest alternatives:
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Create a new branch from your current HEAD (e.g. `git checkout -b <new-branch>`) and push that instead."
+    }
+  }
+}
+```
 
 ---
 
@@ -324,6 +356,8 @@ No parameters.
 
 ## Database
 
+Catch destructive SQL operations before they execute against your database.
+
 ### `warn-destructive-sql`
 
 **Event:** PreToolUse (Bash)  
@@ -344,6 +378,8 @@ No parameters.
 
 ## Warnings
 
+Give agents extra context before potentially risky but non-destructive operations.
+
 ### `warn-large-file-write`
 
 **Event:** PreToolUse (Write)  
@@ -367,7 +403,9 @@ No parameters.
 }
 ```
 
-> **Note:** The hook handler enforces a 1 MB stdin limit on payloads. To test this policy with small content, set `thresholdKb` to a value well below 1024.
+<Note>
+The hook handler enforces a 1 MB stdin limit on payloads. To test this policy with small content, set `thresholdKb` to a value well below 1024.
+</Note>
 
 ---
 
@@ -398,15 +436,115 @@ No parameters.
 
 ---
 
+## AI behavior
+
+Detect when agents get stuck or behave unexpectedly.
+
+### `warn-repeated-tool-calls`
+
+**Event:** PreToolUse (all tools)  
+**Default:** Instructs Claude to reconsider when the same tool is called 3+ times with identical parameters - a common sign the agent is stuck in a loop.
+
+No parameters.
+
+---
+
+## Workflow (beta)
+
+Enforce a disciplined end-of-session workflow. These policies fire on the **Stop** event and deny Claude from stopping until each condition is met. They follow a natural dependency chain: commit → push → PR → CI. If a policy denies, later policies in the chain are skipped (deny short-circuits).
+
+All workflow policies are **fail-open**: if the required tool is not available (e.g. `gh` not installed, no git remote), the policy allows with an informational message explaining why the check was skipped.
+
+### `require-commit-before-stop`
+
+**Event:** Stop  
+**Default:** Denies stopping when there are uncommitted changes (modified, staged, or untracked files). Returns an informational message when the working directory is clean.
+
+No parameters.
+
+---
+
+### `require-push-before-stop`
+
+**Event:** Stop  
+**Default:** Denies stopping when there are unpushed commits or when the current branch has no remote tracking branch. Suggests `git push -u` to create a tracking branch if needed. Fails open if no remote is configured.
+
+**Parameters:**
+
+| Param | Type | Default | Description |
+|-------|------|---------|-------------|
+| `remote` | `string` | `"origin"` | Remote name to push to. |
+
+**Example:**
+
+```json
+{
+  "policyParams": {
+    "require-push-before-stop": {
+      "remote": "upstream"
+    }
+  }
+}
+```
+
+---
+
+### `require-pr-before-stop`
+
+**Event:** Stop  
+**Default:** Denies stopping when no pull request exists for the current branch, or when the existing PR is closed/merged. Instructs Claude to create a PR with `gh pr create`.
+
+No parameters.
+
+<Note>
+This policy requires [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
+Run `gh auth login` with a personal access token that has `repo` scope for read access to
+pull requests. If `gh` is not installed or not authenticated, the policy fails open and reports the reason to Claude.
+</Note>
+
+---
+
+### `require-ci-green-before-stop`
+
+**Event:** Stop  
+**Default:** Denies stopping when CI checks are failing or still running on the current branch. Checks both GitHub Actions workflow runs and third-party bot checks (e.g. CodeRabbit, SonarCloud, Codecov). Treats `skipped` conclusions as success. Returns an informational message when all checks pass.
+
+No parameters.
+
+<Note>
+This policy requires [GitHub CLI](https://cli.github.com/) (`gh`) to be installed and authenticated.
+Run `gh auth login` with a personal access token that has `repo` scope for read access to
+Actions workflow runs and the Checks API. If `gh` is not installed or not authenticated, the policy fails open and reports the reason to Claude.
+</Note>
+
+---
+
 ## Beta policies
 
-Some policies are marked `beta` and are not installed by default. To include them:
+Some policies are marked `beta` and are not installed by default. Beta policies may have rough edges or generate false positives. They graduate to stable in future releases.
+
+**Current beta policies:**
+
+- `require-commit-before-stop` — commit all changes before stopping
+- `require-push-before-stop` — push all commits to remote
+- `require-pr-before-stop` — ensure a PR exists for the branch
+- `require-ci-green-before-stop` — all CI checks must pass
+
+Together, these enforce a **commit → push → PR → CI** workflow.
+
+To install all beta policies:
+
+```bash
+failproofai policies --install --beta
+```
+
+Or install specific workflow policies:
 
 ```bash
-failproofai --install-policies --beta
+failproofai policies --install require-commit-before-stop require-push-before-stop require-pr-before-stop require-ci-green-before-stop
 ```
 
-Beta policies may have rough edges or generate false positives. Use `failproofai --list-policies` to see which policies carry the beta flag.
+Run `failproofai policies` to see which policies carry the beta flag.
 
 ---
 

package/.next/standalone/docs/cli/dashboard.mdx

@@ -0,0 +1,28 @@
+---
+title: View sessions
+description: "Launch the dashboard to browse agent sessions and manage policies"
+---
+
+```bash
+failproofai
+```
+
+Starts the web dashboard at `http://localhost:8020`.
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--port <number>` | Port to listen on (default: `8020`) |
+| `--projects-path <path>` | Override where Claude Code project folders are found |
+| `--allowed-origins <origins>` | Comma-separated hosts/IPs allowed to access dev resources |
+
+## Examples
+
+```bash
+# Launch on a different port
+failproofai --port 9000
+
+# Use a custom projects path
+failproofai --projects-path ~/my-claude-projects
+```

package/.next/standalone/docs/cli/environment-variables.mdx

@@ -0,0 +1,34 @@
+---
+title: Environment variables
+description: "Configure failproofai behavior with environment variables"
+---
+
+## Dashboard
+
+| Variable | Description |
+|----------|-------------|
+| `PORT` | Dashboard port (default: `8020`) |
+| `CLAUDE_PROJECTS_PATH` | Override where Claude Code project folders are found |
+| `FAILPROOFAI_DISABLE_PAGES=policies,projects` | Comma-separated dashboard pages to hide |
+| `FAILPROOFAI_ALLOWED_DEV_ORIGINS` | Hosts/IPs allowed to access dev resources. Same as `--allowed-origins`. |
+
+## Logging
+
+| Variable | Description |
+|----------|-------------|
+| `FAILPROOFAI_LOG_LEVEL=info\|warn\|error` | Server log level (default: `warn`) |
+| `FAILPROOFAI_HOOK_LOG_FILE` | Custom hook log file path, or `true` for default (`~/.failproofai/logs/hooks.log`) |
+
+## Telemetry
+
+| Variable | Description |
+|----------|-------------|
+| `FAILPROOFAI_TELEMETRY_DISABLED=1` | Disable anonymous usage telemetry |
+
+## LLM (for policy evaluation)
+
+| Variable | Description |
+|----------|-------------|
+| `FAILPROOFAI_LLM_BASE_URL` | LLM API endpoint (default: `https://api.openai.com/v1`) |
+| `FAILPROOFAI_LLM_API_KEY` | API key for LLM-powered policies |
+| `FAILPROOFAI_LLM_MODEL` | Model name (default: `gpt-4o-mini`) |

package/.next/standalone/docs/cli/hook.mdx

@@ -0,0 +1,30 @@
+---
+title: Hook handler (internal)
+description: "The subprocess Claude Code calls on each tool event"
+---
+
+```bash
+failproofai --hook <EventType>
+```
+
+This is the command registered in Claude Code's `settings.json` by `failproofai policies --install`. You don't normally call this directly.
+
+Reads a JSON payload from stdin, evaluates all enabled policies, and exits with a code indicating the decision:
+
+| Exit code | Decision | Effect |
+|-----------|----------|--------|
+| `0` | `allow` | Permit the action |
+| `1` | `deny` | Block the action - Claude sees the denial reason |
+| `2` | `instruct` | Inject guidance into Claude's context |
+
+### Supported event types
+
+| Category | Events |
+|----------|--------|
+| **Tool execution** | `PreToolUse`, `PostToolUse`, `PostToolUseFailure`, `PermissionRequest`, `PermissionDenied` |
+| **Session lifecycle** | `SessionStart`, `SessionEnd`, `Stop`, `StopFailure` |
+| **User interaction** | `UserPromptSubmit`, `Notification`, `Elicitation`, `ElicitationResult` |
+| **Subagents & tasks** | `SubagentStart`, `SubagentStop`, `TaskCreated`, `TaskCompleted`, `TeammateIdle` |
+| **Configuration** | `InstructionsLoaded`, `ConfigChange`, `CwdChanged` |
+| **File system** | `FileChanged`, `WorktreeCreate`, `WorktreeRemove` |
+| **Context** | `PreCompact`, `PostCompact` |

package/.next/standalone/docs/cli/install-policies.mdx

@@ -0,0 +1,48 @@
+---
+title: Install policies
+description: "Enable policies so they run on every agent tool call"
+---
+
+```bash
+failproofai policies --install [policy-names...] [options]
+```
+
+Writes hook entries into Claude Code's `settings.json` so failproofai intercepts tool calls.
+
+Aliases: `failproofai p -i`
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--scope user` | Install into `~/.claude/settings.json` (default - all sessions) |
+| `--scope project` | Install into `.claude/settings.json` in the current directory |
+| `--scope local` | Install into `.claude/settings.local.json` in the current directory |
+| `--custom <path>` / `-c` | Path to a JS file containing custom hook policies |
+| `--beta` | Include beta policies |
+
+## Behavior
+
+- **No policy names** - opens an interactive prompt to select policies
+- **Specific names** - enables those policies (added to any already enabled)
+- **`all`** - enables every available policy
+
+Installation is additive: running `--install` again adds new policies without removing existing ones.
+
+## Examples
+
+```bash
+# Install all default policies globally (interactive)
+failproofai policies --install
+
+# Install specific policies for the current project
+failproofai policies --install block-sudo sanitize-api-keys --scope project
+
+# Enable all policies at once
+failproofai policies --install all
+
+# Install with a custom policies file
+failproofai policies --install --custom ./my-policies.js
+```
+
+When `--custom <path>` is provided, the file is validated immediately - it must call `customPolicies.add()` at least once. The resolved path is saved to `policies-config.json` as `customPoliciesPath`.

package/.next/standalone/docs/cli/list-policies.mdx

@@ -0,0 +1,31 @@
+---
+title: List policies
+description: "See which policies are enabled, their parameters, and custom policies"
+---
+
+```bash
+failproofai policies
+```
+
+Shows all policies with their status, configured parameters, and custom policies.
+
+## Sample output
+
+```text
+Failproof AI Hook Policies (user)
+
+  Status  Name                          Description
+  ──────  ──────────────────────────────────────────────────────────────
+  ✓       block-sudo                    Block sudo commands
+            allowPatterns: ["sudo systemctl status"]
+  ✓       block-rm-rf                   Block recursive deletions
+  ✗       block-curl-pipe-sh            Block curl|bash patterns
+  ✓       sanitize-api-keys             Redact API keys from output
+            additionalPatterns: [{ regex: "MY_TOKEN_...", label: "..." }]
+
+  ── Custom Policies (/home/alice/myproject/my-policies.js) ──────────────
+  ✓       require-jira-ticket           Block commits without ticket
+  ✓       approval-gate                 Approval gate for destructive ops
+```
+
+Unknown keys in `policyParams` are flagged here so you can catch typos early.

package/.next/standalone/docs/cli/remove-policies.mdx

@@ -0,0 +1,44 @@
+---
+title: Uninstall policies
+description: "Remove hook entries from Claude Code's settings"
+---
+
+```bash
+failproofai policies --uninstall [policy-names...] [options]
+```
+
+Removes failproofai hook entries from Claude Code's `settings.json`.
+
+Aliases: `failproofai p -u`
+
+## Options
+
+| Flag | Description |
+|------|-------------|
+| `--scope user` | Remove from global settings (default) |
+| `--scope project` | Remove from project settings |
+| `--scope local` | Remove from local settings |
+| `--scope all` | Remove from all scopes at once |
+| `--custom` / `-c` | Clear the `customPoliciesPath` from config |
+| `--beta` | Remove only beta policies from config |
+
+## Behavior
+
+- **No policy names** - removes all failproofai hook entries from the settings file
+- **Specific names** - disables those policies but keeps hooks installed
+
+## Examples
+
+```bash
+# Remove all hooks globally
+failproofai policies --uninstall
+
+# Disable a specific policy (keeps hooks installed)
+failproofai policies --uninstall block-sudo
+
+# Remove hooks from every scope
+failproofai policies --uninstall --scope all
+
+# Clear custom policies path
+failproofai policies --uninstall --custom
+```

package/.next/standalone/docs/cli/version.mdx

@@ -0,0 +1,12 @@
+---
+title: Check version
+description: "Print the installed failproofai version"
+---
+
+```bash
+failproofai --version
+# or
+failproofai -v
+```
+
+Prints the installed version number.

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,65 @@ 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`.
+
+#### `hint` (cross-cutting)
+
+Type: `string` (optional)
+
+A message appended to the reason when a policy returns `deny` or `instruct`. Use it to give Claude actionable guidance without modifying the policy itself.
+
+Works with any policy type — built-in, custom (`custom/`), project convention (`.failproofai-project/`), or user convention (`.failproofai-user/`).
+
+```json
+{
+  "policyParams": {
+    "block-force-push": {
+      "hint": "Try creating a fresh branch instead."
+    },
+    "block-sudo": {
+      "allowPatterns": ["sudo apt-get"],
+      "hint": "Use apt-get directly without sudo."
+    },
+    "custom/my-policy": {
+      "hint": "Ask the user for approval first."
+    }
+  }
+}
+```
+
+When `block-force-push` denies, Claude sees: *"Force-pushing is blocked. Try creating a fresh branch instead."*
+
+Non-string values and empty strings are silently ignored. If `hint` is not set, behavior is unchanged (backward-compatible).
 
 ### `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 Policies](/custom-policies) for authoring details.
+
+### Convention-based policies (v0.0.2-beta.7+)
+
+In addition to the explicit `customPoliciesPath`, failproofai automatically discovers and loads policy files from `.failproofai/policies/` directories:
+
+| Level | Directory | Scope |
+|-------|-----------|-------|
+| Project | `.failproofai/policies/` | Shared with team via version control |
+| User | `~/.failproofai/policies/` | Personal, applies to all projects |
+
+**File matching:** Only files matching `*policies.{js,mjs,ts}` are loaded (e.g. `security-policies.mjs`, `workflow-policies.js`). Other files in the directory are ignored.
+
+**No config needed:** Convention policies require no entries in `policies-config.json`. Just drop files into the directory and they're picked up on the next hook event.
+
+**Union loading:** Both project and user convention directories are scanned. All matching files from both levels are loaded (unlike `customPoliciesPath` which uses first-scope-wins).
 
-The file is loaded fresh on every hook event — there is no caching. See [Custom Hooks](./custom-hooks.md) for authoring details.
+See [Custom Policies](/custom-policies) for more details and examples.
 
 ### `llm`
 
@@ -143,10 +189,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.