docs: mirror `setup agent --env` + prod-default contract (CLI 0.0.38)

Merged
TO
3mo ago
+21-14

Mirror for insta-cli#116 per insta-cli rule 4:

  • setup agent row: --env <prod|staging> flag; bare form always targets prod (persisted switch via the env use path, foreign session dropped, announced); $INSTA_ENV counts as explicit; deliberate custom hosts left alone; the status-aware next: hint.
  • Install one-liners: staging gets its own npx line (--env staging); the env use staging + bare setup agent recipe is replaced (that sequence now switches the machine BACK to prod by design).
  • setup.md task guide mirrored the same way.

⚠️ Merge gate: with the 0.0.38 release (before that, --env is an unknown flag on the published CLI).

🤖 Generated with Claude Code


Summary by cubic

Docs mirror insta setup agent --env and the prod-default contract introduced in CLI 0.0.38. Previously setup agent inherited the current environment; now bare setup agent always targets prod and switches a staging‑leftover machine back. Staging requires --env staging, which persists the switch.

  • Update README.md, insta/cli-reference.md, insta/references/setup.md, and insta/references/mcp.md: add --env <prod|staging>, the prod-default behavior, and a staging one‑liner (npx -y insta setup agent --env staging); remove the env use staging + bare setup agent recipe and purge pre‑0.0.38 env‑inheritance wording.
  • Side effects: bare setup agent on a staging‑switched machine reverts to prod (announced). $INSTA_ENV counts as explicit. A deliberate custom host ($INSTA_API_URL or a persisted apiUrl) remains unchanged unless --env is provided. Setup ends with a status‑aware “next:” hint.
  • Rollout: merge only after CLI 0.0.38 ships. For staging, run npx -y insta setup agent --env staging; do not use env use staging followed by a bare setup agent.