@bongos/core 1.18.0 → 1.18.18

package/migrations/core_195_idea_triage_provenance.sql

@@ -0,0 +1,57 @@
+-- core_195_idea_triage_provenance.sql — give a triage VERDICT somewhere to
+-- record what it decided (task 1002447).
+--
+-- Triage has three verbs; only two of them had storage. `status` records THAT an
+-- idea was discarded or merged, and `promoted_to_task_id` records the task a
+-- promotion produced — but nothing recorded WHICH idea a merge folded into, or
+-- WHY a discard happened. `promoted_to_task_id` cannot stand in for the merge
+-- target: it is `REFERENCES tasks(id)`, so writing an idea id there either trips
+-- the FK or silently points at an unrelated task. BOTH callers that documented
+-- or performed that write are corrected alongside this migration — the
+-- /idea-triage skill doc and the interactive walker `scripts/gds/triage.js`.
+-- Without a target, "merge" is just "discard" wearing a different label.
+--
+-- CORE, not modules/ideas/migrations/, even though the ideas module owns every
+-- query against this table: `idea_inbox` is a CORE table, and a module migration
+-- may only touch its own <key>_-prefixed objects — `fitness.js`
+-- checkModuleMigrationsAdditive hard-fails an `ALTER TABLE idea_inbox` from a
+-- module (ADR 0083 §Decision #5). The module's "new ideas migration goes in
+-- modules/ideas/migrations/" note applies to objects the module OWNS, and it
+-- owns none.
+--
+-- Two additive, nullable columns. Forward-safe by construction: every existing
+-- reader SELECTs an explicit column list, so old code on the new schema neither
+-- sees nor needs these (tests/migrations_forward_safe.mjs).
+
+BEGIN;
+
+ALTER TABLE idea_inbox
+  ADD COLUMN IF NOT EXISTS merged_into_idea_id bigint REFERENCES idea_inbox(id);
+
+ALTER TABLE idea_inbox
+  ADD COLUMN IF NOT EXISTS triage_note text;
+
+-- A target exists IFF the idea is merged. Without this, two ordinary PATCHes
+-- build a merge CHAIN: set A's target while leaving A open, then merge C into A
+-- — whose status still reads 'open', so a status-based no-chains check waves it
+-- through. One direction only (`target IS NULL OR status='merged'`), because
+-- every pre-existing merged row has a NULL target and must stay valid.
+-- CHECK constraints have no ADD ... IF NOT EXISTS, so guard the add (the
+-- migration 042 idiom) and keep the file replay-safe.
+DO $$
+BEGIN
+  IF NOT EXISTS (
+    SELECT 1 FROM pg_constraint
+     WHERE conrelid = 'idea_inbox'::regclass
+       AND conname = 'idea_inbox_merge_target_needs_merged_status'
+  ) THEN
+    ALTER TABLE idea_inbox
+      ADD CONSTRAINT idea_inbox_merge_target_needs_merged_status
+      CHECK (merged_into_idea_id IS NULL OR status = 'merged');
+  END IF;
+END $$;
+
+INSERT INTO schema_migrations (version) VALUES ('core_195_idea_triage_provenance')
+  ON CONFLICT DO NOTHING;
+
+COMMIT;

package/migrations/core_196_session_reward_topup.sql

@@ -0,0 +1,69 @@
+-- core_196_session_reward_topup.sql
+-- Let a multi-ship session be paid for ALL of its cost, not just its first ship.
+--
+-- WHY THIS IS A CORE MIGRATION, NOT modules/economy/. credit_log is a CORE table — the
+-- economy module owns the queries against it, not the table itself (ADR 0083 §Decision #5;
+-- modules/economy/CLAUDE.md "Tables: None owned"). A module migration may only touch its own
+-- economy_-namespaced objects, so this shipped as economy_002_* and reddened the fitness gate
+-- three ways (destructive DDL + index + alter on a non-namespaced table). The real defect was
+-- placement, not DDL: as a module migration these columns only existed when the economy module
+-- happened to be ENABLED, which makes core schema depend on module enablement — the exact
+-- coupling the rule forbids. Relocated per the core_195 precedent (task 1002447).
+--
+-- schema_migrations is stem-keyed, so this re-applies once under its new stem. That is safe
+-- BECAUSE every statement below is IF [NOT] EXISTS — the re-run is a no-op on any database
+-- that already had it as economy_002.
+--
+-- THE DEFECT. Migration 091 made the cost-plus session reward idempotent with a
+-- PARTIAL UNIQUE INDEX on credit_log (session_id) WHERE reason='session.token_reward'
+-- — "the hard DB-level backstop against a double payout". That is correct and stays.
+-- But it was the ONLY control, so once a session booked its first reward row, every
+-- later ship in the same session was a hard no-op. A session's cost keeps growing
+-- after its first ship, and that increment had nowhere to land.
+--
+-- Measured: three tasks shipped from one session, priced $14.30 / $27.76 / $40.32,
+-- paid 17 drachmae where the whole session was worth round(40.32 × 1.20) = 48.
+-- Roughly 65% of real, shipped, graded work went unrewarded. Multi-ship sessions are
+-- normal — one claim at a time, but ship -> new worktree -> claim again.
+--
+-- THE FIX is watermark accounting: each landed ship books the DIFFERENCE between what
+-- the whole session is now worth and what it has already been paid. That needs more
+-- than one row per session, so uniqueness moves from (session_id) to
+-- (session_id, reward_basis) — still scoped to the same reason.
+--
+-- WHY A CUMULATIVE BASIS AND NOT THE DELTA. Two concurrent uploads at the SAME cost
+-- level must still collide and DO NOTHING. reward_basis is the CUMULATIVE owed total
+-- at the moment of the row, so it is monotonic and identical for a racing pair. A bare
+-- delta would be wrong: two genuine increments that happened to be equal would
+-- collide and one payment would be silently lost.
+--
+-- Additive and non-destructive. No historical row changes value.
+
+-- (a) The cumulative cost-plus total this session was owed when the row was written.
+--     NOT NULL DEFAULT 0 (rather than nullable) so the unique index below has clean
+--     semantics: Postgres treats NULLs as DISTINCT in a unique index, so a nullable
+--     basis would let two legacy rows share a session_id and would WEAKEN the very
+--     backstop 091 added.
+--
+--     Existing rows therefore land on reward_basis = 0, which is the marker for
+--     "booked before top-ups existed". The application refuses to top those up: doing
+--     so would be an uncontrolled retroactive payout across every historical session.
+--     Reconstructing what past sessions are owed is a deliberate, owner-signed-off
+--     backfill, tracked separately.
+ALTER TABLE credit_log
+  ADD COLUMN IF NOT EXISTS reward_basis integer NOT NULL DEFAULT 0;
+
+-- (b) Swap the uniqueness key. CREATE the replacement BEFORE dropping the original so
+--     the double-pay backstop is never absent, not even inside this transaction.
+--
+--     For legacy rows (all at basis 0) the new index is exactly as strict as the old
+--     one — (session_id, 0) is unique per session — so nothing already paid can be
+--     paid twice.
+CREATE UNIQUE INDEX IF NOT EXISTS uniq_credit_session_token_reward_basis
+  ON credit_log (session_id, reward_basis)
+  WHERE reason = 'session.token_reward';
+
+DROP INDEX IF EXISTS uniq_credit_session_token_reward;
+
+-- Counter hygiene: as a core migration this consumes core number 196 (next free after
+-- core_195), so the core allocator floor advances with it.

package/modules/autonomy/pollers/routine-timers.js

@@ -8,10 +8,12 @@
 // contributes.pollers:["routine-timers"]; the loader (src/module-loader/loader.js
 // startModulePollers) requires THIS file and calls start(deps) at boot, stop() at
 // shutdown — the module-agnostic successor to the hardcoded `routineTimers.start()`
-// block server.js used to carry. server.js (the game/droplet entrypoint) is the
-// ONLY caller of startModulePollers, never src/platform-server.js, so a future
-// second always-on instance on the same DB can't double-run (and the FOR UPDATE
-// row lock in tallyPeerVotes is the hard guard if one ever does).
+// block server.js used to carry. src/platform-server.js is now the ONLY caller of
+// startModulePollers (task 1002419) — server.js, the retired game/droplet
+// entrypoint, was the previous one, and while it was gone NO module poller ran at
+// all. It runs as a single process (docker-entrypoint.sh `exec`s it, no cluster),
+// so a second always-on instance on the same DB still can't double-run — and the
+// FOR UPDATE row lock in tallyPeerVotes is the hard guard if one ever does.
 //
 // WHY THIS EXISTS
 // ADR 0078 demoted peer-vote-tally to `mode: deterministic` and built an EXTERNAL
@@ -100,10 +102,9 @@ async function runPeerVoteTally(deps = {}) {
 
 // Start the timer(s). Idempotent. Kill-switched by ROUTINE_TIMERS_DISABLED=1.
 // Unref'd so it never holds the process open on a systemd restart. Started by the
-// loader's startModulePollers ONLY on the game/droplet entrypoint (server.js),
-// never in src/platform-server.js, so a future second always-on instance on the
-// same DB can't double-run (and the FOR UPDATE row lock in tallyPeerVotes is the
-// hard guard if one ever does).
+// loader's startModulePollers from src/platform-server.js — the single always-on
+// entrypoint (task 1002419) — so a second instance on the same DB can't double-run
+// (and the FOR UPDATE row lock in tallyPeerVotes is the hard guard if one ever does).
 function start(deps = {}) {
   if (process.env.ROUTINE_TIMERS_DISABLED === '1') {
     console.log('[routine-timers] disabled (ROUTINE_TIMERS_DISABLED=1)');

package/modules/builder-settings/wandering-prefs.js

@@ -18,13 +18,14 @@
 // blob; future behavior knobs add their own reserved keys. A missing key falls
 // back to the rank-derived default below, so the column stays sparse.
 //
-// Resolution = default-by-rank, capped-by-rank, server-enforced.
+// Resolution = default-by-role, capped-by-role, server-enforced (see the ROLE
+// METADATA block below for why a ceiling is metadata and not a permission).
 //   - DEFAULT level rides the trust ladder (Xenos→Locked … Archon→Exploratory).
-//   - MAX (ceiling) per rank: Xenos and Thetes are capped at their default (they
-//     may dial DOWN for more focus, never UP); Metic and Archon may set any
-//     level (their rank is a starting default, not a ceiling). Owner decision
+//   - CEILING per role: Xenos and Thetes are capped at their default (they may
+//     dial DOWN for more focus, never UP); Metic and Archon may set any level
+//     (their rank is a starting default, not a ceiling). Owner decision
 //     2026-06-19: "Thetes is gated; Metic is just a starting default."
-//   - effectiveLevel = clamp(override ?? default, 0, maxForRank). So a Xenos who
+//   - effectiveLevel = clamp(override ?? default, 0, ceiling). So a Xenos who
 //     stores Exploratory is still resolved to Locked — opening the setting up
 //     for self-service later stays safe because the clamp is the enforcement,
 //     not the UI.
@@ -98,15 +99,54 @@ const LEVEL_CONTRACT = Object.freeze({
     + 'investigations worth the user\'s attention as you go, while still landing the claimed task.',
 });
 
-// Default level per rank (the array index in LEVELS). Rides the live rank
-// ladder (xenos<thetes<metic<archon — db.RANKS / boxes.RANK_ORDER). A rank not
-// listed (e.g. a reserved/penalty rank, or an unknown string) falls back to the
-// safest floor: Locked.
-const RANK_DEFAULT = Object.freeze({ xenos: 0, thetes: 1, metic: 2, archon: 3 });
+// ---- the wandering ceiling as ROLE METADATA (BV1.R107, ADR 0151) ----
+//
+// The governance model makes a permission a BOOLEAN atom and a rank a seeded
+// ROLE. A wandering ceiling is neither: it is a NUMBER in 0..3. Spelling it as
+// permissions would need one catalog key per level (`me.wandering.level.0..3`) —
+// four keys no route consumes individually, against the catalog's first rule
+// ("a permission no route consumes does not exist") and multiplying the key count
+// to encode a quantity that was never a yes/no capability.
+//
+// So the ceiling is ROLE METADATA: a property carried BY the role, alongside —
+// not inside — the permission that authorizes the write. The two compose:
+//   • the PERMISSION `me.wandering.set` (catalog: floor xenos, scope 'own',
+//     resource 'builder_prefs') answers MAY this builder set their OWN level. It
+//     is ownership-scoped, so it is answered by resolver.authorizeOwned(), never
+//     by an unconditional "do they hold it" — that is the route gate's business.
+//   • the ROLE METADATA below answers HOW HIGH they may set it. Holding the
+//     permission is never sufficient on its own: effectiveLevel() clamps to the
+//     role's ceiling server-side, so the ceiling is enforcement, not UI copy.
+//
+// Keyed by ROLE KEY. The four seeded rank-roles are named for the ranks they seed
+// (governance_002), so a role key and a rank string coincide — which is why the
+// rank-keyed helpers below still resolve correctly, and why BV1.R108 can fold this
+// table onto the one live ladder without changing a value. A role this table does
+// not name carries NO wandering metadata and resolves to the safest floor
+// (Locked), the same fail-closed posture the resolver takes for a rank with no
+// seeded role.
+const ROLE_WANDERING = Object.freeze({
+  xenos: Object.freeze({ default: 0, ceiling: 0 }),
+  thetes: Object.freeze({ default: 1, ceiling: 1 }),
+  metic: Object.freeze({ default: 2, ceiling: 3 }),
+  archon: Object.freeze({ default: 3, ceiling: 3 }),
+});
+const NO_ROLE_WANDERING = Object.freeze({ default: 0, ceiling: 0 });
+
+function roleWandering(roleKey) {
+  return Object.prototype.hasOwnProperty.call(ROLE_WANDERING, roleKey)
+    ? ROLE_WANDERING[roleKey]
+    : NO_ROLE_WANDERING;
+}
 
-// Ceiling per rank. Below Metic the default IS the ceiling (dial down only);
-// Metic+ may pick any level. Unknown rank → floor (0).
-const RANK_MAX = Object.freeze({ xenos: 0, thetes: 1, metic: 3, archon: 3 });
+// DERIVED projections of the metadata above, kept because scripts/gds/session-eval.js
+// and the /me payload read them by rank. Deriving them means the two views cannot drift.
+const RANK_DEFAULT = Object.freeze(
+  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.default])),
+);
+const RANK_MAX = Object.freeze(
+  Object.fromEntries(Object.entries(ROLE_WANDERING).map(([role, meta]) => [role, meta.ceiling])),
+);
 
 const TOP_LEVEL = LEVELS.length - 1; // 3
 const RESERVED_KEY = 'wandering';
@@ -120,9 +160,10 @@ for (const key of LEVELS) {
 for (let i = 0; i < LEVELS.length; i++) {
   if (LEVEL_META[LEVELS[i]].n !== i) throw new Error(`wandering-prefs: LEVEL_META.${LEVELS[i]}.n must equal its index ${i}`);
 }
-for (const rank of Object.keys(RANK_DEFAULT)) {
-  if (!(rank in RANK_MAX)) throw new Error(`wandering-prefs: RANK_DEFAULT has '${rank}' but RANK_MAX does not`);
-  if (RANK_DEFAULT[rank] > RANK_MAX[rank]) throw new Error(`wandering-prefs: default > max for rank '${rank}'`);
+for (const [role, meta] of Object.entries(ROLE_WANDERING)) {
+  if (!isLevelInt(meta.default)) throw new Error(`wandering-prefs: role '${role}' has a non-level default`);
+  if (!isLevelInt(meta.ceiling)) throw new Error(`wandering-prefs: role '${role}' has a non-level ceiling`);
+  if (meta.default > meta.ceiling) throw new Error(`wandering-prefs: default > ceiling for role '${role}'`);
 }
 
 // ---- pure helpers ----
@@ -141,11 +182,11 @@ function levelIndex(key) {
 }
 
 function defaultLevelForRank(rank) {
-  return Object.prototype.hasOwnProperty.call(RANK_DEFAULT, rank) ? RANK_DEFAULT[rank] : 0;
+  return roleWandering(rank).default;
 }
 
 function maxLevelForRank(rank) {
-  return Object.prototype.hasOwnProperty.call(RANK_MAX, rank) ? RANK_MAX[rank] : 0;
+  return roleWandering(rank).ceiling;
 }
 
 // The override a builder has stored (the raw 'wandering' key off behavior_prefs),
@@ -262,6 +303,8 @@ module.exports = {
   LEVELS,
   LEVEL_META,
   LEVEL_CONTRACT,
+  ROLE_WANDERING,
+  roleWandering,
   RANK_DEFAULT,
   RANK_MAX,
   TOP_LEVEL,

package/modules/dev-box/app/README.md

@@ -0,0 +1,73 @@
+# OTB Dev Box — the desktop switch for a builder's hosted box
+
+A menu-bar (macOS) / system-tray (Windows) app that turns a builder's hosted
+dev box on and off with one switch. Built for the newcomer who should never
+see a terminal: sign in with browser clicks (app pairing, ADR 0045), flip the
+switch, and connect from Claude Desktop or the browser terminal.
+
+What it does beyond the switch — each fixing a failure observed in the
+2026-06-10 onboarding sessions that killed the old `curl | bash` flow:
+
+- **Pairing sign-in** — opens the builders' hall, one Approve click, token
+  delivered over the app's own secret channel (`/api/gds/auth/app-pair/*`).
+  The session is written to `~/.config/otb/gds-session.json`, the same file
+  the `/builder-*` CLI uses — pairing the app signs in the CLI too.
+- **SSH key done right** — generates `~/.ssh/otb_builder` (ed25519) with real
+  600 perms (icacls ACL on Windows) and registers it via `POST /box/ssh-key`.
+- **known_hosts kept fresh** — Claude Desktop's embedded ssh2 reads ONLY
+  `~/.ssh/known_hosts`, and host keys change on every re-provision; the app
+  re-scans and replaces entries each time the box turns active.
+- **Claude Desktop connection file** — installs the managed-settings file to
+  the system path with a native elevation prompt (osascript / UAC), the step
+  the agent-driven flow could never finish.
+- **Native notifications** — box ready, rested while idle.
+- **No heartbeats** — the app never sends `claude_active`; the droplet's idle
+  sweep stays authoritative so an unused box still reclaims itself (~10 min).
+
+## Layout
+
+- `src/main.js` — Electron main: tray, window, IPC, wiring.
+- `src/brand.js` — every brand string (ADR 0004: the civ name lives here only).
+- `src/{pairing,box-controller,gds-client,session-store,ssh-setup,updater}.js` — the
+  logic, Electron-free and unit-tested in `test/unit.mjs`.
+- `src/updater.js` — in-app update check (#924): semver compare + platform→target
+  resolution. `main.js` polls `GET /downloads/devbox/version` on open + every 12h
+  and, when the published release is strictly newer, shows the Update banner; the
+  Update button downloads the installer and hands it to the OS (browser-download
+  fallback on any error). **Bumping `config/devbox-app.json` version is what makes
+  the banner appear in the field** — see [`docs/recipes/devbox-app-release.md`](../docs/recipes/devbox-app-release.md).
+- `renderer/` — the panel UI (sandboxed, contextIsolated; preload exposes
+  named verbs only).
+- `scripts/gen-icons.js` — regenerates all icons from pixel grids (`npm run
+  icons`; borrows `sharp` from the repo root's node_modules).
+
+## Develop
+
+```
+cd devbox-app
+npm install
+npm test          # hermetic unit tests, no Electron needed
+npm start         # run against prod (or OTB_DEVBOX_API_BASE=http://… npm start)
+```
+
+Dev/test env hooks: `OTB_DEVBOX_API_BASE` (point at a stub/staging GDS),
+`OTB_DEVBOX_NO_ELEVATE=1` (skip the managed-settings elevation prompt),
+`OTB_DEVBOX_SCREENSHOT_DIR` (write a PNG of the panel on every state change —
+how CI/verification captures proof).
+
+## Build & release
+
+```
+npm run dist:mac   # dmg, arm64 + x64 (unsigned → ad-hoc)
+npm run dist:win   # NSIS one-click installer, x64 + arm64
+```
+
+CI builds both on every push that touches `devbox-app/**`
+(`.github/workflows/build-devbox-app.yml`) and uploads them as artifacts.
+Publishing = attach the artifacts to a release on the PUBLIC releases repo
+named in `config/devbox-app.json`, then bump that config and ship — the
+branded `/downloads/devbox/*` redirects follow the config. Full recipe:
+`docs/recipes/devbox-app-release.md`.
+
+This subproject is self-contained on purpose: its `package.json` never feeds
+the droplet's `npm ci`, and nothing under `devbox-app/` runs server-side.

package/modules/dev-box/app/electron-builder.tmpl.yml

@@ -0,0 +1,95 @@
+# TEMPLATE — rendered to electron-builder.yml by scripts/gen-brand.js from
+# config/branding.json (@@TOKENS@@ are substituted; ${version}/${arch}/${ext}
+# are electron-builder's own and stay literal). Edit THIS file, never the
+# generated electron-builder.yml.
+#
+# Brand strings (appId, productName, copyright, artifact slug) come from the
+# instance branding so one source tree builds any instance's app (ADR 0004,
+# generalised). Signing rides the instance's own CI (main-ref-gated Apple
+# Developer ID; ADR 0072) — an unarmed build ad-hoc-signs the mac app, which
+# arm64 requires to launch at all.
+#
+# Artifact names are pinned (no spaces, no world name inside — ADR 0004) and
+# MUST match config/devbox-app.json's assets map; tests/devbox_downloads.mjs
+# cross-checks the config side.
+
+appId: @@APP_ID@@
+productName: @@PRODUCT_NAME@@
+copyright: @@COPYRIGHT@@
+
+# buildResources is named build-resources (not electron-builder's default
+# `build`) because the repo root .gitignore ignores build/ everywhere and the
+# app icon in here is COMMITTED source, not output.
+directories:
+  buildResources: build-resources
+  output: dist
+
+files:
+  - src/**/*
+  - renderer/**/*
+  - assets/**/*
+  - package.json
+
+asar: true
+
+mac:
+  category: public.app-category.developer-tools
+  icon: build-resources/icon.png
+  target:
+    - target: dmg
+      arch: [arm64, x64]
+  artifactName: @@PRODUCT_SLUG@@-${version}-${arch}.${ext}
+
+dmg:
+  artifactName: @@PRODUCT_SLUG@@-${version}-${arch}.${ext}
+  # On-brand install window (task 912). The backdrop
+  # (build-resources/dmg-background.png + @2x, drawn by
+  # scripts/gen-dmg-backdrop.py) guides the drag from the container (the app)
+  # into Applications. iconSize + window + the contents coords MUST match
+  # the icon-well centers the backdrop draws (LEFT 180,198 / RIGHT 480,198) — if
+  # you move one, re-run the generator. The volume icon is the app icon (the
+  # container). electron-builder auto-picks dmg-background@2x.png on Retina.
+  #
+  # task 1235: this electron-builder DMG is only an INTERMEDIATE. Its window
+  # backdrop does NOT render on macOS >= Sonoma — electron-builder writes a
+  # `pBBk` bookmark Finder can't resolve, so the install window shows up white.
+  # The CI step "Apply install-window backdrop (dmgbuild)" re-packages the
+  # signed+notarized .app out of this DMG into the FINAL DMG via dmgbuild
+  # (scripts/apply-dmg-backdrop.sh + scripts/dmgbuild-settings.py), which writes
+  # an alias-only .DS_Store that DOES render. Keep the coords below in sync with
+  # dmgbuild-settings.py (currently identical: 180,198 / 480,198, 660x400, size 100).
+  icon: build-resources/icon.png
+  background: build-resources/dmg-background.png
+  iconSize: 100
+  window:
+    width: 660
+    height: 400
+  contents:
+    - x: 180
+      y: 198
+      type: file
+    - x: 480
+      y: 198
+      type: link
+      path: /Applications
+
+win:
+  icon: build-resources/icon.png
+  target:
+    - target: nsis
+      # x64 covers Intel/AMD PCs; arm64 is native for ARM Windows (Surface,
+      # Snapdragon laptops, Parallels VMs on Apple-silicon Macs). x64 also
+      # RUNS on arm64 via Windows emulation, so x64 stays the safe default
+      # link; arm64 is the first-class build for those machines (#908).
+      arch: [x64, arm64]
+
+nsis:
+  oneClick: true
+  perMachine: false
+  runAfterFinish: true
+  deleteAppDataOnUninstall: false
+  # ${arch} suffix added in #908 when arm64 joined — two arches can't share
+  # one filename. Must stay in lockstep with config/devbox-app.json assets.
+  artifactName: @@PRODUCT_SLUG@@-Setup-${version}-${arch}.${ext}
+
+publish: null

package/modules/dev-box/app/electron-builder.yml

@@ -0,0 +1,95 @@
+# TEMPLATE — rendered to electron-builder.yml by scripts/gen-brand.js from
+# config/branding.json (@@TOKENS@@ are substituted; ${version}/${arch}/${ext}
+# are electron-builder's own and stay literal). Edit THIS file, never the
+# generated electron-builder.yml.
+#
+# Brand strings (appId, productName, copyright, artifact slug) come from the
+# instance branding so one source tree builds any instance's app (ADR 0004,
+# generalised). Signing rides the instance's own CI (main-ref-gated Apple
+# Developer ID; ADR 0072) — an unarmed build ad-hoc-signs the mac app, which
+# arm64 requires to launch at all.
+#
+# Artifact names are pinned (no spaces, no world name inside — ADR 0004) and
+# MUST match config/devbox-app.json's assets map; tests/devbox_downloads.mjs
+# cross-checks the config side.
+
+appId: com.cloudbongos.devbox
+productName: Cloud Bongos Dev Box
+copyright: © Cloud Bongos
+
+# buildResources is named build-resources (not electron-builder's default
+# `build`) because the repo root .gitignore ignores build/ everywhere and the
+# app icon in here is COMMITTED source, not output.
+directories:
+  buildResources: build-resources
+  output: dist
+
+files:
+  - src/**/*
+  - renderer/**/*
+  - assets/**/*
+  - package.json
+
+asar: true
+
+mac:
+  category: public.app-category.developer-tools
+  icon: build-resources/icon.png
+  target:
+    - target: dmg
+      arch: [arm64, x64]
+  artifactName: Cloud-Bongos-Dev-Box-${version}-${arch}.${ext}
+
+dmg:
+  artifactName: Cloud-Bongos-Dev-Box-${version}-${arch}.${ext}
+  # On-brand install window (task 912). The backdrop
+  # (build-resources/dmg-background.png + @2x, drawn by
+  # scripts/gen-dmg-backdrop.py) guides the drag from the container (the app)
+  # into Applications. iconSize + window + the contents coords MUST match
+  # the icon-well centers the backdrop draws (LEFT 180,198 / RIGHT 480,198) — if
+  # you move one, re-run the generator. The volume icon is the app icon (the
+  # container). electron-builder auto-picks dmg-background@2x.png on Retina.
+  #
+  # task 1235: this electron-builder DMG is only an INTERMEDIATE. Its window
+  # backdrop does NOT render on macOS >= Sonoma — electron-builder writes a
+  # `pBBk` bookmark Finder can't resolve, so the install window shows up white.
+  # The CI step "Apply install-window backdrop (dmgbuild)" re-packages the
+  # signed+notarized .app out of this DMG into the FINAL DMG via dmgbuild
+  # (scripts/apply-dmg-backdrop.sh + scripts/dmgbuild-settings.py), which writes
+  # an alias-only .DS_Store that DOES render. Keep the coords below in sync with
+  # dmgbuild-settings.py (currently identical: 180,198 / 480,198, 660x400, size 100).
+  icon: build-resources/icon.png
+  background: build-resources/dmg-background.png
+  iconSize: 100
+  window:
+    width: 660
+    height: 400
+  contents:
+    - x: 180
+      y: 198
+      type: file
+    - x: 480
+      y: 198
+      type: link
+      path: /Applications
+
+win:
+  icon: build-resources/icon.png
+  target:
+    - target: nsis
+      # x64 covers Intel/AMD PCs; arm64 is native for ARM Windows (Surface,
+      # Snapdragon laptops, Parallels VMs on Apple-silicon Macs). x64 also
+      # RUNS on arm64 via Windows emulation, so x64 stays the safe default
+      # link; arm64 is the first-class build for those machines (#908).
+      arch: [x64, arm64]
+
+nsis:
+  oneClick: true
+  perMachine: false
+  runAfterFinish: true
+  deleteAppDataOnUninstall: false
+  # ${arch} suffix added in #908 when arm64 joined — two arches can't share
+  # one filename. Must stay in lockstep with config/devbox-app.json assets.
+  artifactName: Cloud-Bongos-Dev-Box-Setup-${version}-${arch}.${ext}
+
+publish: null