Final docs pass before #120: docs vs code, CHANGELOG, What's new 6 (T319)

CHANGELOG.md

@@ -27,7 +27,8 @@ first added in the same Unreleased section is not an entry: edit that entry inst
 - `m` on the cleanup card merges the task's pull request with `gh`, then completes the task and cleans up. `[merge] method` in `config.toml` picks the method; CLI: `--merge`.
 - Block with a reason: `ctrl+b` asks why and what you need. Answer on the task page, under the row (`r`), or with `tsk reply`. Unblocking sends replies to the agent.
 - Review with checks: `ctrl+r` asks what was done and what to check. Mark checks, give feedback (`r`, `tsk reply`), then approve (`ctrl+d`) or send back (`ctrl+s`).
-- Change who a block or review waits on, keeping its replies: `Enter` on its top line, palette **set waiting on…**, or `tsk edit --on`.
+- Change who a block or review waits on, keeping its replies: `w` on its task page, palette **set waiting on…**, or `tsk edit --on`.
+- A blocked or review row addressed to you shows the asker's words on a dim line under it. `z` hides these lines, leaving `✉`; `[board] messages` sets the default.
 - Paper trail: the task page lists who did what, newest first, below the steps, and drops created and updated dates from its footer. `tsk list T12` shows it as `activity`.
 - After: a task can wait for other tasks in any project (`!w T202`, the After field, `tsk edit --after`). When the last one is done, a waiting ready task starts.
 - Agents block and hand back for review with `tsk status`, and use `tsk dispatch`, `tsk clean`, and `tsk reply`. Agent skill 1.6.0 covers them; `tsk update` refreshes installed copies.
@@ -60,7 +61,6 @@ first added in the same Unreleased section is not an entry: edit that entry inst
 - `Esc` on a selected Thread on the task page cancels only the thread, not the whole edit.
 - `ctrl+x` in a new step's row discards that row, instead of removing the step above it or deleting a task.
 - `tsk steps` takes `--` before step text that starts with `-`, as `tsk reply` does.
-- `tsk restore` of an older version keeps task numbering going, so new tasks never reuse a number a deleted task still holds.
 - `tsk trash restore` gives a task the next free number when another task holds its old one, so no two tasks share a number.
 - `tsk capture --state-dir <dir>` saves into that store instead of the default one; any other argument is refused.
 

README.md

@@ -72,8 +72,9 @@ herdr server reload-config
 
 ### Give your agent the skill
 
-The skill teaches your agent to read the board, add tasks, and update their status
-and steps:
+Two skills: `tsk-cli` teaches your agent to read the board, add tasks, and update
+their status and steps. `tsk-coordinator` lets it brief builder agents, review their
+pull requests, and report back on the board:
 
 ```sh
 tsk setup

packaging/README.md

@@ -105,10 +105,16 @@ python3 scripts/release.py assemble <tag> <output-directory>
      that installer from `releases/download/vX.Y.Z/` instead.
    - Smoke `tsk setup herdr` under isolated roots ([AGENTS.md](../AGENTS.md#isolated-state)).
    - Rehearse the update path against a throwaway `HOME` holding an outdated skill and a
-     Herdr config on a custom key:
+     Herdr config on a custom key. Isolate every root the update touches: `HOME`,
+     `TSK_STATE_DIR`, `HERDR_CONFIG_PATH`, `XDG_CONFIG_HOME`, `XDG_STATE_HOME`, and
+     `HERDR_SOCKET_PATH`. Any one left out lets the refresh reach the daily Herdr plugin,
+     skills, or store:
 
      ```sh
-     env HOME=/tmp/x/home XDG_CONFIG_HOME=/tmp/x/home/.config HERDR_SOCKET_PATH=/tmp/x/none.sock \
+     env HOME=/tmp/x/home TSK_STATE_DIR=/tmp/x/state \
+       HERDR_CONFIG_PATH=/tmp/x/home/.config/herdr/config.toml \
+       XDG_CONFIG_HOME=/tmp/x/home/.config XDG_STATE_HOME=/tmp/x/home/.local/state \
+       HERDR_SOCKET_PATH=/tmp/x/none.sock \
        TSK_VERSION=vX.Y.Z TSK_UPDATE=1 TSK_CURRENT_VERSION=vPREV TSK_INSTALL_DIR=/tmp/x/bin \
        sh /tmp/x/install.sh
      ```

site/public/llms.txt

@@ -29,7 +29,7 @@ The human works the board in a TUI; agents read and write the same tasks with th
 
 - Run `tsk guide` first: it prints the workflow and the rules. `tsk help <command>` is the syntax reference.
 - Read with `tsk list --json`. `tsk list T12 --json` returns one task in full: notes, steps, block, review, dispatch, and `activity`.
-- Write with `tsk add`, `tsk edit`, and `tsk steps`. Read the exit code before any retry; `tsk dispatch`, `tsk edit --append-notes`, and some `tsk steps` commands are not idempotent.
+- Write with `tsk add`, `tsk edit`, and `tsk steps`. Read the exit code before any retry; `tsk reply`, `tsk dispatch`, `tsk edit --append-notes`, and some `tsk steps` commands are not idempotent.
 - When your work is finished, hand it back: `tsk status T12 review --done "…" --check "…"`. Set `done` only when the user says so.
 - When you need the human: `tsk status T12 blocked --why "…" --option "…"`, then stop. `tsk reply T12 "…"` answers a block or adds review feedback.
 - `tsk dispatch T12` launches an assigned project task's agent in Herdr. `tsk clean T12` removes its worktree and merged branch; never clean the worktree you run in.

site/src/content/docs/docs/board.md

@@ -142,8 +142,8 @@ A row addressed to you carries a dim **live line** under it, starting `└─`,
 
 | Row | Live line |
 | --- | --- |
-| Blocked on you | Their newest reply, else the block's needs or why: `@claude: the client id from the provider · 2h` |
-| In review on you | Their newest reply, else what was done: `@claude: Built the widget; empty input now handled. · 40m` |
+| Blocked on you | Their newest reply after yours, else the block's needs or why: `@claude: the client id from the provider · 2h` |
+| In review on you | Their newest reply after yours, else what was done: `@claude: Built the widget; empty input now handled. · 40m` |
 | Blocked on a task that is now done or deleted | `T202 is done · unblock it · 1h` |
 
 The age is how old the message is, and the asker is left out when it is you. A block or review with nothing said has no live line. Neither do rows waiting elsewhere, started and done rows, or notices. When a blocking task is done, the blocked task returns to NEEDS YOU, but its status does not change.
@@ -154,13 +154,13 @@ Press `z` to hide every live line, so each task takes one row. A row whose line
 
 Below 110 columns, a click or `→` opens a **peek** under the row. A wider pane opens the details beside the board instead ([Wide layout](#wide-layout)). The peek shows up to five wrapped note lines, then a footer: `@assignee · ⎇ <base> · #thread · project`, without what is unset or already said.
 
-A blocked task's peek shows the block instead of notes: who it waits on, the why, then the options or needs. A review's peek shows what was done and every check: `○` open, `✓` passed, `✗` failed. A task with prerequisites lists them with their status, such as `after T202 · started`. The [task page](/docs/task-page/) shows everything.
+A blocked task's peek shows the block instead of notes: who it waits on, the why, then the options or needs. A review's peek shows what was done and every check: `○` open, `✓` passed, `✗` failed. A task with prerequisites lists them with their status, such as `after T202 · started`, then the tasks waiting on it, such as `before T205`. The [task page](/docs/task-page/) shows everything.
 
 ## Multi-select
 
 `shift+M` turns on multi-select. Mark tasks with `Space`, `shift+↑`/`shift+↓`, or a click; marked rows show `▪`.
 
-With tasks marked, these act on the whole set as one save and one undo step: status changes, delete, archive, assignee, base, and after. `Enter`, editing, task-page actions, and relaunch stay on the cursor.
+With tasks marked, these act on the whole set as one save and one undo step: status changes, delete, archive, assignee, base, after, and waiting on. `Enter`, editing, task-page actions, and relaunch stay on the cursor.
 
 - Starting a set that would launch agents opens [one card first](/docs/dispatch/#start-a-marked-set).
 - Starting moves only open and ready tasks. It skips marked done tasks, and the status row counts them.
@@ -220,9 +220,9 @@ When the last prerequisite is done, each waiting **ready** task starts in the sa
 
 ### Task picker
 
-The task picker is a search box titled `T5 runs after`. The tasks it runs after sit pinned at the top, a done one marked `· done`.
+The task picker is a search box titled `T12 runs after`, or `3 tasks run after` for a marked set. The tasks it runs after sit pinned at the top, marked `✓`, a done one also `· done`.
 
-1. Type a task number (`202` or `T202`) or words from its title, such as `login timeout`. Matches list below the pinned tasks, this project's first. Others show their project.
+1. Type a task number (`202` or `T202`) or words from its title, such as `login timeout`. Matches list below the pinned tasks, this project's first. Others show their project. Done and archived tasks are not offered.
 2. `Enter` or a click on a match pins it and clears the search. `Enter` or a click on a pinned task unpins it. `ctrl+x` unpins every task.
 3. `shift+Enter` saves exactly the pinned tasks. With none pinned, the task runs after nothing.
 

site/src/content/docs/docs/capture.md

@@ -80,15 +80,16 @@ In Herdr, press `prefix+a` after [setup](/docs/install/#add-to-herdr). A popup o
 - `Esc` discards it, after first closing an open step editor or picker.
 - A failed save keeps the draft open to retry or cancel.
 
-To open the popup from a script:
+To open the popup from a script, invoke the plugin action for your platform:
 
-```sh
-herdr plugin action invoke quick-capture --plugin herdr-tsk
-```
+| Platform | Command |
+| --- | --- |
+| macOS, Linux | `herdr plugin action invoke quick-capture --plugin herdr-tsk` |
+| Windows | `herdr plugin action invoke quick-capture-windows --plugin herdr-tsk` |
 
 ## In the terminal
 
-`tsk capture` opens the same capture flow in your terminal, as does `TSK_MODE=capture tsk`. It exits after a save or a discard.
+`tsk capture` opens the same capture flow in your terminal, as does `TSK_MODE=capture tsk`. It exits after a save or a discard. `--state-dir <dir>` saves into another store ([`tsk capture`](/docs/cli/#commands)).
 
 ## From an agent or script
 

site/src/content/docs/docs/cli.md

@@ -579,7 +579,7 @@ tsk project archive atlas
 
 ## trash
 
-Restores a deleted task with its number.
+Restores a deleted task with its number, or the next free one.
 
 ```text
 tsk trash restore <task> [--state-dir <dir>]
@@ -597,7 +597,7 @@ tsk trash restore T12
 
 ## backup
 
-Backs the task store and `config.toml` up to git repositories. Targets, frequency, and what is pushed: [git backups](/docs/storage/#git-backups).
+Backs the task store and `config.toml` up to git repositories. Targets, frequency, and what is pushed: [git backups](/docs/storage/#git-backups). `backup` and `restore` print a URL's credentials as `***` ([credentials](/docs/storage/#credentials)).
 
 ```text
 tsk backup setup [--repo <name>] [--state-dir <dir>]
@@ -634,11 +634,10 @@ tsk restore [<version>] [--all] [--state-dir <dir>]
 | `<version>` | Restore this version without asking, including one only `--all` lists |
 | `--all` | List every version, not the newest 20 per machine |
 
-- The list shows each version's id, time, host, task count, and target, newest first. In a terminal it then asks which to restore; Enter cancels.
+- The list shows each version's id, time, machine, task count, and target, newest first. In a terminal it then asks which to restore; Enter cancels.
 - A restore keeps the replaced store beside it and prints its path. It never changes `config.toml`.
 - It refuses and replaces nothing when there are no targets or the id is unknown. It also refuses while a board or quick capture is open, and for a version from a newer tsk.
 - `tsk restore T12` is not a version: it points at `tsk trash restore T12`. A bare number, such as a `#` from the list, refuses and asks for the id.
-- A backup URL's credentials print as `***` ([credentials](/docs/storage/#credentials)).
 
 **Refusals:** a message with no code, exit 1 ([exit contract](#exit-contract)). A failure while replacing the store exits 3.
 

site/src/content/docs/docs/index.mdx

@@ -48,5 +48,6 @@ You or your agent set a task's status. Checking off every step, or an agent sess
 | Break work into a checklist | [Steps](/docs/steps/) |
 | Hand a task to an agent | [Dispatch](/docs/dispatch/) |
 | See what my agent reads | [tsk for agents](/docs/agents/) |
+| Have my agent run builder agents | [Coordinator skill](/docs/coordinator/) |
 | Script the board | [CLI](/docs/cli/) |
 | Configure tsk, back it up, or restore it | [Storage](/docs/storage/) |

site/src/content/docs/docs/keys.md

@@ -32,7 +32,7 @@ Status, edit, delete, and archive keys take `ctrl`. Bare letters move, open, and
 | Sort by recent, project, thread, title, or assignee | `s` |
 | Fold / unfold the cursor's group | `f` |
 | Fold / unfold every group in view | `shift+F` |
-| Hide / show the [live lines](/docs/board/#rows) under rows | `z` |
+| Hide / show agent messages, the [live lines](/docs/board/#rows) under rows | `z` |
 | Open the desk / last project / Projects view | `1` / `2` / `3` |
 | Pick a project | `p` |
 | Filter by thread, project, or assignee | `t` |
@@ -209,11 +209,11 @@ In the Herdr popup, `shift+Enter` saves and closes it. `Esc` or `ctrl+c` discard
 | Project picker, archive | `ctrl+f` archives the selected project · on the archived tab, `ctrl+f` or `ctrl+u` restores |
 | Archived project's board | `ctrl+u` restores · `Esc`, `p`, or `1`–`3` leaves |
 | Filter and view pickers (`t`, `v`) | type to filter · `↑` / `↓` select · `Tab` or `←` / `→` switch tabs, `shift+Tab` back · `Enter` chooses · `Esc` closes |
-| Group, sort, assignee, and base pickers | type to filter · `↑` / `↓` or `Tab` select · `Enter` applies · `Esc` closes with no change |
+| Group, sort, assignee, and base pickers | type to filter · `↑` / `↓` or `Tab` / `shift+Tab` select · `Enter` applies · `Esc` closes with no change |
 | Assignee and waiting-on pickers, **type a name…** | the row shows what you typed, such as `@dana` · `Enter` applies it |
 | Assignee picker, a person selected | `ctrl+x` [removes the name](/docs/dispatch/#remove-a-name-from-the-list) from the list · `ctrl+u` puts it back |
 | Waiting-on picker | as the assignee picker, and `←` / `→` also move |
-| After picker | type a number or words · `↑` / `↓` select · `Enter` pins a match or unpins a pinned task · `ctrl+x` unpins every task · `shift+Enter` saves the pinned tasks · `Esc` closes with no change |
+| [After picker](/docs/board/#task-picker) | type a number or words · `↑` / `↓` select · `Enter` pins a match or unpins a pinned task · `ctrl+x` unpins every task · `shift+Enter` saves the pinned tasks · `Esc` closes with no change |
 | Board search (`/`) | type or paste · `Backspace` · `Enter` pins the query · `Esc` clears and closes |
 | Palette (`:`) | type to filter · `↑` / `↓` or `Tab` / `shift+Tab` select · `Enter` runs · `Esc` closes |
 | Help (`?`) | type to filter by key or action · `↑` / `↓`, page keys, or the wheel scroll · `Esc` clears the search, then closes |

site/src/content/docs/docs/storage.md

@@ -34,7 +34,8 @@ Where tsk keeps your tasks and settings, how to configure it, and how to back it
 | `backup-repos/` | Local clones of backup targets |
 | `update.json` | The cached [update check](#update-check) |
 | `fetch-stamps.json` | When each repository's remote was last fetched. Dispatch, the base picker, and cleanup reuse a fetch from the last 60 seconds. Safe to delete |
-| `launchers\`, `cleanups\` | Windows only: dispatch launchers and cleanup progress |
+| `launchers/` | Dispatch launchers. Each one deletes itself once its agent starts |
+| `cleanups/` | Marks of worktree removals under way. After an interrupted removal, the next cleanup refuses and says how to finish by hand |
 
 ## Configuration
 

site/src/content/docs/docs/task-page.md

@@ -17,17 +17,17 @@ From the top: the title and status, a BLOCKED or REVIEW section while the task h
 
 Click the task's `T` number to copy it.
 
-The footer reads `@assignee · ⎇ <base> · after T202 · before T203 · #thread · project`:
+The footer reads `@assignee · ⎇ <base> · after T202 · before T205 · #thread · project`:
 
 | Slot | Shows |
 | --- | --- |
 | `@assignee` | The [assignee](/docs/dispatch/#assign): an agent profile, you, or a person. An unassigned task shows `+ assign` when at least one [agent profile](/docs/storage/#configuration) exists. Click to pick |
-| `⎇ <base>` | The base branch. Unset, it shows the repository default, such as `⎇ main (default)`. Click to pick |
-| `after T202, T205` | The tasks this one [runs after](/docs/board/#after). Shown only when set. Click to pick |
-| `before T203` | The tasks that run after this one. Read-only: it changes when you edit theirs. Click a number to open that task |
+| `⎇ <base>` | The base branch. Unset, it shows the repository default, such as `⎇ main (default)`, or `⎇ default` on the desk. Click to pick |
+| `after T202` | The tasks this one [runs after](/docs/board/#after). Shown only when set, or during an edit. Click to pick |
+| `before T205` | The tasks that run after this one. Read-only: it changes when you edit theirs. Click a number to open that task |
 | `#thread · project` | The thread and the project, or desk |
 
-Below it, the action bar lists the page's keys. In view mode it reads `ctrl+e edit`, the task's status actions, `esc close`, and `: commands`. Each one is clickable; `: commands` opens the command palette.
+Below it, the action bar lists the page's keys. In view mode it reads `ctrl+e edit`, the task's status actions, `esc close`, and `: commands`. During an edit, with no field open, it reads `shift+enter save`, `ctrl+a add step`, `esc cancel`, and `: commands`. Each one is clickable; `: commands` opens the command palette.
 
 ## Edit
 

site/src/pages/index.astro

@@ -328,7 +328,7 @@ const softwareApplication = {
                 chord away: <kbd>ctrl+u</kbd>.
               </p>
               <pre class="mini" aria-label="Verb bar"><span class="dim">enter</span> open · <span class="dim">ctrl+d</span> done · <span class="dim">ctrl+n</span> next ·
-<span class="dim">ctrl+o</span> inbox · <span class="dim">ctrl+b</span> block · <span class="dim">?</span> help</pre>
+<span class="dim">ctrl+o</span> inbox · <span class="dim">ctrl+b</span> block · <span class="dim">:</span> commands · <span class="dim">?</span> help</pre>
             </article>
 
             <article class="pillar">

skills/tsk-cli/SKILL.md

@@ -76,6 +76,8 @@ task's running agent, add `--send`: it sends only that reply and prints `sent to
     for your own bookkeeping ([steps](https://gettsk.sh/docs/cli.md#steps)).
 11. **Many tasks at once:** `cat plan.json | tsk add`; on exit 1, retry only the `failed` items
     ([JSON plans](https://gettsk.sh/docs/cli.md#json-plans)).
+12. **A restored task may change number.** `tsk trash restore T12` prints the number it got; use that
+    one from then on ([trash](https://gettsk.sh/docs/cli.md#trash)).
 
 ## Reading the board