securenow 8.24.0 → 8.25.1

package/SKILL-CLI.md

@@ -2,812 +2,442 @@
 
 > **Node.js security:** Use a supported, patched runtime: Node.js 22.23.4+, 24.22.1+, or 26.12.1+ on its respective release line. Earlier patches are affected by [CVE-2026-111497](https://nodejs.org/en/blog/vulnerability/october-2026-security-releases). Upgrading the SecureNow package does not patch Node.js; upgrade the runtime and restart every application process.
 
-Use the `securenow` CLI to perform security DevOps from the terminal: manage apps, investigate threats, control the firewall, analyze traces, handle false positives, and run instrumented Node.js processes. Every command supports `--json` for machine-readable output.
+The `securenow` CLI runs SecureNow from the terminal: set up an app, see what is attacking it, investigate an address, block, rate-limit, challenge, revoke sessions, write and test detection rules, work the review queues, and run the MCP server for coding agents. It describes securenow 8.24.0; items marked **(8.25.0+)** need 8.25.0 or newer. Wiring the SDK into an app is covered by [SKILL-API.md](./SKILL-API.md).
 
-## Installation
+- `npx securenow help` lists every command; `npx securenow help <command>` shows its subcommands and flags. Both work offline: check a flag there before using it.
+- Most read commands take `--json` for machine-readable output and `--app <key>` / `--env <environment>` to pick the target.
+- Write commands act on production apps within about 10 seconds. Ask the person first; `--yes` (or `--force`) only skips the prompt after they agreed.
+- Never print `.securenow/*.json` files or full `snk_live_` keys.
 
-```bash
-# Install globally (recommended for CLI usage)
-npm install -g securenow
-
-# Or install per-project and use via npx
-npm install securenow@latest
-npx securenow <command>
-```
-
-**Full parity with the SDK:** every capability the `securenow` Node SDK exposes has a CLI counterpart — redaction, CIDR matching, log/span emission, firewall preload, config inspection. If you can do it in code, you can do it from the terminal.
+## Before you start
 
-**MCP parity (v8.0+):** the same package also ships a local stdio MCP server for Codex, Claude, and other MCP clients:
+### Install
 
 ```bash
-npx securenow login
-codex mcp add securenow -- npx securenow mcp
-# or
-npx -p securenow securenow-mcp
-```
-
-The MCP server reads admin/control-plane auth from `.securenow/admin.json` and SDK runtime app credentials from `.securenow/runtime.json`, with legacy `.securenow/credentials.json` still supported. Admin/global tools use admin auth; runtime-scoped read tools can use the runtime API key where its scopes allow it. Write tools require `confirm:true` plus a reason.
-
-**For agents, prefer the hosted MCP** (`https://api.securenow.ai/mcp`, OAuth sign-in, no install and always the current tools). With the local stdio server, warm the package once so the first connection doesn't time out on the download (`npx -y securenow@latest --version`), and give the client a longer connect timeout (Claude Code: `MCP_TIMEOUT=120000`).
-
-**Tool profiles** (stdio server): `securenow mcp --profile <name>` (or `SECURENOW_MCP_PROFILE=<name>`) serves only the tools one job needs, so the agent carries less context. Every profile keeps `securenow_auth_status`, `securenow_apps_list` and `securenow_apps_info`; calling a tool outside the profile returns an error naming the profile.
-
-| Profile | Tools | What's in it |
-|---|---|---|
-| `all` (default) | 112 | everything |
-| `investigator` | 58 | every read-only tool, plus forensics question/chat/confirm |
-| `detection` | 47 | `securenow_alert_rule*` (draft, create, test, run, runs, explain, versions, exclusions, request promotion…), traces, logs, forensics, IP intelligence, notifications list/get |
-| `responder` | 77 | notifications, human queue, alert reviews, blocklist, allowlist, trusted IPs, rate limits, challenges, automations, firewall, IP intelligence, plus rule get/runs/explain and traces/logs for context |
-
-```bash
-claude mcp add securenow-investigator -- npx -y securenow@latest mcp --profile investigator
-codex mcp add securenow-detection -- npx securenow mcp --profile detection
+npm install securenow@latest      # in the project; run commands with npx securenow <command>
+npm install -g securenow          # or globally: securenow <command>
+npx securenow version
 ```
 
 ### Authenticate
 
 ```bash
-securenow login             # friendly flow: admin auth + app runtime connection
-securenow admin login       # admin/control-plane CLI and MCP auth only
-securenow app connect       # app/runtime SDK connection only
-securenow admin login --token <JWT>   # headless / CI admin auth
-securenow whoami            # verify both admin auth and runtime app status
-```
-
-**Two-lane credentials (v8.0+):** admin/control-plane auth lives in `.securenow/admin.json`; SDK runtime app config and the runtime API key live in `.securenow/runtime.json`. `securenow login` can run both lanes for onboarding, but `securenow admin login` never replaces runtime app config and `securenow app connect` never replaces admin auth. Legacy combined `.securenow/credentials.json` files are still read.
-
-**Zero-config runtime flow:** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)** and **name** in `.securenow/runtime.json`. The SDK sends traces/logs to the default SecureNow ingestion gateway, which routes by app key, so no env vars or per-instance collector URLs are required for local dev or production.
-
-**Default-on security (v8.0+):** after picking or creating the app, `securenow app connect` turns on that app's firewall toggle, mints a runtime API key with `traces:write + logs:write + firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/runtime.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is needed. To add or rotate a key later without re-running app connect, use `securenow api-key create` or `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
-
-Runtime credentials resolve in order: project `.securenow/runtime.json` -> legacy project `.securenow/credentials.json` -> project named runtime credentials -> global `.securenow/runtime.json` -> legacy global credentials -> global named runtime credentials. Admin auth resolves from `admin.json` first, then legacy `credentials.json`. Runtime config is credentials-json based; environment-variable fallbacks are not supported.
-
-The **runtime API key** should live in runtime credentials as `apiKey`; it authenticates telemetry ingestion and firewall sync.
-
-For CI / Docker / production, use `securenow credentials runtime --env production` to generate a tokenless runtime file, then mount/copy it as `.securenow/credentials.json`. Since v7.7.2, mounting the generated `.securenow/credentials.production.json` filename directly also works when `credentials.json` is absent.
-
-**Environment model:** use one SecureNow app key for local, preview, staging, and production. The credentials field `config.runtime.deploymentEnvironment` separates traces/logs/firewall/forensics by environment. CLI security commands default to `production`; pass `--env local`, `--env staging`, or `--env all` only when that scope is intentional.
-
-### Integrate With Your App
-
-The CLI can also instrument any Node.js app at launch — no code changes:
-
-```bash
-# Express, Fastify, NestJS, Koa, Hapi, raw Node.js
-securenow run src/index.js
-
-# Or via the Node preload flag
-node -r securenow/register src/index.js
-```
-
-For Next.js, run the interactive scaffolding:
-
-```bash
-securenow login
-securenow init
-```
-
-This auto-detects your framework, creates the necessary `instrumentation.ts` and `next.config.js` changes, and reuses the app, instance, and runtime API key written by login or `app connect` to `.securenow/runtime.json`.
-
-### Install This Skill in Cursor
-
-Save this file as `.cursor/skills/securenow-cli/SKILL.md` in your project. Your AI agent will auto-discover it whenever you ask about CLI commands, security investigations, or firewall management.
-
-## Configuration
-
-Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-project):
-
-| File | Content |
-|------|---------|
-| `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
-| `~/.securenow/admin.json` | `token`, `email`, `expiresAt` for global admin/control-plane CLI and MCP auth |
-| `~/.securenow/runtime.json` | `apiKey`, `app`, `config` for global SDK runtime |
-| `.securenow/admin.json` | `token`, `email`, `expiresAt` for project-local admin/control-plane CLI and MCP auth |
-| `.securenow/runtime.json` | `apiKey`, `app`, `config`, `_securenow.explanations` for project-local SDK runtime |
-| `.securenow/credentials.json` | Legacy combined credentials; still read for backward compatibility |
-| `.securenow/credentials.<environment>.json` | Tokenless runtime credentials generated by `securenow credentials runtime --env <environment>`; read in a fixed order, not selected from env vars |
-
-**Credential resolution order:** runtime config resolves from project `.securenow/runtime.json` -> legacy project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `.securenow/runtime.json` -> legacy global credentials -> global named runtime credentials. Admin auth resolves from `admin.json` first, then legacy `credentials.json`. Environment-variable fallbacks are not supported.
-
-**Runtime API key resolution (v8.0+):** project `.securenow/runtime.json` -> legacy project credentials -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global runtime credentials -> legacy global credentials -> global named runtime credentials. Use `securenow app connect` for runtime setup or `securenow api-key set` to rotate a key without touching admin auth or env vars.
-
-```bash
-securenow config set apiUrl https://api.securenow.ai
-securenow config set defaultApp my-app-key
-securenow config get                     # show all
-securenow config get defaultApp          # show one
-securenow config path                    # print file paths + active auth source
+npx securenow login          # browser: admin auth + the app's runtime config (run from the project root)
+npx securenow admin login    # admin/control-plane auth only (CLI and MCP)  [--token <TOKEN>] [--global]
+npx securenow app connect    # runtime only: pick/create the app, mint the runtime API key  [--global]
+npx securenow whoami         # both lanes
+npx securenow logout         # clears admin auth; the runtime config stays  [--global]
 ```
 
-Legacy CLI overrides still exist for operator automation, but runtime SDK config should stay in the credentials file.
-
-## Global Flags
-
-| Flag | Short | Effect |
-|------|-------|--------|
-| `--json` | `-j` | JSON output (pipe-friendly) |
-| `--help` | | Show help for any command |
-| `--verbose` | `-v` | Verbose output |
-| `--force` | `-f` | Skip confirmations |
-| `--yes` | `-y` | Auto-confirm prompts |
-
-SecureNow-specific environment overrides are not supported; use `.securenow/runtime.json`, `.securenow/admin.json`, or `securenow config set`.
-
----
-
-## Command Reference
-
-### Run — Instrument Any Node.js App
-
-```bash
-securenow run <script>                       # auto-detect CJS/ESM, inject OTel preload
-securenow run --watch src/index.js           # pass Node flags through
-securenow run --inspect src/server.js --port 3000
-securenow run --firewall-only app.js         # preload firewall only (no tracing overhead)
-securenow src/index.js                       # shorthand — auto-detected as "run"
-```
+Two lanes, two files: `.securenow/admin.json` (admin token for the CLI and MCP) and `.securenow/runtime.json` (app key, runtime API key `snk_live_...`, SDK config). `--global` writes to `~/.securenow/` instead of the project. Both files are secrets; the CLI adds them to `.gitignore` without ignoring the whole `.securenow/` folder. Never open an auth URL yourself: the CLI generates the callback.
 
-Spawns `node --require securenow/register [--import otel/hook.mjs] <script>`. ESM detection uses nearest `package.json` `"type"` field or `.mjs`/`.cjs` extension. With `--firewall-only`, uses `securenow/firewall-only` instead (credentials-file firewall, no OpenTelemetry).
+### Pick the app and the environment
 
-### Authentication
+- One app key serves every environment. Traces, logs, firewall rules, forensics and alerts are scoped by `config.runtime.deploymentEnvironment` (`production`, `staging`, `preview`, `local`...).
+- CLI security commands default to `production`. `npx securenow init` writes `local` for a development machine, so use `--env local` (or `--env all` where accepted) to see local traffic.
+- `--app <key>` targets another app. `npx securenow apps default <key>` (or `npx securenow config set defaultApp <key>`) sets the default.
 
-```bash
-securenow login                   # friendly flow: admin auth + app runtime connection
-securenow admin login             # admin/control-plane CLI and MCP auth only
-securenow admin login --token <JWT> # headless / CI admin auth
-securenow app connect             # app/runtime SDK connection only
-securenow logout                  # clear admin auth; runtime app config remains
-securenow logout --global         # clear global admin auth only
-securenow whoami                  # show admin auth and runtime app status separately
-```
+## Tasks
 
-### Applications
+### Set up SecureNow in a project
 
 ```bash
-securenow apps                               # list all apps (default subcommand)
-securenow apps list                          # same as above
-securenow apps create <name> [--hosts h1,h2] [--instance <id>]   # interactive instance picker
-securenow apps info <id>                     # show app details
-securenow apps delete <id> [--force]         # delete an app
-securenow apps default <app-key>             # set default app for all commands
-securenow apps discover [appId] [--domain example.com]  # discover subdomains, add as apps
-securenow apps scan [--yes]                  # scan all app domains for new subdomains
+npm install securenow@latest
+npx securenow login
+npx securenow init            # [--env local] [--key snk_live_...] [--ts|--js] [--src|--root] [--force]
+npx securenow doctor && npx securenow test-span
 ```
 
-### API Key Management
+`init` detects the framework, fills `.securenow/runtime.json`, writes the Next.js instrumentation file and config, and prints the start-script change for plain Node. The full wiring per framework is in SKILL-API.md.
 
-Manage the runtime API key stored in runtime credentials. Since v8.0 the app runtime flow writes app-scoped `snk_live_...` keys to `.securenow/runtime.json` by default, so no env var is required for local dev.
+### Production credentials
 
 ```bash
-securenow api-key create --name "CLI runtime" # mint + save a current-app runtime key
-securenow api-key create --app <key-or-id>    # mint + save a runtime key scoped to another app
-securenow api-key set snk_live_xxxxxxxxxx    # save to project ./.securenow/ (default)
-securenow api-key set snk_live_xxx --global  # save to ~/.securenow/ instead
-securenow api-key show                       # print the masked current key + its source
-securenow api-key clear                      # remove just the API key (keeps session/app)
-securenow api-key clear --global             # same, but from the global file
-securenow credentials runtime --env production # write .securenow/credentials.production.json for production secret-file deploys
+npx securenow credentials runtime --env production                 # writes .securenow/credentials.production.json
+npx securenow credentials runtime --env production --format env    # prints SECURENOW_CREDENTIALS=<base64>
+npx securenow credentials runtime --env staging --out deploy/securenow.json
+npx securenow credentials runtime --env production --stdout        # JSON to stdout
 ```
 
-The key must start with `snk_live_`. `securenow app connect` writes the key automatically; use `api-key create` when you have admin auth but no runtime key yet, or `api-key set` when you already have a key from the dashboard. `api-key create` defaults to the current app in `.securenow/runtime.json`, resolves that app UUID to the server app id, creates a one-app `runtime_app` key with `traces:write`, `logs:write`, `firewall:read`, `blocklist:read`, and `allowlist:read`, then stores the one-time plaintext key as `apiKey`.
+The file carries the app key, the runtime API key and the SDK config, never the admin token. Mount it as `<app-root>/.securenow/credentials.json`, or store the `--format env` line as a secret environment variable (Vercel, Railway, Render, Heroku, Fly, Kubernetes). Both contain the runtime API key.
 
-### Init — Project Setup
+Runtime key only:
 
 ```bash
-securenow init [--env local] [--key <API_KEY>]
+npx securenow api-key create --name "CLI runtime"     # mint and save a key for the current app  [--app <key-or-id>] [--global]
+npx securenow api-key set snk_live_...                # save a key you already have  [--global]
+npx securenow api-key show                            # masked key and its source
+npx securenow api-key clear                           # remove the key only  [--global]
 ```
 
-Auto-detects framework (Next.js, Nuxt, Express, Fastify, Koa, Hapi, Node) from `package.json`. Then:
-- **Credentials**: ensures `.securenow/runtime.json` exists with secure defaults and explanations
-- **Next.js**: creates `instrumentation.ts/js` with `securenow/nextjs` + `securenow/nextjs-auto-capture`, and adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when the config can be patched safely
-- **Existing Next.js files**: prints a Codex/Claude-ready merge prompt when instrumentation or config already exists or is too custom to safely patch
-- **Nuxt**: tells you to add `securenow/nuxt` to modules
-- **Node/Express/etc.**: suggests adding `-r securenow/register` to start script
-- Reuses `.securenow/runtime.json` written by login/app connect; production should mount/copy the tokenless runtime file generated by `securenow credentials runtime --env production`
-
-### Dashboard & Status
+### Today's overview
 
 ```bash
-securenow today [--since 24h|7d] [--attackers 20] [--json]  # the Overview: what happened, what SecureNow did, what needs you
-securenow attacker <ip> [--json]             # why an address was flagged: verdict, signals, traffic vs normal, detections, timeline
-securenow status [--app <key>] [--env local|production|all] # dashboard overview
-securenow analytics [--app <key>]            # response analytics
+npx securenow today                     # what happened, what SecureNow did, what needs you  [--since 24h|7d] [--attackers 8]
+npx securenow status --env production   # apps, protection, unread alerts  [--app <key>] [--env local|production|all]
+npx securenow analytics --app <key>     # response-code analytics
+npx securenow logs errors --since 1h    # what is failing: errors grouped by message  [--warn] [--limit 20]
 ```
 
-`today` is the dashboard's home in the terminal:
-- whether each app is covered (data flowing, firewall on, detection monitoring or blocking);
-- attack requests, attackers, what the firewall stopped and what got through;
-- the decisions waiting for you, the top attackers, and what SecureNow did (the agent's actions, automatic blocks,
-  closed probes).
-
-`attacker <ip>` explains one address:
-- the verdict and score with the signals behind them, and its reputation;
-- where it is blocked;
-- its last 3 days of traffic against your apps' normal (error rate, share of traffic, scanner probes, attack
-  payloads answered 2xx);
-- the detections it triggered and what happened to each, a timeline, and questions to paste into
-  `securenow forensics chat`.
-
-MCP: `securenow_overview` and `securenow_attacker` (read).
-
----
+`today` is the dashboard's Overview: whether each app is covered (data flowing, firewall on, detection monitoring or blocking), attack requests and attackers, what the firewall stopped and what got through, decisions waiting, top attackers, and what SecureNow did. MCP: `securenow_overview`.
 
-### Traces
+### Investigate an IP
 
 ```bash
-securenow traces [--app <key>] [--env production] [--limit N] [--start ISO] [--end ISO]
-securenow traces list --app my-app --env production --limit 50
-securenow traces show <traceId> --env production      # full trace detail with spans
-securenow traces analyze <traceId> --env production   # AI-powered trace analysis
+npx securenow attacker 203.0.113.9                    # why it was flagged: verdict, signals, traffic vs normal, detections, timeline
+npx securenow ip 203.0.113.9                          # geo, ASN, reputation, verdict
+npx securenow ip traces 203.0.113.9 --env production  # its requests
+npx securenow traces show <traceId> --env production  # one request: spans, headers, body (redacted)
+npx securenow traces analyze <traceId>                # AI analysis of a trace
+npx securenow firewall hits --ip 203.0.113.9 --since 24h   # what the firewall did to it
+npx securenow agent verify 203.0.113.9                # the double-check the agent runs before acting (alert moment + 3 days)
+npx securenow forensics chat --app <key> "what did 203.0.113.9 do in the last 24 hours?"
 ```
 
-### Logs
-
-```bash
-securenow logs [--app <key>] [--env production] [--limit N] [--minutes M] [--level error|warn|info]
-securenow logs list --app my-app --env production --minutes 30 --level error
-securenow logs trace <traceId> --env production       # logs correlated to a specific trace
-securenow logs errors --app my-app --since 6h [--warn]  # what is failing: error lines grouped by message (ids/numbers normalized), counts, first/last seen, sample traces
-```
-
-For "what's broken right now?", start with `logs errors` (MCP `securenow_logs_errors`): one call returns the distinct failures, not hundreds of raw lines.
-
-### Notifications
-
-```bash
-securenow notifications [--limit N] [--page P]
-securenow notifications list --limit 20
-securenow notifications read <id>            # mark one as read
-securenow notifications read-all             # mark all as read
-securenow notifications unread               # unread count
-```
+`forensics chat` runs discovery queries, shows its SQL and ends each answer with findings; continue with `--conversation <id> "<follow-up>"`. `npx securenow forensics "<question>"` answers one question without memory. Trust the result rows over the summary. MCP: `securenow_attacker`, `securenow_ip_lookup`, `securenow_ip_traces`, `securenow_forensics_chat`.
 
-### Two review queues
+### Triage notifications
 
-SecureNow decides most things alone (instant blocks, automations, IP investigations, self-pausing
-rules). What it won't decide alone waits in two queues. Work **Alert Review** first: one rule fix
-closes every run it caused and the Requires Human rows that came from the same noise.
+SecureNow decides most things alone (instant blocks, automations, IP investigations, rules that pause themselves). What it won't decide waits in two queues; work **Alert Review** first, because one rule fix closes every run it caused.
 
 | Queue | Question | Decisions | CLI |
 |---|---|---|---|
-| Alert Review | "Is this rule right?" A rule fired far too wide, or on an IP treated as your own infrastructure; it usually pauses itself | tune the rule, keep it on, close/dismiss with a reason (never blocks or unblocks) | `securenow review` |
-| Requires Human | "What do we do about this IP or plan?" An investigated IP with a verdict SecureNow won't act on alone, or a proposed plan | block, false positive, close without blocking, approve/reject a plan | `securenow human` |
-
-### Alert Review — is this rule right?
+| Alert Review | "Is this rule right?" A rule fired far too wide, or on your own infrastructure; it usually paused itself | tune the rule, keep it on, close or dismiss with a reason (never blocks or unblocks) | `securenow review` |
+| Requires Human | "What do we do about this IP or plan?" An investigated IP with a verdict SecureNow won't act on alone, or a proposed plan | block, false positive, close without blocking, approve or reject a plan | `securenow human` |
 
 ```bash
-securenow review                             # open runs grouped by root cause (rule + route + evidence shape)
-securenow review list --search lab-auth      # one app (name or key), rule, route or IP
-securenow review show 1                      # group 1: rule, route, IPs, context, its runs
-securenow review show <notificationId>       # one run
-securenow review keep <notificationId> --reason "Correct detection" --yes     # turn the rule back on, stop it auto-pausing, close the run
-securenow review close <notificationId> --outcome rule_tuning --reason "..." --yes
-securenow review dismiss <notificationId> --reason "Not worth acting on" --yes
-securenow review group 1 --outcome rule_tuning --reason "Guard added in v4" --preview   # what would close
-securenow review group 1 --outcome rule_tuning --reason "Guard added in v4" --yes       # close the whole group
-```
-
-Outcomes: `rule_tuning`, `false_positive`, `clean`, `deferred`, `new_alert_rule`, `rate_limited`,
-`ambiguous`, `skipped`, `other`. Closing writes a decision report on the alert and changes no
-enforcement. Tune the rule first (`securenow alerts rules change <id> "..."`), then close its group.
-A mixed group (rows disagree on verdict or sender) needs `--allow-mixed` after reviewing every row.
-
-MCP parity: `securenow_alert_review_runs_list`, `securenow_alert_review_run_get`,
-`securenow_alert_review_run_keep_alive`, `securenow_alert_review_run_resolve`,
-`securenow_alert_review_run_dismiss`, `securenow_alert_review_run_apply_group_decision`; prompt `work_alert_review`.
-
-### Requires Human — what do we do about this IP or plan?
+npx securenow notifications list --limit 20            # [--search <rule or IP>] [--severity critical|high|medium|low] [--page N]
+npx securenow notifications unread
+npx securenow notifications read <id>                  # or: read-all
 
-Use this for the same work shown in **Requires Human**: AI has already grouped alerts, fetched traces, built a report, and left a final Block IP or False Positive decision.
+npx securenow review                                   # open runs grouped by root cause
+npx securenow review show 1                            # a group (row number or arc_ key) or one run (notification id)
+npx securenow alerts rules change <rule-id> "ignore /healthz and raise the threshold to 20"   # fix the rule first
+npx securenow review group 1 --outcome rule_tuning --reason "Guard added" --preview
+npx securenow review group 1 --outcome rule_tuning --reason "Guard added" --yes
+npx securenow review keep <notificationId> --reason "Correct detection" --yes
+npx securenow review dismiss <notificationId> --reason "Not worth acting on" --yes
 
-```bash
-securenow human                              # list human decisions, most urgent first
-securenow human list --limit 20
-securenow human show 1                       # inspect row 1 with AI report, investigation steps, proofs, trace links
-securenow human block 1 --yes --reason "AI evidence confirmed malicious"
-securenow human fp 1 --yes --reason "Scoped false positive after evidence review"
-securenow human close 1 --outcome deferred --reason "Scanner, nothing reachable; not worth a block" --yes   # leaves the queue, nothing blocked
-securenow human action 1 --status rejected --yes --reason "Tuning guard is too broad"
-securenow human prompt 1                     # print a Codex/Claude MCP prompt for this row
-securenow human work --limit 10              # list queue + print MCP runbook for deep queue work
+npx securenow human                                    # decisions waiting, most urgent first
+npx securenow human show 1                             # AI report, proofs, investigation steps, trace links
+npx securenow human block 1 --reason "Confirmed SQL injection with 2xx answers" --yes
+npx securenow human fp 1 --reason "Partner webhook, scoped to /api/hooks" --yes
+npx securenow human close 1 --outcome deferred --reason "Scanner, nothing reachable" --yes
+npx securenow human action 1 --status rejected --reason "Exclusion too broad" --yes
 ```
 
-MCP parity:
-
-- `securenow_human_actions_list`
-- `securenow_notifications_get`
-- `securenow_human_action_report`
-- `securenow_human_action_block`
-- `securenow_human_action_false_positive`
-- `securenow_human_action_close_no_write`
-- `securenow_human_case_action_update`
-- prompts: `investigate_human_action_row`, `work_human_actions`
-
-`human report` only adds a note: the row stays. `human close` removes it without enforcement.
-Approving a `tune_rule` or `create_exclusion` plan with `human action` records the decision and
-changes nothing: change the rule first, then approve. Only `approve_block` blocks.
-
-### The autonomous agent works the queues for you
+Review outcomes: `rule_tuning`, `false_positive`, `clean`, `deferred`, `new_alert_rule`, `rate_limited`, `ambiguous`, `skipped`, `other`. A group whose rows disagree needs `--allow-mixed` after reviewing every row. `human report` only adds a note (the row stays); `human close` removes the row without enforcement; approving a `tune_rule` or `create_exclusion` plan with `human action` only records the decision (change the rule first); only `approve_block` blocks.
 
-SecureNow runs an agent per organization that works both queues on its own: every few minutes when
-there is work, or on demand. Before any decision on an IP it runs the same double-check as
-`agent verify`: what that IP did around the alert and over the last 3 days on every app, its
-sign-ins, the trust lists and reputation. Its blocks only cover the alert's apps and expire. What it
-may do is set per kind of action: `off`, `shadow` (record what it would do, change nothing),
-`suggest` (leave the recommendation on the row for a person) or `act`.
+Each notification carries an `ipInvestigations` array; act only on IPs whose own `status` is `open`:
 
-```bash
-securenow agent                              # status: on/off, mode per action, what it did, agreement with people
-securenow agent on                           # or off (off also revokes a run in progress)
-securenow agent mode all shadow              # start here: it records, you compare with your own decisions
-securenow agent mode block_ip act --yes      # then hand over one kind of action at a time
-securenow agent activity --mode applied      # every decision with its evidence
-securenow agent undo <id> --yes              # unblock / reopen the row / roll the rule back
-securenow agent runs                         # patrols: status, tool calls, cost, summary
-securenow agent run                          # patrol now
-securenow agent verify 203.0.113.9           # the double-check, for any IP
-```
+| Status | Meaning | Action |
+|---|---|---|
+| `open` | No determination yet | Investigate, then decide |
+| `false_positive` | Dismissed by an exclusion, a verified bot or a trusted IP | Skip |
+| `blocked` | Already on the blocklist | Skip |
+| `clean` | Cleared as benign | Skip |
 
-Action types: `close_row`, `false_positive`, `block_ip`, `review_close`, `keep_rule`, `rule_change`,
-`case_action`. The API enforces all of it, whatever the model decides: the agent's token only reaches
-the queue, verification and rule-tuning routes (never trust lists, the allowlist, unblocking,
-automations or prod promotion), it can't block without a verification that allows it, it only edits
-test-mode rules (prod rules get a proposal a person applies), and budgets cap each run and day. An
-action type that people keep undoing drops back to shadow by itself.
+Prefer `metadata.matchedSubdetectors` over guessing which part of a rule fired from the title.
 
-### Run the queues with your own agent
+**False-positive exclusions** keep known-safe traffic from alerting. Keep them as narrow as the evidence (app, rule, path, method, status, user agent, body shape):
 
 ```bash
-claude "$(npx -y securenow@latest agent prompt patrol)"                     # read-only pass: a plan
-claude -p "$(npx -y securenow@latest agent prompt patrol --search my-app --confirm-writes)"   --allowedTools "mcp__securenow"                                           # unattended, acts on one app
+npx securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook" --context '{"method":"POST","path":"/api/stripe/webhook"}'
+npx securenow fp dry-run --conditions '[{"field":"path","operator":"starts_with","value":"/api/stripe/webhook"}]'   # last 3 days
+npx securenow fp create --conditions '[...]' --match-mode all --rule-scope any_rule --reason "Stripe webhook"
+npx securenow fp create --path /api/events --method POST --path-safe standard --ua-safe standard --headers-safe standard --query-keys page,limit --reason "Event webhook"
+npx securenow fp mark <notification-id> <ip> --rule-scope this_rule --reason "Known partner IP"
+npx securenow alerts rules exclusions <rule-id> add --conditions '[...]' --reason "..."     # one rule only
+npx securenow fp list | show <id> | edit <id> --active false | delete <id> --yes
+npx securenow fp test-body @request.json --conditions '[...]'
 ```
 
-`soc_patrol` works Alert Review then Requires Human, up to 10 groups and 10 rows per pass
-(`--max-alert-review-groups`, `--max-human-rows`). The API key's scopes are the hard limit: a
-Read Only key cannot change anything; acting needs `notifications:write`, `alerts:write` and
-`rate_limits:write`. Setup for Claude Code, Codex and Cursor: dashboard → Run With Your Agent.
+Conditions are `{"field", "operator", "value"}`. Fields: `path`, `method`, `user_agent`, `status_code`, `request_body`, `request_headers`. Operators: `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `regex`, `in`, `not_in`, and structural checks (`path_safe_values`, `query_safe_values`, `query_has_only_keys`, `ua_safe_values`, `headers_safe_values`, `headers_has_only_keys`, `body_safe_values`, `body_is_format`, `body_has_only_fields`, `json_has_only_keys`, `json_safe_values`, `json_valid`, `json_max_depth`, `json_schema_match`); prefer the `*_safe_values` checks, which only excuse a request whose value is clean. Match modes: `all`, `any`. Scopes: `this_rule` (only through `fp mark`), `specific_rules` (with `--target-rules id1,id2`), `all_existing`, `any_rule` (the `fp create` default). Presets for `--*-safe`: `standard`, `strict`.
 
-Write tools still require `confirm:true` plus a reason. False positives should stay restrictive to the app, alert rule, path, method/status, user-agent, body pattern, or other exact evidence the AI report supports. Notification IP investigations can include `metadata.matchedSubdetectors`; prefer that exact field over inferring which subdetector fired from the title or sample body.
-
-### Alerts
-
-Before authoring any alert SQL, load the contract shipped by the installed package and compare
-it with fields actually observed for the selected application:
-
-```bash
-securenow telemetry schema --json
-securenow telemetry schema logs --json
-securenow telemetry schema traces --json
-securenow telemetry schema events --json
-securenow telemetry fields --app <key> --env production --since 24h --source all --json
-```
+MCP: `securenow_alert_review_runs_list`, `securenow_alert_review_run_get`, `securenow_alert_review_run_keep_alive`, `securenow_alert_review_run_resolve`, `securenow_alert_review_run_dismiss`, `securenow_alert_review_run_apply_group_decision`, `securenow_human_actions_list`, `securenow_human_action_report`, `securenow_human_action_block`, `securenow_human_action_false_positive`, `securenow_human_action_close_no_write`, `securenow_human_case_action_update`; prompts `work_alert_review`, `work_human_actions`, `investigate_human_action_row`.
 
-`telemetry schema` is offline and versioned with the SDK. `telemetry fields` requires admin
-auth and telemetry access; it returns names, map scopes, data types, occurrence counts, and
-custom event types, but never customer attribute values. Absence means "not observed in this
-window," not "unsupported." Use only documented fields, and label a rule `READY` only when
-its fields were observed and `alerts rules validate` succeeds. Otherwise label it
-`NEEDS_INSTRUMENTATION`, `NEEDS_BASELINE`, or `NEEDS_CUSTOMER_DECISION` as appropriate.
+### Block an IP
 
 ```bash
-securenow alerts                             # list alert rules (default)
-securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
-securenow alerts rules from-text \           # describe a detection in English; checked draft, then create (test mode)
-  "one IP failing 10 sign-ins in 5 minutes" \
-  --app <key> [--env production]             #   picks instant or periodic; --instant/--periodic, --draft-only, --yes
-securenow alerts rules create --name "Secrets probe" --apps <key> \
-  --conditions '[{"field":"path","operator":"contains","value":"/.env"}]'   # an instant rule, no SQL
-securenow alerts rules validate \            # dry-run a candidate query BEFORE creating any rule
-  --sql @rule.sql --app <key>                #   no rule id needed — auto-hosts on an existing (system) rule
-securenow alerts rules create \              # create a custom detection rule from inline SQL
-  --name "Auth: magic-link brute force" \
-  --sql @rule.sql \                          #   SQL, @file, or - for stdin; scope apps with __USER_APP_KEYS__
-  --apps key1,key2 \                         #   or --applications-all
-  --severity high --schedule "*/15 * * * *" \
-  --nlp "single IP flooding /api/auth/signin or /api/auth/callback"
-                                             #   create auto dry-runs + rolls back (deletes) on query failure; --no-validate to skip
-securenow alerts rules show <id>            # one rule; JSON: --json
-securenow alerts rules set-sql <id> --sql @new.sql   # replace a CUSTOM rule's SQL in place (alias: update <id> --sql)
-securenow alerts rules delete <id> --yes    # delete a custom rule (system rules: disable instead)
-securenow alerts rules update <id> --applications-all   # all current & future apps
-securenow alerts rules update <id> --apps key1,key2     # explicit app keys only
-securenow alerts rules test <id> --wait       # dry-run an existing rule's query (default; --mode live inserts 6 synthetic attack requests)
-securenow alerts rules change <id> "raise the threshold to 20"   # rewrite a rule from English: checked, shown before/after, applied as a new version
-securenow alerts rules runs <id> [--since 1h] # what each run saw and why it did or didn't notify (+ next scheduled run)
-securenow alerts rules run <id>               # run a periodic rule now and print the run (--no-wait to just queue it)
-securenow alerts rules why <id> --ip <ip> [--since 1h]   # why the rule did or didn't alert on one address: verdict + findings
-securenow alerts rules quality <id>           # was the rule right to fire? 14-day precision, alerts labeled wrong/unclear and why, what detection learning changed
-securenow alerts rules dry-run-query <id> --sql @candidate.sql --app <key> --wait   # candidate test against a specific host rule
-securenow alerts rules tune-query <id> --sql @candidate.sql --reason "Preserve exploit detector, remove benign broad match" --apply-globally --yes
-securenow alerts rules exclusions <id> list              # embedded rule exclusions
-securenow alerts channels                    # list alert channels (Slack, email, etc.)
-securenow alerts history [--limit N]         # past triggered alerts
+npx securenow blocklist add 203.0.113.42 --env production --duration 24h --reason "credential stuffing"
+npx securenow blocklist add 203.0.113.0/24 --route /admin --mode prefix --method ALL --reason "admin probing"
+npx securenow firewall test-ip 203.0.113.42 --path /admin --method GET --env production   # would it be blocked?
+npx securenow blocklist list --env production         # [--status active|removed] [--search 203.0.] [--approval-status pending]
+npx securenow blocklist unblock <id> --reason "false alarm after review"   # stops enforcement, keeps the history
+npx securenow blocklist approve <pending-id> --yes    # or: reject <pending-id> (records a scoped no-block decision)
+npx securenow blocklist stats
 ```
 
-**Authoring loop that won't strand a broken rule:** `validate --sql @rule.sql --app <key>`
-(dry-run before anything exists) → `create …` (which itself dry-runs and auto-rolls-back on
-failure) → if you later need to fix it, `set-sql <id> --sql @rule.sql` (custom rules) or
-`delete <id>`. Detection `.sql` files may start with `--`/`/* */` comments. Custom-rule SQL is
-editable; **system**-rule SQL changes go through `tune-query … --apply-globally`. Pick the
-right tenant-scope column per table: logs (`signoz_logs.distributed_logs_v2`) use
-`resources_string['service.name'] IN (__USER_APP_KEYS__)`, traces
-(`signoz_traces.distributed_signoz_index_v3`) use `` `resource_string_service$$name` IN (__USER_APP_KEYS__) ``.
-
-`alerts rules create` flags: `--name` (required); one of `--sql <sql|@file|->` or `--query-mapping-id <id>`; one of `--apps k1,k2` or `--applications-all`; optional `--description`, `--nlp` (plain-English intent), `--category`, `--severity critical|high|medium|low`, `--schedule <cron>` (default `*/15 * * * *`), `--throttle-minutes N` / `--no-throttle`, `--execution-mode scheduled|instant|hybrid`, `--channel id1,id2` (defaults to your in-app SecureNow channel). Detection SQL must scope app keys via the `__USER_APP_KEYS__` placeholder and select an `ip` column for per-IP aggregation/remediation: create and set-sql refuse SQL with no ip column (it would never notify) unless `--allow-no-ip`. A new periodic rule runs once right away. Requires `alerts:write`.
-
-**Throttle = one alert per rule AND address** (8.17): an address alerted on within the window (default 15 min) is left out of the next runs' notifications, and other addresses still alert. Alert storms keep one alert per rule per window.
-
-**When a rule stays quiet,** don't guess: `alerts rules runs <id>` shows every run's outcome — `notified`, `no_rows`, `throttled`, `suppressed_blocked` (already blocked, often by another rule's instant block), `suppressed_trusted`, `no_ip` (rows without an ip column), `storm`, `auto_resolved` (dismissed by an exclusion, trusted IP or verified bot), `skipped`, `error` — and which addresses were left out and why. `alerts rules why <id> --ip <ip>` ends in a verdict such as "Detected at 15:06:31 but not notified: 203.0.113.50 was already blocked by instant rule X". `--yes` on `from-text` refuses to create a rule whose check matches your data right now (it would alert at once, usually a bad baseline); review the rows, then `--yes --force` if they are a real attack.
-
-MCP parity for quiet rules: `securenow_alert_rule_runs` (run history), `securenow_alert_rule_run_now` (write, confirm) and `securenow_alert_rule_explain` (`ip`, `since`: verdict + findings).
-
-**Agents don't promote rules; they ask.** When a test-mode rule has proved itself, an agent runs `securenow alerts rules request-promotion <id> --reason "..." --evidence "..."` (MCP `securenow_alert_rule_request_promotion`). A person sees it on the rules page or with `securenow human promotions` and runs `securenow human approve-promotion <request-id> --yes` (the rule goes to prod, recorded as a rule version naming the approver) or `deny-promotion <request-id> --reason "..."`. API keys and MCP tokens can ask but not decide.
-
-MCP parity for noisy alert-rule reviews:
-
-- `securenow_alert_rule_get`
-- `securenow_alert_rule_candidate_test` dry-runs a full candidate SQL query without saving it.
-- `securenow_alert_rule_test_result` polls the dry-run.
-- `securenow_alert_rule_query_update` updates the shared public query mapping behind a system rule for all customer copies. It is admin-only, requires `confirm:true`, `applyGlobally:true`, `reason`, and SQL that keeps `__USER_APP_KEYS__` tenant scoping.
-- `securenow_alert_rule_instant_update` patches Instant rule conditions/config with stale-write guards. Fetch the rule first, pass `expectedRuleVersion` plus `expectedCurrentInstantHash`, use operations such as `remove_condition` / `add_condition` / `update_condition`, and set `applyGlobally:true` for system rules. The API runs seeded before/after checks and returns benign samples removed plus attack samples still matching. If global tuning is denied, it returns a structured admin handoff with the exact patch and missing permission.
-- `securenow_alert_rule_exclusion_add` remains the last-resort customer-specific path; it supports restrictive conditions plus `matchMode` and should not be used to hide a generic system-rule bug.
-
-For system-rule tuning, dry-run the candidate SQL first for scheduled rules, or use `dryRun:true` on `securenow_alert_rule_instant_update` for Instant rules. Save only when the guard preserves attack detection. Good guards add exact exploit tokens, dangerous schemes, matched subdetectors, sensitive path/status evidence, malicious user agents, or repeat thresholds; bad guards simply suppress a noisy path.
+`--route` (aliases `--path`, `--pattern`) with `--mode prefix|exact|regex` and `--method` makes a scoped block; without them the block is global. `blocklist remove` is an alias of `unblock`. Running apps enforce it within about 10 seconds. In the app (layer 1), ranges are IPv4 CIDRs and IPv6 is matched by exact address.
 
----
-
-### IP Intelligence
-
-```bash
-securenow ip <ip-address>                    # lookup (geo, ASN, threat score, reputation)
-securenow ip lookup <ip-address>             # same as above
-securenow ip traces <ip-address> --env production # traces originating from this IP
-```
-
-### Forensics — Natural Language Security Queries
+**Allowlist** is deny-by-default: once any active entry exists for an app and environment, only listed IPs get through. Use it only to lock an app to known IPs, with the person's approval. **Trusted IPs** are the safe way to mark known infrastructure (monitors, office VPN, your servers): alerts on them are suppressed and nobody is restricted.
 
 ```bash
-securenow forensics "show me all SQL injection attempts in the last 24h" --env production
-securenow forensics query "top 10 IPs by blocked requests" --app my-app --env production
-securenow forensics chat --app my-app --env production # interactive forensics chat session (with memory)
-securenow forensics chat --app my-app "which accounts had failed logins then a success?"   # one question, prints the conversation id
-securenow forensics chat --conversation <id> "what else did those IPs do?"                # follow up: the chat remembers the earlier answers
-securenow forensics conversations             # list conversations (dashboard, CLI and agent ones)
-securenow forensics conversations <id>        # show one: questions, SQL, findings, rows
-securenow forensics library                  # view saved/template queries
+npx securenow allowlist add 198.51.100.7 --app <key> --env production --label "Office" --reason "Admin app locked to office"
+npx securenow allowlist list | remove <id> | stats
+npx securenow trusted add 198.51.100.20 --label "Uptime monitor"     # [--app <key>] [--env <env>]
+npx securenow trusted list | remove <id>
 ```
 
-The chat runs discovery queries before answering, shows its SQL, and ends each answer with findings: what the result rows
-show. A follow-up sees the earlier questions, their findings, and the IPs and trace IDs in their results. MCP:
-`securenow_forensics_chat` (pass `conversationId` to continue), `securenow_forensics_conversations_list`,
-`securenow_forensics_conversation_get`. `securenow forensics "<q>"` and `securenow_forensics_query` answer one question
-with no memory.
+Default automations block by risk score (95+ for 7 days, 90–94 for 72 hours, 85–89 for 24 hours): `npx securenow automation list`, `automation defaults --yes`, `automation show <id>`, `automation dry-run <id>`, `automation execute <id> --yes`, `automation create|update|delete`.
 
----
+MCP: `securenow_blocklist_add`, `securenow_blocklist_unblock`, `securenow_firewall_test_ip`, `securenow_allowlist_*`, `securenow_trusted_*`.
 
-### Firewall
+### Rate-limit a route
 
 ```bash
-securenow firewall                           # show status (default)
-securenow firewall status --app <key> --env production   # app/env toggle, sync time, blocked count
-securenow firewall test-ip <ip> --app <key> --env local  # check if IP would be blocked
+npx securenow ratelimit add --route /api/login --method POST --limit 5 --window 1m --env production --reason "login brute force"
+npx securenow ratelimit add --route /api/ --limit 100 --window 1m --header x-api-key        # per API key value
+npx securenow ratelimit add --route /app --limit 300 --window 1m --cookie session           # per session cookie value
+npx securenow ratelimit add --route /api/export --limit 50 --window 1h --key-by global      # one bucket for everyone
+npx securenow ratelimit add 203.0.113.42 --limit 30 --window 1m --duration 24h              # one IP or CIDR
+npx securenow ratelimit parse "5 per minute per IP on POST /api/login for 2h"               # draft only
+npx securenow ratelimit from-text "5 per minute per IP on POST /api/login for 2h" --yes     # create
+npx securenow ratelimit test 203.0.113.42 --path /api/login --method POST --env production
+npx securenow ratelimit list | show <id> | enable <id> | disable <id> | remove <id> --reason "..."
 ```
 
-**Zero-config setup:** running `securenow app connect` enables the selected app's firewall toggle, auto-mints a runtime API key (scoped `traces:write + logs:write + firewall:read + blocklist:read + allowlist:read`), and writes it to `.securenow/runtime.json` after the app is selected. No `SECURENOW_API_KEY` env var needed. If the user already has a key, `securenow api-key set snk_live_...` achieves the same thing; if they only have admin auth, `securenow api-key create` mints and saves a fresh runtime key. See [the landing firewall page](https://securenow.ai/firewall) for an overview.
-
-### Starter Protection — Rules Every App Gets
+`--mode exact|prefix|regex` (default `prefix`), `--method` (default `ALL`), `--window 30s|1m|1h`, `--duration 24h|7d` (expiry), `--key-by ip|global|header|cookie` (`--header <name>` or `--cookie <name>` imply it). Header and cookie values are hashed; requests without them count per IP. Over the limit the app answers 429 with `Retry-After`. Rules are per environment and default to `production`; use `--env local` to try one on a local app. Counters live in each process unless the app sets `config.firewall.rateLimitStore` to a Redis URL. `rate-limit` is an alias of `ratelimit`. MCP: `securenow_rate_limit_parse`, `securenow_rate_limit_create_from_text`, `securenow_rate_limit_create`, `securenow_rate_limit_test`.
 
-An app gets the starter pack when it is created or first sends traffic: about 20 rules (SQL injection, XSS, traversal, command and template injection, Log4Shell, Spring4Shell, metadata SSRF, CRLF, prototype pollution, `.env`/`.git`/backup probes, exploit kits, attack-tool user agents, body payloads, failed sign-ins, 404 scanning). They start in **monitor** mode: they alert, nothing is blocked by them. In **block** mode the 14 block-ready rules block the address for 6 hours on their exploit signatures (URL, headers, user agent; bodies and the scheduled rules only alert).
+### Challenge bots
 
 ```bash
-securenow protect                         # status of the current app: mode, rules, alerts, ready to block?
-securenow protect status --all --json     # every app
-securenow protect enable --app <key>      # turn it on (monitor mode)
-securenow protect block --app <key>       # a person turns blocking on; refused unless the app sees real client IPs
-securenow protect monitor --app <key>     # back to alerts only
-securenow protect disable --app <key>     # off; stays off until someone turns it on
-securenow protect learn --app <key>       # detection learning now (it also runs hourly): label alerts, measure precision, learn safe exclusions
-securenow protect status --rules          # adds each rule's 14-day precision (right / right + wrong)
+npx securenow challenge add --route /login --clearance 30m --env production --reason "credential stuffing wave"
+npx securenow challenge add 203.0.113.0/24 --route /signup --difficulty 16 --escalate-to-block --fail-threshold 10 --block-ttl-hours 24
+npx securenow challenge test 203.0.113.9 --path /login --method GET --env production
+npx securenow challenge list | show <id> | enable <id> | disable <id> | remove <id> --reason "..."
+npx securenow firewall hits --action captcha_challenged --since 1h
 ```
 
-Only a person signed in (`securenow admin login`) can turn blocking on; API keys, MCP connectors and the agent get a 403. Blocking is refused when more than 20% of the app's traffic reaches it through a proxy the SDK doesn't trust: add the proxy to `config.networking.trustedProxies` (IPs, IPv4 ranges or `"cloudflare"`). Tune a noisy starter rule like any rule (exclusions, `alerts rules update`); pack updates never overwrite a rule a person edited.
+Browsers get an invisible proof of work (`--difficulty` in leading zero bits, 4–28, default 14: about a second or less) and a pass for `--clearance` (default 30m). Clients that don't accept HTML get a 403 JSON `challenge_required`, so don't challenge API routes used by non-browser clients. MCP: `securenow_challenge_create`, `securenow_challenge_list`, `securenow_challenge_update`, `securenow_challenge_remove`.
 
-**Detection learning** keeps the starter rules precise per app. Every alert gets a label: was the rule right to fire? A blocked address counts as right, a person's false-positive call as wrong, and an LLM judge (accounts with AI access) labels the rest from the requests and the address's last day of traffic; a failed one-off probe (`/.env` answered 404) is closed as right but not worth action. Precision = right / (right + wrong) over 14 days, target 95%. A rule below it with 3+ wrong alerts gets one exclusion for the legitimate traffic, applied only when it matches the wrong alerts and none of the right ones, can't be pinned to an IP, and still lets every reference attack through even when injected into the excused request; otherwise the rule is flagged for a person. A block-ready rule under 95% (10+ labeled alerts) keeps the app from being ready to block. MCP: `securenow_alert_rule_quality`, `securenow_protection_learn`.
-
-### Blocklist — Block Malicious IPs
+### Revoke a stolen session
 
 ```bash
-securenow blocklist                          # list blocked IPs
-securenow blocklist list
-securenow blocklist add <ip> --app <key> --env production --reason "Brute force"
-securenow blocklist add <ip> --route /admin* --mode prefix --method ALL --reason "Admin probing"
-securenow blocklist unblock <id> --reason "False alarm after review"
-securenow blocklist remove <id>              # compatibility alias for unblock
-securenow blocklist list --status removed    # audit retained unblocks
-securenow blocklist stats                    # block counts, top reasons
+npx securenow revoke session <session-id> --reason "impossible travel" --duration 24h --app <key>   # [--env <env>]
+npx securenow revoke user <user-id> --reason "account takeover"      # every session of that user; default expiry 7d
+npx securenow revoke list                                            # [--type session|user] [--status active|restored]
+npx securenow revoke restore <revocation-id> --reason "verified with the user"
 ```
 
-Scoped blocks use the same model as rate limits: `--route`/`--path`/`--pattern`
-sets `pathPattern`, `--mode`/`--path-mode` chooses `prefix`, `exact`, or
-`regex`, and `--method` limits enforcement to one HTTP method or `ALL`.
-
-Unblock stops firewall enforcement but preserves the block report, history, and
-unblock audit fields. Reblocking the same IP later creates a fresh active block
-without erasing the previous investigation trail.
+The app enforces it within 30 seconds, through one of: `"sessions": { "guard": true }` in its runtime config **(8.25.0+)**, `sessions.guard()` middleware, or `sessions.check(req)` **(8.25.0+)** (SKILL-API.md section 5.10). The session id is the SHA-256 of the Bearer token or session cookie, as it appears in `session.id` on traces and `session.seen` events; the user id is the JWT `sub` or what the app reports. There is no MCP tool for revocation: use this command.
 
-MCP exposes legacy pending-block cleanup separately from current Requires Human
-work:
-
-- `securenow_blocklist_unblock`
-- `securenow_blocklist_remove` (compatibility alias for unblock)
-- `securenow_blocklist_pending_list`
-- `securenow_blocklist_pending_approve`
-- `securenow_blocklist_pending_reject`
-- `securenow_blocklist_pending_bulk_approve`
-- `securenow_blocklist_pending_bulk_reject`
-- prompt: `cleanup_legacy_pending_blocks`
-
-### Rate Limits - Soft Remediation
+### Create an alert rule from English and test it
 
 ```bash
-securenow ratelimit list --env production
-securenow ratelimit add 203.0.113.42 --route /api/login --limit 2 --window 1m --duration 24h
-securenow ratelimit parse "rate limit 203.0.113.42 on POST /api/login to 2 attempts per minute"
-securenow ratelimit from-text "rate limit /api/login for this IP to 2 attempts per minute for 24h" --yes
-securenow ratelimit test 203.0.113.42 --path /api/login --method POST
+npx securenow alerts rules from-text "one IP failing 10 sign-ins in 5 minutes" --app <key> --draft-only   # see the checked draft
+npx securenow alerts rules from-text "one IP failing 10 sign-ins in 5 minutes" --app <key>               # create it (asks)
+npx securenow alerts rules test <rule-id> --wait                 # dry run on real data (default)
+npx securenow alerts rules test <rule-id> --mode live --wait     # inserts 6 synthetic attack requests first
+npx securenow alerts rules run <rule-id>                         # run a periodic rule now  [--no-wait]
+npx securenow alerts rules runs <rule-id> --since 1h             # each run: notified, no_rows, throttled, suppressed_blocked, ...
+npx securenow alerts rules why <rule-id> --ip 203.0.113.50 --since 2h
+npx securenow alerts rules change <rule-id> "raise the threshold to 20"   # rewrite from English as a new version
+npx securenow alerts rules quality <rule-id>                     # 14-day precision, wrong alerts and why
+npx securenow alerts rules promote <rule-id> --yes               # a person: test → prod  (demote: back to test)
+npx securenow alerts rules request-promotion <rule-id> --reason "..." --evidence @evidence.md   # what an agent does instead
 ```
 
-MCP parity:
+`from-text` picks an instant rule (each request, as it arrives) or a periodic one (SQL on a schedule); force it with `--instant` or `--periodic`, and set `--name`, `--severity`, `--env` (default: every environment). New rules start in **test mode**: they alert, and no instant block, automation or agent acts on them. With `--yes`, `from-text` refuses a rule whose check matches your data right now (it would alert at once, usually a bad baseline); `--yes --force` creates it anyway when the rows are a real attack. A person approves promotion requests with `npx securenow human promotions` and `human approve-promotion <request-id> --yes` (or `deny-promotion <request-id> --reason "..."`); API keys and MCP tokens can ask but not decide.
 
-- `securenow_rate_limit_parse`
-- `securenow_rate_limit_create_from_text`
+When a rule stays quiet, `alerts rules runs` names the outcome of every run (`notified`, `no_rows`, `throttled`, `suppressed_blocked`, `suppressed_trusted`, `no_ip`, `storm`, `auto_resolved`, `skipped`, `error`) and `alerts rules why` ends in a verdict such as "Detected at 15:06:31 but not notified: 203.0.113.50 was already blocked". The throttle sends one alert per rule and address per window (default 15 minutes).
 
-### Automation Rules
+**SQL rules.** Read the contract first and check the fields the app really sends:
 
 ```bash
-securenow automation                         # list blocklist automation rules
-securenow automation defaults --yes          # ensure built-in default risk-score rules
-securenow automation show <id>
-securenow automation dry-run <id> --limit 500
-securenow automation execute <id> --yes
+npx securenow telemetry schema --json                  # offline: tables, timestamps, tenant scope, event mapping, templates  [logs|traces|events]
+npx securenow telemetry fields --app <key> --env production --since 24h --json   # names, types, counts, event types (never values)
+npx securenow alerts rules validate --sql @rule.sql --app <key>                  # dry-run before creating anything
+npx securenow alerts rules create --name "Auth: magic-link brute force" --sql @rule.sql --apps <key> \
+  --severity high --schedule "*/15 * * * *" --nlp "single IP flooding /api/auth/signin"
+npx securenow alerts rules create --name "Secrets probe" --apps <key> \
+  --conditions '[{"field":"path","operator":"contains","value":"/.env"}]'      # an instant rule, no SQL
+npx securenow alerts rules set-sql <rule-id> --sql @rule.sql                     # replace a custom rule's SQL
+npx securenow alerts rules delete <rule-id> --yes
 ```
 
-Built-in default automation is enabled by default for all apps/environments and
-uses the canonical `riskScore`: 95-100 blocks for 7 days, 90-94 blocks for 72h,
-85-89 blocks for 24h, and scores below 85 stay in investigation/review unless
-the customer adds a stricter custom rule. Raw SecureNow IPDB confidence remains
-supporting evidence, not the primary automation score.
+Scope app keys with `__USER_APP_KEYS__` (logs: `resources_string['service.name'] IN (__USER_APP_KEYS__)`; traces: `` `resource_string_service$$name` IN (__USER_APP_KEYS__) ``) and return an `ip` column (SQL without one is refused unless `--allow-no-ip`: it would never notify). `create` dry-runs the query and deletes the rule again if it fails (`--no-validate` skips that); a new periodic rule runs once right away. Label a rule `READY` only when its fields were observed and `validate` succeeded, otherwise `NEEDS_INSTRUMENTATION` (the app must send a `track()` event), `NEEDS_BASELINE` or `NEEDS_CUSTOMER_DECISION`. Details: `node_modules/securenow/TELEMETRY-SQL.md`. System rules are tuned with `alerts rules tune-query <id> --sql @candidate.sql --reason "..." --apply-globally --yes` (admin), after `alerts rules dry-run-query <id> --sql @candidate.sql --app <key> --wait`.
 
-### Allowlist — Restrict to Known IPs
+MCP: `securenow_alert_rule_draft`, `securenow_alert_rule_create`, `securenow_alert_rule_test`, `securenow_alert_rule_runs`, `securenow_alert_rule_run_now`, `securenow_alert_rule_explain`, `securenow_alert_rule_request_promotion`, `securenow_alert_rule_candidate_test`, `securenow_alert_rule_instant_update`, `securenow_alert_rule_quality`.
 
-Dangerous production mode: IP Allowlist is deny-by-default. Once any active
-allowlist entry exists for an app/environment, only listed IPs can reach it and
-all other IPs are blocked. Do not use allowlist to mark an IP trusted, suppress
-false positives, or clean up investigations. Use `securenow trusted add` for
-known-safe monitors, office/VPN traffic, or trusted bypass cases.
+### Starter protection
 
 ```bash
-securenow allowlist                          # list allowed IPs
-securenow allowlist list
-securenow allowlist add <ip> --app <key> --env local --label "Office" --reason "Corporate VPN"
-securenow allowlist remove <id>
-securenow allowlist stats
+npx securenow protect                       # the current app: mode, rules, alerts, ready to block?  [--all] [--rules] [--json]
+npx securenow protect enable --app <key>    # monitor mode: rules alert, nothing is blocked
+npx securenow protect block --app <key>     # a signed-in person only: block-ready rules block for 6 hours
+npx securenow protect monitor --app <key>   # back to alerts only
+npx securenow protect disable --app <key>   # off until someone turns it on  [--yes]
+npx securenow protect learn --app <key>     # detection learning now (it also runs hourly)
 ```
 
-### Trusted IPs
+Every app gets about 20 starter rules in monitor mode when it is created or first sends traffic. `protect block` is refused for API keys, MCP connectors and the agent, and while more than 20% of the app's traffic arrives through a proxy the SDK doesn't trust (fix with `config.networking.trustedProxies`). Detection learning labels each alert (right, wrong, unclear), keeps each rule's 14-day precision per app and adds a safe exclusion only when it excuses the wrong alerts and none of the right ones. MCP: `securenow_protection_status`, `securenow_protection_learn`.
 
-Trusted IPs are the safe bypass/suppression mechanism for known infrastructure
-and do not enable deny-by-default allowlist mode.
+### Let the autonomous agent work the queues
 
 ```bash
-securenow trusted                            # list trusted IPs
-securenow trusted list
-securenow trusted add <ip> [--label "CloudFlare edge"]
-securenow trusted remove <id>
+npx securenow agent                          # status: on/off, mode per action, what it did, agreement with people
+npx securenow agent on                       # or: off (also revokes a run in progress)
+npx securenow agent mode all shadow          # record what it would do, change nothing
+npx securenow agent mode block_ip act --yes  # then hand over one kind of action at a time
+npx securenow agent activity --mode applied  # every decision with its evidence  [--action block_ip] [--page N]
+npx securenow agent undo <id> --yes          # unblock, reopen the row, or roll the rule back
+npx securenow agent runs                     # patrols: status, tool calls, cost, summary
+npx securenow agent run                      # patrol now
 ```
 
----
-
-### False Positive Management
+Actions: `close_row`, `false_positive`, `block_ip`, `review_close`, `keep_rule`, `rule_change`, `case_action` (or `all`); modes: `off`, `shadow`, `suggest`, `act`. The API enforces the limits whatever the model decides: the agent's token reaches only the queue, verification and rule-tuning routes, it can't block without a verification that allows it, and an action type that people keep undoing drops back to shadow by itself.
 
-The `fp` command manages exclusion rules that prevent known-safe traffic from triggering security alerts.
+Your own harness instead: `npx securenow agent prompts` lists the runbooks; `npx securenow agent prompt patrol` prints one (`patrol`, `alert-review`, `human-queue`; `--confirm-writes` for the variant that may act, `--search`, `--limit`, `--max-alert-review-groups`, `--max-human-rows`):
 
 ```bash
-securenow fp                                 # list all exclusion rules
-securenow fp list
-securenow fp show <id>                       # rule details
-securenow fp delete <id> [--yes]
-
-# Create exclusion rules
-securenow fp create \
-  --conditions '[{"field":"path","operator":"starts_with","value":"/api/health"}]' \
-  --match-mode all \
-  --rule-scope any_rule \
-  --reason "Health check endpoint"
-
-# Shorthand safe-value presets
-securenow fp create \
-  --path /api/events \
-  --method POST \
-  --path-safe standard \
-  --ua-safe standard \
-  --headers-safe standard \
-  --query-keys page,limit \
-  --headers-keys host,content-type \
-  --reason "Event webhook"
-
-# Edit an existing rule
-securenow fp edit <id> [--active true|false] [--conditions '[...]']
-
-# Test conditions against a request body
-securenow fp test-body '{"user":"admin"}' --conditions '[{"field":"request_body","operator":"contains","value":"\"user\":\"admin\""}]'
-securenow fp test-body @request.json --conditions '[...]'
-
-# Dry-run conditions against the last 3 days of live traces
-securenow fp dry-run --conditions '[{"field":"path","operator":"starts_with","value":"/api/webhook"}]'
-
-# AI-generate exclusion conditions from a description
-securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook" \
-  --context '{"method":"POST","path":"/api/stripe/webhook"}'
-
-# Mark an IP as false positive on a specific notification
-securenow fp mark <notification-id> <ip> \
-  [--conditions '[...]'] \
-  [--reason "Known partner IP"] \
-  [--rule-scope this_rule|specific_rules|all_existing|any_rule] \
-  [--target-rules id1,id2]
+claude -p "$(npx -y securenow@latest agent prompt patrol --search my-app --confirm-writes)" --allowedTools "mcp__securenow"
 ```
 
-**Condition shape:** `{"field": ..., "operator": ..., "value": ...}` (the key is `operator`, not `op`).
-
-**Condition fields:** `path`, `method`, `user_agent`, `status_code`, `request_body`, `request_headers`.
-
-**Operators:** `equals`, `not_equals`, `contains`, `not_contains`, `starts_with`, `ends_with`, `regex`, `in`, `not_in`, plus structural checks — `path_safe_values`, `query_safe_values`, `query_has_only_keys`, `ua_safe_values`, `headers_safe_values`, `headers_has_only_keys`, `body_safe_values`, `body_is_format`, `body_has_only_fields`, `json_has_only_keys`, `json_safe_values`, `json_valid`, `json_max_depth`, `json_schema_match`. Prefer the `*_safe_values` checks over `contains`: they only exclude a request whose value is clean.
-
-**Match modes:** `all` (AND logic), `any` (OR logic).
-
-**Rule scopes:** `this_rule` (single alert rule — only via `fp mark`; for a rule-only exclusion without a notification use `securenow alerts rules exclusions <rule-id> add --conditions '[...]'`), `specific_rules` (comma-separated IDs via `--target-rules`), `all_existing` (all current rules), `any_rule` (all current and future rules; the `fp create` default).
-
-**Safe-value presets:** `standard` or `strict`. These auto-generate conditions that whitelist common safe patterns for paths, query strings, user-agents, and headers.
-
----
-
-### Instances
+### Set up MCP
 
 ```bash
-securenow instances                          # list ClickHouse instances
-securenow instances list
-securenow instances test <id>                # test connection
+npx securenow login                                        # the local server uses this auth
+claude mcp add securenow -- npx securenow mcp              # Claude Code
+codex mcp add securenow -- npx securenow mcp               # Codex
+claude mcp add --transport http securenow https://api.securenow.ai/mcp   # hosted server, OAuth sign-in
 ```
 
----
-
-### Telemetry — Emit Logs and Spans From the Shell
-
-Mirrors the SDK's `getLogger()` and tracing APIs. Useful for cron jobs, shell scripts, and CI pipelines that need to push events into SecureNow without booting the full OTel SDK.
-
-```bash
-# Send a structured log record to the OTLP collector
-securenow log send "Deployment completed" --level info --attrs version=1.2.3,service=api
-securenow log send "Backup failed" --level error --attrs host=db-01
+Cursor, `.cursor/mcp.json`:
 
-# Emit a test span to verify the collector accepts OTLP traffic
-securenow test-span
-securenow test-span "ci.smoke-test"          # custom span name
+```json
+{ "mcpServers": { "securenow": { "command": "npx", "args": ["securenow", "mcp"] } } }
 ```
 
-Both commands use the default SecureNow ingestion gateway plus optional advanced `config.otel.*` overrides from `.securenow/runtime.json` or legacy runtime credentials, and return non-zero on HTTP errors so CI/cron can detect failures.
+- The local stdio server is `npx securenow mcp` (also the `securenow-mcp` bin). Admin tools use `.securenow/admin.json`; app-scoped reads can use `.securenow/runtime.json`. Warm the package once (`npx -y securenow@latest --version`) so the first connection doesn't time out on the download, and give the client a longer connect timeout (Claude Code: `MCP_TIMEOUT=120000`).
+- The hosted server `https://api.securenow.ai/mcp` needs no install and always has the current tools: OAuth sign-in with a SecureNow account (or `Authorization: Bearer <API key>`). The SecureNow plugin for Claude Code and Codex bundles it with skills (`/plugin marketplace add securenow-ai/claude-plugin`, then `/plugin install securenow@securenow`).
+- Read tools are annotated read-only; every write tool refuses to run without `confirm: true` and a non-empty `reason`. Resources: the installed SKILL-API.md, SKILL-CLI.md and NPM_README.md, the project config, the tool catalog. Prompts: `secure_project_setup`, `verify_firewall_default_on`, `investigate_ip`, `investigate_human_action_row`, `work_human_actions`, `work_alert_review`, `soc_patrol`, `agent_patrol`, `cleanup_legacy_pending_blocks`, `configure_default_automation`.
+- Profiles serve only the tools one job needs (`npx securenow mcp --profile <name>` or `SECURENOW_MCP_PROFILE=<name>`). Every profile keeps `securenow_auth_status`, `securenow_apps_list` and `securenow_apps_info`; a tool outside the profile returns an error naming it.
 
-### Utilities — Redaction, CIDR, Diagnostics
+  | Profile | Tools | Contents |
+  |---|---|---|
+  | `all` (default) | 125 | everything |
+  | `investigator` | 65 | every read-only tool, plus forensics question/chat/confirm |
+  | `detection` | 53 | alert rules (draft, create, test, run, runs, explain, versions, exclusions, request promotion...), traces, logs, forensics, IP intelligence, notifications |
+  | `responder` | 82 | notifications, both queues, blocklist, allowlist, trusted IPs, rate limits, challenges, automations, firewall, IP intelligence, plus rule get/runs/explain and traces/logs |
 
-The `redact` command also hides OTP credentials named `code`, `oneTimeCode`, `verificationCode`, and `passcode` (case/separator variants included), while preserving `status_code` and `error_code`. SDK capture uses the same defaults.
+  ```bash
+  claude mcp add securenow-investigator -- npx -y securenow@latest mcp --profile investigator
+  ```
 
-These mirror the SDK exports (`redactSensitiveData`, `createMatcher`, `parseCidr`) so agents can validate behavior without writing Node.
+### Emit an event, a log or a span from a script
 
 ```bash
-# Redact sensitive fields (password, token, card, ssn, etc.)
-securenow redact '{"user":"alice","password":"s3cret","card":"4242"}'
-securenow redact @request.json --fields internal_id,sessionHash
-
-# CIDR operations — match an IP against a list, or parse a range
-securenow cidr match 10.0.0.5 10.0.0.0/24,192.168.0.0/16
-securenow cidr parse 10.0.0.0/24             # network, broadcast, mask, size
-
-# Show resolved config (service name, endpoints, credentials, firewall layers)
-securenow env                                # human-readable
-securenow env --json                         # pipe to jq
-
-# End-to-end diagnostic: probe OTLP + API endpoints, check config
-securenow doctor                             # exits 0 if healthy, 1 otherwise
-securenow doctor --json
+npx securenow event send auth.login.failure --user u_123 --ip 203.0.113.10 --attrs reason=bad_password,method=password
+npx securenow event send auth.otp.send.result --session s_1 --level warn --attrs status=failed --env staging
+npx securenow log send "Backup failed" --level error --attrs host=db-01      # --level trace|debug|info|warn|error|fatal
+npx securenow test-span ci.smoke-test --env production
 ```
 
-The `redact` command accepts a JSON string or `@path/to/file.json` and layers your `--fields` flag on top of `DEFAULT_SENSITIVE_FIELDS`. Exit code from `cidr match` is `0` if the IP matches the list, `2` otherwise — scriptable.
+`event send` posts one custom event to the `/v1/events` ingest with the runtime credentials (`--user`, `--session`, `--ip`, `--user-agent`, `--level`, `--attrs k=v,k=v`, `--env`): the same event `track()` sends from Node, for cron jobs, CI or non-JS services. `log send` and `test-span` exit non-zero on HTTP errors, so CI can catch failures.
 
----
-
-## Workflow Examples for Agentic AI
-
-### Investigate a Security Alert
+### Diagnose a setup
 
 ```bash
-securenow notifications list --limit 5 --json
-# IMPORTANT: parse the ipInvestigations array for each notification — see statuses below
-securenow ip <attacker-ip> --json
-securenow ip traces <attacker-ip> --json
-securenow traces show <trace-id> --json
-securenow traces analyze <trace-id> --json
-# Decision: block the IP
-securenow blocklist add <attacker-ip> --reason "Automated: SQL injection detected"
+npx securenow env            # resolved service name, environment, endpoints, firewall (no secrets)  [--json]
+npx securenow doctor         # probes traces, logs, API and firewall sync; exit 1 on failure  [--json]
+npx securenow test-span      # "Span accepted (HTTP 200)"
+npx securenow firewall status --env production   # the app's firewall state, layers, blocklist
+npx securenow firewall apps                      # every app with its firewall on/off per environment
+npx securenow firewall enable --app <key> --env production   # or: disable
+npx securenow config path                        # config and credential files in use
 ```
 
-#### Notification IP Investigation Statuses
-
-Each notification contains an `ipInvestigations` array. **Every IP has its own `status` field** that you MUST check before taking action or raising flags. Do not rely only on top-level notification fields — always cross-reference each IP's individual investigation status.
-
-| Status | Meaning | Action |
-|--------|---------|--------|
-| `open` | Still needs review — no determination yet | Investigate: run `securenow ip <ip>`, check traces, decide to block or dismiss |
-| `false_positive` | Trusted/dismissed by exclusion rule, verified bot, or trusted IP list | **Skip** — greyed out in UI, no action needed |
-| `blocked` | Already on the user's blocklist | **Skip** — already handled |
-| `clean` | Pipeline analyzed and cleared as benign | **Skip** — verified safe |
-
-**Critical workflow rule:** When investigating notifications, iterate `ipInvestigations[]` and **only flag or act on IPs with `status: "open"`**. IPs marked `false_positive`, `blocked`, or `clean` have already been triaged — do not re-flag them.
-
-### Triage and Suppress a False Positive
+### Threat-modeling prompts
 
 ```bash
-securenow notifications list --json
-# Identify a false positive notification
-securenow fp ai-fill --description "Stripe webhook calls to /api/stripe/webhook"
-# Review the suggested conditions, then create the rule
-securenow fp create --conditions '<ai-suggested-conditions>' --rule-scope any_rule --reason "Stripe webhook"
-# Or directly mark the notification's IP as FP
-securenow fp mark <notification-id> <ip> --rule-scope this_rule --reason "Known Stripe IP"
+npx securenow threat-model --list
+npx securenow threat-model authentication --out threat-prompt.md   # then: "Follow threat-prompt.md"
+npx securenow threat-model authentication | claude -p
 ```
 
-### Onboard a New Application
+Categories include `authentication`, `authorization`, `injection`, `api-security`, `rate-limits-and-abuse`, `webhooks`, `ai-llm-features` and more (`--list`).
 
-```bash
-securenow apps create my-new-app --hosts api.example.com,app.example.com
-securenow apps default my-new-app
-securenow login
-securenow init
-securenow run src/index.js
-securenow status --json
-```
-
-### Security Posture Check
+### Utilities
 
 ```bash
-securenow status --json
-securenow firewall status --json
-securenow blocklist stats --json
-securenow forensics "summarize all attacks in the last 7 days"
+npx securenow redact '{"user":"alice","password":"s3cret","otpCode":"123456","status_code":200}'   # [--fields f1,f2] or @file.json
+npx securenow cidr match 10.0.0.5 10.0.0.0/8,192.168.1.0/24    # exit 0 = match, 2 = no match
+npx securenow cidr parse 10.0.0.0/24                           # network, broadcast, mask, size
 ```
 
-### Discover Attack Surface
-
-```bash
-securenow apps discover --domain example.com
-securenow apps scan --yes
-```
+`redact` uses the same rules as SDK capture (field names, OTP names matched exactly so `status_code` stays, secret-shaped values).
 
----
+## Command reference
 
-## Output Parsing
+`securenow help <command>` is authoritative. Subcommand flags not listed by `help` are shown in its usage lines below.
 
-All commands support `--json` for structured output. When piping to other tools or parsing programmatically, always use `--json`. Table output is the default for human readability.
+| Command | Subcommands | Key flags |
+|---|---|---|
+| `run` | `run [node-flags] [--firewall-only] <script> [args]`; `securenow <script.js>` is a shorthand | `--firewall-only`, Node flags pass through (`--watch`, `--inspect`) |
+| `login` | | `--token`, `--global` |
+| `logout` | | `--global` |
+| `whoami` | | |
+| `admin` | `login` (default), `logout` | `--token`, `--global` |
+| `app` | `connect` (default) | `--global` |
+| `credentials` | `runtime` (default) | `--env` (default `production`), `--out`, `--stdout`, `--format env` |
+| `api-key` | `create`, `set <key>`, `clear`, `show` (default) | `create`: `--name`, `--app <key-or-id>`, `--preset runtime_app`, `--global` |
+| `init` | | `--env` (default `local`), `--key snk_live_...`, `--ts` (`--typescript`), `--js` (`--javascript`), `--src`/`--root` (Next.js file folder; default `src/` when `app/` or `pages/` is there), `--force` (replace the instrumentation file, keeping a `.bak`) |
+| `apps` | `list` (default), `create <name>`, `info <id>`, `delete <id>`, `default <key>`, `discover [appId]`, `scan` | `create`: `--hosts h1,h2`, `--instance <id>`; `delete`: `--force`; `discover`: `--domain`; `scan`: `--yes` |
+| `status` | | `--app`, `--env local\|production\|all` |
+| `today` | | `--since 1h..7d` (default 24h), `--attackers <n>` (default 8), `--json` |
+| `attacker` | `attacker <ip>` | `--json` |
+| `traces` | `list` (default), `show <traceId>`, `analyze <traceId>` | `--app`, `--env`, `--limit`, `--start`, `--end` |
+| `logs` | `list` (default), `trace <traceId>`, `errors` | `--app`, `--env`, `--since 30m\|6h\|2d`, `--minutes`, `--level trace\|debug\|info\|warn\|error\|fatal`, `--limit`, `--start`, `--end`; `errors`: `--warn` |
+| `analytics` | | `--app` |
+| `protect` | `status` (default), `enable`, `disable`, `block`, `monitor`, `learn` | `--app`, `--all`, `--rules`, `--yes` |
+| `agent` | `status` (default), `on`, `off`, `mode <action> <mode>`, `activity`, `undo <id>`, `runs`, `run`, `verify <ip>`, `prompt <name>`, `prompts` | `--action`, `--mode`, `--page`, `--notification`, `--yes`, `--confirm-writes`, `--limit`, `--search`, `--max-alert-review-groups`, `--max-human-rows` |
+| `human` | `list` (default), `show`, `block`, `fp`, `close`, `report`, `action`, `prompt`, `work`, `promotions`, `approve-promotion`, `deny-promotion` | `--reason`, `--outcome`, `--summary`, `--evidence`, `--yes`, `--search`, `--limit`, `--page`, `--status`, `--note`, `--conditions`, `--rule-scope`, `--create-exclusion`, `--missing-proof` |
+| `review` | `list` (default), `show`, `keep`, `close`, `dismiss`, `group` | `--outcome`, `--reason`, `--summary`, `--preview`, `--allow-mixed`, `--search`, `--yes` |
+| `notifications` | `list` (default), `read <id>`, `read-all`, `unread` | `list`: `--limit`, `--page`, `--search`, `--severity` |
+| `alerts` | `rules` (default), `channels`, `history` | `history`: `--limit` |
+| `alerts rules` | `list` (default), `from-text`, `change`, `create`, `show`, `update`, `duplicate`, `promote`, `demote`, `set-sql`, `validate`, `dry-run-query`, `tune-query`, `delete`, `test`, `run`, `runs`, `why`, `quality`, `exclusions <id> [list\|add\|delete]`, `versions`, `version`, `rollback`, `request-promotion` | `--app`, `--apps`, `--applications-all`, `--env`, `--instant`, `--periodic`, `--draft-only`, `--name`, `--sql`, `--conditions`, `--severity`, `--schedule`, `--throttle-minutes`, `--no-throttle`, `--channel`, `--allow-no-ip`, `--no-validate`, `--mode dry_run\|live` (test) / `test\|prod` (list, update), `--status`, `--wait`, `--ip`, `--since`, `--limit`, `--reason`, `--evidence`, `--apply-globally`, `--yes`, `--force` |
+| `fp` | `list` (default), `show`, `create`, `edit`, `delete`, `test-body`, `dry-run`, `ai-fill`, `mark <notification-id> <ip>` | `--conditions`, `--match-mode`, `--rule-scope`, `--target-rules`, `--path`, `--method`, `--path-safe`, `--query-safe`, `--query-keys`, `--ua-safe`, `--headers-safe`, `--headers-keys`, `--reason`, `--description`, `--context`, `--active` |
+| `ip` | `ip <address>` (lookup), `lookup`, `traces <ip>` | `traces`: `--app`, `--env` |
+| `forensics` | `forensics "<question>"`, `query`, `chat`, `conversations [<id>]`, `library` | `--app`, `--env`, `chat`: `--conversation <id>`, `--yes` |
+| `firewall` | `status` (default), `apps`, `enable`, `disable`, `test-ip <ip>`, `hits` | `--app`, `--env`; `test-ip`: `--path`, `--method`; `hits`: `--since`, `--action blocked\|rate_limited\|captcha_challenged`, `--source`, `--rule`, `--ip`, `--limit` |
+| `automation` | `list` (default), `defaults`, `show`, `create`, `update`, `dry-run`, `execute`, `delete` | `--name`, `--conditions`, `--actions`, `--logic`, `--status`, `--body`, `--file`, `--app`, `--applications-all`, `--env`, `--environments-all`, `--limit`, `--sample-limit`, `--yes`; `defaults`: `--force-enable` |
+| `ratelimit` (alias `rate-limit`) | `list` (default), `add [ip]`, `parse`, `from-text`, `show`, `test <ip>`, `enable`, `disable`, `remove` | `--route`/`--path`, `--mode`, `--method`, `--limit`, `--window`, `--duration`, `--key-by`, `--header`, `--cookie`, `--key-name`, `--app`, `--env`, `--reason`, `--text` |
+| `challenge` | `list` (default), `add [ip]`, `show`, `test <ip>`, `enable`, `disable`, `remove` | `--route`/`--path`, `--mode`, `--method`, `--difficulty` (4–28, default 14), `--clearance` (default 30m), `--duration`, `--escalate-to-block`, `--fail-threshold` (10), `--block-ttl-hours` (24), `--app`, `--env`, `--reason` |
+| `blocklist` | `list` (default), `add <ip>`, `unblock <id>`, `remove <id>`, `approve <id>`, `reject <id>`, `stats` | `--route`/`--path`/`--pattern`, `--mode`/`--path-mode`, `--method`, `--duration`, `--app`, `--env`, `--reason`, `--status`, `--approval-status`, `--search`, `--view`, `--page`, `--limit` |
+| `revoke` | `list` (default), `session <id>`, `user <id>`, `restore <id>` | `--reason`, `--duration` (default 7d), `--app`, `--env`, `--type`, `--status` |
+| `allowlist` | `list` (default), `add <ip>`, `remove <id>`, `stats` | `--app` (comma-separated), `--env`, `--label`, `--reason`, `--page`, `--limit` |
+| `trusted` | `list` (default), `add <ip>`, `remove <id>` | `--app`, `--env`, `--label` |
+| `telemetry` | `schema` (default) `[all\|logs\|traces\|events]`, `fields` | `--app`, `--env`, `--since` (max 30d), `--source`, `--limit` (1–500), `--json` |
+| `log` | `send <message>` (default) | `--level`, `--attrs`, `--env` |
+| `event` | `send <type>` (default) | `--user`, `--session`, `--ip`, `--user-agent`, `--level`, `--attrs`, `--env` |
+| `test-span` | `test-span [<name>]` | `--env` |
+| `threat-model` | `threat-model <category>` | `--list`, `--out` |
+| `redact` | `redact '<json>'` or `@file` | `--fields` |
+| `cidr` | `match <ip> <cidrs>`, `parse <cidr>` | |
+| `doctor` | | `--json` |
+| `env` | | `--json` |
+| `mcp` | | `--profile all\|investigator\|detection\|responder` |
+| `instances` | `list` (default), `test <id>` | |
+| `config` | `get [key]`, `set <key> <value>`, `path` | keys: `apiUrl`, `appUrl`, `defaultApp` |
+| `version` | | |
+
+## Flags, environment and errors
 
-## Error Handling
+| Flag | Short | Effect |
+|---|---|---|
+| `--json` | `-j` | JSON output for scripts and agents |
+| `--help` | | Help for the command |
+| `--yes` | `-y` | Confirm a write without the prompt |
+| `--force` | `-f` | Same as `--yes` on most write commands |
 
-| Exit code / Error | Meaning | Recovery |
-|------------------|---------|----------|
-| `Session expired` | Admin JWT expired | `securenow admin login` (or `admin login --global` for shared admin auth) |
-| `Not logged in` | No admin token found | `securenow admin login`; runtime `.securenow/runtime.json` is unrelated |
-| `Access denied (403)` | Insufficient permissions | Check the user's role in the account/organization |
-| `HTTP 402` | The 14-day trial ended and the account has no active subscription (everything, including the firewall, is paused) | Subscribe in the dashboard: $99 per app per month, every feature included |
-| `Cannot connect` | API unreachable | Check `securenow config get apiUrl` or network |
-| `Unknown command` | Typo or unrecognized command | `securenow help` |
+Environment variables the CLI reads: `NO_COLOR` (plain output), `SECURENOW_MCP_PROFILE` (MCP tool profile), `SECURENOW_CREDENTIALS` (runtime credentials, used by `env`, `doctor`, `test-span`, `log send`, `event send`). The admin token always comes from `admin.json` (`npx securenow admin login`).
 
-SecureNow-specific environment overrides are intentionally unsupported for troubleshooting; use explicit CLI config files and normal terminal logs.
+| Error | Meaning | Recovery |
+|---|---|---|
+| `Session expired` | The admin token expired | `npx securenow admin login` |
+| `Not logged in` | No admin token found | `npx securenow admin login` (the runtime file is a separate lane) |
+| `Access denied (403)` | The user's role or the key's scopes don't allow it | Check the role in the organization or the API key's scopes |
+| `HTTP 402` | The 14-day trial ended and the account has no subscription; everything, the firewall included, is paused | Subscribe in the dashboard ($99 per app per month, every feature) |
+| `Cannot connect` | API unreachable | Network, or `npx securenow config get apiUrl` |
+| `Unknown command` | Typo | `npx securenow help` |