@crvouga/atlas 0.6.0 → 0.6.1

package/CHANGELOG.md

@@ -1,6 +1,12 @@
 # Changelog: @crvouga/atlas
 
-## 0.6.0 (2026-10-15)
+## 0.6.1 (2026-10-15)
+
+### Fixes and improvements
+
+- make consumer integration reproducible (#9) ([bfd4e0c](https://github.com/crvouga/atlas/commit/bfd4e0c1c804d1f11fce3299e609af86c50e4732))
+
+## 0.6.0 (2026-10-14)
 
 ### Features
 

package/README.md

@@ -40,8 +40,19 @@ backends, and tells you in one command whether the product still does what it wa
 > [using Atlas from another project](docs/dogfooding.md) and [reporting issues](docs/reporting-issues.md).
 > Releases are automatic: see [releasing](https://github.com/crvouga/atlas/blob/main/docs/releasing.md).
 
+## Given this repo link to integrate Atlas?
+
+Start with **[the agent integration playbook](docs/agents.md#given-only-this-repository-link)** in your own
+project. It covers choosing an integration, installing with your package manager, finding docs for your installed
+version, running without a server, connecting real suites, and proving completion. **[Verify Atlas locally](docs/quickstart.md)**
+is a copyable walkthrough with expected JSON and exit codes; it needs no credentials or existing test suite.
+The machine-readable index is [llms.txt](llms.txt), and [llms-full.txt](llms-full.txt) contains the guides in one file.
+
 ## Run this repository's example
 
+For contributors working in an Atlas checkout with dependencies installed (`bun install --frozen-lockfile`).
+Consumer projects install the npm package instead; they do not need to clone or build this repository.
+
 Use two terminals:
 
 ```sh
@@ -64,20 +75,21 @@ Atlas is built to be integrated and operated by agents, with nothing to click an
 - **`atlas init`** detects a project's test runners, specs and CI and prints a plan (`--format json`) of the exact commands to
   run each suite and send its results; `--write` creates the CI workflow and an `AGENTS.md` section. Running it twice
   changes nothing.
-- **Every command prints JSON on request** (`--format json`), every document has a published JSON Schema, exit codes mean the
-  same everywhere (`0` worked, `1` the answer is no, `2` the command was wrong), and every operation is safe to repeat.
+- **Init and report commands print JSON on request** (`--format json`) with published JSON Schemas and consistent
+  exit codes (`0` worked, `1` the answer is no, `2` the command was wrong). Reapplying init or publishing identical evidence is safe.
 - **The server describes itself:** `GET /api/openapi.json` (OpenAPI 3.1) and `GET /llms.txt` (a guide for an agent given only
   the address) need no token; errors are RFC 9457 problem documents that say what to do.
 - **Documentation is generated from the code beside it:** `llms.txt` / `llms-full.txt` (also in the package), the TypeScript
   reference in [`docs/reference/`](docs/reference/server.md), the CLI and HTTP references, and the settings tables; tests fail when
   any of it drifts.
 
-Start with **[Atlas for AI agents](docs/agents.md)**.
+Start with **[Atlas for AI agents](docs/agents.md)**. A [copyable integration brief](docs/agents.md#an-integration-brief-you-can-give-an-agent)
+lets a user hand an agent this repository URL and a concrete definition of done.
 
 ## Integrate in five minutes
 
 ```sh
-bun add -d @crvouga/atlas            # or npm install -D / pnpm add -D; runs on Bun and Node 22.18+
+bun add -d @crvouga/atlas            # or npm install -D / pnpm add -D
 
 # 1. Each suite publishes a layer of what it ran: a JUnit or CTRF file, an Atlas run, or a checks file.
 bunx atlas report publish --store atlas-reports --producer web-e2e --junit out.xml --specs ./specs --environment desktop-web
@@ -105,7 +117,11 @@ bunx atlas report status --store all --specs ./specs --require-environments desk
 ## One package
 
 Atlas is a single npm package. Each part is its own import path, so a bundler keeps only what you
-import. It runs on Bun and on Node 22.18 or later, with any package manager:
+import. Use your project's package manager:
+
+<!-- generated:runtime-requirements -->
+Supported runtimes (from `package.json`): **node `>=22.18.0`** or **bun `>=1.2.0`**. Node consumers do not need Bun unless they use the Bun WebView driver.
+<!-- /generated:runtime-requirements -->
 
 ```sh
 bun add -d @crvouga/atlas

package/dist/reports/src/init.js

@@ -19,6 +19,7 @@ import { InitPlanSchema } from '../../schema/src/cli-results.js';
 import { collectSpecFiles, specKindOf } from './directory-outline.js';
 import { httpStore } from './http-store.js';
 import { serverToken } from './store-url.js';
+import { PACKAGE_MANAGERS } from './package-managers.js';
 const BEGIN = '<!-- atlas:begin -->';
 const END = '<!-- atlas:end -->';
 function defaultGit(args, cwd) {
@@ -50,9 +51,6 @@ function packageManagerOf(directory, pkg) {
     const declared = typeof pkg?.packageManager === 'string' ? pkg.packageManager.split('@')[0] : null;
     return declared === 'bun' || declared === 'pnpm' || declared === 'yarn' || declared === 'npm' ? declared : pkg ? 'npm' : null;
 }
-/** How the package manager runs a package's binary without installing it: `bunx`, `pnpm dlx`, `yarn dlx`, `npx`. */
-const EXEC = { bun: 'bunx', pnpm: 'pnpm dlx', yarn: 'yarn dlx', npm: 'npx' };
-const INSTALL_DEV = { bun: 'bun add -d', pnpm: 'pnpm add -D', yarn: 'yarn add -D', npm: 'npm install -D' };
 /** The spec files of a project by kind, and the folder to pass as `--specs`. */
 async function specsOf(directory) {
     const candidates = ['specs', 'spec', 'features', 'docs/specs', 'test/features', 'tests/features'];
@@ -118,7 +116,7 @@ function readdirSafe(directory) {
 /** The suite for a detected runner: how to run it so it writes a JUnit file (or the run manifest), and how to publish it. */
 function suiteOf(detected, context) {
     const specs = context.specs ? ` --specs ${context.specs}` : '';
-    const publishCommand = (producer, input, environment) => `${context.exec} @crvouga/atlas report publish --producer ${producer} ${input}${specs}${environment ? ` --environment ${environment}` : ''}`;
+    const publishCommand = (producer, input, environment) => `${context.exec} atlas report publish --producer ${producer} ${input}${specs}${environment ? ` --environment ${environment}` : ''}`;
     const make = (id, output, run, environment, prerequisites = [], format = 'junit', stream = null) => ({
         id, runner: detected.runner, evidence: detected.evidence, run, output, format, environment,
         publish: publishCommand(id, format === 'manifest' ? `--manifest ${output} --upload-run` : `--${format} ${output}`, environment), stream, prerequisites
@@ -136,7 +134,7 @@ function suiteOf(detected, context) {
         case 'bun-test': return make('bun-test', out('bun'), `bun test --reporter=junit --reporter-outfile=${out('bun')}`, null);
         case 'pytest': return make('pytest', out('pytest'), `pytest --junitxml=${out('pytest')}`, null);
         case 'go-test': return make('go-test', out('go'), `go test -v ./... 2>&1 | go-junit-report > ${out('go')}`, null, ['go install github.com/jstemmer/go-junit-report/v2@latest']);
-        default: return make('statecharts', 'atlas-runs/latest/manifest.json', `${context.exec} @crvouga/atlas run --mode fast`, null, [], 'manifest');
+        default: return make('statecharts', 'atlas-runs/latest/manifest.json', `${context.exec} atlas run --mode fast`, null, [], 'manifest');
     }
 }
 /** A suite that does not set its own exit-code handling must still publish: a failure is evidence. */
@@ -144,7 +142,7 @@ function githubWorkflow(suites, context) {
     const setup = context.manager === 'bun'
         ? '      - uses: oven-sh/setup-bun@v2\n      - run: bun install --frozen-lockfile\n'
         : `      - uses: actions/setup-node@v4\n        with: { node-version: 22 }\n      - run: ${context.manager === 'pnpm' ? 'corepack enable && pnpm install --frozen-lockfile' : context.manager === 'yarn' ? 'corepack enable && yarn install --immutable' : 'npm ci'}\n`;
-    const exec = EXEC[context.manager ?? 'npm'];
+    const exec = PACKAGE_MANAGERS[context.manager ?? 'npm'].exec;
     const jobs = suites.map(suite => `  ${suite.id.replace(/[^a-z0-9]+/g, '-')}:
     runs-on: ubuntu-latest
     steps:
@@ -157,13 +155,15 @@ ${setup}      # A failing suite must still publish: a failure is evidence. The j
 `).join('\n');
     return `# Sends every suite's results to the project's Atlas server and gates on the combined report.
 # Generated by \`atlas init\`; safe to edit. Needs the repository variable ATLAS_URL (https://atlas.example.com) and the
-# secrets ATLAS_PUBLISH_TOKEN (a \`publish\` token) and ATLAS_READ_TOKEN (a \`read\` token) of that server.
+# variable ATLAS_PROJECT (a stable project slug), and secrets ATLAS_PUBLISH_TOKEN (a \`publish\` token) and
+# ATLAS_READ_TOKEN (a \`read\` token) of that server.
 name: atlas
 on: [push, pull_request]
 permissions:
   contents: read
 env:
   ATLAS_STORE: \${{ vars.ATLAS_URL }}
+  ATLAS_PROJECT: \${{ vars.ATLAS_PROJECT }}
   ATLAS_TOKEN: \${{ secrets.ATLAS_PUBLISH_TOKEN }}
 jobs:
 ${jobs}
@@ -175,26 +175,27 @@ ${jobs}
       ATLAS_TOKEN: \${{ secrets.ATLAS_READ_TOKEN }}
     steps:
       - uses: actions/checkout@v4
-      - uses: oven-sh/setup-bun@v2
+${setup.trimEnd()}
       # This branch laid over ${context.defaultBranch}: what this run did not re-run is inherited from ${context.defaultBranch}'s latest
       # results, and a laptop's work in progress or another branch's results cannot turn this red.
-      - run: bunx @crvouga/atlas report status --branch "\${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" --branch ${context.defaultBranch} --ignore-modified${context.specs ? ' --require-all-specs' : ''}
+      - run: ${exec} atlas report status --branch "\${GITHUB_HEAD_REF:-$GITHUB_REF_NAME}" --branch ${context.defaultBranch} --ignore-modified${context.specs ? ' --require-all-specs' : ''}
 `;
 }
 /** The `AGENTS.md` section: what Atlas is in this project and the commands to use, replaced between its markers. */
-function agentsSection(plan) {
+function agentsSection(plan, exec) {
     const url = plan.server.url ?? '<the project\'s Atlas server>';
     const lines = [
         BEGIN,
         '## Atlas: test evidence for this project',
         '',
         `This project sends the results of its test suites to an [Atlas](https://github.com/crvouga/atlas) server (${url}), which shows everyone one combined, live report. A check is identified by a stable id; the newest completed result of each check wins; unknown is never a pass. Set \`ATLAS_STORE=${url}\` and \`ATLAS_TOKEN\` (a \`publish\` token for sending, a \`read\` token for asking).`,
+        'Set `ATLAS_PROJECT` to the same stable project slug locally and in CI; this selects the project on a shared node. Use the installed `@crvouga/atlas` and the project\'s lockfile. Integration guide: https://github.com/crvouga/atlas/blob/main/docs/agents.md (version-matched copy: `node_modules/@crvouga/atlas/docs/agents.md`).',
         '',
         '- **Machine-readable API:** `' + `${url}/api/openapi.json` + '` (OpenAPI 3.1). **Guide for agents:** `' + `${url}/llms.txt` + '`.',
         '- **After you change behaviour,** run the suite, then send its results (publish even when it fails: a failure is evidence).',
         ...plan.suites.flatMap(suite => ['', `  - **${suite.id}**: \`${suite.run}\``, `    then \`${suite.publish}\`` + (suite.stream ? ` (or stream: \`${suite.stream}\`)` : '')]),
         '',
-        `- **Is it passing?** \`bunx @crvouga/atlas report status --branch ${plan.git.defaultBranch} --ignore-modified --format json\` (exit 0 passes, 1 does not, 2 means the command was wrong). The failing checks are in \`failing\`.`,
+        `- **Is it passing?** \`${exec} atlas report status --branch ${plan.git.defaultBranch} --ignore-modified --format json\` (exit 0 passes, 1 does not, 2 means the command was wrong). The failing checks are in \`failing\`.`,
         plan.specs.directory ? `- **Specs** live in \`${plan.specs.directory}/\` (${Object.entries(plan.specs.kinds).map(([kind, count]) => `${count} ${kind}`).join(', ')}). Results are laid over them by path.` : '- No spec files were found. Pass `--spec <path>` or `--specs <dir>` to `publish` to link checks to specs.',
         '- Keep each check\'s `id` stable across runs: that is what lets a new result replace an old one.',
         '- Evidence (screenshots, videos, traces, logs) rides on checks: https://github.com/crvouga/atlas/blob/main/docs/extending.md',
@@ -228,13 +229,14 @@ export async function planInit(options) {
     const env = options.env ?? {};
     const git = options.git ?? defaultGit;
     const pkg = readJson(path.join(directory, 'package.json'));
+    const dependencies = { ...pkg?.dependencies, ...pkg?.devDependencies };
     const manager = packageManagerOf(directory, pkg);
     const specs = await specsOf(directory);
     const configured = env.ATLAS_STORE?.split(/[\n,]+/).map(item => item.trim()).find(item => /^https?:\/\//i.test(item));
     const serverUrl = (options.server ?? configured ?? null)?.replace(/\/+$/, '') ?? null;
     const warnings = [];
-    const exec = EXEC[manager ?? 'npm'];
-    const context = { exec, install: INSTALL_DEV[manager ?? 'npm'], specs: specs.directory, server: serverUrl };
+    const { exec, installDev } = PACKAGE_MANAGERS[manager ?? 'npm'];
+    const context = { exec, install: installDev, specs: specs.directory, server: serverUrl };
     const suites = runnersOf(directory, pkg).map(found => suiteOf(found, context));
     if (!suites.length)
         warnings.push('No test runner was recognised (looked for vitest, jest, playwright, cypress, cucumber, mocha, codeceptjs, node --test, bun test, pytest, go test and Atlas statecharts). Add one suite by hand: run it so it writes a JUnit XML or CTRF file, then `atlas report publish --producer <name> --junit <file>`.');
@@ -252,7 +254,7 @@ export async function planInit(options) {
         warnings.push(`${ci} detected: no workflow is generated for it. In its jobs run each suite, then its publish command (with ATLAS_STORE and ATLAS_TOKEN set from secrets), then the gate command from AGENTS.md.`);
     const base = { suites, specs, server: { url: serverUrl, tokenEnv: 'ATLAS_TOKEN' }, git: { branch, defaultBranch } };
     const wanted = [
-        { path: 'AGENTS.md', purpose: 'Tells every agent working in this repository how to send and read test evidence.', next: current => withSection(current, agentsSection(base)) }
+        { path: 'AGENTS.md', purpose: 'Tells every agent working in this repository how to send and read test evidence.', next: current => withSection(current, agentsSection(base, exec)) }
     ];
     if (ci === 'github-actions' && suites.length)
         wanted.push({ path: '.github/workflows/atlas.yml', purpose: 'Runs each suite in CI, sends its results to the server even when it fails, and gates on the combined report.', next: () => githubWorkflow(suites, { manager, defaultBranch, specs: specs.directory }) });
@@ -291,10 +293,11 @@ export async function planInit(options) {
     else if (options.verify)
         warnings.push('--verify needs a server: pass --server or set ATLAS_STORE.');
     const nextSteps = [
+        ...(dependencies['@crvouga/atlas'] ? [] : [`Install Atlas in this project before running the planned commands: ${context.install} @crvouga/atlas. Commit the manifest and lockfile so local runs and CI use the same version.`]),
         ...(serverUrl ? [] : ['Decide which server to send results to (run one with `atlas serve`), then run this again with --server <url>.']),
         ...(options.write ? [] : ['Review the plan, then run again with --write to create the files in `files`.']),
         ...suites.flatMap(suite => suite.prerequisites.map(command => `Install what ${suite.id} needs: ${command}`)),
-        ...(serverUrl ? [`Set ATLAS_STORE=${serverUrl} and ATLAS_TOKEN (a publish token) in CI and on each machine that should send results.`, 'Run `atlas report doctor` to prove the server can be written to and read.'] : []),
+        ...(serverUrl ? [`Set ATLAS_STORE=${serverUrl}, ATLAS_PROJECT (the same stable project slug) and ATLAS_TOKEN (a publish token) in CI and on each machine that should send results.`, 'Run `atlas report doctor` to prove the server can be written to and read.'] : []),
         ...suites.map(suite => `Prove ${suite.id}: run \`${suite.run}\`, then \`${suite.publish}\`, then open ${serverUrl ?? 'the server'} and find its results.`)
     ];
     const ok = verification ? verification.reachable && verification.canPublish && verification.error === null : true;

package/dist/reports/src/package-managers.d.ts

@@ -0,0 +1,35 @@
+/**
+ * @module Consumer package-manager commands
+ *
+ * One source for commands emitted by init, the running server's agent guide, and generated documentation.
+ * Execute the installed CLI so a consumer keeps the versions selected by its own manifest and lockfile.
+ */
+/** Supported consumer package managers, their development install command and installed-binary executor. */
+export declare const PACKAGE_MANAGERS: {
+    readonly bun: {
+        readonly label: "Bun";
+        readonly installDev: "bun add -d";
+        readonly exec: "bunx";
+    };
+    readonly npm: {
+        readonly label: "npm";
+        readonly installDev: "npm install -D";
+        readonly exec: "npm exec --";
+    };
+    readonly pnpm: {
+        readonly label: "pnpm";
+        readonly installDev: "pnpm add -D";
+        readonly exec: "pnpm exec";
+    };
+    readonly yarn: {
+        readonly label: "Yarn";
+        readonly installDev: "yarn add -D";
+        readonly exec: "yarn exec";
+    };
+};
+/**
+ * Markdown installation table for consumer and server agent documentation.
+ * @example
+ * const markdown = packageManagerTable(); // the same commands `atlas init` emits
+ */
+export declare function packageManagerTable(): string;

package/dist/reports/src/package-managers.js

@@ -0,0 +1,23 @@
+/**
+ * @module Consumer package-manager commands
+ *
+ * One source for commands emitted by init, the running server's agent guide, and generated documentation.
+ * Execute the installed CLI so a consumer keeps the versions selected by its own manifest and lockfile.
+ */
+/** Supported consumer package managers, their development install command and installed-binary executor. */
+export const PACKAGE_MANAGERS = {
+    bun: { label: 'Bun', installDev: 'bun add -d', exec: 'bunx' },
+    npm: { label: 'npm', installDev: 'npm install -D', exec: 'npm exec --' },
+    pnpm: { label: 'pnpm', installDev: 'pnpm add -D', exec: 'pnpm exec' },
+    yarn: { label: 'Yarn', installDev: 'yarn add -D', exec: 'yarn exec' }
+};
+/**
+ * Markdown installation table for consumer and server agent documentation.
+ * @example
+ * const markdown = packageManagerTable(); // the same commands `atlas init` emits
+ */
+export function packageManagerTable() {
+    return ['| Package manager | Install | Run the installed CLI |', '| --- | --- | --- |',
+        ...Object.values(PACKAGE_MANAGERS).map(manager => `| ${manager.label} | \`${manager.installDev} @crvouga/atlas\` | \`${manager.exec} atlas\` |`)
+    ].join('\n');
+}

package/dist/schema/src/cli-results.d.ts

@@ -147,10 +147,10 @@ export declare const InitPlanSchema: z.ZodObject<{
     project: z.ZodObject<{
         name: z.ZodNullable<z.ZodString>;
         packageManager: z.ZodNullable<z.ZodEnum<{
-            bun: "bun";
+            npm: "npm";
             pnpm: "pnpm";
+            bun: "bun";
             yarn: "yarn";
-            npm: "npm";
         }>>;
         languages: z.ZodArray<z.ZodString>;
     }, z.core.$loose>;
@@ -208,3 +208,234 @@ export declare const InitPlanSchema: z.ZodObject<{
     nextSteps: z.ZodArray<z.ZodString>;
     warnings: z.ZodArray<z.ZodString>;
 }, z.core.$loose>;
+/**
+ * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
+ * A new result needs an entry here and a runtime scenario in the documentation contract tests.
+ */
+export declare const CLI_RESULTS: {
+    readonly init: {
+        readonly command: "atlas init";
+        readonly schemaName: "init-plan";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            directory: z.ZodString;
+            project: z.ZodObject<{
+                name: z.ZodNullable<z.ZodString>;
+                packageManager: z.ZodNullable<z.ZodEnum<{
+                    npm: "npm";
+                    pnpm: "pnpm";
+                    bun: "bun";
+                    yarn: "yarn";
+                }>>;
+                languages: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>;
+            git: z.ZodObject<{
+                branch: z.ZodNullable<z.ZodString>;
+                defaultBranch: z.ZodString;
+            }, z.core.$loose>;
+            ci: z.ZodEnum<{
+                none: "none";
+                "github-actions": "github-actions";
+                "gitlab-ci": "gitlab-ci";
+                circleci: "circleci";
+            }>;
+            server: z.ZodObject<{
+                url: z.ZodNullable<z.ZodString>;
+                tokenEnv: z.ZodLiteral<"ATLAS_TOKEN">;
+            }, z.core.$loose>;
+            specs: z.ZodObject<{
+                directory: z.ZodNullable<z.ZodString>;
+                kinds: z.ZodRecord<z.ZodString, z.ZodNumber>;
+            }, z.core.$loose>;
+            suites: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                runner: z.ZodString;
+                evidence: z.ZodString;
+                run: z.ZodString;
+                output: z.ZodString;
+                format: z.ZodEnum<{
+                    junit: "junit";
+                    ctrf: "ctrf";
+                    manifest: "manifest";
+                }>;
+                environment: z.ZodNullable<z.ZodString>;
+                publish: z.ZodString;
+                stream: z.ZodNullable<z.ZodString>;
+                prerequisites: z.ZodArray<z.ZodString>;
+            }, z.core.$loose>>;
+            files: z.ZodArray<z.ZodObject<{
+                path: z.ZodString;
+                action: z.ZodEnum<{
+                    create: "create";
+                    update: "update";
+                    unchanged: "unchanged";
+                }>;
+                purpose: z.ZodString;
+                content: z.ZodString;
+            }, z.core.$loose>>;
+            written: z.ZodArray<z.ZodString>;
+            verification: z.ZodNullable<z.ZodObject<{
+                reachable: z.ZodBoolean;
+                role: z.ZodNullable<z.ZodString>;
+                canPublish: z.ZodBoolean;
+                error: z.ZodNullable<z.ZodString>;
+            }, z.core.$loose>>;
+            nextSteps: z.ZodArray<z.ZodString>;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+    readonly publish: {
+        readonly command: "atlas report publish";
+        readonly schemaName: "publish-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            store: z.ZodString;
+            layer: z.ZodObject<{
+                id: z.ZodString;
+                producer: z.ZodString;
+                environment: z.ZodNullable<z.ZodString>;
+                checks: z.ZodNumber;
+                passed: z.ZodNumber;
+                failed: z.ZodNumber;
+                notRun: z.ZodNumber;
+                linkedToSpec: z.ZodNumber;
+                freshness: z.ZodOptional<z.ZodEnum<{
+                    unknown: "unknown";
+                    modified: "modified";
+                }>>;
+                attachmentFiles: z.ZodNumber;
+                attachmentBytes: z.ZodNumber;
+            }, z.core.$loose>;
+            specSet: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                files: z.ZodNumber;
+                branch: z.ZodNullable<z.ZodString>;
+            }, z.core.$loose>>;
+            run: z.ZodOptional<z.ZodObject<{
+                id: z.ZodString;
+                files: z.ZodNumber;
+                bytes: z.ZodNumber;
+                alreadyPublished: z.ZodBoolean;
+            }, z.core.$loose>>;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+    readonly stream: {
+        readonly command: "atlas report stream";
+        readonly schemaName: "stream-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            producer: z.ZodString;
+            environment: z.ZodNullable<z.ZodString>;
+            layers: z.ZodNumber;
+            checks: z.ZodNumber;
+            lost: z.ZodNumber;
+            warnings: z.ZodArray<z.ZodString>;
+        }, z.core.$loose>;
+    };
+    readonly merge: {
+        readonly command: "atlas report merge";
+        readonly schemaName: "merge-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<true>;
+            into: z.ZodString;
+            copied: z.ZodNumber;
+            skipped: z.ZodNumber;
+            ignored: z.ZodNumber;
+        }, z.core.$loose>;
+    };
+    readonly doctor: {
+        readonly command: "atlas report doctor";
+        readonly schemaName: "doctor-result";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodBoolean;
+            stores: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                checks: z.ZodArray<z.ZodObject<{
+                    name: z.ZodString;
+                    ok: z.ZodBoolean;
+                    detail: z.ZodString;
+                    fix: z.ZodOptional<z.ZodString>;
+                }, z.core.$loose>>;
+            }, z.core.$loose>>;
+        }, z.core.$loose>;
+    };
+    readonly status: {
+        readonly command: "atlas report status";
+        readonly schemaName: "report-status";
+        readonly schema: z.ZodObject<{
+            schemaVersion: z.ZodLiteral<1>;
+            ok: z.ZodBoolean;
+            reasons: z.ZodArray<z.ZodString>;
+            checks: z.ZodObject<{
+                passed: z.ZodNumber;
+                failed: z.ZodNumber;
+                running: z.ZodNumber;
+                'not-run': z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>;
+            byEnvironment: z.ZodRecord<z.ZodString, z.ZodObject<{
+                passed: z.ZodNumber;
+                failed: z.ZodNumber;
+                running: z.ZodNumber;
+                'not-run': z.ZodNumber;
+                total: z.ZodNumber;
+            }, z.core.$strip>>;
+            layers: z.ZodNumber;
+            backends: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                label: z.ZodString;
+                available: z.ZodBoolean;
+            }, z.core.$strip>>;
+            notices: z.ZodArray<z.ZodString>;
+            specsWithoutEvidence: z.ZodArray<z.ZodString>;
+            specs: z.ZodArray<z.ZodObject<{
+                path: z.ZodNullable<z.ZodString>;
+                title: z.ZodString;
+                kind: z.ZodString;
+                checks: z.ZodObject<{
+                    passed: z.ZodNumber;
+                    failed: z.ZodNumber;
+                    running: z.ZodNumber;
+                    'not-run': z.ZodNumber;
+                    total: z.ZodNumber;
+                }, z.core.$strip>;
+                byEnvironment: z.ZodRecord<z.ZodString, z.ZodObject<{
+                    passed: z.ZodNumber;
+                    failed: z.ZodNumber;
+                    running: z.ZodNumber;
+                    'not-run': z.ZodNumber;
+                    total: z.ZodNumber;
+                }, z.core.$strip>>;
+            }, z.core.$loose>>;
+            failing: z.ZodArray<z.ZodObject<{
+                spec: z.ZodNullable<z.ZodString>;
+                check: z.ZodString;
+                title: z.ZodString;
+                status: z.ZodEnum<{
+                    failed: "failed";
+                    running: "running";
+                }>;
+                environment: z.ZodNullable<z.ZodString>;
+                producer: z.ZodString;
+                branch: z.ZodNullable<z.ZodString>;
+                sha: z.ZodNullable<z.ZodString>;
+                layer: z.ZodString;
+                backend: z.ZodString;
+                runUrl: z.ZodNullable<z.ZodString>;
+                detail: z.ZodString;
+            }, z.core.$loose>>;
+        }, z.core.$loose>;
+    };
+    readonly error: {
+        readonly command: "a command that was wrong (standard error)";
+        readonly schemaName: "command-error";
+        readonly schema: z.ZodObject<{
+            ok: z.ZodLiteral<false>;
+            error: z.ZodObject<{
+                message: z.ZodString;
+                code: z.ZodLiteral<"usage">;
+            }, z.core.$loose>;
+        }, z.core.$loose>;
+    };
+};

package/dist/schema/src/cli-results.js

@@ -13,6 +13,7 @@
  * @see docs/agents.md
  */
 import { z } from 'zod/v4';
+import { ReportStatusSchema } from './layer.js';
 /** What was written for one layer by `atlas report publish`. */
 export const PublishedLayerSchema = z.looseObject({
     id: z.string().describe('The layer id: 64 hex digits, the SHA-256 of its content. Publishing the same input again gives the same id'),
@@ -122,3 +123,16 @@ export const InitPlanSchema = z.looseObject({
     nextSteps: z.array(z.string()).describe('What to do next, in order, as plain instructions an agent can follow'),
     warnings: z.array(z.string())
 });
+/**
+ * JSON command contracts, shared by schema publication, agent documentation and executable command checks.
+ * A new result needs an entry here and a runtime scenario in the documentation contract tests.
+ */
+export const CLI_RESULTS = {
+    init: { command: 'atlas init', schemaName: 'init-plan', schema: InitPlanSchema },
+    publish: { command: 'atlas report publish', schemaName: 'publish-result', schema: PublishResultSchema },
+    stream: { command: 'atlas report stream', schemaName: 'stream-result', schema: StreamResultSchema },
+    merge: { command: 'atlas report merge', schemaName: 'merge-result', schema: MergeResultSchema },
+    doctor: { command: 'atlas report doctor', schemaName: 'doctor-result', schema: DoctorResultSchema },
+    status: { command: 'atlas report status', schemaName: 'report-status', schema: ReportStatusSchema },
+    error: { command: 'a command that was wrong (standard error)', schemaName: 'command-error', schema: CommandErrorSchema }
+};

package/dist/server/src/llms.js

@@ -6,6 +6,7 @@
  * address, whether it needs a token), so what it says is true of the server that says it, and it points at the
  * machine-readable description (`/api/openapi.json`) rather than repeating it.
  */
+import { packageManagerTable } from '../../reports/src/package-managers.js';
 /** The guide for one server, Markdown. Stable in structure: an agent may read it by its headings. */
 export function llmsTxt(context) {
     const { url } = context;
@@ -28,27 +29,35 @@ ${context.open
 
 ## Integrate a project (run in the project's repository)
 
+Install \`@crvouga/atlas\` with the project's existing package manager first. The commands below use Bun;
+substitute the executor for your package manager. Node also runs the CLI; Bun is optional. Read the installed
+\`docs/agents.md\` for the supported runtime versions and full integration playbook.
+
+${packageManagerTable()}
+
 \`\`\`sh
+bun add -d @crvouga/atlas
 export ATLAS_STORE=${url}${context.open ? '' : '\nexport ATLAS_TOKEN=<a publish token>'}
-bunx @crvouga/atlas init --server ${url}          # detects test runners and specs, prints a plan (add --json for a machine-readable one)
-bunx @crvouga/atlas init --server ${url} --write  # writes the CI workflow and the AGENTS.md section the plan names
-bunx @crvouga/atlas report doctor                 # proves the server can be written to and read
+export ATLAS_PROJECT=checkout-service          # choose the same stable slug locally and in CI
+bunx atlas init --server ${url}                # detects test runners and specs, prints a plan (add --json for a machine-readable one)
+bunx atlas init --server ${url} --write        # writes the CI workflow and the AGENTS.md section the plan names
+bunx atlas report doctor                       # proves the server can be written to and read
 \`\`\`
 
 After each suite, send its results (a JUnit or CTRF file, or JSON lines as checks finish):
 
 \`\`\`sh
-bunx @crvouga/atlas report publish --producer <suite> --junit out.xml --specs ./specs --environment <env>
-my-suite --json | bunx @crvouga/atlas report stream --producer <suite> --environment <env>
+bunx atlas report publish --producer <suite> --junit out.xml --specs ./specs --environment <env>
+my-suite --json | bunx atlas report stream --producer <suite> --environment <env>
 \`\`\`
 
-Or with no tooling at all: \`POST ${url}/api/checks\` with \`{"producer":"smoke","checks":[{"id":"login","title":"can log in","status":"passed"}]}\`.
+Or with no tooling at all: \`POST ${url}/api/checks?project=<slug>\` with \`{"producer":"smoke","checks":[{"id":"login","title":"can log in","status":"passed"}]}\`.
 
 ## Ask whether it passes
 
 \`\`\`sh
-bunx @crvouga/atlas report status --format json --branch main --ignore-modified   # exit 0 pass, 1 does not, 2 wrong command
-curl ${context.open ? '' : '-H "authorization: Bearer $ATLAS_TOKEN" '}${url}/api/status                      # the same verdict; header X-Atlas-Ok: true|false
+bunx atlas report status --format json --branch main --ignore-modified   # exit 0 pass, 1 does not, 2 wrong command
+curl ${context.open ? '' : '-H "authorization: Bearer $ATLAS_TOKEN" '}"${url}/api/status?project=$ATLAS_PROJECT"    # the same verdict; header X-Atlas-Ok: true|false
 \`\`\`
 
 ## Rules worth knowing