@thecolonylab/hivemind 0.1.0 → 0.2.0

package/dist/commands/coverage.js

@@ -6,6 +6,7 @@ import { checkCoverageLocally } from './coverageLocal.js';
 import { saveTestFile, slugify } from '../testFile/write.js';
 import { loadAllTestsFull } from '../testFile/loadAllTests.js';
 import { renderCoveragePrComment } from '../report/prComment.js';
+import { loadConfig } from '../config.js';
 /**
  * The actual diff-aware check: reads the real code diff (not just filenames), sends it — plus
  * every local test with its full steps — to the server. The server figures out which known
@@ -23,6 +24,7 @@ export async function coverageCommand(opts) {
     }
     const diff = getFullDiff(cwd, base);
     const localTests = await loadAllTestsFull(cwd);
+    const config = await loadConfig(cwd);
     const serverUrl = process.env.HIVEMIND_SERVER_URL || 'https://app.thecolonylab.com';
     console.log(`🐝 Scout reading the diff (${changedFiles.length} file${changedFiles.length === 1 ? '' : 's'} changed vs ${base})...`);
     if (opts.local) {
@@ -31,15 +33,15 @@ export async function coverageCommand(opts) {
     let result;
     try {
         result = opts.local
-            ? await checkCoverageLocally({ serverUrl, diff, localTests, headed: opts.headed })
-            : await coverageOnServer(diff, localTests);
+            ? await checkCoverageLocally({ serverUrl, diff, localTests, headed: opts.headed, projectId: config.projectId, projectName: config.projectName })
+            : await coverageOnServer(diff, localTests, config.projectId, config.projectName);
     }
     catch (err) {
         console.error(err.message);
         process.exitCode = 2;
         return;
     }
-    // The server only knows its own path (e.g. /artifacts/...) — it has no idea what URL you're
+    // The server only knows its own path (e.g. /runs/...) — it has no idea what URL you're
     // reaching it at (localhost in dev, a real domain in prod), so the full link gets built here.
     for (const page of result.affectedPages) {
         for (const t of page.testsRun) {

package/dist/commands/coverageLocal.js

@@ -21,7 +21,7 @@ export async function checkCoverageLocally(opts) {
                 headers.Authorization = `Bearer ${apiKey}`;
             const socket = new WebSocket(wsUrl, { headers });
             socket.on('open', () => {
-                socket.send(JSON.stringify({ type: 'start', diff: opts.diff, localTests: opts.localTests }));
+                socket.send(JSON.stringify({ type: 'start', diff: opts.diff, localTests: opts.localTests, projectId: opts.projectId, projectName: opts.projectName }));
             });
             socket.on('message', async (raw) => {
                 let msg;

package/dist/commands/create.js

@@ -10,7 +10,7 @@ export async function createCommand(request, opts) {
     const accountLabels = Object.keys(config.accounts || {});
     let proposed;
     try {
-        proposed = await createOnServer(request, opts.url, existingTests, accountLabels);
+        proposed = await createOnServer(request, opts.url, existingTests, accountLabels, config.projectId);
     }
     catch (err) {
         console.error(err.message);

package/dist/commands/explore.js

@@ -2,6 +2,7 @@ import { join } from 'node:path';
 import { exploreOnServer } from '../serverClient.js';
 import { saveTestFile, slugify } from '../testFile/write.js';
 import { listExistingTests } from '../testFile/listExisting.js';
+import { loadConfig } from '../config.js';
 /**
  * A real multi-page crawl, not a one-shot snapshot — the server maps pages, follows doors, and
  * proposes starter tests along the way. Existing tests are sent along (same pattern `create`
@@ -9,10 +10,12 @@ import { listExistingTests } from '../testFile/listExisting.js';
  */
 export async function exploreCommand(url, opts) {
     console.log(`🐝 Scout dispatched to ${url}...`);
-    const existingTests = await listExistingTests(process.cwd());
+    const cwd = process.cwd();
+    const existingTests = await listExistingTests(cwd);
+    const config = await loadConfig(cwd);
     let proposed;
     try {
-        proposed = await exploreOnServer(url, existingTests);
+        proposed = await exploreOnServer(url, existingTests, config.projectId, config.projectName);
     }
     catch (err) {
         console.error(err.message);

package/dist/commands/init.js

@@ -1,6 +1,10 @@
 import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
+import { dirname, join, basename } from 'node:path';
 import { mkdir, readFile, writeFile, copyFile, access } from 'node:fs/promises';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { randomBytes } from 'node:crypto';
+const execFileAsync = promisify(execFile);
 const __dirname = dirname(fileURLToPath(import.meta.url));
 // dist/commands/init.js -> package root (skill/ ships alongside dist/, see package.json "files")
 const packageRoot = join(__dirname, '..', '..');
@@ -9,6 +13,53 @@ async function exists(path) {
         .then(() => true)
         .catch(() => false);
 }
+/**
+ * Cloud mode (the default) never touches Playwright on this machine at all — the browser lives on
+ * the server. But `--local` mode does, and the starter hivemind.config.json defaults to
+ * localhost:3000, so most fresh projects are headed toward --local sooner or later. Checking here
+ * means the first `--local` run doesn't stall on an unexpected multi-minute download mid-test —
+ * `chromium.executablePath()` is a cheap path lookup, not a launch, so this stays fast when the
+ * browser's already installed (every run after the first).
+ */
+async function ensureLocalBrowser() {
+    const { chromium } = await import('playwright');
+    const installed = await exists(chromium.executablePath());
+    if (installed) {
+        console.log('✓ local browser (for --local mode) already installed');
+        return;
+    }
+    console.log('⧗ downloading local browser for --local mode (one-time, ~150MB)...');
+    try {
+        await execFileAsync('npx', ['playwright', 'install', 'chromium']);
+        console.log('✓ local browser installed');
+    }
+    catch (err) {
+        console.log(`- couldn't auto-install the local browser (${err?.message || err}) — run \`npx playwright install chromium\` yourself before using --local`);
+    }
+}
+const GITIGNORE_BLOCK = `# HIVEMIND:START
+# hivemind local state — real evidence (screenshots, run history, folded-in memory), but not
+# meant to be reviewed in a PR the way hive/tests/ is. Regenerated by every run, safe to delete.
+hive/history/
+hive/artifacts/
+hive/memory.md
+hive/last-run.json
+# HIVEMIND:END
+`;
+/** One hive/ folder for everything — tests/ is the only part meant to be committed and reviewed;
+ *  history/, artifacts/, memory.md, and last-run.json are local-only, excluded here rather than
+ *  living in a separate dot-prefixed folder. */
+async function ensureGitignore(cwd) {
+    const path = join(cwd, '.gitignore');
+    const existing = (await exists(path)) ? await readFile(path, 'utf-8') : '';
+    if (existing.includes('# HIVEMIND:START')) {
+        console.log('- .gitignore already has the hivemind block, left untouched');
+        return;
+    }
+    const updated = existing ? `${existing.trimEnd()}\n\n${GITIGNORE_BLOCK}` : GITIGNORE_BLOCK;
+    await writeFile(path, updated, 'utf-8');
+    console.log(existing ? '✓ .gitignore updated so hive/history, artifacts, memory stay local-only' : '✓ .gitignore created so hive/history, artifacts, memory stay local-only');
+}
 /**
  * One-time setup for a project adopting hivemind — matches TesterArmy's `ta agent init` pattern.
  * Idempotent: safe to run again later, never overwrites something already there.
@@ -17,18 +68,33 @@ export async function initCommand() {
     const cwd = process.cwd();
     await mkdir(join(cwd, 'hive', 'tests'), { recursive: true });
     console.log('✓ hive/tests/ ready');
+    await ensureGitignore(cwd);
     const configPath = join(cwd, 'hivemind.config.json');
     if (await exists(configPath)) {
-        console.log('- hivemind.config.json already exists, left untouched');
+        // Patch in a projectId even for a config that predates this field — without it, every
+        // request to the server would look like it belongs to no project at all (or worse, get
+        // lumped in with other projects on the same account that also lack one).
+        const existing = JSON.parse(await readFile(configPath, 'utf-8'));
+        if (existing.projectId) {
+            console.log('- hivemind.config.json already exists, left untouched');
+        }
+        else {
+            existing.projectId = randomBytes(8).toString('hex');
+            existing.projectName ??= basename(cwd);
+            await writeFile(configPath, JSON.stringify(existing, null, 2) + '\n', 'utf-8');
+            console.log(`✓ hivemind.config.json — added a projectId (project name: "${existing.projectName}")`);
+        }
     }
     else {
         const starter = {
+            projectId: randomBytes(8).toString('hex'),
+            projectName: basename(cwd),
             environments: { default: 'http://localhost:3000' },
             accounts: {},
             areas: {},
         };
         await writeFile(configPath, JSON.stringify(starter, null, 2) + '\n', 'utf-8');
-        console.log('✓ hivemind.config.json created — edit environments.default to match your app');
+        console.log(`✓ hivemind.config.json created (project name: "${starter.projectName}") — edit environments.default to match your app`);
     }
     const agentsPath = join(cwd, 'AGENTS.md');
     const template = await readFile(join(packageRoot, 'skill', 'AGENTS.md.template'), 'utf-8');
@@ -45,6 +111,7 @@ export async function initCommand() {
     await mkdir(skillDir, { recursive: true });
     await copyFile(join(packageRoot, 'skill', 'hivemind-cli', 'SKILL.md'), join(skillDir, 'SKILL.md'));
     console.log('✓ .agents/skills/hivemind-cli/SKILL.md installed');
+    await ensureLocalBrowser();
     console.log('\nDone. A coding agent working in this repo now knows how to use hivemind.');
     console.log('Next: hivemind create "<what to test>" --url <your app url>');
 }

package/dist/commands/remoteExecutor.js

@@ -1,3 +1,4 @@
+const MAX_BROWSER_LOGS = 200;
 /**
  * The Forager — runs on your machine, executes exactly what the Hivemind brain tells it to, one
  * named tool call at a time. Same `execute(name, input)` shape used in-process on the server for
@@ -11,14 +12,55 @@ export class Forager {
     runStart;
     pageStack = [];
     screenshots = [];
+    browserLogs = [];
     constructor(page, runStart) {
         this.page = page;
         this.runStart = runStart;
+        this.attachLogging(page);
+    }
+    /** Same reasoning as the server's ToolExecutor: a click can succeed while the page underneath
+     *  throws a JS error or a fetch 500s, and the report today has no way to show that. This is the
+     *  ONLY side that ever sees these events for a --local run — the server never opened this
+     *  browser — so every call's result carries the full accumulated log back over the socket
+     *  (see execute() below); RemoteToolRunner just keeps the latest one it receives. */
+    attachLogging(page) {
+        const push = (entry) => {
+            if (this.browserLogs.length < MAX_BROWSER_LOGS)
+                this.browserLogs.push(entry);
+        };
+        page.on('console', (msg) => {
+            if (msg.type() === 'log' || msg.type() === 'debug')
+                return;
+            push({ type: 'console', level: msg.type(), text: msg.text().slice(0, 500), elapsedMs: Date.now() - this.runStart });
+        });
+        page.on('pageerror', (err) => {
+            push({ type: 'console', level: 'error', text: err.message.slice(0, 500), elapsedMs: Date.now() - this.runStart });
+        });
+        page.on('requestfailed', (req) => {
+            push({
+                type: 'network',
+                level: 'failed',
+                text: `${req.method()} ${req.url()} — ${req.failure()?.errorText || 'failed'}`.slice(0, 500),
+                elapsedMs: Date.now() - this.runStart,
+            });
+        });
+        page.on('response', (res) => {
+            if (res.status() < 400)
+                return;
+            push({ type: 'network', level: String(res.status()), text: `${res.request().method()} ${res.url()} → ${res.status()}`.slice(0, 500), elapsedMs: Date.now() - this.runStart });
+        });
     }
     getScreenshots() {
         return this.screenshots;
     }
+    getBrowserLogs() {
+        return this.browserLogs;
+    }
     async execute(name, input) {
+        const result = await this.executeInner(name, input);
+        return { ...result, browserLogs: this.browserLogs };
+    }
+    async executeInner(name, input) {
         try {
             switch (name) {
                 case 'browser_navigate': {
@@ -170,6 +212,7 @@ export class Forager {
         await newPage.waitForLoadState('domcontentloaded', { timeout: 10_000 }).catch(() => { });
         this.pageStack.push(prevPage);
         this.page = newPage;
+        this.attachLogging(newPage);
         newPage.on('close', () => {
             if (this.page === newPage) {
                 const fallback = this.pageStack.pop();

package/dist/commands/report.js

@@ -1,6 +1,7 @@
 import { join } from 'node:path';
 import { readFile } from 'node:fs/promises';
 import { exec } from 'node:child_process';
+import { readApiKey } from '../credentials.js';
 function serverUrl() {
     return process.env.HIVEMIND_SERVER_URL || 'https://app.thecolonylab.com';
 }
@@ -9,7 +10,7 @@ function open(url) {
     exec(`${opener} "${url}"`);
 }
 export async function reportCommand() {
-    const pointerPath = join(process.cwd(), '.hive', 'last-run.json');
+    const pointerPath = join(process.cwd(), 'hive', 'last-run.json');
     try {
         const pointer = JSON.parse(await readFile(pointerPath, 'utf-8'));
         console.log(`Opening ${pointer.reportUrl}`);
@@ -21,9 +22,15 @@ export async function reportCommand() {
 }
 export async function historyCommand(opts) {
     const url = `${serverUrl()}/api/runs`;
-    const res = await fetch(url).catch(() => null);
+    const apiKey = await readApiKey();
+    const res = await fetch(url, apiKey ? { headers: { Authorization: `Bearer ${apiKey}` } } : undefined).catch(() => null);
     if (!res || !res.ok) {
-        console.error(`Could not reach hivemind server at ${serverUrl()}. Is it running? (hivemind-server)`);
+        if (res?.status === 401) {
+            console.error(`Not signed in — run "hivemind login <key>" (get a key from the dashboard's Settings page).`);
+        }
+        else {
+            console.error(`Could not reach hivemind server at ${serverUrl()}. Is it running? (hivemind-server)`);
+        }
         process.exitCode = 2;
         return;
     }

package/dist/commands/run.js

@@ -24,15 +24,15 @@ async function runPool(items, limit, worker) {
 }
 async function readLocalMemory(cwd) {
     try {
-        return await readFile(join(cwd, '.hive', 'memory.md'), 'utf-8');
+        return await readFile(join(cwd, 'hive', 'memory.md'), 'utf-8');
     }
     catch {
         return '';
     }
 }
 async function writeLocalMemory(cwd, content) {
-    const path = join(cwd, '.hive', 'memory.md');
-    await mkdir(join(cwd, '.hive'), { recursive: true });
+    const path = join(cwd, 'hive', 'memory.md');
+    await mkdir(join(cwd, 'hive'), { recursive: true });
     await writeFile(path, content, 'utf-8');
 }
 export async function runCommand(target, opts) {
@@ -81,7 +81,7 @@ export async function runCommand(target, opts) {
             console.error(`✗ ${test.name}: ${err.message}`);
             results[index] = {
                 name: test.name,
-                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], durationMs: 0 },
+                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], browserLogs: [], durationMs: 0 },
             };
             return;
         }
@@ -95,7 +95,7 @@ export async function runCommand(target, opts) {
             console.error(`✗ ${test.name}: ${message}`);
             results[index] = {
                 name: test.name,
-                result: { status: 'error', verdict: message, steps: [], toolLog: [], screenshots: [], durationMs: 0 },
+                result: { status: 'error', verdict: message, steps: [], toolLog: [], screenshots: [], browserLogs: [], durationMs: 0 },
             };
             return;
         }
@@ -115,8 +115,9 @@ export async function runCommand(target, opts) {
                     memoryContext,
                     credential,
                     headed: opts.headed,
+                    projectId: config.projectId,
                 });
-                await writeFile(join(cwd, '.hive', 'last-run.json'), JSON.stringify({ reportUrl: reportPath, name: test.name }, null, 2)).catch(() => { });
+                await writeFile(join(cwd, 'hive', 'last-run.json'), JSON.stringify({ reportUrl: reportPath, name: test.name }, null, 2)).catch(() => { });
                 results[index] = { name: test.name, result, reportUrl: reportPath };
                 if (!opts.json) {
                     printResult(test.name, result);
@@ -130,10 +131,12 @@ export async function runCommand(target, opts) {
                     steps: resolvedSteps,
                     memoryContext,
                     credential,
+                    projectId: config.projectId,
+                    projectName: config.projectName,
                 });
                 const reportUrl = `${serverUrl}${reportPath}`;
                 await writeLocalMemory(cwd, updatedMemory).catch(() => { });
-                await writeFile(join(cwd, '.hive', 'last-run.json'), JSON.stringify({ reportUrl, name: test.name }, null, 2)).catch(() => { });
+                await writeFile(join(cwd, 'hive', 'last-run.json'), JSON.stringify({ reportUrl, name: test.name }, null, 2)).catch(() => { });
                 results[index] = { name: test.name, result, reportUrl };
                 if (!opts.json) {
                     printResult(test.name, result);
@@ -145,7 +148,7 @@ export async function runCommand(target, opts) {
             console.error(`✗ ${test.name}: ${err.message}`);
             results[index] = {
                 name: test.name,
-                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], durationMs: 0 },
+                result: { status: 'error', verdict: err.message, steps: [], toolLog: [], screenshots: [], browserLogs: [], durationMs: 0 },
             };
         }
     });

package/dist/commands/runLocal.js

@@ -40,6 +40,7 @@ export async function runTestLocally(opts) {
     try {
         const wsUrl = opts.serverUrl.replace(/^http/, 'ws') + '/ws/local-run';
         const apiKey = await readApiKey();
+        let hostedReportUrl;
         const result = await new Promise((resolve, reject) => {
             const headers = { 'User-Agent': 'Hivemind-Forager/0.1.0' };
             if (apiKey)
@@ -52,6 +53,7 @@ export async function runTestLocally(opts) {
                     url: opts.url,
                     steps: opts.steps,
                     memoryContext: opts.memoryContext,
+                    projectId: opts.projectId,
                     credential: opts.credential,
                 }));
             });
@@ -69,6 +71,7 @@ export async function runTestLocally(opts) {
                     return;
                 }
                 if (msg.type === 'finish') {
+                    hostedReportUrl = msg.reportUrl;
                     resolve(msg.result);
                     socket.close();
                     return;
@@ -89,7 +92,9 @@ export async function runTestLocally(opts) {
         await session.close();
         closed = true;
         await writeRunArtifacts(opts.cwd, runId, opts.name, result);
-        const reportPath = `${artifactDirFor(opts.cwd, runId)}/report.html`;
+        // Prefer the real, hosted, shareable report (shows up in the dashboard's Runs list) — the
+        // local file written above is just a backup for offline viewing, same data either way.
+        const reportPath = hostedReportUrl ? `${opts.serverUrl}${hostedReportUrl}` : `${artifactDirFor(opts.cwd, runId)}/report.html`;
         return { result, reportPath };
     }
     finally {

package/dist/report/artifacts.js

@@ -5,8 +5,11 @@ import { slugify } from '../testFile/write.js';
 function timestampDir() {
     return new Date().toISOString().replace(/[:.]/g, '-');
 }
+/** Everything lives under one hive/ folder — tests/ is the committed part, history/ and
+ *  artifacts/ are local-only and gitignored (see `hivemind init`'s .gitignore rules). One folder
+ *  to look in instead of splitting state across hive/ and a separate .hive/. */
 export function artifactDirFor(cwd, runId) {
-    return join(cwd, 'artifacts', runId);
+    return join(cwd, 'hive', 'artifacts', runId);
 }
 /** Creates the artifact directory for a run BEFORE it starts, so ToolExecutor can write screenshots into it. */
 export async function createArtifactDir(cwd, testName) {
@@ -20,7 +23,7 @@ export async function writeRunArtifacts(cwd, runId, testName, result) {
     const artifactDir = artifactDirFor(cwd, runId);
     const html = renderHtmlReport(testName, result);
     await writeFile(join(artifactDir, 'report.html'), html, 'utf-8');
-    const historyDir = join(cwd, '.hive', 'history');
+    const historyDir = join(cwd, 'hive', 'history');
     await mkdir(historyDir, { recursive: true });
     const entry = {
         name: testName,
@@ -34,7 +37,7 @@ export async function writeRunArtifacts(cwd, runId, testName, result) {
     return artifactDir;
 }
 export async function readHistory(cwd) {
-    const historyDir = join(cwd, '.hive', 'history');
+    const historyDir = join(cwd, 'hive', 'history');
     try {
         const files = await readdir(historyDir);
         const entries = await Promise.all(files

package/dist/serverClient.js

@@ -29,14 +29,14 @@ async function post(path, body) {
 export async function runOnServer(input) {
     return post('/api/runs', input);
 }
-export async function createOnServer(request, url, existingTests, accountLabels) {
-    return post('/api/create', { request, url, existingTests, accountLabels });
+export async function createOnServer(request, url, existingTests, accountLabels, projectId) {
+    return post('/api/create', { request, url, existingTests, accountLabels, projectId });
 }
-export async function exploreOnServer(url, existingTests) {
-    return post('/api/explore', { url, existingTests });
+export async function exploreOnServer(url, existingTests, projectId, projectName) {
+    return post('/api/explore', { url, existingTests, projectId, projectName });
 }
-export async function coverageOnServer(diff, localTests) {
-    return post('/api/coverage', { diff, localTests });
+export async function coverageOnServer(diff, localTests, projectId, projectName) {
+    return post('/api/coverage', { diff, localTests, projectId, projectName });
 }
 export async function getDraftTest(code) {
     const apiKey = await readApiKey();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thecolonylab/hivemind",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Forager — the CLI that runs on your machine and executes for the Hivemind brain. Describe a flow in plain English, an AI agent drives a real browser and reports pass/fail. No LLM key needed on this machine.",
   "type": "module",
   "license": "MIT",
@@ -20,7 +20,7 @@
   "dependencies": {
     "commander": "^12.1.0",
     "dotenv": "^17.4.2",
-    "playwright": "^1.48.0",
+    "playwright": "1.48.0",
     "ws": "^8.21.0"
   },
   "devDependencies": {

package/skill/AGENTS.md.template

@@ -6,8 +6,9 @@ code or selectors required.
 
 - **Skill:** see `.agents/skills/hivemind-cli/SKILL.md` for the full command reference, test file
   format, login/precondition conventions, and how to read results.
-- **Setup check:** `hivemind --help`; server defaults to `http://localhost:4321` unless
-  `HIVEMIND_SERVER_URL` is set.
+- **Setup check:** `hivemind --help`; the CLI talks to the hosted server at
+  `https://app.thecolonylab.com` by default — only set `HIVEMIND_SERVER_URL` if pointing at a
+  self-hosted server instead.
 - **Default workflow:** right after building or changing a UI flow, write or generate a test in
   `hive/tests/`, run it with `hivemind run <file> --url <url> --json`, and fix your own code if it
   fails — before telling the user the feature is done.

package/skill/hivemind-cli/SKILL.md

@@ -25,7 +25,7 @@ machine — the hivemind server (wherever `HIVEMIND_SERVER_URL` points) holds it
 
 ```bash
 hivemind --help
-echo $HIVEMIND_SERVER_URL   # if unset, defaults to http://localhost:4321
+echo $HIVEMIND_SERVER_URL   # if unset, defaults to the hosted server at https://app.thecolonylab.com
 ```
 
 If the command isn't found, it isn't installed — tell the user rather than trying to work around it.
@@ -50,6 +50,17 @@ hivemind explore <url>
 # Open the most recent run's report, or list past runs.
 hivemind report
 hivemind history [--json]
+
+# Diff-aware regression check — for CI, or before opening a PR. Reads the real git diff, figures
+# out which known pages are affected, RE-RUNS whatever local tests already touch them (this is
+# the actual regression check), and drafts a new test for any genuine gap left uncovered. Add
+# --local when testing a build that only exists on this machine/runner (same reasoning as `run`).
+# --pr-comment <path> writes a ready-to-post markdown report (numbered pass/fail + report links).
+hivemind coverage [--changed <base>] [--local] [--pr-comment <path>]
+
+# Pull down a test `coverage` drafted for a gap — identified by a short code (e.g.
+# "amber-fern-cove") shown in its output/PR comment, not by pasting any code.
+hivemind apply <code>
 ```
 
 Always use `--json` on `run` when you (the agent) are consuming the result programmatically — it