securenow 7.5.1 → 7.6.1

package/NPM_README.md

@@ -9,10 +9,9 @@ OpenTelemetry instrumentation library for Node.js, Next.js, and Nuxt application
 - Built-in sensitive data redaction
 - Request body capture for debugging
 - Multi-layer firewall -- auto-blocks IPs from your SecureNow blocklist
-- `withSecureNow()` config wrapper for Next.js -- eliminates manual `serverExternalPackages`
-- `securenow init` CLI scaffolds instrumentation files for any framework
+- `securenow init` scaffolds Next.js instrumentation and safe `serverExternalPackages`
 - `securenow/firewall-only` entry point for firewall without tracing overhead
-- Fully configurable via environment variables
+- Local and production configuration via `.securenow/credentials.json`
 - Single `-r securenow/register` flag -- works for both CJS and ESM apps
 - Native Nuxt 3 module (`securenow/nuxt`)
 
@@ -68,35 +67,26 @@ npx securenow login
 
 During the browser step, the dashboard enables the selected app's firewall toggle, mints an API key (scoped `firewall:read + blocklist:read + allowlist:read`), and the CLI writes it into `.securenow/credentials.json`. Traces, logs, POST body capture, multipart metadata capture, and firewall protection are enabled by default. No env vars, no copy-pasting keys.
 
-For framework scaffolding (Next.js `instrumentation.ts`, etc.) use:
+For framework scaffolding (Next.js `instrumentation.ts`, `next.config.*`, etc.) use:
 
 ```bash
-npx securenow init --key snk_live_abc123...   # --key is optional now that login handles it
+npx securenow init
+# Optional, when you already have a key and did not use browser login:
+npx securenow init --key snk_live_abc123...
 ```
 
 This detects your framework and:
-- **Next.js**: Creates `instrumentation.ts`, suggests `withSecureNow()` for `next.config.js`
+- **Credentials**: Ensures `.securenow/credentials.json` has secure defaults and explanations
+- **Next.js**: Creates `instrumentation.ts`, adds `serverExternalPackages: ['securenow']` when safe, or prints a Codex/Claude-ready merge prompt for existing files
 - **Nuxt 3**: Suggests adding `securenow/nuxt` to modules
 - **Express / Node.js**: Shows how to add `-r securenow/register` to your start script
-- **All**: Writes `SECURENOW_API_KEY` to `.env.local` when `--key` is provided (not needed if `login` already wrote it to `.securenow/credentials.json`)
+- **All**: Stores `--key` in `.securenow/credentials.json`; no local `.env` file is needed
 
 ### 2. Manual Setup
 
-#### Set Environment Variables
-
-```bash
-# Required: Your application identifier
-export SECURENOW_APPID=my-app
+#### Configure Locally
 
-# Required: Your OTLP collector endpoint
-export SECURENOW_INSTANCE=http://your-otlp-collector:4318
-
-# Optional: Enable logging
-export SECURENOW_LOGGING_ENABLED=1
-
-# Optional: Enable the firewall (set your API key)
-export SECURENOW_API_KEY=snk_live_abc123...
-```
+Run `npx securenow login` to write `.securenow/credentials.json`. The SDK reads app identity, collector URL, firewall key, logging/body-capture defaults, and firewall defaults from that file at boot. Production uses the same file shape via `npx securenow credentials runtime --env production`.
 
 #### Run Your Application
 
@@ -161,8 +151,8 @@ npx securenow login
 # Or use a token for CI/headless environments
 npx securenow login --token <YOUR_JWT>
 
-# Log in for this project only (per-project credentials)
-npx securenow login --local
+# Save to ~/.securenow/ instead of this project
+npx securenow login --global
 
 # Check who you're logged in as (shows auth source)
 npx securenow whoami
@@ -179,11 +169,11 @@ npx securenow api-key clear                    # remove just the key
 # Auto-detect framework and scaffold instrumentation files
 npx securenow init
 
-# Pass your API key to auto-write it to .env.local
+# Pass your API key to store it in .securenow/credentials.json
 npx securenow init --key snk_live_abc123...
 ```
 
-For Next.js projects, `init` creates `instrumentation.ts` (or `.js` if no TypeScript) and tells you how to update `next.config.js` with `withSecureNow()`. 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']` 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.
 
 ### MCP for Codex and Claude
 
@@ -394,7 +384,7 @@ npx securenow redact @request.json --fields internal_id,sessionHash
 npx securenow cidr match 10.0.0.5 10.0.0.0/8,192.168.1.0/24  # exit 0 = hit, 2 = miss
 npx securenow cidr parse 10.0.0.0/24                         # network, broadcast, mask, size
 
-# Show resolved config (service name, endpoints, env vars, firewall layers)
+# Show resolved config (service name, endpoints, credentials, firewall layers)
 npx securenow env                 # human-readable
 npx securenow env --json          # pipe to jq
 
@@ -423,10 +413,10 @@ Config files are stored in `~/.securenow/` (global) or `.securenow/` in the proj
 | File | Description |
 |------|-------------|
 | `~/.securenow/config.json` | API URL, default app, output format |
-| `~/.securenow/credentials.json` | Auth token — global (file permissions: 0600) |
-| `.securenow/credentials.json` | Auth token — project-local (use `login --local`) |
+| `~/.securenow/credentials.json` | Auth token, app, API key, config - global (use `login --global`) |
+| `.securenow/credentials.json` | Auth token, app, API key, config, explanations - project-local default |
 
-**Resolution order:** `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+**Resolution order:** project `.securenow/credentials.json` → global `~/.securenow/credentials.json`. Legacy CLI token overrides still work for existing automation.
 
 ### Global Flags
 
@@ -449,31 +439,31 @@ Every command supports these flags:
 
 ### Multi-Project Sessions
 
-Use `--local` to maintain separate logins per project on the same machine:
+Project-local credentials are the default, so separate projects can use separate SecureNow apps on the same machine:
 
 ```bash
 # In project A — log in as user-a@company.com
 cd ~/projects/project-a
-npx securenow login --local
+npx securenow login
 
 # In project B — log in as user-b@company.com
 cd ~/projects/project-b
-npx securenow login --local
+npx securenow login
 
 # Each project uses its own credentials independently
 npx securenow whoami   # Shows auth source: project (.securenow/)
 ```
 
-You can also use the `SECURENOW_TOKEN` env var for per-terminal sessions without touching any files.
+For new automation, prefer project-local or runtime credentials files. `SECURENOW_TOKEN` remains a legacy fallback for per-terminal sessions.
 
 ### CI/CD Integration
 
 ```bash
-# Authenticate with a token in CI (env var — no file needed)
-SECURENOW_TOKEN=$MY_SECRET npx securenow logs --json
+# Generate a tokenless runtime file from a logged-in project
+npx securenow credentials runtime --env production
 
-# Or use login with explicit token
-npx securenow login --token $SECURENOW_TOKEN
+# Store .securenow/credentials.production.json as a deployment secret file,
+# then materialize it as .securenow/credentials.json in the running app.
 
 # Use --json for machine-readable output
 npx securenow logs --json --level error | jq '.logs'
@@ -545,7 +535,7 @@ npx securenow logs --json --level error | jq '.logs'
 | **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, env vars) |
+| | `env [--json]` | Show resolved config (service name, endpoints, credentials) |
 | | `doctor [--json]` | Probe OTLP + API endpoints, check config |
 | **Settings** | `instances` | List instances |
 | | `instances test <id>` | Test connection |
@@ -598,19 +588,11 @@ module.exports = {
     name: 'my-app',
     script: './app.js',
     node_args: '-r securenow/register',
-    env: {
-      SECURENOW_APPID: 'your-app-key',
-      SECURENOW_INSTANCE: 'https://freetrial.securenow.ai:4318',
-      SECURENOW_API_KEY: 'snk_live_abc123...',
-      SECURENOW_LOGGING_ENABLED: '1',
-      SECURENOW_NO_UUID: '1',
-      SECURENOW_CAPTURE_BODY: '1',
-    }
   }]
 };
 ```
 
-> **Important:** Always use `node_args: '-r securenow/register'` in PM2 configs. Without it, PM2 restarts won't load the SDK, and the firewall won't activate.
+> **Important:** Put `.securenow/credentials.json` in the PM2 app root and keep `node_args: '-r securenow/register'`. PM2 restarts will then load the SDK, traces/logs, body capture, and firewall without any SecureNow env vars.
 
 ---
 
@@ -955,70 +937,50 @@ app.listen(3000, () => console.log('Feathers running on port 3000'));
 
 See [Next.js Complete Guide](./docs/NEXTJS-SETUP-COMPLETE.md) for the full reference.
 
-#### Option A: `withSecureNow()` wrapper (v5.13.0+ -- Recommended)
-
-One wrapper handles everything: `serverExternalPackages` (Next 15) or `experimental.serverComponentsExternalPackages` (Next 14), `instrumentationHook`, and webpack warning suppression.
+#### Option A: `securenow init` (Recommended)
 
-**1. Update `next.config.js`:**
-
-```javascript
-const { withSecureNow } = require('securenow/nextjs-webpack-config');
+The init command handles the boring parts: credentials defaults, `instrumentation.ts`, body auto-capture, and `serverExternalPackages` for Next 15+. If existing files are custom, it prints a Codex/Claude-ready prompt instead of guessing.
 
-module.exports = withSecureNow({
-  // your existing config -- reactStrictMode, images, rewrites, etc.
-});
+```bash
+npx securenow login
+npx securenow init
 ```
 
-**2. Create `instrumentation.ts` (or `.js`):**
+**Generated `instrumentation.ts` (or `.js`):**
 
 ```typescript
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+
 export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    const { registerSecureNow } = require('securenow/nextjs');
-    registerSecureNow();
-  }
+  if (process.env.NEXT_RUNTIME !== 'nodejs') return;
+  const { registerSecureNow } = require('securenow/nextjs');
+  registerSecureNow({ captureBody: true });
+  require('securenow/nextjs-auto-capture');
 }
 ```
 
-Or run `npx securenow init` to auto-generate this file.
+**Next.js 15+ `next.config.*`:**
 
-**3. Set environment variables in `.env.local`:**
+```javascript
+const nextConfig = {
+  serverExternalPackages: ['securenow'],
+};
 
-```env
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-SECURENOW_API_KEY=snk_live_abc123...
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_NO_UUID=1
+export default nextConfig;
 ```
 
-That's it. `withSecureNow()` auto-detects your Next.js version and configures:
-- **Next.js 15+**: Sets `serverExternalPackages` with all 13 required OTel packages
-- **Next.js 14**: Sets `experimental.serverComponentsExternalPackages` and `experimental.instrumentationHook: true`
-- **Both**: Suppresses webpack warnings from OpenTelemetry instrumentation packages
+No `.env.local` is needed locally or in production. Use `npx securenow credentials runtime --env production` and mount/copy the resulting JSON as `.securenow/credentials.json`.
 
 #### Option B: Manual configuration
 
-If you prefer not to use the wrapper, manually add the packages:
+If you prefer not to run `init`, manually externalize SecureNow:
 
 ```javascript
 // next.config.js (Next.js 15+)
 module.exports = {
-  serverExternalPackages: [
-    'securenow',
-    '@opentelemetry/sdk-node',
-    '@opentelemetry/auto-instrumentations-node',
-    '@opentelemetry/instrumentation-http',
-    '@opentelemetry/exporter-trace-otlp-http',
-    '@opentelemetry/exporter-logs-otlp-http',
-    '@opentelemetry/sdk-logs',
-    '@opentelemetry/instrumentation',
-    '@opentelemetry/resources',
-    '@opentelemetry/semantic-conventions',
-    '@opentelemetry/api',
-    '@opentelemetry/api-logs',
-    '@vercel/otel',
-  ],
+  serverExternalPackages: ['securenow'],
 };
 ```
 
@@ -1027,26 +989,12 @@ module.exports = {
 module.exports = {
   experimental: {
     instrumentationHook: true,
-    serverComponentsExternalPackages: [
-      'securenow',
-      '@opentelemetry/sdk-node',
-      '@opentelemetry/auto-instrumentations-node',
-      '@opentelemetry/instrumentation-http',
-      '@opentelemetry/exporter-trace-otlp-http',
-      '@opentelemetry/exporter-logs-otlp-http',
-      '@opentelemetry/sdk-logs',
-      '@opentelemetry/instrumentation',
-      '@opentelemetry/resources',
-      '@opentelemetry/semantic-conventions',
-      '@opentelemetry/api',
-      '@opentelemetry/api-logs',
-      '@vercel/otel',
-    ],
+    serverComponentsExternalPackages: ['securenow'],
   },
 };
 ```
 
-**Why is this needed?** Next.js bundles server code with webpack, which breaks OpenTelemetry's dynamic `require()` calls and monkey-patching. Externalizing these packages keeps them as normal Node.js `require()` calls at runtime. The `withSecureNow()` wrapper handles this automatically.
+**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.
 
 ---
 
@@ -1064,13 +1012,7 @@ export default defineNuxtConfig({
 });
 ```
 
-`.env`:
-
-```env
-SECURENOW_APPID=my-nuxt-app
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-SECURENOW_API_KEY=snk_live_abc123...
-```
+Local and production app identity and secure defaults come from `.securenow/credentials.json`.
 
 That's it -- the Nuxt module handles OTel SDK initialization, Nitro externalization, firewall activation, and request tracing automatically. Optional config:
 
@@ -1103,14 +1045,14 @@ The Nuxt server plugin (v5.13.0+) initializes the firewall independently from Op
 | 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` + `withSecureNow()` |
+| Next.js | Yes | Yes | Yes | Yes | Use `instrumentation.ts` + `serverExternalPackages: ['securenow']` |
 | Nuxt 3 | Yes | Yes | Yes | Yes | Use `securenow/nuxt` module |
 
 ---
 
 ## Firewall -- Automatic IP Blocking
 
-SecureNow can automatically block IPs from your blocklist at the application layer. No code changes -- just provide an API key (via `securenow login`, the `api-key` CLI, or env var) and the firewall activates.
+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.
 
 ### Firewall Is Enabled by Default
 
@@ -1124,12 +1066,11 @@ npx securenow login
 # (b) Already have a key? Write it to the creds file directly:
 npx securenow api-key set snk_live_abc123...
 
-# (c) Old-school env var (still works; preferred for CI/Docker/prod):
-# .env
-SECURENOW_API_KEY=snk_live_abc123...
+# (c) Production? Generate a tokenless runtime credentials file:
+npx securenow credentials runtime --env production
 ```
 
-The SDK resolves the firewall key in this order: `SECURENOW_API_KEY` env var (only if it starts with `snk_live_`) → project `./.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+The SDK resolves the firewall key from project `./.securenow/credentials.json`, then global `~/.securenow/credentials.json`. Legacy `SECURENOW_API_KEY` overrides still work for existing deployments.
 
 On startup, you'll see:
 
@@ -1178,15 +1119,11 @@ This is useful when:
 - You're adding the firewall to a project that uses a different tracing solution
 - For Next.js, this avoids the need for `serverExternalPackages` entirely
 
-Environment variables for firewall-only mode:
+Firewall-only mode uses the same `.securenow/credentials.json` key written by `login`, `api-key set`, or mounted from a runtime credentials file:
 
 ```bash
-SECURENOW_API_KEY=snk_live_abc123...       # Required
-SECURENOW_API_URL=https://api.securenow.ai # Optional (auto-detected)
-SECURENOW_FIREWALL_ENABLED=1               # Default: 1
-SECURENOW_FIREWALL_TCP=1                   # Optional: Layer 2
-SECURENOW_FIREWALL_IPTABLES=1              # Optional: Layer 3
-SECURENOW_FIREWALL_CLOUD=cloudflare        # Optional: Layer 4
+npx securenow credentials runtime --env production
+node -r securenow/firewall-only app.js
 ```
 
 ### Blocking Layers
@@ -1220,14 +1157,34 @@ See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for the full reference.
 
 ---
 
-## Environment Variables Reference
+## Credentials Configuration
+
+Local development and production use `.securenow/credentials.json`. Run `npx securenow login` and `npx securenow init`; for production, run `npx securenow credentials runtime --env production` and mount/copy the generated JSON as `.securenow/credentials.json`.
+
+See [docs/ENVIRONMENT-VARIABLES.md](./docs/ENVIRONMENT-VARIABLES.md) and [docs/ENVIRONMENTS.md](./docs/ENVIRONMENTS.md) for the full credentials and environment reference.
+
+### Credentials Fields
 
-### Required Variables
+| Field | Description | Default |
+|----------|-------------|---------|
+| `app.key` | SecureNow app routing UUID / OTel service name. | chosen during login |
+| `app.instance` | OTLP collector base URL. | `https://freetrial.securenow.ai:4318` |
+| `apiKey` | Scoped firewall key (`snk_live_...`). | 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.capture.body` | Request body capture with redaction. | `true` |
+| `config.capture.multipart` | Multipart metadata capture, never file content. | `true` |
+| `config.firewall.enabled` | Local SDK firewall switch; dashboard toggle is per environment. | `true` |
+| `config.otel.*` | Optional custom endpoints, headers, and log level. | empty |
+
+Legacy env fallback aliases are listed below for existing installs only.
+
+### Legacy App Identity Fallbacks
 
 | Variable | Description | Example |
 |----------|-------------|---------|
-| `SECURENOW_APPID` | Your application identifier. Used as the service name in traces. | `my-app` |
-| `SECURENOW_INSTANCE` | Base URL of your OTLP collector endpoint. | `http://localhost:4318` |
+| `SECURENOW_APPID` | Fallback for missing credentials `app.key`. Used as the app routing key/service name. | `<uuid>` |
+| `SECURENOW_INSTANCE` | Fallback for missing credentials `app.instance`. Base URL of your OTLP collector endpoint. | `https://freetrial.securenow.ai:4318` |
 
 ### Optional Configuration
 
@@ -1235,18 +1192,18 @@ See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for the full reference.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OTEL_SERVICE_NAME` | Alternative to SECURENOW_APPID. Standard OpenTelemetry variable. | - |
-| `SECURENOW_NO_UUID` | Set to `1` to disable UUID suffix on service name. Useful for clustered apps. | `0` |
-| `SECURENOW_STRICT` | Set to `1` to exit process if SECURENOW_APPID is not set in cluster mode. | `0` |
+| `OTEL_SERVICE_NAME` | Fallback for missing `app.name`. Standard OpenTelemetry variable. | - |
+| `SECURENOW_NO_UUID` | Legacy fallback for `config.runtime.noUuid`. | `0` |
+| `SECURENOW_STRICT` | Legacy fallback for `config.runtime.strict`. | `0` |
 
 #### Connection Settings
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `OTEL_EXPORTER_OTLP_ENDPOINT` | Alternative to SECURENOW_INSTANCE. Standard OpenTelemetry variable. | - |
-| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Override traces endpoint specifically. | `{SECURENOW_INSTANCE}/v1/traces` |
-| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Override logs endpoint specifically. | `{SECURENOW_INSTANCE}/v1/logs` |
-| `OTEL_EXPORTER_OTLP_HEADERS` | Headers to send with OTLP exports. Format: `key1=value1,key2=value2` | - |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | Fallback for `config.otel.endpoint`. | - |
+| `OTEL_EXPORTER_OTLP_TRACES_ENDPOINT` | Fallback for `config.otel.tracesEndpoint`. | `{instance}/v1/traces` |
+| `OTEL_EXPORTER_OTLP_LOGS_ENDPOINT` | Fallback for `config.otel.logsEndpoint`. | `{instance}/v1/logs` |
+| `OTEL_EXPORTER_OTLP_HEADERS` | Fallback for `config.otel.headers`. Format: `key1=value1,key2=value2` | - |
 
 #### Logging
 
@@ -1277,7 +1234,7 @@ See the [Firewall Guide](./docs/FIREWALL-GUIDE.md) for the full reference.
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `SECURENOW_API_KEY` | API key with `firewall:read` scope. Enables the firewall when set. Since v7.1.0 the firewall also reads this from `.securenow/credentials.json` (written by `securenow login` or `securenow api-key set`); env var only wins if it starts with `snk_live_`. | from creds file |
+| `SECURENOW_API_KEY` | Legacy firewall key override. Prefer `apiKey` in `.securenow/credentials.json`. | from creds file |
 | `SECURENOW_API_URL` | SecureNow API base URL. Auto-detected for co-located deployments (falls back to `http://localhost:4000` on ECONNREFUSED). | `https://api.securenow.ai` |
 | `SECURENOW_FIREWALL_ENABLED` | Master kill-switch. Set to `0` to disable. | `1` |
 | `SECURENOW_FIREWALL_VERSION_INTERVAL` | Seconds between version checks (lightweight ETag-based). | `10` |
@@ -1304,7 +1261,7 @@ See [Firewall Guide](./docs/FIREWALL-GUIDE.md) for complete details on all layer
 
 | Variable | Description | Default |
 |----------|-------------|---------|
-| `NODE_ENV` | Deployment environment name. Sent as `deployment.environment` attribute. | `production` |
+| `SECURENOW_ENVIRONMENT` / `SECURENOW_DEPLOYMENT_ENVIRONMENT` / `NODE_ENV` | Fallback for `config.runtime.deploymentEnvironment`. | `production` |
 
 ---
 
@@ -1388,11 +1345,7 @@ logger.emit({
 
 ```bash
 # Enable tracing + logging (console auto-forwarding is built-in since v5.6.0)
-NODE_OPTIONS="-r securenow/register" \
-SECURENOW_APPID=my-app \
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318 \
-SECURENOW_LOGGING_ENABLED=1 \
-node app.js
+node -r securenow/register app.js
 ```
 
 ---
@@ -1472,41 +1425,34 @@ export SECURENOW_SENSITIVE_FIELDS="custom_secret,internal_token"
 
 ### Complete Example with All Options
 
-```bash
-# Service identification
-export SECURENOW_APPID=my-production-app
-export SECURENOW_NO_UUID=1
-export SECURENOW_STRICT=1
-
-# OTLP backend
-export SECURENOW_INSTANCE=http://collector.example.com:4318
-export OTEL_EXPORTER_OTLP_HEADERS="x-api-key=your-api-key"
-
-# Logging
-export SECURENOW_LOGGING_ENABLED=1
-
-# Request body capture
-export SECURENOW_CAPTURE_BODY=1
-export SECURENOW_MAX_BODY_SIZE=20480
-export SECURENOW_SENSITIVE_FIELDS="internal_id,session_key"
-
-# Firewall
-export SECURENOW_API_KEY=snk_live_abc123...
-export SECURENOW_FIREWALL_TCP=1
-export SECURENOW_FIREWALL_VERSION_INTERVAL=10
-export SECURENOW_FIREWALL_SYNC_INTERVAL=300
-
-# Environment
-export NODE_ENV=production
-
-# Debugging
-export OTEL_LOG_LEVEL=info
-
-# Disable specific instrumentations
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns
-
-# Run application
-NODE_OPTIONS="-r securenow/register" node app.js
+```json
+{
+  "apiKey": "snk_live_...",
+  "app": {
+    "key": "my-production-app",
+    "name": "my-production-app",
+    "instance": "http://collector.example.com:4318"
+  },
+  "config": {
+    "runtime": { "noUuid": true, "strict": true, "deploymentEnvironment": "production" },
+    "otel": {
+      "headers": { "x-api-key": "your-api-key" },
+      "logLevel": "info",
+      "disableInstrumentations": ["fs", "dns"]
+    },
+    "logging": { "enabled": true },
+    "capture": {
+      "body": true,
+      "maxBodySize": 20480,
+      "sensitiveFields": ["internal_id", "session_key"]
+    },
+    "firewall": {
+      "tcp": true,
+      "versionCheckInterval": 10,
+      "syncInterval": 300
+    }
+  }
+}
 ```
 
 ### Using Multiple Logger Instances
@@ -1547,15 +1493,10 @@ if (isLoggingEnabled()) {
 
 ### Programmatic Configuration
 
-While environment variables are recommended, you can also configure programmatically:
+Use `.securenow/credentials.json` for local development, tests, CI, and production:
 
 ```javascript
-// Set environment variables before requiring securenow
-process.env.SECURENOW_APPID = 'my-app';
-process.env.SECURENOW_INSTANCE = 'http://localhost:4318';
-process.env.SECURENOW_LOGGING_ENABLED = '1';
-
-// Then initialize (console log forwarding is automatic since v5.6.0)
+// Reads .securenow/credentials.json from the project root.
 require('securenow/register');
 ```
 
@@ -1636,14 +1577,14 @@ bootstrap();
 
 ### Traces Not Appearing
 
-**Check 1: Verify environment variables**
+**Check 1: Verify credentials resolution**
 
 ```bash
-echo $SECURENOW_APPID
-echo $SECURENOW_INSTANCE
+npx securenow env
+npx securenow status --env local
 ```
 
-Both should output values.
+The output should show an app key, collector endpoint, and deployment environment from `.securenow/credentials.json`.
 
 **Check 2: Verify OTLP collector is running**
 
@@ -1652,11 +1593,14 @@ curl http://localhost:4318/v1/traces
 # Should return 200 or 405 (method not allowed)
 ```
 
-**Check 3: Enable debug logging**
+**Check 3: Enable debug logging in credentials**
 
-```bash
-export OTEL_LOG_LEVEL=debug
-node app.js
+```json
+{
+  "config": {
+    "otel": { "logLevel": "debug" }
+  }
+}
 ```
 
 Look for lines like:
@@ -1680,10 +1624,10 @@ require('securenow/register');
 
 ### Firewall Not Blocking IPs
 
-**Check 1: Is `SECURENOW_API_KEY` set?**
+**Check 1: Is an API key in `.securenow/credentials.json`?**
 
 ```bash
-echo $SECURENOW_API_KEY
+npx securenow api-key show
 ```
 
 **Check 2: Is the IP in the blocklist?**
@@ -1709,7 +1653,7 @@ After blocking an IP, it takes 10-15 seconds to propagate (one version-check int
 
 **Check 5: Are you behind a proxy?**
 
-Set `SECURENOW_TRUSTED_PROXIES` to your proxy's IP so the firewall sees the real client IP.
+Add your proxy IPs to `config.networking.trustedProxies` in `.securenow/credentials.json` so the firewall sees the real client IP.
 
 **Check 6: Using PM2?**
 
@@ -1719,9 +1663,12 @@ Make sure `node_args: '-r securenow/register'` is in your `ecosystem.config.cjs`
 
 **Check 1: Is logging enabled?**
 
-```bash
-echo $SECURENOW_LOGGING_ENABLED
-# Should output: 1
+```json
+{
+  "config": {
+    "logging": { "enabled": true }
+  }
+}
 ```
 
 **Check 2: Verify console instrumentation is loaded**
@@ -1748,9 +1695,12 @@ curl http://localhost:4318/v1/logs
 
 **Check 1: Make sure body capture was not explicitly disabled**
 
-```bash
-echo $SECURENOW_CAPTURE_BODY
-# Should be empty, 1, or true. Remove SECURENOW_CAPTURE_BODY=0 to re-enable defaults.
+```json
+{
+  "config": {
+    "capture": { "body": true }
+  }
+}
 ```
 
 **Check 2: Verify content type**
@@ -1762,42 +1712,59 @@ Body capture only works for:
 
 **Check 3: Check body size**
 
-Bodies larger than `SECURENOW_MAX_BODY_SIZE` are truncated:
+Bodies larger than `config.capture.maxBodySize` are truncated:
 
-```bash
-export SECURENOW_MAX_BODY_SIZE=20480  # Increase to 20KB
+```json
+{
+  "config": {
+    "capture": { "maxBodySize": 20480 }
+  }
+}
 ```
 
 ### High Memory Usage
 
 **Option 1: Disable body capture**
 
-```bash
-export SECURENOW_CAPTURE_BODY=0
+```json
+{
+  "config": {
+    "capture": { "body": false }
+  }
+}
 ```
 
 **Option 2: Reduce body size limit**
 
-```bash
-export SECURENOW_MAX_BODY_SIZE=5120  # 5KB
+```json
+{
+  "config": {
+    "capture": { "maxBodySize": 5120 }
+  }
+}
 ```
 
 **Option 3: Disable specific instrumentations**
 
-```bash
-export SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns,net
+```json
+{
+  "config": {
+    "otel": { "disableInstrumentations": ["fs", "dns", "net"] }
+  }
+}
 ```
 
 ### Next.js Instrumentation Not Working
 
-**Check 1: Using `withSecureNow()`?**
+**Check 1: Is `securenow` externalized?**
 
 ```javascript
-const { withSecureNow } = require('securenow/nextjs-webpack-config');
-module.exports = withSecureNow({ /* your config */ });
+module.exports = {
+  serverExternalPackages: ['securenow'],
+};
 ```
 
-This auto-handles `serverExternalPackages` / `experimental.serverComponentsExternalPackages` and `instrumentationHook` based on your Next.js version.
+For Next.js < 15, add `securenow` to `experimental.serverComponentsExternalPackages` and enable `experimental.instrumentationHook`.
 
 **Check 2: Verify instrumentation file location**
 
@@ -1805,7 +1772,7 @@ This auto-handles `serverExternalPackages` / `experimental.serverComponentsExter
 
 **Check 3: Check for OTel MODULE_NOT_FOUND errors**
 
-If you see `MODULE_NOT_FOUND` for `@opentelemetry/*` packages, your `next.config.js` is missing the externalization. Use `withSecureNow()` to fix this automatically.
+If you see `MODULE_NOT_FOUND` for `@opentelemetry/*` packages, your `next.config.js` is missing the externalization. Run `npx securenow init`; if your config is custom, use the prompt it prints to merge the edit safely.
 
 **Check 4: Restart dev server**
 
@@ -1818,10 +1785,14 @@ npm run dev
 
 **Problem: Different service names for each worker**
 
-**Solution: Use SECURENOW_NO_UUID**
+**Solution: Set `config.runtime.noUuid`**
 
-```bash
-export SECURENOW_NO_UUID=1
+```json
+{
+  "config": {
+    "runtime": { "noUuid": true }
+  }
+}
 ```
 
 This uses the same service name for all workers.
@@ -1838,11 +1809,6 @@ module.exports = {
     script: './app.js',
     instances: 4,
     node_args: '-r securenow/register',
-    env: {
-      SECURENOW_APPID: 'my-app',
-      SECURENOW_INSTANCE: 'http://localhost:4318',
-      SECURENOW_API_KEY: 'snk_live_abc123...',
-    }
   }]
 };
 ```
@@ -1853,18 +1819,16 @@ Without `node_args`, PM2 starts your script directly without the securenow prelo
 
 ## Best Practices
 
-### 1. Use Environment Variables
+### 1. Use the Credentials File
 
-Don't hardcode configuration. Use environment variables:
+Do not hardcode configuration in code or deployment dashboards. Use `.securenow/credentials.json` locally and mount the tokenless runtime file in production:
 
 ```javascript
 // Bad
 process.env.SECURENOW_APPID = 'hardcoded-value';
 
-// Good -- use .env file or export
-// .env
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://localhost:4318
+// Good: use .securenow/credentials.json
+// { "app": { "key": "my-app", "instance": "https://freetrial.securenow.ai:4318" } }
 ```
 
 ### 2. Use Structured Logging
@@ -1933,12 +1897,12 @@ const apiLogger = getLogger('api', '1.0.0');
 
 ### 6. Disable Body Capture Outside Development
 
-```bash
-# .env.development
-SECURENOW_CAPTURE_BODY=1
-
-# .env.production
-SECURENOW_CAPTURE_BODY=0
+```json
+{
+  "config": {
+    "capture": { "body": false }
+  }
+}
 ```
 
 ---