securenow 7.0.0-anas.2 → 7.1.0

package/SKILL-CLI.md

@@ -18,13 +18,17 @@ npx securenow <command>
 ### Authenticate
 
 ```bash
-securenow login             # opens browser OAuth; stores JWT in ~/.securenow/credentials.json
+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 login --local     # save credentials to this project only (.securenow/)
-securenow whoami             # verify session (shows auth source)
+securenow whoami            # verify session (shows email, app, auth source)
 ```
 
-**Per-project credentials:** Use `--local` to keep separate logins in different project directories on the same machine. Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+**Zero-config flow (v7+):** the browser step lets the user pick (or create) an app. The CLI stores the app's **key (UUID)**, **name**, and **instance URL** in `.securenow/credentials.json`. The SDK reads this file at boot and sends traces/logs to the right app bucket — **no env vars required for local dev**.
+
+Credentials resolve in order: `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+
+For CI / Docker / production, set env vars directly (always win over the file): `SECURENOW_APPID=<uuid>`, `SECURENOW_INSTANCE=<url>`, `SECURENOW_API_KEY=<uuid>`.
 
 ### Integrate With Your App
 

package/app-config.js

@@ -14,6 +14,10 @@
  *   - What human label to show?     (resolveAppName) — display only, never
  *                                     sent to the collector.
  *   - Which OTLP collector to hit?  (resolveInstance)
+ *   - Which firewall API key?       (resolveApiKey) — the snk_live_... key the
+ *                                     firewall sends as Bearer to /api/firewall
+ *                                     for blocklist sync. Separate from the
+ *                                     app routing key: this one is user-scoped.
  *
  * Resolution order (first non-empty wins):
  *
@@ -25,7 +29,7 @@
  *   5. Hard default / null
  *
  * Credentials file schema:
- *   { token, email, expiresAt, app: { key: <uuid>, name: <display>, instance } }
+ *   { token, email, expiresAt, apiKey: <snk_live_...>, app: { key, name, instance } }
  */
 
 const fs = require('fs');
@@ -112,6 +116,21 @@ function resolveAppId() {
   return resolveAppKey() || resolveAppName();
 }
 
+// Firewall / user-scoped API key (snk_live_...).
+// Distinct from resolveAppKey: that one is the application UUID for OTel
+// routing. This one authenticates the firewall blocklist sync to /api/firewall,
+// so it must look like a real `snk_live_` key — the app UUID won't pass auth.
+function resolveApiKey() {
+  const fromEnv = pick(process.env.SECURENOW_API_KEY);
+  if (fromEnv && fromEnv.startsWith('snk_live_')) return fromEnv;
+
+  const creds = loadCredentials();
+  const fromCreds = creds && pick(creds.apiKey);
+  if (fromCreds && fromCreds.startsWith('snk_live_')) return fromCreds;
+
+  return null;
+}
+
 function resolveInstance() {
   const fromEnv =
     pick(process.env.SECURENOW_INSTANCE) ||
@@ -143,6 +162,7 @@ module.exports = {
   resolveAppKey,
   resolveAppName,
   resolveAppId,
+  resolveApiKey,
   resolveInstance,
   resolveAll,
   loadCredentials,

package/cli/apiKey.js

@@ -0,0 +1,55 @@
+'use strict';
+
+const config = require('./config');
+const ui = require('./ui');
+
+function maskKey(key) {
+  if (!key || key.length < 16) return key || '';
+  return `${key.slice(0, 12)}••••••${key.slice(-4)}`;
+}
+
+async function set(args, flags) {
+  const key = args[0];
+  if (!key) {
+    ui.error('API key is required. Usage: securenow api-key set <snk_live_...>');
+    process.exit(1);
+  }
+  if (!key.startsWith('snk_live_')) {
+    ui.error('API key must start with "snk_live_"');
+    ui.info('Create one in the dashboard: Settings → API Keys');
+    process.exit(1);
+  }
+
+  const local = flags.global ? false : true;
+  config.setApiKey(key, { local });
+  if (local) config.ensureLocalGitignore();
+
+  ui.success(`API key saved (${maskKey(key)})`);
+  ui.info(local
+    ? 'Stored in project .securenow/credentials.json (local)'
+    : 'Stored in ~/.securenow/credentials.json (global)');
+  ui.info('The firewall will now pick it up automatically — no SECURENOW_API_KEY env var needed.');
+}
+
+async function clear(args, flags) {
+  const local = flags.global ? false : true;
+  const existing = config.getApiKey();
+  config.clearApiKey({ local });
+  if (existing) {
+    ui.success(`Cleared API key (${maskKey(existing)})`);
+  } else {
+    ui.info('No API key was stored');
+  }
+}
+
+async function show() {
+  const key = config.getApiKey();
+  if (!key) {
+    ui.info('No API key stored in credentials. Falling back to SECURENOW_API_KEY env var.');
+    return;
+  }
+  console.log(maskKey(key));
+  ui.info(`Source: ${config.getAuthSource()}`);
+}
+
+module.exports = { set, clear, show };

package/cli/apps.js

@@ -64,17 +64,10 @@ async function list(args, flags) {
     ui.table(['Name', 'Key', 'Instance', 'Created'], rows);
     console.log('');
 
-    if (apps.length > 0) {
-      console.log(`  ${ui.c.bold('Add to your .env:')}`);
-      const first = apps.find(a => a.key === defaultApp) || apps[0];
-      const firstInst = first.instanceId ? instMap[first.instanceId] : null;
-      console.log(`    SECURENOW_APPID=${first.key}`);
-      console.log(`    SECURENOW_INSTANCE=${instanceUrl(firstInst)}`);
-      console.log('');
-    }
-
     if (!defaultApp && apps.length > 0) {
-      ui.info(`Tip: Set a default app with ${ui.c.bold('securenow config set defaultApp <key>')}`);
+      console.log(`  ${ui.c.bold('Use one of these apps in the current project:')}`);
+      console.log(`    ${ui.c.bold('securenow apps default <key>')}`);
+      console.log(`  ${ui.c.dim('(or run `securenow login` to pick interactively)')}`);
       console.log('');
     }
   } catch (err) {
@@ -133,12 +126,9 @@ async function create(args, flags) {
     ]);
 
     console.log('');
-    console.log(`  ${ui.c.bold('Add to your .env.local:')}`);
-    console.log('');
-    console.log(`    SECURENOW_APPID=${app.key}`);
-    console.log(`    SECURENOW_INSTANCE=${envUrl}`);
-    console.log('');
-    ui.info(`Set as default: ${ui.c.bold(`securenow config set defaultApp ${app.key}`)}`);
+    console.log(`  ${ui.c.bold('Use this app in the current project:')}`);
+    console.log(`    ${ui.c.bold(`securenow apps default ${app.key}`)}`);
+    console.log(`  ${ui.c.dim('(writes .securenow/credentials.json — no env var needed)')}`);
     console.log('');
 
     if (flags.json) {
@@ -251,9 +241,8 @@ async function info(args, flags) {
     ]);
 
     console.log('');
-    console.log(`  ${ui.c.bold('Environment variables:')}`);
-    console.log(`    SECURENOW_APPID=${app.key}`);
-    console.log(`    SECURENOW_INSTANCE=${envUrl}`);
+    console.log(`  ${ui.c.bold('Use in current project:')}   ${ui.c.bold(`securenow apps default ${app.key}`)}`);
+    console.log(`  ${ui.c.bold('Or override via env:')}       ${ui.c.dim(`SECURENOW_APPID=${app.key} SECURENOW_INSTANCE=${envUrl}`)}`);
     console.log('');
   } catch (err) {
     s.fail('Failed to fetch application');

package/cli/auth.js

@@ -45,6 +45,7 @@ async function loginWithBrowser() {
   return new Promise((resolve, reject) => {
     let pendingToken = null;
     let pendingApp = null;
+    let pendingApiKey = null;
 
     const server = http.createServer((req, res) => {
       const url = new URL(req.url, `http://127.0.0.1`);
@@ -56,6 +57,7 @@ async function loginWithBrowser() {
         const appKey = url.searchParams.get('app_key');
         const appName = url.searchParams.get('app_name');
         const appInstance = url.searchParams.get('app_instance');
+        const apiKey = url.searchParams.get('api_key');
 
         res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' });
 
@@ -82,6 +84,9 @@ async function loginWithBrowser() {
               instance: appInstance || null,
             };
           }
+          if (apiKey && apiKey.startsWith('snk_live_')) {
+            pendingApiKey = apiKey;
+          }
           const payload = decodeJwtPayload(token);
           const email = payload?.email || 'unknown account';
           const safeEmail = email.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
@@ -139,10 +144,12 @@ async function loginWithBrowser() {
         res.end('{"ok":true}');
         const token = pendingToken;
         const app = pendingApp;
+        const apiKeyFromLogin = pendingApiKey;
         pendingToken = null;
         pendingApp = null;
+        pendingApiKey = null;
         server.close();
-        resolve({ token, app });
+        resolve({ token, app, apiKey: apiKeyFromLogin });
         return;
       }
 
@@ -219,12 +226,13 @@ async function login(args, flags) {
   }
 
   try {
-    const { token, app } = await loginWithBrowser();
+    const { token, app, apiKey } = await loginWithBrowser();
     const payload = decodeJwtPayload(token);
     const email = payload?.email || 'unknown';
     const exp = payload?.exp ? payload.exp * 1000 : null;
 
     config.setAuth(token, email, exp, { local, app });
+    if (apiKey) config.setApiKey(apiKey, { local });
     if (local) config.ensureLocalGitignore();
     console.log('');
     ui.success(`Logged in as ${ui.c.bold(email)}`);
@@ -232,6 +240,9 @@ async function login(args, flags) {
     if (app && (app.name || app.key)) {
       ui.info(`Linked to app ${ui.c.bold(app.name || app.key)}${app.key ? ` (${ui.c.dim(app.key)})` : ''}`);
     }
+    if (apiKey) {
+      ui.info(`Firewall API key saved — the firewall will activate automatically on next start`);
+    }
     if (exp) {
       const days = Math.ceil((exp - Date.now()) / (1000 * 60 * 60 * 24));
       ui.info(`Session expires in ${days} days`);

package/cli/config.js

@@ -135,6 +135,27 @@ function getApp() {
   return creds && creds.app ? creds.app : null;
 }
 
+function setApiKey(apiKey, { local } = {}) {
+  const useLocal = local === true || (local == null && hasLocalCredentials());
+  const targetFile = useLocal ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
+  const existing = loadJSON(targetFile);
+  saveJSON(targetFile, { ...existing, apiKey });
+}
+
+function clearApiKey({ local } = {}) {
+  const useLocal = local === true || (local == null && hasLocalCredentials());
+  const targetFile = useLocal ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
+  const existing = loadJSON(targetFile);
+  if (!existing || !existing.apiKey) return;
+  delete existing.apiKey;
+  saveJSON(targetFile, existing);
+}
+
+function getApiKey() {
+  const creds = loadCredentials();
+  return creds && creds.apiKey ? creds.apiKey : null;
+}
+
 function setApp(app, { local } = {}) {
   const useLocal = local === true || (local == null && hasLocalCredentials());
   const targetFile = useLocal ? LOCAL_CREDENTIALS_FILE : CREDENTIALS_FILE;
@@ -193,6 +214,9 @@ module.exports = {
   setAuth,
   getApp,
   setApp,
+  setApiKey,
+  clearApiKey,
+  getApiKey,
   getAuthSource,
   hasLocalCredentials,
   ensureLocalGitignore,

package/cli/diagnostics.js

@@ -25,7 +25,9 @@ function resolvedConfig() {
       ? `${process.env.OTEL_EXPORTER_OTLP_ENDPOINT.replace(/\/$/, '')}/v1/logs`
       : `${instance.replace(/\/$/, '')}/v1/logs`);
   const headers = process.env.OTEL_EXPORTER_OTLP_HEADERS || '';
-  const apiKey = process.env.SECURENOW_API_KEY || '';
+  // Resolve firewall API key the same way the SDK does: env, then
+  // .securenow/credentials.json (project-local, then global).
+  const apiKey = require('../app-config').resolveApiKey() || '';
   const apiUrl = config.getApiUrl();
   const loggingEnabled = !/^(0|false)$/i.test(String(process.env.SECURENOW_LOGGING_ENABLED ?? ''));
   const captureBody = !/^(0|false)$/i.test(String(process.env.SECURENOW_CAPTURE_BODY ?? ''));

package/cli.js

@@ -73,6 +73,30 @@ const COMMANDS = {
     usage: 'securenow whoami',
     run: () => require('./cli/auth').whoami(),
   },
+  'api-key': {
+    desc: 'Manage the firewall API key stored in .securenow/credentials.json',
+    usage: 'securenow api-key <subcommand> [options]',
+    sub: {
+      set: {
+        desc: 'Save an API key (snk_live_...) to the credentials file',
+        usage: 'securenow api-key set <snk_live_...> [--global]',
+        flags: { global: 'Save to ~/.securenow/ instead of project-local' },
+        run: (a, f) => require('./cli/apiKey').set(a, f),
+      },
+      clear: {
+        desc: 'Remove the stored API key',
+        usage: 'securenow api-key clear [--global]',
+        flags: { global: 'Clear from ~/.securenow/ instead of project-local' },
+        run: (a, f) => require('./cli/apiKey').clear(a, f),
+      },
+      show: {
+        desc: 'Print the masked API key currently in use',
+        usage: 'securenow api-key show',
+        run: () => require('./cli/apiKey').show(),
+      },
+    },
+    defaultSub: 'show',
+  },
   apps: {
     desc: 'Manage applications',
     usage: 'securenow apps <subcommand> [options]',

package/docs/ALL-FRAMEWORKS-QUICKSTART.md

@@ -2,6 +2,14 @@
 
 Protect any Node.js app in minutes. This guide covers **installation, CLI commands, the forensics chat, and IP blocking** for all 11 supported frameworks.
 
+> **v7+ — zero-config shortcut.** For local dev, the short version is:
+> ```bash
+> npm install securenow
+> npx securenow login              # pick/create app in the browser
+> node -r securenow/register app.js
+> ```
+> No `.env` setup. Credentials live in `.securenow/credentials.json` (gitignored automatically). Skip "Step 2 — Set Environment Variables" below unless you're configuring CI / Docker / prod.
+
 ---
 
 ## Table of Contents

package/docs/ENVIRONMENT-VARIABLES.md

@@ -2,32 +2,41 @@
 
 Complete reference for all environment variables supported by SecureNow.
 
+> **v7+: env vars are all optional.** For local dev, `npx securenow login` writes `.securenow/credentials.json` and the SDK reads it at boot — no env vars needed. Env vars are still supported (and always take precedence) for CI / Docker / production.
+
+> **Resolution order** (first non-empty wins): env var → `./.securenow/credentials.json` → `~/.securenow/credentials.json` → `package.json#name` (label only) → default.
+
 ---
 
 ## Quick Reference Table
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| **SECURENOW_APPID** | Required | - | Application identifier / service name |
-| **SECURENOW_INSTANCE** | Required | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
-| **SECURENOW_LOGGING_ENABLED** | Optional | `1` | Enable/disable logging |
-| **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on service name |
-| **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in cluster mode |
-| **SECURENOW_CAPTURE_BODY** | Optional | `0` | Enable request body capture |
+| **SECURENOW_APPID** | Optional | from credentials file | App routing key (UUID). Sent as OTel `service.name`. |
+| **SECURENOW_INSTANCE** | Optional | `https://freetrial.securenow.ai:4318` | OTLP collector base URL |
+| **SECURENOW_API_KEY** | Optional | from credentials file | API key (same UUID as APPID). Enables firewall. |
+| **SECURENOW_LOGGING_ENABLED** | Optional | `1` (on) | Forward `console.*` as OTLP logs. Set to `0` to disable. |
+| **SECURENOW_CAPTURE_BODY** | Optional | `1` (on) | Capture request body. Set to `0` for Fastify/Hapi/Hono. |
+| **SECURENOW_CAPTURE_MULTIPART** | Optional | `1` (on) | Capture multipart field/file metadata. |
 | **SECURENOW_MAX_BODY_SIZE** | Optional | `10240` | Max body size in bytes |
-| **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated list of fields to redact |
-| **SECURENOW_CAPTURE_MULTIPART** | Optional | `0` | Enable multipart/form-data streaming capture |
-| **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of packages to disable |
-| **SECURENOW_TEST_SPAN** | Optional | `0` | Emit test span on startup |
-| **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID |
+| **SECURENOW_SENSITIVE_FIELDS** | Optional | - | Comma-separated extra fields to redact |
+| **SECURENOW_NO_UUID** | Optional | `0` | Disable UUID suffix on `service.instance.id` |
+| **SECURENOW_STRICT** | Optional | `0` | Exit if APPID missing in PM2 cluster mode |
+| **SECURENOW_DISABLE_INSTRUMENTATIONS** | Optional | - | Comma-separated list of OTel instrumentations to disable |
+| **SECURENOW_TEST_SPAN** | Optional | `0` | Emit a single test span on startup (prefer `npx securenow test-span`) |
+| **SECURENOW_HIDE_BANNER** | Optional | `0` | Hide the free-trial banner |
+| **SECURENOW_FIREWALL_ENABLED** | Optional | `1` (on when API key is set) | Firewall master switch |
+| **SECURENOW_ENABLE_MONGODB_INSTRUMENTATION** | Optional | `0` | Opt in to MongoDB instrumentation (off by default since a cursor bug on mongodb@6.6+; safe since SDK v6.0.2) |
+| **OTEL_SERVICE_NAME** | Optional | - | Alternative to SECURENOW_APPID (label only, no routing) |
 | **OTEL_EXPORTER_OTLP_ENDPOINT** | Optional | - | Alternative to SECURENOW_INSTANCE |
-| **OTEL_EXPORTER_OTLP_HEADERS** | Optional | - | Headers for OTLP requests |
+| **OTEL_EXPORTER_OTLP_HEADERS** | Optional | auto (`x-api-key` injected) | Additional OTLP headers |
 | **OTEL_EXPORTER_OTLP_TRACES_ENDPOINT** | Optional | - | Override traces endpoint |
 | **OTEL_EXPORTER_OTLP_LOGS_ENDPOINT** | Optional | - | Override logs endpoint |
-| **OTEL_LOG_LEVEL** | Optional | `none` | SDK log level |
+| **OTEL_LOG_LEVEL** | Optional | `none` | SDK log verbosity (`debug`/`info`/`warn`/`error`) |
 | **NODE_ENV** | Optional | `production` | Environment name |
-| **SECURENOW_API_KEY** | Optional | - | API key for firewall (auto-activates when set) |
-| **SECURENOW_API_URL** | Optional | `https://api.securenow.ai` | API base URL |
+| **SECURENOW_API_URL** | Optional | `https://api.securenow.ai` | Dashboard API base URL |
+| **SECURENOW_APP_URL** | Optional | `https://app.securenow.ai` | Dashboard web base URL |
+| **SECURENOW_TOKEN** | Optional | from credentials file | Auth token (overrides credentials file for CI) |
 | **SECURENOW_FIREWALL_ENABLED** | Optional | `1` | Firewall master kill-switch |
 | **SECURENOW_FIREWALL_SYNC_INTERVAL** | Optional | `60` | Blocklist refresh interval (seconds) |
 | **SECURENOW_FIREWALL_FAIL_MODE** | Optional | `open` | Behavior when API unreachable: open/closed |

package/docs/LOGGING-QUICKSTART.md

@@ -1,36 +1,23 @@
-# SecureNow Logging - Quick Start
+# SecureNow Logging — Quick Start
 
-Get logging set up in your Node.js app in under 2 minutes!
+Get logging sent to your SecureNow dashboard in under 2 minutes.
 
-**Since v5.6.0:** When `SECURENOW_LOGGING_ENABLED=1` is set, all `console.log` / `warn` / `error` / `info` / `debug` calls are automatically forwarded as OTLP log records. You only need `require('securenow/register')`—a separate `console-instrumentation` preload is no longer required.
+**Since v7.0.0:** Logging is **on by default**. `console.log` / `warn` / `error` / `info` / `debug` calls are automatically forwarded as OTLP log records. Disable with `SECURENOW_LOGGING_ENABLED=0` if you don't want it.
 
 ---
 
-## 1. Install
+## 1. Install + login
 
 ```bash
 npm install securenow
+npx securenow login    # pick/create your app in the browser
 ```
 
----
-
-## 2. Configure Environment
-
-Create `.env` file or export variables:
-
-```bash
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_APPID=my-app
-SECURENOW_INSTANCE=http://your-otlp-backend:4318
-
-# For SecureNow / hosted OTLP (example):
-# SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-# OTEL_EXPORTER_OTLP_HEADERS="x-api-key=<your-key>"
-```
+`login` writes `.securenow/credentials.json` locally. No `.env` setup required.
 
 ---
 
-## 3. Add to Your App
+## 2. Add to Your App
 
 **Option A: Automatic Console Logging (Easiest)**
 
@@ -53,7 +40,7 @@ NODE_OPTIONS="-r securenow/register" node app.js
 
 ---
 
-## 4. Run Your App
+## 3. Run Your App
 
 ```bash
 node app.js
@@ -70,12 +57,18 @@ You should see:
 
 ---
 
-## 5. View Logs in SecureNow
+## 4. View Logs in SecureNow
 
 1. Open your SecureNow dashboard
 2. Go to **Logs** section
-3. Filter by `service.name = my-app`
-4. See all your logs with automatic trace correlation!
+3. Your logs appear under the app you picked during `securenow login`
+4. All logs come with automatic trace correlation
+
+Or from the CLI:
+
+```bash
+npx securenow logs --minutes 5
+```
 
 ---
 
@@ -102,20 +95,13 @@ app.listen(3000);
 
 ```typescript
 // instrumentation.ts (in project root)
-export async function register() {
-  if (process.env.NEXT_RUNTIME === 'nodejs') {
-    process.env.SECURENOW_LOGGING_ENABLED = '1';
-    await import('securenow/register');
-  }
+import { registerSecureNow } from 'securenow/nextjs';
+export function register() {
+  registerSecureNow();
 }
 ```
 
-```bash
-# .env.local
-SECURENOW_LOGGING_ENABLED=1
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://localhost:4318
-```
+No `.env.local` needed — credentials come from `.securenow/credentials.json` after `npx securenow login`.
 
 ### Fastify
 
@@ -157,9 +143,10 @@ bootstrap();
 
 **Logs not appearing?**
 
-1. Check `SECURENOW_LOGGING_ENABLED=1` is set
-2. Verify your OTLP / SecureNow endpoint is correct
-3. Enable debug: `OTEL_LOG_LEVEL=debug`
+1. Check `.securenow/credentials.json` exists (run `npx securenow whoami`).
+2. Confirm `SECURENOW_LOGGING_ENABLED` is not set to `0`.
+3. Run `npx securenow doctor` — it probes the full pipeline and reports the failure mode.
+4. Enable verbose output: `OTEL_LOG_LEVEL=debug`.
 
 **Console logs not forwarding?**
 

package/docs/NEXTJS-QUICKSTART.md

@@ -1,67 +1,77 @@
-# Next.js + SecureNow Quick Start
+# Next.js + SecureNow — 30 seconds
 
-## Installation (30 seconds)
+## The whole setup
 
 ```bash
+# 1. Install
 npm install securenow
-```
-
-**🎉 The installer will automatically offer to create the instrumentation file!**
 
-Just answer "Y" when prompted, and it's done!
-
----
+# 2. Pick (or create) your app in the browser — writes .securenow/ locally
+npx securenow login
 
-## Alternative: Manual Setup
+# 3. Scaffold instrumentation.ts and wrap next.config.js
+npx securenow init
 
-If you skipped auto-setup or want to do it manually:
+# 4. Run
+npm run dev
+```
 
-### Option 1: Use CLI (Recommended)
+No `.env.local` edits. No API key copy-paste. The app you picked in step 2 is where your traces land.
 
-```bash
-npx securenow init
-```
+---
 
-### Option 2: Create File Manually
+## What `npx securenow init` generates
 
-Create `instrumentation.ts` at project root:
+**`instrumentation.ts`** (or `.js`, auto-detected):
 
 ```typescript
 import { registerSecureNow } from 'securenow/nextjs';
-export function register() { registerSecureNow(); }
-```
-
-### 2. Create `.env.local`:
-
-```bash
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://your-securenow:4318
+export function register() {
+  registerSecureNow();
+}
 ```
 
-### 3. (Next.js 14 only) Update `next.config.js`:
+It also tells you to wrap `next.config.js`:
 
 ```javascript
-module.exports = {
-  experimental: { instrumentationHook: true }
-}
+const { withSecureNow } = require('securenow/nextjs-webpack-config');
+
+module.exports = withSecureNow({
+  // your existing config
+});
 ```
 
-## Run
+`withSecureNow()` auto-detects Next.js 14 vs 15 vs 16 and sets the right externalization config.
 
-```bash
-npm run dev
-```
+---
 
 ## Verify
 
-Look for:
+Start your app. In the console you should see:
+
 ```
-[securenow] ✅ OpenTelemetry started for Next.js
+[securenow] Next.js integration loading (pid=…)
+[securenow] ✅ OpenTelemetry started for Next.js → https://freetrial.securenow.ai:4318/v1/traces
 ```
 
-Open SecureNow → check for traces from `my-nextjs-app`
+Then:
+
+```bash
+npx securenow test-span      # emit a test span
+npx securenow traces         # see it appear
+```
+
+If `traces` shows your span under the app name you picked, you're done.
 
 ---
 
-**That's it!** See [NEXTJS-GUIDE.md](./NEXTJS-GUIDE.md) for advanced configuration.
+## Overriding for CI / Docker / Vercel
+
+`.securenow/credentials.json` is for local dev. For anywhere you can't run `npx securenow login`, set env vars — they always win:
+
+```bash
+SECURENOW_APPID=<app-key-uuid>              # from: npx securenow apps
+SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+```
 
+See [NEXTJS-GUIDE.md](./NEXTJS-GUIDE.md) for Vercel, standalone builds, and edge runtime details.