Restore documentation layer — match current substrate

ROADMAP: done items moved out of "Next" (codegen rewrite, SSR bridge,
edge manifest, X-Mizan-Invalidate, return-type branching, affects_params,
kernel extraction, two-stage codegen, mizan-ts). Real "Next" in:
framework-adapter wrapper layer (MizanContext + useMizan + DjangoError
on top of the kernel) for React/Vue/Svelte; A1–A4 from ISSUES.md.

CLAUDE: 4-package layout replaced with the actual 7-package layered
architecture (backend protocol adapters + frontend kernel + framework
adapters + SSR worker). "STALE codegen" section rewritten to describe
what's emitted vs. the wrapper layer that isn't yet.

docs/ now tracked (6 files). AFI_ARCHITECTURE rewritten — replaced
the speculative `mizan-ast`/`mizan-csr`/`mizan-rpc`/`mizan-schema`
package names with the real layout, dropped KDL-schema language for
the actual schema-export format. The other 5 docs/ files were already
current and are tracked as-is.

ARCHITECTURE-REWORK.md deleted — same expert review is re-tracked in
the fresher ISSUES.md, two parallel trackers was sediment.

README.md deleted — drift was beyond surgical fixes (`mizan_clients.py`
convention, `<DjangoContext>` provider, removed `@compose` and
`context='local'`, wrong codegen output filenames, 3-package structure
vs. 7). Rewrite waits for the wrapper-layer codegen to land so
user-facing examples reflect reality.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

docs/CACHE_KEYING.md

@@ -0,0 +1,73 @@
+# Cache Keying
+
+*Discovered 2026-04-06.*
+
+## The gap
+
+Mizan specified invalidation but never specified cache keying.
+Without correct cache keying, Edge caching is a **security
+vulnerability** — it serves User A's content to User B.
+
+## Why Vary doesn't work
+
+All major CDNs ignore `Vary` for personalized content. No
+standardized replacement exists.
+
+## Resolution: HMAC cache key (JSON-canonical form)
+
+```
+HMAC-SHA256(secret, JSON.stringify({
+    "c": context,
+    "p": sorted_params,
+    "r": rev,
+    "u": user_id    // omitted for public content
+}, sort_keys=True))
+```
+
+### Key derivation rules
+
+- **Public content** — URL path + query params (standard CDN).
+- **User-scoped content** — HMAC key derivation above.
+- **`@client(auth=...)`** determines whether content is user-scoped.
+- **`rev` parameter** on `@client` for deploy-time logic
+  invalidation. Bumped by the developer when function logic changes.
+
+## Identity layer
+
+MWT (Mizan Web Token) — see [MWT_SPEC.md](MWT_SPEC.md). JWT with
+Mizan claims on `X-Mizan-Token` header. Replaces the old
+`JWTUser` + permission key metadata approach.
+
+## Cache architecture
+
+*Decided 2026-04-06.*
+
+**Not a compiled binary ABI. Not a pluggable Python protocol.**
+
+Each backend adapter (Python, TypeScript, future PHP/C#/Go)
+implements the cache protocol in its own language, backed by Redis.
+**Conformance verified by a shared test suite.**
+
+### Required operations
+
+- `cache_get`
+- `cache_put`
+- `cache_purge`
+- `cache_purge_user`
+
+### Storage
+
+Redis only. Handles persistence, cross-worker sharing, crash
+recovery.
+
+## Deploy invalidation
+
+No full context flush. The `rev` parameter on `@client` is part of
+the HMAC key. When the developer bumps `rev`, old cache entries
+become **unreachable orphans**. No purge needed; no thundering herd.
+
+## Invariant
+
+All cache-related code must implement *identical* HMAC key
+derivation. Cross-language conformance tests enforce this. Any
+divergence is a security vulnerability.