warmtree 0.1.0__tar.gz

warmtree-0.1.0/.gitattributes

@@ -0,0 +1 @@
+* text=auto eol=lf

warmtree-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,23 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+jobs:
+  test:
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, windows-latest]
+    runs-on: ${{ matrix.os }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - run: uv sync
+      - run: uv run ruff check .
+      - run: uv run ruff format --check .
+      - run: uv run pytest -q

warmtree-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,39 @@
+name: Publish
+
+# Publishes to PyPI when a version tag is pushed, using trusted publishing.
+# No API token is stored anywhere; PyPI trusts this workflow's OIDC identity.
+# One-time setup on pypi.org: add a trusted publisher for
+#   owner dcolliervb23, repository warmtree, workflow publish.yml, environment pypi.
+
+on:
+  push:
+    tags: ["v*"]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+        with:
+          python-version: "3.12"
+      - name: Tag must match the package version
+        run: test "v$(uv version --short)" = "$GITHUB_REF_NAME"
+      - run: uv build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1

warmtree-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+dist/
+build/
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.warmtree/

warmtree-0.1.0/.python-version

@@ -0,0 +1 @@
+3.12

warmtree-0.1.0/CLAUDE.md

@@ -0,0 +1,25 @@
+# warmtree — rules for AI sessions in this repo
+
+Read DESIGN.md first. It is the scope. Do not expand it; append ideas to IDEAS.md.
+The scope is the pool only. Do not add port allocation, merge helpers, or
+general cleanup; the design explains why.
+
+## Working rules
+- Prefer boring, readable Python over clever Python. Every line should be one
+  a reviewer can follow without explanation.
+- The maintainer writes the tests and the README. Draft them if asked, then
+  stop and wait for review before committing.
+- Small commits, one step each. Conventional messages (`feat:`, `test:`, `docs:`).
+  Plain messages: no co-author trailers, no session links.
+
+## Publishing hygiene
+- `git config user.email dcolliervb23@users.noreply.github.com` in this repo. Never a personal email.
+- No secrets. PyPI publishing is GitHub Actions trusted publishing only.
+- No local machine paths in any committed file.
+- Assume every commit is public.
+
+## Stack
+- Python 3.12, standard library only at runtime (`dependencies = []`).
+- Dev tools: `uv`, `ruff`, `pytest`. Tests create real temporary git repos.
+- Run tests with `uv run pytest -q`. Lint with `uv run ruff check .`.
+- Must work on Windows, Linux, and WSL. CI runs on ubuntu-latest and windows-latest.

warmtree-0.1.0/DESIGN.md

@@ -0,0 +1,143 @@
+# warmtree design
+
+> `git worktree add` is fast. Everything after it is slow: dependency install,
+> build caches, untracked env files. warmtree keeps a few worktrees already
+> checked out, fast-forwarded, and warmed, so `warmtree take <branch>` hands
+> you a ready workspace in under a second. Built for parallel AI coding agents.
+
+Language: Python 3.12, standard library only.
+
+## Positioning
+
+The worktree-tooling space is crowded. worktrunk (Rust) already does on-create
+hooks, copies ignored files, allocates ports, and cleans up merged worktrees.
+Several smaller tools cover env copying and ports on their own. **No tool
+pre-creates warm worktrees.** The pool is the entire contribution, and the
+scope is held to it on purpose.
+
+warmtree owns the **create** and **release** steps. Everything in between is
+ordinary git, so worktrunk, portree, global git hooks, and editors all work on
+a pooled worktree unchanged. The README documents two workflows: standalone,
+and warmtree-for-create plus worktrunk-for-everything-else.
+
+## Rules
+
+- Standard library only. No runtime dependencies. `uvx warmtree` must work
+  on a machine with nothing but Python and git.
+- Stack-agnostic. warmtree never knows what npm or dotnet are. Projects
+  declare their own warm commands.
+- Boring, readable Python. Every line should be explainable to a reviewer.
+- Tests run against real temporary git repos. Nothing about git is mocked.
+
+## v1 scope
+
+### Config: `.warmtree.toml` at the repo root (parsed with `tomllib`)
+
+```toml
+[pool]
+size = 3                 # slots to keep ready
+base = "main"            # branch slots are parked on
+dir = "../.warmtree/app" # where slots live; default is ../.warmtree/<repo name>
+lockfiles = ["package-lock.json", "uv.lock"]  # re-warm only when these change
+
+[warm]
+run = ["npm ci"]         # executed in the slot at fill/refresh time
+copy = [".env", ".env.local"]  # untracked files copied from the main worktree
+env = true               # write WARMTREE_SLOT=<n> into copied env files
+```
+
+Every key has a default; an empty file means "pool of 2 on the default
+branch, fast-forward only."
+
+### Commands
+| Command | Behavior |
+|---|---|
+| `warmtree init` | Write a starter config. Detects common lockfiles only to pre-fill `lockfiles`; never guesses `run`. Installs the agent skill for any coding agent the repo shows signs of. |
+| `warmtree skill [--tool T] [--force]` | Install or refresh the agent skill in detected or named tool folders. |
+| `warmtree fill` | Create missing slots with `git worktree add --detach`, run `copy`, run `run`, record lockfile hashes. |
+| `warmtree take <branch> [--from <ref>]` | Claim the oldest ready slot: create or check out `<branch>` inside it, print its path, mark it taken. Refill the pool afterward (`--no-refill` to skip; `--refill-background` spawns a detached process). If no slot is ready, fall back to a cold create and say so. |
+| `warmtree release <branch>` | Reset the slot to `base`, discard the working tree (`--keep-branch` keeps the branch ref), return the slot to ready. Refuses if the tree is dirty unless `--force`. |
+| `warmtree refresh` | Fast-forward every ready slot to `base`; if any lockfile hash changed, re-run `run` and `copy` in that slot. Meant for a nightly scheduled task or cron. |
+| `warmtree status` | Table of slots: path, state (ready/taken/warming/stale), branch, age, last warm. `--json` for agents. |
+| `warmtree size [N]` | Show configured size and counts by state. With `N`, write the size to the config and grow or shrink the pool to match; shrinking removes waiting slots only. |
+| `warmtree which` | Name the slot the current directory is inside, so an agent can tell whether it already has a workspace. |
+| `warmtree remove [SLOT...] [--all]` | Delete slots and their worktree registrations. |
+
+### State
+- `state.json` inside the pool dir: slot list with state, branch,
+  created/warmed timestamps, lockfile hashes. One file, rewritten atomically.
+- Concurrency: `take` holds an OS file lock (`msvcrt` on Windows, `fcntl`
+  elsewhere) for the claim. Two agents calling `take` at once get two
+  different slots.
+
+### Agent integration
+- `warmtree/skills/warmtree/SKILL.md` in the open Agent Skills format (read by
+  Claude Code, GitHub Copilot, Codex CLI, Cursor), shipped inside the package.
+  `warmtree init` copies it into the skills folder of every tool the repo
+  shows signs of using (`CLAUDE.md`, `copilot-instructions.md`, `AGENTS.md`,
+  `.cursor/`); `warmtree skill` does the same on demand and never overwrites
+  an edited copy without `--force`. The rule: when an isolated workspace is needed,
+  run `warmtree take <branch>` and `cd` into the printed path instead of
+  `git worktree add`; when done and merged, `warmtree release <branch>`.
+  Before that, `warmtree which` tells the agent whether it is already in a
+  slot, and `warmtree size` tells it whether enough slots are ready for the
+  parallel work it is about to start, and grows the pool if not.
+- `AGENTS.md` paragraph in the README for projects that use that convention.
+- Note in the README that Claude Code's native worktree feature is not
+  intercepted; the skill is the integration.
+
+### Out (v1)
+- Port allocation beyond the `WARMTREE_SLOT` variable. Subdomain routing.
+  Merging, PR creation, branch listing. Any GUI or TUI. Daemon mode. Shared
+  dependency stores. Windows junction tricks for `node_modules`.
+
+## Architecture
+
+```
+warmtree/
+  __init__.py
+  cli.py        argparse entry point, one function per command
+  config.py     load/validate .warmtree.toml, defaults
+  git.py        thin subprocess wrapper: worktree add/remove, fetch, ff, status
+  pool.py       slot lifecycle: fill, take, release, refresh, state persistence
+  lock.py       cross-platform file lock
+  warm.py       run commands, copy files, hash lockfiles, inject WARMTREE_SLOT
+  skill.py      detect coding-agent folders, install the bundled SKILL.md
+  skills/warmtree/SKILL.md
+tests/          pytest against real temporary git repos (no mocks of git)
+```
+
+Key decisions and the reasoning behind each:
+- **Slots are detached worktrees parked on `base`.** A branch is only
+  created at `take`, so a slot is never "on" a branch anyone else is using,
+  and git's one-branch-per-worktree rule never bites the pool.
+- **Reset on release, do not delete.** Deleting and recreating throws away
+  the warm state; resetting keeps `node_modules` and friends intact. Lockfile
+  hashes decide whether a re-warm is needed.
+- **Fallback to cold create.** An empty pool is a slow path, never an error.
+  Agents should never fail because the pool drained.
+- **State in one JSON file with a lock, not SQLite.** Dozens of slots at
+  most; simplest thing that is correct under concurrent `take`.
+- **Standard library only.** The tool has to run before the project's own
+  dependencies exist; that is the whole point.
+
+## Build order
+
+| # | Deliverable | Done when |
+|---|---|---|
+| 1 | config, git wrapper, `init`, `fill`, `status`, tests on temp repos, CI on ubuntu + windows | `fill` creates N detached slots in a temp repo; CI green on both OSes |
+| 2 | `take` with file lock and refill, `release` with reset, `remove`, fallback path | Two concurrent `take` calls get two slots (test); `release` returns a slot to ready |
+| 3 | `warm`: run commands, copy files, lockfile hashing, `refresh`, `WARMTREE_SLOT` | Changing a lockfile makes `refresh` re-run `run` in every slot, unchanged lockfile skips |
+| 4 | SKILL.md, AGENTS.md, README with GIF and worktrunk workflow, trusted publishing to PyPI, tag v0.1.0 | `uvx warmtree status` works on a clean machine; Claude Code takes a slot via the skill |
+
+## Acceptance criteria (v0.1.0)
+- 25+ tests against real git repos, green in CI on Ubuntu and Windows.
+- `take` returns a ready slot in under 1 second on a repo whose `npm ci` takes minutes (measured in the README).
+- Concurrency test in step 2 passes.
+- Zero runtime dependencies; `pyproject.toml` `dependencies = []`.
+- PyPI release published from GitHub Actions via trusted publishing; no API token stored locally.
+
+## Before publishing
+Use it on a large real repo with `size = 2` for a week before the first
+release. Every papercut found goes in IDEAS.md; only bugs are fixed before
+v0.1.0.

warmtree-0.1.0/IDEAS.md

@@ -0,0 +1,11 @@
+# Ideas
+
+Things that came up while building warmtree and are out of scope for v1.
+Append here instead of expanding DESIGN.md.
+
+- **Stream warm output.** `run` output is captured and shown only on failure
+  so `take` keeps stdout clean. A `--verbose` flag on `fill` and `refresh`
+  could stream it to stderr for a first-time `npm ci` that takes minutes.
+- **`refresh --fetch`.** `refresh` moves slots to the local base tip. It could
+  run `git fetch` first, or accept `base = "origin/main"`, which already works
+  because the base is resolved with `rev-parse`.

warmtree-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dan Collier
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

warmtree-0.1.0/PKG-INFO

@@ -0,0 +1,279 @@
+Metadata-Version: 2.5
+Name: warmtree
+Version: 0.1.0
+Summary: A pool of pre-warmed git worktrees for parallel AI coding agents.
+Project-URL: Homepage, https://github.com/dcolliervb23/warmtree
+Author: Dan Collier
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agents,developer-tools,git,worktree
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Version Control :: Git
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# warmtree
+
+A pool of pre-warmed git worktrees for parallel AI coding agents.
+
+`git worktree add` is fast. Everything after it is slow: installing
+dependencies, rebuilding caches, copying the `.env` files git does not track.
+On a large repo that cold start is minutes, and with several agents working in
+parallel you pay it several times a day. warmtree keeps a few worktrees already
+checked out, warmed, and ready, so `warmtree take <branch>` hands you a
+workspace in under a second.
+
+![warmtree demo](docs/demo.gif)
+
+Measured on a private TypeScript app (457 packages, 664 MB of node_modules):
+a cold `git worktree add` + `npm ci` took 6.6 s even with a fast machine and
+network; `warmtree take` handed over a warm slot in 0.15 s.
+
+warmtree owns the **create** and **release** steps only. Everything in between
+is ordinary git, so your editor, hooks, and other worktree tools work on a
+pooled worktree unchanged.
+
+## Status
+
+Early. Stable enough to dogfood, and dogfooded daily on a large private repo.
+
+## Install
+
+Requires Python 3.12+ and git. No other runtime dependencies.
+
+From a clone, for dogfooding while the code is still changing:
+
+```sh
+uv tool install --editable .
+```
+
+Or straight from GitHub:
+
+```sh
+uv tool install git+https://github.com/dcolliervb23/warmtree
+```
+
+Or from PyPI: `uvx warmtree` works on a machine with nothing but Python
+and git.
+
+## Quick start
+
+Run these from inside the repo you want to pool.
+
+```sh
+warmtree init          # writes .warmtree.toml with defaults
+# edit .warmtree.toml: add your install command to [warm] run
+warmtree fill          # creates and warms the slots, two by default
+warmtree status        # see them
+```
+
+Take a slot when you need an isolated workspace, work in it, then release it:
+
+```sh
+cd "$(warmtree take feature/login)"   # bash / zsh
+# ... commit, push, open a PR ...
+warmtree release feature/login
+```
+
+PowerShell:
+
+```powershell
+cd (warmtree take feature/login)
+warmtree release feature/login
+```
+
+`take` prints only the slot path on stdout. Everything else it says goes to
+stderr, so the `cd` idiom works.
+
+Keep slots current with a nightly `warmtree refresh` from cron or Task
+Scheduler, after whatever pulls your base branch.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `warmtree init [--force] [--no-skill]` | Write a starter `.warmtree.toml`. Pre-fills `lockfiles` from what it finds in the repo. Never guesses your install command. Installs the agent skill for any coding agent it detects. |
+| `warmtree skill [--tool T] [--force]` | Install or refresh the agent skill in the tool folders this repo uses, or in the ones named with `--tool`. Never overwrites an edited copy without `--force`. |
+| `warmtree fill` | Create slots until `size` are ready. Each slot is a worktree with a detached HEAD at the base branch, with `copy` files copied in and `run` commands executed. |
+| `warmtree take <branch> [--from REF]` | Claim the oldest ready slot. Creates `<branch>` there (from `REF` or the base branch) or checks it out if it already exists. Prints the path, then refills the pool. |
+| `warmtree take ... --no-refill` | Skip the refill. |
+| `warmtree take ... --refill-background` | Refill in a detached process and return immediately. |
+| `warmtree release <branch> [--keep-branch] [--force]` | Park the slot back on the base branch and mark it ready. Refuses a dirty tree unless `--force`. Deletes the branch if it is merged; an unmerged branch is always kept. |
+| `warmtree refresh` | Move every waiting slot to the current base commit and re-copy files. Re-runs `run` only in slots whose lockfile hashes changed or whose last warm failed. Skips taken slots. |
+| `warmtree size [N]` | Show the configured size and a count of slots by state. With `N`, write the new size to `.warmtree.toml` and grow or shrink the pool to match. Shrinking removes ready slots only. |
+| `warmtree which` | Name the slot the current directory is inside, as `slot-N <state> <branch>`. Exit 1 if not in a slot. |
+| `warmtree remove [SLOT...] [--all] [--force]` | Delete slots and their worktree registrations. Taken slots need `--force`. |
+| `warmtree status [--json]` | Table of slots: name, state, branch, age, last warm, path. `--json` for scripts and agents. |
+
+Slot states:
+
+- `ready`: parked on base, warm, free to take.
+- `taken`: a branch is checked out and someone is working in it.
+- `warming`: `run` commands are executing right now, in `fill` or `refresh`.
+- `stale`: the last warm failed. `refresh` retries it. `take` never hands out a
+  stale slot.
+
+If no slot is ready, `take` falls back to a normal `git worktree add`, tells
+you on stderr, and the new worktree joins the pool as a taken slot. An empty
+pool is a slow path, never an error.
+
+## Configuration
+
+`.warmtree.toml` at the repo root. Every key has a default; an empty file or
+no file at all means a pool of two on the repo's default branch with nothing
+to warm.
+
+```toml
+[pool]
+size = 2                       # slots to keep ready; taken slots do not count
+# base = "main"                # branch slots park on; default: the repo's default branch
+# dir = "../.warmtree/app"     # where slots live; default: ../.warmtree/<repo name>
+lockfiles = ["package-lock.json", "uv.lock"]  # re-warm only when one of these changes
+
+[warm]
+run = ["npm ci"]               # commands run inside a slot at fill and refresh time
+copy = [".env", ".env.local"]  # untracked files copied from the main worktree
+env = true                     # write WARMTREE_SLOT=<n> into the copied env files
+```
+
+Details worth knowing:
+
+- `run` commands go through the shell, in order, inside the slot, with
+  `WARMTREE_SLOT=<n>` in the environment. Output is captured and shown only
+  when a command fails. warmtree has no idea what npm or dotnet are; you do.
+- `copy` paths are relative to the repo root. Files missing from the main
+  worktree are skipped. With `env = true`, copied files named like `.env`,
+  `.env.local`, or `app.env` get a `WARMTREE_SLOT=<n>` line appended, so your
+  project can derive a per-slot port or database name from it.
+- `lockfiles` are hashed inside the slot after each warm. `refresh` re-runs
+  `run` only when a hash differs.
+- `warmtree size N` edits the `size` line in place. Your comments and other
+  keys are left alone.
+- Unknown keys are errors, so a typo never silently disables warming.
+
+## Using it with coding agents
+
+warmtree ships an [Agent Skill](https://agentskills.io): a short set of
+instructions an agent loads when the task calls for an isolated workspace. It
+tells the agent to check whether it is already in a slot (`warmtree which`),
+check capacity before fanning out (`warmtree size`), take a slot instead of
+running `git worktree add`, and release it when the branch is merged.
+
+`warmtree init` installs it automatically wherever it sees signs of a coding
+agent in the repo, and prints each path it wrote:
+
+| Found in the repo | Skill installed at |
+|---|---|
+| `CLAUDE.md` or `.claude/` | `.claude/skills/warmtree/SKILL.md` (Claude Code) |
+| `.github/copilot-instructions.md` | `.github/skills/warmtree/SKILL.md` (GitHub Copilot) |
+| `AGENTS.md` or `.agents/` | `.agents/skills/warmtree/SKILL.md` (Codex and others) |
+| `.cursor/` | `.cursor/skills/warmtree/SKILL.md` (Cursor) |
+
+Commit those folders so every agent on the project gets the skill. To install
+for a tool that was not detected, or to refresh the copies after upgrading
+warmtree:
+
+```sh
+warmtree skill --tool claude        # claude, copilot, codex, or cursor; repeatable
+warmtree skill                      # re-detect and refresh
+warmtree skill --force              # replace a copy you edited by hand
+```
+
+A copy you have edited is never overwritten without `--force`. Pass
+`--no-skill` to `init` to skip all of this.
+
+If your project uses an `AGENTS.md` instead, this paragraph is enough:
+
+> This repo has a warmtree pool. When you need an isolated workspace, run
+> `warmtree take <branch>` and `cd` into the printed path instead of
+> `git worktree add`. Run `warmtree which` first to see if you are already in
+> a slot, and `warmtree size` to check how many are ready before starting
+> parallel work. When the branch is merged, run `warmtree release <branch>`.
+
+Claude Code's built-in worktree feature is not intercepted. The skill is the
+integration.
+
+## With worktrunk
+
+[worktrunk](https://github.com/max-sixty/worktrunk) covers the rest of the
+worktree lifecycle: hooks, port allocation, cleanup of merged branches. The two
+fit together because warmtree only touches create and release.
+
+- Use `warmtree take` instead of `wt switch --create` to get a warm checkout.
+- Inside the slot, worktrunk's commands work as they do in any worktree.
+- When the branch is merged, run `warmtree release <branch>` rather than
+  worktrunk's remove, so the slot goes back to the pool instead of being
+  deleted.
+
+## How it works
+
+- **Slots are detached worktrees parked on the base branch.** A branch is only
+  created at `take`, so a slot is never on a branch someone else is using and
+  git's one-branch-per-worktree rule never bites the pool.
+- **Release resets, it does not delete.** `release` checks out the base
+  branch detached and runs `git clean -fd`, which removes untracked files but
+  keeps ignored ones. `node_modules`, `.venv`, and friends survive, so the slot
+  is still warm for the next take.
+- **Warming never holds the lock.** A slot is marked `warming` under the pool
+  lock, the slow commands run with the lock released, and the result is
+  written under the lock again. A three-minute `npm ci` in one slot never
+  blocks `take` on another.
+- **State is one JSON file with a file lock.** `state.json` lives in the pool
+  directory and is rewritten atomically. `take` holds an OS file lock while it
+  picks a slot, so two agents calling `take` at the same moment get two
+  different slots.
+- **Standard library only.** warmtree has to run before your project's own
+  dependencies exist. That is the whole point.
+
+The pool directory defaults to a sibling of your repo named after it, for
+example `~/dev/.warmtree/myapp/slot-1`, so repos that share a parent folder
+never share a pool.
+
+## Development
+
+```sh
+uv sync                        # creates .venv with Python 3.12, pytest, ruff
+uv run pytest -q               # the whole suite, about a minute
+uv run ruff check .
+uv run ruff format --check .
+```
+
+Those three commands are exactly what CI runs on Ubuntu and Windows. Tests
+create real temporary git repos; nothing about git is mocked, so `git` must
+be on your PATH.
+
+Useful variations:
+
+```sh
+uv run pytest -q tests/test_lifecycle.py   # one file
+uv run pytest -q -k concurrent             # tests whose name matches
+uv run pytest -x                           # stop at the first failure
+uv run pytest -v                           # show every test name
+uv run ruff format .                       # fix formatting instead of checking
+```
+
+### Releasing
+
+Releases go to PyPI through GitHub Actions trusted publishing; no API token is
+stored anywhere. One-time setup on pypi.org: add a trusted publisher for owner
+`dcolliervb23`, repository `warmtree`, workflow `publish.yml`, environment
+`pypi`. Then:
+
+```sh
+uv version 0.1.0            # sets the version in pyproject.toml
+git commit -am "chore: release 0.1.0"
+git tag v0.1.0
+git push && git push --tags
+```
+
+The workflow refuses to publish if the tag and the package version disagree.
+
+## License
+
+MIT