treebox 0.2.0__tar.gz → 0.4.0__tar.gz

treebox-0.4.0/.github/workflows/autofix.yml

@@ -0,0 +1,69 @@
+name: Autofix
+
+# Applies ruff's auto-fixes (`ruff check --fix` + `ruff format`) to pull requests
+# and commits the result back to the PR branch. This is the CI counterpart to the
+# pre-commit hooks: if a change lands unformatted (hooks skipped), the branch is
+# fixed in place instead of just failing the CI gate. Skips fork PRs, where the
+# workflow token cannot push, and its own commits, to avoid loops.
+#
+# Gotcha: pushes made with the default GITHUB_TOKEN (from actions/checkout) do
+# NOT trigger new workflow runs. So the auto-fixed commit this job pushes will
+# not re-run ci.yml. Two implications:
+#   - If branch protection REQUIRES the CI status checks, the auto-fixed SHA will
+#     have no reported checks and the PR will stall. The remedy is to check out
+#     and push using a PAT or GitHub App token stored as a repo secret (e.g.
+#     AUTOFIX_TOKEN) instead of GITHUB_TOKEN, so the push re-triggers CI.
+#   - To close the "merged with a commit CI never validated" hole regardless,
+#     this job re-runs the ruff + mypy checks on the fixed tree below and fails
+#     rather than pushing if they don't pass, so the exact pushed commit is
+#     validated within this run.
+
+on:
+  pull_request:
+
+concurrency:
+  group: autofix-${{ github.ref }}
+  cancel-in-progress: true
+
+permissions:
+  contents: write
+
+jobs:
+  autofix:
+    name: ruff --fix
+    runs-on: ubuntu-latest
+    if: >-
+      github.event.pull_request.head.repo.full_name == github.repository &&
+      github.actor != 'github-actions[bot]'
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.head_ref }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v8.2.0
+        with:
+          enable-cache: true
+
+      - name: ruff check --fix
+        run: uv run --extra dev ruff check --fix src tests
+
+      - name: ruff format
+        run: uv run --extra dev ruff format src tests
+
+      - name: Validate fixed tree
+        run: |
+          uv run --extra dev ruff check src tests
+          uv run --extra dev ruff format --check src tests
+          uv run --extra dev mypy
+
+      - name: Commit fixes
+        run: |
+          if git diff --quiet; then
+            echo "No formatting or lint fixes needed."
+            exit 0
+          fi
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git commit -am "style: apply ruff --fix and format"
+          git push

{treebox-0.2.0 → treebox-0.4.0}/.github/workflows/ci.yml

@@ -29,6 +29,9 @@ jobs:
       - name: Lint
         run: uv run -p ${{ matrix.python-version }} --extra dev ruff check src tests
 
+      - name: Format
+        run: uv run -p ${{ matrix.python-version }} --extra dev ruff format --check src tests
+
       - name: Type check
         run: uv run -p ${{ matrix.python-version }} --extra dev mypy
 

treebox-0.4.0/.pre-commit-config.yaml

@@ -0,0 +1,25 @@
+# Pre-commit hooks: keep every commit lint-clean, formatted, and type-checked.
+# Install once with `uv run --extra dev pre-commit install` (or `pre-commit install`).
+# Run against everything with `uv run --extra dev pre-commit run --all-files`.
+#
+# Keep the ruff rev in sync with the `ruff>=…` pin in pyproject.toml's [dev] extra.
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.20
+    hooks:
+      # Lint and auto-fix (import sorting, pyupgrade, simplify, …), then format.
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+
+  # mypy runs from the project's own dev environment so it sees typer/questionary
+  # stubs and the [tool.mypy] config (files = ["src"]). pass_filenames is off
+  # because that config already selects the files to check.
+  - repo: local
+    hooks:
+      - id: mypy
+        name: mypy
+        entry: uv run --extra dev mypy
+        language: system
+        types: [python]
+        pass_filenames: false

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

@@ -19,9 +19,11 @@ template it provisions is separately pinned to CPython 3.14.6).
 uv run treebox ...                      # run the CLI from the working tree
 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>)
-ruff check src tests                    # lint
+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)
-./scripts/validate.sh                   # lint + tests + live host-runner smoke (real uv, throwaway local remote)
+uv run --extra dev pre-commit install   # install lint/format/type 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
 uv run --extra docs mkdocs build --strict   # build docs to site/ (gitignored)

treebox-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,52 @@
+# Contributing
+
+treebox is a small, one-maintainer project. Contributions are welcome, but the scope is intentionally modest.
+
+## Good contributions
+
+- Bug fixes with a clear reproduction.
+- Documentation fixes that make install, usage, or runner behavior clearer.
+- Small compatibility fixes that preserve the existing CLI and scripting behavior.
+
+For larger feature ideas, open an issue first so we can decide whether they fit the project.
+
+## 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`):
+
+```bash
+uv run --extra dev pre-commit install
+```
+
+Note: `pre-commit install` has no effect inside a treebox worktree, because
+treebox sets `core.hooksPath` for its own pre-push guard, so git ignores the
+hook pre-commit writes to `.git/hooks`. Run the hooks manually there with
+`uv run --extra dev pre-commit run --all-files`.
+
+If the hooks are skipped, the Autofix CI workflow applies the same `ruff --fix`
+and `ruff format` to same-repo PRs and pushes the result back. Note that pushes
+made with the default `GITHUB_TOKEN` do not re-trigger CI, so if this repo ever
+requires the CI status checks under branch protection, the auto-fixed commit
+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:
+
+```bash
+uv run --extra dev python -m pytest
+uv run --extra dev ruff check src tests
+uv run --extra dev ruff format --check src tests
+uv run --extra dev mypy
+```
+
+For docs-only changes, this is enough:
+
+```bash
+uv run --extra docs mkdocs build --strict
+```
+
+## Boundaries
+
+Please preserve the basics: fresh refs by default, no trust in target-repo sandbox config, stable CLI output for scripts, and subscription-based agent auth.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: treebox
-Version: 0.2.0
+Version: 0.4.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/
@@ -23,9 +23,11 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.11
 Requires-Dist: questionary<3,>=2
+Requires-Dist: rich<16,>=13
 Requires-Dist: typer<1.0,>=0.12
 Provides-Extra: dev
 Requires-Dist: mypy>=1.14; extra == 'dev'
+Requires-Dist: pre-commit>=4; extra == 'dev'
 Requires-Dist: pytest-cov>=6; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
@@ -48,6 +50,7 @@ Description-Content-Type: text/markdown
   <a href="https://seth-peters.github.io/treebox/"><img src="https://img.shields.io/badge/docs-seth--peters.github.io%2Ftreebox-2f6f4f" alt="Documentation"></a>
   <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="Python 3.11+">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-2f6f4f" alt="PolyForm Noncommercial License"></a>
+  <a href="https://www.linkedin.com/in/seth-peters/"><img src="https://img.shields.io/badge/LinkedIn-Seth%20Peters-0a66c2?logo=linkedin&logoColor=white" alt="Seth Peters on LinkedIn"></a>
 </p>
 
 <p align="center">
@@ -55,7 +58,7 @@ Description-Content-Type: text/markdown
   <a href="https://seth-peters.github.io/treebox/install/">Install</a> ·
   <a href="https://seth-peters.github.io/treebox/usage/">Usage</a> ·
   <a href="https://seth-peters.github.io/treebox/how-it-works/">How it works</a> ·
-  <a href="https://github.com/Seth-Peters">Seth Peters</a>
+  <a href="https://www.linkedin.com/in/seth-peters/">Seth Peters</a>
 </p>
 
 ---
@@ -68,7 +71,7 @@ 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://github.com/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.
+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.
 
 Provisioning is identical everywhere; a pluggable **isolation mode** decides
 where the agent runs:
@@ -148,7 +151,7 @@ the branch starts as a `treebox/<name>` placeholder that a per-worktree
 pre-push guard keeps **un-pushable** — rename it conventionally
 (`git branch -m feature/user-auth`, `fix/login-race`, `chore/bump-deps`, …)
 when the work has a shape, then push. So a machine-generated name can never
-become a PR title. `-b` is the one path that skips the placeholder: it checks out an
+become a PR title. `--checkout` is the one path that skips the placeholder: it checks out an
 existing branch exactly.
 
 `--base` takes any branch, not just `main` — branch off `dev`, or stack a new
@@ -156,10 +159,11 @@ worktree on top of an existing PR's branch, even while that branch is checked
 out in another worktree. It resolves as the freshly fetched `origin/<base>`,
 so push the base first if its latest commits only exist locally.
 
-**Enter.** Come back to an existing worktree, picking the agent per entry.
-The ref is the name, the *current* branch (renames are followed live), or a
-unique substring of either. Dependencies re-sync only if the lockfile changed
-since last time:
+**Enter.** Come back to an existing worktree. By default it reuses the harness
+the worktree was created with; an explicit `--harness` overrides it for that
+session only, without changing what's recorded on disk. The ref is the name,
+the *current* branch (renames are followed live), or a unique substring of
+either. Dependencies re-sync only if the lockfile changed since last time:
 
 ```bash
 treebox enter fix-auth --harness claude
@@ -206,8 +210,9 @@ conflict). Full reference in the
   hooks are ignored.
 - **Credentials go in as scoped copies.** Only the agents' login files are
   copied into a throwaway per-worktree dir — never the live `~/.claude` /
-  `~/.codex` — and treebox uses your subscription login, never
-  `ANTHROPIC_API_KEY`.
+  `~/.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`.
 
 More in [how it works](https://seth-peters.github.io/treebox/how-it-works/).
 
@@ -226,13 +231,47 @@ All keys, shared-cache overrides, setup hooks, and sandbox templates are
 covered in the
 [configuration guide](https://seth-peters.github.io/treebox/configuration/).
 
+## 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):
+
+```bash
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.config/treebox/templates/node
+```
+
+```dockerfile
+# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+```json
+// ~/.config/treebox/templates/node/container.json
+"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).
+
 ## 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 python -m pytest   # unit + integration suite
-./scripts/validate.sh                 # lint + tests + live host-runner smoke
+./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 
 ## Contributing

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

@@ -13,6 +13,7 @@
   <a href="https://seth-peters.github.io/treebox/"><img src="https://img.shields.io/badge/docs-seth--peters.github.io%2Ftreebox-2f6f4f" alt="Documentation"></a>
   <img src="https://img.shields.io/badge/python-3.11%2B-3776ab" alt="Python 3.11+">
   <a href="LICENSE"><img src="https://img.shields.io/badge/license-PolyForm%20Noncommercial-2f6f4f" alt="PolyForm Noncommercial License"></a>
+  <a href="https://www.linkedin.com/in/seth-peters/"><img src="https://img.shields.io/badge/LinkedIn-Seth%20Peters-0a66c2?logo=linkedin&logoColor=white" alt="Seth Peters on LinkedIn"></a>
 </p>
 
 <p align="center">
@@ -20,7 +21,7 @@
   <a href="https://seth-peters.github.io/treebox/install/">Install</a> ·
   <a href="https://seth-peters.github.io/treebox/usage/">Usage</a> ·
   <a href="https://seth-peters.github.io/treebox/how-it-works/">How it works</a> ·
-  <a href="https://github.com/Seth-Peters">Seth Peters</a>
+  <a href="https://www.linkedin.com/in/seth-peters/">Seth Peters</a>
 </p>
 
 ---
@@ -33,7 +34,7 @@ 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://github.com/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.
+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.
 
 Provisioning is identical everywhere; a pluggable **isolation mode** decides
 where the agent runs:
@@ -113,7 +114,7 @@ the branch starts as a `treebox/<name>` placeholder that a per-worktree
 pre-push guard keeps **un-pushable** — rename it conventionally
 (`git branch -m feature/user-auth`, `fix/login-race`, `chore/bump-deps`, …)
 when the work has a shape, then push. So a machine-generated name can never
-become a PR title. `-b` is the one path that skips the placeholder: it checks out an
+become a PR title. `--checkout` is the one path that skips the placeholder: it checks out an
 existing branch exactly.
 
 `--base` takes any branch, not just `main` — branch off `dev`, or stack a new
@@ -121,10 +122,11 @@ worktree on top of an existing PR's branch, even while that branch is checked
 out in another worktree. It resolves as the freshly fetched `origin/<base>`,
 so push the base first if its latest commits only exist locally.
 
-**Enter.** Come back to an existing worktree, picking the agent per entry.
-The ref is the name, the *current* branch (renames are followed live), or a
-unique substring of either. Dependencies re-sync only if the lockfile changed
-since last time:
+**Enter.** Come back to an existing worktree. By default it reuses the harness
+the worktree was created with; an explicit `--harness` overrides it for that
+session only, without changing what's recorded on disk. The ref is the name,
+the *current* branch (renames are followed live), or a unique substring of
+either. Dependencies re-sync only if the lockfile changed since last time:
 
 ```bash
 treebox enter fix-auth --harness claude
@@ -171,8 +173,9 @@ conflict). Full reference in the
   hooks are ignored.
 - **Credentials go in as scoped copies.** Only the agents' login files are
   copied into a throwaway per-worktree dir — never the live `~/.claude` /
-  `~/.codex` — and treebox uses your subscription login, never
-  `ANTHROPIC_API_KEY`.
+  `~/.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`.
 
 More in [how it works](https://seth-peters.github.io/treebox/how-it-works/).
 
@@ -191,13 +194,47 @@ All keys, shared-cache overrides, setup hooks, and sandbox templates are
 covered in the
 [configuration guide](https://seth-peters.github.io/treebox/configuration/).
 
+## 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):
+
+```bash
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.config/treebox/templates/node
+```
+
+```dockerfile
+# ~/.config/treebox/templates/node/Dockerfile — Node 22 is already baked in
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+```json
+// ~/.config/treebox/templates/node/container.json
+"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).
+
 ## 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 python -m pytest   # unit + integration suite
-./scripts/validate.sh                 # lint + tests + live host-runner smoke
+./scripts/validate.sh                 # lint + format + tests + live host-runner smoke
 ```
 
 ## Contributing

{treebox-0.2.0 → treebox-0.4.0}/docs/configuration.md

@@ -40,7 +40,7 @@ command-line flag  >  config.toml  >  built-in default
 | Key        | Default              | What it controls                                          |
 | ---------- | -------------------- | --------------------------------------------------------- |
 | `isolation`| `host`               | Where agents run: the worktree shell, or a docker sandbox. |
-| `harness`  | `claude`             | Which agent `create`/`enter` launch by default.           |
+| `harness`  | `claude`             | Which agent `create` launches by default; `enter` reuses the harness the worktree was created with unless `--harness` overrides it. |
 | `base`     | `main`               | Base branch for new branches (resolved as `origin/<base>`). |
 | `root`     | `.treebox/worktrees` | Where worktree directories are created, relative to the repo. |
 | `env_file` | `.env`               | The secrets file copied into every new worktree.          |
@@ -66,7 +66,9 @@ cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.a
 syntax, with `${workspaceName}` substituted per worktree), and `runArgs` feed
 `docker run`; `postCreate` is the setup command exec'd in the workspace after
 the container starts. The firewall overlay in `firewall.json` deep-merges on
-top when `--firewall` is set.
+top when the firewall is enabled (`firewall = true` in the config, or
+`--firewall` per run; `--no-firewall` opts a single run out of a config
+default).
 
 Templates in `~/.config/treebox/templates/<name>` are picked by the
 `template` config key or per-invocation with `--template <name>`. The
@@ -75,11 +77,51 @@ mount — so a sandboxed agent can't edit it. Any container config in the
 target repo itself is deliberately ignored; see
 [how it works](how-it-works.md#the-sandbox-config-lives-outside-the-box).
 
+### Worked example: a Node sandbox, not Python
+
+Say your project is Node and you want a box with nothing to do with the
+default Python one. Keep a separate named template and select it per run —
+a `node` box and a `python` box coexist, one per stack. Copy the template out:
+
+```bash
+cp -R "$(python -c 'import treebox.assets, pathlib; print(pathlib.Path(treebox.assets.__file__).parent)')/container" \
+      ~/.config/treebox/templates/node
+```
+
+The shipped image already bundles Node 22 (plus uv, `gh`, ripgrep, and the
+agent CLIs), so a Node project often needs no image change at all. Add any
+**global** tooling to `~/.config/treebox/templates/node/Dockerfile`:
+
+```dockerfile
+USER root
+RUN npm install -g pnpm@9 typescript tsx
+USER ${USERNAME}
+```
+
+Then the one docker-specific step: point `postCreate` in `container.json` at
+your project's install command. In docker isolation, dependency setup is
+driven by the template's `postCreate` — not the host-mode ecosystem
+auto-detect — so a non-Python project must wire its own install here (the
+npm/pnpm cache is mounted, so it stays warm across worktrees):
+
+```json
+"postCreate": "if [ -f pnpm-lock.yaml ]; then pnpm install --frozen-lockfile; elif [ -f package-lock.json ]; then npm ci; else npm install; fi"
+```
+
+Now provision with it, per-invocation or as your default (`template = "node"`):
+
+```bash
+treebox create my-feature --isolation docker --template node
+```
+
+First run builds your image (cached after that), provisions the worktree, runs
+`postCreate` to install deps, and launches the agent inside.
+
 ## Environment variables
 
 | Variable          | Effect                                                        |
 | ----------------- | ------------------------------------------------------------- |
-| `TREEBOX_CONFIG`  | Explicit path to the config file (overrides the XDG lookup).  |
+| `TREEBOX_CONFIG`  | Explicit path to the config file (overrides the XDG lookup). Setting it asserts the file exists — a missing file here is a loud error (exit `2`), not a silent fall-back to defaults. |
 | `XDG_CONFIG_HOME` | Standard XDG base for `treebox/config.toml` and templates.    |
 | `XDG_CACHE_HOME`  | Standard XDG base for the shared package caches treebox mounts. |
 

{treebox-0.2.0 → treebox-0.4.0}/docs/how-it-works.md

@@ -104,5 +104,7 @@ treebox assumes the caller is often another program:
 - **`--json` with a `schemaVersion`** that only gains fields within a version
   (git-porcelain discipline), plus `--print` and `--dry-run` for scripts that
   want the commands, not the side effects.
-- **Per-worktree locking**, so two concurrent `create fix-auth` calls
-  conflict cleanly (`5`) instead of corrupting a worktree.
+- **Per-worktree locking**, held by `create`, `enter`, and `teardown` alike,
+  so racing operations on one name — two `create fix-auth` calls, or a
+  `teardown fix-auth` against a concurrent provision — conflict cleanly (`5`)
+  instead of corrupting or half-removing a worktree.