failproofai 0.0.2 → 0.0.3

package/.next/standalone/README.md

@@ -13,23 +13,25 @@
 [![npm](https://img.shields.io/npm/v/failproofai?style=flat-square&color=CB3837)](https://www.npmjs.com/package/failproofai)
 [![License](https://img.shields.io/badge/license-MIT%20%2B%20Commons%20Clause-blue?style=flat-square)](LICENSE)
 [![CI](https://img.shields.io/github/actions/workflow/status/exospherehost/failproofai/ci.yml?branch=main&style=flat-square&label=CI)](https://github.com/exospherehost/failproofai/actions)
-[![Discord](https://img.shields.io/discord/1234567890?style=flat-square&label=Discord&color=5865F2)](https://discord.com/invite/zT92CAgvkj)
+[![Slack](https://img.shields.io/badge/Slack-join%20us-4A154B?style=flat-square&logo=slack)](https://join.slack.com/t/failproofai/shared_invite/zt-3v63b7k5e-O3NBHmj8X6n9gZSGDx6ggQ)
 
-Open-source hooks, policies, and project visualization for **Claude Code** & the **Agents SDK**.
+**Translations**: [简体中文](docs/i18n/README.zh.md) | [日本語](docs/i18n/README.ja.md) | [한국어](docs/i18n/README.ko.md) | [Español](docs/i18n/README.es.md) | [Português](docs/i18n/README.pt-br.md) | [Deutsch](docs/i18n/README.de.md) | [Français](docs/i18n/README.fr.md) | [Русский](docs/i18n/README.ru.md) | [हिन्दी](docs/i18n/README.hi.md) | [Türkçe](docs/i18n/README.tr.md) | [Tiếng Việt](docs/i18n/README.vi.md) | [Italiano](docs/i18n/README.it.md) | [العربية](docs/i18n/README.ar.md) | [עברית](docs/i18n/README.he.md)
 
-- **Hooks & Policies** — 35+ built-in security policies that run as Claude Code hooks. Block dangerous commands, sanitize secrets, restrict file access, and more.
-- **Custom Policies** — Write your own policies in JavaScript. Same `allow`/`deny`/`instruct` API as built-in policies, with full async support.
-- **Policy Parameters** — Tune built-in policies without writing code: configure allowlists, protected branches, thresholds, and custom patterns.
-- **Session Viewer** — Browse Claude Code projects and sessions locally. Inspect tool calls, messages, and per-session hook activity side-by-side.
+The easiest way to manage policies that keep your AI agents reliable, on-task, and running autonomously - for **Claude Code** & the **Agents SDK**.
 
-Everything runs locally — no data leaves your machine.
+- **30 Built-in Policies** - Catch common agent failure modes out of the box. Block destructive commands, prevent secret leakage, keep agents inside project boundaries, detect loops, and more.
+- **Custom Policies** - Write your own reliability rules in JavaScript. Use the `allow`/`deny`/`instruct` API to enforce conventions, prevent drift, gate operations, or integrate with external systems.
+- **Easy Configuration** - Tune any policy without writing code. Set allowlists, protected branches, thresholds per-project or globally. Three-scope config merges automatically.
+- **Agent Monitor** - See what your agents did while you were away. Browse sessions, inspect every tool call, and review exactly where policies fired.
+
+Everything runs locally - no data leaves your machine.
 
 ---
 
 ## Requirements
 
 - Node.js >= 20.9.0
-- Bun >= 1.3.0 (optional — only needed for development / building from source)
+- Bun >= 1.3.0 (optional - only needed for development / building from source)
 
 ---
 
@@ -59,7 +61,7 @@ Writes hook entries into `~/.claude/settings.json`. Claude Code will now invoke
 failproofai
 ```
 
-Opens `http://localhost:8020` — browse sessions, inspect logs, manage policies.
+Opens `http://localhost:8020` - browse sessions, inspect logs, manage policies.
 
 ### 3. Check what's active
 
@@ -111,10 +113,12 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
   ],
   "policyParams": {
     "block-sudo": {
-      "allowPatterns": ["sudo systemctl status", "sudo journalctl"]
+      "allowPatterns": ["sudo systemctl status", "sudo journalctl"],
+      "hint": "Use apt-get directly without sudo."
     },
     "block-push-master": {
-      "protectedBranches": ["main", "release", "prod"]
+      "protectedBranches": ["main", "release", "prod"],
+      "hint": "Try creating a fresh branch instead."
     },
     "sanitize-api-keys": {
       "additionalPatterns": [
@@ -128,7 +132,7 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
 }
 ```
 
-**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.md](docs/configuration.md) for full merge rules.
+**Three config scopes** are merged automatically (project → local → global). See [docs/configuration.mdx](docs/configuration.mdx) for full merge rules.
 
 ---
 
@@ -136,40 +140,40 @@ Policy configuration lives in `~/.failproofai/policies-config.json` (global) or
 
 | Policy | Description | Configurable |
 |--------|-------------|:---:|
-| `block-sudo` | Block sudo commands | `allowPatterns` |
-| `block-rm-rf` | Block recursive deletions | `allowPaths` |
-| `block-curl-pipe-sh` | Block curl\|bash and wget\|bash | |
+| `block-sudo` | Prevent agents from running privileged system commands | `allowPatterns` |
+| `block-rm-rf` | Prevent accidental recursive file deletion | `allowPaths` |
+| `block-curl-pipe-sh` | Prevent agents from piping untrusted scripts to shell | |
 | `block-failproofai-commands` | Prevent self-uninstallation | |
-| `sanitize-jwt` | Redact JWT tokens from tool output | |
-| `sanitize-api-keys` | Redact API keys from tool output | `additionalPatterns` |
-| `sanitize-connection-strings` | Redact database credentials from tool output | |
-| `sanitize-private-key-content` | Redact PEM private key blocks | |
-| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens | |
-| `block-env-files` | Block access to .env files | |
-| `protect-env-vars` | Block commands that print environment variables | |
-| `block-read-outside-cwd` | Block reading files outside the project | `allowPaths` |
-| `block-secrets-write` | Block writes to private key and certificate files | `additionalPatterns` |
-| `block-push-master` | Block pushing to main/master | `protectedBranches` |
-| `block-work-on-main` | Block checking out main/master | `protectedBranches` |
-| `block-force-push` | Block `git push --force` | |
-| `warn-git-amend` | Warn on `git commit --amend` | |
-| `warn-git-stash-drop` | Warn on `git stash drop` | |
-| `warn-all-files-staged` | Warn on `git add -A` | |
-| `warn-destructive-sql` | Warn on DROP/DELETE SQL statements | |
-| `warn-schema-alteration` | Warn on ALTER TABLE statements | |
-| `warn-large-file-write` | Warn on large file writes | `thresholdKb` |
-| `warn-package-publish` | Warn on `npm publish` | |
-| `warn-background-process` | Warn on background process launches | |
-| `warn-global-package-install` | Warn on global package installs | |
+| `sanitize-jwt` | Stop JWT tokens from leaking into agent context | |
+| `sanitize-api-keys` | Stop API keys from leaking into agent context | `additionalPatterns` |
+| `sanitize-connection-strings` | Stop database credentials from leaking into agent context | |
+| `sanitize-private-key-content` | Redact PEM private key blocks from output | |
+| `sanitize-bearer-tokens` | Redact Authorization Bearer tokens from output | |
+| `block-env-files` | Keep agents from reading .env files | |
+| `protect-env-vars` | Prevent agents from printing environment variables | |
+| `block-read-outside-cwd` | Keep agents inside project boundaries | `allowPaths` |
+| `block-secrets-write` | Prevent writes to private key and certificate files | `additionalPatterns` |
+| `block-push-master` | Prevent accidental pushes to main/master | `protectedBranches` |
+| `block-work-on-main` | Keep agents off protected branches | `protectedBranches` |
+| `block-force-push` | Prevent `git push --force` | |
+| `warn-git-amend` | Remind agents before amending commits | |
+| `warn-git-stash-drop` | Remind agents before dropping stashes | |
+| `warn-all-files-staged` | Catch accidental `git add -A` | |
+| `warn-destructive-sql` | Catch DROP/DELETE SQL before execution | |
+| `warn-schema-alteration` | Catch ALTER TABLE before execution | |
+| `warn-large-file-write` | Catch unexpectedly large file writes | `thresholdKb` |
+| `warn-package-publish` | Catch accidental `npm publish` | |
+| `warn-background-process` | Catch unintended background process launches | |
+| `warn-global-package-install` | Catch unintended global package installs | |
 | …and more | | |
 
-Full policy details and parameter reference: [docs/built-in-policies.md](docs/built-in-policies.md)
+Full policy details and parameter reference: [docs/built-in-policies.mdx](docs/built-in-policies.mdx)
 
 ---
 
 ## Custom policies
 
-Create a `.js` file with your own policies:
+Write your own policies to keep agents reliable and on-task:
 
 ```js
 import { customPolicies, allow, deny, instruct } from "failproofai";
@@ -197,8 +201,9 @@ failproofai policies --install --custom ./my-policies.js
 
 | Function | Effect |
 |----------|--------|
-| `allow()` | Permit the tool call |
-| `deny(message)` | Block the tool call; message shown to Claude |
+| `allow()` | Permit the operation |
+| `allow(message)` | Permit and send informational context to Claude *(beta)* |
+| `deny(message)` | Block the operation; message shown to Claude |
 | `instruct(message)` | Add context to Claude's prompt; does not block |
 
 ### Context object (`ctx`)
@@ -213,7 +218,22 @@ failproofai policies --install --custom ./my-policies.js
 | `session.sessionId` | `string` | Session identifier |
 | `session.transcriptPath` | `string` | Path to the session transcript file |
 
-Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors in custom hooks are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.md](docs/custom-hooks.md) for the full guide.
+Custom hooks support transitive local imports, async/await, and access to `process.env`. Errors are fail-open (logged to `~/.failproofai/hook.log`, built-in policies continue). See [docs/custom-hooks.mdx](docs/custom-hooks.mdx) for the full guide.
+
+### Convention-based policies (v0.0.2-beta.7+)
+
+Drop `*policies.{js,mjs,ts}` files into `.failproofai/policies/` and they're automatically loaded — no `--custom` flag or config changes needed. Works like git hooks: drop a file, it just works.
+
+```text
+# 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
+```
+
+Both levels load (union). Files are loaded alphabetically within each directory. Prefix with `01-`, `02-`, etc. to control order. See [examples/convention-policies/](examples/convention-policies/) for ready-to-use examples.
 
 ---
 
@@ -233,17 +253,39 @@ FAILPROOFAI_TELEMETRY_DISABLED=1 failproofai
 
 | Guide | Description |
 |-------|-------------|
-| [Getting Started](docs/getting-started.md) | Installation and first steps |
-| [CLI Reference](docs/cli-reference.md) | All commands and flags |
-| [Configuration](docs/configuration.md) | Config file format and scope merging |
-| [Built-in Policies](docs/built-in-policies.md) | All 35+ policies with parameters |
-| [Custom Hooks](docs/custom-hooks.md) | Write your own policies |
-| [Dashboard](docs/dashboard.md) | Session viewer and policy management |
-| [Architecture](docs/architecture.md) | How the hook system works |
-| [Testing](docs/testing.md) | Running tests and writing new ones |
+| [Getting Started](docs/getting-started.mdx) | Installation and first steps |
+| [Built-in Policies](docs/built-in-policies.mdx) | All 30 built-in policies with parameters |
+| [Custom Policies](docs/custom-policies.mdx) | Write your own policies |
+| [Configuration](docs/configuration.mdx) | Config file format and scope merging |
+| [Dashboard](docs/dashboard.mdx) | Monitor sessions and review policy activity |
+| [Architecture](docs/architecture.mdx) | How the hook system works |
+| [Testing](docs/testing.mdx) | Running tests and writing new ones |
+
+### Run docs locally
+
+```bash
+docker build -f Dockerfile.docs -t failproofai-docs .
+docker run --rm -p 3000:3000 failproofai-docs
+```
+
+Opens the Mintlify docs site at `http://localhost:3000`. The container watches for changes if you mount the docs directory:
+
+```bash
+docker run --rm -p 3000:3000 -v $(pwd)/docs:/app/docs failproofai-docs
+```
 
 ---
 
+## Note for failproofai contributors
+
+This repo's `.claude/settings.json` uses `bun ./bin/failproofai.mjs --hook <EventType>` instead of the standard `npx -y failproofai` command. This is because running `npx -y failproofai` inside the failproofai project itself creates a self-referencing conflict.
+
+For all other repos, the recommended approach is `npx -y failproofai`, installed via:
+
+```bash
+failproofai policies --install --scope project
+```
+
 ## Contributing
 
 See [CONTRIBUTING.md](CONTRIBUTING.md).
@@ -253,3 +295,7 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 See [LICENSE](LICENSE).
+
+---
+
+Built and Maintained by **ExosphereHost: Reliability Research Lab for Your Agents**. We help enterprises and startups improve the reliability of their AI agents through our own agents, software, and expertise. Learn more at [exosphere.host](https://exosphere.host).

package/.next/standalone/app/components/session-hooks-panel.tsx

@@ -161,6 +161,12 @@ function SessionHooksDetailPanel({
               </span>
             </div>
           </div>
+          {item.policyNames && item.policyNames.length > 1 && (
+            <div>
+              <span className="text-muted-foreground">Policies: </span>
+              <span className="font-mono text-foreground">{item.policyNames.join(", ")}</span>
+            </div>
+          )}
           {item.reason && (
             <div>
               <span className="text-muted-foreground">Full reason: </span>
@@ -346,7 +352,14 @@ export default function SessionHooksPanel({ sessionId, initialData }: SessionHoo
                         {item.toolName ?? "\u2014"}
                       </td>
                       <td className="px-3 py-2 font-mono text-foreground">
-                        {item.policyName ?? "\u2014"}
+                        {item.policyNames && item.policyNames.length > 1 ? (
+                          <span title={item.policyNames.join(", ")}>
+                            {item.policyNames[0]}
+                            <span className="text-muted-foreground text-[0.6rem]"> +{item.policyNames.length - 1}</span>
+                          </span>
+                        ) : (
+                          item.policyName ?? "\u2014"
+                        )}
                       </td>
                       <td
                         className="px-3 py-2 text-muted-foreground truncate max-w-[240px]"

package/.next/standalone/app/policies/hooks-client.tsx

@@ -270,6 +270,12 @@ function DetailPanel({
               </span>
             </div>
           </div>
+          {item.policyNames && item.policyNames.length > 1 && (
+            <div>
+              <span className="text-muted-foreground">Policies: </span>
+              <span className="font-mono text-foreground">{item.policyNames.join(", ")}</span>
+            </div>
+          )}
           {item.reason && (
             <div>
               <span className="text-muted-foreground">Full reason: </span>
@@ -500,7 +506,14 @@ function ActivityTab({
                           {item.toolName ?? "\u2014"}
                         </td>
                         <td className="px-3 py-2 font-mono text-foreground">
-                          {item.policyName ?? "\u2014"}
+                          {item.policyNames && item.policyNames.length > 1 ? (
+                            <span title={item.policyNames.join(", ")}>
+                              {item.policyNames[0]}
+                              <span className="text-muted-foreground text-[0.6rem]"> +{item.policyNames.length - 1}</span>
+                            </span>
+                          ) : (
+                            item.policyName ?? "\u2014"
+                          )}
                         </td>
                         <td
                           className="px-3 py-2 text-muted-foreground truncate max-w-[240px]"

package/.next/standalone/bin/failproofai.mjs

@@ -97,6 +97,11 @@ COMMANDS
   --version, -v                  Print version and exit
   --help, -h                     Show this help message
 
+CONVENTION POLICIES
+  Drop *policies.{js,mjs,ts} files into .failproofai/policies/ for auto-loading.
+  Works at project level (.failproofai/policies/) and user level (~/.failproofai/policies/).
+  No --custom flag or config changes needed — just drop files and they're picked up.
+
 EXAMPLES
   failproofai policies
   failproofai policies --install