docs(agents): realtime layer section + guide reference

AGENTS.md

@@ -370,6 +370,22 @@ See `docs/guides/events-and-jobs.md` and `docs/decisions/adr-015-events-and-jobs
 
 ---
 
+### Realtime layer (ADR-016)
+
+Three rules:
+
+- **R0:** Realtime is for state delivery, not for replacing tRPC. Persistent operations with request/response semantics belong on tRPC procedures. Use realtime when the server needs to push without a request, or the data is too high-frequency for HTTP.
+- **R1:** Channel descriptors are exported; handlers are private. A feature's `realtime/<name>.channel.ts` is re-exported from the package root barrel; `realtime/handlers/*.handler.ts` is wired only in the feature's own bind-* files and never re-exported (ESLint-enforced via `no-realtime-handler-reexport`).
+- **R2:** `socket.io` lives in one package only. Feature packages MUST NOT `import "socket.io"` or `import "socket.io-client"`. Allowlist: `packages/core-realtime/src/socket-io-*.ts` + `apps/*/server.ts`. ESLint rule `no-direct-socket-io` enforces this.
+
+`@repo/core-realtime` provides `IRealtimeBroadcaster` (server → client), `IRealtimeHandlerRegistry` (client → server), and the `SocketIORealtimeServer` adapter. `apps/web-next/server.ts` replaces `next start`/`next dev` with a custom Node http server hosting both Next.js and Socket.IO on port 3000.
+
+Use the generators: `pnpm turbo gen realtime channel`, `pnpm turbo gen realtime handler`. They insert at three fixed `// <gen:realtime-*>` anchor comments per feature.
+
+See `docs/guides/realtime.md` and `docs/decisions/adr-016-realtime-layer.md`.
+
+---
+
 ## Instrumentation conventions
 
 **Symbols (in `core-shared/instrumentation/symbols.ts`):**
@@ -465,6 +481,7 @@ Feature packages MUST NOT `import "@sentry/*"`. Allowlist:
 - **Scaffolding a Feature** — `docs/guides/scaffolding-a-feature.md` — `turbo gen feature` reference (fast path)
 - **Adding a Feature Guide** — `docs/guides/adding-a-feature.md` — step-by-step new feature walkthrough (manual path)
 - **Events and Jobs Guide** — `docs/guides/events-and-jobs.md` — publish, consume, schedule background work
+- **Realtime Guide** — `docs/guides/realtime.md` — declare channels, broadcast, receive
 - **Testing Strategy** — `docs/guides/testing-strategy.md` — test placement, Vitest per-package, Playwright e2e
 - **TDD Workflow** — `docs/guides/tdd-workflow.md` — red-green-refactor cycle, mocking decision tree, coverage targets