Docs: install is the release one-liner, a clone is dev mode

README's first instruction becomes the tokenless curl | tar against
the stable latest-release URL; the clone path moves to a "working on
bench itself" note. CLAUDE.md's Updating section and .env.example's
BENCH_SOURCE comment describe release-based updates: the source is
stamped at build time, BENCH_SOURCE is an override rather than a
prerequisite.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
istos
2026-07-30 07:48:11 +02:00
co-authored by Claude Fable 5
parent d6fb478466
commit 370fdee833
3 changed files with 45 additions and 19 deletions
+12 -6
View File
@@ -9,7 +9,7 @@ its status — there is no other source of truth.
├── install.py ← Wires the project via the agent adapter (see below)
├── start.sh ← One-command start: install + port handling + board
├── stop.sh ← Safe stop: refuses while agents run (--force overrides)
├── update.sh ← Replace core/ from the distribution repo; local/ survives
├── update.sh ← Replace core/ from the published release; local/ survives
├── tasks/ ← Task state, nothing else. Works as a plain folder
│ ├── backlog/…done/ ← kanban even if manager/ is deleted or ignored.
│ └── archive/ ← Archived cards: out of the flow, never deleted
@@ -110,11 +110,17 @@ Commands arm on first click and run on the second.
## Updating
`./.task-manager/update.sh` fetches the distribution repo (`BENCH_SOURCE`
in `local/.env`), replaces `manager/core/` wholesale plus the top-level
scripts, and touches nothing else — tasks, driver, prompt overrides, `.env`
and state all survive. Then re-run `install.py` (idempotent re-wire) and
restart the board.
`./.task-manager/update.sh` downloads the latest GitHub Release of the
distribution repo (`BENCH_REF=v3` pins a tag; the source is stamped into
the script at build time, `BENCH_SOURCE` in `local/.env` overrides it),
replaces `manager/core/` wholesale plus the top-level files named in the
artifact's `manager/core/release-manifest`, and touches nothing else —
tasks, driver, prompt overrides, `.env` and state all survive. No release
published → it says so and changes nothing; developers working on bench
itself update their clone with git instead. Then re-run `install.py`
(idempotent re-wire) and restart the board. Releases are cut from the
bench repo with `release.sh` (never shipped in the artifact): it builds
the tarball from the manifest, tags `v<VERSION>` and publishes via `gh`.
## Installing into a project
+30 -12
View File
@@ -9,13 +9,14 @@ branch, and an archive that is never a delete.
## Install into a repo
```bash
git clone <this repo> .task-manager && rm -rf .task-manager/.git
mkdir .task-manager && curl -L \
https://github.com/12vectors/bench/releases/latest/download/bench.tar.gz \
| tar -xz -C .task-manager
./.task-manager/start.sh # wires the project (idempotent) and serves
```
The first `start.sh` clears the distribution's own cards from `tasks/`,
`plans/` and `reference/` (printing each removal), so a fresh install
starts with an empty board.
No token, no clone: releases are curated artifacts that never contained
bench's own cards or settings, so the board starts empty by construction.
Commit `.task-manager/` into the host repo — core is vendored on purpose,
so clones work offline and updates show up in the host's own diffs.
@@ -23,16 +24,33 @@ so clones work offline and updates show up in the host's own diffs.
## Update
```bash
# in manager/local/.env: BENCH_SOURCE=<this repo's git url>
./.task-manager/update.sh # latest
BENCH_REF=v1 ./.task-manager/update.sh # a specific release tag
./.task-manager/update.sh # latest release
BENCH_REF=v2 ./.task-manager/update.sh # an exact release tag
```
Updates replace `manager/core/` and the top-level scripts wholesale and
touch nothing else — tasks, plans, reference, and everything under
`manager/local/` (your driver, commands, prompt overrides, settings,
state) survive every update. Then `python3 .task-manager/install.py` and
restart the board.
The artifact is stamped with the repo it was built from, so updating
needs no configuration; `BENCH_SOURCE=<owner/repo>` in
`manager/local/.env` overrides the stamp. Updates replace
`manager/core/` and the top-level scripts wholesale and touch nothing
else — tasks, plans, reference, and everything under `manager/local/`
(your driver, commands, prompt overrides, settings, state) survive every
update. Then `python3 .task-manager/install.py` and restart the board.
If the source repo has no published release yet, `update.sh` says so and
changes nothing.
## Working on bench itself
```bash
git clone git@github.com:12vectors/bench.git && cd bench && ./start.sh
```
A clone carries bench's own cards and local/ content — that is dev mode,
not an install. (Installing from a clone anyway works: `install.py`
clears the shipped cards on its first boot in a host repo.) Releases are
built by `./release.sh` from the manifest at
`manager/core/release-manifest`: tag = `v<VERSION>`, one stable asset
name (`bench.tar.gz`), contents at the tarball root — the two things the
install one-liner above depends on.
## The three-layer law
+3 -1
View File
@@ -46,7 +46,9 @@ BOARD_WATCH_INTERVAL=2
BOARD_EVENTS_CAP=800
BOARD_HISTORY_CAP=300
# Where update.sh fetches the task-manager distribution from (a git URL).
# Where update.sh fetches the task-manager's releases from (owner/repo, or
# any GitHub URL). Normally unset: the shipped update.sh is stamped at
# build time with the repo it came from, and this overrides the stamp.
# Updates replace manager/core/ and the top-level scripts; they never touch
# tasks/, plans/, reference/ or manager/local/.
BENCH_SOURCE=