/dex-update

name: dex-update
description: "Preview and safely adopt a Dex update through the receipt-backed lifecycle (look → back up → apply → verify → rewindable). Use when the user says 'update Dex', 'install the new version', or a release notice appeared. Not for undoing an update; use `dex-rollback`. Not just seeing what changed; use `dex-whats-new`."

Dex Update

Use this skill when someone wants the latest Dex capabilities or asks what an update would change. Keep the conversation plain and reassuring. The skill collects choices and renders lifecycle results; it never edits, copies, renames, deletes, or merges vault files itself.

The one route

Every lifecycle operation goes through `core.lifecycle.service` version 1.5.0. Treat its response as authoritative. Do not fall back to direct file operations, Git mutation, an update script, or a hand-built repair when the service refuses.

Whenever this skill runs a Dex Python command, use the vault's own Python: `.venv/Scripts/python.exe` on Windows, `.venv/bin/python` on a Mac or Linux computer, and plain `python3` only when the vault has no `.venv`. A system `python3` can lack the packages Dex installed into `.venv`, and then the update check quietly reports nothing.

Use the service operations in this order:

1. Ask `build_and_preview_topology_migration` to check the installed layout as part of the normal update read. 2. If it reports the older combined layout, follow the one-time migration branch below before reading the ordinary update plan. 3. Ask `build_inventory_and_plan` for the verified inventory and ledger-aware plan. 4. Render the five groups below without changing anything. 5. For safe `adopt` items, ask `build_and_preview_adoption` for the exact preview and approval token. 6. For conflict items, collect the choices below. Keep mine and Compare are read-only; Take theirs and Keep both go through `build_and_preview_conflict_resolution`. 7. Show every proposed file from each preview. Execution requires an explicit yes to that exact preview. 8. Pass unchanged adoption previews and tokens to `execute_approved_adoption`, and unchanged resolution previews and tokens to `execute_approved_conflict_resolution`. 9. Ask `read_lifecycle_state` for the verified post-update state and retention warning, then render every receipt.

For a split vault whose update needs new release bytes, never ask the user to run Git. Before presenting a delivery update, ask `deliver_latest_release` through `core.lifecycle.service`. It proves the newest immutable release in an isolated cache, fetches only that pinned tag and its release-channel ref into Dex's private brain store, then proves the fetched bytes again. This delivery step does not change vault content.

Only when delivery returns its exact release identity, ask `build_and_preview_delivered_release` through `core.lifecycle.service` with that identity. Show every returned write and ask: “Apply this exact update?” Only a fresh explicit yes to that unchanged preview permits `execute_approved_delivered_release` with the same preview and approval token. Render its lifecycle receipt. Then ask `read_lifecycle_state` — the applied version now appears in the same rewind list `/dex-rollback` uses. If delivery, preview, or execution refuses, stop; no vault-content change was made.

**Immediately after a successful apply, run the post-update canary** — one read-only walk through the same doors every later command will use. From the vault root, run `core/health/post_update.py --vault .` with the vault Python when it exists. Prefer `.venv/Scripts/python.exe` on Windows, then `.venv/bin/python` on a Mac or Linux computer, otherwise `python3`. The direct file path matters: it keeps the canary runnable even when the installed packages are the thing that broke.

Relay its complete result verbatim, including any extra line about a proof record that still names the previous version. That leftover is expected: nothing refreshes the record during an update. Say it needs refreshing and give the one command the check printed. Do not say the record can't be trusted or was rejected. On failure, treat it as part of this update, not a separate errand: tell the user plainly that the update applied but something is wrong underneath, and run `/dex-doctor` now. Never report the update as complete while the canary is failing.

Newly written `.claude/skills/*/SKILL.md` files are live in this session. The host slash list may still omit them until the next session; that does not make them unavailable. If the user asks for a skill that now has a SKILL.md on disk, Read that file and follow it. Do not tell them to restart first.

If the service reports UNKNOWN, conflict, changed evidence, an unsafe path, or a rejected transaction, stop. Explain the refusal in ordinary language and leave the vault untouched. A refusal is a safety result, not an invitation to work around the engine.

One-time brain and vault upgrade

The topology check can report that this Dex still keeps the product and the user's notes in one combined history. In that case, the service runs the shipped migrator in `dry-run` mode. This only prepares the local report; it does not start the move.

Render the topology preview in the same five groups used for the ordinary update. The proposed move appears under **Needs your review**. Show the complete report returned by the service and explain:

• Dex will separate its own product history from the user's private vault history.
• Notes, tasks, projects, people, and custom additions stay where they are.
• The new private vault history gets no remote, so Dex does not upload it.
• The old combined history becomes the local undo archive named in the final receipt.

Ask: “Make this exact one-time change?” Only an explicit yes to this displayed report authorizes the move. The earlier request to “update Dex” is not approval. Pass the unchanged preview and approval token to `execute_approved_topology_migration`.

The lifecycle