Zi Setup TUI: versioned engine interface and guided pilot

[ss-o]

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

[ss-o]

Agent handoff

The Zi Setup terminal pilot is ready for maintainer review in z-shell/zi-setup#1.

• Exact head: 265fdcbed0f9994cf8c5da369b376432c2b33534 (fix: enforce setup contract invariants, signed ED25519)
• Scope: standalone Go/Bubble Tea setup client, strict v1 setup artifact parsing, shared TUI/plain/headless workflow, exact-plan phased apply, terminal sanitization, bounded diff preview, documentation, and CI/security policy
• Review fixes: protected in-flight apply from Ctrl+C; required a clean absolute receipt for successful files results; rejected selectable zunit; validated all restricted fact enums
• Hosted validation: all 12 PR checks are green, including five platform builds, tests, Go analysis, CodeQL, and four policy gates
• Local validation: go test -count=1 ./..., go test -race -count=1 ./..., go vet ./..., go mod tidy -diff, go mod verify, actionlint, and git diff --check main...HEAD
• Repository controls: settings audit passed 9/9; squash-only merge, signed commits, strict required checks, linear history, resolved-review-thread enforcement, security scanning, labels, and Renovate are configured
• Review: Copilot reviewer registration did not appear on the exact head, so the ADR-0026 fallback review was completed. It found no remaining actionable issues: feat: add Zi Setup terminal pilot zi-setup#1 (review)

Deferred beyond this pilot: release packaging, a verified bundled engine/distribution bootstrap, streaming engine events, and additional capability choices.

The PR is open and has not been merged.