securenow 7.5.1 → 7.6.0

package/SKILL-API.md

@@ -2,14 +2,14 @@
 
 Instrument any Node.js application with OpenTelemetry tracing, structured logging, request body capture, and a multi-layer IP firewall. Supports Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt 3, Vite (browser), and raw `http.createServer` — with zero code changes for most setups.
 
-**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.
+**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.
 
 ## Installation
 
 ```bash
-npm install securenow
+npm install securenow@latest
 ```
 
 ### Install This Skill in Cursor
@@ -18,14 +18,18 @@ Save this file as `.cursor/skills/securenow-api/SKILL.md` in your project. Your
 
 ## Quick Start — Any Node.js Framework
 
-### 1. Set Environment Variables
+### 1. Install, Login, And Init
 
 ```bash
-# .env or .env.local
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=https://your-collector:4318
+npm install securenow@latest
+node -p "require('./node_modules/securenow/package.json').version"
+npx securenow version
+npx securenow login
+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.
+
 ### 2. Run With Instrumentation
 
 **Option A — CLI (recommended):**
@@ -43,24 +47,24 @@ node -r securenow/register src/index.js
 **Option C — Auto-setup for Next.js:**
 
 ```bash
-npx securenow init --key snk_live_...
+npx securenow init
 ```
 
-That's it. Traces and logs flow to your OTLP collector. No code changes for Express, Fastify, NestJS, Koa, Hapi, and raw Node.
+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.
 
-### 3. Firewall Is Enabled by Default
+### 3. Firewall Is Enabled by Default
 
-Since v7.4.0, 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 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:
 
 ```bash
-npx securenow login              # pick/create app; firewall key is minted automatically
-# or, if you already have one:
-npx securenow api-key set snk_live_abc123...
+npx securenow login              # pick/create app; firewall 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` (auto-gitignored) and the firewall activates on next start. Setting `SECURENOW_API_KEY=snk_live_...` in the environment still works and takes precedence.
+Both paths write the key to `.securenow/credentials.json` (auto-gitignored) 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`.
 
 The firewall syncs your blocklist and enforces it on every request — zero code changes.
 
@@ -110,77 +114,86 @@ npx securenow run app.js
 // ecosystem.config.cjs
 module.exports = {
   apps: [{
-    name: 'my-app',
-    script: './app.js',
-    instances: 4,
-    node_args: '-r securenow/register',
-    env: {
-      SECURENOW_APPID: 'my-app',
-      SECURENOW_INSTANCE: 'https://your-collector:4318',
-      SECURENOW_NO_UUID: '1',
-    },
-  }],
-};
-```
+    name: 'my-app',
+    script: './app.js',
+    instances: 4,
+    node_args: '-r securenow/register',
+    // Reads .securenow/credentials.json from the project root.
+  }],
+};
+```
 
 **Docker:**
 
-```dockerfile
-ENV SECURENOW_APPID=my-app
-ENV SECURENOW_INSTANCE=https://your-collector:4318
-CMD ["node", "-r", "securenow/register", "app.js"]
-```
+```dockerfile
+COPY .securenow/credentials.json ./.securenow/credentials.json
+CMD ["node", "-r", "securenow/register", "app.js"]
+```
 
 ---
 
-### Next.js
-
-Three files to touch:
-
-**1. `next.config.js`** (or `.mjs` / `.ts`):
-
-```javascript
-const { withSecureNow } = require('securenow/nextjs-webpack-config');
-
-module.exports = withSecureNow({
-  // your existing config
-});
-```
-
-`withSecureNow()` auto-detects Next.js version:
-- **>=15**: sets `serverExternalPackages`
-- **<15**: sets `experimental.serverComponentsExternalPackages` + `experimental.instrumentationHook` + webpack ignore rules
-
-**2. `instrumentation.ts`** (or `.js`, can be in `src/`):
-
-```typescript
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow();
-  }
-}
-```
+### Next.js
+
+Run `npx securenow init` first. It creates the straightforward integration below when files are missing, and prints a Codex/Claude-ready merge prompt when existing files need careful edits.
+
+**1. `next.config.js`** (or `.mjs` / `.ts`):
+
+```javascript
+const nextConfig = {
+  serverExternalPackages: ['securenow'],
+};
+
+export default nextConfig;
+```
+
+For Next.js < 15, add `securenow` to `experimental.serverComponentsExternalPackages` instead.
+
+**2. `instrumentation.ts`** (or `.js`, can be in `src/`):
+
+```typescript
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
+  const { registerSecureNow } = require('securenow/nextjs');
+  registerSecureNow({ captureBody: true });
+  require('securenow/nextjs-auto-capture');
+}
+```
 
 `registerSecureNow(options?)` accepts:
 
-```typescript
-interface RegisterOptions {
-  serviceName?: string;   // override SECURENOW_APPID
-  endpoint?: string;      // override SECURENOW_INSTANCE
-  noUuid?: boolean;       // override SECURENOW_NO_UUID
-  captureBody?: boolean;  // override SECURENOW_CAPTURE_BODY
-}
-```
-
-On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-node`.
-
-**3. `.env.local`:**
-
-```bash
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=https://your-collector:4318
-```
+```typescript
+interface RegisterOptions {
+  serviceName?: string;   // override credentials app key/name
+  endpoint?: string;      // override credentials app instance
+  noUuid?: boolean;       // override credentials config.runtime.noUuid
+  captureBody?: boolean;  // override credentials config.capture.body
+}
+```
+
+On Vercel it uses `@vercel/otel`; self-hosted uses vanilla `@opentelemetry/sdk-node`.
+
+**3. Credentials:**
+
+```json
+{
+  "app": {
+    "key": "<uuid>",
+    "name": "my-nextjs-app",
+    "instance": "https://freetrial.securenow.ai:4318"
+  },
+  "config": {
+    "logging": { "enabled": true },
+    "capture": { "body": true, "multipart": true, "maxBodySize": 10240 },
+    "firewall": { "enabled": true }
+  }
+}
+```
+
+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`.
 
 #### Next.js Body Capture
 
@@ -188,15 +201,18 @@ SECURENOW_INSTANCE=https://your-collector:4318
 
 Add to your `instrumentation.ts`:
 
-```typescript
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow({ captureBody: true });
-    require('securenow/nextjs-auto-capture');
-  }
-}
-```
+```typescript
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
+export async function register() {
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
+  const { registerSecureNow } = require('securenow/nextjs');
+  registerSecureNow({ captureBody: true });
+  require('securenow/nextjs-auto-capture');
+}
+```
 
 **Option B — Middleware:**
 
@@ -219,10 +235,11 @@ export const POST = withSecureNow(async (req) => {
 #### Next.js with `securenow init`
 
 ```bash
-npx securenow init --key snk_live_abc123...
+npx securenow login
+npx securenow init
 ```
 
-Auto-detects Next.js, creates `instrumentation.ts`, suggests `next.config` changes, writes API key to `.env.local`.
+Auto-detects Next.js, creates `instrumentation.ts`, adds `serverExternalPackages: ['securenow']` 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.
 
 ---
 
@@ -232,21 +249,14 @@ Auto-detects Next.js, creates `instrumentation.ts`, suggests `next.config` chang
 
 ```typescript
 export default defineNuxtConfig({
-  modules: ['securenow/nuxt'],
-  securenow: {
-    // optional overrides (defaults come from env vars)
-  },
-});
-```
-
-**`.env`:**
-
-```bash
-SECURENOW_APPID=my-nuxt-app
-SECURENOW_INSTANCE=https://your-collector:4318
-```
-
-The Nuxt module auto-configures Nitro externals, runtime config, and a server plugin that sets up OTel tracing + logging + firewall.
+  modules: ['securenow/nuxt'],
+  securenow: {
+    // optional overrides (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 and production app identity, firewall key, and secure defaults come from `.securenow/credentials.json`.
 
 ---
 
@@ -267,7 +277,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.4.0**, `npx securenow login` enables the selected app firewall and writes the key to `.securenow/credentials.json`; `securenow api-key set` can still write/rotate the key later. The `SECURENOW_API_KEY` env var is optional. Resolution order: env (must start with `snk_live_`) → project `./.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+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` -> global `~/.securenow/credentials.json`; legacy env vars are fallback-only for existing deployments.
 
 ```
 Layer 4: Cloud/Edge WAF    →  blocked at CDN (Cloudflare, AWS WAF, GCP Cloud Armor)
@@ -279,16 +289,13 @@ 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 (recommended) — writes the key to .securenow/credentials.json
+npx securenow login              # pick/create app; firewall connects automatically
 # or, if you already have a key:
 npx securenow api-key set snk_live_abc123...
 
-# Optional .env overrides for the stronger layers
-SECURENOW_FIREWALL_TCP=1                  # opt-in Layer 2
-SECURENOW_FIREWALL_IPTABLES=1             # opt-in Layer 3 (Linux, needs root)
-SECURENOW_FIREWALL_CLOUD=cloudflare       # opt-in Layer 4
-# SECURENOW_API_KEY=snk_live_...          # still honored; only wins if it starts with snk_live_
+# Production runtime file:
+npx securenow credentials runtime --env production
 ```
 
 ### Firewall-Only Mode (No Tracing Overhead)
@@ -304,13 +311,14 @@ Loads only dotenv + firewall. No OpenTelemetry, no tracing, no external packages
 
 ### Programmatic Firewall API
 
-```javascript
-const firewall = require('securenow/firewall');
-
-await firewall.init({
-  apiKey: process.env.SECURENOW_API_KEY,
-  apiUrl: 'https://api.securenow.ai',
-  syncInterval: 300,        // full sync every 5 min
+```javascript
+const firewall = require('securenow/firewall');
+const appConfig = require('securenow/app-config');
+
+await firewall.init({
+  ...appConfig.resolveFirewallOptions(),
+  apiUrl: 'https://api.securenow.ai',
+  syncInterval: 300,        // full sync every 5 min
   versionCheckInterval: 10, // lightweight version check every 10s
   failMode: 'open',         // 'open' or 'closed'
   statusCode: 403,
@@ -440,7 +448,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 `SECURENOW_SENSITIVE_FIELDS=field1,field2`.
+Add custom fields via `config.capture.sensitiveFields` in `.securenow/credentials.json`; `SECURENOW_SENSITIVE_FIELDS=field1,field2` is a legacy fallback for existing installs.
 
 **CLI equivalent** (for piping, scripts, debugging what a payload looks like post-redaction):
 
@@ -451,20 +459,22 @@ securenow redact @request.json --fields internal_id,sessionHash
 
 ---
 
-## Environment Variables — Complete Reference
-
-### Required
-
-| Variable | Description | Default |
-|----------|-------------|---------|
-| `SECURENOW_APPID` | Service name / app identifier | *(auto-generated with UUID)* |
-| `SECURENOW_INSTANCE` | OTLP collector base URL | `https://freetrial.securenow.ai:4318` |
+## 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. Environment variables are legacy fallbacks only.
+
+### App Identity
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `SECURENOW_APPID` | Legacy fallback for `app.key` / service name | from credentials file, then package name |
+| `SECURENOW_INSTANCE` | Legacy fallback for `app.instance` / OTLP collector base URL | from credentials file, then `https://freetrial.securenow.ai:4318` |
 
 ### Service Naming
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OTEL_SERVICE_NAME` | OpenTelemetry standard; overrides `SECURENOW_APPID` | — |
+| `OTEL_SERVICE_NAME` | Legacy fallback for `app.name` | — |
 | `SECURENOW_NO_UUID` | `1` to use exact app ID without UUID suffix | `0` |
 | `SECURENOW_STRICT` | `1` to exit if APPID missing in PM2 cluster | `0` |
 
@@ -472,9 +482,9 @@ securenow redact @request.json --fields internal_id,sessionHash
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Standard OTel endpoint; overrides `SECURENOW_INSTANCE` | — |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Override traces endpoint specifically | `{instance}/v1/traces` |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Override logs endpoint specifically | `{instance}/v1/logs` |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Legacy fallback for `config.otel.endpoint` | — |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Legacy fallback for `config.otel.tracesEndpoint` | `{instance}/v1/traces` |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Legacy fallback for `config.otel.logsEndpoint` | `{instance}/v1/logs` |
 | `OTEL_EXPORTER_OTLP_HEADERS` | Comma-separated `key=value` headers for OTLP requests | — |
 
 ### Behavior
@@ -482,21 +492,21 @@ securenow redact @request.json --fields internal_id,sessionHash
 | Variable | Description | Default |
 |----------|-------------|---------|
 | `SECURENOW_LOGGING_ENABLED` | Enable OTLP log export | `1` |
-| `SECURENOW_CAPTURE_BODY` | Capture HTTP request bodies | `1` |
+| `SECURENOW_CAPTURE_BODY` | Capture HTTP request bodies | `1` |
 | `SECURENOW_MAX_BODY_SIZE` | Max body size in bytes | `10240` |
-| `SECURENOW_CAPTURE_MULTIPART` | Capture multipart/form-data (streaming, metadata only) | `1` |
+| `SECURENOW_CAPTURE_MULTIPART` | Capture multipart/form-data (streaming, metadata only) | `1` |
 | `SECURENOW_SENSITIVE_FIELDS` | Comma-separated extra fields to redact | — |
 | `SECURENOW_DISABLE_INSTRUMENTATIONS` | Comma-separated packages to skip (e.g. `fs,dns`) | — |
 | `SECURENOW_TEST_SPAN` | `1` to emit a test span on startup | `0` |
 | `SECURENOW_HIDE_BANNER` | `1` to suppress free-trial upgrade banner | `0` |
 | `OTEL_LOG_LEVEL` | SDK log level: `none`, `error`, `warn`, `info`, `debug` | `none` |
-| `NODE_ENV` | Sent as `deployment.environment` attribute | `production` |
+| `SECURENOW_ENVIRONMENT` / `SECURENOW_DEPLOYMENT_ENVIRONMENT` / `NODE_ENV` | Legacy fallback for `config.runtime.deploymentEnvironment` | `production` |
 
 ### Firewall
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `SECURENOW_API_KEY` | API key (`snk_live_...`); activates firewall when set. Since v7.1.0, this is also read from `.securenow/credentials.json` — env var only wins when it starts with `snk_live_`. | — |
+| `SECURENOW_API_KEY` | Legacy env override for the `apiKey` field (`snk_live_...`). Since v7.5.1, login writes the scoped firewall key to `.securenow/credentials.json`. | - |
 | `SECURENOW_API_URL` | SecureNow API base URL | `https://api.securenow.ai` |
 | `SECURENOW_FIREWALL_ENABLED` | Master kill-switch (`0` to disable) | `1` |
 | `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between lightweight version checks | `10` |
@@ -522,9 +532,9 @@ securenow redact @request.json --fields internal_id,sessionHash
 
 ### Priority Order
 
-**Service name:** `OTEL_SERVICE_NAME` > `SECURENOW_APPID` > auto-generated
-
-**Endpoint:** `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` > `OTEL_EXPORTER_OTLP_ENDPOINT` > `SECURENOW_INSTANCE` > `https://freetrial.securenow.ai:4318`
+**Service name:** credentials `app.key` > credentials `app.name` > legacy env fallback > package name
+
+**Endpoint:** credentials `config.otel.tracesEndpoint` / `config.otel.endpoint` / `app.instance` > legacy env fallback > `https://freetrial.securenow.ai:4318`
 
 ---
 
@@ -533,16 +543,11 @@ securenow redact @request.json --fields internal_id,sessionHash
 ### Add Observability to an Existing Express App
 
 ```bash
-npm install securenow
+npm install securenow@latest
+npx securenow login
 ```
 
-Create `.env`:
-```
-SECURENOW_APPID=my-express-api
-SECURENOW_INSTANCE=https://your-collector:4318
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=1
-```
+No `.env` is needed. `npx securenow login` writes app identity, collector URL, firewall key, and secure defaults to `.securenow/credentials.json`; `npx securenow init` makes sure the file has explanations and is gitignored.
 
 Update `package.json`:
 ```json
@@ -554,17 +559,11 @@ No code changes to the application needed.
 ### Add Observability + Firewall to a Next.js App
 
 ```bash
-npm install securenow
+npm install securenow@latest
 npx securenow login              # pick/create app; firewall key is minted automatically
 ```
 
-`securenow login` enables the selected app's firewall toggle and writes session, app, and firewall key to `.securenow/credentials.json` (auto-gitignored). Traces, logs, request body capture, multipart metadata capture, and firewall enforcement are enabled by default. The `init` command still works for manual setup — it creates `instrumentation.ts` and suggests `next.config` changes. Most users only need this `.env.local`:
-
-```
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=https://your-collector:4318
-# SECURENOW_API_KEY=snk_live_...   (otherwise lives in .securenow/credentials.json)
-```
+`securenow login` enables the selected app's firewall toggle and writes session, app, and firewall key to `.securenow/credentials.json` (auto-gitignored). 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
 
@@ -574,24 +573,27 @@ For apps that only need IP blocking:
 node -r securenow/firewall-only app.js
 ```
 
-Make sure an API key is resolvable — either run `npx securenow login` / `securenow api-key set snk_live_...` (writes the creds file), or set `SECURENOW_API_KEY` in the environment. No other configuration needed.
+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`.
 
-### Production Hardened Configuration
-
-```bash
-SECURENOW_APPID=prod-api
-SECURENOW_INSTANCE=https://collector.prod.internal:4318
-SECURENOW_NO_UUID=1
-SECURENOW_STRICT=1
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_CAPTURE_BODY=0
-SECURENOW_API_KEY=snk_live_abc123...
-SECURENOW_FIREWALL_TCP=1
-SECURENOW_FIREWALL_SYNC_INTERVAL=30
-SECURENOW_FIREWALL_FAIL_MODE=open
-OTEL_LOG_LEVEL=error
-NODE_ENV=production
-```
+### Production Hardened Configuration
+
+```json
+{
+  "apiKey": "snk_live_...",
+  "app": {
+    "key": "prod-api-uuid",
+    "name": "prod-api",
+    "instance": "https://collector.prod.internal:4318"
+  },
+  "config": {
+    "runtime": { "noUuid": true, "strict": true, "deploymentEnvironment": "production" },
+    "logging": { "enabled": true },
+    "capture": { "body": true, "multipart": true },
+    "firewall": { "enabled": true, "tcp": true, "syncInterval": 30, "failMode": "open" },
+    "otel": { "logLevel": "error" }
+  }
+}
+```
 
 ### Instrument a Docker Container
 
@@ -600,25 +602,27 @@ FROM node:20-slim
 WORKDIR /app
 COPY package*.json ./
 RUN npm ci --omit=dev
-COPY . .
-
-ENV SECURENOW_APPID=my-service
-ENV SECURENOW_INSTANCE=http://otel-collector:4318
-ENV SECURENOW_NO_UUID=1
-ENV SECURENOW_API_KEY=snk_live_abc123...
-
-CMD ["node", "-r", "securenow/register", "src/index.js"]
-```
+COPY . .
+# Mount/copy secret file at runtime as /app/.securenow/credentials.json.
+
+CMD ["node", "-r", "securenow/register", "src/index.js"]
+```
 
 ### Kubernetes with Separate Trace/Log Collectors
 
-```bash
-SECURENOW_APPID=k8s-service
-OTEL_EXPORTER_OTLP_TRACES_ENDPOINT=http://tempo:4318/v1/traces
-OTEL_EXPORTER_OTLP_LOGS_ENDPOINT=http://loki:4318/v1/logs
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
-```
+```json
+{
+  "app": { "key": "k8s-service", "name": "k8s-service" },
+  "config": {
+    "otel": {
+      "tracesEndpoint": "http://tempo:4318/v1/traces",
+      "logsEndpoint": "http://loki:4318/v1/logs"
+    },
+    "logging": { "enabled": true },
+    "runtime": { "noUuid": true }
+  }
+}
+```
 
 ---
 
@@ -626,21 +630,21 @@ SECURENOW_NO_UUID=1
 
 On startup, securenow logs its configuration:
 
-```
-[securenow] pid=12345 SECURENOW_APPID="my-app" → service.name=my-app
-[securenow] OTel SDK started → https://collector:4318/v1/traces
-[securenow] Logging: ENABLED → https://collector:4318/v1/logs
-[securenow] Request body capture: ENABLED (max: 10240 bytes)
-[securenow] Firewall: ENABLED
-[securenow] Firewall: synced 142 blocked IPs
-```
-
-Use `OTEL_LOG_LEVEL=debug` and `SECURENOW_TEST_SPAN=1` to troubleshoot connectivity issues.
+```
+[securenow] app.key="my-app" → service.name=my-app
+[securenow] OTel SDK started → https://collector:4318/v1/traces
+[securenow] Logging: ENABLED → https://collector:4318/v1/logs
+[securenow] Request body capture: ENABLED (max: 10240 bytes)
+[securenow] Firewall: ENABLED
+[securenow] Firewall: synced 142 blocked IPs
+```
+
+Set `config.otel.logLevel` to `debug` in `.securenow/credentials.json` or run `securenow test-span --env <env>` to troubleshoot connectivity issues.
 
 **CLI equivalent** (works without booting the SDK — useful when the app won't start):
 
-```bash
-securenow env                     # show resolved service name, endpoints, env vars
-securenow doctor                  # probe OTLP + API endpoints, exits 1 on failure
-securenow test-span               # send a real span to the collector
-```
+```bash
+securenow env                     # show resolved app key, endpoints, and credentials fields
+securenow doctor                  # probe OTLP + API endpoints, exits 1 on failure
+securenow test-span               # send a real span to the collector
+```