/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.4.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.

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. If delivery, preview, or execution refuses, stop; no vault-content change was made.

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 service owns the conversion and recovery loop. If the migrator returns exit code 75, the service routes it through resume until the bounded work is complete. Never run `--auto`, `--resume`, or the migrator directly from this skill.

After success, show the topology receipt, including its transaction identifier, final report, undo archive when present, and each auto/resume attempt. Ask `build_and_preview_topology_migration` again and continue with the ordinary update only when it reports the split as complete.

If the dry-run fails, the report changes before approval, approval is missing, conversion stops, or the final split cannot be proved, show the service refusal and stop. Do not improvise a repair.

One-time local connection refresh

After the topology branch (or at the start of a split-vault update), ask `build_and_preview_mcp_registration`. This checks whether Dex's own Customization Migration connection is missing from an older local setup.

• If `needed` is `false`, say that Dex's local connections are already current and continue.
• If `needed` is `true`, show the returned server name and the complete write preview. Explain: “Dex will add this one Dex-owned local connection. It will not replace, remove, or alter any of your existing connections or their settings.” Ask: “Add this exact Dex connection?”
• Only after a fresh explicit yes, pass the unchanged preview and approval token to `execute_approved_mcp_registration`. Render its transaction receipt, including the saved recovery snapshot.

This is the only update route allowed to add this missing Dex-owned registration. Never edit `.mcp.json` directly, replace an existing server entry, or treat the earlier update approval as approval for this connection change.

Deeply customised setup

Before applyi