diff --git a/.claude/skills/developing-insta-cli/SKILL.md b/.claude/skills/developing-insta-cli/SKILL.md
index df14b85..89bf590 100644
--- a/.claude/skills/developing-insta-cli/SKILL.md
+++ b/.claude/skills/developing-insta-cli/SKILL.md
@@ -19,6 +19,23 @@ npx tsx src/index.ts --help   # run the CLI from source
 - `project create|link` has side effects in cwd (`.insta/`, observe hook, agent skills) — exercise them only in scratch dirs.
 - End-to-end without the cloud: run the insta-oss daemon and point the CLI at it with `INSTA_API_URL` (env wins over persisted config since v0.0.7).
 
+## Architecture (`src/`)
+
+| Path | Responsibility |
+|------|----------------|
+| `index.ts` | commander program — registers every command |
+| `api.ts` | typed platform-API client (auth headers, token refresh, error mapping) |
+| `config.ts` | global `~/.insta/config.json` (apiUrl + tokens + user) · project `./.insta/project.json` (projectId / orgId / current branch) |
+| `commands/` | one file per command group: `auth` `org` `project` `services` `branch` `secrets` `deploy` `compute` `upgrade` `metrics` (+`logs`) `billing` `govern` (policy/approvals) `manifest` `observe` |
+| `observe/` | local `insta observe` hook — `scanner.ts` (AWS/GitHub/Stripe/LLM/DB cred detection), `hook.ts`, `install.ts`, `report.ts` (→ platform event ingest) |
+| `flyctl-build.ts` | source-directory deploy build glue (Fly build context) |
+| `ensure-skills.ts` | installs/refreshes the agent skills into the user's project |
+| `util.ts` | shared helpers |
+
+- **Command/flag changes must be mirrored in `skills/insta/cli-reference.md`** (the superproject
+  `skills/` submodule) — that reference doc is how agents learn the CLI surface, so a new or
+  renamed command/flag is only half-done until it's updated there, in the same change set.
+
 ## Getting a PR merged (main is protected — this exact flow, no other works)
 
 1. Branch from `origin/main`: `feat/*` or `fix/*`. PRs target `main`. **Squash merge.**
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..6848c15
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,23 @@
+# insta-cli — agent notes
+
+The `insta` CLI — a **thin client** of the [platform](../platform) control-plane API for
+project / branch / secrets / deploy / governance, built for developers and agents. Node 20 + TS
+(ESM) + commander; every command wraps a platform API call. A submodule of the **insta-cloud**
+superproject.
+
+## Non-negotiables
+
+1. `main` is branch-protected — **PR only** (squash), needs 1 approving review you can't self-cast.
+   Develop on a `feat/*` or `fix/*` branch off `main`.
+2. When working inside the insta-cloud superproject: commit + push **here first**, then bump the
+   `cli` pointer in the superrepo — never the reverse. (Git mechanics: superproject
+   `developing-on-insta-cloud` skill.)
+3. Pre-commit gate: `npm run typecheck && npm test`.
+4. Command/flag changes must be mirrored in `skills/insta/cli-reference.md` (superproject `skills/`
+   submodule) — that's the agent-facing surface doc.
+
+## Developing here
+
+The full dev guide — dev loop, `src/` architecture, the PR-merge/approval flow, the release
+process (binaries + npm OIDC), and gotchas — is in `.claude/skills/developing-insta-cli/SKILL.md`.
+Claude Code loads it as a skill on demand; other agents (Codex, etc.) can read that file directly.
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..43c994c
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1 @@
+@AGENTS.md