docs: add runnable examples/ directory

[beogip]

Priority: P1 (recommended before announcing)
Source: pre-announcement LinkedIn review note (marketer, 2026-06-03), approved 2026-06-07.

Why

The differentiator is "this isn't theory". A repo with a clonable, runnable examples/ lowers the barrier to entry and gives direct material for the post (the example can be shown in the announcement). The README already has a minimal example, but a runnable one reinforces the proof.

Tasks

1. Create examples/ with at least one complete, runnable tool (ideally one per level L1, L2, L3, or a single one that shows all three outputs).
2. Include the exact command to run it and the expected JSON output.
3. A mini README in the folder explaining how to run the examples.

[claude]

Claude finished @beogip's task in 2m 53s —— View job • claude/issue-26-20260607-1604 • [Create PR ➔](https://github.com/beogip/code-first-agents-tool/compare/main...claude/issue-26-20260607-1604?quick_pull=1&title=Issue%20%2326%3A%20Changes%20from%20Claude&body=This%20PR%20addresses%20issue%20%2326%0A%0AGenerated%20with%20%5BClaude%20Code%5D(https%3A%2F%2Fclaude.ai%2Fcode)

---

Task: Add runnable examples/ directory (issue #26) — ✅ Done

• Gather context (read repo, src, README, fixtures)
• Plan implementation
• Create examples/ with a runnable tool covering L1/L2/L3
• Add run commands + expected JSON output
• Add mini README in examples/
• Run tests / lint / type-check
• Review & deliver PR

What was built

examples/changeset.ts — one complete, deterministic tool that analyzes the shape of a changeset and demonstrates all three output levels from the spec, one subcommand each:

Subcommand	Level	Output
stats	L1 — data	raw signals for the LLM to interpret
size	L2 — classification	a discrete size class the skill can branch on
review-plan	L3 — instructions	a verbatim review procedure the LLM executes

No LLM calls inside the tool; same flags → same JSON. It imports from ../src/index.ts, so it runs against source with no build step:

bun run examples/changeset.ts size --files 12 --additions 340 --deletions 50
# → {"ok":true,"message":"changeset classified as large","classification":"large","total_lines":390}

examples/README.md documents the exact command + expected JSON for each level, plus help/schema introspection and the always-exit-0 error envelopes. The main README.md now links to it.

Verification

• bun test → 113 pass, 0 fail
• bunx tsc --noEmit → clean
• bunx biome check . → clean (only a pre-existing biome schema-version info note, unrelated)
• Every command in examples/README.md was run; documented output matches actual output.

PR: #32 — docs: add runnable examples/ directory
· claude/issue-26-20260607-1604

[github-actions]

🎉 This issue has been resolved in version 0.1.5 🎉

The release is available on:

• npm package (@latest dist-tag)
• GitHub release

Your semantic-release bot 📦🚀