docs: M-Hard 9-11 — README, examples, CI, benchmarks, migration guide

M-Hard 9: Documentation + examples
- README.md, SECURITY.md, THREAT-MODEL.md
- 5 runnable examples: basic conversation, prekey server,
  WebSocket tunnel, identity verification, Dokploy deployment

M-Hard 10: CI + publishing + benchmarks
- GitHub Actions: test workflow with PostgreSQL service container
- GitHub Actions: publish workflow for npm releases on git tags
- Benchmark suite (bench/run.ts) with markdown output
- LICENSE (MIT), CHANGELOG.md, CONTRIBUTING.md

M-Hard 11: Migration guide
- MIGRATION.md with three-phase rollout strategy
- Concrete examples for replacing static AES tunnels
- Concrete examples for per-device push notification migration
- Sections for Orchestrator and Nova migrations

Benchmark highlights:
- AES-256-GCM: ~100K ops/sec
- Encrypt+decrypt roundtrip: ~17K ops/sec
- X3DH handshake: ~165 ops/sec (hardware acceleration limited)
- Compute fingerprint: ~76K ops/sec

All 11 M-Hard milestones complete. 193 tests passing, 0 failures.
Shade is production-ready.

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

examples/03-websocket-tunnel/main.ts

@@ -0,0 +1,71 @@
+import { ShadeSessionManager } from '../../packages/shade-core/src/index.js';
+import { SubtleCryptoProvider, MemoryStorage } from '../../packages/shade-crypto-web/src/index.js';
+import { ShadeWebSocket } from '../../packages/shade-transport/src/index.js';
+
+const crypto = new SubtleCryptoProvider();
+
+async function main() {
+  console.log('=== Shade WebSocket Tunnel ===\n');
+
+  // Set up Alice and Bob
+  const alice = new ShadeSessionManager(crypto, new MemoryStorage());
+  const bob = new ShadeSessionManager(crypto, new MemoryStorage());
+  await alice.initialize();
+  await bob.initialize();
+
+  // Establish session (skipping prekey server for brevity)
+  const otpks = await bob.generateOneTimePreKeys(5);
+  const bundle = await bob.createPreKeyBundle();
+  bundle.oneTimePreKey = { keyId: otpks[0].keyId, publicKey: otpks[0].keyPair.publicKey };
+  await alice.initSessionFromBundle('bob', bundle);
+
+  // Pair of WebSockets connected to each other
+  // Use Bun's built-in WebSocket server + client for the demo
+  const port = 19851;
+  const messages: string[] = [];
+
+  const server = Bun.serve({
+    port,
+    fetch(req, srv) {
+      if (srv.upgrade(req)) return;
+      return new Response('upgrade failed', { status: 500 });
+    },
+    websocket: {
+      async message(ws, message) {
+        // Server side decrypts (acts as Bob)
+        const bytes = message instanceof Uint8Array ? message : new Uint8Array(Buffer.from(message as string));
+        // Need to manually use ShadeWebSocket or do raw decoding
+        console.log(`[Bob received ${bytes.length} encrypted bytes]`);
+        // Forward to Bob's session
+        const { decodeEnvelope } = await import('../../packages/shade-proto/src/index.js');
+        const envelope = decodeEnvelope(bytes);
+        const plain = await bob.decrypt('alice', envelope);
+        messages.push(plain);
+        console.log(`[Bob decrypted]: "${plain}"`);
+      },
+    },
+  });
+
+  // Alice opens a WebSocket and uses ShadeWebSocket wrapper
+  const aliceWs = new WebSocket(`ws://localhost:${port}/`);
+  await new Promise((r) => aliceWs.addEventListener('open', r));
+
+  const aliceShade = new ShadeWebSocket(aliceWs, alice, 'bob');
+
+  console.log('Alice → Bob: "Hello over WebSocket"');
+  await aliceShade.send('Hello over WebSocket');
+
+  console.log('Alice → Bob: "Second message"');
+  await aliceShade.send('Second message');
+
+  // Wait for messages to arrive
+  await new Promise((r) => setTimeout(r, 200));
+
+  console.log('\nMessages Bob received:', messages);
+  console.log('\n=== Done ===');
+
+  aliceShade.close();
+  server.stop();
+}
+
+main().catch(console.error);