@bongos/core 1.17.0

package/docs/adr/0040-remote-control-default-browser-onramp.md

@@ -0,0 +1,47 @@
+# ADR 0040 — Remote Control is the default browser-only on-ramp (reversing 0038's "RC is dead" verdict)
+
+- **Status:** Accepted. **Reverses the "Remote Control is unfixable" conclusion of [ADR 0038](<redacted>.md)** (tasks [#745](https://example.com/builders#/task/745) / [#760](https://example.com/builders#/task/760)). Implemented in the onboarding/Settings work under [#807](https://example.com/builders#/task/807); recorded here under [#838](https://example.com/builders#/task/838); remaining legs (cloud-init trust pre-seed + the connect-guide / recipe-Part-2 rewrites that lead browser-only builders into the Claude app via `/remote-control`) landed under [#824](https://example.com/builders#/task/824).
+- **Date:** 2026-06-07 (trust pre-seed leg: 2026-06-29, [#824](https://example.com/builders#/task/824))
+- **Track:** `internal` (dev-system / builder onboarding)
+- **Builds on:** [ADR 0038](<redacted>.md) (ttyd web terminal + Cloudflare Tunnel), [ADR 0031](<redacted>.md), [ADR 0035](<redacted>.md), [ADR 0039](<redacted>.md), [ADR 0016](<redacted>.md)
+
+## Context
+
+ADR 0038 concluded that Claude Code **Remote Control** (drive a session from the claude.ai web app or the mobile app) was *unfixable* for browser-only builders, and replaced it with a raw `ttyd` web terminal. The three blockers it documented were:
+
+1. Trusted-Devices enrollment is interactive-`/login`-only — no headless path.
+2. `claude rc` only renders its pairing link to a real TTY — a systemd service has none.
+3. Remote Control requires full-scope browser OAuth — every baked-token path is excluded by design.
+
+**All three were artifacts of running RC *headless, as a background service, with no human present.*** ADR 0038's own fix — the ttyd web terminal — dissolves every one of them: it puts a **real human at a real browser-backed PTY**. In that terminal, `/login`, workspace-trust, and Trusted-Devices enrollment all succeed (0038 verified exactly this for plain interactive `claude`).
+
+So Remote Control was never the thing that was broken — the *headless context* was. Given a human PTY, RC works. **Verified live on the prod box (LarsCode) on 2026-06-07:** in the ttyd terminal, `claude` → accept workspace-trust → `/remote-control` prints a pairing link that drives the session from the Claude web/mobile app.
+
+## Decision
+
+**Remote Control is the recommended default experience for browser-only builders, and the onboarding leads with it.** This shipped in [#807](https://example.com/builders#/task/807): the "Claude Online" onboarding path walks the builder through
+
+1. open the box's ttyd terminal (URL + password from the builders' hall),
+2. run `claude` and complete the one-time sign-in,
+3. run **`/remote-control`** to get a link, and
+4. open that link to drive the session from the Claude web/mobile UI.
+
+The ttyd terminal (ADR 0038) is retained but its role narrows to a **one-time launchpad**: the builder logs in and starts Remote Control there, then lives in the Claude app, not the raw terminal.
+
+### Two specifics that are load-bearing
+
+- **Use the in-session `/remote-control` slash command, not the standalone `claude rc` shell command.** The standalone command mis-checks workspace trust ([anthropics/claude-code#35817](https://github.com/anthropics/claude-code/issues/35817)): it reports `Workspace not trusted` even when the directory is trusted inside an interactive session, and a plain shell can't accept the trust dialog. Starting RC from *inside* an already-running, already-trusted `claude` session is the working path.
+- **Closing the online terminal window ends the remote session and closes the dev box.** The onboarding states this so builders aren't surprised; it is a property of the session lifecycle, not a bug.
+
+### What we explicitly do NOT do
+
+- **No headless RC, no `claude-rc.service`.** ADR 0038 was right that RC can't run as a backgrounded service. RC is always started by a human in the ttyd terminal. The `claude-rc.service` / `box-report-pairing.sh` units deleted in [#760](https://example.com/builders#/task/760) stay deleted. (A stale comment in `infra/builder-box-cloud-init.yaml` still referenced the deleted unit; cleaned up under [#838](https://example.com/builders#/task/838).)
+- **No token funneled to the box for RC.** RC authenticates through the builder's own interactive browser `/login` in the ttyd terminal — the same full-scope OAuth ADR 0038 relies on. The trust boundary ([ADR 0016](<redacted>.md)) is unchanged: no Anthropic credential is baked onto the box.
+- **Workspace trust IS now pre-seeded — but as a NON-load-bearing convenience ([#824](https://example.com/builders#/task/824), updating the original deferral).** The cloud-init writes `/root/.claude.json` with `<redacted>` for `/root` + `/workspace` so the first `claude` launch usually skips the trust dialog before the builder reaches `/remote-control`. It is **deliberately best-effort**: the seed runs only when `/root/.claude.json` is absent (it never clobbers a config `claude` later writes), and upstream pre-seeding is known to be flaky ([#9113](https://github.com/anthropics/claude-code/issues/9113)). So nothing depends on it working — if it doesn't take, the builder accepts trust once during sign-in exactly as before. This is a one-keypress smoother, NOT a security control: trust is a UI convenience, and the real trust boundary is unchanged (no Anthropic credential is baked; auth is the builder's own interactive `/login`). The deferred question of whether RC can be spun up without the separate-window terminal dance at all remains open (idea_inbox).
+
+## Consequences
+
+- Browser-only builders (Chromebook, iPad, phone, locked-down laptop) get the full Claude web/mobile UI to drive their dev box — the experience ADR 0038 had to give up.
+- The ttyd terminal becomes plumbing the builder touches once, not their daily surface.
+- Two upstream behaviours we route around rather than depend on: the standalone-`claude rc` trust check (#35817 — avoided by using the slash command) and trust pre-seeding flakiness (#9113 — we now pre-seed for convenience but treat it as best-effort, so a failed seed costs the builder one trust keypress, nothing more). If Anthropic ships a headless RC mode or fixes the standalone trust check, we can simplify, but we do not rely on it.
+- Verification crosses real hardware (box + a human at a browser). ADR 0038's `managed-settings-remote-control.md` recipe carries the end-to-end check; re-run it on any change to the terminal/RC flow.

package/docs/adr/0041-temporary-grader-bypass-killswitch.md

@@ -0,0 +1,40 @@
+# ADR 0041 — Temporary global grader-bypass kill-switch (`GRADER_BYPASS_ENABLED`)
+
+- **Status:** Accepted. Implemented in [#853](https://example.com/builders#/task/853).
+- **Date:** 2026-06-07
+- **Track:** `internal` (dev-system / shipping pipeline)
+- **Builds on:** [ADR 0016](<redacted>.md) (server-enforced permissions / trust boundary), [ADR 0024](<redacted>.md) (the grader)
+
+## Context
+
+The subagent quality grader gates the `completed → confirmed` transition: a task only earns credits and advances toward `shipped` when a passing grade is recorded (`db.applyGrade`). The only existing bypass is the per-ship `--skip-grade` flag, which reroutes to `POST /tasks/:id/confirm` — and that endpoint is **Archon-only** ([#231](https://example.com/builders#/task/231)) precisely so a builder can't push their own work past a failed grade.
+
+That gate becomes a problem during a **grader outage**. When the LLM grader can't run at all (e.g. a provider-wide 429 — as happened repeatedly through early June, resetting Jun 8 3pm ET), *no* non-Archon builder can land work: they can't get a passing grade, and they can't self-confirm. Builders (e.g. builder 25 with outstanding completed tasks) are stuck until either the outage clears or an Archon manually confirms each task one by one.
+
+Lars asked to **temporarily allow everyone to ship without running the grader agents**.
+
+## Decision
+
+Add a **server-side, default-OFF environment kill-switch**: `GRADER_BYPASS_ENABLED`. When — and only when — it is exactly `'1'`:
+
+1. **`POST /api/gds/tasks/:id/confirm`** relaxes from Archon-only to **any authenticated builder**. The endpoint logs every bypass confirm (`[gds] grader-bypass confirm: builder N …`) so the audit trail records it. `confirmTask` still credits the **claim holder**, not the confirmer ([#661](https://example.com/builders#/task/661)), so this is not a credit-self-dealing vector.
+2. **`GET /api/gds/me`** surfaces `grader_bypass: true`.
+3. **`scripts/gds/ship.js`** reads that flag and, for *every* builder, auto-takes the existing `--skip-grade` confirm path (no subagent grader spawned) with a printed notice.
+
+The flag is read **live on each request** — there is no caching. Flipping the env and redeploying is the entire on/off control; turning it off immediately re-arms the Archon-only gate and the normal grader flow.
+
+### Why this honors the trust boundary ([ADR 0016](<redacted>.md))
+
+The relaxation is **server-side and default-OFF**. A builder editing local files (CLAUDE.md, ship.js, skills) cannot turn it on — only an operator with droplet env + deploy access can. When the env is unset, the system behaves exactly as before. The bypass is a deliberate, operator-controlled, logged, *temporary* widening — not a standing grant.
+
+## Consequences
+
+- **Positive:** During a grader outage, all builders keep shipping with a single operator flag; no per-task Archon babysitting. One switch, fully reversible.
+- **Negative / risk:** While ON, the quality gate is effectively off for everyone — work lands unverified. This is acceptable only as an outage measure, not a steady state.
+- **Operating rule:** Treat the flag as a circuit breaker. Turn it **OFF** as soon as the grader is healthy again (the grader 429 resets Jun 8 3pm ET), then `node scripts/gds/ship.js <id> --regrade` the tasks that landed under the bypass to attach a real grade record — consistent with the standing "prefer re-grade over override" rule.
+
+## Operator runbook
+
+- **Turn ON:** set `GRADER_BYPASS_ENABLED=1` in the droplet service env (`/etc/example/*.env` or the systemd unit), restart the Node process / redeploy.
+- **Turn OFF:** remove the var (or set it to anything other than `'1'`), restart/redeploy. The Archon-only confirm gate and normal grader flow resume on the next request.
+- **After OFF:** `--regrade` the bypassed tasks for a real grade record.

package/docs/adr/0042-builder-self-deploy-ci-auto-merge.md

@@ -0,0 +1,82 @@
+# ADR 0042 — Builder self-deploy: CI auto-deploy on main + PR auto-merge
+
+**Date:** 2026-06-07
+**Context:** GDS-V3, task [#679](https://example.com/builders#/task/679) (cut prod deploy over to CI). Completes the [#597](https://example.com/builders#/task/597) / [ADR 0031](<redacted>.md) §6 goal — *no builder box holds the production droplet SSH key*. Extends [ADR 0031](<redacted>.md) §6; re-applies [ADR 0016](<redacted>.md) to CI.
+**Status:** Accepted — **armed in production 2026-06-13** (interim, grader-off variant — task [#859](https://example.com/builders#/task/859); `config/deploy.json` `mode: ci`; see the *Arming record* below + session log [`<redacted>.md`](../session-logs/<redacted>.md)).
+
+## Problem
+
+Deploying to production is the one builder action still gated by *possession of a secret on a particular machine*, not by `builders.rank`. `scripts/gds/ship.js` (and `/merge-mode`) land a confirmed task by, on the shipper's own machine: merging the branch into `main` in a local `main` checkout, `git push origin main`, then `ssh lars@REDACTED_IP "~/deploy.sh"`. That SSH needs the operator's droplet key.
+
+Observed 2026-06-07: builder `#25` ("niels", a Thetes on Windows) took [#631](https://example.com/builders#/task/631) to `confirmed` (built, smoke 16/16, credited) but could not deploy — `ssh … → Permission denied (publickey)`. His box has no droplet key, by design. He had to hand the final step to the operator. Every non-operator builder hits this wall, on every ship. It is the last thing standing between a trusted builder and self-sufficiency.
+
+## Decision
+
+Move production deploy off the shipper's machine and onto GitHub Actions, and land work via **PR auto-merge** instead of a local merge — so a builder with neither a `main` checkout nor the droplet key can ship end to end.
+
+After cutover, the flow is:
+
+1. Builder ships → `ship.js` pushes the **feature branch**, opens a **PR** to `main`, and enables **GitHub auto-merge**. (No local `main` merge, no `git push origin main`, no SSH.)
+2. Required PR checks run. When they pass and branch protection is satisfied, GitHub **auto-merges** to `main` — no human in the loop for an ordinary PR. (Operator decision, [#679](https://example.com/builders#/task/679): *"auto-merge PR when checks pass."*)
+3. The merge to `main` triggers [`.github/workflows/deploy-prod.yml`](../../.github/workflows/deploy-prod.yml) (built inert under [#597](https://example.com/builders#/task/597)), which SSHes `~/deploy.sh` from Actions using a key held **only in repo Actions secrets** — never on any builder box.
+4. `ship.js` **confirms the deploy landed** — PR state `MERGED` → the `deploy-prod` workflow run for the merge commit concluded `success` → public `healthz` 200 — so the synchronous "deploy-confirmed" UX is preserved without the key. On any timeout the task stays at `confirmed` with a precise next step (never a false `shipped`).
+
+### One switch, default OFF, atomic cutover
+
+A single committed switch — [`config/deploy.json`](../../config/deploy.json) `mode` (`laptop` | `ci`), overridable by env `OTB_DEPLOY_MODE` — selects the path. It ships as **`laptop`** (today's behavior, byte-for-byte), so all of this code is **inert** until a deliberate flip. `ship.js` reads it via the pure, exported `parseDeployMode` (env > config > safe-default `laptop`).
+
+The cutover is **atomic** — flipping `config/deploy.json` to `ci` must happen *in lockstep* with arming the GitHub side (`deploy-prod.yml`'s `PROD_SSH_KEY` + `DROPLET_KNOWN_HOSTS` secrets + `PROD_DEPLOY_VIA_CI=true` variable) and branch protection. Half a cutover is a live incident:
+- `ci` here **without** the GitHub side armed → prod stops deploying (nothing runs `deploy.sh`). `deploy-prod.yml` gates the whole job on `PROD_DEPLOY_VIA_CI`, so a disarmed run concludes **`skipped`, not `success`** — and `ship.js`'s `deployRunSucceeded` only accepts `completed`+`success` on the merge commit, so it will NOT false-flip the task to `shipped`; it times out at `confirmed` with a clear message (closes the security-review finding that a disarmed run otherwise looked like a real deploy). An armed-but-secrets-missing run **fails hard** (exit 1), never silently.
+- `laptop` here **with** the GitHub side armed → double-deploy race on the droplet checkout (`deploy-prod.yml`'s own header warns of this).
+
+### The auto-merge gate must be tamper-proof — the security crux
+
+With no human in the merge loop, **the CI checks *are* the authority**. The threat (per [ADR 0016](<redacted>.md)) is a trusted-but-bounded builder weakening the gate from inside their own PR. Two defenses:
+
+1. **[`CODEOWNERS`](../../CODEOWNERS)** — a PR touching any gate surface (`.github/`, `config/deploy.json`, `ship.js`, the grader, `auth.js`/`route-rank-check.js`) **or any code that executes on the droplet at deploy** (`migrations/`, `scripts/migrate.sh`, `package.json`/`package-lock.json`, `scripts/deploy/` — `~/deploy.sh` runs migrations + `npm ci` from the merged tree, so a malicious migration or poisoned lockfile would otherwise auto-merge and run on prod) requires Archon review *even under auto-merge*, when branch protection has "Require review from Code Owners" on. Ordinary PRs (game, art, docs) carry no code owner and auto-merge freely — that's the point.
+
+2. **The grader must RE-RUN in CI** — CODEOWNERS only catches *committed* changes to `ship.js`. A builder could run a **locally-edited, uncommitted** `ship.js` that skips the grade and opens an auto-merge PR anyway. An earlier draft of this ADR proposed a CI check that *reads the server-recorded grade* — but that is **theater**: `POST /tasks/:id/grade` records the grader scores *from the request body* (the server does not recompute them), so a tampered local ship.js can POST a fake passing grade. The only tamper-proof gate runs the grader **in CI, against the PR diff**, where the builder cannot touch it — [`.github/workflows/grade-gate.yml`](../../.github/workflows/grade-gate.yml) + [`scripts/gds/ci-grade.js`](../../scripts/gds/ci-grade.js) ([#855](https://example.com/builders#/task/855)), which reuse the exact production grading path (`ship.js runSubagentGrader` → the adversarial worker panel) and **fail closed**. It is **skip-safe** (green-but-not-gating) until the operator wires a grader auth secret AND marks it a required check — the same inert-until-armed pattern as `deploy-prod.yml`. This is a **hard precondition** of arming `ci` mode.
+
+### Why not just hand builders the droplet key
+
+Rejected. It puts a full shell on the production box (prod DB, every secret) on a remote builder's machine — the exact thing the trust boundary exists to prevent, and a Thetes has no trust powers by design. The deploy key lives only in Actions secrets, used by a workflow whose definition is <redacted>.
+
+## Cutover preconditions (do NOT arm `ci` until ALL hold)
+
+1. **CI grade-gate armed + verified** — the grader RE-RUN-in-CI check (`grade-gate.yml` + `ci-grade.js`, [#855](https://example.com/builders#/task/855)) is built and skip-safe but NOT yet a real gate. The operator must (a) add a grader auth secret (`ANTHROPIC_API_KEY` or `CLAUDE_CODE_OAUTH_TOKEN` — the grader spawns the `claude` CLI, ~4 model calls/PR), (b) verify a real grader-in-CI run passes a known-good PR and fails a known-bad one, and (c) mark `grade-gate` a required status check on `main`. *Without this, `ci` mode lets a tampered local ship.js bypass the quality grader.* (Built in [#855](https://example.com/builders#/task/855); arming/verification is part of the cutover.)
+2. **Functional checks required** — the DB-free **unit suite** runs as a PR check ([`.github/workflows/pr-unit-tests.yml`](../../.github/workflows/pr-unit-tests.yml) + [`scripts/gds/run-unit-tests.js`](../../scripts/gds/run-unit-tests.js), 56 tests, [#856](https://example.com/builders#/task/856)); the operator marks it required at cutover. The **integration smoke** (full server + Postgres service container) is a follow-up ([#862](https://example.com/builders#/task/862)). The existing `secrets-scan` / `dep-audit` already run on PRs.
+3. **Branch protection on `main`** — require a PR (block direct pushes), require the checks in (1)+(2) + Code-Owner review, enable auto-merge.
+4. **`deploy-prod.yml` armed** — `PROD_SSH_KEY` + `DROPLET_KNOWN_HOSTS` secrets + `PROD_DEPLOY_VIA_CI=true` (a dedicated deploy keypair, not a personal key).
+5. **Flip `config/deploy.json` → `ci`** — atomically with (3)+(4).
+
+Until (1)–(5), the switch stays `laptop` and the operator lands work as today (`/merge-mode`).
+
+## Consequences
+
+- **Builder `#25` and every future builder** can ship end to end from any machine (Windows, Chromebook, dev box) with no `main` checkout and no droplet key.
+- **The merge to `main` becomes the control checkpoint** — what reaches `main` goes live within ~1 min. Governance moves from "who holds the key" to "what the checks require + who reviews the gate" — squarely inside the [ADR 0016](<redacted>.md) model.
+- **New dependency:** `ci` mode uses the GitHub CLI (`gh`) on the builder's machine to open the PR + enable auto-merge. A follow-up either adds a `doctor.js` check for `gh` or moves PR creation server-side (the server already holds a GitHub principal) to drop the per-builder dependency.
+- **Deploy confirmation is workflow-run-based**, not commit-pinned at the edge (`/healthz` returns only `ok`). A follow-up can expose the running commit for a stricter edge assertion.
+
+## Follow-ups (filed as GDS tasks)
+
+- CI **grade-gate** reading the server-recorded grade — **blocks cutover** (precondition 1).
+- PR-check workflows: unit suite + integration smoke (Postgres service) as required checks (precondition 2).
+- Drop the per-builder `gh` dependency (server-mediated PR creation) + `doctor.js gh` check.
+- Commit/version endpoint for a commit-pinned edge deploy confirmation.
+
+## Arming record — 2026-06-13 (task 859): the grader-off INTERIM cutover
+
+`ci` mode was **armed in production** on 2026-06-13 under task 859 — but as a deliberate
+**interim variant** that defers precondition 1 (the CI grade-gate), because the
+subagent grader was already globally bypassed (`GRADER_BYPASS_ENABLED=1`, [ADR 0041](<redacted>.md))
+during the provider outage. With the grader off everywhere, gating auto-merge on a
+*grade-gate* would be theater; instead the merge gate is:
+
+- **Required PR checks:** `unit` (the DB-free unit suite, task 856) + `trufflehog` (full-history secret scan). Both were red on `main` for unrelated reasons and were greened first: `anti_grid` (needs numpy, Node-only runner) moved to the unit runner's `KNOWN_FAILING` set; `tests/bfg.mjs` (deliberate fake-DSN fixtures) added to the secret-scan allowlist.
+- **Code-Owner review** on every gate surface (this repo's `CODEOWNERS`), now extended to the gate "brains" (`scripts/gds/run-unit-tests.js`, `.husky/`) so a PR cannot mute a test or allowlist a real secret unreviewed.
+- **Deploy-time `main-audit`** on the droplet (`~/deploy.sh` → `infra/deploy-main-audit-gate.sh`, [ADR 0043](<redacted>.md)) — reverts/blocks sub-Metic edits to permission-sensitive paths regardless of how they merged.
+
+What was set: `PROD_SSH_KEY` (a dedicated ed25519 deploy key, **forced-command `~/deploy.sh`** in the droplet's `authorized_keys`) + `DROPLET_KNOWN_HOSTS` secrets; repo var `PROD_DEPLOY_VIA_CI=true`; branch protection on `main` (require PR, required checks `unit`+`trufflehog`, require Code-Owner review, 0 ordinary approvals, block direct push for non-admins); repo auto-merge enabled; `config/deploy.json` → `ci`. `deploy-prod.yml` verified end-to-end (Actions → SSH → `~/deploy.sh` → public healthz) before the flip.
+
+**Tighten-later (re-arm when the grader returns):** turn `GRADER_BYPASS_ENABLED` off, re-introduce the `grade-gate` required check (precondition 1, needs an `ANTHROPIC_API_KEY` Actions secret), and land the integration-smoke gate (task 862, precondition 2). **Rollback:** set `config/deploy.json` → `laptop` **and** unset the `PROD_DEPLOY_VIA_CI` repo var (admins retain direct main-push for this).

package/docs/adr/0043-git-ssh-trust-boundary-and-rank-floor-on-permission-paths.md

@@ -0,0 +1,74 @@
+# ADR 0043 — Git/SSH trust-boundary gap + a rank floor on permission-sensitive paths
+
+**Date:** 2026-06-08
+**Context:** SEC [#863](https://example.com/builders#/task/863) — the "Builder 25" incident. Extends [ADR 0016](<redacted>.md) (the HTTP trust boundary).
+**Status:** Accepted. Implemented in part (Option A's protections); the full server-side merge+deploy and GitHub-native block are staged behind operator actions (blockers [#15](https://example.com/builders#/blocker/15)–[#17](https://example.com/builders#/task/17)).
+
+## The incident
+
+Builder 25 (`IAMMASTERQUA`, rank **Thetes**) opened a session, found 0 claimable tasks (a real bug — the rank-tier `CASE` in `listClaimableTasks` predated the `thetes` rank, so Thetes collapsed to tier 0), diagnosed it, and **edited `src/bongos/db.js` + `tests/rank_gate.mjs`**. Then, prompted with *"you don't need an archon on lars, push it,"* they **bypassed the entire ship pipeline** — no grader, no `confirmed` gate, no parallel-safety — by running raw git:
+
+```
+git merge --no-ff … && git push origin main      #  → d1b7042..22b7a641, SUCCEEDED
+ssh lars@REDACTED_IP "~/deploy.sh"            #  → Host key verification failed (no key)
+```
+
+The SSH deploy failed (their box had no droplet key), but it didn't matter: the push to `main` landed (`b5de8aff` + merge `22b7a641` are permanent ancestors of prod `main`) and the un-graded change rode to production on the next legitimate deploy.
+
+## The gap
+
+[ADR 0016](<redacted>.md) put authority in `builders.rank` and enforced it **server-side per request** — but **only for `/api/gds/*` HTTP routes**. It explicitly does not cover two surfaces:
+
+1. **GitHub `main` is writable by every collaborator.** The repo is a **free-plan private repo**, so GitHub branch protection is *not available* ("Upgrade to GitHub Pro…"). All collaborators (`example-owner`, `LarsCode`, `willExample`, `IAMMASTERQUA`) have full push to `main`. The grader / confirm / rank gates live inside `ship.js` and the server — a raw `git push origin main` touches neither.
+2. **The legit pipeline itself distributes the dangerous credentials.** `ship.js` does the merge-to-`main` and `ssh …deploy.sh` **client-side, from the builder's machine** — so the design hands every shipping builder the exact credentials needed to bypass it.
+
+A second, softer problem Lars raised: a sub-Metic builder had free rein to **read into and reason about the tiering/permission code** in the first place. Newcomers (`xenos`/`thetes`) should stay in their lane.
+
+## Decision
+
+Two threads.
+
+### A. Close the code-landing path (chosen: Option A now, Option B later)
+
+The protection goal is "un-graded code cannot reach prod, and a raw push to `main` is caught." Three layers, defense-in-depth, where **layer 3 is the authoritative enforcement** (the only one that survives a raw push / `--no-verify`, given GitHub can't block the push on the free plan):
+
+| Layer | Mechanism | Catches | Authoritative? |
+|---|---|---|---|
+| 1 — pre-push hook | `.husky/pre-push` → `scripts/gds/hooks/pre-push.js`. Blocks a direct push to `main` (override `OTB_ALLOW_MAIN_PUSH=1`, used only by the gated `scripts/gds/push-main.js`), and blocks a sub-Metic push that touches a permission-sensitive path. | the cooperative / careless case before the push leaves the box | no — bypassable with `--no-verify` |
+| 2 — grader pre-pass | `grader.permissionPathPrePass(changedFiles, builderRank)` hard-fails the grade if a sub-Metic diff touches a protected path (mirrors the route-rank pre-pass). | the honest GDS ship flow | no — skippable with `--skip-grade` / raw push |
+| 3 — post-push main audit | `scripts/gds/main-audit.js`: reads the **real** git history + **real** builder ranks (roster API, or Postgres via `--db` on the droplet). A resolved sub-Metic author on a protected path is a hard `[BLOCKER]`. Runs nightly (`.claude/scheduled-tasks/main-audit/`) **and** as the deploy gate (`--verify-head --db` from `~/deploy.sh`, `infra/deploy-main-audit-gate.sh`). | a raw `git push origin main`, a `--no-verify`, a `--skip-grade` — anything | **yes** — independent of the builder's cooperation |
+
+"Option A" = the merge-to-`main` + deploy move **server-side** so builders never hold main-push/droplet-SSH at all. The protections above ship now; the *full* server-side move and the credential rotation are operator steps (blockers [#15](https://example.com/builders#/blocker/15), [#16](https://example.com/builders#/blocker/16)). Until then, the legit client-side push is allowed only through `scripts/gds/push-main.js`, and the deploy gate (layer 3) is what guarantees poison never reaches prod.
+
+**"Option B" (deferred, documented):** upgrade GitHub to a Team plan (~$4/active-collaborator/mo) and add a branch-protection ruleset that forbids direct pushes to `main` and restricts it to the owner + a deploy bot. This is the only way to make the push *impossible* rather than *caught*. It composes with Option A — see blocker [#17](https://example.com/builders#/blocker/17). We chose A-first because it is **$0**, invisible to builders, and closes the part that actually bit us; B is a later hardening, not a prerequisite.
+
+### B. A rank floor on permission-sensitive paths
+
+A builder **below Metic** (tier < 3) may not modify the surfaces that define authority and the build pipeline. The protected set is a single glob list in [`src/bongos/permission-path-check.js`](../../src/bongos/permission-path-check.js) (the source of truth) — rank/authz machinery, the ship/grade/deploy pipeline, DB migrations, `infra/`, and the trust-boundary docs. The same pure check feeds all three layers above. CLAUDE.md carries the **behavioral** version of this rule (the soft block that keeps a cooperative agent out of the core); the code is the enforcement, consistent with ADR 0016's "markdown describes, code enforces."
+
+`RANK_TIER` in `permission-path-check.js` is a local copy of `db.REQUIRES_RANK_TIER`; `tests/permission_path.mjs` asserts the two never drift — because a tier map that forgot `thetes` is *literally what caused this incident*.
+
+## Consequences
+
+- **Positive:** the exact incident is now caught at three points; the authoritative audit reproduces it as a `[BLOCKER]` on the real commit (`b5de8aff`). Newcomers are kept out of the core both behaviorally (CLAUDE.md) and mechanically. No recurring cost.
+- **Negative / residual:** on the free plan GitHub still *accepts* a raw push; layer 3 catches it after the fact rather than forbidding it. A determined builder can `git push --no-verify` to a `claude/*` branch — but cannot reach prod, because the deploy gate re-checks. The audit's author→rank resolution relies on the commit author **name** matching a GDS `github_login` (verified true for this pipeline; everyone shares one commit *email*, so email is not a distinguishing signal). An author that can't be resolved is a `review` note, not a block (so the operator's own infra commits don't brick deploys); `--strict` escalates that for paranoid CI.
+- **Operator actions (blockers):** [#15](https://example.com/builders#/task/15) rotate/relocate the droplet deploy key + GitHub main-push credential to a server/CI identity (the full Option A move); [#16](https://example.com/builders#/task/16) add `infra/deploy-main-audit-gate.sh` to `~/deploy.sh`; [#17](https://example.com/builders#/task/17) (optional, later) GitHub Team + branch-protection ruleset (Option B).
+
+## #863-followup: red-team remediation (2026-06-09, task [#872](https://example.com/builders#/task/872))
+
+After shipping, the fix was adversarially red-teamed (a 4-dimension panel + per-finding verification). 15 findings were confirmed real+exploitable. The clearly-correct ones were remediated; one residual is escalated rather than papered over.
+
+**Remediated:**
+- **Layer 3 was instruction-only (finding `#1`).** `infra/deploy-main-audit-gate.sh` told the operator to hand-edit `~/deploy.sh` but nothing wired it, and both deploy paths (ship.js auto-merge AND `.github/workflows/deploy-prod.yml`) just call `~/deploy.sh`. The gate is now installed into the droplet's `~/deploy.sh` (after the `git reset`, before migrations/restart), so it runs on **both** paths from one place. It uses the already-captured `PREV_SHA` to audit the **exact deploy delta** (`OTB_AUDIT_RANGE=<prev>..HEAD`), closing the fixed-window evasion (findings `#8`/[#14](https://example.com/builders#/task/14)).
+- **PROTECTED_GLOBS gaps (findings `#3`/[#9](https://example.com/builders#/task/9)/#10/[#11](https://example.com/builders#/task/11)/[#12](https://example.com/builders#/task/12)).** Added `server.js`, `src/bongos/routes.js`, `scripts/migrate.sh`, `.github/`, `package.json`, `.husky/` (the hooks the gate ships through), `src/bongos/grader-workers/` (the adversarial panel), and the rank-gated source-clone logic (`src/bongos/boxes.js`, `box-access.js`, `box-credential.js`).
+- **Identity-poisoning (finding `#6`).** The audit rank map keyed on `display_name` (builder-controlled — one builder could alias another's login) and `email` (shared — non-distinguishing). It now keys on `github_login` **only**.
+- **Evil-merge blind spot (finding `#5`).** Merge commits are no longer blanket-skipped; `parseCommits` backfills each merge's files with the `git diff-tree --cc` surface (changes in *neither* parent — conflict-resolution smuggling), attributed to the merge author. Clean pipeline merges have an empty set, so feature changes are still attributed to feature commits (no double-count).
+- **Pre-push hook hang (finding `#15`).** `liveRank()` now races a 4 s timeout, so a slow/hung GDS API degrades to "unknown rank → warn-and-allow" (the audit remains the net) instead of blocking every protected-path push.
+
+**Residual, escalated not patched:** git author **name** is attacker-controlled. The deploy gate blocks an author that resolves to a known below-Metic login (the incident class — Builder 25 committed as their real login `IAMMASTERQUA`) and the lazy/honest case, but a determined attacker can set their git author name to a *known Metic+ login* and pass — `--strict` does **not** close this (it only blocks *unrecognized* names, and would brick the non-technical owner's own commits for no real gain), so strict is **opt-in** (`OTB_AUDIT_STRICT=1`), default off. The durable closures are unchanged and remain the priority: **Option B** (GitHub branch protection — builders can't push `main` at all, blocker [#17](https://example.com/builders#/blocker/17)) and/or a **task-linkage audit** that ties each protected-path commit to an Archon-confirmed shipped GDS task (the un-spoofable signal) — filed as a follow-up. Operators/CI should commit as their `github_login` to keep audit output clean.
+
+**Not yet done (finding `#7`, follow-up):** the permission-path pre-pass (layer 2) runs only client-side in `ship.js`; the server `/grade` and `/confirm` routes don't re-run it. Layer 3 is the server-side backstop today; re-running the pre-pass server-side (the server holds the live rank in `req.builder.rank`) would harden the cooperative path.
+
+## Notes
+
+We did **not** take immediate action against Builder 25 — Lars was overseeing the session and the change itself was a legitimate bug fix. The point of this ADR is the *mechanism*, not the person: the system must make the bypass hard and visible regardless of intent.

package/docs/adr/0044-mediterranean-palette-replacement.md

@@ -0,0 +1,73 @@
+# 0044 — Full Mediterranean palette replacement (not a split)
+
+- **Status:** Accepted (direction). Implementation tracked separately.
+- **Date:** 2026-06-10
+- **Deciders:** Lars
+- **Area:** the game world's look (the locked palette governs the colors of every game tile a player sees; the decision is about the world's look, not the pipeline tooling).
+
+## Context
+
+The art pipeline's locked palette is 64 colors extracted from the Pokémon FireRed
+reference corpus (`art/template/palette.json`), per [ADR 0008](./<redacted>.md)
+and the hard constraint in `art/template/style_guide.md` ([#3](https://example.com/builders#/task/3) "Locked palette"). Every
+output pixel must quantize to one of those 64 colors. Per CLAUDE.md §7.1, **any palette
+change is an ADR-level decision** because it ripples through every existing tile and the
+quantizer.
+
+The FireRed-derived palette carries the *structural* style well (it's why the clusters
+read as "Pokémon"), but it is a temperate / "Poke Mart" palette: spring greens, primary
+blues, the bright interior-shop colors. The project's north star is a **sun-bleached
+Mediterranean coast** — olive/sage greens, warm tan sand, turquoise (not navy) sea,
+weathered marble. The style guide already biases generations *toward* Mediterranean within
+the FireRed palette ("Mediterranean palette bias" rule), but the underlying locked colors
+still pull the wrong direction, especially for greens and water.
+
+Blocker [#8](https://example.com/builders#/blocker/8) asked the structural question: **keep the FireRed/"Poke Mart" palette and add a
+separate Mediterranean sub-palette (a split), or replace the locked palette wholesale with a
+Mediterranean-tuned one (full replacement)?**
+
+## Decision
+
+**Full replacement.** Replace the locked 64-color palette with a single Mediterranean-tuned
+palette. Do **not** maintain two coexisting palettes.
+
+Rationale (Lars's call, 2026-06-10):
+
+- **One source of truth.** A split palette means every generation, the quantizer, the
+  deterministic family checks (palette Jaccard, dominant-color overlap), and every reviewer
+  prompt must reason about *which* palette applies to *which* tile. That branching is exactly
+  the kind of pipeline complexity the bootstrapped budget and the single-maintainer reality
+  can't carry. One palette = one set of rules everywhere.
+- **The world has one look.** Off the Boats is a single, persistent, coherent world. There is
+  no "Poke Mart interior" context that needs the temperate palette — the FireRed colors were
+  only ever scaffolding for the *structure*, never the intended final hues.
+- **The bias rule becomes the palette.** Today the style guide *nudges* generations toward
+  Mediterranean within a temperate palette; replacement bakes that intent into the colors
+  themselves, so tiles land Mediterranean by construction instead of by reviewer correction.
+
+## Consequences
+
+- **Re-quantization is required.** Existing committed tiles were quantized against the old
+  palette; some will shift when re-quantized to the new one, and a few may need regeneration.
+  This is the bulk of the implementation work and is tracked as a **separate task** (filed
+  from this ADR) — this ADR records the *direction*, not the swap.
+- **The structure-vs-color split is preserved.** The FireRed *reference corpus and clusters*
+  (`art/references/`, `art/template/cluster_overview.png`) stay — they carry silhouette and
+  rhythm discipline, which is independent of hue. Only `art/template/palette.json` and the
+  downstream quantize/check steps change.
+- **Deterministic family checks need re-baselining.** Palette-Jaccard / dominant-color-overlap
+  thresholds were tuned against the old palette and should be re-checked after the swap.
+- **Reversible.** The old palette is preserved in git history; if the Mediterranean palette
+  proves too narrow (e.g. not enough value steps for shading), we revert the one file and
+  re-quantize back. No data is destroyed.
+- **Container color (blocker [#7](https://example.com/builders#/blocker/7)) composes with this.** The container is now weathered
+  black/charcoal (style-guide rule, 2026-06-10); the replacement palette must carry enough
+  cool-neutral charcoal/grey value steps to render it. Captured as a constraint on the
+  implementation task.
+
+## Implementation
+
+This ADR is the **decision**. The actual work — build the Mediterranean 64-color palette,
+swap `art/template/palette.json`, re-quantize the committed tile set, re-baseline the
+deterministic checks, and visually review — is tracked as its own GDS task (filed alongside
+this ADR from the 2026-06-10 blocker review).

package/docs/adr/0044-per-box-live-game-preview.md

@@ -0,0 +1,57 @@
+# ADR 0044 — Per-box live game preview (the builder sandbox)
+
+**Date:** 2026-06-10
+**Context:** GDS-V3, task [#897](https://example.com/builders#/task/897) (this ADR + the tunnel mechanism), wired into provisioning under [#898](https://example.com/builders#/task/898), hardware-verified under [#899](https://example.com/builders#/task/899). Companion to [ADR 0031](<redacted>.md) (per-builder DigitalOcean box substrate), [ADR 0038](<redacted>.md) (the box's ttyd terminal over a Cloudflare Tunnel — the mechanism this extends), and [ADR 0016](<redacted>.md) (the web tier only *asks*; the control plane holds infra power).
+**Status:** Accepted. Mechanism implemented under [#897](https://example.com/builders#/task/897).
+**Track:** `internal` (dev-system / builder experience).
+
+## Problem
+
+A builder working on the **game** (`public/`, `src/world/`, `src/rooms/`, the art tiles) has no way to *see their change running* before it ships. The only live instance of Off the Boats is production at `example.com`. So the loop today is: edit → ship through the grader/merge/deploy pipeline → look at prod. That is slow, it puts unreviewed game changes one mistake away from players, and a browser-only (Chromebook) builder has no local machine to run the game on at all.
+
+What a builder wants is a **sandbox**: run the game live *on their own dev box* and open it in a browser to review the change — never touching the prod server.
+
+## Decision
+
+**Serve the box's own `node server.js` over a second ingress route on the builder's existing per-box Cloudflare named tunnel, at a stable hostname `sandbox-<login>.example.com`. Run it degraded (no Postgres on the box). Give the builder a `box-preview` command in their terminal to restart it after edits.**
+
+This reuses the entire ADR 0038 substrate — the box already runs a `cloudflared` named tunnel ([#771](https://example.com/builders#/task/771)) with an outbound-only connector. A Cloudflare named tunnel can carry **multiple ingress rules on one connector**, so the game rides the same tunnel the terminal already uses; no second tunnel process, no new connector token.
+
+### 1. Degraded-DB — the game runs with no Postgres
+
+`server.js` binds `127.0.0.1:3000` and needs **no env vars and no DB to boot**. The game tables (`world_events`, `players`) are touched only lazily at runtime, and every call is failure-tolerant (`safeLog` swallows event-log errors; `loadOrCreatePlayer` falls through to a default spawn on a DB error). So `node server.js` on a box with no Postgres serves a **fully playable world** — you can walk, see every tile / world / container / art change, exercise movement and rooms — you just don't get position persistence across reloads or an event log.
+
+For *reviewing a change to the game* that is the right trade. Installing + seeding Postgres on every box (the alternative) is heavier provisioning for persistence the preview doesn't need, especially while the game has no login or purchase loop (V1 limits still hold). Full persistence is a deliberate future follow-up, not a precondition.
+
+### 2. Exposure — a second ingress route, stable apex hostname
+
+The box's named tunnel gains a second ingress rule: `sandbox-<login>.example.com → http://127.0.0.1:3000`, alongside the existing `term-<login>.example.com → 127.0.0.1:7681` (ttyd). Both are **one-label hostnames under the apex**, so Cloudflare's free Universal SSL covers them with no paid certificate — the same constraint that forced the apex (not `dev.*`) terminal hostname in [#771](https://example.com/builders#/task/771). A proxied CNAME for the preview host is upserted next to the terminal's.
+
+Host-based routing in `server.js` keys on the leading subdomain label: `status.*` → dashboard, `builders.*` → hall, **everything else → the game**. `sandbox-<login>` matches neither prefix, so it falls through to the game with zero routing changes. The Colyseus WebSocket rides the same HTTP server, so the world works over the tunnel unchanged.
+
+### 3. The box-side units
+
+- **`box-game-preview.service`** — a systemd unit running `node /workspace/server.js` with `HOST=127.0.0.1 PORT=3000`, `Restart=always`. Modeled on `box-terminal.service`. It depends on the `/workspace` source clone, so it is enabled by `box-source-fetch.sh` after the clone (not at first boot like ttyd), under [#898](https://example.com/builders#/task/898).
+- **`/usr/local/bin/box-preview`** — a baked wrapper the builder runs in their ttyd terminal: `box-preview status` (is it up + the URL), `box-preview restart` (pick up edits), `box-preview logs` (server output). Baked to `/usr/local/bin` so it works regardless of the rank-gated sparse checkout (a Xenos box has no `scripts/` or `.claude/`, idea [#213](https://example.com/builders#/idea/213)).
+
+### 4. The edit → preview loop
+
+The preview is a long-running service so the URL is always live while the box is up. To see a change: edit in the terminal → `box-preview restart` → refresh the browser tab. (A file-watcher auto-restart is a possible future nicety; an explicit restart is predictable and cheap.)
+
+## Trust boundary
+
+Unchanged from ADR 0016 / 0038. The Cloudflare API token that creates the tunnel + DNS lives **only on the control plane** (`scripts/gds/box.js`, the prod droplet's `box.env`), never the web tier. The preview is a *second instance* of the same Node app the box already clones — it holds no prod credentials and cannot reach the prod DB (it has none), so a builder previewing their own branch is fully isolated from production data. The preview hostname is per-builder and only fronts that builder's box.
+
+One consequence to note: because `/api/gds/*` mounts ahead of host-routing in `server.js`, the preview hostname also exposes the box's *own* GDS API surface — but that process has no DB and no OAuth secrets, so it is inert. Acceptable for the sandbox; flagged here so a future reviewer isn't surprised.
+
+## Cost
+
+**$0 added.** Reuses the existing per-box tunnel and connector (Cloudflare Zero Trust free tier). No new droplet, no Postgres, no second tunnel process, no paid certificate (apex one-label host under free Universal SSL).
+
+## Consequences
+
+- A builder can review game changes live in a browser, isolated from prod — the core ask.
+- Browser-only (Chromebook) builders get a real preview with no local machine.
+- The named-tunnel path is required (the tokenless quick tunnel carries only one port). Boxes on the quick-tunnel default do not get a preview until the operator sets `BOX_NAMED_TUNNEL=1` — consistent with the ADR 0038 named-tunnel upgrade story.
+- No persistence in the preview (deliberate; see §1). Position resets on reload; no event log.
+- Mechanism (this task, [#897](https://example.com/builders#/task/897)) ships and is unit-tested ahead of the provisioning wiring ([#898](https://example.com/builders#/task/898)) and hardware verification ([#899](https://example.com/builders#/task/899)) — the [#760](https://example.com/builders#/task/760) → [#771](https://example.com/builders#/task/771) pattern.

package/docs/adr/0045-devbox-desktop-app.md

@@ -0,0 +1,133 @@
+# ADR 0045 — The Dev Box desktop app: a native switch, app-pairing auth, and off-repo distribution
+
+- **Status:** accepted
+- **Date:** 2026-06-10
+- **Task:** [#904](https://example.com/builders#/task/904)
+- **Track:** internal
+- **Extends:** ADR 0031 (cloud dev environments), ADR 0035 (onboarding three paths), ADR 0038 (browser terminal), ADR 0039 (setup-first onboarding UX)
+- **Related:** ADR 0004 (trademark posture), ADR 0016 (trust boundary), ADR 0029 (off-box static hosting precedent)
+
+## Context
+
+The Claude-Desktop onboarding path told a newcomer to paste a prompt that
+makes Claude download and run `connect.sh`. Two exported sessions from the
+same Windows newcomer (2026-06-10, @largekristensen-svg — both attempts in one
+day, both failed) showed the flow is structurally broken, not just rough:
+
+1. **No Windows branch.** `connect.sh` installs the Claude Desktop
+   managed-settings file on macOS (sudo) or falls through to "save it in
+   $HOME" with a Linux-worded message — on Windows. Claude Desktop never sees
+   the SSH config; its logs show `discovered 0 workspace SSH config(s)`.
+2. **The agent cannot finish its own flow.** Claude Desktop's auto-mode
+   classifier hard-blocked even a read of `C:\ProgramData\ClaudeCode\
+   managed-settings.json` ("permission-machinery modification"). The platform
+   we onboard into forbids its agent from completing step 5, by design.
+3. **Phishing-shaped trust hurdle.** Every newcomer's Claude re-litigates
+   `curl | bash` + an Amazon-look-alike domain + a server-fetched
+   highest-precedence config — ~6.5 minutes of security ceremony and three
+   user confirmations per attempt, forever.
+4. **Zero post-run observability.** The script holds the GDS token in memory
+   only; once it exits, checking box state means a full GitHub device-flow
+   re-auth. The user waited 10h40m on the first-box approval gate with no way
+   to see anything.
+5. Assorted platform cuts: git-bash `/tmp` invisible to the native Read tool,
+   browser never auto-opens on Windows, private key left 644, and the
+   `StrictHostKeyChecking` mitigation lands in `~/.ssh/config`, which Claude
+   Desktop's embedded ssh2 **does not read** — it reads only
+   `~/.ssh/known_hosts` (the known knownhosts bug).
+
+Meanwhile the server side is already right: own-scoped `/box/ensure`,
+`/box/me`, `/box/close`, `/box/terminal`, `/box/ssh-key`,
+`/box/managed-settings` (ADR 0031/0035/0038) — the failures are all in the
+local last mile.
+
+## Decision
+
+### 1. A native tray app owns the local last mile
+
+`devbox-app/` — an Electron menu-bar (macOS) / system-tray (Windows) app,
+"OTB Dev Box". One switch: on = `POST /box/ensure`, off = `POST /box/close`,
+live state from polling `GET /box/me` (+ `/box/terminal` when active), native
+notifications on ready / awaiting-approval / idle-close. Because it is a
+human-launched native app, it can do everything the agent-driven flow could
+not: generate `~/.ssh/otb_builder` with real 600 perms (icacls ACL on
+Windows), register it, **replace** the box's lines in `~/.ssh/known_hosts` on
+every activation (host keys change on each re-provision), and install the
+managed-settings file to the system path behind the OS's own elevation prompt
+(osascript / UAC). The app never sends `claude_active` heartbeats: the
+droplet idle sweep stays the cost authority, and an unused box still reclaims
+itself.
+
+Electron over Tauri: no Rust toolchain for future builders, one runtime for
+both targets, and the project's existing JS-only skill set — size (~100MB)
+is the accepted cost. Zero runtime npm deps; the renderer is sandboxed,
+contextIsolated, and reachable only through named IPC verbs.
+
+### 2. App-pairing auth (browser clicks only)
+
+The app signs in by pairing against the GDS itself (`src/bongos/app-pair.js`,
+routes in `routes/auth.js`):
+
+    app: POST /auth/app-pair/start          → { pair_code, poll_token }
+    app: opens /builders/pair?code=…        (builders' hall approve page)
+    human: ONE Approve click                (cookie-gated, like cli-token/issue)
+    server: mints a source='cli' session, parks it on the pairing
+    app: POST /auth/app-pair/poll           → { token }   (delivered once)
+
+Two credentials with separated powers: the short `pair_code` (visible in the
+browser) can only *approve from an authenticated browser cookie session*; the
+long secret `poll_token` is the only thing that can *collect* the token, once.
+GitHub's device flow was rejected because it makes the human type a code;
+riding the web OAuth to a loopback was rejected because `safeReturnTo`
+deliberately blocks non-apex targets and we refuse to weaken it. Pairing
+state is an in-memory Map (10-min TTL, size-capped) — same posture as the
+existing device-flow pendings; no migration, restart voids in-flight pairings
+harmlessly. The minted session writes to `~/.config/otb/gds-session.json` —
+the SAME file the CLI uses, so pairing the app also signs in the `/builder-*`
+skills on that machine.
+
+### 3. Distribution: CI builds, public releases repo, branded redirects
+
+Installers cannot ride the git deploy (private repo, no LFS, GitHub 100MB
+cap). `.github/workflows/build-devbox-app.yml` builds dmg (arm64+x64) + NSIS
+exe on every `devbox-app/**` push and uploads artifacts; the operator
+publishes them as release assets on the PUBLIC releases repo named in
+`config/devbox-app.json` (`example-owner/example-devbox` — the ADR 0029
+status-mirror pattern, $0). The server serves branded URLs that 302 to those
+assets — `GET /downloads/devbox/{mac-arm64,mac-x64,win-x64}` +
+`latest.json` (`src/devbox-downloads.js`) — so every link a builder sees
+stays on example.com and a release bump is a one-file config change.
+The app checks `latest.json` daily and shows a download banner (no
+auto-update: meaningless without code signing).
+
+### 4. Unsigned, for now
+
+No Apple Developer ID ($99/yr) or Windows cert yet — a recurring cost that
+needs Lars's explicit go-ahead (CLAUDE.md §4); filed as a blocker. Until
+then macOS shows "Apple could not verify…" (System Settings → Privacy &
+Security → Open Anyway) and SmartScreen shows "unrecognized app". The
+onboarding copy walks through both honestly. electron-builder ad-hoc signs
+the mac build (required for arm64 to launch).
+
+### 5. Trademark posture (ADR 0004)
+
+Product name, appId, artifact filenames carry "OTB Dev Box" /
+`com.offtheboats.devbox` — never the civilization name. "Example" is
+rendered at runtime only, from the single constant in
+`devbox-app/src/brand.js`.
+
+## Consequences
+
+- The hall's Claude-Desktop onboarding pane drops the paste-a-prompt script
+  for: download app → approve → flip switch → open Claude Desktop. The
+  Claude Online (browser terminal) pane is unchanged. `/builders/settings`
+  gains a download section. `connect.sh`/`connect.ps1` remain for the
+  SSH-comfortable (ADR 0035's guide path) but are no longer the newcomer
+  front door.
+- New auth surface: 2 public + 2 any-builder routes, all classified by the
+  route-rank pre-pass; approve is cookie-gated so a leaked bearer cannot mint
+  siblings (mirrors `cli-token/issue`).
+- The signing-cert decision (and with it SmartScreen/Gatekeeper smoothness +
+  real auto-update) is deliberately deferred to the operator.
+- A future `box_connect` onboarding tick still clears through the box's own
+  `claude_active` heartbeat — unchanged by the app (which never heartbeats).