> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stacknext.space/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> StackNext documentation is written for developers using StackNext in a Next.js App Router project. Use the getting-started and guides sections to install and operate the product, and the reference section for CLI, configuration, MCP and package surfaces. Version-matched package API reference ships inside each npm package under node_modules/@stacknext/<package>/docs/ and is preferred over this site for installed-version APIs. Diagnostic findings are evidence, not confirmed root causes; regression comparisons are deterministic and report-only. Contributor and repository-maintenance documentation is not part of this site.

# Quickstart

> Install StackNext, start the collector and inspect your first request.

## 1. Install and initialize

Inside the Next.js app project:

```bash theme={null}
pnpm add @stacknext/next
pnpm add -D @stacknext/cli
pnpm exec stacknext init
```

`init` creates `stacknext.config.json` and an `instrumentation.ts` or
`instrumentation.js` file when they do not exist. It never overwrites an
existing instrumentation file. See [installation](https://docs.stacknext.space/installation.md) for the manual
patch, other package managers and monorepo details.

## 2. Optional: configure your AI coding agent

```bash theme={null}
pnpm exec stacknext init --agents
```

This adds or updates only a marker-delimited StackNext block in `AGENTS.md`.
Existing instructions are preserved. The block points agents at the local
documentation shipped with the installed packages. See
[AI agent setup](https://docs.stacknext.space/ai-agents/setup.md).

## 3. Start the collector and app

```bash theme={null}
pnpm exec stacknext dev
```

`dev` starts the collector, runs the project's `dev` script, and writes
`.stacknext/run.json` with a short-lived bearer token. Open the printed
dashboard URL, usually `http://127.0.0.1:4400`, and make a request to the app.

> [!NOTE]
>
> The collector binds to loopback, so the dashboard is reachable from your machine
> and nowhere else. The in-memory sample stays empty until the app handles a
> request.

## 4. Verify

```bash theme={null}
pnpm exec stacknext status
pnpm exec stacknext doctor
pnpm exec stacknext coverage
```

The Overview page should show requests, and coverage should report what the
sample observed. `not-observed` and `unknown` are valid evidence states, not
errors.

![StackNext Overview after a first request: request and error counts, p95 latency, recent request latency and diagnostic findings](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/overview.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=15920e8525b5548861d5772ebb134e45)

![StackNext Overview after a first request: request and error counts, p95 latency, recent request latency and diagnostic findings](https://mintcdn.com/stack-next/wvbZ0Zo0GO0UM1X7/screenshots/overview-dark.png?fit=max\&auto=format\&n=wvbZ0Zo0GO0UM1X7\&q=85\&s=7c9e25092218332ce093a2cfffcb3f03)

## 5. Inspect the sample

* **Requests** and **Traces** show route, status, duration and span timelines.
* **Database** shows query events; Drizzle durations are `null`.
* **Errors** shows redacted errors and any correlated trace.
* **Diagnostics** shows deterministic findings. Read the evidence and
  limitations before changing code.
* **Snapshots** lets you freeze the current sample.
* **Runs**, **Baselines** and **Comparisons** hold Playwright-linked regression
  evidence.

CLI equivalents:

```bash theme={null}
pnpm exec stacknext diagnose
pnpm exec stacknext export --stdout
pnpm exec stacknext snapshot save --label "first look"
```

## Next steps

* [Investigate runtime evidence](https://docs.stacknext.space/guides/runtime-evidence.md).
* [Understand diagnostic findings](https://docs.stacknext.space/guides/diagnostics.md).
* [Add custom spans](https://docs.stacknext.space/custom-instrumentation.md).
* [Run a Playwright regression comparison](https://docs.stacknext.space/regression-testing.md).
* [Read the installed package docs](https://docs.stacknext.space/ai-agents/local-docs.md) for exact APIs.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.