@stacknext/cli 0.9.0 → 0.11.0

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CLI_VERSION = "0.9.0";
+export declare const CLI_VERSION = "0.11.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,UAAU,CAAA"}
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,WAAW,WAAW,CAAA"}

package/dist/version.js

@@ -1,2 +1,2 @@
-export const CLI_VERSION = '0.9.0';
+export const CLI_VERSION = '0.11.0';
 //# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -1 +1 @@
-{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,OAAO,CAAA"}
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,WAAW,GAAG,QAAQ,CAAA"}

package/docs/agent-setup.md

@@ -0,0 +1,120 @@
+---
+title: Agent setup
+description: Install StackNext agent instructions, the Agent Skill and the MCP server.
+---
+
+# Agent setup
+
+StackNext has three complementary agent surfaces. They do not replace one
+another.
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:6cb91359416b90497c8a30b4e48bca6633004719cf0d0075494ac3fd6e33f50a -->
+
+| Surface | Purpose | Command |
+| --- | --- | --- |
+| Local package documentation | Version-matched API reference | Ships in the seven documented packages |
+| Managed `AGENTS.md` block | Short project rules and documentation pointers | `stacknext init --agents` |
+| Agent Skill | Detailed evidence-first workflows | `stacknext skill install` |
+| MCP server | Read-only runtime evidence | `stacknext mcp` |
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## 1. Local documentation
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:5322f074c4bd22377289b52567028ebfbba0bcf2a8678742f28a42cbc3ec8e3c -->
+
+The seven packages listed in `DOCUMENTED_PACKAGES` ship `docs/`:
+`@stacknext/cli`, `@stacknext/next`, `@stacknext/core`,
+`@stacknext/regression`, `@stacknext/playwright`, `@stacknext/drizzle` and
+`@stacknext/prisma`. Start with the CLI package's
+`docs/index.md`; the managed block below records its actual path, which may be
+at the workspace root. The generated [package index](packages.md) lists the
+documented packages and which docs to read.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+No command is needed; the docs are part of the package archive.
+
+## 2. Managed `AGENTS.md` block
+
+```bash
+stacknext init --agents
+```
+
+This adds a marked block to the project's `AGENTS.md`:
+
+```md
+<!-- BEGIN STACKNEXT AGENT RULES -->
+...
+<!-- END STACKNEXT AGENT RULES -->
+```
+
+Safety properties:
+
+- An existing `AGENTS.md` is never overwritten.
+- Content outside the markers is preserved byte-for-byte (line endings are
+  preserved).
+- Re-running updates only the block; it never duplicates it.
+- If only one marker exists, the file is left unchanged and the command fails
+  with a clear error instead of guessing.
+- If no `AGENTS.md` exists, one is created.
+- `--skip-agents` is an explicit opt-out for scripts. Agent setup is off by
+  default.
+
+The block points agents at available package docs and the current StackNext
+version. If no package docs are found, it says so instead of referencing
+nonexistent paths.
+
+## 3. Agent Skill
+
+```bash
+stacknext skill install --client opencode
+stacknext skill install --client codex
+stacknext skill install --client claude-code
+```
+
+| Client | Project path |
+| --- | --- |
+| OpenCode | `.opencode/skills/stacknext-debugging` |
+| Codex | `.agents/skills/stacknext-debugging` |
+| Claude Code | `.claude/skills/stacknext-debugging` |
+
+`stacknext skill path` prints the bundled directory and version. `--force`
+replaces an existing skill copy; without it, an existing destination is left
+untouched and the command exits 1.
+
+## 4. MCP server
+
+```bash
+stacknext dev     # collector must be running
+stacknext mcp     # stdio server
+```
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:95c82a21ffd412dd8a9b62c44104a3f93a3959e02214cd944fb055ce979258e0 -->
+
+Configure the client to start the command from the app directory. See
+[commands](commands.md) for `stacknext mcp` and
+[troubleshooting](troubleshooting.md) for client connection issues.
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+## Recommended order
+
+1. Install and initialize StackNext.
+2. Run `stacknext init --agents` if the project uses `AGENTS.md`.
+3. Install the skill for the client you use.
+4. Configure the MCP server.
+5. Start `stacknext dev` before the agent investigates.
+
+## What StackNext does not do
+
+- It does not modify `CLAUDE.md`, `.cursor/rules`, Copilot instructions or
+  global client configuration.
+- It does not install the skill without an explicit client flag.
+- It does not add MCP configuration automatically to arbitrary clients.

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.11.0 | public | CLI, collector and dashboard host | `index.md` |
+| `@stacknext/next` | 0.11.0 | public | Next.js instrumentation | `../../next/docs/index.md` |
+| `@stacknext/core` | 0.11.0 | internal | Shared base package | `../../core/docs/index.md` |
+| `@stacknext/diagnostics` | 0.11.0 | internal | Diagnostic engine | `@stacknext/diagnostics/docs/index.md (resolve from CLI)` |
+| `@stacknext/regression` | 0.11.0 | internal | Regression data model | `../../regression/docs/index.md` |
+| `@stacknext/playwright` | 0.11.0 | public | Playwright fixture | `../../playwright/docs/index.md` |
+| `@stacknext/drizzle` | 0.11.0 | public | Database adapter | `../../drizzle/docs/index.md` |
+| `@stacknext/prisma` | 0.11.0 | public | Database adapter | `../../prisma/docs/index.md` |
+| `@stacknext/mcp` | 0.11.0 | internal | Read-only MCP server | `@stacknext/mcp/docs/index.md (resolve from CLI)` |
+| `@stacknext/dashboard` | 0.11.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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stacknext/cli",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "description": "Local-first runtime debugging, diagnostics and Playwright regression testing for Next.js",
   "license": "MIT",
   "type": "module",
@@ -9,7 +9,8 @@
   },
   "files": [
     "dist",
-    "skills"
+    "skills",
+    "docs"
   ],
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -22,11 +23,11 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@stacknext/core": "0.9.0",
-    "@stacknext/dashboard": "0.9.0",
-    "@stacknext/diagnostics": "0.9.0",
-    "@stacknext/mcp": "0.9.0",
-    "@stacknext/regression": "0.9.0",
+    "@stacknext/core": "0.11.0",
+    "@stacknext/dashboard": "0.11.0",
+    "@stacknext/diagnostics": "0.11.0",
+    "@stacknext/mcp": "0.11.0",
+    "@stacknext/regression": "0.11.0",
     "commander": "14.0.3",
     "zod": "4.6.7"
   },

package/skills/stacknext-debugging/SKILL.md

@@ -4,7 +4,7 @@ description: Investigate Next.js App Router runtime behavior with StackNext's lo
 license: MIT
 compatibility: Next.js 15 or 16 App Router on the Node.js runtime, with a local StackNext collector. No cloud account, AI API key, or remote service is required.
 metadata:
-  version: "0.9.0"
+  version: "0.11.0"
   author: StackNext
 ---
 
@@ -77,6 +77,24 @@ run SQL or call an AI service.
   route/method plus 30-second fallback. Say "correlated" rather than "caused"
   when the link is fallback-based.
 
+## Documentation sources
+
+The package API reference lives in the installed npm archives, not in this
+skill. Before using an API, configuration key or command that you are not
+certain about:
+
+1. Read the CLI package's `docs/index.md` and `docs/packages.md`. Resolve it from
+   the app directory; in a workspace the CLI may be hoisted to the root.
+2. Read the docs for every package involved in the task.
+3. Confirm the version in the package.json next to those docs. Prefer the local
+   docs over the website or model memory; they match the installed version.
+4. If a documented path does not resolve, that package is not available. Do not
+   reference it or assume its APIs are available.
+
+This skill owns investigation procedure and reasoning rules. Package docs own
+the technical reference. See `references/documentation.md` for discovery,
+version checks and optional-package handling.
+
 ## Tool map
 
 | Goal | Tool |
@@ -304,3 +322,4 @@ as current live telemetry.
 - `references/tools.md` — tool arguments, response shapes and `meta`.
 - `references/workflows.md` — detailed investigation playbooks and report examples.
 - `references/setup.md` — install, MCP configuration, skill locations and troubleshooting.
+- `references/documentation.md` — local package docs, version checks and optional packages.

package/skills/stacknext-debugging/references/documentation.md

@@ -0,0 +1,69 @@
+# Documentation discovery
+
+Package documentation ships inside each installed StackNext npm package. It
+describes the installed version, not the latest website release.
+
+## Read in this order
+
+1. The CLI package's `docs/index.md` — entry point and index. Resolve it from the
+   app directory; in a workspace it may be hoisted to the workspace root.
+2. The CLI package's `docs/packages.md` — package table with versions,
+   visibility, roles and relative paths.
+3. The `docs/index.md` of every package involved in the task.
+
+The paths in `packages.md` are relative to the CLI docs directory. Check that a
+directory exists before reading it. Optional packages (`@stacknext/playwright`,
+`@stacknext/drizzle`, `@stacknext/prisma`) may be absent.
+
+## Confirm the version
+
+Read the package's own `package.json` next to the docs directory, or ask the
+user to run:
+
+```bash
+node -p "require('@stacknext/next/package.json').version"
+```
+
+If the local docs are missing, do not invent API details. Say which package
+version is installed and use only behavior visible in the installed
+implementation or tests. The website at the project repository is a conceptual
+and cross-package reference; it may describe a newer release.
+
+## What each reference owns
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:288ca3f0efa2b410cf1f3bece0fab59bbb1407b61e1f2e543eda24a9230e58d8 -->
+
+<!-- coderabbit-ai-generated:v1 -->
+
+<!-- coderabbit-ai-generated-section:v1:a8fa35dd707530ebdf92d07c80b1058c90cff608b5fd3bf71a1c4876289a1632 -->
+
+| Need | Read |
+| --- | --- |
+| Configuration, wire types, redaction | `@stacknext/core/docs` |
+| Registration, manual spans, actions | `@stacknext/next/docs` |
+| Diagnostic rules and evidence | `@stacknext/diagnostics/docs` (only when the package ships documentation) |
+| Capture, baseline and comparison formats | `@stacknext/regression/docs` |
+| Fixture and correlation | `@stacknext/playwright/docs` |
+| CLI commands and local index | `@stacknext/cli/docs` |
+| MCP tools, prompts and security | `@stacknext/mcp/docs` (only when the package ships documentation) |
+| Query adapters | `@stacknext/drizzle/docs`, `@stacknext/prisma/docs` |
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+<!-- /coderabbit-ai-generated:v1 -->
+
+The skill owns procedures. The package docs own API details. Do not copy large
+API tables into a report; cite the package and page you used.
+
+## If the project has no local docs
+
+Older installations may not include `docs/` in the package archive. Then:
+
+1. Tell the user the installed package lacks local documentation.
+2. Use `stacknext` CLI help and the installed TypeScript declarations.
+3. Do not assume an API exists because the website shows it for another
+   version.
+4. Suggest upgrading the packages, or running `stacknext init --agents` after
+   upgrading to refresh managed project instructions.

package/skills/stacknext-debugging/references/setup.md

@@ -15,9 +15,15 @@ pnpm exec stacknext dev
 `dev` starts the collector and the app's own `dev` script, then writes
 `.stacknext/run.json` with a short-lived bearer token. Leave it running.
 
-If the project is not set up yet, see the repository's
-[docs/getting-started.md](../../../docs/getting-started.md). In a source
-checkout, run `pnpm install && pnpm build` first.
+If the project is not set up yet:
+
+1. Read the CLI package's `docs/index.md` and the Next.js package's
+   `docs/installation.md` for the installed version. Resolve the CLI from the app
+   directory; it may be hoisted to the workspace root.
+2. Run `pnpm exec stacknext init` in the app. Add `--agents` if the user wants a
+   managed StackNext block in `AGENTS.md`.
+3. In a StackNext source checkout, run `pnpm install && pnpm build` first and
+   see `docs/getting-started/quickstart.md`.
 
 Check the collector and instrumentation: