securenow 7.7.16 → 8.0.0

package/SKILL-API.md

@@ -4,7 +4,7 @@ Instrument any Node.js application with OpenTelemetry tracing, structured loggin
 
 **CLI parity:** every capability exposed below (redaction, CIDR matching, log/span emission, firewall preload, config inspection) has an equivalent `securenow` CLI command. See [SKILL-CLI.md](./SKILL-CLI.md) for the terminal surface.
 
-**MCP parity (v7.5+):** `npx securenow mcp` starts a local stdio MCP server for Codex, Claude, and other MCP clients. It reuses the same `.securenow/credentials.json` file as the CLI/SDK and exposes SecureNow tools, bundled docs resources, and setup prompts to agents. Alert-rule operators can inspect notifications, read exact `metadata.matchedSubdetectors`, dry-run candidate SQL with `securenow_alert_rule_candidate_test`, and apply global system-rule query fixes with `securenow_alert_rule_query_update` when evidence is clear.
+**MCP parity (v8.0+):** `npx securenow mcp` starts a local stdio MCP server for Codex, Claude, and other MCP clients. It reads admin/control-plane auth from `.securenow/admin.json` and SDK runtime app credentials from `.securenow/runtime.json`, with legacy `.securenow/credentials.json` still supported. Alert-rule operators can inspect notifications, read exact `metadata.matchedSubdetectors`, dry-run candidate SQL with `securenow_alert_rule_candidate_test`, and apply global system-rule query fixes with `securenow_alert_rule_query_update` only when the admin user/plan permits it.
 
 **Noisy alert-rule reviews:** prefer fixing a generic system-rule detector over creating customer-specific false positives. Dry-run candidate SQL first, preserve tenant scoping with `__USER_APP_KEYS__`, keep exploit-specific indicators, then save the shared query mapping only with an audit reason and explicit confirmation.
 
@@ -27,10 +27,12 @@ npm install securenow@latest
 node -p "require('./node_modules/securenow/package.json').version"
 npx securenow version
 npx securenow login
+npx securenow admin login     # admin/control-plane CLI + MCP auth only
+npx securenow app connect     # SDK runtime app + runtime API key only
 npx securenow init
 ```
 
-Use `securenow@7.5.1` or newer. Start authentication with `npx securenow login`; do not manually open auth URLs, because the CLI generates the callback/state values. The login flow lets the user pick or create an app, enables the app firewall by default, writes `.securenow/credentials.json`, and `init` scaffolds the framework integration.
+Use `securenow@7.8.0` or newer for split admin/runtime credentials. Start authentication with `npx securenow login`; do not manually open auth URLs, because the CLI generates the callback/state values. The friendly login flow can connect both lanes, while `npx securenow admin login` only writes `.securenow/admin.json` and `npx securenow app connect` only writes `.securenow/runtime.json`. `init` scaffolds the framework integration.
 
 ### 2. Run With Instrumentation
 
@@ -54,19 +56,21 @@ npx securenow init
 
 That's it. Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are on by default. No code changes for Express, Fastify, NestJS, Koa, Hapi, and raw Node.
 
+Metrics export is off by default. SecureNow sets `OTEL_METRICS_EXPORTER=none` only when the app has not explicitly configured a metrics exporter, so `@opentelemetry/sdk-node` will not start a default metrics reader that retries `localhost:4318`.
+
 ### 3. Firewall Is Enabled by Default
 
-Since v7.5.1, the browser login flow connects the firewall automatically after
-the user picks or creates an app. The firewall key lives in your credentials
-file — no env var required:
+Since v8.0, the app runtime flow connects the firewall automatically after
+the user picks or creates an app. The runtime API key lives in `.securenow/runtime.json`
+so admin CLI/MCP login cannot overwrite it:
 
 ```bash
-npx securenow login              # pick/create app; firewall key is minted automatically
+npx securenow app connect        # pick/create app; runtime API key is minted automatically
 # or, if you already have one:
 npx securenow api-key set snk_live_abc123...
 ```
 
-Both paths write the key to `.securenow/credentials.json` (gitignored via credential-file patterns, not a whole-directory `.securenow/` ignore) and the firewall activates on next start. For production, run `npx securenow credentials runtime --env production` and mount/copy the tokenless file as `.securenow/credentials.json`.
+Both paths write the key to `.securenow/runtime.json` (gitignored via credential-file patterns, not a whole-directory `.securenow/` ignore) and the firewall activates on next start. For production, run `npx securenow credentials runtime --env production` and mount/copy the tokenless file as `.securenow/credentials.json` or `.securenow/credentials.<env>.json`.
 
 The firewall syncs your blocklist and enforces it on every request — zero code changes.
 
@@ -77,7 +81,7 @@ reblock context.
 
 For near-realtime propagation after a block/unblock, set
 `config.firewall.versionCheckInterval` to `1` or `2` in the protected app's
-`.securenow/credentials.json`. The SDK polls `/firewall/sync` with ETag/304, so
+`.securenow/runtime.json` or production runtime credentials. The SDK polls `/firewall/sync` with ETag/304, so
 unchanged checks are lightweight; keep `config.firewall.syncInterval` high as a
 safety-net full refresh.
 
@@ -103,7 +107,7 @@ operator needs to ensure those defaults immediately.
 | `securenow/nuxt` | Nuxt 3 module (add to `modules` array) | ESM |
 | `securenow/firewall` | Standalone firewall; exports `init()`, `shutdown()`, `getStats()`, `getMatcher()`, `getAllowlistMatcher()` | CJS |
 | `securenow/rate-limits` | Rate-limit remediation API helper; exports `parseRateLimitText()`, `createRateLimitFromText()`, `createRateLimit()`, `listRateLimits()` | CJS |
-| `securenow/firewall-only` | Preload: dotenv + firewall only, no tracing | Preload (`-r`) |
+| `securenow/firewall-only` | Preload: credentials-file firewall only, no tracing | Preload (`-r`) |
 | `securenow/cidr` | CIDR utilities; exports `createMatcher()`, `ipToInt()`, `parseCidr()`, `matchesCidr()` | CJS |
 | `securenow/resolve-ip` | IP resolution; exports `resolveClientIp()`, `resolveSocketIp()`, `isFromTrustedProxy()` | CJS |
 | `securenow/console-instrumentation` | Console→OTLP bridge; exports `originalConsole`, `restoreConsole()` | CJS |
@@ -138,7 +142,7 @@ module.exports = {
     script: './app.js',
     instances: 4,
     node_args: '-r securenow/register',
-    // Reads .securenow/credentials.json from the project root.
+    // Reads .securenow/runtime.json from the project root.
   }],
 };
 ```
@@ -146,7 +150,7 @@ module.exports = {
 **Docker:**
 
 ```dockerfile
-COPY .securenow/credentials.json ./.securenow/credentials.json
+COPY .securenow/credentials.production.json ./.securenow/credentials.production.json
 CMD ["node", "-r", "securenow/register", "app.js"]
 ```
 
@@ -214,7 +218,7 @@ On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-n
 }
 ```
 
-Local development and production do not need `.env.local`; `npx securenow login` and `npx securenow init` keep `.securenow/credentials.json` filled and gitignored. For production, run `npx securenow credentials runtime --env production` and mount/copy the generated JSON as `.securenow/credentials.json`.
+Local development and production do not need `.env.local`; `npx securenow app connect` and `npx securenow init` keep `.securenow/runtime.json` filled and gitignored. For production, run `npx securenow credentials runtime --env production` and mount/copy the generated JSON as `.securenow/credentials.json` or `.securenow/credentials.production.json`.
 
 #### Next.js Body Capture
 
@@ -254,11 +258,11 @@ export const POST = withSecureNow(async (req) => {
 #### Next.js with `securenow init`
 
 ```bash
-npx securenow login
+npx securenow app connect
 npx securenow init
 ```
 
-Auto-detects Next.js, creates `instrumentation.ts`, adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, and reuses the app, instance, firewall key, and secure defaults in `.securenow/credentials.json`. If files already exist, it prints an agent-ready prompt with the exact edits to propose.
+Auto-detects Next.js, creates `instrumentation.ts`, adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when safe, and reuses the app, instance, runtime API key, and secure defaults in `.securenow/runtime.json`. If files already exist, it prints an agent-ready prompt with the exact edits to propose.
 
 ---
 
@@ -270,12 +274,12 @@ Auto-detects Next.js, creates `instrumentation.ts`, adds `serverExternalPackages
 export default defineNuxtConfig({
   modules: ['securenow/nuxt'],
   securenow: {
-    // optional overrides (defaults come from .securenow/credentials.json)
+    // optional overrides (defaults come from .securenow/runtime.json)
   },
 });
 ```
 
-The Nuxt module auto-configures Nitro externals, runtime config, and a server plugin that sets up OTel tracing + logging + firewall. Local and production app identity, firewall key, and secure defaults come from `.securenow/credentials.json`.
+The Nuxt module auto-configures Nitro externals, runtime config, and a server plugin that sets up OTel tracing + logging + firewall. Local app identity, runtime API key, and secure defaults come from `.securenow/runtime.json`; production can use tokenless `.securenow/credentials.<env>.json`.
 
 ---
 
@@ -296,7 +300,7 @@ Instruments document load, fetch, XMLHttpRequest, and user interactions with bro
 
 ## Firewall — Multi-Layer IP Blocking
 
-The firewall auto-activates once an API key is resolvable and the app firewall toggle is on. Since **v7.5.1**, `npx securenow login` enables the selected app firewall by default and writes the scoped key to `.securenow/credentials.json`; `securenow api-key set` can still write/rotate the key later. Production should use the tokenless file generated by `securenow credentials runtime --env production`. Resolution order: project `./.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order. Runtime config is credentials-json based; legacy env fallback is disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is explicitly set for an old deployment.
+The firewall auto-activates once a runtime API key is resolvable and the app firewall toggle is on. Since **v8.0**, `npx securenow app connect` enables the selected app firewall by default and writes the scoped runtime key to `.securenow/runtime.json`; `securenow api-key set` can still write/rotate the key later. Production should use the tokenless file generated by `securenow credentials runtime --env production`. Runtime resolution order is project `./.securenow/runtime.json` -> legacy project credentials -> project named runtime credentials -> global runtime/legacy/named runtime credentials. Admin auth lives separately in `admin.json`.
 
 ```
 Layer 4: Cloud/Edge WAF    →  blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
@@ -308,8 +312,8 @@ Layer 1: HTTP Handler      →  403 JSON response (always active)
 ### Activate
 
 ```bash
-# Zero-config (recommended) — writes the key to .securenow/credentials.json
-npx securenow login              # pick/create app; firewall connects automatically
+# Zero-config runtime (recommended) - writes the key to .securenow/runtime.json
+npx securenow app connect        # pick/create app; firewall connects automatically
 # or, if you already have a key:
 npx securenow api-key set snk_live_abc123...
 
@@ -317,6 +321,26 @@ npx securenow api-key set snk_live_abc123...
 npx securenow credentials runtime --env production
 ```
 
+### Scoped Blocklist Entries
+
+Manual blocklist entries can target all routes or only matching request scopes.
+Use the dashboard Advanced section, the API, CLI, or MCP with the same fields:
+
+```json
+{
+  "ip": "203.0.113.42",
+  "pathPattern": "/admin*",
+  "pathMatchMode": "prefix",
+  "method": "ALL",
+  "appKey": "optional-app-key",
+  "environment": "production",
+  "reason": "Admin probing"
+}
+```
+
+`pathMatchMode` accepts `prefix`, `exact`, or `regex`. Omit `pathPattern` and
+use `method: "ALL"` for a global IP/CIDR block.
+
 ### Firewall-Only Mode (No Tracing Overhead)
 
 ```bash
@@ -326,7 +350,7 @@ node -r securenow/firewall-only app.js
 securenow run --firewall-only app.js
 ```
 
-Loads only dotenv + firewall. No OpenTelemetry, no tracing, no external packages needed.
+Loads only the firewall using SecureNow runtime credentials. No OpenTelemetry, no tracing, no external packages needed.
 
 ### Programmatic Firewall API
 
@@ -500,7 +524,7 @@ const safe = redactSensitiveData({ username: 'alice', password: 's3cret', token:
 
 **Auto-redacted fields:** `password`, `passwd`, `pwd`, `secret`, `token`, `api_key`, `apikey`, `access_token`, `auth`, `credentials`, `mysql_pwd`, `stripeToken`, `card`, `cardnumber`, `ccv`, `cvc`, `cvv`, `ssn`, `pin`.
 
-Add custom fields via `config.capture.sensitiveFields` in `.securenow/credentials.json`.
+Add custom fields via `config.capture.sensitiveFields` in `.securenow/runtime.json`.
 
 **CLI equivalent** (for piping, scripts, debugging what a payload looks like post-redaction):
 
@@ -513,13 +537,13 @@ securenow redact @request.json --fields internal_id,sessionHash
 
 ## Credentials Configuration
 
-Local development and production use `.securenow/credentials.json`. Every setting below lives under `app` or `config`; `npx securenow credentials runtime --env production` creates a tokenless production file with the same structure. Since v7.7.2, the SDK also accepts named runtime files such as `.securenow/credentials.production.json` when the canonical `credentials.json` file is absent. Filename lookup is deterministic and does not read environment variables. Legacy env fallback is disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is explicitly set.
+Local development uses `.securenow/runtime.json`; legacy `.securenow/credentials.json` is still read. Every setting below lives under `app` or `config`; `npx securenow credentials runtime --env production` creates a tokenless production file with the same structure. Since v7.7.2, the SDK also accepts named runtime files such as `.securenow/credentials.production.json` when the canonical `credentials.json` file is absent. Filename lookup is deterministic and does not read environment variables. Environment-variable fallbacks are not supported.
 
 | Credentials path | Purpose |
 |---|---|
 | `app.key` | App routing UUID. The SecureNow ingestion gateway routes telemetry by this key |
 | `app.name` | Human-readable app label |
-| `apiKey` | Scoped firewall key (`snk_live_...`) |
+| `apiKey` | Scoped runtime API key (`snk_live_...`) |
 | `config.otel.endpoint` | Optional OTLP base endpoint override |
 | `config.otel.tracesEndpoint` | Optional full traces endpoint |
 | `config.otel.logsEndpoint` | Optional full logs endpoint |
@@ -565,7 +589,7 @@ npm install securenow@latest
 npx securenow login
 ```
 
-No `.env` is needed. `npx securenow login` writes app identity, firewall key, and secure defaults to `.securenow/credentials.json`; the SDK uses the default SecureNow ingestion gateway and the gateway routes by `app.key`. `npx securenow init` makes sure the file has explanations and is gitignored without ignoring the whole `.securenow/` directory.
+No `.env` is needed. `npx securenow app connect` writes app identity, runtime API key, and secure defaults to `.securenow/runtime.json`; the SDK uses the default SecureNow ingestion gateway and the gateway routes by `app.key` while authenticating with the runtime API key. `npx securenow init` makes sure the file has explanations and is gitignored without ignoring the whole `.securenow/` directory.
 
 Update `package.json`:
 ```json
@@ -578,10 +602,10 @@ No code changes to the application needed.
 
 ```bash
 npm install securenow@latest
-npx securenow login              # pick/create app; firewall key is minted automatically
+npx securenow app connect        # pick/create app; runtime API key is minted automatically
 ```
 
-`securenow login` enables the selected app's firewall toggle and writes session, app, and firewall key to `.securenow/credentials.json` (gitignored via credential-file patterns, not a whole-directory `.securenow/` ignore). Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are enabled by default. Then run `npx securenow init`; it creates `instrumentation.ts`, patches `next.config.*` when safe, or prints exact Codex/Claude merge instructions for existing files.
+`securenow app connect` enables the selected app's firewall toggle and writes app/runtime config plus the runtime API key to `.securenow/runtime.json` (gitignored via credential-file patterns, not a whole-directory `.securenow/` ignore). Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are enabled by default. Then run `npx securenow init`; it creates `instrumentation.ts`, patches `next.config.*` when safe, or prints exact Codex/Claude merge instructions for existing files.
 
 ### Enable Firewall With Zero Tracing Overhead
 
@@ -591,7 +615,7 @@ For apps that only need IP blocking:
 node -r securenow/firewall-only app.js
 ```
 
-Make sure an API key is resolvable by running `npx securenow login` first. If you already have a key, `securenow api-key set snk_live_...` writes the creds file. For production, run `npx securenow credentials runtime --env production` and mount/copy it as `.securenow/credentials.json`.
+Make sure an API key is resolvable by running `npx securenow app connect` first. If you already have a key, `securenow api-key set snk_live_...` writes the runtime credentials file. For production, run `npx securenow credentials runtime --env production` and mount/copy it as `.securenow/credentials.json` or `.securenow/credentials.production.json`.
 
 ### Production Hardened Configuration
 

package/SKILL-CLI.md

@@ -24,24 +24,27 @@ codex mcp add securenow -- npx securenow mcp
 npx -p securenow securenow-mcp
 ```
 
-The MCP server reuses `.securenow/credentials.json` and exposes apps, traces, logs, firewall, IP intelligence, forensics, notifications, remediation tools, alert-rule review/tuning tools, bundled docs resources, and setup prompts. Write tools require `confirm:true` plus a reason.
+The MCP server reads admin/control-plane auth from `.securenow/admin.json` and SDK runtime app credentials from `.securenow/runtime.json`, with legacy `.securenow/credentials.json` still supported. Admin/global tools use admin auth; runtime-scoped read tools can use the runtime API key where its scopes allow it. Write tools require `confirm:true` plus a reason.
 
 ### Authenticate
 
 ```bash
-securenow login             # opens browser OAuth + app picker; writes ./.securenow/credentials.json (project-local by default)
-securenow login --global    # save to ~/.securenow/ instead (shared across projects)
-securenow login --token <JWT>   # headless / CI login (get token from dashboard Settings)
-securenow whoami            # verify session (shows email, app, auth source)
-```
+securenow login             # friendly flow: admin auth + app runtime connection
+securenow admin login       # admin/control-plane CLI and MCP auth only
+securenow app connect       # app/runtime SDK connection only
+securenow admin login --token <JWT>   # headless / CI admin auth
+securenow whoami            # verify both admin auth and runtime app status
+```
+
+**Two-lane credentials (v8.0+):** admin/control-plane auth lives in `.securenow/admin.json`; SDK runtime app config and the runtime API key live in `.securenow/runtime.json`. `securenow login` can run both lanes for onboarding, but `securenow admin login` never replaces runtime app config and `securenow app connect` never replaces admin auth. Legacy combined `.securenow/credentials.json` files are still read.
 
-**Zero-config flow (v7+):** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)** and **name** in `.securenow/credentials.json`. The SDK sends traces/logs to the default SecureNow ingestion gateway, which routes by app key — **no env vars or per-instance collector URLs required for local dev or production**.
+**Zero-config runtime flow:** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)** and **name** in `.securenow/runtime.json`. The SDK sends traces/logs to the default SecureNow ingestion gateway, which routes by app key, so no env vars or per-instance collector URLs are required for local dev or production.
 
-**Default-on security (v7.5.1+):** after picking or creating the app, `securenow login` turns on that app's firewall toggle, mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/credentials.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is needed. To add or rotate a key later without re-running login, use `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
+**Default-on security (v7.5.1+):** after picking or creating the app, `securenow app connect` turns on that app's firewall toggle, mints an API key with `firewall:read + blocklist:read + allowlist:read` scopes, and writes it into `.securenow/runtime.json`. Traces, logs, POST body capture, multipart metadata capture, and the firewall are enabled by default. No `SECURENOW_API_KEY` env var is needed. To add or rotate a key later without re-running app connect, use `securenow api-key set snk_live_...` (see [API Key Management](#api-key-management) below).
 
-Credentials resolve in order: project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order. Runtime config is credentials-json based; legacy env fallbacks are disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is set and never choose the credentials filename.
+Runtime credentials resolve in order: project `.securenow/runtime.json` -> legacy project `.securenow/credentials.json` -> project named runtime credentials -> global `.securenow/runtime.json` -> legacy global credentials -> global named runtime credentials. Admin auth resolves from `admin.json` first, then legacy `credentials.json`. Runtime config is credentials-json based; environment-variable fallbacks are not supported.
 
-The **firewall API key** should live in the same credentials file as `apiKey`.
+The **firewall API key** should live in runtime credentials as `apiKey`.
 
 For CI / Docker / production, use `securenow credentials runtime --env production` to generate a tokenless runtime file, then mount/copy it as `.securenow/credentials.json`. Since v7.7.2, mounting the generated `.securenow/credentials.production.json` filename directly also works when `credentials.json` is absent.
 
@@ -62,11 +65,11 @@ node -r securenow/register src/index.js
 For Next.js, run the interactive scaffolding:
 
 ```bash
-securenow login
-securenow init
-```
-
-This auto-detects your framework, creates the necessary `instrumentation.ts` and `next.config.js` changes, and reuses the app, instance, and firewall key written by login to `.securenow/credentials.json`.
+securenow login
+securenow init
+```
+
+This auto-detects your framework, creates the necessary `instrumentation.ts` and `next.config.js` changes, and reuses the app, instance, and runtime API key written by login or `app connect` to `.securenow/runtime.json`.
 
 ### Install This Skill in Cursor
 
@@ -76,16 +79,19 @@ Save this file as `.cursor/skills/securenow-cli/SKILL.md` in your project. Your
 
 Config lives in `~/.securenow/` (global) and optionally `.securenow/` (per-project):
 
-| File | Content |
-|------|---------|
-| `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
-| `~/.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config` (global, use `login --global`) |
-| `.securenow/credentials.json` | `token`, `email`, `expiresAt`, `apiKey`, `app`, `config`, `_securenow.explanations` (project-local default) |
+| File | Content |
+|------|---------|
+| `~/.securenow/config.json` | `apiUrl`, `appUrl`, `defaultApp`, `output` |
+| `~/.securenow/admin.json` | `token`, `email`, `expiresAt` for global admin/control-plane CLI and MCP auth |
+| `~/.securenow/runtime.json` | `apiKey`, `app`, `config` for global SDK runtime |
+| `.securenow/admin.json` | `token`, `email`, `expiresAt` for project-local admin/control-plane CLI and MCP auth |
+| `.securenow/runtime.json` | `apiKey`, `app`, `config`, `_securenow.explanations` for project-local SDK runtime |
+| `.securenow/credentials.json` | Legacy combined credentials; still read for backward compatibility |
 | `.securenow/credentials.<environment>.json` | Tokenless runtime credentials generated by `securenow credentials runtime --env <environment>`; read in a fixed order, not selected from env vars |
 
-**Credential resolution order:** `.securenow/credentials.json` (project) -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> `~/.securenow/credentials.json` (global) -> global named runtime credentials in the same fixed order. Legacy env fallbacks are disabled unless `SECURENOW_ENABLE_LEGACY_ENV=1` is set.
+**Credential resolution order:** runtime config resolves from project `.securenow/runtime.json` -> legacy project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `.securenow/runtime.json` -> legacy global credentials -> global named runtime credentials. Admin auth resolves from `admin.json` first, then legacy `credentials.json`. Environment-variable fallbacks are not supported.
 
-**Firewall API key resolution (v7.5.1+):** project `.securenow/credentials.json` -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global `~/.securenow/credentials.json` -> global named runtime credentials in the same fixed order. Use `securenow login` for default setup or `securenow api-key set` to rotate a key without touching env vars.
+**Runtime API key resolution (v8.0+):** project `.securenow/runtime.json` -> legacy project credentials -> project named runtime credentials in the fixed staging/production/preview/local/test/development/dev/prod order -> global runtime credentials -> legacy global credentials -> global named runtime credentials. Use `securenow app connect` for runtime setup or `securenow api-key set` to rotate a key without touching admin auth or env vars.
 
 ```bash
 securenow config set apiUrl https://api.securenow.ai
@@ -107,7 +113,7 @@ Legacy CLI overrides still exist for operator automation, but runtime SDK config
 | `--force` | `-f` | Skip confirmations |
 | `--yes` | `-y` | Auto-confirm prompts |
 
-Debug mode: `SECURENOW_DEBUG=1 securenow <cmd>` prints stack traces on errors.
+SecureNow-specific environment overrides are not supported; use `.securenow/runtime.json`, `.securenow/admin.json`, or `securenow config set`.
 
 ---
 
@@ -123,17 +129,18 @@ securenow run --firewall-only app.js         # preload firewall only (no tracing
 securenow src/index.js                       # shorthand — auto-detected as "run"
 ```
 
-Spawns `node --require securenow/register [--import otel/hook.mjs] <script>`. ESM detection uses nearest `package.json` `"type"` field or `.mjs`/`.cjs` extension. With `--firewall-only`, uses `securenow/firewall-only` instead (dotenv + firewall, no OpenTelemetry).
+Spawns `node --require securenow/register [--import otel/hook.mjs] <script>`. ESM detection uses nearest `package.json` `"type"` field or `.mjs`/`.cjs` extension. With `--firewall-only`, uses `securenow/firewall-only` instead (credentials-file firewall, no OpenTelemetry).
 
 ### Authentication
 
 ```bash
-securenow login                   # browser-based OAuth (stores in project ./.securenow/)
-securenow login --token <JWT>     # headless / CI login
-securenow login --global          # save credentials to ~/.securenow/ instead
-securenow logout                  # clear active credentials (local if present, else global)
-securenow logout --global         # clear global credentials only
-securenow whoami                  # show email, user ID, API URL, auth source, expiry, default app
+securenow login                   # friendly flow: admin auth + app runtime connection
+securenow admin login             # admin/control-plane CLI and MCP auth only
+securenow admin login --token <JWT> # headless / CI admin auth
+securenow app connect             # app/runtime SDK connection only
+securenow logout                  # clear admin auth; runtime app config remains
+securenow logout --global         # clear global admin auth only
+securenow whoami                  # show admin auth and runtime app status separately
 ```
 
 ### Applications
@@ -151,10 +158,10 @@ securenow apps scan [--yes]                  # scan all app domains for new subd
 
 ### API Key Management
 
-Manage the firewall API key stored in the credentials file. Since v7.5.1 the login flow writes `snk_live_...` keys to `.securenow/credentials.json` by default, so no env var is required for local dev.
+Manage the runtime API key stored in runtime credentials. Since v8.0 the app runtime flow writes app-scoped `snk_live_...` keys to `.securenow/runtime.json` by default, so no env var is required for local dev.
 
 ```bash
-securenow api-key create --name "CLI firewall" # mint + save a firewall key with your logged-in session
+securenow api-key create --name "CLI runtime" # mint + save a runtime API key with your logged-in session
 securenow api-key set snk_live_xxxxxxxxxx    # save to project ./.securenow/ (default)
 securenow api-key set snk_live_xxx --global  # save to ~/.securenow/ instead
 securenow api-key show                       # print the masked current key + its source
@@ -163,7 +170,7 @@ securenow api-key clear --global             # same, but from the global file
 securenow credentials runtime --env production # write .securenow/credentials.production.json for production secret-file deploys
 ```
 
-The key must start with `snk_live_`. `securenow login` with firewall enabled writes the key automatically; use `api-key create` when you have an account session but no runtime key yet, or `api-key set` when you already have a key from the dashboard.
+The key must start with `snk_live_`. `securenow app connect` writes the key automatically; use `api-key create` when you have admin auth but no runtime key yet, or `api-key set` when you already have a key from the dashboard.
 
 ### Init — Project Setup
 
@@ -172,12 +179,12 @@ securenow init [--env local] [--key <API_KEY>]
 ```
 
 Auto-detects framework (Next.js, Nuxt, Express, Fastify, Koa, Hapi, Node) from `package.json`. Then:
-- **Credentials**: ensures `.securenow/credentials.json` exists, has secure defaults/explanations, and local credential JSON files are gitignored without ignoring the whole `.securenow/` directory
+- **Credentials**: ensures `.securenow/runtime.json` exists, has secure defaults/explanations, and local credential JSON files are gitignored without ignoring the whole `.securenow/` directory
 - **Next.js**: creates `instrumentation.ts/js` with `securenow/nextjs` + `securenow/nextjs-auto-capture`, and adds `serverExternalPackages: ['securenow']` plus `outputFileTracingIncludes` when the config can be patched safely
 - **Existing Next.js files**: prints a Codex/Claude-ready merge prompt when instrumentation or config already exists or is too custom to safely patch
 - **Nuxt**: tells you to add `securenow/nuxt` to modules
 - **Node/Express/etc.**: suggests adding `-r securenow/register` to start script
-- Reuses `.securenow/credentials.json` written by login; production should mount/copy the tokenless runtime file generated by `securenow credentials runtime --env production`
+- Reuses `.securenow/runtime.json` written by login/app connect; production should mount/copy the tokenless runtime file generated by `securenow credentials runtime --env production`
 
 ### Dashboard & Status
 
@@ -264,9 +271,10 @@ MCP parity for noisy alert-rule reviews:
 - `securenow_alert_rule_candidate_test` dry-runs a full candidate SQL query without saving it.
 - `securenow_alert_rule_test_result` polls the dry-run.
 - `securenow_alert_rule_query_update` updates the shared public query mapping behind a system rule for all customer copies. It is admin-only, requires `confirm:true`, `applyGlobally:true`, `reason`, and SQL that keeps `__USER_APP_KEYS__` tenant scoping.
+- `securenow_alert_rule_instant_update` patches Instant rule conditions/config with stale-write guards. Fetch the rule first, pass `expectedRuleVersion` plus `expectedCurrentInstantHash`, use operations such as `remove_condition` / `add_condition` / `update_condition`, and set `applyGlobally:true` for system rules. The API runs seeded before/after checks and returns benign samples removed plus attack samples still matching. If global tuning is denied, it returns a structured admin handoff with the exact patch and missing permission.
 - `securenow_alert_rule_exclusion_add` remains the last-resort customer-specific path; it supports restrictive conditions plus `matchMode` and should not be used to hide a generic system-rule bug.
 
-For system-rule tuning, dry-run the candidate SQL first, then save with `tune-query`/`securenow_alert_rule_query_update` only when the guard preserves attack detection. Good guards add exact exploit tokens, dangerous schemes, matched subdetectors, sensitive path/status evidence, malicious user agents, or repeat thresholds; bad guards simply suppress a noisy path.
+For system-rule tuning, dry-run the candidate SQL first for scheduled rules, or use `dryRun:true` on `securenow_alert_rule_instant_update` for Instant rules. Save only when the guard preserves attack detection. Good guards add exact exploit tokens, dangerous schemes, matched subdetectors, sensitive path/status evidence, malicious user agents, or repeat thresholds; bad guards simply suppress a noisy path.
 
 ---
 
@@ -305,7 +313,7 @@ securenow firewall status --app <key> --env production   # app/env toggle, sync
 securenow firewall test-ip <ip> --app <key> --env local  # check if IP would be blocked
 ```
 
-**Zero-config setup (v7.5.1+):** running `securenow login` enables the selected app's firewall toggle, auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and writes it to the credentials file after the app is selected. No `SECURENOW_API_KEY` env var needed. If the user already has a key, `securenow api-key set snk_live_...` achieves the same thing. See [the landing firewall page](https://securenow.ai/firewall) for an overview.
+**Zero-config setup:** running `securenow app connect` enables the selected app's firewall toggle, auto-mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and writes it to `.securenow/runtime.json` after the app is selected. No `SECURENOW_API_KEY` env var needed. If the user already has a key, `securenow api-key set snk_live_...` achieves the same thing. See [the landing firewall page](https://securenow.ai/firewall) for an overview.
 
 ### Blocklist — Block Malicious IPs
 
@@ -313,12 +321,17 @@ securenow firewall test-ip <ip> --app <key> --env local  # check if IP would be
 securenow blocklist                          # list blocked IPs
 securenow blocklist list
 securenow blocklist add <ip> --app <key> --env production --reason "Brute force"
+securenow blocklist add <ip> --route /admin* --mode prefix --method ALL --reason "Admin probing"
 securenow blocklist unblock <id> --reason "False alarm after review"
 securenow blocklist remove <id>              # compatibility alias for unblock
 securenow blocklist list --status removed    # audit retained unblocks
 securenow blocklist stats                    # block counts, top reasons
 ```
 
+Scoped blocks use the same model as rate limits: `--route`/`--path`/`--pattern`
+sets `pathPattern`, `--mode`/`--path-mode` chooses `prefix`, `exact`, or
+`regex`, and `--method` limits enforcement to one HTTP method or `ALL`.
+
 Unblock stops firewall enforcement but preserves the block report, history, and
 unblock audit fields. Reblocking the same IP later creates a fresh active block
 without erasing the previous investigation trail.
@@ -368,7 +381,13 @@ supporting evidence, not the primary automation score.
 
 ### Allowlist — Restrict to Known IPs
 
-```bash
+Dangerous production mode: IP Allowlist is deny-by-default. Once any active
+allowlist entry exists for an app/environment, only listed IPs can reach it and
+all other IPs are blocked. Do not use allowlist to mark an IP trusted, suppress
+false positives, or clean up investigations. Use `securenow trusted add` for
+known-safe monitors, office/VPN traffic, or trusted bypass cases.
+
+```bash
 securenow allowlist                          # list allowed IPs
 securenow allowlist list
 securenow allowlist add <ip> --app <key> --env local --label "Office" --reason "Corporate VPN"
@@ -376,10 +395,13 @@ securenow allowlist remove <id>
 securenow allowlist stats
 ```
 
-### Trusted Proxies
+### Trusted IPs
 
-```bash
-securenow trusted                            # list trusted IPs
+Trusted IPs are the safe bypass/suppression mechanism for known infrastructure
+and do not enable deny-by-default allowlist mode.
+
+```bash
+securenow trusted                            # list trusted IPs
 securenow trusted list
 securenow trusted add <ip> [--label "CloudFlare edge"]
 securenow trusted remove <id>
@@ -473,7 +495,7 @@ securenow test-span
 securenow test-span "ci.smoke-test"          # custom span name
 ```
 
-Both commands use the default SecureNow ingestion gateway plus optional advanced `config.otel.*` overrides from `.securenow/credentials.json`, and return non-zero on HTTP errors so CI/cron can detect failures.
+Both commands use the default SecureNow ingestion gateway plus optional advanced `config.otel.*` overrides from `.securenow/runtime.json` or legacy runtime credentials, and return non-zero on HTTP errors so CI/cron can detect failures.
 
 ### Utilities — Redaction, CIDR, Diagnostics
 
@@ -581,10 +603,10 @@ All commands support `--json` for structured output. When piping to other tools
 
 | Exit code / Error | Meaning | Recovery |
 |------------------|---------|----------|
-| `Session expired` | JWT expired | `securenow login` (or `login --global` for shared credentials) |
-| `Not logged in` | No token found | `securenow login` or mount/copy the right `.securenow/credentials.json` |
+| `Session expired` | Admin JWT expired | `securenow admin login` (or `admin login --global` for shared admin auth) |
+| `Not logged in` | No admin token found | `securenow admin login`; runtime `.securenow/runtime.json` is unrelated |
 | `Access denied (403)` | Insufficient plan or permissions | Upgrade plan or check user role |
 | `Cannot connect` | API unreachable | Check `securenow config get apiUrl` or network |
 | `Unknown command` | Typo or unrecognized command | `securenow help` |
 
-Set `SECURENOW_DEBUG=1` for full stack traces on any error.
+SecureNow-specific environment overrides are intentionally unsupported for troubleshooting; use explicit CLI config files and normal terminal logs.