docs: point the agent skill at umwelt-ctl update #7

Merged

troed merged 2 commits from docs/skill-update into main

2026-10-14 18:19:22 +02:00

troed commented

2026-10-14 18:16:31 +02:00

Owner

Follow-up to #6. The agent skill still listed only remote-install / remote-status / remote-remove, so an agent following it kept telling an operator to refresh a server by hand — and to re-remember which servers had been provisioned with --egress. That is exactly the footgun umwelt-ctl update was added to remove.

Changes

references/remote.md

A new "Refresh after a code change" section naming umwelt-ctl update (bare form, <name>, --all), that it needs no ssh host because it reads the machine-local registry and replays each server's recorded install parameters (remote_dir, config, egress), and what --restart stops (a named run: that server's agents; --all: this host's too).
The stale-agent paragraph now recommends umwelt-ctl update <name> --restart instead of the older remote-install form, and says why the error message names the older one.

references/host-setup.md

Triage step 1 points at update (and --all) for a stale install.

CONFIGURATION.md — its stale-agent remedy said “or, after a code change, umwelt-ctl update <name>”. That is not sufficient: the tree alone does not clear a running agent, which keeps the old code in memory. It now says umwelt-ctl update <name> --restart, with the remote-install alternative stated as the weaker option.

Notes

Docs only — no code touched. The skill is a managed copy, so bash umwelt/install.sh install must re-render it after this merges; until then the installed copy is stale.

Testing

Skill tests 25 passed; full unit suite 1123 passed, 3 skipped (unchanged from main, as this adds no code) — including the skill lint, the cited-anchor check and the pinned source-file list, none of which this touches.

Follow-up to #6. The agent skill still listed only `remote-install` / `remote-status` / `remote-remove`, so an agent following it kept telling an operator to refresh a server by hand — and to re-remember which servers had been provisioned with `--egress`. That is exactly the footgun `umwelt-ctl update` was added to remove. ## Changes **`references/remote.md`** - A new "Refresh after a code change" section naming `umwelt-ctl update` (bare form, `<name>`, `--all`), that it needs **no ssh host** because it reads the machine-local registry and replays each server's recorded install parameters (`remote_dir`, `config`, `egress`), and what `--restart` stops (a named run: that server's agents; `--all`: this host's too). - The stale-agent paragraph now recommends `umwelt-ctl update <name> --restart` instead of the older `remote-install` form, and says why the error message names the older one. **`references/host-setup.md`** - Triage step 1 points at `update` (and `--all`) for a stale install. **`CONFIGURATION.md`** — its stale-agent remedy said “or, after a code change, `umwelt-ctl update <name>`”. That is not sufficient: the tree alone does not clear a *running* agent, which keeps the old code in memory. It now says `umwelt-ctl update <name> --restart`, with the `remote-install` alternative stated as the weaker option. ## Notes Docs only — no code touched. The skill is a managed copy, so `bash umwelt/install.sh install` must re-render it after this merges; until then the installed copy is stale. ## Testing Skill tests `25 passed`; full unit suite `1123 passed, 3 skipped` (unchanged from `main`, as this adds no code) — including the skill lint, the cited-anchor check and the pinned source-file list, none of which this touches.

troed added 2 commits

2026-10-14 18:16:31 +02:00

docs: point the agent skill at umwelt-ctl update 51187a3d66

The skill listed only remote-install/remote-status/remote-remove, so an agent following it kept telling the operator to refresh a server by hand and to re-remember which ones were provisioned with --egress. It now names umwelt-ctl update and --all, explains that the recorded install parameters are replayed so no ssh host or flag is needed, and says what --restart stops. host-setup.md triage step points at update for a stale install.

docs: name the bare update form and fix the stale-agent remedy ad3fbfe5d7

Review follow-ups: the skill snippet now shows the bare local-install form, the replayed record is named in full (remote_dir, config, egress), and CONFIGURATION.md stale-agent remedy now says update <name> --restart, since the tree alone does not clear a running agent.

troed merged commit fb86ccbe41 into main

2026-10-14 18:19:22 +02:00

troed deleted branch docs/skill-update

2026-10-14 18:19:22 +02:00

troed referenced this pull request from a commit

2026-10-14 18:19:23 +02:00

docs: point the agent skill at umwelt-ctl update (#7)