docs: How to add a new protocol — interactive onboarding track

[yasmewad]

What

Adds a seven-lesson interactive onboarding track — How to add a new protocol to smithy-java —
that teaches the client architecture through one concrete task. A protocol touches every layer
(the ClientProtocol contract, schema-directed serde, codecs, SPI discovery, the HTTP base
classes, compliance tests), so working through it end-to-end is a guided tour of the whole framework.

Each lesson is a self-contained HTML file with an interactive self-check (instant feedback),
backed by a Markdown companion for static reading, plus a landing page and a shared glossary.

📄 Documentation/onboarding only — no production code paths touched. Draft, not for merge.

Landing page

Walkthrough (animated)

🎬 Full 64s screen recording touring all seven lessons + the interactive quizzes:
docs/media/protocol-track-walkthrough.mp4
(MP4 links download from a repo path; GitHub only shows an inline player when the file is
drag-dropped into the PR. To embed the player, drag the file from docs/media/ into this box.)

Single-lesson recording (Lesson 1) — GIF

The track

#	Lesson	Teaches
1	The ClientProtocol Contract	One interface, six methods; a traced client.call(...).
2	The Smallest Real Protocol	RpcV2CborProtocol in ~45 lines — contract satisfied by inheritance.
3	Schema-Directed Serde	Why protocols and generated code are decoupled; Schema as the contract.
4	The Codec Layer	What a Codec is; reuse vs write; protocol-axis vs codec-axis.
5	Extensions & Discovery	SchemaExtensionProvider + ServiceLoader / META-INF/services.
6	Choosing Your Base Class	RPC (HttpClientProtocol) vs REST (HttpBindingClientProtocol).
7	Proving It — Compliance Tests	The authoritative correctness bar + the full add-a-protocol checklist.

Start at docs/lessons/index.html. Prefer reading? Every lesson has a .md twin beside it.

Files

docs/
├── lessons/
│   ├── index.html                  # landing page
│   ├── 0001..0007-*.html            # 7 interactive lessons
│   └── 0001..0007-*.md              # 7 non-interactive companions
├── reference/glossary.html          # canonical vocabulary
└── media/                           # overview gif, full-track mp4, posters, lesson-01 gif/mp4

Accuracy

All signatures and file paths are quoted verbatim from the codebase: ClientProtocol,
ClientProtocolFactory, ProtocolSettings, MessageExchange, HttpClientProtocol,
HttpBindingClientProtocol, RpcV2CborProtocol / AbstractRpcV2ClientProtocol,
RestJsonClientProtocol, the AwsJson* / AwsQuery* / RestXml class declarations,
ShapeSerializer, Codec, SchemaExtensionProvider / SchemaExtensionKey,
DetectProtocolPlugin, ProtocolTest, and the real META-INF/services registrations.

Notes for reviewers

• Lessons are static files; interactivity is vanilla JS — no dependencies, no network calls.
• Media totals ~26 MB (one 9 MB MP4 + two GIFs + posters). Say the word if you'd prefer the MP4
  hosted as a release asset / Git LFS instead of committed to the tree.