@bongos/core 1.17.0

package/docs/adr/0033-discord-bot-service-principal.md

@@ -0,0 +1,82 @@
+# ADR 0033 — Discord bot as a service principal (account-linking, both-mode upvoting, role-sync, inbound retirement)
+
+**Date:** 2026-06-04
+**Context:** GDS-V3, task [#619](https://example.com/builders#/task/619). Phase 3 of the Discord integration begun in [ADR 0032](0032-discord-mirror-of-gds.md) ([#607](https://example.com/builders#/task/607)). Where Phase 2 was a one-way webhook (no identity, no inbound), Phase 3 adds a **bot** — a persistent connection that reads reactions/messages and assigns roles — which means Discord *actions* now trigger GDS *writes*. That lands on the trust boundary. Companion to [ADR 0016](<redacted>.md) (the boundary), [ADR 0026](<redacted>.md) (the service-principal + identity-gate pattern this reuses), [ADR 0018](<redacted>.md) (the ranks role-sync mirrors), [ADR 0022](0022-secrets-policy.md) (bot token + OAuth secret), and [ADR 0008](0008-google-chat-oauth-user-auth.md) (the inbound path this retires).
+**Status:** Accepted (design). Implementation seeded as separate sub-tasks (listed at the end); nothing here is built yet. Foundation build is blocked on creating the Discord bot application.
+**Track:** `internal` (dev-system / team communication).
+
+> A decision record, not an implementation. The point is to lock the shape — especially the authorization model — so the build can proceed in reviewable pieces without relitigating the trust question each time.
+
+## Problem
+
+ADR 0032 established that Discord is a one-way mirror of the GDS. Phase 2 honored that trivially: a webhook only ever posts *out*. Phase 3's features all push the other way:
+
+- **Upvoting** — a reaction in Discord should feed the vote/karma system.
+- **Role-sync** — builder ranks should appear as Discord role badges.
+- **Inbound** — team messages in Discord should become ideas, retiring the Google Chat inbound path.
+
+The first and third make a **Discord event cause a GDS write**. Naively, a bot with a database connection could just write karma or votes. That would re-open exactly the hole [ADR 0016](<redacted>.md) closes: an actor *outside* the trust boundary deciding authoritative state. We need a design where the bot can act **without ever becoming an authority**.
+
+## Decision
+
+### 1. The bot is a service principal — trusted for identity, never for authorization
+
+The bot authenticates to the GDS as a dedicated **service principal** (`system_role = 'discord_bot'`), gated by a `requireDiscordBot` middleware that checks that exact identity — **not** a rank. This is the same shape the BFG cross-builder write path uses ([ADR 0026 §6C](<redacted>.md)): a stolen or rank-escalated *human* token has `system_role = NULL` and is rejected; only the bot principal's row passes.
+
+The principal is trusted for **one** thing: asserting "this Discord user, who reacted/posted, is linked builder X." It is **never** trusted to decide what X may do. Every write the bot triggers re-derives authorization from **X's live `builders.rank`** server-side, through the same guards the web/CLI paths use. The bot cannot escalate; at most it can mis-report *which linked user* acted, and that blast radius is bounded (below).
+
+Every bot-triggered write is recorded in `audit_log`, tagged with the originating surface (`discord_bot`) and the asserted Discord user id, so bot-originated peer-votes are distinguishable from direct web/CLI votes during forensic review. (The `audit_log` cited as a control below must carry this surface field — F1 adds it.)
+
+### 2. Account-linking is UI-first and self-asserted
+
+A Discord user becomes "trusted as builder X" only when **X personally links it**: signed into the `/builders` hall (already GitHub-authed), X clicks **Link Discord**, approves a standard Discord OAuth2 sign-in (`identify` scope), and the server stores the `(builder_id ↔ discord_user_id)` pair in a new `discord_links` table. **CSRF protection is mandatory:** the authorize request carries a one-time, unguessable **`state`** parameter bound to X's session (the same protection the existing GitHub web flow uses — `buildAuthorizeUrl(state, …)` in `auth.js`), and `/discord/callback` **rejects any request whose `state` doesn't match**. Without it, an attacker could trick a logged-in builder's browser into a forged callback carrying an attacker-controlled `code`, silently linking the *attacker's* Discord account to the *victim's* builder row — after which every attacker reaction would cast peer-votes as the victim. The `state` check closes that vector; it is a hard requirement of F2, not an option. An **Unlink** affordance is always present. No tokens, no terminal — per the project's <redacted> rule. Because the mapping comes from the *user's own OAuth*, not from the bot, the bot is not trusted to *invent* mappings — only to report which (already-linked) user fired an event.
+
+### 3. Upvoting — both modes, cleanly separated
+
+A 👍 on a shipped item in **#ship-feed** flows: bot → `requireDiscordBot` endpoint with `{discord_user_id, target_task_id}`. The server resolves the link and branches:
+
+- **Linked builder is Metic+ and not the author** → cast a **real peer-vote** through the *existing* `peer_votes` path, re-enforcing every guard server-side: Metic+ only, anti-self-vote, the 7-day karma lag, the tallied-freeze. (Identical authorization to `POST /tasks/:id/vote`.)
+- **Anyone else** (player, Xenos, unlinked, or self-vote) → record a **cosmetic applause** in a separate `discord_applause` store that **never touches `karma_log`**.
+
+The two stores are disjoint by construction: applause is engagement flavor; karma is earned only through the rank-gated path. A Xenos's enthusiasm shows as applause and changes no reputation.
+
+### 4. Role-sync is one-way (GDS → Discord)
+
+On rank change, on link, and on a periodic reconcile, the bot sets the member's Discord role (Xenos / Metic / Archon) from `builders.rank`. This is read-only against the GDS and write-only against Discord — it can never feed authority back in. It makes the role badges *honest* (the point of ADR 0032 §2). Requires the bot to hold **Manage Roles** and to sit above the managed roles in Discord's hierarchy.
+
+### 5. Inbound retirement
+
+The bot listens on a designated channel, files messages into `idea_inbox` via the existing file-idea path (attributed to the linked builder when known), and then the Google Chat **inbound** machinery is retired: the `SessionStart` `poll.js` hook, the `chat-intake-daily` routine, and the `chat-inbox.md` flow. (`scripts/chat/` can then be deleted entirely — outbound already moved in [#607](https://example.com/builders#/task/607).) Requires the **Message Content** intent.
+
+### Hosting & secrets
+
+The bot runs **in-process** in the existing Node server as a module, behind a `DISCORD_BOT_ENABLED` kill-switch (default **off**, fail-closed — like `BFG_WRITE_ENABLED`), with reconnect handling. Adds the `discord.js` dependency. Cost is **~$0** (it rides the droplet we already pay for; Discord is free).
+
+**Secret-deployment note (differs from Phase 2):** the Phase 2 webhook ran on the operator's laptop during `/builder-ship`, so its secret stayed local. The bot runs **on the droplet** (a persistent gateway connection), so the **bot token + Discord OAuth client secret must live on the droplet** (systemd `EnvironmentFile`), per [ADR 0022](0022-secrets-policy.md) — not only in `~/.config/otb/`. This is the first Discord secret the droplet needs.
+
+## Consequences
+
+- The trust boundary holds: the bot maps identity; the GDS still decides. The one invariant to defend in review is **"every bot-triggered write re-checks the linked builder's live rank."**
+- Discord role badges become continuously honest (auto-synced from the DB).
+- Google Chat is fully retired once inbound lands; `scripts/chat/` is removed then.
+- New surface area to own: a `discord.js` dependency, an always-on connection (reconnect/rate-limit handling), and a droplet-side secret.
+- A compromised bot could forge "user X reacted," yielding at most a spurious Metic+ peer-vote — bounded by the anti-self-vote guard, the visible 7-day karma lag, and the `audit_log`, and revocable by the `DISCORD_BOT_ENABLED` kill-switch.
+
+## Alternatives considered
+
+- **Bot writes karma/votes directly (its own DB access).** Rejected — it makes the bot an authority and re-opens [ADR 0016](<redacted>.md). The principal + per-write rank re-check is the whole point.
+- **Trust Discord roles for authorization.** Rejected outright (ADR 0016 / 0032 §2): roles are cosmetic reflections, never keys.
+- **Map Discord→builder by matching usernames (no OAuth link).** Rejected — unverified and spoofable; identity must be self-asserted by the builder.
+- **A separate bot process / service.** Considered; in-process behind a kill-switch is simpler for one droplet. Revisit if the connection destabilizes the web process.
+- **Applause feeds karma (single mode).** Rejected — it would let unranked enthusiasm mint reputation. Keeping applause cosmetic and disjoint from `karma_log` is the load-bearing separation of decision [#3](https://example.com/builders#/task/3).
+
+## Implementation sub-tasks (seeded separately)
+
+1. **F1 — Foundation** (no live bot needed): a new migration (next free number at build time) adding `discord_links`, `discord_applause`, the `discord_bot` service principal, and the `audit_log` originating-surface field + `requireDiscordBot` gate + db helpers + unit tests.
+2. **F2 — Account-linking web flow** (needs OAuth creds): Discord OAuth start/callback routes + Link/Unlink UI on the hall.
+3. **F3 — Bot process** (needs bot token): `discord.js` client, `DISCORD_BOT_ENABLED`-gated, droplet EnvironmentFile, connection + reconnect.
+4. **F4 — Upvoting** (needs F1–F3): reaction handler → bot-principal endpoint (real peer-vote if Metic+, else applause).
+5. **F5 — Role-sync** (needs F1–F3 + Manage Roles): rank → Discord role on change/link/reconcile.
+6. **F6 — Inbound** (needs F3): message handler → `idea_inbox`; retire Google Chat inbound + delete `scripts/chat/`.
+
+**Prerequisite (human, browser):** create the Discord bot application — bot token, OAuth2 client id/secret, the Server Members + Message Content + Guild Message Reactions intents, and the Manage Roles permission. Gates F2/F3 onward.

package/docs/adr/0034-thetes-graduated-newcomer-rank.md

@@ -0,0 +1,53 @@
+# ADR 0034 — `thetes`: a 4th live rank for graduated newcomers, with auto-graduation after 3 ships
+
+**Date:** 2026-06-05
+**Context:** GDS-V3, task [#692](https://example.com/builders#/task/692). Amends [ADR 0018](<redacted>.md) (the three-rank model). Companion to [ADR 0016](<redacted>.md) (server-enforced permissions) and the newcomer-supply work (the `newcomer-generator` routine). Role-sync mirrors it to Discord per [ADR 0033](<redacted>.md).
+**Status:** Accepted + shipped.
+**Track:** `internal` (dev-system / builder onboarding).
+
+## Problem
+
+A new builder defaults to `xenos`, the sandboxed entry rank, which can claim **only** tasks flagged `newcomer_friendly`. That pool is chronically under-supplied: a fresh Xenos repeatedly arrives to an empty queue, files some ideas (which a Xenos cannot even promote — `PATCH /inbox` is Metic+), and finds the queue still empty. Builder 25 hit exactly this loop. The supply-side fix (a generator that tops up `newcomer_friendly` tasks) helps, but it fights physics: it must perpetually feed *every* newcomer's *entire* tenure.
+
+The jump out of the sandbox was also all-or-nothing: `xenos` → `metic`, where Metic carries real trust (idea triage, blocker resolution, red-team filing, planning/priority, claiming sensitive infra). That is too big a grant to hand out just so someone can pick up ordinary work, so it stayed gated behind a manual Archon decision — leaving newcomers stuck in the starved sandbox in the meantime.
+
+## Decision
+
+Add **`thetes`** as a 4th LIVE rank between `xenos` and `metic`, and **time-box the sandbox**: a Xenos auto-graduates to Thetes after shipping a few tasks.
+
+### 1. The ladder gains a tier
+
+`xenos (1) < thetes (2) < metic (3) < archon (4)` — the `REQUIRES_RANK_TIER` map in `src/bongos/db.js`. `thetes` was already a reserved value in the `builders.rank` CHECK enum (migration 023), so no `builders` schema change was needed; migration `068` only widens the inverse gate `tasks.requires_rank` to accept `'thetes'`.
+
+### 2. What Thetes can and cannot do
+
+- **Can:** claim the **entire general queue** — any task whose `requires_rank` is the default `'xenos'` — with **no** `newcomer_friendly` restriction. This is the whole point: a Thetes draws from the large pool, not the starved newcomer pool.
+- **Cannot:** anything scope-shaping or trust-bearing. It is blocked from tasks raised to `requires_rank='metic'/'archon'`, and — because `requireRank()` is **exact-set membership** (`src/bongos/auth.js`), not tier comparison — it inherits **none** of Metic's route grants (idea triage, blocker resolution, red-team, planning/priority, task create/edit). Those stay Metic+ with zero code change.
+
+This asymmetry is what makes the next decision safe.
+
+### 3. Auto-graduation is automatic, bounded, and low-risk
+
+A Xenos is promoted to Thetes the moment their **3rd** task reaches `shipped` (merged + deployed). It happens server-side, **inside the ship transaction** (`db.shipTask` → `db.maybeAutoGraduateToThetes`), atomic with the ship. The count is `COUNT(*)` of the builder's tasks at `status='shipped'` **attributed via `tasks.shipped_by`**, and the promotion is rank-guarded (only a current `xenos`), so it is idempotent — it fires exactly once, and a non-Xenos never re-promotes.
+
+> **Trigger note (corrected in [#704](https://example.com/builders#/task/704)):** the original [#692](https://example.com/builders#/task/692) cut graduated at `confirmed` (credits-earned). The Archon rule is "after 3 tasks are **successfully shipped**," so the trigger moved from the confirm paths to `shipTask`, keyed on `shipped` status + `shipped_by` attribution.
+
+**`thetes` is reachable two ways.** The automatic 3-shipped-tasks graduation above, AND a deliberate Archon promotion via `PATCH /builders/:id/rank` (e.g. to fast-track a builder the Archon already trusts to roam the queue). Both are valid; they coexist. (A short-lived [#704](https://example.com/builders#/task/704) cut wrongly refused manual set-to-thetes; [#706](https://example.com/builders#/task/706) removed that block — the Archon must be able to grant the rank directly.)
+
+Auto-promotion of *rank* normally raises a trust-boundary flag (ADR 0016: rank is authority). It is acceptable here precisely because **graduating to Thetes grants no authority** — only breadth of claiming. The dangerous grant (Thetes → Metic) remains a deliberate Archon promotion through the single rank chokepoint (`PATCH /builders/:id/rank`). So the machine can hand out "you may now pick up normal work" but never "you may now shape scope or touch sensitive infra."
+
+The promotion reuses the existing rank-change machinery (refactored into a shared in-transaction core `_applyRankChangeTx`): it writes the same `credit_log` `rank_change` audit row (here tagged `auto-graduation: N shipped tasks`), earns the standard +5 promotion ceremony delta, does **not** revoke sessions (promotions never do), and fires the post-commit box-access reconcile.
+
+## Consequences
+
+- **The newcomer-supply problem shrinks to a 3-task window.** The `newcomer-generator` now only has to keep the queue stocked for a builder's first three ships, not their whole tenure. Starvation after that is structurally impossible — Thetes draws from the general queue.
+- **`metic` is now also marked LIVE** in the onboarding rank-ladder diagram. The diagram fact-extractor (`diagram-facts.wiredRanks`) gained a 5th signal — membership in `REQUIRES_RANK_TIER` — which is the honest definition of "this rank participates in the live claim gate." Previously `metic` was wired-in-spirit (skills said "Metic+") but the extractor missed it.
+- **Exact-set `requireRank` is load-bearing.** Adding a rank *below* an existing gated rank is safe only because the gates name their allowed ranks explicitly. A tier-based `requireRank` would have silently granted Thetes everything ≥ its tier. This is now documented as the reason the exact-set design stays.
+- **`RANKS` array order is load-bearing too.** `setBuilderRank` derives promotion-vs-demotion from `RANKS.indexOf`; `thetes` had to move to sit between `metic` and `xenos` so `xenos→thetes` reads as a promotion and `thetes→metic` as a further promotion.
+- **Reversibility.** A mis-graduated builder is demoted through the normal Archon path; demotion revokes their sessions, so the lower rank takes effect on their next request.
+
+## Alternatives considered
+
+- **Just raise the newcomer-queue target / fix supply only.** Treats the symptom. A shared pool of N newcomer tasks is always racing consumption; time-boxing the sandbox removes the dependency entirely for everyone past their 3rd ship.
+- **Auto-promote `xenos` straight to `metic`.** Rejected: Metic carries triage/trust/red-team/infra powers no automatic rule should hand out. The new intermediate rank is exactly the "breadth without trust" tier that makes auto-promotion safe.
+- **Promote by drachmae or karma instead of ship count.** Rejected for v1: ship count is the most legible "you've proven you can land work" signal and is already the credit-landing event. A richer policy can layer on later.

package/docs/adr/0035-builder-onboarding-three-paths.md

@@ -0,0 +1,128 @@
+# ADR 0035 — Builder onboarding: three setup paths (Local / DO Box / Remote Control)
+
+**Date:** 2026-06-06
+**Context:** GDS-V3, task [#715](https://example.com/builders#/task/715). Feeds done-when criterion **C1** (`a Metic onboards in ≤ 2h`). This ADR is the *onboarding-as-experience* companion to [ADR 0031](<redacted>.md), which locked the **substrate** (the containerized DO box, auto-suspend, rank-gated source access) but never consolidated how a person actually *arrives*. Builds on [ADR 0034](<redacted>.md) (the `xenos < thetes < metic < archon` ladder), [ADR 0016](<redacted>.md) (server-enforced permissions), [ADR 0022](0022-secrets-policy.md) (no secrets in repo), and the box onboarding middleware shipped in [#701](https://example.com/builders#/task/701) (§9.4 of ADR 0031).
+**Status:** Accepted — §2 (the first-box Archon approval gate) superseded by [ADR 0059](<redacted>.md). *Decision record — locks the onboarding shape and three new policy decisions. The box-lane machinery already exists (ADR 0031 + [#701](https://example.com/builders#/task/701)); the deltas this ADR introduces (the Metic+ local gate, the first-box approval gate, the single hosted guide surface, the primer rewrite) are implementation sub-tasks listed at the end and are NOT yet built.*
+**Track:** `internal` (dev-system / builder onboarding).
+
+> **⚠️ Superseded in part by [ADR 0059](<redacted>.md) (task [#1141](https://example.com/builders#/task/1141)).** Decision **§2 — "A newcomer's FIRST box requires Archon approval"** is **removed**: with admission now invite-gated ([ADR 0050](<redacted>.md)), member-join is the sole human gate, and an admitted builder's first box now provisions hands-off. §1 (Metic+ local clone) and §3 (the single hosted guide) stand unchanged. Read §2 below as historical.
+
+## Problem
+
+A new builder can reach Example three different ways, but the project has never written down what the **arrival experience** is for each, who each is for, or how they're gated. ADR 0031 decided *where the worker runs* (a box we control); it did not decide *how a stranger goes from "I heard about this" to "I'm shipping tasks."* Three concrete gaps force this ADR:
+
+1. **The live onboarding contradicts the intended model.** Today the *only* fully-working setup path is the one documented in [`docs/onboarding/primer.md`](../onboarding/primer.md) "Get set up": **accept a GitHub collaborator invite and clone the private repo onto your own disk** — open to *every* rank, including a brand-new Xenos. ADR 0031 §6 says source access should be a *rank-gated, revocable, box-held* boundary. So the live behavior is the exact opposite of the locked design: an unproven newcomer currently gets a permanent local copy of the whole repo. This must be reconciled.
+2. **The box lane is built but has no front door.** ADR 0031 + [#701](https://example.com/builders#/task/701) shipped the whole provisioning spine — `POST /box/ensure`, the intent queue, the control-plane runner, the pairing-link path. But there is no *guided arrival*: nothing tells a non-technical or Chromebook builder, in plain language, "here is your first session, here is what to type, here is how you wait for your box." The capability exists; the on-ramp doesn't.
+3. **Cost exposure is unbounded at the front door.** Anyone with a GitHub account can complete Device-Flow auth and become a Xenos, and a Xenos is above the box provisioning floor (`DEFAULT_PROVISION_FLOOR = 'xenos'`, [`src/bongos/boxes.js`](../../src/bongos/boxes.js)). With [#701](https://example.com/builders#/task/701)'s auto-draining intent queue, a signup could cause a paid droplet (~$24/mo, ~$5/active after auto-park) to be created with **zero human in the loop**. On a $5,000/yr budget that's a real hole.
+
+## The three paths (what each *is*, who it's for, how it's gated)
+
+Onboarding sorts every builder into exactly one of three on-ramps. All three share one foundation — the GitHub Device-Flow auth that `/builder-setup` already performs (`scripts/gds/setup.js`) and that writes the GDS session token — and all three end at the same place: a builder who can `/builder-start`, claim, and ship. They differ only in **where the worker runs** and **how the builder reaches it**, exactly as ADR 0031's three-pieces model (screen / worker / brain) predicts.
+
+| Path | Worker runs | Reached via | Who it's for | Rank gate |
+|---|---|---|---|---|
+| **1. Local** | The builder's own machine | Native Claude Code / Desktop **Local** | Trusted power users who want to avoid box cost | **Metic+ only** |
+| **2. DO Box** | A per-builder DigitalOcean box | Claude Desktop → **SSH** | The default for completely new users (Mac/Windows) | Xenos+ (first box needs approval) |
+| **3. Remote Control** | The *same* per-builder DO box | Browser → **Remote Control** (`claude rc`) | Chromebook / iPad / thin-device users | Xenos+ (first box needs approval) |
+
+### Path 1 — Local setup (Metic+ only)
+
+- **User group.** Trusted power users who would rather run the repo on their own hardware than pay for (or wait on) a box.
+- **What it is.** Claude Code pointed at a local folder that is a clone of the private GitHub repo — today's flow, unchanged in *mechanics*.
+- **The gate (new policy).** **Local is Metic+ only.** A new user must **not** be able to clone the repo onto their own disk; for everyone below Metic, all source lives inside the box (Path 2/3). This aligns the live behavior with ADR 0031 §6/§9.2, where full source creds first arrive at graduation to Metic. Below Metic, the local on-ramp is simply not offered, and the collaborator-invite path is closed to them.
+- **Onboarding steps.** Same as the current flow: install Claude Code, accept the repo invite, clone into an empty folder, `/builder-setup`, read the primer → `/builder-primer-read` → `/builder-start`.
+
+### Path 2 — DO Box setup (the newcomer default)
+
+- **User group.** Completely new users on a Mac or Windows machine.
+- **What it is.** Claude Code runs *on* an org-controlled, containerized DigitalOcean box provisioned for that builder; the builder's Claude Desktop connects to it over SSH. The repo never lands on the builder's personal disk.
+- **The gate.** Above the `xenos` provisioning floor, so any signed-in builder qualifies — **but the first droplet for a builder who has never had a box requires Archon approval before it is created** (new policy; see Decision §2). "One droplet at a time" is **already enforced**: `box_intents` carries a partial unique index (one open intent per builder) and `builder_boxes` is one row per builder.
+- **Onboarding steps.**
+  1. The new user opens a simple local Claude session pointed at the **hosted onboarding guide** (Decision §3) — the same content that drives the local-onboarding walkthrough today, but aimed at provisioning a box rather than cloning a repo.
+  2. Claude walks the user through requesting a box (`/builder-box` → `POST /box/ensure`), which records a provision intent. The user is told their first box needs a quick approval, and waits.
+  3. Once approved + provisioned, the user opens a new session, their Claude Desktop SSHes into the box, and they are now a builder in Example. The source surface they see is rank-scoped (`starter` sparse-checkout for Xenos/Thetes; `full` at Metic+ — ADR 0031 §9.2).
+
+### Path 3 — Remote Control (Chromebook / thin devices)
+
+> **⚠️ Superseded by [ADR 0038](<redacted>.md).** The `claude rc` headless-service mechanism described below was retired — a headless box cannot bootstrap `claude rc` (interactive-only Trusted-Devices enrollment). The box now serves its own `ttyd` browser terminal over a Cloudflare Tunnel where the builder runs normal interactive `claude`. The Path-3 *intent* (a browser-only thin-device on-ramp to the same per-builder box) stands; the `claude rc`-as-always-on-service mechanics below are historical.
+
+- **User group.** Users on a device that cannot run Claude Desktop (a literal Chromebook, an iPad, a phone).
+- **What it is.** Identical to Path 2 — the same per-builder box — but reached from a browser via Claude's Remote-Control (`claude rc` running as an always-on service on the box).
+- **Onboarding steps.**
+  1. Same as Path 2 steps 1–2, except the guide surface is the **hosted onboarding page in a browser tab** rather than a local Claude folder (a Chromebook has no local dev environment to point Claude at). It is the *same content* (Decision §3) — one guide, two ways to read it.
+  2. After the box is provisioned, the user pairs: `POST /box/ensure` → poll `GET /box/pairing-link` until the `claude rc` link appears (published UP by the box's `box-report-pairing` cron, [#701](https://example.com/builders#/task/701)) → open the link. Claude then drives the box from the browser.
+
+## Decision
+
+The three paths above are the canonical onboarding model. Beyond consolidating them, this ADR locks **three policy decisions** (workshopped with Lars, 2026-06-06) and a **rollout sequence**.
+
+### 1. Local source access is Metic+; everyone below is container-only
+
+The <redacted> + clone-to-own-disk path becomes a **Metic+ affordance**. Below Metic (Xenos, Thetes), there is **no local clone** — source exists only inside the rank-gated box, where it is revocable and audited (ADR 0031 §9.2). This is the onboarding-side enforcement of the trust boundary: *proven* builders may hold a local copy; *unproven* ones work inside the box. Mechanically this means (a) the primer stops instructing newcomers to clone, and (b) collaborator invites are issued only at/after Metic.
+
+> **Honest limit (carried from ADR 0031 §6/§9.2).** A Metic with a local clone, or any authorized builder with a box session, can still copy code they can read. This is defense-in-depth + revocation + audit, not insider-proof DRM. The Metic+ gate raises the bar from "any signup gets the repo forever" to "only a proven, promotable builder does."
+
+### 2. A newcomer's FIRST box requires Archon approval
+
+[#701](https://example.com/builders#/task/701) made `POST /box/ensure` enqueue a provision intent that the control-plane runner auto-drains. That is correct for *wakes* and for *re-provisions* of a builder who has earned a box before — but the **first ever provision for a builder** is now gated:
+
+- A `provision` intent for a builder with **no prior box** (no `builder_boxes` row, or one that has never been `active`) is held in a **pending-approval** state instead of being drained. The runner skips it until an Archon approves.
+- An Archon approves via an Archon-only affordance (a route + a `box.js` operator command — exact surface is an implementation detail; the decision is *that approval gates the first provision*). Approval flips the intent to drainable; the existing runner then provisions it unchanged.
+- **`wake` intents and any subsequent provision** (a builder who has had an `active` box before) are **not** gated — they auto-drain as today. The gate is specifically the *first* paid droplet for an unproven account.
+
+This closes the §Problem-3 cost hole: a stranger can sign in and read, but cannot cause us to spend money until a human says so. It rides the existing `box_intents` queue (add an approval state/column) rather than introducing a new mechanism, and it keeps the §6 trust-boundary invariant intact — the web tier still only *asks*; it never holds `DO_API_TOKEN` and never provisions directly.
+
+> **Why not an invite-code gate (the considered alternative).** Closing signup entirely (invite codes) is the strongest cost+security control, but it adds a distribution burden and forecloses the open, low-friction "anyone can come look" funnel C1 implies. First-box approval keeps the funnel open (sign up, read, file ideas) while still putting a human between a signup and a charge. Revisit invite codes if signup-driven box spend ever becomes a real problem.
+
+### 3. One hosted guide surface for both SSH and RC — no separate bootstrap repo
+
+The pre-box "guide Claude" needs onboarding context, never source. Rather than build and maintain a **separate private bootstrap repo** (the original sketch), there is **one hosted onboarding guide** served from the GDS:
+
+- **SSH/Desktop users** point a local Claude session at it (a hosted page, or the existing public `GET /box/connect` / `connect.sh` bootstrap it links to).
+- **RC/Chromebook users** open the same content as a **browser page** — they have no local folder to point Claude at.
+
+Same content, two ways to consume it. This avoids a second repo to keep in sync, and the *executable* half already exists (the public, `PUBLIC_ORIGIN`-pinned `connect.sh`/`.ps1` from [#685](https://example.com/builders#/task/685)). The new artifact is the **human/Claude-readable guided walkthrough** that frames the whole arrival — sign in → request box → wait for approval → connect/pair — and that is safe to serve publicly because it contains zero source.
+
+### 4. Rollout — gate local to Metic+ now, keep it as a fallback until the box lane is hardware-verified
+
+The box lane (Paths 2 & 3) is **built but unverified on real hardware**, and the box-side source credential is **inert** (`configured:false` — the prod secret is unset; ADR 0031 §9.2/§9.4, [#699](https://example.com/builders#/task/699)). We must never leave **zero** working paths. Therefore:
+
+- **Now:** apply Decision §1's Metic+ gate to the local path, and make Path 2 the *documented* default for newcomers.
+- **Keep:** the collaborator-invite local path as a **Metic+-only fallback** — it stays the proven escape hatch until the box lane works end-to-end on hardware.
+- **Then:** once the verification plan below is green, the box lane becomes the real newcomer default and the local path settles into its permanent Metic+ niche.
+
+## Verification plan (what "test the existing setup" means after this ADR)
+
+ADR 0031 §9 + [#699](https://example.com/builders#/task/699) + [#701](https://example.com/builders#/task/701) record the box lane as hermetically tested but **hardware-unverified**. This ADR's acceptance does not assert the box lane *works* — it asserts the *shape*. The following legs must be exercised on a real box before Path 2/3 can be the default (this is the test campaign that follows this ADR):
+
+1. **Source credential goes live.** Set the prod `BOX_SOURCE_*` secret(s) so `GET /box/source-access` returns `configured:true`; verify a real box sparse-clones the `starter` surface (Xenos) and the `full` surface (Metic) and that the token is scrubbed from `.git/config` (`infra/box-source-fetch.sh`). *Operator gotcha (recorded):* `DO_API_TOKEN` must carry **tag-create** scope or provisioning 422s.
+2. **Auto-provision via the timer.** Install `box-intent-runner.timer` on the control plane; confirm a `POST /box/ensure` intent is drained into a live droplet — **including the new first-box approval gate**: an unapproved first intent stays pending; an Archon approval lets it drain.
+3. **Wake-on-connect.** Park a box, confirm `POST /box/ensure` wakes it from snapshot.
+4. **Desktop SSH connect.** A real Claude Desktop connects to a running box via the managed-settings host (the [#599](https://example.com/builders#/task/599) stable-hostname cutover) and runs Claude Code on it.
+5. **RC pairing end-to-end.** `box-report-pairing` publishes a real `claude rc` link; a browser reads it via `GET /box/pairing-link` and drives the box.
+6. **Guide + primer dry-run.** A fresh GitHub account, following only the hosted guide + rewritten primer, reaches "claimed and shipped a task" within the C1 ≤2h budget — the actual onboarding-time measurement.
+
+## Consequences
+
+- **The live primer must be rewritten.** [`docs/onboarding/primer.md`](../onboarding/primer.md) "Get set up" currently teaches only the open-to-all local clone. It must present the three paths, default newcomers to the box, and apply the Metic+ local gate. The ADR 0031 three-pieces mental model (screen/worker/brain) lands here verbatim, as 0031 §"mental model" always intended.
+- **Collaborator-invite issuance becomes rank-aware.** Invites are issued at/after Metic, not on signup. (The mechanics of *who* sends invites and *when* is an operator step today; the policy is now written.)
+- **`box_intents` gains an approval state.** A small schema/route/CLI addition; the runner learns to skip unapproved first-provisions. No new subsystem.
+- **One thing to maintain, not two.** The single hosted guide means no second repo drifting out of sync — but it does mean the guide content is a real artifact someone owns and keeps current.
+- **Cost stays bounded at the door.** Open, free signup + read; money only after a human approves the first box. Aligns with the §5 cost model of ADR 0031.
+- **No relitigating 0031.** Substrate, auto-suspend, source-scoping, and the intent queue are unchanged. This ADR only adds the onboarding-experience layer and the three policy gates on top.
+
+## Implementation sub-tasks (proposed — to be seeded in a planning/triage session)
+
+Not yet created; listed so a build session has a starting decomposition. None are built by this ADR.
+
+1. **Metic+ local gate.** Stop the primer/onboarding from offering local clone below Metic; make collaborator-invite issuance Metic+.
+2. **First-box approval gate.** Add a pending-approval state to `box_intents` (schema + the runner skip), an Archon-only approve affordance (route + `box.js` command), and surface "your box is awaiting approval" to the waiting builder via `/builder-box`.
+3. **Hosted onboarding guide.** Author the single public guided walkthrough (page + the content a local guide-Claude reads), framing sign-in → request box → await approval → connect/pair, for both SSH and RC. Reuses the existing public `connect.sh`/`.ps1`.
+4. **Primer rewrite.** Replace the local-only "Get set up" with the three-path model + the 0031 mental model; keep `/builder-primer-read` as the gate.
+5. **Run the verification plan.** The six-leg hardware campaign above — this is the "test the existing setup" work that motivated the ADR.
+
+## Open questions (flagged, not blocking)
+
+1. **Approval surface ergonomics.** Should first-box approval be a one-click action in the builders' hall, a Discord interaction (ADR 0033), or an operator CLI only? Lean: builders'-hall action + `box.js` fallback; decide at build time.
+2. **Approval expiry.** Does an approved-but-undrained intent expire, and does a denied newcomer get told why? Lean: approvals don't expire; denials leave an audited note.
+3. **Metic transition off the box.** When a Xenos/Thetes on a box graduates to Metic and *wants* the local path, what's the handoff (re-clone locally, retire the box, or keep both)? Touches ADR 0031 open-question [#1](https://example.com/builders#/task/1) (ownership transition); defer.

package/docs/adr/0036-builders-subdomain-and-ui-reorg.md

@@ -0,0 +1,40 @@
+# ADR 0036 — Builders subdomain + builder-UI reorganization (hall / watch / settings / status)
+
+**Date:** 2026-06-06
+**Context:** GDS-V3, task [#726](https://example.com/builders#/task/726). Builds on [ADR 0016](<redacted>.md) (server-enforced permissions), [ADR 0029](<redacted>.md) / [ADR 0030](<redacted>.md) (the status + hall surfaces being reorganized), and the asset-stamping serving model in `server.js` / `src/asset-version.js`.
+**Status:** Accepted. Shipped under [#726](https://example.com/builders#/task/726) (grader skipped at Lars's instruction — UI/infra reorg, no logic the grader gates).
+**Track:** `internal` (dev-system / builder UI).
+
+## Problem
+
+The builder-facing web had grown into one overloaded surface. The authenticated hall (`example.com/builders`) carried *everything*: a builder's personal standing, the per-skill model picker, AND three Archon-only monitoring panels (security watch, the access-request gate, the roster). Meanwhile the public status dashboard (`status.example.com`) carried operational engineering detail (the Stonemason's Mark grade aggregate, the Surveyor's estimation drift, the Mason's Ledger repo health) that is really *builder* monitoring, not something a public visitor needs. There was no single, easily-gated home for "the builder surface," and no dedicated place for an Archon to watch the GDS and the other builders.
+
+## Decision
+
+Three surfaces, cleanly separated by audience:
+
+1. **`builders.example.com` — a dedicated subdomain for the entire builder surface.** It serves the same `public-builders/` tree, rooted at `/`, so the whole authenticated builder UI sits behind one host that is easy to reason about and gate. Implemented as a thin **rewrite shim** in `server.js` (`isBuildersHost`): every non-API path on the builders host is rewritten onto the existing `/builders/*` tree, so all the established serving + sign-in gating + asset-stamping logic is reused verbatim — zero duplication. The legacy `example.com/builders/*` paths keep working unchanged, so the subdomain is **purely additive**: nothing breaks before DNS + cert land, and existing links / primer nudges / the OAuth callback (`→ /builders`) are untouched.
+
+2. **`builders.example.com/watch` — a new Archon-only monitoring page** ("The Watch"). Sections, in order: **GATE** (pending access requests), **WATCH** (security: open vuln reports + override requests + the audit log), **ROSTER** (the citizen-roll with rank/status actions), **MARKS** (per-builder grade breakdown — new endpoint), **STONEMASON'S MARK** (project-wide grade aggregate, moved off status), **SURVEYOR** (estimation drift, moved off status), **MASON'S LEDGER** (repo health, moved off status), **BFG** (session-ledger tally + link). Gated server-side by `requireArchonPage` on the shared `/builders/watch` path (one matcher covers both hosts since the subdomain rewrites `/watch` → `/builders/watch`); every data endpoint it reads is independently `requireRank('archon')`, so the page gate is defense-in-depth, not the only wall.
+
+3. **`builders.example.com/settings` — a new personal-preferences page.** Holds **VOICES** (the per-skill model picker, moved off the hall) and **CRAFT** (discipline preferences, moved off the now-read-only Standing card). Open to any authenticated builder.
+
+The **hall** (`builders.example.com`) is now a citizen's *personal* dashboard, reordered to: STANDING, HONOURS, KARMA (with the peer-acclaim feed folded under it), WORKS (ships wrought), CLAIM, then MARKS, BOUNTY, ROLL — onboarding WELCOME/PATH still lead for newcomers. The Archon panels and the model picker are gone from it (moved to /watch and /settings respectively); their nav links live in the header gated-nav (the Watch link reveals only for Archons).
+
+The **status dashboard** (`status.example.com`) is slimmed to what a public visitor cares about, reordered to: PULSE, WATCH (uptime), ARCHITECTS, WORKS, TREASURY, LATELY INSCRIBED, THE WORLD. The three engineering tablets moved to /watch.
+
+### Cross-subdomain auth
+
+A single sign-in must span `example.com`, `builders.`, and `status.`. The `gds_session` cookie is now scoped to **`.example.com`** on the production-facing hosts (enumerated allowlist: apex, www, builders, status) and stays **host-only** on localhost and `staging.example.com` — staging is a separate process + DB, so an apex cookie there would bleed a token across environments. The OAuth handshake still runs on the canonical origin (the builders subdomain links sign-in at the apex), so GitHub's fixed redirect_uri registration is unaffected. A validated `?return=` parameter (open-redirect guarded to relative paths + `*.example.com` https URLs only) lets the subdomain bounce a stranger through the apex handshake and land them back on the subdomain. Logout clears both the host-only and apex-scoped cookie forms.
+
+## Alternatives considered
+
+- **Duplicate the serving logic for the subdomain.** Rejected — the rewrite shim reuses the whole `/builders/*` pipeline; a second copy would drift.
+- **Hard-redirect `/builders/*` → the subdomain.** Rejected (for now) — the subdomain needs DNS + cert first; redirecting before that would dark the hall. The subdomain is additive; a redirect can come later once it's verified live.
+- **`/watch` WATCH = uptime (mirror status).** Considered (the status spec called WATCH a status-mirror), but Lars chose `/watch` WATCH = the *security* watch — the Archon's real monitoring concern. Status keeps its own uptime WATCH for the public.
+
+## Consequences
+
+- **Operator one-time setup** (until then everything stays reachable at `example.com/builders/*`): add a Cloudflare DNS A record `builders` → `REDACTED_IP` (proxy ON); confirm the origin cert's `*.example.com` SAN covers it; `caddy reload`. The `builders.example.com` Caddy block ships in `infra/Caddyfile`.
+- New endpoint `GET /api/gds/grades/by-builder?days=` (Archon-only) backs the MARKS section.
+- Dead render functions for the moved hall sections remain defined-but-unreferenced in `builders.js` (all guarded); a follow-up cleanup can delete them.

package/docs/adr/0037-discord-channel-management.md

@@ -0,0 +1,51 @@
+# ADR 0037 — Bot-managed Discord channels from a config file, Archon-gated commands
+
+**Status:** Accepted — 2026-06-06
+**Context task:** [#727](https://example.com/builders#/task/727) (GDS-V3). Absorbs idea_inbox [#200](https://example.com/builders#/idea/200) ("discord builders channel role access auto managed by the example bot").
+**Companions:** [ADR 0032](0032-discord-mirror-of-gds.md) (Discord = one-way window into the GDS), [ADR 0033](<redacted>.md) (the bot is a service principal, never an authority), [ADR 0016](<redacted>.md) (the trust boundary), [ADR 0026 §6C](<redacted>.md) (the <redacted> write pattern this reuses).
+
+## Context
+
+The Example Discord has a fixed channel layout (PUBLIC: welcome, ship-news, agora, support; BUILDERS: ship-feed, ideas, red-team, planning, archon-only). Until now those channels were created and described by hand. Lars asked for two things:
+
+1. The bot should **create and edit channels itself** (topics, and which ranks may see each channel — the access question from idea [#200](https://example.com/builders#/idea/200)).
+2. **Lower ranks cannot command the bot.** Any *command* that makes the bot act must be **Archon-only**; the bot's **passive** features (ship-feed applause counting, #ideas inbound filing, rank role badges) stay open to everyone, as designed in ADR 0033.
+
+The risk this design must avoid is the one ADR 0016 closes: a Discord action becoming an authority. Channel layout is cosmetic, but "the bot edits the server on command" is still a command surface that must be gated where it is load-bearing — the server, against the live `builders.rank`.
+
+## Decision
+
+**1. The channel layout is a repo config file, not bot state.** `docs/discord/channels.json` is the single source of truth: each category/channel declares its `name`, `topic`, and `view` (who may see it — `everyone` or a rank name, where a rank grants that rank and every rank above it). Because changing channels means editing a repo file and merging it, and merging is itself rank-gated, the layout is **Archon-gated by construction**.
+
+**2. The bot reconciles one-way (config → Discord), best-effort, never destructive.** `src/bongos/discord-channels.js` matches existing channels by **slug** (emoji + separators stripped, lowercased — so `📯-ship-news` matches `ship-news`), edits topics + view-permissions **in place**, and creates anything missing. It **never deletes** a channel. This mirrors role-sync (ADR 0033 §4): read the repo, write Discord, no path back. View-permissions are applied as Discord permission overwrites for the `VIEW_CHANNEL` bit only — every other permission bit on a channel, and every unmanaged role's overwrite, is preserved.
+
+**3. The command surface is Archon-only, server-enforced.** `src/bongos/routes/discord.js` exposes `GET /api/gds/discord/channels/plan` (dry run) and `POST /api/gds/discord/channels/reconcile` (apply), both behind `requireBuilder` + `requireRank('archon')`. A Metic, Thetes, Xenos, or unauthenticated caller gets a 403. The CLI (`scripts/gds/discord-channels.js plan|apply`) is a thin wrapper over these routes, so the gate stays on the server — a builder editing local files cannot bypass it (ADR 0016).
+
+**4. The passive sweep is kill-switched, default OFF.** The bot also reconciles channels on connect + every 6h, but only when `DISCORD_CHANNELS_MANAGED=true` (mirrors `BFG_WRITE_ENABLED`, fail-closed). With the switch off, channels are touched **only** by an explicit Archon command. This stops the bot from surprise-editing a guild the moment it connects.
+
+**5. Passive engagement features are untouched.** Applause, #ideas inbound, and role badges remain open to all ranks. "Lower ranks can't use the bot" means **they can't command it**, not that they can't be served by it.
+
+## Access mapping (defaults — editable in the config)
+
+| Channel | view | Who sees it |
+|---|---|---|
+| welcome, ship-news, agora, support | `everyone` | all (players included) |
+| ship-feed | `everyone` | all — keeps the ADR 0033 §3 "anyone can applaud" rule true |
+| ideas | `everyone` | all — keeps inbound open; attribution still requires a link |
+| red-team | `metic` | Metic + Archon (matches `/builder-redteam`) |
+| planning | `metic` | Metic + Archon (matches the planning/priority skills) |
+| archon-only | `archon` | Archon only |
+
+These live in `channels.json` and are reviewed/changed by editing that file.
+
+## Consequences
+
+- **Trust boundary holds.** Channels are a cosmetic reflection of an Archon-reviewed file; the command that applies them re-checks live rank server-side. The bot never decides anything.
+- **Go-live prerequisite (human, browser).** The bot must hold Discord's **Manage Channels** permission and sit above the managed channels — same shape as the Manage Roles prereq in ADR 0033. Without it, reconcile ops 403 and are logged; the GDS is unaffected. Tracked as a blocker on [#727](https://example.com/builders#/task/727).
+- **Live verification deferred.** The pure planner is fully unit-tested (`tests/discord_channels.mjs`); real channel edits require the bot on + Manage Channels and are verified at go-live.
+
+## Alternatives considered
+
+- **Discord slash command (`/channel create`).** Rejected for now — a new in-Discord command surface to secure, when the repo config already gives an Archon-gated, reviewable, version-controlled source of truth.
+- **Pure Discord role permissions, no bot.** Rejected — it would make Discord roles the authority for "who can change channels," exactly the inversion ADR 0016 forbids; and it can't keep topics/structure honest.
+- **Bot writes with its own authority / no kill-switch.** Rejected — re-opens ADR 0016 and risks a connect-time surprise edit. The command gate + default-OFF passive sweep is the whole point.

package/docs/adr/0038-chromebook-ttyd-cloudflare-tunnel.md

@@ -0,0 +1,111 @@
+# ADR 0038 — Chromebook / browser on-ramp via a box-hosted ttyd web terminal over a Cloudflare Tunnel
+
+**Date:** 2026-06-06
+**Context:** GDS-V3, task [#760](https://example.com/builders#/task/760). Feeds done-when criterion **C1** (`a Metic onboards in ≤ 2h`) by restoring a *working* thin-device on-ramp. Companion to [ADR 0031](<redacted>.md) (the per-builder DigitalOcean box substrate), [ADR 0035](<redacted>.md) (the three onboarding paths), [ADR 0016](<redacted>.md) (server-enforced trust boundary — the web tier only *asks*, never holds infra power), and [ADR 0022](0022-secrets-policy.md) (no secrets in repo).
+**Status:** Accepted. **Supersedes the Remote-Control (path 3) approach** in [ADR 0035](<redacted>.md) Path 3 and [ADR 0031](<redacted>.md) §1 / §9.4 (the `claude rc` thin-device on-ramp). Implemented this session under [#760](https://example.com/builders#/task/760).
+
+> **Update (2026-06-07, [ADR 0040](<redacted>.md)):** the "Remote Control is unfixable" conclusion below was specific to running RC *headless, as a background service*. Once this ADR's ttyd web terminal put a real human at a real PTY, Remote Control works — started in-session with `/remote-control` (not the standalone `claude rc`). RC is now the **default** browser-only experience (shipped in [#807](https://example.com/builders#/task/807)); the ttyd terminal is its one-time launchpad. The blockers in *Problem* still hold for *headless* RC. See ADR 0040.
+**Track:** `internal` (dev-system / builder onboarding).
+
+## Problem
+
+A per-builder cloud dev box ([ADR 0031](<redacted>.md)) is reached two ways: Mac/Windows builders via Claude Desktop + SSH (works), and Chromebook / browser-only builders via — originally — Claude's **Remote Control** (`claude rc`) running as a headless systemd service (`infra/claude-rc.service`), with the box publishing a claude.ai pairing link UP to the GDS so the builder reaches it from a browser ([ADR 0031](<redacted>.md) §9.4, [#701](https://example.com/builders#/task/701)).
+
+Task [#745](https://example.com/builders#/task/745) leg-5 verification-tested that path on hardware and found it **broken end to end**. This session's research (June 2026, Claude Code CLI v2.1.x) confirmed it is **not** fixable by plumbing — there are three hard blockers, all on Anthropic's side and by design:
+
+1. **Trusted Devices is interactive-only.** "Trusted Devices for Remote Control" is an org/account policy that requires interactive `/login` device enrollment in a TTY. There is no headless / baked-credential / env-var enrollment path. Observed live: `claude rc` errors `Your organization requires Trusted Devices for Remote Control, but this device is not enrolled. Please run /login in Claude Code to enroll this device.`
+2. **`claude rc` needs a controlling TTY.** It requires a controlling TTY and only renders the pairing URL to a TTY. A systemd service has none, so the URL is never captured.
+3. **Remote Control needs full-scope subscription OAuth.** Every non-interactive auth path (`ANTHROPIC_API_KEY`, `claude setup-token` / `CLAUDE_CODE_OAUTH_TOKEN`, `apiKeyHelper`) is inference-only and is **explicitly excluded** from Remote Control.
+
+Net: a headless box can never bootstrap `claude rc`, and a no-SSH Chromebook builder cannot perform the interactive enrollment *on* the box either. Dead end.
+
+## Decision
+
+**Drop `claude rc` entirely. The box serves its OWN browser session: a `ttyd` web terminal, exposed through an outbound-only Cloudflare Tunnel, dropping the builder into a real interactive shell where they run NORMAL `claude`.**
+
+### 1. ttyd — a real browser-backed PTY on the box
+
+`ttyd` (a lightweight web-terminal daemon) binds to `127.0.0.1:7681`, basic-auth protected with a per-box generated password, and drops the builder into an interactive login shell in `/workspace`. The builder runs ordinary interactive `claude` inside it.
+
+This dissolves all three blockers because there is now a **real human at a real browser-backed PTY**. So `/login` (the OAuth flow opens in the builder's own browser tab), workspace-trust acceptance, **and** Trusted-Devices enrollment all just work — the exact interactive steps that are impossible headlessly.
+
+### 2. Exposure — an outbound-only Cloudflare Tunnel, $0 added cost
+
+A `cloudflared` Cloudflare Tunnel routes the builder's browser to the local ttyd. The box opens **no inbound port** — preserving the firewall posture that made `claude rc`'s outbound websocket attractive in the first place, but this one actually works. Two modes:
+
+- **(a) Quick tunnel (default).** A tokenless tunnel at a random `https://<id>.trycloudflare.com` that needs **zero operator secrets**.
+- **(b) Named tunnel (production upgrade).** A stable, branded hostname on `*.dev.example.com` when the operator configures a connector token — the documented production upgrade.
+
+Cloudflare Tunnel is free (Zero Trust free tier, 50 users) — **$0 added cost**.
+
+### 3. Delivery — reuse the existing trust-boundary-safe plumbing
+
+The box reports its current terminal URL + credential UP to the GDS (`POST /api/gds/box/terminal`, authenticated as the builder via the on-box GDS token); the builder reads them from the browser (`GET /api/gds/box/terminal`, own-resource only, `requireBuilder`). This is the same shape as the migration 070 / [#701](https://example.com/builders#/task/701) pairing path, renamed from the old `/box/pairing(-link)`. New DB columns `terminal_url` / `terminal_credential` / `terminal_at` (migration 073); the old `remote_pairing_*` columns are **deprecated in place**.
+
+### 4. Security model
+
+- **Localhost binding.** ttyd binds to `127.0.0.1` — only the tunnel reaches it.
+- **Basic auth.** HTTP basic auth with a per-box random password, stored mode-600 at `/etc/otb/terminal-credential` and persisted in the box snapshot across park/wake.
+- **Secret containment.** The credential is returned ONLY to the box's own builder via `GET /box/terminal`; it never appears on any public surface or in `box_events`.
+- **Revocation.** Rides the existing rank/status gate + box reconcile: a demoted/deactivated builder loses source access and the box is deprovisioned ([ADR 0031](<redacted>.md) §9.2).
+- **Defense in depth.** An unguessable tunnel URL **and** basic auth, both over HTTPS.
+
+## Consequences
+
+**Good:**
+- Works on any browser, including a literal Chromebook.
+- No new operator secret in the default (quick-tunnel) path.
+- No inbound ports — the box's egress-restricted firewall posture is preserved.
+- Reuses the existing GDS plumbing (intent queue + report-up/read-down), no new subsystem.
+- The builder gets the full real Claude Code TUI; `claude` auth/enrollment is a normal browser click rather than an impossible headless step.
+
+**Trade-offs / honest limits:**
+- **Quick-tunnel URLs are random and change on each `cloudflared` restart.** Handled — the box re-reports the URL each boot, the same ephemeral-URL-per-boot shape the old claude-rc reporter used.
+- **`trycloudflare.com` is positioned for testing, not production SLA** — hence the named-tunnel upgrade for scale.
+- **The per-box basic-auth password is long-lived** (until box rebuild) rather than single-use.
+- **ttyd adds a tiny always-on service** on the box.
+
+**Files:**
+- Added: `infra/box-terminal.service` (ttyd unit), `infra/cloudflared.service` + `infra/cloudflared-run.sh` (tunnel, both modes), `infra/box-report-terminal.sh` (reporter), cloud-init install + wiring, migration 073, `src/bongos/boxes.js` `setTerminalAccess`, `src/bongos/routes/box.js` `GET/POST /box/terminal`.
+- Deleted: `infra/claude-rc.service`, `infra/get-pairing-link.sh`, `infra/box-report-pairing.sh`.
+
+**Follow-up:**
+- **Named-tunnel automation — DONE ([#771](https://example.com/builders#/task/771)).** The control plane creates the per-builder named tunnel + proxied DNS CNAME (`term-<login>.example.com → <id>.cfargotunnel.com`) via the Cloudflare API token and bakes `BOX_TUNNEL_TOKEN` + `BOX_TERMINAL_HOSTNAME` into the box's `/etc/otb/box.env` on `provision`, tearing both down on `deprovision`. OPT-IN (`BOX_NAMED_TUNNEL=1`, default OFF → quick tunnel). Client: `src/bongos/cf-tunnel.js` (mirrors `do-api.js` — injectable fetch, dry-run default, **forces IPv4** since the CF token is IP-locked); orchestration in `scripts/gds/box.js`. See the recipe's "Named-tunnel automation" section.
+- **Hardware-verified live ([#771](https://example.com/builders#/task/771)).** Provisioned a real box: tunnel create + ingress + CNAME + token-bake + teardown all confirmed against the live Cloudflare account; `https://term-example-owner.example.com` served ttyd through the tunnel (401 without creds, 200 with). The walk surfaced three fixes now landed: **(a)** IPv4-pinning in `cf-tunnel.js`; **(b)** the apex-not-`dev.*` hostname default — free Universal SSL covers `*.example.com` (one label) but not a two-label `dev.*` host, which fails TLS at the edge; **(c)** masking the Ubuntu `ttyd` apt package's own auto-started, **credential-less** `ttyd.service` (it grabbed port 7681 → our unit crash-looped *and* an auth-less terminal would have been exposed through the tunnel).
+- **⚠ OPEN — browser-only bootstrap gap.** The terminal units live in the repo, so they only start after `box-source-fetch` clones, which needs the builder's GDS token on the box. A pure browser-only builder has no first-boot way to place that token → terminal never comes up for them (works once a token is seeded via SSH/operator). Fix: bring ttyd up at first boot independent of the clone (cloud-init writes the unit inline). Tracked as a follow-up.
+
+---
+
+## Spike findings (2026-06-28, task 852)
+
+**The spike question:** *"the browser-terminal can't run interactive `claude` because Ink (Claude Code's TUI) needs a raw-mode TTY that ttyd's pipe can't provide."*
+
+**Verdict: the premise is false. ttyd is NOT a pipe — it is a real PTY, and interactive `claude` (the Ink TUI, including raw mode) runs in it. This is the path we shipped and run in production today.** The "can't run interactive claude" symptoms that motivated this spike were real, but they were misdiagnosed: every one of them traced to something *other* than raw-mode capability, and each already has a landed fix. Below is the root-cause walk so this doesn't get re-investigated.
+
+### Root cause — why "Ink needs raw-mode, ttyd can't provide it" is wrong
+
+`ttyd` does not pipe stdio. For each browser connection it allocates a **real kernel pseudo-terminal** via `forkpty()` and runs the login shell as the PTY's session leader. A kernel PTY is exactly the device on which `termios` raw mode (`cfmakeraw` / `ECHO`/`ICANON` cleared) is defined — it is the *same* mechanism a local `xterm` or `ssh` session uses. The browser side (xterm.js over a websocket) is the *display*; the program on the box still talks to a genuine `/dev/pts/N`. So:
+
+- `isatty(0/1) === true` inside the ttyd shell, and a program that calls `tcsetattr` to enter raw mode succeeds.
+- Ink (which puts the terminal in raw mode for keypress-by-keypress input) therefore works — there is nothing about ttyd's transport that prevents it.
+
+A genuine pipe (`cmd | claude`, or a `systemd` service with no controlling terminal) is the case where raw mode fails — `ENOTTY`, no `tcsetattr`. **That is the headless `claude rc` case ADR 0038 originally killed, not the ttyd case.** The spike title conflated the two: the *headless service* had no PTY; the *ttyd terminal a human sits at* has a full one. ADR 0040 already recorded the live confirmation that plain interactive `claude` runs in the ttyd terminal on the prod box.
+
+### What actually broke "interactive claude in the browser terminal" — and the real fixes (all landed)
+
+The symptoms people read as "the TUI won't run / freezes / refuses to start" were these, none of them raw-mode:
+
+1. **`claude` refused to start as root (looked like "TUI won't launch").** The box's `defaultMode=bypassPermissions` (task 1251) makes Claude Code refuse to run as root unless `IS_SANDBOX=1`. The droplet *is* an isolated sandbox. **Fix (task 1314):** `Environment=IS_SANDBOX=1` pinned for the whole ttyd process tree in `infra/box-terminal.service`.
+2. **The TUI froze mid-session (looked like "raw-mode input is dead").** Claude Code's own startup `git` (and any git a hook spawns) hits the token-less `https://github.com` origin of the rank-gated `/workspace` clone, and `git` opens `/dev/tty` for a `Username for 'https://github.com':` prompt *even with stdin redirected* — grabbing the ttyd PTY and hanging the Ink UI until killed. **Fix (task 854):** `Environment=GIT_TERMINAL_PROMPT=0` for the ttyd tree, so the remote-touching git fails fast instead of prompting (credentialed paths — `box-source-fetch`, ship — are unaffected).
+3. **`/remote-control` (the next step after a working TUI) reported "Workspace not trusted."** This is the *standalone* `claude rc` shell command's trust mis-check ([anthropics/claude-code#35817](https://github.com/anthropics/claude-code/issues/35817)), not a ttyd or raw-mode problem. **Fix (ADR 0040):** start Remote Control with the in-session **`/remote-control` slash command** from inside an already-trusted `claude`, never the standalone `claude rc`.
+4. **Session died when the tab closed (looked like an unstable terminal).** ttyd SIGHUPs its child on disconnect, killing a bare login shell + its `claude`. **Fix (task 893):** the launcher wraps the shell in a `tmux new-session -A` "otb" session, so a disconnect only detaches the client; the running `claude` survives on the box and the next connect reattaches.
+
+### What was tried / ruled out
+
+- **Ruled out: "ttyd transport can't carry raw mode."** Contradicted by the PTY mechanism above and by the live prod runs recorded in ADR 0040 and codified in `infra/box-terminal.service` (which the box has run in production through park/wake cycles). No raw-mode-specific failure was ever reproduced once the four issues above were fixed.
+- **Ruled out: switching terminal daemons (gotty / wetty / xterm.js-over-a-different-ws).** They all use the same `forkpty()` PTY model; swapping would not change raw-mode behaviour and would throw away the credential-race / tmux-persistence / first-boot hardening already baked into the ttyd unit. No reason to migrate.
+- **Confirmed working path:** ttyd → real PTY → `tmux` "otb" → `claude` (auto-launched by `otb-box-launch`) → interactive Ink TUI → `/remote-control` to hand off to the Claude web/mobile app (ADR 0040). This is the shipped browser-only on-ramp.
+
+### Recommended next step
+
+**No infra change. Accept and document that interactive `claude` works in the ttyd terminal — the "raw-mode" framing of task 852 is closed as a misdiagnosis.** The four real issues are already fixed in `infra/box-terminal.service` and ADR 0040; this section is the durable record so the false "Ink needs a raw-mode TTY ttyd can't provide" hypothesis is not re-opened. The only genuinely open terminal item remains the **browser-only bootstrap gap** noted just above (ttyd coming up before the GDS token is on the box), which is independent of raw mode and tracked separately.

package/docs/adr/0039-setup-first-onboarding-ux.md

@@ -0,0 +1,49 @@
+# ADR 0039 — Setup-first onboarding UX: two-config selector + action-only Path checklist
+
+**Date:** 2026-06-06
+**Context:** GDS-V3, task [#777](https://example.com/builders#/task/777). Feeds done-when criterion **C1** (`a newcomer onboards in ≤ 2h`). Builds on [ADR 0035](<redacted>.md) (three onboarding paths), [ADR 0038](<redacted>.md) (the box-hosted ttyd browser terminal, now hardware-verified under [#771](https://example.com/builders#/task/771)), [ADR 0033](<redacted>.md) (the Discord OAuth account-link + auto-join), and [ADR 0034](<redacted>.md)/[#692](https://example.com/builders#/task/692) (the 3-ship xenos→thetes promotion).
+**Status:** Accepted. Implemented this session under [#777](https://example.com/builders#/task/777).
+**Track:** `internal` (dev-system / builder onboarding).
+
+## Problem
+
+The builders'-hall onboarding (the "Welcome to the Hall" panel + the "Path into the City" checklist) had two faults for a **zero-technical** newcomer who **won't read paragraphs**:
+
+1. **Setup and milestones were tangled.** The welcome panel mixed *how to get a working environment* (install Claude Code, clone the repo, run `/builder-setup`) with *what to do next*, in dense prose. It also still told newcomers to clone a repo locally — but post-[ADR 0035](<redacted>.md) a Xenos is **box-only** and never clones anything to their own machine.
+2. **The first checklist step was redundant.** "Bear the city's seal" (GitHub sign-in) is already done — a builder signed in with GitHub to even see the page.
+
+## Decision
+
+**Show ONLY setup first, as a two-config selector; then a short, action-only orientation checklist.**
+
+### 1. Setup screen — pick how you connect to your dev box
+
+Both configs reach the SAME hosted dev box (Xenos are box-only, [ADR 0035](<redacted>.md)); the choice is only the *client*:
+
+- **Claude Desktop app (recommended)** — install the desktop app, open it on an empty folder, then paste a single instruction telling Claude to **read the hosted connect guide** (`GET /api/gds/box/connect`) and follow it. That guide (already served, public, no secrets) runs the OS-appropriate `box-connect` bootstrap (device-flow GitHub sign-in + SSH key + Desktop connection file). Then connect via *Code → Environment → "Example Dev Box"*.
+- **Claude Online (browser only)** — no install; the hall **delivers the box terminal automatically**: one "Set up my dev box" button calls `POST /box/ensure` (auto-provision/wake; [#701](https://example.com/builders#/task/701)) and polls `GET /box/terminal`, then shows the ttyd URL + password ([ADR 0038](<redacted>.md)) right in the panel. Open it and type `claude`. No SSH, no `#support` relay.
+
+**Why the hosted guide (not "type a `/builder-*` command"):** a brand-new builder has no repo and therefore none of the project's `/builder-*` skills locally. Pointing Claude at the public guide URL is self-contained — Claude fetches it and runs the bootstrap with nothing pre-installed. The bootstrap self-authenticates via device flow, so it does **not** require `/builder-setup` first.
+
+Steps are short, scannable, and plain-spoken (the Mediterranean theme stays in the headings). The repo-clone walkthrough — and the `/public/repo-info` fetch that fed it — is removed from the newcomer panel. Getting the box itself is requested in Discord `#support` (an Archon provisions it — the [ADR 0035](<redacted>.md) §2 first-box cost gate).
+
+### 2. "The Path into the City" — orientation, action-only, all auto-detected
+
+Four displayed steps: **Join the Discord server** → **Choose thy craft** → **Run `/builder-setup`** → **Ship three works — and rise to Thetes**. The redundant GitHub-sign-in step is dropped from display, as are `first_start`/`first_claim` (implied by shipping). **Every step auto-detects — no manual ticking** ("the city watches"):
+
+- **join_discord** clears when the builder links Discord. The button runs the **existing** OAuth flow (`GET /api/gds/auth/discord/start`, [ADR 0033](<redacted>.md)) — same control as `/builders/settings` — which auto-joins the guild + assigns the rank role; `discord.linked` then reads true. No new Discord backend.
+- **cli_setup** clears once the builder has authenticated the GDS CLI — i.e. run `/builder-setup` (or the box-connect bootstrap); both mint a `source='cli'` session. Detected via `db.hasCliSession` (an `EXISTS` over `builder_sessions`); no manual mark.
+- **pick_disciplines** / **ship_three** are the existing engine-backed steps (craft picker; 3-ship counter).
+
+### 3. Display layer split from the graduation engine
+
+The displayed list is a **read-only view** computed by `shapeForApi(state, { shipCount, discordLinked, cliAuthed })` — it does NOT change the onboarding state machine. The engine `STAGES` array (`auth_complete`…`ship_three`) is untouched, so graduation — and therefore the 3-ship xenos→thetes promotion ([#692](https://example.com/builders#/task/692)) and the graduation broadcast — stays driven **solely by ship-count**, independent of the displayed steps. `join_discord`/`cli_setup` are derived from live signals already available server-side (`discord.linked`, a `source='cli'` session) — **no new column, no migration, no write endpoint**.
+
+## Consequences
+
+- A newcomer sees setup first, picks a config, follows 3–4 plain steps to a working `claude` session, then a 4-step orientation path that ticks itself as they go.
+- No new tables/columns/endpoints: both new steps are pure derivations in `GET /api/gds/me` (and the `PATCH /me/disciplines` echo). `db.hasCliSession(builderId)` is the only new helper.
+- **The only thing that gates the rank-up is shipping three works.** The orientation steps are informational; a builder is never blocked by them.
+- Connect is bootstrapped from the **hosted `GET /api/gds/box/connect` guide** so a builder with no local repo/skills can still onboard (Claude fetches + runs it).
+- **Config B self-serves the terminal in the hall** (`POST /box/ensure` → poll `GET /box/terminal` → show URL + password) — the `#support` relay is gone. A newcomer's first box still waits for a quick Archon approval (ADR 0035 §2 cost gate), surfaced as a "waiting for approval" state. The remaining hardware dependency ([#774](https://example.com/builders#/task/774)) is the box's terminal reporter publishing its URL on a bare first boot; once it does, the hall shows it automatically.
+- The "Join the Discord" button is suppressed when Discord OAuth isn't configured server-side (`discord.configured` false).