10 — README, agent guide & the SDK handoff

[rahlk]

Part of #9. Phase 1 — level 1 closes here.

Learning goals

Documentation as contract: a README that only claims what runs, and the difference between the
user-facing README and the contributor-facing agent guide.

Task

• README modeled on codeanalyzer-python's main-branch layout: shared CLDK logo, one-line
  what-it-is, prerequisites (read minimum Rust from Cargo.toml's rust-version, don't guess),
  install (pip/brew/source), real --help output, worked examples, analysis levels
  (level-2 marked skipped-by-design, level-3 as it lands), output schema pointer, SDK
  integration note. Keep Architecture & Tooling intact as its own heading.
• CLAUDE.md mirroring codeanalyzer-typescript/CLAUDE.md (the canonical template): what the
  project is, architecture-follow-the-pipeline, directory map, commands, schema+packaging
  contract, the I implement — you assist section (non-negotiable here: this repo is my Rust
  classroom), Rules, teaching-loop section, release-announcement auxiliary task.
  ln -sf CLAUDE.md AGENTS.md + the .gitignore un-ignore lines (!CLAUDE.md, !AGENTS.md) —
  verify with git check-ignore AGENTS.md.
• SDK handoff notes in the epic: published package name + version to pin, a sample
  analysis.json, --help text — the cldk-sdk-frontend skill's exact inputs. (Analyzer is a
  compiled binary → the Python SDK binds it via SUBPROCESS, like Java/TS, not in-process.)

Gate

• README claims nothing stubbed as working; --help block matches the real binary.
• git ls-files shows CLAUDE.md + AGENTS.md; git check-ignore AGENTS.md prints nothing.