@soulcraft/sdk 1.0.0

package/docs/IMPLEMENTATION-PLAN.md

@@ -0,0 +1,708 @@
+# @soulcraft/sdk — Detailed Implementation Plan
+
+**Status:** Ready to implement
+**Decisions:** See `ADR-001-sdk-design.md` for all architecture decisions and rationale.
+**Research basis:** Full cross-project exploration of Workshop, Venue, Academy, brainy-client,
+and @soulcraft/auth conducted 2026-02-27.
+
+---
+
+## Source Material — Where Code Comes From
+
+Every module in this SDK migrates or absorbs code from an existing location.
+A new session MUST read the source file(s) before implementing each module.
+
+| SDK Module | Migrates from | Key source files |
+|------------|--------------|-----------------|
+| `transports/local` | `@soulcraft/brainy-client` | `/media/dpsifr/storage/home/Projects/brainy-client/src/transports/local.ts` |
+| `transports/http` | `@soulcraft/brainy-client` | `/media/dpsifr/storage/home/Projects/brainy-client/src/transports/http.ts` |
+| `transports/ws` | `@soulcraft/brainy-client` | `/media/dpsifr/storage/home/Projects/brainy-client/src/transports/ws.ts` |
+| `transports/sse` | Workshop events | `/media/dpsifr/storage/home/Projects/workshop/src/lib/services/vfsEventService.ts` |
+| `modules/brainy` | `@soulcraft/brainy-client` | `/media/dpsifr/storage/home/Projects/brainy-client/src/index.ts` + Brainy types |
+| `modules/vfs` | Brainy VFS sub-API | `node_modules/@soulcraft/brainy/dist/brainy.d.ts` (brain.vfs.*) |
+| `modules/versions` | Brainy versions sub-API | same (brain.versions.*) |
+| `server/instance-pool` | Workshop singleton + Venue cache | `/media/dpsifr/storage/home/Projects/workshop/brainy/brainy-singleton.ts` + `/home/dpsifr/Projects/venue/apps/web/server.ts` |
+| `modules/auth` | `@soulcraft/auth` + Workshop auth | `/media/dpsifr/storage/home/Projects/auth/packages/auth/src/` + `/media/dpsifr/storage/home/Projects/workshop/auth/better-auth.ts` |
+| `modules/license` | Workshop usage + billing | `/media/dpsifr/storage/home/Projects/workshop/brainy/usage-tracking.ts` + `brainy/config-service.ts` |
+| `modules/ai` | Workshop chat | `/media/dpsifr/storage/home/Projects/workshop/chat/` (models.ts, delegator.ts, executor.ts, planner.ts, tools.ts, ui-actions.ts) + `routes/briggy.ts` |
+| `modules/events` | Workshop data-change-emitter | `/media/dpsifr/storage/home/Projects/workshop/events/data-change-emitter.ts` |
+| `modules/skills` | Workshop skill service | `/media/dpsifr/storage/home/Projects/workshop/brainy/skill-service.ts` + `brainy/bundled-skills.ts` |
+| `modules/kits` | Workshop kit loader | `/media/dpsifr/storage/home/Projects/workshop/src/lib/templates/loader.ts` |
+| `modules/formats` | @soulcraft/views + Workshop types | `/media/dpsifr/storage/home/Projects/workshop/packages/views/src/shared/types.ts` + `src/lib/types/richDocument.ts` |
+| `modules/billing` | Workshop billing | `/media/dpsifr/storage/home/Projects/workshop/brainy/usage-tracking.ts` + `brainy/billing-provider.ts` + `brainy/config-service.ts` + `brainy/config-defaults.ts` |
+| `modules/notifications` | Venue notification service | `/home/dpsifr/Projects/venue/apps/web/src/lib/server/notifications/` |
+
+---
+
+## Phase 1 — Foundation ✅ COMPLETE
+
+All items done. Repo created, ADR written, scaffold committed.
+
+Remaining scaffolding items (minor, do at start of Phase 2):
+- [ ] `vitest.config.ts` — test runner config
+- [ ] `.env.example` — document any env vars the SDK needs
+- [ ] Update `src/modules/*/types.ts` placeholder comments as modules are implemented
+
+---
+
+## Phase 2 — Core Data Layer
+
+**Goal:** The SDK can connect to Brainy via all four transports and expose the full
+`sdk.brainy.*`, `sdk.vfs.*`, `sdk.versions.*` API surface. Server mode can create and
+pool Brainy instances with all three strategies.
+
+### 2a. Transport Layer (`src/transports/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/brainy-client/src/transports/`
+
+Four files to create:
+
+#### `src/transports/transport.ts` — Shared interface
+```typescript
+interface Transport {
+  call(method: string, args: unknown[]): Promise<unknown>
+  onEvent(handler: (event: BrainyChangeEvent) => void): void
+  offEvent(handler: (event: BrainyChangeEvent) => void): void
+  isAlive(): boolean
+  close(): Promise<void>
+}
+```
+
+#### `src/transports/local.ts` — In-process, zero overhead
+- Wraps a native Brainy instance
+- Resolves dot-separated method names (e.g. `'vfs.readdir'`) by property traversal
+- `call()` directly invokes `target[method].apply(target, args)`
+- `onEvent`/`offEvent` are no-ops (in-process changes are synchronous)
+- `isAlive()` always true, `close()` is a no-op
+- **Migrate directly from brainy-client local.ts — minimal changes**
+
+#### `src/transports/http.ts` — JSON RPC over HTTP
+- POSTs to `{baseUrl}/api/brainy/rpc`
+- Request: `{ method: string, args: unknown[] }` — plain JSON
+- Response: `{ result: unknown }` or `{ error: { code: string, message: string } }`
+- Auth: `Authorization: Bearer <token>` or `credentials: 'include'` (session cookies)
+- 30s timeout via AbortController
+- Error mapping: 401 → `SDKAuthError`, 403 → `SDKForbiddenError`, timeout → `SDKTimeoutError`
+- No push events — stateless
+- **Migrate directly from brainy-client http.ts — rename error classes**
+
+#### `src/transports/ws.ts` — MessagePack binary RPC + change push
+- Binary MessagePack via `@msgpack/msgpack`
+- Client → Server: `{ id: string, method: string, args: unknown[] }` (encoded)
+- Server → Client:
+  - Ready: `{ type: 'ready', scope: string }`
+  - RPC response: `{ id: string, result?: unknown, error?: { code, message } }`
+  - Change push: `{ type: 'change', event: 'add'|'update'|'delete'|'relate'|'unrelate', entity?, relation? }`
+- Auth: `Authorization: Bearer <token>` on upgrade request
+- Scope: `?scope=<tenantSlug>` query param
+- Reconnection: exponential backoff 1s → 30s, max 10 attempts; never retry on 4001/4003
+- Connection states: `'disconnected' | 'connecting' | 'connected' | 'closed'`
+- `connect()` resolves on `ready` message (15s timeout)
+- **Migrate directly from brainy-client ws.ts — minimal changes**
+
+#### `src/transports/sse.ts` — Server-push event stream (NEW — not in brainy-client)
+- Connects to `{baseUrl}/api/workspace/events` via `EventSource`
+- Listens for VFS and entity change events
+- Reconnects automatically (EventSource handles this natively)
+- Emits typed `DataChangeEvent` objects to registered handlers
+- Does NOT support RPC (send-only from server) — complement to http transport
+- Based on: Workshop's `src/lib/services/vfsEventService.ts`
+
+### 2b. Brainy API Proxy (`src/modules/brainy/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/brainy-client/src/index.ts` + Brainy types
+
+The core of the SDK. A JavaScript `Proxy` that intercepts any property access and routes
+it to the active transport via `transport.call(method, args)`.
+
+#### `src/modules/brainy/proxy.ts`
+```typescript
+// Creates a recursive Proxy that maps any property chain to transport.call()
+// client.find(...) → transport.call('find', [...])
+// client.versions.save(...) → transport.call('versions.save', [...])
+// Special root properties handled locally:
+//   close(), isAlive(), onDataChange(), offDataChange(), _transport, then
+```
+
+#### `src/modules/brainy/types.ts` — Full Brainy type surface
+All types imported or re-exported from `@soulcraft/brainy`:
+- `Entity<T>`, `Relation<T>`, `Result<T>`, `Vector`
+- `NounType`, `VerbType` (enums)
+- `AddParams`, `UpdateParams`, `FindParams`, `SimilarParams`, `RelateParams`
+- `GetOptions`, `GetRelationsParams`, `FindDuplicatesOptions`
+- `BatchResult`, `IndexStats`, `DiagnosticsResult`, `MigrationResult`
+- `BrainyChangeEvent`, `BrainyChangeEntity`, `BrainyChangeRelation` (from brainy-client)
+- `SoulcraftBrainy` — the full SDK interface (extends `Pick<Brainy, all methods>` + change handlers)
+
+Full method list (all must be proxied):
+`add`, `get`, `batchGet`, `update`, `delete`, `find`, `similar`, `embed`, `embedBatch`,
+`similarity`, `relate`, `unrelate`, `getRelations`, `neighbors`, `addMany`, `deleteMany`,
+`updateMany`, `relateMany`, `indexStats`, `findDuplicates`, `cluster`, `defineAggregate`,
+`removeAggregate`, `flush`, `migrate`, `diagnostics`, `clear`
+
+Sub-APIs (also proxied via dot-notation):
+`vfs.*`, `versions.*`, `neural()`, `counts.*`
+
+#### `src/modules/brainy/auth.ts` — Capability tokens
+Migrated from `brainy-client/src/auth.ts`:
+- `createCapabilityToken(options)` — HMAC-SHA256, `<base64url(payload)>.<base64url(sig)>`
+- `verifyCapabilityToken(token, secret)` — constant-time comparison, expiry check
+- `CreateCapabilityTokenOptions`, `CapabilityTokenClaims` types
+- Default TTL: 1 hour
+
+#### `src/modules/brainy/errors.ts`
+- `SDKError` (base)
+- `SDKAuthError` (401)
+- `SDKForbiddenError` (403)
+- `SDKTimeoutError`
+- `SDKDisconnectedError`
+- `SDKRpcError` (server returned error object)
+
+### 2c. VFS Namespace (`src/modules/vfs/`)
+
+**Source:** `node_modules/@soulcraft/brainy` — `brain.vfs.*` sub-API
+
+Thin namespace that delegates to `sdk.brainy.vfs.*` (which routes through the proxy).
+Exists as a first-class namespace so callers write `sdk.vfs.readFile()` not
+`sdk.brainy.vfs.readFile()`.
+
+Full method surface (from Brainy's `VirtualFileSystem`):
+`readFile`, `writeFile`, `appendFile`, `unlink`, `mkdir`, `rmdir`, `readdir`, `stat`,
+`exists`, `search`, `rename`, `copy`, `move`, `getDirectChildren`, `getTreeStructure`,
+`getDescendants`, `getEntity`, `resolvePath`, `watch`, `getTodos`
+
+Types to re-export: `VFSStats`, `VFSDirent`, `VFSEntity`, `VFSMetadata`
+
+### 2d. Versions Namespace (`src/modules/versions/`)
+
+Same pattern as vfs — thin namespace delegating to `sdk.brainy.versions.*`.
+
+Full method surface (from Brainy's `VersioningAPI`):
+`save`, `list`, `getVersion`, `restore`, `compare`, `prune`
+
+Types: `EntityVersion`, `VersionDiff`
+
+### 2e. Server Mode Instance Pool (`src/server/instance-pool.ts`)
+
+**Source:** Workshop's `brainy/brainy-singleton.ts` + Venue's `server.ts` tenantCache
+
+This is the most complex piece in Phase 2. Manages a pool of Brainy instances with
+three strategies.
+
+#### Configuration
+```typescript
+interface InstancePoolConfig {
+  storage: 'filesystem' | 'mmap-filesystem'
+  dataPath: string
+  strategy: 'per-user' | 'per-tenant' | 'per-scope'
+  scopeKey?: (userId: string, workspaceId: string) => string
+  maxInstances: number        // default: 200 (Workshop), 50 (Venue)
+  flushOnEvict: boolean       // default: true
+  cortexActivationFile?: string // path to .soulcraft.json
+}
+```
+
+#### API
+```typescript
+class BrainyInstancePool {
+  async forUser(userId: string, workspaceId: string): Promise<Brainy>
+  async forTenant(tenantSlug: string): Promise<Brainy>
+  async forScope(key: string, factory: () => Promise<Brainy>): Promise<Brainy>
+  async flush(key: string): Promise<void>
+  async flushAll(): Promise<void>
+  async shutdown(): Promise<void>  // flush all + release
+  getStats(): { size: number, maxSize: number, keys: string[] }
+}
+```
+
+#### Implementation notes
+- LRU cache with `lru-cache` package (already in dependencies)
+- On eviction: call `brain.flush()` if `flushOnEvict: true`
+- On `forUser` in `per-user` mode: key = `${emailHash}:${workspaceId}`
+  - Storage path: `{dataPath}/{emailHash}/{workspaceId}/`
+- On `forTenant`: key = `tenantSlug`, path: `{dataPath}/{tenantSlug}/`
+- Cortex activation: load `.soulcraft.json`, pass plugin to Brainy constructor
+- First `forUser/forTenant` call initializes Brainy (25-30s cold start — normal)
+
+### 2f. Server RPC + WS Handler Factories (`src/server/handlers.ts`)
+
+Migrated from `brainy-client/src/server/`:
+
+```typescript
+// Hono-compatible HTTP RPC handler:
+createBrainyHandler(config: BrainyHandlerConfig): (c: Context) => Promise<Response>
+
+// Bun WebSocket handler:
+createBrainyWsHandler(config: BrainyWsHandlerConfig): BrainyWsHandler
+
+// SvelteKit adapter:
+sveltekitBrainyHandler(config): RequestHandler
+```
+
+Config shapes:
+```typescript
+interface BrainyHandlerConfig {
+  getBrainy: (scope: string) => Promise<Brainy>  // pool.forTenant(scope)
+  verifyToken: (token: string) => Promise<CapabilityTokenClaims | null>
+  blockedMethods?: string[]  // e.g. ['clear'] — default []
+}
+```
+
+### 2g. Tests (Phase 2)
+
+- `tests/transports/local.test.ts` — call(), onEvent(), close()
+- `tests/transports/http.test.ts` — mock fetch, JSON RPC, error mapping, auth header
+- `tests/transports/ws.test.ts` — mock WebSocket, MessagePack encode/decode, change push, reconnection
+- `tests/transports/sse.test.ts` — mock EventSource, event parsing, reconnect
+- `tests/brainy/proxy.test.ts` — method proxying, dot-notation sub-APIs, special properties
+- `tests/brainy/auth.test.ts` — createCapabilityToken, verifyCapabilityToken, expiry, timing-safe
+- `tests/server/instance-pool.test.ts` — per-user, per-tenant, per-scope, LRU eviction, flush
+
+---
+
+## Phase 3 — Auth + License
+
+**Goal:** `sdk.auth.*` and `sdk.license.*` are fully functional. Products can drop
+their own auth config and use the SDK middleware directly.
+
+### 3a. Auth Module (`src/modules/auth/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/auth/packages/auth/src/` +
+`/media/dpsifr/storage/home/Projects/workshop/auth/better-auth.ts`
+
+#### `src/modules/auth/types.ts`
+All types from `@soulcraft/auth`:
+- `PlatformRole` — `'creator' | 'viewer' | 'customer' | 'staff' | 'manager' | 'owner' | 'learner' | 'instructor'`
+- `SoulcraftProduct` — `'workshop' | 'venue' | 'academy' | 'portal'`
+- `SoulcraftUserFields` — `{ platformRole, emailHash }`
+- `SoulcraftSessionUser` — resolved session user with all platform fields
+- `SoulcraftSession` — `{ user, sessionId, expiresAt }`
+- `OIDCClientConfig` — `{ idpUrl, clientId, clientSecret, redirectUri? }`
+- `AuthMode` — `'oidc-client'` (always — we dropped standalone per decision 8)
+
+#### `src/modules/auth/config.ts`
+From `@soulcraft/auth/config`:
+- `SOULCRAFT_USER_FIELDS` — better-auth `additionalFields` definition
+- `SOULCRAFT_SESSION_CONFIG` — 30-day sessions, 24-hour rolling refresh
+- `computeEmailHash(email: string): string` — SHA-256 hex of lowercased+trimmed email
+- `getOIDCClientConfig(): OIDCClientConfig` — reads from env
+
+#### `src/modules/auth/better-auth.ts`
+Creates the better-auth instance for a product:
+```typescript
+createProductAuth(options: {
+  product: SoulcraftProduct
+  clientId: string
+  clientSecret: string
+  dbPath?: string
+  defaultRole?: PlatformRole
+}): BetterAuth
+```
+
+Includes: OIDC client plugin (`genericOAuth`), PKCE, `crossSubDomainCookies`,
+`additionalFields` (platformRole + emailHash), `databaseHooks.user.create.before`
+(computes emailHash, sets defaultRole).
+
+#### `src/modules/auth/middleware.ts`
+```typescript
+// Hono middleware:
+createAuthMiddleware(auth: BetterAuth): MiddlewareHandler
+requireAuth(auth: BetterAuth): MiddlewareHandler
+optionalAuth(auth: BetterAuth): MiddlewareHandler
+
+// SvelteKit handle:
+createAuthHandle(auth: BetterAuth): Handle
+
+// Session proxy (for products verifying sessions against auth.soulcraft.com):
+createRemoteSessionVerifier(options: {
+  idpUrl: string
+  cacheTtlMs?: number  // default 30 000
+  cacheMax?: number    // default 500
+}): (cookieHeader: string) => Promise<SoulcraftSession | null>
+```
+
+#### `src/modules/auth/backchannel.ts`
+```typescript
+// Hono route handler for POST /api/auth/backchannel-logout:
+createBackchannelLogoutHandler(options: {
+  auth: BetterAuth
+  clientSecret: string
+  idpUrl: string
+  clientId: string
+}): (c: Context) => Promise<Response>
+```
+
+Implements the full verification flow: parse logout_token, verify HS256 JWT,
+validate iss/aud/events claims, delete all sessions for the subject user.
+
+### 3b. License Module (`src/modules/license/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/brainy/usage-tracking.ts` +
+`brainy/config-service.ts` + `brainy/billing-provider.ts` + `brainy/config-defaults.ts`
+
+#### `src/modules/license/cortex.ts`
+```typescript
+// Activate Cortex from .soulcraft.json activation code:
+activateCortex(options: {
+  activationFile?: string  // default './.soulcraft.json'
+  portalUrl?: string       // default 'https://soulcraft.com'
+}): Promise<CortexPlugin>
+
+// Background heartbeat:
+startHeartbeat(plugin: CortexPlugin, intervalMs?: number): () => void  // returns stop fn
+```
+
+#### `src/modules/license/plan.ts`
+```typescript
+// Plan verification via Portal:
+getLicensePlan(userId: string): Promise<LicensePlan>
+// LicensePlan: { plan: 'free'|'standard'|'pro', status: 'active'|'expired'|'cancelled',
+//               features: { cortex: boolean, ai: { credits: number } } }
+
+isLicenseActive(userId: string): Promise<boolean>
+getLicenseFeatures(userId: string): Promise<LicenseFeatures>
+```
+
+#### `src/modules/license/credits.ts`
+```typescript
+// AI usage metering (migrated from usage-tracking.ts):
+checkAICredits(userId: string): Promise<number>      // remaining credits
+consumeAICredit(userId: string, cost: { inputTokens: number, outputTokens: number }): Promise<void>
+canAccessAI(userId: string): Promise<boolean>
+getModelForUser(userId: string): Promise<string>     // platform model or BYOK
+recordMessageUsage(userId: string, usage: UsageRecord): Promise<void>
+getUsageStatus(userId: string): Promise<UsageStatus>
+```
+
+#### `src/modules/license/byok.ts`
+```typescript
+// BYOK (Bring Your Own Key) API key management:
+validateBYOK(apiKey: string): Promise<boolean>
+getAIProvider(userId: string): Promise<AIProviderConfig>
+// AIProviderConfig: { apiKey: string, source: 'platform' | 'byok' }
+```
+
+### 3c. Tests (Phase 3)
+
+- `tests/auth/config.test.ts` — computeEmailHash, SOULCRAFT_SESSION_CONFIG
+- `tests/auth/middleware.test.ts` — requireAuth 401, optionalAuth null, session extraction
+- `tests/auth/backchannel.test.ts` — JWT verification, claims validation, session deletion
+- `tests/auth/remote-session.test.ts` — LRU cache, TTL, proxy to IdP
+- `tests/license/cortex.test.ts` — activation file parsing, mock Portal exchange
+- `tests/license/credits.test.ts` — quota check, credit consumption, usage recording
+- `tests/license/byok.test.ts` — key validation, provider selection
+
+---
+
+## Phase 4 — AI + Events + Skills + Kits + Formats
+
+**Goal:** The full AI integration, event bus, skill system, kit loader, and Soulcraft
+format types are available in the SDK.
+
+### 4a. AI Module (`src/modules/ai/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/chat/`
+
+#### `src/modules/ai/models.ts`
+From `chat/models.ts`:
+- `MODEL_TIERS` — `{ planner: 'claude-opus-4-6', triage: 'claude-sonnet-4-6', executor: 'claude-haiku-4-5-20251001', fallback: 'claude-haiku-4-5-20251001' }`
+- `estimateCost(inputTokens, outputTokens, model)` → `number`
+- `formatCost(cost: number)` → `string`
+- `ModelRole` type
+
+#### `src/modules/ai/delegator.ts`
+From `chat/delegator.ts` + `chat/executor.ts` + `chat/planner.ts`:
+- `createDelegator(options)` — tiered model routing (Sonnet triage → Haiku execute → Sonnet synthesize)
+- `TriageDecision` — `'direct' | 'delegate_tasks' | 'recommend_plan'`
+- Tool execution with auto-escalation
+
+#### `src/modules/ai/tools.ts`
+From `chat/tools.ts`:
+- `ChatContext` type — `{ mode: 'file' | 'entity' | 'multi' | 'none', ... }`
+- `KitAIContext` type — AI persona + domain knowledge + workflows + graph guidance
+- `generateToolDefinitions(context: ChatContext)` — creates Anthropic tool definitions
+- All tool definition schemas (Workshop-specific tools stay in Workshop)
+
+#### `src/modules/ai/ui-actions.ts`
+From `chat/ui-actions.ts`:
+- `UI_ACTIONS` registry — all UI-controllable actions
+- `generateUIToolDefinitions()` — auto-generates Claude tool definitions from registry
+- `isUIAction(name)`, `getUIAction(name)` helpers
+- `UIAction`, `UIActionParam` types
+
+#### `src/modules/ai/briggy.ts`
+From `routes/briggy.ts`:
+- `BriggyPersona` type — name, description, systemPrompt, voice, etc.
+- `createBriggyHandler(options)` — Hono route handler factory for `/api/briggy/*`
+- `BriggyGenerateRequest`, `BriggyChatRequest`, `BriggyResponse` types
+- Max tokens: 1024 default, 2048 ceiling
+- Stateless generate + session-based chat endpoints
+
+### 4b. Events Module (`src/modules/events/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/events/data-change-emitter.ts`
+
+```typescript
+// All 30+ event types:
+type DataChangeType =
+  | 'vfs_write' | 'vfs_edit' | 'vfs_delete' | 'vfs_mkdir' | 'vfs_rename'
+  | 'vfs_copy' | 'vfs_upload' | 'vfs_bulk_write'
+  | 'entity_create' | 'entity_created' | 'entity_update' | 'entity_updated'
+  | 'entity_delete' | 'relationship_created' | 'relation_create' | 'relation_delete'
+  | 'activity_message_new' | 'activity_tool_new' | 'activity_task_new'
+  | 'activity_note_new' | 'activity_conversation_new'
+  | 'file_deleted' | 'directory_deleted' | 'file_renamed' | 'file_copied'
+  | 'directory_created' | 'data_imported'
+
+interface DataChangeEvent {
+  type: DataChangeType
+  timestamp: number
+  userId: string
+  workspaceId?: string
+  data: { path?: string; id?: string; nounType?: string; [key: string]: unknown }
+}
+
+// Singleton emitter (server-side):
+class PlatformEventBus extends EventEmitter {
+  emitChange(event: DataChangeEvent): void
+  onDataChange(handler: (event: DataChangeEvent) => void): void
+  offDataChange(handler: (event: DataChangeEvent) => void): void
+}
+
+createEventBus(): PlatformEventBus
+```
+
+SSE stream factory (for Hono endpoints):
+```typescript
+createSSEStream(options: {
+  bus: PlatformEventBus
+  filter: (event: DataChangeEvent) => boolean
+  heartbeatMs?: number  // default 30 000
+}): (c: Context) => Response
+```
+
+### 4c. Skills Module (`src/modules/skills/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/brainy/skill-service.ts` +
+`brainy/bundled-skills.ts`
+
+```typescript
+// Skill metadata (from VFS frontmatter):
+interface SkillMetadata {
+  id: string
+  name: string
+  scope: 'universal' | string  // string = kitId
+  userInvocable: boolean
+  disableModelInvocation?: boolean
+  allowedTools?: string[]
+  argumentHint?: string
+}
+
+class SkillService {
+  constructor(private vfs: VfsModule) {}
+  listSkills(): Promise<SkillMetadata[]>
+  getActiveSkills(): Promise<SkillMetadata[]>
+  getUserInvocableSkills(): Promise<SkillMetadata[]>
+  getSkillContent(id: string): Promise<string>  // the markdown content
+  createSkill(meta: SkillMetadata, content: string): Promise<void>
+  updateSkill(id: string, updates: Partial<SkillMetadata>, content?: string): Promise<void>
+  deleteSkill(id: string): Promise<void>
+  toggleSkill(id: string, enabled: boolean): Promise<void>
+}
+
+// Bundled skills (pre-packaged with SDK):
+listBundledSkills(): BundledSkill[]
+installBundledSkill(skillId: string, vfs: VfsModule): Promise<void>
+installAllBundledSkills(vfs: VfsModule): Promise<void>
+getMissingBundledSkills(vfs: VfsModule): Promise<BundledSkill[]>
+```
+
+### 4d. Kits Module (`src/modules/kits/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/src/lib/templates/loader.ts` +
+`@soulcraft/kits` package
+
+```typescript
+// Kit loading and initialization:
+loadKit(kitId: string): Promise<SoulcraftKitConfig>
+listKits(): Promise<SoulcraftKitConfig[]>
+applyKit(kitId: string, brainy: SoulcraftBrainy, vfs: VfsModule): Promise<void>
+
+// Types (re-exported from @soulcraft/kit-schema):
+// SoulcraftKitConfig, WorkshopConfig, WorkshopWorkbench, WorkshopStarterFile,
+// SharedDataModel, AcademyKitBlock, etc.
+```
+
+### 4e. Formats Module (`src/modules/formats/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/packages/views/src/shared/types.ts` +
+`src/lib/types/richDocument.ts`
+
+Centralizes all Soulcraft portable content format types:
+
+```typescript
+// Already exists in @soulcraft/views — migrate here as canonical home:
+export type { WvizDocument, WvizEntity, WvizEdge, WvizViewType } from './wviz.js'
+
+// WDOC (Workshop Document — TipTap/ProseMirror JSON):
+export type { WdocDocument, WdocNode, WdocMark } from './wdoc.js'
+
+// WSLIDE (Workshop Slide):
+export type { WslideDocument, WslideSlide, WslideBackground, WslideTransition } from './wslide.js'
+
+// WQUIZ (Workshop Quiz):
+export type { WquizDocument, WquizQuestion, WquizAnswer } from './wquiz.js'
+
+// Common:
+export type { SoulcraftFormat } from './common.js'
+// SoulcraftFormat = 'wviz' | 'wdoc' | 'wslide' | 'wquiz' | 'wform'
+```
+
+---
+
+## Phase 5 — Billing + Notifications
+
+### 5a. Billing Module (`src/modules/billing/`)
+
+**Source:** `/media/dpsifr/storage/home/Projects/workshop/brainy/usage-tracking.ts` +
+`brainy/billing-provider.ts` + `brainy/config-service.ts` + `brainy/config-defaults.ts`
+
+Note: billing overlaps with license/credits (Phase 3). Phase 3 covers AI credit
+metering. Phase 5 covers the full Stripe subscription + top-up flow.
+
+```typescript
+// Usage tracking (complement to license/credits):
+getCurrentPeriod(): string                          // 'YYYY-MM'
+getPeriodEnd(userId: string): Promise<Date>
+checkUsageLimits(usage: UsageData, limit: number): LimitCheckResult
+
+// Stripe subscription management:
+getSubscriptionStatus(userId: string): Promise<SubscriptionData>
+subscribeToPlan(userId: string, priceId: string): Promise<{ url: string }>
+cancelSubscription(userId: string): Promise<void>
+getPortalUrl(userId: string): Promise<string>
+
+// Top-up credits:
+purchaseTopUp(userId: string, amount: number): Promise<void>
+getTopUpBalance(userId: string): Promise<number>
+addTopUp(userId: string, amount: number): Promise<void>
+
+// Config (plans, pricing — from Firestore or defaults):
+getPlatformConfig(): Promise<PlatformConfig>
+getModelPricing(model: string): Promise<ModelPricing>
+
+// Billing provider (Firestore vs local dev mode):
+createBillingProvider(mode: 'firestore' | 'local'): BillingProvider
+```
+
+### 5b. Notifications Module (`src/modules/notifications/`)
+
+**Source:** `/home/dpsifr/Projects/venue/apps/web/src/lib/server/notifications/`
+
+```typescript
+// Provider-agnostic interface:
+interface NotificationSender {
+  send(notification: Notification): Promise<NotificationResult>
+}
+
+type Notification =
+  | { channel: 'email'; to: string; subject: string; html: string; text: string }
+  | { channel: 'sms'; to: string; body: string }
+
+interface NotificationResult {
+  success: boolean
+  messageId?: string
+  error?: string
+}
+
+// Factory — auto-selects provider from env:
+getNotificationSender(): NotificationSender
+// - POSTMARK_API_KEY set → PostmarkSender
+// - TWILIO_ACCOUNT_SID set → TwilioSender
+// - neither → DevConsoleSender (logs to console)
+
+// Individual providers (for explicit use):
+createPostmarkSender(apiKey: string): NotificationSender
+createTwilioSender(config: TwilioConfig): NotificationSender
+createDevSender(): NotificationSender
+
+// Template helpers (Venue's booking templates become generic):
+renderEmailTemplate(template: string, data: Record<string, unknown>): string
+```
+
+---
+
+## Phase 6 — npm Publish + Migrate All Products
+
+### 6a. Pre-publish checklist
+- [ ] All tests passing (`bun test`)
+- [ ] TypeScript builds cleanly (`bun run check`)
+- [ ] No stubs, no TODOs, no `as any`
+- [ ] JSDoc on every exported symbol
+- [ ] Module-level `@module` block on every file
+- [ ] `package.json` version set to `1.0.0`
+- [ ] `README.md` written with usage examples for all three entry points
+
+### 6b. Publish
+```bash
+npm publish --access restricted
+```
+
+### 6c. Migrate Workshop
+Files to update in `/media/dpsifr/storage/home/Projects/workshop/`:
+1. `package.json` — add `@soulcraft/sdk`, remove `@soulcraft/brainy-client`, `@soulcraft/auth`
+2. `build.sh` — add `sdk` to bundle loop, remove `brainy-client` and `auth`
+3. `auth/better-auth.ts` — replace with `createProductAuth('workshop', ...)` from SDK
+4. `server-hono.ts` — replace brainy-client handler factories with SDK handlers
+5. `brainy/brainy-singleton.ts` — replace with `sdk.server.instancePool`
+6. `brainy/remote-brainy.ts` — replace with SDK `WsTransport`
+7. `brainy/usage-tracking.ts` — replace with `sdk.license.credits.*` + `sdk.billing.*`
+8. All `import { ... } from '@soulcraft/auth'` → `from '@soulcraft/sdk'`
+9. All `import { createBrainyClient } from '@soulcraft/brainy-client'` → `from '@soulcraft/sdk/client'`
+
+### 6d. Migrate Venue
+Files to update in `/home/dpsifr/Projects/venue/`:
+1. `apps/web/package.json` — same package swap
+2. `apps/web/server.ts` — replace brainy-client WS handler with SDK
+3. `apps/web/src/lib/server/auth.ts` — replace with `createProductAuth('venue', ...)`
+4. `apps/web/src/routes/api/brainy/rpc/+server.ts` — replace with SDK HTTP handler
+5. All notification code → `sdk.notifications.*`
+
+### 6e. Migrate Academy
+Files to update in `/media/dpsifr/storage/home/Projects/academy/`:
+1. `package.json`, `auth/better-auth.ts`, `server.ts` — same patterns as Workshop
+
+### 6f. Post-migration
+- Deprecate `@soulcraft/brainy-client` on npmjs.com (`npm deprecate`)
+- Deprecate `@soulcraft/auth` on npmjs.com
+- Update `PLATFORM-HANDOFF.md` thread to RESOLVED
+
+---
+
+## Key Reference Files (Read Before Starting Each Phase)
+
+A new session implementing any phase should read these files FIRST:
+
+**Phase 2:**
+- `/media/dpsifr/storage/home/Projects/brainy-client/src/` — all transport implementations
+- `/media/dpsifr/storage/home/Projects/brainy-client/src/server/` — handler factories
+- `/media/dpsifr/storage/home/Projects/workshop/brainy/brainy-singleton.ts` — instance pool pattern
+- `node_modules/@soulcraft/brainy/dist/brainy.d.ts` — full Brainy type surface
+
+**Phase 3:**
+- `/media/dpsifr/storage/home/Projects/auth/packages/auth/src/` — shared auth types + config
+- `/media/dpsifr/storage/home/Projects/workshop/auth/better-auth.ts` — product auth pattern
+- `/media/dpsifr/storage/home/Projects/workshop/brainy/usage-tracking.ts` — credit metering
+
+**Phase 4:**
+- `/media/dpsifr/storage/home/Projects/workshop/chat/` — entire directory
+- `/media/dpsifr/storage/home/Projects/workshop/events/data-change-emitter.ts`
+- `/media/dpsifr/storage/home/Projects/workshop/brainy/skill-service.ts`
+
+**Phase 5:**
+- `/media/dpsifr/storage/home/Projects/workshop/brainy/billing-provider.ts`
+- `/home/dpsifr/Projects/venue/apps/web/src/lib/server/notifications/`
+
+**Phase 6:**
+- Workshop's `build.sh` — bundle loop pattern
+- All `import` statements in Workshop/Venue/Academy server files