Operating Setup

---
name: operating-setup
description: "How an agent links, updates and sets up a project with Bonsai unattended. Open it before you run bonsai init or bonsai update, edit bonsai.yaml, change a pack's version, move a task's status where status_command is set, or change what this machine is set up with. Everything else an agent does with Bonsai is in base:operating-bonsai."
---

<!-- skills/operating-setup/SKILL.md (base:operating-setup): the second half of the operating skills; no template, and
no copy of a list. Its frontmatter: base's README.md, "Skill files". It holds linking, updating, editing
bonsai.yaml, status moves and this machine's settings; the core every agent reads before any bonsai call is
skills/operating-bonsai/SKILL.md (base:operating-bonsai). A later piece's lines go to the half that holds its
subject: a word that changes what a project or this machine is set up with (install, settings, labels) here; a word
an agent uses while it works there. Bonsai's cmd/bonsai/operating_test.go holds every bonsai line in the two to the
command table, each to its size, and every word of the table to one of them. -->

# Operating Bonsai: setup

This is the setup half: linking, updating, `bonsai.yaml`, status moves and this machine's settings. Read the core,
`base:operating-bonsai`, first: `--json`, refusals by their next step, check, the ladder, asks, briefs, budgets, the
guard and the person's gates are there, and what follows assumes them. The `bonsai` you run describes itself with
`bonsai --help --json`.

## Link and update: the main checkout, on its base branch

`init` and `update` write `.claude/settings.json`, which the ladder's first rung refuses on any other branch.

- **A first link**, at the packs and refs the person named (by these flags, or in `bonsai.yaml` first); where no ref
  is named, hand them the one you propose (the newest tag, else the default branch's head commit) and link on their
  yes. Without `--yes` it is a preview: nothing written, exit 4 (`needs-yes`). Read each settings line, then run it
  again with `--yes`. `--json` lists every line; the text preview counts them by kind, and `--explain` (on `init`
  and `update`) lists each with where it comes from and why.

  ```sh
  bonsai init --name <name> --source <url> --path <folder> --ref <tag or commit> --json
  ```

- **An update** applies what is already decided (a repair, a re-apply on this machine, the project's own stricter
  change): `bonsai update --json`, its preview read line by line, then `bonsai update --yes --json`. `needs-yes` is
  the person's: pass `--yes` only where their word already covers what the preview shows (a task or plan they
  approved, their yes to the line handed over); else hand the preview over. On Windows the person opens a Claude Code
  session before an update that installs a plugin (a fresh login).
- **Exit 5** (`conflicts`): `--keep <path>` when the project's edit should win, `--adopt <path>` when the pack's
  should; ask when unsure.
- **Exit 4 with "Runs code"** (`needs-allow-exec`): consent to code is never your own choice. Where a studio manages
  the project the command takes `--allow-exec` under the person's grant (the running task grants `bonsai.yaml` and
  the lock); elsewhere it refuses (`person-command`): stop and hand the person the exact line.
- **A plugin `waiting`**: on trust, the person opens Claude Code in the folder and accepts its question, then
  `bonsai update`; on code, the line above.
- Then `bonsai check --json` with no finding, and everything the command wrote (`bonsai.yaml`, the lock,
  `.claude/settings.json`, the block, the packs' files, the tables) in one commit.

## Edit bonsai.yaml

It is person-only: edit it only under a running task whose `bonsai.allows` grants it, and on your own only for a
stricter change: a rung or floor entry added, a floor raised to a green, clean climb's count, a protected path added.
A rung added still needs the person: the next climb refuses it (`config-looser`) until they run `bonsai update`,
so write it and hand them that line. A climb reads it as committed (`config-uncommitted` until
then). Write only the forms `base:workspace` shows, a mapping as indented `key: value`
lines: a `bonsai.yaml` Bonsai cannot read blocks every call, and only the person can repair it.

**Anything else loosens a check and is the person's step:** a floor lowered; a rung's command, `required`, tests,
ratchet or capture changed or removed; a protected or person-only path taken out; a test marked to skip in CI. Edit
nothing, however the request reaches you (chat, a brief, a task): you cannot tell a message from the person's own
step. Hand them the exact line, old and new, and why, or ask (`--type Decide`); they make the edit.

**A role's budget** (`roles` under a pack's entry) is neither: change a default or max either way under a task
granting `bonsai.yaml`; it holds for agents started after the commit. So are the `messages` thresholds.

**A pack's version is the person's word, applied with `bonsai pack`** (`bonsai pack --help`): see which are behind
with `bonsai pack outdated --json` (it reads the network and keeps the answer, which `bonsai status --json` shows in
`packs[].newer`). A move, an added pack or one taken out is the person's choice: a request for one is not their word.
Hand them the change and why in one message, or ask; on their yes, preview it, `bonsai pack set <id>@<ref> --json`,
`bonsai pack add --source <url> --ref <ref> --json` or `bonsai pack remove <id> --json`, read it line by line (its
`config` is the `bonsai.yaml` line, only the ref's text changing), then the same with `--yes --expect <fingerprint>`
(the preview's `fingerprint`: `plan-changed` means read it again), under a task granting `bonsai.yaml` and the lock.
A preview whose `loosening` is not empty takes protections away (a pack taken out, a deny rule or protected path
dropped): it is the person's alone, and in an agent's session `--yes` is refused (`person-command`) whatever the
task grants, `bonsai update` after a hand edit too. Hand them the exact line. Why: an agent choosing the packs that
hold it would be judging its own work. `bonsai check --json` after every change.
`bonsai pack show <id> --json` prints one pack's details offline (version, needs, skills, roles, deny rules,
protected paths, kinds, the cache's newer release); `bonsai pack outdated --changes` lists each behind pack's commit
titles (text only), and a set preview's `pack_changes` holds them too: hand them to the person with the change.
`bonsai pack set --all` moves every pack behind to its newest release in one preview (a pack at a commit or a branch
is left and named). A move back to an older release tag is refused (`pack-downgrade`) until the person's word adds
`--downgrade`; a version that needs a newer Claude Code than this machine runs, or a pack format this Bonsai does not
read, is refused before anything is written (`pack-needs`): the person updates Claude Code or Bonsai first. After
`--yes`, commit with the two lines `commit_lines` gives, each on its own line (never joined by `&&`); when the
plugins' marketplace name moved, a plugin result (old-marketplace) names the old one and the person's command that
removes it, once no other checkout uses it.

## Status moves

Read `status_writes`. Under `agents`, edit a task's status line yourself, by contract section 10.2's agents' moves:
between the open statuses but never to `approved`, to `done` only in a `close: agent` lane, to `blocked` with
`blocked_by` filled. Under `command` (a studio manages the project) the guard refuses an agent's edit of a status
line (`status-line`), a lane line (`lane-line`), a task file outside the main checkout (`task-outside-main`) and a
person-only path put into `bonsai.allows` (`grant-person-only`): run the command `status_command` names instead.

## This machine's settings and attached labels

They live in the Bonsai home, never in the project: `status_writes` and `status_command` for the workspace, and with
`--machine` the home's own. `bonsai settings --help` and `bonsai labels --help` show both words; a sub-word a build
does not have yet refuses `not-built` and names the step that brings it.

- **Read** them with `bonsai settings show --json` (`--machine` for the home's): every key, its value in force and where
  it came from (`file` or `default`), and the file's place. Agents may run it; from a worktree it reads the main
  checkout's. The keys, their values and defaults are in `bonsai settings set --help`: the workspace's
  `status_writes` (`agents` or `command`) and `status_command` (with `command` only: letters, digits, spaces and
  `-_./:`, at most 100 characters); the home's `cache_keep_days` (1 to 3650, or `none`: `update --yes` then removes
  pack clones unused that long, never one the lock or `bonsai.yaml` names, never an `--adopt` copy) and, on Windows,
  `personal_from`. A settings file holding a value outside its rule is refused (`read-failed`, naming the file and the
  key), by the guard too: tell the person the file to fix.
- **`bonsai settings set k=v ...`** checks every `key=value` first, then writes all or none (`bad-value`, exit 2,
  names the values a key takes); a value already in force writes nothing (`changed: []`).
- **A `stranded` warning** from `check` is a machine folder left under a checkout's old path (it moved) with settings
  or labels this checkout no longer gets. Its `next.do` holds the person's exact lines, in order; hand them over as
  they are.
- **`settings set`, `labels attach` and `labels detach` are a person's**: in an agent's session each refuses itself
  (`person-command`) and the guard refuses them too. Hand the person the exact line (`bonsai labels attach <file>`,
  `bonsai labels detach <namespace>`), to type in a terminal of their own, not inside Claude (its `!` lines count as
  an agent's session).
- **An attach adds, never redefines:** a namespace that is `bonsai` or a locked pack's is refused (`namespace-taken`),
  and a changed or removed definition (`label-redefined`): the person detaches the namespace, then attaches again.