You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds an Agent tab to docs/getting_started/01_installation.mdx beside the existing automated-setup tabs, for AI coding agents installing Zi on a user's behalf. It is the human-facing companion of the zi-install skill (z-shell/.github#637, #638) and follows the same procedure.
Fetch the installer to a file, compare its sha256 with the public/sh/install.sh line of the published checksum, and run the file with one of the two supported profiles: -a loader, or -i skip for install-only. The sh -c "$(curl ...)" form is called out as unsafe for agents because a failed fetch becomes an empty script that exits 0.
The rules an agent must follow: drive the installer with its flags, never edit .zshrc or the Zi configuration home, respect ZDOTDIR and absolute XDG_* values and stop on a relative ZDOTDIR or ZI_HOME, do not run as root, do not start an interactive shell during installation, read the installer's result lines and stop on its refusals.
Verification per profile: a fresh zsh -ic 'zi -h', then for the loader profile the skill's probe that sources the installed init.zsh in a clean shell, runs zzinit, and requires every helper to be removed; install-only sources zi.zsh from the checkout directory the installer printed on either the fresh-install or the update path.
A copyable instruction block for agents that cannot load the skill.
Per the issue's constraint, the planner from ADR-0025 (z-shell/src#208) is not mentioned until it ships, and no second way to write configuration is described.
pnpm build:en: pass; the built installation.html contains the tab's verification lines and the instruction block.
Prettier 3.9.7 with .trunk/configs/.prettierrc.json: clean.
The documented fetch, checksum, install, and probe sequence was run from the fences in an isolated home (HOME, ZDOTDIR, and all XDG_* redirected) against the current installer: checksum ok, Loader added, zi ok, loader ok. A rerun prints the update line and appends nothing to .zshrc; the probe prints loader missing on an install-only home; a failed fetch exits 22 before anything runs.
Finding outside this change
The installer's success line prints the checkout path with a trailing period, filed as z-shell/src#215.
Add an Agent tab beside the existing automated-setup tabs with the two supported non-interactive installer invocations (`-a loader`, and `-i skip` for install-only), the rules an agent must follow (drive the installer, never edit `.zshrc` or the configuration home, respect `ZDOTDIR` and absolute `XDG_*` values, no root, no interactive shell during installation, stop on installer refusals), verification for each profile, and a copyable instruction block that names the planned `zi-install` skill.
The tab documents the installer as it is on z-shell/src main after #210 and #214; the planner from ADR-0025 (z-shell/src#208) is not mentioned until it ships.
Closes#921
…te message in the Agent tab
Address the Copilot review on #922. The Agent tab now downloads the installer with curl or wget to a file, compares its sha256 with the published checksum, and runs the file, so a failed download exits non-zero instead of handing an empty script to sh. The environment rule tells the agent to stop on a relative ZDOTDIR or ZI_HOME, since the installer changes directory before using them. Install-only verification accepts the checkout directory printed by either the fresh-install or the update path and states that it already includes the bin checkout name. The copyable instruction block carries the same changes.
… skill
z-shell/.github#637 and #638 published the zi-install skill while #922 was open. Link the tab and the copyable block to the skill instead of the tracking issue, adopt its fetch, verify, and run sequence with an exact checksum comparison, its reading of the installer's result lines, and its positive loader probe: sourcing the installed init.zsh in a clean shell, running zzinit, and requiring every loader helper to be removed. The earlier check passed for a pre-existing direct integration without the loader ever running.
Loader probe can pass without running the new loader
docs/getting_started/01_installation.mdx:129
This loader check, repeated in the copyable block on line 154, can report success without proving that the new loader ran. zsh -ic may load zi from an existing integration, and an absent zzinit does not prove this loader defined, invoked, and removed it; the other loader helpers are not checked either. Replace both occurrences with the published skill's clean zsh -f probe, which sources the resolved init.zsh, requires and runs zzinit, then verifies that every loader helper was removed.
Link directly to the published companion skill
docs/getting_started/01_installation.mdx:138
The companion skill is already published: z-shell/.github#636 is completed and .github/skills/zi-install/SKILL.md exists on main. Update this sentence to link the published skill directly, and put that direct URL in the standalone handoff on line 156 instead of describing the skill as merely available.
…d flag the trailing period
Address the Copilot review of c5ba935 on #922. The skill install command carries `--pin <commit>` so an installed copy is a reviewed revision. The checksum fence uses sha256sum and falls back to shasum -a 256, prints nothing with neither tool, on a mismatch, or on a missing line, and was tested in all four states. The install-only verification says the fresh-install line currently ends with a period that is not part of the path (z-shell/src#215), and the copyable block says the same.
Clarify expected annex output and fast-forward refusal conditions
docs/getting_started/01_installation.mdx:127
The result guidance misclassifies normal and failed update output. Both supported profiles print Skipped all annexes, so telling agents to stop whenever the installer “skips” makes a successful run look like a refusal. Also, cannot be fast-forwarded can be caused by local commits as well as uncommitted changes. Mark the annex line as expected, and describe the fast-forward refusal as local commits or changes so agents stop for the right conditions.
Separate verification steps for Loader-only and install-only profiles
docs/getting_started/01_installation.mdx:170
The handoff does not clearly separate verification by profile. An install-only run intentionally leaves .zshrc untouched, so running zsh -ic 'zi -h' or the loader probe can report failure after a valid install. State that both checks are Loader-only and that install-only uses only the printed-checkout zi.zsh check.
… verification by profile
Address the two notes in the Copilot review of ceebb3d on #922. `Skipped all annexes` is printed on every loader and default run, so the result guidance names it as expected output and lists only the three refusal lines as stop conditions; the fast-forward refusal covers local commits as well as changes. The loader checks are stated as loader-only, install-only keeps its single check, and the copyable block separates the two.
An explicit ZI_HOME breaks the Loader profile documented here. The installer clones Zi under that root, but the generated init.zsh does not read ZI_HOME; without a preconfigured ZI[HOME_DIR], it resolves only the legacy or XDG home. A fresh -a loader run can therefore install successfully in the requested root and then make zsh -ic 'zi -h' look elsewhere. Until the installer and loader share this setting, limit explicit ZI_HOME to install-only and make the same restriction in the companion skill.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds an Agent tab to
docs/getting_started/01_installation.mdxbeside the existing automated-setup tabs, for AI coding agents installing Zi on a user's behalf. It is the human-facing companion of the zi-install skill (z-shell/.github#637, #638) and follows the same procedure.public/sh/install.shline of the published checksum, and run the file with one of the two supported profiles:-a loader, or-i skipfor install-only. Thesh -c "$(curl ...)"form is called out as unsafe for agents because a failed fetch becomes an empty script that exits 0..zshrcor the Zi configuration home, respectZDOTDIRand absoluteXDG_*values and stop on a relativeZDOTDIRorZI_HOME, do not run as root, do not start an interactive shell during installation, read the installer's result lines and stop on its refusals.zsh -ic 'zi -h', then for the loader profile the skill's probe that sources the installedinit.zshin a clean shell, runszzinit, and requires every helper to be removed; install-only sourceszi.zshfrom the checkout directory the installer printed on either the fresh-install or the update path.Per the issue's constraint, the planner from ADR-0025 (z-shell/src#208) is not mentioned until it ships, and no second way to write configuration is described.
Closes #921
Verification
pnpm validate:code-fences,pnpm validate:frontmatter: pass.pnpm build:en: pass; the builtinstallation.htmlcontains the tab's verification lines and the instruction block..trunk/configs/.prettierrc.json: clean.HOME,ZDOTDIR, and allXDG_*redirected) against the current installer:checksum ok,Loader added,zi ok,loader ok. A rerun prints the update line and appends nothing to.zshrc; the probe printsloader missingon an install-only home; a failed fetch exits 22 before anything runs.Finding outside this change
The installer's success line prints the checkout path with a trailing period, filed as z-shell/src#215.