securenow 8.23.0 → 8.25.0

package/NPM_README.md

@@ -1,25 +1,28 @@
-# SecureNow - Complete OpenTelemetry Observability for Node.js
+# SecureNow - Complete OpenTelemetry Observability for Node.js
 
 > **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.
 
-OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt applications. Send distributed traces and logs to any OTLP-compatible observability backend.
+OpenTelemetry instrumentation and an in-process firewall for Node.js, Next.js, and Nuxt applications. Traces, logs, crashes and security events go to the SecureNow ingest gateway (`https://ingest.securenow.ai`), where detection runs; an advanced setting can point the OpenTelemetry export at your own OTLP collector instead.
+
+This is the long reference. The step-by-step integration playbook for coding agents is [`SKILL-API.md`](./SKILL-API.md); the CLI by task is [`SKILL-CLI.md`](./SKILL-CLI.md). Items marked **(8.25.0+)** need securenow 8.25.0 or newer.
 
 **Features:**
-- Zero-config automatic instrumentation
-- Distributed tracing for all popular frameworks
-- Automatic logging with console instrumentation
-- Built-in sensitive data redaction
-- Request body capture for debugging
-- Multi-layer firewall -- auto-blocks IPs from your SecureNow blocklist
+- Zero-config automatic instrumentation: one `-r securenow/register` flag for CommonJS, ESM and TypeScript apps
+- Distributed tracing for Express, Fastify, NestJS, Koa, Hapi, Hono, Polka, Feathers, h3, raw `http`, Next.js and Nuxt
+- Automatic logging with console instrumentation, and crash capture
+- Built-in sensitive data redaction (field names, OTP codes, secret-shaped values)
+- Request header and body capture for detection and debugging
+- Multi-layer firewall -- blocks IPs from your SecureNow blocklist, plus rate limits (429) and proof-of-work challenges
+- Custom security events (`securenow/events`) and session revocation (`securenow/sessions`)
 - `securenow init` scaffolds Next.js instrumentation, safe `serverExternalPackages`, and standalone output tracing includes
 - `securenow/firewall-only` entry point for firewall without tracing overhead
 - Split local credentials: `.securenow/admin.json` for CLI/MCP admin auth and `.securenow/runtime.json` for SDK runtime
-- Single `-r securenow/register` flag -- works for both CJS and ESM apps
-- Native Nuxt 3 module (`securenow/nuxt`)
+- Native Nuxt 3 and 4 module (`securenow/nuxt`)
+- CLI and MCP server for coding agents
 
 ---
 
-> **v8.0 credential model:** admin/control-plane CLI and MCP auth lives in `.securenow/admin.json`; SDK runtime app config and the runtime API key live in `.securenow/runtime.json`. `npx securenow login` can run both lanes for onboarding, `npx securenow admin login` refreshes only admin auth, and `npx securenow app connect` refreshes only runtime app config. Legacy combined `.securenow/credentials.json` files are still read, and production runtime exports can still be mounted as `.securenow/credentials.json`.
+> **v8.0 credential model:** admin/control-plane CLI and MCP auth lives in `.securenow/admin.json`; SDK runtime app config and the runtime API key live in `.securenow/runtime.json`. `npx securenow login` can run both lanes for onboarding, `npx securenow admin login` refreshes only admin auth, and `npx securenow app connect` refreshes only runtime app config. Legacy combined `.securenow/credentials.json` files are still read, and production runtime exports are mounted as `.securenow/credentials.json`.
 
 ---
 
@@ -27,20 +30,26 @@ OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt application
 
 - [Installation](#installation)
 - [Quick Start](#quick-start)
-- [CLI -- Command Line Interface](#cli--command-line-interface)
-- [MCP for Codex and Claude](#mcp-for-codex-and-claude)
+- [CLI -- Command Line Interface](#cli----command-line-interface)
 - [Framework-Specific Setup](#framework-specific-setup)
   - [Express.js](#expressjs)
-  - [Next.js](#nextjs)
-  - [Nuxt 3](#nuxt-3)
   - [Fastify](#fastify)
-  - [NestJS](#nestjs)
   - [Koa](#koa)
+  - [NestJS](#nestjs)
   - [Hapi](#hapi)
-- [Firewall -- Automatic IP Blocking](#firewall--automatic-ip-blocking)
-- [Environment Variables Reference](#environment-variables-reference)
+  - [h3, Polka, raw HTTP, Hono, Feathers](#h3-unjs)
+  - [Next.js](#nextjs)
+  - [Nuxt 3 and 4](#nuxt-3-and-4)
+  - [Vite and Bun](#vite)
+  - [Compatibility Matrix](#compatibility-matrix)
+- [Firewall -- Automatic IP Blocking](#firewall----automatic-ip-blocking)
+- [Credentials Configuration](#credentials-configuration)
+- [Entry Points Reference](#entry-points-reference)
 - [Logging Setup](#logging-setup)
 - [Request Body Capture](#request-body-capture)
+- [Custom Security Events](#custom-security-events)
+- [Session Revocation](#session-revocation)
+- [Deployment](#deployment)
 - [Advanced Configuration](#advanced-configuration)
 - [TypeScript Support](#typescript-support)
 - [Troubleshooting](#troubleshooting)
@@ -50,7 +59,7 @@ OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt application
 ## Installation
 
 ```bash
-npm install securenow
+npm install securenow@latest
 ```
 
 Or with yarn:
@@ -71,7 +80,7 @@ Run login - it is a browser flow that picks or creates an app and connects the f
 npx securenow login
 ```
 
-During the browser step, the dashboard enables the selected app's firewall toggle, mints a one-time plaintext runtime API key scoped to that app only (scopes: `traces:write`, `logs:write`, `firewall:read`, `blocklist:read`, `allowlist:read`), and the CLI writes it as `apiKey` in `.securenow/runtime.json`. Admin auth, when part of the flow, is saved separately to `.securenow/admin.json`. Traces, logs, POST body capture, multipart metadata capture, and firewall protection are enabled by default. No env vars, no copy-pasting keys.
+During the browser step, the dashboard enables the selected app's firewall toggle, mints a one-time plaintext runtime API key scoped to that app only (scopes: `traces:write`, `logs:write`, `firewall:read`, `blocklist:read`, `allowlist:read`), and the CLI writes it as `apiKey` in `.securenow/runtime.json`. Admin auth, when part of the flow, is saved separately to `.securenow/admin.json`. Both files are added to `.gitignore` (without ignoring the whole `.securenow/` folder). Traces, logs, POST body capture, multipart metadata capture, and firewall protection are enabled by default. No env vars, no copy-pasting keys.
 
 Metrics export is intentionally off by default. SecureNow sets `OTEL_METRICS_EXPORTER=none` when the app has not explicitly configured metrics, preventing the OpenTelemetry SDK from creating a default metrics reader that retries `localhost:4318`.
 
@@ -84,10 +93,11 @@ npx securenow init --key snk_live_abc123...
 ```
 
 This detects your framework and:
-- **Credentials**: Ensures `.securenow/runtime.json` has secure defaults and explanations
-- **Next.js**: Creates `instrumentation.ts`, adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, or prints a Codex/Claude-ready merge prompt for existing files
-- **Nuxt 3**: Suggests adding `securenow/nuxt` to modules
+- **Credentials**: Ensures `.securenow/runtime.json` has secure defaults and explanations, with `config.runtime.deploymentEnvironment` set to `local` (change it with `--env staging`, etc.)
+- **Next.js**: Creates `instrumentation.ts` (`src/instrumentation.ts` in a `src/` layout, 8.25.0+), adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, or prints a Codex/Claude-ready merge prompt for existing files. Next.js 14 gets the `experimental` keys **(8.25.0+)**
+- **Nuxt 3 and 4**: Reminds you to add `securenow/nuxt` to modules
 - **Express / Node.js**: Shows how to add `-r securenow/register` to your start script
+- **PM2**: Warns when an ecosystem file passes a bare `-r securenow/register`
 - **All**: Stores an optional `--key` in `.securenow/runtime.json`; no local `.env` file is needed. If the runtime API key is missing, run `npx securenow app connect` or `npx securenow api-key create` before sending telemetry.
 
 ### 2. Manual Setup
@@ -104,7 +114,7 @@ Add `-r securenow/register` to your start command -- that's the only change:
 node -r securenow/register app.js
 ```
 
-ESM and CJS apps are both handled automatically (Node >=20.6 auto-registers the ESM loader hook via `module.register()`).
+ESM and CJS apps are both handled automatically: for an ESM app (`"type": "module"` or an `.mjs` entry) the preload registers the OpenTelemetry ESM loader hook with `module.register()` (Node >= 20.6) and prints `[securenow] ESM loader hook auto-registered (module.register)`. TypeScript: `node -r securenow/register --import tsx src/index.ts`, or `node -r securenow/register -r ts-node/register src/index.ts`.
 
 **package.json** example:
 
@@ -121,6 +131,14 @@ ESM and CJS apps are both handled automatically (Node >=20.6 auto-registers the
 NODE_OPTIONS="-r securenow/register" npm start
 ```
 
+Every Node process started with that variable loads SecureNow, npm itself included, so the flag in the start script is cleaner when you can edit it.
+
+**Alternative: the CLI wrapper**
+
+```bash
+npx securenow run app.js        # adds the preload (and the ESM hook for ESM apps), passes Node flags through
+```
+
 **CJS only: Code-based initialization**
 
 ```javascript
@@ -132,21 +150,31 @@ const app = express();
 // ...
 ```
 
+In an ESM app, don't `import 'securenow/register'` inside your code: static imports load before it runs, so libraries are not instrumented. Use the `-r` flag.
+
 You'll see confirmation in the console:
 
 ```
-[securenow] OTel SDK started -> https://ingest.securenow.ai/v1/traces
+[securenow] preload loaded pid=48211
+[securenow] pid=48211 appId="<app-uuid>" instance="https://ingest.securenow.ai" apiKey=set credentials=/srv/app/.securenow/runtime.json → service.name=<app-uuid> instance.id=<app-uuid>-<uuid>
+[securenow] OTel SDK started → https://ingest.securenow.ai/v1/traces
+[securenow] Logging: ENABLED → https://ingest.securenow.ai/v1/logs
+[securenow] Request body capture: ENABLED (max: 10240 bytes, redacting 68 sensitive fields)
 [securenow] Firewall: ENABLED
-[securenow] Firewall: synced 142 blocked IPs (138 exact + 4 CIDR ranges)
+[securenow] Firewall: environment=local
+[securenow] Firewall: Layer 1 (HTTP 403)      active
+[securenow] Firewall: synced 142 global blocked IPs (138 exact + 4 CIDR ranges) and 0 scoped block rules
 ```
 
+`credentials=` names the file (or `env:SECURENOW_CREDENTIALS`) the settings came from; `service.name` must be your app key.
+
 ---
 
 ## CLI -- Command Line Interface
 
-The `securenow` CLI gives you full access to the SecureNow platform from the terminal -- no browser required for day-to-day workflows. Zero additional dependencies.
+The `securenow` CLI gives you full access to the SecureNow platform from the terminal -- no browser required for day-to-day workflows. Zero additional dependencies. `npx securenow help` lists every command and `npx securenow help <command>` its subcommands and flags (offline). [`SKILL-CLI.md`](./SKILL-CLI.md) organizes the commands by task.
 
-**Full CLI/SDK parity:** every SDK export has a matching CLI command. `redactSensitiveData` -> `securenow redact`, `createMatcher` -> `securenow cidr match`, `getLogger().emit()` -> `securenow log send`, startup smoke spans -> `securenow test-span`, `node -r securenow/firewall-only` -> `securenow run --firewall-only`. False-positive triage (`fp create`, `fp ai-fill`, `fp mark`) works from the terminal without the web dashboard.
+**CLI/SDK parity:** SDK helpers have matching CLI commands. `redactSensitiveData` -> `securenow redact`, `createMatcher` -> `securenow cidr match`, `getLogger().emit()` -> `securenow log send`, `track()` -> `securenow event send`, startup smoke spans -> `securenow test-span`, `node -r securenow/firewall-only` -> `securenow run --firewall-only`. False-positive triage (`fp create`, `fp ai-fill`, `fp mark`) works from the terminal without the web dashboard.
 
 ### Getting Started
 
@@ -156,7 +184,7 @@ npx securenow login
 
 # Admin/control-plane CLI and MCP auth only.
 npx securenow admin login
-npx securenow admin login --token <YOUR_JWT>
+npx securenow admin login --token <YOUR_TOKEN>
 
 # App/runtime SDK config only.
 npx securenow app connect
@@ -164,7 +192,7 @@ npx securenow app connect
 # Save to ~/.securenow/ instead of this project
 npx securenow login --global
 
-# Check who you're logged in as (shows auth source)
+# Check who you're logged in as (admin auth and runtime app)
 npx securenow whoami
 
 # Need or already have a runtime API key? Create or store it without re-running login:
@@ -182,9 +210,12 @@ npx securenow init
 
 # Optional: pass an existing runtime API key to store it in .securenow/runtime.json
 npx securenow init --key snk_live_abc123...
+
+# Force the instrumentation file language
+npx securenow init --typescript   # or --javascript
 ```
 
-For Next.js projects, `init` creates `instrumentation.ts` (or `.js` if no TypeScript), adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, and prints exact merge instructions for Codex/Claude when existing files need judgment. For Nuxt, it suggests adding `securenow/nuxt` to your modules. For Express/Node, it shows the `-r securenow/register` flag.
+For Next.js projects, `init` creates `instrumentation.ts` (or `.js` if no TypeScript), adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, and prints exact merge instructions for Codex/Claude when existing files need judgment. For Nuxt, it reminds you to add `securenow/nuxt` to your modules. For Express/Node, it shows the `-r securenow/register` flag.
 
 ### MCP for Codex and Claude
 
@@ -192,14 +223,17 @@ SecureNow includes a local stdio MCP server that resolves credentials by operati
 
 ```bash
 npx securenow login
+claude mcp add securenow -- npx securenow mcp
 codex mcp add securenow -- npx securenow mcp
-# or
+# or run the bin directly
 npx -p securenow securenow-mcp
 ```
 
-Admin/global tools use `.securenow/admin.json`. App-scoped runtime reads can use `.securenow/runtime.json` or an explicit app key. The MCP surface exposes tools for applications, traces, logs, firewall, IP intelligence, forensics, notifications, blocklist, allowlist, trusted IPs, rate-limit remediation, and docs-backed prompts/resources. Write actions require `confirm:true` and a reason. Use `securenow_blocklist_unblock` to stop firewall enforcement while keeping the block report/history; `securenow_blocklist_remove` is a compatibility alias.
+Cursor uses `.cursor/mcp.json`: `{ "mcpServers": { "securenow": { "command": "npx", "args": ["securenow", "mcp"] } } }`.
 
-For hosted clients, SecureNow can expose the same surface at `https://api.securenow.ai/mcp`. The hosted endpoint uses the same API authentication and scope checks as the rest of SecureNow.
+Admin/global tools use `.securenow/admin.json`. App-scoped runtime reads can use `.securenow/runtime.json` or an explicit app key. The MCP surface exposes tools for applications, traces, logs, firewall, IP intelligence, forensics, notifications, both review queues, alert rules, starter protection, blocklist, allowlist, trusted IPs, rate limits, challenges, automations, and docs-backed prompts/resources. Write actions require `confirm:true` and a reason. Use `securenow_blocklist_unblock` to stop firewall enforcement while keeping the block report/history; `securenow_blocklist_remove` is a compatibility alias. `npx securenow mcp --profile investigator|detection|responder` serves a smaller tool set. Session revocation has no MCP tool: use `securenow revoke`.
+
+For hosted clients, the same surface is at `https://api.securenow.ai/mcp`, with OAuth sign-in (or `Authorization: Bearer <API key>`), e.g. `claude mcp add --transport http securenow https://api.securenow.ai/mcp`. The hosted endpoint uses the same API authentication and scope checks as the rest of SecureNow.
 
 ### Managing Applications
 
@@ -220,12 +254,23 @@ npx securenow apps default <app-key>
 npx securenow apps delete <app-id> --force
 ```
 
+### Overview and attackers
+
+```bash
+# The dashboard's Overview: what happened, what SecureNow did, what needs you
+npx securenow today
+npx securenow today --since 7d --attackers 20
+
+# Why an address was flagged: verdict, signals, traffic vs normal, detections, timeline
+npx securenow attacker 203.0.113.42
+```
+
 ### Viewing Traces
 
 ```bash
 # List recent traces (uses default app, or specify --app)
 npx securenow traces
-npx securenow traces --app <key> --limit 50
+npx securenow traces --app <key> --env production --limit 50
 
 # Show detailed spans for a trace
 npx securenow traces show <traceId>
@@ -239,10 +284,13 @@ npx securenow traces analyze <traceId>
 ```bash
 # List recent logs
 npx securenow logs
-npx securenow logs --app <key> --minutes 30 --level error
+npx securenow logs --app <key> --since 30m --level error
 
 # Show logs for a specific trace
 npx securenow logs trace <traceId>
+
+# What is failing: error lines grouped by message
+npx securenow logs errors --since 6h
 ```
 
 ### Notifications
@@ -250,6 +298,7 @@ npx securenow logs trace <traceId>
 ```bash
 # List notifications
 npx securenow notifications
+npx securenow notifications list --search "SQL injection" --severity high
 
 # Check unread count
 npx securenow notifications unread
@@ -259,30 +308,24 @@ npx securenow notifications read <id>
 npx securenow notifications read-all
 ```
 
-### Alerting
+The two review queues: `npx securenow review` (Alert Review: "is this rule right?") and `npx securenow human` (Requires Human: block, false positive or close). See SKILL-CLI.md.
 
-### Revoke / kill sessions (new in 8.3)
+### Alerting
 
-```js
-const securenow = require('securenow/sessions');
-// One line: emits session.seen (feeds impossible-travel / concurrent-session
-// detection) AND rejects revoked sessions. Auto-detects NextAuth/connect.sid/JWT.
-app.use(securenow.guard());
-// ...or check manually:
-if (securenow.isRevoked({ sessionId, userId })) return res.status(401).send('re-auth');
-// ...or emit-only (detection without enforcement):
-app.use(securenow.capture());
-```
+#### Revoke / kill sessions
 
-Revoke from the CLI (the SDK enforces within ~seconds, outbound-only, fail-open):
+Revoke from the CLI; the SDK enforces it within 30 seconds (outbound sync, fail-open):
 
 ```bash
 npx securenow revoke session <session-id> --reason "impossible travel"
 npx securenow revoke user <user-id> --duration 7d        # kill all of a user's sessions
 npx securenow revoke list
+npx securenow revoke restore <revocation-id>
 ```
 
-### Emit custom security events (new in 8.2)
+How the app enforces it (zero-code config **(8.25.0+)**, `guard()` middleware, or `check()` **(8.25.0+)**): [Session Revocation](#session-revocation).
+
+#### Emit custom security events
 
 ```js
 const { track } = require('securenow/events');
@@ -296,19 +339,19 @@ track('auth.login.success', {
 });
 ```
 
-Events become queryable by alert rules immediately (`attributes_string['event.type']`, `['enduser.id']`, `['session.id']`, `['http.client_ip']`). Non-JS apps emit the same thing with a plain POST to `/v1/events`:
+Events become queryable by alert rules immediately (`attributes_string['event.type']`, `['enduser.id']`, `['session.id']`, `['http.client_ip']`). Non-JS apps emit the same thing with a plain POST to `/v1/events` on the ingest gateway:
 
 ```
-POST https://<your-ingest-host>/v1/events
+POST https://ingest.securenow.ai/v1/events
 Authorization: Bearer snk_live_...
 X-SecureNow-App-Key: <app-uuid>
 
 { "events": [ { "type": "auth.login.success", "user_id": "u_1", "session_id": "s_1", "ip": "1.2.3.4" } ] }
 ```
 
-CLI: `npx securenow event send auth.login.failure --user u_1 --ip 1.2.3.4 --attrs reason=bad_token`
+CLI: `npx securenow event send auth.login.failure --user u_1 --ip 1.2.3.4 --attrs reason=bad_token`. More in [Custom Security Events](#custom-security-events).
 
-### Build alert SQL from the installed telemetry contract
+#### Build alert SQL from the installed telemetry contract
 
 The NPM package ships the exact ClickHouse table/field contract used for alert-rule authoring.
 Agents should read it instead of guessing SQL columns:
@@ -338,13 +381,20 @@ Mark detections `NEEDS_INSTRUMENTATION` when the repository must add a `track()`
 verification plus SQL validation. See `node_modules/securenow/TELEMETRY-SQL.md` for tables,
 timestamp handling, privacy rules, templates, and the full test-to-production lifecycle.
 
+#### Rules from English, SQL rules, runs
+
 ```bash
-# Describe a detection in English (new in 8.16): SecureNow picks an instant rule (every request,
+# Describe a detection in English: SecureNow picks an instant rule (every request,
 # as it arrives) or a periodic one (SQL on a schedule), writes it from your app's real data,
 # checks it against that data, and creates it in test mode when you confirm
 npx securenow alerts rules from-text "a sign-in from a new address, then a password change within 5 minutes" --app <app-key>
+npx securenow alerts rules from-text "one IP failing 10 sign-ins in 5 minutes" --app <app-key> --draft-only
+
+# Test it: dry run on real data, or live with 6 synthetic attack requests
+npx securenow alerts rules test <rule-id> --wait
+npx securenow alerts rules test <rule-id> --mode live --wait
 
-# Create a custom detection rule from your own SQL (new in 8.1)
+# Create a custom detection rule from your own SQL
 npx securenow alerts rules create \
   --name "Auth: magic-link brute force" \
   --sql @rule.sql \
@@ -352,11 +402,17 @@ npx securenow alerts rules create \
   --severity high \
   --nlp "single IP flooding /api/auth/signin or /api/auth/callback"
 
-# What each run did, run one now, and why a rule didn't alert on an address (new in 8.17)
+# What each run did, run one now, and why a rule didn't alert on an address
 npx securenow alerts rules runs <rule-id>
 npx securenow alerts rules run <rule-id>
 npx securenow alerts rules why <rule-id> --ip 203.0.113.50 --since 2h
 
+# Rewrite from English, check precision, promote (a person) or ask for promotion (an agent)
+npx securenow alerts rules change <rule-id> "raise the threshold to 20"
+npx securenow alerts rules quality <rule-id>
+npx securenow alerts rules promote <rule-id> --yes
+npx securenow alerts rules request-promotion <rule-id> --reason "Quiet for a week, caught the replayed attack"
+
 # View / manage alert rules, channels, and history
 npx securenow alerts rules
 npx securenow alerts rules show <rule-id>
@@ -368,7 +424,17 @@ npx securenow alerts channels
 npx securenow alerts history --limit 20
 ```
 
-Your detection SQL scopes app keys with the `__USER_APP_KEYS__` placeholder and selects an `ip` column for per-IP aggregation and remediation (SQL without one is refused: it would never notify). SecureNow stores the query, runs it once right away and then on the rule's schedule (default every 15 min), and routes matches to your in-app channel (override with `--channel <id>`). The throttle sends one alert per address every 15 minutes by default; other addresses still alert. Requires an API key with `alerts:write`.
+Your detection SQL scopes app keys with the `__USER_APP_KEYS__` placeholder and selects an `ip` column for per-IP aggregation and remediation (SQL without one is refused: it would never notify). SecureNow stores the query, runs it once right away and then on the rule's schedule (default every 15 min), and routes matches to your in-app channel (override with `--channel <id>`). The throttle sends one alert per address every 15 minutes by default; other addresses still alert. New rules start in test mode (alerts only: no instant block, automation or agent action) until promoted. Requires an API key with `alerts:write`.
+
+#### Starter protection
+
+```bash
+npx securenow protect                    # mode, rules, alerts, ready to block?
+npx securenow protect block --app <key>  # a signed-in person turns blocking on
+npx securenow protect monitor --app <key>
+```
+
+Every app gets about 20 starter rules in monitor mode on first traffic. Blocking is refused while more than 20% of the app's traffic arrives through a proxy the SDK doesn't trust.
 
 ### IP Intelligence & Blocklist
 
@@ -382,6 +448,7 @@ npx securenow ip traces 203.0.113.42
 # Manage the blocklist
 npx securenow blocklist
 npx securenow blocklist add 203.0.113.42 --reason "Brute force scanner"
+npx securenow blocklist add 203.0.113.42 --route /admin --mode prefix --duration 24h --reason "Admin probing"
 npx securenow blocklist unblock <id> --reason "Reviewed as safe"
 npx securenow blocklist remove <id>          # compatibility alias
 npx securenow blocklist list --status removed
@@ -393,6 +460,25 @@ npx securenow trusted add 10.0.0.1 --label "Office VPN"
 npx securenow trusted remove <id>
 ```
 
+### Rate Limits & Challenges
+
+```bash
+# Rate limits (429 + Retry-After), applied by running apps within about 10 seconds
+npx securenow ratelimit add --route /api/login --method POST --limit 5 --window 1m --env production
+npx securenow ratelimit add --route /api/ --limit 100 --window 1m --header x-api-key
+npx securenow ratelimit from-text "5 per minute per IP on POST /api/login for 2h" --yes
+npx securenow ratelimit test 203.0.113.42 --path /api/login --method POST
+npx securenow ratelimit list
+
+# Proof-of-work challenges (browsers solve it invisibly; a pass lasts 30 minutes by default)
+npx securenow challenge add --route /login --clearance 30m
+npx securenow challenge test 203.0.113.42 --path /login
+npx securenow challenge list
+
+# Who the firewall stopped
+npx securenow firewall hits --since 1h
+```
+
 ### Forensic Queries
 
 Ask questions in plain English -- the AI translates them to SQL and runs them against your data.
@@ -402,20 +488,15 @@ Ask questions in plain English -- the AI translates them to SQL and runs them ag
 npx securenow forensics "show top 10 attacking IPs in the last hour"
 npx securenow forensics "which endpoints had 5xx errors today"
 
+# Chat with memory: follow-ups see earlier answers
+npx securenow forensics chat --app <key> "which accounts had failed logins then a success?"
+npx securenow forensics chat --conversation <id> "what else did those IPs do?"
+npx securenow forensics conversations
+
 # Browse the saved query library
 npx securenow forensics library
 ```
 
-### API Map
-
-```bash
-# View all discovered API endpoints
-npx securenow api-map
-
-# API map statistics
-npx securenow api-map stats
-```
-
 ### Analytics & Dashboard
 
 ```bash
@@ -424,6 +505,7 @@ npx securenow analytics --app <key>
 
 # Full dashboard overview (apps, protection status, unread alerts)
 npx securenow status
+npx securenow status --env all
 ```
 
 ### Instances
@@ -467,28 +549,31 @@ npx securenow fp edit <id> --active false
 npx securenow fp delete <id> --yes
 ```
 
-### Telemetry -- Emit Logs and Spans From the Shell
+### Telemetry -- Emit Logs, Events 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**.
+Mirrors the SDK's `getLogger()`, `track()` and tracing APIs. Useful for cron jobs, shell scripts, CI pipelines and non-JS services that need to push data into SecureNow **without booting the full OTel SDK**.
 
 ```bash
-# Send a structured log record to your OTLP collector
+# Send a structured log record
 npx securenow log send "Deployment completed" --level info --attrs version=1.2.3,service=api
 npx securenow log send "Backup failed" --level error --attrs host=db-01
 
-# Emit a test span to verify the collector accepts OTLP traffic
+# Send a custom security event (same as track())
+npx securenow event send auth.login.failure --user u_1 --ip 203.0.113.10 --attrs reason=bad_password
+
+# Emit a test span to verify the ingest accepts OTLP traffic
 npx securenow test-span
 npx securenow test-span "ci.smoke-test"          # custom span name
 ```
 
-Both commands use the resolved credentials JSON endpoints and headers. Non-zero exit on HTTP errors so CI/cron can detect failures.
+All three use the resolved runtime credentials (file or `SECURENOW_CREDENTIALS`) and exit non-zero on HTTP errors so CI/cron can detect failures.
 
 ### Utilities -- Redaction, CIDR, Diagnostics
 
 SDK helpers surfaced as CLI commands so agents (and humans) can validate behavior without writing Node.
 
 ```bash
-# Redact sensitive fields (password, token, card, ssn, etc.)
+# Redact sensitive fields (password, token, email, card, OTP codes, etc.)
 npx securenow redact '{"user":"alice","password":"s3cret","card":"4242"}'
 npx securenow redact @request.json --fields internal_id,sessionHash
 
@@ -503,6 +588,10 @@ npx securenow env --json          # pipe to jq
 # End-to-end diagnostic: probe OTLP + API endpoints
 npx securenow doctor              # exits 0 if healthy, 1 otherwise
 npx securenow doctor --json
+
+# Threat-modeling prompts for your coding agent
+npx securenow threat-model --list
+npx securenow threat-model authentication --out threat-prompt.md
 ```
 
 ### Configuration
@@ -514,7 +603,6 @@ npx securenow config get
 # Set values
 npx securenow config set apiUrl https://custom-api.example.com
 npx securenow config set defaultApp <app-key>
-npx securenow config set format json
 
 # Show config file paths
 npx securenow config path
@@ -524,15 +612,15 @@ Config files are stored in `~/.securenow/` (global) or `.securenow/` in the proj
 
 | File | Description |
 |------|-------------|
-| `~/.securenow/config.json` | API URL, default app, output format |
+| `~/.securenow/config.json` | API URL, dashboard URL, default app |
 | `~/.securenow/admin.json` | Global admin/control-plane CLI and MCP auth |
 | `~/.securenow/runtime.json` | Global SDK runtime app config and runtime API key |
 | `.securenow/admin.json` | Project-local admin/control-plane CLI and MCP auth |
 | `.securenow/runtime.json` | Project-local SDK runtime app config and runtime API key |
-| `.securenow/credentials.json` | Legacy combined credentials; still read for backward compatibility |
+| `.securenow/credentials.json` | Legacy combined credentials, or the production runtime file mounted on a server |
 | `.securenow/credentials.<environment>.json` | Tokenless runtime credentials generated by `credentials runtime --env <environment>`; read in a fixed order, not selected from env vars |
 
-**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`. Legacy CLI token overrides still work for existing automation.
+**Resolution order:** the SDK reads `SECURENOW_CREDENTIALS` first. Otherwise, starting from the working directory and the entry script's folder (under PM2, the app folder PM2 recorded) and walking up through parent folders, the first file found wins, checked in this order in each folder: `.securenow/runtime.json`, `.securenow/credentials.json`, then named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order. Then the same names in `~/.securenow/`. Files are never merged. Admin auth resolves from `admin.json` first, then legacy `credentials.json`.
 
 ### Global Flags
 
@@ -542,16 +630,20 @@ Every command supports these flags:
 |------|-------|-------------|
 | `--json` | `-j` | Output as JSON for scripting and CI/CD |
 | `--help` | | Show help for the command |
-| `--app <key>` | | Override the default application key |
+| `--yes` | `-y` | Confirm a write without the prompt |
+
+Most commands also accept `--app <key>` (target another app) and `--env <environment>` (default `production` for security commands).
 
 ### CLI Configuration
 
-Normal SDK runtime setup uses `.securenow/runtime.json`; admin CLI/MCP auth uses `.securenow/admin.json`.
-SecureNow-specific environment overrides are no longer supported by the SDK or CLI.
+Normal SDK runtime setup uses `.securenow/runtime.json`; admin CLI/MCP auth uses `.securenow/admin.json`. The SDK reads only `SECURENOW_CREDENTIALS` and `SECURENOW_DISABLED` from the environment; every other `SECURENOW_*` variable is ignored.
 
-| Override | Description |
+| Variable | Description |
 |----------|-------------|
 | `NO_COLOR` | Disable colored CLI output |
+| `SECURENOW_MCP_PROFILE` | MCP tool profile (`investigator`, `detection`, `responder`), same as `securenow mcp --profile` |
+| `SECURENOW_CREDENTIALS` | Runtime credentials JSON (raw or base64) for the SDK and for `env`, `doctor`, `test-span`, `log send`, `event send` |
+| `SECURENOW_DISABLED` | `1` turns the SDK off in that process (test runs) |
 
 ### Multi-Project Sessions
 
@@ -580,10 +672,18 @@ npx securenow credentials runtime --env production
 
 # Store .securenow/credentials.production.json as a deployment secret file,
 # then materialize it as .securenow/credentials.json in the running app.
-# Since v7.7.2, mounting it as .securenow/credentials.production.json
-# also works when the canonical credentials.json file is absent.
+# Mounting it as .securenow/credentials.production.json also works when no
+# other credentials file is present (a runtime.json or credentials.json
+# next to it would win).
 # The SDK checks named files in a fixed order and does not use env vars
 # to pick the credentials filename.
+# Hosts without file mounts (Vercel, Railway, Render, Heroku, Fly):
+npx securenow credentials runtime --env production --format env
+# -> SECURENOW_CREDENTIALS=<base64>; store it as a secret environment variable.
+#    It takes precedence over credential files.
+
+# Test runs: keep them from reporting to the real app
+SECURENOW_DISABLED=1 npm test
 
 # Use --json for machine-readable output
 npx securenow logs --json --level error | jq '.logs'
@@ -593,59 +693,77 @@ npx securenow logs --json --level error | jq '.logs'
 
 | Category | Command | Description |
 |----------|---------|-------------|
-| **Setup** | `init` | Auto-scaffold instrumentation for your framework |
+| **Setup** | `init` | Auto-scaffold instrumentation for your framework (`--env`, `--key`, `--typescript`/`--javascript`) |
+| | `run <script>` | Run a Node app with the preload (`--firewall-only`, Node flags pass through) |
 | **Auth** | `login` | Friendly onboarding: admin auth + app runtime connection |
-| | `admin login` | Authenticate admin/control-plane CLI and MCP tools |
+| | `admin login` / `admin logout` | Authenticate (or clear) admin/control-plane CLI and MCP tools |
 | | `app connect` | Select/create app and write SDK runtime config |
 | | `logout` | Clear admin auth; runtime app config remains |
 | | `whoami` | Show admin auth and runtime app status separately |
+| | `credentials runtime` | Tokenless production runtime file (`--env`, `--out`, `--stdout`, `--format env`) |
 | **Apps** | `apps` | List applications |
-| | `apps create <name>` | Create application |
+| | `apps create <name>` | Create application (`--hosts`, `--instance`) |
 | | `apps info <id>` | Application details |
 | | `apps delete <id>` | Delete application |
 | | `apps default <key>` | Set default app |
+| | `apps discover` / `apps scan` | Discover subdomains and add them as apps |
 | **API Key** | `api-key create [--name "CLI runtime"] [--app <key-or-id>] [--global]` | Mint and save a one-app `runtime_app` key with your logged-in session. Defaults to the current runtime app |
 | | `api-key set <snk_live_...> [--global]` | Save runtime API key to `.securenow/runtime.json` |
 | | `api-key show` | Show masked key + source |
 | | `api-key clear [--global]` | Remove stored key (leaves session/app) |
-| **Observe** | `traces` | List traces |
+| **Observe** | `today` | The Overview: what happened, what SecureNow did, what needs you |
+| | `attacker <ip>` | Why an address was flagged |
+| | `traces` | List traces |
 | | `traces show <id>` | Trace details |
 | | `traces analyze <id>` | AI trace analysis |
 | | `logs` | List logs |
 | | `logs trace <id>` | Logs for a trace |
+| | `logs errors` | Error lines grouped by message |
 | | `analytics` | Response analytics |
 | | `status` | Dashboard overview |
-| **Detect** | `notifications` | List notifications |
+| **Detect** | `protect` | Starter protection: `status`, `enable`, `disable`, `block`, `monitor`, `learn` |
+| | `notifications` | List notifications |
 | | `notifications unread` | Unread count |
 | | `notifications read <id>` | Mark read |
 | | `notifications read-all` | Mark all read |
+| | `review` | Alert Review: `list`, `show`, `keep`, `close`, `dismiss`, `group` |
+| | `human` | Requires Human: `list`, `show`, `block`, `fp`, `close`, `report`, `action`, `prompt`, `work`, `promotions`, `approve-promotion`, `deny-promotion` |
+| | `agent` | The autonomous agent: `status`, `on`, `off`, `mode`, `activity`, `undo`, `runs`, `run`, `verify`, `prompt`, `prompts` |
 | | `alerts rules` | List rules (status, apps, schedule) |
+| | `alerts rules from-text "<english>" --app <key>` | Draft, check and create a rule from English (test mode) |
+| | `alerts rules create` | Create a rule from SQL (`--sql`) or instant conditions (`--conditions`) |
 | | `alerts rules show <id>` | Rule detail |
 | | `alerts rules update <id> --applications-all` / `--apps k1,k2` | Application scope |
+| | `alerts rules test <id> [--mode live] --wait` | Dry run, or live with synthetic attacks |
 | | `alerts rules runs <id>` / `run <id>` | Run history (outcome of each run) / run a periodic rule now |
 | | `alerts rules why <id> --ip <ip>` | Why the rule did or didn't alert on an address |
+| | `alerts rules change <id> "<english>"` | Rewrite a rule from English as a new version |
+| | `alerts rules promote <id>` / `demote <id>` | Test mode to prod and back (a person) |
+| | `alerts rules request-promotion <id>` | Ask a person to promote (agents) |
+| | `alerts rules validate --sql @rule.sql --app <key>` | Dry-run candidate SQL |
 | | `alerts channels` | Alert channels |
 | | `alerts history` | Alert history |
 | **Investigate** | `ip <addr>` | IP intelligence |
 | | `ip traces <addr>` | Traces from IP |
 | | `forensics "<query>"` | NL forensic query |
+| | `forensics chat` / `forensics conversations` | Forensics chat with memory |
 | | `forensics library` | Saved queries |
-| | `api-map` | API endpoints |
-| | `api-map stats` | API stats |
-| **Firewall** | `firewall status` | Firewall status and API key info |
+| **Firewall** | `firewall status` | Firewall status and layers |
+| | `firewall apps` | Apps with their firewall on/off state |
+| | `firewall enable` / `firewall disable` | Per-app, per-environment toggle |
 | | `firewall test-ip <ip>` | Check if an IP would be blocked |
+| | `firewall hits` | Blocks, 429s and challenges per rule and per IP |
 | | `run --firewall-only <script>` | Preload firewall without OTel tracing overhead |
 | **Remediate** | `blocklist` | Blocked IPs |
-| | `automation` | List blocklist automation rules |
-| | `automation dry-run <id>` | Preview automation matches without writing blocks |
-| | `automation execute <id> --yes` | Run an automation rule now |
-| | `blocklist add <ip>` | Block IP |
+| | `blocklist add <ip>` | Block IP (`--route`, `--mode`, `--method`, `--duration`, `--reason`) |
 | | `blocklist unblock <id>` | Unblock IP and retain report/history |
 | | `blocklist remove <id>` | Compatibility alias for unblock |
+| | `blocklist approve <id>` / `blocklist reject <id>` | Decide a pending block |
 | | `blocklist stats` | Block stats |
-| | `ratelimit parse "<request>"` | Fill a rate-limit draft from natural language |
-| | `ratelimit from-text "<request>" --yes` | Create a soft rate-limit rule from natural language |
-| | `ratelimit test <ip> --path /api/login` | Check whether a request would match rate-limit rules |
+| | `automation` | List blocklist automation rules (`defaults`, `show`, `create`, `update`, `dry-run`, `execute`, `delete`) |
+| | `ratelimit add` / `from-text` / `parse` / `test` / `list` / `enable` / `disable` / `remove` | Rate-limit rules (alias `rate-limit`) |
+| | `challenge add` / `test` / `list` / `enable` / `disable` / `remove` | Proof-of-work challenge rules |
+| | `revoke session <id>` / `revoke user <id>` / `revoke list` / `revoke restore <id>` | Session revocation |
 | | `allowlist` | Allowed IPs (restrict-mode) |
 | | `allowlist add <ip>` | Allow IP (`--label`, `--reason`) |
 | | `allowlist remove <id>` | Remove from allowlist |
@@ -662,17 +780,21 @@ npx securenow logs --json --level error | jq '.logs'
 | | `fp dry-run --conditions '[...]'` | Dry-run against last 3 days of traces |
 | | `fp ai-fill --description "..."` | AI-generate exclusion conditions |
 | | `fp mark <notification-id> <ip>` | Mark an IP as FP on a notification |
-| **Telemetry** | `log send "<msg>" --level info --attrs k=v` | Emit an OTLP log record |
+| **Telemetry** | `telemetry schema` / `telemetry fields` | Alert-SQL contract and fields observed for an app |
+| | `log send "<msg>" --level info --attrs k=v` | Emit an OTLP log record |
+| | `event send <type> --user <id> --ip <ip>` | Emit a custom security event |
 | | `test-span [<name>]` | Emit a test span to the collector |
 | **Utilities** | `redact '<json>' [--fields f1,f2]` | Redact sensitive fields (accepts `@file.json`) |
 | | `cidr match <ip> <cidrs>` | IP vs. CIDR list (exit 0 hit / 2 miss) |
 | | `cidr parse <cidr>` | Parse CIDR (network, broadcast, mask, size) |
 | | `env [--json]` | Show resolved config (service name, endpoints, credentials) |
 | | `doctor [--json]` | Probe OTLP + API endpoints, check config |
+| | `threat-model <category>` | Print a threat-modeling prompt (`--list`, `--out`) |
+| | `mcp [--profile <name>]` | Start the MCP server over stdio |
 | **Settings** | `instances` | List instances |
 | | `instances test <id>` | Test connection |
 | | `config get` | Show config |
-| | `config set <k> <v>` | Set config value |
+| | `config set <k> <v>` | Set config value (`apiUrl`, `appUrl`, `defaultApp`) |
 | | `config path` | Config file paths |
 | | `version` | Show version |
 
@@ -680,8 +802,10 @@ npx securenow logs --json --level error | jq '.logs'
 
 ## Framework-Specific Setup
 
-> **v5.6.0+:** When `config.logging.enabled` is `true`, all `console.log`/`warn`/`error`/`info`/`debug` calls
-> are **automatically** forwarded as OTLP log records. The separate `require('securenow/console-instrumentation')` is no longer needed (but still available for backward compat).
+> When `config.logging.enabled` is `true` (the default), all `console.log`/`warn`/`error`/`info`/`debug` calls
+> are **automatically** forwarded as OTLP log records. No extra require is needed.
+
+Every server below runs on `node:http`, so one preload covers it: `node -r securenow/register <entry>`. In a CommonJS entry, `require('securenow/register')` as the very first line is equivalent. The examples contain no SecureNow code.
 
 ### Express.js
 
@@ -691,7 +815,6 @@ npm install securenow express
 
 ```javascript
 // app.js
-require('securenow/register');
 const express = require('express');
 
 const app = express();
@@ -708,9 +831,11 @@ app.listen(3000, () => console.log('Express running on port 3000'));
 ```
 
 ```bash
-node app.js
+node -r securenow/register app.js
 ```
 
+Express 4 and 5 record `http.route`. One span per middleware is off by default (`config.otel.middlewareSpans: true` turns it on).
+
 #### With PM2
 
 ```javascript
@@ -719,12 +844,17 @@ module.exports = {
   apps: [{
     name: 'my-app',
     script: './app.js',
-    node_args: '-r securenow/register',
+    cwd: __dirname,
+    instances: 'max', // or leave out for fork mode
+    // An absolute path, resolved when PM2 loads this file: in cluster mode Node resolves a bare
+    // '-r securenow/register' from the PM2 daemon's folder, so workers started by `pm2 resurrect`
+    // at boot crash-loop with "Cannot find module 'securenow/register'".
+    node_args: ['-r', require.resolve('securenow/register')],
   }]
 };
 ```
 
-> **Important:** Put `.securenow/runtime.json` in the PM2 app root for local/dev deployments, or mount the production runtime export as `.securenow/credentials.json`. Keep `node_args: '-r securenow/register'`. PM2 restarts will then load the SDK, traces/logs, body capture, and firewall without any SecureNow env vars.
+> **Important:** Put `.securenow/runtime.json` in the PM2 app root for local/dev deployments, or mount the production runtime export as `.securenow/credentials.json`. PM2 restarts will then load the SDK, traces/logs, body capture, and firewall without any SecureNow env vars. Fork and cluster mode both read the app folder PM2 started (`pm_cwd`), whichever folder the PM2 daemon itself was started from (before 8.24.0 a cluster worker searched the daemon's folder and could start without credentials). After changing `node_args`, run `pm2 delete my-app && pm2 start ecosystem.config.cjs && pm2 save`.
 
 ---
 
@@ -736,7 +866,6 @@ npm install securenow fastify
 
 ```javascript
 // app.js
-require('securenow/register');
 const Fastify = require('fastify');
 const fastify = Fastify({ logger: true });
 
@@ -755,7 +884,11 @@ fastify.listen({ port: 3000 }, (err) => {
 });
 ```
 
-> **Default:** Traces, logs, POST body capture, multipart metadata capture, and firewall protection are on. If a specific Fastify version or plugin stack reports request-stream conflicts, set `config.capture.body=false` in credentials as a local override.
+```bash
+node -r securenow/register app.js
+```
+
+> **Default:** Traces, logs, POST body capture, multipart metadata capture, and firewall protection are on. The route template (`http.route`, span name `GET /tasks`) and handler exceptions are recorded through Fastify's `fastify.initialization` diagnostics channel (8.24.0+). Tested on Fastify 5.12.
 
 ---
 
@@ -767,7 +900,6 @@ npm install securenow koa @koa/router koa-bodyparser
 
 ```javascript
 // app.js
-require('securenow/register');
 const Koa = require('koa');
 const Router = require('@koa/router');
 const bodyParser = require('koa-bodyparser');
@@ -790,6 +922,12 @@ app.use(router.allowedMethods());
 app.listen(3000, () => console.log('Koa running on port 3000'));
 ```
 
+```bash
+node -r securenow/register app.js
+```
+
+`http.route` comes from `@koa/router`; body capture records what the body parser reads.
+
 ---
 
 ### NestJS
@@ -831,6 +969,8 @@ bootstrap();
 
 ```bash
 node -r securenow/register -r ts-node/register app.ts
+# compiled output (production):
+node -r securenow/register dist/main.js
 ```
 
 PM2 config:
@@ -840,7 +980,7 @@ PM2 config:
   name: 'my-nestjs-app',
   script: 'app.ts',
   interpreter: 'node',
-  node_args: '-r securenow/register -r ts-node/register',
+  node_args: ['-r', require.resolve('securenow/register'), '-r', require.resolve('ts-node/register')],
 }
 ```
 
@@ -854,7 +994,6 @@ npm install securenow @hapi/hapi
 
 ```javascript
 // app.js
-require('securenow/register');
 const Hapi = require('@hapi/hapi');
 
 const init = async () => {
@@ -878,11 +1017,15 @@ const init = async () => {
 init().catch((err) => { console.error(err); process.exit(1); });
 ```
 
-> **Default:** Traces, logs, POST body capture, multipart metadata capture, and firewall protection are on. If a specific Hapi version or payload plugin reports request-stream conflicts, set `config.capture.body=false` in credentials as a local override.
+```bash
+node -r securenow/register app.js
+```
+
+> **Default:** Traces, logs, POST body capture, multipart metadata capture, and firewall protection are on. Hapi records `http.route`. Tested on Hapi 21.4.
 
 ---
 
-### h3 (UnJS / Nitro)
+### h3 (UnJS)
 
 ```bash
 npm install securenow h3
@@ -890,7 +1033,6 @@ npm install securenow h3
 
 ```javascript
 // app.js
-require('securenow/register');
 const { createApp, createRouter, defineEventHandler, readBody, setResponseStatus, toNodeListener } = require('h3');
 const http = require('http');
 
@@ -913,6 +1055,12 @@ http.createServer(toNodeListener(app)).listen(3000, () => {
 });
 ```
 
+```bash
+node -r securenow/register app.js
+```
+
+`http.route` from the h3 router **(8.25.0+)**; before, the raw path. Nitro inside Nuxt: see [Nuxt 3 and 4](#nuxt-3-and-4).
+
 ---
 
 ### Polka
@@ -925,7 +1073,6 @@ Polka is minimalist -- no built-in body parser:
 
 ```javascript
 // app.js
-require('securenow/register');
 const polka = require('polka');
 
 function jsonBody(req, res, next) {
@@ -950,6 +1097,12 @@ polka()
   .listen(3000, () => console.log('Polka running on port 3000'));
 ```
 
+```bash
+node -r securenow/register app.js
+```
+
+Pass errors to `next(err)` (a thrown error crashes Polka). `http.route` **(8.25.0+)**.
+
 ---
 
 ### Micro / Raw HTTP
@@ -962,7 +1115,6 @@ npm install securenow
 
 ```javascript
 // app.js
-require('securenow/register');
 const http = require('http');
 
 function sendJson(res, status, body) {
@@ -990,6 +1142,12 @@ async function handler(req, res) {
 http.createServer(handler).listen(3000, () => console.log('HTTP running on port 3000'));
 ```
 
+```bash
+node -r securenow/register app.js
+```
+
+`https.createServer` and the HTTP/2 compatibility API (`'request'` event) are covered the same way; spans carry the raw path.
+
 ---
 
 ### Hono (ESM)
@@ -1022,7 +1180,7 @@ serve({ fetch: app.fetch, port: 3000 }, () => console.log('Hono running on port
 node -r securenow/register app.mjs
 ```
 
-> **Default:** Traces, logs, POST body capture, multipart metadata capture, and firewall protection are on. For Hono ESM apps, keep using the `node -r securenow/register app.mjs` preload instead of adding `require('securenow/register')` inside `.mjs` files.
+> **Default:** Traces, logs, POST body capture, multipart metadata capture, and firewall protection are on. Keep using the `node -r securenow/register app.mjs` preload instead of importing `securenow/register` inside `.mjs` files. Only Hono on `@hono/node-server` is covered (not `Bun.serve`, Deno or Workers). `http.route` **(8.25.0+)**.
 
 ---
 
@@ -1036,7 +1194,6 @@ Feathers uses Express transport -- same setup as Express:
 
 ```javascript
 // app.js
-require('securenow/register');
 const feathers = require('@feathersjs/feathers');
 const express = require('@feathersjs/express');
 const errors = require('@feathersjs/errors');
@@ -1063,6 +1220,12 @@ app.use(express.errorHandler());
 app.listen(3000, () => console.log('Feathers running on port 3000'));
 ```
 
+```bash
+node -r securenow/register app.js
+```
+
+`http.route` **(8.25.0+)**. The Koa transport works the same way.
+
 ---
 
 ### Next.js
@@ -1071,7 +1234,7 @@ Use `npx securenow init` for the current Next.js integration; it creates or prin
 
 #### Option A: `securenow init` (Recommended)
 
-The init command handles the boring parts: credentials defaults, `instrumentation.ts`, body auto-capture, `serverExternalPackages`, and standalone output tracing includes for Next 15+. If existing files are custom, it prints a Codex/Claude-ready prompt instead of guessing.
+The init command handles the boring parts: credentials defaults, `instrumentation.ts`, body auto-capture, `serverExternalPackages`, and standalone output tracing includes for Next 15+ (Next 14 **(8.25.0+)**). If existing files are custom, it prints a Codex/Claude-ready prompt instead of guessing.
 
 ```bash
 npx securenow login
@@ -1082,12 +1245,16 @@ npx securenow init
 
 ```typescript
 export async function register() {
-  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
-
-  const securenowNext = await import(/* webpackIgnore: true */ 'securenow/nextjs');
-  const registerSecureNow = securenowNext.registerSecureNow || securenowNext.default?.registerSecureNow;
-  registerSecureNow({ captureBody: true });
-  await import(/* webpackIgnore: true */ 'securenow/nextjs-auto-capture');
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const securenowNext = await import('securenow/nextjs');
+      const registerSecureNow = securenowNext.registerSecureNow || securenowNext.default?.registerSecureNow;
+      registerSecureNow({ captureBody: true });
+      await import('securenow/nextjs-auto-capture');
+    } catch (error) {
+      console.error('[securenow] SecureNow did not start; the app is running without it:', error);
+    }
+  }
 }
 ```
 
@@ -1104,11 +1271,17 @@ const nextConfig = {
 export default nextConfig;
 ```
 
-No `.env.local` is needed locally or in production. Local setup reads `.securenow/runtime.json`; production should use `npx securenow credentials runtime --env production` and mount/copy the resulting JSON as `.securenow/credentials.json`.
+No `.env.local` is needed locally or in production. Local setup reads `.securenow/runtime.json`; production should use `npx securenow credentials runtime --env production` and mount/copy the resulting JSON as `.securenow/credentials.json` (in a standalone Docker image, next to `server.js`, i.e. `.next/standalone/.securenow/credentials.json` before copying). On Vercel or another host without file mounts, run `npx securenow credentials runtime --env production --format env` and store the printed `SECURENOW_CREDENTIALS` value as a secret environment variable. On Vercel the integration uses `@vercel/otel`; that setup is not tested end to end and the firewall is not verified on Vercel serverless functions.
+
+Keep the imports inside the `nodejs` block and without `webpackIgnore`: Next.js then drops them from the Edge build and traces `securenow` and its dependencies into `output: 'standalone'`. An instrumentation file written by `init` before 8.24.0 used `webpackIgnore`, so standalone images shipped without OpenTelemetry and every request returned 500; run `npx securenow init` again to replace it.
+
+**Where the file goes:** next to `app/` or `pages/`. With a `src/` layout (`src/app`, `src/pages`), Next.js 14 and 15 only load `src/instrumentation.ts` (16 also loads a root file). From 8.25.0 `init` writes it there and moves a root file it generated before; `--src`/`--root` force the folder, `--force` replaces an existing file (the old one is kept as `.bak`).
+
+**What's covered:** HTTP server spans with client IP and redacted headers and bodies, console logs, the firewall, rate limits and challenges, for Node.js route handlers, server components and API routes. The Edge runtime is not instrumented (Edge middleware and `export const runtime = 'edge'` routes get nothing). `http.route` is on the HTTP span **(8.25.0+)**; before, Next.js 16 put it on Next's own span and Next.js 15 recorded `next.route`.
 
 #### Option B: Manual configuration
 
-If you prefer not to run `init`, manually externalize SecureNow:
+If you prefer not to run `init`, create the instrumentation file above and externalize SecureNow:
 
 ```javascript
 // next.config.js (Next.js 15+)
@@ -1121,23 +1294,25 @@ module.exports = {
 ```
 
 ```javascript
-// next.config.js (Next.js 14)
+// next.config.js (Next.js 14): all three keys live under experimental
 module.exports = {
   experimental: {
     instrumentationHook: true,
     serverComponentsExternalPackages: ['securenow'],
-  },
-  outputFileTracingIncludes: {
-    '/*': ['./node_modules/securenow/**/*'],
+    outputFileTracingIncludes: {
+      '/*': ['./node_modules/securenow/**/*'],
+    },
   },
 };
 ```
 
-**Why is this needed?** Next.js bundles server code with webpack, which can break OpenTelemetry's dynamic `require()` calls and monkey-patching. Externalizing `securenow` keeps the SDK as normal Node.js runtime code. `outputFileTracingIncludes` keeps SecureNow's runtime modules available in standalone/self-hosted output, including the firewall.
+**Why is this needed?** Next.js bundles server code with webpack or Turbopack, which can break OpenTelemetry's dynamic `require()` calls and monkey-patching. Externalizing `securenow` keeps the SDK as normal Node.js runtime code, and Next.js traces its dependencies into standalone output. `outputFileTracingIncludes` adds SecureNow's own files that are loaded at runtime, including the firewall. Next.js 15.5 and 16.4 are tested (Turbopack and webpack, `next start` and standalone); Next.js 14 is expected to work but is not tested.
+
+You don't need `securenow/nextjs-middleware` or `securenow/nextjs-wrapper` for body capture: since 8.24.0 bodies are captured at the HTTP layer, and `securenow/nextjs-auto-capture` is only a fallback.
 
 ---
 
-### Nuxt 3
+### Nuxt 3 and 4
 
 ```bash
 npm install securenow
@@ -1151,47 +1326,66 @@ export default defineNuxtConfig({
 });
 ```
 
-Local app identity, runtime API key, and secure defaults come from `.securenow/runtime.json`; production can mount the generated tokenless runtime file as `.securenow/credentials.json` or `.securenow/credentials.<env>.json`.
+Then run `npx securenow init` to fill `.securenow/runtime.json`. Local app identity, runtime API key, and secure defaults come from that file; production can mount the generated tokenless runtime file as `.securenow/credentials.json` in the folder you start `node .output/server/index.mjs` from, or set `SECURENOW_CREDENTIALS` (see `credentials runtime --format env`).
 
-That's it -- the Nuxt module handles OTel SDK initialization, Nitro externalization, firewall activation, and request tracing automatically. Optional config:
+That's it: the module's Nitro plugin loads the same runtime as `node -r securenow/register` (tracing with header and body capture, logs, crash capture, firewall, rate limits, challenges) and keeps `securenow` external, so Nitro copies it with its dependencies into `.output/server/node_modules`. It also records the matched route as `http.route` and handler errors as exceptions. Settings go in `.securenow/runtime.json` (`config.capture.body`, `config.logging.enabled`, ...); `securenow: { ... }` options in `nuxt.config` are no longer used, and the build prints a warning if you set them.
 
-```typescript
-export default defineNuxtConfig({
-  modules: ['securenow/nuxt'],
-  securenow: {
-    captureBody: true,
-    logging: true,
-    noUuid: true,
-  },
-});
+`nuxt dev` is traced too. Its requests arrive through Nuxt's dev proxy: from 8.25.0 the client IP is known there; before, it was unknown and IP blocking only applied to the built server.
+
+Before 8.24.0 the module's plugin crashed the `nuxt build` server at startup. Starting `.output/server/index.mjs` with `node -r securenow/register` and no module also works. Tested on Nuxt 3.21 and 4.6.
+
+---
+
+### Vite
+
+Browser telemetry is not sent to SecureNow: browser ingestion is disabled since 8.0, and `securenow/web-vite` sends nothing. Instrument the Node process that serves the app:
+
+```bash
+# vite preview
+node -r securenow/register-vite node_modules/vite/bin/vite.js preview
+
+# a Vite SSR server (Express + Vite middleware, ...)
+node -r securenow/register server.js
+```
+
+`securenow/register-vite` is the same runtime as `securenow/register`. A static build served by nginx or a CDN has no Node process for SecureNow to run in.
+
+### Bun
+
+```bash
+bun --preload securenow/register app.js
 ```
 
-The Nuxt server plugin (v5.13.0+) initializes the firewall independently from OpenTelemetry, so IP blocking works even if tracing encounters an error.
+Works for apps served through `node:http` (tested with Express 5 on Bun 1.3). `Bun.serve` is not traced or protected. Deno is not supported.
 
 ---
 
 ### Compatibility Matrix
 
-| Framework | Traces | Logs | Body Capture | Firewall | Notes |
-|-----------|--------|------|--------------|----------|-------|
-| Express | Yes | Yes | Yes | Yes | Fully compatible |
-| Fastify | Yes | Yes | Yes | Yes | Default on; use `config.capture.body=false` only for local stream conflicts |
-| Koa | Yes | Yes | Yes | Yes | Needs `koa-bodyparser` |
-| NestJS | Yes | Yes | Yes | Yes | Use `-r ts-node/register` |
-| Hapi | Yes | Yes | Yes | Yes | Default on; use `config.capture.body=false` only for local stream conflicts |
-| h3 | Yes | Yes | Yes | Yes | Uses `toNodeListener()` |
-| Polka | Yes | Yes | Yes | Yes | Needs manual body parser |
-| Micro/HTTP | Yes | Yes | Yes | Yes | Full control |
-| Hono | Yes | Yes | Yes | Yes | Use ESM `-r` preload |
-| Feathers | Yes | Yes | Yes | Yes | Uses Express transport |
-| Next.js | Yes | Yes | Yes | Yes | Use `instrumentation.ts` + `serverExternalPackages` + `outputFileTracingIncludes` |
-| Nuxt 3 | Yes | Yes | Yes | Yes | Use `securenow/nuxt` module |
+| Framework | Traces | Logs | Body Capture | Firewall | `http.route` | Notes |
+|-----------|--------|------|--------------|----------|--------------|-------|
+| Express 4 and 5 | Yes | Yes | Yes | Yes | Yes | CommonJS, ESM, TypeScript via tsx (tested 4.22, 5.3) |
+| Fastify 5 | Yes | Yes | Yes | Yes | Yes | Route and handler exceptions through Fastify's `fastify.initialization` channel (8.24.0+) |
+| Koa 3 | Yes | Yes | Yes | Yes | With `@koa/router` | Body needs a body parser |
+| NestJS 11 | Yes | Yes | Yes | Yes | Yes | `-r securenow/register` before `-r ts-node/register` for TypeScript |
+| Hapi 21 | Yes | Yes | Yes | Yes | Yes | |
+| h3 1 | Yes | Yes | Yes | Yes | 8.25.0+ | Uses `toNodeListener()`; handler exceptions on the span 8.25.0+ |
+| Polka 0.5 | Yes | Yes | Yes | Yes | 8.25.0+ | Needs a body parser; pass errors to `next(err)` (a thrown error crashes Polka); `next(err)` exceptions on the span 8.25.0+ |
+| Raw `http`/`https`/`http2` | Yes | Yes | Yes | Yes | No (raw path) | HTTP/2 compatibility API covered, raw `'stream'` servers not |
+| Hono 4 (`@hono/node-server`) | Yes | Yes | Yes | Yes | 8.25.0+ | Errors reach the logs through Hono's default handler; handler exceptions on the span 8.25.0+ |
+| Feathers 5 | Yes | Yes | Yes | Yes | 8.25.0+ | Koa or Express transport; 5xx service errors on the span 8.25.0+ |
+| Next.js 15 and 16 | Yes | Yes | Yes | Yes | On the HTTP span 8.25.0+ | `instrumentation.ts` + `serverExternalPackages` + `outputFileTracingIncludes`; `next start` and `output: 'standalone'`; Node.js runtime only |
+| Next.js 14 | Yes | Yes | Yes | Yes | | `init` support 8.25.0+; tested on 14.2.35 |
+| Nuxt 3 and 4 | Yes | Yes | Yes | Yes | Yes | `securenow/nuxt` module; `nuxt build` output and `nuxt dev` |
+| Bun 1.3 (`node:http` apps) | Yes | Yes | Yes | Yes | As the framework | `bun --preload securenow/register`; `Bun.serve` is not supported |
+
+Not supported: Deno, edge runtimes (Cloudflare Workers, Vercel Edge), `Bun.serve`, browser telemetry. Not tested: Vercel, AWS Lambda and other serverless platforms.
 
 ---
 
 ## Firewall -- Automatic IP Blocking
 
-SecureNow can automatically block IPs from your blocklist at the application layer. No code changes -- provide an API key via `securenow login`, the `api-key` CLI, or a runtime credentials file and the firewall activates.
+SecureNow can automatically block IPs from your blocklist at the application layer. No code changes -- provide a runtime API key via `securenow login`, the `api-key` CLI, or a runtime credentials file and the firewall activates.
 
 ### Firewall Is Enabled by Default
 
@@ -1209,28 +1403,32 @@ npx securenow api-key set snk_live_abc123...
 npx securenow credentials runtime --env production
 ```
 
-The SDK resolves the runtime API key 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, then global named runtime credentials in the same fixed order.
+The SDK resolves the runtime API key from the same source as everything else: `SECURENOW_CREDENTIALS`, then 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, then the same files in `~/.securenow/`.
 
 On startup, you'll see:
 
 ```
 [securenow] Firewall: ENABLED
+[securenow] Firewall: environment=production
 [securenow] Firewall: Layer 1 (HTTP 403)      active
-[securenow] Firewall: synced 142 blocked IPs (138 exact + 4 CIDR ranges)
+[securenow] Firewall: synced 142 global blocked IPs (138 exact + 4 CIDR ranges) and 0 scoped block rules
 ```
 
+Each app and environment also has a remote on/off switch: `npx securenow firewall enable` / `disable --app <key> --env production`, applied without a deploy. `config.firewall.enabled` in the file is ignored.
+
 ### How It Works
 
 The firewall uses a version-based sync protocol for efficiency:
 
-1. **Version check** every 10 seconds (lightweight request with ETag; unchanged polls return 304 with no body)
-2. **Full blocklist sync** only when the version changes (or every hour as a safety net)
-3. **In-memory matching** with a pre-compiled set (exact IPs) and sorted CIDR list for sub-millisecond lookups
-4. **Exponential backoff** with jitter when the API is temporarily unreachable
-5. **Allowlist support** -- trusted IPs are never blocked, even if they appear on the blocklist
-6. **Localhost fallback** -- when the configured API URL is unreachable (ECONNREFUSED), the SDK automatically tries `http://localhost:4000` for co-located deployments
+1. **Version check** every 10 seconds (`config.firewall.versionCheckInterval`; a lightweight request with ETag, unchanged polls return 304 with no body)
+2. **Full blocklist sync** only when the version changes (or every hour as a safety net, `config.firewall.syncInterval`)
+3. **In-memory matching** with a pre-compiled set (exact IPs) and IPv4 and IPv6 CIDR lists (IPv6 8.25.0+) for sub-millisecond lookups
+4. **Exponential backoff** with jitter when the API is temporarily unreachable, a circuit breaker after 5 consecutive errors (2-minute pause), and 429 `Retry-After` support
+5. **Allowlist** -- deny-by-default: when an app/environment has any active allowlist entry, only listed IPs get through, and listed IPs skip the blocklist, rate limits and challenges
+6. **Order per request** -- allowlist, blocklist, scoped (route/method) blocks, challenge, rate limit
+7. **Fail-open** by default (`config.firewall.failMode: "open"`); `"closed"` answers 403 to every request until the first sync succeeds
 
-After you block an IP in the dashboard or CLI, it typically takes 10-15 seconds to propagate to all running instances.
+After you block an IP in the dashboard or CLI, it reaches running instances within about 10 seconds (set `versionCheckInterval` to 1–2 for near-instant propagation).
 
 ### Firewall-Only Mode (No Tracing)
 
@@ -1258,7 +1456,7 @@ This is useful when:
 - You're adding the firewall to a project that uses a different tracing solution
 - For non-Next Node apps, this avoids framework-specific tracing setup entirely
 
-Firewall-only mode uses the same runtime API key written by `login`, `app connect`, `api-key create`, `api-key set`, or mounted from a runtime credentials file:
+Firewall-only mode includes the blocklist, allowlist, scoped blocks, rate limits, challenges and, **(8.25.0+)**, the zero-code session guard. It uses the same runtime API key written by `login`, `app connect`, `api-key create`, `api-key set`, or mounted from a runtime credentials file:
 
 ```bash
 npx securenow credentials runtime --env production
@@ -1271,29 +1469,42 @@ The firewall supports four layers -- Layer 1 is always on, the rest are opt-in:
 
 | Layer | Credentials key | Description |
 |-------|---------|-------------|
-| **Layer 1: HTTP** | *(always on)* | Returns 403 Forbidden with a security alert page. Works with proxy headers. |
-| **Layer 2: TCP** | `config.firewall.tcp=true` | `socket.destroy()` -- zero bytes sent back |
-| **Layer 3: iptables** | `config.firewall.iptables=true` | Kernel-level DROP (Linux, requires root) |
-| **Layer 4: Cloud WAF** | `config.firewall.cloud="cloudflare"` | Pushes to Cloudflare, AWS WAF, or GCP Cloud Armor |
+| **Layer 1: HTTP** | *(always on)* | Returns 403 (`config.firewall.statusCode`): JSON `{"error":"Forbidden","ip":"..."}` for API clients, a security alert page for browsers. Works with proxy headers. |
+| **Layer 2: TCP** | `config.firewall.tcp=true` | `socket.destroy()` before HTTP parsing -- zero bytes sent back. Sees only the connection's source IP; connections from trusted proxies are left to Layer 1. Checked on each server `connection` **(8.25.0+)**; before, it hooked `listen()` and missed the servers most apps start before the SDK has finished starting |
+| **Layer 3: iptables** | `config.firewall.iptables=true` | Kernel-level DROP in a dedicated `SECURENOW_BLOCK` chain (ip6tables for IPv6), or a `securenow` nft table where iptables is missing **(8.25.0+)**. Linux, root or `CAP_NET_ADMIN`; direct client connections only. 8.25.0 validates every entry, runs without a shell and applies each sync as one batch |
+| **Layer 4: Cloud WAF** | `config.firewall.cloud="cloudflare"` / `"aws"` / `"gcp"` | Pushes the global blocklist to Cloudflare (an account IP list named `securenow-blocklist` that your own WAF rule must reference), AWS WAFv2 (IP set; `npm i @aws-sdk/client-wafv2`) or GCP Cloud Armor (`deny(403)` rules at priority 2000; `npm i @google-cloud/compute`), at most every 30 seconds. `config.firewall.cloudDryRun=true` only logs. 8.25.0 fixes IPv6 ranges, Cloud Armor's 10-range limit and stale rules. Request format tested, not run against real accounts |
+
+Layers 2 to 4 carry the global blocklist; scoped blocks, rate limits and challenges are Layer 1 only. Turn Layers 2 to 4 on with 8.25.0+. In a container, Layer 3 needs `--cap-add NET_ADMIN` and the `iptables` package.
 
 ### Blocked Page
 
 When an IP is blocked at Layer 1, the user sees a full-page security alert with:
-- Their detected IP address
+- Their detected IP address (masked)
 - A warning that malicious activity was detected
 - Contact information (`contact@securenow.ai`) for false positives
 
 ### Get an API Key
 
 ```bash
-npx securenow login
-npx securenow firewall status
+npx securenow app connect          # pick/create the app; mints and saves the runtime key
+npx securenow api-key create       # with admin auth: mint and save a key for the current app
+npx securenow firewall status      # then check the firewall state
 ```
 
-Or create one from the dashboard with the `firewall:read` scope.
+Or create one in the dashboard with the runtime scopes and save it with `npx securenow api-key set snk_live_...`.
 
 Use `npx securenow firewall status`, `npx securenow firewall apps`, and `npx securenow help firewall` for the current firewall reference.
 
+### Trusted Proxies and the Client IP
+
+Forwarding headers (`X-Forwarded-For`, then `CF-Connecting-IP`, `True-Client-IP`, `X-Real-IP`, `X-Client-IP`) count only when the connection comes from a trusted proxy. Trusted by default: private ranges, loopback, the host's own addresses and, **(8.25.0+)**, Unix-socket and named-pipe connections (for example nginx `proxy_pass http://unix:/run/app.sock`). Add public load balancers and CDNs:
+
+```json
+{ "config": { "networking": { "trustedProxies": ["cloudflare", "203.0.113.10", "198.51.100.0/24"] } } }
+```
+
+Entries are exact IPv4/IPv6 addresses, IPv4 or IPv6 CIDRs (IPv6 8.25.0+), or `"cloudflare"` for Cloudflare's published edge ranges (IPv4, and IPv6 from 8.25.0). A client can't choose its IP through `X-Forwarded-For`.
+
 ---
 
 ## Credentials Configuration
@@ -1306,22 +1517,49 @@ Use `.securenow/runtime.json` as the local source of truth. Run `npx securenow e
 
 | Field | Description | Default |
 |----------|-------------|---------|
-| `app.key` | App routing UUID. The SecureNow ingestion gateway routes telemetry by this key. | selected during login |
+| `app.key` | App routing UUID. It becomes `service.name`; the SecureNow ingestion gateway routes telemetry by this key. | selected during login |
 | `app.name` | Human-readable app label. | selected during login |
 | `apiKey` | One-app scoped runtime API key (`snk_live_...`) for telemetry ingestion and firewall sync. Runtime scopes are `traces:write`, `logs:write`, `firewall:read`, `blocklist:read`, and `allowlist:read`. | minted during login |
-| `config.runtime.deploymentEnvironment` | `deployment.environment` trace/log scope. | `local` from init, `production` from runtime credentials |
-| `config.logging.enabled` | Automatic console log export. | `true` |
+| `config.runtime.deploymentEnvironment` | `deployment.environment` trace/log/firewall scope (`dev`/`development` become `local`, `prod` becomes `production`). | `production`; `local` from init |
+| `config.runtime.noUuid` | One service name for every worker. Leave it automatic: `false` breaks dashboard routing. | `null` (automatic) |
+| `config.runtime.strict` | Exit PM2/cluster workers when no app identity resolves. | `false` |
+| `config.runtime.testSpan` | Emit a startup smoke span. | `false` |
+| `config.logging.enabled` | Automatic console log export (and crash capture). | `true` |
+| `config.logging.redact` | Redact credential fields and secret shapes in exported log lines (8.25.0+). | `true` |
 | `config.capture.body` | Request body capture with redaction. | `true` |
 | `config.capture.multipart` | Multipart metadata capture, never file content. | `true` |
+| `config.capture.maxBodySize` | Largest body captured, in bytes (minimum 1024); larger bodies are recorded as `[TOO LARGE: <n> bytes]`. | `10240` |
+| `config.capture.sensitiveFields` | Extra field names to redact (also applied to header names). | `[]` |
+| `config.otel.endpoint` | Advanced: your own OTLP collector instead of `https://ingest.securenow.ai`. | `null` |
+| `config.otel.tracesEndpoint` / `logsEndpoint` | Advanced: split collectors. | `null` |
+| `config.otel.headers` | Extra OTLP headers (app key, auth and environment are added automatically). | `{}` |
+| `config.otel.logLevel` | OpenTelemetry diagnostics: `error`, `warn`, `info`, `debug`, `none`. | `error` |
+| `config.otel.disableInstrumentations` | Instrumentation package names to skip, e.g. `@opentelemetry/instrumentation-dns`. | `[]` |
+| `config.otel.middlewareSpans` | One span per Express/Koa middleware per request. | `false` |
+| `config.networking.trustedProxies` | Extra trusted proxies: IPv4/IPv6 addresses and CIDRs, `"cloudflare"`. | `[]` |
+| `config.firewall.failMode` | `open` or `closed` (403 for everyone until the first sync). | `open` |
+| `config.firewall.statusCode` | HTTP status for blocked requests. | `403` |
+| `config.firewall.log` | Firewall console lines (startup and each decision). | `true` |
+| `config.firewall.tcp` / `iptables` / `cloud` / `cloudDryRun` | Layers 2, 3, 4 and the Layer 4 dry run. | `false` / `false` / `null` / `false` |
+| `config.firewall.cloudflare.*`, `aws.*`, `gcp.*` | Layer 4 provider settings (`apiToken`, `accountId`; `wafIpSetId`, `wafIpSetName`, `wafScope`; `projectId`, `securityPolicy`). | `aws.wafIpSetName: "securenow-blocklist"`, `aws.wafScope: "REGIONAL"` |
+| `config.firewall.rateLimitStore` | `redis://` or `rediss://` URL for rate-limit counters shared across processes and hosts. | `null` (per process) |
+| `config.firewall.versionCheckInterval` | Seconds between lightweight version checks. | `10` |
+| `config.firewall.syncInterval` | Seconds between safety-net full resyncs. | `3600` |
 | `config.firewall.enabled` | Deprecated local hint. Runtime enable/disable uses the dashboard/API environment toggle. | ignored |
-| `config.otel.*` | Optional custom endpoints, headers, and log level. | empty |
+| `config.sessions.guard` **(8.25.0+)** | 401 for revoked sessions in every framework, no code. | `false` |
+| `config.sessions.capture` **(8.25.0+)** | Send `session.seen` for session-theft detection. | `false` |
+| `config.sessions.cookieNames` **(8.25.0+)** | Extra session cookie names. | `[]` |
+
+`app.instance` from older files is ignored; use `config.otel.endpoint` for a self-hosted collector.
 
 The credentials file is versioned with `_securenow.schemaVersion`. The SDK reads
 all runtime settings from this JSON plus built-in defaults. Production should
 mount a tokenless runtime credentials file at `.securenow/credentials.json`.
-Environment-variable fallback is not supported.
+The only environment variables the SDK reads are `SECURENOW_CREDENTIALS` (the same
+JSON, raw or base64, for hosts that can't mount a file; it wins over every file)
+and `SECURENOW_DISABLED`. Every other `SECURENOW_*` variable is ignored.
 
-**Default sensitive fields (auto-redacted):** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`, `code`, `otpCode`, `oneTimeCode`, `verificationCode`, `passcode`
+**Default sensitive fields (auto-redacted, 68 names):** passwords and secrets (`password`, `passwd`, `pwd`, `secret`, `credentials`, `mysql_pwd`), tokens and auth (`token`, `api_key`, `apikey`, `access_token`, `auth`, `authorization`, `bearer`, `sessionid`, `session_id`, `cookie`, `set-cookie`, `otp`, `mfa`, `totp`), payment (`stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `iban`, `account`, `accountnumber`, `routing`, `sortcode`, `taxid`), personal data (`ssn`, `pin`, `email`, `e_mail`, `phone`, `mobile`, `dob`, `birthdate`, `firstname`, `lastname`, `fullname`, `address`, `postcode`, `zip`, `passport`, `license`), and OTP names matched exactly (`code`, `otpCode`, `oneTimeCode`, `oneTimePassword`, `passcode`, `verificationCode`, `confirmationCode`, `emailCode`, `smsCode`, `loginCode`, `signInCode`, `authCode`, `authenticationCode`, `mfaCode`, `totpCode`, `2faCode`, `securityCode`, `recoveryCode`, `backupCode`).
 
 For instrumentation, firewall layers, debugging, trusted proxies, and deployment
 environment, edit the matching `config.*` keys in `.securenow/runtime.json`
@@ -1339,12 +1577,19 @@ SecureNow provides multiple entry points depending on your needs:
 |-------------|-------|-------------------|-------------------|-------|
 | `securenow/register` | `node -r securenow/register app.js` | Yes | Yes | Default -- full tracing + firewall |
 | `securenow/firewall-only` | `node -r securenow/firewall-only app.js` | No | Yes | Firewall only, no OTel overhead |
-| `securenow/nextjs` | `await import(/* webpackIgnore: true */ 'securenow/nextjs')` | Yes | Yes | Next.js instrumentation hook |
-| `securenow/nuxt` | `modules: ['securenow/nuxt']` | Yes | Yes | Nuxt 3 module |
-| `securenow/nextjs-webpack-config` | `withSecureNow(config)` | - | - | Next.js config wrapper |
-| `securenow/firewall` | `require('securenow/firewall').init({...})` | No | Yes | Programmatic firewall API |
-| `securenow/rate-limits` | `require('securenow/rate-limits').parseRateLimitText(...)` | No | Yes | Rate-limit remediation API helper |
-| `securenow/tracing` | `require('securenow/tracing')` | Yes | No | Programmatic tracing API |
+| `securenow/nextjs` | `await import('securenow/nextjs')` inside the `nodejs` block of `instrumentation.ts` | Yes | Yes | Next.js instrumentation hook |
+| `securenow/nextjs-auto-capture` | imported by the generated `instrumentation.ts` | - | - | Body-capture fallback |
+| `securenow/nuxt` | `modules: ['securenow/nuxt']` | Yes | Yes | Nuxt 3 and 4 module |
+| `securenow/register-vite` | `node -r securenow/register-vite node_modules/vite/bin/vite.js preview` | Yes | Yes | Same as `securenow/register`, for the Node process serving a Vite app |
+| `securenow/events` | `require('securenow/events').track(type, props)` | No | No | Custom security events |
+| `securenow/sessions` | `require('securenow/sessions').guard()` / `.check(req)` **(8.25.0+)** | No | No | Session revocation |
+| `securenow/firewall` | `require('securenow/firewall').getStats()` | No | Yes | Programmatic firewall API (`init`, `shutdown`, `getStats`, `getMatcher`, `getAllowlistMatcher`) |
+| `securenow/rate-limits` | `require('securenow/rate-limits').parseRateLimitText(...)` | No | No | Rate-limit remediation API helper (calls the SecureNow API) |
+| `securenow/resolve-ip` | `require('securenow/resolve-ip').resolveClientIp(req)` | No | No | Client IP with the trusted-proxy rules |
+| `securenow/cidr` | `require('securenow/cidr').createMatcher([...]).isBlocked(ip)` | No | No | Exact-IP and CIDR matching, IPv4 and IPv6 (IPv6 ranges 8.25.0+) |
+| `securenow/tracing` | `require('securenow/tracing').getLogger(name, version)` | Yes | No | Programmatic logging API |
+| `securenow/telemetry-schema` | `require('securenow/telemetry-schema')` | No | No | Alert-SQL contract |
+| `securenow/nextjs-webpack-config` | `withSecureNow(config)` | - | - | Legacy Next.js config wrapper (also adds a webpack hook); prefer the plain config above |
 
 ---
 
@@ -1354,11 +1599,10 @@ SecureNow provides multiple entry points depending on your needs:
 
 Console log forwarding is enabled by default through
 `config.logging.enabled: true`; all console calls are automatically forwarded as
-OTLP log records:
+OTLP log records, linked to the active trace:
 
 ```javascript
-// At the top of your main file
-require('securenow/register');
+// Started with: node -r securenow/register app.js
 
 // With config.logging.enabled=true, all console logs are automatically sent
 console.log('Application started');
@@ -1375,21 +1619,22 @@ console.debug('Debug info');
 - `console.error()` -> ERROR
 - `console.debug()` -> DEBUG
 
-Logging is controlled by `config.logging.enabled` in `.securenow/runtime.json` locally or the mounted production runtime credentials file.
+A first string argument with printf placeholders (`%s`, `%d`...) is formatted like `console.log` does; objects are sent as JSON; errors keep their stack. Exported lines are redacted (8.25.0+; `config.logging.redact: false` turns it off): credential fields (password, token, apiKey, authorization, cookie, OTP codes, card numbers...) in logged objects, JSON and `key=value` text, and secret shapes anywhere in the line (JWTs, Bearer/Basic credentials, `sk_`/`pk_`/`rk_`/`snk_` keys, card numbers, emails) become `[REDACTED]`. The terminal shows the line as written.
+
+Logging is controlled by `config.logging.enabled` in `.securenow/runtime.json` locally or the mounted production runtime credentials file. Crash capture (uncaught exceptions and unhandled rejections as `FATAL` records, flushed before the process exits) needs it on.
 
 ### Direct Logger API
 
 For more control, use the OpenTelemetry logger API:
 
 ```javascript
-require('securenow/register');
 const { getLogger } = require('securenow/tracing');
 
-// Get a logger instance
+// Get a logger instance (null when logging is disabled)
 const logger = getLogger('my-module', '1.0.0');
 
 // Emit structured logs
-logger.emit({
+logger?.emit({
   severityNumber: 9,      // INFO
   severityText: 'INFO',
   body: 'User logged in',
@@ -1406,19 +1651,20 @@ logger.emit({
 - `9` - INFO
 - `13` - WARN
 - `17` - ERROR
+- `21` - FATAL
 
 ### Using with NODE_OPTIONS
 
 ```bash
-# Enable tracing + logging (console auto-forwarding is built-in since v5.6.0)
-node -r securenow/register app.js
+# Tracing + logging without editing the start script
+NODE_OPTIONS="-r securenow/register" npm start
 ```
 
 ---
 
 ## Request Body Capture
 
-SecureNow captures HTTP request bodies in traces by default, with sensitive fields automatically redacted. Set `config.capture.body=false` in `.securenow/runtime.json` locally or the mounted production runtime credentials file only when you need an opt-out.
+SecureNow captures HTTP request bodies in traces by default, with sensitive fields automatically redacted. Detections read them (instant rules see attacks in POST bodies). Set `config.capture.body=false` in `.securenow/runtime.json` locally or the mounted production runtime credentials file only when you need an opt-out.
 
 ### Body Capture Defaults
 
@@ -1441,6 +1687,8 @@ SecureNow captures HTTP request bodies in traces by default, with sensitive fiel
 - `application/graphql`
 - `multipart/form-data` (metadata capture is on unless `config.capture.multipart=false`)
 
+Other content types are not captured. The body is observed while your app reads it and never consumed, so a route that never reads its body (no body parser) records none. A body larger than `maxBodySize` is recorded as `[TOO LARGE: <n> bytes]`. Request headers are captured as `http.request.headers` with credential headers (`cookie`, `authorization`, anything containing `token`, `secret`, `session`, `csrf`, `api-key`...) redacted.
+
 ### Multipart Body Capture (v5.8.0+)
 
 Multipart/form-data metadata capture is enabled by default. Set `config.capture.multipart=false` to disable it. Uses a streaming parser that never buffers file content -- memory stays at ~few KB regardless of upload size.
@@ -1468,7 +1716,9 @@ SecureNow 8.11.2 redacts sign-in credentials named `code`, `otpCode`, `oneTimeCo
 
 All request bodies are automatically scanned and sensitive fields are redacted:
 
-**Automatically redacted fields:** `password`, `secret`, `token`, `api_key`, `card`, `cvv`, `ssn`, and more.
+**Automatically redacted fields:** `password`, `secret`, `token`, `api_key`, `card`, `cvv`, `ssn`, `email`, `phone`, `address` and more (the full list is in [Credentials Configuration](#credentials-configuration)). Field names match case-insensitively as substrings, so `creditCard` and `userEmail` are caught too.
+
+**Redacted by shape, under any field name:** JWTs, `Bearer`/`Basic` credentials, `sk_`/`pk_`/`rk_`/`snk_` live and test keys, email addresses, and card numbers that pass the Luhn check.
 
 **Add custom fields to redact:**
 
@@ -1487,19 +1737,119 @@ All request bodies are automatically scanned and sensitive fields are redacted:
 ```javascript
 // POST /api/users with body:
 {
+  "username": "johnd",
   "email": "user@example.com",
   "password": "secret123",
-  "name": "John Doe"
+  "plan": "pro"
 }
 
 // Captured in trace as:
 {
-  "email": "user@example.com",
+  "username": "johnd",
+  "email": "[REDACTED]",
   "password": "[REDACTED]",
-  "name": "John Doe"
+  "plan": "pro"
+}
+```
+
+Preview any payload with `npx securenow redact '<json>'`.
+
+---
+
+## Custom Security Events
+
+Report what only your app knows (sign-ins, OTPs, password resets, MFA). Events feed brute-force, credential-stuffing and account-takeover detection, and alert rules can query them.
+
+```javascript
+const { track } = require('securenow/events');
+const { resolveClientIp } = require('securenow/resolve-ip');
+
+app.post('/api/login', async (req, res) => {
+  const ip = resolveClientIp(req);            // same trusted-proxy rules as the firewall
+  const user = await findUserByEmail(req.body.email);
+  if (!user || !(await verifyPassword(user, req.body.password))) {
+    track('auth.login.failure', {
+      userId: user ? user.id : undefined,
+      ip,
+      userAgent: req.get('user-agent'),
+      severity: 'warn',
+      attributes: { reason: user ? 'bad_password' : 'unknown_user' },
+    });
+    return res.status(401).json({ error: 'Invalid email or password' });
+  }
+  track('auth.login.success', { userId: user.id, ip, userAgent: req.get('user-agent'), attributes: { method: 'password' } });
+  res.json({ ok: true });
+});
+```
+
+`track(type, { userId, sessionId, ip, userAgent, severity, ts, attributes })` is fire-and-forget: it buffers up to 1000 events, sends batches of up to 100 every 2 seconds, and never throws. `flush()` returns a promise for scripts that exit right away. It works in any Node process that can resolve the runtime credentials, with or without the preload.
+
+Recommended auth events: `auth.login.failure`, `auth.login.success`, `auth.otp.send.requested`, `auth.otp.send.result`, `auth.otp.verify.failure`, `auth.otp.verify.success`, `auth.password_reset.requested`, `auth.password_reset.completed`, `auth.mfa.challenge.failure`, `auth.mfa.challenge.success`, `auth.session.revoked`.
+
+Check what arrives with `npx securenow telemetry fields --since 1h --json` (it lists custom event types). From a shell or a non-JS service: `npx securenow event send <type> --user <id> --ip <ip> --attrs k=v`.
+
+---
+
+## Session Revocation
+
+Revoke a stolen session (or every session of a user) with `npx securenow revoke session <id>` / `revoke user <id>`; the SDK pulls active revocations every 30 seconds and rejects matching requests locally. It fails open: an outage never blocks sign-ins.
+
+The session id is the SHA-256 of the Bearer token or of the first session cookie found (`__Secure-next-auth.session-token`, `__Host-next-auth.session-token`, `next-auth.session-token`, `connect.sid`, `session`, `sid`, plus `config.sessions.cookieNames` **(8.25.0+)**); the user id is the JWT `sub`.
+
+**Zero code, every framework (8.25.0+)** — in `.securenow/runtime.json`:
+
+```json
+{ "config": { "sessions": { "guard": true, "capture": true } } }
+```
+
+`guard` answers a revoked session or user with 401 and clears the session cookies; `capture` sends `session.seen` (deduplicated per session and IP every 5 minutes) for session-theft detection. It runs with `-r securenow/register`, Next.js, Nuxt and `securenow/firewall-only`, and needs the runtime API key.
+
+**Express-style middleware** (Express, Connect, Polka, NestJS with the Express adapter, Feathers-Express):
+
+```js
+const sessions = require('securenow/sessions');
+// Emits session.seen (feeds impossible-travel / concurrent-session detection)
+// and rejects revoked sessions. Auto-detects NextAuth / connect.sid / JWT.
+app.use(sessions.guard());
+// ...or with your own ids:
+app.use(sessions.guard({ getSessionId: (req) => req.session?.id, getUserId: (req) => req.user?.id }));
+// ...or emit-only (detection without enforcement):
+app.use(sessions.capture());
+```
+
+**Anything else (8.25.0+)** — `sessions.check(req)` takes a Node request or a Web `Request` and returns `{ revoked, sessionId, userId }`; you return the 401:
+
+```js
+// Fastify
+fastify.addHook('onRequest', async (request, reply) => {
+  if (sessions.check(request.raw).revoked) return reply.code(401).send({ error: 'session_revoked' });
+});
+
+// Next.js route handler (Node.js runtime)
+import { check } from 'securenow/sessions';
+export async function GET(request) {
+  if (check(request).revoked) return Response.json({ error: 'session_revoked' }, { status: 401 });
+  return Response.json({ ok: true });
 }
 ```
 
+Koa (`sessions.check(ctx.req)`), Hono (`sessions.check(c.req.raw)`) and h3 (`sessions.check(event.node.req)`) work the same way; examples in SKILL-API.md, section 5.10.
+
+**Lower level:** `sessions.isRevoked({ sessionId, userId })`. Call `sessions.start()` once at boot when this is all you use.
+
+---
+
+## Deployment
+
+The same credentials file works everywhere; only how it reaches the app changes. Recipes with full Dockerfiles, Kubernetes manifests and systemd units are in SKILL-API.md, section 6.
+
+- **Docker:** `CMD ["node", "-r", "securenow/register", "src/index.js"]` with `WORKDIR` set to the app folder. Mount the production file at `/app/.securenow/credentials.json` or pass `SECURENOW_CREDENTIALS` (`docker run --env-file securenow.env` with the line printed by `--format env`). Keep `.securenow/runtime.json` and `admin.json` out of the image with a `.dockerignore`. Next.js standalone: the file goes next to `server.js`. Nuxt: in the folder you run `node .output/server/index.mjs` from.
+- **Kubernetes:** a Secret mounted as `/app/.securenow/credentials.json` (`subPath`), or `SECURENOW_CREDENTIALS` from a Secret.
+- **PM2:** `node_args: ['-r', require.resolve('securenow/register')]` in `ecosystem.config.cjs`, fork or cluster.
+- **systemd / VMs:** `WorkingDirectory` = the app folder; `ExecStart=/usr/bin/node -r securenow/register src/index.js`.
+- **Railway, Render, Heroku, Fly:** `SECURENOW_CREDENTIALS` as a secret variable.
+- **Vercel:** `SECURENOW_CREDENTIALS` in the project's environment; not tested end to end, firewall not verified on serverless functions.
+
 ---
 
 ## Advanced Configuration
@@ -1510,16 +1860,14 @@ All request bodies are automatically scanned and sensitive fields are redacted:
 {
   "apiKey": "snk_live_...",
   "app": {
-    "key": "my-production-app",
-    "name": "my-production-app",
-    "instance": "http://collector.example.com:4318"
+    "key": "<app-uuid>",
+    "name": "my-production-app"
   },
   "config": {
-    "runtime": { "noUuid": true, "strict": true, "deploymentEnvironment": "production" },
+    "runtime": { "strict": true, "deploymentEnvironment": "production" },
     "otel": {
-      "headers": { "x-securenow-app-key": "my-production-app" },
-      "logLevel": "info",
-      "disableInstrumentations": ["fs", "dns"]
+      "logLevel": "warn",
+      "disableInstrumentations": ["@opentelemetry/instrumentation-dns", "@opentelemetry/instrumentation-net"]
     },
     "logging": { "enabled": true },
     "capture": {
@@ -1527,15 +1875,20 @@ All request bodies are automatically scanned and sensitive fields are redacted:
       "maxBodySize": 20480,
       "sensitiveFields": ["internal_id", "session_key"]
     },
+    "networking": { "trustedProxies": ["cloudflare"] },
     "firewall": {
-      "tcp": true,
-      "versionCheckInterval": 10,
-      "syncInterval": 300
-    }
+      "tcp": false,
+      "versionCheckInterval": 2,
+      "syncInterval": 3600,
+      "rateLimitStore": "redis://redis:6379"
+    },
+    "sessions": { "guard": true, "capture": true }
   }
 }
 ```
 
+`sessions` needs 8.25.0+. To send telemetry to your own collector instead of SecureNow (advanced; the SecureNow dashboard then sees nothing), set `config.otel.endpoint`.
+
 ### Using Multiple Logger Instances
 
 ```javascript
@@ -1545,14 +1898,14 @@ const authLogger = getLogger('auth-service', '1.0.0');
 const dbLogger = getLogger('database', '1.0.0');
 const apiLogger = getLogger('api-handler', '1.0.0');
 
-authLogger.emit({
+authLogger?.emit({
   severityNumber: 9,
   severityText: 'INFO',
   body: 'User authenticated',
   attributes: { userId: 123 },
 });
 
-dbLogger.emit({
+dbLogger?.emit({
   severityNumber: 13,
   severityText: 'WARN',
   body: 'Slow query detected',
@@ -1574,23 +1927,26 @@ if (isLoggingEnabled()) {
 
 ### Programmatic Configuration
 
-Use `.securenow/runtime.json` for local development and tests; CI/production should mount the generated runtime credentials file:
+Use `.securenow/runtime.json` for local development and tests; CI/production should mount the generated runtime credentials file. There is no configuration API: the preload reads the file (or `SECURENOW_CREDENTIALS`) at boot.
 
 ```javascript
 // Reads .securenow/runtime.json first, with legacy/generated runtime credentials as fallbacks.
 require('securenow/register');
 ```
 
+`require('securenow/app-config')` exposes the resolved values (`resolveAll()`, `resolveFirewallOptions()`, ...) for diagnostics.
+
 ---
 
 ## TypeScript Support
 
-SecureNow includes full TypeScript definitions.
+SecureNow ships type definitions for `securenow/tracing`, `securenow/events`, `securenow/sessions`, `securenow/nextjs`, `securenow/nuxt`, `securenow/rate-limits` and `securenow/telemetry-schema`.
 
 ### Type Definitions
 
 ```typescript
 import { getLogger, isLoggingEnabled, Logger, LogRecord } from 'securenow/tracing';
+import { track } from 'securenow/events';
 
 // Get a typed logger
 const logger: Logger | null = getLogger('my-service', '1.0.0');
@@ -1606,38 +1962,52 @@ if (logger) {
       action: 'login',
     },
   };
-  
+
   logger.emit(logRecord);
 }
 
 // Check if enabled
 const enabled: boolean = isLoggingEnabled();
+
+// Custom event
+track('auth.login.success', { userId: 'u_123', attributes: { method: 'password' } });
 ```
 
+Run TypeScript apps with `node -r securenow/register --import tsx src/index.ts`, `node -r securenow/register -r ts-node/register src/index.ts`, or the compiled output.
+
 ### Next.js with TypeScript
 
 ```typescript
-// instrumentation.ts
+// instrumentation.ts (src/instrumentation.ts with a src/ layout)
 export async function register() {
-  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
-
-  const securenowNext = await import(/* webpackIgnore: true */ 'securenow/nextjs');
-  const registerSecureNow = securenowNext.registerSecureNow || securenowNext.default?.registerSecureNow;
-  registerSecureNow({ captureBody: true });
-  await import(/* webpackIgnore: true */ 'securenow/nextjs-auto-capture');
+  if (process.env.NEXT_RUNTIME === 'nodejs') {
+    try {
+      const securenowNext = await import('securenow/nextjs');
+      const registerSecureNow = securenowNext.registerSecureNow || securenowNext.default?.registerSecureNow;
+      registerSecureNow({ captureBody: true });
+      await import('securenow/nextjs-auto-capture');
+    } catch (error) {
+      console.error('[securenow] SecureNow did not start; the app is running without it:', error);
+    }
+  }
 }
 ```
 
-```javascript
-// next.config.js
-const { withSecureNow } = require('securenow/nextjs-webpack-config');
+```typescript
+// next.config.ts (Next.js 15+)
+import type { NextConfig } from 'next';
 
-module.exports = withSecureNow({
-  reactStrictMode: true,
-});
+const nextConfig: NextConfig = {
+  serverExternalPackages: ['securenow'],
+  outputFileTracingIncludes: {
+    '/*': ['./node_modules/securenow/**/*'],
+  },
+};
+
+export default nextConfig;
 ```
 
-`withSecureNow()` adds the server external package config and `outputFileTracingIncludes` for standalone/self-hosted builds.
+The older `withSecureNow()` wrapper from `securenow/nextjs-webpack-config` still exists, but it also adds a `webpack` hook; the plain config above is what `init` writes and what is tested.
 
 ### NestJS with TypeScript
 
@@ -1669,25 +2039,22 @@ npx securenow env
 npx securenow status --env local
 ```
 
-The output should show an app key, runtime API key source, collector endpoint, and deployment environment from `.securenow/runtime.json` or the mounted runtime credentials file.
+The output should show an app key, runtime API key source, collector endpoint, and deployment environment from `.securenow/runtime.json` or the mounted runtime credentials file. `Service name` must be the app key UUID.
 
-**Check 2: Verify OTLP collector is running**
+**Check 2: Look at the right environment**
 
-```bash
-curl http://localhost:4318/v1/traces
-# Should return 200 or 405 (method not allowed)
-```
+`npx securenow init` writes `deploymentEnvironment: "local"`, while the CLI and dashboard default to `production`. Use `--env local` (or `--env all`), or set the environment you expect.
 
 **Check 3: Run doctor and enable debug diagnostics**
 
 ```bash
 npx securenow doctor --json
-OTEL_LOG_LEVEL=debug node -r securenow/register app.js
+npx securenow test-span
 ```
 
-Doctor checks OTLP reachability and flags duplicate `@opentelemetry/api` versions that can silently leave tracing on the OpenTelemetry noop provider.
+Doctor probes traces, logs, the API and firewall sync, and flags duplicate `@opentelemetry/api` versions that can silently leave tracing on the OpenTelemetry noop provider. `test-span` should print `Span accepted (HTTP 200)`.
 
-For a persistent setting, update credentials:
+For a persistent diagnostic setting, update credentials (or run once with `OTEL_LOG_LEVEL=debug`):
 
 ```json
 {
@@ -1699,12 +2066,14 @@ For a persistent setting, update credentials:
 
 Look for lines like:
 ```
-[securenow] OTel SDK started -> http://localhost:4318/v1/traces
+[securenow] OTel SDK started → https://ingest.securenow.ai/v1/traces
 ```
 
+No `[securenow]` line at all means the process that serves HTTP never loaded the SDK: put the preload on the command that actually starts it (start script, Docker `CMD`, PM2 `node_args`, systemd `ExecStart`).
+
 **Check 4: Verify initialization order**
 
-SecureNow must be required BEFORE any other modules:
+SecureNow must be loaded BEFORE any other modules:
 
 ```javascript
 // Correct
@@ -1716,19 +2085,28 @@ const express = require('express');
 require('securenow/register');
 ```
 
+In ESM apps, use `node -r securenow/register` instead of an `import` in your code, and look for `[securenow] ESM loader hook auto-registered (module.register)` at startup (Node >= 20.6).
+
+**Check 5: Wrong credentials?**
+
+The startup line shows `credentials=<file>` or `credentials=env:SECURENOW_CREDENTIALS`. `SECURENOW_CREDENTIALS` wins over every file; a `runtime.json` beats a `credentials.production.json` in the same folder; a parent folder or `~/.securenow/` is used when the project has none. Remove the stray source.
+
 ### Firewall Not Blocking IPs
 
 **Check 1: Is a runtime API key in `.securenow/runtime.json` or the mounted runtime credentials file?**
 
 ```bash
 npx securenow api-key show
+npx securenow env          # "Firewall  enabled", not "missing firewall API key"
 ```
 
-**Check 2: Is the IP in the blocklist?**
+**Check 2: Is the IP in the blocklist, for this app and environment?**
 
 ```bash
-npx securenow blocklist
-npx securenow firewall test-ip 1.2.3.4
+npx securenow blocklist --env production
+npx securenow firewall test-ip 1.2.3.4 --path /admin --env production
+npx securenow firewall apps          # firewall on for that environment?
+npx securenow firewall hits --ip 1.2.3.4
 ```
 
 **Check 3: Check startup logs for sync status**
@@ -1736,14 +2114,15 @@ npx securenow firewall test-ip 1.2.3.4
 You should see:
 ```
 [securenow] Firewall: ENABLED
-[securenow] Firewall: synced 142 blocked IPs
+[securenow] Firewall: environment=production
+[securenow] Firewall: synced 142 global blocked IPs (138 exact + 4 CIDR ranges) and 0 scoped block rules
 ```
 
-If you see `initial sync failed`, check the API URL and key.
+If you see `initial sync failed`, check the network and the key. `Firewall: environment=` must match the environment of the block.
 
 **Check 4: Wait for propagation**
 
-After blocking an IP, it takes 10-15 seconds to propagate (one version-check interval).
+After blocking an IP, it takes up to one version-check interval (10 seconds by default) to propagate.
 
 **Check 5: Are you behind a proxy?**
 
@@ -1755,11 +2134,15 @@ proxy_set_header X-Real-IP $remote_addr;
 proxy_set_header X-Forwarded-Proto $scheme;
 ```
 
-SecureNow trusts private, loopback, and same-host proxy peers automatically. For external load balancers or public proxy IPs, add them to `config.networking.trustedProxies` in `.securenow/runtime.json` or the mounted runtime credentials file: exact IPs, IPv4 ranges such as `"203.0.113.0/24"`, or `"cloudflare"` for Cloudflare's published edge ranges (8.21.0+). If no forwarded header reaches the app, SecureNow can detect the attack shape but cannot recover the real visitor IP from traces. Starter protection refuses block mode for an app whose traffic arrives through a proxy it doesn't trust, because a block would hit the proxy and everyone behind it.
+SecureNow trusts private, loopback, and same-host proxy peers automatically, and Unix-socket connections from 8.25.0. For external load balancers or public proxy IPs, add them to `config.networking.trustedProxies` in `.securenow/runtime.json` or the mounted runtime credentials file: exact IPs, IPv4 ranges such as `"203.0.113.0/24"`, or `"cloudflare"` for Cloudflare's published edge ranges (8.21.0+). If no forwarded header reaches the app, SecureNow can detect the attack shape but cannot recover the real visitor IP from traces. Starter protection refuses block mode for an app whose traffic arrives through a proxy it doesn't trust, because a block would hit the proxy and everyone behind it.
+
+**Check 6: Allowlist or layers**
 
-**Check 6: Using PM2?**
+An IP on the app's allowlist skips the blocklist. Layers 2 and 3 only see direct connections; behind a proxy, Layer 1 does the blocking. At Layer 1, IPv6 addresses and ranges match from 8.25.0 (before, IPv6 ranges never matched).
 
-Make sure `node_args: '-r securenow/register'` is in your `ecosystem.config.cjs`. Without it, PM2 restarts skip the SDK entirely.
+**Check 7: Using PM2?**
+
+Make sure `node_args: ['-r', require.resolve('securenow/register')]` is in your `ecosystem.config.cjs`. Without it, PM2 restarts skip the SDK entirely; with a bare `'-r securenow/register'`, cluster workers started from another folder (`pm2 resurrect` at boot) crash with `Cannot find module 'securenow/register'`.
 
 ### Logs Not Appearing
 
@@ -1773,24 +2156,24 @@ Make sure `node_args: '-r securenow/register'` is in your `ecosystem.config.cjs`
 }
 ```
 
-**Check 2: Verify console instrumentation is loaded**
+**Check 2: Verify the SDK is loaded**
 
-```javascript
-require('securenow/register');
+```bash
+node -r securenow/register app.js
 ```
 
 **Check 3: Check console output**
 
 You should see:
 ```
-[securenow] Logging: ENABLED -> http://localhost:4318/v1/logs
+[securenow] Logging: ENABLED → https://ingest.securenow.ai/v1/logs
 ```
 
-**Check 4: Verify OTLP logs endpoint**
+**Check 4: Query them**
 
 ```bash
-curl http://localhost:4318/v1/logs
-# Should return 200 or 405
+npx securenow logs --since 15m --env local
+npx securenow log send "manual test" --level info
 ```
 
 ### Request Body Not Captured
@@ -1811,10 +2194,15 @@ Body capture only works for:
 - `application/json`
 - `application/x-www-form-urlencoded`
 - `application/graphql`
+- `multipart/form-data` (metadata)
+
+**Check 3: Does the route read its body?**
+
+SecureNow records the body as the app reads it. A route without a body parser (Koa without `koa-bodyparser`, Polka without a parser) records none.
 
-**Check 3: Check body size**
+**Check 4: Check body size**
 
-Bodies larger than `config.capture.maxBodySize` are truncated:
+Bodies larger than `config.capture.maxBodySize` are recorded as `[TOO LARGE: <n> bytes]` instead of their content:
 
 ```json
 {
@@ -1824,6 +2212,10 @@ Bodies larger than `config.capture.maxBodySize` are truncated:
 }
 ```
 
+**Check 5: Next.js Edge runtime**
+
+Routes with `export const runtime = 'edge'` and Edge middleware are not instrumented.
+
 ### High Memory Usage
 
 **Option 1: Disable body capture**
@@ -1846,16 +2238,18 @@ Bodies larger than `config.capture.maxBodySize` are truncated:
 }
 ```
 
-**Option 3: Disable specific instrumentations**
+**Option 3: Disable specific instrumentations** (full package names)
 
 ```json
 {
   "config": {
-    "otel": { "disableInstrumentations": ["fs", "dns", "net"] }
+    "otel": { "disableInstrumentations": ["@opentelemetry/instrumentation-dns", "@opentelemetry/instrumentation-net"] }
   }
 }
 ```
 
+Keep `config.otel.middlewareSpans` off (the default): one span per middleware per request is most of the telemetry on a busy Express app.
+
 ### Next.js Instrumentation Not Working
 
 **Check 1: Is `securenow` externalized?**
@@ -1869,15 +2263,15 @@ module.exports = {
 };
 ```
 
-For Next.js < 15, add `securenow` to `experimental.serverComponentsExternalPackages` and enable `experimental.instrumentationHook`.
+For Next.js 14, the keys go under `experimental` together with `instrumentationHook: true` (see Option B above).
 
 **Check 2: Verify instrumentation file location**
 
-`instrumentation.ts` or `instrumentation.js` must be in the project root (same level as `app/` or `pages/`).
+`instrumentation.ts` or `instrumentation.js` must sit next to `app/` or `pages/`: the project root, or `src/` when the project uses a `src/` layout.
 
 **Check 3: Check for OTel MODULE_NOT_FOUND errors**
 
-If you see `MODULE_NOT_FOUND` for `@opentelemetry/*`, `./firewall`, or other SecureNow runtime modules, your `next.config.js` is missing the externalization or standalone output include. Run `npx securenow init`; if your config is custom, use the prompt it prints to merge the edit safely.
+If you see `MODULE_NOT_FOUND` for `@opentelemetry/*`, `./firewall`, or other SecureNow runtime modules, or every standalone request returns 500, your instrumentation file still uses `webpackIgnore` (written by `init` before 8.24.0) or `next.config.js` is missing the externalization or standalone output include. Run `npx securenow init`; if your config is custom, use the prompt it prints to merge the edit safely.
 
 **Check 4: Restart dev server**
 
@@ -1890,7 +2284,9 @@ npm run dev
 
 **Problem: Different service names for each worker**
 
-**Solution: Set `config.runtime.noUuid`**
+**Solution: let `config.runtime.noUuid` stay automatic**
+
+With `app.key` in the credentials, every worker reports under the app key. A per-worker suffix appears only when `noUuid` is set to `false` or no app key was found (check the `credentials=` startup line):
 
 ```json
 {
@@ -1900,8 +2296,6 @@ npm run dev
 }
 ```
 
-This uses the same service name for all workers.
-
 **Problem: Workers not instrumented / firewall not active**
 
 **Solution: Use node_args in PM2 config**
@@ -1913,12 +2307,16 @@ module.exports = {
     name: 'my-app',
     script: './app.js',
     instances: 4,
-    node_args: '-r securenow/register',
+    node_args: ['-r', require.resolve('securenow/register')],
   }]
 };
 ```
 
-Without `node_args`, PM2 starts your script directly without the securenow preload, so neither tracing nor the firewall will be active.
+Without `node_args`, PM2 starts your script directly without the securenow preload, so neither tracing nor the firewall will be active. Use the absolute path: in cluster mode Node resolves a bare `-r securenow/register` from the PM2 daemon's folder, and the workers crash-loop when the daemon was started elsewhere (as `pm2 resurrect` does at boot). Rate limits count per worker unless `config.firewall.rateLimitStore` points at Redis.
+
+### Tests Sending Data
+
+Test runs load the project's `.securenow` credentials and report to the real app. Run them with `SECURENOW_DISABLED=1 npm test`.
 
 ---
 
@@ -1933,7 +2331,7 @@ Do not hardcode configuration in code or deployment dashboards. Use `.securenow/
 const appKey = 'hardcoded-value';
 
 // Good: use .securenow/runtime.json
-// { "app": { "key": "<uuid>", "instance": "https://ingest.securenow.ai" }, "apiKey": "snk_live_..." }
+// { "app": { "key": "<uuid>", "name": "my-api" }, "apiKey": "snk_live_..." }
 ```
 
 ### 2. Use Structured Logging
@@ -1947,7 +2345,7 @@ console.log('User 123 logged in');
 // Better -- structured attributes
 console.log('User logged in', {
   userId: 123,
-  email: 'user@example.com',
+  plan: 'pro',
   timestamp: new Date().toISOString(),
 });
 ```
@@ -1971,18 +2369,21 @@ console.debug('Cache hit', { key: 'user:123' });
 
 ### 4. Don't Log Sensitive Data
 
-Even though SecureNow automatically redacts common sensitive fields, avoid logging:
+Request bodies, headers and (from 8.25.0) log lines are redacted, but log redaction recognizes field names and value shapes, not meaning:
 
 ```javascript
-// Bad
+// Bad: "hunter2" has no secret shape and no field name, so it is exported
+console.log(`Password for ${user.id} reset to hunter2`);
+
+// Redacted (8.25.0+), but still better not logged
 console.log('Login attempt', {
-  email: 'user@example.com',
-  password: 'secret123', // Will be redacted, but don't log it!
+  email: 'user@example.com', // -> [REDACTED]
+  password: 'secret123',     // -> [REDACTED]
 });
 
 // Good
 console.log('Login attempt', {
-  email: 'user@example.com',
+  userId: user.id,
   timestamp: Date.now(),
 });
 ```
@@ -2000,51 +2401,47 @@ const dbLogger = getLogger('database', '1.0.0');
 const apiLogger = getLogger('api', '1.0.0');
 ```
 
-### 6. Disable Body Capture Outside Development
+### 6. Keep Body Capture On, Tune Redaction
+
+Detections read request bodies (SQL injection, XSS and command payloads often arrive in POST bodies). Rather than turning capture off, add your own field names:
 
 ```json
 {
   "config": {
-    "capture": { "body": false }
+    "capture": { "sensitiveFields": ["national_id", "internal_token"] }
   }
 }
 ```
 
+### 7. Emit Auth Events
+
+`track()` the sign-in, OTP, reset and MFA outcomes (see [Custom Security Events](#custom-security-events)): they are what brute-force and account-takeover detection needs.
+
 ---
 
 ## Supported Runtimes
 
-- **Node.js:** 18+
-- **Frameworks:** Express, Next.js, Nuxt 3, Fastify, NestJS, Koa, Hapi, and more
-- **Databases:** PostgreSQL, MySQL, MongoDB, Redis
-- **HTTP Clients:** axios, fetch, node-fetch, got, request
-- **GraphQL:** Apollo Server, GraphQL.js
-- **Message Queues:** Redis, BullMQ
-- **And many more via OpenTelemetry auto-instrumentation**
+- **Node.js:** tested on Node 24.22 (CI: Node 24); use a patched 22, 24 or 26 release (see the security note). ESM apps need Node >= 20.6 for the automatic loader hook.
+- **Bun:** 1.3, for apps served through `node:http` (`Bun.serve` is not supported)
+- **Frameworks (tested):** Express 4.22 and 5.3, Fastify 5.12, NestJS 11.2, Koa 3.3, Hapi 21.4, Hono 4, Polka 0.5, Feathers 5.0, h3 1.15, Next.js 15.5 and 16.4, Nuxt 3.21 and 4.6; PM2 5.4 (fork and cluster). Older majors are expected to work but are not tested.
+- **Databases:** PostgreSQL, MySQL, MongoDB, Redis (OpenTelemetry auto-instrumentation)
+- **HTTP Clients:** Node `http`/`https` and the clients built on them, `fetch` (undici)
+- **Not supported:** Deno, edge runtimes (Cloudflare Workers, Vercel Edge), browser telemetry. Not tested: Vercel, AWS Lambda and other serverless platforms.
 
 ---
 
 ## Automatic Instrumentations
 
-SecureNow automatically instruments:
+SecureNow loads the OpenTelemetry Node auto-instrumentations (`@opentelemetry/auto-instrumentations-node`), plus its own HTTP and MongoDB setup and route capture for Fastify (and, 8.25.0+, Hono, h3, Feathers, Polka and Next.js). Among them:
 
 - HTTP/HTTPS (incoming and outgoing)
-- Express.js
-- Fastify
-- Koa
-- Hapi
-- Next.js
-- PostgreSQL
-- MySQL/MySQL2
-- MongoDB
-- Redis
-- GraphQL
-- gRPC
-- DNS
-- File System
-- And 50+ more libraries
-
-No code changes needed!
+- Express.js, Koa, Hapi, NestJS
+- PostgreSQL, MySQL/MySQL2, MongoDB, Redis/ioredis
+- GraphQL, gRPC
+- DNS, net
+- And the rest of the OpenTelemetry auto-instrumentation set
+
+Skip any of them with `config.otel.disableInstrumentations` (full package names). No code changes needed!
 
 ---
 
@@ -2058,53 +2455,54 @@ No code changes needed!
               +---------------------------+
               |     SecureNow Library      |
               |  +---------------------+  |
-              |  |    Firewall Layer    |  |  <-- Blocks IPs before they reach your app
+              |  |    Firewall Layer    |  |  <-- Blocks, rate-limits and challenges before your app
               |  +---------------------+  |
               |  | Auto-instrumentation |  |
               |  | Console wrapper      |  |
               |  | Body capture         |  |
+              |  | Crash capture        |  |
               |  +---------------------+  |
               +---------------------------+
                            |
                  +---------+---------+
                  |                   |
                  v                   v
-          +-----------+      +-----------+
-          | OTel SDK  |      | SecureNow |
-          | OTLP      |      | API       |
-          | Exporters |      | (blocklist|
-          +-----------+      |  sync)    |
-                 |           +-----------+
-                 v
-          +-----------+
-          | Your OTLP |
-          | Backend   |
-          +-----------+
+          +-----------+      +-------------+
+          | OTel SDK  |      | Firewall    |
+          | OTLP      |      | sync        |
+          | Exporters |      | (blocklist, |
+          +-----------+      |  rules)     |
+                 |           +-------------+
+                 v                   |
+          +--------------------------------+
+          | SecureNow ingest gateway        |
+          | https://ingest.securenow.ai     |
+          +--------------------------------+
 ```
 
 ---
 
 ## Performance
 
-- **Minimal overhead:** < 1% CPU and memory impact
-- **Batch export:** Traces and logs are batched before sending
+- **Low overhead:** traces and logs are batched before export
 - **Async processing:** No blocking of application threads
-- **Configurable:** Disable instrumentations you don't need
-- **Firewall:** Sub-millisecond IP lookups using pre-compiled hash sets and sorted CIDR lists
+- **Configurable:** Disable instrumentations you don't need; middleware spans are off by default
+- **Firewall:** Sub-millisecond IP lookups using pre-compiled hash sets and CIDR lists, all in memory
 - **Smart sync:** Version-based polling with ETag/304 eliminates unnecessary data transfer
+- **Rate limits:** the firewall never waits on Redis when a shared store is configured
 
 ---
 
 ## Security
 
-- **Automatic redaction** of sensitive fields (passwords, tokens, keys)
+- **Automatic redaction** of sensitive fields (passwords, tokens, keys, emails, card numbers, OTP codes) in captured headers and bodies
 - **Configurable** sensitive field patterns
-- **No data stored** locally -- everything sent to your OTLP backend
+- **No data stored** locally -- telemetry is sent to the SecureNow ingest gateway
 - **Multi-layer firewall** -- blocks IPs at HTTP, TCP, OS, and cloud-edge levels
-- **API keys** with granular scopes, IP allowlisting, and SHA-256 hashing
-- **Allowlist support** -- trusted IPs are never blocked
+- **Runtime API keys** scoped to one app (`traces:write`, `logs:write`, `firewall:read`, `blocklist:read`, `allowlist:read`)
+- **Allowlist support** -- deny-by-default lock to known IPs
 - **Fail-open by default** -- network issues never accidentally block legitimate traffic
-- **Open source** -- audit the code yourself
+- **Readable source** -- the package ships unminified; audit it in `node_modules/securenow`
 
 ---
 
@@ -2116,21 +2514,20 @@ ISC
 
 ## Support
 
-- **Documentation:** [GitHub Docs](https://github.com/your-repo/securenow-npm/tree/main/docs)
-- **Issues:** [GitHub Issues](https://github.com/your-repo/securenow-npm/issues)
-- **Examples:** [GitHub Examples](https://github.com/your-repo/securenow-npm/tree/main/examples)
+- **Documentation:** [`SKILL-API.md`](./SKILL-API.md), [`SKILL-CLI.md`](./SKILL-CLI.md) and `TELEMETRY-SQL.md` in this package, `npx securenow help`, and [securenow.ai](https://securenow.ai)
+- **Contact:** [contact@securenow.ai](mailto:contact@securenow.ai)
 
 ---
 
 ## Changelog
 
-See [CHANGELOG.md](CHANGELOG.md) for version history.
+`npx securenow version` prints the installed version. Release notes are kept in the CHANGELOG of the SecureNow source repository.
 
 ---
 
 ## Contributing
 
-Contributions are welcome! Please read [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
+Questions, bug reports and suggestions: [contact@securenow.ai](mailto:contact@securenow.ai).
 
 ---