@ankurhalder/codebase-snapshot 2.1.1 → 3.0.0

package/README.md

@@ -54,6 +54,11 @@ npx @ankurhalder/codebase-snapshot init --preset react-vite --max-part-bytes 120
 - **TypeScript AST extraction** — directives, imports, exports (including `export *` and anonymous
   defaults), functions, classes, interfaces, types, enums, components, hooks, and route handlers.
 - **Structured summaries** — JSON key shapes and Markdown headings, computed from redacted text.
+- **Built for AI agents** — `codebase-snapshot describe --format json` returns a machine-readable
+  contract (workflow, every option and default, exit codes, presets, safety rules), and
+  `codebase-snapshot skill --install` writes the bundled agent skill into `AGENTS.md`,
+  `.claude/skills/` and `.cursor/rules/` so a zero-context agent discovers the tool
+  automatically. See [docs/agent.md](docs/agent.md).
 - **Zero-config presets** — auto-detects Next.js, Vite, Node/Express/Nest, and plain TypeScript.
 - **Real integrity validation** — verifies source hashes, every emitted `parts/*.md` against its recorded
   `byteSize`/`sha256`, monolith artifacts, and the recorded configuration.
@@ -94,11 +99,43 @@ and troubleshooting.
 
 ---
 
+## 🤖 For AI agents
+
+An agent with **no prior knowledge** of this tool can drive it end to end. Two commands
+exist for exactly that:
+
+```bash
+# Machine-readable contract: workflow, every option + default, exit codes,
+# presets, safety rules and troubleshooting — as JSON on stdout.
+npx @ankurhalder/codebase-snapshot@latest describe --format json
+
+# Write the bundled agent skill where agents look for it:
+# AGENTS.md, .claude/skills/codebase-snapshot/SKILL.md, .cursor/rules/
+npx @ankurhalder/codebase-snapshot@latest skill --install
+```
+
+The typical agent flow, once the contract is read:
+
+```bash
+npx @ankurhalder/codebase-snapshot@latest init --yes   # detect the project, write config
+npx @ankurhalder/codebase-snapshot@latest generate     # write ./snapshot/
+npx @ankurhalder/codebase-snapshot@latest validate     # exit 0 = matches disk
+```
+
+The bare form works too — `npx @ankurhalder/codebase-snapshot generate` — because the
+package ships exactly one executable, which is what lets npm resolve it. Pin `@latest`
+(or `@3`) when you need the same build on every machine.
+
+Details, including the contract schema and the skill's install targets, are in
+[docs/agent.md](docs/agent.md).
+
+---
+
 ## 🛠️ CLI
 
 ```bash
 codebase-snapshot [command] [options]
-snap [command] [options]
+codebase-snapshot [command] [options]
 ```
 
 Every option accepts both `--opt value` and `--opt=value`. Human-readable progress goes to **stderr**;