docs(update): stop claiming self-update deletes the box image

[madarco]

What

Backlog item: "self-update shouldn't remove the docker image anymore, since the hash will do that only when needed."

The actual docker image rm was already gone from post-update-refresh.ts (it now reports build-context freshness instead). This PR is the language sweep — every message, help string, comment and doc line that still told the user the box image gets wiped, which was now a lie.

Changes

• apps/cli/src/commands/update.ts — the printed plan line no longer says docker image rm -f <image>; it now reads that the image is re-checked and left in place, and its build-context fingerprint rebuilds it on the next create only if the context changed. Added a plan line for the existing cloud-base adoption step. --skip-self help updated to match ("re-check the image", not "refresh image").
• apps/cli/src/index.ts — the "agentbox was updated" startup prompt now says "re-check the box image" instead of "box image".
• apps/cli/src/commands/install.ts — comment "image wipe" → "image re-check".
• docs/architecture.md, docs/development.md, docs/test-plan.md — describe the freshness check + cloud-base adoption; dropped the "agentbox self-update does the docker rmi for you" claim.
• apps/web/content/docs/cli.mdx already reflected reality ("checked, not deleted") — left as is.

No runtime behaviour change to post-update-refresh.ts (no remaining deletion was found there).

Verification

• pnpm --filter @madarco/agentbox lint — clean
• pnpm --filter @madarco/agentbox typecheck — clean
• pnpm --filter @madarco/agentbox test — 1084 passed, 1 skipped
• Built the CLI and ran the smoke tests below.

node apps/cli/dist/index.js self-update --dry-run

┌  agentbox self-update
│
●  already the newest (0.28.0-nightly.202607290716) [nightly channel] — refreshing skills/image/relay/app anyway
│
●  plan:
│    self-update: skipped (0.28.0-nightly.202607290716 is already the newest build)
│    skills: refresh agentbox-managed host skill files in ~/.claude (and Codex/OpenCode)
│    image: re-check agentbox/box:dev (left in place; its build-context fingerprint rebuilds it on the next create only if it changed)
│    bases: adopt any matching cloud base bake from the control box, if one is configured
│    relay: stop, then respawn
│    app: update the menu-bar app if the published build changed (macOS, when installed)
│
└  dry run — nothing changed

The plan no longer promises an image removal.

node apps/cli/dist/index.js self-update --help

Update agentbox: self-update via npm/pnpm (unless run via npx), refresh the
host skills, re-check the box image (rebuilt on the next create only if its
build context changed), reload the relay/hub, and update the menu-bar app
...
  --skip-self          skip the package self-update; only refresh the skills,
                       re-check the image, and reload the relay + app

https://claude.ai/code/session_011pKPDo9WP1sxwQTQBxHF47

---

Note

Low Risk
String and documentation updates only; no changes to post-update refresh or image handling logic.

Overview
This PR is a language-only sweep: runtime behavior in post-update-refresh was already not removing agentbox/box:dev; user-facing strings still claimed a wipe.

CLI messaging now says the box image is re-checked and left in place, with rebuild on the next create/claude only when the build-context fingerprint changes. That applies to the self-update description and --skip-self help, the dry-run plan line (replacing docker image rm -f), the post-version-change confirm in index.ts, and an install-wizard comment. The dry-run plan also surfaces the existing cloud-base adoption step as bases: adopt any matching cloud base bake….

Docs (architecture.md, development.md, test-plan.md) match: content-addressed context, no “self-update deletes the image for you,” and UPDATE test signals expect re-check not deletion.

^{Reviewed by Cursor Bugbot for commit bc7f54f. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
agentbox-web	Ready	Preview, Comment	Jul 29, 2026 7:50am