docs(paths): document XDG-first Zi defaults and legacy migration

[ss-o]

Summary

Document the finalized XDG-first Zi path behavior, legacy preservation, and explicit migration workflow in the canonical wiki.

Deliverables

• Keep the customization path table synchronized with the implemented resolver.
• Explain precedence: explicit ZI[...], detected legacy installation, valid absolute XDG value, then XDG specification fallback.
• Document that ZDOTDIR is not a Zi application-data root.
• Add a legacy-installation section explaining why $HOME/.zi may remain active and how users can opt into migration.
• Document the both-roots-present diagnostic and recovery steps.
• Review active examples for misleading hard-coded $HOME/.zi defaults while preserving clearly historical terminal recordings where source fidelity matters.
• Link to the migration feature issue until an automated command is released.

Verification

• Check all path examples against the finalized Zi and src behavior.
• Run the wiki's existing documentation checks.
• Verify links and anchors.

Dependency

Final wording depends on the Zi core resolver and installer reconciliation. Drafting may begin earlier, but publication must not describe unshipped behavior as current.

Next action

Inventory the active installation and customization pages that state a default path and prepare a synchronized update after the resolver lands.

[ss-o]

Local documentation reconciliation is complete and uncommitted in the docs/init-loader-defaults worktree behind open PR #890. The remote PR is unchanged.

The canonical customization page now documents explicit-overrides first, recognized legacy retention, absolute XDG validation, specification fallbacks, ZDOTDIR exclusion, derived-only XDG_ZI_* outputs, both-present diagnostics, and the no-automatic-migration boundary with a link to zi#429. Loader installation examples validate absolute config paths, and active ZPFX prose now derives from ZI[HOME_DIR]; historical recorded legacy paths were preserved.

Validation:

• code-fence validator passes;
• frontmatter validator passes;
• plugin-standard validator passes 25/25;
• pnpm build:en passes with 75 artifacts, 69 canonical documents, 74 link-bearing files, and 9/9 corpus tests;
• git diff --check passes.

No commit, push, PR update, or publication was performed.