agents-city 0.3.0-beta.21 → 0.3.0

package/README.md

@@ -5,6 +5,14 @@
 **Run several autonomous agent cities on one machine, and connect only the
 cities that should talk.**
 
+```bash
+npm install -g agents-city
+agents-city
+```
+
+That is the whole installation. The second command opens the town hall in your
+browser and walks you through creating your first city.
+
 Agents City is a local-first, multi-model orchestrator for repository work. Each
 city has its own identity, domain, chair seat, goal, repo support agents,
 editable knowledge, live-recognised skills, and explicit roads to other cities.
@@ -85,53 +93,66 @@ The important boundaries are:
 
 ## Quick start
 
-### Right now: the real npm experience without publishing
-
-Packing first matters: this tests the exact file list a person would receive
-from npm, not the whole checkout.
+### Install from npm
 
 ```bash
-cd /path/to/agents-city
-npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g agents-city
 agents-city --version
-agents-city seat
 ```
 
-You do not need to run `npm publish`. The installation is global only for your
-currently active Node installation.
+This is `0.x` on purpose: the commands are usable today, and the file formats
+and APIs can still change between minor versions. Nothing here pretends to be
+frozen yet.
 
-### Registry installation once available
+You need Node.js 22+, Python 3 and tmux; the
+[requirements table](#base-requirements) has the details, and `agents-city seat`
+offers to install tmux when it is missing. Nothing is installed system-wide
+beyond the npm global folder of your active Node installation.
 
-Check availability and dist-tags first:
+### Try it without installing anything
 
 ```bash
-npm view agents-city dist-tags --json
+npx agents-city
 ```
 
-If it returns `E404`, use the local tarball in the previous section. Once the
-registry shows a `beta` dist-tag, install it with:
+`npx` downloads the package into its cache, runs it, and leaves your global npm
+folder untouched — the fastest way to see whether this is for you.
+
+### Then: the Hall, or the terminal
 
 ```bash
-npm install -g agents-city@beta
-agents-city --version
-agents-city seat
+agents-city        # the town hall in your browser (same as: agents-city hall)
+agents-city seat   # the terminal wizard, if you prefer not to leave the shell
 ```
 
-Use `@beta` while this is a prerelease. Bare `npm install -g agents-city` should
-be reserved for the future stable release carrying the `latest` tag.
+The Hall listens on `127.0.0.1`, chooses a free port, and opens the browser. You
+can create or select a city, edit its configuration, tune each agent's engine
+and watch the live map there. The Hall and the CLI use the same underlying
+modules, so neither is the "lesser" path.
 
-### Open the Hall instead of the terminal wizard
+### Update, or remove
 
 ```bash
-agents-city
-# equivalent to:
-agents-city hall
+npm install -g agents-city        # update to the newest release
+npm uninstall -g agents-city      # remove the program
 ```
 
-The Hall listens on `127.0.0.1`, chooses a free port, and opens the browser. You
-can create or select a city and edit its configuration there. The Hall and CLI
-use the same underlying modules.
+Uninstalling leaves `~/.agents-city`, your cities and your repositories exactly
+where they are: the program is not your data.
+
+### Install from a source checkout instead
+
+For contributors, and for anyone who wants to read the code before running it.
+Packing first is the honest test: it exercises the exact file list a person
+receives from npm, not your whole working copy.
+
+```bash
+git clone https://github.com/jlcases/agents-city.git
+cd agents-city
+npm pack
+npm install -g ./agents-city-*.tgz
+agents-city --version
+```
 
 ## Requirements and installation
 
@@ -146,6 +167,7 @@ use the same underlying modules.
 | tmux | one window per seat/repo; `seat` tries to install it when missing |
 | macOS or Linux | natively supported platforms |
 | WSL | required on Windows because native Windows has no bash/tmux |
+| bubblewrap | optional, Linux only: it IS the cage there. Without it agents run uncaged — see [the cage](#the-cage-the-broker-and-the-audit-chain) |
 
 Each runtime also needs its own installed and authenticated CLI. Agents City
 does not bundle or replace Claude, Codex, OpenCode, or Kimi accounts.
@@ -172,15 +194,19 @@ onboarding, Agents City uses the separate `gh` CLI:
 
 `gh` is not bundled inside the Agents City npm package.
 
-### Update a local installation
+### Update an installation
 
 ```bash
-cd /path/to/agents-city
-npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g agents-city        # from the registry
 agents-city --version
 ```
 
+From a source checkout, pack and install the tarball instead:
+
+```bash
+cd /path/to/agents-city && npm pack && npm install -g ./agents-city-*.tgz
+```
+
 Already-running sessions retain the code loaded in memory. To apply the new
 version to one city:
 
@@ -204,7 +230,7 @@ restart one specific city.
 
 ## First run, step by step
 
-`agents-city seat` creates `home` when no city exists and asks for five decisions.
+`agents-city seat` creates `home` when no city exists and asks seven questions.
 
 ### 1. Work domain
 
@@ -228,22 +254,39 @@ built-in options are:
 This is the responsibility of the city lead. It is not the city name or runtime.
 The seat remains chair even when you choose `blank`.
 
-### 3. Repositories and each agent's role
-
-You can read repositories from disk, your GitHub account, or a GitHub
-organisation. Each selected local repo receives:
-
-- a tmux window;
-- a private bus actor;
-- its repository as working directory;
-- an explicit operating role;
-- the skills its runtime can already discover there.
-
-A repo role may come from another domain. For example, a software city can give
-`po` to its product repo, `seo` to a portfolio, and `data-engineer` to a
-pipeline. None becomes chair.
-
-Selecting zero repos is also valid: the city opens with only its seat.
+### 3. The agents, one at a time
+
+This is the city itself, and it is a loop rather than a list of folders to tick.
+Each agent is asked for in full, and then you are asked for another, until you
+say the city is complete:
+
+1. **Its name** — what you call it in its window, on the map, and on the bus.
+2. **The kind of work it does** — `code`, `knowledge` or `coordinator`. This is
+   not a permission: it decides how its house grows on the map, so a person
+   whose work is documents is not measured in pull requests.
+3. **Its role** — its specialty, from this city's domain or another one. A
+   software city can give `po` to a product agent, `seo` to a portfolio one and
+   `data-engineer` to a pipeline. None becomes chair.
+4. **Everything it works on** — any number of repositories (read from disk, your
+   GitHub account, or an organisation) *plus* any number of document folders.
+   One agent may answer for three services and a handbook at once, and an agent
+   with no git anywhere is a first-class agent. They are mounted inside its
+   workspace, not turned into separate agents.
+5. **What runs it** — Claude with a model and effort of its own, or Codex,
+   OpenCode, Kimi, or an explicit terminal fallback.
+6. **The skills it starts with** — a skill folder or `.zip` installed into that
+   agent's own home. Only offered for engines that read skills; an agent on
+   Codex is told its engine ignores them instead of being sold something that
+   does nothing.
+
+Each agent then receives a tmux window, a private bus actor, its workspace as
+working directory, and the skills its runtime can already discover in what it
+mounts.
+
+Saying the city has no agents is also valid: it opens with only its seat, and
+roads connect it to other cities.
+
+Change the roster any time with `agents-city seat --agents`.
 
 ### 4. Goal
 
@@ -259,19 +302,49 @@ A goal may be quantitative or qualitative. It stores:
 
 You may skip it and configure it later with `agents-city seat --goal`.
 
-### 5. Runtime for each window
-
-Pressing Enter keeps Claude everywhere. You may instead choose per window:
+### 5. Runtime for your own chair
 
-- Claude and, optionally, model/effort;
-- Codex;
-- OpenCode;
-- Kimi;
-- an unknown command through the explicit terminal fallback.
+Every agent's engine was decided on the agent itself, in question 3. What is
+left is your own window — the one that holds the chair role, the `/city:`
+commands and the plugin. Pressing Enter keeps it on your Claude; you may instead
+choose Claude with a model and effort, Codex, OpenCode, Kimi, or an unknown
+command through the explicit terminal fallback.
 
 Persistent choices live in the owner card. `seat --model` and `--effort` are
 one-launch overrides only.
 
+### 6. Whether your chair asks permission
+
+Per city, in `city.yml` as `seat_yolo`. Locally the seat is your own hands on
+your own machine, so asking you for permission in your own chair is a choice,
+not a law. Agent windows keep their own cage either way, and launching with
+`--no-yolo` still brakes the whole session, seat included.
+
+### 7. The city on your desktop
+
+Offered once, when the city is new: a real desktop shortcut carrying the city's
+name and an icon coloured from its own identity — a macOS `.app` bundle or a
+Linux `.desktop` entry. Double-click it and the city opens.
+
+It runs the same line you would type, so it is a labelled button on the front
+door rather than a second way in. Add or remove one any time:
+
+```bash
+agents-city shortcut              # this city, on your desktop
+agents-city shortcut home --hall  # a door that opens the map instead
+agents-city shortcut --remove     # take it off again
+agents-city shortcut --to ~/bin   # somewhere other than the desktop
+```
+
+**On Windows** the city lives inside WSL, and a `~/Desktop` in WSL is the Linux
+home's desktop — which nobody ever looks at. So the shortcut is written to the
+**Windows** desktop instead, asked of Windows itself rather than guessed from a
+username (a desktop redirected to OneDrive or a domain profile is not under
+`C:\Users\<name>\Desktop`). It is a real `.lnk`, built through Windows' own
+PowerShell so it can carry an `.ico`, and it launches `wsl.exe` running the same
+command in a login shell. Where interop is unavailable, a double-clickable
+`.cmd` is written instead — same door, plain icon.
+
 ### What gets created
 
 ```text
@@ -415,8 +488,10 @@ agents-city cities
 agents-city road
 agents-city bus
 agents-city committee
+agents-city agents
 agents-city skills
 agents-city city
+agents-city shortcut
 agents-city demo
 agents-city report
 agents-city tokens
@@ -424,6 +499,8 @@ agents-city logs
 agents-city benchmark
 agents-city reset
 agents-city exit
+agents-city doctor
+agents-city update
 agents-city test
 ```
 
@@ -473,6 +550,12 @@ spectator token rotates with the hub, accepts only an origin on this computer,
 and is read-only: the browser cannot direct the committee. `Ctrl-c` stops the
 Hall.
 
+Two buttons sit under the brand: **day/night**, and **ES/EN**. The Hall speaks
+Spanish and English, starting in the browser's own language and remembering an
+explicit choice. Translations are keyed by the English sentence, so anything not
+yet translated falls back to readable English rather than to an identifier — new
+strings are never blocked on a translation pass.
+
 ### `agents-city setup`
 
 Creates or selects a city and opens the Hall; `--tui` hands the flow to `seat`.
@@ -712,6 +795,30 @@ skills/*/SKILL.md
 Actual invocation depends on the runtime. Agents City advertises the capability
 for the member and lets the provider enforce its own discovery and use rules.
 
+### `agents-city agents`
+
+Lists this city's agents and manages what each one works on. An agent's mounts
+are symlinks inside its workspace, so this is the terminal equivalent of the
+Hall's **works on** row and of question 3 of the wizard.
+
+```bash
+agents-city agents list --card ~/.agents-city/alice/home/alice.md --data ~/.agents-city/alice/home
+agents-city agents mounts --agent urgencias --data ~/.agents-city/alice/home
+agents-city agents mount --agent urgencias --src ~/documents/handbook --data …
+agents-city agents unmount --agent urgencias --name handbook --data …
+```
+
+| Command | Effect |
+|---|---|
+| `list` | every agent: name, slug, role, runtime, kind, working directory |
+| `mounts` | one agent's mounts, as label and real target |
+| `mount --src PATH` | mount a repo, a worktree or a folder of documents |
+| `unmount --name LABEL` | remove that mount; the folder itself is untouched |
+| `sync` / `sync-all` | rebuild the workspaces from the card, as the launcher does |
+
+Unmounting removes a symlink and a card key. It never deletes what the link
+pointed at.
+
 ### `agents-city city`
 
 Opens one city's local map without starting an agent session.
@@ -738,6 +845,45 @@ control) toggles fullscreen, and the Hall's live rail is resizable by dragging
 its edge. The full contract is in
 [docs/map-live-layers.md](docs/map-live-layers.md).
 
+### `agents-city shortcut`
+
+Puts a city on your desktop: its name, an icon coloured from its own identity,
+and a double-click that opens it.
+
+```bash
+agents-city shortcut               # the selected city
+agents-city shortcut product       # a specific one
+agents-city shortcut --hall        # a door that opens the map instead of the seat
+agents-city shortcut --remove      # take it off the desktop
+agents-city shortcut --to ~/bin    # write it somewhere else
+```
+
+| Option | Effect |
+|---|---|
+| `--hall` | the shortcut opens the browser map instead of the tmux city |
+| `--remove` | remove this city's shortcut |
+| `--to DIR` | write it into another folder than the desktop |
+
+What gets written depends on the desktop, and each is a real one rather than a
+script pretending:
+
+| Platform | Shortcut | Icon |
+|---|---|---|
+| macOS | `.app` bundle running the city in Terminal | `.icns`, built with the system's `iconutil` |
+| Linux | `.desktop` entry, marked trusted where `gio` exists | `.png` under `XDG_DATA_HOME` |
+| Windows (WSL) | `.lnk` on the **Windows** desktop, launching `wsl.exe` | `.ico`, when PowerShell interop is reachable |
+
+All of them run the same line you would type, so the shortcut is a labelled
+button on the front door rather than a second way in. The icon is generated
+without any image library: a PNG written by hand, wrapped as `.ico` for Windows
+and converted by `iconutil` for macOS.
+
+On Windows the city lives inside WSL, and a `~/Desktop` there is the Linux
+home's desktop that nobody looks at — so the Windows desktop is asked of Windows
+itself, never assembled from a username, because a desktop redirected to OneDrive
+or a domain profile is not under `C:\Users\<name>\Desktop`. Without interop a
+double-clickable `.cmd` is written instead: same door, plain icon.
+
 ### `agents-city demo`
 
 Opens one fictional, disposable demo city in the complete Hall. The map owns
@@ -905,13 +1051,21 @@ benchmark; by itself it proves neither higher answer quality nor a SOTA claim.
 
 ### `agents-city reset`
 
-Resets **one** managed city while preserving its stable identity and repositories.
+Resets managed cities while preserving their stable identity and repositories.
 
 ```bash
-agents-city reset product --dry-run
+agents-city reset product --dry-run   # show every effect, change nothing
 agents-city reset product
+agents-city reset product client-a    # several, space separated
+agents-city reset all                 # every city this owner has
 ```
 
+One unknown name aborts the **whole** run before anything is touched: resetting
+three cities and then stopping on a typo is the worst outcome a destructive
+command can have. The Hall has the same thing as a button, in **Cities** — it
+first shows what disappears, what survives and where the copy lands, and asks
+you to type the city's name.
+
 The reset plan:
 
 1. verifies the target is a managed city, not an arbitrary path;
@@ -942,6 +1096,41 @@ Hall may stay up. Without a city, it shows or closes everything managed by
 Agents City. A tmux session may contain unsaved work, so dry-run is the safe way
 to confirm scope.
 
+### `agents-city doctor`
+
+Checks this machine and says which part is missing, in one screen.
+
+```bash
+agents-city doctor
+```
+
+It reports the tools it needs (python3, tmux, bash, git, node, and `gh` as
+optional), which agent runtimes are installed, **which cage this kernel gives
+you** — seatbelt, bubblewrap, or none and why — the selected city and its card,
+whether the Hall bundle is built, and whether a newer version is published. It
+exits non-zero when something is broken, so it works in a script too.
+
+Passed a config file instead, it keeps its older job: detect an old config
+shape, explain it, and migrate it with `--fix` (leaving a backup).
+
+### `agents-city update`
+
+```bash
+agents-city update            # install the newest published version
+agents-city update --check    # only ask: installed vs published
+agents-city update --tag beta # follow a dist-tag
+```
+
+The check is **one GET to the public npm registry**, cached for a day under
+`~/.agents-city/.runtime/`. Nothing about your machine is sent — no identifier,
+no counter, no telemetry — and `CITY_UPDATE_CHECK=0` switches it off entirely.
+It runs only where you deliberately opened something: `doctor`, `update`, and
+the Hall (which shows one line when a release is out). A plain
+`agents-city cities` never touches the network.
+
+Installed from a git checkout, `update` refuses and tells you the command that
+fits your install instead of running `npm install -g` over your working copy.
+
 ### `agents-city test`
 
 Runs checkout tests. With no arguments it runs every suite; with names it runs
@@ -1194,7 +1383,7 @@ it never gains authority to command a local repo directly.
 ```bash
 cd /path/to/agents-city
 npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g ./agents-city-*.tgz
 agents-city seat
 ```
 
@@ -1466,7 +1655,7 @@ authentication failure is not counted as a fast sample.
 ```bash
 cd /path/to/agents-city
 npm pack
-npm install -g ./agents-city-0.3.0-beta.21.tgz
+npm install -g ./agents-city-*.tgz
 agents-city --version
 agents-city exit product --dry-run
 agents-city exit product
@@ -1586,7 +1775,7 @@ message lifetime. `bus inbox` consumes `road-inbox`, not append-only history.
 | `AGENTS_CITY_USER` | resolved local identity | force an owner for tests/migrations |
 | `AGENTS_CITY_DATA` | selected city | force a city folder from an outside terminal |
 | `CITY_CODE_DIR` | `~/codigo` | destination for accepted GitHub clones |
-| `CITY_SEARCH_IN` | common home roots | colon-separated roots for local repo search |
+| `CITY_SEARCH_IN` | common home roots | colon-separated roots to search (`;` also accepted, for Windows) |
 | `CITY_SEARCH_DEPTH` | `4` | maximum depth of that search |
 | `AGENTS_CITY_ORG` | empty | filter repositories by organisation; empty means all |
 | `CITY_SETTLE` | `8` | initial Claude startup wait in seconds |
@@ -1596,6 +1785,12 @@ message lifetime. `bus inbox` consumes `road-inbox`, not append-only history.
 | `AGENTS_CITY_URL` | `CITY_BUS_URL` | reporting/map endpoint when separate |
 | `CITY_DIR` | `~/.claude/channels/city-bus` | compatibility folder for `.env` and hooks |
 | `CITY_HOOKS` | `city` | `everywhere` runs the conscience hooks in every Claude session, not only city runtimes |
+| `CITY_DESKTOP` | `~/Desktop`, or the Windows desktop under WSL | where `agents-city shortcut` writes |
+| `CITY_CAGE` | `1` | `0` launches every window uncaged |
+| `CITY_CAGE_DENY` | empty | extra colon-separated paths to seal |
+| `CITY_CAGE_ALLOW_WRITE` | empty | extra colon-separated paths to keep writable |
+| `CITY_UPDATE_CHECK` | `1` | `0` never asks npm whether a newer version exists |
+| `CITY_CAGE_BWRAP` | probed | `1`/`0` answers "can this Linux build a namespace?" without probing; the launcher sets it once per city |
 
 Examples:
 
@@ -1611,10 +1806,27 @@ agents-city cities create lab
 CITY_SETTLE=0 CITY_STAGGER=0 agents-city seat --city product
 ```
 
-The local repository index is cached for one day at
-`$XDG_CACHE_HOME/agents-city/repos.tsv` or `~/.cache/agents-city/repos.tsv`. The
-Hall offers a refresh. From a terminal, if you change `CITY_SEARCH_IN` while the
-cache is still valid, remove **only that index file** and repeat `seat --repos`.
+### What a house can be given to work on
+
+`plugin/scripts/busca.py` walks your disk once and indexes three kinds of place:
+
+* **repositories** — named by their `origin` remote, not by the folder they sit
+  in, so a clone is findable by the name you would say out loud;
+* **worktrees** — a linked worktree is the folder an isolated agent actually
+  works in, and it is listed as `repo@branch`, a distinct thing to pick;
+* **folders of documents** — a directory with writing in it and no git anywhere,
+  which is what a `knowledge` agent mounts.
+
+It reads `.git/config` and `HEAD` directly rather than running `git` once per
+repository, so a full scan finishes while somebody is looking at the screen, and
+it runs anywhere Python does — macOS, Linux and Windows alike. The guide and the
+Hall search this index; `plugin/scripts/find-repos.sh` is a thin shim over it for
+shell callers, printing the git half only.
+
+The index is cached for one day at `$XDG_CACHE_HOME/agents-city/lugares.tsv` or
+`~/.cache/agents-city/lugares.tsv`. Both the Hall's house form and the seat offer
+a refresh; from a terminal, `busca.py --refresh` rebuilds it, which is also what
+you want after changing `CITY_SEARCH_IN` while the cache is still valid.
 
 Transport setting precedence is:
 
@@ -1656,7 +1868,8 @@ but "do not ask" and "touch everything" are different axes, and only the first
 one is yolo. On macOS Claude, OpenCode and Kimi repo windows launch inside a
 generated seatbelt profile: writes land only in their own repo and runtime state, and the files
 that turn a prompt injection into a credential theft (`~/.ssh`,
-`~/.git-credentials`, `~/.aws`, gh and cloud configs, remote road tokens) are
+`~/.git-credentials`, `~/.aws`, gh and cloud configs, remote road tokens, and
+Claude Code's own `~/.claude/.credentials.json`) are
 sealed at the kernel — reads and writes, children and grandchildren included.
 The agent is never asked anything; forbidden paths simply do not exist for it.
 Codex instead applies its native `workspace-write` sandbox and is not wrapped
@@ -1664,6 +1877,21 @@ in seatbelt: MCP workers such as `node_repl` apply their own sandbox, and macOS
 rejects that operation inside an already-caged process. `CITY_CAGE=0`
 deliberately disables the applicable confinement layer.
 
+**On Linux the cage is bubblewrap.** The seal is built the way Linux builds
+these — a mount namespace where the sealed paths are simply not mounted, so
+`~/.ssh` inside the cage is an empty directory and `~/.git-credentials` reads as
+nothing. Same promise as the seatbelt, different mechanism, and `bin/test-cage.py`
+proves it against a real namespace on every Linux CI run: the planted key is
+unreadable, the repo stays writable, a write into a sealed directory never
+reaches the disk, and a grandchild process cannot escape.
+
+It needs `bubblewrap` installed (`apt install bubblewrap`) and unprivileged user
+namespaces enabled — Agents City checks that bwrap can really build one rather
+than trusting that the binary exists, and a machine where it cannot says so and
+launches uncaged, exactly as before. There is no confinement on other platforms:
+without a cage, run agents over work you would be comfortable running a script
+over.
+
 Because a caged window cannot read the `gh` token, PRs and pushes go through
 an opt-in credential broker (`CITY_BROKER=1`): a small owner-side process that
 holds the credentials, accepts per-window tokens bound to a single repo,
@@ -1837,8 +2065,8 @@ agents-city seat --repos
 ```
 
 Discovery requires `.git` (a directory or worktree file) and an `origin` remote.
-If roots just changed, refresh in the Hall or remove only
-`~/.cache/agents-city/repos.tsv`. `AGENTS_CITY_ORG` may be filtering the repo;
+If roots just changed, use the house form's **Search again**, or run
+`plugin/scripts/busca.py --refresh`. `AGENTS_CITY_ORG` may be filtering the repo;
 leave it empty to index every remote.
 
 ### GitHub does not show private repos or organisations
@@ -1964,7 +2192,7 @@ npm pack --dry-run
 npm pack
 
 CITY_TEST_PREFIX="$(mktemp -d)"
-npm install -g --prefix "$CITY_TEST_PREFIX" ./agents-city-0.3.0-beta.21.tgz
+npm install -g --prefix "$CITY_TEST_PREFIX" ./agents-city-*.tgz
 "$CITY_TEST_PREFIX/bin/agents-city" --version
 "$CITY_TEST_PREFIX/bin/agents-city" --help
 ```

package/bin/agents-city.js

@@ -32,11 +32,14 @@ const ORDENES = {
   reset: { que: ['bin/reset'], di: 'reset one city to onboarding, recoverably' },
   skills: { que: ['bin/skills'], di: 'recognise the skills installed in each repo' },
   city: { que: ['bin/city'], di: 'draw your city' },
+  shortcut: { que: ['bin/shortcut'], di: 'put a city on your desktop: icon, name, double-click' },
   demo: { que: ['bin/demo'], di: 'Aurora Games — see it working, no account' },
   setup: { que: ['bin/setup.py'], di: 'create or open a personal city' },
   report: { que: ['bin/report.py'], di: 'report growth from your folders' },
   tokens: { que: ['bin/tokens.py'], di: 'report token spend' },
   exit: { que: ['bin/exit'], di: 'close the day — every session and agent, or one city' },
+  doctor: { que: ['bin/doctor'], di: 'check this machine: tools, runtimes, cage, city, version' },
+  update: { que: ['bin/update'], di: 'install the newest published version (--check just asks)' },
   test: { que: ['bin/test'], di: 'every check in the repo' },
 };
 

package/bin/doctor

@@ -0,0 +1,3 @@
+#!/usr/bin/env bash
+# Check this machine: tools, runtimes, the cage, the city, and the version.
+exec python3 "$(cd "$(dirname "$0")/../plugin/scripts" && pwd)/doctor.py" "$@"