Dex Update

<!-- Generated from `.claude/skills/dex-update/SKILL.md` by `scripts/generate-agents-skills.py`. Do not edit. -->

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.

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 one-line result verbatim. 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 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 applying an update, collect the deep Doctor report with python3 core/utils/doctor.py --deep. JSON is stdout-only; progress is stderr. This returns JSON on stdout: every check with a verdict (OK / OFF / BROKEN / UNKNOWN), any Tier-1 heals already applied, and an instruments block saying whether the doctor itself ran completely. While it runs, stderr prints Checking this Dex install (read-only)..., then names each check as it starts (for example Checking customizations.assessment...). If a run sits still, the last named check is the one that is stuck. If the collector itself fails to run: that IS the finding. Report it first, with the error. Use that report to decide whether to offer this branch. Offer it when customization_assessment.completeness is OK and customization_assessment.identity.customization_count is at least 1, or when the user says they have customised Dex heavily. If the verified count is zero, follow the normal lightweight update path and do not mention this branch. If completeness is UNKNOWN, or the report has no customization_assessment, show Doctor's uncertainty and do not infer a zero count. If the uncertainty is that Dex could not verify which version is installed (baseline-not-verified, or Doctor's "couldn't verify which Dex version is installed" line), point at the starting-version repair — the person runs python3 -m core.update.reanchor_cli --dry-run in their own terminal — and do not continue this update until that repair has set a starting version. Do not run the repair yourself. When Doctor returns partial: true, show the observed records and every exclusion path, reason, and guidance as a partial inventory. Do not run the Capsule preview or ask for Capsule approval until reassessment returns completeness OK.

Detect and explain

Render what the assessment found through /dex-doctor Step 3b's authority rules, including all four returned groups. Explain that this journey inventories what the user changed, preserves the evidence in a protected snapshot called the Capsule, guides the update through the existing approval flow, and then offers the rebuild with this exact promise: “rebuilds your customisations on the new version, shows you anything it can't safely carry forward, and the declared write set is previewed and snapshotted; rewind remains available while its snapshot is retained among the newest three and the activated files remain unchanged.”

A Capsule is a protected local snapshot of the evidence for every customization. It is stored under System/.dex/, is never uploaded, and survives the update. This is not an automatic rebuild: candidate planning, staging, activation, and rewind each keep their own authority boundary.

Preview and create the Capsule

Run python3 -m core.customization_migration.cli preview. Show every returned preview line and the preview_sha256 verbatim. Then ask: “Create this exact snapshot?” The earlier request to “update Dex” is not approval.

Only after a fresh explicit yes, run python3 -m core.customization_migration.cli create --confirm-token PREVIEW_SHA256 with the unchanged digest from that preview. The returned Capsule receipt is authority: render its capsule_id, file_count, byte_count, and transaction_id verbatim. Do not say the evidence is preserved until that receipt exists.

Proceed through the normal update

After the Capsule receipt exists, return to the one-route lifecycle above and use its normal preview and approval flow unchanged. Conflicts still offer Keep mine / Take theirs / Keep both, with Compare available before the user chooses. Capsule approval never counts as update or conflict approval.

Re-check after the update

Read migration_status_to_dict through Doctor's customization_migration_status section or the registered Customization Migration MCP status tool. Reproduce the Capsule id, state, validation status, mismatches, and pending flag. Say the Capsule is intact only when its validation status is OK; otherwise say the preserved evidence cannot be verified and follow /dex-update guidance without inventing repair steps.

Run the deep customization assessment again and render it through the Step 3b authority rules. State plainly which customizations are in update-replaceable-location and which are in update-untouched-location. Do not rename those groups or claim that a location predicts an automatic rebuild.

CLAUDE.md differences are file-level evidence, never an orphan-line list. Do not tell the user to move any differing line into CLAUDE-custom.md. Use Compare and the lifecycle conflict choices without raw file edits.

Propose the rebuild

Read the Capsule evidence only through the registered MCP. Use read_customization_capsule_section for evidence and read_customization_capsule_blob with the exact Capsule id and SHA-256 for source bytes. Author candidates only from that evidence and those readable blobs. Classify an item manual when its source is restricted or model-unreadable; never reconstruct it from memory. Author one canonical candidate in a local scratch file outside the vault named CANDIDATE_JSON. The no-token stage command makes no vault write: it parses the closed candidate shape and delegates to validate_regeneration_candidate before it returns a preview. Run that preview before proposing the candidate. Every customization must have exactly one disposition; never omit an item or use model confidence as verification.

Present every disposition and its evidence. If an item is blocked or needs manual review, present one question at a time. Update and revalidate the candidate after each answer. Do not stage while required questions remain unresolved or exact-set validation refuses the candidate.

Stage and verify

Run python3 -m core.customization_migration.cli stage CANDIDATE_JSON to obtain the private staging preview. Render every line, including every disposition, future live path, and preview_sha256. Ask: “Stage this exact candidate for verification?” Capsule approval and update approval do not count.

Only after a fresh explicit yes, run python3 -m core.customization_migration.cli stage CANDIDATE_JSON --confirm-token PREVIEW_SHA256 with the unchanged token. Render the CLI's safe staging receipt summary.

Run python3 -m core.customization_migration.cli verify CAPSULE_ID PROPOSAL_ID to preview the verification verdict and obtain VERIFICATION_TOKEN; this makes no verification-report write. Ask: “Seal this exact verification report?” Only after a fresh explicit yes, run python3 -m core.customization_migration.cli verify CAPSULE_ID PROPOSAL_ID --confirm-token VERIFICATION_TOKEN. Render only the CLI's safe verification and receipt summaries. Treat a result as verified only when the engine says verified. If the returned per-item value is manual, render manual; if it is unknown, render unknown. Never promote either one, and never describe a blocked report as complete.