docs(cli): package and document Zoo CLI

[taltas]

Stack

Position 6 of 6 in the Zoo CLI stack.

• Parent/base: fm/zoo-cli-interactive (PR feat(cli): add interactive Zoo terminal client #1160)
• Top of stack
• Native local ancestry is preserved; GitHub uses the recorded classic fallback because native stacked PR submission is unavailable for this repository.

Scope

• Adds relocatable lockstep client, bundled private host, production extension, runtime dependencies, checksums, and supported macOS ARM64/Linux x64/Linux ARM64 release artifacts.
• Adds release gates for protocol, host, packaged subprocess, build, help, and version behavior.
• Documents installation, interactive and automation workflows, approvals/threat model, credentials/vaults, project compatibility, sessions/resume, output contracts, signals/timeouts, ephemeral behavior, supported platforms, non-goals, troubleshooting, and roo coexistence.
• Adds security, privacy/telemetry, artifact, rollback, and support review evidence.
• Links the CLI from the main README and tests documented command discoverability against live help.

Acceptance Evidence

• pnpm --dir packages/zoo-host build, test, and typecheck
• pnpm --dir apps/zoo test (11 tests) and typecheck
• Repository pre-commit lint and pre-push typecheck
• Documentation formatted and live-help consistency tested

Risk

The initial artifact matrix is intentionally narrow and release lockstep is mandatory. Modes/models metadata commands remain withheld because canonical queries currently activate mutable extension services. Signing and publication credentials remain maintainer-controlled.

flowchart LR
    C[apps/zoo client] --> A[Relocatable artifact]
    H[Bundled zoo-host] --> A
    E[Production extension] --> A
    D[Runtime dependencies] --> A
    A --> M{Supported matrix}
    M --> MA[macOS ARM64]
    M --> LX[Linux x64]
    M --> LA[Linux ARM64]
    MA --> S[Smoke, checksum, upload]
    LX --> S
    LA --> S

Loading

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f9bee49b-dec5-4a70-9b36-97a63ab5ab68

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[edelauna]

Lets also update codcov step to include CLI as well.

[edelauna]

tsup externalizes every node_modules package except those listed in noExternal — which here is only @roo-code/zoo-protocol (apps/zoo/tsup.config.ts:11). But apps/zoo/src/index.ts does import { Command, Option } from "commander" at the top of the entry module. Since this dependency object installs only ink and react, commander would not be resolvable inside the artifact — even the --help / --version smoke steps below would fail. Should commander be added here? It is not a transitive dependency of ink/react, so a fresh install cannot inherit it.

Suggested change

	node -e 'const p=require("./apps/zoo/package.json"); console.log(JSON.stringify({name:p.name,version:p.version,private:true,type:"module",dependencies:{ink:p.dependencies.ink,react:p.dependencies.react}},null,2))' > "$root/package.json"
	node -e "const p=require('./apps/zoo/package.json'); console.log(JSON.stringify({name:p.name,version:p.version,private:true,type:'module',dependencies:{ink:p.dependencies.ink,react:p.dependencies.react,commander:p.dependencies.commander}},null,2))" > "$root/package.json"

[edelauna]

stream-json and --approval are registered on the run/resume subcommands (via the automation()/shared() helpers), not on the top-level --help this test invokes. So these two assertions only ever check the markdown — a regression that silently dropped either flag from the CLI would still pass. Worth also asserting against zoo run --help?

[edelauna]

The existing cli-release.yml guards this for Linux runners with a sha256sum → shasum fallback. Should this match that pattern so the checksum doesn't depend on Perl's shasum being present on the Ubuntu runners?