docs: document gate log subcommand

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: GaaraZhu

CHANGELOG.md

@@ -1,5 +1,9 @@
 ## [Unreleased]
 
+### 🚀 Features
+
+- Add `gate log` — a live feed of interception events (matched, redacted, passed through, rejected, blocked) for confirming gate is actually working. Counts and labels only, never command lines, SQL text, or PII values. Prints recorded events and exits by default; `-f`/`--follow` keeps watching, like `docker logs -f`
+
 ### 🐛 Bug Fixes
 
 - Fix AU/NZ international phone numbers not matched when `+` is separated from digits by whitespace (e.g. `+ 640220831619`, `+6 40220831619`) — values are now whitespace-stripped before regex matching

README.md

@@ -245,6 +245,7 @@ The ones you'll use most:
 | `gate scan` | PII risk report across your schema |
 | `gate allowlist add/remove/list` | Manage column-name false positives |
 | `gate retro` | Protection retrospective — total queries & PII fields redacted, breakdown by tool and PII type/category, hit rate with visual progress bar, and low-confidence warnings with allowlist hints |
+| `gate log [-f]` | Live feed of interception events — see what gate matched, redacted, or blocked in real time. Counts and labels only, never raw command lines or PII |
 | `gate enable` / `gate disable` | Toggle redaction without uninstalling |
 | `gate validate` | Check config for errors before the first session |
 | `gate protect` / `gate unprotect` *(Unix only)* | Transfer config ownership to root |

docs/commands.md

@@ -13,6 +13,7 @@ Full reference for every `gate` subcommand. Use `gate --help` and `gate <subcomm
 | `gate allowlist remove <col> [col...]` | Remove column names from the allowlist. |
 | `gate allowlist list` | Show the current allowlist. |
 | `gate retro` | Protection retrospective (a.k.a. stats / audit / report). Prints how many queries gate protected and how many PII fields it redacted, with a top-types breakdown. Reads from the on-disk stats log; disable collection with `stats.enabled: false` in config. |
+| `gate log [-f\|--follow] [--json] [--tool <name>] [--path bash\|mcp\|stdin]` | Live feed of interception events — which commands gate matched, redacted, passed through, rejected, or blocked. Counts and labels only, never command lines, SQL text, or PII values. Prints recorded events and exits by default; `-f`/`--follow` keeps watching for new ones, like `docker logs -f`. `--tool`/`--path` filter the feed; `--json` emits raw event lines. |
 | `gate enable` | Enable PII redaction (sets `enabled: true` in config). |
 | `gate disable` | Disable PII redaction (sets `enabled: false` in config). |
 | `gate validate` | Check config for errors and warnings. |