@progen-labs/spectra 0.5.0 → 0.7.0

package/dist/index.html

@@ -5,7 +5,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Performance Profiler</title>
     <link rel="icon" href="data:," />
-    <script type="module" crossorigin src="/assets/index-mtYxDBW7.js"></script>
+    <script type="module" crossorigin src="/assets/index-BDIjT029.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-z14kjW8r.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@progen-labs/spectra",
-  "version": "0.5.0",
+  "version": "0.7.0",
   "description": "Spectra — a Chrome DevTools Protocol profiler that identifies the files, functions and components causing frontend slowness, across React, Vue, Svelte, Angular and Next.js builds.",
   "type": "module",
   "bin": {
@@ -18,12 +18,14 @@
     "server",
     "shared",
     "schema",
+    "agents",
     "src",
     "dist",
     "index.html",
     "vite.config.js",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "spectra": "node bin/spectra.js",
@@ -34,10 +36,13 @@
     "profile": "node server/cli.js",
     "test": "node --test \"server/**/test-*.js\" \"action/test-*.js\"",
     "test:vscode": "npm --prefix vscode test",
-    "bench": "node bench/run.mjs"
+    "bench": "node bench/run.mjs",
+    "size": "npm run build && node scripts/size-report.mjs",
+    "lint": "eslint .",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include=\"server/**\" --test-coverage-include=\"shared/**\" --test-coverage-include=\"bin/**\" --test-coverage-exclude=\"**/test-*.js\" --test-coverage-exclude=\"server/probe.browser.js\" --test-coverage-lines=70 --test-coverage-branches=70 --test-coverage-functions=72 \"server/**/test-*.js\" \"action/test-*.js\""
   },
   "engines": {
-    "node": ">=18"
+    "node": ">=22.12"
   },
   "keywords": [
     "performance",
@@ -61,7 +66,7 @@
   ],
   "author": "Progen Labs (Sourav Debnath)",
   "license": "MIT",
-  "homepage": "https://github.com/progen-labs/spectra#readme",
+  "homepage": "https://progen-labs.github.io/website/#spectra",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/progen-labs/spectra.git"
@@ -77,12 +82,32 @@
     "puppeteer-core": "^25.13.0"
   },
   "devDependencies": {
+    "@eslint/js": "^9.39.5",
     "@modelcontextprotocol/sdk": "^1.32.1",
+    "@size-limit/file": "^14.2.0",
     "@vitejs/plugin-react": "^6.1.2",
     "d3": "^7.9.0",
+    "eslint": "^9.39.5",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "globals": "^17.13.0",
     "highlight.js": "^11.10.0",
+    "publint": "^0.3.25",
     "react": "^18.3.1",
     "react-dom": "^18.3.1",
+    "size-limit": "^14.2.0",
     "vite": "^8.3.4"
-  }
+  },
+  "size-limit": [
+    {
+      "name": "Dashboard JavaScript (brotli)",
+      "path": "dist/assets/*.js",
+      "limit": "115 kB"
+    },
+    {
+      "name": "Dashboard CSS (brotli)",
+      "path": "dist/assets/*.css",
+      "limit": "10 kB"
+    }
+  ]
 }

package/schema/config.schema.json

@@ -139,6 +139,30 @@
           "description": "How long to wait for a manual sign-in (default 300)"
         }
       }
+    },
+    "agentDocs": {
+      "description": "Spectra's knowledge doc for AI agents, written the first time Spectra runs in the project (see `spectra agents`). false: never write it; a list: only for these agents. Left out: AGENTS.md and the agents this project or machine uses.",
+      "oneOf": [
+        {
+          "type": "boolean"
+        },
+        {
+          "type": "array",
+          "items": {
+            "enum": [
+              "agents-md",
+              "claude",
+              "cursor",
+              "copilot",
+              "windsurf",
+              "cline",
+              "roo",
+              "gemini"
+            ]
+          },
+          "uniqueItems": true
+        }
+      ]
     }
   }
 }

package/schema/result.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://unpkg.com/@progen-labs/spectra/schema/result.schema.json",
   "title": "Spectra result",
-  "description": "What `spectra … --json` prints and `--out` writes. A small envelope that points at the full reports on disk. Additive changes keep schemaVersion; breaking changes bump it.",
+  "description": "What `spectra \u2026 --json` prints and `--out` writes. A small envelope that points at the full reports on disk. Additive changes keep schemaVersion; breaking changes bump it.",
   "type": "object",
   "required": [
     "schemaVersion",
@@ -19,7 +19,8 @@
         "profile",
         "evaluation",
         "compare",
-        "reports"
+        "reports",
+        "improve"
       ]
     },
     "spectraVersion": {
@@ -81,6 +82,18 @@
       "then": {
         "$ref": "#/$defs/reports"
       }
+    },
+    {
+      "if": {
+        "properties": {
+          "kind": {
+            "const": "improve"
+          }
+        }
+      },
+      "then": {
+        "$ref": "#/$defs/improve"
+      }
     }
   ],
   "$defs": {
@@ -258,7 +271,7 @@
             "string",
             "null"
           ],
-          "description": "exact, or located (≈, found by searching the source)."
+          "description": "exact, or located (\u2248, found by searching the source)."
         },
         "abs": {
           "type": [
@@ -744,6 +757,54 @@
           }
         }
       }
+    },
+    "improve": {
+      "type": "object",
+      "description": "One step of a guided `spectra improve` session (next, check, report or stop): the text shown to whoever makes the changes, and the session state.",
+      "required": [
+        "step",
+        "message",
+        "session"
+      ],
+      "properties": {
+        "step": {
+          "enum": [
+            "next",
+            "check",
+            "report",
+            "stop"
+          ]
+        },
+        "message": {
+          "type": "string",
+          "description": "What was printed: the problem to fix, the verdict on a change, or the report."
+        },
+        "task": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "The problem to work on now, if any: title, file, line, severity, impactMs, fix, culprits."
+        },
+        "attempt": {
+          "type": "object",
+          "description": "check only: the change just measured, with outcome (kept, no-gain, slower, mixed, new-problem, unproven, checks-failed) and reason."
+        },
+        "result": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "report and stop: the overall before \u2192 after (verdict, confidence, headlines) when something was kept."
+        },
+        "session": {
+          "type": [
+            "object",
+            "null"
+          ],
+          "description": "The whole session: baseline, current (the result files of the latest kept state), queue, task, attempts, skipped, kept."
+        }
+      }
     }
   }
 }

package/server/agents-cli.js

@@ -0,0 +1,70 @@
+/**
+ * spectra agents: puts Spectra's knowledge doc where AI agents read their
+ * project instructions (server/agents.js), or takes it out again.
+ *
+ *   spectra agents                 the agents this project or machine uses, and AGENTS.md
+ *   spectra agents --all           every supported agent
+ *   spectra agents --only claude,copilot
+ *   spectra agents --remove        take it out of every agent's files
+ *   spectra agents --list          the supported agents, and which ones were detected
+ *   spectra agents --print         print the knowledge doc
+ *   … --dir <project>  --dry-run
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { parseArgs } from './args.js';
+import { TARGETS, TARGET_IDS, describe, detectTargets, installAgentDocs, knowledge, removeAgentDocs, writeNote } from './agents.js';
+
+const { opt, flag } = parseArgs(process.argv.slice(2), { values: ['dir', 'only'] });
+const root = path.resolve(opt('dir', process.cwd()));
+const dryRun = flag('dry-run');
+
+if (flag('help') || process.argv.includes('-h')) {
+  console.log(`usage: spectra agents [--all | --only <ids>] [--remove] [--list] [--print] [--dir <project>] [--dry-run]
+
+Teaches your AI agents about Spectra: what it does, which command answers which
+request, and how to read the results. It writes Spectra's knowledge doc where
+each agent reads its project instructions, so you can ask in plain words
+("why is checkout slow?", "did my change help?") and the agent runs Spectra.
+It happens by itself the first time Spectra runs in a project; this does it by hand.
+
+Agents: ${TARGET_IDS.join(', ')}
+Off for a project: "agentDocs": false in spectra.config.json (or SPECTRA_AGENT_DOCS=0).`);
+  process.exit(0);
+}
+
+if (flag('print')) {
+  console.log(knowledge());
+  process.exit(0);
+}
+
+if (flag('list')) {
+  const found = new Set(detectTargets({ root }));
+  for (const t of TARGETS) console.log(`  ${found.has(t.id) ? '✓' : ' '} ${t.id.padEnd(10)} ${t.file.padEnd(46)} ${t.name}`);
+  console.log('\n✓ = written by default (detected in this project or on this machine). --all writes every one.');
+  process.exit(0);
+}
+
+if (flag('remove')) {
+  const results = removeAgentDocs({ root, dryRun });
+  // and don't bring them back on the next run
+  if (!dryRun) writeNote(root, { removed: true });
+  console.log(results.length ? `${dryRun ? 'Would remove' : 'Removed'} Spectra's knowledge doc:\n${describe(results)}` : 'Nothing to remove.');
+  process.exit(0);
+}
+
+let targets;
+if (flag('all')) targets = TARGET_IDS;
+else if (opt('only')) {
+  targets = String(opt('only')).split(',').map(s => s.trim()).filter(Boolean);
+  const unknown = targets.filter(id => !TARGET_IDS.includes(id));
+  if (unknown.length) {
+    console.error(`spectra: unknown agent ${unknown.join(', ')} (known: ${TARGET_IDS.join(', ')})`);
+    process.exit(1);
+  }
+}
+const results = installAgentDocs({ root, targets, dryRun });
+if (!dryRun) writeNote(root, { version: JSON.parse(fs.readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version });
+console.log(`${dryRun ? 'Would write' : 'Wrote'} Spectra's knowledge doc for your AI agents:\n${describe(results)}`);
+console.log('\nAsk your agent in plain words, e.g. "why is the checkout page slow?" or "did my last change make it faster?".');
+console.log('Remove it with: npx spectra agents --remove');

package/server/agents.js

@@ -0,0 +1,335 @@
+/**
+ * Teaches AI coding agents about Spectra. The knowledge doc (agents/spectra.md:
+ * what Spectra does, which command answers which request, how to read the
+ * results, the rules) is written where each agent reads its project
+ * instructions, so a user can just ask in plain words ("why is checkout
+ * slow?", "did my change help?") and the agent runs the right Spectra command.
+ *
+ * Written the first time Spectra runs in a project it is installed in (no
+ * install script, so package managers and supply-chain scanners have nothing
+ * to flag), refreshed when Spectra updates, and on demand with `spectra agents`.
+ *
+ * Files Spectra owns carry a `spectra:managed` marker and are replaced on
+ * update; in shared files (AGENTS.md, CLAUDE.md, GEMINI.md) only the block
+ * between the `spectra:start` and `spectra:end` markers is touched. A file
+ * without the marker is never overwritten, and `--remove` takes everything
+ * back out, leaving the rest of each file as it was.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const PKG_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+export const DOC_FILE = path.join(PKG_ROOT, 'agents', 'spectra.md');
+const VERSION = JSON.parse(fs.readFileSync(path.join(PKG_ROOT, 'package.json'), 'utf8')).version;
+
+const MANAGED = 'spectra:managed';
+const START = '<!-- spectra:start -->';
+const END = '<!-- spectra:end -->';
+const note = `written by @progen-labs/spectra ${VERSION} and replaced when it updates; remove with: npx spectra agents --remove`;
+const DESCRIPTION =
+  'Spectra (@progen-labs/spectra, installed in this project) measures and improves frontend performance. Use it when the user asks why the app or a page is slow, about jank, re-renders, long tasks, load time or Web Vitals (LCP, TBT, CLS, INP), to profile a page or an interaction, to prove that a change made things faster, to set performance budgets, or to profile pages behind a login.';
+
+/** The knowledge doc, with its headings one level deeper when it sits inside another file. */
+export function knowledge({ nested = false } = {}) {
+  const doc = fs.readFileSync(DOC_FILE, 'utf8').trim();
+  return nested ? doc.replace(/^(#{1,5}) /gm, '#$1 ') : doc;
+}
+
+const frontmatter = fields =>
+  `---\n${Object.entries(fields)
+    .map(([k, v]) => (v === '' ? `${k}:` : `${k}: ${v}`))
+    .join('\n')}\n---\n`;
+const ownFile = (head = '') => `${head}<!-- ${MANAGED}: ${note} -->\n\n${knowledge()}\n`;
+const quoted = s => JSON.stringify(s);
+
+/**
+ * Where each agent reads project instructions. `home` and `project` are the
+ * signs that the agent is in use: a folder or file in the user's home, or in
+ * the project. AGENTS.md, the cross-agent standard, is always written.
+ */
+export const TARGETS = [
+  {
+    id: 'agents-md',
+    name: 'AGENTS.md (Codex, GitHub Copilot, Cursor, Windsurf, Zed, Jules, Amp and other agents)',
+    file: 'AGENTS.md',
+    block: () => knowledge({ nested: true }),
+    always: true,
+  },
+  {
+    id: 'claude',
+    name: 'Claude Code',
+    file: '.claude/skills/spectra/SKILL.md',
+    content: () => ownFile(frontmatter({ name: 'spectra', description: quoted(DESCRIPTION) })),
+    // and a short note in its memory file, which it always reads
+    also: {
+      file: 'CLAUDE.md',
+      block: () =>
+        '## Spectra (performance)\n\nThis project has Spectra (`@progen-labs/spectra`) installed. For anything about speed, slowness, re-renders, Web Vitals or proving that a change made things faster, follow the `spectra` skill (`.claude/skills/spectra/SKILL.md`) and measure with `npx spectra …` instead of guessing.',
+    },
+    project: ['CLAUDE.md', '.claude'],
+    home: ['.claude', '.claude.json'],
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor',
+    file: '.cursor/rules/spectra.mdc',
+    content: () => ownFile(frontmatter({ description: quoted(DESCRIPTION), globs: '', alwaysApply: 'false' })),
+    project: ['.cursor', '.cursorrules'],
+    home: ['.cursor'],
+  },
+  {
+    id: 'copilot',
+    name: 'GitHub Copilot (VS Code, Visual Studio, JetBrains, the coding agent)',
+    file: '.github/instructions/spectra.instructions.md',
+    content: () => ownFile(frontmatter({ applyTo: quoted('**'), description: quoted(DESCRIPTION) })),
+    project: ['.github/copilot-instructions.md', '.github/instructions', '.github/prompts', '.vscode'],
+    home: ['.vscode', '.vscode-insiders', '.config/github-copilot'],
+  },
+  {
+    id: 'windsurf',
+    name: 'Windsurf',
+    file: '.windsurf/rules/spectra.md',
+    content: () => ownFile(frontmatter({ trigger: 'model_decision', description: quoted(DESCRIPTION) })),
+    project: ['.windsurf', '.windsurfrules'],
+    home: ['.codeium/windsurf'],
+  },
+  {
+    id: 'cline',
+    name: 'Cline',
+    file: '.clinerules/spectra.md',
+    content: () => ownFile(),
+    project: ['.clinerules'],
+    home: ['Documents/Cline'],
+  },
+  {
+    id: 'roo',
+    name: 'Roo Code',
+    file: '.roo/rules/spectra.md',
+    content: () => ownFile(),
+    project: ['.roo', '.roorules'],
+    home: ['.roo'],
+  },
+  {
+    id: 'gemini',
+    name: 'Gemini CLI',
+    file: 'GEMINI.md',
+    block: () => knowledge({ nested: true }),
+    project: ['GEMINI.md', '.gemini'],
+    home: ['.gemini'],
+  },
+];
+export const TARGET_IDS = TARGETS.map(t => t.id);
+
+const exists = p => {
+  try {
+    fs.statSync(p);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+/** The agents this project or machine uses, plus AGENTS.md. */
+export function detectTargets({ root, home = os.homedir() }) {
+  return TARGETS.filter(
+    t => t.always || (t.project || []).some(p => exists(path.join(root, p))) || (t.home || []).some(p => home && exists(path.join(home, p))),
+  ).map(t => t.id);
+}
+
+/** What `agentDocs` in spectra.config.json asks for: false (none), an array of target ids, or undefined (the default). */
+export function readAgentDocsSetting(root) {
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(root, 'spectra.config.json'), 'utf8'));
+    return config?.agentDocs;
+  } catch {
+    return undefined;
+  }
+}
+
+const blockText = text => `${START}\n<!-- ${note} -->\n\n${text}\n${END}`;
+
+// where Spectra's block is in a shared file: [start, end), or null
+function findBlock(text) {
+  const i = text.indexOf(START);
+  const j = i < 0 ? -1 : text.indexOf(END, i);
+  return i < 0 || j < 0 ? null : [i, j + END.length];
+}
+
+// the file without Spectra's block, and the blank lines it was set apart with
+function withoutBlock(text) {
+  const [i, j] = findBlock(text);
+  const head = text.slice(0, i).replace(/\s*$/, '');
+  const tail = text.slice(j).replace(/^\s*/, '');
+  const rest = head && tail ? `${head}\n\n${tail}` : head || tail;
+  return rest ? `${rest.replace(/\s*$/, '')}\n` : '';
+}
+
+function writeBlock(file, text, dryRun) {
+  const before = exists(file) ? fs.readFileSync(file, 'utf8') : null;
+  const block = blockText(text);
+  const at = before == null ? null : findBlock(before);
+  const after =
+    before == null
+      ? `${block}\n`
+      : at
+        ? `${before.slice(0, at[0])}${block}${before.slice(at[1])}` // in place: the rest stays exactly as it was
+        : `${before.replace(/\s*$/, '')}${before.trim() ? '\n\n' : ''}${block}\n`;
+  if (after === before) return 'unchanged';
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, after);
+  }
+  return before == null ? 'created' : 'updated';
+}
+
+function writeOwn(file, content, dryRun) {
+  const before = exists(file) ? fs.readFileSync(file, 'utf8') : null;
+  if (before != null && !before.includes(MANAGED)) return 'skipped (a file of yours is already there)';
+  if (before === content) return 'unchanged';
+  if (!dryRun) {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, content);
+  }
+  return before == null ? 'created' : 'updated';
+}
+
+/**
+ * Writes the knowledge doc for the given targets (default: the detected ones).
+ * Returns [{ id, name, file, result }], result being created, updated,
+ * unchanged or skipped (…).
+ */
+export function installAgentDocs({ root, targets, home, dryRun = false } = {}) {
+  const ids = targets || detectTargets({ root, home });
+  const out = [];
+  for (const t of TARGETS.filter(x => ids.includes(x.id))) {
+    const file = path.join(root, t.file);
+    out.push({ id: t.id, name: t.name, file: t.file, result: t.block ? writeBlock(file, t.block(), dryRun) : writeOwn(file, t.content(), dryRun) });
+    if (t.also) out.push({ id: t.id, name: t.name, file: t.also.file, result: writeBlock(path.join(root, t.also.file), t.also.block(), dryRun) });
+  }
+  return out;
+}
+
+// removes now-empty folders Spectra made, up to (not including) the project root
+function pruneDirs(dir, root) {
+  while (dir.startsWith(root) && dir !== root) {
+    try {
+      if (fs.readdirSync(dir).length) return;
+      fs.rmdirSync(dir);
+    } catch {
+      return;
+    }
+    dir = path.dirname(dir);
+  }
+}
+
+/** Takes the knowledge doc out of every agent's files; the rest of each file stays. */
+export function removeAgentDocs({ root, dryRun = false } = {}) {
+  const out = [];
+  const files = TARGETS.flatMap(t => [{ t, file: t.file, block: !!t.block }, ...(t.also ? [{ t, file: t.also.file, block: true }] : [])]);
+  for (const { t, file: rel, block } of files) {
+    const file = path.join(root, rel);
+    if (!exists(file)) continue;
+    const text = fs.readFileSync(file, 'utf8');
+    if (block) {
+      if (!findBlock(text)) continue;
+      const rest = withoutBlock(text);
+      if (!dryRun) {
+        if (rest) fs.writeFileSync(file, rest);
+        else fs.rmSync(file); // Spectra made it: nothing else was in it
+      }
+      out.push({ id: t.id, name: t.name, file: rel, result: rest ? 'removed' : 'deleted' });
+    } else if (text.includes(MANAGED)) {
+      if (!dryRun) {
+        fs.rmSync(file);
+        pruneDirs(path.dirname(file), root);
+      }
+      out.push({ id: t.id, name: t.name, file: rel, result: 'deleted' });
+    }
+  }
+  return out;
+}
+
+// what Spectra did in a project, so it acts once per version and never undoes a removal
+const noteFile = root => path.join(root, '.spectra', 'agent-docs.json');
+const readNote = root => {
+  try {
+    return JSON.parse(fs.readFileSync(noteFile(root), 'utf8'));
+  } catch {
+    return null;
+  }
+};
+export function writeNote(root, note) {
+  try {
+    fs.mkdirSync(path.dirname(noteFile(root)), { recursive: true });
+    fs.writeFileSync(noteFile(root), `${JSON.stringify({ ...note, at: new Date().toISOString() }, null, 2)}\n`);
+  } catch {}
+}
+
+/**
+ * Should this run of `spectra` write the docs? Only in a project Spectra is
+ * installed in (its node_modules holds this copy of Spectra, and the command
+ * runs inside it): not under `npx` from its cache, not a global install, not
+ * Spectra's own repository, not in CI, and not when the user opted out or
+ * removed the docs. Once per Spectra version: the first run writes them for
+ * the agents in use; after an update, only what is already there is refreshed.
+ */
+export function firstRunPlan({ cwd = process.cwd(), env = process.env, pkgRoot = PKG_ROOT } = {}) {
+  if (env.SPECTRA_AGENT_DOCS === '0' || env.SPECTRA_AGENT_DOCS === 'false') return { skip: 'SPECTRA_AGENT_DOCS=0' };
+  if (env.CI && env.CI !== 'false' && env.CI !== '0') return { skip: 'CI' };
+  const real = (() => {
+    try {
+      return fs.realpathSync(pkgRoot);
+    } catch {
+      return path.resolve(pkgRoot);
+    }
+  })();
+  const at = real.indexOf(`${path.sep}node_modules${path.sep}`);
+  if (at < 0) return { skip: "not installed from npm (Spectra's own repository)" };
+  const root = real.slice(0, at);
+  const here = (() => {
+    try {
+      return fs.realpathSync(cwd);
+    } catch {
+      return path.resolve(cwd);
+    }
+  })();
+  if (here !== root && !here.startsWith(root + path.sep)) return { skip: 'not run inside the project Spectra is installed in (npx or a global install)' };
+  if (!exists(path.join(root, 'package.json'))) return { skip: 'no package.json' };
+  const setting = readAgentDocsSetting(root);
+  if (setting === false) return { skip: '"agentDocs": false in spectra.config.json' };
+  const note = readNote(root);
+  if (note?.removed) return { skip: 'removed with `spectra agents --remove`' };
+  if (note?.version === VERSION) return { skip: 'already done for this version' };
+  return { root, mode: note ? 'refresh' : 'install', targets: Array.isArray(setting) ? setting.filter(id => TARGET_IDS.includes(id)) : undefined };
+}
+
+/** Rewrites only the Spectra content that is already in the project (after an update). */
+export function refreshAgentDocs({ root, dryRun = false } = {}) {
+  const out = [];
+  for (const t of TARGETS) {
+    const files = [{ file: t.file, write: f => (t.block ? writeBlock(f, t.block(), dryRun) : writeOwn(f, t.content(), dryRun)) }];
+    if (t.also) files.push({ file: t.also.file, write: f => writeBlock(f, t.also.block(), dryRun) });
+    for (const { file: rel, write } of files) {
+      const file = path.join(root, rel);
+      if (!exists(file)) continue;
+      const text = fs.readFileSync(file, 'utf8');
+      if (!findBlock(text) && !text.includes(MANAGED)) continue;
+      out.push({ id: t.id, name: t.name, file: rel, result: write(file) });
+    }
+  }
+  return out;
+}
+
+/** The first-run step: does what firstRunPlan says, and remembers it. Returns the files it changed. */
+export function ensureAgentDocs(opts = {}) {
+  const plan = firstRunPlan(opts);
+  if (plan.skip) return { skip: plan.skip, changed: [] };
+  const results = plan.mode === 'install' ? installAgentDocs({ root: plan.root, targets: plan.targets }) : refreshAgentDocs({ root: plan.root });
+  writeNote(plan.root, { version: VERSION });
+  return { root: plan.root, changed: results.filter(r => r.result === 'created' || r.result === 'updated') };
+}
+
+/** One line per file, for people. */
+export const describe = results => results.map(r => `  ${r.result.padEnd(9)} ${r.file}  (${r.name})`).join('\n');

package/server/explore/boot.js

@@ -8,6 +8,8 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 
+// terminal colour codes in the dev server's output
+// eslint-disable-next-line no-control-regex
 const ANSI = /\x1b\[[0-9;]*m/g;
 const URL_RE =
   /(https?:\/\/(?:localhost|127\.0\.0\.1|0\.0\.0\.0)(?::\d+)?[^\s)'"<]*)/i;