feat(installer): add guided setup planner

[ss-o]

Summary

install.sh previously mixed checkout updates, startup-file edits, migration, and optional recipe execution in one operation. This adds the ADR-0025 guided setup planner with deterministic plan and separately validated apply phases, while preserving the normal curl .../install.sh | sh entry point.

• verify downloaded installer assets against the checksum manifest
• keep standalone companion downloads on one ZI_SRC_REF, defaulting to main
• validate checkout and file preconditions before mutation, with locks and receipts for drift detection
• migrate recognized direct, loader, annex, and zunit startup blocks without evaluating their values
• emit a short managed .zshrc block that sources the generated setup.zsh entry point
• defer pinned annex and zunit recipes to the first shell startup
• refuse ambiguous integrations, changed managed blocks, symlinked startup targets, and checkout drift
• exercise portable profiles on Linux, macOS, and Windows, with native zpmod builds on Linux and macOS

Compatibility

The standard one-line installer remains supported and is covered by exact curl-to-sh regressions. It stays a standalone entry point: no repository checkout is required, and it fetches verified planner assets automatically. A pinned installer can set ZI_SRC_REF to the same tag, branch, or commit so all companion assets come from one revision.

Existing custom Zi integration and symlinked .zshrc targets now require manual reconciliation, and annex or zunit recipes complete on the first shell startup. The current z-shell/zd image clones Zi directly and does not depend on this installer path.

The implementation-facing instruction route is published separately in z-shell/.github#649.

Validation

• sh tests/installers.sh (45 checks)
• POSIX sh and Bash POSIX syntax checks
• ShellCheck for public shell scripts and installer tests
• actionlint for the changed workflows
• checksum generation idempotence
• git diff --check and conflict-marker scan
• Windows Install on windows-latest for pull request and push events

Refs #208

[cloudflare-workers-and-pages]

Deploying src with    Cloudflare Pages

Latest commit:	f054431
Status:	✅  Deploy successful!
Preview URL:	https://2cf79d36.zi-src.pages.dev
Branch Preview URL:	https://feature-208.zi-src.pages.dev

View logs

[ss-o]

Fallback review under ADR-0026: Copilot request not registered on f054431

Maintainer-directed class-1 exception: this is an author-side fallback review and does not provide the independent second reader required by ADR-0026 for class-1 repositories.

No blocking findings.

Reviewed the final base-to-head diff for the standalone installer path, checksum coupling, guided plan and split apply phases, path serialization, legacy migration, checkout and file preconditions, lock behavior, symlink refusal, profile pinning, workflow changes, documentation, and issue #208 acceptance criteria.

Validation performed on the reviewed SHA:

• sh tests/installers.sh passed.
• POSIX shell syntax, git diff --check, actionlint, and ShellCheck over public/sh/*.sh passed.
• Checksum regeneration was idempotent.
• A real isolated curl | sh installation from the published feature-208 branch passed with ZI_SRC_REF=feature-208; it fetched its companion assets, cloned Zi, wrote setup files, and honored -i skip without creating .zshrc.
• All 12 hosted PR checks are green, including Linux, macOS, both Windows runs, CodeQL, configured Zsh lint, ShellCheck, and Cloudflare.

Residual gate: because z-shell/src is class 1, obtain a second human review or restored Copilot review before merge. The Cygwin job intentionally skips the native zpmod build because its packaged Zsh is too old; Linux and macOS exercise that build.