@bongos/core 1.19.882 → 1.19.883

package/docs/recipes/work-on-a-task-from-your-dev-box.md

@@ -1,122 +0,0 @@
-# Work on a task from your dev box
-
-> Your dev box serves your **rank scope**: Metic+ boxes carry the **whole repo**;
-> newcomer (starter) boxes carry the safe starter surface. Task-scoped slices are
-> **paused** per [ADR 0193](../adr/0193-pause-task-scoped-box-slices.md) (the
-> machinery from [ADR 0148](../adr/0148-task-scoped-box-source-access.md) remains;
-> `BOX_TASK_SCOPE=on` re-enables it). Your GitHub token never leaves the server —
-> see "How git works on a box" below, and
-> [ADR 0150](../adr/0150-box-first-boot-bringup-vendored-instances.md) for how the
-> box comes up.
-
-## TL;DR
-
-In your dev box's terminal:
-
-```bash
-/builder-start          # see what you can claim
-/builder-claim <N>      # claim task N (locks it to your session)
-/builder-sync           # pull the latest main onto the box right now
-# …work in /workspace…
-/builder-ship           # smoke + review, then land + deploy — awards credits
-```
-
-That's the whole loop. `/builder-sync` pulls fresh code within seconds instead of
-waiting for the box's ~10-minute refresh.
-
-## How git works on a box — read this BEFORE diagnosing "stuck"
-
-The box holds **no stored git credential, ever** — and that is the design, not a
-fault ([ADR 0055](../adr/0055-server-mediated-branch-publish.md)):
-
-- **Reads are server-mediated, per request.** Every remote git operation goes
-  through `/usr/local/bin/otb-git-credential`, which asks the control plane
-  (`GET /box/source-access`) for a **short-lived, read-only** credential. The
-  server checks your **live** rank + status on every single request — demotion or
-  deactivation cuts off the next fetch instantly.
-- **`git push` always fails with 403 here — by design.** The read credential
-  cannot write. Landing code is the server's job: `/builder-ship` uploads your
-  work, opens the PR, and lands it. Never try to fix the 403 by embedding a
-  token or editing git config.
-- **Source refreshes from `main` every ~10 minutes** (the `box-source-fetch`
-  cron; log at `/tmp/box-source-fetch.log`). `/builder-sync` runs the same fetch
-  on demand.
-- **If a remote git op says `could not read Username`, or the sync log shows
-  401:** the box's Bongos session expired. Run `/builder-reauth`, then
-  `/builder-sync`. That is the whole fix.
-
-The box writes these same facts to `/workspace/CLAUDE.local.md` on every sync, so
-a Claude session on the box loads them automatically (the file is gitignored and
-box-written — don't edit it).
-
-## The model — what's on your box
-
-- **Metic and above:** the full repo in `/workspace` — same tree as a laptop
-  clone, refreshed from `main` by the sync cron.
-- **Below Metic (starter):** the starter surface — methodology (`CLAUDE.md`,
-  `.claude/`), build tooling (`scripts/`, `src/bongos/`), `docs/`, `infra/`,
-  `tests/`, and the sandbox-runnable product code. Rank, checked live by the
-  server, is what bounds a box — not the task you claimed
-  ([ADR 0193](../adr/0193-pause-task-scoped-box-slices.md)).
-
-## Step by step
-
-### 1. Connect to your box
-
-If you haven't yet, run **`/builder-connect`** (or follow the
-[dev-box lifecycle recipe](builder-box-lifecycle.md)) to raise and connect to your
-box, then **`/builder-setup`** once on the box to sign the Bongos CLI in. The browser
-terminal drops you into `/workspace` — the one working folder.
-
-> **`bongos shell` / `bongos code` sync on connect (BV1.R101).** Connecting with
-> either verb runs the source fetch for you first, so you land in `/workspace`
-> already fresh. (The browser terminal drops you straight into `/workspace`; run
-> `/builder-sync` there if you want the latest immediately.)
-
-### 2. See what you can claim — `/builder-start`
-
-Lists the tasks that are `ready` and parallel-safe against everyone else's active
-claims. Pick one.
-
-### 3. Claim it — `/builder-claim <N>`
-
-Locks task N to your session so no parallel session collides with your work.
-
-### 4. Freshen the code — `/builder-sync`
-
-Re-runs the box's source fetch immediately so `/workspace` is on the current
-`main` before you branch. (The ~10-minute cron does this on its own as a
-backstop.) Off a box there's nothing to sync — your source is your local
-checkout — and the command tells you so.
-
-### 5. Work — in `/workspace`
-
-One folder, always. When you switch tasks, keep working in place.
-
-### 6. Ship — `/builder-ship`
-
-Runs the smoke tests and the review gate, then lands + deploys and awards credits.
-
-## Switching tasks
-
-One box, one working folder, one active claim at a time (the server enforces
-one-claim-per-session). To move to a different task:
-
-1. `/builder-ship` (or `/builder-release`) the current claim.
-2. `/builder-claim <M>` the new one — and keep working in `/workspace`.
-
-## Notes + gotchas
-
-- **`tests/` is on every box** — a starter box can run the suite for the code it
-  holds (tests live in the top-level `tests/`, not inside `modules/<key>/`).
-- **Idle boxes park, they don't die.** After ~2 hours of no activity the box is
-  **parked**: a snapshot is kept and the droplet is destroyed, so compute billing
-  stops and a wake restores your filesystem. Only weeks of staying parked lead to
-  reclaim (with a warning first). Still: **ship or commit before you step away** —
-  a snapshot is a safety net, not a workflow.
-- **`/builder-sync` is idempotent** — safe to re-run; it just does, on demand, what
-  the cron does on its schedule.
-- **A fresh box comes up with the code already cloned.** If a box ever comes up
-  *bare* (no code, no terminal), that's the packaging bug
-  [ADR 0150](../adr/0150-box-first-boot-bringup-vendored-instances.md) fixed on the
-  control plane — flag it rather than working around it.