@sdods/cli 0.9.0 → 0.10.0

package/dist/commands/browsers.js

@@ -75,7 +75,7 @@ export async function browserStatuses(names = DOWNLOADED_BROWSERS) {
     return names.map((name) => {
         const engine = ENGINE_OF[name] ?? 'chromium';
         const channel = CHANNEL_OF[name] ?? null;
-        let executable = null;
+        let executable;
         try {
             executable = channel ? channelExecutable(channel) : pw[engine].executablePath();
         }

package/dist/commands/init.js

@@ -140,12 +140,12 @@ export async function initWorkspace(target, flags) {
             // 1.63 is the floor, not a preference: below it an npm-installed workspace records every
             // Gherkin step SKIPPED in messages.ndjson (see runner-compat.ts).
             '@playwright/test': flags.link && flags.pm === 'bun' ? 'link:@playwright/test' : '^1.63.0',
-            'playwright-bdd': flags.link && flags.pm === 'bun' ? 'link:playwright-bdd' : '^9.2.0',
+            'playwright-bdd': flags.link && flags.pm === 'bun' ? 'link:playwright-bdd' : '^9.2.1',
         },
         devDependencies: {
-            '@types/node': '^22.15.0',
-            typescript: '~5.9.3',
-            tsx: '^4.23.0',
+            '@types/node': '^22.20.2',
+            typescript: '~6.0.3',
+            tsx: '^4.23.13',
         },
         trustedDependencies: [
             '@playwright/test',

package/dist/commands/report.js

@@ -1,10 +1,12 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
-import { dirname, extname, join, resolve } from 'node:path';
+import { copyFileSync, existsSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, statSync, writeFileSync, } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { basename, dirname, extname, join, resolve } from 'node:path';
 import { execa } from 'execa';
 import pc from 'picocolors';
-import { runFiles } from '@sdods/contracts';
-import { SdodsError } from '@sdods/core';
+import { legacyRunFiles, runFiles, } from '@sdods/contracts';
+import { SdodsError, collectGateEvidence, evaluateGates, gateReportsFromRunnerJson, gateTotalsFromRunnerStats, hasGates, ingestGateJudge, } from '@sdods/core';
 import { createContext } from '../context.js';
+import { gateFailedError, printGates } from '../gates.js';
 import { json, ok, out, table, warn } from '../ui.js';
 function artifactsRoot(rootDir) {
     return resolve(rootDir, process.env.SDODS_ARTIFACTS_DIR ?? '.sdods/runs');
@@ -35,6 +37,82 @@ async function openPath(p) {
     const cmd = process.platform === 'darwin' ? 'open' : process.platform === 'win32' ? 'start' : 'xdg-open';
     await execa(cmd, [p], { shell: process.platform === 'win32' }).catch(() => undefined);
 }
+/**
+ * The process `report merge` judges: `--process` (with `-p`, or the project in a run.json), or the
+ * process a run.json names when it declares gates. `undefined` when there is nothing to judge.
+ */
+function resolveMergeProcess(ctx, input) {
+    const manifest = input.manifestDirs
+        .map((d) => readJsonFile(join(d, runFiles.manifest)))
+        .find(Boolean);
+    const name = input.process ?? manifest?.process;
+    if (!name)
+        return undefined;
+    const slug = input.project ?? manifest?.projectSlug;
+    if (!slug)
+        throw new SdodsError('CONFIG_INVALID', `--process ${name} needs the project that defines it, and no run.json names one.`, {
+            hint: `Pass -p <slug>: sdods report merge --process ${name} -p <slug> <dirs...>`,
+            exitCode: 2,
+        });
+    let proc;
+    try {
+        proc = ctx.registry.processOf(slug, name);
+    }
+    catch (e) {
+        // Named explicitly, an unknown process is an error. Inferred from a run.json this checkout
+        // cannot resolve, it only means there is nothing here to judge it by; the merge still runs.
+        if (input.process)
+            throw e;
+        warn(`run.json names process "${name}" of ${slug}, which this checkout does not define: gates not judged.`);
+        return undefined;
+    }
+    if (!hasGates(proc.gates)) {
+        // Named explicitly, a process without gates is a mistake worth saying; inferred, it is not.
+        if (input.process)
+            warn(`process "${name}" of ${slug} declares no gates, so there is nothing to judge.`);
+        return undefined;
+    }
+    return { slug, process: proc };
+}
+/**
+ * A merge workspace for `playwright merge-reports`: the blob reports of every directory copied into
+ * one (it reads exactly one directory; prefixed, because two runs' shard 1 carry the same file
+ * name), and a merge config that pins the root the report paths are relative to. Blobs recorded
+ * under different checkouts, such as CI's Playwright container (`/__w/…`) and its bare runner
+ * (`/home/runner/work/…`), otherwise refuse to merge ("recorded with different test directories").
+ */
+function mergeWorkspace(dirs, rootDir) {
+    const dir = mkdtempSync(join(tmpdir(), 'sdods-merge-'));
+    const reports = join(dir, 'reports');
+    mkdirSync(reports);
+    dirs.forEach((from, i) => {
+        for (const name of readdirSync(from))
+            if (name.endsWith('.zip'))
+                copyFileSync(join(from, name), join(reports, `${i + 1}-${name}`));
+    });
+    const config = join(dir, 'merge.config.mjs');
+    writeFileSync(config, `export default ${JSON.stringify({ testDir: rootDir })};\n`);
+    return { reports, config, dir };
+}
+/** The error Playwright printed, rather than the last lines of its stack. */
+function mergeFailureHint(stderr) {
+    const lines = (stderr ?? '').split('\n');
+    const at = lines.findIndex((l) => /^\s*Error\b/.test(l));
+    const picked = at >= 0 ? lines.slice(at, at + 12).filter((l) => !/^\s+at /.test(l)) : lines.slice(-3);
+    return picked.join(' ').replace(/\s+/g, ' ').trim() || undefined;
+}
+/** Writes the merged verdict where `sdods run --process` writes one, so ingest records it the same way. */
+function recordMergedGates(runDir, gates) {
+    writeFileSync(join(runDir, runFiles.gates), JSON.stringify(gates, null, 2));
+    const manifestFile = join(runDir, runFiles.manifest);
+    const manifest = readJsonFile(manifestFile);
+    if (manifest)
+        writeFileSync(manifestFile, JSON.stringify({ ...manifest, gatesPassed: gates.passed }, null, 2));
+    const summaryFile = join(runDir, runFiles.summary);
+    const summary = readJsonFile(summaryFile);
+    if (summary)
+        writeFileSync(summaryFile, JSON.stringify({ ...summary, gates }, null, 2));
+}
 export function register(program) {
     const report = program
         .command('report')
@@ -172,12 +250,25 @@ export function register(program) {
                 artifactsRoot: root,
                 replace: Boolean(opts.replace),
                 env: opts.env,
+                // A run with no gates.json whose process declares gates is judged here, as the run would have been.
+                gates: ingestGateJudge({
+                    manifest: manifest ?? m.readManifest(join(root, opts.runId)),
+                    runDir: join(root, opts.runId),
+                    processOf: (slug, name) => ctx.registry.processOf(slug, name),
+                }),
             });
             if (ctx.opts.json)
                 return json(res);
             ok(`Ingested run ${res.runId} (${res.projectSlug}): ${res.scenarios} scenario(s), ${res.attempts} attempt(s), ${res.steps} step(s), ${res.artifacts} artifact(s), ${res.healEvents} heal event(s)`);
             const t = res.totals;
             out(`${pc.green(`${t.passed} passed`)}  ${pc.red(`${t.failed} failed`)}  ${pc.yellow(`${t.flaky} flaky`)}  ${pc.dim(`${t.skipped} skipped`)}  → ${res.status}`);
+            if (res.gates)
+                out(`gates · process ${res.gates.process}: ${res.gates.passed
+                    ? pc.green('passed')
+                    : pc.red(`FAILED (${res.gates.rows
+                        .filter((r) => !r.passed)
+                        .map((r) => r.gate)
+                        .join(', ')})`)}`);
             if (res.filesSkipped.length)
                 out(pc.dim(`skipped (already ingested): ${res.filesSkipped.join(', ')}`));
             if (res.parseErrors)
@@ -189,9 +280,11 @@ export function register(program) {
     });
     report
         .command('merge <dirs...>')
-        .description('Merge sharded run reports into one HTML report and JUnit file')
+        .description('Merge sharded run reports into one HTML report and JUnit file, and judge process gates on the whole run')
         .option('--run <id>', 'run id to write the merged report into (default: latest)')
         .option('--reporter <list>', 'reporters for the merged output', 'html,junit')
+        .option('--process <name>', "evaluate this process's gates over the merged shards; exit 1 when one is not met (default: the process in run.json, when it declares gates)")
+        .option('-p, --project <slug>', 'project that defines --process (default: from run.json)')
         .action(async (dirs, opts, cmd) => {
         const ctx = createContext(cmd);
         const root = artifactsRoot(ctx.rootDir);
@@ -212,28 +305,82 @@ export function register(program) {
                 exitCode: 2,
             });
         }
+        const shardDirs = dirs.map((d) => resolve(ctx.rootDir, d));
+        // The run directory each shard report sits in (`<run>/shard-reports`) holds that shard's
+        // @a11y and @perf scenario reports, which is the gate evidence the merged report lacks.
+        const shardRunDirs = shardDirs
+            .filter((d) => [runFiles.shardReports, legacyRunFiles.shardReports].includes(basename(d)))
+            .map((d) => dirname(d));
+        const gated = resolveMergeProcess(ctx, {
+            process: opts.process,
+            project: opts.project,
+            manifestDirs: [runDir, ...shardRunDirs],
+        });
+        const reporters = String(opts.reporter)
+            .split(',')
+            .map((r) => r.trim())
+            .filter(Boolean);
+        const mergedJson = join(runDir, runFiles.mergedResults);
+        if (gated && !reporters.includes('json'))
+            reporters.push('json');
+        if (gated)
+            mkdirSync(runDir, { recursive: true });
         // Shard reports are produced by `sdods run --reporter blob --shard i/n`; merging them
         // rebuilds one HTML report and JUnit file for the whole matrix.
+        const workspace = mergeWorkspace(shardDirs, ctx.rootDir);
         const args = [
             'playwright',
             'merge-reports',
+            '--config',
+            workspace.config,
             '--reporter',
-            opts.reporter,
-            ...dirs.map((d) => resolve(ctx.rootDir, d)),
+            reporters.join(','),
+            workspace.reports,
         ];
         const res = await execa('npx', args, {
             cwd: ctx.rootDir,
             reject: false,
-            env: { ...process.env, PLAYWRIGHT_HTML_OUTPUT_DIR: join(runDir, runFiles.htmlReport) },
+            env: {
+                ...process.env,
+                PLAYWRIGHT_HTML_OUTPUT_DIR: join(runDir, runFiles.htmlReport),
+                ...(gated ? { PLAYWRIGHT_JSON_OUTPUT_FILE: mergedJson } : {}),
+            },
         });
-        if (res.exitCode !== 0) {
-            throw new SdodsError('RUN_FAILED', `Merging shard reports failed (exit ${res.exitCode}).`, {
-                hint: res.stderr?.split('\n').slice(-3).join(' ') || undefined,
-            });
+        let gates;
+        try {
+            if (res.exitCode !== 0) {
+                throw new SdodsError('RUN_FAILED', `Merging shard reports failed (exit ${res.exitCode}).`, { hint: mergeFailureHint(res.stderr) });
+            }
+            if (gated) {
+                const merged = readJsonFile(mergedJson);
+                gates = evaluateGates({
+                    process: gated.process.name,
+                    gates: gated.process.gates,
+                    totals: gateTotalsFromRunnerStats(merged?.stats),
+                    // The shards' run directories, and the reports attached in the blobs themselves: a
+                    // download of the shard reports alone still carries its evidence.
+                    evidence: collectGateEvidence([runDir, ...shardRunDirs], gateReportsFromRunnerJson(merged)),
+                });
+                recordMergedGates(runDir, gates);
+            }
+        }
+        finally {
+            rmSync(workspace.dir, { recursive: true, force: true });
         }
         if (ctx.opts.json)
-            return json({ runId, merged: dirs.length, htmlReport: join(runDir, runFiles.htmlReport) });
-        ok(`Merged ${dirs.length} shard report dir(s) into ${join(runDir, runFiles.htmlReport)}`);
+            json({
+                runId,
+                merged: dirs.length,
+                htmlReport: join(runDir, runFiles.htmlReport),
+                ...(gates ? { gates } : {}),
+            });
+        else {
+            ok(`Merged ${dirs.length} shard report dir(s) into ${join(runDir, runFiles.htmlReport)}`);
+            if (gates)
+                printGates(gates);
+        }
+        if (gates && !gates.passed)
+            throw gateFailedError(gates, join(runDir, runFiles.gates));
     });
     report
         .command('traceability')

package/dist/commands/run.js

@@ -7,6 +7,7 @@ import { SdodsError, CLI_OVERRIDES_ENV, VERSION, checkPoolCapacity, collectGateE
 import { analyzeChangeImpact } from '@sdods/mcp';
 import { createContext } from '../context.js';
 import { browserStatuses } from './browsers.js';
+import { gateFailedError, printGates } from '../gates.js';
 import { maybeNotify, notifyRun } from '../notify.js';
 import { installedPlaywrightVersion, stepResultsWarning } from '../runner-compat.js';
 import { collect, json, out, parseIntFlag, renderError, table, warn } from '../ui.js';
@@ -447,12 +448,13 @@ export async function runCommand(flags, cmd) {
     const summary = readSummary(runDir, runId, exitCode, Date.now() - started);
     // Process gates are judged here, from the run that just finished, before anything publishes it.
     // One shard of several holds only part of the run, so its pass rate and its a11y/perf evidence
-    // are not the run's; a sharded process is gated where the shards are merged, not per shard.
+    // are not the run's; a sharded process is gated where the shards are merged
+    // (`sdods report merge --process`), not per shard.
     const shardTotal = cfg.runtime.shard?.total ?? 1;
     let gates;
     if (proc && hasGates(proc.gates) && exitCode !== 130) {
         if (shardTotal > 1) {
-            warn(`process "${proc.name}" gates are not evaluated on shard ${cfg.runtime.shard?.current}/${shardTotal}: one shard is not the whole run.`);
+            warn(`process "${proc.name}" gates are not evaluated on shard ${cfg.runtime.shard?.current}/${shardTotal}: one shard is not the whole run. Judge them on the merged shards with \`sdods report merge --process ${proc.name}\`.`);
         }
         else {
             gates = evaluateGates({
@@ -550,17 +552,8 @@ export async function runCommand(flags, cmd) {
         json({ runId, runDir, exitCode: finalExit, summary, manifest, notify, gates });
     }
     else {
-        if (gates) {
-            out('');
-            out(pc.bold(`gates · process ${gates.process}`));
-            table(gates.rows.map((r) => ({
-                gate: r.gate,
-                threshold: r.threshold,
-                actual: r.actual,
-                result: r.passed ? 'pass' : 'FAIL',
-                detail: r.detail ?? '',
-            })));
-        }
+        if (gates)
+            printGates(gates);
         const t = summary?.totals;
         out('');
         out(`${finalExit === 0 ? pc.green('✔ passed') : finalExit === 130 ? pc.yellow('■ cancelled') : finalExit === 2 ? pc.yellow('■ nothing ran') : pc.red('✖ failed')}  ${t ? `${t.passed} passed, ${t.failed} failed, ${t.skipped} skipped, ${t.flaky} flaky` : ''}  ${pc.dim(`(${Math.round((Date.now() - started) / 1000)}s)`)}`);
@@ -568,13 +561,8 @@ export async function runCommand(flags, cmd) {
         out(pc.dim(`html report: ${join(runDir, runFiles.htmlReport, 'index.html')}`));
         out(pc.dim(`dashboard:   ${join(runDir, runFiles.dashboard, 'index.html')}`));
     }
-    if (gates && !gates.passed) {
-        const failed = gates.rows.filter((r) => !r.passed);
-        renderError(new SdodsError('GATE_FAILED', `Process "${gates.process}" did not meet ${failed.length} gate(s): ${failed.map((r) => `${r.gate} (${r.actual}, needs ${r.threshold})`).join('; ')}.`, {
-            hint: `The verdict is in ${join(runDir, runFiles.gates)}. Gates are set under processes[].gates in sdods.project.yaml.`,
-            docsPath: '/docs/guides/processes-and-testing-types',
-        }), Boolean(ctx.opts.json));
-    }
+    if (gates && !gates.passed)
+        renderError(gateFailedError(gates, join(runDir, runFiles.gates)), Boolean(ctx.opts.json));
     return finalExit;
 }
 /**

package/dist/commands/schedule.js

@@ -279,7 +279,7 @@ export function register(program) {
             if (opts.target === 'github') {
                 const file = join(ctx.rootDir, '.github', 'workflows', `scheduled-${e.project}-${e.name}.yml`);
                 mkdirSync(join(ctx.rootDir, '.github', 'workflows'), { recursive: true });
-                writeFileSync(file, `name: scheduled ${e.project} ${e.name}\non:\n  schedule:\n    - cron: '${e.cron}'\n  workflow_dispatch: {}\njobs:\n  run:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v4\n      - uses: oven-sh/setup-bun@v2\n      - uses: actions/setup-node@v4\n        with: { node-version: 22 }\n      - run: bun install\n      - run: bun run sdods browsers install --with-deps\n      - run: bun run sdods run ${e.args.join(' ')} --trigger schedule --run-id sched-${e.name}-\${{ github.run_id }}\n        env:\n          SDODS_SERVER_URL: \${{ secrets.SDODS_SERVER_URL }}\n          SDODS_TOKEN: \${{ secrets.SDODS_TOKEN }}\n      - uses: actions/upload-artifact@v4\n        if: always()\n        with: { name: sdods-${e.project}-${e.name}, path: .sdods/runs }\n`);
+                writeFileSync(file, `name: scheduled ${e.project} ${e.name}\non:\n  schedule:\n    - cron: '${e.cron}'\n  workflow_dispatch: {}\njobs:\n  run:\n    runs-on: ubuntu-latest\n    steps:\n      - uses: actions/checkout@v7\n      - uses: oven-sh/setup-bun@v2\n      - uses: actions/setup-node@v7\n        with: { node-version: 22 }\n      - run: bun install\n      - run: bun run sdods browsers install --with-deps\n      - run: bun run sdods run ${e.args.join(' ')} --trigger schedule --run-id sched-${e.name}-\${{ github.run_id }}\n        env:\n          SDODS_SERVER_URL: \${{ secrets.SDODS_SERVER_URL }}\n          SDODS_TOKEN: \${{ secrets.SDODS_TOKEN }}\n      - uses: actions/upload-artifact@v7\n        if: always()\n        with: { name: sdods-${e.project}-${e.name}, path: .sdods/runs }\n`);
                 written.push(file);
             }
             else if (opts.target === 'launchd') {

package/dist/commands/trace.js

@@ -56,8 +56,8 @@ export function register(program) {
         .option('--list', 'list trace files instead of opening them')
         .action(async (zip, opts, cmd) => {
         const ctx = createContext(cmd);
-        let zips = [];
-        let source = '';
+        let zips;
+        let source;
         if (zip) {
             const p = resolvePath(ctx.opts.cwd ?? process.cwd(), zip);
             if (!existsSync(p))

package/dist/gates.d.ts

@@ -0,0 +1,11 @@
+import type { GateResult } from '@sdods/contracts';
+import { SdodsError } from '@sdods/core';
+/**
+ * How a process gate verdict reads on the terminal, and the error a breach fails with. Shared by
+ * `sdods run --process` (an unsharded run) and `sdods report merge --process` (the shards of one),
+ * so a gate looks the same wherever it was judged.
+ */
+export declare function printGates(gates: GateResult): void;
+/** The `GATE_FAILED` error for a verdict that did not pass. Exit 1: a gate not met is a failure. */
+export declare function gateFailedError(gates: GateResult, verdictFile: string): SdodsError;
+//# sourceMappingURL=gates.d.ts.map

package/dist/gates.js

@@ -0,0 +1,29 @@
+import pc from 'picocolors';
+import { SdodsError } from '@sdods/core';
+import { out, table } from './ui.js';
+/**
+ * How a process gate verdict reads on the terminal, and the error a breach fails with. Shared by
+ * `sdods run --process` (an unsharded run) and `sdods report merge --process` (the shards of one),
+ * so a gate looks the same wherever it was judged.
+ */
+export function printGates(gates) {
+    out('');
+    out(pc.bold(`gates · process ${gates.process}`));
+    table(gates.rows.map((r) => ({
+        gate: r.gate,
+        threshold: r.threshold,
+        actual: r.actual,
+        result: r.passed ? 'pass' : 'FAIL',
+        detail: r.detail ?? '',
+    })));
+}
+/** The `GATE_FAILED` error for a verdict that did not pass. Exit 1: a gate not met is a failure. */
+export function gateFailedError(gates, verdictFile) {
+    const failed = gates.rows.filter((r) => !r.passed);
+    return new SdodsError('GATE_FAILED', `Process "${gates.process}" did not meet ${failed.length} gate(s): ${failed.map((r) => `${r.gate} (${r.actual}, needs ${r.threshold})`).join('; ')}.`, {
+        hint: `The verdict is in ${verdictFile}. Gates are set under processes[].gates in sdods.project.yaml.`,
+        docsPath: '/docs/guides/processes-and-testing-types',
+        exitCode: 1,
+    });
+}
+//# sourceMappingURL=gates.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/cli",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "SDODS command line: run, record, analyze, agents, MCP server, scheduler and the web server.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -24,22 +24,22 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.9.0",
-    "@sdods/core": "0.9.0",
+    "@sdods/contracts": "0.10.0",
+    "@sdods/core": "0.10.0",
     "commander": "^15.0.0",
     "execa": "^10.0.1",
     "picocolors": "^1.1.1",
     "semver": "^7.8.5",
-    "yaml": "^2.9.0",
-    "zod": "^4.5.4",
+    "yaml": "^2.9.1",
+    "zod": "^4.6.5",
     "@playwright/test": "^1.63.0",
     "playwright-core": "^1.63.0",
-    "@sdods/integrations": "0.9.0",
-    "@sdods/mcp": "0.9.0",
-    "@sdods/agents": "0.9.0",
-    "@sdods/db": "0.9.0",
+    "@sdods/integrations": "0.10.0",
+    "@sdods/mcp": "0.10.0",
+    "@sdods/agents": "0.10.0",
+    "@sdods/db": "0.10.0",
     "csv-parse": "^7.0.2",
-    "@sdods/server": "0.9.0"
+    "@sdods/server": "0.10.0"
   },
   "homepage": "https://sdods.com",
   "bugs": {

package/skills/sdods-start-ui/SKILL.md

@@ -161,11 +161,12 @@ Defaults: **`http://127.0.0.1:4444`** for the CLI, **`http://localhost:8080`** f
 image binds `0.0.0.0:8080`). `--open` launches the browser (`open` / `start` / `xdg-open` by
 platform). `--host 0.0.0.0` exposes it on the LAN — only do that deliberately.
 
-On Apple silicon the published image is `linux/amd64` only, and Docker refuses the pull rather
-than emulating. Add the platform flag:
+The image is published for `linux/amd64` and `linux/arm64`, so the same command runs natively on
+Apple silicon and arm64 servers. Tags up to `0.9.0` carry amd64 only, and Docker refuses that pull
+on arm64 rather than emulating; for those, add the platform flag:
 
 ```bash
-docker run --rm --platform linux/amd64 -p 8080:8080 -v sdods-data:/data ghcr.io/siri1410/sdods-server
+docker run --rm --platform linux/amd64 -p 8080:8080 -v sdods-data:/data ghcr.io/siri1410/sdods-server:0.9.0
 ```
 
 If the run must come from a source checkout, `bun run web:build` is not optional — see
@@ -278,7 +279,7 @@ the API running **without** the UI bundle — that is the source-checkout case,
 | Fresh install, but `/login` says "ask an admin" | the login page does not redirect to `/setup` | open the `/setup?token=…` URL from the `serve` output, or `sdods users create --admin` |
 | Global CLI errors on a repo project (`CONFIG_INVALID`, unknown browser) | version skew between the global CLI and the checkout | use `bun run sdods` inside a checkout; upgrade the global one otherwise |
 | `sdods: command not found` after installing | the bin dir is not on PATH — `~/.local/bin`, or `%LOCALAPPDATA%\SDODS\bin` on Windows | add it, or re-run the installer with `--modify-path` / `-ModifyPath` |
-| Docker: `no matching manifest for linux/arm64/v8` | amd64-only image on Apple silicon | add `--platform linux/amd64` |
+| Docker: `no matching manifest for linux/arm64/v8` | an amd64-only tag (`0.9.0` or earlier) on Apple silicon or arm64 | pull a newer tag, or add `--platform linux/amd64` |
 | UI loads, runs never start | browser engines missing | `sdods browsers install -b chromium` (the positional `sdods browsers install chromium` also works on current versions, and failed with `too many arguments` before). Bare `sdods browsers install` installs all engines; on Linux `--with-deps` needs root |
 | Node too old | SDODS needs Node 22+ | `nvm use 22` / `fnm use 22`. On macOS/Linux the installer also takes `--install-node`; **`install.ps1` has no such flag** — it exits and tells you to run `winget install OpenJS.NodeJS.LTS`, `scoop install nodejs-lts` or `nvm install 22` |
 | Anything else | — | `sdods doctor` first; it reports what it found, not what it expected |