docs: zero-to-hero tutorial + reference + AgentSkill (takeover of #63)

[vpavlin]

Summary

Takes over #63 (author unavailable) and refreshes every added doc to match the current spel CLI. The original commits from @jimmy-claw are preserved on this branch; a single takeover commit sits on top with Jimmy as Co-Authored-By.

Closes #63.

What changed vs #63

Between March (when Jimmy wrote the docs) and now, v0.2.0 shipped with a large CLI overhaul. The docs on #63 still referenced the old lez-cli world. This PR fixes that:

• Naming — lez-cli → spel, lez_cli → spel_cli, lez-client-gen → spel-client-gen, lez-framework[-core|-macros] → spel-framework[-core|-macros], LezOutput/LezError/LezResult/LezIdl → Spel* across every added file. Kept LEZ (the zone), lez-multisig (the external repo), and the macro names #[lez_program]/#[instruction]/#[account] as-is.
• spel.toml config — new [program] / [programs.<name>] discovery is now documented in cli.md, the tutorial's Step 8, the skill's cli-ref.md, quickstart.md, and SKILL.md. Also noted that init scaffolds a spel.toml by default (verified in spel-cli/src/init.rs).
• --dry-run[=text|json] — covers full-tx resolution output, JSON mode suppressing preamble, and the u128/nonce decimal-string precision note. Includes example text and JSON output blocks that match spel-cli/src/tx.rs.
• -- separator — every multi-flag example now uses -- when mixing global flags with instruction flags; added an explicit "Invocation Syntax" section plus a gotcha entry explaining why.
• --program <NAME|HEX|FILE> — documented the three-way resolution. --program-id is marked deprecated.
• PDA seed display — pda section and dry-run examples show the seeds: [program_id, "state", Account(x), Arg(y)] output format.
• fryorcraken's unresolved comment on cli.md:37 — resolved inline: the init section now explicitly says "scaffolding" and init refer to the same operation.
• Minor fix — cargo install --path spel → cargo install --path spel-cli # installs as the spel binary.

Files touched

docs/reference/README.md             |   6 +-
docs/reference/cli.md                | 247 +++++++++++++++++++++++++++-------
docs/reference/client-gen.md         |  14 +-
docs/reference/idl.md                |   6 +-
docs/reference/macros.md             |  42 +++---
docs/reference/types.md              |  34 ++---
docs/tutorial.md                     | 164 +++++++++++++++-----
skills/spel/SKILL.md                 |  16 +--
skills/spel/references/cli-ref.md    | 109 +++++++++++----
skills/spel/references/gotchas.md    |  33 ++++-
skills/spel/references/quickstart.md |  58 ++++----

Test plan

• Reviewer sanity-checks docs/reference/cli.md against spel --help on main
• Reviewer confirms the dry-run example output blocks match spel-cli/src/tx.rs render functions (print_dry_run_text / print_dry_run_json)
• Reviewer walks through tutorial Steps 7-8 with the scaffolded spel.toml against a real program
• grep -rnE "lez-cli|lez_cli|lez-client-gen|lez-framework|LezOutput|LezError|LezResult|LezIdl" docs/ skills/ returns no matches

🤖 Generated with Claude Code