Docs front door: newcomer quickstart, flow diagram, README overhaul

[aaylward]

What

Two related front-door improvements, both at the owner's request.

Quickstart rewritten for someone new to Smithy. The old "Write a model" step never showed a model — it jumped straight to the protocol overlay and assumed Smithy fluency.

• Step 2 now shows the complete todo model (the same shapes the CI-built examples/bazel-consumer module uses) with a construct-by-construct walkthrough: namespaces, service, operation with inline input :=/output :=, and what each trait does — @required/@length (server-side validation → 400 ValidationException, optionality → std::optional), @http/@httpLabel (routing), @error+@httpError (typed modeled errors). A wire-level table maps each call to its actual HTTP request/response.
• A mermaid flow diagram up front shows the three stages: model files → generated client/server cc_librarys (hermetic, in the build graph) → the handler and integration test you write. Rendered with mermaid-cli and layout-checked.
• Step 4 shows the handler implementation itself (typed Outcome, Error::Modeled + set_detail for the 404), not just transport wiring, plus client calls demonstrating the typed error. Snippets mirror todo_integration_test.cc, which CI builds.
• Two-sentence "what is Smithy" intro and a "Where to go next" section.

README overhauled. The quickstart now sits above the fold ("Start here →" under the project description). The phase-status table — internal phase numbers as row labels, 150-word status cells duplicating PLAN.md and the CHANGELOG, hand-edited on nearly every merge, and doubling as the only docs index — is replaced by:

• "What works today (v0.1.0)" — a capability summary in plain terms, with a "not yet" line (streaming, BCR/Maven publishing) pointing at docs/PLAN.md, where per-phase status lives.
• A documentation index — one compact table covering every doc, so no link depends on a status cell anymore.

Testing

• Docs-only change — no code, no generated output touched.
• The mermaid diagram renders cleanly (verified with mermaid-cli; GitHub renders mermaid blocks natively).
• All quickstart snippets verified against examples/bazel-consumer/ (model shapes, handler methods, detail<NoSuchTask>() usage), which the consumer CI job builds standalone on every commit.
• Every link in the new README docs index verified to resolve.

Checklist

• Tests added/updated for the change (n/a — docs only; snippets mirror the CI-built consumer example)
• bazel test //... and (cd codegen && gradle build spotlessCheck) pass locally (unaffected by this change)
• Formatting clean (markdown only)
• Architectural decisions recorded as an ADR (not applicable)

🤖 Generated with Claude Code

https://claude.ai/code/session_01SyQAo21Pv6GYhHrkbQj8xQ