chore(orchestrator): complete Phase 6 milestone v0.0.7 (#105)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>

.env.example

@@ -18,3 +18,17 @@ BETTER_AUTH_URL=http://localhost:4000
 
 # Gateway
 GATEWAY_PORT=4000
+
+# Discord Plugin (optional — set DISCORD_BOT_TOKEN to enable)
+# DISCORD_BOT_TOKEN=
+# DISCORD_GUILD_ID=
+# DISCORD_GATEWAY_URL=http://localhost:4000
+
+# Telegram Plugin (optional — set TELEGRAM_BOT_TOKEN to enable)
+# TELEGRAM_BOT_TOKEN=
+# TELEGRAM_GATEWAY_URL=http://localhost:4000
+
+# Authentik SSO (optional — set AUTHENTIK_CLIENT_ID to enable)
+# AUTHENTIK_ISSUER=https://auth.example.com
+# AUTHENTIK_CLIENT_ID=
+# AUTHENTIK_CLIENT_SECRET=

.woodpecker/ci.yml

@@ -1,22 +1,25 @@
 variables:
   - &node_image 'node:22-alpine'
-  - &install_deps |
-    corepack enable
-    pnpm install --frozen-lockfile
+  - &enable_pnpm 'corepack enable'
 
 when:
   - event: [push, pull_request, manual]
 
+# Steps run sequentially to avoid OOM on the CI runner.
+# node_modules is installed once by the install step and shared across
+# all subsequent steps via Woodpecker's shared workspace volume.
+
 steps:
   install:
     image: *node_image
     commands:
-      - *install_deps
+      - corepack enable
+      - pnpm install --frozen-lockfile
 
   typecheck:
     image: *node_image
     commands:
-      - *install_deps
+      - *enable_pnpm
       - pnpm typecheck
     depends_on:
       - install
@@ -24,34 +27,31 @@ steps:
   lint:
     image: *node_image
     commands:
-      - *install_deps
+      - *enable_pnpm
       - pnpm lint
     depends_on:
-      - install
+      - typecheck
 
   format:
     image: *node_image
     commands:
-      - *install_deps
+      - *enable_pnpm
       - pnpm format:check
     depends_on:
-      - install
+      - lint
 
   test:
     image: *node_image
     commands:
-      - *install_deps
+      - *enable_pnpm
       - pnpm test
     depends_on:
-      - install
+      - format
 
   build:
     image: *node_image
     commands:
-      - *install_deps
+      - *enable_pnpm
       - pnpm build
     depends_on:
-      - typecheck
-      - lint
-      - format
       - test

apps/gateway/package.json

@@ -8,21 +8,27 @@
     "build": "tsc",
     "dev": "tsx watch src/main.ts",
     "lint": "eslint src",
-    "typecheck": "tsc --noEmit",
+    "typecheck": "tsc --noEmit -p tsconfig.typecheck.json",
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@fastify/helmet": "^13.0.2",
     "@mariozechner/pi-ai": "~0.57.1",
     "@mariozechner/pi-coding-agent": "~0.57.1",
     "@mosaic/auth": "workspace:^",
     "@mosaic/brain": "workspace:^",
     "@mosaic/coord": "workspace:^",
     "@mosaic/db": "workspace:^",
+    "@mosaic/discord-plugin": "workspace:^",
+    "@mosaic/telegram-plugin": "workspace:^",
+    "@mosaic/log": "workspace:^",
+    "@mosaic/memory": "workspace:^",
     "@mosaic/types": "workspace:^",
     "@nestjs/common": "^11.0.0",
     "@nestjs/core": "^11.0.0",
     "@nestjs/platform-fastify": "^11.0.0",
     "@nestjs/platform-socket.io": "^11.0.0",
+    "@nestjs/throttler": "^6.5.0",
     "@nestjs/websockets": "^11.0.0",
     "@opentelemetry/auto-instrumentations-node": "^0.71.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
@@ -33,7 +39,10 @@
     "@opentelemetry/semantic-conventions": "^1.40.0",
     "@sinclair/typebox": "^0.34.48",
     "better-auth": "^1.5.5",
+    "class-transformer": "^0.5.1",
+    "class-validator": "^0.15.1",
     "fastify": "^5.0.0",
+    "node-cron": "^4.2.1",
     "reflect-metadata": "^0.2.0",
     "rxjs": "^7.8.0",
     "socket.io": "^4.8.0",
@@ -41,6 +50,7 @@
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/node-cron": "^3.0.11",
     "@types/uuid": "^10.0.0",
     "tsx": "^4.0.0",
     "typescript": "^5.8.0",

apps/gateway/src/__tests__/resource-ownership.test.ts

@@ -0,0 +1,137 @@
+import { ForbiddenException } from '@nestjs/common';
+import { describe, expect, it, vi } from 'vitest';
+import { ConversationsController } from '../conversations/conversations.controller.js';
+import { MissionsController } from '../missions/missions.controller.js';
+import { ProjectsController } from '../projects/projects.controller.js';
+import { TasksController } from '../tasks/tasks.controller.js';
+
+function createBrain() {
+  return {
+    conversations: {
+      findAll: vi.fn(),
+      findById: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      remove: vi.fn(),
+      findMessages: vi.fn(),
+      addMessage: vi.fn(),
+    },
+    projects: {
+      findAll: vi.fn(),
+      findById: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      remove: vi.fn(),
+    },
+    missions: {
+      findAll: vi.fn(),
+      findById: vi.fn(),
+      findByProject: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      remove: vi.fn(),
+    },
+    tasks: {
+      findAll: vi.fn(),
+      findById: vi.fn(),
+      findByProject: vi.fn(),
+      findByMission: vi.fn(),
+      findByStatus: vi.fn(),
+      create: vi.fn(),
+      update: vi.fn(),
+      remove: vi.fn(),
+    },
+  };
+}
+
+describe('Resource ownership checks', () => {
+  it('forbids access to another user conversation', async () => {
+    const brain = createBrain();
+    brain.conversations.findById.mockResolvedValue({ id: 'conv-1', userId: 'user-2' });
+    const controller = new ConversationsController(brain as never);
+
+    await expect(controller.findOne('conv-1', { id: 'user-1' })).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+  });
+
+  it('forbids access to another user project', async () => {
+    const brain = createBrain();
+    brain.projects.findById.mockResolvedValue({ id: 'project-1', ownerId: 'user-2' });
+    const controller = new ProjectsController(brain as never);
+
+    await expect(controller.findOne('project-1', { id: 'user-1' })).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+  });
+
+  it('forbids access to a mission owned by another project owner', async () => {
+    const brain = createBrain();
+    brain.missions.findById.mockResolvedValue({ id: 'mission-1', projectId: 'project-1' });
+    brain.projects.findById.mockResolvedValue({ id: 'project-1', ownerId: 'user-2' });
+    const controller = new MissionsController(brain as never);
+
+    await expect(controller.findOne('mission-1', { id: 'user-1' })).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+  });
+
+  it('forbids access to a task owned by another project owner', async () => {
+    const brain = createBrain();
+    brain.tasks.findById.mockResolvedValue({ id: 'task-1', projectId: 'project-1' });
+    brain.projects.findById.mockResolvedValue({ id: 'project-1', ownerId: 'user-2' });
+    const controller = new TasksController(brain as never);
+
+    await expect(controller.findOne('task-1', { id: 'user-1' })).rejects.toBeInstanceOf(
+      ForbiddenException,
+    );
+  });
+
+  it('forbids creating a task with an unowned project', async () => {
+    const brain = createBrain();
+    brain.projects.findById.mockResolvedValue({ id: 'project-1', ownerId: 'user-2' });
+    const controller = new TasksController(brain as never);
+
+    await expect(
+      controller.create(
+        {
+          title: 'Task',
+          projectId: 'project-1',
+        },
+        { id: 'user-1' },
+      ),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+
+  it('forbids listing tasks for an unowned project', async () => {
+    const brain = createBrain();
+    brain.projects.findById.mockResolvedValue({ id: 'project-1', ownerId: 'user-2' });
+    const controller = new TasksController(brain as never);
+
+    await expect(
+      controller.list({ id: 'user-1' }, 'project-1', undefined, undefined),
+    ).rejects.toBeInstanceOf(ForbiddenException);
+  });
+
+  it('lists only tasks for the current user owned projects when no filter is provided', async () => {
+    const brain = createBrain();
+    brain.projects.findAll.mockResolvedValue([
+      { id: 'project-1', ownerId: 'user-1' },
+      { id: 'project-2', ownerId: 'user-2' },
+    ]);
+    brain.missions.findAll.mockResolvedValue([{ id: 'mission-1', projectId: 'project-1' }]);
+    brain.tasks.findAll.mockResolvedValue([
+      { id: 'task-1', projectId: 'project-1' },
+      { id: 'task-2', missionId: 'mission-1' },
+      { id: 'task-3', projectId: 'project-2' },
+    ]);
+    const controller = new TasksController(brain as never);
+
+    await expect(
+      controller.list({ id: 'user-1' }, undefined, undefined, undefined),
+    ).resolves.toEqual([
+      { id: 'task-1', projectId: 'project-1' },
+      { id: 'task-2', missionId: 'mission-1' },
+    ]);
+  });
+});

apps/gateway/src/agent/agent.service.ts

@@ -7,11 +7,15 @@ import {
   type ToolDefinition,
 } from '@mariozechner/pi-coding-agent';
 import type { Brain } from '@mosaic/brain';
+import type { Memory } from '@mosaic/memory';
 import { BRAIN } from '../brain/brain.tokens.js';
+import { MEMORY } from '../memory/memory.tokens.js';
+import { EmbeddingService } from '../memory/embedding.service.js';
 import { CoordService } from '../coord/coord.service.js';
 import { ProviderService } from './provider.service.js';
 import { createBrainTools } from './tools/brain-tools.js';
 import { createCoordTools } from './tools/coord-tools.js';
+import { createMemoryTools } from './tools/memory-tools.js';
 import type { SessionInfoDto } from './session.dto.js';
 
 export interface AgentSessionOptions {
@@ -42,9 +46,15 @@ export class AgentService implements OnModuleDestroy {
   constructor(
     @Inject(ProviderService) private readonly providerService: ProviderService,
     @Inject(BRAIN) private readonly brain: Brain,
+    @Inject(MEMORY) private readonly memory: Memory,
+    @Inject(EmbeddingService) private readonly embeddingService: EmbeddingService,
     @Inject(CoordService) private readonly coordService: CoordService,
   ) {
-    this.customTools = [...createBrainTools(brain), ...createCoordTools(coordService)];
+    this.customTools = [
+      ...createBrainTools(brain),
+      ...createCoordTools(coordService),
+      ...createMemoryTools(memory, embeddingService.available ? embeddingService : null),
+    ];
     this.logger.log(`Registered ${this.customTools.length} custom tools`);
   }
 

apps/gateway/src/agent/provider.service.ts

@@ -9,7 +9,7 @@ export class ProviderService implements OnModuleInit {
   private registry!: ModelRegistry;
 
   async onModuleInit(): Promise<void> {
-    const authStorage = AuthStorage.create();
+    const authStorage = AuthStorage.inMemory();
     this.registry = new ModelRegistry(authStorage);
 
     this.registerOllamaProvider();
@@ -89,7 +89,7 @@ export class ProviderService implements OnModuleInit {
     const modelsEnv = process.env['OLLAMA_MODELS'] ?? 'llama3.2,codellama,mistral';
     const modelIds = modelsEnv
       .split(',')
-      .map((m) => m.trim())
+      .map((modelId: string) => modelId.trim())
       .filter(Boolean);
 
     this.registerCustomProvider({

apps/gateway/src/agent/routing.service.ts

@@ -145,8 +145,11 @@ export class RoutingService {
 
   private classifyTier(model: ModelInfo): CostTier {
     const cost = model.cost.input;
-    if (cost <= COST_TIER_THRESHOLDS.cheap.maxInput) return 'cheap';
-    if (cost <= COST_TIER_THRESHOLDS.standard.maxInput) return 'standard';
+    const cheapThreshold = COST_TIER_THRESHOLDS['cheap'];
+    const standardThreshold = COST_TIER_THRESHOLDS['standard'];
+
+    if (cost <= cheapThreshold.maxInput) return 'cheap';
+    if (cost <= standardThreshold.maxInput) return 'standard';
     return 'premium';
   }
 

apps/gateway/src/agent/tools/memory-tools.ts

@@ -0,0 +1,158 @@
+import { Type } from '@sinclair/typebox';
+import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
+import type { Memory } from '@mosaic/memory';
+import type { EmbeddingProvider } from '@mosaic/memory';
+
+export function createMemoryTools(
+  memory: Memory,
+  embeddingProvider: EmbeddingProvider | null,
+): ToolDefinition[] {
+  const searchMemory: ToolDefinition = {
+    name: 'memory_search',
+    label: 'Search Memory',
+    description:
+      'Search across stored insights and knowledge using natural language. Returns semantically similar results.',
+    parameters: Type.Object({
+      userId: Type.String({ description: 'User ID to search memory for' }),
+      query: Type.String({ description: 'Natural language search query' }),
+      limit: Type.Optional(Type.Number({ description: 'Max results (default 5)' })),
+    }),
+    async execute(_toolCallId, params) {
+      const { userId, query, limit } = params as {
+        userId: string;
+        query: string;
+        limit?: number;
+      };
+
+      if (!embeddingProvider) {
+        return {
+          content: [
+            {
+              type: 'text' as const,
+              text: 'Semantic search unavailable — no embedding provider configured',
+            },
+          ],
+          details: undefined,
+        };
+      }
+
+      const embedding = await embeddingProvider.embed(query);
+      const results = await memory.insights.searchByEmbedding(userId, embedding, limit ?? 5);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(results, null, 2) }],
+        details: undefined,
+      };
+    },
+  };
+
+  const getPreferences: ToolDefinition = {
+    name: 'memory_get_preferences',
+    label: 'Get User Preferences',
+    description: 'Retrieve stored preferences for a user.',
+    parameters: Type.Object({
+      userId: Type.String({ description: 'User ID' }),
+      category: Type.Optional(
+        Type.String({
+          description: 'Filter by category: communication, coding, workflow, appearance, general',
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const { userId, category } = params as { userId: string; category?: string };
+      type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
+      const prefs = category
+        ? await memory.preferences.findByUserAndCategory(userId, category as Cat)
+        : await memory.preferences.findByUser(userId);
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(prefs, null, 2) }],
+        details: undefined,
+      };
+    },
+  };
+
+  const savePreference: ToolDefinition = {
+    name: 'memory_save_preference',
+    label: 'Save User Preference',
+    description:
+      'Store a learned user preference (e.g., "prefers tables over paragraphs", "timezone: America/Chicago").',
+    parameters: Type.Object({
+      userId: Type.String({ description: 'User ID' }),
+      key: Type.String({ description: 'Preference key' }),
+      value: Type.String({ description: 'Preference value (JSON string)' }),
+      category: Type.Optional(
+        Type.String({
+          description: 'Category: communication, coding, workflow, appearance, general',
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const { userId, key, value, category } = params as {
+        userId: string;
+        key: string;
+        value: string;
+        category?: string;
+      };
+      type Cat = 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
+      let parsedValue: unknown;
+      try {
+        parsedValue = JSON.parse(value);
+      } catch {
+        parsedValue = value;
+      }
+      const pref = await memory.preferences.upsert({
+        userId,
+        key,
+        value: parsedValue,
+        category: (category as Cat) ?? 'general',
+        source: 'agent',
+      });
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(pref, null, 2) }],
+        details: undefined,
+      };
+    },
+  };
+
+  const saveInsight: ToolDefinition = {
+    name: 'memory_save_insight',
+    label: 'Save Insight',
+    description:
+      'Store a learned insight, decision, or knowledge extracted from the current interaction.',
+    parameters: Type.Object({
+      userId: Type.String({ description: 'User ID' }),
+      content: Type.String({ description: 'The insight or knowledge to store' }),
+      category: Type.Optional(
+        Type.String({
+          description: 'Category: decision, learning, preference, fact, pattern, general',
+        }),
+      ),
+    }),
+    async execute(_toolCallId, params) {
+      const { userId, content, category } = params as {
+        userId: string;
+        content: string;
+        category?: string;
+      };
+      type Cat = 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
+
+      let embedding: number[] | null = null;
+      if (embeddingProvider) {
+        embedding = await embeddingProvider.embed(content);
+      }
+
+      const insight = await memory.insights.create({
+        userId,
+        content,
+        embedding,
+        source: 'agent',
+        category: (category as Cat) ?? 'learning',
+      });
+      return {
+        content: [{ type: 'text' as const, text: JSON.stringify(insight, null, 2) }],
+        details: undefined,
+      };
+    },
+  };
+
+  return [searchMemory, getPreferences, savePreference, saveInsight];
+}

apps/gateway/src/app.module.ts

@@ -1,4 +1,5 @@
 import { Module } from '@nestjs/common';
+import { APP_GUARD } from '@nestjs/core';
 import { HealthController } from './health/health.controller.js';
 import { DatabaseModule } from './database/database.module.js';
 import { AuthModule } from './auth/auth.module.js';
@@ -10,9 +11,15 @@ import { ProjectsModule } from './projects/projects.module.js';
 import { MissionsModule } from './missions/missions.module.js';
 import { TasksModule } from './tasks/tasks.module.js';
 import { CoordModule } from './coord/coord.module.js';
+import { MemoryModule } from './memory/memory.module.js';
+import { LogModule } from './log/log.module.js';
+import { SkillsModule } from './skills/skills.module.js';
+import { PluginModule } from './plugin/plugin.module.js';
+import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
 
 @Module({
   imports: [
+    ThrottlerModule.forRoot([{ name: 'default', ttl: 60_000, limit: 60 }]),
     DatabaseModule,
     AuthModule,
     BrainModule,
@@ -23,7 +30,17 @@ import { CoordModule } from './coord/coord.module.js';
     MissionsModule,
     TasksModule,
     CoordModule,
+    MemoryModule,
+    LogModule,
+    SkillsModule,
+    PluginModule,
   ],
   controllers: [HealthController],
+  providers: [
+    {
+      provide: APP_GUARD,
+      useClass: ThrottlerGuard,
+    },
+  ],
 })
 export class AppModule {}

apps/gateway/src/auth/resource-ownership.ts

@@ -0,0 +1,11 @@
+import { ForbiddenException } from '@nestjs/common';
+
+export function assertOwner(
+  ownerId: string | null | undefined,
+  userId: string,
+  resourceName: string,
+): void {
+  if (!ownerId || ownerId !== userId) {
+    throw new ForbiddenException(`${resourceName} does not belong to the current user`);
+  }
+}

apps/gateway/src/chat/__tests__/chat-security.test.ts

@@ -0,0 +1,80 @@
+import { readFileSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { validateSync } from 'class-validator';
+import { describe, expect, it, vi } from 'vitest';
+import { SendMessageDto } from '../../conversations/conversations.dto.js';
+import { ChatRequestDto } from '../chat.dto.js';
+import { validateSocketSession } from '../chat.gateway-auth.js';
+
+describe('Chat controller source hardening', () => {
+  it('applies AuthGuard and reads the current user', () => {
+    const source = readFileSync(resolve('src/chat/chat.controller.ts'), 'utf8');
+
+    expect(source).toContain('@UseGuards(AuthGuard)');
+    expect(source).toContain('@CurrentUser() user: { id: string }');
+  });
+});
+
+describe('WebSocket session authentication', () => {
+  it('returns null when the handshake does not resolve to a session', async () => {
+    const result = await validateSocketSession(
+      {},
+      {
+        api: {
+          getSession: vi.fn().mockResolvedValue(null),
+        },
+      },
+    );
+
+    expect(result).toBeNull();
+  });
+
+  it('returns the resolved session when Better Auth accepts the headers', async () => {
+    const session = { user: { id: 'user-1' }, session: { id: 'session-1' } };
+
+    const result = await validateSocketSession(
+      { cookie: 'session=abc' },
+      {
+        api: {
+          getSession: vi.fn().mockResolvedValue(session),
+        },
+      },
+    );
+
+    expect(result).toEqual(session);
+  });
+});
+
+describe('Chat DTO validation', () => {
+  it('rejects unsupported message roles', () => {
+    const dto = Object.assign(new SendMessageDto(), {
+      content: 'hello',
+      role: 'moderator',
+    });
+
+    const errors = validateSync(dto);
+
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it('rejects oversized conversation message content above 10000 characters', () => {
+    const dto = Object.assign(new SendMessageDto(), {
+      content: 'x'.repeat(10_001),
+      role: 'user',
+    });
+
+    const errors = validateSync(dto);
+
+    expect(errors.length).toBeGreaterThan(0);
+  });
+
+  it('rejects oversized chat content above 10000 characters', () => {
+    const dto = Object.assign(new ChatRequestDto(), {
+      content: 'x'.repeat(10_001),
+    });
+
+    const errors = validateSync(dto);
+
+    expect(errors.length).toBeGreaterThan(0);
+  });
+});

apps/gateway/src/chat/chat.controller.ts

@@ -1,12 +1,20 @@
-import { Controller, Post, Body, Logger, HttpException, HttpStatus, Inject } from '@nestjs/common';
+import {
+  Controller,
+  Post,
+  Body,
+  Logger,
+  HttpException,
+  HttpStatus,
+  Inject,
+  UseGuards,
+} from '@nestjs/common';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import { Throttle } from '@nestjs/throttler';
 import { AgentService } from '../agent/agent.service.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
 import { v4 as uuid } from 'uuid';
-
-interface ChatRequest {
-  conversationId?: string;
-  content: string;
-}
+import { ChatRequestDto } from './chat.dto.js';
 
 interface ChatResponse {
   conversationId: string;
@@ -14,13 +22,18 @@ interface ChatResponse {
 }
 
 @Controller('api/chat')
+@UseGuards(AuthGuard)
 export class ChatController {
   private readonly logger = new Logger(ChatController.name);
 
   constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
 
   @Post()
-  async chat(@Body() body: ChatRequest): Promise<ChatResponse> {
+  @Throttle({ default: { limit: 10, ttl: 60_000 } })
+  async chat(
+    @Body() body: ChatRequestDto,
+    @CurrentUser() user: { id: string },
+  ): Promise<ChatResponse> {
     const conversationId = body.conversationId ?? uuid();
 
     try {
@@ -36,6 +49,8 @@ export class ChatController {
       throw new HttpException('Agent session unavailable', HttpStatus.SERVICE_UNAVAILABLE);
     }
 
+    this.logger.debug(`Handling chat request for user=${user.id}, conversation=${conversationId}`);
+
     let responseText = '';
 
     const done = new Promise<void>((resolve, reject) => {

apps/gateway/src/chat/chat.dto.ts

@@ -0,0 +1,31 @@
+import { IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+
+export class ChatRequestDto {
+  @IsOptional()
+  @IsUUID()
+  conversationId?: string;
+
+  @IsString()
+  @MaxLength(10_000)
+  content!: string;
+}
+
+export class ChatSocketMessageDto {
+  @IsOptional()
+  @IsUUID()
+  conversationId?: string;
+
+  @IsString()
+  @MaxLength(10_000)
+  content!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  provider?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  modelId?: string;
+}

apps/gateway/src/chat/chat.gateway-auth.ts

@@ -0,0 +1,30 @@
+import type { IncomingHttpHeaders } from 'node:http';
+import { fromNodeHeaders } from 'better-auth/node';
+
+export interface SocketSessionResult {
+  session: unknown;
+  user: { id: string };
+}
+
+export interface SessionAuth {
+  api: {
+    getSession(context: { headers: Headers }): Promise<SocketSessionResult | null>;
+  };
+}
+
+export async function validateSocketSession(
+  headers: IncomingHttpHeaders,
+  auth: SessionAuth,
+): Promise<SocketSessionResult | null> {
+  const sessionHeaders = fromNodeHeaders(headers);
+  const result = await auth.api.getSession({ headers: sessionHeaders });
+
+  if (!result) {
+    return null;
+  }
+
+  return {
+    session: result.session,
+    user: { id: result.user.id },
+  };
+}

apps/gateway/src/chat/chat.gateway.ts

@@ -11,18 +11,17 @@ import {
 } from '@nestjs/websockets';
 import { Server, Socket } from 'socket.io';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
+import type { Auth } from '@mosaic/auth';
 import { AgentService } from '../agent/agent.service.js';
+import { AUTH } from '../auth/auth.tokens.js';
 import { v4 as uuid } from 'uuid';
-
-interface ChatMessage {
-  conversationId?: string;
-  content: string;
-  provider?: string;
-  modelId?: string;
-}
+import { ChatSocketMessageDto } from './chat.dto.js';
+import { validateSocketSession } from './chat.gateway-auth.js';
 
 @WebSocketGateway({
-  cors: { origin: '*' },
+  cors: {
+    origin: process.env['GATEWAY_CORS_ORIGIN'] ?? 'http://localhost:3000',
+  },
   namespace: '/chat',
 })
 export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewayDisconnect {
@@ -35,13 +34,25 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     { conversationId: string; cleanup: () => void }
   >();
 
-  constructor(@Inject(AgentService) private readonly agentService: AgentService) {}
+  constructor(
+    @Inject(AgentService) private readonly agentService: AgentService,
+    @Inject(AUTH) private readonly auth: Auth,
+  ) {}
 
   afterInit(): void {
     this.logger.log('Chat WebSocket gateway initialized');
   }
 
-  handleConnection(client: Socket): void {
+  async handleConnection(client: Socket): Promise<void> {
+    const session = await validateSocketSession(client.handshake.headers, this.auth);
+    if (!session) {
+      this.logger.warn(`Rejected unauthenticated WebSocket client: ${client.id}`);
+      client.disconnect();
+      return;
+    }
+
+    client.data.user = session.user;
+    client.data.session = session.session;
     this.logger.log(`Client connected: ${client.id}`);
   }
 
@@ -58,7 +69,7 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
   @SubscribeMessage('message')
   async handleMessage(
     @ConnectedSocket() client: Socket,
-    @MessageBody() data: ChatMessage,
+    @MessageBody() data: ChatSocketMessageDto,
   ): Promise<void> {
     const conversationId = data.conversationId ?? uuid();
 

apps/gateway/src/conversations/conversations.controller.ts

@@ -16,7 +16,8 @@ import type { Brain } from '@mosaic/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
-import type {
+import { assertOwner } from '../auth/resource-ownership.js';
+import {
   CreateConversationDto,
   UpdateConversationDto,
   SendMessageDto,
@@ -33,10 +34,8 @@ export class ConversationsController {
   }
 
   @Get(':id')
-  async findOne(@Param('id') id: string) {
-    const conversation = await this.brain.conversations.findById(id);
-    if (!conversation) throw new NotFoundException('Conversation not found');
-    return conversation;
+  async findOne(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    return this.getOwnedConversation(id, user.id);
   }
 
   @Post()
@@ -49,7 +48,12 @@ export class ConversationsController {
   }
 
   @Patch(':id')
-  async update(@Param('id') id: string, @Body() dto: UpdateConversationDto) {
+  async update(
+    @Param('id') id: string,
+    @Body() dto: UpdateConversationDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    await this.getOwnedConversation(id, user.id);
     const conversation = await this.brain.conversations.update(id, dto);
     if (!conversation) throw new NotFoundException('Conversation not found');
     return conversation;
@@ -57,22 +61,25 @@ export class ConversationsController {
 
   @Delete(':id')
   @HttpCode(HttpStatus.NO_CONTENT)
-  async remove(@Param('id') id: string) {
+  async remove(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    await this.getOwnedConversation(id, user.id);
     const deleted = await this.brain.conversations.remove(id);
     if (!deleted) throw new NotFoundException('Conversation not found');
   }
 
   @Get(':id/messages')
-  async listMessages(@Param('id') id: string) {
-    const conversation = await this.brain.conversations.findById(id);
-    if (!conversation) throw new NotFoundException('Conversation not found');
+  async listMessages(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    await this.getOwnedConversation(id, user.id);
     return this.brain.conversations.findMessages(id);
   }
 
   @Post(':id/messages')
-  async addMessage(@Param('id') id: string, @Body() dto: SendMessageDto) {
-    const conversation = await this.brain.conversations.findById(id);
-    if (!conversation) throw new NotFoundException('Conversation not found');
+  async addMessage(
+    @Param('id') id: string,
+    @Body() dto: SendMessageDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    await this.getOwnedConversation(id, user.id);
     return this.brain.conversations.addMessage({
       conversationId: id,
       role: dto.role,
@@ -80,4 +87,11 @@ export class ConversationsController {
       metadata: dto.metadata,
     });
   }
+
+  private async getOwnedConversation(id: string, userId: string) {
+    const conversation = await this.brain.conversations.findById(id);
+    if (!conversation) throw new NotFoundException('Conversation not found');
+    assertOwner(conversation.userId, userId, 'Conversation');
+    return conversation;
+  }
 }

apps/gateway/src/conversations/conversations.dto.ts

@@ -1,15 +1,36 @@
-export interface CreateConversationDto {
+import { IsIn, IsObject, IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+
+export class CreateConversationDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   title?: string;
+
+  @IsOptional()
+  @IsUUID()
   projectId?: string;
 }
 
-export interface UpdateConversationDto {
+export class UpdateConversationDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   title?: string;
+
+  @IsOptional()
+  @IsUUID()
   projectId?: string | null;
 }
 
-export interface SendMessageDto {
-  role: 'user' | 'assistant' | 'system';
-  content: string;
+export class SendMessageDto {
+  @IsIn(['user', 'assistant', 'system'])
+  role!: 'user' | 'assistant' | 'system';
+
+  @IsString()
+  @MaxLength(10_000)
+  content!: string;
+
+  @IsOptional()
+  @IsObject()
   metadata?: Record<string, unknown>;
 }

apps/gateway/src/log/cron.service.ts

@@ -0,0 +1,44 @@
+import { Injectable, Logger, type OnModuleInit, type OnModuleDestroy } from '@nestjs/common';
+import cron from 'node-cron';
+import { SummarizationService } from './summarization.service.js';
+
+@Injectable()
+export class CronService implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(CronService.name);
+  private readonly tasks: cron.ScheduledTask[] = [];
+
+  constructor(private readonly summarization: SummarizationService) {}
+
+  onModuleInit(): void {
+    const summarizationSchedule = process.env['SUMMARIZATION_CRON'] ?? '0 */6 * * *'; // every 6 hours
+    const tierManagementSchedule = process.env['TIER_MANAGEMENT_CRON'] ?? '0 3 * * *'; // daily at 3am
+
+    this.tasks.push(
+      cron.schedule(summarizationSchedule, () => {
+        this.summarization.runSummarization().catch((err) => {
+          this.logger.error(`Scheduled summarization failed: ${err}`);
+        });
+      }),
+    );
+
+    this.tasks.push(
+      cron.schedule(tierManagementSchedule, () => {
+        this.summarization.runTierManagement().catch((err) => {
+          this.logger.error(`Scheduled tier management failed: ${err}`);
+        });
+      }),
+    );
+
+    this.logger.log(
+      `Cron scheduled: summarization="${summarizationSchedule}", tier="${tierManagementSchedule}"`,
+    );
+  }
+
+  onModuleDestroy(): void {
+    for (const task of this.tasks) {
+      task.stop();
+    }
+    this.tasks.length = 0;
+    this.logger.log('Cron tasks stopped');
+  }
+}

apps/gateway/src/log/log.controller.ts

@@ -0,0 +1,62 @@
+import { Body, Controller, Get, Inject, Param, Post, Query, UseGuards } from '@nestjs/common';
+import type { LogService } from '@mosaic/log';
+import { LOG_SERVICE } from './log.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import type { IngestLogDto, QueryLogsDto } from './log.dto.js';
+
+@Controller('api/logs')
+@UseGuards(AuthGuard)
+export class LogController {
+  constructor(@Inject(LOG_SERVICE) private readonly logService: LogService) {}
+
+  @Post()
+  async ingest(@Query('userId') userId: string, @Body() dto: IngestLogDto) {
+    return this.logService.logs.ingest({
+      sessionId: dto.sessionId,
+      userId,
+      level: dto.level,
+      category: dto.category,
+      content: dto.content,
+      metadata: dto.metadata,
+    });
+  }
+
+  @Post('batch')
+  async ingestBatch(@Query('userId') userId: string, @Body() dtos: IngestLogDto[]) {
+    const entries = dtos.map((dto) => ({
+      sessionId: dto.sessionId,
+      userId,
+      level: dto.level as 'debug' | 'info' | 'warn' | 'error' | undefined,
+      category: dto.category as
+        | 'decision'
+        | 'tool_use'
+        | 'learning'
+        | 'error'
+        | 'general'
+        | undefined,
+      content: dto.content,
+      metadata: dto.metadata,
+    }));
+    return this.logService.logs.ingestBatch(entries);
+  }
+
+  @Get()
+  async query(@Query('userId') userId: string, @Query() params: QueryLogsDto) {
+    return this.logService.logs.query({
+      userId,
+      sessionId: params.sessionId,
+      level: params.level,
+      category: params.category,
+      tier: params.tier,
+      since: params.since ? new Date(params.since) : undefined,
+      until: params.until ? new Date(params.until) : undefined,
+      limit: params.limit ? Number(params.limit) : undefined,
+      offset: params.offset ? Number(params.offset) : undefined,
+    });
+  }
+
+  @Get(':id')
+  async findOne(@Param('id') id: string) {
+    return this.logService.logs.findById(id);
+  }
+}

apps/gateway/src/log/log.dto.ts

@@ -0,0 +1,18 @@
+export interface IngestLogDto {
+  sessionId: string;
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  category?: 'decision' | 'tool_use' | 'learning' | 'error' | 'general';
+  content: string;
+  metadata?: Record<string, unknown>;
+}
+
+export interface QueryLogsDto {
+  sessionId?: string;
+  level?: 'debug' | 'info' | 'warn' | 'error';
+  category?: 'decision' | 'tool_use' | 'learning' | 'error' | 'general';
+  tier?: 'hot' | 'warm' | 'cold';
+  since?: string;
+  until?: string;
+  limit?: string;
+  offset?: string;
+}

apps/gateway/src/log/log.module.ts

@@ -0,0 +1,24 @@
+import { Global, Module } from '@nestjs/common';
+import { createLogService, type LogService } from '@mosaic/log';
+import type { Db } from '@mosaic/db';
+import { DB } from '../database/database.module.js';
+import { LOG_SERVICE } from './log.tokens.js';
+import { LogController } from './log.controller.js';
+import { SummarizationService } from './summarization.service.js';
+import { CronService } from './cron.service.js';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: LOG_SERVICE,
+      useFactory: (db: Db): LogService => createLogService(db),
+      inject: [DB],
+    },
+    SummarizationService,
+    CronService,
+  ],
+  controllers: [LogController],
+  exports: [LOG_SERVICE, SummarizationService],
+})
+export class LogModule {}

apps/gateway/src/log/log.tokens.ts

@@ -0,0 +1 @@
+export const LOG_SERVICE = 'LOG_SERVICE';

apps/gateway/src/log/summarization.service.ts

@@ -0,0 +1,178 @@
+import { Inject, Injectable, Logger } from '@nestjs/common';
+import type { LogService } from '@mosaic/log';
+import type { Memory } from '@mosaic/memory';
+import { LOG_SERVICE } from './log.tokens.js';
+import { MEMORY } from '../memory/memory.tokens.js';
+import { EmbeddingService } from '../memory/embedding.service.js';
+import type { Db } from '@mosaic/db';
+import { sql, summarizationJobs } from '@mosaic/db';
+import { DB } from '../database/database.module.js';
+
+const SUMMARIZATION_PROMPT = `You are a knowledge extraction assistant. Given the following agent interaction logs, extract the key decisions, learnings, and patterns. Output a concise summary (2-4 sentences) that captures the most important information for future reference. Focus on actionable insights, not raw events.
+
+Logs:
+{logs}
+
+Summary:`;
+
+interface ChatCompletion {
+  choices: Array<{ message: { content: string } }>;
+}
+
+@Injectable()
+export class SummarizationService {
+  private readonly logger = new Logger(SummarizationService.name);
+  private readonly apiKey: string | undefined;
+  private readonly baseUrl: string;
+  private readonly model: string;
+
+  constructor(
+    @Inject(LOG_SERVICE) private readonly logService: LogService,
+    @Inject(MEMORY) private readonly memory: Memory,
+    private readonly embeddings: EmbeddingService,
+    @Inject(DB) private readonly db: Db,
+  ) {
+    this.apiKey = process.env['OPENAI_API_KEY'];
+    this.baseUrl = process.env['SUMMARIZATION_API_URL'] ?? 'https://api.openai.com/v1';
+    this.model = process.env['SUMMARIZATION_MODEL'] ?? 'gpt-4o-mini';
+  }
+
+  /**
+   * Run one summarization cycle:
+   * 1. Find hot logs older than 24h with decision/learning/tool_use categories
+   * 2. Group by session
+   * 3. Summarize each group via cheap LLM
+   * 4. Store as insights with embeddings
+   * 5. Transition processed logs to warm tier
+   */
+  async runSummarization(): Promise<{ logsProcessed: number; insightsCreated: number }> {
+    const cutoff = new Date(Date.now() - 24 * 60 * 60 * 1000); // 24h ago
+
+    // Create job record
+    const [job] = await this.db
+      .insert(summarizationJobs)
+      .values({ status: 'running', startedAt: new Date() })
+      .returning();
+
+    try {
+      const logs = await this.logService.logs.getLogsForSummarization(cutoff, 200);
+      if (logs.length === 0) {
+        await this.db
+          .update(summarizationJobs)
+          .set({ status: 'completed', completedAt: new Date() })
+          .where(sql`id = ${job!.id}`);
+        return { logsProcessed: 0, insightsCreated: 0 };
+      }
+
+      // Group logs by session
+      const bySession = new Map<string, typeof logs>();
+      for (const log of logs) {
+        const group = bySession.get(log.sessionId) ?? [];
+        group.push(log);
+        bySession.set(log.sessionId, group);
+      }
+
+      let insightsCreated = 0;
+
+      for (const [sessionId, sessionLogs] of bySession) {
+        const userId = sessionLogs[0]?.userId;
+        if (!userId) continue;
+
+        const logsText = sessionLogs.map((l) => `[${l.category}] ${l.content}`).join('\n');
+
+        const summary = await this.summarize(logsText);
+        if (!summary) continue;
+
+        const embedding = this.embeddings.available
+          ? await this.embeddings.embed(summary)
+          : undefined;
+
+        await this.memory.insights.create({
+          userId,
+          content: summary,
+          embedding: embedding ?? null,
+          source: 'summarization',
+          category: 'learning',
+          metadata: { sessionId, logCount: sessionLogs.length },
+        });
+        insightsCreated++;
+      }
+
+      // Transition processed logs to warm
+      await this.logService.logs.promoteToWarm(cutoff);
+
+      await this.db
+        .update(summarizationJobs)
+        .set({
+          status: 'completed',
+          logsProcessed: logs.length,
+          insightsCreated,
+          completedAt: new Date(),
+        })
+        .where(sql`id = ${job!.id}`);
+
+      this.logger.log(`Summarization complete: ${logs.length} logs → ${insightsCreated} insights`);
+      return { logsProcessed: logs.length, insightsCreated };
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      await this.db
+        .update(summarizationJobs)
+        .set({ status: 'failed', errorMessage: message, completedAt: new Date() })
+        .where(sql`id = ${job!.id}`);
+      this.logger.error(`Summarization failed: ${message}`);
+      throw error;
+    }
+  }
+
+  /**
+   * Run tier management:
+   * - Warm logs older than 30 days → cold
+   * - Cold logs older than 90 days → purged
+   * - Decay old insight relevance scores
+   */
+  async runTierManagement(): Promise<void> {
+    const warmCutoff = new Date(Date.now() - 30 * 24 * 60 * 60 * 1000);
+    const coldCutoff = new Date(Date.now() - 90 * 24 * 60 * 60 * 1000);
+    const decayCutoff = new Date(Date.now() - 14 * 24 * 60 * 60 * 1000);
+
+    const promoted = await this.logService.logs.promoteToCold(warmCutoff);
+    const purged = await this.logService.logs.purge(coldCutoff);
+    const decayed = await this.memory.insights.decayOldInsights(decayCutoff);
+
+    this.logger.log(
+      `Tier management: ${promoted} logs→cold, ${purged} purged, ${decayed} insights decayed`,
+    );
+  }
+
+  private async summarize(logsText: string): Promise<string | null> {
+    if (!this.apiKey) {
+      this.logger.warn('No API key configured — skipping summarization');
+      return null;
+    }
+
+    const prompt = SUMMARIZATION_PROMPT.replace('{logs}', logsText);
+
+    const response = await fetch(`${this.baseUrl}/chat/completions`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        messages: [{ role: 'user', content: prompt }],
+        max_tokens: 300,
+        temperature: 0.3,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`Summarization API error: ${response.status} ${body}`);
+      return null;
+    }
+
+    const json = (await response.json()) as ChatCompletion;
+    return json.choices[0]?.message.content ?? null;
+  }
+}

apps/gateway/src/main.ts

@@ -1,19 +1,45 @@
 import './tracing.js';
 import 'reflect-metadata';
 import { NestFactory } from '@nestjs/core';
-import { Logger } from '@nestjs/common';
+import { Logger, ValidationPipe } from '@nestjs/common';
 import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
+import helmet from '@fastify/helmet';
 import { AppModule } from './app.module.js';
 import { mountAuthHandler } from './auth/auth.controller.js';
 
 async function bootstrap(): Promise<void> {
+  if (!process.env['BETTER_AUTH_SECRET']) {
+    throw new Error('BETTER_AUTH_SECRET is required');
+  }
+
+  if (
+    process.env['AUTHENTIK_CLIENT_ID'] &&
+    (!process.env['AUTHENTIK_CLIENT_SECRET'] || !process.env['AUTHENTIK_ISSUER'])
+  ) {
+    console.warn(
+      '[warn] AUTHENTIK_CLIENT_ID is set but AUTHENTIK_CLIENT_SECRET or AUTHENTIK_ISSUER is missing — Authentik SSO will not work',
+    );
+  }
+
   const logger = new Logger('Bootstrap');
-  const app = await NestFactory.create<NestFastifyApplication>(AppModule, new FastifyAdapter());
+  const app = await NestFactory.create<NestFastifyApplication>(
+    AppModule,
+    new FastifyAdapter({ bodyLimit: 1_048_576 }),
+  );
+
+  await app.register(helmet as never, { contentSecurityPolicy: false });
+  app.useGlobalPipes(
+    new ValidationPipe({
+      whitelist: true,
+      forbidNonWhitelisted: true,
+      transform: true,
+    }),
+  );
 
   mountAuthHandler(app);
 
-  const port = process.env['GATEWAY_PORT'] ?? 4000;
-  await app.listen(port as number, '0.0.0.0');
+  const port = Number(process.env['GATEWAY_PORT'] ?? 4000);
+  await app.listen(port, '0.0.0.0');
   logger.log(`Gateway listening on port ${port}`);
 }
 

apps/gateway/src/memory/embedding.service.ts

@@ -0,0 +1,69 @@
+import { Injectable, Logger } from '@nestjs/common';
+import type { EmbeddingProvider } from '@mosaic/memory';
+
+const DEFAULT_MODEL = 'text-embedding-3-small';
+const DEFAULT_DIMENSIONS = 1536;
+
+interface EmbeddingResponse {
+  data: Array<{ embedding: number[]; index: number }>;
+  model: string;
+  usage: { prompt_tokens: number; total_tokens: number };
+}
+
+/**
+ * Generates embeddings via the OpenAI-compatible embeddings API.
+ * Supports OpenAI, Azure OpenAI, and any provider with a compatible endpoint.
+ */
+@Injectable()
+export class EmbeddingService implements EmbeddingProvider {
+  private readonly logger = new Logger(EmbeddingService.name);
+  private readonly apiKey: string | undefined;
+  private readonly baseUrl: string;
+  private readonly model: string;
+
+  readonly dimensions = DEFAULT_DIMENSIONS;
+
+  constructor() {
+    this.apiKey = process.env['OPENAI_API_KEY'];
+    this.baseUrl = process.env['EMBEDDING_API_URL'] ?? 'https://api.openai.com/v1';
+    this.model = process.env['EMBEDDING_MODEL'] ?? DEFAULT_MODEL;
+  }
+
+  get available(): boolean {
+    return !!this.apiKey;
+  }
+
+  async embed(text: string): Promise<number[]> {
+    const results = await this.embedBatch([text]);
+    return results[0]!;
+  }
+
+  async embedBatch(texts: string[]): Promise<number[][]> {
+    if (!this.apiKey) {
+      this.logger.warn('No OPENAI_API_KEY configured — returning zero vectors');
+      return texts.map(() => new Array<number>(this.dimensions).fill(0));
+    }
+
+    const response = await fetch(`${this.baseUrl}/embeddings`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Authorization: `Bearer ${this.apiKey}`,
+      },
+      body: JSON.stringify({
+        model: this.model,
+        input: texts,
+        dimensions: this.dimensions,
+      }),
+    });
+
+    if (!response.ok) {
+      const body = await response.text();
+      this.logger.error(`Embedding API error: ${response.status} ${body}`);
+      throw new Error(`Embedding API returned ${response.status}`);
+    }
+
+    const json = (await response.json()) as EmbeddingResponse;
+    return json.data.sort((a, b) => a.index - b.index).map((d) => d.embedding);
+  }
+}

apps/gateway/src/memory/memory.controller.ts

@@ -0,0 +1,126 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  NotFoundException,
+  Param,
+  Post,
+  Query,
+  UseGuards,
+} from '@nestjs/common';
+import type { Memory } from '@mosaic/memory';
+import { MEMORY } from './memory.tokens.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import { EmbeddingService } from './embedding.service.js';
+import type { UpsertPreferenceDto, CreateInsightDto, SearchMemoryDto } from './memory.dto.js';
+
+@Controller('api/memory')
+@UseGuards(AuthGuard)
+export class MemoryController {
+  constructor(
+    @Inject(MEMORY) private readonly memory: Memory,
+    private readonly embeddings: EmbeddingService,
+  ) {}
+
+  // ─── Preferences ────────────────────────────────────────────────────
+
+  @Get('preferences')
+  async listPreferences(@Query('userId') userId: string, @Query('category') category?: string) {
+    if (category) {
+      return this.memory.preferences.findByUserAndCategory(
+        userId,
+        category as Parameters<typeof this.memory.preferences.findByUserAndCategory>[1],
+      );
+    }
+    return this.memory.preferences.findByUser(userId);
+  }
+
+  @Get('preferences/:key')
+  async getPreference(@Query('userId') userId: string, @Param('key') key: string) {
+    const pref = await this.memory.preferences.findByUserAndKey(userId, key);
+    if (!pref) throw new NotFoundException('Preference not found');
+    return pref;
+  }
+
+  @Post('preferences')
+  async upsertPreference(@Query('userId') userId: string, @Body() dto: UpsertPreferenceDto) {
+    return this.memory.preferences.upsert({
+      userId,
+      key: dto.key,
+      value: dto.value,
+      category: dto.category,
+      source: dto.source,
+    });
+  }
+
+  @Delete('preferences/:key')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async removePreference(@Query('userId') userId: string, @Param('key') key: string) {
+    const deleted = await this.memory.preferences.remove(userId, key);
+    if (!deleted) throw new NotFoundException('Preference not found');
+  }
+
+  // ─── Insights ───────────────────────────────────────────────────────
+
+  @Get('insights')
+  async listInsights(@Query('userId') userId: string, @Query('limit') limit?: string) {
+    return this.memory.insights.findByUser(userId, limit ? Number(limit) : undefined);
+  }
+
+  @Get('insights/:id')
+  async getInsight(@Param('id') id: string) {
+    const insight = await this.memory.insights.findById(id);
+    if (!insight) throw new NotFoundException('Insight not found');
+    return insight;
+  }
+
+  @Post('insights')
+  async createInsight(@Query('userId') userId: string, @Body() dto: CreateInsightDto) {
+    const embedding = this.embeddings.available
+      ? await this.embeddings.embed(dto.content)
+      : undefined;
+
+    return this.memory.insights.create({
+      userId,
+      content: dto.content,
+      source: dto.source,
+      category: dto.category,
+      metadata: dto.metadata,
+      embedding: embedding ?? null,
+    });
+  }
+
+  @Delete('insights/:id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async removeInsight(@Param('id') id: string) {
+    const deleted = await this.memory.insights.remove(id);
+    if (!deleted) throw new NotFoundException('Insight not found');
+  }
+
+  // ─── Search ─────────────────────────────────────────────────────────
+
+  @Post('search')
+  async searchMemory(@Query('userId') userId: string, @Body() dto: SearchMemoryDto) {
+    if (!this.embeddings.available) {
+      return {
+        query: dto.query,
+        results: [],
+        message: 'Semantic search requires OPENAI_API_KEY for embeddings',
+      };
+    }
+
+    const queryEmbedding = await this.embeddings.embed(dto.query);
+    const results = await this.memory.insights.searchByEmbedding(
+      userId,
+      queryEmbedding,
+      dto.limit ?? 10,
+      dto.maxDistance ?? 0.8,
+    );
+
+    return { query: dto.query, results };
+  }
+}

apps/gateway/src/memory/memory.dto.ts

@@ -0,0 +1,19 @@
+export interface UpsertPreferenceDto {
+  key: string;
+  value: unknown;
+  category?: 'communication' | 'coding' | 'workflow' | 'appearance' | 'general';
+  source?: string;
+}
+
+export interface CreateInsightDto {
+  content: string;
+  source?: 'agent' | 'user' | 'summarization' | 'system';
+  category?: 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
+  metadata?: Record<string, unknown>;
+}
+
+export interface SearchMemoryDto {
+  query: string;
+  limit?: number;
+  maxDistance?: number;
+}

apps/gateway/src/memory/memory.module.ts

@@ -0,0 +1,22 @@
+import { Global, Module } from '@nestjs/common';
+import { createMemory, type Memory } from '@mosaic/memory';
+import type { Db } from '@mosaic/db';
+import { DB } from '../database/database.module.js';
+import { MEMORY } from './memory.tokens.js';
+import { MemoryController } from './memory.controller.js';
+import { EmbeddingService } from './embedding.service.js';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: MEMORY,
+      useFactory: (db: Db): Memory => createMemory(db),
+      inject: [DB],
+    },
+    EmbeddingService,
+  ],
+  controllers: [MemoryController],
+  exports: [MEMORY, EmbeddingService],
+})
+export class MemoryModule {}

apps/gateway/src/memory/memory.tokens.ts

@@ -0,0 +1 @@
+export const MEMORY = 'MEMORY';

apps/gateway/src/missions/missions.controller.ts

@@ -2,6 +2,7 @@ import {
   Body,
   Controller,
   Delete,
+  ForbiddenException,
   Get,
   HttpCode,
   HttpStatus,
@@ -15,7 +16,9 @@ import {
 import type { Brain } from '@mosaic/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
-import type { CreateMissionDto, UpdateMissionDto } from './missions.dto.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { assertOwner } from '../auth/resource-ownership.js';
+import { CreateMissionDto, UpdateMissionDto } from './missions.dto.js';
 
 @Controller('api/missions')
 @UseGuards(AuthGuard)
@@ -28,14 +31,15 @@ export class MissionsController {
   }
 
   @Get(':id')
-  async findOne(@Param('id') id: string) {
-    const mission = await this.brain.missions.findById(id);
-    if (!mission) throw new NotFoundException('Mission not found');
-    return mission;
+  async findOne(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    return this.getOwnedMission(id, user.id);
   }
 
   @Post()
-  async create(@Body() dto: CreateMissionDto) {
+  async create(@Body() dto: CreateMissionDto, @CurrentUser() user: { id: string }) {
+    if (dto.projectId) {
+      await this.getOwnedProject(dto.projectId, user.id, 'Mission');
+    }
     return this.brain.missions.create({
       name: dto.name,
       description: dto.description,
@@ -45,7 +49,15 @@ export class MissionsController {
   }
 
   @Patch(':id')
-  async update(@Param('id') id: string, @Body() dto: UpdateMissionDto) {
+  async update(
+    @Param('id') id: string,
+    @Body() dto: UpdateMissionDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    await this.getOwnedMission(id, user.id);
+    if (dto.projectId) {
+      await this.getOwnedProject(dto.projectId, user.id, 'Mission');
+    }
     const mission = await this.brain.missions.update(id, dto);
     if (!mission) throw new NotFoundException('Mission not found');
     return mission;
@@ -53,8 +65,34 @@ export class MissionsController {
 
   @Delete(':id')
   @HttpCode(HttpStatus.NO_CONTENT)
-  async remove(@Param('id') id: string) {
+  async remove(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    await this.getOwnedMission(id, user.id);
     const deleted = await this.brain.missions.remove(id);
     if (!deleted) throw new NotFoundException('Mission not found');
   }
+
+  private async getOwnedMission(id: string, userId: string) {
+    const mission = await this.brain.missions.findById(id);
+    if (!mission) throw new NotFoundException('Mission not found');
+    await this.getOwnedProject(mission.projectId, userId, 'Mission');
+    return mission;
+  }
+
+  private async getOwnedProject(
+    projectId: string | null | undefined,
+    userId: string,
+    resourceName: string,
+  ) {
+    if (!projectId) {
+      throw new ForbiddenException(`${resourceName} does not belong to the current user`);
+    }
+
+    const project = await this.brain.projects.findById(projectId);
+    if (!project) {
+      throw new ForbiddenException(`${resourceName} does not belong to the current user`);
+    }
+
+    assertOwner(project.ownerId, userId, resourceName);
+    return project;
+  }
 }

apps/gateway/src/missions/missions.dto.ts

@@ -1,14 +1,46 @@
-export interface CreateMissionDto {
-  name: string;
+import { IsIn, IsObject, IsOptional, IsString, IsUUID, MaxLength } from 'class-validator';
+
+const missionStatuses = ['planning', 'active', 'paused', 'completed', 'failed'] as const;
+
+export class CreateMissionDto {
+  @IsString()
+  @MaxLength(255)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
   description?: string;
+
+  @IsOptional()
+  @IsUUID()
   projectId?: string;
+
+  @IsOptional()
+  @IsIn(missionStatuses)
   status?: 'planning' | 'active' | 'paused' | 'completed' | 'failed';
 }
 
-export interface UpdateMissionDto {
+export class UpdateMissionDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   name?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
   description?: string | null;
+
+  @IsOptional()
+  @IsUUID()
   projectId?: string | null;
+
+  @IsOptional()
+  @IsIn(missionStatuses)
   status?: 'planning' | 'active' | 'paused' | 'completed' | 'failed';
+
+  @IsOptional()
+  @IsObject()
   metadata?: Record<string, unknown> | null;
 }

apps/gateway/src/plugin/plugin.interface.ts

@@ -0,0 +1,5 @@
+export interface IChannelPlugin {
+  readonly name: string;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}

apps/gateway/src/plugin/plugin.module.ts

@@ -0,0 +1,109 @@
+import {
+  Global,
+  Inject,
+  Logger,
+  Module,
+  type OnModuleDestroy,
+  type OnModuleInit,
+} from '@nestjs/common';
+import { DiscordPlugin } from '@mosaic/discord-plugin';
+import { TelegramPlugin } from '@mosaic/telegram-plugin';
+import { PluginService } from './plugin.service.js';
+import type { IChannelPlugin } from './plugin.interface.js';
+import { PLUGIN_REGISTRY } from './plugin.tokens.js';
+
+class DiscordChannelPluginAdapter implements IChannelPlugin {
+  readonly name = 'discord';
+
+  constructor(private readonly plugin: DiscordPlugin) {}
+
+  async start(): Promise<void> {
+    await this.plugin.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.plugin.stop();
+  }
+}
+
+class TelegramChannelPluginAdapter implements IChannelPlugin {
+  readonly name = 'telegram';
+
+  constructor(private readonly plugin: TelegramPlugin) {}
+
+  async start(): Promise<void> {
+    await this.plugin.start();
+  }
+
+  async stop(): Promise<void> {
+    await this.plugin.stop();
+  }
+}
+
+const DEFAULT_GATEWAY_URL = 'http://localhost:4000';
+
+function createPluginRegistry(): IChannelPlugin[] {
+  const plugins: IChannelPlugin[] = [];
+  const discordToken = process.env['DISCORD_BOT_TOKEN'];
+  const discordGuildId = process.env['DISCORD_GUILD_ID'];
+  const discordGatewayUrl = process.env['DISCORD_GATEWAY_URL'] ?? DEFAULT_GATEWAY_URL;
+
+  if (discordToken) {
+    plugins.push(
+      new DiscordChannelPluginAdapter(
+        new DiscordPlugin({
+          token: discordToken,
+          guildId: discordGuildId,
+          gatewayUrl: discordGatewayUrl,
+        }),
+      ),
+    );
+  }
+
+  const telegramToken = process.env['TELEGRAM_BOT_TOKEN'];
+  const telegramGatewayUrl = process.env['TELEGRAM_GATEWAY_URL'] ?? DEFAULT_GATEWAY_URL;
+
+  if (telegramToken) {
+    plugins.push(
+      new TelegramChannelPluginAdapter(
+        new TelegramPlugin({
+          token: telegramToken,
+          gatewayUrl: telegramGatewayUrl,
+        }),
+      ),
+    );
+  }
+
+  return plugins;
+}
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: PLUGIN_REGISTRY,
+      useFactory: (): IChannelPlugin[] => createPluginRegistry(),
+    },
+    PluginService,
+  ],
+  exports: [PluginService, PLUGIN_REGISTRY],
+})
+export class PluginModule implements OnModuleInit, OnModuleDestroy {
+  private readonly logger = new Logger(PluginModule.name);
+
+  constructor(@Inject(PLUGIN_REGISTRY) private readonly plugins: IChannelPlugin[]) {}
+
+  async onModuleInit(): Promise<void> {
+    for (const plugin of this.plugins) {
+      this.logger.log(`Starting plugin: ${plugin.name}`);
+      await plugin.start();
+    }
+  }
+
+  async onModuleDestroy(): Promise<void> {
+    for (const plugin of [...this.plugins].reverse()) {
+      this.logger.log(`Stopping plugin: ${plugin.name}`);
+      await plugin.stop();
+    }
+  }
+}

apps/gateway/src/plugin/plugin.service.ts

@@ -0,0 +1,16 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { PLUGIN_REGISTRY } from './plugin.tokens.js';
+import type { IChannelPlugin } from './plugin.interface.js';
+
+@Injectable()
+export class PluginService {
+  constructor(@Inject(PLUGIN_REGISTRY) private readonly plugins: IChannelPlugin[]) {}
+
+  getPlugins(): IChannelPlugin[] {
+    return this.plugins;
+  }
+
+  getPlugin(name: string): IChannelPlugin | undefined {
+    return this.plugins.find((plugin: IChannelPlugin) => plugin.name === name);
+  }
+}

apps/gateway/src/plugin/plugin.tokens.ts

@@ -0,0 +1 @@
+export const PLUGIN_REGISTRY = Symbol('PLUGIN_REGISTRY');

apps/gateway/src/projects/projects.controller.ts

@@ -16,7 +16,8 @@ import type { Brain } from '@mosaic/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
-import type { CreateProjectDto, UpdateProjectDto } from './projects.dto.js';
+import { assertOwner } from '../auth/resource-ownership.js';
+import { CreateProjectDto, UpdateProjectDto } from './projects.dto.js';
 
 @Controller('api/projects')
 @UseGuards(AuthGuard)
@@ -29,10 +30,8 @@ export class ProjectsController {
   }
 
   @Get(':id')
-  async findOne(@Param('id') id: string) {
-    const project = await this.brain.projects.findById(id);
-    if (!project) throw new NotFoundException('Project not found');
-    return project;
+  async findOne(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    return this.getOwnedProject(id, user.id);
   }
 
   @Post()
@@ -46,7 +45,12 @@ export class ProjectsController {
   }
 
   @Patch(':id')
-  async update(@Param('id') id: string, @Body() dto: UpdateProjectDto) {
+  async update(
+    @Param('id') id: string,
+    @Body() dto: UpdateProjectDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    await this.getOwnedProject(id, user.id);
     const project = await this.brain.projects.update(id, dto);
     if (!project) throw new NotFoundException('Project not found');
     return project;
@@ -54,8 +58,16 @@ export class ProjectsController {
 
   @Delete(':id')
   @HttpCode(HttpStatus.NO_CONTENT)
-  async remove(@Param('id') id: string) {
+  async remove(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    await this.getOwnedProject(id, user.id);
     const deleted = await this.brain.projects.remove(id);
     if (!deleted) throw new NotFoundException('Project not found');
   }
+
+  private async getOwnedProject(id: string, userId: string) {
+    const project = await this.brain.projects.findById(id);
+    if (!project) throw new NotFoundException('Project not found');
+    assertOwner(project.ownerId, userId, 'Project');
+    return project;
+  }
 }

apps/gateway/src/projects/projects.dto.ts

@@ -1,12 +1,38 @@
-export interface CreateProjectDto {
-  name: string;
+import { IsIn, IsObject, IsOptional, IsString, MaxLength } from 'class-validator';
+
+const projectStatuses = ['active', 'paused', 'completed', 'archived'] as const;
+
+export class CreateProjectDto {
+  @IsString()
+  @MaxLength(255)
+  name!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
   description?: string;
+
+  @IsOptional()
+  @IsIn(projectStatuses)
   status?: 'active' | 'paused' | 'completed' | 'archived';
 }
 
-export interface UpdateProjectDto {
+export class UpdateProjectDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   name?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
   description?: string | null;
+
+  @IsOptional()
+  @IsIn(projectStatuses)
   status?: 'active' | 'paused' | 'completed' | 'archived';
+
+  @IsOptional()
+  @IsObject()
   metadata?: Record<string, unknown> | null;
 }

apps/gateway/src/skills/skills.controller.ts

@@ -0,0 +1,67 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  NotFoundException,
+  Param,
+  Patch,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { SkillsService } from './skills.service.js';
+import { AuthGuard } from '../auth/auth.guard.js';
+import type { CreateSkillDto, UpdateSkillDto } from './skills.dto.js';
+
+@Controller('api/skills')
+@UseGuards(AuthGuard)
+export class SkillsController {
+  constructor(private readonly skills: SkillsService) {}
+
+  @Get()
+  async list() {
+    return this.skills.findAll();
+  }
+
+  @Get(':id')
+  async findOne(@Param('id') id: string) {
+    const skill = await this.skills.findById(id);
+    if (!skill) throw new NotFoundException('Skill not found');
+    return skill;
+  }
+
+  @Post()
+  async create(@Body() dto: CreateSkillDto) {
+    return this.skills.create({
+      name: dto.name,
+      description: dto.description,
+      version: dto.version,
+      source: dto.source,
+      config: dto.config,
+      enabled: dto.enabled,
+    });
+  }
+
+  @Patch(':id')
+  async update(@Param('id') id: string, @Body() dto: UpdateSkillDto) {
+    const skill = await this.skills.update(id, dto);
+    if (!skill) throw new NotFoundException('Skill not found');
+    return skill;
+  }
+
+  @Patch(':id/toggle')
+  async toggle(@Param('id') id: string, @Body() body: { enabled: boolean }) {
+    const skill = await this.skills.toggle(id, body.enabled);
+    if (!skill) throw new NotFoundException('Skill not found');
+    return skill;
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async remove(@Param('id') id: string) {
+    const deleted = await this.skills.remove(id);
+    if (!deleted) throw new NotFoundException('Skill not found');
+  }
+}

apps/gateway/src/skills/skills.dto.ts

@@ -0,0 +1,15 @@
+export interface CreateSkillDto {
+  name: string;
+  description?: string;
+  version?: string;
+  source?: 'builtin' | 'community' | 'custom';
+  config?: Record<string, unknown>;
+  enabled?: boolean;
+}
+
+export interface UpdateSkillDto {
+  description?: string;
+  version?: string;
+  config?: Record<string, unknown>;
+  enabled?: boolean;
+}

apps/gateway/src/skills/skills.module.ts

@@ -0,0 +1,10 @@
+import { Module } from '@nestjs/common';
+import { SkillsService } from './skills.service.js';
+import { SkillsController } from './skills.controller.js';
+
+@Module({
+  providers: [SkillsService],
+  controllers: [SkillsController],
+  exports: [SkillsService],
+})
+export class SkillsModule {}

apps/gateway/src/skills/skills.service.ts

@@ -0,0 +1,52 @@
+import { Inject, Injectable } from '@nestjs/common';
+import { eq, type Db, skills } from '@mosaic/db';
+import { DB } from '../database/database.module.js';
+
+type Skill = typeof skills.$inferSelect;
+type NewSkill = typeof skills.$inferInsert;
+
+@Injectable()
+export class SkillsService {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  async findAll(): Promise<Skill[]> {
+    return this.db.select().from(skills);
+  }
+
+  async findEnabled(): Promise<Skill[]> {
+    return this.db.select().from(skills).where(eq(skills.enabled, true));
+  }
+
+  async findById(id: string): Promise<Skill | undefined> {
+    const rows = await this.db.select().from(skills).where(eq(skills.id, id));
+    return rows[0];
+  }
+
+  async findByName(name: string): Promise<Skill | undefined> {
+    const rows = await this.db.select().from(skills).where(eq(skills.name, name));
+    return rows[0];
+  }
+
+  async create(data: NewSkill): Promise<Skill> {
+    const rows = await this.db.insert(skills).values(data).returning();
+    return rows[0]!;
+  }
+
+  async update(id: string, data: Partial<NewSkill>): Promise<Skill | undefined> {
+    const rows = await this.db
+      .update(skills)
+      .set({ ...data, updatedAt: new Date() })
+      .where(eq(skills.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async remove(id: string): Promise<boolean> {
+    const rows = await this.db.delete(skills).where(eq(skills.id, id)).returning();
+    return rows.length > 0;
+  }
+
+  async toggle(id: string, enabled: boolean): Promise<Skill | undefined> {
+    return this.update(id, { enabled });
+  }
+}

apps/gateway/src/tasks/tasks.controller.ts

@@ -2,6 +2,7 @@ import {
   Body,
   Controller,
   Delete,
+  ForbiddenException,
   Get,
   HttpCode,
   HttpStatus,
@@ -16,7 +17,9 @@ import {
 import type { Brain } from '@mosaic/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
-import type { CreateTaskDto, UpdateTaskDto } from './tasks.dto.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import { assertOwner } from '../auth/resource-ownership.js';
+import { CreateTaskDto, UpdateTaskDto } from './tasks.dto.js';
 
 @Controller('api/tasks')
 @UseGuards(AuthGuard)
@@ -25,28 +28,63 @@ export class TasksController {
 
   @Get()
   async list(
+    @CurrentUser() user: { id: string },
     @Query('projectId') projectId?: string,
     @Query('missionId') missionId?: string,
     @Query('status') status?: string,
   ) {
-    if (projectId) return this.brain.tasks.findByProject(projectId);
-    if (missionId) return this.brain.tasks.findByMission(missionId);
-    if (status)
-      return this.brain.tasks.findByStatus(
-        status as Parameters<typeof this.brain.tasks.findByStatus>[0],
-      );
-    return this.brain.tasks.findAll();
+    if (projectId) {
+      await this.getOwnedProject(projectId, user.id, 'Task');
+      return this.brain.tasks.findByProject(projectId);
+    }
+    if (missionId) {
+      await this.getOwnedMission(missionId, user.id, 'Task');
+      return this.brain.tasks.findByMission(missionId);
+    }
+
+    const [projects, missions, tasks] = await Promise.all([
+      this.brain.projects.findAll(),
+      this.brain.missions.findAll(),
+      status
+        ? this.brain.tasks.findByStatus(
+            status as Parameters<typeof this.brain.tasks.findByStatus>[0],
+          )
+        : this.brain.tasks.findAll(),
+    ]);
+
+    const ownedProjectIds = new Set(
+      projects.filter((project) => project.ownerId === user.id).map((project) => project.id),
+    );
+    const ownedMissionIds = new Set(
+      missions
+        .filter(
+          (ownedMission) =>
+            typeof ownedMission.projectId === 'string' &&
+            ownedProjectIds.has(ownedMission.projectId),
+        )
+        .map((ownedMission) => ownedMission.id),
+    );
+
+    return tasks.filter(
+      (task) =>
+        (task.projectId ? ownedProjectIds.has(task.projectId) : false) ||
+        (task.missionId ? ownedMissionIds.has(task.missionId) : false),
+    );
   }
 
   @Get(':id')
-  async findOne(@Param('id') id: string) {
-    const task = await this.brain.tasks.findById(id);
-    if (!task) throw new NotFoundException('Task not found');
-    return task;
+  async findOne(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    return this.getOwnedTask(id, user.id);
   }
 
   @Post()
-  async create(@Body() dto: CreateTaskDto) {
+  async create(@Body() dto: CreateTaskDto, @CurrentUser() user: { id: string }) {
+    if (dto.projectId) {
+      await this.getOwnedProject(dto.projectId, user.id, 'Task');
+    }
+    if (dto.missionId) {
+      await this.getOwnedMission(dto.missionId, user.id, 'Task');
+    }
     return this.brain.tasks.create({
       title: dto.title,
       description: dto.description,
@@ -61,7 +99,18 @@ export class TasksController {
   }
 
   @Patch(':id')
-  async update(@Param('id') id: string, @Body() dto: UpdateTaskDto) {
+  async update(
+    @Param('id') id: string,
+    @Body() dto: UpdateTaskDto,
+    @CurrentUser() user: { id: string },
+  ) {
+    await this.getOwnedTask(id, user.id);
+    if (dto.projectId) {
+      await this.getOwnedProject(dto.projectId, user.id, 'Task');
+    }
+    if (dto.missionId) {
+      await this.getOwnedMission(dto.missionId, user.id, 'Task');
+    }
     const task = await this.brain.tasks.update(id, {
       ...dto,
       dueDate: dto.dueDate ? new Date(dto.dueDate) : dto.dueDate === null ? null : undefined,
@@ -72,8 +121,46 @@ export class TasksController {
 
   @Delete(':id')
   @HttpCode(HttpStatus.NO_CONTENT)
-  async remove(@Param('id') id: string) {
+  async remove(@Param('id') id: string, @CurrentUser() user: { id: string }) {
+    await this.getOwnedTask(id, user.id);
     const deleted = await this.brain.tasks.remove(id);
     if (!deleted) throw new NotFoundException('Task not found');
   }
+
+  private async getOwnedTask(id: string, userId: string) {
+    const task = await this.brain.tasks.findById(id);
+    if (!task) throw new NotFoundException('Task not found');
+
+    if (task.projectId) {
+      await this.getOwnedProject(task.projectId, userId, 'Task');
+      return task;
+    }
+
+    if (task.missionId) {
+      await this.getOwnedMission(task.missionId, userId, 'Task');
+      return task;
+    }
+
+    throw new ForbiddenException('Task does not belong to the current user');
+  }
+
+  private async getOwnedMission(missionId: string, userId: string, resourceName: string) {
+    const mission = await this.brain.missions.findById(missionId);
+    if (!mission?.projectId) {
+      throw new ForbiddenException(`${resourceName} does not belong to the current user`);
+    }
+
+    await this.getOwnedProject(mission.projectId, userId, resourceName);
+    return mission;
+  }
+
+  private async getOwnedProject(projectId: string, userId: string, resourceName: string) {
+    const project = await this.brain.projects.findById(projectId);
+    if (!project) {
+      throw new ForbiddenException(`${resourceName} does not belong to the current user`);
+    }
+
+    assertOwner(project.ownerId, userId, resourceName);
+    return project;
+  }
 }

apps/gateway/src/tasks/tasks.dto.ts

@@ -1,24 +1,103 @@
-export interface CreateTaskDto {
-  title: string;
+import {
+  ArrayMaxSize,
+  IsArray,
+  IsIn,
+  IsISO8601,
+  IsObject,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+} from 'class-validator';
+
+const taskStatuses = ['not-started', 'in-progress', 'blocked', 'done', 'cancelled'] as const;
+const taskPriorities = ['critical', 'high', 'medium', 'low'] as const;
+
+export class CreateTaskDto {
+  @IsString()
+  @MaxLength(255)
+  title!: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
   description?: string;
+
+  @IsOptional()
+  @IsIn(taskStatuses)
   status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
+
+  @IsOptional()
+  @IsIn(taskPriorities)
   priority?: 'critical' | 'high' | 'medium' | 'low';
+
+  @IsOptional()
+  @IsUUID()
   projectId?: string;
+
+  @IsOptional()
+  @IsUUID()
   missionId?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   assignee?: string;
+
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(50)
+  @IsString({ each: true })
   tags?: string[];
+
+  @IsOptional()
+  @IsISO8601()
   dueDate?: string;
 }
 
-export interface UpdateTaskDto {
+export class UpdateTaskDto {
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   title?: string;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(10_000)
   description?: string | null;
+
+  @IsOptional()
+  @IsIn(taskStatuses)
   status?: 'not-started' | 'in-progress' | 'blocked' | 'done' | 'cancelled';
+
+  @IsOptional()
+  @IsIn(taskPriorities)
   priority?: 'critical' | 'high' | 'medium' | 'low';
+
+  @IsOptional()
+  @IsUUID()
   projectId?: string | null;
+
+  @IsOptional()
+  @IsUUID()
   missionId?: string | null;
+
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
   assignee?: string | null;
+
+  @IsOptional()
+  @IsArray()
+  @ArrayMaxSize(50)
+  @IsString({ each: true })
   tags?: string[] | null;
+
+  @IsOptional()
+  @IsISO8601()
   dueDate?: string | null;
+
+  @IsOptional()
+  @IsObject()
   metadata?: Record<string, unknown> | null;
 }

apps/gateway/tsconfig.typecheck.json

@@ -0,0 +1,18 @@
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "rootDir": "../..",
+    "baseUrl": ".",
+    "paths": {
+      "@mosaic/auth": ["../../packages/auth/src/index.ts"],
+      "@mosaic/brain": ["../../packages/brain/src/index.ts"],
+      "@mosaic/coord": ["../../packages/coord/src/index.ts"],
+      "@mosaic/db": ["../../packages/db/src/index.ts"],
+      "@mosaic/log": ["../../packages/log/src/index.ts"],
+      "@mosaic/memory": ["../../packages/memory/src/index.ts"],
+      "@mosaic/types": ["../../packages/types/src/index.ts"],
+      "@mosaic/discord-plugin": ["../../plugins/discord/src/index.ts"],
+      "@mosaic/telegram-plugin": ["../../plugins/telegram/src/index.ts"]
+    }
+  }
+}

docs/MISSION-MANIFEST.md

@@ -8,10 +8,10 @@
 **ID:** mvp-20260312
 **Statement:** Build Mosaic Stack v0.1.0 — a self-hosted, multi-user AI agent platform with web dashboard, TUI, remote control, shared memory, mission orchestration, and extensible skill/plugin architecture. All TypeScript. Pi as agent harness. Brain as knowledge layer. Queue as coordination backbone.
 **Phase:** Execution
-**Current Milestone:** Phase 4: Memory & Intelligence (v0.0.5)
-**Progress:** 4 / 8 milestones
+**Current Milestone:** Phase 7: Polish & Beta (v0.1.0)
+**Progress:** 7 / 8 milestones
 **Status:** active
-**Last Updated:** 2026-03-13 UTC
+**Last Updated:** 2026-03-14 UTC
 
 ## Success Criteria
 
@@ -35,9 +35,9 @@
 | 1   | ms-158 | Phase 1: Core API (v0.0.2)              | done        | —      | —     | 2026-03-13 | 2026-03-13 |
 | 2   | ms-159 | Phase 2: Agent Layer (v0.0.3)           | done        | —      | —     | 2026-03-13 | 2026-03-12 |
 | 3   | ms-160 | Phase 3: Web Dashboard (v0.0.4)         | done        | —      | —     | 2026-03-12 | 2026-03-13 |
-| 4   | ms-161 | Phase 4: Memory & Intelligence (v0.0.5) | not-started | —      | —     | —          | —          |
-| 5   | ms-162 | Phase 5: Remote Control (v0.0.6)        | not-started | —      | —     | —          | —          |
-| 6   | ms-163 | Phase 6: CLI & Tools (v0.0.7)           | not-started | —      | —     | —          | —          |
+| 4   | ms-161 | Phase 4: Memory & Intelligence (v0.0.5) | done        | —      | —     | 2026-03-13 | 2026-03-13 |
+| 5   | ms-162 | Phase 5: Remote Control (v0.0.6)        | done        | —      | #99   | 2026-03-14 | 2026-03-14 |
+| 6   | ms-163 | Phase 6: CLI & Tools (v0.0.7)           | done        | —      | #104  | 2026-03-14 | 2026-03-14 |
 | 7   | ms-164 | Phase 7: Polish & Beta (v0.1.0)         | not-started | —      | —     | —          | —          |
 
 ## Deployment
@@ -68,7 +68,8 @@
 | 7       | claude-opus-4-6 | 2026-03-12           | —        | context limit | P2-007           |
 | 8       | claude-opus-4-6 | 2026-03-12           | —        | context limit | Phase 2 complete |
 | 9       | claude-opus-4-6 | 2026-03-12           | —        | context limit | P3-007           |
-| 10      | claude-opus-4-6 | 2026-03-13           | —        | active        | P3-008           |
+| 10      | claude-opus-4-6 | 2026-03-13           | —        | context limit | P3-008           |
+| 11      | claude-opus-4-6 | 2026-03-14           | —        | active        | P5-005           |
 
 ## Scratchpad
 

docs/TASKS.md

@@ -2,67 +2,67 @@
 
 > Single-writer: orchestrator only. Workers read but never modify.
 
-| id     | status      | milestone | description                                                   | pr  | notes |
-| ------ | ----------- | --------- | ------------------------------------------------------------- | --- | ----- |
-| P0-001 | done        | Phase 0   | Scaffold monorepo                                             | #60 | #1    |
-| P0-002 | done        | Phase 0   | @mosaic/types — migrate and extend shared types               | #65 | #2    |
-| P0-003 | done        | Phase 0   | @mosaic/db — Drizzle schema and PG connection                 | #67 | #3    |
-| P0-004 | done        | Phase 0   | @mosaic/auth — BetterAuth email/password setup                | #68 | #4    |
-| P0-005 | done        | Phase 0   | Docker Compose — PG 17, Valkey 8, SigNoz                      | #65 | #5    |
-| P0-006 | done        | Phase 0   | OTEL foundation — OpenTelemetry SDK setup                     | #65 | #6    |
-| P0-007 | done        | Phase 0   | CI pipeline — Woodpecker config                               | #69 | #7    |
-| P0-008 | done        | Phase 0   | Project docs — AGENTS.md, CLAUDE.md, README                   | #69 | #8    |
-| P0-009 | done        | Phase 0   | Verify Phase 0 — CI green, all packages build                 | #70 | #9    |
-| P1-001 | done        | Phase 1   | apps/gateway scaffold — NestJS + Fastify adapter              | #61 | #10   |
-| P1-002 | done        | Phase 1   | Auth middleware — BetterAuth session validation               | #71 | #11   |
-| P1-003 | done        | Phase 1   | @mosaic/brain — migrate from v0, PG backend                   | #71 | #12   |
-| P1-004 | done        | Phase 1   | @mosaic/queue — migrate from v0                               | #71 | #13   |
-| P1-005 | done        | Phase 1   | Gateway routes — conversations CRUD + messages                | #72 | #14   |
-| P1-006 | done        | Phase 1   | Gateway routes — tasks, projects, missions CRUD               | #72 | #15   |
-| P1-007 | done        | Phase 1   | WebSocket server — chat streaming                             | #61 | #16   |
-| P1-008 | done        | Phase 1   | Basic agent dispatch — single provider                        | #61 | #17   |
-| P1-009 | done        | Phase 1   | Verify Phase 1 — gateway functional, API tested               | #73 | #18   |
-| P2-001 | done        | Phase 2   | @mosaic/agent — Pi SDK integration + agent pool               | #61 | #19   |
-| P2-002 | done        | Phase 2   | Multi-provider support — Anthropic + Ollama                   | #74 | #20   |
-| P2-003 | done        | Phase 2   | Agent routing engine — cost/capability matrix                 | #75 | #21   |
-| P2-004 | done        | Phase 2   | Tool registration — brain, queue, memory tools                | #76 | #22   |
-| P2-005 | done        | Phase 2   | @mosaic/coord — migrate from v0, gateway integration          | #77 | #23   |
-| P2-006 | done        | Phase 2   | Agent session management — tmux + monitoring                  | #78 | #24   |
-| P2-007 | done        | Phase 2   | Verify Phase 2 — multi-provider routing works                 | #79 | #25   |
-| P3-001 | done        | Phase 3   | apps/web scaffold — Next.js 16 + BetterAuth + Tailwind        | #82 | #26   |
-| P3-002 | done        | Phase 3   | Auth pages — login, registration, SSO redirect                | #83 | #27   |
-| P3-003 | done        | Phase 3   | Chat UI — conversations, messages, streaming                  | #84 | #28   |
-| P3-004 | done        | Phase 3   | Task management — list view + kanban board                    | #86 | #29   |
-| P3-005 | done        | Phase 3   | Project & mission views — dashboard + PRD viewer              | #87 | #30   |
-| P3-006 | done        | Phase 3   | Settings — provider config, profile, integrations             | #88 | #31   |
-| P3-007 | done        | Phase 3   | Admin panel — user management, RBAC                           | #89 | #32   |
-| P3-008 | done        | Phase 3   | Verify Phase 3 — web dashboard functional E2E                 | —   | #33   |
-| P4-001 | not-started | Phase 4   | @mosaic/memory — preference + insight stores                  | —   | #34   |
-| P4-002 | not-started | Phase 4   | Semantic search — pgvector embeddings + search API            | —   | #35   |
-| P4-003 | not-started | Phase 4   | @mosaic/log — log ingest, parsing, tiered storage             | —   | #36   |
-| P4-004 | not-started | Phase 4   | Summarization pipeline — Haiku-tier LLM + cron                | —   | #37   |
-| P4-005 | not-started | Phase 4   | Memory integration — inject into agent sessions               | —   | #38   |
-| P4-006 | not-started | Phase 4   | Skill management — catalog, install, config                   | —   | #39   |
-| P4-007 | not-started | Phase 4   | Verify Phase 4 — memory + log pipeline working                | —   | #40   |
-| P5-001 | not-started | Phase 5   | Plugin host — gateway plugin loading + channel interface      | —   | #41   |
-| P5-002 | done        | Phase 5   | @mosaic/discord-plugin — Discord bot + channel plugin         | #61 | #42   |
-| P5-003 | not-started | Phase 5   | @mosaic/telegram-plugin — Telegraf bot + channel plugin       | —   | #43   |
-| P5-004 | not-started | Phase 5   | SSO — Authentik OIDC adapter end-to-end                       | —   | #44   |
-| P5-005 | not-started | Phase 5   | Verify Phase 5 — Discord + Telegram + SSO working             | —   | #45   |
-| P6-001 | not-started | Phase 6   | @mosaic/cli — unified CLI binary + subcommands                | —   | #46   |
-| P6-002 | not-started | Phase 6   | @mosaic/prdy — migrate PRD wizard from v0                     | —   | #47   |
-| P6-003 | not-started | Phase 6   | @mosaic/quality-rails — migrate scaffolder from v0            | —   | #48   |
-| P6-004 | not-started | Phase 6   | @mosaic/mosaic — install wizard for v1                        | —   | #49   |
-| P6-005 | done        | Phase 6   | Pi TUI integration — mosaic tui                               | #61 | #50   |
-| P6-006 | not-started | Phase 6   | Verify Phase 6 — CLI functional, all subcommands              | —   | #51   |
-| P7-001 | not-started | Phase 7   | MCP endpoint hardening — streamable HTTP transport            | —   | #52   |
-| P7-002 | not-started | Phase 7   | Additional SSO providers — WorkOS + Keycloak                  | —   | #53   |
-| P7-003 | not-started | Phase 7   | Additional LLM providers — Codex, Z.ai, LM Studio, llama.cpp  | —   | #54   |
-| P7-004 | not-started | Phase 7   | E2E test suite — Playwright critical paths                    | —   | #55   |
-| P7-005 | not-started | Phase 7   | Performance optimization                                      | —   | #56   |
-| P7-006 | not-started | Phase 7   | Documentation — user guide, admin guide, dev guide            | —   | #57   |
-| P7-007 | not-started | Phase 7   | Bare-metal deployment docs + .env.example                     | —   | #58   |
-| P7-008 | not-started | Phase 7   | Beta release gate — v0.1.0 tag                                | —   | #59   |
-| FIX-01 | done        | Backlog   | Call piSession.dispose() in AgentService.destroySession       | #78 | #62   |
-| FIX-02 | not-started | Backlog   | TUI agent:end — fix React state updater side-effect           | —   | #63   |
-| FIX-03 | not-started | Backlog   | Agent session — cwd sandbox, system prompt, tool restrictions | —   | #64   |
+| id     | status      | milestone | description                                                   | pr   | notes |
+| ------ | ----------- | --------- | ------------------------------------------------------------- | ---- | ----- |
+| P0-001 | done        | Phase 0   | Scaffold monorepo                                             | #60  | #1    |
+| P0-002 | done        | Phase 0   | @mosaic/types — migrate and extend shared types               | #65  | #2    |
+| P0-003 | done        | Phase 0   | @mosaic/db — Drizzle schema and PG connection                 | #67  | #3    |
+| P0-004 | done        | Phase 0   | @mosaic/auth — BetterAuth email/password setup                | #68  | #4    |
+| P0-005 | done        | Phase 0   | Docker Compose — PG 17, Valkey 8, SigNoz                      | #65  | #5    |
+| P0-006 | done        | Phase 0   | OTEL foundation — OpenTelemetry SDK setup                     | #65  | #6    |
+| P0-007 | done        | Phase 0   | CI pipeline — Woodpecker config                               | #69  | #7    |
+| P0-008 | done        | Phase 0   | Project docs — AGENTS.md, CLAUDE.md, README                   | #69  | #8    |
+| P0-009 | done        | Phase 0   | Verify Phase 0 — CI green, all packages build                 | #70  | #9    |
+| P1-001 | done        | Phase 1   | apps/gateway scaffold — NestJS + Fastify adapter              | #61  | #10   |
+| P1-002 | done        | Phase 1   | Auth middleware — BetterAuth session validation               | #71  | #11   |
+| P1-003 | done        | Phase 1   | @mosaic/brain — migrate from v0, PG backend                   | #71  | #12   |
+| P1-004 | done        | Phase 1   | @mosaic/queue — migrate from v0                               | #71  | #13   |
+| P1-005 | done        | Phase 1   | Gateway routes — conversations CRUD + messages                | #72  | #14   |
+| P1-006 | done        | Phase 1   | Gateway routes — tasks, projects, missions CRUD               | #72  | #15   |
+| P1-007 | done        | Phase 1   | WebSocket server — chat streaming                             | #61  | #16   |
+| P1-008 | done        | Phase 1   | Basic agent dispatch — single provider                        | #61  | #17   |
+| P1-009 | done        | Phase 1   | Verify Phase 1 — gateway functional, API tested               | #73  | #18   |
+| P2-001 | done        | Phase 2   | @mosaic/agent — Pi SDK integration + agent pool               | #61  | #19   |
+| P2-002 | done        | Phase 2   | Multi-provider support — Anthropic + Ollama                   | #74  | #20   |
+| P2-003 | done        | Phase 2   | Agent routing engine — cost/capability matrix                 | #75  | #21   |
+| P2-004 | done        | Phase 2   | Tool registration — brain, queue, memory tools                | #76  | #22   |
+| P2-005 | done        | Phase 2   | @mosaic/coord — migrate from v0, gateway integration          | #77  | #23   |
+| P2-006 | done        | Phase 2   | Agent session management — tmux + monitoring                  | #78  | #24   |
+| P2-007 | done        | Phase 2   | Verify Phase 2 — multi-provider routing works                 | #79  | #25   |
+| P3-001 | done        | Phase 3   | apps/web scaffold — Next.js 16 + BetterAuth + Tailwind        | #82  | #26   |
+| P3-002 | done        | Phase 3   | Auth pages — login, registration, SSO redirect                | #83  | #27   |
+| P3-003 | done        | Phase 3   | Chat UI — conversations, messages, streaming                  | #84  | #28   |
+| P3-004 | done        | Phase 3   | Task management — list view + kanban board                    | #86  | #29   |
+| P3-005 | done        | Phase 3   | Project & mission views — dashboard + PRD viewer              | #87  | #30   |
+| P3-006 | done        | Phase 3   | Settings — provider config, profile, integrations             | #88  | #31   |
+| P3-007 | done        | Phase 3   | Admin panel — user management, RBAC                           | #89  | #32   |
+| P3-008 | done        | Phase 3   | Verify Phase 3 — web dashboard functional E2E                 | —    | #33   |
+| P4-001 | done        | Phase 4   | @mosaic/memory — preference + insight stores                  | —    | #34   |
+| P4-002 | done        | Phase 4   | Semantic search — pgvector embeddings + search API            | —    | #35   |
+| P4-003 | done        | Phase 4   | @mosaic/log — log ingest, parsing, tiered storage             | —    | #36   |
+| P4-004 | done        | Phase 4   | Summarization pipeline — Haiku-tier LLM + cron                | —    | #37   |
+| P4-005 | done        | Phase 4   | Memory integration — inject into agent sessions               | —    | #38   |
+| P4-006 | done        | Phase 4   | Skill management — catalog, install, config                   | —    | #39   |
+| P4-007 | done        | Phase 4   | Verify Phase 4 — memory + log pipeline working                | —    | #40   |
+| P5-001 | done        | Phase 5   | Plugin host — gateway plugin loading + channel interface      | —    | #41   |
+| P5-002 | done        | Phase 5   | @mosaic/discord-plugin — Discord bot + channel plugin         | #61  | #42   |
+| P5-003 | done        | Phase 5   | @mosaic/telegram-plugin — Telegraf bot + channel plugin       | —    | #43   |
+| P5-004 | done        | Phase 5   | SSO — Authentik OIDC adapter end-to-end                       | —    | #44   |
+| P5-005 | done        | Phase 5   | Verify Phase 5 — Discord + Telegram + SSO working             | #99  | #45   |
+| P6-001 | done        | Phase 6   | @mosaic/cli — unified CLI binary + subcommands                | #104 | #46   |
+| P6-002 | done        | Phase 6   | @mosaic/prdy — migrate PRD wizard from v0                     | #101 | #47   |
+| P6-003 | done        | Phase 6   | @mosaic/quality-rails — migrate scaffolder from v0            | #100 | #48   |
+| P6-004 | done        | Phase 6   | @mosaic/mosaic — install wizard for v1                        | #103 | #49   |
+| P6-005 | done        | Phase 6   | Pi TUI integration — mosaic tui                               | #61  | #50   |
+| P6-006 | done        | Phase 6   | Verify Phase 6 — CLI functional, all subcommands              | —    | #51   |
+| P7-001 | not-started | Phase 7   | MCP endpoint hardening — streamable HTTP transport            | —    | #52   |
+| P7-002 | not-started | Phase 7   | Additional SSO providers — WorkOS + Keycloak                  | —    | #53   |
+| P7-003 | not-started | Phase 7   | Additional LLM providers — Codex, Z.ai, LM Studio, llama.cpp  | —    | #54   |
+| P7-004 | not-started | Phase 7   | E2E test suite — Playwright critical paths                    | —    | #55   |
+| P7-005 | not-started | Phase 7   | Performance optimization                                      | —    | #56   |
+| P7-006 | not-started | Phase 7   | Documentation — user guide, admin guide, dev guide            | —    | #57   |
+| P7-007 | not-started | Phase 7   | Bare-metal deployment docs + .env.example                     | —    | #58   |
+| P7-008 | not-started | Phase 7   | Beta release gate — v0.1.0 tag                                | —    | #59   |
+| FIX-01 | done        | Backlog   | Call piSession.dispose() in AgentService.destroySession       | #78  | #62   |
+| FIX-02 | not-started | Backlog   | TUI agent:end — fix React state updater side-effect           | —    | #63   |
+| FIX-03 | not-started | Backlog   | Agent session — cwd sandbox, system prompt, tool restrictions | —    | #64   |

docs/plans/2026-03-13-gateway-security-hardening.md

@@ -0,0 +1,98 @@
+# Gateway Security Hardening Implementation Plan
+
+> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task.
+
+**Goal:** Finish the requested gateway security hardening fixes in the existing `fix/gateway-security` worktree and produce a PR-ready branch.
+
+**Architecture:** Tighten NestJS gateway boundaries in-place by enforcing auth guards, session validation, ownership checks, DTO validation, and Fastify security defaults. Preserve the current module structure and existing ESM import conventions.
+
+**Tech Stack:** NestJS 11, Fastify, Socket.IO, Better Auth, class-validator, Vitest, pnpm, TypeScript ESM
+
+---
+
+### Task 1: Reconcile Security Tests
+
+**Files:**
+
+- Modify: `apps/gateway/src/chat/__tests__/chat-security.test.ts`
+- Modify: `apps/gateway/src/__tests__/resource-ownership.test.ts`
+
+**Step 1: Write the failing test**
+
+- Encode the requested DTO constraints and socket-auth contract exactly.
+
+**Step 2: Run test to verify it fails**
+
+Run: `pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`
+
+Expected: FAIL on current DTO/helper mismatch.
+
+**Step 3: Write minimal implementation**
+
+- Update DTO/helper/controller code only where tests prove a gap.
+
+**Step 4: Run test to verify it passes**
+
+Run the same command and require green.
+
+### Task 2: Align Gateway Runtime Hardening
+
+**Files:**
+
+- Modify: `apps/gateway/src/conversations/conversations.dto.ts`
+- Modify: `apps/gateway/src/chat/chat.dto.ts`
+- Modify: `apps/gateway/src/chat/chat.gateway-auth.ts`
+- Modify: `apps/gateway/src/chat/chat.gateway.ts`
+- Modify: `apps/gateway/src/main.ts`
+- Modify: `apps/gateway/src/app.module.ts`
+
+**Step 1: Verify remaining requested deltas**
+
+- Confirm code matches requested guard, rate limit, helmet, body limit, env validation, and CORS settings.
+
+**Step 2: Apply minimal patch**
+
+- Keep changes scoped to requested behavior only.
+
+**Step 3: Run targeted tests**
+
+Run: `pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`
+
+Expected: PASS.
+
+### Task 3: Verification, Review, and Delivery
+
+**Files:**
+
+- Create: `docs/reports/code-review/gateway-security-20260313.md`
+- Create: `docs/reports/qa/gateway-security-20260313.md`
+- Modify: `docs/scratchpads/gateway-security-20260313.md`
+
+**Step 1: Run baseline gates**
+
+Run:
+
+```bash
+pnpm typecheck
+pnpm lint
+```
+
+**Step 2: Perform manual code review**
+
+- Record correctness/security/testing/doc findings.
+
+**Step 3: Commit and publish**
+
+Run:
+
+```bash
+git add -A
+git commit -m "fix(gateway): security hardening — auth guards, ownership checks, validation, rate limiting"
+git push origin fix/gateway-security
+```
+
+**Step 4: Open PR and notify**
+
+- Open PR titled `fix(gateway): security hardening — auth guards, ownership checks, validation, rate limiting`
+- Run `openclaw system event --text "PR ready: mosaic-mono-v1 fix/gateway-security — 7 security fixes" --mode now`
+- Remove worktree after PR is created.

docs/plans/authentik-sso-setup.md

@@ -0,0 +1,40 @@
+# Authentik SSO Setup
+
+## Create the Authentik application
+
+1. In Authentik, create an OAuth2/OpenID Provider.
+2. Create an Application and link it to that provider.
+3. Copy the generated client ID and client secret.
+
+## Required environment variables
+
+Set these values for the gateway/auth runtime:
+
+```bash
+AUTHENTIK_CLIENT_ID=your-client-id
+AUTHENTIK_CLIENT_SECRET=your-client-secret
+AUTHENTIK_ISSUER=https://authentik.example.com
+```
+
+`AUTHENTIK_ISSUER` should be the Authentik base URL, for example `https://authentik.example.com`.
+
+## Redirect URI
+
+Configure this redirect URI in the Authentik provider/application:
+
+```text
+{BETTER_AUTH_URL}/api/auth/callback/authentik
+```
+
+Example:
+
+```text
+https://mosaic.example.com/api/auth/callback/authentik
+```
+
+## Test the flow
+
+1. Start the gateway with `BETTER_AUTH_URL` and the Authentik environment variables set.
+2. Open the Mosaic login flow and choose the Authentik provider.
+3. Complete the Authentik login.
+4. Confirm the browser returns to Mosaic and a session is created successfully.

docs/reports/code-review/gateway-security-20260313.md

@@ -0,0 +1,23 @@
+# Code Review Report — Gateway Security Hardening
+
+## Scope Reviewed
+
+- `apps/gateway/src/chat/chat.gateway-auth.ts`
+- `apps/gateway/src/chat/chat.gateway.ts`
+- `apps/gateway/src/conversations/conversations.dto.ts`
+- `apps/gateway/src/chat/__tests__/chat-security.test.ts`
+
+## Findings
+
+- No blocker findings in the final changed surface.
+
+## Review Summary
+
+- Correctness: socket auth helper now returns Better Auth session data unchanged, and gateway disconnects clients whose handshake does not narrow to a valid session payload
+- Security: conversation role validation now rejects `system`; conversation content ceiling is 32k; chat request ceiling remains 10k
+- Testing: targeted auth, ownership, and DTO regression tests pass
+- Quality: `pnpm typecheck`, `pnpm lint`, and `pnpm format:check` all pass after the final edits
+
+## Residual Risk
+
+- `chat.gateway.ts` uses local narrowing around an `unknown` session result because the requested helper contract intentionally returns `unknown`.

docs/reports/qa/gateway-security-20260313.md

@@ -0,0 +1,39 @@
+# QA Report — Gateway Security Hardening
+
+## Scope
+
+- Chat HTTP auth guard hardening
+- Chat WebSocket session validation
+- DTO validation rules for chat and conversation payloads
+- Ownership regression coverage for by-id routes
+
+## TDD
+
+- Required: yes
+- Applied: yes
+- Red step: targeted tests failed on socket session reshaping and DTO role/length mismatches
+- Green step: targeted tests passed after runtime and DTO alignment
+
+## Baseline Verification
+
+| Command | Result | Evidence |
+| --- | --- | --- |
+| `pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts` | pass | 3 test files passed, 20 tests passed |
+| `pnpm typecheck` | pass | turbo completed 18/18 package typecheck tasks |
+| `pnpm lint` | pass | turbo completed 18/18 package lint tasks |
+| `pnpm format:check` | pass | `All matched files use Prettier code style!` |
+
+## Situational Verification
+
+| Acceptance Criterion | Verification Method | Evidence |
+| --- | --- | --- |
+| Chat controller requires auth and current-user context | source assertion test | `chat-security.test.ts` checks `@UseGuards(AuthGuard)` and `@CurrentUser() user: { id: string }` |
+| WebSocket handshake requires Better Auth session | unit tests for `validateSocketSession()` | null handshake returns `null`; valid handshake returns original session object |
+| Conversation messages reject non-user/assistant roles | class-validator test | `system` role fails validation |
+| Conversation messages enforce a 32k max length | class-validator test | `32_001` chars fail validation |
+| Chat request payload enforces a 10k max length | class-validator test | `10_001` chars fail validation |
+| By-id routes reject cross-user access | ownership regression tests | conversations, projects, missions, tasks each raise `ForbiddenException` for non-owner access |
+
+## Residual Risk
+
+- No live HTTP or WebSocket smoke test against a running gateway process was executed in this session.

docs/scratchpads/41-plugin-host.md

@@ -0,0 +1,30 @@
+# Scratchpad — P5-001 Plugin Host
+
+- Task: P5-001 / issue #41
+- Branch: feat/p5-plugin-host
+- Objective: add global NestJS plugin host module, wire Discord import, register active plugins from env, and attach to AppModule.
+- TDD: skipped as optional for module wiring/integration work; relying on targeted typecheck/lint and module-level situational verification.
+- Constraints: ESM .js imports, explicit @Inject(), follow existing gateway patterns, do not touch TASKS.md.
+
+## Progress Log
+
+- 2026-03-13: session started in worktree; loading gateway/plugin package context.
+- 2026-03-13: implemented initial plugin module, service, interface, and AppModule wiring; pending verification.
+- 2026-03-13: added `@mosaic/discord-plugin` as a gateway workspace dependency and regenerated `pnpm-lock.yaml`.
+- 2026-03-13: built gateway dependency chain so workspace packages exported `dist/*` for clean TypeScript resolution in this fresh worktree.
+- 2026-03-13: verification complete.
+
+## Verification
+
+- `pnpm --filter @mosaic/gateway... build` ✅
+- `pnpm --filter @mosaic/gateway typecheck` ✅
+- `pnpm --filter @mosaic/gateway lint` ✅
+- `pnpm format:check` ✅
+- `pnpm typecheck` ✅
+- `pnpm lint` ✅
+
+## Review
+
+- Automated review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted`
+- Manual review: diff inspection of gateway plugin host changes
+- Result: no blocker findings

docs/scratchpads/gateway-security-20260313.md

@@ -0,0 +1,68 @@
+# Gateway Security Hardening Scratchpad
+
+## Metadata
+
+- Date: 2026-03-13
+- Worktree: `/home/jwoltje/src/mosaic-mono-v1-worktrees/sec-remediation`
+- Branch: `fix/gateway-security`
+- Scope: Finish 7 requested gateway security fixes without switching branches or worktrees
+- Related tracker: worker task only; `docs/TASKS.md` is orchestrator-owned and left unchanged
+- Budget assumption: no explicit token cap; keep scope limited to requested gateway/auth/validation hardening
+
+## Objective
+
+Complete the remaining gateway security hardening work:
+
+1. Chat HTTP auth guard enforcement
+2. Chat WebSocket session validation
+3. Ownership checks on by-id CRUD routes
+4. Global validation pipe and DTO enforcement
+5. Rate limiting
+6. Helmet security headers
+7. Body limit and env validation
+
+## Plan
+
+1. Reconcile current worktree state against requested fixes.
+2. Patch or extend tests first for DTO/auth behavior mismatches.
+3. Implement minimal code changes to satisfy tests and requested behavior.
+4. Run targeted gateway tests.
+5. Run baseline gates: `pnpm typecheck`, `pnpm lint`.
+6. Perform manual code review and record findings.
+7. Commit, push branch, open PR, send OpenClaw event, remove worktree.
+
+## Progress Log
+
+### 2026-03-13T00:00 local
+
+- Loaded required Mosaic/global/runtime instructions and applicable skills.
+- Confirmed active worktree is `sec-remediation` and branch is already dirty with prior session changes.
+- Identified remaining gaps: DTO validation mismatch and non-requested socket auth helper typing/behavior drift.
+
+## TDD Notes
+
+- Required: yes. This is security/auth/permission logic.
+- Approach: update targeted unit tests first, verify failure, then patch code minimally.
+
+## Verification Log
+
+- `pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`
+  - Red: failed on socket session reshaping and DTO role/length mismatches.
+  - Green: passed with 3 test files and 20 tests passing.
+- `pnpm typecheck`
+  - Pass on 2026-03-13 with 18/18 package typecheck tasks successful.
+- `pnpm lint`
+  - Pass on 2026-03-13 with 18/18 package lint tasks successful.
+- `pnpm format:check`
+  - Pass on 2026-03-13 with `All matched files use Prettier code style!`
+
+## Review Log
+
+- Manual review completed against auth, authorization, validation, and runtime hardening requirements.
+- No blocker findings remained after remediation.
+
+## Risks / Blockers
+
+- Repository instructions conflict on PR merge behavior; user explicitly instructed PR-only, no merge. Follow user instruction.
+- Existing worktree contains prior-session modifications; do not revert unrelated changes.
+- `missions` and `tasks` currently depend on project ownership because the schema does not carry a direct user owner column.

docs/scratchpads/mvp-20260312.md

@@ -73,6 +73,34 @@ User confirmed: start the planning gate.
 | ------- | ---------- | --------- | ---------- | ----------------------------------------------------------------------------------- |
 | 7-8     | 2026-03-12 | Phase 2   | P2-007     | 19 unit tests (routing + coord). PR #79 merged, issue #25 closed. Phase 2 complete. |
 
+### Session 11 — Phase 5 completion
+
+| Session | Date       | Milestone | Tasks Done | Outcome                                                                                                                                         |
+| ------- | ---------- | --------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| 11      | 2026-03-14 | Phase 5   | P5-005     | Wired Telegram plugin into gateway (was stubbed). Updated .env.example with all P5 env vars. PR #99 merged, issue #45 closed. Phase 5 complete. |
+
+**Findings during verification:**
+
+- Telegram plugin was built but not wired into gateway (stub warning in plugin.module.ts)
+- Discord plugin was fully wired
+- SSO/Authentik OIDC adapter was fully wired
+- All three quality gates passing
+
+### Session 11 (continued) — Phase 6 completion
+
+| Session | Date       | Milestone | Tasks Done                             | Outcome                                                                                                          |
+| ------- | ---------- | --------- | -------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 11      | 2026-03-14 | Phase 6   | P6-002, P6-003, P6-004, P6-001, P6-006 | Full CLI & Tools migration. PRs #100-#104 merged. Also fixed 2 gateway startup bugs (PR #102). Phase 6 complete. |
+
+**Phase 6 details:**
+
+- P6-002: @mosaic/prdy migrated from v0 (~400 LOC). PR #101.
+- P6-003: @mosaic/quality-rails migrated from v0 (~500 LOC). PR #100.
+- P6-004: @mosaic/mosaic wizard migrated from v0 (2272 LOC, 28 files). PR #103.
+- P6-001: CLI subcommands wired — tui, prdy, quality-rails, wizard all working. PR #104.
+- BUG-1: PLUGIN_REGISTRY circular import fixed via plugin.tokens.ts. PR #102.
+- BUG-2: AuthStorage.create() → .inMemory() to prevent silent exit. PR #102.
+
 ## Open Questions
 
 (none at this time)
@@ -114,3 +142,9 @@ User confirmed: start the planning gate.
 | Session | Date       | Milestone | Tasks Done | Outcome                                                                                                                    |
 | ------- | ---------- | --------- | ---------- | -------------------------------------------------------------------------------------------------------------------------- |
 | 10      | 2026-03-13 | Phase 3   | P3-008     | Phase 3 verification: typecheck 18/18, lint 18/18, format clean, build green (10 routes), 10 tests pass. Phase 3 complete. |
+
+### Session 10 (continued) — Phase 4 Memory & Intelligence
+
+| Session | Date       | Milestone | Tasks Done            | Outcome                                                                                                                                                                                                                                                                            |
+| ------- | ---------- | --------- | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 10      | 2026-03-13 | Phase 4   | P4-001 through P4-007 | Full memory + log system: DB schema (preferences, insights w/ pgvector, agent_logs, skills, summarization_jobs), @mosaic/memory + @mosaic/log packages, embedding service, summarization pipeline w/ cron, memory tools in agent sessions, skill management CRUD. All gates green. |

docs/scratchpads/p5-003-telegram-plugin.md

@@ -0,0 +1,50 @@
+# Scratchpad — P5-003 Telegram Plugin
+
+## Objective
+
+Implement `@mosaic/telegram-plugin` by matching the established Discord plugin pattern with Telegraf + socket.io-client, add package docs, and pass package typecheck/lint.
+
+## Requirements Source
+
+- docs/PRD.md: Phase 5 remote control / Telegram plugin
+- docs/TASKS.md: P5-003
+- User task brief dated 2026-03-13
+
+## Plan
+
+1. Inspect Discord plugin behavior and package conventions
+2. Add Telegram runtime dependencies if missing
+3. Implement Telegram plugin with matching gateway event flow
+4. Add README usage documentation
+5. Run package typecheck and lint
+6. Run code review and remediate findings
+7. Commit, push, open PR, notify, remove worktree
+
+## TDD Rationale
+
+ASSUMPTION: No existing telegram package test harness or fixture coverage makes package-level TDD
+disproportionate for this plugin scaffold task. Validation will rely on typecheck, lint, and
+manual structural parity with the Discord plugin.
+
+## Risks
+
+- Telegram API typings may differ from Discord’s event shapes and require narrower guards.
+- Socket event payloads may already include `role` in shared gateway expectations.
+
+## Progress Log
+
+- 2026-03-13: Loaded Mosaic/global/repo guidance, mission files, Discord reference implementation, and Telegram package scaffold.
+- 2026-03-13: Added `telegraf` and `socket.io-client` to `@mosaic/telegram-plugin`.
+- 2026-03-13: Implemented Telegram message forwarding, gateway streaming accumulation, response chunking, and package README.
+
+## Verification Evidence
+
+- `pnpm --filter @mosaic/telegram-plugin typecheck` → pass
+- `pnpm --filter @mosaic/telegram-plugin lint` → pass
+- `pnpm typecheck` → pass
+- `pnpm lint` → pass
+
+## Review
+
+- Automated uncommitted review wrapper was invoked for the current delta.
+- Manual review completed against Discord parity, gateway event contracts, and package docs; no additional blockers found.

docs/scratchpads/p5-004-authentik-sso.md

@@ -0,0 +1,44 @@
+# P5-004 Scratchpad
+
+- Objective: Add optional Authentik OIDC SSO adapter via Better Auth genericOAuth.
+- Task ref: P5-004
+- Issue ref: #96
+- Plan:
+  1. Inspect auth/gateway surfaces and Better Auth plugin shape.
+  2. Add failing coverage for auth config/startup validation where feasible.
+  3. Implement adapter, docs, and warnings.
+  4. Run targeted typechecks, lint, and review.
+
+- TDD note: no low-friction auth plugin or bootstrap-env test seam exists for `packages/auth/src/auth.ts` or `apps/gateway/src/main.ts`. This change is configuration-oriented and does not alter an existing behavioral contract with a current test harness. I skipped new tests for this pass and relied on exact typecheck/lint/test commands plus manual review.
+
+- Changes:
+  1. Added conditional Better Auth `genericOAuth` plugin registration for the `authentik` provider in `packages/auth/src/auth.ts`.
+  2. Added a soft startup warning in `apps/gateway/src/main.ts` for incomplete Authentik env configuration.
+  3. Added `docs/plans/authentik-sso-setup.md` with env, redirect URI, and test-flow guidance.
+  4. Confirmed `packages/auth/src/index.ts` already exports `AuthConfig`; no change required there.
+
+- Verification:
+  1. `pnpm --filter @mosaic/db build`
+  2. `pnpm --filter @mosaic/auth typecheck`
+  3. `pnpm --filter @mosaic/gateway typecheck`
+  4. `pnpm lint`
+  5. `pnpm format:check`
+  6. `pnpm --filter @mosaic/auth test`
+  7. `pnpm --filter @mosaic/gateway test`
+
+- Results:
+  1. `@mosaic/auth` typecheck passed after replacing the non-existent `enabled` field with conditional plugin registration.
+  2. `@mosaic/gateway` typecheck passed.
+  3. Repo lint passed.
+  4. Prettier check passed after formatting `apps/gateway/src/main.ts`.
+  5. `@mosaic/auth` tests reported `No test files found, exiting with code 0`.
+  6. `@mosaic/gateway` tests passed: `3` files, `20` tests.
+
+- Review:
+  1. Manual review of the diff found no blocker issues.
+  2. External `codex-code-review.sh --uncommitted` was attempted but did not return a usable verdict in-session; no automated review findings were available from that run.
+
+- Situational evidence:
+  1. Provider activation is env-gated by `AUTHENTIK_CLIENT_ID`.
+  2. Misconfigured optional SSO surfaces a warning instead of crashing gateway startup.
+  3. Setup doc records the expected redirect path: `{BETTER_AUTH_URL}/api/auth/callback/authentik`.

docs/scratchpads/task-mission-ownership-20260313.md

@@ -0,0 +1,58 @@
+# Task Ownership Gap Fix Scratchpad
+
+## Metadata
+
+- Date: 2026-03-13
+- Worktree: `/home/jwoltje/src/mosaic-mono-v1-worktrees/fix-task-ownership`
+- Branch: `fix/task-mission-ownership`
+- Scope: Fix ownership checks in TasksController/MissionsController and extend gateway ownership tests
+- Related tracker: worker task only; `docs/TASKS.md` is orchestrator-owned and left unchanged
+- Budget assumption: no explicit token cap; keep scope limited to requested gateway permission fixes
+
+## Objective
+
+Close ownership gaps so task listing/creation and mission creation enforce project/mission ownership and reject cross-user access.
+
+## Acceptance Criteria
+
+1. TasksController `list()` enforces ownership for `projectId` and `missionId`, and does not return cross-user data when neither filter is provided.
+2. TasksController `create()` rejects unowned `projectId` and `missionId` references.
+3. MissionsController `create()` rejects unowned `projectId` references.
+4. Gateway ownership tests cover forbidden task creation and forbidden task listing by unowned project.
+
+## Plan
+
+1. Inspect current controller and ownership test patterns.
+2. Add failing permission tests first.
+3. Patch controller methods with existing ownership helpers.
+4. Run targeted gateway tests, then gateway typecheck/lint/full test.
+5. Perform independent review, record evidence, then complete the requested git/PR workflow.
+
+## TDD Notes
+
+- Required: yes. This is auth/permission logic and a bugfix.
+- Strategy: add failing tests in `resource-ownership.test.ts`, verify red, then implement minimal controller changes.
+
+## Verification Log
+
+- `pnpm --filter @mosaic/gateway test -- src/__tests__/resource-ownership.test.ts`
+  - Red: failed with 2 expected permission-path failures before controller changes.
+  - Green: passed after wiring ownership checks and adding owned-task filtering coverage.
+- `pnpm --filter @mosaic/gateway typecheck`
+  - Pass on 2026-03-13 after fixing parameter ordering and mission project nullability.
+- `pnpm --filter @mosaic/gateway lint`
+  - Pass on 2026-03-13.
+- `pnpm --filter @mosaic/gateway test`
+  - Pass on 2026-03-13 with 3 test files and 23 tests passing.
+- `pnpm format:check`
+  - Pass on 2026-03-13.
+
+## Review Log
+
+- Manual review: checked for auth regressions, cross-user list leakage, and dashboard behavior impact; kept unfiltered task list functional by filtering to owned projects/missions instead of returning an empty list.
+- Automated review: `~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted` running/re-run for independent review evidence.
+
+## Risks / Blockers
+
+- Repository-wide Mosaic instructions require merge/issue closure, but the user explicitly instructed PR-only and no merge; follow the user instruction.
+- `docs/TASKS.md` is orchestrator-owned and will not be edited from this worker task.

packages/auth/src/auth.ts

@@ -1,5 +1,6 @@
 import { betterAuth } from 'better-auth';
 import { drizzleAdapter } from 'better-auth/adapters/drizzle';
+import { genericOAuth } from 'better-auth/plugins';
 import type { Db } from '@mosaic/db';
 
 export interface AuthConfig {
@@ -10,6 +11,33 @@ export interface AuthConfig {
 
 export function createAuth(config: AuthConfig) {
   const { db, baseURL, secret } = config;
+  const authentikIssuer = process.env['AUTHENTIK_ISSUER'];
+  const authentikClientId = process.env['AUTHENTIK_CLIENT_ID'];
+  const authentikClientSecret = process.env['AUTHENTIK_CLIENT_SECRET'];
+  const plugins = authentikClientId
+    ? [
+        genericOAuth({
+          config: [
+            {
+              providerId: 'authentik',
+              clientId: authentikClientId,
+              clientSecret: authentikClientSecret ?? '',
+              discoveryUrl: authentikIssuer
+                ? `${authentikIssuer}/.well-known/openid-configuration`
+                : undefined,
+              authorizationUrl: authentikIssuer
+                ? `${authentikIssuer}/application/o/authorize/`
+                : undefined,
+              tokenUrl: authentikIssuer ? `${authentikIssuer}/application/o/token/` : undefined,
+              userInfoUrl: authentikIssuer
+                ? `${authentikIssuer}/application/o/userinfo/`
+                : undefined,
+              scopes: ['openid', 'email', 'profile'],
+            },
+          ],
+        }),
+      ]
+    : undefined;
 
   return betterAuth({
     database: drizzleAdapter(db, {
@@ -36,6 +64,7 @@ export function createAuth(config: AuthConfig) {
       expiresIn: 60 * 60 * 24 * 7, // 7 days
       updateAge: 60 * 60 * 24, // refresh daily
     },
+    plugins,
   });
 }
 

packages/cli/package.json

@@ -21,6 +21,9 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@mosaic/mosaic": "workspace:^",
+    "@mosaic/prdy": "workspace:^",
+    "@mosaic/quality-rails": "workspace:^",
     "ink": "^5.0.0",
     "ink-text-input": "^6.0.0",
     "ink-spinner": "^5.0.0",
@@ -29,6 +32,7 @@
     "commander": "^13.0.0"
   },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "@types/react": "^18.3.0",
     "tsx": "^4.0.0",
     "typescript": "^5.8.0",

packages/cli/src/cli.ts

@@ -1,6 +1,8 @@
 #!/usr/bin/env node
 
 import { Command } from 'commander';
+import { buildPrdyCli } from '@mosaic/prdy';
+import { createQualityRailsCli } from '@mosaic/quality-rails';
 
 const program = new Command();
 
@@ -25,4 +27,85 @@ program
     );
   });
 
+// prdy subcommand
+// buildPrdyCli() returns a wrapper Command; extract the 'prdy' subcommand from it.
+// Type cast is required because @mosaic/prdy uses commander@12 while @mosaic/cli uses commander@13.
+const prdyWrapper = buildPrdyCli();
+const prdyCmd = prdyWrapper.commands.find((c) => c.name() === 'prdy');
+if (prdyCmd !== undefined) {
+  program.addCommand(prdyCmd as unknown as Command);
+}
+
+// quality-rails subcommand
+// createQualityRailsCli() returns a wrapper Command; extract the 'quality-rails' subcommand.
+const qrWrapper = createQualityRailsCli();
+const qrCmd = qrWrapper.commands.find((c) => c.name() === 'quality-rails');
+if (qrCmd !== undefined) {
+  program.addCommand(qrCmd as unknown as Command);
+}
+
+// wizard subcommand — wraps @mosaic/mosaic installation wizard
+program
+  .command('wizard')
+  .description('Run the Mosaic installation wizard')
+  .option('--non-interactive', 'Run without prompts (uses defaults + flags)')
+  .option('--source-dir <path>', 'Source directory for framework files')
+  .option('--mosaic-home <path>', 'Target config directory')
+  .option('--name <name>', 'Agent name')
+  .option('--role <description>', 'Agent role description')
+  .option('--style <style>', 'Communication style: direct|friendly|formal')
+  .option('--accessibility <prefs>', 'Accessibility preferences')
+  .option('--guardrails <rules>', 'Custom guardrails')
+  .option('--user-name <name>', 'Your name')
+  .option('--pronouns <pronouns>', 'Your pronouns')
+  .option('--timezone <tz>', 'Your timezone')
+  .action(async (opts: Record<string, string | boolean | undefined>) => {
+    // Dynamic import to avoid loading wizard deps for other commands
+    const {
+      runWizard,
+      ClackPrompter,
+      HeadlessPrompter,
+      createConfigService,
+      WizardCancelledError,
+      DEFAULT_MOSAIC_HOME,
+    } = await import('@mosaic/mosaic');
+
+    try {
+      const mosaicHome = (opts['mosaicHome'] as string | undefined) ?? DEFAULT_MOSAIC_HOME;
+      const sourceDir = (opts['sourceDir'] as string | undefined) ?? mosaicHome;
+
+      const prompter = opts['nonInteractive'] ? new HeadlessPrompter() : new ClackPrompter();
+
+      const configService = createConfigService(mosaicHome, sourceDir);
+
+      await runWizard({
+        mosaicHome,
+        sourceDir,
+        prompter,
+        configService,
+        cliOverrides: {
+          soul: {
+            agentName: opts['name'] as string | undefined,
+            roleDescription: opts['role'] as string | undefined,
+            communicationStyle: opts['style'] as 'direct' | 'friendly' | 'formal' | undefined,
+            accessibility: opts['accessibility'] as string | undefined,
+            customGuardrails: opts['guardrails'] as string | undefined,
+          },
+          user: {
+            userName: opts['userName'] as string | undefined,
+            pronouns: opts['pronouns'] as string | undefined,
+            timezone: opts['timezone'] as string | undefined,
+          },
+        },
+      });
+    } catch (err) {
+      if (err instanceof WizardCancelledError) {
+        console.log('\nWizard cancelled.');
+        process.exit(0);
+      }
+      console.error('Wizard failed:', err);
+      process.exit(1);
+    }
+  });
+
 program.parse();

packages/db/src/index.ts

@@ -1,4 +1,18 @@
 export { createDb, type Db, type DbHandle } from './client.js';
 export { runMigrations } from './migrate.js';
 export * from './schema.js';
-export { eq, and, or, desc, asc, sql, inArray, isNull, isNotNull } from 'drizzle-orm';
+export {
+  eq,
+  and,
+  or,
+  desc,
+  asc,
+  sql,
+  inArray,
+  isNull,
+  isNotNull,
+  gt,
+  lt,
+  gte,
+  lte,
+} from 'drizzle-orm';

packages/db/src/schema.ts

@@ -3,7 +3,18 @@
  * drizzle-kit reads this file directly (avoids CJS/ESM extension issues).
  */
 
-import { pgTable, text, timestamp, boolean, uuid, jsonb, index } from 'drizzle-orm/pg-core';
+import {
+  pgTable,
+  text,
+  timestamp,
+  boolean,
+  uuid,
+  jsonb,
+  index,
+  real,
+  integer,
+  customType,
+} from 'drizzle-orm/pg-core';
 
 // ─── Auth (BetterAuth-compatible) ────────────────────────────────────────────
 
@@ -211,3 +222,152 @@ export const messages = pgTable(
   },
   (t) => [index('messages_conversation_id_idx').on(t.conversationId)],
 );
+
+// ─── pgvector custom type ───────────────────────────────────────────────────
+
+const vector = customType<{ data: number[]; driverParam: string; config: { dimensions: number } }>({
+  dataType(config) {
+    return `vector(${config?.dimensions ?? 1536})`;
+  },
+  fromDriver(value: unknown): number[] {
+    const str = value as string;
+    return str
+      .slice(1, -1)
+      .split(',')
+      .map((v) => Number(v));
+  },
+  toDriver(value: number[]): string {
+    return `[${value.join(',')}]`;
+  },
+});
+
+// ─── Memory ─────────────────────────────────────────────────────────────────
+
+export const preferences = pgTable(
+  'preferences',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    key: text('key').notNull(),
+    value: jsonb('value').notNull(),
+    category: text('category', {
+      enum: ['communication', 'coding', 'workflow', 'appearance', 'general'],
+    })
+      .notNull()
+      .default('general'),
+    source: text('source'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    index('preferences_user_id_idx').on(t.userId),
+    index('preferences_user_key_idx').on(t.userId, t.key),
+  ],
+);
+
+export const insights = pgTable(
+  'insights',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    content: text('content').notNull(),
+    embedding: vector('embedding', { dimensions: 1536 }),
+    source: text('source', {
+      enum: ['agent', 'user', 'summarization', 'system'],
+    })
+      .notNull()
+      .default('agent'),
+    category: text('category', {
+      enum: ['decision', 'learning', 'preference', 'fact', 'pattern', 'general'],
+    })
+      .notNull()
+      .default('general'),
+    relevanceScore: real('relevance_score').notNull().default(1.0),
+    metadata: jsonb('metadata'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+    decayedAt: timestamp('decayed_at', { withTimezone: true }),
+  },
+  (t) => [
+    index('insights_user_id_idx').on(t.userId),
+    index('insights_category_idx').on(t.category),
+    index('insights_relevance_idx').on(t.relevanceScore),
+  ],
+);
+
+// ─── Agent Logs ─────────────────────────────────────────────────────────────
+
+export const agentLogs = pgTable(
+  'agent_logs',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    sessionId: text('session_id').notNull(),
+    userId: text('user_id').references(() => users.id, { onDelete: 'set null' }),
+    level: text('level', { enum: ['debug', 'info', 'warn', 'error'] })
+      .notNull()
+      .default('info'),
+    category: text('category', {
+      enum: ['decision', 'tool_use', 'learning', 'error', 'general'],
+    })
+      .notNull()
+      .default('general'),
+    content: text('content').notNull(),
+    metadata: jsonb('metadata'),
+    tier: text('tier', { enum: ['hot', 'warm', 'cold'] })
+      .notNull()
+      .default('hot'),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    summarizedAt: timestamp('summarized_at', { withTimezone: true }),
+    archivedAt: timestamp('archived_at', { withTimezone: true }),
+  },
+  (t) => [
+    index('agent_logs_session_id_idx').on(t.sessionId),
+    index('agent_logs_user_id_idx').on(t.userId),
+    index('agent_logs_tier_idx').on(t.tier),
+    index('agent_logs_created_at_idx').on(t.createdAt),
+  ],
+);
+
+// ─── Skills ─────────────────────────────────────────────────────────────────
+
+export const skills = pgTable(
+  'skills',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    name: text('name').notNull().unique(),
+    description: text('description'),
+    version: text('version'),
+    source: text('source', { enum: ['builtin', 'community', 'custom'] })
+      .notNull()
+      .default('custom'),
+    config: jsonb('config'),
+    enabled: boolean('enabled').notNull().default(true),
+    installedBy: text('installed_by').references(() => users.id, { onDelete: 'set null' }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+    updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('skills_enabled_idx').on(t.enabled)],
+);
+
+// ─── Summarization Jobs ─────────────────────────────────────────────────────
+
+export const summarizationJobs = pgTable(
+  'summarization_jobs',
+  {
+    id: uuid('id').primaryKey().defaultRandom(),
+    status: text('status', { enum: ['pending', 'running', 'completed', 'failed'] })
+      .notNull()
+      .default('pending'),
+    logsProcessed: integer('logs_processed').notNull().default(0),
+    insightsCreated: integer('insights_created').notNull().default(0),
+    errorMessage: text('error_message'),
+    startedAt: timestamp('started_at', { withTimezone: true }),
+    completedAt: timestamp('completed_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [index('summarization_jobs_status_idx').on(t.status)],
+);

packages/log/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@mosaic/log",
   "version": "0.0.0",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -15,6 +16,10 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests"
   },
+  "dependencies": {
+    "@mosaic/db": "workspace:*",
+    "drizzle-orm": "^0.45.1"
+  },
   "devDependencies": {
     "typescript": "^5.8.0",
     "vitest": "^2.0.0"

packages/log/src/agent-logs.ts

@@ -0,0 +1,117 @@
+import { eq, and, desc, lt, sql, type Db, agentLogs } from '@mosaic/db';
+
+export type AgentLog = typeof agentLogs.$inferSelect;
+export type NewAgentLog = typeof agentLogs.$inferInsert;
+
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+export type LogCategory = 'decision' | 'tool_use' | 'learning' | 'error' | 'general';
+export type LogTier = 'hot' | 'warm' | 'cold';
+
+export interface LogQuery {
+  userId?: string;
+  sessionId?: string;
+  level?: LogLevel;
+  category?: LogCategory;
+  tier?: LogTier;
+  since?: Date;
+  until?: Date;
+  limit?: number;
+  offset?: number;
+}
+
+export function createAgentLogsRepo(db: Db) {
+  return {
+    async ingest(entry: NewAgentLog): Promise<AgentLog> {
+      const rows = await db.insert(agentLogs).values(entry).returning();
+      return rows[0]!;
+    },
+
+    async ingestBatch(entries: NewAgentLog[]): Promise<AgentLog[]> {
+      if (entries.length === 0) return [];
+      return db.insert(agentLogs).values(entries).returning();
+    },
+
+    async query(params: LogQuery): Promise<AgentLog[]> {
+      const conditions = [];
+
+      if (params.userId) conditions.push(eq(agentLogs.userId, params.userId));
+      if (params.sessionId) conditions.push(eq(agentLogs.sessionId, params.sessionId));
+      if (params.level) conditions.push(eq(agentLogs.level, params.level));
+      if (params.category) conditions.push(eq(agentLogs.category, params.category));
+      if (params.tier) conditions.push(eq(agentLogs.tier, params.tier));
+      if (params.since) conditions.push(sql`${agentLogs.createdAt} >= ${params.since}`);
+      if (params.until) conditions.push(sql`${agentLogs.createdAt} <= ${params.until}`);
+
+      const where = conditions.length > 0 ? and(...conditions) : undefined;
+
+      return db
+        .select()
+        .from(agentLogs)
+        .where(where)
+        .orderBy(desc(agentLogs.createdAt))
+        .limit(params.limit ?? 100)
+        .offset(params.offset ?? 0);
+    },
+
+    async findById(id: string): Promise<AgentLog | undefined> {
+      const rows = await db.select().from(agentLogs).where(eq(agentLogs.id, id));
+      return rows[0];
+    },
+
+    /**
+     * Transition hot logs older than the cutoff to warm tier.
+     * Returns the number of logs transitioned.
+     */
+    async promoteToWarm(olderThan: Date): Promise<number> {
+      const result = await db
+        .update(agentLogs)
+        .set({ tier: 'warm', summarizedAt: new Date() })
+        .where(and(eq(agentLogs.tier, 'hot'), lt(agentLogs.createdAt, olderThan)))
+        .returning();
+      return result.length;
+    },
+
+    /**
+     * Transition warm logs older than the cutoff to cold tier.
+     */
+    async promoteToCold(olderThan: Date): Promise<number> {
+      const result = await db
+        .update(agentLogs)
+        .set({ tier: 'cold', archivedAt: new Date() })
+        .where(and(eq(agentLogs.tier, 'warm'), lt(agentLogs.createdAt, olderThan)))
+        .returning();
+      return result.length;
+    },
+
+    /**
+     * Delete cold logs older than the retention period.
+     */
+    async purge(olderThan: Date): Promise<number> {
+      const result = await db
+        .delete(agentLogs)
+        .where(and(eq(agentLogs.tier, 'cold'), lt(agentLogs.createdAt, olderThan)))
+        .returning();
+      return result.length;
+    },
+
+    /**
+     * Get hot logs ready for summarization (decisions + learnings).
+     */
+    async getLogsForSummarization(olderThan: Date, limit = 100): Promise<AgentLog[]> {
+      return db
+        .select()
+        .from(agentLogs)
+        .where(
+          and(
+            eq(agentLogs.tier, 'hot'),
+            lt(agentLogs.createdAt, olderThan),
+            sql`${agentLogs.category} IN ('decision', 'learning', 'tool_use')`,
+          ),
+        )
+        .orderBy(agentLogs.createdAt)
+        .limit(limit);
+    },
+  };
+}
+
+export type AgentLogsRepo = ReturnType<typeof createAgentLogsRepo>;

packages/log/src/index.ts

@@ -1 +1,11 @@
-export const VERSION = '0.0.0';
+export { createLogService, type LogService } from './log-service.js';
+export {
+  createAgentLogsRepo,
+  type AgentLogsRepo,
+  type AgentLog,
+  type NewAgentLog,
+  type LogLevel,
+  type LogCategory,
+  type LogTier,
+  type LogQuery,
+} from './agent-logs.js';

packages/log/src/log-service.ts

@@ -0,0 +1,12 @@
+import type { Db } from '@mosaic/db';
+import { createAgentLogsRepo, type AgentLogsRepo } from './agent-logs.js';
+
+export interface LogService {
+  logs: AgentLogsRepo;
+}
+
+export function createLogService(db: Db): LogService {
+  return {
+    logs: createAgentLogsRepo(db),
+  };
+}

packages/memory/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@mosaic/memory",
   "version": "0.0.0",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {
@@ -16,7 +17,9 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@mosaic/types": "workspace:*"
+    "@mosaic/db": "workspace:*",
+    "@mosaic/types": "workspace:*",
+    "drizzle-orm": "^0.45.1"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

packages/memory/src/index.ts

@@ -1 +1,15 @@
-export const VERSION = '0.0.0';
+export { createMemory, type Memory } from './memory.js';
+export {
+  createPreferencesRepo,
+  type PreferencesRepo,
+  type Preference,
+  type NewPreference,
+} from './preferences.js';
+export {
+  createInsightsRepo,
+  type InsightsRepo,
+  type Insight,
+  type NewInsight,
+  type SearchResult,
+} from './insights.js';
+export type { VectorStore, VectorSearchResult, EmbeddingProvider } from './vector-store.js';

packages/memory/src/insights.ts

@@ -0,0 +1,89 @@
+import { eq, and, desc, sql, lt, type Db, insights } from '@mosaic/db';
+
+export type Insight = typeof insights.$inferSelect;
+export type NewInsight = typeof insights.$inferInsert;
+
+export interface SearchResult {
+  insight: Insight;
+  distance: number;
+}
+
+export function createInsightsRepo(db: Db) {
+  return {
+    async findByUser(userId: string, limit = 50): Promise<Insight[]> {
+      return db
+        .select()
+        .from(insights)
+        .where(eq(insights.userId, userId))
+        .orderBy(desc(insights.createdAt))
+        .limit(limit);
+    },
+
+    async findById(id: string): Promise<Insight | undefined> {
+      const rows = await db.select().from(insights).where(eq(insights.id, id));
+      return rows[0];
+    },
+
+    async create(data: NewInsight): Promise<Insight> {
+      const rows = await db.insert(insights).values(data).returning();
+      return rows[0]!;
+    },
+
+    async update(id: string, data: Partial<NewInsight>): Promise<Insight | undefined> {
+      const rows = await db
+        .update(insights)
+        .set({ ...data, updatedAt: new Date() })
+        .where(eq(insights.id, id))
+        .returning();
+      return rows[0];
+    },
+
+    async remove(id: string): Promise<boolean> {
+      const rows = await db.delete(insights).where(eq(insights.id, id)).returning();
+      return rows.length > 0;
+    },
+
+    /**
+     * Semantic search using pgvector cosine distance.
+     * Requires the vector extension and an embedding for the query.
+     */
+    async searchByEmbedding(
+      userId: string,
+      queryEmbedding: number[],
+      limit = 10,
+      maxDistance = 0.8,
+    ): Promise<SearchResult[]> {
+      const embeddingStr = `[${queryEmbedding.join(',')}]`;
+      const rows = await db.execute(sql`
+        SELECT *,
+               (embedding <=> ${embeddingStr}::vector) AS distance
+        FROM insights
+        WHERE user_id = ${userId}
+          AND embedding IS NOT NULL
+          AND (embedding <=> ${embeddingStr}::vector) < ${maxDistance}
+        ORDER BY distance ASC
+        LIMIT ${limit}
+      `);
+
+      return rows as unknown as SearchResult[];
+    },
+
+    /**
+     * Decay relevance scores for old insights that haven't been accessed recently.
+     */
+    async decayOldInsights(olderThan: Date, decayFactor = 0.95): Promise<number> {
+      const result = await db
+        .update(insights)
+        .set({
+          relevanceScore: sql`${insights.relevanceScore} * ${decayFactor}`,
+          decayedAt: new Date(),
+          updatedAt: new Date(),
+        })
+        .where(and(lt(insights.updatedAt, olderThan), sql`${insights.relevanceScore} > 0.1`))
+        .returning();
+      return result.length;
+    },
+  };
+}
+
+export type InsightsRepo = ReturnType<typeof createInsightsRepo>;

packages/memory/src/memory.ts

@@ -0,0 +1,15 @@
+import type { Db } from '@mosaic/db';
+import { createPreferencesRepo, type PreferencesRepo } from './preferences.js';
+import { createInsightsRepo, type InsightsRepo } from './insights.js';
+
+export interface Memory {
+  preferences: PreferencesRepo;
+  insights: InsightsRepo;
+}
+
+export function createMemory(db: Db): Memory {
+  return {
+    preferences: createPreferencesRepo(db),
+    insights: createInsightsRepo(db),
+  };
+}

packages/memory/src/preferences.ts

@@ -0,0 +1,59 @@
+import { eq, and, type Db, preferences } from '@mosaic/db';
+
+export type Preference = typeof preferences.$inferSelect;
+export type NewPreference = typeof preferences.$inferInsert;
+
+export function createPreferencesRepo(db: Db) {
+  return {
+    async findByUser(userId: string): Promise<Preference[]> {
+      return db.select().from(preferences).where(eq(preferences.userId, userId));
+    },
+
+    async findByUserAndKey(userId: string, key: string): Promise<Preference | undefined> {
+      const rows = await db
+        .select()
+        .from(preferences)
+        .where(and(eq(preferences.userId, userId), eq(preferences.key, key)));
+      return rows[0];
+    },
+
+    async findByUserAndCategory(
+      userId: string,
+      category: Preference['category'],
+    ): Promise<Preference[]> {
+      return db
+        .select()
+        .from(preferences)
+        .where(and(eq(preferences.userId, userId), eq(preferences.category, category)));
+    },
+
+    async upsert(data: NewPreference): Promise<Preference> {
+      const existing = await db
+        .select()
+        .from(preferences)
+        .where(and(eq(preferences.userId, data.userId), eq(preferences.key, data.key)));
+
+      if (existing[0]) {
+        const rows = await db
+          .update(preferences)
+          .set({ value: data.value, category: data.category, updatedAt: new Date() })
+          .where(eq(preferences.id, existing[0].id))
+          .returning();
+        return rows[0]!;
+      }
+
+      const rows = await db.insert(preferences).values(data).returning();
+      return rows[0]!;
+    },
+
+    async remove(userId: string, key: string): Promise<boolean> {
+      const rows = await db
+        .delete(preferences)
+        .where(and(eq(preferences.userId, userId), eq(preferences.key, key)))
+        .returning();
+      return rows.length > 0;
+    },
+  };
+}
+
+export type PreferencesRepo = ReturnType<typeof createPreferencesRepo>;

packages/memory/src/vector-store.ts

@@ -0,0 +1,39 @@
+/**
+ * VectorStore interface — abstraction over pgvector that allows future
+ * swap to Qdrant, Pinecone, etc.
+ */
+export interface VectorStore {
+  /** Store an embedding with an associated document ID. */
+  store(documentId: string, embedding: number[], metadata?: Record<string, unknown>): Promise<void>;
+
+  /** Search for similar embeddings, returning document IDs and distances. */
+  search(
+    queryEmbedding: number[],
+    limit?: number,
+    filter?: Record<string, unknown>,
+  ): Promise<VectorSearchResult[]>;
+
+  /** Delete an embedding by document ID. */
+  remove(documentId: string): Promise<void>;
+}
+
+export interface VectorSearchResult {
+  documentId: string;
+  distance: number;
+  metadata?: Record<string, unknown>;
+}
+
+/**
+ * EmbeddingProvider interface — generates embeddings from text.
+ * Implemented by the gateway using the configured LLM provider.
+ */
+export interface EmbeddingProvider {
+  /** Generate an embedding vector for the given text. */
+  embed(text: string): Promise<number[]>;
+
+  /** Generate embeddings for multiple texts in batch. */
+  embedBatch(texts: string[]): Promise<number[][]>;
+
+  /** The dimensionality of the embeddings this provider generates. */
+  dimensions: number;
+}

packages/mosaic/package.json

@@ -1,8 +1,13 @@
 {
   "name": "@mosaic/mosaic",
-  "version": "0.0.0",
+  "version": "0.1.0",
+  "description": "Mosaic installation wizard",
+  "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
+  "bin": {
+    "mosaic-wizard": "dist/index.js"
+  },
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
@@ -15,7 +20,15 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --passWithNoTests"
   },
+  "dependencies": {
+    "@clack/prompts": "^0.9.1",
+    "commander": "^12.1.0",
+    "picocolors": "^1.1.1",
+    "yaml": "^2.6.1",
+    "zod": "^3.23.8"
+  },
   "devDependencies": {
+    "@types/node": "^22.0.0",
     "typescript": "^5.8.0",
     "vitest": "^2.0.0"
   }

packages/mosaic/src/config/config-service.ts

@@ -0,0 +1,23 @@
+import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
+import { FileConfigAdapter } from './file-adapter.js';
+
+/**
+ * ConfigService interface — abstracts config read/write operations.
+ * Currently backed by FileConfigAdapter (writes .md files from templates).
+ * Designed for future swap to SqliteConfigAdapter or PostgresConfigAdapter.
+ */
+export interface ConfigService {
+  readSoul(): Promise<SoulConfig>;
+  readUser(): Promise<UserConfig>;
+  readTools(): Promise<ToolsConfig>;
+
+  writeSoul(config: SoulConfig): Promise<void>;
+  writeUser(config: UserConfig): Promise<void>;
+  writeTools(config: ToolsConfig): Promise<void>;
+
+  syncFramework(action: InstallAction): Promise<void>;
+}
+
+export function createConfigService(mosaicHome: string, sourceDir: string): ConfigService {
+  return new FileConfigAdapter(mosaicHome, sourceDir);
+}

packages/mosaic/src/config/file-adapter.ts

@@ -0,0 +1,158 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { ConfigService } from './config-service.js';
+import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
+import { soulSchema, userSchema, toolsSchema } from './schemas.js';
+import { renderTemplate } from '../template/engine.js';
+import {
+  buildSoulTemplateVars,
+  buildUserTemplateVars,
+  buildToolsTemplateVars,
+} from '../template/builders.js';
+import { atomicWrite, backupFile, syncDirectory } from '../platform/file-ops.js';
+
+/**
+ * Parse a SoulConfig from an existing SOUL.md file.
+ */
+function parseSoulFromMarkdown(content: string): SoulConfig {
+  const config: SoulConfig = {};
+
+  const nameMatch = content.match(/You are \*\*(.+?)\*\*/);
+  if (nameMatch?.[1]) config.agentName = nameMatch[1];
+
+  const roleMatch = content.match(/Role identity: (.+)/);
+  if (roleMatch?.[1]) config.roleDescription = roleMatch[1];
+
+  if (content.includes('Be direct, concise')) {
+    config.communicationStyle = 'direct';
+  } else if (content.includes('Be warm and conversational')) {
+    config.communicationStyle = 'friendly';
+  } else if (content.includes('Use professional, structured')) {
+    config.communicationStyle = 'formal';
+  }
+
+  return config;
+}
+
+/**
+ * Parse a UserConfig from an existing USER.md file.
+ */
+function parseUserFromMarkdown(content: string): UserConfig {
+  const config: UserConfig = {};
+
+  const nameMatch = content.match(/\*\*Name:\*\* (.+)/);
+  if (nameMatch?.[1]) config.userName = nameMatch[1];
+
+  const pronounsMatch = content.match(/\*\*Pronouns:\*\* (.+)/);
+  if (pronounsMatch?.[1]) config.pronouns = pronounsMatch[1];
+
+  const tzMatch = content.match(/\*\*Timezone:\*\* (.+)/);
+  if (tzMatch?.[1]) config.timezone = tzMatch[1];
+
+  return config;
+}
+
+/**
+ * Parse a ToolsConfig from an existing TOOLS.md file.
+ */
+function parseToolsFromMarkdown(content: string): ToolsConfig {
+  const config: ToolsConfig = {};
+
+  const credsMatch = content.match(/\*\*Location:\*\* (.+)/);
+  if (credsMatch?.[1]) config.credentialsLocation = credsMatch[1];
+
+  return config;
+}
+
+export class FileConfigAdapter implements ConfigService {
+  constructor(
+    private mosaicHome: string,
+    private sourceDir: string,
+  ) {}
+
+  async readSoul(): Promise<SoulConfig> {
+    const path = join(this.mosaicHome, 'SOUL.md');
+    if (!existsSync(path)) return {};
+    return parseSoulFromMarkdown(readFileSync(path, 'utf-8'));
+  }
+
+  async readUser(): Promise<UserConfig> {
+    const path = join(this.mosaicHome, 'USER.md');
+    if (!existsSync(path)) return {};
+    return parseUserFromMarkdown(readFileSync(path, 'utf-8'));
+  }
+
+  async readTools(): Promise<ToolsConfig> {
+    const path = join(this.mosaicHome, 'TOOLS.md');
+    if (!existsSync(path)) return {};
+    return parseToolsFromMarkdown(readFileSync(path, 'utf-8'));
+  }
+
+  async writeSoul(config: SoulConfig): Promise<void> {
+    const validated = soulSchema.parse(config);
+    const templatePath = this.findTemplate('SOUL.md.template');
+    if (!templatePath) return;
+
+    const template = readFileSync(templatePath, 'utf-8');
+    const vars = buildSoulTemplateVars(validated);
+    const output = renderTemplate(template, vars);
+
+    const outPath = join(this.mosaicHome, 'SOUL.md');
+    backupFile(outPath);
+    atomicWrite(outPath, output);
+  }
+
+  async writeUser(config: UserConfig): Promise<void> {
+    const validated = userSchema.parse(config);
+    const templatePath = this.findTemplate('USER.md.template');
+    if (!templatePath) return;
+
+    const template = readFileSync(templatePath, 'utf-8');
+    const vars = buildUserTemplateVars(validated);
+    const output = renderTemplate(template, vars);
+
+    const outPath = join(this.mosaicHome, 'USER.md');
+    backupFile(outPath);
+    atomicWrite(outPath, output);
+  }
+
+  async writeTools(config: ToolsConfig): Promise<void> {
+    const validated = toolsSchema.parse(config);
+    const templatePath = this.findTemplate('TOOLS.md.template');
+    if (!templatePath) return;
+
+    const template = readFileSync(templatePath, 'utf-8');
+    const vars = buildToolsTemplateVars(validated);
+    const output = renderTemplate(template, vars);
+
+    const outPath = join(this.mosaicHome, 'TOOLS.md');
+    backupFile(outPath);
+    atomicWrite(outPath, output);
+  }
+
+  async syncFramework(action: InstallAction): Promise<void> {
+    const preservePaths =
+      action === 'keep' || action === 'reconfigure'
+        ? ['SOUL.md', 'USER.md', 'TOOLS.md', 'memory']
+        : [];
+
+    syncDirectory(this.sourceDir, this.mosaicHome, {
+      preserve: preservePaths,
+      excludeGit: true,
+    });
+  }
+
+  /**
+   * Look for template in source dir first, then mosaic home.
+   */
+  private findTemplate(name: string): string | null {
+    const candidates = [
+      join(this.sourceDir, 'templates', name),
+      join(this.mosaicHome, 'templates', name),
+    ];
+    for (const path of candidates) {
+      if (existsSync(path)) return path;
+    }
+    return null;
+  }
+}

packages/mosaic/src/config/schemas.ts

@@ -0,0 +1,43 @@
+import { z } from 'zod';
+
+export const communicationStyleSchema = z.enum(['direct', 'friendly', 'formal']).default('direct');
+
+export const soulSchema = z
+  .object({
+    agentName: z.string().min(1).max(50).default('Assistant'),
+    roleDescription: z.string().default('execution partner and visibility engine'),
+    communicationStyle: communicationStyleSchema,
+    accessibility: z.string().default('none'),
+    customGuardrails: z.string().default(''),
+  })
+  .partial();
+
+export const gitProviderSchema = z.object({
+  name: z.string().min(1),
+  url: z.string().min(1),
+  cli: z.string().min(1),
+  purpose: z.string().min(1),
+});
+
+export const userSchema = z
+  .object({
+    userName: z.string().default(''),
+    pronouns: z.string().default('They/Them'),
+    timezone: z.string().default('UTC'),
+    background: z.string().default('(not configured)'),
+    accessibilitySection: z
+      .string()
+      .default('(No specific accommodations configured. Edit this section to add any.)'),
+    communicationPrefs: z.string().default(''),
+    personalBoundaries: z.string().default('(Edit this section to add any personal boundaries.)'),
+    projectsTable: z.string().default(''),
+  })
+  .partial();
+
+export const toolsSchema = z
+  .object({
+    gitProviders: z.array(gitProviderSchema).default([]),
+    credentialsLocation: z.string().default('none'),
+    customToolsSection: z.string().default(''),
+  })
+  .partial();

packages/mosaic/src/constants.ts

@@ -0,0 +1,38 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const VERSION = '0.1.0';
+
+export const DEFAULT_MOSAIC_HOME = join(homedir(), '.config', 'mosaic');
+
+export const DEFAULTS = {
+  agentName: 'Assistant',
+  roleDescription: 'execution partner and visibility engine',
+  communicationStyle: 'direct' as const,
+  pronouns: 'They/Them',
+  timezone: 'UTC',
+  background: '(not configured)',
+  accessibilitySection: '(No specific accommodations configured. Edit this section to add any.)',
+  personalBoundaries: '(Edit this section to add any personal boundaries.)',
+  projectsTable: `| Project | Stack | Registry |
+|---------|-------|----------|
+| (none configured) | | |`,
+  credentialsLocation: 'none',
+  customToolsSection: `## Custom Tools
+
+(Add any machine-specific tools, scripts, or workflows here.)`,
+  gitProvidersTable: `| Instance | URL | CLI | Purpose |
+|----------|-----|-----|---------|
+| (add your git providers here) | | | |`,
+};
+
+export const RECOMMENDED_SKILLS = new Set([
+  'brainstorming',
+  'code-review-excellence',
+  'lint',
+  'systematic-debugging',
+  'verification-before-completion',
+  'writing-plans',
+  'executing-plans',
+  'architecture-patterns',
+]);

packages/mosaic/src/errors.ts

@@ -0,0 +1,20 @@
+export class WizardCancelledError extends Error {
+  override name = 'WizardCancelledError';
+  constructor() {
+    super('Wizard cancelled by user');
+  }
+}
+
+export class ValidationError extends Error {
+  override name = 'ValidationError';
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+export class TemplateError extends Error {
+  override name = 'TemplateError';
+  constructor(templatePath: string, message: string) {
+    super(`Template error in ${templatePath}: ${message}`);
+  }
+}

packages/mosaic/src/index.ts

@@ -1 +1,84 @@
-export const VERSION = '0.0.0';
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { Command } from 'commander';
+import { ClackPrompter } from './prompter/clack-prompter.js';
+import { HeadlessPrompter } from './prompter/headless-prompter.js';
+import { createConfigService } from './config/config-service.js';
+import { runWizard } from './wizard.js';
+import { WizardCancelledError } from './errors.js';
+import { VERSION, DEFAULT_MOSAIC_HOME } from './constants.js';
+import type { CommunicationStyle } from './types.js';
+
+export { VERSION, DEFAULT_MOSAIC_HOME };
+export { runWizard } from './wizard.js';
+export { ClackPrompter } from './prompter/clack-prompter.js';
+export { HeadlessPrompter } from './prompter/headless-prompter.js';
+export { createConfigService } from './config/config-service.js';
+export { WizardCancelledError } from './errors.js';
+
+const program = new Command()
+  .name('mosaic-wizard')
+  .description('Mosaic Installation Wizard')
+  .version(VERSION);
+
+program
+  .option('--non-interactive', 'Run without prompts (uses defaults + flags)')
+  .option('--source-dir <path>', 'Source directory for framework files')
+  .option('--mosaic-home <path>', 'Target config directory', DEFAULT_MOSAIC_HOME)
+  // SOUL.md overrides
+  .option('--name <name>', 'Agent name')
+  .option('--role <description>', 'Agent role description')
+  .option('--style <style>', 'Communication style: direct|friendly|formal')
+  .option('--accessibility <prefs>', 'Accessibility preferences')
+  .option('--guardrails <rules>', 'Custom guardrails')
+  // USER.md overrides
+  .option('--user-name <name>', 'Your name')
+  .option('--pronouns <pronouns>', 'Your pronouns')
+  .option('--timezone <tz>', 'Your timezone')
+  .action(async (opts: Record<string, string | boolean | undefined>) => {
+    try {
+      const mosaicHome = (opts['mosaicHome'] as string) ?? DEFAULT_MOSAIC_HOME;
+      const sourceDir = (opts['sourceDir'] as string | undefined) ?? mosaicHome;
+
+      const prompter = opts['nonInteractive'] ? new HeadlessPrompter() : new ClackPrompter();
+
+      const configService = createConfigService(mosaicHome, sourceDir);
+
+      const style = opts['style'] as CommunicationStyle | undefined;
+
+      await runWizard({
+        mosaicHome,
+        sourceDir,
+        prompter,
+        configService,
+        cliOverrides: {
+          soul: {
+            agentName: opts['name'] as string | undefined,
+            roleDescription: opts['role'] as string | undefined,
+            communicationStyle: style,
+            accessibility: opts['accessibility'] as string | undefined,
+            customGuardrails: opts['guardrails'] as string | undefined,
+          },
+          user: {
+            userName: opts['userName'] as string | undefined,
+            pronouns: opts['pronouns'] as string | undefined,
+            timezone: opts['timezone'] as string | undefined,
+          },
+        },
+      });
+    } catch (err) {
+      if (err instanceof WizardCancelledError) {
+        console.log('\nWizard cancelled.');
+        process.exit(0);
+      }
+      console.error('Wizard failed:', err);
+      process.exit(1);
+    }
+  });
+
+const entryPath = process.argv[1] ? resolve(process.argv[1]) : '';
+if (entryPath.length > 0 && entryPath === fileURLToPath(import.meta.url)) {
+  program.parse();
+}

packages/mosaic/src/platform/detect.ts

@@ -0,0 +1,39 @@
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { homedir, platform } from 'node:os';
+
+export type ShellType = 'zsh' | 'bash' | 'fish' | 'powershell' | 'unknown';
+
+export function detectShell(): ShellType {
+  const shell = process.env['SHELL'] ?? '';
+  if (shell.includes('zsh')) return 'zsh';
+  if (shell.includes('bash')) return 'bash';
+  if (shell.includes('fish')) return 'fish';
+  if (platform() === 'win32') return 'powershell';
+  return 'unknown';
+}
+
+export function getShellProfilePath(): string | null {
+  const home = homedir();
+
+  if (platform() === 'win32') {
+    return join(home, 'Documents', 'PowerShell', 'Microsoft.PowerShell_profile.ps1');
+  }
+
+  const shell = detectShell();
+  switch (shell) {
+    case 'zsh': {
+      const zdotdir = process.env['ZDOTDIR'] ?? home;
+      return join(zdotdir, '.zshrc');
+    }
+    case 'bash': {
+      const bashrc = join(home, '.bashrc');
+      if (existsSync(bashrc)) return bashrc;
+      return join(home, '.profile');
+    }
+    case 'fish':
+      return join(home, '.config', 'fish', 'config.fish');
+    default:
+      return join(home, '.profile');
+  }
+}

packages/mosaic/src/platform/file-ops.ts

@@ -0,0 +1,114 @@
+import {
+  readFileSync,
+  writeFileSync,
+  existsSync,
+  mkdirSync,
+  copyFileSync,
+  renameSync,
+  readdirSync,
+  unlinkSync,
+  statSync,
+} from 'node:fs';
+import { dirname, join, relative } from 'node:path';
+
+const MAX_BACKUPS = 3;
+
+/**
+ * Atomic write: write to temp file, then rename.
+ * Creates parent directories as needed.
+ */
+export function atomicWrite(filePath: string, content: string): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+  const tmpPath = `${filePath}.tmp-${process.pid.toString()}`;
+  writeFileSync(tmpPath, content, 'utf-8');
+  renameSync(tmpPath, filePath);
+}
+
+/**
+ * Create a backup of a file before overwriting.
+ * Rotates backups to keep at most MAX_BACKUPS.
+ */
+export function backupFile(filePath: string): string | null {
+  if (!existsSync(filePath)) return null;
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '').replace('T', '-').slice(0, 19);
+  const backupPath = `${filePath}.bak-${timestamp}`;
+  copyFileSync(filePath, backupPath);
+  rotateBackups(filePath);
+  return backupPath;
+}
+
+function rotateBackups(filePath: string): void {
+  const dir = dirname(filePath);
+  const baseName = filePath.split('/').pop() ?? '';
+  const prefix = `${baseName}.bak-`;
+
+  try {
+    const backups = readdirSync(dir)
+      .filter((f: string) => f.startsWith(prefix))
+      .sort()
+      .reverse();
+
+    for (let i = MAX_BACKUPS; i < backups.length; i++) {
+      const backup = backups[i];
+      if (backup !== undefined) {
+        unlinkSync(join(dir, backup));
+      }
+    }
+  } catch {
+    // Non-fatal: backup rotation failure doesn't block writes
+  }
+}
+
+/**
+ * Sync a source directory to a target, with optional preserve paths.
+ * Replaces the rsync/cp logic from install.sh.
+ */
+export function syncDirectory(
+  source: string,
+  target: string,
+  options: { preserve?: string[]; excludeGit?: boolean } = {},
+): void {
+  const preserveSet = new Set(options.preserve ?? []);
+
+  // Collect files from source
+  function copyRecursive(src: string, dest: string, relBase: string): void {
+    if (!existsSync(src)) return;
+
+    const stat = statSync(src);
+    if (stat.isDirectory()) {
+      const relPath = relative(relBase, src);
+
+      // Skip .git
+      if (options.excludeGit && relPath === '.git') return;
+
+      // Skip preserved paths at top level
+      if (preserveSet.has(relPath) && existsSync(dest)) return;
+
+      mkdirSync(dest, { recursive: true });
+      for (const entry of readdirSync(src)) {
+        copyRecursive(join(src, entry), join(dest, entry), relBase);
+      }
+    } else {
+      const relPath = relative(relBase, src);
+
+      // Skip preserved files at top level
+      if (preserveSet.has(relPath) && existsSync(dest)) return;
+
+      mkdirSync(dirname(dest), { recursive: true });
+      copyFileSync(src, dest);
+    }
+  }
+
+  copyRecursive(source, target, source);
+}
+
+/**
+ * Safely read a file, returning null if it doesn't exist.
+ */
+export function safeReadFile(filePath: string): string | null {
+  try {
+    return readFileSync(filePath, 'utf-8');
+  } catch {
+    return null;
+  }
+}

packages/mosaic/src/prompter/clack-prompter.ts

@@ -0,0 +1,152 @@
+import * as p from '@clack/prompts';
+import { WizardCancelledError } from '../errors.js';
+import type {
+  WizardPrompter,
+  SelectOption,
+  MultiSelectOption,
+  ProgressHandle,
+} from './interface.js';
+
+function guardCancel<T>(value: T | symbol): T {
+  if (p.isCancel(value)) {
+    throw new WizardCancelledError();
+  }
+  return value as T;
+}
+
+export class ClackPrompter implements WizardPrompter {
+  intro(message: string): void {
+    p.intro(message);
+  }
+
+  outro(message: string): void {
+    p.outro(message);
+  }
+
+  note(message: string, title?: string): void {
+    p.note(message, title);
+  }
+
+  log(message: string): void {
+    p.log.info(message);
+  }
+
+  warn(message: string): void {
+    p.log.warn(message);
+  }
+
+  async text(opts: {
+    message: string;
+    placeholder?: string;
+    defaultValue?: string;
+    validate?: (value: string) => string | void;
+  }): Promise<string> {
+    const validate = opts.validate
+      ? (v: string) => {
+          const r = opts.validate!(v);
+          return r === undefined ? undefined : r;
+        }
+      : undefined;
+    const result = await p.text({
+      message: opts.message,
+      placeholder: opts.placeholder,
+      defaultValue: opts.defaultValue,
+      validate,
+    });
+    return guardCancel(result);
+  }
+
+  async confirm(opts: { message: string; initialValue?: boolean }): Promise<boolean> {
+    const result = await p.confirm({
+      message: opts.message,
+      initialValue: opts.initialValue,
+    });
+    return guardCancel(result);
+  }
+
+  async select<T>(opts: {
+    message: string;
+    options: SelectOption<T>[];
+    initialValue?: T;
+  }): Promise<T> {
+    const clackOptions = opts.options.map((o) => ({
+      value: o.value as T,
+      label: o.label,
+      hint: o.hint,
+    }));
+    const result = await p.select({
+      message: opts.message,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any -- clack Option conditional type needs concrete Primitive
+      options: clackOptions as any,
+      initialValue: opts.initialValue,
+    });
+    return guardCancel(result) as T;
+  }
+
+  async multiselect<T>(opts: {
+    message: string;
+    options: MultiSelectOption<T>[];
+    required?: boolean;
+  }): Promise<T[]> {
+    const clackOptions = opts.options.map((o) => ({
+      value: o.value as T,
+      label: o.label,
+      hint: o.hint,
+    }));
+    const result = await p.multiselect({
+      message: opts.message,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options: clackOptions as any,
+      required: opts.required,
+      initialValues: opts.options.filter((o) => o.selected).map((o) => o.value),
+    });
+    return guardCancel(result) as T[];
+  }
+
+  async groupMultiselect<T>(opts: {
+    message: string;
+    options: Record<string, MultiSelectOption<T>[]>;
+    required?: boolean;
+  }): Promise<T[]> {
+    const grouped: Record<string, { value: T; label: string; hint?: string }[]> = {};
+    for (const [group, items] of Object.entries(opts.options)) {
+      grouped[group] = items.map((o) => ({
+        value: o.value as T,
+        label: o.label,
+        hint: o.hint,
+      }));
+    }
+    const result = await p.groupMultiselect({
+      message: opts.message,
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      options: grouped as any,
+      required: opts.required,
+    });
+    return guardCancel(result) as T[];
+  }
+
+  spinner(): ProgressHandle {
+    const s = p.spinner();
+    let started = false;
+    return {
+      update(message: string) {
+        if (!started) {
+          s.start(message);
+          started = true;
+        } else {
+          s.message(message);
+        }
+      },
+      stop(message?: string) {
+        if (started) {
+          s.stop(message);
+          started = false;
+        }
+      },
+    };
+  }
+
+  separator(): void {
+    p.log.info('');
+  }
+}

packages/mosaic/src/prompter/headless-prompter.ts

@@ -0,0 +1,131 @@
+import type {
+  WizardPrompter,
+  SelectOption,
+  MultiSelectOption,
+  ProgressHandle,
+} from './interface.js';
+
+export type AnswerValue = string | boolean | string[];
+
+export class HeadlessPrompter implements WizardPrompter {
+  private answers: Map<string, AnswerValue>;
+  private logs: string[] = [];
+
+  constructor(answers: Record<string, AnswerValue> = {}) {
+    this.answers = new Map(Object.entries(answers));
+  }
+
+  intro(message: string): void {
+    this.logs.push(`[intro] ${message}`);
+  }
+  outro(message: string): void {
+    this.logs.push(`[outro] ${message}`);
+  }
+  note(message: string, title?: string): void {
+    this.logs.push(`[note] ${title ?? ''}: ${message}`);
+  }
+  log(message: string): void {
+    this.logs.push(`[log] ${message}`);
+  }
+  warn(message: string): void {
+    this.logs.push(`[warn] ${message}`);
+  }
+
+  async text(opts: {
+    message: string;
+    placeholder?: string;
+    defaultValue?: string;
+    validate?: (value: string) => string | void;
+  }): Promise<string> {
+    const answer = this.answers.get(opts.message);
+    const value =
+      typeof answer === 'string'
+        ? answer
+        : opts.defaultValue !== undefined
+          ? opts.defaultValue
+          : undefined;
+
+    if (value === undefined) {
+      throw new Error(`HeadlessPrompter: no answer for "${opts.message}"`);
+    }
+
+    if (opts.validate) {
+      const error = opts.validate(value);
+      if (error)
+        throw new Error(`HeadlessPrompter validation failed for "${opts.message}": ${error}`);
+    }
+
+    return value;
+  }
+
+  async confirm(opts: { message: string; initialValue?: boolean }): Promise<boolean> {
+    const answer = this.answers.get(opts.message);
+    if (typeof answer === 'boolean') return answer;
+    return opts.initialValue ?? true;
+  }
+
+  async select<T>(opts: {
+    message: string;
+    options: SelectOption<T>[];
+    initialValue?: T;
+  }): Promise<T> {
+    const answer = this.answers.get(opts.message);
+    if (answer !== undefined) {
+      // Find matching option by value string comparison
+      const match = opts.options.find((o) => String(o.value) === String(answer));
+      if (match) return match.value;
+    }
+    if (opts.initialValue !== undefined) return opts.initialValue;
+    if (opts.options.length === 0) {
+      throw new Error(`HeadlessPrompter: no options for "${opts.message}"`);
+    }
+    const first = opts.options[0];
+    if (first === undefined) {
+      throw new Error(`HeadlessPrompter: no options for "${opts.message}"`);
+    }
+    return first.value;
+  }
+
+  async multiselect<T>(opts: {
+    message: string;
+    options: MultiSelectOption<T>[];
+    required?: boolean;
+  }): Promise<T[]> {
+    const answer = this.answers.get(opts.message);
+    if (Array.isArray(answer)) {
+      return opts.options
+        .filter((o) => (answer as string[]).includes(String(o.value)))
+        .map((o) => o.value);
+    }
+    return opts.options.filter((o) => o.selected).map((o) => o.value);
+  }
+
+  async groupMultiselect<T>(opts: {
+    message: string;
+    options: Record<string, MultiSelectOption<T>[]>;
+    required?: boolean;
+  }): Promise<T[]> {
+    const answer = this.answers.get(opts.message);
+    if (Array.isArray(answer)) {
+      const all = Object.values(opts.options).flat();
+      return all.filter((o) => (answer as string[]).includes(String(o.value))).map((o) => o.value);
+    }
+    return Object.values(opts.options)
+      .flat()
+      .filter((o) => o.selected)
+      .map((o) => o.value);
+  }
+
+  spinner(): ProgressHandle {
+    return {
+      update(_message: string) {},
+      stop(_message?: string) {},
+    };
+  }
+
+  separator(): void {}
+
+  getLogs(): string[] {
+    return [...this.logs];
+  }
+}

packages/mosaic/src/prompter/interface.ts

@@ -0,0 +1,49 @@
+export interface SelectOption<T = string> {
+  value: T;
+  label: string;
+  hint?: string;
+}
+
+export interface MultiSelectOption<T = string> extends SelectOption<T> {
+  selected?: boolean;
+}
+
+export interface ProgressHandle {
+  update(message: string): void;
+  stop(message?: string): void;
+}
+
+export interface WizardPrompter {
+  intro(message: string): void;
+  outro(message: string): void;
+  note(message: string, title?: string): void;
+  log(message: string): void;
+  warn(message: string): void;
+
+  text(opts: {
+    message: string;
+    placeholder?: string;
+    defaultValue?: string;
+    validate?: (value: string) => string | void;
+  }): Promise<string>;
+
+  confirm(opts: { message: string; initialValue?: boolean }): Promise<boolean>;
+
+  select<T>(opts: { message: string; options: SelectOption<T>[]; initialValue?: T }): Promise<T>;
+
+  multiselect<T>(opts: {
+    message: string;
+    options: MultiSelectOption<T>[];
+    required?: boolean;
+  }): Promise<T[]>;
+
+  groupMultiselect<T>(opts: {
+    message: string;
+    options: Record<string, MultiSelectOption<T>[]>;
+    required?: boolean;
+  }): Promise<T[]>;
+
+  spinner(): ProgressHandle;
+
+  separator(): void;
+}

packages/mosaic/src/runtime/detector.ts

@@ -0,0 +1,82 @@
+import { execSync } from 'node:child_process';
+import { platform } from 'node:os';
+import type { RuntimeName } from '../types.js';
+
+export interface RuntimeInfo {
+  name: RuntimeName;
+  label: string;
+  installed: boolean;
+  path?: string;
+  version?: string;
+  installHint: string;
+}
+
+const RUNTIME_DEFS: Record<
+  RuntimeName,
+  { label: string; command: string; versionFlag: string; installHint: string }
+> = {
+  claude: {
+    label: 'Claude Code',
+    command: 'claude',
+    versionFlag: '--version',
+    installHint: 'npm install -g @anthropic-ai/claude-code',
+  },
+  codex: {
+    label: 'Codex',
+    command: 'codex',
+    versionFlag: '--version',
+    installHint: 'npm install -g @openai/codex',
+  },
+  opencode: {
+    label: 'OpenCode',
+    command: 'opencode',
+    versionFlag: 'version',
+    installHint: 'See https://opencode.ai for install instructions',
+  },
+};
+
+export function detectRuntime(name: RuntimeName): RuntimeInfo {
+  const def = RUNTIME_DEFS[name];
+  const isWindows = platform() === 'win32';
+  const whichCmd = isWindows ? `where ${def.command} 2>nul` : `which ${def.command} 2>/dev/null`;
+
+  try {
+    const pathOutput =
+      execSync(whichCmd, {
+        encoding: 'utf-8',
+        timeout: 5000,
+      })
+        .trim()
+        .split('\n')[0] ?? '';
+
+    let version: string | undefined;
+    try {
+      version = execSync(`${def.command} ${def.versionFlag} 2>/dev/null`, {
+        encoding: 'utf-8',
+        timeout: 5000,
+      }).trim();
+    } catch {
+      // Version detection is optional
+    }
+
+    return {
+      name,
+      label: def.label,
+      installed: true,
+      path: pathOutput,
+      version,
+      installHint: def.installHint,
+    };
+  } catch {
+    return {
+      name,
+      label: def.label,
+      installed: false,
+      installHint: def.installHint,
+    };
+  }
+}
+
+export function getInstallInstructions(name: RuntimeName): string {
+  return RUNTIME_DEFS[name].installHint;
+}

packages/mosaic/src/runtime/installer.ts

@@ -0,0 +1,12 @@
+import type { RuntimeName } from '../types.js';
+import { getInstallInstructions } from './detector.js';
+
+export function formatInstallInstructions(name: RuntimeName): string {
+  const hint = getInstallInstructions(name);
+  const labels: Record<RuntimeName, string> = {
+    claude: 'Claude Code',
+    codex: 'Codex',
+    opencode: 'OpenCode',
+  };
+  return `To install ${labels[name]}:\n  ${hint}`;
+}

packages/mosaic/src/runtime/mcp-config.ts

@@ -0,0 +1,95 @@
+import { readFileSync, writeFileSync, existsSync, mkdirSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { homedir } from 'node:os';
+import type { RuntimeName } from '../types.js';
+
+const MCP_ENTRY = {
+  command: 'npx',
+  args: ['-y', '@modelcontextprotocol/server-sequential-thinking'],
+};
+
+export function configureMcpForRuntime(runtime: RuntimeName): void {
+  switch (runtime) {
+    case 'claude':
+      return configureClaudeMcp();
+    case 'codex':
+      return configureCodexMcp();
+    case 'opencode':
+      return configureOpenCodeMcp();
+  }
+}
+
+function ensureDir(filePath: string): void {
+  mkdirSync(dirname(filePath), { recursive: true });
+}
+
+function configureClaudeMcp(): void {
+  const settingsPath = join(homedir(), '.claude', 'settings.json');
+  ensureDir(settingsPath);
+
+  let data: Record<string, unknown> = {};
+  if (existsSync(settingsPath)) {
+    try {
+      data = JSON.parse(readFileSync(settingsPath, 'utf-8')) as Record<string, unknown>;
+    } catch {
+      // Start fresh if corrupt
+    }
+  }
+
+  if (
+    !data['mcpServers'] ||
+    typeof data['mcpServers'] !== 'object' ||
+    Array.isArray(data['mcpServers'])
+  ) {
+    data['mcpServers'] = {};
+  }
+  (data['mcpServers'] as Record<string, unknown>)['sequential-thinking'] = MCP_ENTRY;
+
+  writeFileSync(settingsPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}
+
+function configureCodexMcp(): void {
+  const configPath = join(homedir(), '.codex', 'config.toml');
+  ensureDir(configPath);
+
+  let content = '';
+  if (existsSync(configPath)) {
+    content = readFileSync(configPath, 'utf-8');
+    // Remove existing sequential-thinking section
+    content = content
+      .replace(/\[mcp_servers\.(sequential-thinking|sequential_thinking)\][\s\S]*?(?=\n\[|$)/g, '')
+      .trim();
+  }
+
+  content +=
+    '\n\n[mcp_servers.sequential-thinking]\n' +
+    'command = "npx"\n' +
+    'args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]\n';
+
+  writeFileSync(configPath, content, 'utf-8');
+}
+
+function configureOpenCodeMcp(): void {
+  const configPath = join(homedir(), '.config', 'opencode', 'config.json');
+  ensureDir(configPath);
+
+  let data: Record<string, unknown> = {};
+  if (existsSync(configPath)) {
+    try {
+      data = JSON.parse(readFileSync(configPath, 'utf-8')) as Record<string, unknown>;
+    } catch {
+      // Start fresh
+    }
+  }
+
+  if (!data['mcp'] || typeof data['mcp'] !== 'object' || Array.isArray(data['mcp'])) {
+    data['mcp'] = {};
+  }
+  (data['mcp'] as Record<string, unknown>)['sequential-thinking'] = {
+    type: 'local',
+    command: ['npx', '-y', '@modelcontextprotocol/server-sequential-thinking'],
+    enabled: true,
+  };
+
+  writeFileSync(configPath, JSON.stringify(data, null, 2) + '\n', 'utf-8');
+}

packages/mosaic/src/skills/catalog.ts

@@ -0,0 +1,96 @@
+import { readdirSync, readFileSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { parse as parseYaml } from 'yaml';
+import { RECOMMENDED_SKILLS } from '../constants.js';
+
+export interface SkillEntry {
+  name: string;
+  description: string;
+  version?: string;
+  recommended: boolean;
+  source: 'canonical' | 'local';
+}
+
+export function loadSkillsCatalog(mosaicHome: string): SkillEntry[] {
+  const skills: SkillEntry[] = [];
+
+  // Load canonical skills
+  const canonicalDir = join(mosaicHome, 'skills');
+  if (existsSync(canonicalDir)) {
+    skills.push(...loadSkillsFromDir(canonicalDir, 'canonical'));
+  }
+
+  // Fallback to source repo
+  const sourceDir = join(mosaicHome, 'sources', 'agent-skills', 'skills');
+  if (skills.length === 0 && existsSync(sourceDir)) {
+    skills.push(...loadSkillsFromDir(sourceDir, 'canonical'));
+  }
+
+  // Load local skills
+  const localDir = join(mosaicHome, 'skills-local');
+  if (existsSync(localDir)) {
+    skills.push(...loadSkillsFromDir(localDir, 'local'));
+  }
+
+  return skills.sort((a, b) => a.name.localeCompare(b.name));
+}
+
+function loadSkillsFromDir(dir: string, source: 'canonical' | 'local'): SkillEntry[] {
+  const entries: SkillEntry[] = [];
+
+  let dirEntries;
+  try {
+    dirEntries = readdirSync(dir, { withFileTypes: true });
+  } catch {
+    return entries;
+  }
+
+  for (const entry of dirEntries) {
+    if (!entry.isDirectory() || entry.name.startsWith('.')) continue;
+
+    const skillMdPath = join(dir, entry.name, 'SKILL.md');
+    if (!existsSync(skillMdPath)) continue;
+
+    try {
+      const content = readFileSync(skillMdPath, 'utf-8');
+      const frontmatter = parseFrontmatter(content);
+
+      entries.push({
+        name: (frontmatter['name'] as string | undefined) ?? entry.name,
+        description: (frontmatter['description'] as string | undefined) ?? '',
+        version: frontmatter['version'] as string | undefined,
+        recommended: RECOMMENDED_SKILLS.has(entry.name),
+        source,
+      });
+    } catch {
+      // Skip malformed skills
+      entries.push({
+        name: entry.name,
+        description: '',
+        recommended: RECOMMENDED_SKILLS.has(entry.name),
+        source,
+      });
+    }
+  }
+
+  return entries;
+}
+
+function parseFrontmatter(content: string): Record<string, unknown> {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match?.[1]) return {};
+
+  try {
+    return (parseYaml(match[1]) as Record<string, unknown>) ?? {};
+  } catch {
+    // Fallback: simple key-value parsing
+    const result: Record<string, string> = {};
+    for (const line of match[1].split('\n')) {
+      const kv = line.match(/^(\w[\w-]*)\s*:\s*(.+)/);
+      if (kv?.[1] !== undefined && kv[2] !== undefined) {
+        result[kv[1]] = kv[2].replace(/^['"]|['"]$/g, '');
+      }
+    }
+    return result;
+  }
+}

packages/mosaic/src/skills/categories.ts

@@ -0,0 +1,143 @@
+/**
+ * Skill category definitions and mapping.
+ * Skills are assigned to categories by name, with keyword fallback.
+ */
+
+export const SKILL_CATEGORIES: Record<string, string[]> = {
+  'Frontend & UI': [
+    'ai-sdk',
+    'algorithmic-art',
+    'antfu',
+    'canvas-design',
+    'frontend-design',
+    'next-best-practices',
+    'nuxt',
+    'pinia',
+    'shadcn-ui',
+    'slidev',
+    'tailwind-design-system',
+    'theme-factory',
+    'ui-animation',
+    'unocss',
+    'vercel-composition-patterns',
+    'vercel-react-best-practices',
+    'vercel-react-native-skills',
+    'vue',
+    'vue-best-practices',
+    'vue-router-best-practices',
+    'vueuse-functions',
+    'web-artifacts-builder',
+    'web-design-guidelines',
+    'vite',
+    'vitepress',
+  ],
+  'Backend & Infrastructure': [
+    'architecture-patterns',
+    'fastapi',
+    'mcp-builder',
+    'nestjs-best-practices',
+    'python-performance-optimization',
+    'tsdown',
+    'turborepo',
+    'pnpm',
+    'dispatching-parallel-agents',
+    'subagent-driven-development',
+    'create-agent',
+    'proactive-agent',
+    'using-superpowers',
+    'kickstart',
+    'executing-plans',
+  ],
+  'Testing & Quality': [
+    'code-review-excellence',
+    'lint',
+    'pr-reviewer',
+    'receiving-code-review',
+    'requesting-code-review',
+    'systematic-debugging',
+    'test-driven-development',
+    'verification-before-completion',
+    'vitest',
+    'vue-testing-best-practices',
+    'webapp-testing',
+  ],
+  'Marketing & Growth': [
+    'ab-test-setup',
+    'analytics-tracking',
+    'competitor-alternatives',
+    'copy-editing',
+    'copywriting',
+    'email-sequence',
+    'form-cro',
+    'free-tool-strategy',
+    'launch-strategy',
+    'marketing-ideas',
+    'marketing-psychology',
+    'onboarding-cro',
+    'page-cro',
+    'paid-ads',
+    'paywall-upgrade-cro',
+    'popup-cro',
+    'pricing-strategy',
+    'product-marketing-context',
+    'programmatic-seo',
+    'referral-program',
+    'schema-markup',
+    'seo-audit',
+    'signup-flow-cro',
+    'social-content',
+  ],
+  'Product & Strategy': [
+    'brainstorming',
+    'brand-guidelines',
+    'content-strategy',
+    'writing-plans',
+    'skill-creator',
+    'writing-skills',
+    'prd',
+  ],
+  'Developer Practices': ['finishing-a-development-branch', 'using-git-worktrees'],
+  'Auth & Security': [
+    'better-auth-best-practices',
+    'create-auth-skill',
+    'email-and-password-best-practices',
+    'organization-best-practices',
+    'two-factor-authentication-best-practices',
+  ],
+  'Content & Documentation': [
+    'doc-coauthoring',
+    'docx',
+    'internal-comms',
+    'pdf',
+    'pptx',
+    'slack-gif-creator',
+    'xlsx',
+  ],
+};
+
+// Reverse lookup: skill name -> category
+const SKILL_TO_CATEGORY = new Map<string, string>();
+for (const [category, skills] of Object.entries(SKILL_CATEGORIES)) {
+  for (const skill of skills) {
+    SKILL_TO_CATEGORY.set(skill, category);
+  }
+}
+
+export function categorizeSkill(name: string, description: string): string {
+  const mapped = SKILL_TO_CATEGORY.get(name);
+  if (mapped) return mapped;
+  return inferCategoryFromDescription(description);
+}
+
+function inferCategoryFromDescription(desc: string): string {
+  const lower = desc.toLowerCase();
+  if (/\b(react|vue|css|frontend|ui|component|tailwind|design)\b/.test(lower))
+    return 'Frontend & UI';
+  if (/\b(api|backend|server|docker|infra|deploy)\b/.test(lower)) return 'Backend & Infrastructure';
+  if (/\b(test|lint|review|debug|quality)\b/.test(lower)) return 'Testing & Quality';
+  if (/\b(marketing|seo|copy|ads|cro|conversion|email)\b/.test(lower)) return 'Marketing & Growth';
+  if (/\b(auth|security|2fa|password|credential)\b/.test(lower)) return 'Auth & Security';
+  if (/\b(doc|pdf|word|sheet|writing|comms)\b/.test(lower)) return 'Content & Documentation';
+  if (/\b(product|strategy|brainstorm|plan|prd)\b/.test(lower)) return 'Product & Strategy';
+  return 'Developer Practices';
+}

packages/mosaic/src/stages/detect-install.ts

@@ -0,0 +1,95 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { ConfigService } from '../config/config-service.js';
+import type { WizardState, InstallAction } from '../types.js';
+
+function detectExistingInstall(mosaicHome: string): boolean {
+  if (!existsSync(mosaicHome)) return false;
+  return (
+    existsSync(join(mosaicHome, 'bin/mosaic')) ||
+    existsSync(join(mosaicHome, 'AGENTS.md')) ||
+    existsSync(join(mosaicHome, 'SOUL.md'))
+  );
+}
+
+function detectExistingIdentity(mosaicHome: string): {
+  hasSoul: boolean;
+  hasUser: boolean;
+  hasTools: boolean;
+  agentName?: string;
+} {
+  const soulPath = join(mosaicHome, 'SOUL.md');
+  const hasSoul = existsSync(soulPath);
+  let agentName: string | undefined;
+
+  if (hasSoul) {
+    try {
+      const content = readFileSync(soulPath, 'utf-8');
+      const match = content.match(/You are \*\*(.+?)\*\*/);
+      agentName = match?.[1];
+    } catch {
+      // Non-fatal
+    }
+  }
+
+  return {
+    hasSoul,
+    hasUser: existsSync(join(mosaicHome, 'USER.md')),
+    hasTools: existsSync(join(mosaicHome, 'TOOLS.md')),
+    agentName,
+  };
+}
+
+export async function detectInstallStage(
+  p: WizardPrompter,
+  state: WizardState,
+  config: ConfigService,
+): Promise<void> {
+  const existing = detectExistingInstall(state.mosaicHome);
+  if (!existing) {
+    state.installAction = 'fresh';
+    return;
+  }
+
+  const identity = detectExistingIdentity(state.mosaicHome);
+  const identitySummary = identity.agentName
+    ? `Agent: ${identity.agentName}`
+    : 'No identity configured';
+
+  p.note(
+    `Found existing Mosaic installation at:\n${state.mosaicHome}\n\n` +
+      `${identitySummary}\n` +
+      `SOUL.md: ${identity.hasSoul ? 'yes' : 'no'}\n` +
+      `USER.md: ${identity.hasUser ? 'yes' : 'no'}\n` +
+      `TOOLS.md: ${identity.hasTools ? 'yes' : 'no'}`,
+    'Existing Installation Detected',
+  );
+
+  state.installAction = await p.select<InstallAction>({
+    message: 'What would you like to do?',
+    options: [
+      {
+        value: 'keep',
+        label: 'Keep identity, update framework',
+        hint: 'Preserves SOUL.md, USER.md, TOOLS.md, memory/',
+      },
+      {
+        value: 'reconfigure',
+        label: 'Reconfigure identity',
+        hint: 'Re-run identity setup, update framework',
+      },
+      {
+        value: 'reset',
+        label: 'Fresh install',
+        hint: 'Replace everything',
+      },
+    ],
+  });
+
+  if (state.installAction === 'keep') {
+    state.soul = await config.readSoul();
+    state.user = await config.readUser();
+    state.tools = await config.readTools();
+  }
+}

packages/mosaic/src/stages/finalize.ts

@@ -0,0 +1,165 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, appendFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { platform } from 'node:os';
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { ConfigService } from '../config/config-service.js';
+import type { WizardState } from '../types.js';
+import { getShellProfilePath } from '../platform/detect.js';
+
+function linkRuntimeAssets(mosaicHome: string): void {
+  const script = join(mosaicHome, 'bin', 'mosaic-link-runtime-assets');
+  if (existsSync(script)) {
+    try {
+      spawnSync('bash', [script], { timeout: 30000, stdio: 'pipe' });
+    } catch {
+      // Non-fatal: wizard continues
+    }
+  }
+}
+
+function syncSkills(mosaicHome: string): void {
+  const script = join(mosaicHome, 'bin', 'mosaic-sync-skills');
+  if (existsSync(script)) {
+    try {
+      spawnSync('bash', [script], { timeout: 60000, stdio: 'pipe' });
+    } catch {
+      // Non-fatal
+    }
+  }
+}
+
+interface DoctorResult {
+  warnings: number;
+  output: string;
+}
+
+function runDoctor(mosaicHome: string): DoctorResult {
+  const script = join(mosaicHome, 'bin', 'mosaic-doctor');
+  if (!existsSync(script)) {
+    return { warnings: 0, output: 'mosaic-doctor not found' };
+  }
+
+  try {
+    const result = spawnSync('bash', [script], {
+      timeout: 30000,
+      encoding: 'utf-8',
+      stdio: 'pipe',
+    });
+    const output = result.stdout ?? '';
+    const warnings = (output.match(/WARN/g) ?? []).length;
+    return { warnings, output };
+  } catch {
+    return { warnings: 1, output: 'Doctor check failed' };
+  }
+}
+
+type PathAction = 'already' | 'added' | 'skipped';
+
+function setupPath(mosaicHome: string, _p: WizardPrompter): PathAction {
+  const binDir = join(mosaicHome, 'bin');
+  const currentPath = process.env['PATH'] ?? '';
+
+  if (currentPath.includes(binDir)) {
+    return 'already';
+  }
+
+  const profilePath = getShellProfilePath();
+  if (!profilePath) return 'skipped';
+
+  const isWindows = platform() === 'win32';
+  const exportLine = isWindows
+    ? `\n# Mosaic\n$env:Path = "${binDir};$env:Path"\n`
+    : `\n# Mosaic\nexport PATH="${binDir}:$PATH"\n`;
+
+  // Check if already in profile
+  if (existsSync(profilePath)) {
+    const content = readFileSync(profilePath, 'utf-8');
+    if (content.includes(binDir)) {
+      return 'already';
+    }
+  }
+
+  try {
+    appendFileSync(profilePath, exportLine, 'utf-8');
+    return 'added';
+  } catch {
+    return 'skipped';
+  }
+}
+
+export async function finalizeStage(
+  p: WizardPrompter,
+  state: WizardState,
+  config: ConfigService,
+): Promise<void> {
+  p.separator();
+
+  const spin = p.spinner();
+
+  // 1. Sync framework files (before config writes so identity files aren't overwritten)
+  spin.update('Syncing framework files...');
+  await config.syncFramework(state.installAction);
+
+  // 2. Write config files (after sync so they aren't overwritten by source templates)
+  if (state.installAction !== 'keep') {
+    spin.update('Writing configuration files...');
+    await config.writeSoul(state.soul);
+    await config.writeUser(state.user);
+    await config.writeTools(state.tools);
+  }
+
+  // 3. Link runtime assets
+  spin.update('Linking runtime assets...');
+  linkRuntimeAssets(state.mosaicHome);
+
+  // 4. Sync skills
+  if (state.selectedSkills.length > 0) {
+    spin.update('Syncing skills...');
+    syncSkills(state.mosaicHome);
+  }
+
+  // 5. Run doctor
+  spin.update('Running health audit...');
+  const doctorResult = runDoctor(state.mosaicHome);
+
+  spin.stop('Installation complete');
+
+  // 6. PATH setup
+  const pathAction = setupPath(state.mosaicHome, p);
+
+  // 7. Summary
+  const summary: string[] = [
+    `Agent: ${state.soul.agentName ?? 'Assistant'}`,
+    `Style: ${state.soul.communicationStyle ?? 'direct'}`,
+    `Runtimes: ${state.runtimes.detected.join(', ') || 'none detected'}`,
+    `Skills: ${state.selectedSkills.length.toString()} selected`,
+    `Config: ${state.mosaicHome}`,
+  ];
+
+  if (doctorResult.warnings > 0) {
+    summary.push(
+      `Health: ${doctorResult.warnings.toString()} warning(s) — run 'mosaic doctor' for details`,
+    );
+  } else {
+    summary.push('Health: all checks passed');
+  }
+
+  p.note(summary.join('\n'), 'Installation Summary');
+
+  // 8. Next steps
+  const nextSteps: string[] = [];
+  if (pathAction === 'added') {
+    const profilePath = getShellProfilePath();
+    nextSteps.push(`Reload shell: source ${profilePath ?? '~/.profile'}`);
+  }
+  if (state.runtimes.detected.length === 0) {
+    nextSteps.push('Install at least one runtime (claude, codex, or opencode)');
+  }
+  nextSteps.push("Launch with 'mosaic claude' (or codex/opencode)");
+  nextSteps.push('Edit identity files directly in ~/.config/mosaic/ for fine-tuning');
+
+  p.note(nextSteps.map((s, i) => `${(i + 1).toString()}. ${s}`).join('\n'), 'Next Steps');
+
+  p.outro('Mosaic is ready.');
+}

packages/mosaic/src/stages/mode-select.ts

@@ -0,0 +1,20 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState, WizardMode } from '../types.js';
+
+export async function modeSelectStage(p: WizardPrompter, state: WizardState): Promise<void> {
+  state.mode = await p.select<WizardMode>({
+    message: 'Installation mode',
+    options: [
+      {
+        value: 'quick',
+        label: 'Quick Start',
+        hint: 'Sensible defaults, minimal questions (~2 min)',
+      },
+      {
+        value: 'advanced',
+        label: 'Advanced',
+        hint: 'Full customization of identity, runtimes, and skills',
+      },
+    ],
+  });
+}

packages/mosaic/src/stages/runtime-setup.ts

@@ -0,0 +1,64 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState, RuntimeName } from '../types.js';
+import { detectRuntime, type RuntimeInfo } from '../runtime/detector.js';
+import { formatInstallInstructions } from '../runtime/installer.js';
+import { configureMcpForRuntime } from '../runtime/mcp-config.js';
+
+const RUNTIME_NAMES: RuntimeName[] = ['claude', 'codex', 'opencode'];
+
+export async function runtimeSetupStage(p: WizardPrompter, state: WizardState): Promise<void> {
+  p.separator();
+
+  const spin = p.spinner();
+  spin.update('Detecting installed runtimes...');
+
+  const runtimes: RuntimeInfo[] = RUNTIME_NAMES.map(detectRuntime);
+
+  spin.stop('Runtime detection complete');
+
+  const detected = runtimes.filter((r) => r.installed);
+  const notDetected = runtimes.filter((r) => !r.installed);
+
+  if (detected.length > 0) {
+    const summary = detected
+      .map((r) => `  ${r.label}: ${r.version ?? 'installed'} (${r.path ?? 'unknown'})`)
+      .join('\n');
+    p.note(summary, 'Detected Runtimes');
+  } else {
+    p.warn('No runtimes detected. Install at least one to use Mosaic.');
+  }
+
+  state.runtimes.detected = detected.map((r) => r.name);
+
+  // Offer installation info for missing runtimes in advanced mode
+  if (state.mode === 'advanced' && notDetected.length > 0) {
+    const showInstall = await p.confirm({
+      message: `${notDetected.length.toString()} runtime(s) not found. Show install instructions?`,
+      initialValue: false,
+    });
+
+    if (showInstall) {
+      for (const rt of notDetected) {
+        p.note(formatInstallInstructions(rt.name), `Install ${rt.label}`);
+      }
+    }
+  }
+
+  // Configure MCP sequential-thinking for detected runtimes
+  if (detected.length > 0) {
+    const spin2 = p.spinner();
+    spin2.update('Configuring sequential-thinking MCP...');
+    try {
+      for (const rt of detected) {
+        configureMcpForRuntime(rt.name);
+      }
+      spin2.stop('MCP sequential-thinking configured');
+      state.runtimes.mcpConfigured = true;
+    } catch (err) {
+      spin2.stop('MCP configuration failed (non-fatal)');
+      p.warn(
+        `MCP setup failed: ${err instanceof Error ? err.message : String(err)}. Run 'mosaic seq fix' later.`,
+      );
+    }
+  }
+}

packages/mosaic/src/stages/skills-select.ts

@@ -0,0 +1,77 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState } from '../types.js';
+import { loadSkillsCatalog } from '../skills/catalog.js';
+import { SKILL_CATEGORIES, categorizeSkill } from '../skills/categories.js';
+
+function truncate(str: string, max: number): string {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 1) + '\u2026';
+}
+
+export async function skillsSelectStage(p: WizardPrompter, state: WizardState): Promise<void> {
+  p.separator();
+
+  const spin = p.spinner();
+  spin.update('Loading skills catalog...');
+
+  const catalog = loadSkillsCatalog(state.mosaicHome);
+  spin.stop(`Found ${catalog.length.toString()} available skills`);
+
+  if (catalog.length === 0) {
+    p.warn("No skills found. Run 'mosaic sync' after installation to fetch skills.");
+    state.selectedSkills = [];
+    return;
+  }
+
+  if (state.mode === 'quick') {
+    const defaults = catalog.filter((s) => s.recommended).map((s) => s.name);
+    state.selectedSkills = defaults;
+    p.note(
+      `Selected ${defaults.length.toString()} recommended skills.\n` +
+        `Run 'mosaic sync' later to browse the full catalog.`,
+      'Skills',
+    );
+    return;
+  }
+
+  // Advanced mode: categorized browsing
+  p.note(
+    'Skills give agents domain expertise for specific tasks.\n' +
+      'Browse by category and select the ones you want.\n' +
+      "You can always change this later with 'mosaic sync'.",
+    'Skills Selection',
+  );
+
+  // Build grouped options
+  const grouped: Record<
+    string,
+    { value: string; label: string; hint?: string; selected?: boolean }[]
+  > = {};
+
+  // Initialize all categories
+  for (const categoryName of Object.keys(SKILL_CATEGORIES)) {
+    grouped[categoryName] = [];
+  }
+
+  for (const skill of catalog) {
+    const category = categorizeSkill(skill.name, skill.description);
+    if (!grouped[category]) grouped[category] = [];
+    grouped[category]!.push({
+      value: skill.name,
+      label: skill.name,
+      hint: truncate(skill.description, 60),
+      selected: skill.recommended,
+    });
+  }
+
+  // Remove empty categories
+  for (const key of Object.keys(grouped)) {
+    if ((grouped[key]?.length ?? 0) === 0) delete grouped[key];
+  }
+
+  state.selectedSkills = await p.groupMultiselect({
+    message: 'Select skills (space to toggle)',
+    options: grouped,
+    required: false,
+  });
+}

packages/mosaic/src/stages/soul-setup.ts

@@ -0,0 +1,70 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState, CommunicationStyle } from '../types.js';
+import { DEFAULTS } from '../constants.js';
+
+export async function soulSetupStage(p: WizardPrompter, state: WizardState): Promise<void> {
+  if (state.installAction === 'keep') return;
+
+  p.separator();
+  p.note(
+    'Your agent identity defines how AI assistants behave,\n' +
+      'their principles, and communication style.\n' +
+      'This creates SOUL.md.',
+    'Agent Identity',
+  );
+
+  if (!state.soul.agentName) {
+    state.soul.agentName = await p.text({
+      message: 'What name should agents use?',
+      placeholder: 'e.g., Jarvis, Assistant, Mosaic',
+      defaultValue: DEFAULTS.agentName,
+      validate: (v) => {
+        if (v.length === 0) return 'Name cannot be empty';
+        if (v.length > 50) return 'Name must be under 50 characters';
+        return undefined;
+      },
+    });
+  }
+
+  if (state.mode === 'advanced') {
+    if (!state.soul.roleDescription) {
+      state.soul.roleDescription = await p.text({
+        message: 'Agent role description',
+        placeholder: 'e.g., execution partner and visibility engine',
+        defaultValue: DEFAULTS.roleDescription,
+      });
+    }
+  } else {
+    state.soul.roleDescription ??= DEFAULTS.roleDescription;
+  }
+
+  if (!state.soul.communicationStyle) {
+    state.soul.communicationStyle = await p.select<CommunicationStyle>({
+      message: 'Communication style',
+      options: [
+        { value: 'direct', label: 'Direct', hint: 'Concise, no fluff, actionable' },
+        { value: 'friendly', label: 'Friendly', hint: 'Warm but efficient, conversational' },
+        { value: 'formal', label: 'Formal', hint: 'Professional, structured, thorough' },
+      ],
+      initialValue: 'direct',
+    });
+  }
+
+  if (state.mode === 'advanced') {
+    if (!state.soul.accessibility) {
+      state.soul.accessibility = await p.text({
+        message: 'Accessibility preferences',
+        placeholder: "e.g., ADHD-friendly chunking, dyslexia-aware formatting, or 'none'",
+        defaultValue: 'none',
+      });
+    }
+
+    if (!state.soul.customGuardrails) {
+      state.soul.customGuardrails = await p.text({
+        message: 'Custom guardrails (optional)',
+        placeholder: 'e.g., Never auto-commit to main',
+        defaultValue: '',
+      });
+    }
+  }
+}

packages/mosaic/src/stages/tools-setup.ts

@@ -0,0 +1,73 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState, GitProvider } from '../types.js';
+import { DEFAULTS } from '../constants.js';
+
+export async function toolsSetupStage(p: WizardPrompter, state: WizardState): Promise<void> {
+  if (state.installAction === 'keep') return;
+
+  if (state.mode === 'quick') {
+    state.tools.gitProviders = [];
+    state.tools.credentialsLocation = DEFAULTS.credentialsLocation;
+    state.tools.customToolsSection = DEFAULTS.customToolsSection;
+    return;
+  }
+
+  p.separator();
+  p.note(
+    'Tool configuration tells agents about your git providers,\n' +
+      'credential locations, and custom tools.\n' +
+      'This creates TOOLS.md.',
+    'Tool Reference',
+  );
+
+  const addProviders = await p.confirm({
+    message: 'Configure git providers?',
+    initialValue: false,
+  });
+
+  state.tools.gitProviders = [];
+  if (addProviders) {
+    let addMore = true;
+    while (addMore) {
+      const name = await p.text({
+        message: 'Provider name',
+        placeholder: 'e.g., Gitea, GitHub',
+      });
+      const url = await p.text({
+        message: 'Provider URL',
+        placeholder: 'e.g., https://github.com',
+      });
+      const cli = await p.select<string>({
+        message: 'CLI tool',
+        options: [
+          { value: 'gh', label: 'gh (GitHub CLI)' },
+          { value: 'tea', label: 'tea (Gitea CLI)' },
+          { value: 'glab', label: 'glab (GitLab CLI)' },
+        ],
+      });
+      const purpose = await p.text({
+        message: 'Purpose',
+        placeholder: 'e.g., Primary code hosting',
+        defaultValue: 'Code hosting',
+      });
+
+      state.tools.gitProviders.push({
+        name,
+        url,
+        cli,
+        purpose,
+      } satisfies GitProvider);
+
+      addMore = await p.confirm({
+        message: 'Add another provider?',
+        initialValue: false,
+      });
+    }
+  }
+
+  state.tools.credentialsLocation = await p.text({
+    message: 'Credential file path',
+    placeholder: "e.g., ~/.secrets/credentials.env, or 'none'",
+    defaultValue: DEFAULTS.credentialsLocation,
+  });
+}

packages/mosaic/src/stages/user-setup.ts

@@ -0,0 +1,77 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState } from '../types.js';
+import { DEFAULTS } from '../constants.js';
+import { buildCommunicationPrefs } from '../template/builders.js';
+
+export async function userSetupStage(p: WizardPrompter, state: WizardState): Promise<void> {
+  if (state.installAction === 'keep') return;
+
+  p.separator();
+  p.note(
+    'Your user profile helps agents understand your context,\n' +
+      'accessibility needs, and communication preferences.\n' +
+      'This creates USER.md.',
+    'User Profile',
+  );
+
+  if (!state.user.userName) {
+    state.user.userName = await p.text({
+      message: 'Your name',
+      placeholder: 'How agents should address you',
+      defaultValue: '',
+    });
+  }
+
+  if (!state.user.pronouns) {
+    state.user.pronouns = await p.text({
+      message: 'Your pronouns',
+      placeholder: 'e.g., He/Him, She/Her, They/Them',
+      defaultValue: DEFAULTS.pronouns,
+    });
+  }
+
+  // Auto-detect timezone
+  let detectedTz: string;
+  try {
+    detectedTz = Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    detectedTz = DEFAULTS.timezone;
+  }
+
+  if (!state.user.timezone) {
+    state.user.timezone = await p.text({
+      message: 'Your timezone',
+      placeholder: `e.g., ${detectedTz}`,
+      defaultValue: detectedTz,
+    });
+  }
+
+  if (state.mode === 'advanced') {
+    state.user.background = await p.text({
+      message: 'Professional background (brief)',
+      placeholder: 'e.g., Full-stack developer, 10 years TypeScript/React',
+      defaultValue: DEFAULTS.background,
+    });
+
+    state.user.accessibilitySection = await p.text({
+      message: 'Neurodivergence / accessibility accommodations',
+      placeholder: 'e.g., ADHD-friendly chunking, or press Enter to skip',
+      defaultValue: DEFAULTS.accessibilitySection,
+    });
+
+    state.user.personalBoundaries = await p.text({
+      message: 'Personal boundaries for agents',
+      placeholder: 'e.g., No unsolicited career advice, or press Enter to skip',
+      defaultValue: DEFAULTS.personalBoundaries,
+    });
+  } else {
+    state.user.background = DEFAULTS.background;
+    state.user.accessibilitySection = DEFAULTS.accessibilitySection;
+    state.user.personalBoundaries = DEFAULTS.personalBoundaries;
+  }
+
+  // Derive communication preferences from SOUL style
+  state.user.communicationPrefs = buildCommunicationPrefs(
+    state.soul.communicationStyle ?? 'direct',
+  );
+}

packages/mosaic/src/stages/welcome.ts

@@ -0,0 +1,15 @@
+import type { WizardPrompter } from '../prompter/interface.js';
+import type { WizardState } from '../types.js';
+import { VERSION } from '../constants.js';
+
+export async function welcomeStage(p: WizardPrompter, _state: WizardState): Promise<void> {
+  p.intro(`Mosaic Installation Wizard v${VERSION}`);
+  p.note(
+    `Mosaic is an agent framework that gives AI coding assistants\n` +
+      `a persistent identity, shared skills, and structured workflows.\n\n` +
+      `It works with Claude Code, Codex, and OpenCode.\n\n` +
+      `All config is stored locally in ~/.config/mosaic/.\n` +
+      `No data is sent anywhere. No accounts required.`,
+    'What is Mosaic?',
+  );
+}

packages/mosaic/src/template/builders.ts

@@ -0,0 +1,144 @@
+import type {
+  CommunicationStyle,
+  SoulConfig,
+  UserConfig,
+  ToolsConfig,
+  GitProvider,
+} from '../types.js';
+import { DEFAULTS } from '../constants.js';
+import type { TemplateVars } from './engine.js';
+
+/**
+ * Build behavioral principles text based on communication style.
+ * Replicates mosaic-init lines 177-204 exactly.
+ */
+function buildBehavioralPrinciples(style: CommunicationStyle, accessibility?: string): string {
+  let principles: string;
+
+  switch (style) {
+    case 'direct':
+      principles = `1. Clarity over performance theater.
+2. Practical execution over abstract planning.
+3. Truthfulness over confidence: state uncertainty explicitly.
+4. Visible state over hidden assumptions.
+5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations.`;
+      break;
+    case 'friendly':
+      principles = `1. Be helpful and approachable while staying efficient.
+2. Provide context and explain reasoning when helpful.
+3. Truthfulness over confidence: state uncertainty explicitly.
+4. Visible state over hidden assumptions.
+5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations.`;
+      break;
+    case 'formal':
+      principles = `1. Maintain professional, structured communication.
+2. Provide thorough analysis with explicit tradeoffs.
+3. Truthfulness over confidence: state uncertainty explicitly.
+4. Document decisions and rationale clearly.
+5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations.`;
+      break;
+  }
+
+  if (accessibility && accessibility !== 'none' && accessibility.length > 0) {
+    principles += `\n6. ${accessibility}.`;
+  }
+
+  return principles;
+}
+
+/**
+ * Build communication style text based on style choice.
+ * Replicates mosaic-init lines 208-227 exactly.
+ */
+function buildCommunicationStyleText(style: CommunicationStyle): string {
+  switch (style) {
+    case 'direct':
+      return `- Be direct, concise, and concrete.
+- Avoid fluff, hype, and anthropomorphic roleplay.
+- Do not simulate certainty when facts are missing.
+- Prefer actionable next steps and explicit tradeoffs.`;
+    case 'friendly':
+      return `- Be warm and conversational while staying focused.
+- Explain your reasoning when it helps the user.
+- Do not simulate certainty when facts are missing.
+- Prefer actionable next steps with clear context.`;
+    case 'formal':
+      return `- Use professional, structured language.
+- Provide thorough explanations with supporting detail.
+- Do not simulate certainty when facts are missing.
+- Present options with explicit tradeoffs and recommendations.`;
+  }
+}
+
+/**
+ * Build communication preferences for USER.md based on style.
+ * Replicates mosaic-init lines 299-316 exactly.
+ */
+export function buildCommunicationPrefs(style: CommunicationStyle): string {
+  switch (style) {
+    case 'direct':
+      return `- Direct and concise
+- No sycophancy
+- Executive summaries and tables for overview`;
+    case 'friendly':
+      return `- Warm and conversational
+- Explain reasoning when helpful
+- Balance thoroughness with brevity`;
+    case 'formal':
+      return `- Professional and structured
+- Thorough explanations with supporting detail
+- Formal tone with explicit recommendations`;
+  }
+}
+
+/**
+ * Build git providers markdown table from provider list.
+ * Replicates mosaic-init lines 362-384.
+ */
+function buildGitProvidersTable(providers?: GitProvider[]): string {
+  if (!providers || providers.length === 0) {
+    return DEFAULTS.gitProvidersTable;
+  }
+
+  const rows = providers
+    .map((p) => `| ${p.name} | ${p.url} | \`${p.cli}\` | ${p.purpose} |`)
+    .join('\n');
+
+  return `| Instance | URL | CLI | Purpose |
+|----------|-----|-----|---------|
+${rows}`;
+}
+
+export function buildSoulTemplateVars(config: SoulConfig): TemplateVars {
+  const style = config.communicationStyle ?? 'direct';
+  const guardrails = config.customGuardrails ? `- ${config.customGuardrails}` : '';
+
+  return {
+    AGENT_NAME: config.agentName ?? DEFAULTS.agentName,
+    ROLE_DESCRIPTION: config.roleDescription ?? DEFAULTS.roleDescription,
+    BEHAVIORAL_PRINCIPLES: buildBehavioralPrinciples(style, config.accessibility),
+    COMMUNICATION_STYLE: buildCommunicationStyleText(style),
+    CUSTOM_GUARDRAILS: guardrails,
+  };
+}
+
+export function buildUserTemplateVars(config: UserConfig): TemplateVars {
+  return {
+    USER_NAME: config.userName ?? '',
+    PRONOUNS: config.pronouns ?? DEFAULTS.pronouns,
+    TIMEZONE: config.timezone ?? DEFAULTS.timezone,
+    BACKGROUND: config.background ?? DEFAULTS.background,
+    ACCESSIBILITY_SECTION: config.accessibilitySection ?? DEFAULTS.accessibilitySection,
+    COMMUNICATION_PREFS: config.communicationPrefs ?? buildCommunicationPrefs('direct'),
+    PERSONAL_BOUNDARIES: config.personalBoundaries ?? DEFAULTS.personalBoundaries,
+    PROJECTS_TABLE: config.projectsTable ?? DEFAULTS.projectsTable,
+  };
+}
+
+export function buildToolsTemplateVars(config: ToolsConfig): TemplateVars {
+  return {
+    GIT_PROVIDERS_TABLE: buildGitProvidersTable(config.gitProviders),
+    CREDENTIALS_LOCATION: config.credentialsLocation ?? DEFAULTS.credentialsLocation,
+    CUSTOM_TOOLS_SECTION: config.customToolsSection ?? DEFAULTS.customToolsSection,
+  };
+}

packages/mosaic/src/template/engine.ts

@@ -0,0 +1,23 @@
+export interface TemplateVars {
+  [key: string]: string;
+}
+
+/**
+ * Replaces {{PLACEHOLDER}} tokens with provided values.
+ * Does NOT expand ${ENV_VAR} syntax — those pass through for shell resolution.
+ */
+export function renderTemplate(
+  template: string,
+  vars: TemplateVars,
+  options: { strict?: boolean } = {},
+): string {
+  return template.replace(/\{\{([A-Z_][A-Z0-9_]*)\}\}/g, (match, varName: string) => {
+    if (varName in vars) {
+      return vars[varName] ?? '';
+    }
+    if (options.strict) {
+      throw new Error(`Template variable not provided: {{${varName}}}`);
+    }
+    return '';
+  });
+}

packages/mosaic/src/types.ts

@@ -0,0 +1,53 @@
+export type WizardMode = 'quick' | 'advanced';
+export type InstallAction = 'fresh' | 'keep' | 'reconfigure' | 'reset';
+export type CommunicationStyle = 'direct' | 'friendly' | 'formal';
+export type RuntimeName = 'claude' | 'codex' | 'opencode';
+
+export interface SoulConfig {
+  agentName?: string;
+  roleDescription?: string;
+  communicationStyle?: CommunicationStyle;
+  accessibility?: string;
+  customGuardrails?: string;
+}
+
+export interface UserConfig {
+  userName?: string;
+  pronouns?: string;
+  timezone?: string;
+  background?: string;
+  accessibilitySection?: string;
+  communicationPrefs?: string;
+  personalBoundaries?: string;
+  projectsTable?: string;
+}
+
+export interface GitProvider {
+  name: string;
+  url: string;
+  cli: string;
+  purpose: string;
+}
+
+export interface ToolsConfig {
+  gitProviders?: GitProvider[];
+  credentialsLocation?: string;
+  customToolsSection?: string;
+}
+
+export interface RuntimeState {
+  detected: RuntimeName[];
+  mcpConfigured: boolean;
+}
+
+export interface WizardState {
+  mosaicHome: string;
+  sourceDir: string;
+  mode: WizardMode;
+  installAction: InstallAction;
+  soul: SoulConfig;
+  user: UserConfig;
+  tools: ToolsConfig;
+  runtimes: RuntimeState;
+  selectedSkills: string[];
+}