diff --git a/.claude/agents/docs-reviewer.md b/.claude/agents/docs-reviewer.md
new file mode 100644
index 0000000..152d458
--- /dev/null
+++ b/.claude/agents/docs-reviewer.md
@@ -0,0 +1,168 @@
+---
+name: docs-reviewer
+description: Reviews documentation files for terminology consistency, structural quality, and AI writing tropes. Read-only — reports findings without modifying files.
+---
+
+# Docs Reviewer Agent
+
+You review documentation files and produce a structured report of findings. You do NOT modify any files.
+
+## Determining Target Files
+
+Based on the prompt you receive, determine which files to review:
+
+- If given specific file paths, use those
+- If given a directory, glob for all `.md` files in it
+- If asked to review "recent changes" or "last commit", use `git diff --name-only HEAD~1` (or the appropriate range) filtered to `.md` files
+- If the scope is unclear, ask for clarification via your report
+
+Read every target file fully before starting your review passes.
+
+## Review Process
+
+Perform three passes sequentially. Track findings per file with line numbers where possible.
+
+---
+
+### Pass 1 — Consistency & Terminology
+
+Check across all reviewed files:
+
+1. **Stale terms**: Look for vendor-specific or outdated terminology that should have been generalized. Common patterns:
+   - Product names that should be generic (e.g., "Keycloak" should be "authentication server")
+   - Old feature names that were renamed
+   - Inconsistent capitalization of product/feature names
+
+2. **Cross-file consistency**: When the same concept appears in multiple files, verify it uses identical wording. For example, if one file says "account identifier" and another says "account slug" for the same concept, flag the inconsistency.
+
+3. **CLI flag accuracy**: If a source code repo is accessible (check sibling directories like `../scout-cli`), compare flag descriptions in docs against the actual `#[arg(...)]` annotations or `--help` text in the source.
+
+---
+
+### Pass 2 — Structural Quality
+
+Check each file for:
+
+1. **Frontmatter completeness**: These fields must be present:
+   - `title`
+   - `sidebar_label`
+   - `description`
+   - `keywords` (as a list)
+
+2. **H1 matches title**: The first `# Heading` should match or closely reflect the frontmatter `title`.
+
+3. **Internal links valid**: For every relative markdown link (e.g., `[text](./other.md)`), verify the target file exists using Glob or Read.
+
+4. **See Also section**: Pages that reference other commands or concepts inline should have a "See Also" section at the bottom with links.
+
+5. **Heading hierarchy**: Headings should not skip levels. An H2 (`##`) should not be followed directly by an H4 (`####`) without an H3 in between.
+
+6. **Code blocks tagged**: Every fenced code block (```) should have a language identifier (e.g.,```bash, ```json).
+
+---
+
+### Pass 3 — Writing Quality (AI Tropes)
+
+Scan for AI writing patterns that make text feel artificial. A single occurrence of a pattern may be acceptable. Flag it as a problem when: a trope is used repeatedly in one file, or multiple different tropes cluster together in a section.
+
+#### Word Choice
+
+- **Magic adverbs**: Overuse of "quietly", "deeply", "fundamentally", "remarkably", "arguably" to manufacture subtle importance.
+- **"Delve" and friends**: "delve", "certainly", "utilize", "leverage" (as verb), "robust", "streamline", "harness".
+- **Ornate nouns**: "tapestry", "landscape", "paradigm", "synergy", "ecosystem", "framework" used as generic descriptors where simpler words work.
+- **"Serves as" dodge**: Pompous alternatives to "is" or "are" — "serves as", "stands as", "marks", "represents".
+
+#### Sentence Structure
+
+- **Negative parallelism**: Repeated "It's not X, it's Y" pattern. Once per piece can work; multiple is a problem.
+- **Dramatic countdown**: "Not X. Not Y. Just Z." — negating things before revealing the point.
+- **Rhetorical self-answer**: "The X? A Y." — posing a question and answering it immediately ("The result? Devastating.").
+- **Anaphora abuse**: Same sentence opening repeated multiple times in succession ("They could... They could... They could...").
+- **Tricolon abuse**: Overuse of rule-of-three patterns. One is elegant; three back-to-back is a pattern failure.
+- **Filler transitions**: "It's worth noting", "It bears mentioning", "Importantly", "Interestingly", "Notably".
+- **Superficial analyses**: Tacking "-ing" phrases onto sentences for shallow analysis ("highlighting its importance", "reflecting broader trends").
+- **False ranges**: "From X to Y" where X and Y aren't on a real scale ("From innovation to cultural transformation").
+- **Gerund fragment litany**: A claim followed by a stream of verbless fragments ("Fixing small bugs. Writing straightforward features. Implementing well-defined tickets.").
+
+#### Paragraph Structure
+
+- **Short punchy fragments**: Very short sentences as standalone paragraphs for manufactured emphasis ("He published this. Openly. In a book.").
+- **Listicle in a trench coat**: Numbered lists disguised as prose ("The first wall is... The second wall is... The third wall is...").
+
+#### Tone
+
+- **False suspense**: "Here's the kicker", "Here's the thing", "Here's where it gets interesting", "Here's what most people miss".
+- **Patronizing analogies**: Defaulting to "Think of it as..." instead of trusting the reader to understand directly.
+- **Futuristic invitations**: Opening with "Imagine a world where..." to sell an argument.
+- **False vulnerability**: Simulating self-awareness performatively ("And yes, I'm openly in love with...").
+- **Obviousness assertions**: "The truth is simple", "The reality is simpler", "History is clear" — asserting instead of proving.
+- **Stakes inflation**: Inflating every argument to world-historical significance ("fundamentally reshape how we think about everything").
+- **Pedagogical voice**: "Let's break this down", "Let's unpack this", "Let's explore", "Let's dive in".
+- **Vague attributions**: Citing unnamed "experts", "observers", or "industry reports". No named source = no source.
+- **Invented concept labels**: Coining compound labels ("supervision paradox", "acceleration trap") and using them as if established.
+
+#### Formatting
+
+- **Em-dash overuse**: More than 2-3 em dashes per piece is too many. Prefer commas.
+- **Bold-first bullets**: Starting every bullet with a bolded keyword. Almost nobody formats lists this way naturally.
+- **Unicode decoration**: Unicode arrows, smart quotes, and special characters that can't be easily typed on a standard keyboard.
+
+#### Composition
+
+- **Fractal summaries**: Summarizing at every level. Drop "In this section, we'll explore..." and "As we've seen..."
+- **Dead metaphor**: Latching onto one metaphor and repeating it 5-10 times across the piece.
+- **Historical analogy stacking**: Rapid-fire listing historical companies or revolutions for false authority ("Apple didn't... Facebook didn't... Stripe didn't...").
+- **One-point dilution**: Restating a single argument 10 ways across thousands of words.
+- **Content duplication**: Repeating sections or paragraphs.
+- **Signposted conclusion**: Announcing "In conclusion" or "To sum up".
+- **Dismiss with optimism**: "Despite its challenges..." — acknowledging problems only to immediately dismiss them.
+
+---
+
+## Output Format
+
+Structure your report exactly like this:
+
+```
+## Docs Review Report
+
+### Files Reviewed
+- path/to/file1.md
+- path/to/file2.md
+
+### Pass 1 — Consistency & Terminology
+
+#### path/to/file1.md
+- [line 34] "account slug" — inconsistent with "account identifier" used in file2.md line 12
+
+(or "No issues found" if clean)
+
+### Pass 2 — Structural Quality
+
+#### path/to/file1.md
+- Missing `keywords` in frontmatter
+- [line 45] Code block without language tag
+
+(or "No issues found" if clean)
+
+### Pass 3 — Writing Quality
+
+#### path/to/file1.md
+- [line 12] **Filler transition**: "It's worth noting that..."
+- [line 28] **Magic adverb**: "deeply integrated" — consider "tightly integrated" or just "integrated"
+- Pattern: **Pedagogical voice** appears 3 times (lines 5, 22, 41)
+
+(or "No issues found" if clean)
+
+### Summary
+- N issues, M suggestions across K files
+- Issues = must fix; Suggestions = consider fixing
+```
+
+## Guidelines
+
+- Be specific: quote the problematic text, give the line number, name the issue
+- Distinguish severity: inconsistencies and broken links are issues (must fix); a single filler word is a suggestion (consider fixing)
+- Don't be pedantic: one "notably" in an otherwise clean file is not worth flagging
+- Focus on patterns: three tricolons in one file is more important than one tricolon
+- Keep the report concise: if a file is clean, say so and move on
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
index 2c18169..3051a87 100644
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -25,7 +25,9 @@ jobs:
 
       - uses: DavidAnson/markdownlint-cli2-action@v19
         with:
-          globs: "**/*.md"
+          globs: |
+            **/*.md
+            !.claude/**
         continue-on-error: false
 
   build:
diff --git a/.markdownlintignore b/.markdownlintignore
index 733679c..bd46600 100644
--- a/.markdownlintignore
+++ b/.markdownlintignore
@@ -1,3 +1,5 @@
 node_modules
 build
 plans/
+docs/superpowers/
+.claude/
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..96dc3d7
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,62 @@
+# Project: base14-docs
+
+## Commands
+
+```bash
+npm run start        # Dev server
+npm run build        # Production build
+npm run check        # Typecheck + markdownlint + build (full CI check)
+npm run markdownlint # Lint markdown with auto-fix
+```
+
+## Project Structure
+
+- `docs/` — Documentation pages (Docusaurus autogenerated sidebars)
+- `blog/` — Blog posts (date-prefixed directories)
+- `src/components/` — React components (including Feedback widget)
+- `src/css/` — Custom styles
+- `static/` — Static assets (images, robots.txt)
+- `build/` — Generated output (gitignored, do NOT edit)
+
+## Doc Sections
+
+- `docs/instrument/` — Instrumentation guides (apps, collectors, infra components)
+- `docs/observe/` — Observability features (LogX, TraceX)
+- `docs/operate/` — Operational guides (dashboards, alerts, user mgmt)
+- `docs/guides/` — How-to guides (AI observability, CI/CD, Flutter, etc.)
+- `docs/scout-cli/` — Scout CLI reference docs
+- `docs/scout-mcp/` — Scout MCP server docs
+
+## Markdown Frontmatter
+
+Every doc page must have: title, sidebar_label, description, keywords.
+Sidebar ordering uses sidebar_position in frontmatter.
+Sidebars are autogenerated from directory structure (see sidebars.ts).
+
+## Markdownlint
+
+Config: `.markdownlint.json`
+Disabled rules: MD024 (duplicate headings), MD025 (single H1),
+MD033 (inline HTML), MD060.
+Line length enforced except in code blocks and tables.
+
+## Gotchas
+
+- `build/` contains generated copies of all docs — never edit files there
+- `onBrokenLinks` is set to `"throw"` in docusaurus.config.ts
+  — broken internal links will fail the build
+- `docs/superpowers/` is gitignored (Claude-generated specs)
+- Node >= 24.0 required (see engines in package.json)
+- postinstall runs patch-package — check `patches/` if deps behave oddly
+
+## Workflow: After editing docs
+
+Run the docs-reviewer agent to check consistency, structure, and writing quality:
+
+```text
+@docs-reviewer Review the files I just changed
+```
+
+This checks: terminology consistency across files, frontmatter
+completeness, internal link validity, heading hierarchy, and
+AI writing tropes.
diff --git a/docs/getting-started.md b/docs/getting-started.md
index eb99ed6..a2474b8 100644
--- a/docs/getting-started.md
+++ b/docs/getting-started.md
@@ -46,6 +46,13 @@ for a quick win and a clear next step.
 - [Kubernetes](/instrument/collector-setup/kubernetes-helm-setup)
 - [Docker](/instrument/collector-setup/docker-compose-example)
 
+## I want to use the CLI
+
+- [Install Scout CLI](/scout-cli/installation)
+- [Generate an OTel Collector config](/scout-cli/open-source/config-init)
+- [Validate a collector config](/scout-cli/open-source/config-validate)
+- [Query logs, traces, and metrics](/scout-cli/platform/logs)
+
 ## I want CI/CD observability
 
 - [GitHub Actions Observability](/guides/cicd-observability/github-actions-observability)
diff --git a/docs/scout-cli/_category_.json b/docs/scout-cli/_category_.json
new file mode 100644
index 0000000..bb7f808
--- /dev/null
+++ b/docs/scout-cli/_category_.json
@@ -0,0 +1,9 @@
+{
+  "label": "Scout CLI",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "scout-cli/index"
+  }
+}
diff --git a/docs/scout-cli/index.md b/docs/scout-cli/index.md
new file mode 100644
index 0000000..addcfb2
--- /dev/null
+++ b/docs/scout-cli/index.md
@@ -0,0 +1,90 @@
+---
+title: Scout CLI
+sidebar_label: Overview
+sidebar_position: 1
+description:
+  Scout CLI is a command-line tool for querying observability data from the Scout
+  platform and managing OpenTelemetry Collector configurations offline.
+keywords:
+  - scout cli
+  - observability cli
+  - opentelemetry cli
+  - otel collector config
+  - scout command line
+  - base14 scout cli
+---
+
+# Scout CLI
+
+Scout CLI brings observability workflows to your terminal. Authenticate with the
+Scout platform to query logs, metrics, traces, alerts, and service topology — or
+use the open-source config commands to validate, generate, and test
+OpenTelemetry Collector configurations without a backend.
+
+## Platform Commands
+
+These commands require authentication with a
+[Scout](https://base14.io) backend.
+
+| Command | Description |
+|---------|-------------|
+| [login](./platform/login.md) | Authenticate with the Scout platform |
+| [logout](./platform/logout.md) | Remove stored credentials |
+| [status](./platform/status.md) | Check authentication status |
+| [context](./platform/context.md) | Manage multiple account contexts |
+| [alerts](./platform/alerts.md) | Query alert history |
+| [logs](./platform/logs.md) | Query service logs |
+| [metrics](./platform/metrics.md) | Query service metrics |
+| [traces](./platform/traces.md) | Query distributed traces |
+| [service-map](./platform/service-map.md) | Visualize service topology |
+
+## Open Source Commands
+
+These commands work entirely offline with no Scout account required.
+
+| Command | Description |
+|---------|-------------|
+| [config validate](./open-source/config-validate.md) | Validate an OTel Collector YAML config |
+| [config init](./open-source/config-init.md) | Generate a production-ready OTel Collector config |
+| [config test](./open-source/config-test.md) | Live-test an OTel Collector config |
+
+:::tip No account needed
+The `scout config` commands are fully open source. You can validate, generate,
+and test OpenTelemetry Collector configurations without signing up for Scout.
+:::
+
+## Quick Start
+
+**Platform users** — authenticate and start querying:
+
+```bash
+scout login --account my-org
+scout logs payment-service --since 10m
+scout traces payment-service --status Error
+```
+
+**Open-source users** — generate and validate a collector config:
+
+```bash
+scout config init
+scout config validate --file otel-collector-config.yaml
+scout config test --file otel-collector-config.yaml
+```
+
+## Global Flags
+
+Every command accepts these flags:
+
+| Flag | Description |
+|------|-------------|
+| `-v, --verbose` | Enable verbose debug logging to stderr |
+| `-a, --account <NAME>` | Override the active account context |
+
+See [Global Flags](./reference/global-flags.md) for details.
+
+## See Also
+
+- [Installation](./installation.md) — install Scout CLI
+- [Global Flags](./reference/global-flags.md) — flags available on every command
+- [Environment Variables](./reference/environment-variables.md)
+  — configure Scout via env vars
diff --git a/docs/scout-cli/installation.md b/docs/scout-cli/installation.md
new file mode 100644
index 0000000..e54c9c9
--- /dev/null
+++ b/docs/scout-cli/installation.md
@@ -0,0 +1,40 @@
+---
+title: Installation
+sidebar_label: Installation
+sidebar_position: 2
+description:
+  Install the Scout CLI on macOS or Linux via Homebrew.
+keywords:
+  - scout cli install
+  - scout cli setup
+  - scout cli download
+  - homebrew scout
+  - opentelemetry cli install
+---
+
+# Installation
+
+## Prerequisites
+
+- **macOS**, **Linux**, or **Windows**
+- A terminal with shell access
+
+## Install with Homebrew (macOS / Linux)
+
+```bash
+brew tap base14/tap
+brew install scout
+```
+
+## Verify
+
+```bash
+scout --version
+```
+
+## Next Steps
+
+- **Platform users** — [Authenticate with Scout](./platform/login.md) to start
+  querying telemetry data
+- **Open-source users** — [Generate an OTel Collector config](./open-source/config-init.md)
+  to get started without a backend
diff --git a/docs/scout-cli/open-source/_category_.json b/docs/scout-cli/open-source/_category_.json
new file mode 100644
index 0000000..66f87cd
--- /dev/null
+++ b/docs/scout-cli/open-source/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Open Source Commands",
+  "position": 4,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Open Source Commands",
+    "description": "Offline commands for validating, generating, and testing OpenTelemetry Collector configurations. No Scout backend required."
+  }
+}
diff --git a/docs/scout-cli/open-source/config-init.md b/docs/scout-cli/open-source/config-init.md
new file mode 100644
index 0000000..400e23a
--- /dev/null
+++ b/docs/scout-cli/open-source/config-init.md
@@ -0,0 +1,106 @@
+---
+title: scout config init
+sidebar_label: config init
+sidebar_position: 2
+description:
+  Generate a production-ready OpenTelemetry Collector configuration file using an
+  interactive wizard. Supports Prometheus endpoint discovery, signal selection,
+  and multiple authentication methods.
+keywords:
+  - otel config generator
+  - opentelemetry config wizard
+  - collector config init
+  - scout config init
+  - otel collector setup
+---
+
+# scout config init
+
+Generate a production-ready OpenTelemetry Collector configuration file through
+an interactive wizard. The wizard walks you through service identity, signal
+types, OTLP endpoints, and authentication setup.
+
+![scout config init demo](/img/scout-cli/10-config-init.gif)
+
+## Usage
+
+```bash
+scout config init
+```
+
+This command is fully interactive — it has no flags.
+
+## Wizard Steps
+
+### 1. Prometheus Discovery (Optional)
+
+The wizard asks if you have Prometheus endpoints to scrape. If yes, you provide
+comma-separated endpoint URLs. The wizard checks HTTP reachability and extracts
+job labels.
+
+### 2. Service Identity
+
+Enter the service name for your application (e.g., `payment-service`). This is
+skipped if discovered from Prometheus endpoints.
+
+### 3. Environment
+
+Enter the deployment environment (e.g., `dev`, `staging`, `prod`).
+
+### 4. Signal Types
+
+Select which telemetry signals to enable:
+
+- **Traces** (default: enabled)
+- **Metrics** (default: enabled)
+- **Logs** (default: disabled)
+
+### 5. OTLP Endpoint
+
+Enter the OTLP exporter endpoint URL where the collector should send data
+(e.g., `https://your-backend.example.com/otlp`).
+
+### 6. Authentication Method
+
+Choose how the collector authenticates with the backend:
+
+| Method | Details |
+|--------|---------|
+| **None** | No authentication |
+| **Bearer Token** | Inline value or env var `${SCOUT_OTEL_AUTH_TOKEN}` |
+| **OAuth2 Client Credentials** | Inline or env vars: `${SCOUT_OTEL_CLIENT_ID}`, `${SCOUT_OTEL_CLIENT_SECRET}`, `${SCOUT_OTEL_TOKEN_URL}` |
+
+## Output
+
+The wizard generates an `otel-collector-config.yaml` file in the current
+directory. If the file already exists, you're prompted before overwriting.
+
+The generated config includes:
+
+- OTLP receivers (gRPC and HTTP)
+- Selected signal pipelines (traces, metrics, logs)
+- Memory limiter, batch processor, and retry settings
+- Resource processor with service name and environment
+- OTLP exporter with gzip compression
+- Health check extension
+
+:::note
+This is an interactive command. It requires a TTY and cannot be used in
+non-interactive or CI environments. For CI, create the config locally and commit
+it to your repository.
+:::
+
+:::tip
+After generating, validate and test your config:
+
+```bash
+scout config validate --file otel-collector-config.yaml
+scout config test --file otel-collector-config.yaml
+```
+
+:::
+
+## See Also
+
+- [config validate](./config-validate.md) — validate a configuration file
+- [config test](./config-test.md) — live-test a configuration
diff --git a/docs/scout-cli/open-source/config-test.md b/docs/scout-cli/open-source/config-test.md
new file mode 100644
index 0000000..45ddfec
--- /dev/null
+++ b/docs/scout-cli/open-source/config-test.md
@@ -0,0 +1,131 @@
+---
+title: scout config test
+sidebar_label: config test
+sidebar_position: 3
+description:
+  Live-test an OpenTelemetry Collector configuration by spawning a collector,
+  injecting debug components, and sending OTLP probes to verify each pipeline.
+keywords:
+  - otel config test
+  - opentelemetry collector test
+  - config validation
+  - scout config test
+  - otel pipeline test
+---
+
+# scout config test
+
+Live-test an OpenTelemetry Collector configuration by patching it with debug
+components, spawning a local collector, and sending OTLP probes to verify each
+pipeline works end-to-end.
+
+![scout config test demo](/img/scout-cli/11-config-test.gif)
+
+## Usage
+
+```bash
+scout config test [flags]
+```
+
+You can also pipe a config via stdin:
+
+```bash
+cat otel-collector.yaml | scout config test
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--file` | path | — | Path to the OTel config file. Reads from stdin if omitted |
+| `--dry-run` | bool | `false` | Show patched config without running the collector |
+| `--raw` | bool | `false` | Output JSON (patched config in dry-run, lifecycle result in live mode) |
+| `--isolated` | bool | `false` | Remove non-debug exporters from pipelines |
+| `--collector-bin` | path | — | Path to the OTel Collector binary. Auto-detects if not set |
+| `--startup-timeout` | seconds | `15` | Max seconds to wait for collector health check |
+| `--timeout` | seconds | `30` | Max seconds for the full test session |
+| `--interactive` | bool | `false` | Keep collector running after probes; show zpages/pprof URLs |
+
+## Examples
+
+Test a config file:
+
+```bash
+scout config test --file otel-collector-config.yaml
+```
+
+Preview the patched config without running the collector:
+
+```bash
+scout config test --file otel-collector-config.yaml --dry-run
+```
+
+Run in isolated mode (removes production exporters):
+
+```bash
+scout config test --file otel-collector-config.yaml --isolated
+```
+
+Use a specific collector binary:
+
+```bash
+scout config test --file otel-collector-config.yaml --collector-bin /usr/local/bin/otelcol-contrib
+```
+
+Keep the collector running for manual inspection:
+
+```bash
+scout config test --file otel-collector-config.yaml --interactive
+```
+
+Increase timeouts for slow environments:
+
+```bash
+scout config test --file otel-collector-config.yaml --startup-timeout 30 --timeout 60
+```
+
+## How It Works
+
+1. **Validates** the configuration (exits with code 2 if invalid)
+2. **Patches** the config with a debug exporter and extensions (zpages, pprof)
+3. **Starts** the OTel Collector binary (exits with code 3 on failure)
+4. **Waits** for the health check endpoint (polls every 500ms)
+5. **Sends** OTLP probes for each configured pipeline (traces, metrics, logs)
+6. **Monitors** the debug exporter output for probe data
+7. **Reports** per-pipeline pass/fail verdicts
+8. **Exits** with the appropriate code
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | All pipelines passed |
+| `1` | One or more pipelines failed or partially passed |
+| `2` | Configuration validation errors |
+| `3` | Collector failed to start |
+| `4` | No OTel Collector binary found |
+
+## Collector Binary Detection
+
+If `--collector-bin` is not specified, the command searches for a collector
+binary in this order:
+
+1. `otelcol-contrib` in `$PATH`
+2. `otelcol` in `$PATH`
+3. `~/.scout/bin/` directory
+
+:::warning
+The `--isolated` flag removes all non-debug exporters from pipelines. This
+prevents the test from sending data to production backends, but the patched
+config won't match your actual deployment.
+:::
+
+:::tip
+Use `--interactive` to keep the collector running after probes complete. This
+gives you access to zpages and pprof endpoints for debugging.
+:::
+
+## See Also
+
+- [config validate](./config-validate.md) — validate a configuration file
+- [config init](./config-init.md) — generate a configuration file
diff --git a/docs/scout-cli/open-source/config-validate.md b/docs/scout-cli/open-source/config-validate.md
new file mode 100644
index 0000000..ed9843a
--- /dev/null
+++ b/docs/scout-cli/open-source/config-validate.md
@@ -0,0 +1,97 @@
+---
+title: scout config validate
+sidebar_label: config validate
+sidebar_position: 1
+description:
+  Validate an OpenTelemetry Collector YAML configuration file offline. Checks
+  YAML syntax, component registry, pipeline references, and best practices.
+keywords:
+  - otel config validate
+  - opentelemetry collector config
+  - yaml validation
+  - otel collector validate
+  - scout config validate
+---
+
+# scout config validate
+
+Validate an OpenTelemetry Collector YAML configuration file without needing a
+running collector or Scout backend. Checks structure, component names, pipeline
+references, and best practices.
+
+![scout config validate demo](/img/scout-cli/09-config-validate.gif)
+
+## Usage
+
+```bash
+scout config validate [flags]
+```
+
+You can also pipe a config via stdin:
+
+```bash
+cat otel-collector.yaml | scout config validate
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--file` | path | — | Path to the YAML config file. Reads from stdin if omitted |
+| `--raw` | bool | `false` | Output structured JSON instead of human-readable text |
+
+## Examples
+
+Validate a config file:
+
+```bash
+scout config validate --file otel-collector-config.yaml
+```
+
+Validate from stdin:
+
+```bash
+cat otel-collector-config.yaml | scout config validate
+```
+
+Output structured JSON for CI integration:
+
+```bash
+scout config validate --file otel-collector-config.yaml --raw
+```
+
+## Validation Stages
+
+The validator checks your configuration in five stages:
+
+1. **YAML parsing** — syntax correctness
+2. **Top-level structure** — required sections (`service`, `pipelines`,
+   components)
+3. **Component names** — checked against the otelcol-contrib registry
+   (v0.111.0)
+4. **Cross-reference integrity** — pipeline references match defined components
+5. **Best practices** — unused components, missing health check extensions
+
+Errors fail validation. Warnings are reported but don't affect the exit code.
+
+## Exit Codes
+
+| Code | Meaning |
+|------|---------|
+| `0` | Valid configuration (warnings allowed) |
+| `1` | Validation errors found |
+| `2` | I/O or usage error (file not found, no input) |
+
+:::tip
+Use exit codes in CI pipelines to gate deployments on valid configurations:
+
+```bash
+scout config validate --file otel-collector-config.yaml || exit 1
+```
+
+:::
+
+## See Also
+
+- [config init](./config-init.md) — generate a configuration file
+- [config test](./config-test.md) — live-test a configuration
diff --git a/docs/scout-cli/platform/_category_.json b/docs/scout-cli/platform/_category_.json
new file mode 100644
index 0000000..98e2cf8
--- /dev/null
+++ b/docs/scout-cli/platform/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Platform Commands",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "generated-index",
+    "title": "Platform Commands",
+    "description": "Commands that interact with the Scout backend for authentication, querying telemetry data, and managing account contexts."
+  }
+}
diff --git a/docs/scout-cli/platform/alerts.md b/docs/scout-cli/platform/alerts.md
new file mode 100644
index 0000000..eb3e44f
--- /dev/null
+++ b/docs/scout-cli/platform/alerts.md
@@ -0,0 +1,99 @@
+---
+title: scout alerts
+sidebar_label: alerts
+sidebar_position: 5
+description:
+  Query alert history from the Scout platform. Filter by time range, tags,
+  and dashboard.
+keywords:
+  - scout alerts
+  - alert history
+  - observability alerts
+  - scout cli alerts
+  - alert query
+---
+
+# scout alerts
+
+Query alert history from the Scout platform. Results include alert name, state,
+previous state, timestamp, dashboard UID, and tags.
+
+![scout alerts demo](/img/scout-cli/04-alerts.gif)
+
+## Usage
+
+```bash
+scout alerts [flags]
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--limit` | integer | `20` | Maximum number of results (1–100) |
+| `--since` | duration | — | Time window (e.g., `2h`, `1d`). Max: 7 days. Conflicts with `--start` |
+| `--start` | RFC 3339 | — | Start time. Conflicts with `--since` |
+| `--end` | RFC 3339 | — | End time. Requires `--start` |
+| `--tag` | string | — | Filter by tag. Repeatable for multiple tags |
+| `--dashboard` | string | — | Filter by dashboard UID |
+| `--raw` | bool | `false` | Output JSON |
+
+## Examples
+
+Query the 20 most recent alerts:
+
+```bash
+scout alerts
+```
+
+Query alerts from the last 2 hours:
+
+```bash
+scout alerts --since 2h
+```
+
+Query alerts in a specific time range:
+
+```bash
+scout alerts --start 2026-03-26T14:00:00Z --end 2026-03-26T16:00:00Z
+```
+
+Filter by tag:
+
+```bash
+scout alerts --tag critical --tag payment
+```
+
+Filter by dashboard and output JSON:
+
+```bash
+scout alerts --dashboard abc123 --raw
+```
+
+Get more results:
+
+```bash
+scout alerts --since 1d --limit 100
+```
+
+## Time Ranges
+
+Use `--since` for relative time windows or `--start`/`--end` for absolute
+ranges. These two approaches are mutually exclusive.
+
+| Flag | Format | Example |
+|------|--------|---------|
+| `--since` | Duration string | `30m`, `2h`, `1d` |
+| `--start` | RFC 3339 | `2026-03-26T14:00:00Z` |
+| `--end` | RFC 3339 | `2026-03-26T16:00:00Z` |
+
+:::warning
+The maximum time range is 7 days. Queries exceeding this limit will return an
+error.
+:::
+
+## See Also
+
+- [logs](./logs.md) — query service logs
+- [traces](./traces.md) — query distributed traces
+- [metrics](./metrics.md) — query service metrics
diff --git a/docs/scout-cli/platform/context.md b/docs/scout-cli/platform/context.md
new file mode 100644
index 0000000..806dcce
--- /dev/null
+++ b/docs/scout-cli/platform/context.md
@@ -0,0 +1,147 @@
+---
+title: scout context
+sidebar_label: context
+sidebar_position: 4
+description:
+  Manage multiple Scout account contexts. Switch between organizations, view
+  context details, and configure API endpoints.
+keywords:
+  - scout context
+  - account management
+  - scout cli accounts
+  - multi-account
+  - switch organization
+---
+
+# scout context
+
+Manage authentication contexts when working with multiple Scout organizations.
+Each context stores an account name, authentication endpoint, and Scout API URL.
+
+![scout context demo](/img/scout-cli/03-context.gif)
+
+## Usage
+
+```bash
+scout context <SUBCOMMAND>
+```
+
+## Subcommands
+
+| Subcommand | Description |
+|------------|-------------|
+| `list` | List all configured contexts |
+| `set <NAME>` | Set the active context |
+| `show` | Display details of the current context |
+| `delete <NAME>` | Delete a context and its credentials |
+| `set-api-url <URL>` | Set the Scout API URL for a context |
+
+## scout context list
+
+List all configured contexts. The active context is marked with `*`.
+
+```bash
+scout context list
+```
+
+## scout context set
+
+Switch to a different account context.
+
+```bash
+scout context set <NAME>
+```
+
+**Arguments:**
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `NAME` | string | Context name to activate |
+
+**Example:**
+
+```bash
+scout context set staging-org
+```
+
+## scout context show
+
+Display details of the current active context, including name, endpoint, account
+slug, and API URL.
+
+```bash
+scout context show
+```
+
+## scout context delete
+
+Delete a context and remove its stored credentials.
+
+```bash
+scout context delete <NAME>
+```
+
+**Arguments:**
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `NAME` | string | Context name to delete |
+
+**Example:**
+
+```bash
+scout context delete old-org
+```
+
+## scout context set-api-url
+
+Override the Scout API URL for a context. Useful when connecting to a
+self-hosted Scout instance.
+
+```bash
+scout context set-api-url <URL>
+```
+
+**Arguments:**
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `URL` | string | Scout API endpoint URL |
+
+**Flags:**
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `-a, --account` | string | active context | Target a specific context instead of the active one |
+
+**Example:**
+
+```bash
+scout context set-api-url https://scout-api.internal.example.com
+```
+
+## Example Workflow
+
+Set up multiple organizations and switch between them:
+
+```bash
+# Authenticate with two organizations
+scout login --account prod-org
+scout login --account staging-org
+
+# List contexts
+scout context list
+
+# Switch to staging
+scout context set staging-org
+
+# Verify
+scout context show
+```
+
+## See Also
+
+- [login](./login.md) — authenticate with Scout
+- [status](./status.md) — check authentication status
+- [Global Flags](../reference/global-flags.md) — use `-a` to override context
+  per-command
diff --git a/docs/scout-cli/platform/login.md b/docs/scout-cli/platform/login.md
new file mode 100644
index 0000000..2d4e921
--- /dev/null
+++ b/docs/scout-cli/platform/login.md
@@ -0,0 +1,88 @@
+---
+title: scout login
+sidebar_label: login
+sidebar_position: 1
+description:
+  Authenticate with the Scout platform using OAuth2. Opens a browser for
+  PKCE authentication and stores credentials locally.
+keywords:
+  - scout login
+  - scout authentication
+  - oauth2 pkce
+  - scout cli auth
+---
+
+# scout login
+
+Authenticate with the Scout platform using an OAuth2 authorization code flow
+with PKCE. The command opens your browser to complete authentication, then stores
+tokens locally for subsequent commands.
+
+![scout login demo](/img/scout-cli/01-login.gif)
+
+## Usage
+
+```bash
+scout login --account <SLUG> [flags]
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `-a, --account` | string | *(required)* | Account slug. Env: `SCOUT_ACCOUNT_SLUG` |
+| `--auth-url` | string | `https://id.base14.io` | Authentication server URL. Env: `SCOUT_AUTH_URL` |
+| `--force` | bool | `false` | Re-authenticate even if a valid session exists |
+
+## Examples
+
+Authenticate with your organization:
+
+```bash
+scout login --account my-org
+```
+
+Force re-authentication to refresh tokens:
+
+```bash
+scout login --account my-org --force
+```
+
+Use a custom authentication server:
+
+```bash
+scout login --account my-org --auth-url https://auth.example.com
+```
+
+Use environment variables instead of flags:
+
+```bash
+export SCOUT_ACCOUNT_SLUG=my-org
+scout login
+```
+
+## How It Works
+
+1. Validates the account exists on the authentication server
+2. Starts a local HTTP listener for the OAuth2 callback
+3. Opens your browser to the authorization URL
+4. Exchanges the authorization code for access and refresh tokens
+5. Discovers the Scout API URL via the accounts API
+6. Stores tokens in your system keychain (falls back to
+   `~/.scout/credentials.json` with mode `0600`)
+
+:::note
+The login flow has a 5-minute timeout. If you don't complete browser
+authentication within that window, the command will exit.
+:::
+
+:::tip
+If the browser doesn't open automatically, the command prints a URL you can copy
+and paste manually.
+:::
+
+## See Also
+
+- [logout](./logout.md) — remove stored credentials
+- [status](./status.md) — check authentication status
+- [context](./context.md) — manage multiple account contexts
diff --git a/docs/scout-cli/platform/logout.md b/docs/scout-cli/platform/logout.md
new file mode 100644
index 0000000..4e6d2f0
--- /dev/null
+++ b/docs/scout-cli/platform/logout.md
@@ -0,0 +1,73 @@
+---
+title: scout logout
+sidebar_label: logout
+sidebar_position: 2
+description:
+  Remove stored Scout credentials for one or all accounts. Optionally revokes
+  the authentication session.
+keywords:
+  - scout logout
+  - remove credentials
+  - scout cli logout
+  - revoke session
+---
+
+# scout logout
+
+Remove stored credentials for a specific account or all accounts. If an
+authentication session is active, the command attempts to revoke it.
+
+![scout logout demo](/img/scout-cli/11-logout.gif)
+
+## Usage
+
+```bash
+scout logout [flags]
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `-a, --account` | string | — | Log out a specific account |
+| `--all` | bool | `false` | Log out of all accounts |
+| `--raw` | bool | `false` | Output JSON |
+
+## Examples
+
+Log out of a specific account:
+
+```bash
+scout logout --account my-org
+```
+
+Log out of all accounts:
+
+```bash
+scout logout --all
+```
+
+Output result as JSON:
+
+```bash
+scout logout --account my-org --raw
+```
+
+:::note
+If you omit both `--account` and `--all` and multiple sessions exist, the
+command prompts you to select an account interactively.
+:::
+
+## Behavior
+
+- Removes credentials from the system keychain (or `~/.scout/credentials.json`)
+- Attempts auth session revocation (best-effort — succeeds even if the
+  server is unreachable)
+- Keeps profile configuration intact so you can re-authenticate later
+- Shows remaining available sessions after logout
+
+## See Also
+
+- [login](./login.md) — authenticate with Scout
+- [status](./status.md) — check authentication status
+- [context](./context.md) — manage account contexts
diff --git a/docs/scout-cli/platform/logs.md b/docs/scout-cli/platform/logs.md
new file mode 100644
index 0000000..87ee6c4
--- /dev/null
+++ b/docs/scout-cli/platform/logs.md
@@ -0,0 +1,122 @@
+---
+title: scout logs
+sidebar_label: logs
+sidebar_position: 6
+description:
+  Query service logs from the Scout platform. Filter by severity, body text,
+  attributes, trace ID, and time range.
+keywords:
+  - scout logs
+  - log query
+  - opentelemetry logs
+  - scout cli logs
+  - service logs
+  - log search
+---
+
+# scout logs
+
+Query logs for a specific service from the Scout platform. Filter by severity,
+body content, attributes, and more.
+
+![scout logs demo](/img/scout-cli/05-logs.gif)
+
+## Usage
+
+```bash
+scout logs <SERVICE> [flags]
+```
+
+## Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `SERVICE` | string | *(required)* Service name to query logs for |
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--severity` | string | — | Severity levels, comma-delimited. Repeatable. Values: `INFO`, `WARN`, `ERROR`, `DEBUG`, `FATAL` |
+| `--contains` | string | — | Filter by body substring (case-insensitive) |
+| `--attr` | KEY=VALUE | — | Filter by log attribute. Repeatable (AND logic) |
+| `--resource` | KEY=VALUE | — | Filter by resource attribute. Repeatable (AND logic) |
+| `--trace-id` | string | — | Filter by trace ID |
+| `--since` | duration | `5m` | Time window (max: 15 minutes). Conflicts with `--start` |
+| `--start` | RFC 3339 | — | Start time. Conflicts with `--since` |
+| `--end` | RFC 3339 | — | End time. Requires `--start` |
+| `--limit` | integer | `100` | Maximum number of results (max: 1000) |
+| `--raw` | bool | `false` | Output JSON |
+| `--body-only` | bool | `false` | Output only log bodies, one per line. Conflicts with `--raw` |
+| `--discover` | bool | `false` | Show available log metadata instead of querying |
+| `--wide` | bool | `false` | Show full log bodies without truncation |
+
+## Examples
+
+Query recent logs for a service:
+
+```bash
+scout logs payment-service
+```
+
+Filter by severity:
+
+```bash
+scout logs payment-service --severity ERROR,WARN
+```
+
+Search log bodies:
+
+```bash
+scout logs payment-service --contains "timeout" --since 10m
+```
+
+Filter by attributes:
+
+```bash
+scout logs payment-service --attr user_id=123 --resource environment=prod
+```
+
+Correlate with a trace:
+
+```bash
+scout logs payment-service --trace-id abc123def456
+```
+
+Output only log bodies:
+
+```bash
+scout logs payment-service --body-only
+```
+
+Discover available metadata:
+
+```bash
+scout logs payment-service --discover
+```
+
+## Attribute Filtering
+
+Use `--attr` and `--resource` to filter by key-value pairs. Multiple filters of
+the same type use AND logic.
+
+```bash
+# Both conditions must match
+scout logs payment-service --attr user_id=123 --attr action=checkout
+```
+
+:::tip
+Use `--discover` to see available attribute keys and severity values before
+building a targeted query.
+:::
+
+:::warning
+The maximum time range is 15 minutes. For longer queries, use `--start` and
+`--end` with explicit timestamps.
+:::
+
+## See Also
+
+- [traces](./traces.md) — query distributed traces
+- [metrics](./metrics.md) — query service metrics
+- [alerts](./alerts.md) — query alert history
diff --git a/docs/scout-cli/platform/metrics.md b/docs/scout-cli/platform/metrics.md
new file mode 100644
index 0000000..2882554
--- /dev/null
+++ b/docs/scout-cli/platform/metrics.md
@@ -0,0 +1,94 @@
+---
+title: scout metrics
+sidebar_label: metrics
+sidebar_position: 7
+description:
+  Query service metrics from the Scout platform. Filter by metric type and name.
+  View metric names, types, descriptions, and activity timestamps.
+keywords:
+  - scout metrics
+  - metric query
+  - opentelemetry metrics
+  - scout cli metrics
+  - service metrics
+---
+
+# scout metrics
+
+Query metrics for a specific service from the Scout platform. Lists metric
+names, types, descriptions, and when they were first and last seen.
+
+![scout metrics demo](/img/scout-cli/06-metrics.gif)
+
+## Usage
+
+```bash
+scout metrics <SERVICE> [flags]
+```
+
+## Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `SERVICE` | string | *(required)* Service name to query metrics for |
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--since` | duration | `1h` | Time window (max: 1 hour). Conflicts with `--start` |
+| `--start` | RFC 3339 | — | Start time. Conflicts with `--since` |
+| `--end` | RFC 3339 | — | End time. Requires `--start` |
+| `--type` | string | — | Filter by metric type (e.g., `counter`, `gauge`, `histogram`) |
+| `--search` | string | — | Filter metrics by name substring (case-insensitive) |
+| `--wide` | bool | `false` | Show full descriptions without truncation |
+| `--raw` | bool | `false` | Output JSON |
+
+## Examples
+
+List all metrics for a service:
+
+```bash
+scout metrics payment-service
+```
+
+Filter by metric type:
+
+```bash
+scout metrics payment-service --type histogram
+```
+
+Search by metric name:
+
+```bash
+scout metrics payment-service --search latency
+```
+
+Combine type and search filters:
+
+```bash
+scout metrics payment-service --type counter --search request
+```
+
+Show full descriptions:
+
+```bash
+scout metrics payment-service --wide
+```
+
+Output as JSON:
+
+```bash
+scout metrics payment-service --raw
+```
+
+:::note
+The maximum time range is 1 hour. Metrics are sorted alphabetically by name in
+the default output.
+:::
+
+## See Also
+
+- [logs](./logs.md) — query service logs
+- [traces](./traces.md) — query distributed traces
+- [alerts](./alerts.md) — query alert history
diff --git a/docs/scout-cli/platform/service-map.md b/docs/scout-cli/platform/service-map.md
new file mode 100644
index 0000000..3eb5808
--- /dev/null
+++ b/docs/scout-cli/platform/service-map.md
@@ -0,0 +1,87 @@
+---
+title: scout service-map
+sidebar_label: service-map
+sidebar_position: 9
+description:
+  Visualize service topology and dependencies from the Scout platform. View
+  service-to-service communication patterns in the terminal or as JSON.
+keywords:
+  - service map
+  - service topology
+  - service dependencies
+  - scout cli service map
+  - microservices topology
+---
+
+# scout service-map
+
+Visualize service dependencies and topology. Shows which services communicate
+with each other, the span names involved, and when the connections were last
+observed.
+
+![scout service-map demo](/img/scout-cli/08-service-map.gif)
+
+## Usage
+
+```bash
+scout service-map [flags]
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--service` | string | — | Filter to specific services. Repeatable |
+| `--since` | duration | `1h` | Time window (max: 1 hour). Conflicts with `--start` |
+| `--start` | RFC 3339 | — | Start time. Conflicts with `--since` |
+| `--end` | RFC 3339 | — | End time. Requires `--start` |
+| `--raw` | bool | `false` | Output JSON |
+| `--interactive` | bool | `false` | Launch interactive TUI view |
+
+## Examples
+
+Show the full service topology:
+
+```bash
+scout service-map
+```
+
+Filter to specific services:
+
+```bash
+scout service-map --service payment --service notification
+```
+
+Show topology for the last 30 minutes:
+
+```bash
+scout service-map --since 30m
+```
+
+Launch the interactive terminal view:
+
+```bash
+scout service-map --interactive
+```
+
+Export as JSON for further analysis:
+
+```bash
+scout service-map --raw
+```
+
+:::tip
+Use `--interactive` to explore the service topology in a terminal-based UI that
+lets you navigate between services and their connections.
+:::
+
+:::note
+The maximum time range is 1 hour. Dependencies are grouped by source and target
+service pairs with deduplicated span names.
+:::
+
+## See Also
+
+- [traces](./traces.md) — query distributed traces
+- [logs](./logs.md) — query service logs
+- [metrics](./metrics.md) — query service metrics
diff --git a/docs/scout-cli/platform/status.md b/docs/scout-cli/platform/status.md
new file mode 100644
index 0000000..0a1aa1a
--- /dev/null
+++ b/docs/scout-cli/platform/status.md
@@ -0,0 +1,76 @@
+---
+title: scout status
+sidebar_label: status
+sidebar_position: 3
+description:
+  Display login status and token validity for all configured Scout accounts.
+  Optionally verify tokens with a live API call.
+keywords:
+  - scout status
+  - scout auth status
+  - scout session
+  - token validation
+---
+
+# scout status
+
+Display the authentication status for all configured accounts, including user
+email and token expiration. The active account is highlighted.
+
+![scout status demo](/img/scout-cli/02-status.gif)
+
+## Usage
+
+```bash
+scout status [flags]
+```
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--raw` | bool | `false` | Output JSON |
+| `--check` | bool | `false` | Verify the active token with a live API call to the auth server userinfo endpoint |
+
+## Examples
+
+Check local token status:
+
+```bash
+scout status
+```
+
+Verify the active token is still valid on the server:
+
+```bash
+scout status --check
+```
+
+Get status as JSON (useful for scripts):
+
+```bash
+scout status --raw
+```
+
+## Output
+
+The command lists all configured accounts with:
+
+- Account name
+- User email (extracted from the JWT)
+- Token expiration time
+- Whether the token is expired
+
+The active context is marked with a `*` prefix.
+
+:::tip
+Use `--check` to verify the token is still valid on the server. Without it,
+`scout status` only reads local token data and checks the expiration claim — the
+token could have been revoked server-side.
+:::
+
+## See Also
+
+- [login](./login.md) — authenticate with Scout
+- [logout](./logout.md) — remove credentials
+- [context](./context.md) — manage account contexts
diff --git a/docs/scout-cli/platform/traces.md b/docs/scout-cli/platform/traces.md
new file mode 100644
index 0000000..cd40eeb
--- /dev/null
+++ b/docs/scout-cli/platform/traces.md
@@ -0,0 +1,121 @@
+---
+title: scout traces
+sidebar_label: traces
+sidebar_position: 8
+description:
+  Query distributed traces from the Scout platform. Filter by span name, status
+  code, attributes, and time range. Drill into individual traces by ID.
+keywords:
+  - scout traces
+  - distributed tracing
+  - trace query
+  - opentelemetry traces
+  - scout cli traces
+  - span search
+---
+
+# scout traces
+
+Query traces and spans for a specific service from the Scout platform. Filter by
+span name, status code, attributes, and time range.
+
+![scout traces demo](/img/scout-cli/07-traces.gif)
+
+## Usage
+
+```bash
+scout traces <SERVICE> [flags]
+```
+
+## Arguments
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `SERVICE` | string | *(required)* Service name to query traces for |
+
+## Flags
+
+| Flag | Type | Default | Description |
+|------|------|---------|-------------|
+| `--span` | string | — | Filter by span name. Repeatable (OR logic) |
+| `--status` | string | — | Filter by status code. Repeatable. Values: `Unset`, `Ok`, `Error` (case-insensitive) |
+| `--attr` | KEY=VALUE | — | Filter by span attribute. Repeatable (AND logic) |
+| `--resource` | KEY=VALUE | — | Filter by resource attribute. Repeatable (AND logic) |
+| `--since` | duration | `5m` | Time window (max: 15 minutes). Conflicts with `--start` |
+| `--start` | RFC 3339 | — | Start time. Conflicts with `--since` |
+| `--end` | RFC 3339 | — | End time. Requires `--start` |
+| `--limit` | integer | `50` | Maximum number of results (max: 100) |
+| `--raw` | bool | `false` | Output JSON |
+| `--discover` | bool | `false` | Show available span metadata instead of querying |
+| `--id` | string | — | Drill into a specific trace by ID. Extends the time window to 60 minutes |
+
+## Examples
+
+Query recent traces:
+
+```bash
+scout traces payment-service
+```
+
+Filter by span name:
+
+```bash
+scout traces payment-service --span checkout --span payment
+```
+
+Filter by error status:
+
+```bash
+scout traces payment-service --status Error
+```
+
+Filter by attributes:
+
+```bash
+scout traces payment-service --attr user_id=123 --resource environment=prod
+```
+
+Drill into a specific trace:
+
+```bash
+scout traces payment-service --id abc123def456
+```
+
+Discover available span names and attributes:
+
+```bash
+scout traces payment-service --discover
+```
+
+## Filtering Logic
+
+- **`--span`** — Multiple values use OR logic (matches any of the given span
+  names)
+- **`--status`** — Multiple values use OR logic. Valid values: `Unset`, `Ok`,
+  `Error` (case-insensitive)
+- **`--attr` and `--resource`** — Multiple values use AND logic (all conditions
+  must match)
+
+:::tip
+Use `--discover` to see available span names, status codes, and attribute keys
+before building a targeted query.
+:::
+
+:::note
+When using `--id` to drill into a specific trace, the time window is
+automatically extended to 60 minutes to ensure the full trace is captured.
+:::
+
+## Time Ranges
+
+| Method | Max Window |
+|--------|-----------|
+| `--since` | 15 minutes |
+| `--start` / `--end` | 30 minutes |
+| `--id` | 60 minutes |
+
+## See Also
+
+- [logs](./logs.md) — query service logs
+- [metrics](./metrics.md) — query service metrics
+- [service-map](./service-map.md) — visualize service topology
diff --git a/docs/scout-cli/platform/tui.md b/docs/scout-cli/platform/tui.md
new file mode 100644
index 0000000..6d150cf
--- /dev/null
+++ b/docs/scout-cli/platform/tui.md
@@ -0,0 +1,142 @@
+---
+title: TUI Mode
+sidebar_label: TUI Mode
+sidebar_position: 10
+description:
+  Launch the Scout interactive terminal dashboard. View service health, alerts,
+  dependencies, and logs in a real-time terminal UI.
+keywords:
+  - scout tui
+  - terminal ui
+  - interactive dashboard
+  - scout cli dashboard
+  - service health dashboard
+---
+
+# TUI Mode
+
+Running `scout` without a subcommand launches an interactive terminal dashboard.
+The TUI provides a real-time view of service health, alerts, dependencies, and
+logs — all from your terminal.
+
+![scout TUI demo](/img/scout-cli/12-tui.gif)
+
+## Usage
+
+```bash
+scout
+```
+
+:::note
+TUI mode requires an active authentication session. Run
+[`scout login`](./login.md) first.
+:::
+
+## Views
+
+The TUI has three main views, accessible via keyboard navigation.
+
+### Home
+
+The default landing view shows a health summary dashboard with three sections
+(cycle with `Tab`):
+
+| Section | Description |
+|---------|-------------|
+| **Heatmap** | Service health visualization. Switch modes with `1`–`4`: error rate, latency, alerts, dependencies |
+| **Alerts** | Active and firing alerts with rule names, severity, and timestamps |
+| **Services** | Table of all services with error rates, latency, last-seen timestamps, and dependency counts |
+
+In the Services section, sort by different columns:
+
+| Key | Sort By |
+|-----|---------|
+| `e` | Error rate |
+| `l` | Latency |
+| `n` | Name |
+| `d` | Dependencies |
+| `t` | Status |
+| `o` | Last seen |
+
+### Services
+
+A searchable list of all discovered services. Filter by name with `/`, then
+press `Enter` to confirm or `Esc` to clear. Select a service and press `L` to
+view its logs.
+
+### Logs
+
+A live log stream for the selected service. Shows timestamp, severity, and
+message body. Press `Enter` to expand a log entry and view trace ID, span ID,
+attributes, and resource metadata.
+
+| Feature | Key |
+|---------|-----|
+| Toggle autoscroll | `s` (fetches new logs every 2 seconds) |
+| Toggle line wrap | `w` |
+| Filter logs | `/` |
+| Expand/collapse entry | `Enter` |
+| Horizontal scroll (wrap off) | `Left` / `Right` |
+
+## Keyboard Shortcuts
+
+### Global
+
+| Key | Action |
+|-----|--------|
+| `q` | Quit |
+| `Ctrl+C` | Force quit |
+| `?` | Toggle help overlay |
+| `r` | Refresh data |
+| `j` / `Down` | Move down |
+| `k` / `Up` | Move up |
+| `g` | Jump to top |
+| `G` | Jump to bottom |
+
+### Home View
+
+| Key | Action |
+|-----|--------|
+| `Tab` | Cycle sections (Heatmap, Alerts, Services) |
+| `1`–`4` | Switch heatmap mode (error rate, latency, alerts, dependencies) |
+| `Left` / `Right` | Page through heatmap |
+| `Enter` | Open alert URL or view selected service |
+| `s` | Switch to Services view |
+
+### Services View
+
+| Key | Action |
+|-----|--------|
+| `/` | Enter filter mode |
+| `L` | View logs for selected service |
+| `Esc` | Back to Home |
+
+### Logs View
+
+| Key | Action |
+|-----|--------|
+| `s` | Toggle autoscroll |
+| `w` | Toggle line wrap |
+| `/` | Filter logs |
+| `Enter` | Expand/collapse log detail |
+| `Left` / `Right` | Horizontal scroll (wrap off) |
+| `Home` / `End` | Jump to start/end of line |
+| `Esc` | Close detail or go back to Services |
+
+## Auto-Refresh
+
+The TUI refreshes data automatically in the background:
+
+| Data | Interval |
+|------|----------|
+| Services and topology | Every 30 seconds |
+| Health summary | Every 30 seconds |
+| Logs (autoscroll on) | Every 2 seconds |
+
+Press `r` at any time to trigger an immediate refresh.
+
+## See Also
+
+- [login](./login.md) — authenticate before launching the TUI
+- [logs](./logs.md) — query logs from the command line
+- [service-map](./service-map.md) — view service topology from the command line
diff --git a/docs/scout-cli/reference/_category_.json b/docs/scout-cli/reference/_category_.json
new file mode 100644
index 0000000..cd486e6
--- /dev/null
+++ b/docs/scout-cli/reference/_category_.json
@@ -0,0 +1,10 @@
+{
+  "label": "Reference",
+  "position": 5,
+  "collapsed": true,
+  "link": {
+    "type": "generated-index",
+    "title": "Scout CLI Reference",
+    "description": "Environment variables, configuration files, and global flags for the Scout CLI."
+  }
+}
diff --git a/docs/scout-cli/reference/environment-variables.md b/docs/scout-cli/reference/environment-variables.md
new file mode 100644
index 0000000..e3daae9
--- /dev/null
+++ b/docs/scout-cli/reference/environment-variables.md
@@ -0,0 +1,55 @@
+---
+title: Environment Variables
+sidebar_label: Environment Variables
+sidebar_position: 1
+description:
+  Environment variables for configuring the Scout CLI. Override authentication
+  endpoints, API URLs, and output behavior.
+keywords:
+  - scout env vars
+  - scout configuration
+  - scout environment variables
+  - scout cli config
+---
+
+# Environment Variables
+
+Scout CLI reads these environment variables. Flags take precedence over
+environment variables when both are set.
+
+## Authentication
+
+| Variable | Description | Default | Used By |
+|----------|-------------|---------|---------|
+| `SCOUT_ACCOUNT_SLUG` | Default account slug | — | [login](../platform/login.md) |
+| `SCOUT_AUTH_URL` | Authentication server URL | `https://id.base14.io` | [login](../platform/login.md) |
+
+## API
+
+| Variable | Description | Default | Used By |
+|----------|-------------|---------|---------|
+| `SCOUT_API_URL` | Override the Scout API base URL | Auto-discovered on login | All platform commands |
+| `SCOUT_ACCOUNTS_API_URL` | Override the accounts discovery API URL | `https://api.base14.io` | [login](../platform/login.md) |
+
+## OTel Collector Authentication
+
+These variables are referenced in configs generated by
+[`scout config init`](../open-source/config-init.md):
+
+| Variable | Description |
+|----------|-------------|
+| `SCOUT_OTEL_AUTH_TOKEN` | Bearer token for OTLP exporter authentication |
+| `SCOUT_OTEL_CLIENT_ID` | OAuth2 client ID for OTLP exporter |
+| `SCOUT_OTEL_CLIENT_SECRET` | OAuth2 client secret for OTLP exporter |
+| `SCOUT_OTEL_TOKEN_URL` | OAuth2 token endpoint for OTLP exporter |
+
+## Output and Debugging
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NO_COLOR` | Disable ANSI color output when set to any value | — |
+| `RUST_LOG` | Set log level for debug output (e.g., `debug`, `info`) | — |
+
+## See Also
+
+- [Global Flags](./global-flags.md) — flags available on every command
diff --git a/docs/scout-cli/reference/global-flags.md b/docs/scout-cli/reference/global-flags.md
new file mode 100644
index 0000000..2a29360
--- /dev/null
+++ b/docs/scout-cli/reference/global-flags.md
@@ -0,0 +1,60 @@
+---
+title: Global Flags
+sidebar_label: Global Flags
+sidebar_position: 2
+description:
+  Global flags available on every Scout CLI command. Enable verbose logging or
+  override the active account context.
+keywords:
+  - scout cli flags
+  - scout verbose
+  - scout account flag
+  - scout global options
+---
+
+# Global Flags
+
+These flags are available on every Scout CLI command.
+
+## Flags
+
+| Flag | Type | Description |
+|------|------|-------------|
+| `-v, --verbose` | bool | Enable verbose debug logging to stderr. Useful for troubleshooting authentication, API requests, and config parsing |
+| `-a, --account <NAME>` | string | Override the active account context for this command. Equivalent to running `scout context set <NAME>` temporarily |
+
+## Examples
+
+Enable verbose logging to debug a failing query:
+
+```bash
+scout -v logs payment-service --since 5m
+```
+
+Run a command against a different account without switching context:
+
+```bash
+scout -a staging-org alerts --since 1h
+```
+
+Combine both flags:
+
+```bash
+scout -v -a prod-org traces payment-service --status Error
+```
+
+:::tip
+Verbose output is written to stderr, so you can still pipe or redirect the
+command's normal output:
+
+```bash
+scout -v logs payment-service --raw 2>debug.log | jq .
+```
+
+:::
+
+## See Also
+
+- [Environment Variables](./environment-variables.md) — configure Scout CLI
+  via environment
+- [context](../platform/context.md) — manage account contexts persistently
diff --git a/sidebars.ts b/sidebars.ts
index da456c0..fe81817 100644
--- a/sidebars.ts
+++ b/sidebars.ts
@@ -16,6 +16,11 @@ const sidebars: SidebarsConfig = {
   tutorialSidebar: [
     'introduction',
     'getting-started',
+    {
+      type: 'category',
+      label: 'Scout CLI',
+      items: [{type: 'autogenerated', dirName: 'scout-cli'}],
+    },
     {
       type: 'category',
       label: 'Scout MCP',
diff --git a/static/img/scout-cli/01-login.gif b/static/img/scout-cli/01-login.gif
new file mode 100644
index 0000000..f7cce7f
Binary files /dev/null and b/static/img/scout-cli/01-login.gif differ
diff --git a/static/img/scout-cli/02-status.gif b/static/img/scout-cli/02-status.gif
new file mode 100644
index 0000000..1d8c529
Binary files /dev/null and b/static/img/scout-cli/02-status.gif differ
diff --git a/static/img/scout-cli/03-context.gif b/static/img/scout-cli/03-context.gif
new file mode 100644
index 0000000..7be5eb7
Binary files /dev/null and b/static/img/scout-cli/03-context.gif differ
diff --git a/static/img/scout-cli/04-alerts.gif b/static/img/scout-cli/04-alerts.gif
new file mode 100644
index 0000000..c4085b6
Binary files /dev/null and b/static/img/scout-cli/04-alerts.gif differ
diff --git a/static/img/scout-cli/05-logs.gif b/static/img/scout-cli/05-logs.gif
new file mode 100644
index 0000000..3e4eba3
Binary files /dev/null and b/static/img/scout-cli/05-logs.gif differ
diff --git a/static/img/scout-cli/06-metrics.gif b/static/img/scout-cli/06-metrics.gif
new file mode 100644
index 0000000..44bd9ce
Binary files /dev/null and b/static/img/scout-cli/06-metrics.gif differ
diff --git a/static/img/scout-cli/07-traces.gif b/static/img/scout-cli/07-traces.gif
new file mode 100644
index 0000000..ee4aa5a
Binary files /dev/null and b/static/img/scout-cli/07-traces.gif differ
diff --git a/static/img/scout-cli/08-service-map.gif b/static/img/scout-cli/08-service-map.gif
new file mode 100644
index 0000000..cce1ae6
Binary files /dev/null and b/static/img/scout-cli/08-service-map.gif differ
diff --git a/static/img/scout-cli/09-config-validate.gif b/static/img/scout-cli/09-config-validate.gif
new file mode 100644
index 0000000..98bd0dd
Binary files /dev/null and b/static/img/scout-cli/09-config-validate.gif differ
diff --git a/static/img/scout-cli/10-config-init.gif b/static/img/scout-cli/10-config-init.gif
new file mode 100644
index 0000000..6b8ce57
Binary files /dev/null and b/static/img/scout-cli/10-config-init.gif differ
diff --git a/static/img/scout-cli/11-config-test.gif b/static/img/scout-cli/11-config-test.gif
new file mode 100644
index 0000000..698b38f
Binary files /dev/null and b/static/img/scout-cli/11-config-test.gif differ
diff --git a/static/img/scout-cli/11-logout.gif b/static/img/scout-cli/11-logout.gif
new file mode 100644
index 0000000..badb626
Binary files /dev/null and b/static/img/scout-cli/11-logout.gif differ
diff --git a/static/img/scout-cli/12-tui.gif b/static/img/scout-cli/12-tui.gif
new file mode 100644
index 0000000..df0f490
Binary files /dev/null and b/static/img/scout-cli/12-tui.gif differ