@cloudbeat/atlas-cli 0.3.0 → 0.4.0

package/dist/docs/skills.md

@@ -0,0 +1,88 @@
+# The Skills
+
+`atlas skills install` writes six skills plus a vendor-neutral `AGENTS.md`. Each
+skill is a short document covering one part of load testing: what to do, in what
+order, and which mistakes to avoid.
+
+They are plain Markdown. Read them, edit them for your project, commit them —
+they are yours once installed.
+
+## How they load
+
+Claude Code reads each skill's description and loads the one that fits your
+request, so you never name a skill yourself. Ask *"why did the test fail?"* and
+it loads the results skill; ask *"record a checkout"* and it loads the recording
+one. Several can load in one conversation as the work moves on.
+
+Assistants without skill support read the same guidance, condensed, from
+`AGENTS.md`.
+
+## What each one covers
+
+### `atlas-load-test`
+
+The end-to-end flow, and the one that usually loads first for *"load test our
+checkout"*. Picking or creating a plan, uploading data, sizing, the mandatory
+smoke run, then the real run and the report. Mostly it sequences the others.
+
+### `atlas-record`
+
+Recording a scenario from a real browser. Choosing who clicks — you or the
+assistant — driving the browser through the accessibility tree, naming
+transactions before performing them, signing in without handing over a password,
+and the traps: native dialogs that freeze a session, one click recording two
+requests, everything before the first action landing in one transaction.
+
+### `atlas-test-plan`
+
+Plans and data files, and the longest of the six. Downloading before editing,
+the three kinds of change in order of preference, and how these plans are laid
+out — think-time settings, host settings, the numbered transactions that make a
+report readable, and sizing through run-time properties.
+
+It also carries the two things that save the most time in practice: the stages
+for turning a fresh recording into a real test (flow → test data → dynamic
+values → checks → upload), and a local debugging recipe that switches think time
+off in a throwaway copy, runs one user, and restores the original — seconds
+instead of minutes per attempt.
+
+### `atlas-correlate`
+
+Values the server issues per session — CSRF tokens, session ids, cart ids — and
+why a replayed one produces a fast, clean, meaningless test. Reviewing what the
+recorder detected with its evidence, pinning what it missed, and telling those
+apart from values that belong in a data file instead.
+
+### `atlas-run`
+
+Starting and sizing a run: how users map onto machines, ramp-up, fixed machines
+versus a cluster, pass/fail thresholds, exit codes and CI usage, and what to do
+while a run is queued behind someone else's.
+
+### `atlas-analyze`
+
+Reading a result: the aggregation report, the shape of a run over time, the
+errors behind a failure — and recognising the failure modes where a broken test
+looks like a healthy one. If you only read one, read this one.
+
+## Editing them
+
+Installed skills are ordinary files in your repository. Adding your own
+conventions is normal and encouraged:
+
+- which project maps to which service
+- the thresholds your team gates on
+- environments that must never be load tested
+- who to ask before a run above a certain size
+
+`atlas skills install` will not overwrite a file you have edited unless you pass
+`--force`, so your changes survive an upgrade. When you do upgrade, diff first.
+
+## Listing what you have
+
+```sh
+atlas skills list              # what this CLI version carries
+atlas skills install --force   # refresh after upgrading the CLI
+```
+
+[Build your own integration →](/agents/automation)

package/dist/docs/test-plans.md

@@ -0,0 +1,92 @@
+# Test Plan Requirements
+
+Atlas runs standard JMeter test plans, but a plan written on a desktop needs a
+few changes before it runs correctly on a fleet of Linux load generators. These
+are the things that actually catch people out.
+
+## Data file paths
+
+Reference data files by a plain relative path:
+
+```
+./users.csv          ✅
+users.csv            ✅
+C:\Users\me\users.csv   ❌
+/home/me/data/users.csv ❌
+./data/users.csv        ❌
+```
+
+A project's files live in one flat folder — see [Test Files](/guide/test-files).
+
+If a **CSV Data Set Config** path can't be resolved, every thread in that thread
+group throws before issuing a single request. There are no failed samples: the
+summary reports `0.00%` errors and the dashboard **omits that thread group**
+entirely while the others look healthy.
+
+If a thread group is missing from your results, check its data file paths first.
+
+Every file the plan references must also actually be uploaded.
+
+## Disable GUI listeners
+
+Switch these off before uploading:
+
+- **View Results Tree**
+- **Aggregate Report**
+- **Simple Data Writer**
+
+They consume a lot of memory during a headless run — enough to destabilise a
+long test — and Atlas collects its own results regardless. A **Simple Data
+Writer** pointing at a `C:\...` path is doubly useless.
+
+## Thread counts are per machine
+
+Atlas does not divide your threads across machines. A 100-thread plan on 5
+generators is **500** concurrent users.
+
+Decide the number you want in total, then divide by how many generators you plan
+to use.
+
+## Header rows in CSV files
+
+Whether line 1 of a data file is a header is decided by your plan's **CSV Data
+Set Config**, not guessed:
+
+- If **Variable Names** is filled in and **Ignore first line** is true, line 1 is
+  a header.
+- If **Variable Names** is empty, JMeter reads line 1 as the names — so it counts
+  as a header too.
+
+Get this right and each machine's slice keeps the header while the data rows are
+divided. Get it wrong and you either inject a bogus row or lose a real one.
+
+## Timers and pacing
+
+Think time matters more in a distributed test, not less. Without it, every
+virtual user hammers as fast as the network allows, which produces a number that
+looks impressive and means nothing.
+
+## Parameterising the target
+
+If you test more than one environment, drive the host from a variable rather
+than hardcoding it, and pass it at run time:
+
+```sh
+atlas run -p SHOP --args "-Jhost=staging.example.com"
+```
+
+## A checklist
+
+Before your first run:
+
+- [ ] Data file paths are relative (`./file.csv`)
+- [ ] Every referenced file is uploaded
+- [ ] GUI listeners disabled
+- [ ] Thread count is per-machine, and you've multiplied by your generator count
+- [ ] Header handling matches your files
+- [ ] Timers present
+- [ ] The plan runs locally in headless mode first: `jmeter -n -t plan.jmx`
+
+That last one is the highest-value check. `jmeter -n -t plan.jmx` on your own
+machine catches most problems in seconds, without waiting for machines to power
+on.

package/dist/docs/troubleshooting.md

@@ -0,0 +1,79 @@
+# Troubleshooting
+
+## A thread group is missing from my results
+
+The usual cause is a **data file path that can't be resolved**. Every thread in
+that group fails before sending a request, so there are no errors to report — the
+group simply isn't there.
+
+Check the **CSV Data Set Config** entries in that thread group and make each one
+a relative path (`./data.csv`), then confirm the file is uploaded. See
+[Test Plan Requirements](/reference/test-plans).
+
+## The test finished in seconds with no results
+
+Usually the plan didn't start properly. Check:
+
+- The plan runs locally: `jmeter -n -t plan.jmx`
+- Every referenced file is uploaded
+- The machine is big enough — an undersized generator can fail to start JMeter
+  at all rather than running slowly
+
+## Max Users is lower than I expected
+
+Max Users adds up the concurrent users reported by every machine. If you ran on
+5 generators and it shows roughly one machine's worth, the others weren't
+producing load.
+
+Check the Fleet page: were all the machines connected? Open **Watch** during a
+run to see per-machine activity live.
+
+## A machine shows as on, but not connected
+
+The machine is running but its agent isn't reaching Atlas. On the machine:
+
+- Confirm the Atlas agent service is running
+- Confirm it can reach your Atlas instance over outbound HTTPS
+- Check for a proxy or firewall rule blocking outbound connections
+
+The agent reconnects on its own once the connection is restored.
+
+## My test is queued and hasn't started
+
+A load generator runs one test at a time. If the machines you asked for are
+busy, your run waits and starts automatically when they free up. Either wait, or
+choose different machines.
+
+## Stop said it couldn't reach a machine
+
+Atlas only marks a machine stopped once it has confirmed the process actually
+ended. If it can't reach one, it tells you and the run stays open — deliberately,
+so a test can't keep running unnoticed while the record says it stopped.
+
+Retry the stop when the machine is reachable again.
+
+## Error rate is high but I can't see why
+
+Click the **Error %** cell for a request in the aggregation report. That opens
+the actual errors — response codes, messages, and the full request and response
+for each distinct failure.
+
+If errors are concentrated in one endpoint, click its **Label** to chart that
+request on its own and see when it started failing.
+
+## Results look wrong for one request
+
+Check whether the same sampler name exists in more than one thread group. Atlas
+keeps them as separate rows attributed to the right group — if you expected them
+combined, that's why the numbers differ from a single-machine JMeter run.
+
+## A recorded plan fails on the second run
+
+Usually a dynamic value that wasn't correlated — a token that was valid when you
+recorded and isn't now. Re-record with correlation enabled (the default), and
+check that the step which issues the token is part of the recording.
+
+## Getting help
+
+When reporting a problem, include the **test ID** (`SHOP-20260818-194201`). It
+identifies the run and everything recorded about it.

package/dist/plan.js

@@ -0,0 +1,250 @@
+"use strict";
+/**
+ * Reading a JMeter test plan well enough to say whether it will work here.
+ *
+ * This is an advisory scan, not the deploy path: the control plane does its own
+ * work on the copy it sends out (flattening data-file paths it recognises,
+ * switching off GUI listeners, attaching Atlas reporting). What it CANNOT fix is
+ * a data file that was never uploaded, a plan with no enabled thread group, or a
+ * file whose structure it cannot attach reporting to — and every one of those
+ * fails quietly at run time, which is what this exists to catch beforehand.
+ *
+ * Regex over the XML, deliberately: the same shape the control plane uses, no
+ * parser dependency, and it never rewrites anything.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.checkPlan = checkPlan;
+/** Lower-cased basename, tolerant of Windows separators — matches how the
+ *  control plane decides whether a reference means an uploaded file. */
+function basenameKey(filename) {
+    const parts = filename.replace(/\\/g, '/').split('/');
+    return (parts[parts.length - 1] ?? filename).trim().toLowerCase();
+}
+function basename(filename) {
+    const parts = filename.replace(/\\/g, '/').split('/');
+    return (parts[parts.length - 1] ?? filename).trim();
+}
+function stringProp(block, name) {
+    const m = block.match(new RegExp(`<stringProp name="${name}">([\\s\\S]*?)</stringProp>`));
+    return m ? m[1].trim() : '';
+}
+function intProp(block, name) {
+    const m = block.match(new RegExp(`<(?:string|int)Prop name="${name}">([\\s\\S]*?)</(?:string|int)Prop>`));
+    return m ? m[1].trim() : '';
+}
+function attr(tag, name) {
+    return new RegExp(`${name}="([^"]*)"`).exec(tag)?.[1] ?? '';
+}
+/** JMeter treats a missing `enabled` attribute as true. */
+function isEnabled(tag) {
+    return attr(tag, 'enabled') !== 'false';
+}
+const THREAD_GROUP_TAGS = [
+    'ThreadGroup',
+    'SetupThreadGroup',
+    'PostThreadGroup',
+    'com\\.blazemeter\\.jmeter\\.threads\\.concurrency\\.ConcurrencyThreadGroup',
+    'kg\\.apc\\.jmeter\\.threads\\.UltimateThreadGroup',
+];
+function readThreadGroups(jmx) {
+    const out = [];
+    for (const tag of THREAD_GROUP_TAGS) {
+        const re = new RegExp(`<(${tag})\\b([^>]*)>([\\s\\S]*?)</\\1>`, 'g');
+        let m;
+        while ((m = re.exec(jmx)) !== null) {
+            const [, kind, attrs, body] = m;
+            const threads = intProp(body, 'ThreadGroup.num_threads') || intProp(body, 'TargetLevel');
+            const property = /\$\{__P\(([^,)]+)/.exec(threads)?.[1]?.trim();
+            out.push({
+                name: attr(`<x ${attrs}>`, 'testname'),
+                kind,
+                enabled: isEnabled(`<x ${attrs}>`),
+                threads,
+                loops: intProp(body, 'LoopController.loops'),
+                ...(property ? { sizeProperty: property } : {}),
+            });
+        }
+    }
+    return out;
+}
+function readDataFiles(jmx, uploaded) {
+    const known = uploaded ? new Set(uploaded.map(basenameKey)) : undefined;
+    // Keyed by the file it resolves to: a plan commonly reads one file from
+    // several data sets, and reporting it four times helps nobody.
+    const byFile = new Map();
+    const re = /<CSVDataSet\b([^>]*)>([\s\S]*?)<\/CSVDataSet>/g;
+    let m;
+    while ((m = re.exec(jmx)) !== null) {
+        const [, attrs, body] = m;
+        const reference = stringProp(body, 'filename');
+        if (!reference)
+            continue;
+        // A path built at run time can't be judged now, and the control plane leaves
+        // it alone for the same reason.
+        if (reference.includes('${'))
+            continue;
+        const key = basenameKey(reference);
+        const enabled = isEnabled(`<x ${attrs}>`);
+        const hasPath = /[\\/]/.test(reference);
+        const existing = byFile.get(key);
+        if (existing) {
+            if (!existing.references.includes(reference))
+                existing.references.push(reference);
+            existing.enabled ||= enabled;
+            existing.hasPath ||= hasPath;
+            continue;
+        }
+        byFile.set(key, {
+            filename: basename(reference),
+            references: [reference],
+            enabled,
+            hasPath,
+            ...(known ? { uploaded: known.has(key) } : {}),
+        });
+    }
+    return [...byFile.values()];
+}
+/** Listeners the control plane switches off in the deployed copy. */
+const DISABLED_AT_DEPLOY = {
+    ViewResultsFullVisualizer: 'View Results Tree',
+    SimpleDataWriter: 'Simple Data Writer',
+};
+function readListeners(jmx) {
+    const out = [];
+    const re = /<ResultCollector\b([^>]*)>/g;
+    let m;
+    while ((m = re.exec(jmx)) !== null) {
+        const tag = m[0];
+        const guiclass = attr(tag, 'guiclass');
+        if (!(guiclass in DISABLED_AT_DEPLOY))
+            continue;
+        out.push({
+            guiclass,
+            name: attr(tag, 'testname') || DISABLED_AT_DEPLOY[guiclass],
+            enabled: isEnabled(tag),
+        });
+    }
+    return out;
+}
+/**
+ * Whether Atlas can attach its reporting.
+ *
+ * It is inserted as the last child of the Test Plan's hashTree, which needs the
+ * file to end in the standard way. A plan that fails this runs and produces
+ * nothing — no dashboard, no results — so it is an error, not a nicety.
+ */
+function reportingCanAttach(jmx) {
+    return /<\/hashTree>(\s*)<\/hashTree>(\s*)<\/jmeterTestPlan>(\s*)$/.test(jmx);
+}
+function checkPlan(jmx, uploaded) {
+    const issues = [];
+    const threadGroups = readThreadGroups(jmx);
+    const dataFiles = readDataFiles(jmx, uploaded);
+    const listeners = readListeners(jmx);
+    const canAttach = reportingCanAttach(jmx);
+    if (!/<jmeterTestPlan\b/.test(jmx)) {
+        issues.push({
+            severity: 'error',
+            code: 'not-a-test-plan',
+            message: 'This file is not a JMeter test plan.',
+        });
+    }
+    const opens = (jmx.match(/<hashTree>/g) ?? []).length;
+    const closes = (jmx.match(/<\/hashTree>/g) ?? []).length;
+    if (opens !== closes) {
+        issues.push({
+            severity: 'error',
+            code: 'unbalanced',
+            message: `The plan's structure is broken: ${opens} <hashTree> against ${closes} closing tags.`,
+            fix: 'Restore the file and redo the edit — JMeter will not open it in this state.',
+        });
+    }
+    if (!canAttach) {
+        issues.push({
+            severity: 'error',
+            code: 'reporting-cannot-attach',
+            message: 'Atlas cannot attach its reporting to this plan, so a run would produce no results.',
+            fix: 'Open and re-save the plan in JMeter so it ends with the standard structure.',
+        });
+    }
+    const enabledGroups = threadGroups.filter(g => g.enabled);
+    if (threadGroups.length === 0) {
+        issues.push({
+            severity: 'error',
+            code: 'no-thread-groups',
+            message: 'The plan has no thread groups, so it would run nothing.',
+        });
+    }
+    else if (enabledGroups.length === 0) {
+        issues.push({
+            severity: 'error',
+            code: 'all-thread-groups-disabled',
+            message: `All ${threadGroups.length} thread group(s) are disabled, so the run would do nothing.`,
+            fix: 'Enable the one you mean to run.',
+        });
+    }
+    for (const file of dataFiles.filter(f => f.enabled)) {
+        const shown = file.references[0];
+        if (file.uploaded === false) {
+            // The one that hurts: every thread in the group fails before sampling, so
+            // the group disappears from the results with no errors to explain it.
+            issues.push({
+                severity: 'error',
+                code: 'data-file-missing',
+                message: `"${file.filename}" is read by the plan but is not in the project.`,
+                fix: `Upload it: atlas files upload ${file.filename}`,
+            });
+        }
+        else if (file.uploaded && file.hasPath) {
+            issues.push({
+                severity: 'info',
+                code: 'data-file-path',
+                message: `"${shown}" is a path; Atlas will use the uploaded "${file.filename}".`,
+            });
+        }
+        else if (file.uploaded === undefined && file.hasPath) {
+            issues.push({
+                severity: 'warning',
+                code: 'data-file-path-unchecked',
+                message: `"${shown}" is a path from another machine.`,
+                fix: `Make sure "${file.filename}" is uploaded to the project; then Atlas resolves it for you.`,
+            });
+        }
+    }
+    const liveListeners = listeners.filter(l => l.enabled);
+    if (liveListeners.length) {
+        issues.push({
+            severity: 'info',
+            code: 'gui-listeners',
+            message: `${liveListeners.map(l => `"${l.name}"`).join(', ')} will be switched off for the run.`,
+        });
+    }
+    if (enabledGroups.length && enabledGroups.every(g => !g.sizeProperty)) {
+        issues.push({
+            severity: 'warning',
+            code: 'fixed-thread-count',
+            message: 'User counts are fixed inside the plan, so the only way to scale it is more machines.',
+            fix: 'Use ${__P(threads,N)} for the thread count to size the run with -Jthreads.',
+        });
+    }
+    else {
+        // Say which property, because it is whatever the plan's author chose.
+        const props = [...new Set(enabledGroups.map(g => g.sizeProperty).filter(Boolean))];
+        if (props.length) {
+            issues.push({
+                severity: 'info',
+                code: 'sizable',
+                message: `Size this run with ${props.map(p => `-J${p}=<n>`).join(' ')}.`,
+            });
+        }
+    }
+    return {
+        threadGroups,
+        dataFiles,
+        listeners,
+        reportingCanAttach: canAttach,
+        issues,
+        ok: !issues.some(i => i.severity === 'error'),
+    };
+}
+//# sourceMappingURL=plan.js.map

package/dist/skills/AGENTS.md

@@ -0,0 +1,70 @@
+# Atlas load testing
+
+This project uses [Atlas](https://atlas.cloudbeat.io) for load testing. The
+`atlas` CLI drives it; `atlas-rec` records scenarios from a browser.
+
+Every command takes `--json`, and failures print JSON on standard error with a
+meaningful exit code (`0` pass, `1` a threshold was breached, `2` a usage or
+authentication problem, `3` the run failed or the server was unreachable).
+
+```bash
+atlas schema --json          # every command, argument and option
+atlas docs                   # the documentation, offline
+atlas docs troubleshooting   # one topic
+```
+
+## The flow
+
+```bash
+atlas whoami --json                       # who am I, which account
+atlas projects --json                     # what can I see
+atlas files list -p <project> --json      # test plans and data files
+atlas files download -p <project> <file> -o ./<file>   # before editing anything
+atlas plan check ./<file> -p <project>    # will it run, and report?
+atlas files upload -p <project> ./<file>  # same name replaces, no version history
+atlas capacity --json                     # machines, clusters, usage allowance
+atlas run -p <project> --jmx <plan> --servers <n> --wait --gate "error_rate<1,p95<2000"
+atlas results <testId> --json             # aggregation report
+atlas timeseries <testId> --json          # the shape of the run
+atlas errors <testId> --full              # what failed, with request and response
+```
+
+Recording a scenario, driven from the command line:
+
+```bash
+atlas-rec start <url> -o flow.jmx    # opens a browser, returns a session
+atlas-rec snapshot                   # what is on the page
+atlas-rec click --text "Sign in"     # act on it
+atlas-rec tx new "Checkout"          # name the step that comes next
+atlas-rec stop                       # write the plan
+atlas-rec suggest flow.capture.json  # values that change per session
+```
+
+## Rules that prevent real damage
+
+- **A run costs machine time on someone's account.** Confirm before starting one
+  that is not a smoke test, and never stop a run you did not start.
+- **Smoke-run first**: one machine, two users, a minute. Then check the results
+  actually contain data before scaling up.
+- **Load multiplies by machines.** Each machine runs the whole plan, so total
+  users = users-in-the-plan x machines.
+- **A test that measured nothing looks better than one that worked.** A missing
+  thread group with zero errors, a run that ended in seconds, or fast 200s that
+  return the login page all mean the test failed, not that the application is
+  fast.
+- **Download before you edit or replace a stored file.** Uploading replaces it
+  and nothing keeps the old version.
+- **Check a plan before uploading or running it.** A data file the project does
+  not have takes out a whole thread group with zero errors to explain it.
+- **Think time is a setting, not a property.** Recorded plans pause between steps
+  using a `Settings - Sleeps` variables element; `-J` does not change it. Before
+  running a plan locally to debug it, check that element and disable it in your
+  working copy, or one user takes minutes instead of seconds. Put it back exactly
+  as it was before uploading.
+- **A recording is a draft.** After stopping, report what was captured and ask
+  what to do next rather than uploading it. Offer to move the values every user
+  would otherwise repeat — credentials, search terms, ids — into a data file.
+- **Report what happened**, including failed gates and uncertainty.
+
+Full guidance is in the Atlas skills (`atlas skills install`) and at
+https://atlas.cloudbeat.io/docs.

package/dist/skills/atlas-analyze/SKILL.md

@@ -0,0 +1,104 @@
+---
+name: atlas-analyze
+description: Read and explain the results of an Atlas load test - the aggregation report, the shape of the run over time, the errors behind a failure - and recognise the failure modes where a broken test looks like a healthy one. Use when someone asks how a test went, what the numbers mean, why a test failed, or why results look wrong or missing.
+---
+
+# Reading results
+
+```bash
+atlas results <testId>                 # aggregation report, TOTAL first
+atlas timeseries <testId>              # users, response time, error rate over time
+atlas errors <testId>                  # distinct errors, most common first
+atlas errors <testId> --full           # with the request and response behind each
+```
+
+Add `--json` to any of them. `--label "<name>"` narrows timeseries and errors to
+one transaction or request.
+
+## Before interpreting anything, check the test was valid
+
+A load test that measured nothing usually looks *better* than one that worked.
+Rule these out first:
+
+**Is every thread group present?** Compare the report against the plan. A missing
+thread group with **zero errors** is the classic symptom of a data file the plan
+could not open: every user in that group fails before sending a request, so there
+is nothing to report as an error and the group simply vanishes while the others
+look healthy. The cause is almost always a data file that was never uploaded to
+the project. `atlas plan check -p <project> --jmx <plan>` names it in one line.
+(A path from another machine, `C:\data\users.csv`, is not itself the problem —
+Atlas resolves that to the uploaded file. Nothing uploaded under that name is.)
+
+**Did it run for a plausible length of time?** A run that ends in a few seconds
+with an empty dashboard did not run: the plan could not be started at all.
+
+**Is the dashboard empty despite a full-length run?** Atlas attaches its
+reporting to the plan when it deploys, and a file with an unusual structure can
+defeat that — the test runs and reports nothing. `atlas plan check` says so
+before you spend the time.
+
+**Are the response codes real?** A wall of fast 200s that return the login page
+is a failed test that passes every threshold. Check `atlas errors --full`, and be
+suspicious of response times that are far better than the application's normal
+behaviour.
+
+**Did every machine report?** Users should add up to roughly what you asked for
+(users-per-machine x machines). If the peak is a fraction of that, a machine was
+not running.
+
+## Then read the numbers
+
+- **Percentiles, not averages.** p95 and p99 are what users feel; an average
+  hides the tail completely.
+- **Error rate is errors over requests for the whole test**, not an average of
+  per-interval rates. The TOTAL row is authoritative.
+- **Throughput is the result, not the goal.** If throughput flattens while users
+  keep climbing, you have found the saturation point — that is usually the
+  headline of the whole test.
+- **Look at the shape.** `timeseries` shows where response time started to climb
+  and whether errors began at a particular user count. "It broke at about 300
+  users" is a more useful finding than any single number.
+- **Per-transaction matters more than TOTAL.** One slow step in an otherwise fast
+  plan is invisible in the total and obvious per label.
+
+## Explaining errors
+
+`atlas errors --full` gives the actual request and response for each distinct
+error. Sort out which kind you have:
+
+- **4xx** — usually the test, not the application: a stale correlated value, an
+  expired session, data that does not exist in the target environment.
+- **5xx** — usually the application, and worth reporting with the response body.
+- **Timeouts / connection errors** — the application or something in front of it
+  giving up. Check when they started against the user count.
+- **Assertion failures** — the request succeeded but returned the wrong thing,
+  such as a login page instead of the page you asked for.
+
+A failure that appears only above a certain load is the interesting one. Report
+the level it appeared at.
+
+## Comparing runs
+
+```bash
+atlas tests -p <project> --json    # recent runs with peak users, requests, error %
+atlas results <previous> --json
+```
+
+Compare like with like: the same plan, the same number of machines, the same
+user count. A regression is only a regression if the shape of the test was the
+same.
+
+## Writing it up
+
+A good report says, in this order:
+
+1. Whether it passed, against the thresholds that were set.
+2. What load was actually applied — users, ramp, duration, machines.
+3. Response time under that load: p95 per key transaction, not just the total.
+4. Where it started to degrade, from the time series.
+5. What failed, with real examples from the error detail.
+6. What to do next.
+
+State the uncertainty plainly where it exists. "The test never reached the target
+load because one machine dropped out" is a far more useful sentence than a
+confident summary of numbers that do not mean what they appear to.