Add Scout CLI documentation

.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

.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:

.markdownlintignore

@@ -1,3 +1,5 @@
 node_modules
 build
 plans/
+docs/superpowers/
+.claude/

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.

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)

docs/scout-cli/_category_.json

@@ -0,0 +1,9 @@
+{
+  "label": "Scout CLI",
+  "position": 3,
+  "collapsed": false,
+  "link": {
+    "type": "doc",
+    "id": "scout-cli/index"
+  }
+}

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