docs: rewrite README for a public audience, split contributor docs out

[CarmenDou]

insta-cli is public, and its README had drifted well behind the CLI. This rewrites it for an outside reader and moves contributor material into a new CONTRIBUTING.md.

What was wrong

Verified against src/index.ts, src/env.ts, install.sh and the npm registry:

Issue	Detail
Command coverage	Documented ~35 of 60 leaf commands. Missing: setup agent, mcp install, run, regions, all seven compute subcommands, all four observe subcommands, upgrade/autoupdate, branch merge, services rename/set-access/secrets, secrets set/unset/tree
Wrong default	Quickstart said the API defaults to http://localhost:8080; DEFAULT_ENV is prod → https://api.instacloud.com
Wrong skill ref	Environments table said insta-skills@devel; the code uses #devel, and env.ts documents that the @ form is parsed as a skill-name filter and silently resolves to main
Stale caveat	A blockquote warned that the staging one-liner 404s until agents-staging.sh lands on main. It is on main
Stale roadmap	Closing note said "image building will come later"; deploy [dir] with remote Fly builds shipped
Missing install path	The npm package insta was never mentioned
Dead link	[platform](../platform) resolves inside the insta-cloud superproject but 404s on github.com, and insta-platform is private
No license section	Repo is Apache-2.0

Approach to the command list

AGENTS.md already designates insta/cli-reference.md in InsForge/insta-skills as the agent-facing surface doc that command and flag changes must be mirrored into. The README was maintaining a second, worse copy of the same table — which is how it drifted.

So the README now lists all 13 command groups and 13 top-level commands at group granularity (the whole surface is visible, nothing hidden) and links to cli-reference.md for flags, approval gates and plan limits. Command names change rarely; flags are what drifted.

Structure

Rewrote around what a reader needs in order: install → quickstart → the four concepts that make the CLI make sense (branch-scoped services, the credential seam, approvals, the agent surface) → environments → commands → configuration. Dropped the patched-in blockquotes, the inline comment stacks inside copy-paste code blocks, and the four separate passes over "prod and staging are different deployments".

New CONTRIBUTING.md takes the dev loop, src/ architecture, the cli-reference mirroring rule, PR conventions, Bun cross-compilation, the release process, and pointing the CLI at a local control plane.

Checks

npm run typecheck clean; npm test 161 passing across 20 files. Docs-only change.

Companion PR for insta-skills follows.

---

Summary by cubic

Rewrite the README for a public audience and align it with the current CLI; move contributor docs into CONTRIBUTING.md. Clarifies install/auth, environments, and the full command surface; fixes staging details, updates the tech stack, and retitles the README to match the repo.

• Docs
  • Split contributor content to CONTRIBUTING.md; add tech stack (Node ≥18, TypeScript ESM, commander) and build/release steps.
  • Install: binary and npm paths, agent one‑liner; explicit staging installer (install.sh --agents --staging -y) with CloudFront cache note; auto‑update behavior and insta autoupdate toggle.
  • Authentication: OAuth loopback flow and insta login --env; control‑plane callback requirement {INSTA_API_BASE_URL}/api/auth/callback/<provider>; token storage/refresh.
  • Environments: correct defaults; staging skill source InsForge/insta-skills#devel; hard‑fail when environment can’t be applied (<0.0.23).
  • Commands: list all command groups with a link to insta/cli-reference.md; document that insta status shows environment, login, and linked project/branch.
  • Cleanup: keep the “secret seam”; remove stale notes and dead links; retitle the README to match the repository name.

^{Written for commit 48c0fae. Summary will update on new commits.}

[jwfing]

Review: docs — README rewrite + split out CONTRIBUTING.md

Summary: A docs-only rewrite of README.md for an external audience plus a new CONTRIBUTING.md; I verified essentially every factual claim against the source of truth and it all holds up.

Requirements context

No matching spec/plan found — this repo has no docs/superpowers/ (and no docs/ directory at all), so I assessed against the PR description and the actual sources it claims to have been verified against: src/index.ts, src/env.ts, src/config.ts, src/commands/auth.ts, install.sh, .github/workflows/release.yml, package.json, and LICENSE.

Findings

Critical

(none)

Suggestion

• Functionality / cross-repo link dependency — README.md and CONTRIBUTING.md point the reader at insta/cli-reference.md on insta-skills@main as the flag-level reference. The PR body notes a companion insta-skills PR "follows". Since the README now delegates flag/approval/plan-limit accuracy to that file, the linked main copy should already be current (or the companion PR merged first) so a reader following the link on merge day doesn't hit a stale reference. Prod's skill source is main, so the link target itself is correct — this is a sequencing note, not a defect.

Information

• Software engineering (test coverage) — Docs-only change; no runtime surface, so no new tests are warranted. PR states npm run typecheck clean and npm test 161 passing; the repo gates are ci (typecheck + vitest), consistent with CONTRIBUTING.md.
• Functionality (verification notes) — Spot-checked the specific corrections claimed in the PR body and all are accurate:
  • Command surface matches src/index.ts:55-228 at group granularity — setup agent, mcp install, run, regions, the 7 compute subcommands (start/stop/suspend/status/set-domain/check-domain/remove-domain), the 4 observe subcommands, branch merge, services rename/set-access/secrets, and secrets set/unset/tree are all present.
  • Default env: DEFAULT_ENV = 'prod' → https://api.instacloud.com (src/env.ts:30-43) — the old localhost:8080 default is correctly gone.
  • Staging skill ref is InsForge/insta-skills#devel (src/env.ts:39), and the @-form pitfall is documented in env.ts:22-26 — the fix is real.
  • install.sh: installs to ~/.insta/bin, verifies SHA256SUMS, honours INSTA_VERSION/INSTA_INSTALL_DIR, and hard-fails (exit 1, "still pointed at PRODUCTION", >= 0.0.23) at install.sh:206-218 — matches the README's claim exactly.
  • All nine documented env vars exist in source (INSTA_API_URL, INSTA_ENV, INSTA_MCP_URL, INSTA_SKILLS_REPO, INSTA_PROJECT_ID, INSTA_ORG_ID, INSTA_BRANCH, INSTA_PASSWORD, INSTA_NO_AUTOUPDATE).
  • release.yml builds five platform binaries + SHA256SUMS and publishes to npm via OIDC trusted publishing with --provenance — matches CONTRIBUTING.md.
  • LICENSE is Apache-2.0; npm package name is insta; .claude/skills/developing-insta-cli/SKILL.md referenced by CONTRIBUTING.md exists.
• Security — No security-relevant changes. Worth noting the OAuth self-hosting instructions are correct and safety-relevant: the loopback listener binds 127.0.0.1 and the browser opens {apiUrl}/auth/cli/authorize (src/commands/auth.ts:67-71), and the README correctly directs the provider callback to the control plane ({INSTA_API_BASE_URL}/api/auth/callback/<provider>), not the loopback address.
• Performance — N/A (documentation).
• Minor — release.yml:69-72 computes SHA256SUMS over the raw binary names then gzips the linux/darwin assets, so the actual release download is insta-linux-x64.gz etc. (install.sh gunzips transparently). CONTRIBUTING.md's "artifacts are named insta-linux-x64 … and are real native executables" describes the logical/checksum names, which is fine — flagging only for completeness.

Verdict

approved (informational; a human still gives the GitHub approval). Zero Critical findings — this is a careful, well-verified docs rewrite that brings the README back in line with the current CLI. The one Suggestion is a merge-sequencing note on the companion insta-skills PR, not a blocker.

[jwfing]

LGTM - approved.

[cubic-dev-ai]

No issues found across 2 files

_{Re-trigger cubic}

[cubic-dev-ai]

1 issue found across 2 files (changes from recent commits).

Prompt for AI agents (unresolved issues)

Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.


<file name="CONTRIBUTING.md">

<violation number="1" location="CONTRIBUTING.md:23">
P3: The statement 'Every command wraps one control-plane API call' is not accurate for `insta upgrade`, which fetches from GitHub/npm registries and does not call the control-plane API.</violation>
</file>

<sub>Reply with feedback, questions, or to request a fix.

Re-trigger cubic</sub>

[cubic-dev-ai]

P3: The statement 'Every command wraps one control-plane API call' is not accurate for insta upgrade, which fetches from GitHub/npm registries and does not call the control-plane API.

Prompt for AI agents

Check if this issue is valid — if so, understand the root cause and fix it. At CONTRIBUTING.md, line 23:

<comment>The statement 'Every command wraps one control-plane API call' is not accurate for `insta upgrade`, which fetches from GitHub/npm registries and does not call the control-plane API.</comment>

<file context>
@@ -19,6 +19,9 @@ Run `npm run typecheck && npm test` before every commit.
 ## Architecture
 
+Node 18 or newer, TypeScript compiled to ESM, [commander](https://github.com/tj/commander.js)
+for the command surface. Every command wraps one control-plane API call.
+
 | Path | Responsibility |
</file context>