@stacknext/cli 0.8.0 → 0.10.0

package/docs/commands.md

@@ -0,0 +1,192 @@
+---
+title: Commands
+description: Complete reference for the stacknext CLI commands and options.
+---
+
+# Commands
+
+Run `stacknext <command> --help` for the installed version's exact flags. All
+commands run from a Next.js application directory unless stated otherwise.
+
+## `stacknext init`
+
+Configure a project. Writes `stacknext.config.json` and generated
+`instrumentation.ts`/`.js` only when absent; never overwrites user files.
+
+| Option | Meaning |
+| --- | --- |
+| `--install` | Install `@stacknext/next` with the detected package manager. |
+| `--agents` | Add or update the managed StackNext block in `AGENTS.md`. |
+| `--skip-agents` | Explicitly skip the managed block (the default). |
+
+## `stacknext dev`
+
+Start the loopback collector and dashboard, then run the app's `dev` script.
+
+| Option | Meaning |
+| --- | --- |
+| `--open` | Open the dashboard in the default browser. |
+| `--quiet` | Reduce startup output. |
+| `--token <token>` | Use an existing token (16+ characters). |
+
+`dev` writes `.stacknext/run.json` with mode `0600` and removes it on graceful
+shutdown. Stop it with SIGINT/SIGTERM, not `SIGKILL`.
+
+## `stacknext status`
+
+Print the runtime, collector connection and current counts.
+
+| Option | Meaning |
+| --- | --- |
+| `--json` | Machine-readable output. |
+
+## `stacknext doctor`
+
+Check Node.js, Next.js, the App Router, config, instrumentation, adapters,
+dashboard build, runtime file permissions and collector health.
+
+| Option | Meaning |
+| --- | --- |
+| `--json` | Machine-readable result with `checks`, `failures`, `warnings`. |
+
+Exit code is `1` when a check fails.
+
+## `stacknext coverage`
+
+Show what the current retention window observed. Evidence, not a score.
+
+| Option | Meaning |
+| --- | --- |
+| `--json` | Machine-readable `CoverageReport`. |
+
+## `stacknext diagnose`
+
+List deterministic findings or show one finding.
+
+| Option | Meaning |
+| --- | --- |
+| `--id <finding-id>` | Show one finding and its related trace. |
+| `--trace-id <trace-id>` | Findings that reference a trace. |
+| `--category <category>` | `database`, `http`, `performance`, `errors`, `runtime`. |
+| `--severity <severity>` | `info`, `warning`, `error`. |
+| `--status <status>` | `observed`, `possible`, `insufficient-evidence`. |
+| `--rule <rule-id>` | One of the six rule ids. |
+| `--route <route>` | Route substring. |
+| `--since <time>` / `--until <time>` | ISO timestamp or epoch ms. |
+| `--limit <n>` / `--offset <n>` | Pagination. |
+| `-q, --q <text>` | Search text. |
+| `--json` | Machine-readable output. |
+
+## `stacknext capture`
+
+Run a test command and save correlated telemetry as a run.
+
+```bash
+stacknext capture --name baseline -- pnpm exec playwright test --workers=1
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--name <name>` | Run name. |
+| `--project <name>` | Project name override. |
+| `--attach` | Require an existing `stacknext dev` collector. |
+| `--url <url>` | Attach to a specific loopback collector. |
+| `--token <token>` | Token for `--url`. |
+| `--json` | Machine-readable result. |
+| `--quiet` | Reduce output. |
+
+A successful child with incomplete telemetry exits `3`.
+
+## `stacknext runs`
+
+| Command | Options | Purpose |
+| --- | --- | --- |
+| `runs list` | `--limit`, `--offset`, `--json` | List live and saved runs. |
+| `runs show <run-id>` | `--json` | Show one run and its samples. |
+
+## `stacknext baseline`
+
+| Command | Options | Purpose |
+| --- | --- | --- |
+| `baseline save <run-id>` | `--name <name>`, `--notes <text>`, `--overwrite`, `--json` | Save a completed run. |
+| `baseline list` | `--limit`, `--offset`, `--json` | List baselines. |
+| `baseline show <baseline-id>` | `--json` | Show one baseline. |
+| `baseline remove <baseline-id>` | `--yes`, `--json` | Permanently remove one baseline. |
+
+`--name` is required. Only a completed run can become a baseline.
+
+## `stacknext compare`
+
+```bash
+stacknext compare <baseline-id> <candidate-run-id>
+```
+
+| Option | Meaning |
+| --- | --- |
+| `--json` | Machine-readable result. |
+| `--ignore-environment` | Compare despite environment differences (warning retained). |
+| `--min-samples <n>` | Minimum verified samples per side (default 3). |
+| `--duration-regression-pct <n>` | Default 20. |
+| `--duration-regression-ms <n>` | Default 25. |
+| `--duration-improvement-pct <n>` | Default 20. |
+| `--duration-improvement-ms <n>` | Default 25. |
+| `--count-regression-min <n>` | Default 1. |
+| `--fail-on <status>` | Exit 1 for `regression`, `inconclusive` or `any`. |
+| `--no-save` | Do not persist the comparison. |
+
+Comparisons are report-only by default. `inconclusive` is not a pass.
+
+## `stacknext snapshot`
+
+| Command | Options | Purpose |
+| --- | --- | --- |
+| `snapshot save` | `--label`, `--json` | Freeze the current sample. |
+| `snapshot list` | `--limit`, `--offset`, `--json` | List snapshots. |
+| `snapshot show <id>` | `--json` | Show a summary or full payload. |
+| `snapshot export <id>` | `-o, --output`, `--stdout`, `--force` | Export redacted JSON. |
+| `snapshot import <file>` | `--label`, `--json` | Import and re-redact. |
+| `snapshot delete <id>` | `--yes`, `--json` | Delete one snapshot. |
+
+`snapshots` is an alias for `snapshot`.
+
+## `stacknext export`
+
+| Option | Meaning |
+| --- | --- |
+| `-o, --output <file>` | Output path. |
+| `--stdout` | Write JSON to stdout. |
+| `--force` | Overwrite an existing output file. |
+
+## `stacknext mcp`
+
+Start the read-only stdio MCP server.
+
+| Option | Meaning |
+| --- | --- |
+| `--collector <url>` | Collector URL (defaults to runtime state). |
+| `--token <token>` | Bearer token (defaults to runtime state). |
+
+## `stacknext skill`
+
+| Command | Options | Purpose |
+| --- | --- | --- |
+| `skill path` | `--json` | Print the bundled skill directory and version. |
+| `skill install` | `--client opencode\|codex\|claude-code`, `--dir`, `--force`, `--json` | Copy the skill into a project. |
+
+## `stacknext uninstall`
+
+Print a removal plan unless `--yes` is passed.
+
+| Option | Meaning |
+| --- | --- |
+| `--yes` | Apply the plan. |
+| `--keep-config` | Preserve `stacknext.config.json`. |
+| `--remove-data` | Remove `.stacknext` saved data (refused while running). |
+| `--json` | Machine-readable report. |
+
+## Global
+
+```bash
+stacknext --version
+stacknext --help
+```

package/docs/configuration.md

@@ -0,0 +1,100 @@
+---
+title: Configuration
+description: stacknext.config.json, runtime state, ports and environment variables.
+---
+
+# Configuration
+
+## Project config
+
+`stacknext init` creates `stacknext.config.json` at the application root. The
+full schema, defaults and validation rules live in
+the `@stacknext/core` package's `docs/configuration.md` (follow its relative path
+in `packages.md`).
+
+Minimal generated example:
+
+```json
+{
+  "projectName": "my-app",
+  "dashboard": { "port": 4400 },
+  "collector": { "maxSpans": 5000, "retentionMs": 600000 },
+  "instrumentation": { "verbose": false, "captureFetch": true, "captureErrors": true },
+  "privacy": {
+    "captureHeaders": false,
+    "captureRequestBodies": false,
+    "captureSqlParameters": false,
+    "redactSensitiveData": true
+  },
+  "database": { "drizzle": false, "prisma": false },
+  "slowRequestMs": 500
+}
+```
+
+Missing fields are filled with defaults when loaded. Unknown fields are
+rejected. Privacy capture flags must remain `false` and redaction must remain
+`true`.
+
+## Runtime state
+
+While `stacknext dev` runs:
+
+```text
+.stacknext/
+├── .gitignore
+├── run.json        # mode 0600, contains the bearer token
+├── snapshots/
+├── runs/
+├── baselines/
+└── comparisons/
+```
+
+`run.json` is written on startup and removed on graceful shutdown. If a process
+is killed, the file can be stale; `stacknext doctor` detects a dead pid. Never
+commit or share `run.json`.
+
+`.stacknext` is created with mode `0700`; saved records use `0600`.
+
+## Ports
+
+- Preferred dashboard/collector port: 4400.
+- If busy, StackNext tries the next 25 ports.
+- The example app listens on 4402 by default.
+
+The collector binds only to `127.0.0.1` or `localhost` and rejects non-loopback
+`Host` headers.
+
+## Environment variables
+
+| Variable | Used by | Meaning |
+| --- | --- | --- |
+| `STACKNEXT_COLLECTOR_URL` | app, Playwright | Loopback collector URL. |
+| `STACKNEXT_TOKEN` | app, capture | Bearer token. |
+| `STACKNEXT_PROJECT_NAME` | app | Project name. |
+| `STACKNEXT_SERVICE_NAME` | app | OTel service name. |
+| `STACKNEXT_NEXT_VERSION` | app | Next.js version for environment checks. |
+| `STACKNEXT_CAPTURE_FETCH` | app | `0` drops fetch spans. |
+| `STACKNEXT_CAPTURE_ERRORS` | app | `0` disables error collection. |
+| `STACKNEXT_DEBUG` | app, CLI | `1` enables debug logs. |
+| `NEXT_OTEL_VERBOSE` | app | `1` enables documented verbose Next.js spans. |
+| `STACKNEXT_TEST_RUN_ID` | Playwright | Active run id. |
+| `STACKNEXT_CAPTURE_SETTLE_MS` | Playwright | Probe delay (default 500). |
+| `STACKNEXT_CAPTURE_TIMEOUT_MS` | Playwright | Probe timeout (default 5000). |
+| `STACKNEXT_PACK_DIR` | release scripts | Archive output directory. |
+
+`stacknext dev` exports the first group to the Next.js child process. An
+explicit value wins over the config; for example `NEXT_OTEL_VERBOSE=0` disables
+verbose tracing even when `instrumentation.verbose` is `true`.
+
+## Config ownership
+
+- `stacknext dev` reads and validates the config.
+- `stacknext doctor` reports invalid fields with issue paths.
+- `stacknext uninstall` removes the config unless `--keep-config` is passed.
+- Regression and snapshots record the resolved config with their evidence.
+
+## Related
+
+- [@stacknext/core configuration](../../core/docs/configuration.md)
+- [Agent setup](agent-setup.md)
+- [Troubleshooting](troubleshooting.md)

package/docs/index.md

@@ -0,0 +1,142 @@
+---
+title: StackNext local documentation
+description: Entry point and package index for the version-matched StackNext documentation installed with @stacknext/cli.
+---
+
+# StackNext local documentation
+
+This directory ships inside the installed `@stacknext/cli` package. It is the
+fastest way for a developer or coding agent to find documentation that matches
+the installed StackNext version, without network access.
+
+## Start here
+
+1. Read [commands](commands.md) for the CLI surface.
+2. Read [configuration](configuration.md) for `stacknext.config.json`.
+3. Read [agent setup](agent-setup.md) when configuring an AI client.
+4. Read the package document for every package involved in the task.
+
+The generated [package index](packages.md) lists the documented packages, their
+versions, their role and the path to each package's own documentation.
+
+## Version matching
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:e6af214d2a4b32adab7521d25e5832f83653a892caaf39c3eddbd1f46461e7a6 -->
+
+Packages currently shipping a `docs/` directory include package-specific
+documentation in the same npm archive as their code. That documentation
+therefore matches the installed version by construction.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+Check a version before relying on an API:
+
+```bash
+node -p "require('@stacknext/next/package.json').version"
+```
+
+Read the `package.json` next to the package's `docs/` directory. Do not assume
+that this documentation matches a different release or the project's main
+branch.
+
+## Locating package documentation
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:e89f29adfff1f8925389640671146bfdf24816a645149772ceb1d2ad0c5288cd -->
+
+Package docs ship inside installed packages that currently include a `docs/` directory. Start from this CLI `docs/`
+directory and use the relative paths in the generated
+[package index](packages.md), because optional and internal packages may not sit
+at the app's root `node_modules` path.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+Direct integration packages are normally at the app root when installed there:
+
+```text
+node_modules/@stacknext/cli/docs/index.md
+node_modules/@stacknext/next/docs/index.md
+node_modules/@stacknext/drizzle/docs/index.md
+node_modules/@stacknext/prisma/docs/index.md
+node_modules/@stacknext/playwright/docs/index.md
+```
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:a2a2d1bacf1a7101a5884977852db99861650a2a201f6dffdf985fa4ec246abe -->
+
+`@stacknext/core` and `@stacknext/regression` are installed through the CLI
+and ship documentation. In a pnpm workspace, locate their docs using the
+relative paths listed in `packages.md`. The CLI also installs
+`@stacknext/diagnostics`, `@stacknext/mcp` and `@stacknext/dashboard`, which
+do not currently ship `docs/` directories.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+If neither the direct path nor the relative index path exists, the package is
+not available to this project. Do not invent its documentation path or assume
+its APIs are available.
+
+## Which package to read
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:cce8643ce7fa90852e67d36250d2daa286bf00bf29c08506b2ca194409f5b5a8 -->
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:4ccde9b676836098da0c0e0810b43c6306a967030d387f11f30aed3a2b950eab -->
+
+| Task | Read |
+| --- | --- |
+| Install, configure or run StackNext | `cli`, `next` |
+| Change `instrumentation.ts` or manual spans | `next` |
+| Work with shared types, redaction, transport or snapshots | `core` |
+| Change or interpret diagnostic findings | CLI [commands](commands.md) |
+| Work with Playwright capture, baselines or comparisons | `playwright`, `regression` |
+| Add Drizzle query evidence | `drizzle` |
+| Add Prisma query evidence | `prisma` |
+| Configure an MCP client or use runtime evidence | CLI [agent setup](agent-setup.md) |
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Optional and internal packages
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:a2dd9b11290d93c4f272aa68aa40252cdb2bb1e42b5f87e52a85da57d3345086 -->
+
+- **Public integration packages:** `@stacknext/cli`, `@stacknext/next`,
+  `@stacknext/playwright`, `@stacknext/drizzle`, `@stacknext/prisma`.
+- **Installed by the CLI:** `@stacknext/core`, `@stacknext/diagnostics`,
+  `@stacknext/regression`, `@stacknext/mcp`, `@stacknext/dashboard`.
+- Optional packages are only present when the project installed them. Never
+  instruct an agent to read a package directory that is not installed.
+- Internal packages that ship `docs/` are documented for maintainers;
+  applications should not install them directly.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Rules for coding agents
+
+- Prefer this local documentation over model memory or online documentation for
+  the installed version.
+- Verify the package version before using an API or example.
+- Do not assume undocumented exports, configuration keys or integrations exist.
+- For runtime investigation, use the StackNext MCP tools where available.
+- Follow the installed `stacknext-debugging` Agent Skill for evidence-first
+  workflows.
+- Treat diagnostic findings as evidence, not confirmed root causes.
+- Treat `inconclusive` regression comparisons as inconclusive, not passes.
+
+## More documentation
+
+- [Agent setup](agent-setup.md) — `stacknext init --agents`, MCP and skills.
+- [Skill installation](skill.md) — supported clients and paths.
+- [Troubleshooting](troubleshooting.md) — missing telemetry, ports and clients.
+- [Package index](packages.md) — generated list of installed package docs.

package/docs/packages.md

@@ -0,0 +1,71 @@
+---
+title: Installed package documentation
+description: Generated index of the documented StackNext packages and their local documentation paths.
+---
+
+<!-- Generated by scripts/sync-docs.mjs. Do not edit this file. -->
+
+# Installed package documentation
+
+This index is generated from the packages that ship documentation. It does
+not mean every package is installed in a project. Check the path before
+reading: optional packages can be absent.
+
+Versions in this table are the versions of the package that produced this
+archive. Read the `version` field in the package.json next to the docs
+directory to confirm the installed version.
+
+| Package | Version | Visibility | Role | Documentation |
+| --- | --- | --- | --- | --- |
+| `@stacknext/cli` | 0.10.0 | public | CLI, collector and dashboard host | `index.md` |
+| `@stacknext/next` | 0.10.0 | public | Next.js instrumentation | `../../next/docs/index.md` |
+| `@stacknext/core` | 0.10.0 | internal | Shared base package | `../../core/docs/index.md` |
+| `@stacknext/diagnostics` | 0.10.0 | internal | Diagnostic engine | `@stacknext/diagnostics/docs/index.md (resolve from CLI)` |
+| `@stacknext/regression` | 0.10.0 | internal | Regression data model | `../../regression/docs/index.md` |
+| `@stacknext/playwright` | 0.10.0 | public | Playwright fixture | `../../playwright/docs/index.md` |
+| `@stacknext/drizzle` | 0.10.0 | public | Database adapter | `../../drizzle/docs/index.md` |
+| `@stacknext/prisma` | 0.10.0 | public | Database adapter | `../../prisma/docs/index.md` |
+| `@stacknext/mcp` | 0.10.0 | internal | Read-only MCP server | `@stacknext/mcp/docs/index.md (resolve from CLI)` |
+| `@stacknext/dashboard` | 0.10.0 | internal | Static dashboard | `@stacknext/dashboard/docs/index.md (resolve from CLI)` |
+
+## How to use this index
+
+Starting from `node_modules/@stacknext/cli/docs/`, read `index.md`. For every
+other package with a relative path, use the table. For example:
+
+```text
+node_modules/@stacknext/cli/docs/index.md
+../../next/docs/index.md   # from node_modules/@stacknext/cli/docs/
+```
+
+Do not assume an internal package is at the app-root `node_modules` path.
+For diagnostics, MCP and dashboard, resolve the package from the installed
+CLI so the docs match its dependency version, including hoisted installs.
+Run this from the project directory:
+
+```js
+const { createRequire } = require('node:module')
+const { dirname, join } = require('node:path')
+const cliRequire = createRequire(require.resolve('@stacknext/cli/package.json'))
+for (const name of ['@stacknext/diagnostics', '@stacknext/mcp', '@stacknext/dashboard']) {
+  console.log(join(dirname(cliRequire.resolve(`${name}/package.json`)), 'docs', 'index.md'))
+}
+```
+
+If resolution fails, the dependency is unavailable. Do not instruct an
+agent to read a missing package directory.
+
+## Public, optional and internal packages
+
+- **Public integration packages** are intended for direct installation when
+  the project uses the corresponding feature.
+- **Internal packages** are installed as dependencies of the CLI or another
+  package. Their docs are for maintainers and advanced contributors.
+- Optional packages (`@stacknext/playwright`, `@stacknext/drizzle` and
+  `@stacknext/prisma`) are only present when explicitly installed.
+
+## Related
+
+- `index.md` — local documentation entry point.
+- `agent-setup.md` — managed AGENTS.md, MCP and skill setup.
+- `commands.md` — CLI reference.

package/docs/skill.md

@@ -0,0 +1,75 @@
+---
+title: Agent Skill
+description: The bundled stacknext-debugging skill, supported clients and installation behavior.
+---
+
+# Agent Skill
+
+`@stacknext/cli` ships the portable Agent Skill at:
+
+```text
+node_modules/@stacknext/cli/skills/stacknext-debugging/
+├── SKILL.md
+└── references/
+    ├── documentation.md
+    ├── setup.md
+    ├── tools.md
+    └── workflows.md
+```
+
+The repository's `skills/stacknext-debugging/` directory is the canonical
+source. It is copied into the CLI archive before packing.
+
+## What it covers
+
+- local documentation discovery and version checks;
+- the twenty read-only MCP tools;
+- evidence-first workflows for errors, slow requests, database activity,
+  diagnostic findings, regression records and snapshots;
+- mandatory reasoning rules: observation versus causation, null durations,
+  overlapping spans, coverage gaps, `inconclusive` comparisons and the
+  difference between a snapshot and live telemetry.
+
+The skill does not duplicate full package API references. It points to the
+installed package docs for those.
+
+## Commands
+
+```bash
+stacknext skill path
+stacknext skill path --json
+stacknext skill install --client opencode
+stacknext skill install --client codex
+stacknext skill install --client claude-code
+stacknext skill install --client codex --dir ./apps/my-app
+stacknext skill install --client codex --force
+```
+
+## Behavior
+
+- `skill path` prints the bundled directory, or `{ path, version }` with
+  `--json`.
+- `skill install` copies the whole directory into the client's project path.
+- An existing destination is not replaced without `--force`; the command exits
+  `1` and reports the path.
+- `--dir` selects the project root; it defaults to the current directory.
+- Unsupported clients throw with the three supported names.
+
+## Version alignment
+
+`SKILL.md` frontmatter contains `metadata.version`, which must equal the
+StackNext package version. The release workflow and package archive validation
+enforce this. The repository skill is updated by the release preparation script
+along with package versions.
+
+## Portable format
+
+`SKILL.md` follows the Agent Skills specification with YAML frontmatter and a
+concise body. Details live in `references/`. Keep it portable: no
+client-specific syntax in the canonical skill and no claim of support without a
+recorded test in `docs/agent-testing.md`.
+
+## Client paths
+
+See [Agent setup](agent-setup.md) for the project paths and the recommended
+installation order.

package/docs/troubleshooting.md

@@ -0,0 +1,84 @@
+---
+title: Troubleshooting
+description: Fix missing telemetry, port conflicts, stale runtime state, MCP and agent setup problems.
+---
+
+# Troubleshooting
+
+## Start with doctor
+
+```bash
+stacknext doctor
+stacknext doctor --json
+```
+
+It checks Node.js, Next.js, the App Router, configuration, instrumentation,
+adapters, dashboard build, runtime file permissions and collector health. It
+exits `1` when a check fails.
+
+## Dashboard is empty
+
+1. Confirm you started the app with `stacknext dev`, not `next dev`.
+2. Make a request after the app is ready.
+3. Run `stacknext status --json` and check `runtime` and `connections`.
+4. Run `stacknext coverage`. `active` means connected but not exercised;
+   `configured` means no app is connected.
+5. Inspect `instrumentation.ts` and the app logs with `STACKNEXT_DEBUG=1`.
+
+## Port already in use
+
+The dashboard prefers 4400 and tries the next 25 ports. Check the URL printed by
+`stacknext dev`. The example app uses 4402 by default. Stop orphaned `next dev`
+processes on ports 4400–4425 before restarting.
+
+## Stale `.stacknext/run.json`
+
+If `stacknext dev` crashes or is killed, `doctor` reports a stale pid. Restart
+`stacknext dev`; it replaces the state. Do not reuse or share the token.
+
+## Stop the server cleanly
+
+Send SIGINT or SIGTERM to `stacknext dev`. It closes the collector, stops the
+app child and removes `.stacknext/run.json`. `SIGKILL` skips cleanup and can
+leave the state file behind.
+
+## MCP client cannot connect
+
+- Start `stacknext dev` before the client starts the server.
+- Run `stacknext mcp` from the app directory, or pass `--collector` and
+  `--token`.
+- Ensure stdout is not mixed with logs. The server writes logs to stderr.
+- Check that the collector URL is loopback. Remote URLs are rejected.
+- Restart the client after changing its MCP configuration.
+
+## `stacknext init --agents` fails
+
+- If `AGENTS.md` contains only one of the two markers, the command refuses to
+  guess and leaves the file unchanged. Restore or remove the partial block.
+- Check file permissions.
+- `--skip-agents` skips the operation; it is the default when `--agents` is not
+  passed.
+
+## Skill installation refuses to overwrite
+
+The destination already exists. Review it, then use `--force` to replace it, or
+choose another project directory with `--dir`.
+
+## Capture exits 3
+
+The test command succeeded but telemetry correlation is incomplete. Inspect
+`stacknext runs show <run-id> --json` and the sample reasons. Do not interpret
+the run as a pass. See
+`node_modules/@stacknext/playwright/docs/troubleshooting.md`.
+
+## Verbose tracing is slower
+
+`NEXT_OTEL_VERBOSE=1` adds spans and dev-server work. Use it for short
+investigations, not permanently. Set `NEXT_OTEL_VERBOSE=0` to override
+`instrumentation.verbose: true`.
+
+## Package versions do not match
+
+Run `stacknext --version` and compare all `@stacknext/*` entries in the lockfile.
+All ten packages are released at one version. Mismatched versions are
+unsupported.