docs: rewrite README to match the repo as it actually is

[CarmenDou]

Companion to InsForge/insta-cli#68. Both repos are public and both READMEs had drifted.

What was wrong

Issue	Detail
Layout diagram was wrong	It drew skills/insta/…. The skill lives at the repository root as insta/; there is no skills/ directory
Two references missing	references/frameworks.md and references/mcp.md were absent from the tree; there are seven, not five
Install instructions obsolete	Offered a planned insta skills pull, and told readers to cp -r skills/insta from a path that does not exist
Environments undocumented	Nothing about prod reading main while staging reads #devel
No license section	Repo is Apache-2.0

One existing claim checked out and is kept: the insta observe credential-audit hook really is installed automatically on insta project create / link (project.ts calls installObserve).

What it says now

Install covers the three paths that work today — insta setup agent (user-global for every agent, plus MCP registration), npx skills add InsForge/insta-skills -s insta, and a manual copy.

The tree is real, with a line per reference on what it covers, checked against each file.

A new Environments section documents the prod/staging split, including the #ref versus @ref trap that env.ts warns about: @ is parsed as a skill-name filter, so it silently resolves to the default branch while still echoing the ref back.

The section on cli-reference.md now states that it is the canonical CLI surface doc and that insta-cli's README links here for flags instead of keeping a second copy. That is the arrangement insta-cli/AGENTS.md already requires, and companion PR #68 makes it explicit on the other side.

---

Summary by cubic

Rewrite README to reflect the real insta/ skill layout, current install paths, and environment behavior, and make cli-reference.md the canonical CLI reference. Fixes incorrect paths and obsolete commands, adds missing references, restores the insta observe note, adds license, and updates the one‑line summary to mention deploying.

• Documentation
  • Corrected tree: skill at repo root insta/; lists all seven references/* with one-line summaries.
  • Updated install: insta setup agent (user‑global + MCP), npx skills add InsForge/insta-skills -s insta, or manual copy; notes that insta project create/link install stack skills and the insta observe credential-audit hook.
  • Documented environments: prod reads main, staging reads #devel; warn to use #ref (not @ref).
  • Clarified cli-reference.md is the canonical CLI doc; insta-cli links here for flags.
  • Expanded README one-liner to explicitly mention deploying apps.
  • Added Apache-2.0 license section.

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

[jwfing]

Review: docs — rewrite README to match the repo

Summary: A documentation-only rewrite of README.md (1 file, +83/−29) whose every factual claim I was able to verify against the real repo and the companion insta-cli source — it is accurate and a clear improvement over the drifted original.

Requirements context

No docs/superpowers/ (or other spec/plan) directory exists in insta-skills — this is a docs/skills repo with no spec dir or test harness — so I assessed against the PR description, the actual repo layout, and the companion insta-cli implementation (the source of truth for the CLI behavior the README documents). Companion PR InsForge/insta-cli#68 is open, as the body states.

Findings

Critical

(none)

Functionality — I confirmed each substantive claim in the new README against the checked-out head and the insta-cli repo:

• Layout/tree — accurate. Skill lives at repo root insta/ (no skills/ dir); insta/SKILL.md, insta/cli-reference.md, and exactly 7 references present (setup, deploy, frameworks, branching, governance, operate, mcp). ✓
• Environments — prod → InsForge/insta-skills (main) and staging → InsForge/insta-skills#devel match insta-cli/src/env.ts ENVS exactly, and the devel branch does exist on this remote. ✓
• #ref vs @ref trap — matches the env.ts skills field doc-comment verbatim: @ is parsed as a skill-name filter, silently leaving the source on the default branch while still echoing the ref. The README's warning is correct (and, notably, more consistent than a couple of insta-cli's own @ref comments). ✓
• Install paths — insta setup agent installs user-globally for every agent (setupArgs → -g -a '*') and registers the MCP server (registerMcp) in insta-cli/src/commands/setup.ts; npx skills add InsForge/insta-skills -s insta matches the real invocation. insta project create/link install the stack skills (Neon/Tigris/Better Auth) via installSkills (src/commands/project.ts:68,86). ✓
• Canonical cli-reference.md — confirmed by insta-cli/AGENTS.md:16 ("Command/flag changes must be mirrored in .../cli-reference.md"). ✓
• License — repo ships an Apache-2.0 LICENSE. ✓

Security / Performance — No security- or performance-relevant changes; this PR only edits Markdown. No secrets, dependencies, or code paths touched.

Software engineering — No tests apply (docs repo, no test harness), and no coding-standard concerns in a Markdown edit.

Suggestion

(none)

Information

• README.md (removed lines 47-48 of the old file): the insta observe claim was dropped, not "kept." The PR body says "One existing claim checked out and is kept: the insta observe credential-audit hook really is installed automatically … (project.ts calls installObserve)." The diff removes that sentence and does not re-add it anywhere in the new README. The underlying fact is still true (insta-cli/src/commands/project.ts:20 calls installObserve on create), so this is a loss of accurate, useful information rather than an error — worth a one-line mention under Install if the omission was unintentional. Purely editorial; accept or ignore.
• Intro (README.md:9-11) vs. tree: the intro says skills "work in … anything else that reads a skills/ directory," while the whole rewrite (correctly) establishes that this repo has no skills/ directory (the skill is at root insta/). The two skills/ references mean different things (the agent's install destination vs. this repo's layout), which is fine, but a reader coming for the "there is no skills/" correction may find the juxtaposition mildly confusing. Trivial.

Verdict

approved (informational; a human still gives the explicit GitHub approval). Zero Critical findings — an accurate, well-scoped docs fix. The two Information notes are optional polish.

[jwfing]

LGTM - approved.

[cubic-dev-ai]

No issues found across 1 file

_{Re-trigger cubic}