cc-safety-net 1.0.6 → 2.0.0

package/README.md

@@ -1,954 +1,254 @@
-# CC Safety Net
+<h1>
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="./.github/assets/cc-safety-net-header-logo-dark.svg">
+    <source media="(prefers-color-scheme: light)" srcset="./.github/assets/cc-safety-net-header-logo-light.svg">
+    <img alt="CC Safety Net" src="./.github/assets/cc-safety-net-header-logo-light.svg">
+  </picture>
+</h1>
 
 [![CI](https://github.com/kenryu42/cc-safety-net/actions/workflows/ci.yml/badge.svg)](https://github.com/kenryu42/cc-safety-net/actions/workflows/ci.yml)
 [![codecov](https://codecov.io/github/kenryu42/cc-safety-net/branch/main/graph/badge.svg?token=C9QTION6ZF)](https://codecov.io/github/kenryu42/cc-safety-net)
 [![Version](https://img.shields.io/github/v/tag/kenryu42/cc-safety-net?label=version&color=blue)](https://github.com/kenryu42/cc-safety-net)
-[![Codex](https://img.shields.io/badge/Codex-white)](#codex-installation)
-[![Claude Code](https://img.shields.io/badge/Claude%20Code-D27656)](#claude-code-installation)
-[![Copilot CLI](https://img.shields.io/badge/Copilot%20CLI-4EA5C9)](#github-copilot-cli-installation)
-[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-678AE3)](#gemini-cli-installation)
-[![Kimi Code](https://img.shields.io/badge/Kimi%20Code-5587FF)](#kimi-code-installation)
-[![OpenCode](https://img.shields.io/badge/OpenCode-black)](#opencode-installation)
-[![Pi](https://img.shields.io/badge/Pi%20Coding-22262E)](#pi-installation)
+[![Amp Code](https://img.shields.io/badge/Amp%20Code-467C51)](https://ccsafetynet.com/docs/installation#amp-code-installation)
+[![Antigravity CLI](https://img.shields.io/badge/Antigravity%20CLI-8AA1F8)](https://ccsafetynet.com/docs/installation#antigravity-cli-installation)
+[![Claude Code](https://img.shields.io/badge/Claude%20Code-D27656)](https://ccsafetynet.com/docs/installation#claude-code-installation)
+[![Codex](https://img.shields.io/badge/Codex-white)](https://ccsafetynet.com/docs/installation#codex-installation)
+[![Cursor](https://img.shields.io/badge/Cursor-000000)](https://ccsafetynet.com/docs/installation#cursor-installation)
+[![Gemini CLI](https://img.shields.io/badge/Gemini%20CLI-678AE3)](https://ccsafetynet.com/docs/installation#gemini-cli-installation)
+[![GitHub Copilot CLI](https://img.shields.io/badge/GitHub%20Copilot%20CLI-4EA5C9)](https://ccsafetynet.com/docs/installation#github-copilot-cli-installation)
+[![Hermes Agent](https://img.shields.io/badge/Hermes%20Agent-2D3E50)](#hermes-agent-and-openclaw)
+[![Kimi Code](https://img.shields.io/badge/Kimi%20Code-5587FF)](https://ccsafetynet.com/docs/installation#kimi-code-installation)
+[![OpenClaw](https://img.shields.io/badge/OpenClaw-B4532A)](#hermes-agent-and-openclaw)
+[![OpenCode](https://img.shields.io/badge/OpenCode-black)](https://ccsafetynet.com/docs/installation#opencode-installation)
+[![Pi](https://img.shields.io/badge/Pi%20Coding-22262E)](https://ccsafetynet.com/docs/installation#pi-installation)
 [![License: MIT](https://img.shields.io/badge/License-MIT-red.svg)](https://opensource.org/licenses/MIT)
 
 <div align="center">
 
-[![CC Safety Net](./.github/assets/cc-safety-net.png)](./.github/assets/cc-safety-net.png)
+[![CC Safety Net](./.github/assets/cc-safety-net-v2.png)](./.github/assets/cc-safety-net-v2.png)
 
 </div>
 
-A Coding Agent CLI plugin that acts as a safety net, catching destructive git and filesystem commands before they execute.
-
-## Contents
-
-- [Why This Exists](#why-this-exists)
-- [Why Use This Instead of Permission Deny Rules?](#why-use-this-instead-of-permission-deny-rules)
-- [What About Sandboxing?](#what-about-sandboxing)
-- [Prerequisites](#prerequisites)
-- [Quick Start](#quick-start)
-  - [Codex Installation](#codex-installation)
-  - [Claude Code Installation](#claude-code-installation)
-  - [Gemini CLI Installation](#gemini-cli-installation)
-  - [GitHub Copilot CLI Installation](#github-copilot-cli-installation)
-  - [Kimi Code Installation](#kimi-code-installation)
-  - [OpenCode Installation](#opencode-installation)
-  - [Pi Installation](#pi-installation)
-- [Status Line Integration](#status-line-integration)
-  - [Emoji Mode Indicators](#emoji-mode-indicators)
-- [Diagnostics](#diagnostics)
-- [Explain (Debug Analysis)](#explain-debug-analysis)
-- [Commands Blocked](#commands-blocked)
-- [Commands Allowed](#commands-allowed)
-- [What Happens When Blocked](#what-happens-when-blocked)
-- [Testing the Hook](#testing-the-hook)
-- [Breaking Change: Custom Rules Migration](#breaking-change-custom-rules-migration)
-- [Custom Rules](#custom-rules)
-  - [Config File Location](#config-file-location)
-  - [Rule Schema](#rule-schema)
-  - [Matching Behavior](#matching-behavior)
-  - [Rule Examples](#rule-examples)
-  - [Error Handling](#error-handling)
-- [Advanced Features](#advanced-features)
-  - [Strict Mode](#strict-mode)
-  - [Paranoid Mode](#paranoid-mode)
-  - [Worktree Mode](#worktree-mode)
-  - [Shell Wrapper Detection](#shell-wrapper-detection)
-  - [Interpreter One-Liner Detection](#interpreter-one-liner-detection)
-  - [Secret Redaction](#secret-redaction)
-  - [Audit Logging](#audit-logging)
-- [Development](#development)
-- [License](#license)
-
-## Why This Exists
-
-We learned the [hard way](https://www.reddit.com/r/ClaudeAI/comments/1pgxckk/claude_cli_deleted_my_entire_home_directory_wiped/) that instructions aren't enough to keep AI agents in check.
-After Claude Code silently wiped out hours of progress with a single `rm -rf ~/` or `git checkout --`, it became evident that **soft** rules in an `CLAUDE.md` or `AGENTS.md` file cannot replace **hard** technical constraints.
-The current approach is to use a dedicated hook to programmatically prevent agents from running destructive commands.
-
-## Why Use This Instead of Permission Deny Rules?
-
-Claude Code's `.claude/settings.json` supports [deny rules](https://code.claude.com/docs/en/iam#tool-specific-permission-rules) with wildcard matching (e.g., `Bash(git reset --hard:*)`). Here's how this plugin differs:
-
-### At a Glance
-
-| | Permission Deny Rules | CC Safety Net |
-|---|---|---|
-| **Setup** | Manual configuration required | Works out of the box |
-| **Parsing** | Wildcard pattern matching | Semantic command analysis |
-| **Execution order** | Runs second | Runs first (PreToolUse hook) |
-| **Shell wrappers** | Not handled automatically (must match wrapper forms) | Recursively analyzed (up to 10 levels) |
-| **Interpreter one-liners** | Not handled automatically (must match interpreter forms) | Detected and blocked |
-
-### Permission Rules Have Known Bypass Vectors
-
-Even with wildcard matching, Bash permission patterns are intentionally limited and can be bypassed in many ways:
-
-| Bypass Method | Example |
-|---------------|---------|
-| Options before value | `curl -X GET http://evil.com` bypasses `Bash(curl http://evil.com:*)` |
-| Shell variables | `URL=http://evil.com && curl $URL` bypasses URL pattern |
-| Flag reordering | `rm -r -f /` bypasses `Bash(rm -rf:*)` |
-| Extra whitespace | `rm  -rf /` (double space) bypasses pattern |
-| Shell wrappers | `sh -c "rm -rf /"` bypasses `Bash(rm:*)` entirely |
-
-### CC Safety Net Handles What Patterns Can't
-
-| Scenario | Permission Rules | CC Safety Net |
-|----------|------------------|------------|
-| `git checkout -b feature` (safe) | Blocked by `Bash(git checkout:*)` | Allowed |
-| `git checkout -- file` (dangerous) | Blocked by `Bash(git checkout:*)` | Blocked |
-| `rm -rf /tmp/cache` (safe) | Blocked by `Bash(rm -rf:*)` | Allowed |
-| `rm -r -f /` (dangerous) | Allowed (flag order) | Blocked |
-| `bash -c 'git reset --hard'` | Allowed (wrapper) | Blocked |
-| `python -c 'os.system("rm -rf /")'` | Allowed (interpreter) | Blocked |
-
-### Defense in Depth
-
-PreToolUse hooks run [**before**](https://code.claude.com/docs/en/iam#additional-permission-control-with-hooks) the permission system. This means CC Safety Net inspects every command first, regardless of your permission configuration. Even if you misconfigure deny rules, CC Safety Net provides a fallback layer of protection.
-
-**Use both together**: Permission deny rules for quick, user-configurable blocks; CC Safety Net for robust, bypass-resistant protection that works out of the box.
-
-## What About Sandboxing?
-
-Claude Code offers [native sandboxing](https://code.claude.com/docs/en/sandboxing) that provides OS-level filesystem and network isolation. Here's how it compares to CC Safety Net:
-
-### Different Layers of Protection
-
-| | Sandboxing | CC Safety Net |
-|---|---|---|
-| **Enforcement** | OS-level (Seatbelt/bubblewrap) | Application-level (PreToolUse hook) |
-| **Approach** | Containment — restricts filesystem + network access | Command analysis — blocks destructive operations |
-| **Filesystem** | Writes restricted (default: cwd); reads are broad by default | Only destructive operations blocked |
-| **Network** | Domain-based proxy filtering | None |
-| **Git awareness** | None | Explicit rules for destructive git operations |
-| **Bypass resistance** | High — OS enforces boundaries | Lower — analyzes command strings only |
-
-### Why Sandboxing Isn't Enough
-
-Sandboxing restricts filesystem + network access, but it doesn't understand whether an operation is destructive within those boundaries. These commands are not blocked by the sandbox boundary:
+CC Safety Net — short for **Coding CLI** Safety Net — is a PreToolUse hook that blocks destructive commands and access to secrets like SSH keys and `.env` files, before AI coding agents run them. It parses command **semantics**, so flag reordering, shell wrappers, and interpreter one-liners can't bypass it.
 
 > [!NOTE]
-> Whether they're auto-run or require confirmation depends on your sandbox mode (auto-allow vs regular permissions), and network access still depends on your allowed-domain policy. Claude Code can also retry a command outside the sandbox via `dangerouslyDisableSandbox` (with user permission); this can be disabled with `allowUnsandboxedCommands: false`.
+> **[Full documentation →](https://ccsafetynet.com/docs)** — installation, configuration, reference, guides, and the security model live on the docs site. This README is the short version.
 
-| Command | Sandboxing | CC Safety Net |
-|---------|------------|------------|
-| `git reset --hard` | Allowed (within cwd) | **Blocked** |
-| `git checkout -- .` | Allowed (within cwd) | **Blocked** |
-| `git stash clear` | Allowed (within cwd) | **Blocked** |
-| `git push --force` | Allowed (if remote domain is allowed) | **Blocked** |
-| `rm -rf .` | Allowed (within cwd) | **Blocked** |
+## Why this exists
 
-Sandboxing sees `git reset --hard` as a safe operation—it only modifies files within the current directory. But you just lost all uncommitted work.
+We learned the [hard way](https://www.reddit.com/r/ClaudeAI/comments/1pgxckk/claude_cli_deleted_my_entire_home_directory_wiped/) that instructions aren't enough to keep AI agents in check. After an agent silently wiped hours of progress with a single `rm -rf ~/` or `git checkout --`, it became clear that **soft** rules in a `CLAUDE.md` or `AGENTS.md` file cannot replace **hard** technical constraints. CC Safety Net is that constraint: it observes relevant tool calls and blocks destructive commands and secret access before they reach the shell. See [What Is CC Safety Net](https://ccsafetynet.com/docs/introduction) for the full background.
 
-### When to Use Sandboxing Instead
+## What's new in v2.0.0
 
-Sandboxing is the better choice when your primary concern is:
-
-- **Prompt injection attacks** — Reduces exfiltration risk by restricting outbound domains (depends on your allowed-domain policy)
-- **Malicious dependencies** — Limits filesystem writes and network access by default (subject to your sandbox configuration)
-- **Untrusted code execution** — OS-level containment is stronger than pattern matching
-- **Network control** — CC Safety Net has no network protection
-
-### Recommended: Use Both
-
-They protect against different threats:
-
-- **Sandboxing** contains blast radius — even if something goes wrong, damage is limited to cwd and approved network domains
-- **CC Safety Net** prevents footguns — catches git-specific mistakes that are technically "safe" from the sandbox's perspective
-
-Running both together provides defense-in-depth. Sandboxing handles unknown threats; CC Safety Net handles known destructive patterns that sandboxing permits.
-
-## Prerequisites
-
-- **Node.js**: Version 18 or higher is required to run this plugin
-
-## Quick Start
-
-### Codex Installation
-
-1. Enable Codex plugin hooks in `~/.codex/config.toml`:
-
-  ```toml
-  [features]
-  plugin_hooks = true
-  ```
-
-2. Add the marketplace:
+> [!TIP]
+> **Already running v1?** One command upgrades every installed integration to v2: `npx -y cc-safety-net@latest update`. If you defined custom rules under v1, also read [Upgrading from an older version](#upgrading-from-an-older-version).
 
-  ```bash
-  codex plugin marketplace add kenryu42/cc-marketplace
-  ```
+- **Rebuilt evaluation engine** — canonical command IR, deeply immutable policy snapshots, and an ordered guard pipeline with intrinsic decision tracing behind `explain`.
+- **Secret protection** — built-in rules block content access to SSH keys, `.env` files, cloud credentials, and coding-CLI credential stores, across shell commands and file tools alike.
+- **Always-on catastrophic protections** — recursive deletion of root or home, Git metadata mutation (`.git` control plane, hooks, worktrees, submodules), and mutation of the user policy file are blocked in every mode, regardless of overrides.
+- **Safety presets** — `standard`/`strict`/`paranoid` levels with per-rule overrides, trusted delete allow-paths, and env vars that can only raise protection.
+- **Policy GUI** — `cc-safety-net gui` serves a local, token-authenticated editor with live preset preview.
+- **Universal installer** — interactive `install`/`uninstall` across all twelve supported agent CLIs, with an `update` command for installed integrations.
+- **Command-decision audit trail** — allowed and blocked command decisions recorded by default to local per-project JSONL with secret redaction, retained for 30 days by default, browsable via `cc-safety-net logs`.
+- **Documented threat model** — the [SECURITY.md](SECURITY.md) mode contract, explicit resource limits, and a residual-risk registry of adjudicated bypass families.
 
-3. Start Codex.
-4. In the TUI, run `/plugins`.
-5. Use arrow keys to select `[cc-marketplace]`.
-6. Press Enter to install the plugin.
-7. run `/hooks` and select the safety-net PreToolUse hook and press `t` to trust it.
+## Quick start
 
----
+**Prerequisite:** Node.js 18 or higher.
 
-### Claude Code Installation
+Run the interactive selector to install CC Safety Net into one or more installed coding CLIs:
 
 ```bash
-/plugin marketplace add kenryu42/cc-marketplace
-/plugin install safety-net@cc-marketplace
-/reload-plugins
+npx -y cc-safety-net@latest install
 ```
 
-### Claude Code Auto-Update
-
-1. Run `/plugin` → Select `Marketplaces` → Choose `cc-marketplace` → Enable auto-update
-
----
-
-### Gemini CLI Installation
+To update every installed integration:
 
 ```bash
-gemini extensions install https://github.com/kenryu42/gemini-safety-net
+npx -y cc-safety-net@latest update
 ```
 
----
+The `@latest` qualifier matters: a bare `cc-safety-net` spec can re-run an older
+cached copy from the npx cache instead of the current release.
 
-### GitHub Copilot CLI Installation
+To remove integrations interactively:
 
 ```bash
-/plugin install kenryu42/copilot-safety-net
+npx -y cc-safety-net uninstall
 ```
 
----
-
-### Kimi Code Installation
-
-Install CC Safety Net into your Kimi Code config:
+If you use the CLI often, install it globally to get `ccsn`, a shorter alias for the same commands:
 
 ```bash
-npx -y cc-safety-net hook install --kimi-code
+npm install -g cc-safety-net
+ccsn doctor
 ```
 
-Optional: run `npx skill add kenryu42/cc-safety-net` to add the `/cc-safety-net` skill for configuring custom rules.
+CC Safety Net works across twelve coding agent CLIs — **Claude Code, Antigravity CLI, Codex, Gemini CLI, GitHub Copilot CLI, Kimi Code, OpenCode, Pi, Cursor, Amp Code, Hermes Agent, and OpenClaw** — on **Windows, macOS, and Linux** (the Hermes Agent and OpenClaw integrations are macOS and Linux only; see [Hermes Agent and OpenClaw](#hermes-agent-and-openclaw)). Per-agent instructions, the target flags for scripted non-interactive installs, post-install steps, and per-agent caveats are on [Installation](https://ccsafetynet.com/docs/installation); how each integration hooks its agent is on [Integration Architecture](https://ccsafetynet.com/docs/guides/integration-architecture).
 
----
-
-
-### OpenCode Installation
-
-Install CC Safety Net with OpenCode's native plugin command:
-
-```bash
-opencode plugin -g cc-safety-net
-```
+## Hermes Agent and OpenClaw
 
-> [!NOTE]
-> OpenCode can sometimes keep using a stale cached plugin version. See
-> anomalyco/opencode#25293 for the current tracking issue.
->
-> To force OpenCode to reinstall `cc-safety-net`, remove its cached package and
-> install the version you want:
->
-> ```sh
-> rm -rf ~/.cache/opencode/packages/cc-safety-net@latest
-> opencode plugin -g -f cc-safety-net@latest
->
-> If you prefer pinning a specific version:
->
-> rm -rf ~/.cache/opencode/packages/cc-safety-net@latest
-> opencode plugin -g -f cc-safety-net@<version>
->
-> Restart OpenCode after updating so the plugin is loaded from the refreshed
-> cache.
-
----
-
-### Pi Installation
-
-Install CC Safety Net with Pi's package installer:
+These two integrations are newer than the docs site, so their setup steps and coverage
+boundaries live here.
 
 ```bash
-pi install npm:cc-safety-net
-```
-
----
-
-## Status Line Integration
-
-CC Safety Net can display its status in Claude Code's status line, showing whether protection is active and which modes are enabled.
-
-Add the following to your `~/.claude/settings.json`:
-
-**Using Bun (recommended):**
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "bunx cc-safety-net statusline --claude-code"
-  }
-}
-```
-
-**Using Claude X:**
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "BUN_BE_BUN=1 claude x cc-safety-net statusline --claude-code"
-  }
-}
-```
-> [!NOTE]
-> The `claude x` command is only compatible with the native version of Claude Code. If you installed via npm, please use `npx` or `bunx` instead.
-
-
-
-**Using NPM:**
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "npx -y cc-safety-net statusline --claude-code"
-  }
-}
-```
+# Hermes Agent — installs a managed Python plugin, then restart Hermes
+npx -y cc-safety-net@latest install --hermes-agent
+npx -y cc-safety-net@latest uninstall --hermes-agent
 
-**Piping with existing status line:**
-
-If you already have a status line command, you can pipe CC Safety Net at the end:
-
-```json
-{
-  "statusLine": {
-    "type": "command",
-    "command": "your-existing-command | bunx cc-safety-net statusline --claude-code"
-  }
-}
+# OpenClaw — installs a bundled plugin through OpenClaw's own CLI, then restart the Gateway
+npx -y cc-safety-net@latest install --openclaw
+npx -y cc-safety-net@latest uninstall --openclaw
 ```
 
-Changes take effect immediately — no restart needed.
-
-### Emoji Mode Indicators
+Run `npx cc-safety-net doctor` after either install: it is the only surface that reports a plugin
+that is present but not enabled, not ours, or out of date. It reads disk and config only and never
+asks a running host whether the plugin loaded, so a stopped OpenClaw Gateway is not reported as a
+failure — the OpenClaw install verifies the load itself.
 
-The status line displays different emojis based on the current configuration:
+**Hermes Agent.** Install writes a managed plugin to `$HERMES_HOME/plugins/cc-safety-net/`
+(`~/.hermes` when `HERMES_HOME` is unset) and then
+runs `hermes plugins enable cc-safety-net --no-allow-tool-override`. It is an ordinary Hermes user
+plugin: it runs inside the Hermes process with the trust Hermes grants user plugins, and it is
+inert until Hermes is restarted. On every `pre_tool_call` it shells out to
+`npx -y cc-safety-net hook --hermes-agent` with a 30-second timeout, and blocks the call itself
+whenever that analysis cannot complete — missing `npx`, spawn failure, timeout, unreadable output,
+or a Hermes session directory it cannot read.
+Protected tools are `terminal`, `read_file`, `write_file`, and `patch`; calls to any other Hermes
+tool are not forwarded and get no decision. Uninstall runs `hermes plugins disable cc-safety-net`
+first — Hermes only resolves a plugin that is still on disk — and then removes the managed files,
+so the config entry goes with them; a failing or missing `hermes` is reported as a warning and the
+files are removed anyway.
 
-| Status | Display | Meaning |
-|--------|---------|---------|
-| Plugin disabled | `🛡️ CC Safety Net ❌` | CC Safety Net plugin is not enabled |
-| Default mode | `🛡️ CC Safety Net ✅` | Protection active with default settings |
-| Strict mode | `🛡️ CC Safety Net 🔒` | `CC_SAFETY_NET_STRICT=1` — fail-closed on unparseable commands |
-| Paranoid mode | `🛡️ CC Safety Net 👁️` | `CC_SAFETY_NET_PARANOID=1` — all paranoid checks enabled |
-| Paranoid RM only | `🛡️ CC Safety Net 🗑️` | `CC_SAFETY_NET_PARANOID_RM=1` — blocks `rm -rf` even within cwd |
-| Paranoid interpreters only | `🛡️ CC Safety Net 🐚` | `CC_SAFETY_NET_PARANOID_INTERPRETERS=1` — blocks interpreter one-liners |
-| Worktree mode | `🛡️ CC Safety Net 🌳` | `CC_SAFETY_NET_WORKTREE=1` — relax local git discards inside linked worktrees |
-| Strict + Paranoid | `🛡️ CC Safety Net 🔒👁️` | Both strict and paranoid modes enabled |
+**OpenClaw.** Install runs `openclaw plugins install <bundled plugin dir> --force` followed by
+`openclaw plugins enable cc-safety-net`, then verifies the plugin actually loaded. **Restart the
+OpenClaw Gateway afterwards, and if `plugins.allow` is set in `openclaw.json` it must also list
+`cc-safety-net`** — until both are true the plugin never runs and nothing is blocked. The plugin
+registers `before_tool_call` for the canonical `exec` tool only and returns a plain allow or
+block; it never rewrites tool parameters. It resolves the agent workspace as the policy and
+execution directory, and denies a call whose `workdir` resolves outside that workspace or whose
+agent or workspace context cannot be established. Live end-to-end tests (`bun run test:e2e:live`,
+run before a release) drive the real `openclaw` binary against a throwaway state directory: our
+CLI installs the plugin, the host reports it loaded with the hook registered, and a real Gateway
+agent turn puts a real `exec` call through it — a harmless command runs, `git reset --hard` is
+blocked before it can touch the workspace.
 
-Multiple mode emojis are combined when multiple environment variables are set. Mode flags use `CC_SAFETY_NET_*` names; legacy `SAFETY_NET_*` names are still accepted.
+**What is not covered.**
 
-## Diagnostics
+- **Hermes bang-shell.** A `!command` you type yourself does not raise `pre_tool_call`; it goes
+  straight to Hermes' own command guard. CC Safety Net sees model-generated tool calls only, not
+  every subprocess Hermes starts.
+- **Hermes shell hooks fail open.** Hermes' `hooks:` dispatcher allows the tool call when a hook
+  cannot start, times out, or returns unparseable output. That is why the shipped integration is
+  the Python plugin, which blocks on its own failures, and why `hooks:` is a diagnostic path only.
+  One case stays outside our reach either way: if Hermes never loads the plugin, nothing blocks
+  and only `doctor` will say so.
+- **OpenClaw execution hosts.** `exec` calls with no `host`, `host: "auto"`, or `host: "gateway"`
+  are analysed as local Gateway calls. Explicit `host: "sandbox"` and `host: "node"` are blocked
+  as unsupported, because no test proves a correct path mapping for them. When a sandbox runtime
+  is active, an `auto` call runs in the sandbox filesystem while paths are still analysed against
+  the Gateway workspace — command rules are unaffected, path rules can be evaluated against the
+  wrong filesystem. The same applies when a call carries no `host` and your configured
+  `tools.exec.host` default is `node` or `sandbox`: the call is still analysed as a local Gateway
+  call.
+- **OpenClaw Codex-native relay.** Untested, and therefore unclaimed. The live end-to-end tests
+  drive OpenClaw's own agent runtime, so they say nothing about a Codex-native shell, patch, or
+  MCP call.
+- **OpenClaw file tools.** `apply_patch` and OpenClaw's read/write/edit tools are not protected;
+  only `exec` is.
+- **Windows.** Both integrations assume the POSIX layout. Relocated state is handled the way the
+  hosts resolve it — `HERMES_HOME` for Hermes, then `OPENCLAW_STATE_DIR` and the directory of
+  `OPENCLAW_CONFIG_PATH` for OpenClaw, falling back to `~/.hermes` and `~/.openclaw`. The Windows
+  defaults are not: install and detection target the POSIX path there, so Hermes writes to the
+  wrong directory and OpenClaw's own CLI installs correctly while `doctor` misreports the state.
 
-Run the diagnostic command to verify your installation and troubleshoot issues:
+## What it does
 
-```bash
+| Capability | What it catches |
+|---|---|
+| **Semantic command analysis** | `rm -rf` on destructive targets, `git reset --hard`, `git checkout --`, `git push --force`, `git stash clear`, `git clean -f`, unsafe `find -delete`, `dd`/`mkfs`/`shred` — by intent, not string pattern. `git checkout -b feature` (safe) is allowed while `git checkout -- file` (destructive) is blocked. |
+| **Shell wrapper detection** | Destructive commands hidden in `bash -c`, `sh -c`, and similar wrappers, recursively analyzed up to 10 levels deep. |
+| **Interpreter one-liners** | Destructive code in `python -c`, `node -e`, `ruby -e`, `perl -e` one-liners (e.g. `os.system("rm -rf /")`). |
+| **Fail-closed by default** | Malformed hook input and unparseable commands (in strict mode) block rather than allow. Invalid config never blocks: an unverifiable rule source is dropped and an unreadable `policy.json` falls back to protective defaults, both with a warning on every reporting surface. |
+| **Secret protection** | Content access to SSH keys, `.env` files, `~/.aws`, kube/docker/gcloud configs, and coding-CLI credential stores — enforced on shell commands and file tools (read/edit/write/search) alike. |
+| **Custom rules via rulebooks** | Add your own blocking rules at user or project scope, pinned by SHA-256 digest when fetched from GitHub. |
+| **Audit logging** | Allowed and blocked command decisions written to local per-project JSONL with secrets auto-redacted, retained for 30 days by default. Browse them with `npx cc-safety-net logs`, or triage them in the **Activity** view of `npx cc-safety-net gui`. |
+
+Full rule catalogs: [Blocked Commands](https://ccsafetynet.com/docs/reference/blocked-commands) · [Allowed Commands](https://ccsafetynet.com/docs/reference/allowed-commands) · [Secret Protection](https://ccsafetynet.com/docs/reference/secret-protection).
+
+## Why not just use a sandbox?
+
+A workspace-writable sandbox still permits `git reset --hard`, `git push --force`, and `rm -rf .` *inside* the project directory, because the OS only sees writes to an allowed path. Sandboxing contains blast radius; CC Safety Net catches the destructive operations sandboxing permits — use both for defense-in-depth. See [vs Sandboxing](https://ccsafetynet.com/docs/guides/vs-sandboxing).
+
+## Safety presets
+
+Set a session safety preset with `CC_SAFETY_NET_LEVEL=standard|strict|paranoid`:
+
+| Preset | Effect |
+|---|---|
+| Standard | Blocks recognizable destructive Git and filesystem commands. Allows metadata-only checks of built-in sensitive paths while continuing to block content access. Recommended for normal coding. |
+| Strict | Standard, plus blocks dynamic or unparseable commands the analyzer cannot verify safely and metadata-only discovery of built-in sensitive paths. Occasional false positives on advanced shell. |
+| Paranoid | Strict, plus blocks `rm -rf` inside your project and interpreter one-liners. Expect friction; for untrusted agents or high-stakes repos. |
+
+Presets supply inherited defaults; `policy.json` stores only your explicit deviations — per-rule overrides, allow paths, deny paths, worktree mode, and audit retention. Environment variables can only raise protection, never lower it. The full contract is on [Modes](https://ccsafetynet.com/docs/configuration/modes), [Policy](https://ccsafetynet.com/docs/configuration/policy), and [Environment](https://ccsafetynet.com/docs/configuration/environment), or edit everything visually with the [local GUI](https://ccsafetynet.com/docs/guides/dashboard).
+
+## Diagnostics and tracing
+
+```bash
+# Summarize what is being enforced right now
+npx cc-safety-net status
+# Verify your installation and run a self-test
 npx cc-safety-net doctor
-# or with bun
-bunx cc-safety-net doctor
-```
-
-The doctor command checks:
-
-| Check | Description |
-|-------|-------------|
-| Hook Integration | Verifies the plugin is properly configured for each supported platform |
-| Self-Test | Runs sample commands to confirm blocking works correctly |
-| Configuration | Validates custom rules in user and project configs |
-| Environment | Shows status of mode flags (`CC_SAFETY_NET_STRICT`, `CC_SAFETY_NET_PARANOID`, etc.; legacy `SAFETY_NET_*` also listed when set) |
-| Recent Activity | Summarizes blocked commands from the last 7 days |
-| System Info | Displays versions of all relevant tools |
-| Update Check | Checks if a newer version is available |
-
-### Options
-
-| Flag | Description |
-|------|-------------|
-| `--json` | Output in JSON format (useful for sharing in bug reports) |
-| `--skip-update-check` | Skip the npm version check |
-
-## Explain (Debug Analysis)
-
-Trace how CC Safety Net analyzes a command step-by-step. Useful for debugging why a command is blocked or allowed, or when developing custom rules.
-
-```bash
+# Trace how a command is analyzed step-by-step
 npx cc-safety-net explain "git reset --hard"
-# or with bun
-bunx cc-safety-net explain "git reset --hard"
+# Browse recorded denials from the audit trail (add --all to include allowed commands)
+npx cc-safety-net logs
+# Review what was blocked and edit your policy in a local web GUI
+npx cc-safety-net gui
 ```
 
-### Options
+`doctor`, `explain`, and `logs` support `--json` for machine-readable output. The audit trail records command decisions only — never command output or prompts — and stays on your machine. Invalid configuration never blocks your agent: unverifiable rule sources are dropped and every degraded state is reported on the next block message, `doctor`, the status line, and the GUI banner.
 
-| Flag | Description |
-|------|-------------|
-| `--json` | Output analysis as JSON |
-| `--cwd <path>` | Use custom working directory for analysis |
+Details: [CLI Commands](https://ccsafetynet.com/docs/reference/cli-commands) · [Explain Trace](https://ccsafetynet.com/docs/reference/explain-trace) · [Audit Log](https://ccsafetynet.com/docs/reference/audit-log) · [Dashboard](https://ccsafetynet.com/docs/guides/dashboard) · [Configuration Recovery](https://ccsafetynet.com/docs/configuration/recovery).
 
-### Examples
+## Limitations
 
-```bash
-npx cc-safety-net explain "rm -rf /"
-npx cc-safety-net explain --json "git checkout -- file.txt"
-npx cc-safety-net explain --cwd /tmp "git status"
-```
+CC Safety Net denies a tool call before it runs; it does not enforce filesystem permissions, inspect network egress, or contain a process. Two v2 bounds worth knowing up front: the policy and sensitive-path command extractors remain primarily POSIX-oriented, so native PowerShell path expressions such as `Get-Content $HOME\.ssh\id_rsa` can evade static path extraction; and policy-file protection is a best-effort exact-path guard, not command emulation. Use operating-system permissions, a sandbox, or equivalent runtime enforcement when complete protection is required.
 
-## Commands Blocked
-
-| Command Pattern | Why It's Dangerous |
-|-----------------|-------------------|
-| git checkout -- files | Discards uncommitted changes permanently |
-| git checkout \<ref\> -- \<path\> | Overwrites working tree with ref version |
-| git checkout \<ref\> \<path\> | May overwrite working tree when Git disambiguates ref vs pathspec |
-| git restore files | Discards uncommitted changes |
-| git restore --worktree | Explicitly discards working tree changes |
-| git switch --discard-changes | Discards uncommitted changes when switching branches |
-| git switch --force / -f | Discards uncommitted changes (force switch) |
-| git reset --hard | Destroys all uncommitted changes |
-| git reset --merge | Can lose uncommitted changes |
-| git clean -f | Removes untracked files permanently |
-| git push --force / -f | Destroys remote history |
-| git branch -D | Force-deletes branch without merge check |
-| git stash drop | Permanently deletes stashed changes |
-| git stash clear | Deletes ALL stashed changes |
-| git worktree remove --force | Force-deletes worktree without checking for changes |
-| rm -rf (destructive targets) | Recursive file deletion of root, home, parent, absolute, or non-temp paths outside cwd |
-| rm -rf / or ~ or $HOME | Root/home deletion is extremely dangerous |
-| find ... -delete | Permanently removes files matching criteria |
-| xargs rm -rf | Dynamic input makes targets unpredictable |
-| xargs \<shell\> -c | Can execute arbitrary commands |
-| parallel rm -rf | Dynamic input makes targets unpredictable |
-| parallel \<shell\> -c | Can execute arbitrary commands |
-| dd writing to block devices | Can overwrite disks or partitions |
-| mkfs on block devices | Formats disks or partitions |
-| shred | Permanently destroys file contents |
-
-## Commands Allowed
-
-| Command Pattern | Why It's Safe |
-|-----------------|--------------|
-| git checkout -b branch | Creates new branch |
-| git checkout --orphan | Creates orphan branch |
-| git restore --staged | Only unstages, doesn't discard |
-| git restore --help/--version | Help/version output |
-| git branch -d | Safe delete with merge check |
-| git clean -n / --dry-run | Preview only |
-| git push --force-with-lease | Safe force push |
-| rm -rf /tmp/... | Temp directories are ephemeral |
-| rm -rf /var/tmp/... | System temp directory |
-| rm -rf $TMPDIR/... | User's temp directory |
-| rm -rf ./... (within cwd) | Limited to current working directory |
-| git restore / checkout -- / reset --hard / clean -f (in linked worktree) | Relaxed only when `CC_SAFETY_NET_WORKTREE=1` and cwd is a linked worktree |
-
-## What Happens When Blocked
-
-When a destructive command is detected, the plugin blocks the tool execution and provides a reason.
-
-Example output:
-```text
-BLOCKED by CC Safety Net
-
-Reason: git checkout -- discards uncommitted changes permanently. Use 'git stash' first.
-
-Command: git checkout -- src/main.py
-
-If this operation is truly needed, ask the user for explicit permission and have them run the command manually.
-```
+The full residual-risk registry lives in [SECURITY.md](SECURITY.md); the practical consequences are on [Known Limitations](https://ccsafetynet.com/docs/guides/known-limitations).
 
-## Testing the Hook
+## Upgrading from an older version
 
-You can manually test the hook by attempting to run blocked commands in Claude Code:
+Upgrade every installed integration to the current release with one command:
 
 ```bash
-# This should be blocked
-git checkout -- README.md
-
-# This should be allowed
-git checkout -b test-branch
+npx -y cc-safety-net@latest update
 ```
 
-## Breaking Change: Custom Rules Migration
-
 > [!WARNING]
-> The custom rules system has moved from legacy inline config files to a rulebook-based layout. Legacy inline config files (`.safety-net.json` and `~/.cc-safety-net/config.json`) are **no longer loaded at runtime**. If they contain rules, commands now **fail closed** (stay blocked) until you migrate.
+> If you previously defined custom rules in a legacy inline config (`.safety-net.json` or `~/.cc-safety-net/config.json`), those files are **no longer loaded at runtime** and **their rules are not enforcing anything**. Nothing is blocked, so you will not notice this from normal use — the commands those rules used to block now run. Run `npx -y cc-safety-net rule migrate` to convert them to the rulebook layout, then `npx -y cc-safety-net doctor` to confirm the runtime is `ready`. See the [migration guide](https://ccsafetynet.com/docs/configuration/custom-rules#migration-from-legacy-config).
 
-### Who Is Affected
+## Full documentation
 
-- **Affected**: users who previously defined custom rules in `.safety-net.json` (project scope) or `~/.cc-safety-net/config.json` (user scope).
-- **Not affected**: users with no custom rules. All built-in destructive-command protections are unchanged and continue to work out of the box.
+All details live on the docs site at **[ccsafetynet.com/docs](https://ccsafetynet.com/docs)**:
 
-### What Breaks
-
-| Legacy file state | New behavior |
-|-------------------|--------------|
-| Empty legacy file | Silently ignored — built-in rules only |
-| Legacy file with rules | Fail closed until migrated with `rule migrate` |
-| Invalid legacy file | Fail closed until fixed and migrated, or removed |
-
-"Fail closed" means commands stay blocked until the legacy rules are migrated to the new layout.
-
-### How to Migrate
-
-```bash
-# Convert legacy inline rules into the new rulebook layout
-npx -y cc-safety-net rule migrate
-
-# Optionally delete verified legacy files after migration
-npx -y cc-safety-net rule migrate --cleanup
-
-# Validate the migrated rules
-npx -y cc-safety-net rule verify
-npx -y cc-safety-net rule test
-```
-
-### Before / After
-
-**Before** — a single inline config with rules embedded:
-
-```text
-.safety-net.json          # project rules (inline)
-~/.cc-safety-net/config.json   # user rules (inline)
-```
-
-**After** — `rule migrate` creates a rulebook-based layout automatically:
-
-```text
-.cc-safety-net/rules/rule.json                    # project rulebook sources + overrides
-.cc-safety-net/rules/project-rules/rulebook.json  # migrated project rules
-~/.cc-safety-net/rules/rule.json                  # user rulebook sources + overrides
-~/.cc-safety-net/rules/user-rules/rulebook.json   # migrated user rules
-```
-
-See [Custom Rules](#custom-rules) for the full authoring guide and [Error Handling](#error-handling) for fail-closed details.
-
-## Custom Rules
-
-Beyond the built-in protections, you can define your own blocking rules to enforce team conventions or project-specific safety policies.
-
-> [!TIP]
-> The best way to create custom rules is to use the `/cc-safety-net` skill to create custom rules interactively with natural language.
-
-### Examples
-
-```
-/cc-safety-net read my package.json and suggest blocking rules
-/cc-safety-net set up rules to block all terraform destroy commands
-/cc-safety-net verify my rules and fix any errors
-```
-
-> [!NOTE]
-> If your agent does not support skills, prompt it with:
-> ```
-> run npx -y cc-safety-net rule doc and help me set up custom rules
-> ```
-
-### Create Rules Manually
-
-Create a starter project rule config and rulebook:
-
-```bash
-npx -y cc-safety-net rule init
-```
-
-This creates `.cc-safety-net/rules/rule.json`:
-
-```json
-{
-  "version": 1,
-  "rules": ["project-rules"],
-  "overrides": {}
-}
-```
-
-Rule definitions live in `.cc-safety-net/rules/project-rules/rulebook.json`:
-
-```json
-{
-  "rulebook_version": 1,
-  "name": "project-rules",
-  "version": "1.0.0",
-  "description": "Project-specific CC Safety Net rules.",
-  "author": "project",
-  "allowed_commands": ["git"],
-  "rules": [
-    {
-      "name": "block-git-add-all",
-      "command": "git",
-      "subcommand": "add",
-      "block_args": ["-A", "--all", "."],
-      "reason": "Use 'git add <specific-files>' instead of blanket add."
-    }
-  ],
-  "tests": [
-    {
-      "command": "git add -A",
-      "expect": "blocked",
-      "rule": "block-git-add-all"
-    },
-    {
-      "command": "git add README.md",
-      "expect": "allowed"
-    }
-  ]
-}
-```
-
-After editing rulebooks, run:
-
-```bash
-npx -y cc-safety-net rule sync
-npx -y cc-safety-net rule verify
-npx -y cc-safety-net rule test
-```
-
-Now `git add -A`, `git add --all`, and `git add .` will be blocked with your custom message.
-
-### Config File Location
-
-Config files are loaded from two scopes and merged:
-
-1. **User scope**: `~/.cc-safety-net/rules/rule.json` (use `rule init --global`)
-2. **Project scope**: `.cc-safety-net/rules/rule.json` in the current working directory
-
-Local rulebook sources are bare names like `project-rules`. GitHub rulebook sources use `owner/repo#ref/<rulebook-name>` and point to `.cc-safety-net/rules/<rulebook-name>/rulebook.json` in that repository.
-
-Legacy inline config files (`.safety-net.json` and `~/.cc-safety-net/config.json`) are no longer loaded at runtime. Empty legacy files are ignored, but legacy files with rules and invalid legacy files fail closed until migrated or fixed. Convert existing legacy rules with `npx -y cc-safety-net rule migrate`; use `npx -y cc-safety-net rule migrate --cleanup` if you also want to delete verified legacy files after migration. See [Breaking Change: Custom Rules Migration](#breaking-change-custom-rules-migration) for the full upgrade guide.
-
-**Merging behavior**:
-- Rulebooks from both scopes are combined
-- Duplicate active rulebook names are invalid
-- Project overrides win over user overrides for the same `<rulebook-name>/<rule-name>` key
-
-This allows you to define personal defaults in user scope while letting projects disable or replace reasons for specific rules.
-
-If no config file is found in either location, only built-in rules apply.
-
-### Config Schema
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `version` | integer | Yes | Schema version (must be `1`) |
-| `rules` | array | No | List of rulebook source strings (defaults to empty) |
-| `overrides` | object | No | Rule overrides keyed by `<rulebook-name>/<rule-name>` |
-
-Override values are either `"off"` to disable a rule or `{ "reason": "..." }` to replace the rule reason.
-
-### Rulebook Schema
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `rulebook_version` | integer | Yes | Rulebook schema version (must be `1`) |
-| `name` | string | Yes | Rulebook name; must match the local directory name or GitHub source name |
-| `version` | string | Yes | Rulebook version |
-| `description` | string | No | Human-readable description |
-| `author` | string | No | Rulebook author |
-| `allowed_commands` | array | Yes | Commands this rulebook is allowed to define rules for |
-| `rules` | array | Yes | Custom blocking rules |
-| `tests` | array | Yes | Rulebook fixtures |
-
-### Rule Schema
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `name` | string | Yes | Unique within the rulebook (letters, numbers, hyphens, underscores; max 64 chars) |
-| `command` | string | Yes | Base command to match; must be listed in `allowed_commands` |
-| `subcommand` | string | No | Subcommand to match (e.g., `add`, `install`). If omitted, matches any. |
-| `block_args` | array | Yes | Arguments that trigger the block (at least one required) |
-| `reason` | string | Yes | Message shown when blocked (max 256 chars) |
-
-### Fixture Schema
-
-| Field | Type | Required | Description |
-|-------|------|----------|-------------|
-| `command` | string | Yes | Shell command fixture |
-| `expect` | string | Yes | Either `blocked` or `allowed` |
-| `rule` | string | For blocked fixtures | Rule expected to block the command |
-
-Every rule must have at least one blocked fixture. Add allowed fixtures for close-but-safe commands.
-
-### Matching Behavior
-
-- **Commands** are normalized to basename (`/usr/bin/git` → `git`)
-- **Subcommand** is the first non-option argument after the command
-- **Arguments** are matched literally (no regex, no glob), with short option expansion
-- A command is blocked if **any** argument in `block_args` is present
-- **Short options** are expanded: `-Ap` matches `-A` (bundled flags are unbundled)
-- **Long options** use exact match: `--all-files` does NOT match `--all`
-- Custom rules only add restrictions—they cannot bypass built-in protections
-
-#### Known Limitations
-
-- **Short option expansion**: `-Cfoo` is treated as `-C -f -o -o`, not `-C foo`. Blocking `-f` may false-positive on attached option values.
-
-### Rule Examples
-
-#### Block global npm installs
-
-`.cc-safety-net/rules/rule.json`:
-
-```json
-{
-  "version": 1,
-  "rules": ["project-rules"],
-  "overrides": {}
-}
-```
-
-`.cc-safety-net/rules/project-rules/rulebook.json`:
-
-```json
-{
-  "rulebook_version": 1,
-  "name": "project-rules",
-  "version": "1.0.0",
-  "allowed_commands": ["npm"],
-  "rules": [
-    {
-      "name": "block-npm-global",
-      "command": "npm",
-      "subcommand": "install",
-      "block_args": ["-g", "--global"],
-      "reason": "Global npm installs can cause version conflicts. Use npx or local install."
-    }
-  ],
-  "tests": [
-    {
-      "command": "npm install -g typescript",
-      "expect": "blocked",
-      "rule": "block-npm-global"
-    },
-    {
-      "command": "npm install typescript",
-      "expect": "allowed"
-    }
-  ]
-}
-```
-
-#### Block dangerous docker commands
-
-```json
-{
-  "rulebook_version": 1,
-  "name": "project-rules",
-  "version": "1.0.0",
-  "allowed_commands": ["docker"],
-  "rules": [
-    {
-      "name": "block-docker-system-prune",
-      "command": "docker",
-      "subcommand": "system",
-      "block_args": ["prune"],
-      "reason": "docker system prune removes all unused data. Use targeted cleanup instead."
-    }
-  ],
-  "tests": [
-    {
-      "command": "docker system prune",
-      "expect": "blocked",
-      "rule": "block-docker-system-prune"
-    },
-    {
-      "command": "docker ps",
-      "expect": "allowed"
-    }
-  ]
-}
-```
-
-#### Multiple rules
-
-```json
-{
-  "rulebook_version": 1,
-  "name": "project-rules",
-  "version": "1.0.0",
-  "allowed_commands": ["git", "npm"],
-  "rules": [
-    {
-      "name": "block-git-add-all",
-      "command": "git",
-      "subcommand": "add",
-      "block_args": ["-A", "--all", ".", "-u", "--update"],
-      "reason": "Use 'git add <specific-files>' instead of blanket add."
-    },
-    {
-      "name": "block-npm-global",
-      "command": "npm",
-      "subcommand": "install",
-      "block_args": ["-g", "--global"],
-      "reason": "Use npx or local install instead of global."
-    }
-  ],
-  "tests": [
-    {
-      "command": "git add -A",
-      "expect": "blocked",
-      "rule": "block-git-add-all"
-    },
-    {
-      "command": "npm install -g typescript",
-      "expect": "blocked",
-      "rule": "block-npm-global"
-    }
-  ]
-}
-```
-
-### Error Handling
-
-Rulebook-backed custom rules fail closed when configured rulebooks cannot be loaded safely:
-
-| Scenario | Behavior |
-|----------|----------|
-| Config file not found | Silent — use built-in rules only |
-| Invalid rule config | Fail closed until fixed |
-| Empty legacy config | Silent — use built-in rules only |
-| Legacy config with rules and no migrated rule config | Fail closed until `rule migrate` creates the new rule config |
-| Invalid legacy config | Fail closed until fixed or removed |
-| Missing or stale lock/cache | Fail closed until `rule sync` repairs it |
-| Invalid local rulebook | Fail closed until the rulebook is fixed and synced |
-| Invalid GitHub rulebook | Fail closed until the source is fixed or removed |
-
-
-> [!IMPORTANT]  
-> If you add or modify custom rules manually, always validate them with `npx -y cc-safety-net rule verify` and `npx -y cc-safety-net rule test`.
-
-### Block Output Format
-
-When a custom rule blocks a command, the output includes the rule name:
-
-```text
-BLOCKED by CC Safety Net
-
-Reason: [block-git-add-all] Use 'git add <specific-files>' instead of blanket add.
-
-Command: git add -A
-```
-
-## Advanced Features
-
-Mode and debug flags use **`CC_SAFETY_NET_*`** environment variables. Older **`SAFETY_NET_*`** names (without the `CC_` prefix) still work for strict, paranoid, and worktree toggles.
-
-### Strict Mode
-
-Malformed or missing hook input JSON always fails closed. By default, ambiguous shell
-command parsing is allowed through. Enable strict mode to fail closed when a shell
-command cannot be safely analyzed (e.g., unterminated quotes or malformed `bash -c`
-wrappers):
-
-```bash
-export CC_SAFETY_NET_STRICT=1
-```
-
-### Paranoid Mode
-
-Paranoid mode enables stricter safety checks that may be disruptive to normal workflows.
-You can enable it globally or via focused toggles:
-
-```bash
-# Enable all paranoid checks
-export CC_SAFETY_NET_PARANOID=1
-
-# Or enable specific paranoid checks
-export CC_SAFETY_NET_PARANOID_RM=1
-export CC_SAFETY_NET_PARANOID_INTERPRETERS=1
-```
-
-Paranoid behavior:
-
-- **rm**: blocks non-temp `rm -rf` even within the current working directory.
-- **interpreters**: blocks interpreter one-liners like `python -c`, `node -e`, `ruby -e`,
-  and `perl -e` (these can hide destructive commands).
-
-### Worktree Mode
-
-Linked git worktrees are designed as disposable, isolated workspaces — discarding
-changes inside one doesn't risk the main working tree. Worktree mode relaxes
-local-discard rules when (and only when) the command is proven to run inside a
-linked worktree:
-
-```bash
-export CC_SAFETY_NET_WORKTREE=1
-```
-
-When enabled, these commands are allowed inside a linked worktree:
-
-- `git restore <file>` and `git restore --worktree <file>`
-- `git checkout -- <file>`, `git checkout <ref> -- <file>`, `git checkout --force`,
-  and ambiguous multi-positional checkout forms
-- `git switch --discard-changes` and `git switch -f / --force`
-- `git reset --hard` and `git reset --merge`
-- `git clean -f` (and combined short flags like `-fd`)
-
-These remain blocked even in linked worktrees because they reach beyond the
-local working tree:
-
-- `git push --force` (affects remote)
-- `git branch -D` (affects shared refs)
-- `git stash drop` / `git stash clear` (stash is shared across worktrees)
-- `git worktree remove --force` (could delete another worktree)
-
-Detection is fail-closed and mostly filesystem-based:
-
-- A linked worktree is identified by a `.git` *file* containing `gitdir:` whose
-  resolved git directory contains a `commondir` file. Main worktrees and
-  submodules don't satisfy this and are not relaxed.
-- The cwd walk uses `realpath` so symlinked paths resolve correctly.
-- `git -C <path>` (including chained `-C` and attached `-Cpath`) is honored;
-  unresolved targets keep the command blocked.
-- Relaxation is disabled if cwd becomes unknown (e.g., after `cd`/`pushd`),
-  if `--git-dir` / `--work-tree` is passed, or if `GIT_DIR` / `GIT_WORK_TREE`
-  / `GIT_COMMON_DIR` is set in the environment.
-- Git may be invoked from a trusted system path to inspect effective config that
-  could make submodule operations recursive.
-
-### Shell Wrapper Detection
-
-The guard recursively analyzes commands wrapped in shells:
-
-```bash
-bash -c 'git reset --hard'    # Blocked
-sh -lc 'rm -rf /'             # Blocked
-bash -c 'git stash drop'      # Blocked
-```
-
-### Interpreter One-Liner Detection
-
-Detects destructive commands hidden in Python/Node/Ruby/Perl one-liners:
-
-```bash
-python -c 'import os; os.system("rm -rf /")'  # Blocked
-python -c 'import os; os.system("git stash drop")'  # Blocked
-python -c 'import os; os.system("dd if=/dev/zero of=/dev/sda")'  # Blocked
-python -c 'import os; os.system("mkfs.ext4 /dev/sda1")'  # Blocked
-python -c 'import os; os.system("shred -u secret.txt")'  # Blocked
-```
-
-### Secret Redaction
-
-Block messages automatically redact sensitive data (tokens, passwords, API keys) to prevent leaking secrets in logs.
-
-### Audit Logging
-
-All blocked commands are logged to `~/.cc-safety-net/logs/<session_id>.jsonl` for audit purposes:
-
-```json
-{"ts": "2025-01-15T10:30:00Z", "command": "git reset --hard", "segment": "git reset --hard", "reason": "...", "cwd": "/path/to/project"}
-```
-
-Sensitive data in log entries is automatically redacted.
+| Area | Pages |
+|---|---|
+| Get started | [Introduction](https://ccsafetynet.com/docs/introduction) · [Installation](https://ccsafetynet.com/docs/installation) · [Quickstart](https://ccsafetynet.com/docs/quickstart) · [How It Works](https://ccsafetynet.com/docs/guides/how-it-works) · [Dashboard](https://ccsafetynet.com/docs/guides/dashboard) |
+| Configuration | [Modes](https://ccsafetynet.com/docs/configuration/modes) · [Policy](https://ccsafetynet.com/docs/configuration/policy) · [Environment](https://ccsafetynet.com/docs/configuration/environment) · [Custom Rules](https://ccsafetynet.com/docs/configuration/custom-rules) · [Status Line](https://ccsafetynet.com/docs/configuration/status-line) · [Configuration Recovery](https://ccsafetynet.com/docs/configuration/recovery) |
+| Reference | [Blocked Commands](https://ccsafetynet.com/docs/reference/blocked-commands) · [Allowed Commands](https://ccsafetynet.com/docs/reference/allowed-commands) · [Secret Protection](https://ccsafetynet.com/docs/reference/secret-protection) · [Audit Log](https://ccsafetynet.com/docs/reference/audit-log) · [CLI Commands](https://ccsafetynet.com/docs/reference/cli-commands) · [Explain Trace](https://ccsafetynet.com/docs/reference/explain-trace) · [Glossary](https://ccsafetynet.com/docs/reference/glossary) |
+| Guides | [Architecture](https://ccsafetynet.com/docs/guides/architecture) · [Analysis Engine](https://ccsafetynet.com/docs/guides/analysis-engine) · [Design Principles](https://ccsafetynet.com/docs/guides/design-principles) · [Security Model](https://ccsafetynet.com/docs/guides/security-model) · [vs Sandboxing](https://ccsafetynet.com/docs/guides/vs-sandboxing) · [Integration Architecture](https://ccsafetynet.com/docs/guides/integration-architecture) · [Known Limitations](https://ccsafetynet.com/docs/guides/known-limitations) · [Troubleshooting](https://ccsafetynet.com/docs/guides/troubleshooting) |
+| Project | [Contributing](https://ccsafetynet.com/docs/contributing) · [Security Policy](https://ccsafetynet.com/docs/security) |
 
 ## Development
 
 See [CONTRIBUTING.md](CONTRIBUTING.md) for details on how to contribute to this project.
 
+Generated distribution ownership is intentionally narrow. Only `dist/index.js`,
+`dist/index.d.ts`, `dist/bin/cc-safety-net.js`, and `dist/pi/index.js` are tracked. Run
+`bun run verify:build`, `bun run verify:package`, and `bun run verify:repository-plugin` when
+changing packaging, integrations, or release automation.
+
 ## License
 
 MIT