docs(schema): update docs for #54 — proto registry + buf CI gate

- packages/shared-types/README.md: new — documents HTTP vs event surfaces,
  proto file layout, schema evolution rules, and how to run buf locally
- ml/serving/README.md: note pydantic payload validation in consumer section
- CLAUDE.md: replace "schema registry enforced when #54 lands" with
  the actual state; remove #54 from active-work list

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/shared-types/README.md

@@ -0,0 +1,63 @@
+# @oo/shared-types
+
+Canonical contracts for all inter-module communication. Two surfaces:
+
+| Surface | Format | Location |
+|---------|--------|----------|
+| HTTP (sync) | OpenAPI / TypeScript interfaces | `src/http/` |
+| Events (async) | Protocol Buffers + TS interfaces | `src/events/`, `events/` |
+
+## HTTP types
+
+Hand-written TypeScript interfaces generated from OpenAPI specs. Imported by
+`services/api`, `apps/web`, and `ml/serving` (Python hand-mirrors).
+
+| File | Types |
+|------|-------|
+| `src/http/tip.ts` | `TipCandidate`, `RecommendResponse`, `TipFeedback` |
+| `src/http/auth.ts` | `SessionUser` |
+| `src/http/integrations.ts` | `IntegrationsResponse`, `Integration` |
+| `src/http/user.ts` | `UserProfile` |
+| `src/http/signal.ts` | `Signal`, `SignalSource` |
+
+## Event types
+
+Protobuf schemas live in `events/oo/events/v1/`. TypeScript interfaces in
+`src/events/index.ts` mirror the proto envelope and payload types.
+
+| Proto file | Messages |
+|------------|----------|
+| `envelope.proto` | `Envelope` (wraps every event) |
+| `signals.proto` | `TaskSyncedPayload`, `TipServedPayload`, `TipFeedbackPayload`, `TipRewardFailedPayload` |
+| `integration.proto` | `IntegrationTokenExpiredPayload` |
+
+**Schema evolution rules (ADR-0005):**
+- Additive changes only within a version (new fields, new message types).
+- Removed fields must be marked `reserved` — never reuse a field number.
+- Breaking changes require a new package version (`oo.events.v2`) and a `schemaVersion` bump in the envelope.
+
+## Schema registry / CI gate
+
+`buf` enforces lint and breaking-change detection on every PR that touches `events/`:
+
+```bash
+# Lint
+buf lint events/
+
+# Breaking-change check against main
+buf breaking events/ --against '.git#branch=main,subdir=packages/shared-types/events'
+```
+
+Local shortcut: `./scripts/buf-check.sh`
+
+CI: `.gitea/workflows/buf-check.yaml` (requires a Gitea Actions runner).
+
+Install buf: `curl -sSfL https://github.com/bufbuild/buf/releases/latest/download/buf-Linux-x86_64 -o /usr/local/bin/buf && chmod +x /usr/local/bin/buf`
+
+## Contract
+
+`/health` — not applicable (library package, no process).
+
+**Extraction criteria** — always a shared library. Extract to a separate registry
+service only when schema governance requires independent versioning and deployment
+(e.g. external consumers, SLA divergence from the monorepo).