release(v4.0.0): Shade GA — V3.x consolidation + audit prep

V3.1 → V3.12 consolidated and tagged for the first GA release. Wire
format unchanged from 0.4.x — 4.0 peers interoperate with 0.4.x peers
byte-for-byte. The version bump is semantic: audit-cycle complete,
opt-in surface fully exposed, threat model refreshed for every new
surface.

Highlights:
- All 24 @shade/* packages bumped to 4.0.0 in lockstep.
- CHANGELOG 4.0.0 section is the canonical manifest of what landed.
- THREAT-MODEL extended (§10 fingerprint gates, §11 WebRTC P2P, §12
  Web-Worker boundary) + residual-risks table refreshed.
- OpenAPI now covers all 27 routes: prekey, transfer, KT, inbox,
  bridge, observer, /metrics, /healthz, /ready.
- MIGRATION 0.3.x → 4.0 documented + smoke-tested against
  shade migrate-storage on a real SQLite DB.
- docs/audit/REVIEW-BUNDLE.md + SCOPE.md ready for external reviewer.
- scripts/soak.ts harness for the GA-stable 2-week soak window.
- All V*.md plans archived under docs/archive/ with Status: Done.
- Voice/Video carved out into V5.0; 4.0 audit focuses on the frozen
  non-realtime stack.

Tests: TS 1000/1000 + Kotlin 11/11 cross-platform vectors green.
Docker: gt.zyon.no/stian/shade-prekey:4.0.0 builds and reports
  version 4.0.0 on /health.

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

packages/shade-recovery/README.md

@@ -0,0 +1,63 @@
+# `@shade/recovery`
+
+Social key recovery for Shade — V3.10.
+
+Shamir Secret Sharing over GF(2^8) splits the user's identity backup
+key into `n` shares; any threshold-many `k` together reconstruct the
+identity onto a new device. Distribution and reconstruction ride
+existing 1:1 Shade sessions — no centralized recovery agent.
+
+## Install
+
+```bash
+bun add @shade/recovery
+```
+
+## Quick wire-up
+
+```ts
+import {
+  setupRecovery,
+  attachGuardian,
+  requestRecovery,
+  MemoryRecoveryStore,
+} from '@shade/recovery';
+
+// Primary (Alice's existing device)
+await setupRecovery({
+  shade,
+  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
+  threshold: 3,
+  deliver: async (to, envelope) => myOutbox.send(to, envelope),
+});
+
+// Each guardian
+attachGuardian({
+  shade,
+  store: new MemoryRecoveryStore(),    // swap for persistent store in prod
+  approve: async (ctx) => askUser(ctx),
+  deliver: async (to, envelope) => myOutbox.send(to, envelope),
+});
+
+// New device (Alice on a fresh phone)
+await requestRecovery({
+  shade: tempShade,
+  originalAddress: 'alice',
+  setupId: '<from recovery card>',
+  threshold: 3,
+  guardians: ['bob', 'carol', 'dan', 'eve', 'faythe'],
+  deliver: async (to, envelope) => myOutbox.send(to, envelope),
+});
+```
+
+See [`docs/recovery.md`](../../docs/recovery.md) for the full
+threat model, persistence recommendations, and guardian-UX guidance.
+
+## Tests
+
+```bash
+bun test                    # all
+bun test tests/shamir       # Shamir primitives
+bun test tests/integration  # 3-of-5 end-to-end
+bun test tests/adversarial  # k-1 collusion + forged shares + OOB-gate
+```