feat(paths): coordinate XDG-first Zi defaults and legacy migration

[ss-o]

Outcome

Make Zi resolve fresh/default storage through the XDG Base Directory model while preserving existing legacy installations and coordinating every affected repository.

Current evidence

• z-shell/zi next at 6f0eda7158289c0d6bd8f29ea589691f6a34d80e chooses $HOME/.zi whenever HOME exists. Its cache and config selection can also override explicitly set XDG variables based on directory existence.
• z-shell/src main at 5f527697e82534d07227f1be79ba0eb85c3fcec6 already defaults to ${XDG_DATA_HOME:-$HOME/.local/share}/zi, ${XDG_CACHE_HOME:-$HOME/.cache}/zi, and ${XDG_CONFIG_HOME:-$HOME/.config}/zi.
• The canonical wiki documents the XDG data-home default.
• An isolated Zsh diagnostic confirmed that sourcing the core directly and loading through the published loader select different roots under the same environment.
• No open issue or pull request explicitly tracking this unification was found on 2026-08-28.

Approved design boundary

1. Explicit ZI[...] path values remain highest precedence.
2. A detected legacy installation remains on $HOME/.zi; no automatic relocation occurs.
3. Fresh/default resolution uses valid absolute XDG variables and the specification defaults.
4. Zi creates missing destination directories instead of requiring their parents to exist.
5. Relative XDG values are invalid and ignored.
6. ZDOTDIR is not used as an application data, cache, or configuration root.
7. XDG_ZI_* compatibility outputs must not become a second ambiguous input API.
8. Migration, persistent state/log classification, installer alignment, documentation, and zpmod compatibility remain explicitly tracked deliverables.

Target defaults

Zi field	Default
ZI[HOME_DIR]	${XDG_DATA_HOME:-$HOME/.local/share}/zi
ZI[CACHE_DIR]	${XDG_CACHE_HOME:-$HOME/.cache}/zi
ZI[CONFIG_DIR]	${XDG_CONFIG_HOME:-$HOME/.config}/zi
ZPFX	${ZI[HOME_DIR]}/polaris
ZI[ZCOMPDUMP_PATH]	${ZI[CACHE_DIR]}/.zcompdump

Coordination requirements

• Use native sub-issues for each repository-owned deliverable.
• Preserve installer security validation and self-update/reload behavior.
• Add observable path-resolution coverage, including legacy-only, XDG-only, both-present, unset/empty, invalid-relative, missing-parent, spaces, and explicit override cases.
• Treat this as a public behavior change and document migration before release.
• Keep source implementation, commits, pushes, pull requests, and release work separately authorized.

Next action

Finalize the core resolver contract in the Zi implementation sub-issue, then implement it with focused behavior tests before reconciling dependent repositories.

References

• https://specifications.freedesktop.org/basedir/latest/
• https://github.com/z-shell/zi/blob/next/zi.zsh#L70-L163
• https://github.com/z-shell/src/blob/main/public/zsh/init.zsh#L13-L31
• https://github.com/z-shell/wiki/blob/main/docs/guides/02_customization.mdx#L33-L52

[ss-o]

Agent handoff

Status: In progress
Repository: z-shell/.github with cross-repository sub-issues
Branch/PR: None
Tracker/Issue: #553

Current state

• The approved XDG-first, legacy-safe architecture is recorded in this parent.
• Six native sub-issues cover Zi core, src installer/loader, wiki documentation, zpmod, explicit migration, and state/cache classification.
• Native blocker relationships record the execution order.
• All seven issues are in Z-shell Delivery Project 28 with Status, Item Type, Impact, Effort, Priority, and Workstream set.
• No source implementation, branch, commit, push, pull request, or release action has occurred.
• A required strategic Linear mirror was searched and no duplicate was found. Creation was rejected by the integration safety gate because authorization did not specifically name the connected ss-o Linear workspace and payload. Do not retry without that explicit approval.

Verification

• Parent sub-issues REST read: six expected open implementation/follow-up issues returned.
• Project 28 item read: seven expected items returned with explicit classification.
• GitHub issue reads: all seven issues are open with canonical work-type and area labels.
• Dependency reads: src, wiki, zpmod, and migration blockers resolve to the intended issue URLs.

Blockers

• Source implementation requires separate explicit authorization.
• Linear mirror requires explicit authorization to create one issue in the connected ss-o workspace, team z-shell, project Z-Shell Workspace, containing the GitHub parent/Project 28 links and approved architecture summary.

Next steps

1. Obtain source implementation authorization, then begin with the resolver truth table and focused Zi tests in fix(paths): implement an XDG-first legacy-safe resolver zi#428.
2. If explicitly authorized, create and link the single Linear strategic mirror.
3. Reconcile src, wiki, and zpmod only after the core resolver contract is finalized.

Policy drift observed

Project 28's live description references meta:initiative and runbooks/sub-issues.md, but the live z-shell/.github repository currently provides neither. This hierarchy used the existing meta:org-tracked label and native GitHub sub-issues. The drift was reported here but not fixed under the Zi scope.