docs: reorganize docs/, delete bmad archive, add mkdocs site

[lesnik512]

Summary

• Delete docs/archive/ (~5,000 lines of bmad-era PRD / architecture / epics / product briefs / per-story specs). The one load-bearing rationale (decoder single-parse-pass at Seam 3) was inlined into docs/dev/engineering.md first so nothing is lost.
• Move agent/contributor workflow artifacts out of docs/. docs/superpowers/ → tool-neutral planning/ directory at repo root (planning/specs/, planning/plans/, planning/deferred-work.md). All renames via git mv so history is preserved.
• Move engineering reference into the published tree. docs/engineering.md → docs/dev/engineering.md; root CONTRIBUTING.md → docs/dev/contributing.md with a thin root CONTRIBUTING.md stub preserving GitHub's "open a PR" UI integration.
• Stand up a minimal mkdocs site (mkdocs.yml, .readthedocs.yaml, docs/requirements.txt, docs/index.md) published via Read the Docs, modeled on modern-di's setup. Quick-Start + Development (Engineering Notes, Contributing) — user-guide content grows in follow-up PRs.
• README.md refactor — slim, aligned with the modern-python org pattern, links to the new docs site.
• No source code touched. No CI grep invariants change. The src/ layout stays.

Test Plan

• just lint-ci exits 0 (no source changes — should be unaffected)
• just test exits 0, 295 passed, 100% coverage maintained
• uv run --with mkdocs --with mkdocs-material mkdocs build --strict exits 0 with zero broken-link warnings
• git log --follow planning/specs/2026-06-01-auth-coercion-design.md shows pre-rename history (verifies git mv preserved history across the move)
• grep -rn "docs/archive\|docs/superpowers/\|docs/engineering\.md\|docs/deferred-work\.md" docs/ CLAUDE.md README.md returns zero hits in the published tree
• Manual review: docs/dev/engineering.md section 3 Seam 3 contains the inlined decoder rationale (maxsize=1024 cache on _get_adapter factory, msgspec.json.decode alternative) — confirms the archive deletion lost no load-bearing rationale

Post-merge follow-ups (out of scope for this PR)

1. Create the Read the Docs project at https://readthedocs.org (modern-python/httpware). GitHub integration auto-configures the webhook.
2. Verify the first RTD build on main after merge.
3. Claim the httpware.readthedocs.io subdomain. If unavailable, update site_url in mkdocs.yml and the README docs link.
4. (Optional) Add an RTD build-status badge to the README.

Notes on accepted deviations

• Historical planning files inside planning/ (specifically 2026-05-31-bmad-to-superpowers-transition-*.md and 2026-05-31-release-0.1.0-prep-*.md) intentionally retain references to docs/archive/ and docs/superpowers/. These are past-tense narrative describing what those earlier transitions did; rewriting them would falsify the historical record. They are not user-visible (not part of the mkdocs site) and not load-bearing.

Spec: `planning/specs/2026-06-02-docs-reorg-and-mkdocs-design.md`
Plan: `planning/plans/2026-06-02-docs-reorg-and-mkdocs-plan.md`