securenow 7.0.0-anas.2 → 7.1.0

package/README.md

@@ -1,28 +1,25 @@
 # SecureNow
 
-OpenTelemetry instrumentation for Node.js, Next.js, and Nuxt applications - send **traces and logs** to any OTLP-compatible backend (including SecureNow).
+Zero-config OpenTelemetry for Node.js, Next.js, and Nuxt — traces, logs, body capture, and IP firewall in one install. **No env vars. No copy-pasting keys.**
 
 **Official npm package:** [securenow](http://securenow.ai/)
 
 ---
 
-## 🚀 Quick Start
-
-### For Any Node.js App (Express, Fastify, NestJS, Koa, Hapi, etc.)
+## 🚀 30-second setup
 
 ```bash
 # 1. Install
 npm install securenow
 
-# 2. Set env vars
-export SECURENOW_APPID=my-app
-export SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
+# 2. Pick (or create) your app in the browser — writes .securenow/ locally
+npx securenow login
 
-# 3. Add -r securenow/register to your start command
-node -r securenow/register src/app.js
+# 3. Start your app — one flag is all it takes
+node -r securenow/register src/index.js
 ```
 
-That's it. One `-r` flag is all you need — ESM and CJS apps are handled automatically (Node >=20.6 auto-registers the ESM loader hook).
+That's it. No `.env` edits, no API keys to paste, no peer-dep warnings. Your traces arrive in the app you picked during login.
 
 > **package.json** example:
 > ```json
@@ -32,26 +29,51 @@ That's it. One `-r` flag is all you need — ESM and CJS apps are handled automa
 > }
 > ```
 
-You can also use `NODE_OPTIONS` so your existing scripts stay unchanged:
-```bash
-NODE_OPTIONS="-r securenow/register" npm start
+---
+
+## How it works
+
+`npx securenow login` opens a browser, lets you pick (or create) an application, and writes a **project-local** credentials file to `.securenow/credentials.json`:
+
+```json
+{
+  "token": "...",
+  "email": "you@example.com",
+  "app": {
+    "key": "<uuid>",
+    "name": "my-backend",
+    "instance": "https://freetrial.securenow.ai:4318"
+  }
+}
 ```
 
-See the [All Frameworks Quick Start](./docs/ALL-FRAMEWORKS-QUICKSTART.md) for tested setup guides.
+The SDK reads this file at boot and sends traces/logs directly to the right app bucket. The file is auto-added to `.gitignore` so it never lands in git.
 
 ---
 
-### For Next.js Applications
+## Framework integration
+
+### Node.js / Express / Fastify / NestJS / Koa / Hapi
+
+Just add `-r securenow/register` to your start command. No code changes. Every route, DB call, and `console.log` is captured automatically.
 
 ```bash
-# 1. Install
-npm install securenow
+node -r securenow/register src/app.js
+```
+
+Or with `NODE_OPTIONS` if you can't change the script:
+
+```bash
+NODE_OPTIONS="-r securenow/register" npm start
+```
+
+### Next.js
 
-# 2. Auto-scaffold instrumentation files
-npx securenow init --key snk_live_abc123...
+```bash
+npx securenow init
 ```
 
-This creates `instrumentation.ts` and tells you to wrap your `next.config.js`:
+Creates `instrumentation.ts` and shows you how to wrap `next.config.js`:
 
 ```javascript
 // next.config.js
@@ -62,382 +84,282 @@ module.exports = withSecureNow({
 });
 ```
 
-`withSecureNow()` auto-detects Next.js 14 vs 15 and sets the correct externalization config. No manual `serverExternalPackages` list needed.
-
-Configure `.env.local`:
-
-```bash
-SECURENOW_APPID=my-nextjs-app
-SECURENOW_INSTANCE=http://your-otlp-collector:4318
-SECURENOW_API_KEY=snk_live_abc123...
-```
-
-**Done!** See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md) for details.
-
----
+`withSecureNow()` auto-detects Next.js 14 vs 15 vs 16. See [Next.js Complete Guide](./docs/NEXTJS-GUIDE.md).
 
-### For Nuxt 3 Applications
-
-```bash
-# 1. Install
-npm install securenow
-```
-
-Add the module to your `nuxt.config.ts`:
+### Nuxt 3
 
 ```ts
+// nuxt.config.ts
 export default defineNuxtConfig({
   modules: ['securenow/nuxt'],
 });
 ```
 
-Set environment variables in `.env`:
-
-```bash
-SECURENOW_APPID=my-nuxt-app
-SECURENOW_INSTANCE=https://freetrial.securenow.ai:4318
-```
-
-**Done!** All server-side requests are now traced automatically. The firewall also activates automatically when `SECURENOW_API_KEY` is set. See the [Nuxt 3 Complete Guide](./docs/NUXT-GUIDE.md) for details.
+See [Nuxt 3 Guide](./docs/NUXT-GUIDE.md).
 
 ---
 
-### CLI -- Manage Everything from the Terminal
-
-```bash
-# Set up your project (auto-detects framework, creates instrumentation files)
-npx securenow init --key snk_live_abc123...
-
-# Authenticate
-npx securenow login
-
-# Create an app and get the key
-npx securenow apps create my-app
-
-# Set it as default so you don't need --app every time
-npx securenow config set defaultApp <key>
+## What's captured automatically
 
-# View traces, logs
-npx securenow traces
-npx securenow logs
+- ✅ HTTP spans (Express, Fastify, NestJS, Koa, Hapi, Next.js, Nuxt, raw `http`)
+- ✅ Database spans (Postgres, MySQL, MongoDB, Redis)
+- ✅ `console.log/info/warn/error/debug` forwarded as OTLP logs with trace correlation
+- ✅ Request body capture (JSON, GraphQL, form-encoded) with auto-redaction of `password`, `token`, `api_key`, `authorization`, `cookie`, etc.
+- ✅ Multipart upload metadata (field names, file names, sizes, content-types — never file content)
+- ✅ Firewall (500k+ known-bad IPs, refreshed hourly) — activates as soon as you've logged in
 
-# IP intelligence, forensic queries, blocklist
-npx securenow ip 1.2.3.4
-npx securenow forensics "show top attacking IPs in the last hour"
-npx securenow blocklist add 1.2.3.4 --reason "scanner"
-
-# Firewall — automatic IP blocking
-npx securenow firewall status
-npx securenow firewall test-ip 1.2.3.4
-
-# False-positive triage from the terminal (full parity with the dashboard)
-npx securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"
-npx securenow fp mark <notification-id> <ip> --reason "Known partner IP"
-
-# Telemetry from scripts/CI — no SDK boot required
-npx securenow log send "Deploy succeeded" --level info --attrs version=1.2.3
-npx securenow test-span                              # verify collector connectivity
-
-# Diagnostics & utilities
-npx securenow doctor                                 # probe OTLP + API endpoints
-npx securenow env                                    # show resolved config
-npx securenow redact '{"user":"a","password":"s"}'   # preview redaction
-npx securenow cidr match 10.0.0.5 10.0.0.0/8         # exit 0 = hit, 2 = miss
-
-# Full dashboard overview
-npx securenow status
-```
-
-Run `npx securenow help` for all commands. See the [CLI Reference](#cli-reference) below.
-
-> **Full CLI/SDK parity (v6.1.0+).** Every SDK export has a CLI counterpart: `redactSensitiveData` → `securenow redact`, `createMatcher` → `securenow cidr match`, `getLogger().emit()` → `securenow log send`, `SECURENOW_TEST_SPAN` → `securenow test-span`, `node -r securenow/firewall-only` → `securenow run --firewall-only`.
+All of these are **on by default**. Each can be disabled individually with an env var if needed (e.g. `SECURENOW_CAPTURE_BODY=0`).
 
 ---
 
----
+## Overriding via environment variables (CI, Docker, prod)
 
-## 📦 Installation
+`.securenow/credentials.json` is the zero-config path for local dev. For CI, containers, or prod servers where you can't run `npx securenow login`, set env vars — they always take precedence:
 
 ```bash
-npm install securenow
-# or
-yarn add securenow
-# or
-pnpm add securenow
+SECURENOW_APPID=<app-key-uuid>              # routing key (from dashboard or `npx securenow apps`)
+SECURENOW_INSTANCE=https://your-collector   # defaults to freetrial
+SECURENOW_API_KEY=<same uuid>               # enables the firewall
 ```
 
----
+Resolution order (first non-empty wins):
+
+1. Environment variable
+2. Project-local `.securenow/credentials.json`
+3. Global `~/.securenow/credentials.json`
+4. `package.json#name` (label only — won't route telemetry)
 
-## ⚙️ Configuration
+---
 
-### Environment Variables
+## CLI
 
 ```bash
-# Required: Your application identifier
-SECURENOW_APPID=my-app-name
+# Setup
+npx securenow login                 # browser auth + app picker (saves to ./.securenow/)
+npx securenow login --global        # save to ~/.securenow/ instead
+npx securenow login --token <TOKEN> # headless (CI)
+npx securenow init                  # scaffold Next.js instrumentation files
+
+# Apps
+npx securenow apps                  # list all apps
+npx securenow apps create my-app    # create and get the key
+npx securenow apps default <key>    # change which app this project uses
+
+# Observability
+npx securenow traces                # list recent traces
+npx securenow logs                  # tail logs
+npx securenow status                # dashboard summary
+npx securenow doctor                # diagnose config + connectivity
+
+# Security
+npx securenow firewall status
+npx securenow blocklist add 1.2.3.4 --reason "scanner"
+npx securenow fp ai-fill --description "Stripe webhook POST /api/stripe/webhook"
 
-# Optional: Your OTLP collector endpoint
-# Default: https://freetrial.securenow.ai:4318
-SECURENOW_INSTANCE=http://your-otlp-collector:4318
+# Telemetry from shell (no SDK boot)
+npx securenow log send "Deploy succeeded" --level info
+npx securenow test-span             # verify collector connectivity
+```
 
-# Optional: Enable Logging
-SECURENOW_LOGGING_ENABLED=1                 # Enable automatic log collection
+Full reference: run `npx securenow help` or see [CLI Reference](#cli-reference) below.
 
-# Optional: Additional configuration
-SECURENOW_NO_UUID=1                         # Don't append UUID to service name
-OTEL_LOG_LEVEL=info                         # debug|info|warn|error
-SECURENOW_DISABLE_INSTRUMENTATIONS=fs,dns   # Disable specific instrumentations
-OTEL_EXPORTER_OTLP_HEADERS="x-api-key=..."  # Authentication headers
+---
 
-# Optional: Request body capture (for debugging)
-SECURENOW_CAPTURE_BODY=1                    # Capture request bodies in traces
-SECURENOW_MAX_BODY_SIZE=10240               # Max body size in bytes
-SECURENOW_SENSITIVE_FIELDS="field1,field2"  # Additional fields to redact
+## Environment variables (optional)
 
-# Optional: Multipart body capture (file upload metadata)
-SECURENOW_CAPTURE_MULTIPART=1               # Capture multipart field names, values & file metadata
-```
+Only set these if you want to override the zero-config defaults.
 
-### Legacy Environment Variables (still supported)
+| Variable | Default | Purpose |
+|---|---|---|
+| `SECURENOW_APPID` | from credentials file | App routing key (UUID) — sent as OTel `service.name` |
+| `SECURENOW_INSTANCE` | `https://freetrial.securenow.ai:4318` | OTLP collector endpoint |
+| `SECURENOW_API_KEY` | from credentials file | Enables firewall + collector routing |
+| `SECURENOW_LOGGING_ENABLED` | `1` (on) | Forward `console.*` as OTLP logs. Set to `0` to disable. |
+| `SECURENOW_CAPTURE_BODY` | `1` (on) | Capture JSON / form request bodies. Set to `0` for Fastify/Hapi/Hono. |
+| `SECURENOW_CAPTURE_MULTIPART` | `1` (on) | Capture multipart metadata (not content). |
+| `SECURENOW_MAX_BODY_SIZE` | `10240` | Max bytes captured per body. |
+| `SECURENOW_SENSITIVE_FIELDS` | `password,token,authorization,...` | Extra fields to redact (comma-separated). |
+| `SECURENOW_DISABLE_INSTRUMENTATIONS` | — | Comma-separated OTel instrumentations to disable. |
+| `SECURENOW_NO_UUID` | `0` | Don't append a UUID to `service.instance.id`. |
+| `SECURENOW_STRICT` | `0` | Exit with code 1 if `SECURENOW_APPID` is missing in a PM2 cluster. |
+| `OTEL_EXPORTER_OTLP_HEADERS` | — | Raw OTLP headers (e.g. `x-api-key=...`). |
+| `OTEL_LOG_LEVEL` | — | `debug`/`info`/`warn`/`error`. |
 
-```bash
-export securenow=<API-KEY>
-export securenow_instance='http://<dedicated_instance>:4318'
-```
+Full list: [docs/ENVIRONMENT-VARIABLES.md](./docs/ENVIRONMENT-VARIABLES.md).
 
 ---
 
-## 🎯 Supported Frameworks & Libraries
+## Supported frameworks
 
-SecureNow automatically instruments:
-
-### Web Frameworks
-- ✅ Next.js (App Router & Pages Router)
-- ✅ Nuxt 3 (Nitro server)
-- ✅ Express.js
-- ✅ Fastify
-- ✅ NestJS
-- ✅ Koa
-- ✅ Hapi
+### Web
+Next.js (App & Pages Router) · Nuxt 3 · Express · Fastify · NestJS · Koa · Hapi
 
 ### Databases
-- ✅ PostgreSQL
-- ✅ MySQL / MySQL2
-- ✅ MongoDB
-- ✅ Redis
-
-### Logging
-- ✅ Automatic console logging (console.log, info, warn, error)
-- ✅ Structured logging with OpenTelemetry
-- ✅ Automatic trace-log correlation
-- ✅ Works with all frameworks
+PostgreSQL · MySQL / MySQL2 · MongoDB · Redis
 
 ### Other
-- ✅ HTTP/HTTPS requests
-- ✅ GraphQL
-- ✅ gRPC
-- ✅ And many more via OpenTelemetry auto-instrumentation
+HTTP/HTTPS · GraphQL · gRPC · and many more via [@opentelemetry/auto-instrumentations-node](https://www.npmjs.com/package/@opentelemetry/auto-instrumentations-node).
+
+> MongoDB instrumentation is opt-in (`SECURENOW_ENABLE_MONGODB_INSTRUMENTATION=1`) because older versions corrupted cursors on `mongodb@6.6+`. Safe again since SDK v6.0.2.
 
 ---
 
-## 📚 Documentation
+## Documentation
 
 ### Quick Starts
-- **[Next.js Quick Start](./docs/NEXTJS-QUICKSTART.md)** - Get started in 30 seconds
-- **[Nuxt 3 Guide](./docs/NUXT-GUIDE.md)** - One-line Nuxt module setup
-- **[Logging Quick Start](./docs/LOGGING-QUICKSTART.md)** - Add logging in 2 minutes
+- [Next.js Quick Start](./docs/NEXTJS-QUICKSTART.md)
+- [Nuxt 3 Guide](./docs/NUXT-GUIDE.md)
+- [All Frameworks](./docs/ALL-FRAMEWORKS-QUICKSTART.md)
+- [Logging Quick Start](./docs/LOGGING-QUICKSTART.md)
 
 ### Complete Guides
-- **[Firewall Guide](./docs/FIREWALL-GUIDE.md)** - Automatic multi-layer IP blocking
-- **[API Keys Guide](./docs/API-KEYS-GUIDE.md)** - API key management and scopes
-- **[Next.js Complete Guide](./docs/NEXTJS-GUIDE.md)** - Full Next.js integration guide
-- **[Nuxt 3 Complete Guide](./docs/NUXT-GUIDE.md)** - Full Nuxt 3 integration guide
-- **[Logging Complete Guide](./docs/LOGGING-GUIDE.md)** - Full logging setup for all frameworks
-- **[📚 Complete Documentation](./docs/INDEX.md)** - All guides and references
+- [Firewall](./docs/FIREWALL-GUIDE.md)
+- [API Keys](./docs/API-KEYS-GUIDE.md)
+- [Next.js Complete](./docs/NEXTJS-GUIDE.md)
+- [Nuxt 3 Complete](./docs/NUXT-GUIDE.md)
+- [Logging Complete](./docs/LOGGING-GUIDE.md)
+- [📚 All Docs](./docs/INDEX.md)
 
 ### Examples
-- **[Code Examples](./examples/)** - Ready-to-use examples for different setups
+- [Code Examples](./examples/)
 
 ---
 
 ## CLI Reference
 
-After installing the package, the `securenow` CLI is available via `npx securenow` or globally after `npm install -g securenow`.
+After install, the `securenow` CLI is available via `npx securenow` or globally with `npm install -g securenow`.
 
 ### Run (convenience wrapper)
 
 | Command | Description |
-|---------|-------------|
-| `securenow run <script>` | Run a Node.js app with `-r securenow/register` injected |
+|---|---|
+| `securenow run <script>` | Run a Node app with `-r securenow/register` injected |
 | `securenow run --watch <script>` | Same, with Node.js watch mode |
-
-Most users won't need this — just add `-r securenow/register` to your existing start script.
+| `securenow run --firewall-only <script>` | Preload the firewall only, skip OTel |
 
 ### Authentication
 
 | Command | Description |
-|---------|-------------|
-| `securenow login` | Log in via browser (opens OAuth flow) |
-| `securenow login --token <TOKEN>` | Log in with a token (for CI/headless) |
-| `securenow login --local` | Log in and save credentials to the current project only |
-| `securenow logout` | Clear stored credentials |
-| `securenow logout --local` | Clear project-local credentials only |
-| `securenow whoami` | Show current session info (including auth source) |
+|---|---|
+| `securenow login` | Browser auth + pick app (writes ./.securenow/ by default) |
+| `securenow login --global` | Save to ~/.securenow/ instead |
+| `securenow login --token <TOKEN>` | Headless (CI/servers) |
+| `securenow logout` | Clear project-local credentials |
+| `securenow logout --global` | Clear ~/.securenow/ instead |
+| `securenow whoami` | Show current session (email, app, expiry) |
 
 ### Applications
 
 | Command | Description |
-|---------|-------------|
-| `securenow apps` | List all applications |
-| `securenow apps create <name>` | Create app and get the app key |
-| `securenow apps info <id>` | Show application details |
-| `securenow apps delete <id>` | Delete an application |
-| `securenow apps default <key>` | Set default app for all commands |
+|---|---|
+| `securenow apps` | List all apps for your account |
+| `securenow apps create <name>` | Create an app |
+| `securenow apps info <id>` | Show app details |
+| `securenow apps delete <id>` | Delete an app |
+| `securenow apps default <key>` | Switch which app this project uses (updates `.securenow/`) |
 
 ### Observability
 
 | Command | Description |
-|---------|-------------|
-| `securenow traces --app <key>` | List recent traces |
-| `securenow traces show <traceId>` | Show trace spans |
-| `securenow traces analyze <traceId>` | AI security analysis of a trace |
-| `securenow logs --app <key>` | View logs (with `--minutes`, `--level`) |
-| `securenow logs trace <traceId>` | View logs for a specific trace |
-| `securenow analytics` | Response code analytics overview |
-| `securenow status` | Full dashboard summary |
+|---|---|
+| `securenow traces` | Recent traces |
+| `securenow traces show <traceId>` | Trace spans |
+| `securenow traces analyze <traceId>` | AI security analysis |
+| `securenow logs` | View logs (`--minutes`, `--level`) |
+| `securenow logs trace <traceId>` | Logs for a trace |
+| `securenow analytics` | Response code analytics |
+| `securenow status` | Dashboard summary |
 
 ### Detect & Respond
 
 | Command | Description |
-|---------|-------------|
+|---|---|
 | `securenow notifications` | List notifications |
-| `securenow notifications unread` | Show unread count |
-| `securenow notifications read <id>` | Mark notification as read |
-| `securenow notifications read-all` | Mark all as read |
-| `securenow alerts rules` | List alert rules (status, applications, schedule) |
-| `securenow alerts rules show <id>` | Show one rule (includes all-apps vs explicit apps) |
-| `securenow alerts rules update <id> --applications-all` | Set rule to all current & future apps |
-| `securenow alerts rules update <id> --apps k1,k2` | Scope rule to specific app keys |
-| `securenow alerts channels` | List alert channels |
-| `securenow alerts history` | View alert history |
+| `securenow notifications unread` | Unread count |
+| `securenow alerts rules` | List alert rules |
+| `securenow alerts history` | Alert history |
 
 ### Investigate
 
 | Command | Description |
-|---------|-------------|
-| `securenow ip <address>` | IP intelligence lookup (geo, abuse score, verdict) |
-| `securenow ip traces <address>` | Show traces originating from an IP |
-| `securenow forensics "<query>"` | Natural language forensic query (NL to SQL) |
-| `securenow forensics library` | View saved query library |
-| `securenow api-map` | View discovered API endpoints |
-| `securenow api-map stats` | API map statistics |
+|---|---|
+| `securenow ip <address>` | IP intel (geo, abuse, verdict) |
+| `securenow ip traces <address>` | Traces from an IP |
+| `securenow forensics "<query>"` | Natural language forensic query |
+| `securenow api-map` | Discovered API endpoints |
 
 ### Firewall
 
 | Command | Description |
-|---------|-------------|
-| `securenow firewall status` | Show firewall status, active layers, and API key info |
-| `securenow firewall test-ip <ip>` | Check if an IP would be blocked by the current blocklist |
-| `securenow run --firewall-only <script>` | Run a Node.js app with the firewall preloaded but **no** OTel tracing overhead |
+|---|---|
+| `securenow firewall status` | Firewall layers + key info |
+| `securenow firewall test-ip <ip>` | Would this IP be blocked? |
 
 ### Remediation
 
 | Command | Description |
-|---------|-------------|
+|---|---|
 | `securenow blocklist` | List blocked IPs |
-| `securenow blocklist add <ip>` | Block an IP (`--reason <reason>`) |
-| `securenow blocklist remove <id>` | Remove from blocklist |
-| `securenow blocklist stats` | Blocklist statistics |
-| `securenow allowlist` | List allowed IPs (restrict-mode) |
-| `securenow allowlist add <ip>` | Allow an IP (`--label`, `--reason`) |
-| `securenow allowlist remove <id>` | Remove from allowlist |
-| `securenow trusted` | List trusted IPs |
-| `securenow trusted add <ip>` | Add trusted IP (`--label <label>`) |
-| `securenow trusted remove <id>` | Remove trusted IP |
-
-### False-Positive Management
+| `securenow blocklist add <ip> [--reason ...]` | Block an IP |
+| `securenow allowlist add <ip>` | Allow an IP (restrict-mode) |
+| `securenow trusted add <ip>` | Mark an IP as trusted |
 
-Full false-positive triage without leaving the terminal — mirrors the web dashboard one-for-one.
+### False positives
 
 | Command | Description |
-|---------|-------------|
-| `securenow fp` / `securenow fp list` | List all exclusion rules |
-| `securenow fp show <id>` | Show rule details (conditions, scope, match mode) |
-| `securenow fp create --conditions '[...]'` | Create a raw exclusion rule |
-| `securenow fp create --path /api/events --method POST --path-safe standard --ua-safe standard --reason "..."` | Create with safe-value presets |
-| `securenow fp edit <id> [--active true\|false] [--conditions '[...]']` | Edit an existing rule |
-| `securenow fp delete <id> [--yes]` | Delete a rule |
-| `securenow fp test-body '<json>' --conditions '[...]'` | Test conditions against a request body |
-| `securenow fp dry-run --conditions '[...]'` | Dry-run against the last 3 days of live traces |
-| `securenow fp ai-fill --description "Stripe webhook POST to /api/stripe/webhook"` | AI-generate exclusion conditions |
-| `securenow fp mark <notification-id> <ip>` | Mark an IP as false positive on a specific notification |
-
-### Telemetry
-
-Emit OTLP logs and spans from the shell — for cron jobs, CI pipelines, and scripts. No SDK boot required.
+|---|---|
+| `securenow fp` | List exclusion rules |
+| `securenow fp ai-fill --description "..."` | AI-generate exclusion conditions |
+| `securenow fp mark <notif-id> <ip>` | Mark an alert as a false positive |
+| `securenow fp dry-run --conditions '[...]'` | Test against last 3 days of traces |
 
-| Command | Description |
-|---------|-------------|
-| `securenow log send "<message>" [--level info\|warn\|error] [--attrs k=v,k=v]` | Send a single log record via OTLP/HTTP |
-| `securenow test-span [<name>]` | Emit a test span to verify collector connectivity |
-
-### Utilities
-
-SDK helpers surfaced as CLI commands — debug redaction, test CIDR matching, inspect config without writing Node.
+### Telemetry from the shell
 
 | Command | Description |
-|---------|-------------|
-| `securenow redact '<json>' [--fields f1,f2]` | Redact sensitive fields (also accepts `@file.json`) |
-| `securenow cidr match <ip> <cidr1,cidr2>` | Check if an IP matches a CIDR list (exit `0` hit / `2` miss) |
-| `securenow cidr parse <cidr>` | Parse a CIDR — print network, broadcast, mask, size |
-| `securenow env [--json]` | Show resolved config (service name, endpoints, env vars) |
-| `securenow doctor [--json]` | End-to-end diagnostic: probe OTLP + API, check config |
+|---|---|
+| `securenow log send "<msg>" [--level info\|warn\|error]` | Emit a log record via OTLP |
+| `securenow test-span` | Send a test span |
 
-### Settings
+### Diagnostics & utilities
 
 | Command | Description |
-|---------|-------------|
-| `securenow instances` | List ClickHouse instances |
-| `securenow instances test <id>` | Test instance connection |
-| `securenow config get` | Show all config values |
-| `securenow config set <key> <value>` | Set a config value |
-| `securenow config path` | Show config file locations |
-| `securenow init [--key <KEY>]` | Auto-scaffold instrumentation for your framework |
-| `securenow version` | Show CLI version |
-
-### Global Flags
+|---|---|
+| `securenow doctor` | Probe OTLP + API, check config |
+| `securenow env` | Show resolved config |
+| `securenow redact '<json>'` | Preview redaction |
+| `securenow cidr match <ip> <cidr>` | Test CIDR match (exit 0/2) |
 
-| Flag | Description |
-|------|-------------|
-| `--json` | Output as JSON (works on every command) |
-| `--help` | Show help for any command |
-| `--app <key>` | Specify app key (or set default with `config set defaultApp`) |
-| `--local` | Save/clear credentials per-project (login/logout only) |
+### Global flags
 
-### Configuration
+| Flag | Effect |
+|---|---|
+| `--json` | Machine-readable output |
+| `--help` | Help for any command |
+| `--app <key>` | Override which app |
+| `--global` | Global credentials scope (login/logout) |
 
-Credentials and settings are stored in `~/.securenow/` (global) or `.securenow/` (per-project):
+### Where things live
 
 | File | Purpose |
-|------|---------|
+|---|---|
+| `./.securenow/credentials.json` | Project-local token + app (default) |
+| `~/.securenow/credentials.json` | Global (with `login --global`) |
 | `~/.securenow/config.json` | API URL, default app, preferences |
-| `~/.securenow/credentials.json` | Auth token — global (restricted permissions) |
-| `.securenow/credentials.json` | Auth token — project-local (use `login --local`) |
 
-**Credential resolution order:** `SECURENOW_TOKEN` env var → project `.securenow/credentials.json` → global `~/.securenow/credentials.json`.
+Resolution order: `SECURENOW_TOKEN` env → project `.securenow/` → global `~/.securenow/`.
 
-Override the API URL with `securenow config set apiUrl <url>` or the `SECURENOW_API_URL` environment variable.
+Override the API with `securenow config set apiUrl <url>` or `SECURENOW_API_URL`.
 
 ---
 
 ## Support
 
 - **Website:** [securenow.ai](http://securenow.ai/)
-- **Issues:** Report bugs and request features
-- **Documentation:** Full documentation and guides
+- **Docs:** see `docs/` folder
+- **Issues:** report bugs and requests on GitHub
 
 ---
 
 ## License
 
-ISC
+ISC