treebox 0.4.0__tar.gz → 0.5.0__tar.gz

{treebox-0.4.0 → treebox-0.5.0}/CLAUDE.md

@@ -21,8 +21,8 @@ uv run --extra dev python -m pytest     # full unit + integration suite
 uv run --extra dev python -m pytest tests/test_units.py::test_name   # single test (or -k <pattern>)
 uv run --extra dev ruff check src tests # lint
 uv run --extra dev ruff format --check src tests   # format check (drop --check to apply)
-uv run --extra dev mypy                 # type check (config in pyproject.toml)
-uv run --extra dev pre-commit install   # install lint/format/type hooks (see CONTRIBUTING.md)
+uv run --extra dev mypy                 # strict type check (config in pyproject.toml)
+uv run --extra dev pre-commit install   # install lint/format/strict type-check hooks (see CONTRIBUTING.md)
 ./scripts/validate.sh                   # lint + format + tests + live host-runner smoke (real uv, throwaway local remote)
 uv pip install -e ".[dev]"              # editable dev environment
 uv run --extra docs mkdocs serve        # docs site (docs/ + mkdocs.yml), live-reloading
@@ -52,13 +52,13 @@ run (pluggable)**.
   git just works). `HARNESS_COMMANDS` maps `claude`/`codex` to their
   fully-autonomous launch argv.
 - **`cli.py`** (Typer) is the entry point: `create [NAME] / enter <ref> /
-  list / teardown <ref>... / doctor` (`ls`/`rm` are hidden aliases of
-  list/teardown). `enter`/`teardown` resolve a ref as
+  list / teardown <ref>... / doctor / version` (`ls`/`rm` are hidden aliases
+  of list/teardown). `enter`/`teardown` resolve a ref as
   name → live branch → unique substring (`resolve.py`); ambiguity exits 2.
-  It enforces **stable exit codes** (`0` ok · `2` usage · `3` not-found · `4`
-  auth/fetch · `5` conflict) and **`--json`** output carrying a
-  `schemaVersion` that only gains fields within a version — a breaking reshape
-  bumps it (git-porcelain discipline). Agents
+  It enforces **stable exit codes** (`0` ok · `1` runtime/doctor hard-check ·
+  `2` usage · `3` not-found · `4` auth/fetch · `5` conflict) and **`--json`**
+  output carrying a `schemaVersion` that only gains fields within a version —
+  a breaking reshape bumps it (git-porcelain discipline). Agents
   branch on these, so don't change their meanings casually.
 - **`ecosystems.py`** detects package managers (uv, npm, pnpm, go, cargo),
   drives their cache-backed setup, and defines which manifest files feed the
@@ -73,11 +73,14 @@ run (pluggable)**.
   with `git branch -m`). `create --checkout feature/auth` derives the name by
   flattening slashes to `--` (`feature--auth`); generated names come from
   `names.py`.
-- **`config.py`** is **user-level TOML only**, never read from the target repo —
-  a repo-level config could run arbitrary host commands. Same principle in
-  **`assets.py`**: the sandbox template is operator-owned and rendered into
-  a host-side dir *beside* the worktree, never inside the mount, so a boxed agent
-  cannot edit the config that defines its own sandbox.
+- **`config.py`** is **user-level TOML only** (`$TREEBOX_CONFIG`, else
+  `$TREEBOX_HOME/config.toml`, default `~/.treebox/config.toml`), never read
+  from the target repo — a repo-level config could run arbitrary host commands.
+  Same principle in **`assets.py`**: templates resolve from
+  `$TREEBOX_TEMPLATE_DIR`, then `$TREEBOX_HOME/templates/<name>` (default
+  `~/.treebox/templates/<name>`), and the sandbox template is operator-owned
+  and rendered into a host-side dir *beside* the worktree, never inside the
+  mount, so a boxed agent cannot edit the config that defines its own sandbox.
 
 ## Invariants to preserve
 

{treebox-0.4.0 → treebox-0.5.0}/CONTRIBUTING.md

@@ -13,7 +13,7 @@ For larger feature ideas, open an issue first so we can decide whether they fit
 ## Local checks
 
 Install the pre-commit hooks once so every commit is auto-formatted, lint-fixed,
-and type-checked (`ruff format`, `ruff check --fix`, and `mypy`):
+and type-checked in strict mode (`ruff format`, `ruff check --fix`, and `mypy`):
 
 ```bash
 uv run --extra dev pre-commit install
@@ -32,7 +32,8 @@ will have no reported checks and the PR will stall; the remedy is to push from
 the workflow using a PAT or GitHub App token stored as a repo secret (e.g.
 `AUTOFIX_TOKEN`) instead of `GITHUB_TOKEN`.
 
-For code changes, run the relevant checks before opening a PR:
+For code changes, run the relevant checks before opening a PR. Mypy runs in
+strict mode (configured in `pyproject.toml`):
 
 ```bash
 uv run --extra dev python -m pytest

{treebox-0.4.0 → treebox-0.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 0.4.0
+Version: 0.5.0
 Summary: Isolated, ready-to-run git worktrees for AI coding agents — host-native or docker-sandboxed.
 Project-URL: Homepage, https://github.com/Seth-Peters/treebox
 Project-URL: Documentation, https://seth-peters.github.io/treebox/
@@ -36,13 +36,13 @@ Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
 Description-Content-Type: text/markdown
 
 <p align="center">
-  <img src="assets/treebox-logo.png" alt="treebox" width="220">
+  <img src="https://raw.githubusercontent.com/Seth-Peters/treebox/main/assets/treebox-logo.png" alt="treebox logo: a small tree growing inside a glass box" width="300">
 </p>
 
-<h1 align="center">treebox</h1>
+<h1 align="center">Spin up worktrees, put them in a box,<br>tear them down - treebox</h1>
 
 <p align="center">
-  <strong>Isolated, ready-to-run git worktrees for AI coding agents.</strong>
+  <strong>Isolated, ready-to-run git worktrees for coding agents.</strong>
 </p>
 
 <p align="center">
@@ -61,17 +61,19 @@ Description-Content-Type: text/markdown
   <a href="https://www.linkedin.com/in/seth-peters/">Seth Peters</a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Seth-Peters/treebox/main/assets/treebox-demo.gif" alt="treebox lifecycle demo: create, enter, ls, and an interactive teardown" width="900">
+</p>
+
 ---
 
-Run `treebox create` and it fetches, cuts a worktree from a fresh
-`origin/<base>`, copies your `.env`, installs dependencies from a shared
+`treebox` hands coding agents isolated, ready-to-run git worktrees — one
+directory per worktree name. `treebox create` fetches, cuts a worktree from a
+fresh `origin/<base>`, copies your `.env`, installs dependencies from a shared
 cache, and launches `claude` or `codex` inside. No branch name needed up
-front: the worktree gets a stable name (yours, or a generated petname) and an
-un-pushable `treebox/<name>` placeholder branch the agent renames when the
-work takes shape. Agents work the same repo in parallel without collisions —
-on a laptop or over plain SSH.
-
-Built by [Seth Peters](https://www.linkedin.com/in/seth-peters/) as a small, operator-focused layer for AI agent infrastructure: git worktrees, sandbox boundaries, subscription auth, and repeatable developer environments. If that is the kind of problem you are solving, the [docs](https://seth-peters.github.io/treebox/) go deeper on the design tradeoffs — and I'm [on LinkedIn](https://www.linkedin.com/in/seth-peters/) if you want to compare notes.
+front: the worktree gets a stable name and an un-pushable `treebox/<name>`
+placeholder branch the agent renames when the work takes shape. Agents work the same repo
+in parallel without collisions — on a laptop or over plain SSH.
 
 Provisioning is identical everywhere; a pluggable **isolation mode** decides
 where the agent runs:
@@ -81,26 +83,6 @@ where the agent runs:
 | `host` (default) | none      | the worktree shell                                    |
 | `docker`         | sandboxed | a docker container, with your `.env` + caches mounted |
 
-## Every agent ships its own cage
-
-Every coding agent invents its own answer to "run me in parallel" and "don't
-let me touch the wrong thing" — a different config file, a different schema, a
-different word for the same idea:
-
-| Agent | Sandbox / permission config | Built-in worktrees | Config lives in |
-| ----- | --------------------------- | ------------------ | --------------- |
-| **Claude Code** | `permissions` allow/ask/deny **+** native OS sandbox (Seatbelt/bubblewrap) **+** dev container | Yes (`--worktree`) | `.claude/settings.json`, `.devcontainer/` |
-| **OpenAI Codex** | `sandbox_mode` × `approval_policy` (Seatbelt / Landlock+seccomp) | No in CLI (app only) | `~/.codex/config.toml`, `[profiles.*]` |
-| **opencode** | `permission` per-tool allow/ask/deny (no OS sandbox) | No (community plugins) | `opencode.json` |
-| **pi** | none built-in ("all permissions by default"); BYO Docker/VM + trust prompt | No in core (`pi-subagents`) | `~/.pi/agent/settings.json` |
-
-Learn one and it teaches you nothing about the next, and none of it ports
-across tools. treebox owns the *isolation* layer instead — **one
-worktree-per-branch layout, one operator-owned sandbox, one config file** — and
-launches your agent of choice inside it. Learn treebox once; swap the agent,
-keep the box. Full comparison with citations:
-[Agents & sandboxing](https://seth-peters.github.io/treebox/agents/).
-
 ## Install
 
 ```bash
@@ -112,7 +94,7 @@ instructions if uv is missing — it never installs a package manager behind
 your back. Or install directly:
 
 ```bash
-uv tool install git+https://github.com/Seth-Peters/treebox
+uv tool install treebox
 ```
 
 Host isolation needs only `git` and a logged-in agent CLI (`claude` /
@@ -123,8 +105,7 @@ requirements and installer overrides.
 
 ## Usage
 
-The whole surface is five commands, and a worktree's life runs through all of
-them.
+The worktree lifecycle is five commands.
 
 **Check the host.** `doctor` verifies exactly what `create` will need — git,
 agent logins, `.env`, credentials for the required fetch — and prints the fix
@@ -189,12 +170,32 @@ treebox teardown fix-auth brave-otter --delete-branch
 treebox teardown                        # pick interactively
 ```
 
-treebox is built to be scripted, including by agents: every command takes
-`--json` (data to stdout, diagnostics to stderr, a schema that only gains
-fields within a version), `--dry-run` prints the exact commands without running them, and exit
-codes are stable (`0` ok · `2` usage · `3` not found · `4` auth · `5`
-conflict). Full reference in the
-[usage guide](https://seth-peters.github.io/treebox/usage/).
+treebox is built to be scripted, including by agents: the worktree commands and
+`doctor` take `--json` (data to stdout, diagnostics to stderr, a schema that
+only gains fields within a version), `--dry-run` prints the exact commands
+without running them, and exit codes are stable (`0` ok · `1` runtime/doctor
+blocked · `2` usage · `3` not found · `4` auth · `5` conflict). Full
+reference in the [usage guide](https://seth-peters.github.io/treebox/usage/).
+
+## Every agent ships its own cage
+
+Every coding agent invents its own answer to "run me in parallel" and "don't
+let me touch the wrong thing" — a different config file, a different schema, a
+different word for the same idea:
+
+| Agent | Sandbox / permission config | Built-in worktrees | Config lives in |
+| ----- | --------------------------- | ------------------ | --------------- |
+| **Claude Code** | `permissions` allow/ask/deny **+** native OS sandbox (Seatbelt/bubblewrap) **+** dev container | Yes (`--worktree`) | `.claude/settings.json`, `.devcontainer/` |
+| **OpenAI Codex** | `sandbox_mode` × `approval_policy` (Seatbelt / Landlock+seccomp) | No in CLI (app only) | `~/.codex/config.toml`, `[profiles.*]` |
+| **opencode** | `permission` per-tool allow/ask/deny (no OS sandbox) | No (community plugins) | `opencode.json` |
+| **pi** | none built-in ("all permissions by default"); BYO Docker/VM + trust prompt | No in core (`pi-subagents`) | `~/.pi/agent/settings.json` |
+
+Learn one and it teaches you nothing about the next, and none of it ports
+across tools. treebox owns the *isolation* layer instead — **one
+named-worktree layout, one operator-owned sandbox, one config file** — and
+launches your agent of choice inside it. Learn treebox once; swap the agent,
+keep the box. Full comparison with citations:
+[Agents & sandboxing](https://seth-peters.github.io/treebox/agents/).
 
 ## Design
 
@@ -211,14 +212,14 @@ conflict). Full reference in the
 - **Credentials go in as scoped copies.** Only the agents' login files are
   copied into a throwaway per-worktree dir — never the live `~/.claude` /
   `~/.codex` — refreshed on every entry so a host logout or a fresh login
-  reaches the sandbox next time, and treebox uses your subscription login,
-  never `ANTHROPIC_API_KEY`.
+  reaches the sandbox next time; treebox uses your subscription login.
 
 More in [how it works](https://seth-peters.github.io/treebox/how-it-works/).
 
 ## Configuration
 
-Optional, and user-level only (`~/.config/treebox/config.toml`) — treebox
+Optional, and user-level only (`$TREEBOX_CONFIG`, else
+`$TREEBOX_HOME/config.toml`, default `~/.treebox/config.toml`) — treebox
 never reads config from the target repo:
 
 ```toml
@@ -233,44 +234,51 @@ covered in the
 
 ## Customizing isolation
 
-`docker` isolation is defined by an **operator-owned template** — a
-`Dockerfile` + `container.json` you copy out and edit, kept beside the worktree
-so a boxed agent can't touch its own cage. The shipped image bundles Node 22,
-uv, `gh`, ripgrep, and the agent CLIs, so a Node project often needs no image
-change. For a genuinely separate, non-Python box, copy the template and edit
-two things — global tooling in the `Dockerfile`, and `postCreate` to install
-your repo's deps (in docker, setup runs `postCreate`, not the host-mode
-ecosystem auto-detect):
+`docker` isolation builds from a **template you own** — a directory of files
+treebox ships and you edit. treebox renders it beside the worktree so a boxed
+agent can't touch its own cage. Three steps:
+
+**1. Copy the template out** — you edit a copy, never the shipped one. Name it
+(here `node`); a `node` box and a `python` box can coexist, one per stack:
 
 ```bash
+mkdir -p ~/.treebox/templates
 cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
-      ~/.config/treebox/templates/node
+      ~/.treebox/templates/node
 ```
 
+**2. Edit two files.** The shipped image already bundles Node 22, uv, `gh`,
+ripgrep, and the agent CLIs, so most projects touch only these:
+
 ```dockerfile
-# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
+# ~/.treebox/templates/node/Dockerfile — global tooling
 USER root
 RUN npm install -g pnpm@9 typescript tsx
 USER ${USERNAME}
 ```
 
 ```json
-// ~/.config/treebox/templates/node/container.json
+// ~/.treebox/templates/node/container.json — your install command
 "postCreate": "if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; else npm install; fi"
 ```
 
-Then select it per run (`--isolation docker --template node`) or set
-`template = "node"` in your config — a `node` box and a `python` box coexist,
-one per stack. Full walkthrough in the
-[configuration guide](https://seth-peters.github.io/treebox/configuration/#worked-example-a-node-sandbox-not-python).
+(In docker, setup runs `postCreate`, not the host-mode ecosystem auto-detect,
+so a non-Python project wires its install here.)
+
+**3. Point treebox at it** — per run with `--isolation docker --template node`,
+or set `template = "node"` in `~/.treebox/config.toml`.
+
+Full walkthrough — every file in a template and the `container.json` schema — in
+the [configuration guide](https://seth-peters.github.io/treebox/configuration/#customizing-the-sandbox).
 
 ## Development
 
 ```bash
 git clone https://github.com/Seth-Peters/treebox && cd treebox
 uv run treebox ...                    # run the CLI from the working tree
-uv run --extra dev pre-commit install # lint/format/type hooks (see CONTRIBUTING.md)
+uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
 uv run --extra dev python -m pytest   # unit + integration suite
+uv run --extra dev mypy               # strict type check
 ./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 

{treebox-0.4.0 → treebox-0.5.0}/README.md

@@ -1,11 +1,11 @@
 <p align="center">
-  <img src="assets/treebox-logo.png" alt="treebox" width="220">
+  <img src="https://raw.githubusercontent.com/Seth-Peters/treebox/main/assets/treebox-logo.png" alt="treebox logo: a small tree growing inside a glass box" width="300">
 </p>
 
-<h1 align="center">treebox</h1>
+<h1 align="center">Spin up worktrees, put them in a box,<br>tear them down - treebox</h1>
 
 <p align="center">
-  <strong>Isolated, ready-to-run git worktrees for AI coding agents.</strong>
+  <strong>Isolated, ready-to-run git worktrees for coding agents.</strong>
 </p>
 
 <p align="center">
@@ -24,17 +24,19 @@
   <a href="https://www.linkedin.com/in/seth-peters/">Seth Peters</a>
 </p>
 
+<p align="center">
+  <img src="https://raw.githubusercontent.com/Seth-Peters/treebox/main/assets/treebox-demo.gif" alt="treebox lifecycle demo: create, enter, ls, and an interactive teardown" width="900">
+</p>
+
 ---
 
-Run `treebox create` and it fetches, cuts a worktree from a fresh
-`origin/<base>`, copies your `.env`, installs dependencies from a shared
+`treebox` hands coding agents isolated, ready-to-run git worktrees — one
+directory per worktree name. `treebox create` fetches, cuts a worktree from a
+fresh `origin/<base>`, copies your `.env`, installs dependencies from a shared
 cache, and launches `claude` or `codex` inside. No branch name needed up
-front: the worktree gets a stable name (yours, or a generated petname) and an
-un-pushable `treebox/<name>` placeholder branch the agent renames when the
-work takes shape. Agents work the same repo in parallel without collisions —
-on a laptop or over plain SSH.
-
-Built by [Seth Peters](https://www.linkedin.com/in/seth-peters/) as a small, operator-focused layer for AI agent infrastructure: git worktrees, sandbox boundaries, subscription auth, and repeatable developer environments. If that is the kind of problem you are solving, the [docs](https://seth-peters.github.io/treebox/) go deeper on the design tradeoffs — and I'm [on LinkedIn](https://www.linkedin.com/in/seth-peters/) if you want to compare notes.
+front: the worktree gets a stable name and an un-pushable `treebox/<name>`
+placeholder branch the agent renames when the work takes shape. Agents work the same repo
+in parallel without collisions — on a laptop or over plain SSH.
 
 Provisioning is identical everywhere; a pluggable **isolation mode** decides
 where the agent runs:
@@ -44,26 +46,6 @@ where the agent runs:
 | `host` (default) | none      | the worktree shell                                    |
 | `docker`         | sandboxed | a docker container, with your `.env` + caches mounted |
 
-## Every agent ships its own cage
-
-Every coding agent invents its own answer to "run me in parallel" and "don't
-let me touch the wrong thing" — a different config file, a different schema, a
-different word for the same idea:
-
-| Agent | Sandbox / permission config | Built-in worktrees | Config lives in |
-| ----- | --------------------------- | ------------------ | --------------- |
-| **Claude Code** | `permissions` allow/ask/deny **+** native OS sandbox (Seatbelt/bubblewrap) **+** dev container | Yes (`--worktree`) | `.claude/settings.json`, `.devcontainer/` |
-| **OpenAI Codex** | `sandbox_mode` × `approval_policy` (Seatbelt / Landlock+seccomp) | No in CLI (app only) | `~/.codex/config.toml`, `[profiles.*]` |
-| **opencode** | `permission` per-tool allow/ask/deny (no OS sandbox) | No (community plugins) | `opencode.json` |
-| **pi** | none built-in ("all permissions by default"); BYO Docker/VM + trust prompt | No in core (`pi-subagents`) | `~/.pi/agent/settings.json` |
-
-Learn one and it teaches you nothing about the next, and none of it ports
-across tools. treebox owns the *isolation* layer instead — **one
-worktree-per-branch layout, one operator-owned sandbox, one config file** — and
-launches your agent of choice inside it. Learn treebox once; swap the agent,
-keep the box. Full comparison with citations:
-[Agents & sandboxing](https://seth-peters.github.io/treebox/agents/).
-
 ## Install
 
 ```bash
@@ -75,7 +57,7 @@ instructions if uv is missing — it never installs a package manager behind
 your back. Or install directly:
 
 ```bash
-uv tool install git+https://github.com/Seth-Peters/treebox
+uv tool install treebox
 ```
 
 Host isolation needs only `git` and a logged-in agent CLI (`claude` /
@@ -86,8 +68,7 @@ requirements and installer overrides.
 
 ## Usage
 
-The whole surface is five commands, and a worktree's life runs through all of
-them.
+The worktree lifecycle is five commands.
 
 **Check the host.** `doctor` verifies exactly what `create` will need — git,
 agent logins, `.env`, credentials for the required fetch — and prints the fix
@@ -152,12 +133,32 @@ treebox teardown fix-auth brave-otter --delete-branch
 treebox teardown                        # pick interactively
 ```
 
-treebox is built to be scripted, including by agents: every command takes
-`--json` (data to stdout, diagnostics to stderr, a schema that only gains
-fields within a version), `--dry-run` prints the exact commands without running them, and exit
-codes are stable (`0` ok · `2` usage · `3` not found · `4` auth · `5`
-conflict). Full reference in the
-[usage guide](https://seth-peters.github.io/treebox/usage/).
+treebox is built to be scripted, including by agents: the worktree commands and
+`doctor` take `--json` (data to stdout, diagnostics to stderr, a schema that
+only gains fields within a version), `--dry-run` prints the exact commands
+without running them, and exit codes are stable (`0` ok · `1` runtime/doctor
+blocked · `2` usage · `3` not found · `4` auth · `5` conflict). Full
+reference in the [usage guide](https://seth-peters.github.io/treebox/usage/).
+
+## Every agent ships its own cage
+
+Every coding agent invents its own answer to "run me in parallel" and "don't
+let me touch the wrong thing" — a different config file, a different schema, a
+different word for the same idea:
+
+| Agent | Sandbox / permission config | Built-in worktrees | Config lives in |
+| ----- | --------------------------- | ------------------ | --------------- |
+| **Claude Code** | `permissions` allow/ask/deny **+** native OS sandbox (Seatbelt/bubblewrap) **+** dev container | Yes (`--worktree`) | `.claude/settings.json`, `.devcontainer/` |
+| **OpenAI Codex** | `sandbox_mode` × `approval_policy` (Seatbelt / Landlock+seccomp) | No in CLI (app only) | `~/.codex/config.toml`, `[profiles.*]` |
+| **opencode** | `permission` per-tool allow/ask/deny (no OS sandbox) | No (community plugins) | `opencode.json` |
+| **pi** | none built-in ("all permissions by default"); BYO Docker/VM + trust prompt | No in core (`pi-subagents`) | `~/.pi/agent/settings.json` |
+
+Learn one and it teaches you nothing about the next, and none of it ports
+across tools. treebox owns the *isolation* layer instead — **one
+named-worktree layout, one operator-owned sandbox, one config file** — and
+launches your agent of choice inside it. Learn treebox once; swap the agent,
+keep the box. Full comparison with citations:
+[Agents & sandboxing](https://seth-peters.github.io/treebox/agents/).
 
 ## Design
 
@@ -174,14 +175,14 @@ conflict). Full reference in the
 - **Credentials go in as scoped copies.** Only the agents' login files are
   copied into a throwaway per-worktree dir — never the live `~/.claude` /
   `~/.codex` — refreshed on every entry so a host logout or a fresh login
-  reaches the sandbox next time, and treebox uses your subscription login,
-  never `ANTHROPIC_API_KEY`.
+  reaches the sandbox next time; treebox uses your subscription login.
 
 More in [how it works](https://seth-peters.github.io/treebox/how-it-works/).
 
 ## Configuration
 
-Optional, and user-level only (`~/.config/treebox/config.toml`) — treebox
+Optional, and user-level only (`$TREEBOX_CONFIG`, else
+`$TREEBOX_HOME/config.toml`, default `~/.treebox/config.toml`) — treebox
 never reads config from the target repo:
 
 ```toml
@@ -196,44 +197,51 @@ covered in the
 
 ## Customizing isolation
 
-`docker` isolation is defined by an **operator-owned template** — a
-`Dockerfile` + `container.json` you copy out and edit, kept beside the worktree
-so a boxed agent can't touch its own cage. The shipped image bundles Node 22,
-uv, `gh`, ripgrep, and the agent CLIs, so a Node project often needs no image
-change. For a genuinely separate, non-Python box, copy the template and edit
-two things — global tooling in the `Dockerfile`, and `postCreate` to install
-your repo's deps (in docker, setup runs `postCreate`, not the host-mode
-ecosystem auto-detect):
+`docker` isolation builds from a **template you own** — a directory of files
+treebox ships and you edit. treebox renders it beside the worktree so a boxed
+agent can't touch its own cage. Three steps:
+
+**1. Copy the template out** — you edit a copy, never the shipped one. Name it
+(here `node`); a `node` box and a `python` box can coexist, one per stack:
 
 ```bash
+mkdir -p ~/.treebox/templates
 cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
-      ~/.config/treebox/templates/node
+      ~/.treebox/templates/node
 ```
 
+**2. Edit two files.** The shipped image already bundles Node 22, uv, `gh`,
+ripgrep, and the agent CLIs, so most projects touch only these:
+
 ```dockerfile
-# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
+# ~/.treebox/templates/node/Dockerfile — global tooling
 USER root
 RUN npm install -g pnpm@9 typescript tsx
 USER ${USERNAME}
 ```
 
 ```json
-// ~/.config/treebox/templates/node/container.json
+// ~/.treebox/templates/node/container.json — your install command
 "postCreate": "if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; else npm install; fi"
 ```
 
-Then select it per run (`--isolation docker --template node`) or set
-`template = "node"` in your config — a `node` box and a `python` box coexist,
-one per stack. Full walkthrough in the
-[configuration guide](https://seth-peters.github.io/treebox/configuration/#worked-example-a-node-sandbox-not-python).
+(In docker, setup runs `postCreate`, not the host-mode ecosystem auto-detect,
+so a non-Python project wires its install here.)
+
+**3. Point treebox at it** — per run with `--isolation docker --template node`,
+or set `template = "node"` in `~/.treebox/config.toml`.
+
+Full walkthrough — every file in a template and the `container.json` schema — in
+the [configuration guide](https://seth-peters.github.io/treebox/configuration/#customizing-the-sandbox).
 
 ## Development
 
 ```bash
 git clone https://github.com/Seth-Peters/treebox && cd treebox
 uv run treebox ...                    # run the CLI from the working tree
-uv run --extra dev pre-commit install # lint/format/type hooks (see CONTRIBUTING.md)
+uv run --extra dev pre-commit install # lint/format/strict type-check hooks (see CONTRIBUTING.md)
 uv run --extra dev python -m pytest   # unit + integration suite
+uv run --extra dev mypy               # strict type check
 ./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 

{treebox-0.4.0 → treebox-0.5.0}/docs/agents.md

@@ -8,7 +8,7 @@ of words for the same ideas. Learn one and it teaches you nothing about the
 next.
 
 That fragmentation is treebox's reason to exist. treebox owns the *isolation*
-layer — one worktree-per-branch layout and one operator-owned sandbox — and
+layer — one named-worktree layout and one operator-owned sandbox — and
 launches your agent of choice inside it. **One config to learn, any agent in
 the box.**
 
@@ -54,8 +54,9 @@ whichever agent you launch:
 
     ---
 
-    `~/.config/treebox/config.toml` picks the isolation mode, harness, base, caches, and
-    sandbox template. It's the single source of truth, and it's never read
+    `$TREEBOX_CONFIG`, else `$TREEBOX_HOME/config.toml` (default
+    `~/.treebox/config.toml`), picks the isolation mode, harness, base, caches,
+    and sandbox template. It's the single source of truth, and it's never read
     from the target repo.
 
 - :material-swap-horizontal:{ .lg .middle } **Swap the agent, keep the box**