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

# How StackNext works

> The collector, sample, dashboard, diagnostics, snapshots and regression records that make up StackNext.

A Next.js dev server already emits OpenTelemetry spans, but the evidence is
scattered across terminals, framework internals and database logs. StackNext
collects the supported spans, query events and request errors into one bounded
in-memory sample and gives you four ways to read it:

* a dashboard served by the local collector;
* `stacknext` CLI commands for status, coverage, diagnostics, snapshots and
  regression records;
* a read-only MCP server for AI coding agents;
* redacted snapshots and regression records stored under `.stacknext`.

## Data flow

Fig 0.1
Local data flow

Your app

<ul>
  <li>
    Next.js
  </li>

  <li>
    Drizzle
  </li>

  <li>
    Prisma
  </li>
</ul>

plus custom spans and manual action helpers

spans · query events · errors

Instrumentation
redact

@stacknext/nextredacts in the app · sends asynchronously, off the request path

loopback only · bearer token

Collector · one Node process
redact

127.0.0.1:4400validates every envelope · never blocks a request

in-memory sample5,000 spans · 10-minute windowcapacity limits · drop counters

same sample · read-only

Dashboard

requests · traces · queries

CLI + export

coverage · diagnose · snapshot

MCP server

read-only tools · GET only

only on an explicit save

Local records · redacted

snapshots
runs
baselines
comparisons

`.stacknext/` · 0600 files · never uploaded or auto-deleted

`stacknext dev` starts the collector and runs your app's own `dev` script. It
writes the collector URL and a short-lived bearer token to
`.stacknext/run.json` and passes them to the Next.js process. The app sends
telemetry over loopback only.

## What you can answer

| Question | Evidence source |
| - | - |
| Which routes are slow? | Requests, spans, `find_slow_requests` and slow-request findings |
| Did a query pattern repeat? | Query events and the `n-plus-one-queries` rule |
| Is an error repeating? | Error records, fingerprint findings and trace correlation |
| What did this sample actually observe? | Instrumentation coverage |
| Did a covered Playwright flow regress? | A saved baseline and candidate comparison |
| What did the app look like earlier? | A saved, redacted snapshot |

## Local-first by design

Runtime evidence often contains enough information to identify a bug, but
sending it to a hosted service adds an account, a network boundary and a new
privacy decision. StackNext binds the collector to `127.0.0.1`, requires a
bearer token for ingestion, stores telemetry in memory with capacity and
retention limits, and keeps explicit records in redacted local files.

The result is a debugging loop that works offline and never needs an AI API key.
The MCP client you connect may still send tool results to a hosted model; that
is the client's policy, not a StackNext network path.

## What it deliberately does not do

* It does not capture bodies, headers, cookies, URL query values or SQL bind
  parameters.
* It does not support the Edge runtime, production instrumentation or frameworks
  other than Next.js App Router.
* It does not run SQL or `EXPLAIN`, edit source code or recommend indexes from
  telemetry alone.
* It does not treat a heuristic finding as a confirmed root cause or a
  comparison as a statistical test.
* It does not replace an existing OpenTelemetry provider.

Read [core concepts](https://docs.stacknext.space/overview/core-concepts.md), [limitations](https://docs.stacknext.space/limitations.md) and
[privacy](https://docs.stacknext.space/privacy.md) before relying on it.


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