docs: AGENTS.md + CLAUDE.md; enrich developing-insta-cli

[jwfing]

Per-repo agent context; keeps the existing developing-insta-cli skill as canonical.

What

• AGENTS.md — always-on rules (main protected → PR-only/squash/1 review, feat/*/fix/* off main, submodule commit-order, pre-commit gate, mirror command changes into skills/insta/cli-reference.md) + a pointer to the skill. Read by Claude Code, Codex, and other AGENTS.md-aware tools.
• CLAUDE.md — @AGENTS.md (matches the frontend/ convention).
• developing-insta-cli skill — folded in a src/ architecture map + the cli-reference sync rule it lacked. Existing dev-loop / PR-approval / release content unchanged.

Naming follows this repo's existing developing-insta-cli (other insta-cloud submodules use developing-on-<module>).

🤖 Generated with Claude Code

[jwfing]

Summary

Docs-only PR adding an always-on CLAUDE.md and folding a src/ architecture map + cli-reference sync rule into the developing-insta-cli skill; tightly scoped (+40/−0, 2 files) and accurate apart from a couple of gaps in the command-group enumeration.

Requirements context

No matching spec/plan found — this repo has no docs/superpowers/ (nor a docs/ directory at all), so I assessed against the PR description alone plus the actual src/ tree at head (51387c8). The PR's own stated intent is "orientation layer without duplicating the existing skill," and the doc explicitly positions the command surface as "how agents learn the CLI" — so I checked the map against the real source.

Findings

Critical

(none)

Suggestion

• Functionality / accuracy — commands/ row omits two real command groups. .claude/skills/developing-insta-cli/SKILL.md:29 states "one file per command group" and then enumerates auth org project services branch secrets deploy compute upgrade metrics (+logs) billing govern manifest observe. But src/commands/ also contains run.ts and setup.ts, both imported and registered in index.ts (run <cmd> [args...] at src/index.ts:62, imported src/index.ts:8; setup group at src/index.ts:68, imported src/index.ts:7). Since the doc's purpose is to be the authoritative source-tree map for agents, an incomplete "one file per group" list will mislead. Please add run and setup.

Information

• resolve-project.ts not in the architecture table. The table (SKILL.md:24-31) maps the src/ top level but omits src/resolve-project.ts (a distinct module used by src/api.ts), while util.ts gets its own row. Minor — worth a row or a note if the table is meant to be exhaustive.
• Node version phrasing. CLAUDE.md:4 says "Node 20 + TS (ESM)", whereas package.json engines is node: ">=18". Not a contradiction (20 satisfies ≥18), but "Node 20" reads as a hard requirement; consider aligning the wording with engines (or noting 20 as the CI/target runtime).
• Verified-accurate, for the record: metrics (+logs) correctly reflects that logs (src/index.ts:144) is implemented in metrics.ts (both route through the obs import at src/index.ts:19) rather than its own file; and the pre-commit gate npm run typecheck && npm test (CLAUDE.md:14) matches the typecheck and test scripts in package.json.

Software engineering

Scope is clean — one concern, docs-only, no code touched, no drive-by edits; naming (developing-insta-cli, CLAUDE.md) follows existing repo/superproject convention. No tests are applicable to a docs change.

Security

No security-relevant changes — no code, no user input, no secrets, no auth logic touched.

Performance

Not applicable — documentation only.

Verdict

approved (informational — zero Critical findings). The two Suggestion/Information accuracy nits on the command-group list are worth a quick follow-up but are non-blocking. Human approval still required via the normal GitHub approve flow.

[Fermionic-Lyu]

LGTM, Approved.