onboarding phase 2: author the context/ operator tree

Add the context/ tree (main2) — the garden's on-demand operations manual for
agents, per designs/streamlined-onboarding.md §§ 3, 3.1, 3.2, 4. Twelve files:
a routing top README, first-run/ (the guided tutorial track: README with the
ordered stage list + interaction norms, plus identity/auth/first-job leaves)
and operations/ (day-2 routing README plus starting/leader-follower/scaling/
deploy/schedules/health leaves). Each leaf opens with an exit-criterion
abstract; content migrated from README.md and CLAUDE.md §§ Job system / Host
environment per § 4 (sources left intact — phase 4 trims them).

Amend skills/context-library/SKILL.md's scope line to declare it canonical for
context/ on main2 as a second canonical tree (same discipline, different
branch), rather than forking the discipline.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: endolinbot

context/README.md

@@ -0,0 +1,42 @@
+# context/ — the garden's operations manual for agents
+
+This tree is the garden's **operator procedure for agents**, read on demand by
+the liaison — never auto-loaded. It answers two questions: how do I walk a
+brand-new user through their first run (`help`), and how do I operate a running
+instance day to day (`help <topic>`). It ships with the code on `main2`, so the
+procedure and the scripts it drives version together. If your query is "what
+command does X" or "walk the user through Y," it is here or one hop away; if it
+is "why is the machinery shaped this way," that is `designs/`, and this tree
+routes you there rather than repeating it.
+
+What this tree does **not** hold: per-instance state or history (that is the
+journal, `journal2`); architectural rationale (that is `designs/`); imported
+material (that is `references/`); and procedures already encoded as skills —
+where a skill owns a procedure (restore, schedule, job-board), the page here
+**routes to it** and adds only the operator's framing. See
+`skills/context-library/SKILL.md` for the authoring discipline this tree obeys,
+and `designs/streamlined-onboarding.md` for why it exists.
+
+## Children
+
+- **[first-run/](first-run/README.md)** — the guided first-run tutorial the
+  liaison drives when a user says **help** on a not-yet-armed instance: an
+  ordered, conversational stage list (welcome → identity → bot credentials →
+  starting the garden → first job → where next) plus the interaction norms that
+  bind the liaison driving it. Read here to run the tour or to answer a
+  first-run question (identity, auth, posting a first job).
+
+- **[operations/](operations/README.md)** — day-2 procedure, picked by symptom
+  or intent: starting the garden at command level, leader/follower on multiple
+  hosts, scaling the pool, the deliberate deploy, schedules, and health. Read
+  here to *do* an operation on a running instance, or to answer `help <topic>`
+  for an operator.
+
+## Convention
+
+Cross-references **within** this tree are relative (`first-run/identity.md`,
+`../operations/starting.md`). Cross-references to **other** trees — skills,
+designs, roles, the top-level READMEs — are repo-root paths
+(`skills/restore/SKILL.md`, `designs/multibot-leader-follower.md`). A new
+operational topic lands as a new leaf with a row in the nearest directory
+README; split a directory only when its README stops routing cleanly.

context/first-run/README.md

@@ -0,0 +1,78 @@
+# first-run/ — the guided first-run tutorial
+
+The ordered, conversational track the liaison drives when a user says **help**
+on a not-yet-armed instance. This README **is** the tutorial script: it lists
+the stages in run order with a one-line abstract each, and it carries the
+**interaction norms** that bind the liaison driving it. There is deliberately no
+separate tutorial script to drift from — this ordered tree is the single source
+of truth, and each stage page is read just-in-time as the liaison reaches it.
+Read here to run the tour, to resume a half-finished one, or to answer a
+first-run question. Day-2 operation of a running instance is a sibling tree,
+`../operations/README.md`.
+
+Bare **help** starts at stage 1 and walks through. **start the garden** jumps
+straight to stage 4 (the user who wants motion, not a tour). On an
+**already-armed** instance, bare `help` skips the walk and degenerates to a
+status summary (units, board counts, leadership, drain state) plus the
+`help <topic>` menu — the stage pages double as the topic answers, so nothing
+is written twice.
+
+## Interaction norms (binding on the liaison driving the track)
+
+- **Ask before acting, act on approval.** Every mutating step is proposed in one
+  sentence with the exact command shown, then run **by the liaison itself** on a
+  yes — never printed for the human to copy. Read-only checks (probes, status
+  reads) run freely without asking.
+- **Verify after each stage** — a unit list, a `gh auth status`, a board read —
+  and show the one-line result, so trust accumulates stage by stage.
+- **Resumable and idempotent.** Every stage begins with its own probe and skips
+  cleanly when already done, so `help` after a half-finished first run continues
+  where it left off, and `help` on a healthy instance degenerates to the status
+  summary.
+- **Escalate, don't improvise, on policy.** Stages that touch permissioned
+  surfaces (watch-set widening, the ferry, identity switches) are *described*
+  but never *performed* in the tutorial; route to the maintainer-authorization
+  paths that govern them rather than acting.
+
+## The stages
+
+1. **Welcome.** One paragraph on what the garden is and what the tutorial will
+   do, ending with "shall we?". No page — it is this framing.
+
+2. **Identity → [identity.md](identity.md).** Confirm we are in-container (the
+   guard already ran), read `.garden`, and ask the one question only the human
+   can answer: is this name unique among your running instances? On a collision,
+   offer the rename and run it on approval.
+
+3. **Bot credentials → [auth.md](auth.md).** Probe `gh auth status` and `.ssh/`.
+   For missing pieces: generate the bot ssh key, print the public half and wait
+   while the human adds it to the **bot** account, run `gh auth login` and relay
+   the device code. Verify by whoami-ing the `gh` wrapper.
+
+4. **Starting the garden → [first-job.md](first-job.md) for the board, and the
+   command-level substance in `../operations/starting.md`.** The conversational
+   pivot: on **start the garden** the liaison performs the whole bring-up itself
+   — linger, install and enable units, size the pool, designate the leader on a
+   first host, arm its own Monitors, offer the optional armings — asking before
+   each consequential step and verifying after. The commands live in
+   `../operations/starting.md` (agent-facing detail the liaison executes on
+   demand), deliberately **not** here: this stage stays a conversation.
+
+5. **First job → [first-job.md](first-job.md).** Offer to post a small real job,
+   watch it cross `todo/ → doin/ → tada/`, and read the report back — teaching
+   the board's shape and the core verbs.
+
+6. **Where to go next.** Point at `help <topic>` (the `../operations/` tree),
+   the control surfaces, and the README's conceptual §§ 2–3 for the architecture
+   tour. No page — it is this handoff.
+
+## Children (stage pages)
+
+- **[identity.md](identity.md)** — the `GARDEN` shard identity: the `.garden`
+  file as the one naming knob, the `GARDEN=… ./garden` convenience form, the
+  uniqueness requirement, and the rename / parallel-pool moves.
+- **[auth.md](auth.md)** — the three credentials (claude login or API key, bot
+  ssh key, bot gh token): probes, the liaison-run halves, the human-only browser
+  clicks, and the conservative non-bypass launch variant.
+- **[first-job.md](first-job.md)** — posting a first job, the board's states,
+  and the core verbs with pointers to the vocabulary table.

context/first-run/auth.md

@@ -0,0 +1,75 @@
+# The three credentials
+
+A fresh clone holds no credentials. A working instance needs exactly three, and
+each has a **liaison-run half** and an irreducible **human-only click**: the
+**claude** login (or an API key), the **bot ssh key**, and the **bot gh token**.
+This page is the probes, the halves, and the human moments — plus the
+conservative non-bypass launch variant for a user who wants per-command prompts.
+All three credentials land in the bind-mounted home and persist across
+`./garden reset`. If your question is "how does the bot authenticate" or "why is
+`gh` acting as the wrong identity," you are here; the ferry's separate,
+maintainer-only human-identity path is `README.md` § The ferry and
+`roles/boatman/AGENT.md`.
+
+## 1. Claude auth — inside golden-path step 2, zero extra steps
+
+The exec'd `claude` runs its own first-launch onboarding: pick a login method,
+open the printed URL **in a browser on the host** (the container has none),
+paste the code back. The credential lands in the bind-mounted home.
+
+- **Beaten path:** a **Claude subscription login** — the whole fleet runs on one
+  subscription.
+- **Alternate path:** export `ANTHROPIC_API_KEY` **before the first
+  `./garden`**; the launcher forwards it at container creation and the login is
+  skipped entirely.
+
+Neither is a procedure the human runs by hand — the tool prompts for it. It is
+one sentence of residue: "have a Claude subscription or an API key."
+
+## 2. Bot ssh key — liaison generates, human pastes
+
+The launcher deliberately does **not** forward your SSH agent: an
+agent-forwarded human identity must not leak into bot actions. The bot uses its
+own key under `<garden-root>/.ssh/` (which is `~/.ssh/` inside the container,
+gitignored). The liaison's half:
+
+1. Probe `.ssh/` for an existing `id_ed25519`.
+2. If absent, generate one and **print the public half**.
+3. **Wait** while the human pastes it into the **bot** GitHub account's SSH keys
+   — the human-only click.
+
+## 3. Bot gh token — liaison runs login, human authorizes
+
+Inside the container, authenticate `gh` as the **bot**:
+
+1. Probe `gh auth status`.
+2. If unauthenticated, run `gh auth login` and **relay the device-flow URL and
+   code** to the human, who opens it and clicks "authorize" — the human-only
+   click. The token lands in `.config/gh/` (bind-mounted, gitignored).
+3. **Verify** by whoami-ing the fleet's `gh` wrapper — it must report the bot
+   login, not your identity. The wrapper pins every call to the bot; the one
+   exception is the ferry's explicit `GARDEN_GH_IDENTITY=kriskowal` override
+   (`designs/fleet-gh-identity.md`).
+
+## The conservative non-bypass launch variant
+
+Bare `./garden` execs the liaison with `--dangerously-skip-permissions` (auto
+mode) — matching the fleet's existing headless posture and making the tutorial
+usable (prompt-per-command would turn the tour into dozens of nags). The
+interactive liaison still **asks before consequential garden operations** per
+the tutorial's ask-before-acting contract (`README.md` in this tree, §
+Interaction norms).
+
+A user who wants per-command prompts instead of bypass can launch conservatively
+via the debug shell:
+
+```sh
+./garden sh                                    # today's enter behavior: bash -l, no claude
+claude --permission-mode acceptEdits           # prompt on non-edit actions
+```
+
+Optionally seed a `scripts/jobs/*` allowlist so the routine board commands stop
+prompting. This variant is documented, **not defaulted** — auto mode is the
+default (`designs/streamlined-onboarding.md` § 1.3). Claude Code's own one-time
+bypass acknowledgment (a single keystroke on first launch) stays as the explicit
+opt-in moment.

context/first-run/first-job.md

@@ -0,0 +1,63 @@
+# Posting a first job
+
+The last teaching stage: post one small real job, watch it cross the board's
+three states, and read the report back — so the user sees the whole
+producer→board→worker→report loop once, concretely. This page is how the liaison
+posts that first job, what the board states mean, and the core verbs that turn a
+sentence of intent into a job. If your question is "how does work reach a
+worker" or "what does the board look like," you are here; the full job-board
+mechanics (the git-push claim CAS, the per-doer worktrees) are
+`skills/job-board/SKILL.md`, and the complete verb list is `README.md` § Key
+vocabulary and `CLAUDE.md` § Orchestrator vocabulary.
+
+## Posting the job
+
+The liaison never does the substance itself — it **posts a job to the board**,
+and a gardener claims it. The primitive:
+
+```sh
+scripts/jobs/post-job.sh <basename> [body]
+```
+
+`<basename>` is a short deterministic name derived from the change identity; the
+body names the repo, any PR/comment URL, and the task in a sentence or two. For
+the tutorial, a tiny self-contained job (a trivial garden-library edit, or a
+"say hello and report" job) is enough to demonstrate the loop without waiting on
+CI. Post it, then watch.
+
+## The three board states
+
+Every job is a file that moves through three directories on the `journal2`
+branch:
+
+- **`todo/`** — posted, unclaimed. Any eligible gardener may race to claim it.
+- **`doin/`** — claimed. The accepted `git push` to `origin/journal2` is the
+  compare-and-swap that serializes the claim: first pusher wins, the rest back
+  off to another job. The worker runs it in an isolated per-job worktree.
+- **`tada/`** — done. The worker's completion report lands here; the follow-up
+  service reads each report's `## Follow-ups` section and turns actionable ones
+  into new jobs, so the board feeds itself.
+
+Watch a job cross `todo/ → doin/ → tada/`, then read the report back to the
+user. That is the entire life of an issue in miniature (`README.md` § The life
+of an issue).
+
+## The core verbs
+
+The user steers in plain language — a sentence of intent becomes a job — but
+these verbs are precise shorthand, and the PR-comment watchers recognize the
+branch-op ones deterministically:
+
+- **design X** / propose X / spec X — draft a design, open it as a DRAFT PR.
+- **build #N** / build X — implement an approved design.
+- **run the gauntlet #N** — the full PR chain: clean → panel review → fix-loop →
+  un-draft.
+- **fix #N**, **rebase #N**, **weave #N**, **shepherd #N**, **merge #N** — the
+  branch-op verbs that unstick and advance a PR.
+- **defer X** / park X, **promote X** / go ahead — steer the plan queue.
+- **ferry #N** — carry approved work upstream under the maintainer's identity;
+  authorization required.
+
+The authoritative tables (with what each does and which are watcher-recognized)
+are `README.md` § Key vocabulary and `CLAUDE.md` § Orchestrator vocabulary —
+point the user there rather than reproducing the full list.

context/first-run/identity.md

@@ -0,0 +1,76 @@
+# The GARDEN shard identity
+
+Every garden instance has one logical name — its **`GARDEN` shard identity** —
+and it **must be unique across every running instance you own**. It keys job
+claims, per-host worker counts (`hosts/<host>`), journal index entries, and the
+leader marker; two instances sharing a name silently corrupt each other's
+per-host state. This page is the naming knob and the uniqueness discipline: the
+`.garden` file as the one place the name lives, `GARDEN=… ./garden` as sugar
+over it, why an exported env var does not reach the fleet, and the rename /
+parallel-pool moves. If your question is "how do I name this instance" or "these
+two instances are stepping on each other," you are in the right place; the
+multi-host leader/follower mechanics that the marker gates are
+`../operations/leader-follower.md`.
+
+## The one naming knob: `.garden`
+
+The streamlined, preferred way to name an instance is one line **before the
+first `./garden`**:
+
+```sh
+echo petunias > .garden
+```
+
+The launcher reads `.garden` when present and derives the container name and
+`--hostname` from it. Bare `./garden` needs **no environment variables** — every
+default is satisfactory, and an unnamed instance falls back to the container
+hostname. You only name an instance when you run **more than one**.
+
+The convenience form does the same thing through an env var:
+
+```sh
+GARDEN=petunias ./garden
+```
+
+This sets the container hostname **and** writes `.garden`, so the container is
+built and named from that identity either way. The env var is **sugar over the
+file**, and the file is the documented default. `GARDEN_CONTAINER` /
+`GARDEN_HOSTNAME` remain as expert overrides; `GARDEN_SHARD` is a deprecated
+alias for `GARDEN` for one release.
+
+## How the fleet resolves the identity
+
+Every fleet script resolves `GARDEN` as: **`GARDEN` env → the gitignored
+`.garden` file → `hostname -s`** (`common.sh`). The durable file exists because
+an **exported `GARDEN` does not reach the systemd `--user` units** — they are
+started by the user manager, not your shell, so they read the file, not your
+environment. That is the whole reason the name is written to disk rather than
+left in the environment: set it at container-creation time so it lands in
+`.garden`, and every unit sees it.
+
+## The uniqueness check (the human's one answer)
+
+The kernel hostname cannot be changed from inside a container (its capabilities
+are zero), so the logical name is **fixed at container creation** via
+`--hostname`/`--name` (both `GARDEN_CONTAINER`). During the tutorial the liaison
+reads `.garden` and asks the single question only the human can answer: **"is
+this name unique among your running garden instances?"** A default or a
+collision is the only thing that needs fixing here.
+
+## Rename, and the parallel-pool move
+
+To **rename** an existing instance, reset and re-create it under the new name:
+
+```sh
+./garden reset
+echo <unique-name> > .garden   # or: GARDEN=<unique-name> ./garden
+./garden
+```
+
+For a **lighter, per-invocation** identity — a second follower pool on the same
+machine, launched from a checked-out worktree with no Dockerfile change — just
+export `GARDEN=<unique>` for that invocation. Set `GARDEN` at creation only when
+a pool's identity must differ from its hostname.
+
+Rationale for the container/hostname coupling and the resolution order lives in
+`CLAUDE.md` § Host environment; this page is the operator's how-to.

context/operations/README.md

@@ -0,0 +1,47 @@
+# operations/ — day-2 procedure, picked by symptom or intent
+
+Command-level operator procedure for a **running** instance: everything the
+liaison executes on demand after the first run. Pick a child by what you are
+trying to do or what is wrong. This tree holds the *how-to*; the *why* is
+`designs/`, and each page routes there for rationale rather than repeating it,
+and to the owning skill where a skill already encodes the procedure (restore,
+schedule). The conversational first-run tour is the sibling tree,
+`../first-run/README.md`; the command-level substance behind its
+"start the garden" stage lives here in [starting.md](starting.md).
+
+## Pick by intent
+
+- **[starting.md](starting.md)** — *"start the garden" / bring up a fresh
+  instance.* Linger, install and enable units, size the pool, designate the
+  leader on a first host, the liaison's three Monitors and their singleton
+  rules, and the optional armings (issue inbox, bulletin PAT). This is the
+  agent-facing detail the liaison runs for tutorial stage 4 and any later
+  re-start — not a human checklist.
+
+- **[leader-follower.md](leader-follower.md)** — *"add a second host" /
+  "hand off leadership" / "which services run where."* Leader-marker semantics,
+  what runs on followers vs. the leader, follower stand-up, and the
+  drain→stand-down→re-point handoff. No automatic failover. Routes to
+  `designs/multibot-leader-follower.md` for rationale.
+
+- **[scaling.md](scaling.md)** — *"scale up/down" / "pause the fleet."* Sizing
+  the pool, `set-gardeners` per host, and `drain on/off` — when to prefer which.
+
+- **[deploy.md](deploy.md)** — *"an upgrade is ready" / "what is the root
+  checkout."* The deliberate deploy: the upgrade-ready signal, `deploy-garden.sh`,
+  and why the root checkout is a deployed version, not a dev tree.
+
+- **[schedules.md](schedules.md)** — *"run something weekly / once at a time."*
+  Recurring and one-shot schedules. Routes to `skills/schedule/SKILL.md`.
+
+- **[health.md](health.md)** — *"a unit failed" / "recover after an outage" /
+  "what are the reaper, deadmail, poison."* Failed-unit checks, the restore
+  engagement (routes to `skills/restore/SKILL.md`), and the self-healing
+  services in one paragraph each.
+
+## Convention
+
+Within-tree cross-references are relative; cross-tree references (skills,
+designs, roles) are repo-root paths. A new operational topic lands as a new leaf
+with a row above; split this directory only when this README stops routing
+cleanly.