@sdods/cli 0.2.0 → 0.2.2

package/dist/commands/browsers.js

@@ -76,7 +76,7 @@ export function register(program) {
     });
     browsers
         .command('list')
-        .description('Show which browsers are installed and where')
+        .description('Show which browsers are installed and where; exits 1 if any is missing')
         .option('-p, --project <slug>', 'limit to the browsers declared by a project')
         .action(async (opts, cmd) => {
         const ctx = createContext(cmd);

package/dist/commands/coverage.js

@@ -4,7 +4,7 @@ import { heading, json, out, table } from '../ui.js';
 export function register(program) {
     program
         .command('coverage')
-        .description('Route, endpoint and role coverage by scenarios, split by suite tag')
+        .description('Route, endpoint and role coverage by scenarios, split by suite tag; exits 1 if any module has no scenarios')
         .requiredOption('-p, --project <slug>', 'project slug')
         .option('-e, --env <name>', 'environment (for the OpenAPI spec and API base URL)')
         .option('--openapi [file]', 'include endpoints from the OpenAPI spec (env api.openapi or a file)')

package/dist/commands/har.js

@@ -1,4 +1,5 @@
-import { relative } from 'node:path';
+import { existsSync, readdirSync } from 'node:fs';
+import { join, relative } from 'node:path';
 import pc from 'picocolors';
 import { SdodsError } from '@sdods/core';
 import { createContext } from '../context.js';
@@ -73,6 +74,10 @@ export function register(program) {
             browser: opts.browser.length ? opts.browser : ['chromium'],
             harUpdate: true,
         }), cmd);
+        // Playwright writes the browser HAR itself, verbatim, including the Cookie, Set-Cookie and
+        // Authorization headers of the application under test. HARs are meant to be committed, so
+        // strip the credentials before anyone can commit a live session.
+        await scrubRecordedHars(ctx, opts.project, opts.env);
     });
     har
         .command('replay')
@@ -121,4 +126,33 @@ export function register(program) {
         table(rows, ['env', 'name', 'tag', 'size', 'api', 'glob', 'recorded', 'scenarios']);
     });
 }
+/**
+ * Replace credential values in every HAR under the project's har/<env> directory after a
+ * recording run. Reports what it touched: a silent rewrite of a file the user is about to commit
+ * would be worse than the leak it prevents.
+ */
+async function scrubRecordedHars(ctx, project, env) {
+    if (!project)
+        return;
+    const { scrubHarFile } = await import('@sdods/core/har');
+    const entry = ctx.registry.entriesList().find((e) => e.slug === project);
+    if (!entry)
+        return;
+    const dir = join(entry.root, 'har', env ?? '');
+    if (!existsSync(dir))
+        return;
+    let files = 0;
+    let values = 0;
+    for (const name of readdirSync(dir)) {
+        if (!name.endsWith('.har'))
+            continue;
+        const n = scrubHarFile(join(dir, name));
+        if (n > 0) {
+            files++;
+            values += n;
+        }
+    }
+    if (files > 0)
+        out(pc.dim(`scrubbed ${values} credential value(s) from ${files} HAR file(s)`));
+}
 //# sourceMappingURL=har.js.map

package/dist/commands/tokens.js

@@ -86,21 +86,28 @@ export function register(program) {
     tokens
         .command('revoke <id>')
         .description('Revoke a token by id')
-        .action(async (id, cmd) => {
+        .action(async (id, _opts, cmd) => {
         const ctx = createContext(cmd);
         const db = await import('@sdods/db');
         const adb = await db.openDb();
         try {
-            await db.revokeApiToken(adb.db, id);
-            await db.audit(adb.db, {
-                actorType: 'cli',
-                action: 'token.revoke',
-                targetType: 'api_token',
-                targetId: id,
-            });
+            // Reporting success for an id that does not exist reads as "the token is gone" when
+            // nothing was checked at all — an operator revoking a leaked token needs the difference.
+            const revoked = await db.revokeApiToken(adb.db, id);
+            if (revoked) {
+                await db.audit(adb.db, {
+                    actorType: 'cli',
+                    action: 'token.revoke',
+                    targetType: 'api_token',
+                    targetId: id,
+                });
+            }
             if (ctx.opts.json)
-                return json({ id, revoked: true });
-            ok(`Revoked ${id}`);
+                return json({ id, revoked });
+            if (revoked)
+                ok(`Revoked ${id}`);
+            else
+                warn(`No live token with id ${id}; nothing to revoke.`);
         }
         finally {
             await adb.close();

package/dist/commands/users.js

@@ -1,4 +1,5 @@
 import { SdodsError } from '@sdods/core';
+import { MIN_PASSWORD_LENGTH } from '@sdods/contracts/names';
 import { createContext } from '../context.js';
 import { json, ok, table } from '../ui.js';
 async function openDb() {
@@ -13,7 +14,7 @@ export function register(program) {
         .command('create')
         .description('Create a user; --admin makes a platform admin and organization owner')
         .requiredOption('--username <name>', 'login name')
-        .requiredOption('--password <password>', 'password (min 8 chars)')
+        .requiredOption('--password <password>', `password (min ${MIN_PASSWORD_LENGTH} chars)`)
         .option('--admin', 'platform admin + owner of every organization without an owner')
         .option('--role <role>', 'viewer | editor | admin', 'viewer')
         .option('--email <email>', 'email')
@@ -88,7 +89,7 @@ export function register(program) {
     users
         .command('set-role <username> <role>')
         .description('Change a platform role (viewer | editor | admin)')
-        .action(async (username, role, cmd) => {
+        .action(async (username, role, _opts, cmd) => {
         const ctx = createContext(cmd);
         const adb = await openDb();
         try {
@@ -112,7 +113,7 @@ export function register(program) {
     users
         .command('deactivate <username>')
         .description('Deactivate a user (sessions and tokens stop working)')
-        .action(async (username, cmd) => {
+        .action(async (username, _opts, cmd) => {
         const ctx = createContext(cmd);
         const adb = await openDb();
         try {

package/dist/context.js

@@ -1,5 +1,12 @@
 import { ProjectRegistry, setLogJson, setLogLevel } from '@sdods/core';
 export function globalOptions(cmd) {
+    // Commander calls an action with (...positionalArgs, options, command). A callback that forgets
+    // the options parameter receives the options object here instead of the Command, and the failure
+    // surfaced as an unhelpful "root.opts is not a function".
+    if (typeof cmd?.opts !== 'function' || !('parent' in cmd)) {
+        throw new Error('createContext expected the Commander Command. An action callback takes ' +
+            '(...args, options, command) — the options parameter is probably missing.');
+    }
     let root = cmd;
     while (root.parent)
         root = root.parent;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sdods/cli",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "SDODS command line: run, record, analyze, agents, MCP server, scheduler and the web server.",
   "license": "Apache-2.0",
   "author": "SDODS <admin@sdods.com>",
@@ -23,8 +23,8 @@
     "node": ">=22"
   },
   "dependencies": {
-    "@sdods/contracts": "0.2.0",
-    "@sdods/core": "0.2.0",
+    "@sdods/contracts": "0.2.2",
+    "@sdods/core": "0.2.2",
     "commander": "^15.0.0",
     "execa": "^10.0.1",
     "picocolors": "^1.1.1",
@@ -33,12 +33,12 @@
     "zod": "^4.5.4",
     "@playwright/test": "^1.62.1",
     "playwright-core": "^1.62.1",
-    "@sdods/integrations": "0.2.0",
-    "@sdods/mcp": "0.2.0",
-    "@sdods/agents": "0.2.0",
-    "@sdods/db": "0.2.0",
+    "@sdods/integrations": "0.2.2",
+    "@sdods/mcp": "0.2.2",
+    "@sdods/agents": "0.2.2",
+    "@sdods/db": "0.2.2",
     "csv-parse": "^7.0.2",
-    "@sdods/server": "0.2.0"
+    "@sdods/server": "0.2.2"
   },
   "homepage": "https://sdods.com",
   "bugs": {

package/templates/.claude/skills/code-signing/SKILL.md

@@ -0,0 +1,238 @@
+---
+name: code-signing
+description: Obtain and wire code-signing certificates for the SDODS desktop app so macOS Gatekeeper and Windows SmartScreen stop blocking it. Use when asked about signing, notarization, Gatekeeper, SmartScreen, "app is damaged", "unidentified developer", Developer ID certificates, Azure Artifact Signing, or why the installers show security warnings.
+---
+
+# Signing the SDODS desktop installers
+
+Unsigned installers work, but every user is told not to run them. macOS refuses a double-click
+("SDODS is damaged" or "unidentified developer") and Windows SmartScreen interrupts the install.
+That undercuts the one-click promise more than any technical problem in the app.
+
+**Everything in the build is already wired.** Supply the credentials as CI secrets and signing turns
+on with no code change. What cannot be automated is acquiring the certificates: both require a
+person's legal identity and a payment.
+
+Facts below were verified against Microsoft and Apple documentation in September 2026. Two pieces
+of widely repeated advice are now **wrong** — see the corrections at the end.
+
+---
+
+## macOS — Gatekeeper
+
+### What to buy
+
+**Apple Developer Program, $99/year.** There is no free path that satisfies Gatekeeper. Enrol at
+<https://developer.apple.com/programs/>. Individual enrolment needs a legal name and payment;
+organisation enrolment additionally needs a D-U-N-S number and takes longer.
+
+### What to create
+
+A **Developer ID Application** certificate — *not* "Apple Distribution", which is for the App
+Store and will not satisfy Gatekeeper for direct download.
+
+1. Xcode → Settings → Accounts → Manage Certificates → **+** → Developer ID Application.
+   (Or Certificates, Identifiers & Profiles on the developer portal with a CSR.)
+2. Export it from Keychain Access as a `.p12` with a strong password.
+3. Base64 it for CI: `base64 -i cert.p12 | pbcopy`.
+
+### Notarization credentials
+
+Notarization is a separate step: Apple scans the signed app and issues a ticket. It needs an
+**app-specific password**, not your Apple ID password — create one at <https://appleid.apple.com>
+under Sign-In and Security. You also need your **Team ID** (developer portal → Membership).
+
+Locally, store credentials in the keychain once so the secret never reaches an env var or a log:
+
+```bash
+xcrun notarytool store-credentials sdods-notary \
+  --apple-id you@example.com --team-id ABCDE12345 --password <app-specific-password>
+```
+
+### CI secrets
+
+| Secret | Value |
+|---|---|
+| `MAC_CSC_LINK` | base64 of the `.p12` |
+| `MAC_CSC_KEY_PASSWORD` | the `.p12` password |
+| `APPLE_ID` | the Apple ID email |
+| `APPLE_APP_SPECIFIC_PASSWORD` | app-specific password |
+| `APPLE_TEAM_ID` | 10-character Team ID |
+
+`.github/workflows/desktop.yml` already passes all five. electron-builder signs and notarizes when
+they are present and silently skips when they are not, so unsigned builds keep working.
+
+### What is already correct in this repo
+
+- `hardenedRuntime: true` — required for notarization.
+- `entitlements` **and** `entitlementsInherit` both point at `build/entitlements.mac.plist`.
+- That plist sets `com.apple.security.cs.disable-library-validation`. **Do not remove it.** The app
+  runs `.node` native modules that npm downloads at runtime; to the hardened runtime those are
+  unsigned code, so without this the app notarizes successfully and then dies at first database
+  open with an opaque dyld error.
+- `mac.binaries` lists `Contents/Resources/node/bin/node`, so the bundled Node runtime is signed
+  too. A second executable inside the bundle is not signed automatically.
+
+### Timing
+
+`notarytool` typically returns in 2–10 minutes for a 100–200 MB bundle, ~15 at the 95th percentile.
+Around major macOS releases it can take 30–60. Budget for it in the release process; it is not a
+sign that something is wrong.
+
+### Verifying
+
+```bash
+codesign --verify --deep --strict --verbose=2 /Applications/SDODS.app
+spctl -a -vvv -t install /Applications/SDODS.app     # expect "accepted / Notarized Developer ID"
+xcrun stapler validate /Applications/SDODS.app
+```
+
+### Until certificates exist
+
+Users can bypass Gatekeeper themselves — right-click SDODS in Applications → **Open** → confirm.
+macOS remembers the choice. The download page prints this automatically while
+`DESKTOP_RELEASE.signed` is false. `xattr -dr com.apple.quarantine /Applications/SDODS.app` also
+works but is worse advice to give strangers.
+
+---
+
+## Windows — SmartScreen
+
+### The gating question: where are you?
+
+**Azure Artifact Signing** (formerly Azure Trusted Signing) is the best option, but it is
+geographically restricted:
+
+- **Individual developers: USA and Canada only.**
+- Organisations: USA, Canada, EU, UK.
+
+If you are an individual outside the US/Canada, this route is closed and an OV certificate is the
+answer. Settle this before spending time on Azure — it determines the whole path.
+
+### Option A — Azure Artifact Signing (preferred where available)
+
+Generally available since April 2026. ~**$9.99/month** for 5,000 signatures and one certificate
+profile ($99.99/month for 100,000 and ten profiles) — cheaper than any traditional certificate,
+and **no hardware token**, which is what makes it work in CI at all.
+
+Individuals may now apply as self-employed; the 3-years-of-history requirement from the preview
+was dropped at GA. Identity validation runs through a third party (au10tix) and takes a few
+business days.
+
+Setup:
+
+1. Azure subscription → create an **Artifact Signing** account (pick the region nearest your CI).
+2. Complete identity validation. Assign yourself the **Identity Verifier** role — validation
+   cannot be completed without it, which is the usual place people get stuck.
+3. Create a **certificate profile** (type: Public Trust).
+4. Create a service principal for CI and grant it **Code Signing Certificate Profile Signer** on
+   the account.
+
+Then add to `apps/desktop/electron-builder.yml` under `win:`:
+
+```yaml
+win:
+  azureSignOptions:
+    publisherName: '<exact name on the certificate>'
+    endpoint: 'https://<region>.codesigning.azure.net/'
+    codeSigningAccountName: '<account>'
+    certificateProfileName: '<profile>'
+```
+
+and set `AZURE_TENANT_ID`, `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET` as CI secrets.
+
+**Version note:** the block above is electron-builder v26 syntax, which is what this repo pins
+(26.15.3, the current release). v27 collapses Windows signing into a single `win.sign`
+discriminated union (`type: 'signtool' | 'hsm' | 'pkcs11' | 'azure'`) and removes
+`win.azureSignOptions` / `win.signtoolOptions`; `electron-builder migrate-schema` rewrites it.
+Check which major version is installed before copying config from a blog post.
+
+### Option B — OV certificate
+
+From DigiCert, Sectigo, GlobalSign and similar. **$150–300/year.**
+
+Since June 2023 the CA/Browser Forum requires the private key to live on an HSM or hardware token.
+That is the real cost: a USB token cannot be plugged into a GitHub-hosted runner, so you either use
+the CA's cloud HSM option or sign on a self-hosted runner. Choose a cloud-HSM product if you want
+CI signing at all.
+
+Wire it through the existing `WIN_CSC_LINK` / `WIN_CSC_KEY_PASSWORD` secrets, or the CA's own
+signing tool via a custom `sign` hook.
+
+### Option C — self-signed
+
+Testing and enterprise-managed fleets only. Windows does not trust it, so public users get a
+**stronger** block than with no signature at all. Never ship this publicly.
+
+### Reputation
+
+Signing does not remove SmartScreen warnings on day one. Reputation accrues to the publisher
+identity as releases are downloaded and run without incident. What matters is signing **every**
+release with the **same** identity — switching certificates resets the accumulated trust.
+
+---
+
+## Linux
+
+No signing is required: AppImage and `.deb` install without any equivalent of Gatekeeper. Optional
+hardening if it becomes useful:
+
+- GPG-sign the `.deb` and publish the public key.
+- Ship a `.zsync` file beside the AppImage for delta updates.
+
+`SHA256SUMS.txt` already ships with every release, which is the verification most Linux users
+expect.
+
+---
+
+## Two corrections to common advice
+
+**EV certificates no longer bypass SmartScreen.** They did — instantly, on first download — which
+is why almost every older guide recommends paying the EV premium for a new app. **Microsoft removed
+that behaviour in 2024.** EV-signed files now build reputation exactly like OV-signed ones. An
+existing EV certificate is still perfectly valid; buying one *specifically* to skip SmartScreen is
+no longer justified. (I gave this outdated advice earlier in this project.)
+
+**"Azure Trusted Signing" is now "Azure Artifact Signing."** Same service, renamed. Search results
+and documentation are split across both names, and the individual-developer eligibility rules
+changed at GA — preview-era pages saying individuals cannot sign up are out of date.
+
+---
+
+## Is there a free option?
+
+**Windows: yes, but only for open source.** [SignPath Foundation](https://signpath.org/terms)
+gives qualifying projects free OV-level signing through a managed pipeline. Their conditions:
+
+- an **OSI-approved licence with no commercial dual-licensing** — Apache-2.0 qualifies;
+- **no proprietary or non-open-source components**, including code from the maintainer;
+- actively maintained, already released in the form to be signed, and functionality described on
+  the download page.
+
+SDODS is Apache-2.0, so the licence is fine — but the repository is **private**, and the programme
+is for open-source projects. Today it does not qualify. Making the source public would unlock it,
+and would also remove the need for the separate public releases repo and let the
+`NEXT_PUBLIC_REPO_PUBLIC` flags across both sites switch on. Applications take days to weeks.
+
+**macOS: no.** There is no free path to a Developer ID certificate or to notarization. A free Apple
+ID signs for local development only; the result still fails Gatekeeper on anyone else's Mac. The
+$99/year membership is unavoidable for direct distribution.
+
+**Linux: already free** — nothing to sign.
+
+So the realistic floors are **$99/year** (Apple, plus SignPath for Windows if the source goes
+public) or **~$219/year** (Apple plus Azure Artifact Signing at $9.99/month) with the source
+staying private.
+
+---
+
+## After signing works
+
+1. Verify a real download on a machine that has never seen the app, not the build machine.
+2. Sync the download page with `--signed`, which removes the Gatekeeper/SmartScreen instructions:
+   ```bash
+   bun run desktop:sync-release desktop-v0.1.0 --signed
+   ```
+3. Enable `electron-updater` for the app shell. It was left off deliberately: Squirrel.Mac
+   **refuses to install an unsigned update**, so auto-update only becomes real once macOS signing
+   is in place. See the `sdods-desktop-release` skill.

package/templates/.claude/skills/sdods-desktop-release/SKILL.md

@@ -0,0 +1,170 @@
+---
+name: sdods-desktop-release
+description: Build, test, release and publish the SDODS desktop app (apps/desktop) for macOS, Windows and Linux, and update the download page on sdods.com. Use when asked to build the desktop app, cut a desktop release, tag desktop-v*, publish installers, refresh the download page, or debug a packaged build that will not start.
+---
+
+# Releasing the SDODS desktop app
+
+The desktop app is an Electron **supervisor**: it owns a private SDODS workspace, installs
+`@sdods/cli` from npm into it, and runs `sdods serve` as a child of a **bundled Node runtime**. It
+does not reimplement SDODS and it does not host the server in-process.
+
+Read this before changing anything in `apps/desktop` — most of it is here because something failed
+in a way that produced no error message.
+
+## The loop
+
+```bash
+# 1. Prove the runtime contract (no Electron involved). Catches npm/init/native-module problems.
+bun run --cwd apps/desktop probe
+
+# 2. Develop
+bun run desktop:dev
+
+# 3. Package for this machine
+bun run --cwd apps/desktop dist:mac      # dist:win · dist:linux
+
+# 4. Release
+git tag desktop-v0.1.0 && git push origin desktop-v0.1.0   # triggers .github/workflows/desktop.yml
+#    ... workflow drafts a release in the PUBLIC releases repo; publish it by hand ...
+bun run desktop:sync-release desktop-v0.1.0                # writes apps/www/lib/desktop-release.ts
+git commit -am 'chore(www): desktop 0.1.0 downloads' && merge to main   # www workflow deploys
+```
+
+**Order matters.** Sync the manifest only after the release is *published*, not while it is a
+draft — the download page links straight at the asset URLs, and draft assets are not downloadable.
+The sync script refuses to run against a draft for exactly this reason.
+
+## Where the binaries live, and why not in this repo
+
+`siri1410/SDODS` is **private**, and **release assets on a private repo are private too** — a
+GitHub download link would 404 for every visitor. So installers are published to a separate
+**public** repository that holds nothing but releases:
+
+```bash
+gh repo create siri1410/sdods-releases --public -d 'SDODS desktop installers'
+```
+
+Then, on the source repo: a `DESKTOP_RELEASE_TOKEN` secret (a fine-grained PAT with
+`Contents: read+write` on the releases repo **only** — `GITHUB_TOKEN` cannot write across
+repositories), and optionally a `DESKTOP_RELEASE_REPO` variable to point somewhere else.
+
+Source stays closed; only the built installers are public. This also keeps `electron-updater`
+straightforward later, since it reads GitHub releases natively.
+
+**Beware:** `git ls-remote https://github.com/siri1410/SDODS.git` **succeeds** on a machine with
+`gh auth` configured, because its credential helper is global. That is not an anonymous probe and
+it has produced the wrong conclusion here twice. Check visibility with
+`gh api repos/<slug> --jq .private`.
+
+## Naming and versioning
+
+- **SemVer** on `apps/desktop/package.json`; the tag is `desktop-v<version>`, kept separate from
+  the `@sdods/*` npm versions because the app ships on its own cadence.
+- **Every artifact says what it is**: `<product>-<version>-<platform>-<arch>.<ext>` —
+  `SDODS-0.1.0-mac-arm64.dmg`, `SDODS-Setup-0.1.0-win-x64.exe`,
+  `SDODS-0.1.0-linux-x64.AppImage`. electron-builder's defaults omit the platform on macOS, so
+  `SDODS-0.1.0-arm64.dmg` could equally be a Linux build in a listing of six files.
+- **`SHA256SUMS.txt`** ships with every release. It matters more than usual while builds are
+  unsigned: it is the only way a user can verify what they downloaded.
+  `sha256sum -c SHA256SUMS.txt --ignore-missing`
+
+## Verifying a build actually works
+
+A packaged build that starts is not the same as one that works. The real test is a run started
+from the app's own Runs page — that exercises `process.execPath`, the workspace layout and the
+browser cache at once.
+
+```bash
+# Install like a user, then launch with NOTHING on PATH. This is the zero-prerequisite promise.
+env -i HOME="$HOME" USER="$USER" TMPDIR="$TMPDIR" PATH="/usr/bin:/bin:/usr/sbin:/sbin" \
+  SDODS_DESKTOP_WORKSPACE=/tmp/sdods-test \
+  /Applications/SDODS.app/Contents/MacOS/SDODS
+```
+
+Then: Runs → Start run → layer `ui`, browser `chromium`, tags `@smoke` → Run. It should pass 4/0/0.
+
+Useful env vars:
+
+| Variable | Purpose |
+|---|---|
+| `SDODS_DESKTOP_WORKSPACE` | Override the `~/SDODS` default. Always set this when testing, or you litter the real home directory. |
+| `SDODS_DESKTOP_NODE` | Point at a specific `node` binary instead of the staged/system one. |
+
+Logs: `~/Library/Application Support/SDODS/logs/desktop.log` (menu → Open Logs Folder). App state
+lives beside it; `rm -rf` that directory for a clean first-run test.
+
+## Traps — each one cost a debugging session
+
+**Never spawn `process.execPath`.** Under Electron that is the Electron binary, so spawning it
+launches a second copy of the app, which hits the single-instance lock and dies **silently**. Use
+`nodeBin()` from `src/main/runtime.ts`. Same reason the server is a child process rather than
+in-process: `packages/server/src/services/cli.ts` builds every child argv from `process.execPath`.
+
+**Never spawn `npm` by bare name.** Windows has `npm.cmd`, not `npm`, and a GUI app launched from
+the Dock inherits a minimal PATH. Use `npmCli()`, which resolves npm's own entry point.
+
+**A missing `extraResources` source is only a warning.** It once produced an x64 `.dmg` with no
+Node runtime and a zero exit code. `scripts/before-pack.mjs` stages the runtime per arch and fails
+hard; `desktop.yml` re-checks every packaged app. Do not remove either.
+
+**Signals do not fire in the packaged app.** A SIGTERM runs none of `before-quit`, `will-quit`,
+`exit`, or `process.on('SIGTERM')` — Electron terminates natively — so the detached server child
+outlives the app. The guarantee is the pidfile: the server's pid is recorded and the next launch
+reaps it. Test it with `kill -9` on the app, not `kill`.
+
+**Browsers are needed for every layer, not just UI.** SDODS merges one BDD fixture set across
+layers, so an api-layer run against an empty `PLAYWRIGHT_BROWSERS_PATH` fails with
+`browserType.launch: Executable doesn't exist`. Chromium is fetched after the dashboard loads.
+
+**`sdods init` needs `--force --no-install --no-browsers`.** It refuses a non-empty directory,
+its `--pm` accepts only `bun|pnpm` (neither is on a user machine), and it would pull browsers. It
+overwrites `package.json` on purpose — its manifest declares `@playwright/test` and
+`playwright-bdd`, which `sdods run` needs — so npm install runs again afterwards.
+
+**`@sdods/server@0.2.1` hardcodes `cliBin: resolve(rootDir, 'packages/cli/src/bin.ts')`**, a
+monorepo-only path, so UI-triggered runs die with ERR_MODULE_NOT_FOUND. `bootstrap.ts` writes a
+bridge at that path, but only while the installed server still contains that string. **Publishing a
+server newer than 0.2.1 removes the need for it** and fixes `sdods serve` for every npm user.
+
+**Do not build the macOS `universal` target.** It lipo-merges two packs that each want a different
+`node` binary at one path. `before-pack.mjs` rejects it. Ship separate arm64 and x64 artifacts.
+
+**`apps/desktop` must declare no production dependencies.** electron-builder's dependency collector
+has no handling for bun's `node_modules/.bun` symlink layout. Everything is bundled by rollup and
+`files` excludes `node_modules` outright. Adding a runtime dependency will break packaging.
+
+## Browser architecture detection on the download page
+
+An Apple silicon Mac reports `Intel Mac OS X` in its user agent. Parsing the UA alone recommends
+the Intel build to nearly every modern Mac. `detectArch()` uses
+`navigator.userAgentData.getHighEntropyValues(['architecture'])`, which is truthful on Chromium;
+Safari and Firefox return nothing, so macOS defaults to Apple silicon deliberately. Every other
+build is listed underneath, and the full list is server-rendered so no-JS visitors lose nothing.
+
+## Signing
+
+Builds are unsigned today, so macOS shows "damaged / unidentified developer" and Windows shows
+SmartScreen. The download page prints the per-OS workaround automatically while
+`DESKTOP_RELEASE.signed` is false.
+
+Everything is wired behind CI secrets already — supply them and signing turns on with no code
+change: `CSC_LINK`, `CSC_KEY_PASSWORD`, `APPLE_ID`, `APPLE_APP_SPECIFIC_PASSWORD`, `APPLE_TEAM_ID`
+for macOS; `WIN_CSC_LINK`, `WIN_CSC_KEY_PASSWORD` for Windows. Obtaining the certificates requires
+a person: Apple Developer Program ($99/yr), and for Windows **Azure Trusted Signing** (~$10/month)
+rather than a traditional OV certificate, which has required an FIPS hardware token since June 2023
+and does not fit CI. After signing lands, pass `--signed` to `desktop:sync-release`.
+
+## Files
+
+| Path | What it is |
+|---|---|
+| `apps/desktop/src/main/index.ts` | Lifecycle: bootstrap → serve → authenticate → load. Pidfile and orphan reaping. |
+| `apps/desktop/src/main/runtime.ts` | Bundled Node resolution and the child environment. |
+| `apps/desktop/src/main/bootstrap.ts` | The five-step first-run install, and the 0.2.1 CLI bridge. |
+| `apps/desktop/src/main/server.ts` | Port choice, `sdods serve` child, health poll, setup-token capture. |
+| `apps/desktop/src/main/auth.ts` | Admin creation, safeStorage vault, cookie injection. |
+| `apps/desktop/scripts/probe.ts` | The runtime contract, provable without Electron. |
+| `apps/desktop/scripts/fetch-node-runtime.ts` | Downloads + SHASUMS-verifies + prunes Node. |
+| `scripts/sync-desktop-release.ts` | GitHub release → `apps/www/lib/desktop-release.ts`. |
+| `.github/workflows/desktop.yml` | Tag-gated matrix build, artifact verification, draft release. |