Zi Setup TUI: versioned engine interface and guided pilot #222

Trigger

ADR-0025 deferred a terminal interface until the guided setup planner shipped and the maintainer recorded that the interface had become the adoption bottleneck. The planner shipped in src#221. Its manual plan and phased apply commands are safe and reviewable, but using them directly requires knowledge of installer paths, plan artifacts, hashes, migration rules, and partial-failure handling. That is now the main obstacle to the intended guided onboarding flow.

This issue records the ADR-0025 trigger and owns the next bounded milestone.

Scope

1. Add versioned, machine-readable directory artifacts to public/sh/setup.sh:
   • bounded read-only describe --output DIR discovery;
   • documented operations and warnings in zi-setup-plan-v1;
   • apply --result DIR result artifacts with stable error codes and exit statuses.
2. Keep the planner as the only authority for path resolution, generated Zsh, file changes, preconditions, application, and receipts.
3. Build a local Go and Bubble Tea v2 pilot for Discover -> Choose -> Review -> Apply -> Result after the engine contract is tested.
4. Offer loader and annex as the only selectable profiles. Keep zunit solely for compatibility when migrating existing installer output.
5. Validate the flow in disposable homes, including reopen with no content changes, drift refusal, symlink refusal, partial failure, plain mode, and an 80x24 terminal.

Boundaries

• No arbitrary plugin marketplace, prompt replacement, other-manager removal, package or font installation, chsh, daemon, or current-shell mutation.
• Unknown Zsh integrations remain untouched and receive patch or remediation guidance.
• Normal shell startup does not execute or depend on the TUI.
• Repository creation, release publication, and distribution bootstrap remain separately authorized work.

Acceptance

• Engine artifacts have explicit version identifiers, atomic publication, compatibility tests, and no decision-making dependency on human-readable output.
• TUI and plain modes pass the same arguments and approve the same plan hash for identical inputs.
• Apply always binds to the reviewed plan hash and reports checkout and files phases separately.
• Existing sh tests/installers.sh checks remain green on supported CI platforms.

References

• ADR-0025: https://github.com/z-shell/.github/blob/main/decisions/0025-guided-setup-planner-first.md
• Planner implementation: feat(installer): add guided setup planner #221
• Planner contract issue: Guided setup planner: implementation contract deferred from ADR-0025 review #208