docs(#32): runnable examples for the primitive→event walk-through

[joeldsouzax]

What

Adds a runnable examples/ set for the crate — the adoption front door, and integration tests in one. Closes the shippable portion of #32 (P2.2).

Five self-verifying examples, each returning Result from main and asserting its invariants (no unwrap/expect), ordered as a layered walk-through up the module stack:

Example	Teaches	required-features
encode_primitive	qb64 encode ↔ decode round-trip of a Matter; the derivation code makes a primitive self-describing	stream
keypair_sign_verify	generate Ed25519 → sign → verify; tampered message rejected	crypto, stream
parse_stream	build a count-code framed CESR stream → parse into typed signature groups	stream
incept_aid	incept a KERI AID; self-addressing prefix equals the event SAID, verified on deserialize	serder
multisig_threshold_icp	multi-key inception with simple (M-of-N) and weighted Tholder thresholds	serder

Each is wired into Cargo.toml with required-features (same pattern as concurrent_parse) and linked from a new README Examples section. Because nix flake check compiles every example, the set doubles as a live tripwire against public-API regressions.

Research findings — API warts filed for cleanup

The research pass predicted by #32 ("examples catch ergonomic problems") surfaced three issues, each verified from source and filed separately:

• Builders emit only Identifier::Basic prefixes — cannot construct a self-addressing KEL chain (write/read parity gap) #68 (bug/parity) — the event builders take Prefixer (Matter<VerKeyCode>) and always emit Identifier::Basic, but deserialize accepts Identifier::SelfAddressing. A real self-addressing icp → ixn → rot KEL is therefore not buildable through the public API (write/read parity violation).
• qb64 encoding of a Matter requires the stream feature (encode/decode live in different layers) #67 (devx) — encoding a Matter to qb64 requires the stream feature (matter_to_qb64 lives there, not core) and returns a ParseError on an encode path.
• No indexed-signature verification: sign_indexed yields Siger but verify only accepts Cigar #69 (devx) — sign_indexed yields a Siger, but verify only accepts a Cigar; no indexed-signature verification.

Deferred

The key_event_log (icp→ixn→rot chain) and delegated_inception examples are deferred until #68 lands — building them today would require a fabricated Basic prefix unrelated to the inception, which would teach an incorrect KEL.

Verification

nix flake check fully green: clippy, fmt, taplo, audit, deny, nextest, doctest, wasm32, no_std, fuzz-replay, typos. All five examples run to exit 0 with assertions passing.

Refs #32.

🤖 Generated with Claude Code

[codspeed-hq]

Merging this PR will not alter performance

✅ 21 untouched benchmarks

---

_{Comparing docs/32-runnable-examples (1993dea) with main (7b5dab6)}