workforest 0.5.0__tar.gz → 0.5.2__tar.gz

{workforest-0.5.0 → workforest-0.5.2}/.claude/rules/architecture.md

@@ -19,3 +19,15 @@
   environment variables, or exit codes updates both README.md and the
   affected page in the same change. `tests/test_man.py` catches drift from
   `cli.py`, not from prose — keep the wording in sync by hand.
+- Script groups (`hooks.py`): a `bulk`/`pipeline` runs under a forked
+  supervisor that leads the process group and takes the tty exactly like a
+  command, so records, `wf stop`, `exclusive`, `cleanup`, and `-b` need no
+  group-specific code. Bulk members must never take the tty (only one
+  group can own it); they run in the supervisor's process group so a
+  signal to the group reaches them all, write to a pty when stderr is a
+  terminal (so their programs keep colors) and to a pipe otherwise, and
+  the supervisor relays their lines prefixed. A bulk always waits for
+  every member. An outcome of `-SIGINT` or exit 130 is an interruption
+  (warning, `wf` dies by SIGINT), never a failure. Forked-child bodies are
+  `# pragma: no cover`; the logic lives in tested pure helpers
+  (`_Prefixer`, `_pump`, `_bulk_outcome`, `_run_step`).

{workforest-0.5.0 → workforest-0.5.2}/.github/workflows/ci.yml

@@ -49,3 +49,7 @@ jobs:
           # puts that directory on $MANPATH for venv installs
           MANPATH=/tmp/venv/share/man man -w workforest wf 5 workforest wf
           /tmp/venv/bin/workforest shell-init bash | grep -q 'MANPATH=/tmp/venv/share/man'
+          # the init starter is package data too
+          git init -q /tmp/repo
+          (cd /tmp/repo && /tmp/venv/bin/workforest init)
+          test -s /tmp/repo/.workforest.yaml

{workforest-0.5.0 → workforest-0.5.2}/.github/workflows/publish_aur.yml

@@ -3,11 +3,18 @@ name: Publish to AUR
 on:
   release:
     types: [published]
+  workflow_dispatch:
+    inputs:
+      version:
+        description: "Release version to publish (e.g. 0.2.1)"
+        required: true
 
 jobs:
   publish:
     runs-on: ubuntu-latest
     container: archlinux:latest
+    env:
+      RELEASE_VERSION: ${{ github.event_name == 'workflow_dispatch' && inputs.version || github.ref_name }}
     environment:
       name: aur
       url: https://aur.archlinux.org/packages/workforest
@@ -15,15 +22,18 @@ jobs:
       contents: read
     steps:
       - name: Install system dependencies
-        run: >
-          pacman -Syu --noconfirm base-devel git openssh pacman-contrib namcap man-db
-          python python-yaml python-build python-installer python-wheel python-hatchling
+        run: |
+          # The archlinux image drops man pages at install time
+          # (NoExtract = usr/share/man/*); the smoke test below needs them.
+          sed -i '/^NoExtract.*usr\/share\/man/d' /etc/pacman.conf
+          pacman -Syu --noconfirm base-devel git openssh pacman-contrib namcap man-db \
+            python python-yaml python-build python-installer python-wheel python-hatchling
 
       - uses: actions/checkout@v4
 
       - name: Render PKGBUILD from template
         run: |
-          version="${GITHUB_REF_NAME#v}"
+          version="${RELEASE_VERSION#v}"
           cd packaging/AUR
           sed "s/@VERSION@/$version/g" PKGBUILD.template > PKGBUILD
           # makepkg refuses to run as root
@@ -47,7 +57,7 @@ jobs:
         env:
           AUR_SSH_PRIVATE_KEY: ${{ secrets.AUR_SSH_PRIVATE_KEY }}
         run: |
-          version="${GITHUB_REF_NAME#v}"
+          version="${RELEASE_VERSION#v}"
           # Explicit paths only: ssh resolves ~ from the passwd entry (/root),
           # while the shell resolves it from $HOME (/github/home) — they differ
           # in container jobs. Host keys are pinned rather than keyscanned.

{workforest-0.5.0 → workforest-0.5.2}/.github/workflows/publish_homebrew.yml

@@ -48,7 +48,7 @@ jobs:
           test -f "$(brew --prefix)/share/man/man1/wf.1"
           test -f "$(brew --prefix)/share/man/man5/workforest.5"
           test -f "$(brew --prefix)/share/man/man5/wf.5"
-          # the formula relocates them, so shell-init must not touch MANPATH
+          # the formula moves them out of the venv, so shell-init must not touch MANPATH
           ! workforest shell-init bash | grep -q MANPATH
 
       - name: Push to tap

{workforest-0.5.0 → workforest-0.5.2}/.gitignore

@@ -1,3 +1,7 @@
+# IDE
+.vscode
+.idea
+
 # Python
 __pycache__/
 *.pyc
@@ -21,4 +25,4 @@ packaging/AUR/.SRCINFO
 packaging/homebrew/workforest.rb
 
 # Tooling config
-.workforest.yaml
+/.workforest.yaml

{workforest-0.5.0 → workforest-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: workforest
-Version: 0.5.0
+Version: 0.5.2
 Summary: Git worktree forest management: create, open, and clean up per-branch worktrees with project-defined setup hooks
 Project-URL: Homepage, https://github.com/ArkadyBuryakov/workforest
 Author-email: Arkady Buryakov <arkady@buryakov.pro>
@@ -18,6 +18,13 @@ Requires-Python: >=3.14
 Requires-Dist: pyyaml>=6.0
 Description-Content-Type: text/markdown
 
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ArkadyBuryakov/workforest/HEAD/assets/logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/ArkadyBuryakov/workforest/HEAD/assets/logo-light.svg" alt="Workforest logo" width="160">
+  </picture>
+</p>
+
 # Workforest
 
 ## Elevator pitch
@@ -71,11 +78,12 @@ line to your `~/.bashrc` / `~/.zshrc`:
 eval "$(workforest shell-init)"
 ```
 
-This upgrades `wf` to a shell function (needed so `wf open` can change your
-shell's directory — a plain binary cannot), registers completions, and — for
-`uv tool`/`pipx` installs, whose files live in a venv — puts the man pages on
-`$MANPATH`. Without it everything still works, but "open in current shell"
-prints the `cd` command instead of performing it.
+This upgrades both `workforest` and `wf` to one shell function (needed so
+`open` can change your shell's directory — a plain binary cannot; either
+spelling, or an alias of either, behaves the same), registers completions,
+and — for `uv tool`/`pipx` installs, whose files live in a venv — puts the
+man pages on `$MANPATH`. Without it everything still works, but "open in
+current shell" prints the `cd` command instead of performing it.
 
 Reference: `man workforest` (commands) and `man 5 workforest` (the
 configuration files); `wf` works in place of `workforest` for both.
@@ -110,8 +118,9 @@ Layered, YAML or JSON; later layers override earlier ones:
 
 Scalars and lists replace; the `openers`/`wrappers`/`scripts` mappings
 merge per key (`null` removes an entry). `workforest config` shows the
-merged result and where each layer came from; `workforest init` scaffolds a
-project file (`--local` for a personal one). Nothing in the environment
+merged result and where each layer came from; `workforest init` writes a
+short, fully commented starter (`--local` for a personal one) — inert until
+you uncomment something. Nothing in the environment
 changes the result — files and flags only.
 
 All keys, with defaults:
@@ -124,14 +133,14 @@ openers: {}             # name -> what `-o NAME` runs, and where
 wrappers: {}            # name -> command that runs $WF_COMMAND elsewhere (window, pane, direnv)
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
-scripts: {}             # name -> command for `wf run NAME` (or a mapping, see Scripts)
+scripts: {}             # name -> command or group for `wf run NAME` (see Scripts)
 stop_timeout: 30        # seconds a stopped script gets after SIGTERM before SIGKILL
 ```
 
 ### Openers
 
 An opener is a shell command that runs with the worktree root as working
-directory, either **in your terminal** (the default: the `wf` wrapper does
+directory, either **in your terminal** (the default: the shell function does
 `cd` there and runs it) or **in the background** (`background: true`:
 spawned detached, `wf` returns immediately — for GUI apps and commands that
 hand off to a daemon or multiplexer). Optionally it runs **through a
@@ -215,7 +224,7 @@ installed to `/usr/share/doc/workforest/examples/` by the Arch package.
 
 `wf run NAME [ARGS...]` runs a `scripts` entry from the root of the current
 worktree, with any extra arguments shell-quoted and appended. An entry is a
-shell command string, or a mapping:
+shell command string, a mapping, or a group of other entries (see below):
 
 ```yaml
 scripts:
@@ -236,9 +245,10 @@ terminal, so Ctrl-C and Ctrl-Z reach it directly; a signal sent to `wf`
 itself (SIGINT, SIGTERM, SIGHUP) is forwarded to the whole group. `cleanup`
 then runs — after a normal exit, a failure, or a kill — in the same
 worktree with the same `WF_*` variables. `wf run` fails with the command's
-status, or `128+N` when the command was killed by signal N; a command
-killed by SIGINT ends `wf` the way Ctrl-C would, so a shell loop around it
-aborts.
+status, or `128+N` when the command was killed by signal N. A command
+killed by SIGINT — or exiting 130, as a shell does once its child was — is
+reported as interrupted, a warning rather than an error, and ends `wf` the
+way Ctrl-C would, so a shell loop around it aborts.
 
 A `background` script (or `wf run -b NAME`) is detached instead: it runs
 under a supervisor of its own — the same process-group and cleanup
@@ -267,6 +277,48 @@ orphan) is stopped and cleaned up by whoever stops it when `/proc`
 confirms the pid was not recycled; elsewhere it is reported and left
 alone.
 
+#### Groups
+
+A `bulk` entry runs other entries at once; a `pipeline` entry runs them one
+after another. Members are named, not written inline, so each keeps its own
+`exclusive`, `cleanup`, and `stop_timeout`, and a group may name another
+group (cycles are a config error):
+
+```yaml
+scripts:
+  migrate: npm run db:migrate
+  dev:
+    bulk: [backend, frontend]     # both at once; done when both have ended
+  fresh:
+    pipeline: [migrate, dev]      # in order; the first failure ends it
+    background: true
+```
+
+A group is a script like any other: `wf run -b`, `background`,
+`exclusive`, and `cleanup` apply to it, and `wf stop GROUP` stops every
+member, waits for all their cleanups, then runs the group's own. A group
+takes no extra arguments; its `stop_timeout` defaults to the longest of
+its members'. Members stay individually visible: `wf stop MEMBER` stops
+that member out from under a running group, and a member already running
+in the worktree fails its step.
+
+A pipeline's steps run like consecutive `wf run`s, each with the
+terminal; a `background` member is started and left running while the
+pipeline moves on. The pipeline ends with the first failing step's status.
+
+A bulk relays its members' output line by line, each line prefixed with
+the member's name:
+
+```
+backend  | Attaching to db-1, api-1
+frontend | VITE v5.4  ready in 312 ms
+backend  | api-1 | listening on :8000
+```
+
+Members cannot read the terminal, but Ctrl-C reaches them all. A bulk
+waits for every member — so `bulk: [lint, test, typecheck]` shows every
+failure, not just the first — and fails if any of them did.
+
 ### Script environment
 
 `setup_scripts`, `scripts`, and hooks run via `$SHELL -c` with:
@@ -303,6 +355,10 @@ scripts:
     background: true
     cleanup: docker compose down
     stop_timeout: 60
+  dev:
+    bulk: [backend, frontend]
+  fresh:
+    pipeline: [migrate, dev]
 ```
 
 ## Commands
@@ -310,7 +366,7 @@ scripts:
 ```
 workforest create [BRANCH] [-o OPENER] [-w WRAPPER] [-p PATH] [--no-hooks] [--no-open]
 workforest open   [NAME]   [-o OPENER] [-w WRAPPER] [-p PATH]
-workforest list   [--porcelain]
+workforest list   [--porcelain | --json]
 workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
 workforest checkout NAME   [--force]
 workforest run    [-b] SCRIPT [ARGS...]
@@ -338,7 +394,11 @@ which is not a stable interface, so any Claude Code update may break it.
 Exit codes: `0` ok · `1` error · `2` usage · `3` cancelled · `4` config error
 · `128+N` the `run` command was killed by signal N.
 Human messages go to stderr; stdout carries only machine output (`cd`
-directives for the `wf` wrapper, `--porcelain` listings, dumps).
+directives for the shell function, `--porcelain`/`--json` listings, dumps).
+`list --json` describes the whole forest for programs — `main` (the main
+checkout, in the same `name`/`branch`/`path`/`dirty` shape as each entry of
+`worktrees`) and the resolved `worktrees_dir` — for editor integrations
+and other programs.
 
 ## Development
 
@@ -353,7 +413,7 @@ Man pages are hand-written roff under `man/` (`workforest.1` and
 `workforest.5`, plus `wf.1`/`wf.5` links to them); `tests/test_man.py` fails when they drift from
 `cli.py`. They ship as `share/man` data in the wheel, which is how every
 package gets them: the Arch package installs the wheel to `/usr`, the
-Homebrew formula relocates them out of its venv, and `uv tool`/`pipx` keep
+Homebrew formula moves them out of its venv, and `uv tool`/`pipx` keep
 them in the venv where `workforest shell-init` points `$MANPATH`.
 
 Packaging templates live under `packaging/` (one directory per package

{workforest-0.5.0 → workforest-0.5.2}/README.md

@@ -1,3 +1,10 @@
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ArkadyBuryakov/workforest/HEAD/assets/logo-dark.svg">
+    <img src="https://raw.githubusercontent.com/ArkadyBuryakov/workforest/HEAD/assets/logo-light.svg" alt="Workforest logo" width="160">
+  </picture>
+</p>
+
 # Workforest
 
 ## Elevator pitch
@@ -51,11 +58,12 @@ line to your `~/.bashrc` / `~/.zshrc`:
 eval "$(workforest shell-init)"
 ```
 
-This upgrades `wf` to a shell function (needed so `wf open` can change your
-shell's directory — a plain binary cannot), registers completions, and — for
-`uv tool`/`pipx` installs, whose files live in a venv — puts the man pages on
-`$MANPATH`. Without it everything still works, but "open in current shell"
-prints the `cd` command instead of performing it.
+This upgrades both `workforest` and `wf` to one shell function (needed so
+`open` can change your shell's directory — a plain binary cannot; either
+spelling, or an alias of either, behaves the same), registers completions,
+and — for `uv tool`/`pipx` installs, whose files live in a venv — puts the
+man pages on `$MANPATH`. Without it everything still works, but "open in
+current shell" prints the `cd` command instead of performing it.
 
 Reference: `man workforest` (commands) and `man 5 workforest` (the
 configuration files); `wf` works in place of `workforest` for both.
@@ -90,8 +98,9 @@ Layered, YAML or JSON; later layers override earlier ones:
 
 Scalars and lists replace; the `openers`/`wrappers`/`scripts` mappings
 merge per key (`null` removes an entry). `workforest config` shows the
-merged result and where each layer came from; `workforest init` scaffolds a
-project file (`--local` for a personal one). Nothing in the environment
+merged result and where each layer came from; `workforest init` writes a
+short, fully commented starter (`--local` for a personal one) — inert until
+you uncomment something. Nothing in the environment
 changes the result — files and flags only.
 
 All keys, with defaults:
@@ -104,14 +113,14 @@ openers: {}             # name -> what `-o NAME` runs, and where
 wrappers: {}            # name -> command that runs $WF_COMMAND elsewhere (window, pane, direnv)
 symlinks: []            # untracked assets linked from main into new worktrees
 setup_scripts: []       # shell snippets run in a fresh worktree
-scripts: {}             # name -> command for `wf run NAME` (or a mapping, see Scripts)
+scripts: {}             # name -> command or group for `wf run NAME` (see Scripts)
 stop_timeout: 30        # seconds a stopped script gets after SIGTERM before SIGKILL
 ```
 
 ### Openers
 
 An opener is a shell command that runs with the worktree root as working
-directory, either **in your terminal** (the default: the `wf` wrapper does
+directory, either **in your terminal** (the default: the shell function does
 `cd` there and runs it) or **in the background** (`background: true`:
 spawned detached, `wf` returns immediately — for GUI apps and commands that
 hand off to a daemon or multiplexer). Optionally it runs **through a
@@ -195,7 +204,7 @@ installed to `/usr/share/doc/workforest/examples/` by the Arch package.
 
 `wf run NAME [ARGS...]` runs a `scripts` entry from the root of the current
 worktree, with any extra arguments shell-quoted and appended. An entry is a
-shell command string, or a mapping:
+shell command string, a mapping, or a group of other entries (see below):
 
 ```yaml
 scripts:
@@ -216,9 +225,10 @@ terminal, so Ctrl-C and Ctrl-Z reach it directly; a signal sent to `wf`
 itself (SIGINT, SIGTERM, SIGHUP) is forwarded to the whole group. `cleanup`
 then runs — after a normal exit, a failure, or a kill — in the same
 worktree with the same `WF_*` variables. `wf run` fails with the command's
-status, or `128+N` when the command was killed by signal N; a command
-killed by SIGINT ends `wf` the way Ctrl-C would, so a shell loop around it
-aborts.
+status, or `128+N` when the command was killed by signal N. A command
+killed by SIGINT — or exiting 130, as a shell does once its child was — is
+reported as interrupted, a warning rather than an error, and ends `wf` the
+way Ctrl-C would, so a shell loop around it aborts.
 
 A `background` script (or `wf run -b NAME`) is detached instead: it runs
 under a supervisor of its own — the same process-group and cleanup
@@ -247,6 +257,48 @@ orphan) is stopped and cleaned up by whoever stops it when `/proc`
 confirms the pid was not recycled; elsewhere it is reported and left
 alone.
 
+#### Groups
+
+A `bulk` entry runs other entries at once; a `pipeline` entry runs them one
+after another. Members are named, not written inline, so each keeps its own
+`exclusive`, `cleanup`, and `stop_timeout`, and a group may name another
+group (cycles are a config error):
+
+```yaml
+scripts:
+  migrate: npm run db:migrate
+  dev:
+    bulk: [backend, frontend]     # both at once; done when both have ended
+  fresh:
+    pipeline: [migrate, dev]      # in order; the first failure ends it
+    background: true
+```
+
+A group is a script like any other: `wf run -b`, `background`,
+`exclusive`, and `cleanup` apply to it, and `wf stop GROUP` stops every
+member, waits for all their cleanups, then runs the group's own. A group
+takes no extra arguments; its `stop_timeout` defaults to the longest of
+its members'. Members stay individually visible: `wf stop MEMBER` stops
+that member out from under a running group, and a member already running
+in the worktree fails its step.
+
+A pipeline's steps run like consecutive `wf run`s, each with the
+terminal; a `background` member is started and left running while the
+pipeline moves on. The pipeline ends with the first failing step's status.
+
+A bulk relays its members' output line by line, each line prefixed with
+the member's name:
+
+```
+backend  | Attaching to db-1, api-1
+frontend | VITE v5.4  ready in 312 ms
+backend  | api-1 | listening on :8000
+```
+
+Members cannot read the terminal, but Ctrl-C reaches them all. A bulk
+waits for every member — so `bulk: [lint, test, typecheck]` shows every
+failure, not just the first — and fails if any of them did.
+
 ### Script environment
 
 `setup_scripts`, `scripts`, and hooks run via `$SHELL -c` with:
@@ -283,6 +335,10 @@ scripts:
     background: true
     cleanup: docker compose down
     stop_timeout: 60
+  dev:
+    bulk: [backend, frontend]
+  fresh:
+    pipeline: [migrate, dev]
 ```
 
 ## Commands
@@ -290,7 +346,7 @@ scripts:
 ```
 workforest create [BRANCH] [-o OPENER] [-w WRAPPER] [-p PATH] [--no-hooks] [--no-open]
 workforest open   [NAME]   [-o OPENER] [-w WRAPPER] [-p PATH]
-workforest list   [--porcelain]
+workforest list   [--porcelain | --json]
 workforest delete NAME...  [--force] [--delete-branch | --keep-branch]
 workforest checkout NAME   [--force]
 workforest run    [-b] SCRIPT [ARGS...]
@@ -318,7 +374,11 @@ which is not a stable interface, so any Claude Code update may break it.
 Exit codes: `0` ok · `1` error · `2` usage · `3` cancelled · `4` config error
 · `128+N` the `run` command was killed by signal N.
 Human messages go to stderr; stdout carries only machine output (`cd`
-directives for the `wf` wrapper, `--porcelain` listings, dumps).
+directives for the shell function, `--porcelain`/`--json` listings, dumps).
+`list --json` describes the whole forest for programs — `main` (the main
+checkout, in the same `name`/`branch`/`path`/`dirty` shape as each entry of
+`worktrees`) and the resolved `worktrees_dir` — for editor integrations
+and other programs.
 
 ## Development
 
@@ -333,7 +393,7 @@ Man pages are hand-written roff under `man/` (`workforest.1` and
 `workforest.5`, plus `wf.1`/`wf.5` links to them); `tests/test_man.py` fails when they drift from
 `cli.py`. They ship as `share/man` data in the wheel, which is how every
 package gets them: the Arch package installs the wheel to `/usr`, the
-Homebrew formula relocates them out of its venv, and `uv tool`/`pipx` keep
+Homebrew formula moves them out of its venv, and `uv tool`/`pipx` keep
 them in the venv where `workforest shell-init` points `$MANPATH`.
 
 Packaging templates live under `packaging/` (one directory per package

workforest-0.5.2/assets/logo-dark.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="26.677 49.555 48.277 47.922">
+  <path fill="#e6edf3" d="m 40.35,71.984 -10.673,17.25 14.26,0.002 -0.874,5.241 8.619,-0.001 -1.192,-5.47 6.692,0.001 -0.611,3.667 h 6.015 l -0.612,-3.667 9.98,-0.002 -7.47,-12.071 2.501,-0.041 -7.398,-13.555 -7.416,13.555 2.501,0.041 L 47.831,87.978 53.253156,77.719406 50.83,77.658 55.434,68.012 47.373,52.555 36.776,71.926 Z"/>
+</svg>

workforest-0.5.2/assets/logo-light.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="26.677 49.555 48.277 47.922">
+  <path fill="#1f2328" d="m 40.35,71.984 -10.673,17.25 14.26,0.002 -0.874,5.241 8.619,-0.001 -1.192,-5.47 6.692,0.001 -0.611,3.667 h 6.015 l -0.612,-3.667 9.98,-0.002 -7.47,-12.071 2.501,-0.041 -7.398,-13.555 -7.416,13.555 2.501,0.041 L 47.831,87.978 53.253156,77.719406 50.83,77.658 55.434,68.012 47.373,52.555 36.776,71.926 Z"/>
+</svg>

workforest-0.5.2/assets/logo.svg

@@ -0,0 +1,3 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="26.677 49.555 48.277 47.922">
+  <path fill="currentColor" d="m 40.35,71.984 -10.673,17.25 14.26,0.002 -0.874,5.241 8.619,-0.001 -1.192,-5.47 6.692,0.001 -0.611,3.667 h 6.015 l -0.612,-3.667 9.98,-0.002 -7.47,-12.071 2.501,-0.041 -7.398,-13.555 -7.416,13.555 2.501,0.041 L 47.831,87.978 53.253156,77.719406 50.83,77.658 55.434,68.012 47.373,52.555 36.776,71.926 Z"/>
+</svg>

{workforest-0.5.0 → workforest-0.5.2}/man/workforest.1

@@ -31,7 +31,7 @@ workforest, wf \- git worktree forest management
 .IR PATH ]
 .YS
 .SY "workforest list"
-.RB [ \-\-porcelain ]
+.RB [ \-\-porcelain " | " \-\-json ]
 .YS
 .SY "workforest delete"
 .IR NAME .\|.\|.
@@ -106,7 +106,7 @@ After
 .B shell-init
 (see
 .BR "SHELL INTEGRATION" )
-it is a shell function that can change the calling shell's directory.
+both are one shell function that can change the calling shell's directory.
 .SH COMMANDS
 .SS create [\fIBRANCH\fR]
 Create (or reuse) a worktree for
@@ -188,6 +188,23 @@ and
 (dirty) or
 .B 0
 (clean), separated by tabs.
+.TP
+.B \-\-json
+The whole forest as a JSON object, for editor integrations and other
+programs:
+.B main
+(the main checkout) and each entry of
+.B worktrees
+carry
+.BR name ,
+.B branch
+(null when detached),
+.BR path ,
+and
+.B dirty
+(true/false);
+.B worktrees_dir
+is the resolved worktrees directory.
 .SS delete \fINAME\fR...
 Delete one or more worktrees.
 Every name is resolved before anything is removed, so a typo fails the
@@ -216,7 +233,14 @@ Skip the dirty-worktree confirmation.
 Run the named script from the merged configuration's
 .B scripts
 map, from the root of the current worktree.
-Extra arguments are shell-quoted and appended to the script command.
+Extra arguments are shell-quoted and appended to the script command (a
+group \(em a
+.B bulk
+or
+.B pipeline
+entry, see
+.BR workforest (5)
+\(em takes none).
 See
 .B ENVIRONMENT
 for the variables scripts receive.
@@ -239,10 +263,17 @@ while it is already running in this worktree (see
 .BR stop ).
 The exit status is the command's, or 128+\fIN\fR when it was killed by
 signal
-.IR N ;
-a command killed by SIGINT ends
+.IR N .
+A command killed by SIGINT \(em or exiting 130, as a shell does once its
+child was \(em is reported as interrupted, a warning rather than an
+error, and ends
 .B workforest
 by SIGINT as well, so a shell loop around it aborts.
+A group runs under a supervisor that takes the command's place in all of
+the above: a pipeline runs its members in order and ends with the first
+failing step's status; a bulk runs them at once, relays their output with
+the member's name as a line prefix, and ends with the first failing
+member's status once all have ended.
 .TP
 .BR \-b ", " \-\-background
 Detach instead: the command runs under a supervisor of its own with its
@@ -265,6 +296,9 @@ foreground or background, started from any terminal \(em with SIGTERM,
 then SIGKILL after
 .B stop_timeout
 seconds, and wait for its cleanup to finish.
+For a group this stops every member and waits for all of their cleanups,
+then the group's own; a member can also be stopped by name out from
+under a running group.
 Fails when nothing is running.
 .TP
 .B \-\-all
@@ -314,9 +348,12 @@ The
 .B delete
 tab stays open after each deletion for bulk cleanup.
 .SS init
-Scaffold a fully commented
+Write a short, fully commented
 .B .workforest.yaml
-project configuration in the main checkout.
+starter in the main checkout. Every key is commented out, so the file
+changes nothing until edited; see
+.BR workforest (5)
+for the reference.
 .TP
 .B \-\-local
 Place it in
@@ -359,15 +396,14 @@ A subprocess cannot change its parent shell's directory, so add to your
 eval "$(workforest shell-init)"
 .EE
 .PP
-This defines
-.B wf
-as a shell function that runs
-.B workforest
-and evaluates the directive it prints (a
+This defines both
+.BR workforest " and " wf
+as one shell function that runs the workforest binary and evaluates the
+directive it prints (a
 .B cd
-into the worktree, followed by the opener command); registers tab
-completion for both
-.BR wf " and " workforest ;
+into the worktree, followed by the opener command), so either spelling
+\(em or an alias of either \(em behaves the same; registers tab
+completion for both;
 and, when workforest was installed into a Python environment whose
 manual pages are not on the default search path (a
 .B uv tool
@@ -499,7 +535,6 @@ command was killed by signal
 .PP
 Human-readable messages go to stderr.
 Stdout carries only machine output: directives for the
-.B wf
 shell function, listings, and configuration dumps.
 .SH EXAMPLES
 .TP