docs: add What Happens During a Migration for Talos Director

[sterlingkoch]

What

A new explanation page, What Happens During a Migration, under Compute.

Why

Migrate from VMware is the console how-to. Someone planning a migration also needs to know where a conversion runs, what each stage changes, what each cutover mode does to the source VM, and what happens when something fails. That is explanation, so it gets its own page rather than growing the how-to.

Change

• New page public/director/compute/what-happens-during-a-migration.mdx: planning in waves, where the conversion runs, prerequisites (including the VDDK fallback), the stages with a Mermaid diagram and status table, cutover modes, failure handling, and the other import paths (OVF, existing disk images, cross-cluster, cross-instance).
• Nav entry after Migrate from VMware in director.yaml, and the regenerated docs.json.
• A one-sentence link from the Migrate from VMware intro.

Testing

• Ran: make style-check-changed-local, npx mint broken-links, and npx mint dev, with the diagram checked in light and dark mode.
• By: an agent (Cursor), reviewed by Sterling.
• Result: no style errors, no broken links.
• Filled from outside the page: the migration engine's stages and failure behavior, from engineering review of the Talos Director overview draft.

[mintlify]

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated
siderolabs	🟢 Ready	View Preview	Oct 16, 2026, 7:25 AM

💡 Tip: Enable Automations to automatically generate PRs for you.

[github-actions]

📋 Automated documentation review

⚠️ The reviewer did not finish on commit 3fb549b (it timed out or errored) — see the workflow run log. This run did not produce a result; any findings from an earlier run on this PR still stand.

[Iheanacho-ai]

i think this doc is headed like a feature article rather than documentation, and might be difficult to search and find things. other headings i suggest are:

Before anything is copied --> Requirements
The stages --> Conversion stages
What each cutover mode does to the source --> Cutover modes
If something goes wrong --> Failure handling and rollback
Other ways in --> Other migration methods

[Iheanacho-ai]

this makes it seem like this section is describing how to plan a migration. would this be a better heading "Converting VMs in waves."

[Iheanacho-ai]

these are what claude said, are the code red reviews on this pr, what do you think of them:

These four could cause real harm if they're wrong. Everything else is clarity or polish.

1. Downtime is understated. The Note and the mode table say the outage is shutdown, final delta, and first boot. The diagram puts Converting and Customizing inside the outage too, and a full qemu-img conversion can take a long time. A team that plans its maintenance window from the table could overrun it. This is the most important one.

2. Cancel and rollback promise more than they deliver. "The source VM is left as the engine found it" can't hold if you cancel after cutover, because the source is already shut down and VMware Tools are gone. "Rolling back means powering it on again" also skips that the source no longer has Tools. Rollback is what people rely on when things go wrong, so it has to be accurate.

3. The force window may mean a hard power-off. "The engine proceeds anyway" sounds harmless. If it actually forces the source off, the final delta comes from a VM that wasn't shut down cleanly, which is a data-consistency risk for databases and similar workloads. Readers need to know before they pick a force window.

4. A warm job without VDDK may not actually be warm. If vCenter's standard export can't do changed-block deltas, a "scheduled" or "automatic" job without VDDK is effectively a full copy. The mode table would then promise a short outage that doesn't happen.

All four need an engineer to confirm before you rewrite anything, since I can't check them against the source. The wording of each fix depends on the answer.

[Iheanacho-ai]

claude said there are some contradictions here:

• **VDDK required versus optional. This page says scheduled and automatic cutover require VDDK and fail without it. The wizard page, corrected in docs: Talos Director corrections (NSX, VDDK, SIEM export, VM sizing, platform diagram) #857, says that without VDDK a warm conversion falls back to vCenter’s standard export. One of them is wrong. Confirm with Sterling before either page ships.
• Where you upload VDDK. This page says Settings > VM > Conversion. The wizard page says the content library.
• What the guest credentials are for. This page says reading the network configuration and post-boot configuration. The wizard page says reading the network configuration and removing VMware Tools.
• VMware Tools removal. This page says three different things:
  • Customizing removes open-vm-tools from Linux guests.
  • Starting removes VMware Tools from Windows guests “if you asked for it”.
  • Rollback says the source “keeps its VMware Tools”.

The last one is about the source VM, so it’s technically consistent, but readers will trip over it. Also, the wizard page has no option for “if you asked for it”. Is it a field in Configure?

• Where virt-v2v belongs. The Converting row lists it next to disk format. In the wizard, virt-v2v is a separate field, Conversion Method (Direct versus virt-v2v), not a disk format. Move it out of the format sentence, or explain how the method changes the Converting stage.

• Scheduled cutover downtime. The wizard page says “a brief final sync”. This page correctly says the outage also includes conversion, customization, and VM creation. The wizard page’s line needs updating to match.**