@progen-labs/spectra 0.5.0 → 0.7.0

package/CHANGELOG.md

@@ -0,0 +1,94 @@
+# Changelog
+
+Every release of Spectra, newest first. Versions follow [semantic versioning](https://semver.org); while Spectra is 0.x, a minor version can change behaviour. The same changelog is on the [website](https://progen-labs.github.io/website/#spectra/docs/changelog).
+
+Update an existing install with `npm install --save-dev @progen-labs/spectra@latest`, and check yours with `npx spectra --version`.
+
+## 0.7.0 (25 October 2026)
+
+**Ask your AI agent to "improve the performance", and Spectra does the rest.** Spectra's main command is now `spectra improve`: it measures the app, finds the problems in your own code, has each one fixed, measures the change, and keeps only what measurably helped. Everything else Spectra can do is still there, behind it.
+
+- **`spectra improve`**, two ways with the same rules. **Guided**: `npx spectra improve next` measures and names the first problem (file, line, cost, suggested fix); the AI agent you are talking to, or you, makes that one change; `npx spectra improve check` runs your checks, measures again and says keep or undo, then names the next problem; `npx spectra improve report` sums it up. Any agent can drive it, with no extra tools. **Unattended**: `npx spectra improve` finds a coding agent on your machine (Claude Code, Codex, Gemini CLI, Copilot CLI, Cursor, OpenCode or Amp; `--agent` to choose) and does the whole loop in a copy of your last commit, with the kept fixes as commits on `spectra/improve-<time>`. `spectra fix` stays as the old name. Sessions live in `.spectra/improve/`. See [Improve the performance](https://progen-labs.github.io/website/#spectra/docs/improve).
+- **The MCP server** has the same loop as tools: `improve_next`, `improve_check` and `improve_report`, next to the six it had. The Claude Code plugin's *improve-performance* skill uses them.
+- **Your agent knows the loop.** The knowledge doc Spectra writes for AI agents, and `npx spectra` with no command, now lead with it.
+- **A fairer keep rule.** A change is undone for a new critical finding only when the finding is in your own code: a vendor chunk the dev server renamed between measurements no longer undoes a good fix. In `spectra compare`, a chunk keeps its identity across content hashes and query strings (`react-dom-hmN8LOy-.js?v=1` and `react-dom-Zq1x_9ab.js?v=2` are the same resource).
+- **Docs for the simple path first.** The README and the website lead with install, ask, review; the command reference, budgets, CI, MCP, the dashboard and the rest follow.
+
+## 0.6.1 (22 October 2026)
+
+- **Node.js 22.12 or newer.** Spectra's Chrome driver, puppeteer-core, needs it, so `engines` in `package.json` now says so instead of Node 18, and every release is installed and run on it in CI. Node 20 reached its end of life in April 2026.
+- **No install script.** Spectra's knowledge doc for AI agents is now written the first time Spectra runs in your project, instead of during `npm install`, so package managers and supply-chain scanners such as Socket have no install script to flag. It works the same with npm, pnpm, Yarn and Bun, once per version, and never comes back after `npx spectra agents --remove`. See [Any AI agent](https://progen-labs.github.io/website/#spectra/docs/agents).
+- **A sign-in click that goes nowhere is retried.** On a busy page or a slow machine, the click on the sign-in button can be lost. When the form sent nothing at all, Spectra now presses Enter in the last field once, and if the form still sent nothing, the error says so and asks for the button's selector. See [Signing in](https://progen-labs.github.io/website/#spectra/docs/signing-in).
+- **A change as big as the noise is noise.** A comparison now counts a change only when it is bigger than the spread between runs, as the docs always said. Before, a change exactly equal to it counted, so one long task in two of three runs could mark a change slower in `spectra compare`, the GitHub Action and `spectra fix`.
+- **zod 4.6.7** in the lockfile (through puppeteer-core), for a high-severity advisory in 4.6.5. A fresh install already gets the fixed version.
+
+## 0.6.0 (22 October 2026)
+
+**Your AI agent knows Spectra.** Installing Spectra now teaches your coding agent what it does: which command answers which request, how to read the results, how to prove a change made things faster, and the rules to follow. So you can ask in plain words ("why is checkout slow?", "did my change help?") and the agent runs Spectra for you. The knowledge doc goes into `AGENTS.md` (Codex, GitHub Copilot's coding agent, Cursor, Windsurf, Zed and others) and, for the agents your project or machine uses, a Claude Code skill, GitHub Copilot instructions, a Cursor rule, and Windsurf, Cline, Roo Code and Gemini CLI files. Your own text is never touched. `npx spectra agents` does it by hand (pnpm and Bun skip install steps until you allow them), and `--remove` takes it out. See [Any AI agent](https://progen-labs.github.io/website/#spectra/docs/agents).
+
+## 0.5.0 (22 October 2026)
+
+Spectra signs in, and every label names your framework.
+
+- **Signing in, every kind of login.** Most production frontends sit behind a login; now Spectra signs in before it profiles. A **login form** (one or two steps, forms that render late, in iframes or web components, behind a **Sign in** button, on your identity provider), with **authenticator codes** from a TOTP secret; **signing in yourself** in the Chrome window for SMS or email codes, passkeys and CAPTCHAs; the **browser's login prompt** (HTTP Basic or Digest); a **token, cookie or localStorage entry**; or a **sign-in link**. In the dashboard, turn on **My app needs a sign-in**; on the command line use `--login-url` and `--login-user` with `SPECTRA_LOGIN_PASSWORD`, or put the non-secret parts in `spectra.config.json` for every tool. Secrets stay in memory, are never written to disk, a report or a log, and the config file refuses them. See [Signing in](https://progen-labs.github.io/website/#spectra/docs/signing-in).
+- **Framework-agnostic labels.** The dashboard, findings, comparisons and PDFs say **Components**, **Component render time** and the framework the page runs (React, Vue or Angular), instead of "React" everywhere.
+- **The framework is detected in the page.** The probe is ready for React, Vue and Angular on every page, so an Angular or Vue app is profiled as itself even when Spectra starts from another folder, a monorepo root or an editor. Before, it took the framework from the `package.json` where Spectra started and fell back to React.
+- **Page map for every app.** The page screenshot is now always taken, and Vue and Angular components are pinned on it, not only React ones.
+- **Fixed**: a plain JavaScript page no longer gets a "No React renderer was seen" finding, and the dashboard's pill says **No component framework seen** without looking like an error.
+
+## 0.4.1 (17 October 2026)
+
+- **`spectra fix` skips findings that are already fixed.** One fix often clears several findings. After each kept fix, a finding the new measurement no longer shows is listed as skipped ("already resolved by an earlier kept change") instead of being handed to the agent, which saves its time and cost. Found by the first [real-agent bench run](https://progen-labs.github.io/website/#spectra/docs/harness-bench), where one of three attempts went to a finding the first fix had cleared.
+
+## 0.4.0 (17 October 2026)
+
+The [AI fix harness](https://progen-labs.github.io/website/#spectra/docs/harness). `spectra fix` hands the costliest findings in your own code to a coding agent (Claude Code by default, or any command), one at a time, in a git worktree of your last commit. A change is kept as a commit on a new branch only when it stays within scope, your checks pass (they can test the running app at `$SPECTRA_FIX_URL`) and Spectra measures it faster beyond run-to-run noise; otherwise it is undone. Each session leaves a Markdown report and a history, so failed findings aren't retried. A [test bench](https://progen-labs.github.io/website/#spectra/docs/harness-bench) checks the harness's decisions in CI. See [spectra fix](https://progen-labs.github.io/website/#spectra/docs/cli-fix) and [Checks and safety](https://progen-labs.github.io/website/#spectra/docs/harness-safety).
+
+## GitHub Action v1 (17 October 2026)
+
+`uses: progen-labs/spectra@v1` profiles each pull request and its base commit on the same runner, compares them, enforces budgets, and reports in the job summary and an optional pull request comment. See [GitHub Action](https://progen-labs.github.io/website/#spectra/docs/github-action).
+
+## VS Code extension 0.1.0 (17 October 2026)
+
+The first release of the [VS Code extension](https://progen-labs.github.io/website/#spectra/docs/vscode), on the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=progen-labs.spectra-performance) as `progen-labs.spectra-performance`: findings in the Problems panel at the exact line, CodeLens above costly components and functions, headline numbers in the status bar, verify against a baseline, golden paths, the dashboard in the editor, results shared with the CLI and AI assistants, and Spectra's MCP server offered to agent mode.
+
+## 0.3.0 (17 October 2026)
+
+Spectra works inside your AI assistant.
+
+- **`spectra mcp`**: Spectra as an MCP server, with `profile_page`, `verify_change`, `compare_profiles`, `run_golden_paths`, `list_reports` and `get_report`. Local pages only by default; one browser at a time; progress notifications and cancellation. See [MCP server](https://progen-labs.github.io/website/#spectra/docs/mcp-server).
+- **Claude Code plugin**: `/plugin marketplace add progen-labs/spectra`, then `/plugin install spectra@progen-labs`. Claude fixes performance problems one at a time and keeps a change only when Spectra measures an improvement; `/spectra:audit` reports without editing. See [Claude Code plugin](https://progen-labs.github.io/website/#spectra/docs/claude-code).
+- **Cleaner stops**: stopping or cancelling a run now also closes Chrome and stops the dev server Spectra started.
+
+## 0.2.0 (17 October 2026)
+
+Faster loops, honest comparisons and machine-readable output. Everything is additive: existing commands and options behave as before.
+
+- **`--quick`**: a single page-load profile, the fast loop. See [Quick and repeated profiles](https://progen-labs.github.io/website/#spectra/docs/quick-profiles).
+- **`--runs N`**: record several times and report medians, the spread and how many runs saw each finding.
+- **`spectra compare`**: noise-aware before and after, from `--out` result files, report ids or report files. `--fail-on-regression` exits with code 2. See [Compare](https://progen-labs.github.io/website/#spectra/docs/compare).
+- **`spectra reports`**: list saved reports. See [spectra reports](https://progen-labs.github.io/website/#spectra/docs/reports).
+- **Budgets** in `spectra.config.json`, checked on every run, with exit codes for CI. See [Budgets and CI](https://progen-labs.github.io/website/#spectra/docs/budgets).
+- **`--json` and `--out`**: a versioned result with published JSON Schemas. Saved reports carry a `schemaVersion`. See [JSON output](https://progen-labs.github.io/website/#spectra/docs/json-output).
+- **A lighter install**: 29 packages and 33 MB instead of 73 packages and 54 MB, because the dashboard ships prebuilt.
+- **Fixed**: relative `--scenario` paths now resolve against your directory. Zero times read "0 ms", and a single run's summary line no longer prints "nullms".
+- **Dashboard fixes**: on laptop-sized windows the report tabs wrap instead of hiding **Compare commits** off the edge, and the Long tasks cards keep file names, functions and times inside the card.
+
+## 0.1.3 (11 October 2026)
+
+- **Angular**: per-component change-detection counts and self time from Angular's development-mode profiler.
+
+## 0.1.2 (11 October 2026)
+
+- Fixed every reported dependency vulnerability.
+
+## 0.1.1 (11 October 2026)
+
+- **Vue**: deep component support through Vue's DevTools hook.
+- **Next.js**: profiled through React.
+
+## 0.1.0 (11 October 2026)
+
+- First release on npm as `@progen-labs/spectra`.
+- `spectra performance`: self-boots your dev server, discovers actionable elements and runs the safe [golden-path suite](https://progen-labs.github.io/website/#spectra/docs/golden-paths).
+- `spectra dashboard`: the full dashboard with no build step, including PDF export and commit comparison.

package/README.md

@@ -1,335 +1,216 @@
-# @progen-labs/spectra
+<h1 align="center">Spectra</h1>
 
-**Find out which file, which function and which component makes your frontend slow — automatically.**
+<p align="center">
+  <b>Make your web app faster. Ask your AI agent, or run one command.</b>
+  <br>
+  <sub>React · Next.js · Vue · Angular · Svelte · any web frontend &nbsp;|&nbsp; Claude Code · Cursor · Copilot · Codex · Gemini · VS Code · CI</sub>
+</p>
 
-Spectra is a CLI and dashboard that profiles a frontend build through the Chrome DevTools Protocol
-(tracing + CPU sampling) plus a small in-page probe for component re-renders and Web Vitals. Run one
-command and it starts your dev server, auto-discovers the actionable elements on the page, drives a set
-of **golden-path journeys**, records each one, and reports a ranked list of culprits — each with the
-exact function, file and line, the evidence, and a suggested fix.
+<p align="center">
+  <a href="https://www.npmjs.com/package/@progen-labs/spectra"><img alt="npm version" src="https://img.shields.io/npm/v/@progen-labs/spectra?style=flat-square&color=0a84ff&label=npm"></a>
+  <a href="https://github.com/progen-labs/spectra/actions/workflows/checks.yml"><img alt="tests" src="https://img.shields.io/github/check-runs/progen-labs/spectra/main?nameFilter=Tests%20%28Node%2022%2C%20ubuntu-latest%29&style=flat-square&label=tests"></a>
+  <a href="https://www.npmjs.com/package/@progen-labs/spectra"><img alt="Downloads" src="https://img.shields.io/npm/dm/@progen-labs/spectra?style=flat-square&color=0a84ff"></a>
+  <a href="LICENSE"><img alt="MIT license" src="https://img.shields.io/npm/l/@progen-labs/spectra?style=flat-square&color=0a84ff"></a>
+</p>
 
-Deep component-level attribution for **React, Next.js, Vue and Angular** (component names, render counts
-and per-component render/change-detection time; source files too, where the framework exposes them). For
-**Svelte and any other build**, a source-mapped generic profile still pinpoints the slow files and
-functions. The framework is detected in the page itself, so it is right wherever you start Spectra from.
-Apps behind a login work too: Spectra [signs in first](#behind-a-login), with every kind of login. A
-[Progen Labs](https://github.com/progen-labs) project — independent, open source, no telemetry, no account
-required.
+<p align="center">
+  <a href="https://progen-labs.github.io/website/#spectra/docs/improve"><b>Documentation</b></a>
+  &nbsp;·&nbsp;
+  <a href="https://progen-labs.github.io/website/#spectra/demo"><b>2½-minute demo</b></a>
+  &nbsp;·&nbsp;
+  <a href="#get-started">Get started</a>
+  &nbsp;·&nbsp;
+  <a href="#measure-without-changing-anything">Measure only</a>
+  &nbsp;·&nbsp;
+  <a href="#project-health">Project health</a>
+</p>
 
-**Watch the demo (2½ minutes):** [progen-labs.github.io/website/#spectra/demo](https://progen-labs.github.io/website/#spectra/demo).
+Spectra runs your app in Chrome, measures it, and finds the problems in **your own code**: the exact file, function,
+line and component, with a suggested fix. Then it has each problem fixed, measures the change, and keeps only what
+measurably helped. It works with the AI coding agent you already use, or on its own. Everything runs on your
+machine: no account, no telemetry, no uploads. A [Progen Labs](https://github.com/progen-labs) project, free and
+open source.
 
-**Documentation:** the full guide, with annotated screenshots of every screen, is at
-[progen-labs.github.io/website](https://progen-labs.github.io/website/#spectra/docs/introduction).
+## Get started
 
-## Install
+**1. Install.** Node.js 22.12 or newer and a local Chrome, Chromium or Edge (Spectra drives the browser you have).
 
 ```bash
 npm install --save-dev @progen-labs/spectra
+npx spectra
 ```
 
-Requirements: **Node 18+** and a local **Chrome / Chromium / Edge** (Spectra drives your installed
-browser; it does not download one). If it can't find Chrome, set `CHROME_PATH` to the executable.
-
-## Quick start
-
-From the root of your project:
+`npx spectra` sets things up: it teaches your AI coding agent what Spectra does, in the file the agent reads for
+your project (`AGENTS.md`, a Claude Code skill, Copilot instructions, a Cursor rule…). Nothing happens at install time.
 
-```bash
-npx spectra performance
-```
-
-With no `--url`, Spectra:
+**2. Ask your agent.** In Claude Code, Cursor, GitHub Copilot, Codex, Gemini CLI, Windsurf or any other coding agent,
+in plain words:
 
-1. detects your framework and starts your dev server (`npm run dev`/`start`/`serve`),
-2. records a baseline page load,
-3. auto-discovers the actionable elements (links, buttons, inputs, forms),
-4. synthesizes and runs **golden-path journeys** — safely (see below),
-5. prints a performance matrix and saves a report per journey, then stops the server.
+> improve the performance
 
-```
-#  Golden path            Result    TBT    LCP  LongT  Top finding
-—  Initial page load      PASS      0ms  128ms      0  [warning] main chunk served uncompressed
-1  Click "Pricing"        PASS      0ms      —      0  [warning] Large DOM: 2,139 nodes
-2  Click "Folders"        PASS      0ms      —      0  [critical] TreeNode re-rendered 1100× (96% wasted)
-...
-Automation: 8/8 golden paths passed.
-```
+The agent runs Spectra's loop. Spectra measures the app and names the first problem: file, line, cost, suggested fix.
+The agent makes that one change. Spectra runs your checks, measures again, and says **keep** or **undo**. Repeat.
+Then the agent tells you what got faster, with the before → after numbers, and what it tried that didn't help.
 
-Then open the visual dashboard — ranked culprits, component re-renders, long tasks, the golden-path matrix,
-**PDF export** and **commit-to-commit compare**:
+Or let Spectra do the whole thing unattended, with a coding agent installed on your machine:
 
 ```bash
-npx spectra dashboard --open
-```
-
-![The Spectra dashboard: the top culprit of a recording, burn() in src/heavy.js, with its time and a suggested fix](docs/dashboard.webp)
-
-A [tour of the dashboard](https://progen-labs.github.io/website/#spectra/docs/dashboard), with every part
-labelled, is in the docs.
-
-## Commands
-
-```
-spectra performance [options]            Golden-path evaluation (default)
-spectra performance --quick              One page-load profile (about 15 s)
-spectra compare <before> <after>         Did it get faster? Noise-aware before/after
-spectra reports                          List saved reports
-spectra mcp [--project <dir>]            MCP server for AI tools (stdio)
-spectra dashboard [--port N] [--open]    Open the dashboard UI
-spectra --help                           Full option list
-spectra --version
+npx spectra improve
 ```
 
-**`performance` options**
+It finds the agent (Claude Code, Codex, Gemini CLI, Copilot CLI, Cursor, OpenCode or Amp; `--agent` to choose),
+works in a copy of your last commit, and puts the kept fixes on a branch, one commit each, with the measurements in
+the commit messages. Your own files are never touched.
 
-| Option | Description |
-| --- | --- |
-| `--url <page>` | Evaluate an already-running page; skips self-boot |
-| `--paths <n>` | Max golden paths to run (default 12) |
-| `--command "<cmd>"` | Override the dev-server command |
-| `--boot-timeout <s>` | How long to wait for the dev server (default 60) |
-| `--headed` | Show the browser window |
-| `--login-url <url>`, `--login-user <name>` | Sign in first: the login page and the username; the password comes from `SPECTRA_LOGIN_PASSWORD` (see [Behind a login](#behind-a-login)) |
-| `--login <method>` | `form`, `link`, `http`, `token` or `manual` (you sign in in the Chrome window); guessed when left out |
-| `--quick` | One page-load profile instead of the golden-path suite: the fast loop |
-| `--runs <n>` | Record n times and report the median (with `--quick` or `--mode`) |
-| `--mode live\|load` | Classic single-page profile instead of the golden-path suite |
-| `--json` | Print a machine-readable result on stdout (tables go to stderr) |
-| `--out <file>` | Also write that result to a file (an input for `compare`) |
-| `--config <file>` | Budgets and sign-in file (default: `spectra.config.json` in your project) |
-
-## Behind a login
-
-Most production frontends sit behind a login, and the Chrome Spectra launches starts signed out. Tell
-Spectra how your app signs in and it signs in before it records, so the login never shows up in a
-measurement:
-
-| Method | For |
-| --- | --- |
-| **Login form** (`form`) | A username and password on your app's login page or its identity provider (OAuth, OpenID Connect, SAML): one or two steps, forms that render late, in iframes or web components, behind a "Sign in" button, with **authenticator codes** from a TOTP secret |
-| **I'll sign in myself** (`manual`) | SMS or email codes, push approvals, passkeys, CAPTCHAs: Chrome opens on the login page and Spectra waits for you |
-| **Browser prompt** (`http`) | HTTP Basic or Digest, common on staging servers |
-| **Token or cookie** (`token`) | A header (sent only to your app's origin), cookies or localStorage entries |
-| **Sign-in link** (`link`) | A URL that signs in by itself, such as a dev-only auto-login |
-
-In the dashboard, turn on **My app needs a sign-in** under **Page to profile**. On the command line:
+**3. Review.** The changes are in your working tree (`git diff`) or on the branch (`git log -p HEAD..spectra/improve-…`).
+Commit, or merge, and you're done.
 
-```bash
-SPECTRA_LOGIN_PASSWORD="$TEST_PASSWORD" npx spectra performance --login-url http://localhost:3000/login --login-user demo@example.com
-npx spectra performance --login manual --login-url https://staging.example.com/login
-```
+## What a session looks like
 
-Or once, for every command, the VS Code extension, the MCP server and `spectra fix`, in `spectra.config.json`:
+The guided loop on Spectra's React demo app. Each step is one short command, so any agent can drive it:
 
-```json
-{ "signIn": { "method": "form", "url": "http://localhost:3000/login", "username": "demo@example.com" } }
 ```
+$ npx spectra improve next
+spectra: measuring the baseline (3 page loads) …
+Problem 1 of 5: Row is slow to render: 1442ms total, 0.2ms per render (7200×)
+  Where: src/Row.jsx:3
+  Cost: about 1.44 s, seen in 3 runs
+  Where the time went:
+    Row() in src/Row.jsx:3: 1.44 s (slow render)
+  Suggested fix: Move expensive calculations into useMemo, virtualise long lists, …
 
-Secrets come only from the dashboard or the environment (`SPECTRA_LOGIN_PASSWORD`, `SPECTRA_LOGIN_TOTP_SECRET`,
-`SPECTRA_LOGIN_HEADER`, `SPECTRA_LOGIN_COOKIES`, `SPECTRA_LOGIN_STORAGE`). They stay in memory: never written
-to disk, a report, a log or an error message, and `spectra.config.json` refuses them. Spectra never solves
-CAPTCHAs. Use a test account where you can. See
-[Signing in](https://progen-labs.github.io/website/#spectra/docs/signing-in), with a short video.
+Make ONE focused change in src/Row.jsx that removes or reduces this cost, keeping the behaviour exactly the same …
+Then run:  npx spectra improve check
 
-## Measure, change, verify
+$ npx spectra improve check            # after the agent's change
+spectra: running the checks (npm test) …
+spectra: measuring the change …
+✓ Kept: JavaScript CPU time: 1.55 s → 162 ms (−90%)
+  also Row (src/Row.jsx) — render time: 1.44 s → 35.4 ms (−98%)
+  Checks passed: npm test.
+  Keep this change.
 
-Performance numbers are noisy, so Spectra never trusts a single recording when you ask it whether a change
-helped. Record a few runs before and after, then compare:
+Problem 2 of 4: App rendered 60× (19/s)
+  Where: src/main.jsx:15
+  …
 
-```bash
-npx spectra performance --quick --runs 5 --out before.json
-# …make your change…
-npx spectra performance --quick --runs 5 --out after.json
-npx spectra compare before.json after.json
-```
+$ npx spectra improve check            # after a change that did nothing
+✗ Undo this change: no measurable improvement: every change was within run-to-run noise.
+  Revert the files you changed for this problem (and only those), then continue.
 
+$ npx spectra improve report
+Spectra improve — 1 of 2 problems fixed
+  ✓ fixed       Row is slow to render … (src/Row.jsx:3): JavaScript CPU time: 1.55 s → 162 ms (−90%)
+  ✗ undone      App rendered 60× (19/s) (src/main.jsx:15) — no measurable improvement
+Overall, before → after: IMPROVED (confidence: medium)
+  ✓ JavaScript CPU time: 1.55 s → 162 ms (−90%)
+  ✓ Row (src/Row.jsx) — render time: 1.44 s → 35.4 ms (−98%)
 ```
-Spectra compare — IMPROVED (confidence: medium)
-  ✓ JavaScript CPU time: 1.52 s → 92.1 ms (−94%)
-  ✓ Row (src/Row.jsx) — render time: 1.44 s → 7.4 ms (−99%)
 
-Findings: 3 resolved · 2 new · 10 still present
-  resolved  [critical] Row is slow to render: 1444ms total, 0.2ms per render (7200×)
-```
+## How it decides
 
-Each side is reduced to its median, and a difference only counts when it is larger than the run-to-run
-spread. A side can be a `--out` result file, a report id from `spectra reports`, a report file, or several
-ids joined by commas.
+Spectra makes every decision; the agent only edits.
 
-## Budgets and CI
+- **Measured, not guessed.** Three page loads before and after each change, reduced to medians. A change counts
+  only when it is bigger than the run-to-run noise, so a lucky run never decides.
+- **Your checks first.** Your `test`, type-check and `build` scripts (or `--check "<cmd>"`) must pass after every
+  change. A faster page that breaks is undone.
+- **Your code only.** Problems in `node_modules` are reported, not fixed. A new critical problem in your own code
+  undoes a change; a vendor chunk renamed between builds does not.
+- **One change at a time, in order of cost.** A fix that also clears other problems skips them.
+- **Unattended, in isolation.** A git worktree of your last commit with its own dev server; changes to
+  `package.json`, lockfiles, configuration, tests or CI, deletions, or more than 150 lines are refused; nothing is
+  pushed or merged.
 
-Put limits in `spectra.config.json` at your project root:
+The rules are Spectra's code, checked by a [test bench](https://progen-labs.github.io/website/#spectra/docs/harness-bench)
+in CI: a real fix must be kept, a "faster" page that renders nothing must be caught, a cosmetic change must not count.
+See [How improve decides](https://progen-labs.github.io/website/#spectra/docs/harness).
 
-```json
-{
-  "$schema": "./node_modules/@progen-labs/spectra/schema/config.schema.json",
-  "budgets": { "tbtMs": 200, "lcpMs": 2500, "cls": 0.1, "criticalFindings": 0 }
-}
-```
+## What it works with
 
-Every `spectra performance` run checks them: the median for `--quick`/`--mode`, every journey for the
-golden-path suite. Metrics a recording did not measure are skipped, never failed. Available budgets:
-`tbtMs`, `lcpMs`, `fcpMs`, `cls`, `inpMs`, `ttfbMs`, `longTaskCount`, `maxLongTaskMs`, `scriptingMs`,
-`forcedLayoutCount`, `domNodes`, `heapUsedMb`, `transferKb`, `criticalFindings`, `findingCount`.
-
-Exit codes make it a CI gate:
-
-| Code | Meaning |
+| | |
 | --- | --- |
-| `0` | Done, and within budget |
-| `1` | Could not run (no Chrome, server down, bad config) |
-| `2` | Ran, but a budget was exceeded, or `compare --fail-on-regression` found a regression |
-
-### GitHub Action
-
-The repository is also a GitHub Action. On every pull request it profiles the change and its base commit on the
-same runner, compares them beyond run-to-run noise, enforces your budgets, and writes the result to the job summary
-and (optionally) a PR comment:
-
-```yaml
-name: Performance
-on: pull_request
-permissions:
-  contents: read
-  pull-requests: write   # only for comment: true
-jobs:
-  spectra:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v4
-      - uses: actions/setup-node@v4
-        with: { node-version: 22 }
-      - run: npm ci
-      - uses: progen-labs/spectra@v1
-        with:
-          compare-to-base: true
-          fail-on-regression: true
-          comment: true
-```
-
-Inputs include `url`, `command`, `mode` (`quick` or `golden-paths`), `runs`, `config`, `fail-on-budget` and
-`working-directory`; outputs are `result-file`, `verdict`, `over-budget` and `summary-file`. Full reports are
-uploaded as an artifact. See the [Action guide](https://progen-labs.github.io/website/#spectra/docs/github-action).
-
-## Machine-readable output
-
-`--json` prints a small, versioned result on stdout and sends every human-readable line to stderr, so it can
-be piped into `jq`, an editor or an AI agent. Each result has `schemaVersion` and a `kind` (`profile`,
-`evaluation`, `compare` or `reports`) and points at the full reports on disk rather than embedding them.
-Findings carry the file, line, cost in ms and a suggested fix. The format is described by a JSON Schema
-shipped with the package (`schema/result.schema.json`); additive changes keep `schemaVersion`, breaking
-changes bump it. Saved reports carry their own `schemaVersion` too.
-
-## Use it from your AI assistant
-
-Spectra is an [MCP](https://modelcontextprotocol.io) server too, so an AI coding assistant can profile a page,
-fix what it finds, and prove each fix with before/after measurements.
-
-**Claude Code**, with the plugin (adds an *improve-performance* skill and `/spectra:audit`):
+| **Frameworks** | Component names, render counts and timings for **React, Next.js, Vue and Angular**; source-mapped files and functions for **Svelte, SolidJS and any other build**. Detected in the page itself. |
+| **AI agents** | Any agent that reads `AGENTS.md` (Codex, Copilot's coding agent, Cursor, Windsurf, Zed, Jules, Amp…), plus Claude Code (a skill), GitHub Copilot (instructions), Cursor, Windsurf, Cline, Roo Code and Gemini CLI, each in its own file. MCP clients get the loop as tools (`improve_next`, `improve_check`, `improve_report`); there is a [Claude Code plugin](https://progen-labs.github.io/website/#spectra/docs/claude-code). |
+| **Unattended** | Claude Code, Codex CLI, Gemini CLI, GitHub Copilot CLI, Cursor CLI, OpenCode, Amp, or any command of yours. |
+| **Editors** | The [VS Code extension](https://marketplace.visualstudio.com/items?itemName=progen-labs.spectra-performance) shows each finding at its line and render counts above components. |
+| **CI** | The [GitHub Action](https://progen-labs.github.io/website/#spectra/docs/github-action) profiles every pull request against its base commit and enforces your budgets. |
+| **Apps behind a login** | Spectra [signs in first](https://progen-labs.github.io/website/#spectra/docs/signing-in): a login form (one or two steps, single sign-on, authenticator codes), you in the browser window, the browser prompt, a token or cookie, or a sign-in link. Secrets stay in memory. |
 
-```
-/plugin marketplace add progen-labs/spectra
-/plugin install spectra@progen-labs
-```
-
-**Any MCP client** (Claude Code without the plugin, Claude Desktop, Cursor, VS Code, Windsurf…): run
-`npx -y @progen-labs/spectra mcp` as a stdio server (Spectra 0.3.0 or later). For example:
+## Measure without changing anything
 
 ```bash
-claude mcp add spectra -- npx -y @progen-labs/spectra mcp
+npx spectra performance                  # starts your dev server, finds the page's buttons, links and
+                                         # forms, runs safe user journeys through them, reports each one
+npx spectra performance --quick --runs 3 # one page, three loads, medians: the fast loop
+npx spectra dashboard --open             # the visual dashboard: culprits, page map, call trees, PDFs
 ```
 
-```json
-{ "mcpServers": { "spectra": { "command": "npx", "args": ["-y", "@progen-labs/spectra", "mcp", "--project", "/path/to/your/app"] } } }
 ```
-
-Tools: `profile_page`, `verify_change` (re-profile and compare against a baseline), `compare_profiles`,
-`run_golden_paths`, `list_reports` and `get_report`. The server profiles pages on this machine only (start it with
-`--allow-remote` to lift that), runs one browser at a time, and stops Chrome and any dev server it started when a
-call is cancelled. See the [MCP guide](https://progen-labs.github.io/website/#spectra/docs/mcp-server).
-
-## The AI fix harness
-
-`spectra fix` hands the costliest findings in your own code to a coding agent, one at a time, and keeps a change only
-when your checks still pass and Spectra measures the page faster beyond run-to-run noise. Kept changes arrive as
-commits on a new branch, `spectra/fix-<time>`, for you to review; everything else is undone.
-
-```bash
-npx spectra fix                       # Claude Code (signed in) fixes up to 3 findings
-npx spectra fix --check "npm run e2e" --max-fixes 5
-npx spectra fix --agent "./my-agent.sh"   # any agent: instructions on stdin
+#  Golden path            Result    TBT    LCP  LongT  Top finding
+—  Initial page load      PASS      0ms  128ms      0  [warning] main chunk served uncompressed
+1  Click "Pricing"        PASS      0ms      —      0  [warning] Large DOM: 2,139 nodes
+2  Click "Folders"        PASS      0ms      —      0  [critical] TreeNode re-rendered 1100× (96% wasted)
+Automation: 8/8 golden paths passed.
 ```
 
-The harness, not the agent, makes every decision:
-
-- **Isolation.** It works in a git worktree of your last commit, with its own dev server. Your working tree is never
-  touched, and nothing is pushed or merged.
-- **Your checks first.** Your test, type-check and build scripts (or `--check`, which can test the running app at
-  `$SPECTRA_FIX_URL`) must pass before any change and after each one. A faster page that breaks is undone.
-- **Scope rules.** A change may not touch `package.json`, lockfiles, configuration, tests or CI, delete files, or
-  exceed 150 lines.
-- **Proof.** The change is kept only if `spectra compare` says *improved* with medium or high confidence and no new
-  critical finding; with low confidence it measures again.
-- **A record.** Each kept commit carries its evidence; `.spectra/fix/<time>/report.md` summarises the session, and a
-  history skips findings that failed before. A finding that an earlier kept fix already cleared is skipped too.
-
-By default the agent is Claude Code in headless mode, allowed only to read and edit files (no shell, no web, no MCP),
-with a spending cap per finding. A test bench (`npm run bench`) checks the harness's decisions in CI: a real fix is
-kept, a "faster" change that breaks the page is caught, a cosmetic change doesn't count, and an edit to
-`package.json` is refused. With Claude Code on the demo app, it kept two of three fixes and cut JavaScript CPU time
-from 1.51 s to 82.5 ms (−95%) for $0.44. See [the AI fix harness](https://progen-labs.github.io/website/#spectra/docs/harness).
-
-## In VS Code
+![The Spectra dashboard: the top culprit of a recording, burn() in src/heavy.js, with its time and a suggested fix](docs/dashboard.webp)
 
-The Spectra extension (`vscode/`) puts results where you work: every finding in the **Problems panel** at the file
-and line responsible, **CodeLens** above the costliest components and functions
-(`⚡ Spectra: Row · 7,200 renders · 1.44 s rendering`), headline numbers in the **status bar**, **Verify against
-baseline** after a change, golden paths, and the dashboard inside the editor. Results that the CLI or an AI
-assistant writes to `.spectra/results` appear automatically, and on VS Code 1.101+ it offers Spectra's MCP server to
-agent mode. It runs your project's Spectra (0.2.0 or later) or `npx`.
+Prove a change yourself with `npx spectra performance --quick --runs 5 --out before.json`, the same with `after.json`,
+then `npx spectra compare before.json after.json`. Put limits in `spectra.config.json` and every run becomes a CI gate
+(exit code 2 when over budget). `--json` prints a versioned result for scripts and editors. See
+[Measure a page](https://progen-labs.github.io/website/#spectra/docs/cli-performance),
+[Compare](https://progen-labs.github.io/website/#spectra/docs/compare),
+[Budgets and CI](https://progen-labs.github.io/website/#spectra/docs/budgets) and
+[JSON output](https://progen-labs.github.io/website/#spectra/docs/json-output).
 
-Install **Spectra — frontend performance** from the [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=progen-labs.spectra-performance), or from a terminal:
+## Commands
 
-```bash
-code --install-extension progen-labs.spectra-performance
+```
+spectra improve [options]               Make the app faster, unattended (spectra improve --help)
+spectra improve next|check|report|stop  The same, step by step, for your AI agent or you
+spectra performance [options]           Measure only: golden-path journeys, or --quick
+spectra compare <before> <after>        Did it get faster? Beyond run-to-run noise
+spectra reports                         List saved reports
+spectra dashboard [--open]              The dashboard UI
+spectra mcp [--project <dir>]           MCP server for AI tools (stdio)
+spectra agents [--remove]               Teach your AI agents what Spectra does
+spectra --help                          Every option
 ```
 
-For Cursor, Windsurf or VSCodium (Open VSX), until it is listed there: `cd vscode && npx @vscode/vsce package
---no-dependencies`, then install `spectra-performance-0.1.0.vsix` with **Extensions: Install from VSIX…**.
-
-See the [VS Code guide](https://progen-labs.github.io/website/#spectra/docs/vscode).
-
-## Safe by default
-
-Auto-exploration never triggers destructive actions. Spectra detects controls that would mutate state —
-anything labelled delete / pay / checkout / log out, logout links, and `POST`/`PUT`/`DELETE` form submits —
-and **skips** them unless you explicitly allow them. Form fields are filled with synthetic values; GET
-searches and navigations are fair game. If a session expires and the app sends Spectra back to its login page,
-Spectra signs in again.
-
-## Where results go
+Everything Spectra does runs on your machine, in a separate Chrome profile, on a development build (production
+builds hide component timings). Reports go to `.spectra/` in your project; keep it out of git. Automatic exploration
+never clicks delete, pay or log out, and never submits a form that changes data.
 
-Reports are written to `.spectra/reports/` in your project (add it to `.gitignore`). Each golden path is a
-full report you can open in `spectra dashboard`, export to PDF, or compare against another commit.
+## Project health
 
-## How it works
+<p align="center">
+  <a href="https://github.com/progen-labs/spectra/actions/workflows/checks.yml"><img alt="tests" src="https://img.shields.io/github/check-runs/progen-labs/spectra/main?nameFilter=Tests%20%28Node%2022%2C%20ubuntu-latest%29&style=flat-square&label=tests"></a>
+  <a href="https://github.com/progen-labs/spectra/actions/workflows/checks.yml"><img alt="lint" src="https://img.shields.io/github/check-runs/progen-labs/spectra/main?nameFilter=Lint&style=flat-square&label=lint"></a>
+  <a href="https://github.com/progen-labs/spectra/actions/workflows/checks.yml"><img alt="npm audit" src="https://img.shields.io/github/check-runs/progen-labs/spectra/main?nameFilter=npm%20audit&style=flat-square&label=npm%20audit"></a>
+  <a href="https://github.com/progen-labs/spectra/actions/workflows/checks.yml"><img alt="snyk" src="https://img.shields.io/github/check-runs/progen-labs/spectra/main?nameFilter=Snyk&style=flat-square&label=snyk"></a>
+  <a href="https://socket.dev/npm/package/@progen-labs/spectra"><img alt="Socket" src="https://socket.dev/api/badge/npm/package/@progen-labs/spectra"></a>
+  <a href="https://github.com/progen-labs/spectra/actions/workflows/checks.yml"><img alt="size budget" src="https://img.shields.io/github/check-runs/progen-labs/spectra/main?nameFilter=Size%20budget&style=flat-square&label=size%20budget"></a>
+  <a href="https://scorecard.dev/viewer/?uri=github.com/progen-labs/spectra"><img alt="OpenSSF Scorecard" src="https://api.scorecard.dev/projects/github.com/progen-labs/spectra/badge?style=flat-square"></a>
+  <a href="https://www.npmjs.com/package/@progen-labs/spectra?activeTab=code"><img alt="unpacked size" src="https://img.shields.io/npm/unpacked-size/@progen-labs/spectra?style=flat-square&label=unpacked&color=0a84ff"></a>
+</p>
 
-Spectra launches Chrome via `puppeteer-core`, records a CDP trace + CPU profile, and injects a probe that
-tracks component renders, slow interactions and Web Vitals. It maps sampled frames back to your source
-through source maps (and bundler markers as a fallback), then ranks the files, functions and components
-that cost the most main-thread time. See the
-[deep-dive docs](https://github.com/progen-labs/spectra/blob/main/DOCS.md) for how capture, correlation
-and report generation work.
+Every pull request and push to `main` runs the same checks, and **spectra-bot** reports them in one comment on each
+pull request: the tests on Node 22, 24 and 26 across Linux, macOS and Windows with a coverage floor, lint, `npm audit`
+and Snyk, Socket's supply-chain score, size budgets, the links in the docs, the improve bench, the GitHub Action on the
+demo app, CodeQL and the OpenSSF Scorecard. Every action is pinned to a commit, and CI installs from the committed
+lockfile. Releases carry a changelog, the package, its SBOM and signed build attestations. See
+[CONTRIBUTING.md](CONTRIBUTING.md), [CHANGELOG.md](CHANGELOG.md) and, for security issues, [SECURITY.md](SECURITY.md).
 
 ## Documentation
 
-- **[The guide](https://progen-labs.github.io/website/#spectra/docs/introduction)**: every feature, with
-  annotated screenshots. Start with
-  [Quick start](https://progen-labs.github.io/website/#spectra/docs/quick-start),
-  [Compare before and after](https://progen-labs.github.io/website/#spectra/docs/compare),
+- **[The guide](https://progen-labs.github.io/website/#spectra/docs/improve)**: start with
+  [Improve the performance](https://progen-labs.github.io/website/#spectra/docs/improve) and
+  [Your AI agent](https://progen-labs.github.io/website/#spectra/docs/agents); then
+  [Measure a page](https://progen-labs.github.io/website/#spectra/docs/cli-performance),
   [Budgets and CI](https://progen-labs.github.io/website/#spectra/docs/budgets),
-  [JSON output](https://progen-labs.github.io/website/#spectra/docs/json-output),
-  [Claude Code](https://progen-labs.github.io/website/#spectra/docs/claude-code), the
+  [MCP server](https://progen-labs.github.io/website/#spectra/docs/mcp-server),
+  [How improve decides](https://progen-labs.github.io/website/#spectra/docs/harness), the
   [Findings reference](https://progen-labs.github.io/website/#spectra/docs/findings) and
   [Troubleshooting](https://progen-labs.github.io/website/#spectra/docs/troubleshooting).
 - **[DOCS.md](DOCS.md)**: the in-repo manual, the technical deep dive, and how to contribute.