Epic: docs that are awesome (animated demo, JSON schemas, migration guides, error catalogue, quality gates) #27

Why

The docs site (MkDocs Material, 14 pages, strict build, screenshots generated from real output) is already solid. This epic is about the things that make documentation great rather than complete: a moving picture on the front page, guides for people arriving from other tools, machine-checkable schemas for the config files, an error catalogue that agents and the FAQ can point at, and CI gates so quality does not drift. Several items are prerequisites for the course and the VS Code extension.

What is in scope

• P1 animated demo on the README and docs home; JSON schemas for apic.yaml, http-client.env.json and the session file
• P2 migration guides (Postman, Bruno, Hurl, httpyac, curl/Taskfile); error catalogue; link, spell and style checks in CI; comparison page refresh with a "not planned" section
• P3 versioned docs with mike; architecture and contributor page

Where

• docs/, mkdocs.yml, .github/workflows/docs.yml, docs/assets/demo.tape, scripts/shot, Taskfile.yml