securenow 8.11.2 → 8.11.3

package/SKILL-CLI.md

@@ -1,255 +1,255 @@
-# SecureNow CLI — Agent Skill
-
-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.
-
-## Installation
-
-```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.
-
-**MCP parity (v8.0+):** the same package also ships a local stdio MCP server for Codex, Claude, and other MCP clients:
-
-```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.
-
-### 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
-```
-
-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"
-```
-
-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).
-
-### Authentication
-
-```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
-```
-
-### Applications
-
-```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
-```
-
-### API Key Management
-
-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.
-
-```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
-```
-
-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`.
-
-### Init — Project Setup
-
-```bash
-securenow init [--env local] [--key <API_KEY>]
-```
-
-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
-
-```bash
-securenow status [--app <key>] [--env local|production|all] # dashboard overview
-securenow analytics [--app <key>]            # response analytics
-```
-
----
-
-### Traces
-
-```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
-```
-
-### 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
-```
-
-### 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
-```
-
-### Human Actions — AI-Prepared Decision Queue
-
-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.
-
-```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 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
-```
-
-MCP parity:
-
-- `securenow_human_actions_list`
-- `securenow_notifications_get`
-- `securenow_human_action_report`
-- `securenow_human_action_block`
-- `securenow_human_action_false_positive`
-- `securenow_human_case_action_update`
-- prompts: `investigate_human_action_row`, `work_human_actions`
-
-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.
-
+# SecureNow CLI — Agent Skill
+
+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.
+
+## Installation
+
+```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.
+
+**MCP parity (v8.0+):** the same package also ships a local stdio MCP server for Codex, Claude, and other MCP clients:
+
+```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.
+
+### 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
+```
+
+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"
+```
+
+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).
+
+### Authentication
+
+```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
+```
+
+### Applications
+
+```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
+```
+
+### API Key Management
+
+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.
+
+```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
+```
+
+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`.
+
+### Init — Project Setup
+
+```bash
+securenow init [--env local] [--key <API_KEY>]
+```
+
+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
+
+```bash
+securenow status [--app <key>] [--env local|production|all] # dashboard overview
+securenow analytics [--app <key>]            # response analytics
+```
+
+---
+
+### Traces
+
+```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
+```
+
+### 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
+```
+
+### 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
+```
+
+### Human Actions — AI-Prepared Decision Queue
+
+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.
+
+```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 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
+```
+
+MCP parity:
+
+- `securenow_human_actions_list`
+- `securenow_notifications_get`
+- `securenow_human_action_report`
+- `securenow_human_action_block`
+- `securenow_human_action_false_positive`
+- `securenow_human_case_action_update`
+- prompts: `investigate_human_action_row`, `work_human_actions`
+
+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
@@ -271,385 +271,376 @@ its fields were observed and `alerts rules validate` succeeds. Otherwise label i
 `NEEDS_INSTRUMENTATION`, `NEEDS_BASELINE`, or `NEEDS_CUSTOMER_DECISION` as appropriate.
 
 ```bash
-securenow alerts                             # list alert rules (default)
-securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
-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> --mode dry_run --wait  # validate an existing rule's query
-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
-```
-
-**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. Requires `alerts:write`.
-
-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.
-
----
-
-### 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
-
-```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
-securenow forensics library                  # view saved/template queries
-```
-
-### API Map
-
-```bash
-securenow api-map                            # list discovered API endpoints
-securenow api-map list                       # same
-securenow api-map stats                      # endpoint statistics
-```
-
----
-
-### Firewall
-
-```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
-```
-
-**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.
-
-### Blocklist — Block Malicious IPs
-
-```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
-```
-
-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.
-
-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
-
-```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
-```
-
-MCP parity:
-
-- `securenow_rate_limit_parse`
-- `securenow_rate_limit_create_from_text`
-
-### Automation Rules
-
-```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
-```
-
-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.
-
-### Allowlist — Restrict to Known IPs
-
-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.
-
-```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
-```
-
-### Trusted IPs
-
-Trusted IPs are the safe bypass/suppression mechanism for known infrastructure
-and do not enable deny-by-default allowlist mode.
-
-```bash
-securenow trusted                            # list trusted IPs
-securenow trusted list
-securenow trusted add <ip> [--label "CloudFlare edge"]
-securenow trusted remove <id>
-```
-
----
-
-### False Positive Management
-
-The `fp` command manages exclusion rules that prevent known-safe traffic from triggering security alerts.
-
-```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":"http.target","op":"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":"body.user","op":"eq","value":"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":"http.target","op":"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]
-```
-
-**Condition fields:** `http.target`, `http.method`, `http.url`, `http.user_agent`, `http.request.header.*`, `body.*`, `http.status_code`, `net.peer.ip`, and more.
-
-**Operators:** `eq`, `neq`, `contains`, `not_contains`, `starts_with`, `ends_with`, `regex`, `in`, `not_in`, `exists`, `not_exists`, `gt`, `lt`, `gte`, `lte`.
-
-**Match modes:** `all` (AND logic), `any` (OR logic).
-
-**Rule scopes:** `this_rule` (single alert rule), `specific_rules` (comma-separated IDs via `--target-rules`), `all_existing` (all current rules), `any_rule` (all current and future rules).
-
-**Safe-value presets:** `standard` or `strict`. These auto-generate conditions that whitelist common safe patterns for paths, query strings, user-agents, and headers.
-
----
-
-### Instances
-
-```bash
-securenow instances                          # list ClickHouse instances
-securenow instances list
-securenow instances test <id>                # test connection
-```
-
----
-
-### 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
-
-# Emit a test span to verify the collector accepts OTLP traffic
-securenow test-span
-securenow test-span "ci.smoke-test"          # custom span name
-```
-
-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.
-
+securenow alerts                             # list alert rules (default)
+securenow alerts rules                       # list alert rules (columns: Status, Applications, Schedule)
+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> --mode dry_run --wait  # validate an existing rule's query
+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
+```
+
+**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. Requires `alerts:write`.
+
+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.
+
+---
+
+### 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
+
+```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
+securenow forensics library                  # view saved/template queries
+```
+
+---
+
+### Firewall
+
+```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
+```
+
+**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.
+
+### Blocklist — Block Malicious IPs
+
+```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
+```
+
+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.
+
+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
+
+```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
+```
+
+MCP parity:
+
+- `securenow_rate_limit_parse`
+- `securenow_rate_limit_create_from_text`
+
+### Automation Rules
+
+```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
+```
+
+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.
+
+### Allowlist — Restrict to Known IPs
+
+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.
+
+```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
+```
+
+### Trusted IPs
+
+Trusted IPs are the safe bypass/suppression mechanism for known infrastructure
+and do not enable deny-by-default allowlist mode.
+
+```bash
+securenow trusted                            # list trusted IPs
+securenow trusted list
+securenow trusted add <ip> [--label "CloudFlare edge"]
+securenow trusted remove <id>
+```
+
+---
+
+### False Positive Management
+
+The `fp` command manages exclusion rules that prevent known-safe traffic from triggering security alerts.
+
+```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]
+```
+
+**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
+
+```bash
+securenow instances                          # list ClickHouse instances
+securenow instances list
+securenow instances test <id>                # test connection
+```
+
+---
+
+### 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
+
+# Emit a test span to verify the collector accepts OTLP traffic
+securenow test-span
+securenow test-span "ci.smoke-test"          # custom span name
+```
+
+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.
+
 ### Utilities — Redaction, CIDR, Diagnostics
 
-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.
-
-These mirror the SDK exports (`redactSensitiveData`, `createMatcher`, `parseCidr`) so agents can validate behavior without writing Node.
-
-```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
-```
-
-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.
-
----
-
-## Workflow Examples for Agentic AI
-
-### Investigate a Security Alert
-
-```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"
-```
-
-#### 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
-
-```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"
-```
-
-### Onboard a New Application
-
-```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
-
-```bash
-securenow status --json
-securenow firewall status --json
-securenow blocklist stats --json
-securenow api-map stats --json
-securenow forensics "summarize all attacks in the last 7 days"
-```
-
-### Discover Attack Surface
-
-```bash
-securenow apps discover --domain example.com
-securenow apps scan --yes
-securenow api-map list --json
-securenow api-map stats --json
-```
-
----
-
-## Output Parsing
-
-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.
-
-## Error Handling
-
-| 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 plan or permissions | Upgrade plan or check user role |
-| `Cannot connect` | API unreachable | Check `securenow config get apiUrl` or network |
-| `Unknown command` | Typo or unrecognized command | `securenow help` |
-
-SecureNow-specific environment overrides are intentionally unsupported for troubleshooting; use explicit CLI config files and normal terminal 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.
+
+These mirror the SDK exports (`redactSensitiveData`, `createMatcher`, `parseCidr`) so agents can validate behavior without writing Node.
+
+```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
+```
+
+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.
+
+---
+
+## Workflow Examples for Agentic AI
+
+### Investigate a Security Alert
+
+```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"
+```
+
+#### 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
+
+```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"
+```
+
+### Onboard a New Application
+
+```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
+
+```bash
+securenow status --json
+securenow firewall status --json
+securenow blocklist stats --json
+securenow forensics "summarize all attacks in the last 7 days"
+```
+
+### Discover Attack Surface
+
+```bash
+securenow apps discover --domain example.com
+securenow apps scan --yes
+```
+
+---
+
+## Output Parsing
+
+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.
+
+## Error Handling
+
+| 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 plan or permissions | Upgrade plan or check user role |
+| `Cannot connect` | API unreachable | Check `securenow config get apiUrl` or network |
+| `Unknown command` | Typo or unrecognized command | `securenow help` |
+
+SecureNow-specific environment overrides are intentionally unsupported for troubleshooting; use explicit CLI config files and normal terminal logs.