fix(packages): bump db/memory/queue for PGlite + adapter factories

Same class of bug as #386: source content changed without a version
bump, so the published tarballs on Gitea are stale and missing exports
that the gateway imports at runtime.

- @mosaic/db@0.0.2 registry tarball has no client-pglite.* files —
  gateway crashes with "does not provide an export named createPgliteDb"
  (createPgliteDb was added in fc7fa119 without bumping the version)
- @mosaic/memory@0.0.2 is missing factory.* / types.* on registry
- @mosaic/queue@0.0.2 is missing factory.* / types.* on registry

Bumps:
- @mosaic/db 0.0.2 → 0.0.3
- @mosaic/memory 0.0.2 → 0.0.3
- @mosaic/queue 0.0.2 → 0.0.3
- @mosaic/gateway 0.0.5 → 0.0.6 (required because ^0.0.2 in sub-1.0
  semver only matches 0.0.2 exactly, so gateway must republish with
  ^0.0.3 deps)

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

.env.example

@@ -23,8 +23,8 @@ VALKEY_URL=redis://localhost:6380
 
 
 # ─── Gateway ─────────────────────────────────────────────────────────────────
-# TCP port the NestJS/Fastify gateway listens on (default: 4000)
-GATEWAY_PORT=4000
+# TCP port the NestJS/Fastify gateway listens on (default: 14242)
+GATEWAY_PORT=14242
 
 # Comma-separated list of allowed CORS origins.
 # Must include the web app origin in production.
@@ -37,12 +37,12 @@ GATEWAY_CORS_ORIGIN=http://localhost:3000
 BETTER_AUTH_SECRET=change-me-to-a-random-32-char-string
 
 # Public base URL of the gateway (used by BetterAuth for callback URLs)
-BETTER_AUTH_URL=http://localhost:4000
+BETTER_AUTH_URL=http://localhost:14242
 
 
 # ─── Web App (Next.js) ───────────────────────────────────────────────────────
 # Public gateway URL — accessible from the browser, not just the server.
-NEXT_PUBLIC_GATEWAY_URL=http://localhost:4000
+NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
 
 
 # ─── OpenTelemetry ───────────────────────────────────────────────────────────
@@ -121,12 +121,12 @@ OTEL_SERVICE_NAME=mosaic-gateway
 # ─── Discord Plugin (optional — set DISCORD_BOT_TOKEN to enable) ─────────────
 # DISCORD_BOT_TOKEN=
 # DISCORD_GUILD_ID=
-# DISCORD_GATEWAY_URL=http://localhost:4000
+# DISCORD_GATEWAY_URL=http://localhost:14242
 
 
 # ─── Telegram Plugin (optional — set TELEGRAM_BOT_TOKEN to enable) ───────────
 # TELEGRAM_BOT_TOKEN=
-# TELEGRAM_GATEWAY_URL=http://localhost:4000
+# TELEGRAM_GATEWAY_URL=http://localhost:14242
 
 
 # ─── SSO Providers (add credentials to enable) ───────────────────────────────

.woodpecker/ci.yml

@@ -15,6 +15,7 @@ steps:
     image: *node_image
     commands:
       - corepack enable
+      - apk add --no-cache python3 make g++
       - pnpm install --frozen-lockfile
 
   typecheck:

.woodpecker/publish.yml

@@ -35,17 +35,31 @@ steps:
       - |
         echo "//git.mosaicstack.dev/api/packages/mosaic/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
         echo "@mosaic:registry=https://git.mosaicstack.dev/api/packages/mosaic/npm/" >> ~/.npmrc
-      # Publish all non-private packages (--no-git-checks skips dirty/branch checks in CI)
-      # --filter excludes private apps (gateway, web) and the root
+      # Publish non-private packages to Gitea (--no-git-checks skips dirty/branch checks in CI)
+      # --filter excludes web (private)
       - >
         pnpm --filter "@mosaic/*"
-        --filter "!@mosaic/gateway"
         --filter "!@mosaic/web"
         publish --no-git-checks --access public
         || echo "[publish] Some packages may already exist at this version — continuing"
     depends_on:
       - build
 
+  # TODO: Uncomment when ready to publish to npmjs.org
+  # publish-npmjs:
+  #   image: *node_image
+  #   environment:
+  #     NPM_TOKEN:
+  #       from_secret: npmjs_token
+  #   commands:
+  #     - *enable_pnpm
+  #     - apk add --no-cache jq bash
+  #     - bash scripts/publish-npmjs.sh
+  #   depends_on:
+  #     - build
+  #   when:
+  #     - event: [tag]
+
   build-gateway:
     image: gcr.io/kaniko-project/executor:debug
     environment:

apps/gateway/package.json

@@ -1,9 +1,23 @@
 {
   "name": "@mosaic/gateway",
-  "version": "0.0.2",
-  "private": true,
+  "version": "0.0.6",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "apps/gateway"
+  },
   "type": "module",
   "main": "dist/main.js",
+  "bin": {
+    "mosaic-gateway": "dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaic/npm/",
+    "access": "public"
+  },
   "scripts": {
     "build": "tsc",
     "dev": "tsx watch src/main.ts",
@@ -14,17 +28,19 @@
   "dependencies": {
     "@anthropic-ai/sdk": "^0.80.0",
     "@fastify/helmet": "^13.0.2",
-    "@mariozechner/pi-ai": "~0.57.1",
-    "@mariozechner/pi-coding-agent": "~0.57.1",
+    "@mariozechner/pi-ai": "^0.65.0",
+    "@mariozechner/pi-coding-agent": "^0.65.0",
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@mosaic/auth": "workspace:^",
     "@mosaic/brain": "workspace:^",
+    "@mosaic/config": "workspace:^",
     "@mosaic/coord": "workspace:^",
     "@mosaic/db": "workspace:^",
     "@mosaic/discord-plugin": "workspace:^",
     "@mosaic/log": "workspace:^",
     "@mosaic/memory": "workspace:^",
     "@mosaic/queue": "workspace:^",
+    "@mosaic/storage": "workspace:^",
     "@mosaic/telegram-plugin": "workspace:^",
     "@mosaic/types": "workspace:^",
     "@nestjs/common": "^11.0.0",
@@ -33,7 +49,7 @@
     "@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/auto-instrumentations-node": "^0.72.0",
     "@opentelemetry/exporter-metrics-otlp-http": "^0.213.0",
     "@opentelemetry/exporter-trace-otlp-http": "^0.213.0",
     "@opentelemetry/resources": "^2.6.0",

apps/gateway/src/admin/admin-tokens.controller.ts

@@ -0,0 +1,90 @@
+import {
+  Body,
+  Controller,
+  Delete,
+  Get,
+  HttpCode,
+  HttpStatus,
+  Inject,
+  Param,
+  Post,
+  UseGuards,
+} from '@nestjs/common';
+import { randomBytes, createHash } from 'node:crypto';
+import { eq, type Db, adminTokens } from '@mosaic/db';
+import { v4 as uuid } from 'uuid';
+import { DB } from '../database/database.module.js';
+import { AdminGuard } from './admin.guard.js';
+import { CurrentUser } from '../auth/current-user.decorator.js';
+import type {
+  CreateTokenDto,
+  TokenCreatedDto,
+  TokenDto,
+  TokenListDto,
+} from './admin-tokens.dto.js';
+
+function hashToken(plaintext: string): string {
+  return createHash('sha256').update(plaintext).digest('hex');
+}
+
+function toTokenDto(row: typeof adminTokens.$inferSelect): TokenDto {
+  return {
+    id: row.id,
+    label: row.label,
+    scope: row.scope,
+    expiresAt: row.expiresAt?.toISOString() ?? null,
+    lastUsedAt: row.lastUsedAt?.toISOString() ?? null,
+    createdAt: row.createdAt.toISOString(),
+  };
+}
+
+@Controller('api/admin/tokens')
+@UseGuards(AdminGuard)
+export class AdminTokensController {
+  constructor(@Inject(DB) private readonly db: Db) {}
+
+  @Post()
+  async create(
+    @Body() dto: CreateTokenDto,
+    @CurrentUser() user: { id: string },
+  ): Promise<TokenCreatedDto> {
+    const plaintext = randomBytes(32).toString('hex');
+    const tokenHash = hashToken(plaintext);
+    const id = uuid();
+
+    const expiresAt = dto.expiresInDays
+      ? new Date(Date.now() + dto.expiresInDays * 24 * 60 * 60 * 1000)
+      : null;
+
+    const [row] = await this.db
+      .insert(adminTokens)
+      .values({
+        id,
+        userId: user.id,
+        tokenHash,
+        label: dto.label ?? 'CLI token',
+        scope: dto.scope ?? 'admin',
+        expiresAt,
+      })
+      .returning();
+
+    return { ...toTokenDto(row!), plaintext };
+  }
+
+  @Get()
+  async list(@CurrentUser() user: { id: string }): Promise<TokenListDto> {
+    const rows = await this.db
+      .select()
+      .from(adminTokens)
+      .where(eq(adminTokens.userId, user.id))
+      .orderBy(adminTokens.createdAt);
+
+    return { tokens: rows.map(toTokenDto), total: rows.length };
+  }
+
+  @Delete(':id')
+  @HttpCode(HttpStatus.NO_CONTENT)
+  async revoke(@Param('id') id: string, @CurrentUser() _user: { id: string }): Promise<void> {
+    await this.db.delete(adminTokens).where(eq(adminTokens.id, id));
+  }
+}

apps/gateway/src/admin/admin-tokens.dto.ts

@@ -0,0 +1,33 @@
+import { IsString, IsOptional, IsInt, Min } from 'class-validator';
+
+export class CreateTokenDto {
+  @IsString()
+  label!: string;
+
+  @IsOptional()
+  @IsString()
+  scope?: string;
+
+  @IsOptional()
+  @IsInt()
+  @Min(1)
+  expiresInDays?: number;
+}
+
+export interface TokenDto {
+  id: string;
+  label: string;
+  scope: string;
+  expiresAt: string | null;
+  lastUsedAt: string | null;
+  createdAt: string;
+}
+
+export interface TokenCreatedDto extends TokenDto {
+  plaintext: string;
+}
+
+export interface TokenListDto {
+  tokens: TokenDto[];
+  total: number;
+}

apps/gateway/src/admin/admin.guard.ts

@@ -6,10 +6,11 @@ import {
   Injectable,
   UnauthorizedException,
 } from '@nestjs/common';
+import { createHash } from 'node:crypto';
 import { fromNodeHeaders } from 'better-auth/node';
 import type { Auth } from '@mosaic/auth';
 import type { Db } from '@mosaic/db';
-import { eq, users as usersTable } from '@mosaic/db';
+import { eq, adminTokens, users as usersTable } from '@mosaic/db';
 import type { FastifyRequest } from 'fastify';
 import { AUTH } from '../auth/auth.tokens.js';
 import { DB } from '../database/database.module.js';
@@ -19,6 +20,8 @@ interface UserWithRole {
   role?: string;
 }
 
+type AuthenticatedRequest = FastifyRequest & { user: unknown; session: unknown };
+
 @Injectable()
 export class AdminGuard implements CanActivate {
   constructor(
@@ -28,8 +31,64 @@ export class AdminGuard implements CanActivate {
 
   async canActivate(context: ExecutionContext): Promise<boolean> {
     const request = context.switchToHttp().getRequest<FastifyRequest>();
-    const headers = fromNodeHeaders(request.raw.headers);
 
+    // Try bearer token auth first
+    const authHeader = request.raw.headers['authorization'];
+    if (authHeader?.startsWith('Bearer ')) {
+      return this.validateBearerToken(request, authHeader.slice(7));
+    }
+
+    // Fall back to BetterAuth session
+    return this.validateSession(request);
+  }
+
+  private async validateBearerToken(request: FastifyRequest, plaintext: string): Promise<boolean> {
+    const tokenHash = createHash('sha256').update(plaintext).digest('hex');
+
+    const [row] = await this.db
+      .select({
+        tokenId: adminTokens.id,
+        userId: adminTokens.userId,
+        scope: adminTokens.scope,
+        expiresAt: adminTokens.expiresAt,
+        userName: usersTable.name,
+        userEmail: usersTable.email,
+        userRole: usersTable.role,
+      })
+      .from(adminTokens)
+      .innerJoin(usersTable, eq(adminTokens.userId, usersTable.id))
+      .where(eq(adminTokens.tokenHash, tokenHash))
+      .limit(1);
+
+    if (!row) {
+      throw new UnauthorizedException('Invalid API token');
+    }
+
+    if (row.expiresAt && row.expiresAt < new Date()) {
+      throw new UnauthorizedException('API token expired');
+    }
+
+    if (row.userRole !== 'admin') {
+      throw new ForbiddenException('Admin access required');
+    }
+
+    // Update last-used timestamp (fire-and-forget)
+    this.db
+      .update(adminTokens)
+      .set({ lastUsedAt: new Date() })
+      .where(eq(adminTokens.id, row.tokenId))
+      .then(() => {})
+      .catch(() => {});
+
+    const req = request as AuthenticatedRequest;
+    req.user = { id: row.userId, name: row.userName, email: row.userEmail, role: row.userRole };
+    req.session = { id: `token:${row.tokenId}`, userId: row.userId };
+
+    return true;
+  }
+
+  private async validateSession(request: FastifyRequest): Promise<boolean> {
+    const headers = fromNodeHeaders(request.raw.headers);
     const result = await this.auth.api.getSession({ headers });
 
     if (!result) {
@@ -38,8 +97,6 @@ export class AdminGuard implements CanActivate {
 
     const user = result.user as UserWithRole;
 
-    // Ensure the role field is populated. better-auth should include additionalFields
-    // in the session, but as a fallback, fetch the role from the database if needed.
     let userRole = user.role;
     if (!userRole) {
       const [dbUser] = await this.db
@@ -48,7 +105,6 @@ export class AdminGuard implements CanActivate {
         .where(eq(usersTable.id, user.id))
         .limit(1);
       userRole = dbUser?.role ?? 'member';
-      // Update the session user object with the fetched role
       (user as UserWithRole).role = userRole;
     }
 
@@ -56,8 +112,9 @@ export class AdminGuard implements CanActivate {
       throw new ForbiddenException('Admin access required');
     }
 
-    (request as FastifyRequest & { user: unknown; session: unknown }).user = result.user;
-    (request as FastifyRequest & { user: unknown; session: unknown }).session = result.session;
+    const req = request as AuthenticatedRequest;
+    req.user = result.user;
+    req.session = result.session;
 
     return true;
   }

apps/gateway/src/admin/admin.module.ts

@@ -2,10 +2,18 @@ import { Module } from '@nestjs/common';
 import { AdminController } from './admin.controller.js';
 import { AdminHealthController } from './admin-health.controller.js';
 import { AdminJobsController } from './admin-jobs.controller.js';
+import { AdminTokensController } from './admin-tokens.controller.js';
+import { BootstrapController } from './bootstrap.controller.js';
 import { AdminGuard } from './admin.guard.js';
 
 @Module({
-  controllers: [AdminController, AdminHealthController, AdminJobsController],
+  controllers: [
+    AdminController,
+    AdminHealthController,
+    AdminJobsController,
+    AdminTokensController,
+    BootstrapController,
+  ],
   providers: [AdminGuard],
 })
 export class AdminModule {}

apps/gateway/src/admin/bootstrap.controller.ts

@@ -0,0 +1,101 @@
+import {
+  Body,
+  Controller,
+  ForbiddenException,
+  Get,
+  Inject,
+  InternalServerErrorException,
+  Post,
+} from '@nestjs/common';
+import { randomBytes, createHash } from 'node:crypto';
+import { count, eq, type Db, users as usersTable, adminTokens } from '@mosaic/db';
+import type { Auth } from '@mosaic/auth';
+import { v4 as uuid } from 'uuid';
+import { AUTH } from '../auth/auth.tokens.js';
+import { DB } from '../database/database.module.js';
+import type { BootstrapSetupDto, BootstrapStatusDto, BootstrapResultDto } from './bootstrap.dto.js';
+
+@Controller('api/bootstrap')
+export class BootstrapController {
+  constructor(
+    @Inject(AUTH) private readonly auth: Auth,
+    @Inject(DB) private readonly db: Db,
+  ) {}
+
+  @Get('status')
+  async status(): Promise<BootstrapStatusDto> {
+    const [result] = await this.db.select({ total: count() }).from(usersTable);
+    return { needsSetup: (result?.total ?? 0) === 0 };
+  }
+
+  @Post('setup')
+  async setup(@Body() dto: BootstrapSetupDto): Promise<BootstrapResultDto> {
+    // Only allow setup when zero users exist
+    const [result] = await this.db.select({ total: count() }).from(usersTable);
+    if ((result?.total ?? 0) > 0) {
+      throw new ForbiddenException('Setup already completed — users exist');
+    }
+
+    // Create admin user via BetterAuth API
+    const authApi = this.auth.api as unknown as {
+      createUser: (opts: {
+        body: { name: string; email: string; password: string; role?: string };
+      }) => Promise<{
+        user: { id: string; name: string; email: string };
+      }>;
+    };
+
+    const created = await authApi.createUser({
+      body: {
+        name: dto.name,
+        email: dto.email,
+        password: dto.password,
+        role: 'admin',
+      },
+    });
+
+    // Verify user was created
+    const [user] = await this.db
+      .select()
+      .from(usersTable)
+      .where(eq(usersTable.id, created.user.id))
+      .limit(1);
+
+    if (!user) throw new InternalServerErrorException('User created but not found');
+
+    // Ensure role is admin (createUser may not set it via BetterAuth)
+    if (user.role !== 'admin') {
+      await this.db.update(usersTable).set({ role: 'admin' }).where(eq(usersTable.id, user.id));
+    }
+
+    // Generate admin API token
+    const plaintext = randomBytes(32).toString('hex');
+    const tokenHash = createHash('sha256').update(plaintext).digest('hex');
+    const tokenId = uuid();
+
+    const [token] = await this.db
+      .insert(adminTokens)
+      .values({
+        id: tokenId,
+        userId: user.id,
+        tokenHash,
+        label: 'Initial setup token',
+        scope: 'admin',
+      })
+      .returning();
+
+    return {
+      user: {
+        id: user.id,
+        name: user.name,
+        email: user.email,
+        role: 'admin',
+      },
+      token: {
+        id: token!.id,
+        plaintext,
+        label: token!.label,
+      },
+    };
+  }
+}

apps/gateway/src/admin/bootstrap.dto.ts

@@ -0,0 +1,31 @@
+import { IsString, IsEmail, MinLength } from 'class-validator';
+
+export class BootstrapSetupDto {
+  @IsString()
+  name!: string;
+
+  @IsEmail()
+  email!: string;
+
+  @IsString()
+  @MinLength(8)
+  password!: string;
+}
+
+export interface BootstrapStatusDto {
+  needsSetup: boolean;
+}
+
+export interface BootstrapResultDto {
+  user: {
+    id: string;
+    name: string;
+    email: string;
+    role: string;
+  };
+  token: {
+    id: string;
+    plaintext: string;
+    label: string;
+  };
+}

apps/gateway/src/agent/__tests__/provider-adapters.test.ts

@@ -62,7 +62,7 @@ function restoreEnv(saved: Map<EnvKey, string | undefined>): void {
 }
 
 function makeRegistry(): ModelRegistry {
-  return new ModelRegistry(AuthStorage.inMemory());
+  return ModelRegistry.inMemory(AuthStorage.inMemory());
 }
 
 // ---------------------------------------------------------------------------

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

@@ -67,7 +67,7 @@ export class ProviderService implements OnModuleInit, OnModuleDestroy {
 
   async onModuleInit(): Promise<void> {
     const authStorage = AuthStorage.inMemory();
-    this.registry = new ModelRegistry(authStorage);
+    this.registry = ModelRegistry.inMemory(authStorage);
 
     // Build the default set of adapters that rely on the registry
     this.adapters = [

apps/gateway/src/app.module.ts

@@ -1,6 +1,7 @@
 import { Module } from '@nestjs/common';
 import { APP_GUARD } from '@nestjs/core';
 import { HealthController } from './health/health.controller.js';
+import { ConfigModule } from './config/config.module.js';
 import { DatabaseModule } from './database/database.module.js';
 import { AuthModule } from './auth/auth.module.js';
 import { BrainModule } from './brain/brain.module.js';
@@ -28,6 +29,7 @@ import { ThrottlerGuard, ThrottlerModule } from '@nestjs/throttler';
 @Module({
   imports: [
     ThrottlerModule.forRoot([{ name: 'default', ttl: 60_000, limit: 60 }]),
+    ConfigModule,
     DatabaseModule,
     AuthModule,
     BrainModule,

apps/gateway/src/auth/auth.module.ts

@@ -14,7 +14,7 @@ import { SsoController } from './sso.controller.js';
       useFactory: (db: Db): Auth =>
         createAuth({
           db,
-          baseURL: process.env['BETTER_AUTH_URL'] ?? 'http://localhost:4000',
+          baseURL: process.env['BETTER_AUTH_URL'] ?? 'http://localhost:14242',
           secret: process.env['BETTER_AUTH_SECRET'],
         }),
       inject: [DB],

apps/gateway/src/config/config.module.ts

@@ -0,0 +1,16 @@
+import { Global, Module } from '@nestjs/common';
+import { loadConfig, type MosaicConfig } from '@mosaic/config';
+
+export const MOSAIC_CONFIG = 'MOSAIC_CONFIG';
+
+@Global()
+@Module({
+  providers: [
+    {
+      provide: MOSAIC_CONFIG,
+      useFactory: (): MosaicConfig => loadConfig(),
+    },
+  ],
+  exports: [MOSAIC_CONFIG],
+})
+export class ConfigModule {}

apps/gateway/src/database/database.module.ts

@@ -1,28 +1,51 @@
+import { mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
 import { Global, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-import { createDb, type Db, type DbHandle } from '@mosaic/db';
+import { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaic/db';
+import { createStorageAdapter, type StorageAdapter } from '@mosaic/storage';
+import type { MosaicConfig } from '@mosaic/config';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 
 export const DB_HANDLE = 'DB_HANDLE';
 export const DB = 'DB';
+export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
 
 @Global()
 @Module({
   providers: [
     {
       provide: DB_HANDLE,
-      useFactory: (): DbHandle => createDb(),
+      useFactory: (config: MosaicConfig): DbHandle => {
+        if (config.tier === 'local') {
+          const dataDir = join(homedir(), '.config', 'mosaic', 'gateway', 'pglite');
+          mkdirSync(dataDir, { recursive: true });
+          return createPgliteDb(dataDir);
+        }
+        return createDb(config.storage.type === 'postgres' ? config.storage.url : undefined);
+      },
+      inject: [MOSAIC_CONFIG],
     },
     {
       provide: DB,
       useFactory: (handle: DbHandle): Db => handle.db,
       inject: [DB_HANDLE],
     },
+    {
+      provide: STORAGE_ADAPTER,
+      useFactory: (config: MosaicConfig): StorageAdapter => createStorageAdapter(config.storage),
+      inject: [MOSAIC_CONFIG],
+    },
   ],
-  exports: [DB],
+  exports: [DB, STORAGE_ADAPTER],
 })
 export class DatabaseModule implements OnApplicationShutdown {
-  constructor(@Inject(DB_HANDLE) private readonly handle: DbHandle) {}
+  constructor(
+    @Inject(DB_HANDLE) private readonly handle: DbHandle,
+    @Inject(STORAGE_ADAPTER) private readonly storageAdapter: StorageAdapter,
+  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await this.handle.close();
+    await Promise.all([this.handle.close(), this.storageAdapter.close()]);
   }
 }

apps/gateway/src/main.ts

@@ -1,5 +1,13 @@
+#!/usr/bin/env node
 import { config } from 'dotenv';
-import { resolve } from 'node:path';
+import { existsSync } from 'node:fs';
+import { resolve, join } from 'node:path';
+import { homedir } from 'node:os';
+
+// Load .env from daemon config dir (global install / daemon mode).
+// Loaded first so monorepo .env can override for local dev.
+const daemonEnv = join(homedir(), '.config', 'mosaic', 'gateway', '.env');
+if (existsSync(daemonEnv)) config({ path: daemonEnv });
 
 // Load .env from monorepo root (cwd is apps/gateway when run via pnpm filter)
 config({ path: resolve(process.cwd(), '../../.env') });
@@ -51,7 +59,7 @@ async function bootstrap(): Promise<void> {
   mountAuthHandler(app);
   mountMcpHandler(app, app.get(McpService));
 
-  const port = Number(process.env['GATEWAY_PORT'] ?? 4000);
+  const port = Number(process.env['GATEWAY_PORT'] ?? 14242);
   await app.listen(port, '0.0.0.0');
   logger.log(`Gateway listening on port ${port}`);
 }

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

@@ -1,11 +1,29 @@
 import { Global, Module } from '@nestjs/common';
-import { createMemory, type Memory } from '@mosaic/memory';
+import {
+  createMemory,
+  type Memory,
+  createMemoryAdapter,
+  type MemoryAdapter,
+  type MemoryConfig,
+} from '@mosaic/memory';
 import type { Db } from '@mosaic/db';
-import { DB } from '../database/database.module.js';
+import type { StorageAdapter } from '@mosaic/storage';
+import type { MosaicConfig } from '@mosaic/config';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
+import { DB, STORAGE_ADAPTER } from '../database/database.module.js';
 import { MEMORY } from './memory.tokens.js';
 import { MemoryController } from './memory.controller.js';
 import { EmbeddingService } from './embedding.service.js';
 
+export const MEMORY_ADAPTER = 'MEMORY_ADAPTER';
+
+function buildMemoryConfig(config: MosaicConfig, storageAdapter: StorageAdapter): MemoryConfig {
+  if (config.memory.type === 'keyword') {
+    return { type: 'keyword', storage: storageAdapter };
+  }
+  return { type: config.memory.type };
+}
+
 @Global()
 @Module({
   providers: [
@@ -14,9 +32,15 @@ import { EmbeddingService } from './embedding.service.js';
       useFactory: (db: Db): Memory => createMemory(db),
       inject: [DB],
     },
+    {
+      provide: MEMORY_ADAPTER,
+      useFactory: (config: MosaicConfig, storageAdapter: StorageAdapter): MemoryAdapter =>
+        createMemoryAdapter(buildMemoryConfig(config, storageAdapter)),
+      inject: [MOSAIC_CONFIG, STORAGE_ADAPTER],
+    },
     EmbeddingService,
   ],
   controllers: [MemoryController],
-  exports: [MEMORY, EmbeddingService],
+  exports: [MEMORY, MEMORY_ADAPTER, EmbeddingService],
 })
 export class MemoryModule {}

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

@@ -48,7 +48,7 @@ class TelegramChannelPluginAdapter implements IChannelPlugin {
   }
 }
 
-const DEFAULT_GATEWAY_URL = 'http://localhost:4000';
+const DEFAULT_GATEWAY_URL = 'http://localhost:14242';
 
 function createPluginRegistry(): IChannelPlugin[] {
   const plugins: IChannelPlugin[] = [];

apps/gateway/src/queue/queue.module.ts

@@ -1,9 +1,21 @@
 import { Global, Module } from '@nestjs/common';
+import { createQueueAdapter, type QueueAdapter } from '@mosaic/queue';
+import type { MosaicConfig } from '@mosaic/config';
+import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { QueueService } from './queue.service.js';
 
+export const QUEUE_ADAPTER = 'QUEUE_ADAPTER';
+
 @Global()
 @Module({
-  providers: [QueueService],
-  exports: [QueueService],
+  providers: [
+    QueueService,
+    {
+      provide: QUEUE_ADAPTER,
+      useFactory: (config: MosaicConfig): QueueAdapter => createQueueAdapter(config.queue),
+      inject: [MOSAIC_CONFIG],
+    },
+  ],
+  exports: [QueueService, QUEUE_ADAPTER],
 })
 export class QueueModule {}

apps/web/playwright.config.ts

@@ -5,7 +5,7 @@ import { defineConfig, devices } from '@playwright/test';
  *
  * Assumes:
  *   - Next.js web app running on http://localhost:3000
- *   - NestJS gateway running on http://localhost:4000
+ *   - NestJS gateway running on http://localhost:14242
  *
  * Run with:   pnpm --filter @mosaic/web test:e2e
  */

apps/web/src/lib/api.ts

@@ -1,4 +1,4 @@
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:4000';
+const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
 
 export interface ApiRequestInit extends Omit<RequestInit, 'body'> {
   body?: unknown;

apps/web/src/lib/auth-client.ts

@@ -2,7 +2,7 @@ import { createAuthClient } from 'better-auth/react';
 import { adminClient, genericOAuthClient } from 'better-auth/client/plugins';
 
 export const authClient = createAuthClient({
-  baseURL: process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:4000',
+  baseURL: process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242',
   plugins: [adminClient(), genericOAuthClient()],
 });
 

apps/web/src/lib/socket.ts

@@ -1,6 +1,6 @@
 import { io, type Socket } from 'socket.io-client';
 
-const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:4000';
+const GATEWAY_URL = process.env['NEXT_PUBLIC_GATEWAY_URL'] ?? 'http://localhost:14242';
 
 let socket: Socket | null = null;
 

docs/TASKS-TUI_Improvements.md

@@ -93,7 +93,7 @@ packages/cli/src/tui/
 cd /home/jwoltje/src/mosaic-mono-v1-worktrees/tui-improvements
 pnpm --filter @mosaic/cli exec tsx src/cli.ts tui
 # or after build:
-node packages/cli/dist/cli.js tui --gateway http://localhost:4000
+node packages/cli/dist/cli.js tui --gateway http://localhost:14242
 ```
 
 ### Quality Gates

docs/TASKS.md

@@ -1,73 +1,30 @@
-# Tasks — Harness Foundation
+# Tasks — Storage Abstraction Retrofit
 
 > Single-writer: orchestrator only. Workers read but never modify.
 >
+> **Mission:** Decouple gateway from hardcoded Postgres/Valkey backends. Introduce interface-driven middleware so the gateway is backend-agnostic. Default to local tier (SQLite + JSON) for zero-dependency installs.
+>
 > **`agent` column values:** `codex` | `sonnet` | `haiku` | `glm-5` | `opus` | `—` (auto/default)
 
-| id     | status | agent  | milestone          | description                                                        | pr   | notes       |
-| ------ | ------ | ------ | ------------------ | ------------------------------------------------------------------ | ---- | ----------- |
-| M1-001 | done   | sonnet | M1: Persistence    | Wire ChatGateway → ConversationsRepo for user messages             | #292 | #224 closed |
-| M1-002 | done   | sonnet | M1: Persistence    | Wire agent event relay → ConversationsRepo for assistant responses | #292 | #225 closed |
-| M1-003 | done   | sonnet | M1: Persistence    | Store message metadata: model, provider, tokens, tool calls        | #292 | #226 closed |
-| M1-004 | done   | sonnet | M1: Persistence    | Load message history into Pi session on resume                     | #301 | #227 closed |
-| M1-005 | done   | sonnet | M1: Persistence    | Context window management: summarize when >80%                     | #301 | #228 closed |
-| M1-006 | done   | sonnet | M1: Persistence    | Conversation search endpoint                                       | #299 | #229 closed |
-| M1-007 | done   | sonnet | M1: Persistence    | TUI /history command                                               | #297 | #230 closed |
-| M1-008 | done   | sonnet | M1: Persistence    | Verify persistence — 20 tests                                      | #304 | #231 closed |
-| M2-001 | done   | sonnet | M2: Security       | InsightsRepo userId on searchByEmbedding                           | #290 | #232 closed |
-| M2-002 | done   | sonnet | M2: Security       | InsightsRepo userId on findByUser/decay                            | #290 | #233 closed |
-| M2-003 | done   | sonnet | M2: Security       | PreferencesRepo userId verified                                    | #294 | #234 closed |
-| M2-004 | done   | sonnet | M2: Security       | Memory tools userId injection fixed                                | #294 | #235 closed |
-| M2-005 | done   | sonnet | M2: Security       | ConversationsRepo ownership checks                                 | #293 | #236 closed |
-| M2-006 | done   | sonnet | M2: Security       | AgentsRepo findAccessible scoped                                   | #293 | #237 closed |
-| M2-007 | done   | sonnet | M2: Security       | Cross-user isolation — 28 tests                                    | #305 | #238 closed |
-| M2-008 | done   | sonnet | M2: Security       | Valkey SCAN + /gc admin-only                                       | #298 | #239 closed |
-| M3-001 | done   | sonnet | M3: Providers      | IProviderAdapter + OllamaAdapter                                   | #306 | #240 closed |
-| M3-002 | done   | sonnet | M3: Providers      | AnthropicAdapter                                                   | #309 | #241 closed |
-| M3-003 | done   | sonnet | M3: Providers      | OpenAIAdapter                                                      | #310 | #242 closed |
-| M3-004 | done   | sonnet | M3: Providers      | OpenRouterAdapter                                                  | #311 | #243 closed |
-| M3-005 | done   | sonnet | M3: Providers      | ZaiAdapter (GLM-5)                                                 | #314 | #244 closed |
-| M3-006 | done   | sonnet | M3: Providers      | Ollama embedding support                                           | #311 | #245 closed |
-| M3-007 | done   | sonnet | M3: Providers      | Provider health checks                                             | #308 | #246 closed |
-| M3-008 | done   | sonnet | M3: Providers      | Model capability matrix                                            | #303 | #247 closed |
-| M3-009 | done   | sonnet | M3: Providers      | EmbeddingService → Ollama default                                  | #308 | #248 closed |
-| M3-010 | done   | sonnet | M3: Providers      | OAuth token storage (AES-256-GCM)                                  | #317 | #249 closed |
-| M3-011 | done   | sonnet | M3: Providers      | Provider credentials CRUD                                          | #317 | #250 closed |
-| M3-012 | done   | sonnet | M3: Providers      | Verify providers — 40 tests                                        | #319 | #251 closed |
-| M4-001 | done   | sonnet | M4: Routing        | routing_rules DB schema                                            | #315 | #252 closed |
-| M4-002 | done   | sonnet | M4: Routing        | Condition types                                                    | #315 | #253 closed |
-| M4-003 | done   | sonnet | M4: Routing        | Action types                                                       | #315 | #254 closed |
-| M4-004 | done   | sonnet | M4: Routing        | Default routing rules (11 seeds)                                   | #316 | #255 closed |
-| M4-005 | done   | sonnet | M4: Routing        | Task classifier (60+ tests)                                        | #316 | #256 closed |
-| M4-006 | done   | sonnet | M4: Routing        | Routing decision pipeline                                          | #318 | #257 closed |
-| M4-007 | done   | sonnet | M4: Routing        | /model override                                                    | #323 | #258 closed |
-| M4-008 | done   | sonnet | M4: Routing        | Routing transparency in session:info                               | #323 | #259 closed |
-| M4-009 | done   | sonnet | M4: Routing        | Routing rules CRUD API                                             | #320 | #260 closed |
-| M4-010 | done   | sonnet | M4: Routing        | Per-user routing overrides                                         | #320 | #261 closed |
-| M4-011 | done   | sonnet | M4: Routing        | Agent specialization capabilities                                  | #320 | #262 closed |
-| M4-012 | done   | sonnet | M4: Routing        | Routing wired into ChatGateway                                     | #323 | #263 closed |
-| M4-013 | done   | sonnet | M4: Routing        | Verify routing — 9 E2E tests                                       | #323 | #264 closed |
-| M5-001 | done   | sonnet | M5: Sessions       | Agent config loaded on session create                              | #323 | #265 closed |
-| M5-002 | done   | sonnet | M5: Sessions       | /model command end-to-end                                          | #323 | #266 closed |
-| M5-003 | done   | sonnet | M5: Sessions       | /agent command mid-session                                         | #323 | #267 closed |
-| M5-004 | done   | sonnet | M5: Sessions       | Session ↔ conversation binding                                     | #321 | #268 closed |
-| M5-005 | done   | sonnet | M5: Sessions       | Session info broadcast                                             | #321 | #269 closed |
-| M5-006 | done   | sonnet | M5: Sessions       | /agent new from TUI                                                | #321 | #270 closed |
-| M5-007 | done   | sonnet | M5: Sessions       | Session metrics                                                    | #321 | #271 closed |
-| M5-008 | done   | sonnet | M5: Sessions       | Verify sessions — 28 tests                                         | #324 | #272 closed |
-| M6-001 | done   | sonnet | M6: Jobs           | BullMQ + Valkey config                                             | #324 | #273 closed |
-| M6-002 | done   | sonnet | M6: Jobs           | Queue service with typed jobs                                      | #324 | #274 closed |
-| M6-003 | done   | sonnet | M6: Jobs           | Summarization → BullMQ                                             | #324 | #275 closed |
-| M6-004 | done   | sonnet | M6: Jobs           | GC → BullMQ                                                        | #324 | #276 closed |
-| M6-005 | done   | sonnet | M6: Jobs           | Tier management → BullMQ                                           | #324 | #277 closed |
-| M6-006 | done   | sonnet | M6: Jobs           | Admin jobs API                                                     | #325 | #278 closed |
-| M6-007 | done   | sonnet | M6: Jobs           | Job event logging                                                  | #325 | #279 closed |
-| M6-008 | done   | sonnet | M6: Jobs           | Verify jobs                                                        | #324 | #280 closed |
-| M7-001 | done   | sonnet | M7: Channel Design | IChannelAdapter interface                                          | #325 | #281 closed |
-| M7-002 | done   | sonnet | M7: Channel Design | Channel message protocol                                           | #325 | #282 closed |
-| M7-003 | done   | sonnet | M7: Channel Design | Matrix integration design                                          | #326 | #283 closed |
-| M7-004 | done   | sonnet | M7: Channel Design | Conversation multiplexing                                          | #326 | #284 closed |
-| M7-005 | done   | sonnet | M7: Channel Design | Remote auth bridging                                               | #326 | #285 closed |
-| M7-006 | done   | sonnet | M7: Channel Design | Agent-to-agent via Matrix                                          | #326 | #286 closed |
-| M7-007 | done   | sonnet | M7: Channel Design | Multi-user isolation in Matrix                                     | #326 | #287 closed |
-| M7-008 | done   | sonnet | M7: Channel Design | channel-protocol.md published                                      | #326 | #288 closed |
+| id        | status      | agent  | description                                                      | tokens |
+| --------- | ----------- | ------ | ---------------------------------------------------------------- | ------ |
+| SA-P1-001 | done        | sonnet | Define QueueAdapter interface in packages/queue/src/types.ts     | 3K     |
+| SA-P1-002 | done        | sonnet | Define StorageAdapter interface in packages/storage/src/types.ts | 3K     |
+| SA-P1-003 | done        | sonnet | Define MemoryAdapter interface in packages/memory/src/types.ts   | 3K     |
+| SA-P1-004 | done        | sonnet | Create adapter factory pattern + config types                    | 3K     |
+| SA-P2-001 | done        | sonnet | Refactor @mosaic/queue: wrap ioredis as BullMQ adapter           | 3K     |
+| SA-P2-002 | done        | sonnet | Create @mosaic/storage: wrap Drizzle as Postgres adapter         | 6K     |
+| SA-P2-003 | done        | sonnet | Refactor @mosaic/memory: extract pgvector adapter                | 4K     |
+| SA-P2-004 | done        | sonnet | Update gateway modules to use factories + DI tokens              | 5K     |
+| SA-P2-005 | done        | opus   | Verify Phase 2: all tests pass, typecheck clean                  | —      |
+| SA-P3-001 | done        | sonnet | Implement local queue adapter: JSON file persistence             | 5K     |
+| SA-P3-002 | done        | sonnet | Implement SQLite storage adapter with better-sqlite3             | 8K     |
+| SA-P3-003 | done        | sonnet | Implement keyword memory adapter — no vector dependency          | 4K     |
+| SA-P3-004 | done        | opus   | Verify Phase 3: 42 new tests, 347 total passing                  | —      |
+| SA-P4-001 | done        | sonnet | MosaicConfig schema + loader with tier auto-detection            | 6K     |
+| SA-P4-002 | done        | sonnet | CLI: mosaic gateway init — interactive wizard                    | 4K     |
+| SA-P4-003 | done        | sonnet | CLI: mosaic gateway start/stop/status lifecycle                  | 5K     |
+| SA-P4-004 | done        | opus   | Verify Phase 4: 381 tests passing, 40/40 tasks clean             | —      |
+| SA-P5-001 | not-started | codex  | Migration tooling: mosaic storage export/import                  | —      |
+| SA-P5-002 | not-started | codex  | Docker Compose profiles: local vs team                           | —      |
+| SA-P5-003 | not-started | codex  | Final verification + docs: README, architecture diagram          | —      |

docs/design/storage-abstraction-middleware.md

@@ -0,0 +1,555 @@
+# Storage & Queue Abstraction — Middleware Architecture
+
+Design
+Status: Design (retrofit required)
+date: 2026-04-02
+context: Agents coupled directly to infrastructure backends, bypassing intended middleware layer
+
+---
+
+## The Problem
+
+Current packages are **direct adapters**, not **middleware**:
+| Package | Current State | Intended Design |
+|---------|---------------|-----------------|
+| `@mosaic/queue` | `ioredis` hardcoded | Interface → BullMQ OR local-files |
+| `@mosaic/db` | Drizzle + Postgres hardcoded | Interface → Postgres OR SQLite OR JSON/MD |
+| `@mosaic/memory` | pgvector required | Interface → pgvector OR sqlite-vec OR keyword-search |
+
+## The gateway and TUI import these packages directly, which means they they're coupled to specific infrastructure. Users cannot run Mosaic Stack without Postgres + Valkey.
+
+## The Intended Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                     Gateway / TUI / CLI                          │
+│            (agnostic of storage backend, talks to middleware)    │
+└───────────────────────────┬─────────────────────────────────────┘
+                            │
+        ┌───────────────────┼───────────────────┐
+        │                 │                       │
+        ▼─────────────────┴─────────────────┴─────────────────┘
+        |                 |                     |                 |
+        ▼─────────────────┴───────────────────┴─────────────────┘
+        |                 |                     |                 |
+   Queue               Storage             Memory
+        |                 |                     |                 |
+   ┌─────────┬─────────┬─────────┬─────────────────────────────────┐
+   | BullMQ | | Local  | | Postgres | SQLite | JSON/MD | pgvector | sqlite-vec | keyword |
+   |(Valkey)| |(files) |         |             |         |          |          |
+   └─────────┴─────────┴─────────┴─────────────────────────────────┘
+```
+
+The gateway imports the interface, not the backend. At startup it reads config and instantiates the correct adapter.
+
+## The Drift
+
+```typescript
+// What should have happened:
+gateway/queue.service.ts → @mosaic/queue (interface) → queue.adapter.ts
+
+// What actually happened:
+gateway/queue.service.ts → @mosaic/queue → ioredis (hardcoded)
+```
+
+## The Current State Analysis
+
+### `@mosaic/queue` (packages/queue/src/queue.ts)
+
+```typescript
+import Redis from 'ioredis'; // ← Direct import of backend
+
+export function createQueue(config?: QueueConfig): QueueHandle {
+  const url = config?.url ?? process.env['VALKEY_URL'] ?? DEFAULT_VALKEY_URL;
+  const redis = new Redis(url, { maxRetriesPerRequest: 3 });
+  // ...queue ops directly on redis...
+}
+```
+
+**Problem:** `ioredis` is imported in the package, not the adapter interface. Consumers cannot swap backends.
+
+### `@mosaic/db` (packages/db/src/client.ts)
+
+```typescript
+import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
+import postgres from 'postgres';
+
+export function createDb(url?: string): DbHandle {
+  const connectionString = url ?? process.env['DATABASE_URL'] ?? DEFAULT_DATABASE_URL;
+  const sql = postgres(connectionString, { max: 20, idle_timeout: 30, connect_timeout: 5 });
+  const db = drizzle(sql, { schema });
+  // ...
+}
+```
+
+**Problem:** Drizzle + Postgres is hardcoded. No SQLite, JSON, or file-based options.
+
+### `@mosaic/memory` (packages/memory/src/memory.ts)
+
+```typescript
+import type { Db } from '@mosaic/db'; // ← Depends on Drizzle/PG
+
+export function createMemory(db: Db): Memory {
+  return {
+    preferences: createPreferencesRepo(db),
+    insights: createInsightsRepo(db),
+  };
+}
+```
+
+**Problem:** Memory package is tightly coupled to `@mosaic/db` (which is Postgres-only). No alternative storage backends.
+
+## The Target Interfaces
+
+### Queue Interface
+
+```typescript
+// packages/queue/src/types.ts
+export interface QueueAdapter {
+  readonly name: string;
+
+  enqueue(queueName: string, payload: TaskPayload): Promise<void>;
+  dequeue(queueName: string): Promise<TaskPayload | null>;
+  length(queueName: string): Promise<number>;
+  publish(channel: string, message: string): Promise<void>;
+  subscribe(channel: string, handler: (message: string) => void): () => void;
+  close(): Promise<void>;
+}
+
+export interface TaskPayload {
+  id: string;
+  type: string;
+  data: Record<string, unknown>;
+  createdAt: string;
+}
+
+export interface QueueConfig {
+  type: 'bullmq' | 'local';
+  url?: string; // For bullmq: Valkey/Redis URL
+  dataDir?: string; // For local: directory for JSON persistence
+}
+```
+
+### Storage Interface
+
+```typescript
+// packages/storage/src/types.ts
+export interface StorageAdapter {
+  readonly name: string;
+
+  // Entity CRUD
+  create<T>(collection: string, data: O): Promise<T>;
+  read<T>(collection: string, id: string): Promise<T | null>;
+  update<T>(collection: string, id: string, data: Partial<O>): Promise<T | null>;
+  delete(collection: string, id: string): Promise<boolean>;
+
+  // Queries
+  find<T>(collection: string, filter: Record<string, unknown>): Promise<T[]>;
+  findOne<T>(collection: string, filter: Record<string, unknown): Promise<T | null>;
+
+  // Bulk operations
+  createMany<T>(collection: string, items: O[]): Promise<T[]>;
+  updateMany<T>(collection: string, ids: string[], data: Partial<O>): Promise<number>;
+  deleteMany(collection: string, ids: string[]): Promise<number>;
+
+  // Raw queries (for complex queries)
+  query<T>(collection: string, query: string, params?: unknown[]): Promise<T[]>;
+
+  // Transaction support
+  transaction<T>(fn: (tx: StorageTransaction) => Promise<T>): Promise<T>;
+
+  close(): Promise<void>;
+}
+
+export interface StorageTransaction {
+  commit(): Promise<void>;
+  rollback(): Promise<void>;
+}
+
+export interface StorageConfig {
+  type: 'postgres' | 'sqlite' | 'files';
+  url?: string;      // For postgres
+  path?: string;      // For sqlite/files
+}
+```
+
+### Memory Interface (Vector + Preferences)
+
+```typescript
+// packages/memory/src/types.ts
+export interface MemoryAdapter {
+  readonly name: string;
+
+  // Preferences (key-value storage)
+  getPreference(userId: string, key: string): Promise<unknown | null>;
+  setPreference(userId: string, key: string, value: unknown): Promise<void>;
+  deletePreference(userId: string, key: string): Promise<boolean>;
+  listPreferences(
+    userId: string,
+    category?: string,
+  ): Promise<Array<{ key: string; value: unknown }>>;
+
+  // Insights (with optional vector search)
+  storeInsight(insight: NewInsight): Promise<Insight>;
+  getInsight(id: string): Promise<Insight | null>;
+  searchInsights(query: string, limit?: number, filter?: InsightFilter): Promise<SearchResult[]>;
+  deleteInsight(id: string): Promise<boolean>;
+
+  // Embedding provider (optional, null = no vector search)
+  readonly embedder?: EmbeddingProvider | null;
+
+  close(): Promise<void>;
+}
+
+export interface NewInsight {
+  id: string;
+  userId: string;
+  content: string;
+  embedding?: number[]; // If embedder is available
+  source: 'agent' | 'user' | 'summarization' | 'system';
+  category: 'decision' | 'learning' | 'preference' | 'fact' | 'pattern' | 'general';
+  relevanceScore: number;
+  metadata?: Record<string, unknown>;
+  createdAt: Date;
+  decayedAt?: Date;
+}
+
+export interface InsightFilter {
+  userId?: string;
+  category?: string;
+  source?: string;
+  minRelevance?: number;
+  fromDate?: Date;
+  toDate?: Date;
+}
+
+export interface SearchResult {
+  documentId: string;
+  content: string;
+  distance: number;
+  metadata?: Record<string, unknown>;
+}
+
+export interface MemoryConfig {
+  type: 'pgvector' | 'sqlite-vec' | 'keyword';
+  storage: StorageAdapter;
+  embedder?: EmbeddingProvider;
+}
+
+export interface EmbeddingProvider {
+  embed(text: string): Promise<number[]>;
+  embedBatch(texts: string[]): Promise<number[][]>;
+  readonly dimensions: number;
+}
+```
+
+## Three Tiers
+
+### Tier 1: Local (Zero Dependencies)
+
+**Target:** Single user, single machine, no external services
+
+| Component | Backend                                       | Storage      |
+| --------- | --------------------------------------------- | ------------ |
+| Queue     | In-process + JSON files in `~/.mosaic/queue/` |
+| Storage   | SQLite (better-sqlite3) `~/.mosaic/data.db`   |
+| Memory    | Keyword search                                | SQLite table |
+| Vector    | None                                          | N/A          |
+
+**Dependencies:**
+
+- `better-sqlite3` (bundled)
+- No Postgres, No Valkey, No pgvector
+
+**Upgrade path:**
+
+1. Run `mosaic gateway configure` → select "local" tier
+2. Gateway starts with SQLite database
+3. Optional: run `mosaic gateway upgrade --tier team` to migrate to Postgres
+
+### Tier 2: Team (Postgres + Valkey)
+
+**Target:** Multiple users, shared server, CI/CD environments
+
+| Component | Backend        | Storage                        |
+| --------- | -------------- | ------------------------------ |
+| Queue     | BullMQ         | Valkey                         |
+| Storage   | Postgres       | Shared PG instance             |
+| Memory    | pgvector       | Postgres with vector extension |
+| Vector    | LLM embeddings | Configured provider            |
+
+**Dependencies:**
+
+- PostgreSQL 17+ with pgvector extension
+- Valkey (Redis-compatible)
+- LLM provider for embeddings
+
+**Migration from Local → Team:**
+
+1. `mosaic gateway backup` → creates dump of SQLite database
+2. `mosaic gateway upgrade --tier team` → restores to Postgres
+3. Queue replays from BullMQ (may need manual reconciliation for in-flight jobs)
+4. Memory embeddings regenerated if vector search was new
+
+### Tier 3: Enterprise (Clustered)
+
+**Target:** Large teams, multi-region, high availability
+
+| Component | Backend                     | Storage                       |
+| --------- | --------------------------- | ----------------------------- |
+| Queue     | BullMQ cluster              | Multiple Valkey nodes         |
+| Storage   | Postgres cluster            | Primary + replicas            |
+| Memory    | Dedicated vector DB         | Qdrant, Pinecone, or pgvector |
+| Vector    | Dedicated embedding service | Separate microservice         |
+
+## MarkdownDB Integration
+
+For file-based storage, we use [MarkdownDB](https://markdowndb.com) to parse MD files into queryable data.
+
+**What it provides:**
+
+- Parses frontmatter (YAML/JSON/TOML)
+- Extracts links, tags, metadata
+- Builds index in JSON or SQLite
+- Queryable via SQL-like interface
+
+**Usage in Mosaic:**
+
+```typescript
+// Local tier with MD files for documents
+const storage = createStorageAdapter({
+  type: 'files',
+  path: path.join(mosaicHome, 'docs'),
+  markdowndb: {
+    parseFrontmatter: true,
+    extractLinks: true,
+    indexFile: 'index.json',
+  },
+});
+```
+
+## Dream Mode — Memory Consolidation
+
+Automated equivalent to Claude Code's "Dream: Memory Consolidation" cycle
+
+**Trigger:** Every 24 hours (if 5+ sessions active)
+
+**Phases:**
+
+1. **Orient** — What happened, what's the current state
+   - Scan recent session logs
+   - Identify active tasks, missions, conversations
+   - Calculate time window (last 24h)
+
+2. **Gather** — Pull in relevant context
+   - Load conversations, decisions, agent logs
+   - Extract key interactions and outcomes
+   - Identify patterns and learnings
+
+3. **Consolidate** — Summarize and compress
+   - Generate summary of the last 24h
+   - Extract key decisions and their rationale
+   - Identify recurring patterns
+   - Compress verbose logs into concise insights
+
+4. **Prune** — Archive and cleanup
+   - Archive raw session files to dated folders
+   - Delete redundant/temporary data
+   - Update MEMORY.md with consolidated content
+   - Update insight relevance scores
+
+**Implementation:**
+
+```typescript
+// In @mosaic/dream (new package)
+export async function runDreamCycle(config: DreamConfig): Promise<DreamResult> {
+  const memory = await loadMemoryAdapter(config.storage);
+
+  // Orient
+  const sessions = await memory.getRecentSessions(24 * 60 * 60 * 1000);
+  if (sessions.length < 5) return { skipped: true, reason: 'insufficient_sessions' };
+
+  // Gather
+  const context = await gatherContext(memory, sessions);
+
+  // Consolidate
+  const consolidated = await consolidateWithLLM(context, config.llm);
+
+  // Prune
+  await pruneArchivedData(memory, config.retention);
+
+  // Store consolidated insights
+  await memory.storeInsights(consolidated.insights);
+
+  return {
+    sessionsProcessed: sessions.length,
+    insightsCreated: consolidated.insights.length,
+    bytesPruned: consolidated.bytesRemoved,
+  };
+}
+```
+
+---
+
+## Retrofit Plan
+
+### Phase 1: Interface Extraction (2-3 days)
+
+**Goal:** Define interfaces without changing existing behavior
+
+1. Create `packages/queue/src/types.ts` with `QueueAdapter` interface
+2. Create `packages/storage/src/types.ts` with `StorageAdapter` interface
+3. Create `packages/memory/src/types.ts` with `MemoryAdapter` interface (refactor existing)
+4. Add adapter registry pattern to each package
+5. No breaking changes — existing code continues to work
+
+### Phase 2: Refactor Existing to Adapters (3-5 days)
+
+**Goal:** Move existing implementations behind adapters
+
+#### 2.1 Queue Refactor
+
+1. Rename `packages/queue/src/queue.ts` → `packages/queue/src/adapters/bullmq.ts`
+2. Create `packages/queue/src/index.ts` to export factory function
+3. Factory function reads config, instantiates correct adapter
+4. Update gateway imports to use factory
+
+#### 2.2 Storage Refactor
+
+1. Create `packages/storage/` (new package)
+2. Move Drizzle logic to `packages/storage/src/adapters/postgres.ts`
+3. Create SQLite adapter in `packages/storage/src/adapters/sqlite.ts`
+4. Update gateway to use storage factory
+5. Deprecate direct `@mosaic/db` imports
+
+#### 2.3 Memory Refactor
+
+1. Extract existing logic to `packages/memory/src/adapters/pgvector.ts`
+2. Create keyword adapter in `packages/memory/src/adapters/keyword.ts`
+3. Update vector-store.ts to be adapter-agnostic
+
+### Phase 3: Local Tier Implementation (2-3 days)
+
+**Goal:** Zero-dependency baseline
+
+1. Implement `packages/queue/src/adapters/local.ts` (in-process + JSON persistence)
+2. Implement `packages/storage/src/adapters/files.ts` (JSON + MD via MarkdownDB)
+3. Implement `packages/memory/src/adapters/keyword.ts` (TF-IDF search)
+4. Add `packages/dream/` for consolidation cycle
+5. Wire up local tier in gateway startup
+
+### Phase 4: Configuration System (1-2 days)
+
+**Goal:** Runtime backend selection
+
+1. Create `packages/config/src/storage.ts` for storage configuration
+2. Add `mosaic.config.ts` schema with storage tier settings
+3. Update gateway to read config on startup
+4. Add `mosaic gateway configure` CLI command
+5. Add tier migration commands (`mosaic gateway upgrade`)
+
+### Phase 5: Testing & Documentation (2-3 days)
+
+1. Unit tests for each adapter
+2. Integration tests for factory pattern
+3. Migration tests (local → team)
+4. Update README and architecture docs
+5. Add configuration guide
+
+---
+
+## File Changes Summary
+
+### New Files
+
+```
+packages/
+├── config/
+│   └── src/
+│       ├── storage.ts          # Storage config schema
+│       └── index.ts
+├── dream/                    # NEW: Dream mode consolidation
+│   ├── src/
+│   │   ├── index.ts
+│   │   ├── orient.ts
+│   │   ├── gather.ts
+│   │   ├── consolidate.ts
+│   │   └── prune.ts
+│   └── package.json
+├── queue/
+│   └── src/
+│       ├── types.ts           # NEW: QueueAdapter interface
+│       ├── index.ts           # NEW: Factory function
+│       └── adapters/
+│           ├── bullmq.ts      # MOVED from queue.ts
+│           └── local.ts       # NEW: In-process adapter
+├── storage/                  # NEW: Storage abstraction
+│   ├── src/
+│   │   ├── types.ts           # StorageAdapter interface
+│   │   ├── index.ts           # Factory function
+│   │   └── adapters/
+│   │       ├── postgres.ts    # MOVED from @mosaic/db
+│   │       ├── sqlite.ts      # NEW: SQLite adapter
+│   │       └── files.ts       # NEW: JSON/MD adapter
+│   └── package.json
+└── memory/
+    └── src/
+        ├── types.ts           # UPDATED: MemoryAdapter interface
+        ├── index.ts           # UPDATED: Factory function
+        └── adapters/
+            ├── pgvector.ts    # EXTRACTED from existing code
+            ├── sqlite-vec.ts  # NEW: SQLite with vectors
+            └── keyword.ts     # NEW: TF-IDF search
+```
+
+### Modified Files
+
+```
+packages/
+├── db/                       # DEPRECATED: Logic moved to storage adapters
+├── queue/
+│   └── src/
+│       └── queue.ts          # → adapters/bullmq.ts
+├── memory/
+│   ├── src/
+│   │   ├── memory.ts         # → use factory
+│   │   ├── insights.ts       # → use factory
+│   │   └── preferences.ts    # → use factory
+│   └── package.json          # Remove pgvector from dependencies
+└── gateway/
+    └── src/
+        ├── database/
+        │   └── database.module.ts  # Update to use storage factory
+        ├── memory/
+        │   └── memory.module.ts  # Update to use memory factory
+        └── queue/
+            └── queue.module.ts  # Update to use queue factory
+```
+
+---
+
+## Breaking Changes
+
+1. **`@mosaic/db`** → **`@mosaic/storage`** (with migration guide)
+2. Direct `ioredis` imports → Use `@mosaic/queue` factory
+3. Direct `pgvector` queries → Use `@mosaic/memory` factory
+4. Gateway startup now requires storage config (defaults to local)
+
+## Non-Breaking Migration Path
+
+1. Existing deployments with Postgres/Valkey continue to work (default config)
+2. New deployments can choose local tier
+3. Migration commands available when ready to upgrade
+
+---
+
+## Success Criteria
+
+- [ ] Local tier runs with zero external dependencies
+- [ ] All three tiers (local, team, enterprise) work correctly
+- [ ] Factory pattern correctly selects backend at runtime
+- [ ] Migration from local → team preserves all data
+- [ ] Dream mode consolidates 24h of sessions
+- [ ] Documentation covers all three tiers and migration paths
+- [ ] All existing tests pass
+- [ ] New adapters have >80% coverage

docs/guides/admin-guide.md

@@ -230,10 +230,10 @@ external clients. Authentication requires a valid BetterAuth session (cookie or
 ### Gateway
 
 | Variable              | Default                  | Description                                    |
-| --------------------- | ----------------------- | ---------------------------------------------- |
-| `GATEWAY_PORT`        | `4000`                  | Port the gateway listens on                    |
+| --------------------- | ------------------------ | ---------------------------------------------- |
+| `GATEWAY_PORT`        | `14242`                  | Port the gateway listens on                    |
 | `GATEWAY_CORS_ORIGIN` | `http://localhost:3000`  | Allowed CORS origin for browser clients        |
-| `BETTER_AUTH_URL`     | `http://localhost:4000` | Public URL of the gateway (used by BetterAuth) |
+| `BETTER_AUTH_URL`     | `http://localhost:14242` | Public URL of the gateway (used by BetterAuth) |
 
 ### SSO (Optional)
 
@@ -293,10 +293,10 @@ Each OIDC provider requires its client ID, client secret, and issuer URL togethe
 ### Plugins
 
 | Variable               | Description                                                                |
-| ---------------------- | ------------------------------------------------------------------------- |
+| ---------------------- | -------------------------------------------------------------------------- |
 | `DISCORD_BOT_TOKEN`    | Discord bot token (enables Discord plugin)                                 |
 | `DISCORD_GUILD_ID`     | Discord guild/server ID                                                    |
-| `DISCORD_GATEWAY_URL`  | Gateway URL for Discord plugin to call (default: `http://localhost:4000`) |
+| `DISCORD_GATEWAY_URL`  | Gateway URL for Discord plugin to call (default: `http://localhost:14242`) |
 | `TELEGRAM_BOT_TOKEN`   | Telegram bot token (enables Telegram plugin)                               |
 | `TELEGRAM_GATEWAY_URL` | Gateway URL for Telegram plugin to call                                    |
 
@@ -310,8 +310,8 @@ Each OIDC provider requires its client ID, client secret, and issuer URL togethe
 ### Web App
 
 | Variable                  | Default                  | Description                            |
-| ------------------------- | ----------------------- | -------------------------------------- |
-| `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:4000` | Gateway URL used by the Next.js client |
+| ------------------------- | ------------------------ | -------------------------------------- |
+| `NEXT_PUBLIC_GATEWAY_URL` | `http://localhost:14242` | Gateway URL used by the Next.js client |
 
 ### Coordination
 

docs/guides/deployment.md

@@ -194,7 +194,7 @@ server {
 
     # WebSocket support (for chat.gateway.ts / Socket.IO)
     location /socket.io/ {
-        proxy_pass http://127.0.0.1:4000;
+        proxy_pass http://127.0.0.1:14242;
         proxy_http_version 1.1;
         proxy_set_header Upgrade $http_upgrade;
         proxy_set_header Connection "upgrade";
@@ -204,7 +204,7 @@ server {
 
     # REST + auth
     location / {
-        proxy_pass http://127.0.0.1:4000;
+        proxy_pass http://127.0.0.1:14242;
         proxy_set_header Host $host;
         proxy_set_header X-Real-IP $remote_addr;
         proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
@@ -234,11 +234,11 @@ server {
 # /etc/caddy/Caddyfile
 
 your-domain.example.com {
-    reverse_proxy /socket.io/* localhost:4000 {
+    reverse_proxy /socket.io/* localhost:14242 {
         header_up Upgrade {http.upgrade}
         header_up Connection {http.connection}
     }
-    reverse_proxy localhost:4000
+    reverse_proxy localhost:14242
 }
 
 app.your-domain.example.com {
@@ -328,7 +328,7 @@ MaxRetentionSec=30day
 - Set `BETTER_AUTH_SECRET` to a cryptographically random value (`openssl rand -base64 32`).
 - Restrict `GATEWAY_CORS_ORIGIN` to your exact frontend origin — do not use `*`.
 - Run services as a dedicated non-root system user (e.g., `mosaic`).
-- Firewall: only expose ports 80/443 externally; keep 4000 and 3000 bound to `127.0.0.1`.
+- Firewall: only expose ports 80/443 externally; keep 14242 and 3000 bound to `127.0.0.1`.
 - Set `AGENT_FILE_SANDBOX_DIR` to a directory outside the application root to prevent agent tools from accessing source code.
 - If using `AGENT_USER_TOOLS`, enumerate only the tools non-admin users need.
 

docs/guides/dev-guide.md

@@ -112,11 +112,11 @@ DATABASE_URL=postgresql://mosaic:mosaic@localhost:5433/mosaic
 BETTER_AUTH_SECRET=change-me-to-a-random-secret
 
 # Gateway
-GATEWAY_PORT=4000
+GATEWAY_PORT=14242
 GATEWAY_CORS_ORIGIN=http://localhost:3000
 
 # Web
-NEXT_PUBLIC_GATEWAY_URL=http://localhost:4000
+NEXT_PUBLIC_GATEWAY_URL=http://localhost:14242
 
 # Optional: Ollama
 OLLAMA_BASE_URL=http://localhost:11434
@@ -141,7 +141,7 @@ migrations in production).
 pnpm --filter @mosaic/gateway exec tsx src/main.ts
 ```
 
-The gateway starts on port `4000` by default.
+The gateway starts on port `14242` by default.
 
 ### 6. Start the Web App
 
@@ -395,7 +395,7 @@ directory are defined there.
 
 ## API Endpoint Reference
 
-All endpoints are served by the gateway at `http://localhost:4000` by default.
+All endpoints are served by the gateway at `http://localhost:14242` by default.
 
 ### Authentication
 

docs/guides/user-guide.md

@@ -16,7 +16,7 @@
 ### Prerequisites
 
 Mosaic Stack requires a running gateway. Your administrator provides the URL
-(default: `http://localhost:4000`) and creates your account.
+(default: `http://localhost:14242`) and creates your account.
 
 ### Logging In (Web)
 
@@ -177,7 +177,7 @@ mosaic --help
 ### Signing In
 
 ```bash
-mosaic login --gateway http://localhost:4000 --email you@example.com
+mosaic login --gateway http://localhost:14242 --email you@example.com
 ```
 
 You are prompted for a password if `--password` is not supplied. The session
@@ -192,8 +192,8 @@ mosaic tui
 Options:
 
 | Flag                    | Default                  | Description                        |
-| ----------------------- | ----------------------- | ---------------------------------- |
-| `--gateway <url>`       | `http://localhost:4000` | Gateway URL                        |
+| ----------------------- | ------------------------ | ---------------------------------- |
+| `--gateway <url>`       | `http://localhost:14242` | Gateway URL                        |
 | `--conversation <id>`   | —                        | Resume a specific conversation     |
 | `--model <modelId>`     | server default           | Model to use (e.g. `llama3.2`)     |
 | `--provider <provider>` | server default           | Provider (e.g. `ollama`, `openai`) |

docs/scratchpads/update-checker-package-20260404.md

@@ -0,0 +1,34 @@
+# Scratchpad — updater package target fix (#382)
+
+- Objective: Fix `mosaic update` so modern installs query `@mosaic/mosaic` instead of stale `@mosaic/cli`.
+- Scope: updater logic, user-facing update/install hints, tests, package version bump(s).
+- Constraints: preserve backward compatibility for older `@mosaic/cli` installs if practical.
+- Acceptance:
+  - fresh installs using `@mosaic/mosaic` report latest correctly
+  - older installs do not regress unnecessarily
+  - tests cover package lookup behavior
+  - release version bumped for changed package(s)
+
+## Decisions
+
+- Prefer `@mosaic/mosaic` when both modern and legacy packages are installed globally.
+- For legacy `@mosaic/cli` installs, query `@mosaic/cli` first, then fall back to `@mosaic/mosaic` if the legacy package is not published.
+- Share install-target selection from `packages/mosaic` so both the consolidated CLI and the legacy `packages/cli` entrypoint print/install the same package target.
+- Extend the update cache to persist the resolved target package as well as the version so cached checks preserve the migration target.
+
+## Validation
+
+- `pnpm install`
+- `pnpm --filter @mosaic/mosaic test -- __tests__/update-checker.test.ts`
+- `pnpm exec eslint --no-warn-ignored packages/mosaic/src/runtime/update-checker.ts packages/mosaic/src/cli.ts packages/mosaic/src/index.ts packages/mosaic/__tests__/update-checker.test.ts packages/cli/src/cli.ts`
+- `pnpm --filter @mosaic/mosaic lint`
+- pre-push hooks: `typecheck`, `lint`, `format:check`
+
+## Review
+
+- Manual review of the updater diff caught and fixed a cache regression where fallback results would lose the resolved package target on subsequent cached checks.
+
+## Risks / Notes
+
+- Direct `pnpm --filter @mosaic/mosaic typecheck` and `pnpm --filter @mosaic/cli ...` checks were not representative in this worktree because `packages/cli` is excluded from `pnpm-workspace.yaml` and the standalone package check lacked the built workspace dependency graph.
+- The repo's pre-push hooks provided the authoritative validation path here and passed: root `typecheck`, `lint`, and `format:check`.

mosaic.config.json

@@ -0,0 +1,6 @@
+{
+  "tier": "local",
+  "storage": { "type": "pglite", "dataDir": ".mosaic/storage-pglite" },
+  "queue": { "type": "local", "dataDir": ".mosaic/queue" },
+  "memory": { "type": "keyword" }
+}

packages/agent/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/agent",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/agent"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/auth/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/auth",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/auth"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/auth/src/auth.ts

@@ -35,7 +35,7 @@ export function createAuth(config: AuthConfig) {
       provider: 'pg',
       usePlural: true,
     }),
-    baseURL: baseURL ?? process.env['BETTER_AUTH_URL'] ?? 'http://localhost:4000',
+    baseURL: baseURL ?? process.env['BETTER_AUTH_URL'] ?? 'http://localhost:14242',
     secret: secret ?? process.env['BETTER_AUTH_SECRET'],
     basePath: '/api/auth',
     trustedOrigins,

packages/brain/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/brain",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/brain"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/cli/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/cli",
-  "version": "0.0.3",
+  "version": "0.0.17",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/cli"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -22,6 +27,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.0",
+    "@mosaic/config": "workspace:^",
     "@mosaic/mosaic": "workspace:^",
     "@mosaic/prdy": "workspace:^",
     "@mosaic/quality-rails": "workspace:^",

packages/cli/src/cli.ts

@@ -2,11 +2,12 @@
 
 import { createRequire } from 'module';
 import { Command } from 'commander';
-import { createQualityRailsCli } from '@mosaic/quality-rails';
+import { registerQualityRails } from '@mosaic/quality-rails';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerMissionCommand } from './commands/mission.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
+import { registerGatewayCommand } from './commands/gateway.js';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION: string = (_require('../package.json') as { version: string }).version;
@@ -32,7 +33,7 @@ registerLaunchCommands(program);
 program
   .command('login')
   .description('Sign in to a Mosaic gateway')
-  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
   .option('-e, --email <email>', 'Email address')
   .option('-p, --password <password>', 'Password')
   .action(async (opts: { gateway: string; email?: string; password?: string }) => {
@@ -66,7 +67,7 @@ program
 program
   .command('tui')
   .description('Launch interactive TUI connected to the gateway')
-  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
   .option('-c, --conversation <id>', 'Resume a conversation by ID')
   .option('-m, --model <modelId>', 'Model ID to use (e.g. gpt-4o, llama3.2)')
   .option('-p, --provider <provider>', 'Provider to use (e.g. openai, ollama)')
@@ -207,7 +208,7 @@ const sessionsCmd = program.command('sessions').description('Manage active agent
 sessionsCmd
   .command('list')
   .description('List active agent sessions')
-  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
   .action(async (opts: { gateway: string }) => {
     const { withAuth } = await import('./commands/with-auth.js');
     const auth = await withAuth(opts.gateway);
@@ -242,7 +243,7 @@ sessionsCmd
 sessionsCmd
   .command('resume <id>')
   .description('Resume an existing agent session in the TUI')
-  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
   .action(async (id: string, opts: { gateway: string }) => {
     const { loadSession, validateSession } = await import('./auth.js');
 
@@ -275,7 +276,7 @@ sessionsCmd
 sessionsCmd
   .command('destroy <id>')
   .description('Terminate an active agent session')
-  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
   .action(async (id: string, opts: { gateway: string }) => {
     const { withAuth } = await import('./commands/with-auth.js');
     const auth = await withAuth(opts.gateway);
@@ -290,6 +291,10 @@ sessionsCmd
     }
   });
 
+// ─── gateway ──────────────────────────────────────────────────────────
+
+registerGatewayCommand(program);
+
 // ─── agent ─────────────────────────────────────────────────────────────
 
 registerAgentCommand(program);
@@ -300,11 +305,7 @@ registerMissionCommand(program);
 
 // ─── quality-rails ──────────────────────────────────────────────────────
 
-const qrWrapper = createQualityRailsCli();
-const qrCmd = qrWrapper.commands.find((c) => c.name() === 'quality-rails');
-if (qrCmd !== undefined) {
-  program.addCommand(qrCmd as unknown as Command);
-}
+registerQualityRails(program);
 
 // ─── update ─────────────────────────────────────────────────────────────
 
@@ -313,7 +314,8 @@ program
   .description('Check for and install Mosaic CLI updates')
   .option('--check', 'Check only, do not install')
   .action(async (opts: { check?: boolean }) => {
-    const { checkForUpdate, formatUpdateNotice } = await import('@mosaic/mosaic');
+    const { checkForUpdate, formatUpdateNotice, getInstallCommand } =
+      await import('@mosaic/mosaic');
     const { execSync } = await import('node:child_process');
 
     console.log('Checking for updates…');
@@ -343,7 +345,7 @@ program
     try {
       // Relies on @mosaic:registry in ~/.npmrc — do NOT pass --registry
       // globally or non-@mosaic deps will 404 against the Gitea registry.
-      execSync('npm install -g @mosaic/cli@latest', {
+      execSync(getInstallCommand(result), {
         stdio: 'inherit',
         timeout: 60_000,
       });

packages/cli/src/commands/agent.ts

@@ -34,7 +34,7 @@ export function registerAgentCommand(program: Command) {
   const cmd = program
     .command('agent')
     .description('Manage agent configurations')
-    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
     .option('--list', 'List all agents')
     .option('--new', 'Create a new agent')
     .option('--show <idOrName>', 'Show agent details')

packages/cli/src/commands/gateway.ts

@@ -0,0 +1,152 @@
+import type { Command } from 'commander';
+import {
+  getDaemonPid,
+  readMeta,
+  startDaemon,
+  stopDaemon,
+  waitForHealth,
+} from './gateway/daemon.js';
+
+interface GatewayParentOpts {
+  host: string;
+  port: string;
+  token?: string;
+}
+
+function resolveOpts(raw: GatewayParentOpts): { host: string; port: number; token?: string } {
+  const meta = readMeta();
+  return {
+    host: raw.host ?? meta?.host ?? 'localhost',
+    port: parseInt(raw.port, 10) || meta?.port || 14242,
+    token: raw.token ?? meta?.adminToken,
+  };
+}
+
+export function registerGatewayCommand(program: Command): void {
+  const gw = program
+    .command('gateway')
+    .description('Manage the Mosaic gateway daemon')
+    .helpOption('--help', 'Display help')
+    .option('-h, --host <host>', 'Gateway host', 'localhost')
+    .option('-p, --port <port>', 'Gateway port', '14242')
+    .option('-t, --token <token>', 'Admin API token')
+    .action(() => {
+      gw.outputHelp();
+    });
+
+  // ─── install ────────────────────────────────────────────────────────────
+
+  gw.command('install')
+    .description('Install and configure the gateway daemon')
+    .option('--skip-install', 'Skip npm package installation (use local build)')
+    .action(async (cmdOpts: { skipInstall?: boolean }) => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      const { runInstall } = await import('./gateway/install.js');
+      await runInstall({ ...opts, skipInstall: cmdOpts.skipInstall });
+    });
+
+  // ─── start ──────────────────────────────────────────────────────────────
+
+  gw.command('start')
+    .description('Start the gateway daemon')
+    .action(async () => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      try {
+        const pid = startDaemon();
+        console.log(`Gateway started (PID ${pid.toString()})`);
+        console.log('Waiting for health...');
+        const healthy = await waitForHealth(opts.host, opts.port);
+        if (healthy) {
+          console.log(`Gateway ready at http://${opts.host}:${opts.port.toString()}`);
+        } else {
+          console.warn('Gateway started but health check timed out. Check logs.');
+        }
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── stop ───────────────────────────────────────────────────────────────
+
+  gw.command('stop')
+    .description('Stop the gateway daemon')
+    .action(async () => {
+      try {
+        await stopDaemon();
+        console.log('Gateway stopped.');
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── restart ────────────────────────────────────────────────────────────
+
+  gw.command('restart')
+    .description('Restart the gateway daemon')
+    .action(async () => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      const pid = getDaemonPid();
+      if (pid !== null) {
+        console.log('Stopping gateway...');
+        await stopDaemon();
+      }
+      console.log('Starting gateway...');
+      try {
+        const newPid = startDaemon();
+        console.log(`Gateway started (PID ${newPid.toString()})`);
+        const healthy = await waitForHealth(opts.host, opts.port);
+        if (healthy) {
+          console.log(`Gateway ready at http://${opts.host}:${opts.port.toString()}`);
+        } else {
+          console.warn('Gateway started but health check timed out. Check logs.');
+        }
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── status ─────────────────────────────────────────────────────────────
+
+  gw.command('status')
+    .description('Show gateway daemon status and health')
+    .action(async () => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      const { runStatus } = await import('./gateway/status.js');
+      await runStatus(opts);
+    });
+
+  // ─── config ─────────────────────────────────────────────────────────────
+
+  gw.command('config')
+    .description('View or modify gateway configuration')
+    .option('--set <KEY=VALUE>', 'Set a configuration value')
+    .option('--unset <KEY>', 'Remove a configuration key')
+    .option('--edit', 'Open config in $EDITOR')
+    .action(async (cmdOpts: { set?: string; unset?: string; edit?: boolean }) => {
+      const { runConfig } = await import('./gateway/config.js');
+      await runConfig(cmdOpts);
+    });
+
+  // ─── logs ───────────────────────────────────────────────────────────────
+
+  gw.command('logs')
+    .description('View gateway daemon logs')
+    .option('-f, --follow', 'Follow log output')
+    .option('-n, --lines <count>', 'Number of lines to show', '50')
+    .action(async (cmdOpts: { follow?: boolean; lines?: string }) => {
+      const { runLogs } = await import('./gateway/logs.js');
+      runLogs({ follow: cmdOpts.follow, lines: parseInt(cmdOpts.lines ?? '50', 10) });
+    });
+
+  // ─── uninstall ──────────────────────────────────────────────────────────
+
+  gw.command('uninstall')
+    .description('Uninstall the gateway daemon and optionally remove data')
+    .action(async () => {
+      const { runUninstall } = await import('./gateway/uninstall.js');
+      await runUninstall();
+    });
+}

packages/cli/src/commands/gateway/config.ts

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { ENV_FILE, getDaemonPid, readMeta, META_FILE, ensureDirs } from './daemon.js';
+
+// Keys that should be masked in output
+const SECRET_KEYS = new Set([
+  'BETTER_AUTH_SECRET',
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'ZAI_API_KEY',
+  'OPENROUTER_API_KEY',
+  'DISCORD_BOT_TOKEN',
+  'TELEGRAM_BOT_TOKEN',
+]);
+
+function maskValue(key: string, value: string): string {
+  if (SECRET_KEYS.has(key) && value.length > 8) {
+    return value.slice(0, 4) + '…' + value.slice(-4);
+  }
+  return value;
+}
+
+function parseEnvFile(): Map<string, string> {
+  const map = new Map<string, string>();
+  if (!existsSync(ENV_FILE)) return map;
+
+  const lines = readFileSync(ENV_FILE, 'utf-8').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    map.set(trimmed.slice(0, eqIdx), trimmed.slice(eqIdx + 1));
+  }
+  return map;
+}
+
+function writeEnvFile(entries: Map<string, string>): void {
+  ensureDirs();
+  const lines: string[] = [];
+  for (const [key, value] of entries) {
+    lines.push(`${key}=${value}`);
+  }
+  writeFileSync(ENV_FILE, lines.join('\n') + '\n', { mode: 0o600 });
+}
+
+interface ConfigOpts {
+  set?: string;
+  unset?: string;
+  edit?: boolean;
+}
+
+export async function runConfig(opts: ConfigOpts): Promise<void> {
+  // Set a value
+  if (opts.set) {
+    const eqIdx = opts.set.indexOf('=');
+    if (eqIdx === -1) {
+      console.error('Usage: mosaic gateway config --set KEY=VALUE');
+      process.exit(1);
+    }
+    const key = opts.set.slice(0, eqIdx);
+    const value = opts.set.slice(eqIdx + 1);
+    const entries = parseEnvFile();
+    entries.set(key, value);
+    writeEnvFile(entries);
+    console.log(`Set ${key}=${maskValue(key, value)}`);
+    promptRestart();
+    return;
+  }
+
+  // Unset a value
+  if (opts.unset) {
+    const entries = parseEnvFile();
+    if (!entries.has(opts.unset)) {
+      console.error(`Key not found: ${opts.unset}`);
+      process.exit(1);
+    }
+    entries.delete(opts.unset);
+    writeEnvFile(entries);
+    console.log(`Removed ${opts.unset}`);
+    promptRestart();
+    return;
+  }
+
+  // Open in editor
+  if (opts.edit) {
+    if (!existsSync(ENV_FILE)) {
+      console.error(`No config file found at ${ENV_FILE}`);
+      console.error('Run `mosaic gateway install` first.');
+      process.exit(1);
+    }
+    const editor = process.env['EDITOR'] ?? process.env['VISUAL'] ?? 'vi';
+    try {
+      execSync(`${editor} "${ENV_FILE}"`, { stdio: 'inherit' });
+      promptRestart();
+    } catch {
+      console.error('Editor exited with error.');
+    }
+    return;
+  }
+
+  // Default: show current config
+  showConfig();
+}
+
+function showConfig(): void {
+  if (!existsSync(ENV_FILE)) {
+    console.log('No gateway configuration found.');
+    console.log('Run `mosaic gateway install` to set up.');
+    return;
+  }
+
+  const entries = parseEnvFile();
+  const meta = readMeta();
+
+  console.log('Mosaic Gateway Configuration');
+  console.log('────────────────────────────');
+  console.log(`  Config file: ${ENV_FILE}`);
+  console.log(`  Meta file:   ${META_FILE}`);
+  console.log();
+
+  if (entries.size === 0) {
+    console.log('  (empty)');
+    return;
+  }
+
+  const maxKeyLen = Math.max(...[...entries.keys()].map((k) => k.length));
+  for (const [key, value] of entries) {
+    const padding = ' '.repeat(maxKeyLen - key.length);
+    console.log(`  ${key}${padding}  ${maskValue(key, value)}`);
+  }
+
+  if (meta?.adminToken) {
+    console.log();
+    console.log(`  Admin token: ${maskValue('token', meta.adminToken)}`);
+  }
+}
+
+function promptRestart(): void {
+  if (getDaemonPid() !== null) {
+    console.log('\nGateway is running — restart to apply changes: mosaic gateway restart');
+  }
+}

packages/cli/src/commands/gateway/daemon.ts

@@ -0,0 +1,245 @@
+import { spawn, execSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  openSync,
+  constants,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+export const GATEWAY_HOME = resolve(
+  process.env['MOSAIC_GATEWAY_HOME'] ?? join(homedir(), '.config', 'mosaic', 'gateway'),
+);
+export const PID_FILE = join(GATEWAY_HOME, 'daemon.pid');
+export const LOG_DIR = join(GATEWAY_HOME, 'logs');
+export const LOG_FILE = join(LOG_DIR, 'gateway.log');
+export const ENV_FILE = join(GATEWAY_HOME, '.env');
+export const META_FILE = join(GATEWAY_HOME, 'meta.json');
+
+// ─── Meta ───────────────────────────────────────────────────────────────────
+
+export interface GatewayMeta {
+  version: string;
+  installedAt: string;
+  entryPoint: string;
+  adminToken?: string;
+  host: string;
+  port: number;
+}
+
+export function readMeta(): GatewayMeta | null {
+  if (!existsSync(META_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(META_FILE, 'utf-8')) as GatewayMeta;
+  } catch {
+    return null;
+  }
+}
+
+export function writeMeta(meta: GatewayMeta): void {
+  ensureDirs();
+  writeFileSync(META_FILE, JSON.stringify(meta, null, 2), { mode: 0o600 });
+}
+
+// ─── Directories ────────────────────────────────────────────────────────────
+
+export function ensureDirs(): void {
+  mkdirSync(GATEWAY_HOME, { recursive: true, mode: 0o700 });
+  mkdirSync(LOG_DIR, { recursive: true, mode: 0o700 });
+}
+
+// ─── PID management ─────────────────────────────────────────────────────────
+
+export function readPid(): number | null {
+  if (!existsSync(PID_FILE)) return null;
+  try {
+    const pid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10);
+    return Number.isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+export function isRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getDaemonPid(): number | null {
+  const pid = readPid();
+  if (pid === null) return null;
+  return isRunning(pid) ? pid : null;
+}
+
+// ─── Entry point resolution ─────────────────────────────────────────────────
+
+export function resolveGatewayEntry(): string {
+  // Check meta.json for custom entry point
+  const meta = readMeta();
+  if (meta?.entryPoint && existsSync(meta.entryPoint)) {
+    return meta.entryPoint;
+  }
+
+  // Try to resolve from globally installed @mosaic/gateway
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgPath = req.resolve('@mosaic/gateway/package.json');
+    const mainEntry = join(resolve(pkgPath, '..'), 'dist', 'main.js');
+    if (existsSync(mainEntry)) return mainEntry;
+  } catch {
+    // Not installed globally
+  }
+
+  throw new Error('Cannot find gateway entry point. Run `mosaic gateway install` first.');
+}
+
+// ─── Start / Stop / Health ──────────────────────────────────────────────────
+
+export function startDaemon(): number {
+  const running = getDaemonPid();
+  if (running !== null) {
+    throw new Error(`Gateway is already running (PID ${running.toString()})`);
+  }
+
+  ensureDirs();
+  const entryPoint = resolveGatewayEntry();
+
+  // Load env vars from gateway .env
+  const env: Record<string, string> = { ...process.env } as Record<string, string>;
+  if (existsSync(ENV_FILE)) {
+    for (const line of readFileSync(ENV_FILE, 'utf-8').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eqIdx = trimmed.indexOf('=');
+      if (eqIdx > 0) env[trimmed.slice(0, eqIdx)] = trimmed.slice(eqIdx + 1);
+    }
+  }
+
+  const logFd = openSync(LOG_FILE, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND);
+
+  const child = spawn('node', [entryPoint], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env,
+    cwd: GATEWAY_HOME,
+  });
+
+  if (!child.pid) {
+    throw new Error('Failed to spawn gateway process');
+  }
+
+  writeFileSync(PID_FILE, child.pid.toString(), { mode: 0o600 });
+  child.unref();
+
+  return child.pid;
+}
+
+export async function stopDaemon(timeoutMs = 10_000): Promise<void> {
+  const pid = getDaemonPid();
+  if (pid === null) {
+    throw new Error('Gateway is not running');
+  }
+
+  process.kill(pid, 'SIGTERM');
+
+  // Poll for exit
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (!isRunning(pid)) {
+      cleanPidFile();
+      return;
+    }
+    await sleep(250);
+  }
+
+  // Force kill
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    // Already dead
+  }
+  cleanPidFile();
+}
+
+function cleanPidFile(): void {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+    // Ignore
+  }
+}
+
+export async function waitForHealth(
+  host: string,
+  port: number,
+  timeoutMs = 30_000,
+): Promise<boolean> {
+  const start = Date.now();
+  let delay = 500;
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://${host}:${port.toString()}/health`);
+      if (res.ok) return true;
+    } catch {
+      // Not ready yet
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 1.5, 3000);
+  }
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── npm install helper ─────────────────────────────────────────────────────
+
+const GITEA_REGISTRY = 'https://git.mosaicstack.dev/api/packages/mosaic/npm/';
+
+export function installGatewayPackage(): void {
+  console.log('Installing @mosaic/gateway from Gitea registry...');
+  execSync(`npm install -g @mosaic/gateway@latest --@mosaic:registry=${GITEA_REGISTRY}`, {
+    stdio: 'inherit',
+    timeout: 120_000,
+  });
+}
+
+export function uninstallGatewayPackage(): void {
+  try {
+    execSync('npm uninstall -g @mosaic/gateway', {
+      stdio: 'inherit',
+      timeout: 60_000,
+    });
+  } catch {
+    console.warn('Warning: npm uninstall may not have completed cleanly.');
+  }
+}
+
+export function getInstalledGatewayVersion(): string | null {
+  try {
+    const output = execSync('npm ls -g @mosaic/gateway --json --depth=0', {
+      encoding: 'utf-8',
+      timeout: 15_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const data = JSON.parse(output) as {
+      dependencies?: { '@mosaic/gateway'?: { version?: string } };
+    };
+    return data.dependencies?.['@mosaic/gateway']?.version ?? null;
+  } catch {
+    return null;
+  }
+}

packages/cli/src/commands/gateway/install.ts

@@ -0,0 +1,259 @@
+import { randomBytes } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import type { GatewayMeta } from './daemon.js';
+import {
+  ENV_FILE,
+  GATEWAY_HOME,
+  ensureDirs,
+  installGatewayPackage,
+  readMeta,
+  resolveGatewayEntry,
+  startDaemon,
+  waitForHealth,
+  writeMeta,
+  getInstalledGatewayVersion,
+} from './daemon.js';
+
+interface InstallOpts {
+  host: string;
+  port: number;
+  skipInstall?: boolean;
+}
+
+function prompt(rl: ReturnType<typeof createInterface>, question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+export async function runInstall(opts: InstallOpts): Promise<void> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await doInstall(rl, opts);
+  } finally {
+    rl.close();
+  }
+}
+
+async function doInstall(rl: ReturnType<typeof createInterface>, opts: InstallOpts): Promise<void> {
+  // Check existing installation
+  const existing = readMeta();
+  if (existing) {
+    const answer = await prompt(
+      rl,
+      `Gateway already installed (v${existing.version}). Reinstall? [y/N] `,
+    );
+    if (answer.toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      return;
+    }
+  }
+
+  // Step 1: Install npm package
+  if (!opts.skipInstall) {
+    installGatewayPackage();
+  }
+
+  ensureDirs();
+
+  // Step 2: Collect configuration
+  console.log('\n─── Gateway Configuration ───\n');
+
+  // Tier selection
+  console.log('Storage tier:');
+  console.log('  1. Local (embedded database, no dependencies)');
+  console.log('  2. Team (PostgreSQL + Valkey required)');
+  const tierAnswer = (await prompt(rl, 'Select [1]: ')).trim() || '1';
+  const tier = tierAnswer === '2' ? 'team' : 'local';
+
+  const port =
+    opts.port !== 14242
+      ? opts.port
+      : parseInt(
+          (await prompt(rl, `Gateway port [${opts.port.toString()}]: `)) || opts.port.toString(),
+          10,
+        );
+
+  let databaseUrl: string | undefined;
+  let valkeyUrl: string | undefined;
+
+  if (tier === 'team') {
+    databaseUrl =
+      (await prompt(rl, 'DATABASE_URL [postgresql://mosaic:mosaic@localhost:5433/mosaic]: ')) ||
+      'postgresql://mosaic:mosaic@localhost:5433/mosaic';
+
+    valkeyUrl =
+      (await prompt(rl, 'VALKEY_URL [redis://localhost:6380]: ')) || 'redis://localhost:6380';
+  }
+
+  const anthropicKey = await prompt(rl, 'ANTHROPIC_API_KEY (optional, press Enter to skip): ');
+
+  const corsOrigin =
+    (await prompt(rl, 'CORS origin [http://localhost:3000]: ')) || 'http://localhost:3000';
+
+  // Generate auth secret
+  const authSecret = randomBytes(32).toString('hex');
+
+  // Step 3: Write .env
+  const envLines = [
+    `GATEWAY_PORT=${port.toString()}`,
+    `BETTER_AUTH_SECRET=${authSecret}`,
+    `BETTER_AUTH_URL=http://${opts.host}:${port.toString()}`,
+    `GATEWAY_CORS_ORIGIN=${corsOrigin}`,
+    `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`,
+    `OTEL_SERVICE_NAME=mosaic-gateway`,
+  ];
+
+  if (tier === 'team' && databaseUrl && valkeyUrl) {
+    envLines.push(`DATABASE_URL=${databaseUrl}`);
+    envLines.push(`VALKEY_URL=${valkeyUrl}`);
+  }
+
+  if (anthropicKey) {
+    envLines.push(`ANTHROPIC_API_KEY=${anthropicKey}`);
+  }
+
+  writeFileSync(ENV_FILE, envLines.join('\n') + '\n', { mode: 0o600 });
+  console.log(`\nConfig written to ${ENV_FILE}`);
+
+  // Step 3b: Write mosaic.config.json
+  const mosaicConfig =
+    tier === 'local'
+      ? {
+          tier: 'local',
+          storage: { type: 'pglite', dataDir: join(GATEWAY_HOME, 'storage-pglite') },
+          queue: { type: 'local', dataDir: join(GATEWAY_HOME, 'queue') },
+          memory: { type: 'keyword' },
+        }
+      : {
+          tier: 'team',
+          storage: { type: 'postgres', url: databaseUrl },
+          queue: { type: 'bullmq', url: valkeyUrl },
+          memory: { type: 'pgvector' },
+        };
+
+  const configFile = join(GATEWAY_HOME, 'mosaic.config.json');
+  writeFileSync(configFile, JSON.stringify(mosaicConfig, null, 2) + '\n', { mode: 0o600 });
+  console.log(`Config written to ${configFile}`);
+
+  // Step 4: Write meta.json
+  let entryPoint: string;
+  try {
+    entryPoint = resolveGatewayEntry();
+  } catch {
+    console.error('Error: Gateway package not found after install.');
+    console.error('Check that @mosaic/gateway installed correctly.');
+    return;
+  }
+
+  const version = getInstalledGatewayVersion() ?? 'unknown';
+
+  const meta = {
+    version,
+    installedAt: new Date().toISOString(),
+    entryPoint,
+    host: opts.host,
+    port,
+  };
+  writeMeta(meta);
+
+  // Step 5: Start the daemon
+  console.log('\nStarting gateway daemon...');
+  try {
+    const pid = startDaemon();
+    console.log(`Gateway started (PID ${pid.toString()})`);
+  } catch (err) {
+    console.error(`Failed to start: ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+
+  // Step 6: Wait for health
+  console.log('Waiting for gateway to become healthy...');
+  const healthy = await waitForHealth(opts.host, port, 30_000);
+  if (!healthy) {
+    console.error('Gateway did not become healthy within 30 seconds.');
+    console.error(`Check logs: mosaic gateway logs`);
+    return;
+  }
+  console.log('Gateway is healthy.\n');
+
+  // Step 7: Bootstrap — first user setup
+  await bootstrapFirstUser(rl, opts.host, port, meta);
+
+  console.log('\n─── Installation Complete ───');
+  console.log(`  Endpoint:  http://${opts.host}:${port.toString()}`);
+  console.log(`  Config:    ${GATEWAY_HOME}`);
+  console.log(`  Logs:      mosaic gateway logs`);
+  console.log(`  Status:    mosaic gateway status`);
+}
+
+async function bootstrapFirstUser(
+  rl: ReturnType<typeof createInterface>,
+  host: string,
+  port: number,
+  meta: Omit<GatewayMeta, 'adminToken'> & { adminToken?: string },
+): Promise<void> {
+  const baseUrl = `http://${host}:${port.toString()}`;
+
+  try {
+    const statusRes = await fetch(`${baseUrl}/api/bootstrap/status`);
+    if (!statusRes.ok) return;
+
+    const status = (await statusRes.json()) as { needsSetup: boolean };
+    if (!status.needsSetup) {
+      console.log('Admin user already exists — skipping setup.');
+      return;
+    }
+  } catch {
+    console.warn('Could not check bootstrap status — skipping first user setup.');
+    return;
+  }
+
+  console.log('─── Admin User Setup ───\n');
+
+  const name = (await prompt(rl, 'Admin name: ')).trim();
+  if (!name) {
+    console.error('Name is required.');
+    return;
+  }
+
+  const email = (await prompt(rl, 'Admin email: ')).trim();
+  if (!email) {
+    console.error('Email is required.');
+    return;
+  }
+
+  const password = (await prompt(rl, 'Admin password (min 8 chars): ')).trim();
+  if (password.length < 8) {
+    console.error('Password must be at least 8 characters.');
+    return;
+  }
+
+  try {
+    const res = await fetch(`${baseUrl}/api/bootstrap/setup`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, email, password }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      console.error(`Bootstrap failed (${res.status.toString()}): ${body}`);
+      return;
+    }
+
+    const result = (await res.json()) as {
+      user: { id: string; email: string };
+      token: { plaintext: string };
+    };
+
+    // Save admin token to meta
+    meta.adminToken = result.token.plaintext;
+    writeMeta(meta as GatewayMeta);
+
+    console.log(`\nAdmin user created: ${result.user.email}`);
+    console.log('Admin API token saved to gateway config.');
+  } catch (err) {
+    console.error(`Bootstrap error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

packages/cli/src/commands/gateway/logs.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { LOG_FILE } from './daemon.js';
+
+interface LogsOpts {
+  follow?: boolean;
+  lines?: number;
+}
+
+export function runLogs(opts: LogsOpts): void {
+  if (!existsSync(LOG_FILE)) {
+    console.log('No log file found. Is the gateway installed?');
+    return;
+  }
+
+  if (opts.follow) {
+    const lines = opts.lines ?? 50;
+    const tail = spawn('tail', ['-n', lines.toString(), '-f', LOG_FILE], {
+      stdio: 'inherit',
+    });
+    tail.on('error', () => {
+      // Fallback for systems without tail
+      console.log(readLastLines(opts.lines ?? 50));
+      console.log('\n(--follow requires `tail` command)');
+    });
+    return;
+  }
+
+  // Just print last N lines
+  console.log(readLastLines(opts.lines ?? 50));
+}
+
+function readLastLines(n: number): string {
+  const content = readFileSync(LOG_FILE, 'utf-8');
+  const lines = content.split('\n');
+  return lines.slice(-n).join('\n');
+}

packages/cli/src/commands/gateway/status.ts

@@ -0,0 +1,115 @@
+import { getDaemonPid, readMeta, LOG_FILE, GATEWAY_HOME } from './daemon.js';
+
+interface GatewayOpts {
+  host: string;
+  port: number;
+  token?: string;
+}
+
+interface ServiceStatus {
+  name: string;
+  status: string;
+  latency?: string;
+}
+
+interface AdminHealth {
+  status: string;
+  services: {
+    database: { status: string; latencyMs: number };
+    cache: { status: string; latencyMs: number };
+  };
+  agentPool?: { active: number };
+  providers?: Array<{ name: string; available: boolean; models: number }>;
+}
+
+export async function runStatus(opts: GatewayOpts): Promise<void> {
+  const meta = readMeta();
+  const pid = getDaemonPid();
+
+  console.log('Mosaic Gateway Status');
+  console.log('─────────────────────');
+
+  // Daemon status
+  if (pid !== null) {
+    console.log(`  Status:    running (PID ${pid.toString()})`);
+  } else {
+    console.log('  Status:    stopped');
+  }
+
+  // Version
+  console.log(`  Version:   ${meta?.version ?? 'unknown'}`);
+
+  // Endpoint
+  const host = opts.host;
+  const port = opts.port;
+  console.log(`  Endpoint:  http://${host}:${port.toString()}`);
+  console.log(`  Config:    ${GATEWAY_HOME}`);
+  console.log(`  Logs:      ${LOG_FILE}`);
+
+  if (pid === null) return;
+
+  // Health check
+  try {
+    const healthRes = await fetch(`http://${host}:${port.toString()}/health`);
+    if (!healthRes.ok) {
+      console.log('\n  Health:    unreachable');
+      return;
+    }
+  } catch {
+    console.log('\n  Health:    unreachable');
+    return;
+  }
+
+  // Admin health (requires token)
+  const token = opts.token ?? meta?.adminToken;
+  if (!token) {
+    console.log(
+      '\n  (No admin token — run `mosaic gateway config` to set one for detailed status)',
+    );
+    return;
+  }
+
+  try {
+    const res = await fetch(`http://${host}:${port.toString()}/api/admin/health`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!res.ok) {
+      console.log('\n  Admin health: unauthorized or unavailable');
+      return;
+    }
+
+    const health = (await res.json()) as AdminHealth;
+
+    console.log('\n  Services:');
+    const services: ServiceStatus[] = [
+      {
+        name: 'Database',
+        status: health.services.database.status,
+        latency: `${health.services.database.latencyMs.toString()}ms`,
+      },
+      {
+        name: 'Cache',
+        status: health.services.cache.status,
+        latency: `${health.services.cache.latencyMs.toString()}ms`,
+      },
+    ];
+
+    for (const svc of services) {
+      const latStr = svc.latency ? ` (${svc.latency})` : '';
+      console.log(`    ${svc.name}:${' '.repeat(10 - svc.name.length)}${svc.status}${latStr}`);
+    }
+
+    if (health.providers && health.providers.length > 0) {
+      const available = health.providers.filter((p) => p.available);
+      const names = available.map((p) => p.name).join(', ');
+      console.log(`\n  Providers: ${available.length.toString()} active (${names})`);
+    }
+
+    if (health.agentPool) {
+      console.log(`  Sessions:  ${health.agentPool.active.toString()} active`);
+    }
+  } catch {
+    console.log('\n  Admin health: connection error');
+  }
+}

packages/cli/src/commands/gateway/uninstall.ts

@@ -0,0 +1,62 @@
+import { existsSync, rmSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import {
+  GATEWAY_HOME,
+  getDaemonPid,
+  readMeta,
+  stopDaemon,
+  uninstallGatewayPackage,
+} from './daemon.js';
+
+export async function runUninstall(): Promise<void> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await doUninstall(rl);
+  } finally {
+    rl.close();
+  }
+}
+
+function prompt(rl: ReturnType<typeof createInterface>, question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function doUninstall(rl: ReturnType<typeof createInterface>): Promise<void> {
+  const meta = readMeta();
+  if (!meta) {
+    console.log('Gateway is not installed.');
+    return;
+  }
+
+  const answer = await prompt(rl, 'Uninstall Mosaic Gateway? [y/N] ');
+  if (answer.toLowerCase() !== 'y') {
+    console.log('Aborted.');
+    return;
+  }
+
+  // Stop if running
+  if (getDaemonPid() !== null) {
+    console.log('Stopping gateway daemon...');
+    try {
+      await stopDaemon();
+      console.log('Stopped.');
+    } catch (err) {
+      console.warn(`Warning: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Remove config/data
+  const removeData = await prompt(rl, `Remove all gateway data at ${GATEWAY_HOME}? [y/N] `);
+  if (removeData.toLowerCase() === 'y') {
+    if (existsSync(GATEWAY_HOME)) {
+      rmSync(GATEWAY_HOME, { recursive: true, force: true });
+      console.log('Gateway data removed.');
+    }
+  }
+
+  // Uninstall npm package
+  console.log('Uninstalling npm package...');
+  uninstallGatewayPackage();
+
+  console.log('\nGateway uninstalled.');
+}

packages/cli/src/commands/launch.ts

@@ -7,6 +7,7 @@
 
 import { execFileSync, execSync, spawnSync } from 'node:child_process';
 import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
 import { homedir } from 'node:os';
 import { join, dirname } from 'node:path';
 import type { Command } from 'commander';
@@ -67,7 +68,7 @@ function checkSoul(): void {
     }
 
     // Fallback: legacy bash mosaic-init
-    const initBin = join(MOSAIC_HOME, 'tools', '_scripts', 'mosaic-init');
+    const initBin = fwScript('mosaic-init');
     if (existsSync(initBin)) {
       spawnSync(initBin, [], { stdio: 'inherit' });
     } else {
@@ -78,7 +79,7 @@ function checkSoul(): void {
 }
 
 function checkSequentialThinking(runtime: string): void {
-  const checker = join(MOSAIC_HOME, 'tools', '_scripts', 'mosaic-ensure-sequential-thinking');
+  const checker = fwScript('mosaic-ensure-sequential-thinking');
   if (!existsSync(checker)) return; // Skip if checker doesn't exist
   const result = spawnSync(checker, ['--check', '--runtime', runtime], { stdio: 'ignore' });
   if (result.status !== 0) {
@@ -491,12 +492,29 @@ function delegateToScript(scriptPath: string, args: string[], env?: Record<strin
   }
 }
 
+/**
+ * Resolve a path under the framework tools directory. Prefers the version
+ * bundled in the @mosaic/mosaic npm package (always matches the installed
+ * CLI version) over the deployed copy in ~/.config/mosaic/ (may be stale).
+ */
+function resolveTool(...segments: string[]): string {
+  try {
+    const req = createRequire(import.meta.url);
+    const mosaicPkg = dirname(req.resolve('@mosaic/mosaic/package.json'));
+    const bundled = join(mosaicPkg, 'framework', 'tools', ...segments);
+    if (existsSync(bundled)) return bundled;
+  } catch {
+    // Fall through to deployed copy
+  }
+  return join(MOSAIC_HOME, 'tools', ...segments);
+}
+
 function fwScript(name: string): string {
-  return join(MOSAIC_HOME, 'tools', '_scripts', name);
+  return resolveTool('_scripts', name);
 }
 
 function toolScript(toolDir: string, name: string): string {
-  return join(MOSAIC_HOME, 'tools', toolDir, name);
+  return resolveTool(toolDir, name);
 }
 
 // ─── Coord (mission orchestrator) ───────────────────────────────────────────

packages/cli/src/commands/mission.ts

@@ -40,7 +40,7 @@ export function registerMissionCommand(program: Command) {
   const cmd = program
     .command('mission')
     .description('Manage missions')
-    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
     .option('--list', 'List all missions')
     .option('--init', 'Create a new mission')
     .option('--plan <idOrName>', 'Run PRD wizard for a mission')
@@ -86,7 +86,7 @@ export function registerMissionCommand(program: Command) {
   cmd
     .command('task')
     .description('Manage mission tasks')
-    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
     .option('--list', 'List tasks for a mission')
     .option('--new', 'Create a task')
     .option('--update <taskId>', 'Update a task')

packages/cli/src/commands/prdy.ts

@@ -6,7 +6,7 @@ export function registerPrdyCommand(program: Command) {
   const cmd = program
     .command('prdy')
     .description('PRD wizard — create and manage Product Requirement Documents')
-    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:4000')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
     .option('--init [name]', 'Create a new PRD')
     .option('--update [name]', 'Update an existing PRD')
     .option('--project <idOrName>', 'Scope to project')

packages/config/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mosaic/config",
+  "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/config"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  },
+  "dependencies": {
+    "@mosaic/memory": "workspace:^",
+    "@mosaic/queue": "workspace:^",
+    "@mosaic/storage": "workspace:^"
+  },
+  "devDependencies": {
+    "eslint": "^9.0.0",
+    "typescript": "^5.8.0",
+    "vitest": "^2.0.0"
+  },
+  "publishConfig": {
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaic/npm/",
+    "access": "public"
+  },
+  "files": [
+    "dist"
+  ]
+}

packages/config/src/index.ts

@@ -0,0 +1,7 @@
+export type { MosaicConfig, StorageTier, MemoryConfigRef } from './mosaic-config.js';
+export {
+  DEFAULT_LOCAL_CONFIG,
+  DEFAULT_TEAM_CONFIG,
+  loadConfig,
+  validateConfig,
+} from './mosaic-config.js';

packages/config/src/mosaic-config.ts

@@ -0,0 +1,140 @@
+import { readFileSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import type { StorageConfig } from '@mosaic/storage';
+import type { QueueAdapterConfig as QueueConfig } from '@mosaic/queue';
+
+/* ------------------------------------------------------------------ */
+/*  Types                                                              */
+/* ------------------------------------------------------------------ */
+
+export type StorageTier = 'local' | 'team';
+
+export interface MemoryConfigRef {
+  type: 'pgvector' | 'sqlite-vec' | 'keyword';
+}
+
+export interface MosaicConfig {
+  tier: StorageTier;
+  storage: StorageConfig;
+  queue: QueueConfig;
+  memory: MemoryConfigRef;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Defaults                                                           */
+/* ------------------------------------------------------------------ */
+
+export const DEFAULT_LOCAL_CONFIG: MosaicConfig = {
+  tier: 'local',
+  storage: { type: 'pglite', dataDir: '.mosaic/storage-pglite' },
+  queue: { type: 'local', dataDir: '.mosaic/queue' },
+  memory: { type: 'keyword' },
+};
+
+export const DEFAULT_TEAM_CONFIG: MosaicConfig = {
+  tier: 'team',
+  storage: { type: 'postgres', url: 'postgresql://mosaic:mosaic@localhost:5432/mosaic' },
+  queue: { type: 'bullmq' },
+  memory: { type: 'pgvector' },
+};
+
+/* ------------------------------------------------------------------ */
+/*  Validation                                                         */
+/* ------------------------------------------------------------------ */
+
+const VALID_TIERS = new Set<string>(['local', 'team']);
+const VALID_STORAGE_TYPES = new Set<string>(['postgres', 'pglite', 'files']);
+const VALID_QUEUE_TYPES = new Set<string>(['bullmq', 'local']);
+const VALID_MEMORY_TYPES = new Set<string>(['pgvector', 'sqlite-vec', 'keyword']);
+
+export function validateConfig(raw: unknown): MosaicConfig {
+  if (typeof raw !== 'object' || raw === null) {
+    throw new Error('MosaicConfig must be a non-null object');
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  // tier
+  const tier = obj['tier'];
+  if (typeof tier !== 'string' || !VALID_TIERS.has(tier)) {
+    throw new Error(`Invalid tier "${String(tier)}" — expected "local" or "team"`);
+  }
+
+  // storage
+  const storage = obj['storage'];
+  if (typeof storage !== 'object' || storage === null) {
+    throw new Error('config.storage must be a non-null object');
+  }
+  const storageType = (storage as Record<string, unknown>)['type'];
+  if (typeof storageType !== 'string' || !VALID_STORAGE_TYPES.has(storageType)) {
+    throw new Error(`Invalid storage.type "${String(storageType)}"`);
+  }
+
+  // queue
+  const queue = obj['queue'];
+  if (typeof queue !== 'object' || queue === null) {
+    throw new Error('config.queue must be a non-null object');
+  }
+  const queueType = (queue as Record<string, unknown>)['type'];
+  if (typeof queueType !== 'string' || !VALID_QUEUE_TYPES.has(queueType)) {
+    throw new Error(`Invalid queue.type "${String(queueType)}"`);
+  }
+
+  // memory
+  const memory = obj['memory'];
+  if (typeof memory !== 'object' || memory === null) {
+    throw new Error('config.memory must be a non-null object');
+  }
+  const memoryType = (memory as Record<string, unknown>)['type'];
+  if (typeof memoryType !== 'string' || !VALID_MEMORY_TYPES.has(memoryType)) {
+    throw new Error(`Invalid memory.type "${String(memoryType)}"`);
+  }
+
+  return {
+    tier: tier as StorageTier,
+    storage: storage as StorageConfig,
+    queue: queue as QueueConfig,
+    memory: memory as MemoryConfigRef,
+  };
+}
+
+/* ------------------------------------------------------------------ */
+/*  Loader                                                             */
+/* ------------------------------------------------------------------ */
+
+function detectFromEnv(): MosaicConfig {
+  if (process.env['DATABASE_URL']) {
+    return {
+      ...DEFAULT_TEAM_CONFIG,
+      storage: {
+        type: 'postgres',
+        url: process.env['DATABASE_URL'],
+      },
+      queue: {
+        type: 'bullmq',
+        url: process.env['VALKEY_URL'],
+      },
+    };
+  }
+  return DEFAULT_LOCAL_CONFIG;
+}
+
+export function loadConfig(configPath?: string): MosaicConfig {
+  // 1. Explicit path or default location
+  const paths = configPath
+    ? [resolve(configPath)]
+    : [
+        resolve(process.cwd(), 'mosaic.config.json'),
+        resolve(process.cwd(), '../../mosaic.config.json'), // monorepo root when cwd is apps/gateway
+      ];
+
+  for (const p of paths) {
+    if (existsSync(p)) {
+      const raw: unknown = JSON.parse(readFileSync(p, 'utf-8'));
+      return validateConfig(raw);
+    }
+  }
+
+  // 2. Fall back to env-var detection
+  return detectFromEnv();
+}

packages/config/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src"
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist"]
+}

packages/coord/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/coord",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/coord"
+  },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/db/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/db",
-  "version": "0.0.2",
+  "version": "0.0.3",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/db"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -28,6 +33,7 @@
     "vitest": "^2.0.0"
   },
   "dependencies": {
+    "@electric-sql/pglite": "^0.2.17",
     "drizzle-orm": "^0.45.1",
     "postgres": "^3.4.8"
   },

packages/db/src/client-pglite.ts

@@ -0,0 +1,15 @@
+import { PGlite } from '@electric-sql/pglite';
+import { drizzle } from 'drizzle-orm/pglite';
+import * as schema from './schema.js';
+import type { DbHandle } from './client.js';
+
+export function createPgliteDb(dataDir: string): DbHandle {
+  const client = new PGlite(dataDir);
+  const db = drizzle(client, { schema });
+  return {
+    db: db as unknown as DbHandle['db'],
+    close: async () => {
+      await client.close();
+    },
+  };
+}

packages/db/src/index.ts

@@ -1,4 +1,5 @@
 export { createDb, type Db, type DbHandle } from './client.js';
+export { createPgliteDb } from './client-pglite.js';
 export { runMigrations } from './migrate.js';
 export * from './schema.js';
 export {
@@ -16,4 +17,5 @@ export {
   gte,
   lte,
   ilike,
+  count,
 } from 'drizzle-orm';

packages/db/src/schema.ts

@@ -91,6 +91,28 @@ export const verifications = pgTable('verifications', {
   updatedAt: timestamp('updated_at', { withTimezone: true }).notNull().defaultNow(),
 });
 
+// ─── Admin API Tokens ───────────────────────────────────────────────────────
+
+export const adminTokens = pgTable(
+  'admin_tokens',
+  {
+    id: text('id').primaryKey(),
+    userId: text('user_id')
+      .notNull()
+      .references(() => users.id, { onDelete: 'cascade' }),
+    tokenHash: text('token_hash').notNull(),
+    label: text('label').notNull(),
+    scope: text('scope').notNull().default('admin'),
+    expiresAt: timestamp('expires_at', { withTimezone: true }),
+    lastUsedAt: timestamp('last_used_at', { withTimezone: true }),
+    createdAt: timestamp('created_at', { withTimezone: true }).notNull().defaultNow(),
+  },
+  (t) => [
+    index('admin_tokens_user_id_idx').on(t.userId),
+    uniqueIndex('admin_tokens_hash_idx').on(t.tokenHash),
+  ],
+);
+
 // ─── Teams ───────────────────────────────────────────────────────────────────
 // Declared before projects because projects references teams.
 

packages/design-tokens/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/design-tokens",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/design-tokens"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/forge/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/forge",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/forge"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/log/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/log",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/log"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/macp/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/macp",
   "version": "0.0.2",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/macp"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/memory/package.json

@@ -1,6 +1,11 @@
 {
   "name": "@mosaic/memory",
-  "version": "0.0.2",
+  "version": "0.0.3",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/memory"
+  },
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,6 +23,7 @@
   },
   "dependencies": {
     "@mosaic/db": "workspace:*",
+    "@mosaic/storage": "workspace:*",
     "@mosaic/types": "workspace:*",
     "drizzle-orm": "^0.45.1"
   },

packages/memory/src/adapters/keyword.test.ts

@@ -0,0 +1,298 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import type { StorageAdapter } from '@mosaic/storage';
+import { KeywordAdapter } from './keyword.js';
+
+/* ------------------------------------------------------------------ */
+/*  In-memory mock StorageAdapter                                     */
+/* ------------------------------------------------------------------ */
+
+function createMockStorage(): StorageAdapter {
+  const collections = new Map<string, Map<string, Record<string, unknown>>>();
+  let idCounter = 0;
+
+  function getCollection(name: string): Map<string, Record<string, unknown>> {
+    if (!collections.has(name)) collections.set(name, new Map());
+    return collections.get(name)!;
+  }
+
+  const adapter: StorageAdapter = {
+    name: 'mock',
+
+    async create<T extends Record<string, unknown>>(
+      collection: string,
+      data: T,
+    ): Promise<T & { id: string }> {
+      const id = String(++idCounter);
+      const record = { ...data, id };
+      getCollection(collection).set(id, record);
+      return record as T & { id: string };
+    },
+
+    async read<T extends Record<string, unknown>>(
+      collection: string,
+      id: string,
+    ): Promise<T | null> {
+      const record = getCollection(collection).get(id);
+      return (record as T) ?? null;
+    },
+
+    async update(collection: string, id: string, data: Record<string, unknown>): Promise<boolean> {
+      const col = getCollection(collection);
+      const existing = col.get(id);
+      if (!existing) return false;
+      col.set(id, { ...existing, ...data });
+      return true;
+    },
+
+    async delete(collection: string, id: string): Promise<boolean> {
+      return getCollection(collection).delete(id);
+    },
+
+    async find<T extends Record<string, unknown>>(
+      collection: string,
+      filter?: Record<string, unknown>,
+    ): Promise<T[]> {
+      const col = getCollection(collection);
+      const results: T[] = [];
+      for (const record of col.values()) {
+        if (filter && !matchesFilter(record, filter)) continue;
+        results.push(record as T);
+      }
+      return results;
+    },
+
+    async findOne<T extends Record<string, unknown>>(
+      collection: string,
+      filter: Record<string, unknown>,
+    ): Promise<T | null> {
+      const col = getCollection(collection);
+      for (const record of col.values()) {
+        if (matchesFilter(record, filter)) return record as T;
+      }
+      return null;
+    },
+
+    async count(collection: string, filter?: Record<string, unknown>): Promise<number> {
+      const rows = await adapter.find(collection, filter);
+      return rows.length;
+    },
+
+    async transaction<T>(fn: (tx: StorageAdapter) => Promise<T>): Promise<T> {
+      return fn(adapter);
+    },
+
+    async migrate(): Promise<void> {},
+    async close(): Promise<void> {},
+  };
+
+  return adapter;
+}
+
+function matchesFilter(record: Record<string, unknown>, filter: Record<string, unknown>): boolean {
+  for (const [key, value] of Object.entries(filter)) {
+    if (record[key] !== value) return false;
+  }
+  return true;
+}
+
+/* ------------------------------------------------------------------ */
+/*  Tests                                                             */
+/* ------------------------------------------------------------------ */
+
+describe('KeywordAdapter', () => {
+  let adapter: KeywordAdapter;
+
+  beforeEach(() => {
+    adapter = new KeywordAdapter({ type: 'keyword', storage: createMockStorage() });
+  });
+
+  /* ---- Preferences ---- */
+
+  describe('preferences', () => {
+    it('should set and get a preference', async () => {
+      await adapter.setPreference('u1', 'theme', 'dark');
+      const value = await adapter.getPreference('u1', 'theme');
+      expect(value).toBe('dark');
+    });
+
+    it('should return null for missing preference', async () => {
+      const value = await adapter.getPreference('u1', 'nonexistent');
+      expect(value).toBeNull();
+    });
+
+    it('should upsert an existing preference', async () => {
+      await adapter.setPreference('u1', 'theme', 'dark');
+      await adapter.setPreference('u1', 'theme', 'light');
+      const value = await adapter.getPreference('u1', 'theme');
+      expect(value).toBe('light');
+    });
+
+    it('should delete a preference', async () => {
+      await adapter.setPreference('u1', 'theme', 'dark');
+      const deleted = await adapter.deletePreference('u1', 'theme');
+      expect(deleted).toBe(true);
+      const value = await adapter.getPreference('u1', 'theme');
+      expect(value).toBeNull();
+    });
+
+    it('should return false when deleting nonexistent preference', async () => {
+      const deleted = await adapter.deletePreference('u1', 'nope');
+      expect(deleted).toBe(false);
+    });
+
+    it('should list preferences by userId', async () => {
+      await adapter.setPreference('u1', 'theme', 'dark', 'appearance');
+      await adapter.setPreference('u1', 'lang', 'en', 'locale');
+      await adapter.setPreference('u2', 'theme', 'light', 'appearance');
+
+      const prefs = await adapter.listPreferences('u1');
+      expect(prefs).toHaveLength(2);
+      expect(prefs.map((p) => p.key).sort()).toEqual(['lang', 'theme']);
+    });
+
+    it('should filter preferences by category', async () => {
+      await adapter.setPreference('u1', 'theme', 'dark', 'appearance');
+      await adapter.setPreference('u1', 'lang', 'en', 'locale');
+
+      const prefs = await adapter.listPreferences('u1', 'appearance');
+      expect(prefs).toHaveLength(1);
+      expect(prefs[0]!.key).toBe('theme');
+    });
+  });
+
+  /* ---- Insights ---- */
+
+  describe('insights', () => {
+    it('should store and retrieve an insight', async () => {
+      const insight = await adapter.storeInsight({
+        userId: 'u1',
+        content: 'TypeScript is great for type safety',
+        source: 'chat',
+        category: 'technical',
+        relevanceScore: 0.9,
+      });
+
+      expect(insight.id).toBeDefined();
+      expect(insight.content).toBe('TypeScript is great for type safety');
+
+      const fetched = await adapter.getInsight(insight.id);
+      expect(fetched).not.toBeNull();
+      expect(fetched!.content).toBe('TypeScript is great for type safety');
+    });
+
+    it('should return null for missing insight', async () => {
+      const result = await adapter.getInsight('nonexistent');
+      expect(result).toBeNull();
+    });
+
+    it('should delete an insight', async () => {
+      const insight = await adapter.storeInsight({
+        userId: 'u1',
+        content: 'test',
+        source: 'chat',
+        category: 'general',
+        relevanceScore: 0.5,
+      });
+
+      const deleted = await adapter.deleteInsight(insight.id);
+      expect(deleted).toBe(true);
+
+      const fetched = await adapter.getInsight(insight.id);
+      expect(fetched).toBeNull();
+    });
+  });
+
+  /* ---- Keyword Search ---- */
+
+  describe('searchInsights', () => {
+    beforeEach(async () => {
+      await adapter.storeInsight({
+        userId: 'u1',
+        content: 'TypeScript provides excellent type safety for JavaScript projects',
+        source: 'chat',
+        category: 'technical',
+        relevanceScore: 0.9,
+      });
+      await adapter.storeInsight({
+        userId: 'u1',
+        content: 'React hooks simplify state management in components',
+        source: 'chat',
+        category: 'technical',
+        relevanceScore: 0.8,
+      });
+      await adapter.storeInsight({
+        userId: 'u1',
+        content: 'TypeScript and React work great together for type safe components',
+        source: 'chat',
+        category: 'technical',
+        relevanceScore: 0.85,
+      });
+      await adapter.storeInsight({
+        userId: 'u2',
+        content: 'TypeScript is popular',
+        source: 'chat',
+        category: 'general',
+        relevanceScore: 0.5,
+      });
+    });
+
+    it('should find insights by exact keyword', async () => {
+      const results = await adapter.searchInsights('u1', 'hooks');
+      expect(results).toHaveLength(1);
+      expect(results[0]!.content).toContain('hooks');
+    });
+
+    it('should be case-insensitive', async () => {
+      const results = await adapter.searchInsights('u1', 'TYPESCRIPT');
+      expect(results.length).toBeGreaterThanOrEqual(1);
+      for (const r of results) {
+        expect(r.content.toLowerCase()).toContain('typescript');
+      }
+    });
+
+    it('should rank multi-word matches higher', async () => {
+      const results = await adapter.searchInsights('u1', 'TypeScript React');
+      // The insight mentioning both "TypeScript" and "React" should rank first (score=2)
+      expect(results[0]!.score).toBe(2);
+      expect(results[0]!.content).toContain('TypeScript');
+      expect(results[0]!.content).toContain('React');
+    });
+
+    it('should return empty for no matches', async () => {
+      const results = await adapter.searchInsights('u1', 'python django');
+      expect(results).toHaveLength(0);
+    });
+
+    it('should filter by userId', async () => {
+      const results = await adapter.searchInsights('u2', 'TypeScript');
+      expect(results).toHaveLength(1);
+      expect(results[0]!.content).toBe('TypeScript is popular');
+    });
+
+    it('should respect limit option', async () => {
+      const results = await adapter.searchInsights('u1', 'TypeScript', { limit: 1 });
+      expect(results).toHaveLength(1);
+    });
+
+    it('should return empty for empty query', async () => {
+      const results = await adapter.searchInsights('u1', '   ');
+      expect(results).toHaveLength(0);
+    });
+  });
+
+  /* ---- Lifecycle ---- */
+
+  describe('lifecycle', () => {
+    it('should have name "keyword"', () => {
+      expect(adapter.name).toBe('keyword');
+    });
+
+    it('should have null embedder', () => {
+      expect(adapter.embedder).toBeNull();
+    });
+
+    it('should close without error', async () => {
+      await expect(adapter.close()).resolves.toBeUndefined();
+    });
+  });
+});

packages/memory/src/adapters/keyword.ts

@@ -0,0 +1,195 @@
+import type { StorageAdapter } from '@mosaic/storage';
+import type {
+  MemoryAdapter,
+  MemoryConfig,
+  NewInsight,
+  Insight,
+  InsightSearchResult,
+} from '../types.js';
+import type { EmbeddingProvider } from '../vector-store.js';
+
+type KeywordConfig = Extract<MemoryConfig, { type: 'keyword' }>;
+
+const PREFERENCES = 'preferences';
+const INSIGHTS = 'insights';
+
+type PreferenceRecord = Record<string, unknown> & {
+  id: string;
+  userId: string;
+  key: string;
+  value: unknown;
+  category: string;
+};
+
+type InsightRecord = Record<string, unknown> & {
+  id: string;
+  userId: string;
+  content: string;
+  source: string;
+  category: string;
+  relevanceScore: number;
+  metadata: Record<string, unknown>;
+  createdAt: string;
+  updatedAt?: string;
+  decayedAt?: string;
+};
+
+export class KeywordAdapter implements MemoryAdapter {
+  readonly name = 'keyword';
+  readonly embedder: EmbeddingProvider | null = null;
+
+  private storage: StorageAdapter;
+
+  constructor(config: KeywordConfig) {
+    this.storage = config.storage;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Preferences                                                       */
+  /* ------------------------------------------------------------------ */
+
+  async getPreference(userId: string, key: string): Promise<unknown | null> {
+    const row = await this.storage.findOne<PreferenceRecord>(PREFERENCES, { userId, key });
+    return row?.value ?? null;
+  }
+
+  async setPreference(
+    userId: string,
+    key: string,
+    value: unknown,
+    category?: string,
+  ): Promise<void> {
+    const existing = await this.storage.findOne<PreferenceRecord>(PREFERENCES, { userId, key });
+    if (existing) {
+      await this.storage.update(PREFERENCES, existing.id, {
+        value,
+        ...(category !== undefined ? { category } : {}),
+      });
+    } else {
+      await this.storage.create(PREFERENCES, {
+        userId,
+        key,
+        value,
+        category: category ?? 'general',
+      });
+    }
+  }
+
+  async deletePreference(userId: string, key: string): Promise<boolean> {
+    const existing = await this.storage.findOne<PreferenceRecord>(PREFERENCES, { userId, key });
+    if (!existing) return false;
+    return this.storage.delete(PREFERENCES, existing.id);
+  }
+
+  async listPreferences(
+    userId: string,
+    category?: string,
+  ): Promise<Array<{ key: string; value: unknown; category: string }>> {
+    const filter: Record<string, unknown> = { userId };
+    if (category !== undefined) filter.category = category;
+
+    const rows = await this.storage.find<PreferenceRecord>(PREFERENCES, filter);
+    return rows.map((r) => ({ key: r.key, value: r.value, category: r.category }));
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Insights                                                          */
+  /* ------------------------------------------------------------------ */
+
+  async storeInsight(insight: NewInsight): Promise<Insight> {
+    const now = new Date();
+    const row = await this.storage.create<Record<string, unknown>>(INSIGHTS, {
+      userId: insight.userId,
+      content: insight.content,
+      source: insight.source,
+      category: insight.category,
+      relevanceScore: insight.relevanceScore,
+      metadata: insight.metadata ?? {},
+      createdAt: now.toISOString(),
+    });
+
+    return {
+      id: row.id,
+      userId: insight.userId,
+      content: insight.content,
+      source: insight.source,
+      category: insight.category,
+      relevanceScore: insight.relevanceScore,
+      metadata: insight.metadata,
+      createdAt: now,
+    };
+  }
+
+  async getInsight(id: string): Promise<Insight | null> {
+    const row = await this.storage.read<InsightRecord>(INSIGHTS, id);
+    if (!row) return null;
+    return toInsight(row);
+  }
+
+  async searchInsights(
+    userId: string,
+    query: string,
+    opts?: { limit?: number; embedding?: number[] },
+  ): Promise<InsightSearchResult[]> {
+    const limit = opts?.limit ?? 10;
+    const words = query
+      .toLowerCase()
+      .split(/\s+/)
+      .filter((w) => w.length > 0);
+
+    if (words.length === 0) return [];
+
+    const rows = await this.storage.find<InsightRecord>(INSIGHTS, { userId });
+
+    const scored: InsightSearchResult[] = [];
+    for (const row of rows) {
+      const content = row.content.toLowerCase();
+      let score = 0;
+      for (const word of words) {
+        if (content.includes(word)) score++;
+      }
+      if (score > 0) {
+        scored.push({
+          id: row.id,
+          content: row.content,
+          score,
+          metadata: row.metadata ?? undefined,
+        });
+      }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    return scored.slice(0, limit);
+  }
+
+  async deleteInsight(id: string): Promise<boolean> {
+    return this.storage.delete(INSIGHTS, id);
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Lifecycle                                                         */
+  /* ------------------------------------------------------------------ */
+
+  async close(): Promise<void> {
+    // no-op — storage adapter manages its own lifecycle
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+function toInsight(row: InsightRecord): Insight {
+  return {
+    id: row.id,
+    userId: row.userId,
+    content: row.content,
+    source: row.source,
+    category: row.category,
+    relevanceScore: row.relevanceScore,
+    metadata: row.metadata ?? undefined,
+    createdAt: new Date(row.createdAt),
+    updatedAt: row.updatedAt ? new Date(row.updatedAt) : undefined,
+    decayedAt: row.decayedAt ? new Date(row.decayedAt) : undefined,
+  };
+}

packages/memory/src/adapters/pgvector.ts

@@ -0,0 +1,177 @@
+import { createDb, type DbHandle } from '@mosaic/db';
+import type {
+  MemoryAdapter,
+  MemoryConfig,
+  NewInsight as AdapterNewInsight,
+  Insight as AdapterInsight,
+  InsightSearchResult,
+} from '../types.js';
+import type { EmbeddingProvider } from '../vector-store.js';
+import {
+  createPreferencesRepo,
+  type PreferencesRepo,
+  type Preference,
+  type NewPreference,
+} from '../preferences.js';
+import {
+  createInsightsRepo,
+  type InsightsRepo,
+  type NewInsight as DbNewInsight,
+} from '../insights.js';
+
+type PgVectorConfig = Extract<MemoryConfig, { type: 'pgvector' }>;
+
+export class PgVectorAdapter implements MemoryAdapter {
+  readonly name = 'pgvector';
+  readonly embedder: EmbeddingProvider | null;
+
+  private handle: DbHandle;
+  private preferences: PreferencesRepo;
+  private insights: InsightsRepo;
+
+  constructor(config: PgVectorConfig) {
+    this.handle = createDb();
+    this.preferences = createPreferencesRepo(this.handle.db);
+    this.insights = createInsightsRepo(this.handle.db);
+    this.embedder = config.embedder ?? null;
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Preferences                                                       */
+  /* ------------------------------------------------------------------ */
+
+  async getPreference(userId: string, key: string): Promise<unknown | null> {
+    const row = await this.preferences.findByUserAndKey(userId, key);
+    return row?.value ?? null;
+  }
+
+  async setPreference(
+    userId: string,
+    key: string,
+    value: unknown,
+    category?: string,
+  ): Promise<void> {
+    await this.preferences.upsert({
+      userId,
+      key,
+      value,
+      ...(category ? { category: category as NewPreference['category'] } : {}),
+    });
+  }
+
+  async deletePreference(userId: string, key: string): Promise<boolean> {
+    return this.preferences.remove(userId, key);
+  }
+
+  async listPreferences(
+    userId: string,
+    category?: string,
+  ): Promise<Array<{ key: string; value: unknown; category: string }>> {
+    const rows = category
+      ? await this.preferences.findByUserAndCategory(userId, category as Preference['category'])
+      : await this.preferences.findByUser(userId);
+
+    return rows.map((r) => ({ key: r.key, value: r.value, category: r.category }));
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Insights                                                          */
+  /* ------------------------------------------------------------------ */
+
+  async storeInsight(insight: AdapterNewInsight): Promise<AdapterInsight> {
+    const row = await this.insights.create({
+      userId: insight.userId,
+      content: insight.content,
+      source: insight.source as DbNewInsight['source'],
+      category: insight.category as DbNewInsight['category'],
+      relevanceScore: insight.relevanceScore,
+      metadata: insight.metadata ?? {},
+      embedding: insight.embedding ?? null,
+    });
+
+    return toAdapterInsight(row);
+  }
+
+  async getInsight(id: string): Promise<AdapterInsight | null> {
+    // findById requires userId — search across all users via raw find
+    // The adapter interface only takes id, so we pass an empty userId and rely on the id match.
+    // Since the repo requires userId, we use a two-step approach.
+    const row = await this.insights.findById(id, '');
+    if (!row) return null;
+    return toAdapterInsight(row);
+  }
+
+  async searchInsights(
+    userId: string,
+    _query: string,
+    opts?: { limit?: number; embedding?: number[] },
+  ): Promise<InsightSearchResult[]> {
+    if (opts?.embedding) {
+      const results = await this.insights.searchByEmbedding(
+        userId,
+        opts.embedding,
+        opts.limit ?? 10,
+      );
+      return results.map((r) => ({
+        id: r.insight.id,
+        content: r.insight.content,
+        score: 1 - r.distance,
+        metadata: (r.insight.metadata as Record<string, unknown>) ?? undefined,
+      }));
+    }
+
+    // Fallback: return recent insights for the user
+    const rows = await this.insights.findByUser(userId, opts?.limit ?? 10);
+    return rows.map((r) => ({
+      id: r.id,
+      content: r.content,
+      score: Number(r.relevanceScore),
+      metadata: (r.metadata as Record<string, unknown>) ?? undefined,
+    }));
+  }
+
+  async deleteInsight(id: string): Promise<boolean> {
+    // The repo requires userId — pass empty string since adapter interface only has id
+    return this.insights.remove(id, '');
+  }
+
+  /* ------------------------------------------------------------------ */
+  /*  Lifecycle                                                         */
+  /* ------------------------------------------------------------------ */
+
+  async close(): Promise<void> {
+    await this.handle.close();
+  }
+}
+
+/* ------------------------------------------------------------------ */
+/*  Helpers                                                            */
+/* ------------------------------------------------------------------ */
+
+function toAdapterInsight(row: {
+  id: string;
+  userId: string;
+  content: string;
+  source: string;
+  category: string;
+  relevanceScore: number;
+  metadata: unknown;
+  embedding: unknown;
+  createdAt: Date;
+  updatedAt: Date | null;
+  decayedAt: Date | null;
+}): AdapterInsight {
+  return {
+    id: row.id,
+    userId: row.userId,
+    content: row.content,
+    source: row.source,
+    category: row.category,
+    relevanceScore: row.relevanceScore,
+    metadata: (row.metadata as Record<string, unknown>) ?? undefined,
+    embedding: (row.embedding as number[]) ?? undefined,
+    createdAt: row.createdAt,
+    updatedAt: row.updatedAt ?? undefined,
+    decayedAt: row.decayedAt ?? undefined,
+  };
+}

packages/memory/src/factory.ts

@@ -0,0 +1,18 @@
+import type { MemoryAdapter, MemoryConfig } from './types.js';
+
+type MemoryType = MemoryConfig['type'];
+
+const registry = new Map<MemoryType, (config: MemoryConfig) => MemoryAdapter>();
+
+export function registerMemoryAdapter(
+  type: MemoryType,
+  factory: (config: MemoryConfig) => MemoryAdapter,
+): void {
+  registry.set(type, factory);
+}
+
+export function createMemoryAdapter(config: MemoryConfig): MemoryAdapter {
+  const factory = registry.get(config.type);
+  if (!factory) throw new Error(`No adapter registered for type: ${config.type}`);
+  return factory(config);
+}

packages/memory/src/index.ts

@@ -13,3 +13,27 @@ export {
   type SearchResult,
 } from './insights.js';
 export type { VectorStore, VectorSearchResult, EmbeddingProvider } from './vector-store.js';
+export type {
+  MemoryAdapter,
+  MemoryConfig,
+  NewInsight as AdapterNewInsight,
+  Insight as AdapterInsight,
+  InsightSearchResult,
+} from './types.js';
+export { createMemoryAdapter, registerMemoryAdapter } from './factory.js';
+export { PgVectorAdapter } from './adapters/pgvector.js';
+export { KeywordAdapter } from './adapters/keyword.js';
+
+// Auto-register adapters at module load time
+import { registerMemoryAdapter } from './factory.js';
+import { PgVectorAdapter } from './adapters/pgvector.js';
+import { KeywordAdapter } from './adapters/keyword.js';
+import type { MemoryConfig } from './types.js';
+
+registerMemoryAdapter('pgvector', (config: MemoryConfig) => {
+  return new PgVectorAdapter(config as Extract<MemoryConfig, { type: 'pgvector' }>);
+});
+
+registerMemoryAdapter('keyword', (config: MemoryConfig) => {
+  return new KeywordAdapter(config as Extract<MemoryConfig, { type: 'keyword' }>);
+});

packages/memory/src/types.ts

@@ -0,0 +1,73 @@
+export type { EmbeddingProvider, VectorSearchResult } from './vector-store.js';
+import type { EmbeddingProvider } from './vector-store.js';
+import type { StorageAdapter } from '@mosaic/storage';
+
+/* ------------------------------------------------------------------ */
+/*  Insight types (adapter-level, decoupled from Drizzle schema)      */
+/* ------------------------------------------------------------------ */
+
+export interface NewInsight {
+  userId: string;
+  content: string;
+  source: string;
+  category: string;
+  relevanceScore: number;
+  metadata?: Record<string, unknown>;
+  embedding?: number[];
+}
+
+export interface Insight extends NewInsight {
+  id: string;
+  createdAt: Date;
+  updatedAt?: Date;
+  decayedAt?: Date;
+}
+
+export interface InsightSearchResult {
+  id: string;
+  content: string;
+  score: number;
+  metadata?: Record<string, unknown>;
+}
+
+/* ------------------------------------------------------------------ */
+/*  MemoryAdapter interface                                           */
+/* ------------------------------------------------------------------ */
+
+export interface MemoryAdapter {
+  readonly name: string;
+
+  // Preferences
+  getPreference(userId: string, key: string): Promise<unknown | null>;
+  setPreference(userId: string, key: string, value: unknown, category?: string): Promise<void>;
+  deletePreference(userId: string, key: string): Promise<boolean>;
+  listPreferences(
+    userId: string,
+    category?: string,
+  ): Promise<Array<{ key: string; value: unknown; category: string }>>;
+
+  // Insights
+  storeInsight(insight: NewInsight): Promise<Insight>;
+  getInsight(id: string): Promise<Insight | null>;
+  searchInsights(
+    userId: string,
+    query: string,
+    opts?: { limit?: number; embedding?: number[] },
+  ): Promise<InsightSearchResult[]>;
+  deleteInsight(id: string): Promise<boolean>;
+
+  // Embedding
+  readonly embedder: EmbeddingProvider | null;
+
+  // Lifecycle
+  close(): Promise<void>;
+}
+
+/* ------------------------------------------------------------------ */
+/*  MemoryConfig                                                      */
+/* ------------------------------------------------------------------ */
+
+export type MemoryConfig =
+  | { type: 'pgvector'; embedder?: EmbeddingProvider }
+  | { type: 'sqlite-vec'; embedder?: EmbeddingProvider }
+  | { type: 'keyword'; storage: StorageAdapter };

packages/mosaic/__tests__/update-checker.test.ts

@@ -1,7 +1,40 @@
-import { describe, expect, it } from 'vitest';
+import { beforeEach, describe, expect, it, vi } from 'vitest';
 import { semverLt, formatUpdateNotice } from '../src/runtime/update-checker.js';
 import type { UpdateCheckResult } from '../src/runtime/update-checker.js';
 
+const { execSyncMock, cacheFiles } = vi.hoisted(() => ({
+  execSyncMock: vi.fn(),
+  cacheFiles: new Map<string, string>(),
+}));
+
+vi.mock('node:child_process', () => ({
+  execSync: execSyncMock,
+}));
+
+vi.mock('node:fs', () => ({
+  existsSync: vi.fn((path: string) => cacheFiles.has(path)),
+  mkdirSync: vi.fn(),
+  readFileSync: vi.fn((path: string) => {
+    const value = cacheFiles.get(path);
+    if (value === undefined) {
+      throw new Error(`ENOENT: ${path}`);
+    }
+    return value;
+  }),
+  writeFileSync: vi.fn((path: string, content: string) => {
+    cacheFiles.set(path, content);
+  }),
+}));
+
+vi.mock('node:os', () => ({
+  homedir: vi.fn(() => '/mock-home'),
+}));
+
+async function importUpdateChecker() {
+  vi.resetModules();
+  return import('../src/runtime/update-checker.js');
+}
+
 describe('semverLt', () => {
   it('returns true when a < b', () => {
     expect(semverLt('0.0.1', '0.0.2')).toBe(true);
@@ -25,6 +58,11 @@ describe('semverLt', () => {
 });
 
 describe('formatUpdateNotice', () => {
+  beforeEach(() => {
+    execSyncMock.mockReset();
+    cacheFiles.clear();
+  });
+
   it('returns empty string when up to date', () => {
     const result: UpdateCheckResult = {
       current: '1.0.0',
@@ -49,4 +87,109 @@ describe('formatUpdateNotice', () => {
     expect(notice).toContain('0.1.0');
     expect(notice).toContain('Update available');
   });
+
+  it('uses @mosaic/mosaic hints for modern installs', async () => {
+    execSyncMock.mockImplementation((command: string) => {
+      if (command.includes('ls -g --depth=0 --json')) {
+        return JSON.stringify({
+          dependencies: {
+            '@mosaic/mosaic': { version: '0.0.17' },
+            '@mosaic/cli': { version: '0.0.16' },
+          },
+        });
+      }
+
+      if (command.includes('view @mosaic/mosaic version')) {
+        return '0.0.18';
+      }
+
+      throw new Error(`Unexpected command: ${command}`);
+    });
+
+    const { checkForUpdate } = await importUpdateChecker();
+    const result = checkForUpdate({ skipCache: true });
+    const notice = formatUpdateNotice(result);
+
+    expect(result.current).toBe('0.0.17');
+    expect(result.latest).toBe('0.0.18');
+    expect(notice).toContain('@mosaic/mosaic@latest');
+    expect(notice).not.toContain('@mosaic/cli@latest');
+  });
+
+  it('falls back to @mosaic/mosaic for legacy @mosaic/cli installs when cli is unavailable', async () => {
+    execSyncMock.mockImplementation((command: string) => {
+      if (command.includes('ls -g --depth=0 --json')) {
+        return JSON.stringify({
+          dependencies: {
+            '@mosaic/cli': { version: '0.0.16' },
+          },
+        });
+      }
+
+      if (command.includes('view @mosaic/cli version')) {
+        throw new Error('not found');
+      }
+
+      if (command.includes('view @mosaic/mosaic version')) {
+        return '0.0.17';
+      }
+
+      throw new Error(`Unexpected command: ${command}`);
+    });
+
+    const { checkForUpdate } = await importUpdateChecker();
+    const result = checkForUpdate({ skipCache: true });
+    const notice = formatUpdateNotice(result);
+
+    expect(result.current).toBe('0.0.16');
+    expect(result.latest).toBe('0.0.17');
+    expect(notice).toContain('@mosaic/mosaic@latest');
+  });
+
+  it('does not reuse a cached modern-package result for a legacy install', async () => {
+    let installedPackage = '@mosaic/mosaic';
+
+    execSyncMock.mockImplementation((command: string) => {
+      if (command.includes('ls -g --depth=0 --json')) {
+        return JSON.stringify({
+          dependencies:
+            installedPackage === '@mosaic/mosaic'
+              ? { '@mosaic/mosaic': { version: '0.0.17' } }
+              : { '@mosaic/cli': { version: '0.0.16' } },
+        });
+      }
+
+      if (command.includes('view @mosaic/mosaic version')) {
+        return installedPackage === '@mosaic/mosaic' ? '0.0.18' : '0.0.17';
+      }
+
+      if (command.includes('view @mosaic/cli version')) {
+        throw new Error('not found');
+      }
+
+      throw new Error(`Unexpected command: ${command}`);
+    });
+
+    const { checkForUpdate } = await importUpdateChecker();
+
+    const modernResult = checkForUpdate();
+    installedPackage = '@mosaic/cli';
+    const legacyResult = checkForUpdate();
+
+    expect(modernResult.currentPackage).toBe('@mosaic/mosaic');
+    expect(modernResult.targetPackage).toBe('@mosaic/mosaic');
+    expect(modernResult.latest).toBe('0.0.18');
+
+    expect(legacyResult.currentPackage).toBe('@mosaic/cli');
+    expect(legacyResult.targetPackage).toBe('@mosaic/mosaic');
+    expect(legacyResult.latest).toBe('0.0.17');
+    expect(execSyncMock).toHaveBeenCalledWith(
+      expect.stringContaining('view @mosaic/cli version'),
+      expect.any(Object),
+    );
+    expect(execSyncMock).toHaveBeenCalledWith(
+      expect.stringContaining('view @mosaic/mosaic version'),
+      expect.any(Object),
+    );
+  });
 });

packages/mosaic/framework/tools/_scripts/mosaic-sync-skills

@@ -56,24 +56,66 @@ if [[ $fetch -eq 1 ]]; then
   if [[ -d "$SKILLS_REPO_DIR/.git" ]]; then
     echo "[mosaic-skills] Updating skills source: $SKILLS_REPO_DIR"
 
-    # Stash any local changes (dirty index or worktree) before pulling
-    local_changes=0
-    if ! git -C "$SKILLS_REPO_DIR" diff --quiet 2>/dev/null || \
-       ! git -C "$SKILLS_REPO_DIR" diff --cached --quiet 2>/dev/null; then
-      local_changes=1
-      echo "[mosaic-skills] Stashing local changes..."
-      git -C "$SKILLS_REPO_DIR" stash push -q -m "mosaic-sync-skills auto-stash"
+    # ── Detect dirty state ──────────────────────────────────────────────
+    dirty=""
+    dirty="$(git -C "$SKILLS_REPO_DIR" status --porcelain 2>/dev/null || true)"
+
+    if [[ -n "$dirty" ]]; then
+      # ── Auto-migrate customized skills to skills-local/ ─────────────
+      # Instead of stash/pop (fragile, merge conflicts), we:
+      #   1. Identify which skill dirs contain user edits
+      #   2. Copy those full skill dirs into skills-local/ (preserving edits)
+      #   3. Reset the repo clean so pull always succeeds
+      #   4. skills-local/ takes precedence during linking, so edits win
+
+      SOURCE_SKILLS_SUBDIR="$SKILLS_REPO_DIR/skills"
+      migrated=()
+
+      while IFS= read -r line; do
+        # porcelain format: XY <path>  — extract the file path
+        file="${line:3}"
+        # Only migrate files under skills/ subdir in the repo
+        if [[ "$file" == skills/* ]]; then
+          # Extract the skill directory name (first path component after skills/)
+          skill_name="${file#skills/}"
+          skill_name="${skill_name%%/*}"
+
+          # Skip if already migrated this skill in this run
+          local_skill_dir="$MOSAIC_LOCAL_SKILLS_DIR/$skill_name"
+          if [[ -d "$local_skill_dir" ]]; then
+            continue
           fi
 
-    if ! git -C "$SKILLS_REPO_DIR" pull --rebase; then
+          # Skip if skill_name is empty or hidden
+          if [[ -z "$skill_name" || "$skill_name" == .* ]]; then
+            continue
+          fi
+
+          # Copy the skill (with user's edits) from repo working tree to skills-local/
+          if [[ -d "$SOURCE_SKILLS_SUBDIR/$skill_name" ]]; then
+            cp -R "$SOURCE_SKILLS_SUBDIR/$skill_name" "$local_skill_dir"
+            migrated+=("$skill_name")
+          fi
+        fi
+      done <<< "$dirty"
+
+      if [[ ${#migrated[@]} -gt 0 ]]; then
+        echo "[mosaic-skills] Migrated ${#migrated[@]} customized skill(s) to skills-local/:"
+        for s in "${migrated[@]}"; do
+          echo "  → $MOSAIC_LOCAL_SKILLS_DIR/$s"
+        done
+        echo "[mosaic-skills] Your edits are preserved there and take precedence over canonical."
+      fi
+
+      # Reset repo to clean state so pull always works
+      echo "[mosaic-skills] Resetting source repo to clean state..."
+      git -C "$SKILLS_REPO_DIR" checkout . 2>/dev/null || true
+      git -C "$SKILLS_REPO_DIR" clean -fd 2>/dev/null || true
+    fi
+
+    if ! git -C "$SKILLS_REPO_DIR" pull --rebase 2>/dev/null; then
       echo "[mosaic-skills] WARN: pull failed — continuing with existing checkout" >&2
-    fi
-
-    # Restore stashed changes
-    if [[ $local_changes -eq 1 ]]; then
-      echo "[mosaic-skills] Restoring local changes..."
-      git -C "$SKILLS_REPO_DIR" stash pop -q 2>/dev/null || \
-        echo "[mosaic-skills] WARN: stash pop had conflicts — check $SKILLS_REPO_DIR" >&2
+      git -C "$SKILLS_REPO_DIR" rebase --abort 2>/dev/null || true
     fi
   else
     echo "[mosaic-skills] Cloning skills source to: $SKILLS_REPO_DIR"

packages/mosaic/package.json

@@ -1,11 +1,17 @@
 {
   "name": "@mosaic/mosaic",
-  "version": "0.0.3-1",
+  "version": "0.0.19",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaic/mosaic-stack.git",
+    "directory": "packages/mosaic"
+  },
   "description": "Mosaic agent framework — installation wizard and meta package",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "bin": {
+    "mosaic": "dist/cli.js",
     "mosaic-wizard": "dist/index.js"
   },
   "exports": {
@@ -21,19 +27,27 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@mosaic/config": "workspace:*",
     "@mosaic/forge": "workspace:*",
     "@mosaic/macp": "workspace:*",
     "@mosaic/prdy": "workspace:*",
     "@mosaic/quality-rails": "workspace:*",
     "@mosaic/types": "workspace:*",
     "@clack/prompts": "^0.9.1",
-    "commander": "^12.1.0",
+    "commander": "^13.0.0",
+    "ink": "^5.0.0",
+    "ink-spinner": "^5.0.0",
+    "ink-text-input": "^6.0.0",
     "picocolors": "^1.1.1",
+    "react": "^18.3.0",
+    "socket.io-client": "^4.8.0",
     "yaml": "^2.6.1",
     "zod": "^3.23.8"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",
+    "@types/react": "^18.3.0",
+    "tsx": "^4.0.0",
     "typescript": "^5.8.0",
     "vitest": "^2.0.0"
   },

packages/mosaic/src/auth.ts

@@ -0,0 +1,115 @@
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { resolve } from 'node:path';
+import { homedir } from 'node:os';
+
+const SESSION_DIR = resolve(homedir(), '.mosaic');
+const SESSION_FILE = resolve(SESSION_DIR, 'session.json');
+
+interface StoredSession {
+  gatewayUrl: string;
+  cookie: string;
+  userId: string;
+  email: string;
+  expiresAt: string;
+}
+
+export interface AuthResult {
+  cookie: string;
+  userId: string;
+  email: string;
+}
+
+/**
+ * Sign in to the gateway and return the session cookie.
+ */
+export async function signIn(
+  gatewayUrl: string,
+  email: string,
+  password: string,
+): Promise<AuthResult> {
+  const res = await fetch(`${gatewayUrl}/api/auth/sign-in/email`, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json', Origin: gatewayUrl },
+    body: JSON.stringify({ email, password }),
+    redirect: 'manual',
+  });
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    throw new Error(`Sign-in failed (${res.status}): ${body}`);
+  }
+
+  // Extract set-cookie header
+  const setCookieHeader = res.headers.getSetCookie?.() ?? [];
+  const sessionCookie = setCookieHeader
+    .map((c) => c.split(';')[0]!)
+    .filter((c) => c.startsWith('better-auth.session_token='))
+    .join('; ');
+
+  if (!sessionCookie) {
+    throw new Error('No session cookie returned from sign-in');
+  }
+
+  // Parse the response body for user info
+  const data = (await res.json()) as { user?: { id: string; email: string } };
+  const userId = data.user?.id ?? 'unknown';
+  const userEmail = data.user?.email ?? email;
+
+  return { cookie: sessionCookie, userId, email: userEmail };
+}
+
+/**
+ * Save session to ~/.mosaic/session.json
+ */
+export function saveSession(gatewayUrl: string, auth: AuthResult): void {
+  if (!existsSync(SESSION_DIR)) {
+    mkdirSync(SESSION_DIR, { recursive: true });
+  }
+
+  const session: StoredSession = {
+    gatewayUrl,
+    cookie: auth.cookie,
+    userId: auth.userId,
+    email: auth.email,
+    expiresAt: new Date(Date.now() + 7 * 24 * 60 * 60 * 1000).toISOString(), // 7 days
+  };
+
+  writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2), 'utf-8');
+}
+
+/**
+ * Load a saved session. Returns null if no session, expired, or wrong gateway.
+ */
+export function loadSession(gatewayUrl: string): AuthResult | null {
+  if (!existsSync(SESSION_FILE)) return null;
+
+  try {
+    const raw = readFileSync(SESSION_FILE, 'utf-8');
+    const session = JSON.parse(raw) as StoredSession;
+
+    if (session.gatewayUrl !== gatewayUrl) return null;
+    if (new Date(session.expiresAt) < new Date()) return null;
+
+    return {
+      cookie: session.cookie,
+      userId: session.userId,
+      email: session.email,
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Validate that a stored session is still active by hitting get-session.
+ */
+export async function validateSession(gatewayUrl: string, cookie: string): Promise<boolean> {
+  try {
+    const res = await fetch(`${gatewayUrl}/api/auth/get-session`, {
+      headers: { Cookie: cookie, Origin: gatewayUrl },
+    });
+    return res.ok;
+  } catch {
+    return false;
+  }
+}

packages/mosaic/src/cli.ts

@@ -0,0 +1,426 @@
+#!/usr/bin/env node
+
+import { createRequire } from 'module';
+import { Command } from 'commander';
+import { registerQualityRails } from '@mosaic/quality-rails';
+import { registerAgentCommand } from './commands/agent.js';
+import { registerMissionCommand } from './commands/mission.js';
+// prdy is registered via launch.ts
+import { registerLaunchCommands } from './commands/launch.js';
+import { registerGatewayCommand } from './commands/gateway.js';
+import {
+  backgroundUpdateCheck,
+  checkForUpdate,
+  formatUpdateNotice,
+  getInstallCommand,
+} from './runtime/update-checker.js';
+import { runWizard } from './wizard.js';
+import { ClackPrompter } from './prompter/clack-prompter.js';
+import { HeadlessPrompter } from './prompter/headless-prompter.js';
+import { createConfigService } from './config/config-service.js';
+import { WizardCancelledError } from './errors.js';
+import { DEFAULT_MOSAIC_HOME } from './constants.js';
+
+const _require = createRequire(import.meta.url);
+const CLI_VERSION: string = (_require('../package.json') as { version: string }).version;
+
+// Fire-and-forget update check at startup (non-blocking, cached 1h)
+try {
+  backgroundUpdateCheck();
+} catch {
+  // Silently ignore — update check is best-effort
+}
+
+const program = new Command();
+
+program.name('mosaic').description('Mosaic Stack CLI').version(CLI_VERSION);
+
+// ─── runtime launchers + framework commands ────────────────────────────
+
+registerLaunchCommands(program);
+
+// ─── login ──────────────────────────────────────────────────────────────
+
+program
+  .command('login')
+  .description('Sign in to a Mosaic gateway')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+  .option('-e, --email <email>', 'Email address')
+  .option('-p, --password <password>', 'Password')
+  .action(async (opts: { gateway: string; email?: string; password?: string }) => {
+    const { signIn, saveSession } = await import('./auth.js');
+
+    let email = opts.email;
+    let password = opts.password;
+
+    if (!email || !password) {
+      const readline = await import('node:readline');
+      const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+      const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+      if (!email) email = await ask('Email: ');
+      if (!password) password = await ask('Password: ');
+      rl.close();
+    }
+
+    try {
+      const auth = await signIn(opts.gateway, email, password);
+      saveSession(opts.gateway, auth);
+      console.log(`Signed in as ${auth.email} (${opts.gateway})`);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+// ─── tui ────────────────────────────────────────────────────────────────
+
+program
+  .command('tui')
+  .description('Launch interactive TUI connected to the gateway')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+  .option('-c, --conversation <id>', 'Resume a conversation by ID')
+  .option('-m, --model <modelId>', 'Model ID to use (e.g. gpt-4o, llama3.2)')
+  .option('-p, --provider <provider>', 'Provider to use (e.g. openai, ollama)')
+  .option('--agent <idOrName>', 'Connect to a specific agent')
+  .option('--project <idOrName>', 'Scope session to project')
+  .action(
+    async (opts: {
+      gateway: string;
+      conversation?: string;
+      model?: string;
+      provider?: string;
+      agent?: string;
+      project?: string;
+    }) => {
+      const { loadSession, validateSession, signIn, saveSession } = await import('./auth.js');
+
+      // Try loading saved session
+      let session = loadSession(opts.gateway);
+
+      if (session) {
+        const valid = await validateSession(opts.gateway, session.cookie);
+        if (!valid) {
+          console.log('Session expired. Please sign in again.');
+          session = null;
+        }
+      }
+
+      // No valid session — prompt for credentials
+      if (!session) {
+        const readline = await import('node:readline');
+        const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+        const ask = (q: string): Promise<string> =>
+          new Promise((resolve) => rl.question(q, resolve));
+
+        console.log(`Sign in to ${opts.gateway}`);
+        const email = await ask('Email: ');
+        const password = await ask('Password: ');
+        rl.close();
+
+        try {
+          const auth = await signIn(opts.gateway, email, password);
+          saveSession(opts.gateway, auth);
+          session = auth;
+          console.log(`Signed in as ${auth.email}\n`);
+        } catch (err) {
+          console.error(err instanceof Error ? err.message : String(err));
+          process.exit(1);
+        }
+      }
+
+      // Resolve agent ID if --agent was passed by name
+      let agentId: string | undefined;
+      let agentName: string | undefined;
+      if (opts.agent) {
+        try {
+          const { fetchAgentConfigs } = await import('./tui/gateway-api.js');
+          const agents = await fetchAgentConfigs(opts.gateway, session.cookie);
+          const match = agents.find((a) => a.id === opts.agent || a.name === opts.agent);
+          if (match) {
+            agentId = match.id;
+            agentName = match.name;
+          } else {
+            console.error(`Agent "${opts.agent}" not found.`);
+            process.exit(1);
+          }
+        } catch (err) {
+          console.error(
+            `Failed to resolve agent: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      }
+
+      // Resolve project ID if --project was passed by name
+      let projectId: string | undefined;
+      if (opts.project) {
+        try {
+          const { fetchProjects } = await import('./tui/gateway-api.js');
+          const projects = await fetchProjects(opts.gateway, session.cookie);
+          const match = projects.find((p) => p.id === opts.project || p.name === opts.project);
+          if (match) {
+            projectId = match.id;
+          } else {
+            console.error(`Project "${opts.project}" not found.`);
+            process.exit(1);
+          }
+        } catch (err) {
+          console.error(
+            `Failed to resolve project: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      }
+
+      // Auto-create a conversation if none was specified
+      let conversationId = opts.conversation;
+      if (!conversationId) {
+        try {
+          const { createConversation } = await import('./tui/gateway-api.js');
+          const conv = await createConversation(opts.gateway, session.cookie, {
+            ...(projectId ? { projectId } : {}),
+          });
+          conversationId = conv.id;
+        } catch (err) {
+          console.error(
+            `Failed to create conversation: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exit(1);
+        }
+      }
+
+      // Dynamic import to avoid loading React/Ink for other commands
+      const { render } = await import('ink');
+      const React = await import('react');
+      const { TuiApp } = await import('./tui/app.js');
+
+      render(
+        React.createElement(TuiApp, {
+          gatewayUrl: opts.gateway,
+          conversationId,
+          sessionCookie: session.cookie,
+          initialModel: opts.model,
+          initialProvider: opts.provider,
+          agentId,
+          agentName: agentName ?? undefined,
+          projectId,
+          version: CLI_VERSION,
+        }),
+        { exitOnCtrlC: false },
+      );
+    },
+  );
+
+// ─── sessions ───────────────────────────────────────────────────────────
+
+const sessionsCmd = program.command('sessions').description('Manage active agent sessions');
+
+sessionsCmd
+  .command('list')
+  .description('List active agent sessions')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+  .action(async (opts: { gateway: string }) => {
+    const { withAuth } = await import('./commands/with-auth.js');
+    const auth = await withAuth(opts.gateway);
+    const { fetchSessions } = await import('./tui/gateway-api.js');
+
+    try {
+      const result = await fetchSessions(auth.gateway, auth.cookie);
+      if (result.total === 0) {
+        console.log('No active sessions.');
+        return;
+      }
+      console.log(`Active sessions (${result.total}):\n`);
+      for (const s of result.sessions) {
+        const created = new Date(s.createdAt).toLocaleString();
+        const durationSec = Math.round(s.durationMs / 1000);
+        console.log(`  ID:       ${s.id}`);
+        console.log(`  Model:    ${s.provider}/${s.modelId}`);
+        console.log(`  Created:  ${created}`);
+        console.log(`  Prompts:  ${s.promptCount}`);
+        console.log(`  Duration: ${durationSec}s`);
+        if (s.channels.length > 0) {
+          console.log(`  Channels: ${s.channels.join(', ')}`);
+        }
+        console.log('');
+      }
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+sessionsCmd
+  .command('resume <id>')
+  .description('Resume an existing agent session in the TUI')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+  .action(async (id: string, opts: { gateway: string }) => {
+    const { loadSession, validateSession } = await import('./auth.js');
+
+    const session = loadSession(opts.gateway);
+    if (!session) {
+      console.error('Not signed in. Run `mosaic login` first.');
+      process.exit(1);
+    }
+
+    const valid = await validateSession(opts.gateway, session.cookie);
+    if (!valid) {
+      console.error('Session expired. Run `mosaic login` again.');
+      process.exit(1);
+    }
+
+    const { render } = await import('ink');
+    const React = await import('react');
+    const { TuiApp } = await import('./tui/app.js');
+
+    render(
+      React.createElement(TuiApp, {
+        gatewayUrl: opts.gateway,
+        conversationId: id,
+        sessionCookie: session.cookie,
+        version: CLI_VERSION,
+      }),
+    );
+  });
+
+sessionsCmd
+  .command('destroy <id>')
+  .description('Terminate an active agent session')
+  .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+  .action(async (id: string, opts: { gateway: string }) => {
+    const { withAuth } = await import('./commands/with-auth.js');
+    const auth = await withAuth(opts.gateway);
+    const { deleteSession } = await import('./tui/gateway-api.js');
+
+    try {
+      await deleteSession(auth.gateway, auth.cookie, id);
+      console.log(`Session ${id} destroyed.`);
+    } catch (err) {
+      console.error(err instanceof Error ? err.message : String(err));
+      process.exit(1);
+    }
+  });
+
+// ─── gateway ──────────────────────────────────────────────────────────
+
+registerGatewayCommand(program);
+
+// ─── agent ─────────────────────────────────────────────────────────────
+
+registerAgentCommand(program);
+
+// ─── mission ───────────────────────────────────────────────────────────
+
+registerMissionCommand(program);
+
+// ─── quality-rails ──────────────────────────────────────────────────────
+
+registerQualityRails(program);
+
+// ─── update ─────────────────────────────────────────────────────────────
+
+program
+  .command('update')
+  .description('Check for and install Mosaic CLI updates')
+  .option('--check', 'Check only, do not install')
+  .action(async (opts: { check?: boolean }) => {
+    // checkForUpdate and formatUpdateNotice imported statically above
+    const { execSync } = await import('node:child_process');
+
+    console.log('Checking for updates…');
+    const result = checkForUpdate({ skipCache: true });
+
+    if (!result.latest) {
+      console.error('Could not reach the Mosaic registry.');
+      process.exit(1);
+    }
+
+    console.log(`  Installed: ${result.current || '(none)'}`);
+    console.log(`  Latest:    ${result.latest}`);
+
+    if (!result.updateAvailable) {
+      console.log('\n✔ Up to date.');
+      return;
+    }
+
+    const notice = formatUpdateNotice(result);
+    if (notice) console.log(notice);
+
+    if (opts.check) {
+      process.exit(2); // Signal to callers that an update exists
+    }
+
+    console.log('Installing update…');
+    try {
+      // Relies on @mosaic:registry in ~/.npmrc — do NOT pass --registry
+      // globally or non-@mosaic deps will 404 against the Gitea registry.
+      execSync(getInstallCommand(result), {
+        stdio: 'inherit',
+        timeout: 60_000,
+      });
+      console.log('\n✔ Updated successfully.');
+    } catch {
+      console.error('\nUpdate failed. Try manually: bash tools/install.sh');
+      process.exit(1);
+    }
+  });
+
+// ─── 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>) => {
+    // All wizard imports are now static (see top of file)
+
+    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/mosaic/src/commands/agent.ts

@@ -0,0 +1,241 @@
+import type { Command } from 'commander';
+import { withAuth } from './with-auth.js';
+import { selectItem } from './select-dialog.js';
+import {
+  fetchAgentConfigs,
+  createAgentConfig,
+  updateAgentConfig,
+  deleteAgentConfig,
+  fetchProjects,
+  fetchProviders,
+} from '../tui/gateway-api.js';
+import type { AgentConfigInfo } from '../tui/gateway-api.js';
+
+function formatAgent(a: AgentConfigInfo): string {
+  const sys = a.isSystem ? ' [system]' : '';
+  return `${a.name}${sys} — ${a.provider}/${a.model} (${a.status})`;
+}
+
+function showAgentDetail(a: AgentConfigInfo) {
+  console.log(`  ID:           ${a.id}`);
+  console.log(`  Name:         ${a.name}`);
+  console.log(`  Provider:     ${a.provider}`);
+  console.log(`  Model:        ${a.model}`);
+  console.log(`  Status:       ${a.status}`);
+  console.log(`  System:       ${a.isSystem ? 'yes' : 'no'}`);
+  console.log(`  Project:      ${a.projectId ?? '—'}`);
+  console.log(`  System Prompt: ${a.systemPrompt ? `${a.systemPrompt.slice(0, 80)}...` : '—'}`);
+  console.log(`  Tools:        ${a.allowedTools ? a.allowedTools.join(', ') : 'all'}`);
+  console.log(`  Skills:       ${a.skills ? a.skills.join(', ') : '—'}`);
+  console.log(`  Created:      ${new Date(a.createdAt).toLocaleString()}`);
+}
+
+export function registerAgentCommand(program: Command) {
+  const cmd = program
+    .command('agent')
+    .description('Manage agent configurations')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+    .option('--list', 'List all agents')
+    .option('--new', 'Create a new agent')
+    .option('--show <idOrName>', 'Show agent details')
+    .option('--update <idOrName>', 'Update an agent')
+    .option('--delete <idOrName>', 'Delete an agent')
+    .action(
+      async (opts: {
+        gateway: string;
+        list?: boolean;
+        new?: boolean;
+        show?: string;
+        update?: string;
+        delete?: string;
+      }) => {
+        const auth = await withAuth(opts.gateway);
+
+        if (opts.list) {
+          return listAgents(auth.gateway, auth.cookie);
+        }
+        if (opts.new) {
+          return createAgentWizard(auth.gateway, auth.cookie);
+        }
+        if (opts.show) {
+          return showAgent(auth.gateway, auth.cookie, opts.show);
+        }
+        if (opts.update) {
+          return updateAgentWizard(auth.gateway, auth.cookie, opts.update);
+        }
+        if (opts.delete) {
+          return deleteAgent(auth.gateway, auth.cookie, opts.delete);
+        }
+
+        // Default: interactive select
+        return interactiveSelect(auth.gateway, auth.cookie);
+      },
+    );
+
+  return cmd;
+}
+
+async function resolveAgent(
+  gateway: string,
+  cookie: string,
+  idOrName: string,
+): Promise<AgentConfigInfo | undefined> {
+  const agents = await fetchAgentConfigs(gateway, cookie);
+  return agents.find((a) => a.id === idOrName || a.name === idOrName);
+}
+
+async function listAgents(gateway: string, cookie: string) {
+  const agents = await fetchAgentConfigs(gateway, cookie);
+  if (agents.length === 0) {
+    console.log('No agents found.');
+    return;
+  }
+  console.log(`Agents (${agents.length}):\n`);
+  for (const a of agents) {
+    const sys = a.isSystem ? ' [system]' : '';
+    const project = a.projectId ? ` project=${a.projectId.slice(0, 8)}` : '';
+    console.log(`  ${a.name}${sys}  ${a.provider}/${a.model}  ${a.status}${project}`);
+  }
+}
+
+async function showAgent(gateway: string, cookie: string, idOrName: string) {
+  const agent = await resolveAgent(gateway, cookie, idOrName);
+  if (!agent) {
+    console.error(`Agent "${idOrName}" not found.`);
+    process.exit(1);
+  }
+  showAgentDetail(agent);
+}
+
+async function interactiveSelect(gateway: string, cookie: string) {
+  const agents = await fetchAgentConfigs(gateway, cookie);
+  const selected = await selectItem(agents, {
+    message: 'Select an agent:',
+    render: formatAgent,
+    emptyMessage: 'No agents found. Create one with `mosaic agent --new`.',
+  });
+  if (selected) {
+    showAgentDetail(selected);
+  }
+}
+
+async function createAgentWizard(gateway: string, cookie: string) {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    const name = await ask('Agent name: ');
+    if (!name.trim()) {
+      console.error('Name is required.');
+      return;
+    }
+
+    // Project selection
+    const projects = await fetchProjects(gateway, cookie);
+    let projectId: string | undefined;
+    if (projects.length > 0) {
+      const selected = await selectItem(projects, {
+        message: 'Assign to project (optional):',
+        render: (p) => `${p.name} (${p.status})`,
+      });
+      if (selected) projectId = selected.id;
+    }
+
+    // Provider / model selection
+    const providers = await fetchProviders(gateway, cookie);
+    let provider = 'default';
+    let model = 'default';
+
+    if (providers.length > 0) {
+      const allModels = providers.flatMap((p) =>
+        p.models.map((m) => ({ provider: p.name, model: m.id, label: `${p.name}/${m.id}` })),
+      );
+      if (allModels.length > 0) {
+        const selected = await selectItem(allModels, {
+          message: 'Select model:',
+          render: (m) => m.label,
+        });
+        if (selected) {
+          provider = selected.provider;
+          model = selected.model;
+        }
+      }
+    }
+
+    const systemPrompt = await ask('System prompt (optional, press Enter to skip): ');
+
+    const agent = await createAgentConfig(gateway, cookie, {
+      name: name.trim(),
+      provider,
+      model,
+      projectId,
+      systemPrompt: systemPrompt.trim() || undefined,
+    });
+
+    console.log(`\nAgent "${agent.name}" created (${agent.id}).`);
+  } finally {
+    rl.close();
+  }
+}
+
+async function updateAgentWizard(gateway: string, cookie: string, idOrName: string) {
+  const agent = await resolveAgent(gateway, cookie, idOrName);
+  if (!agent) {
+    console.error(`Agent "${idOrName}" not found.`);
+    process.exit(1);
+  }
+
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    console.log(`Updating agent: ${agent.name}\n`);
+
+    const name = await ask(`Name [${agent.name}]: `);
+    const systemPrompt = await ask(`System prompt [${agent.systemPrompt ? 'set' : 'none'}]: `);
+
+    const updates: Record<string, unknown> = {};
+    if (name.trim()) updates['name'] = name.trim();
+    if (systemPrompt.trim()) updates['systemPrompt'] = systemPrompt.trim();
+
+    if (Object.keys(updates).length === 0) {
+      console.log('No changes.');
+      return;
+    }
+
+    const updated = await updateAgentConfig(gateway, cookie, agent.id, updates);
+    console.log(`\nAgent "${updated.name}" updated.`);
+  } finally {
+    rl.close();
+  }
+}
+
+async function deleteAgent(gateway: string, cookie: string, idOrName: string) {
+  const agent = await resolveAgent(gateway, cookie, idOrName);
+  if (!agent) {
+    console.error(`Agent "${idOrName}" not found.`);
+    process.exit(1);
+  }
+
+  if (agent.isSystem) {
+    console.error('Cannot delete system agents.');
+    process.exit(1);
+  }
+
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise<string>((resolve) =>
+    rl.question(`Delete agent "${agent.name}"? (y/N): `, resolve),
+  );
+  rl.close();
+
+  if (answer.toLowerCase() !== 'y') {
+    console.log('Cancelled.');
+    return;
+  }
+
+  await deleteAgentConfig(gateway, cookie, agent.id);
+  console.log(`Agent "${agent.name}" deleted.`);
+}

packages/mosaic/src/commands/gateway.ts

@@ -0,0 +1,152 @@
+import type { Command } from 'commander';
+import {
+  getDaemonPid,
+  readMeta,
+  startDaemon,
+  stopDaemon,
+  waitForHealth,
+} from './gateway/daemon.js';
+
+interface GatewayParentOpts {
+  host: string;
+  port: string;
+  token?: string;
+}
+
+function resolveOpts(raw: GatewayParentOpts): { host: string; port: number; token?: string } {
+  const meta = readMeta();
+  return {
+    host: raw.host ?? meta?.host ?? 'localhost',
+    port: parseInt(raw.port, 10) || meta?.port || 14242,
+    token: raw.token ?? meta?.adminToken,
+  };
+}
+
+export function registerGatewayCommand(program: Command): void {
+  const gw = program
+    .command('gateway')
+    .description('Manage the Mosaic gateway daemon')
+    .helpOption('--help', 'Display help')
+    .option('-h, --host <host>', 'Gateway host', 'localhost')
+    .option('-p, --port <port>', 'Gateway port', '14242')
+    .option('-t, --token <token>', 'Admin API token')
+    .action(() => {
+      gw.outputHelp();
+    });
+
+  // ─── install ────────────────────────────────────────────────────────────
+
+  gw.command('install')
+    .description('Install and configure the gateway daemon')
+    .option('--skip-install', 'Skip npm package installation (use local build)')
+    .action(async (cmdOpts: { skipInstall?: boolean }) => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      const { runInstall } = await import('./gateway/install.js');
+      await runInstall({ ...opts, skipInstall: cmdOpts.skipInstall });
+    });
+
+  // ─── start ──────────────────────────────────────────────────────────────
+
+  gw.command('start')
+    .description('Start the gateway daemon')
+    .action(async () => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      try {
+        const pid = startDaemon();
+        console.log(`Gateway started (PID ${pid.toString()})`);
+        console.log('Waiting for health...');
+        const healthy = await waitForHealth(opts.host, opts.port);
+        if (healthy) {
+          console.log(`Gateway ready at http://${opts.host}:${opts.port.toString()}`);
+        } else {
+          console.warn('Gateway started but health check timed out. Check logs.');
+        }
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── stop ───────────────────────────────────────────────────────────────
+
+  gw.command('stop')
+    .description('Stop the gateway daemon')
+    .action(async () => {
+      try {
+        await stopDaemon();
+        console.log('Gateway stopped.');
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── restart ────────────────────────────────────────────────────────────
+
+  gw.command('restart')
+    .description('Restart the gateway daemon')
+    .action(async () => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      const pid = getDaemonPid();
+      if (pid !== null) {
+        console.log('Stopping gateway...');
+        await stopDaemon();
+      }
+      console.log('Starting gateway...');
+      try {
+        const newPid = startDaemon();
+        console.log(`Gateway started (PID ${newPid.toString()})`);
+        const healthy = await waitForHealth(opts.host, opts.port);
+        if (healthy) {
+          console.log(`Gateway ready at http://${opts.host}:${opts.port.toString()}`);
+        } else {
+          console.warn('Gateway started but health check timed out. Check logs.');
+        }
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ─── status ─────────────────────────────────────────────────────────────
+
+  gw.command('status')
+    .description('Show gateway daemon status and health')
+    .action(async () => {
+      const opts = resolveOpts(gw.opts() as GatewayParentOpts);
+      const { runStatus } = await import('./gateway/status.js');
+      await runStatus(opts);
+    });
+
+  // ─── config ─────────────────────────────────────────────────────────────
+
+  gw.command('config')
+    .description('View or modify gateway configuration')
+    .option('--set <KEY=VALUE>', 'Set a configuration value')
+    .option('--unset <KEY>', 'Remove a configuration key')
+    .option('--edit', 'Open config in $EDITOR')
+    .action(async (cmdOpts: { set?: string; unset?: string; edit?: boolean }) => {
+      const { runConfig } = await import('./gateway/config.js');
+      await runConfig(cmdOpts);
+    });
+
+  // ─── logs ───────────────────────────────────────────────────────────────
+
+  gw.command('logs')
+    .description('View gateway daemon logs')
+    .option('-f, --follow', 'Follow log output')
+    .option('-n, --lines <count>', 'Number of lines to show', '50')
+    .action(async (cmdOpts: { follow?: boolean; lines?: string }) => {
+      const { runLogs } = await import('./gateway/logs.js');
+      runLogs({ follow: cmdOpts.follow, lines: parseInt(cmdOpts.lines ?? '50', 10) });
+    });
+
+  // ─── uninstall ──────────────────────────────────────────────────────────
+
+  gw.command('uninstall')
+    .description('Uninstall the gateway daemon and optionally remove data')
+    .action(async () => {
+      const { runUninstall } = await import('./gateway/uninstall.js');
+      await runUninstall();
+    });
+}

packages/mosaic/src/commands/gateway/config.ts

@@ -0,0 +1,143 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { execSync } from 'node:child_process';
+import { ENV_FILE, getDaemonPid, readMeta, META_FILE, ensureDirs } from './daemon.js';
+
+// Keys that should be masked in output
+const SECRET_KEYS = new Set([
+  'BETTER_AUTH_SECRET',
+  'ANTHROPIC_API_KEY',
+  'OPENAI_API_KEY',
+  'ZAI_API_KEY',
+  'OPENROUTER_API_KEY',
+  'DISCORD_BOT_TOKEN',
+  'TELEGRAM_BOT_TOKEN',
+]);
+
+function maskValue(key: string, value: string): string {
+  if (SECRET_KEYS.has(key) && value.length > 8) {
+    return value.slice(0, 4) + '…' + value.slice(-4);
+  }
+  return value;
+}
+
+function parseEnvFile(): Map<string, string> {
+  const map = new Map<string, string>();
+  if (!existsSync(ENV_FILE)) return map;
+
+  const lines = readFileSync(ENV_FILE, 'utf-8').split('\n');
+  for (const line of lines) {
+    const trimmed = line.trim();
+    if (!trimmed || trimmed.startsWith('#')) continue;
+    const eqIdx = trimmed.indexOf('=');
+    if (eqIdx === -1) continue;
+    map.set(trimmed.slice(0, eqIdx), trimmed.slice(eqIdx + 1));
+  }
+  return map;
+}
+
+function writeEnvFile(entries: Map<string, string>): void {
+  ensureDirs();
+  const lines: string[] = [];
+  for (const [key, value] of entries) {
+    lines.push(`${key}=${value}`);
+  }
+  writeFileSync(ENV_FILE, lines.join('\n') + '\n', { mode: 0o600 });
+}
+
+interface ConfigOpts {
+  set?: string;
+  unset?: string;
+  edit?: boolean;
+}
+
+export async function runConfig(opts: ConfigOpts): Promise<void> {
+  // Set a value
+  if (opts.set) {
+    const eqIdx = opts.set.indexOf('=');
+    if (eqIdx === -1) {
+      console.error('Usage: mosaic gateway config --set KEY=VALUE');
+      process.exit(1);
+    }
+    const key = opts.set.slice(0, eqIdx);
+    const value = opts.set.slice(eqIdx + 1);
+    const entries = parseEnvFile();
+    entries.set(key, value);
+    writeEnvFile(entries);
+    console.log(`Set ${key}=${maskValue(key, value)}`);
+    promptRestart();
+    return;
+  }
+
+  // Unset a value
+  if (opts.unset) {
+    const entries = parseEnvFile();
+    if (!entries.has(opts.unset)) {
+      console.error(`Key not found: ${opts.unset}`);
+      process.exit(1);
+    }
+    entries.delete(opts.unset);
+    writeEnvFile(entries);
+    console.log(`Removed ${opts.unset}`);
+    promptRestart();
+    return;
+  }
+
+  // Open in editor
+  if (opts.edit) {
+    if (!existsSync(ENV_FILE)) {
+      console.error(`No config file found at ${ENV_FILE}`);
+      console.error('Run `mosaic gateway install` first.');
+      process.exit(1);
+    }
+    const editor = process.env['EDITOR'] ?? process.env['VISUAL'] ?? 'vi';
+    try {
+      execSync(`${editor} "${ENV_FILE}"`, { stdio: 'inherit' });
+      promptRestart();
+    } catch {
+      console.error('Editor exited with error.');
+    }
+    return;
+  }
+
+  // Default: show current config
+  showConfig();
+}
+
+function showConfig(): void {
+  if (!existsSync(ENV_FILE)) {
+    console.log('No gateway configuration found.');
+    console.log('Run `mosaic gateway install` to set up.');
+    return;
+  }
+
+  const entries = parseEnvFile();
+  const meta = readMeta();
+
+  console.log('Mosaic Gateway Configuration');
+  console.log('────────────────────────────');
+  console.log(`  Config file: ${ENV_FILE}`);
+  console.log(`  Meta file:   ${META_FILE}`);
+  console.log();
+
+  if (entries.size === 0) {
+    console.log('  (empty)');
+    return;
+  }
+
+  const maxKeyLen = Math.max(...[...entries.keys()].map((k) => k.length));
+  for (const [key, value] of entries) {
+    const padding = ' '.repeat(maxKeyLen - key.length);
+    console.log(`  ${key}${padding}  ${maskValue(key, value)}`);
+  }
+
+  if (meta?.adminToken) {
+    console.log();
+    console.log(`  Admin token: ${maskValue('token', meta.adminToken)}`);
+  }
+}
+
+function promptRestart(): void {
+  if (getDaemonPid() !== null) {
+    console.log('\nGateway is running — restart to apply changes: mosaic gateway restart');
+  }
+}

packages/mosaic/src/commands/gateway/daemon.ts

@@ -0,0 +1,245 @@
+import { spawn, execSync } from 'node:child_process';
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+  unlinkSync,
+  openSync,
+  constants,
+} from 'node:fs';
+import { join, resolve } from 'node:path';
+import { homedir } from 'node:os';
+import { createRequire } from 'node:module';
+
+// ─── Paths ──────────────────────────────────────────────────────────────────
+
+export const GATEWAY_HOME = resolve(
+  process.env['MOSAIC_GATEWAY_HOME'] ?? join(homedir(), '.config', 'mosaic', 'gateway'),
+);
+export const PID_FILE = join(GATEWAY_HOME, 'daemon.pid');
+export const LOG_DIR = join(GATEWAY_HOME, 'logs');
+export const LOG_FILE = join(LOG_DIR, 'gateway.log');
+export const ENV_FILE = join(GATEWAY_HOME, '.env');
+export const META_FILE = join(GATEWAY_HOME, 'meta.json');
+
+// ─── Meta ───────────────────────────────────────────────────────────────────
+
+export interface GatewayMeta {
+  version: string;
+  installedAt: string;
+  entryPoint: string;
+  adminToken?: string;
+  host: string;
+  port: number;
+}
+
+export function readMeta(): GatewayMeta | null {
+  if (!existsSync(META_FILE)) return null;
+  try {
+    return JSON.parse(readFileSync(META_FILE, 'utf-8')) as GatewayMeta;
+  } catch {
+    return null;
+  }
+}
+
+export function writeMeta(meta: GatewayMeta): void {
+  ensureDirs();
+  writeFileSync(META_FILE, JSON.stringify(meta, null, 2), { mode: 0o600 });
+}
+
+// ─── Directories ────────────────────────────────────────────────────────────
+
+export function ensureDirs(): void {
+  mkdirSync(GATEWAY_HOME, { recursive: true, mode: 0o700 });
+  mkdirSync(LOG_DIR, { recursive: true, mode: 0o700 });
+}
+
+// ─── PID management ─────────────────────────────────────────────────────────
+
+export function readPid(): number | null {
+  if (!existsSync(PID_FILE)) return null;
+  try {
+    const pid = parseInt(readFileSync(PID_FILE, 'utf-8').trim(), 10);
+    return Number.isNaN(pid) ? null : pid;
+  } catch {
+    return null;
+  }
+}
+
+export function isRunning(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+export function getDaemonPid(): number | null {
+  const pid = readPid();
+  if (pid === null) return null;
+  return isRunning(pid) ? pid : null;
+}
+
+// ─── Entry point resolution ─────────────────────────────────────────────────
+
+export function resolveGatewayEntry(): string {
+  // Check meta.json for custom entry point
+  const meta = readMeta();
+  if (meta?.entryPoint && existsSync(meta.entryPoint)) {
+    return meta.entryPoint;
+  }
+
+  // Try to resolve from globally installed @mosaic/gateway
+  try {
+    const req = createRequire(import.meta.url);
+    const pkgPath = req.resolve('@mosaic/gateway/package.json');
+    const mainEntry = join(resolve(pkgPath, '..'), 'dist', 'main.js');
+    if (existsSync(mainEntry)) return mainEntry;
+  } catch {
+    // Not installed globally
+  }
+
+  throw new Error('Cannot find gateway entry point. Run `mosaic gateway install` first.');
+}
+
+// ─── Start / Stop / Health ──────────────────────────────────────────────────
+
+export function startDaemon(): number {
+  const running = getDaemonPid();
+  if (running !== null) {
+    throw new Error(`Gateway is already running (PID ${running.toString()})`);
+  }
+
+  ensureDirs();
+  const entryPoint = resolveGatewayEntry();
+
+  // Load env vars from gateway .env
+  const env: Record<string, string> = { ...process.env } as Record<string, string>;
+  if (existsSync(ENV_FILE)) {
+    for (const line of readFileSync(ENV_FILE, 'utf-8').split('\n')) {
+      const trimmed = line.trim();
+      if (!trimmed || trimmed.startsWith('#')) continue;
+      const eqIdx = trimmed.indexOf('=');
+      if (eqIdx > 0) env[trimmed.slice(0, eqIdx)] = trimmed.slice(eqIdx + 1);
+    }
+  }
+
+  const logFd = openSync(LOG_FILE, constants.O_WRONLY | constants.O_CREAT | constants.O_APPEND);
+
+  const child = spawn('node', [entryPoint], {
+    detached: true,
+    stdio: ['ignore', logFd, logFd],
+    env,
+    cwd: GATEWAY_HOME,
+  });
+
+  if (!child.pid) {
+    throw new Error('Failed to spawn gateway process');
+  }
+
+  writeFileSync(PID_FILE, child.pid.toString(), { mode: 0o600 });
+  child.unref();
+
+  return child.pid;
+}
+
+export async function stopDaemon(timeoutMs = 10_000): Promise<void> {
+  const pid = getDaemonPid();
+  if (pid === null) {
+    throw new Error('Gateway is not running');
+  }
+
+  process.kill(pid, 'SIGTERM');
+
+  // Poll for exit
+  const start = Date.now();
+  while (Date.now() - start < timeoutMs) {
+    if (!isRunning(pid)) {
+      cleanPidFile();
+      return;
+    }
+    await sleep(250);
+  }
+
+  // Force kill
+  try {
+    process.kill(pid, 'SIGKILL');
+  } catch {
+    // Already dead
+  }
+  cleanPidFile();
+}
+
+function cleanPidFile(): void {
+  try {
+    unlinkSync(PID_FILE);
+  } catch {
+    // Ignore
+  }
+}
+
+export async function waitForHealth(
+  host: string,
+  port: number,
+  timeoutMs = 30_000,
+): Promise<boolean> {
+  const start = Date.now();
+  let delay = 500;
+
+  while (Date.now() - start < timeoutMs) {
+    try {
+      const res = await fetch(`http://${host}:${port.toString()}/health`);
+      if (res.ok) return true;
+    } catch {
+      // Not ready yet
+    }
+    await sleep(delay);
+    delay = Math.min(delay * 1.5, 3000);
+  }
+  return false;
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+// ─── npm install helper ─────────────────────────────────────────────────────
+
+const GITEA_REGISTRY = 'https://git.mosaicstack.dev/api/packages/mosaic/npm/';
+
+export function installGatewayPackage(): void {
+  console.log('Installing @mosaic/gateway from Gitea registry...');
+  execSync(`npm install -g @mosaic/gateway@latest --@mosaic:registry=${GITEA_REGISTRY}`, {
+    stdio: 'inherit',
+    timeout: 120_000,
+  });
+}
+
+export function uninstallGatewayPackage(): void {
+  try {
+    execSync('npm uninstall -g @mosaic/gateway', {
+      stdio: 'inherit',
+      timeout: 60_000,
+    });
+  } catch {
+    console.warn('Warning: npm uninstall may not have completed cleanly.');
+  }
+}
+
+export function getInstalledGatewayVersion(): string | null {
+  try {
+    const output = execSync('npm ls -g @mosaic/gateway --json --depth=0', {
+      encoding: 'utf-8',
+      timeout: 15_000,
+      stdio: ['pipe', 'pipe', 'pipe'],
+    });
+    const data = JSON.parse(output) as {
+      dependencies?: { '@mosaic/gateway'?: { version?: string } };
+    };
+    return data.dependencies?.['@mosaic/gateway']?.version ?? null;
+  } catch {
+    return null;
+  }
+}

packages/mosaic/src/commands/gateway/install.ts

@@ -0,0 +1,259 @@
+import { randomBytes } from 'node:crypto';
+import { writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { createInterface } from 'node:readline';
+import type { GatewayMeta } from './daemon.js';
+import {
+  ENV_FILE,
+  GATEWAY_HOME,
+  ensureDirs,
+  installGatewayPackage,
+  readMeta,
+  resolveGatewayEntry,
+  startDaemon,
+  waitForHealth,
+  writeMeta,
+  getInstalledGatewayVersion,
+} from './daemon.js';
+
+interface InstallOpts {
+  host: string;
+  port: number;
+  skipInstall?: boolean;
+}
+
+function prompt(rl: ReturnType<typeof createInterface>, question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+export async function runInstall(opts: InstallOpts): Promise<void> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await doInstall(rl, opts);
+  } finally {
+    rl.close();
+  }
+}
+
+async function doInstall(rl: ReturnType<typeof createInterface>, opts: InstallOpts): Promise<void> {
+  // Check existing installation
+  const existing = readMeta();
+  if (existing) {
+    const answer = await prompt(
+      rl,
+      `Gateway already installed (v${existing.version}). Reinstall? [y/N] `,
+    );
+    if (answer.toLowerCase() !== 'y') {
+      console.log('Aborted.');
+      return;
+    }
+  }
+
+  // Step 1: Install npm package
+  if (!opts.skipInstall) {
+    installGatewayPackage();
+  }
+
+  ensureDirs();
+
+  // Step 2: Collect configuration
+  console.log('\n─── Gateway Configuration ───\n');
+
+  // Tier selection
+  console.log('Storage tier:');
+  console.log('  1. Local (embedded database, no dependencies)');
+  console.log('  2. Team (PostgreSQL + Valkey required)');
+  const tierAnswer = (await prompt(rl, 'Select [1]: ')).trim() || '1';
+  const tier = tierAnswer === '2' ? 'team' : 'local';
+
+  const port =
+    opts.port !== 14242
+      ? opts.port
+      : parseInt(
+          (await prompt(rl, `Gateway port [${opts.port.toString()}]: `)) || opts.port.toString(),
+          10,
+        );
+
+  let databaseUrl: string | undefined;
+  let valkeyUrl: string | undefined;
+
+  if (tier === 'team') {
+    databaseUrl =
+      (await prompt(rl, 'DATABASE_URL [postgresql://mosaic:mosaic@localhost:5433/mosaic]: ')) ||
+      'postgresql://mosaic:mosaic@localhost:5433/mosaic';
+
+    valkeyUrl =
+      (await prompt(rl, 'VALKEY_URL [redis://localhost:6380]: ')) || 'redis://localhost:6380';
+  }
+
+  const anthropicKey = await prompt(rl, 'ANTHROPIC_API_KEY (optional, press Enter to skip): ');
+
+  const corsOrigin =
+    (await prompt(rl, 'CORS origin [http://localhost:3000]: ')) || 'http://localhost:3000';
+
+  // Generate auth secret
+  const authSecret = randomBytes(32).toString('hex');
+
+  // Step 3: Write .env
+  const envLines = [
+    `GATEWAY_PORT=${port.toString()}`,
+    `BETTER_AUTH_SECRET=${authSecret}`,
+    `BETTER_AUTH_URL=http://${opts.host}:${port.toString()}`,
+    `GATEWAY_CORS_ORIGIN=${corsOrigin}`,
+    `OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318`,
+    `OTEL_SERVICE_NAME=mosaic-gateway`,
+  ];
+
+  if (tier === 'team' && databaseUrl && valkeyUrl) {
+    envLines.push(`DATABASE_URL=${databaseUrl}`);
+    envLines.push(`VALKEY_URL=${valkeyUrl}`);
+  }
+
+  if (anthropicKey) {
+    envLines.push(`ANTHROPIC_API_KEY=${anthropicKey}`);
+  }
+
+  writeFileSync(ENV_FILE, envLines.join('\n') + '\n', { mode: 0o600 });
+  console.log(`\nConfig written to ${ENV_FILE}`);
+
+  // Step 3b: Write mosaic.config.json
+  const mosaicConfig =
+    tier === 'local'
+      ? {
+          tier: 'local',
+          storage: { type: 'pglite', dataDir: join(GATEWAY_HOME, 'storage-pglite') },
+          queue: { type: 'local', dataDir: join(GATEWAY_HOME, 'queue') },
+          memory: { type: 'keyword' },
+        }
+      : {
+          tier: 'team',
+          storage: { type: 'postgres', url: databaseUrl },
+          queue: { type: 'bullmq', url: valkeyUrl },
+          memory: { type: 'pgvector' },
+        };
+
+  const configFile = join(GATEWAY_HOME, 'mosaic.config.json');
+  writeFileSync(configFile, JSON.stringify(mosaicConfig, null, 2) + '\n', { mode: 0o600 });
+  console.log(`Config written to ${configFile}`);
+
+  // Step 4: Write meta.json
+  let entryPoint: string;
+  try {
+    entryPoint = resolveGatewayEntry();
+  } catch {
+    console.error('Error: Gateway package not found after install.');
+    console.error('Check that @mosaic/gateway installed correctly.');
+    return;
+  }
+
+  const version = getInstalledGatewayVersion() ?? 'unknown';
+
+  const meta = {
+    version,
+    installedAt: new Date().toISOString(),
+    entryPoint,
+    host: opts.host,
+    port,
+  };
+  writeMeta(meta);
+
+  // Step 5: Start the daemon
+  console.log('\nStarting gateway daemon...');
+  try {
+    const pid = startDaemon();
+    console.log(`Gateway started (PID ${pid.toString()})`);
+  } catch (err) {
+    console.error(`Failed to start: ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+
+  // Step 6: Wait for health
+  console.log('Waiting for gateway to become healthy...');
+  const healthy = await waitForHealth(opts.host, port, 30_000);
+  if (!healthy) {
+    console.error('Gateway did not become healthy within 30 seconds.');
+    console.error(`Check logs: mosaic gateway logs`);
+    return;
+  }
+  console.log('Gateway is healthy.\n');
+
+  // Step 7: Bootstrap — first user setup
+  await bootstrapFirstUser(rl, opts.host, port, meta);
+
+  console.log('\n─── Installation Complete ───');
+  console.log(`  Endpoint:  http://${opts.host}:${port.toString()}`);
+  console.log(`  Config:    ${GATEWAY_HOME}`);
+  console.log(`  Logs:      mosaic gateway logs`);
+  console.log(`  Status:    mosaic gateway status`);
+}
+
+async function bootstrapFirstUser(
+  rl: ReturnType<typeof createInterface>,
+  host: string,
+  port: number,
+  meta: Omit<GatewayMeta, 'adminToken'> & { adminToken?: string },
+): Promise<void> {
+  const baseUrl = `http://${host}:${port.toString()}`;
+
+  try {
+    const statusRes = await fetch(`${baseUrl}/api/bootstrap/status`);
+    if (!statusRes.ok) return;
+
+    const status = (await statusRes.json()) as { needsSetup: boolean };
+    if (!status.needsSetup) {
+      console.log('Admin user already exists — skipping setup.');
+      return;
+    }
+  } catch {
+    console.warn('Could not check bootstrap status — skipping first user setup.');
+    return;
+  }
+
+  console.log('─── Admin User Setup ───\n');
+
+  const name = (await prompt(rl, 'Admin name: ')).trim();
+  if (!name) {
+    console.error('Name is required.');
+    return;
+  }
+
+  const email = (await prompt(rl, 'Admin email: ')).trim();
+  if (!email) {
+    console.error('Email is required.');
+    return;
+  }
+
+  const password = (await prompt(rl, 'Admin password (min 8 chars): ')).trim();
+  if (password.length < 8) {
+    console.error('Password must be at least 8 characters.');
+    return;
+  }
+
+  try {
+    const res = await fetch(`${baseUrl}/api/bootstrap/setup`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ name, email, password }),
+    });
+
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      console.error(`Bootstrap failed (${res.status.toString()}): ${body}`);
+      return;
+    }
+
+    const result = (await res.json()) as {
+      user: { id: string; email: string };
+      token: { plaintext: string };
+    };
+
+    // Save admin token to meta
+    meta.adminToken = result.token.plaintext;
+    writeMeta(meta as GatewayMeta);
+
+    console.log(`\nAdmin user created: ${result.user.email}`);
+    console.log('Admin API token saved to gateway config.');
+  } catch (err) {
+    console.error(`Bootstrap error: ${err instanceof Error ? err.message : String(err)}`);
+  }
+}

packages/mosaic/src/commands/gateway/logs.ts

@@ -0,0 +1,37 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { LOG_FILE } from './daemon.js';
+
+interface LogsOpts {
+  follow?: boolean;
+  lines?: number;
+}
+
+export function runLogs(opts: LogsOpts): void {
+  if (!existsSync(LOG_FILE)) {
+    console.log('No log file found. Is the gateway installed?');
+    return;
+  }
+
+  if (opts.follow) {
+    const lines = opts.lines ?? 50;
+    const tail = spawn('tail', ['-n', lines.toString(), '-f', LOG_FILE], {
+      stdio: 'inherit',
+    });
+    tail.on('error', () => {
+      // Fallback for systems without tail
+      console.log(readLastLines(opts.lines ?? 50));
+      console.log('\n(--follow requires `tail` command)');
+    });
+    return;
+  }
+
+  // Just print last N lines
+  console.log(readLastLines(opts.lines ?? 50));
+}
+
+function readLastLines(n: number): string {
+  const content = readFileSync(LOG_FILE, 'utf-8');
+  const lines = content.split('\n');
+  return lines.slice(-n).join('\n');
+}

packages/mosaic/src/commands/gateway/status.ts

@@ -0,0 +1,115 @@
+import { getDaemonPid, readMeta, LOG_FILE, GATEWAY_HOME } from './daemon.js';
+
+interface GatewayOpts {
+  host: string;
+  port: number;
+  token?: string;
+}
+
+interface ServiceStatus {
+  name: string;
+  status: string;
+  latency?: string;
+}
+
+interface AdminHealth {
+  status: string;
+  services: {
+    database: { status: string; latencyMs: number };
+    cache: { status: string; latencyMs: number };
+  };
+  agentPool?: { active: number };
+  providers?: Array<{ name: string; available: boolean; models: number }>;
+}
+
+export async function runStatus(opts: GatewayOpts): Promise<void> {
+  const meta = readMeta();
+  const pid = getDaemonPid();
+
+  console.log('Mosaic Gateway Status');
+  console.log('─────────────────────');
+
+  // Daemon status
+  if (pid !== null) {
+    console.log(`  Status:    running (PID ${pid.toString()})`);
+  } else {
+    console.log('  Status:    stopped');
+  }
+
+  // Version
+  console.log(`  Version:   ${meta?.version ?? 'unknown'}`);
+
+  // Endpoint
+  const host = opts.host;
+  const port = opts.port;
+  console.log(`  Endpoint:  http://${host}:${port.toString()}`);
+  console.log(`  Config:    ${GATEWAY_HOME}`);
+  console.log(`  Logs:      ${LOG_FILE}`);
+
+  if (pid === null) return;
+
+  // Health check
+  try {
+    const healthRes = await fetch(`http://${host}:${port.toString()}/health`);
+    if (!healthRes.ok) {
+      console.log('\n  Health:    unreachable');
+      return;
+    }
+  } catch {
+    console.log('\n  Health:    unreachable');
+    return;
+  }
+
+  // Admin health (requires token)
+  const token = opts.token ?? meta?.adminToken;
+  if (!token) {
+    console.log(
+      '\n  (No admin token — run `mosaic gateway config` to set one for detailed status)',
+    );
+    return;
+  }
+
+  try {
+    const res = await fetch(`http://${host}:${port.toString()}/api/admin/health`, {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    if (!res.ok) {
+      console.log('\n  Admin health: unauthorized or unavailable');
+      return;
+    }
+
+    const health = (await res.json()) as AdminHealth;
+
+    console.log('\n  Services:');
+    const services: ServiceStatus[] = [
+      {
+        name: 'Database',
+        status: health.services.database.status,
+        latency: `${health.services.database.latencyMs.toString()}ms`,
+      },
+      {
+        name: 'Cache',
+        status: health.services.cache.status,
+        latency: `${health.services.cache.latencyMs.toString()}ms`,
+      },
+    ];
+
+    for (const svc of services) {
+      const latStr = svc.latency ? ` (${svc.latency})` : '';
+      console.log(`    ${svc.name}:${' '.repeat(10 - svc.name.length)}${svc.status}${latStr}`);
+    }
+
+    if (health.providers && health.providers.length > 0) {
+      const available = health.providers.filter((p) => p.available);
+      const names = available.map((p) => p.name).join(', ');
+      console.log(`\n  Providers: ${available.length.toString()} active (${names})`);
+    }
+
+    if (health.agentPool) {
+      console.log(`  Sessions:  ${health.agentPool.active.toString()} active`);
+    }
+  } catch {
+    console.log('\n  Admin health: connection error');
+  }
+}

packages/mosaic/src/commands/gateway/uninstall.ts

@@ -0,0 +1,62 @@
+import { existsSync, rmSync } from 'node:fs';
+import { createInterface } from 'node:readline';
+import {
+  GATEWAY_HOME,
+  getDaemonPid,
+  readMeta,
+  stopDaemon,
+  uninstallGatewayPackage,
+} from './daemon.js';
+
+export async function runUninstall(): Promise<void> {
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    await doUninstall(rl);
+  } finally {
+    rl.close();
+  }
+}
+
+function prompt(rl: ReturnType<typeof createInterface>, question: string): Promise<string> {
+  return new Promise((resolve) => rl.question(question, resolve));
+}
+
+async function doUninstall(rl: ReturnType<typeof createInterface>): Promise<void> {
+  const meta = readMeta();
+  if (!meta) {
+    console.log('Gateway is not installed.');
+    return;
+  }
+
+  const answer = await prompt(rl, 'Uninstall Mosaic Gateway? [y/N] ');
+  if (answer.toLowerCase() !== 'y') {
+    console.log('Aborted.');
+    return;
+  }
+
+  // Stop if running
+  if (getDaemonPid() !== null) {
+    console.log('Stopping gateway daemon...');
+    try {
+      await stopDaemon();
+      console.log('Stopped.');
+    } catch (err) {
+      console.warn(`Warning: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+
+  // Remove config/data
+  const removeData = await prompt(rl, `Remove all gateway data at ${GATEWAY_HOME}? [y/N] `);
+  if (removeData.toLowerCase() === 'y') {
+    if (existsSync(GATEWAY_HOME)) {
+      rmSync(GATEWAY_HOME, { recursive: true, force: true });
+      console.log('Gateway data removed.');
+    }
+  }
+
+  // Uninstall npm package
+  console.log('Uninstalling npm package...');
+  uninstallGatewayPackage();
+
+  console.log('\nGateway uninstalled.');
+}

packages/mosaic/src/commands/launch.ts

@@ -0,0 +1,772 @@
+/**
+ * Native runtime launcher — replaces the bash mosaic-launch script.
+ *
+ * Builds a composed runtime prompt from AGENTS.md + RUNTIME.md + USER.md +
+ * TOOLS.md + mission context + PRD status, then exec's into the target CLI.
+ */
+
+import { execFileSync, execSync, spawnSync } from 'node:child_process';
+import { existsSync, mkdirSync, readFileSync, writeFileSync, readdirSync, rmSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { homedir } from 'node:os';
+import { join, dirname } from 'node:path';
+import type { Command } from 'commander';
+
+const MOSAIC_HOME = process.env['MOSAIC_HOME'] ?? join(homedir(), '.config', 'mosaic');
+
+type RuntimeName = 'claude' | 'codex' | 'opencode' | 'pi';
+
+const RUNTIME_LABELS: Record<RuntimeName, string> = {
+  claude: 'Claude Code',
+  codex: 'Codex',
+  opencode: 'OpenCode',
+  pi: 'Pi',
+};
+
+// ─── Pre-flight checks ──────────────────────────────────────────────────────
+
+function checkMosaicHome(): void {
+  if (!existsSync(MOSAIC_HOME)) {
+    console.error(`[mosaic] ERROR: ${MOSAIC_HOME} not found.`);
+    console.error(
+      '[mosaic] Install: bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)',
+    );
+    process.exit(1);
+  }
+}
+
+function checkFile(path: string, label: string): void {
+  if (!existsSync(path)) {
+    console.error(`[mosaic] ERROR: ${label} not found: ${path}`);
+    process.exit(1);
+  }
+}
+
+function checkRuntime(cmd: string): void {
+  try {
+    execSync(`which ${cmd}`, { stdio: 'ignore' });
+  } catch {
+    console.error(`[mosaic] ERROR: '${cmd}' not found in PATH.`);
+    console.error(`[mosaic] Install ${cmd} before launching.`);
+    process.exit(1);
+  }
+}
+
+function checkSoul(): void {
+  const soulPath = join(MOSAIC_HOME, 'SOUL.md');
+  if (!existsSync(soulPath)) {
+    console.log('[mosaic] SOUL.md not found. Running setup wizard...');
+
+    // Prefer the TypeScript wizard (idempotent, detects existing files)
+    try {
+      const result = spawnSync(process.execPath, [process.argv[1]!, 'wizard'], {
+        stdio: 'inherit',
+      });
+      if (result.status === 0 && existsSync(soulPath)) return;
+    } catch {
+      // Fall through to legacy init
+    }
+
+    // Fallback: legacy bash mosaic-init
+    const initBin = fwScript('mosaic-init');
+    if (existsSync(initBin)) {
+      spawnSync(initBin, [], { stdio: 'inherit' });
+    } else {
+      console.error('[mosaic] Setup failed. Run: mosaic wizard');
+      process.exit(1);
+    }
+  }
+}
+
+function checkSequentialThinking(runtime: string): void {
+  const checker = fwScript('mosaic-ensure-sequential-thinking');
+  if (!existsSync(checker)) return; // Skip if checker doesn't exist
+  const result = spawnSync(checker, ['--check', '--runtime', runtime], { stdio: 'ignore' });
+  if (result.status !== 0) {
+    console.error('[mosaic] ERROR: sequential-thinking MCP is required but not configured.');
+    console.error(`[mosaic] Fix: ${checker} --runtime ${runtime}`);
+    process.exit(1);
+  }
+}
+
+// ─── File helpers ────────────────────────────────────────────────────────────
+
+function readOptional(path: string): string {
+  try {
+    return readFileSync(path, 'utf-8');
+  } catch {
+    return '';
+  }
+}
+
+function readJson(path: string): Record<string, unknown> | null {
+  try {
+    return JSON.parse(readFileSync(path, 'utf-8')) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+// ─── Mission context ─────────────────────────────────────────────────────────
+
+interface MissionInfo {
+  name: string;
+  id: string;
+  status: string;
+  milestoneCount: number;
+  completedCount: number;
+}
+
+function detectMission(): MissionInfo | null {
+  const missionFile = '.mosaic/orchestrator/mission.json';
+  const data = readJson(missionFile);
+  if (!data) return null;
+
+  const status = String(data['status'] ?? 'inactive');
+  if (status !== 'active' && status !== 'paused') return null;
+
+  const milestones = Array.isArray(data['milestones']) ? data['milestones'] : [];
+  const completed = milestones.filter(
+    (m) =>
+      typeof m === 'object' &&
+      m !== null &&
+      (m as Record<string, unknown>)['status'] === 'completed',
+  );
+
+  return {
+    name: String(data['name'] ?? 'unnamed'),
+    id: String(data['mission_id'] ?? ''),
+    status,
+    milestoneCount: milestones.length,
+    completedCount: completed.length,
+  };
+}
+
+function buildMissionBlock(mission: MissionInfo): string {
+  return `# ACTIVE MISSION — HARD GATE (Read Before Anything Else)
+
+An active orchestration mission exists in this project. This is a BLOCKING requirement.
+
+**Mission:** ${mission.name}
+**ID:** ${mission.id}
+**Status:** ${mission.status}
+**Milestones:** ${mission.completedCount} / ${mission.milestoneCount} completed
+
+## MANDATORY — Before ANY Response to the User
+
+You MUST complete these steps before responding to any user message, including simple greetings:
+
+1. Read \`~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md\` (mission lifecycle protocol)
+2. Read \`docs/MISSION-MANIFEST.md\` for full mission scope, milestones, and success criteria
+3. Read the latest scratchpad in \`docs/scratchpads/\` for session history, decisions, and corrections
+4. Read \`docs/TASKS.md\` for current task state (what is done, what is next)
+5. After reading all four, acknowledge the mission state to the user before proceeding
+
+If the user gives a task, execute it within the mission context. If no task is given, present mission status and ask how to proceed.
+
+`;
+}
+
+// ─── PRD status ──────────────────────────────────────────────────────────────
+
+function buildPrdBlock(): string {
+  const prdFile = 'docs/PRD.md';
+  if (!existsSync(prdFile)) return '';
+
+  const content = readFileSync(prdFile, 'utf-8');
+  const patterns = [
+    /^#{2,3} .*(problem statement|objective)/im,
+    /^#{2,3} .*(scope|non.goal|out of scope|in.scope)/im,
+    /^#{2,3} .*(user stor|stakeholder|user.*requirement)/im,
+    /^#{2,3} .*functional requirement/im,
+    /^#{2,3} .*non.functional/im,
+    /^#{2,3} .*acceptance criteria/im,
+    /^#{2,3} .*(technical consideration|constraint|dependenc)/im,
+    /^#{2,3} .*(risk|open question)/im,
+    /^#{2,3} .*(success metric|test|verification)/im,
+    /^#{2,3} .*(milestone|delivery|scope version)/im,
+  ];
+
+  let sections = 0;
+  for (const pattern of patterns) {
+    if (pattern.test(content)) sections++;
+  }
+
+  const assumptions = (content.match(/ASSUMPTION:/g) ?? []).length;
+  const status = sections < 10 ? `incomplete (${sections}/10 sections)` : 'ready';
+
+  return `
+# PRD Status
+
+- **File:** docs/PRD.md
+- **Status:** ${status}
+- **Assumptions:** ${assumptions}
+
+`;
+}
+
+// ─── Runtime prompt builder ──────────────────────────────────────────────────
+
+function buildRuntimePrompt(runtime: RuntimeName): string {
+  const runtimeContractPaths: Record<RuntimeName, string> = {
+    claude: join(MOSAIC_HOME, 'runtime', 'claude', 'RUNTIME.md'),
+    codex: join(MOSAIC_HOME, 'runtime', 'codex', 'RUNTIME.md'),
+    opencode: join(MOSAIC_HOME, 'runtime', 'opencode', 'RUNTIME.md'),
+    pi: join(MOSAIC_HOME, 'runtime', 'pi', 'RUNTIME.md'),
+  };
+
+  const runtimeFile = runtimeContractPaths[runtime];
+  checkFile(runtimeFile, `Runtime contract for ${runtime}`);
+
+  const parts: string[] = [];
+
+  // Mission context (injected first)
+  const mission = detectMission();
+  if (mission) {
+    parts.push(buildMissionBlock(mission));
+  }
+
+  // PRD status
+  const prdBlock = buildPrdBlock();
+  if (prdBlock) parts.push(prdBlock);
+
+  // Hard gate
+  parts.push(`# Mosaic Launcher Runtime Contract (Hard Gate)
+
+This contract is injected by \`mosaic\` launch and is mandatory.
+
+First assistant response MUST start with exactly one mode declaration line:
+1. Orchestration mission: \`Now initiating Orchestrator mode...\`
+2. Implementation mission: \`Now initiating Delivery mode...\`
+3. Review-only mission: \`Now initiating Review mode...\`
+
+No tool call or implementation step may occur before that first line.
+
+Mosaic hard gates OVERRIDE runtime-default caution for routine delivery operations.
+For required push/merge/issue-close/release actions, execute without routine confirmation prompts.
+`);
+
+  // AGENTS.md
+  parts.push(readFileSync(join(MOSAIC_HOME, 'AGENTS.md'), 'utf-8'));
+
+  // USER.md
+  const user = readOptional(join(MOSAIC_HOME, 'USER.md'));
+  if (user) parts.push('\n\n# User Profile\n\n' + user);
+
+  // TOOLS.md
+  const tools = readOptional(join(MOSAIC_HOME, 'TOOLS.md'));
+  if (tools) parts.push('\n\n# Machine Tools\n\n' + tools);
+
+  // Runtime-specific contract
+  parts.push('\n\n# Runtime-Specific Contract\n\n' + readFileSync(runtimeFile, 'utf-8'));
+
+  return parts.join('\n');
+}
+
+// ─── Session lock ────────────────────────────────────────────────────────────
+
+function writeSessionLock(runtime: string): void {
+  const missionFile = '.mosaic/orchestrator/mission.json';
+  const lockFile = '.mosaic/orchestrator/session.lock';
+  const data = readJson(missionFile);
+  if (!data) return;
+
+  const status = String(data['status'] ?? 'inactive');
+  if (status !== 'active' && status !== 'paused') return;
+
+  const sessionId = `${runtime}-${new Date().toISOString().replace(/[:.]/g, '-')}-${process.pid}`;
+  const lock = {
+    session_id: sessionId,
+    runtime,
+    pid: process.pid,
+    started_at: new Date().toISOString(),
+    project_path: process.cwd(),
+    milestone_id: '',
+  };
+
+  try {
+    mkdirSync(dirname(lockFile), { recursive: true });
+    writeFileSync(lockFile, JSON.stringify(lock, null, 2) + '\n');
+
+    // Clean up on exit
+    const cleanup = () => {
+      try {
+        rmSync(lockFile, { force: true });
+      } catch {
+        // best-effort
+      }
+    };
+    process.on('exit', cleanup);
+    process.on('SIGINT', () => {
+      cleanup();
+      process.exit(130);
+    });
+    process.on('SIGTERM', () => {
+      cleanup();
+      process.exit(143);
+    });
+  } catch {
+    // Non-fatal
+  }
+}
+
+// ─── Resumable session advisory ──────────────────────────────────────────────
+
+function checkResumableSession(): void {
+  const lockFile = '.mosaic/orchestrator/session.lock';
+  const missionFile = '.mosaic/orchestrator/mission.json';
+
+  if (existsSync(lockFile)) {
+    const lock = readJson(lockFile);
+    if (lock) {
+      const pid = Number(lock['pid'] ?? 0);
+      if (pid > 0) {
+        try {
+          process.kill(pid, 0); // Check if alive
+        } catch {
+          // Process is dead — stale lock
+          rmSync(lockFile, { force: true });
+          console.log(`[mosaic] Cleaned up stale session lock (PID ${pid} no longer running).\n`);
+        }
+      }
+    }
+  } else if (existsSync(missionFile)) {
+    const data = readJson(missionFile);
+    if (data && data['status'] === 'active') {
+      console.log('[mosaic] Active mission detected. Generate continuation prompt with:');
+      console.log('[mosaic]   mosaic coord continue\n');
+    }
+  }
+}
+
+// ─── Write config for runtimes that read from fixed paths ────────────────────
+
+function ensureRuntimeConfig(runtime: RuntimeName, destPath: string): void {
+  const prompt = buildRuntimePrompt(runtime);
+  mkdirSync(dirname(destPath), { recursive: true });
+  const existing = readOptional(destPath);
+  if (existing !== prompt) {
+    writeFileSync(destPath, prompt);
+  }
+}
+
+// ─── Pi skill/extension discovery ────────────────────────────────────────────
+
+function discoverPiSkills(): string[] {
+  const args: string[] = [];
+  for (const skillsRoot of [join(MOSAIC_HOME, 'skills'), join(MOSAIC_HOME, 'skills-local')]) {
+    if (!existsSync(skillsRoot)) continue;
+    try {
+      for (const entry of readdirSync(skillsRoot, { withFileTypes: true })) {
+        if (!entry.isDirectory()) continue;
+        const skillDir = join(skillsRoot, entry.name);
+        if (existsSync(join(skillDir, 'SKILL.md'))) {
+          args.push('--skill', skillDir);
+        }
+      }
+    } catch {
+      // skip
+    }
+  }
+  return args;
+}
+
+function discoverPiExtension(): string[] {
+  const ext = join(MOSAIC_HOME, 'runtime', 'pi', 'mosaic-extension.ts');
+  return existsSync(ext) ? ['--extension', ext] : [];
+}
+
+// ─── Launch functions ────────────────────────────────────────────────────────
+
+function getMissionPrompt(): string {
+  const mission = detectMission();
+  if (!mission) return '';
+  return `Active mission detected: ${mission.name}. Read the mission state files and report status.`;
+}
+
+function launchRuntime(runtime: RuntimeName, args: string[], yolo: boolean): never {
+  checkMosaicHome();
+  checkFile(join(MOSAIC_HOME, 'AGENTS.md'), 'AGENTS.md');
+  checkSoul();
+  checkRuntime(runtime);
+
+  // Pi doesn't need sequential-thinking (has native thinking levels)
+  if (runtime !== 'pi') {
+    checkSequentialThinking(runtime);
+  }
+
+  checkResumableSession();
+
+  const missionPrompt = getMissionPrompt();
+  const hasMissionNoArgs = missionPrompt && args.length === 0;
+  const label = RUNTIME_LABELS[runtime];
+  const modeStr = yolo ? ' in YOLO mode' : '';
+  const missionStr = hasMissionNoArgs ? ' (active mission detected)' : '';
+
+  writeSessionLock(runtime);
+
+  switch (runtime) {
+    case 'claude': {
+      const prompt = buildRuntimePrompt('claude');
+      const cliArgs = yolo ? ['--dangerously-skip-permissions'] : [];
+      cliArgs.push('--append-system-prompt', prompt);
+      if (hasMissionNoArgs) {
+        cliArgs.push(missionPrompt);
+      } else {
+        cliArgs.push(...args);
+      }
+      console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
+      execRuntime('claude', cliArgs);
+      break;
+    }
+
+    case 'codex': {
+      ensureRuntimeConfig('codex', join(homedir(), '.codex', 'instructions.md'));
+      const cliArgs = yolo ? ['--dangerously-bypass-approvals-and-sandbox'] : [];
+      if (hasMissionNoArgs) {
+        cliArgs.push(missionPrompt);
+      } else {
+        cliArgs.push(...args);
+      }
+      console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
+      execRuntime('codex', cliArgs);
+      break;
+    }
+
+    case 'opencode': {
+      ensureRuntimeConfig('opencode', join(homedir(), '.config', 'opencode', 'AGENTS.md'));
+      console.log(`[mosaic] Launching ${label}${modeStr}...`);
+      execRuntime('opencode', args);
+      break;
+    }
+
+    case 'pi': {
+      const prompt = buildRuntimePrompt('pi');
+      const cliArgs = ['--append-system-prompt', prompt];
+      cliArgs.push(...discoverPiSkills());
+      cliArgs.push(...discoverPiExtension());
+      if (hasMissionNoArgs) {
+        cliArgs.push(missionPrompt);
+      } else {
+        cliArgs.push(...args);
+      }
+      console.log(`[mosaic] Launching ${label}${modeStr}${missionStr}...`);
+      execRuntime('pi', cliArgs);
+      break;
+    }
+  }
+
+  process.exit(0); // Unreachable but satisfies never
+}
+
+/** exec into the runtime, replacing the current process. */
+function execRuntime(cmd: string, args: string[]): void {
+  try {
+    // Use execFileSync with inherited stdio to replace the process
+    const result = spawnSync(cmd, args, {
+      stdio: 'inherit',
+      env: process.env,
+    });
+    process.exit(result.status ?? 0);
+  } catch (err) {
+    console.error(`[mosaic] Failed to launch ${cmd}:`, err instanceof Error ? err.message : err);
+    process.exit(1);
+  }
+}
+
+// ─── Framework script/tool delegation ───────────────────────────────────────
+
+function delegateToScript(scriptPath: string, args: string[], env?: Record<string, string>): never {
+  if (!existsSync(scriptPath)) {
+    console.error(`[mosaic] Script not found: ${scriptPath}`);
+    process.exit(1);
+  }
+  try {
+    execFileSync('bash', [scriptPath, ...args], {
+      stdio: 'inherit',
+      env: { ...process.env, ...env },
+    });
+    process.exit(0);
+  } catch (err) {
+    process.exit((err as { status?: number }).status ?? 1);
+  }
+}
+
+/**
+ * Resolve a path under the framework tools directory. Prefers the version
+ * bundled in the @mosaic/mosaic npm package (always matches the installed
+ * CLI version) over the deployed copy in ~/.config/mosaic/ (may be stale).
+ */
+function resolveTool(...segments: string[]): string {
+  try {
+    const req = createRequire(import.meta.url);
+    const mosaicPkg = dirname(req.resolve('@mosaic/mosaic/package.json'));
+    const bundled = join(mosaicPkg, 'framework', 'tools', ...segments);
+    if (existsSync(bundled)) return bundled;
+  } catch {
+    // Fall through to deployed copy
+  }
+  return join(MOSAIC_HOME, 'tools', ...segments);
+}
+
+function fwScript(name: string): string {
+  return resolveTool('_scripts', name);
+}
+
+function toolScript(toolDir: string, name: string): string {
+  return resolveTool(toolDir, name);
+}
+
+// ─── Coord (mission orchestrator) ───────────────────────────────────────────
+
+const COORD_SUBCMDS: Record<string, string> = {
+  status: 'session-status.sh',
+  session: 'session-status.sh',
+  init: 'mission-init.sh',
+  mission: 'mission-status.sh',
+  progress: 'mission-status.sh',
+  continue: 'continue-prompt.sh',
+  next: 'continue-prompt.sh',
+  run: 'session-run.sh',
+  start: 'session-run.sh',
+  smoke: 'smoke-test.sh',
+  test: 'smoke-test.sh',
+  resume: 'session-resume.sh',
+  recover: 'session-resume.sh',
+};
+
+function runCoord(args: string[]): never {
+  checkMosaicHome();
+  let runtime = 'claude';
+  let yoloFlag = '';
+  const coordArgs: string[] = [];
+
+  for (const arg of args) {
+    if (arg === '--claude' || arg === '--codex' || arg === '--pi') {
+      runtime = arg.slice(2);
+    } else if (arg === '--yolo') {
+      yoloFlag = '--yolo';
+    } else {
+      coordArgs.push(arg);
+    }
+  }
+
+  const subcmd = coordArgs[0] ?? 'help';
+  const subArgs = coordArgs.slice(1);
+  const script = COORD_SUBCMDS[subcmd];
+
+  if (!script) {
+    console.log(`mosaic coord — mission coordinator tools
+
+Commands:
+  init --name <name> [opts]   Initialize a new mission
+  mission [--project <path>]  Show mission progress dashboard
+  status [--project <path>]   Check agent session health
+  continue [--project <path>] Generate continuation prompt
+  run [--project <path>]      Launch runtime with mission context
+  smoke                       Run orchestration smoke checks
+  resume [--project <path>]   Crash recovery
+
+Runtime: --claude (default) | --codex | --pi | --yolo`);
+    process.exit(subcmd === 'help' ? 0 : 1);
+  }
+
+  if (yoloFlag) subArgs.unshift(yoloFlag);
+  delegateToScript(toolScript('orchestrator', script), subArgs, {
+    MOSAIC_COORD_RUNTIME: runtime,
+  });
+}
+
+// ─── Prdy (PRD tools via framework scripts) ─────────────────────────────────
+
+const PRDY_SUBCMDS: Record<string, string> = {
+  init: 'prdy-init.sh',
+  update: 'prdy-update.sh',
+  validate: 'prdy-validate.sh',
+  check: 'prdy-validate.sh',
+  status: 'prdy-status.sh',
+};
+
+function runPrdyLocal(args: string[]): never {
+  checkMosaicHome();
+  let runtime = 'claude';
+  const prdyArgs: string[] = [];
+
+  for (const arg of args) {
+    if (arg === '--claude' || arg === '--codex' || arg === '--pi') {
+      runtime = arg.slice(2);
+    } else {
+      prdyArgs.push(arg);
+    }
+  }
+
+  const subcmd = prdyArgs[0] ?? 'help';
+  const subArgs = prdyArgs.slice(1);
+  const script = PRDY_SUBCMDS[subcmd];
+
+  if (!script) {
+    console.log(`mosaic prdy — PRD creation and validation
+
+Commands:
+  init [--project <path>] [--name <feature>]   Create docs/PRD.md
+  update [--project <path>]                    Update existing PRD
+  validate [--project <path>]                  Check PRD completeness
+  status [--project <path>]                    Quick PRD health check
+
+Runtime: --claude (default) | --codex | --pi`);
+    process.exit(subcmd === 'help' ? 0 : 1);
+  }
+
+  delegateToScript(toolScript('prdy', script), subArgs, {
+    MOSAIC_PRDY_RUNTIME: runtime,
+  });
+}
+
+// ─── Seq (sequential-thinking MCP) ──────────────────────────────────────────
+
+function runSeq(args: string[]): never {
+  checkMosaicHome();
+  const action = args[0] ?? 'check';
+  const rest = args.slice(1);
+  const checker = fwScript('mosaic-ensure-sequential-thinking');
+
+  switch (action) {
+    case 'check':
+      delegateToScript(checker, ['--check', ...rest]);
+      break; // unreachable
+    case 'fix':
+    case 'apply':
+      delegateToScript(checker, rest);
+      break;
+    case 'start': {
+      console.log('[mosaic] Starting sequential-thinking MCP server...');
+      try {
+        execFileSync('npx', ['-y', '@modelcontextprotocol/server-sequential-thinking', ...rest], {
+          stdio: 'inherit',
+        });
+        process.exit(0);
+      } catch (err) {
+        process.exit((err as { status?: number }).status ?? 1);
+      }
+      break;
+    }
+    default:
+      console.error(`[mosaic] Unknown seq subcommand '${action}'. Use: check|fix|start`);
+      process.exit(1);
+  }
+}
+
+// ─── Upgrade ────────────────────────────────────────────────────────────────
+
+function runUpgrade(args: string[]): never {
+  checkMosaicHome();
+  const subcmd = args[0];
+
+  if (!subcmd || subcmd === 'release') {
+    delegateToScript(fwScript('mosaic-release-upgrade'), args.slice(subcmd === 'release' ? 1 : 0));
+  } else if (subcmd === 'check') {
+    delegateToScript(fwScript('mosaic-release-upgrade'), ['--dry-run', ...args.slice(1)]);
+  } else if (subcmd === 'project') {
+    delegateToScript(fwScript('mosaic-upgrade'), args.slice(1));
+  } else if (subcmd.startsWith('-')) {
+    delegateToScript(fwScript('mosaic-release-upgrade'), args);
+  } else {
+    delegateToScript(fwScript('mosaic-upgrade'), args);
+  }
+}
+
+// ─── Commander registration ─────────────────────────────────────────────────
+
+export function registerLaunchCommands(program: Command): void {
+  // Runtime launchers
+  for (const runtime of ['claude', 'codex', 'opencode', 'pi'] as const) {
+    program
+      .command(runtime)
+      .description(`Launch ${RUNTIME_LABELS[runtime]} with Mosaic injection`)
+      .allowUnknownOption(true)
+      .allowExcessArguments(true)
+      .action((_opts: unknown, cmd: Command) => {
+        launchRuntime(runtime, cmd.args, false);
+      });
+  }
+
+  // Yolo mode
+  program
+    .command('yolo <runtime>')
+    .description('Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi)')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action((runtime: string, _opts: unknown, cmd: Command) => {
+      const valid: RuntimeName[] = ['claude', 'codex', 'opencode', 'pi'];
+      if (!valid.includes(runtime as RuntimeName)) {
+        console.error(
+          `[mosaic] ERROR: Unsupported yolo runtime '${runtime}'. Use: ${valid.join('|')}`,
+        );
+        process.exit(1);
+      }
+      launchRuntime(runtime as RuntimeName, cmd.args, true);
+    });
+
+  // Coord (mission orchestrator)
+  program
+    .command('coord')
+    .description('Mission coordinator tools (init, status, run, continue, resume)')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action((_opts: unknown, cmd: Command) => {
+      runCoord(cmd.args);
+    });
+
+  // Prdy (PRD tools via local framework scripts)
+  program
+    .command('prdy')
+    .description('PRD creation and validation (init, update, validate, status)')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action((_opts: unknown, cmd: Command) => {
+      runPrdyLocal(cmd.args);
+    });
+
+  // Seq (sequential-thinking MCP management)
+  program
+    .command('seq')
+    .description('sequential-thinking MCP management (check/fix/start)')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action((_opts: unknown, cmd: Command) => {
+      runSeq(cmd.args);
+    });
+
+  // Upgrade (release + project)
+  program
+    .command('upgrade')
+    .description('Upgrade Mosaic release or project files')
+    .allowUnknownOption(true)
+    .allowExcessArguments(true)
+    .action((_opts: unknown, cmd: Command) => {
+      runUpgrade(cmd.args);
+    });
+
+  // Direct framework script delegates
+  const directCommands: Record<string, { desc: string; script: string }> = {
+    init: { desc: 'Generate SOUL.md (agent identity contract)', script: 'mosaic-init' },
+    doctor: { desc: 'Health audit — detect drift and missing files', script: 'mosaic-doctor' },
+    sync: { desc: 'Sync skills from canonical source', script: 'mosaic-sync-skills' },
+    bootstrap: {
+      desc: 'Bootstrap a repo with Mosaic standards',
+      script: 'mosaic-bootstrap-repo',
+    },
+  };
+
+  for (const [name, { desc, script }] of Object.entries(directCommands)) {
+    program
+      .command(name)
+      .description(desc)
+      .allowUnknownOption(true)
+      .allowExcessArguments(true)
+      .action((_opts: unknown, cmd: Command) => {
+        checkMosaicHome();
+        delegateToScript(fwScript(script), cmd.args);
+      });
+  }
+}

packages/mosaic/src/commands/mission.ts

@@ -0,0 +1,385 @@
+import type { Command } from 'commander';
+import { withAuth } from './with-auth.js';
+import { selectItem } from './select-dialog.js';
+import {
+  fetchMissions,
+  fetchMission,
+  createMission,
+  updateMission,
+  fetchMissionTasks,
+  createMissionTask,
+  updateMissionTask,
+  fetchProjects,
+} from '../tui/gateway-api.js';
+import type { MissionInfo, MissionTaskInfo } from '../tui/gateway-api.js';
+
+function formatMission(m: MissionInfo): string {
+  return `${m.name} — ${m.status}${m.phase ? ` (${m.phase})` : ''}`;
+}
+
+function showMissionDetail(m: MissionInfo) {
+  console.log(`  ID:          ${m.id}`);
+  console.log(`  Name:        ${m.name}`);
+  console.log(`  Status:      ${m.status}`);
+  console.log(`  Phase:       ${m.phase ?? '—'}`);
+  console.log(`  Project:     ${m.projectId ?? '—'}`);
+  console.log(`  Description: ${m.description ?? '—'}`);
+  console.log(`  Created:     ${new Date(m.createdAt).toLocaleString()}`);
+}
+
+function showTaskDetail(t: MissionTaskInfo) {
+  console.log(`  ID:          ${t.id}`);
+  console.log(`  Status:      ${t.status}`);
+  console.log(`  Description: ${t.description ?? '—'}`);
+  console.log(`  Notes:       ${t.notes ?? '—'}`);
+  console.log(`  PR:          ${t.pr ?? '—'}`);
+  console.log(`  Created:     ${new Date(t.createdAt).toLocaleString()}`);
+}
+
+export function registerMissionCommand(program: Command) {
+  const cmd = program
+    .command('mission')
+    .description('Manage missions')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+    .option('--list', 'List all missions')
+    .option('--init', 'Create a new mission')
+    .option('--plan <idOrName>', 'Run PRD wizard for a mission')
+    .option('--update <idOrName>', 'Update a mission')
+    .option('--project <idOrName>', 'Scope to project')
+    .argument('[id]', 'Show mission detail by ID')
+    .action(
+      async (
+        id: string | undefined,
+        opts: {
+          gateway: string;
+          list?: boolean;
+          init?: boolean;
+          plan?: string;
+          update?: string;
+          project?: string;
+        },
+      ) => {
+        const auth = await withAuth(opts.gateway);
+
+        if (opts.list) {
+          return listMissions(auth.gateway, auth.cookie);
+        }
+        if (opts.init) {
+          return initMission(auth.gateway, auth.cookie);
+        }
+        if (opts.plan) {
+          return planMission(auth.gateway, auth.cookie, opts.plan, opts.project);
+        }
+        if (opts.update) {
+          return updateMissionWizard(auth.gateway, auth.cookie, opts.update);
+        }
+        if (id) {
+          return showMission(auth.gateway, auth.cookie, id);
+        }
+
+        // Default: interactive select
+        return interactiveSelect(auth.gateway, auth.cookie);
+      },
+    );
+
+  // Task subcommand
+  cmd
+    .command('task')
+    .description('Manage mission tasks')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+    .option('--list', 'List tasks for a mission')
+    .option('--new', 'Create a task')
+    .option('--update <taskId>', 'Update a task')
+    .option('--mission <idOrName>', 'Mission ID or name')
+    .argument('[taskId]', 'Show task detail')
+    .action(
+      async (
+        taskId: string | undefined,
+        taskOpts: {
+          gateway: string;
+          list?: boolean;
+          new?: boolean;
+          update?: string;
+          mission?: string;
+        },
+      ) => {
+        const auth = await withAuth(taskOpts.gateway);
+
+        const missionId = await resolveMissionId(auth.gateway, auth.cookie, taskOpts.mission);
+        if (!missionId) return;
+
+        if (taskOpts.list) {
+          return listTasks(auth.gateway, auth.cookie, missionId);
+        }
+        if (taskOpts.new) {
+          return createTaskWizard(auth.gateway, auth.cookie, missionId);
+        }
+        if (taskOpts.update) {
+          return updateTaskWizard(auth.gateway, auth.cookie, missionId, taskOpts.update);
+        }
+        if (taskId) {
+          return showTask(auth.gateway, auth.cookie, missionId, taskId);
+        }
+
+        return listTasks(auth.gateway, auth.cookie, missionId);
+      },
+    );
+
+  return cmd;
+}
+
+async function resolveMissionByName(
+  gateway: string,
+  cookie: string,
+  idOrName: string,
+): Promise<MissionInfo | undefined> {
+  const missions = await fetchMissions(gateway, cookie);
+  return missions.find((m) => m.id === idOrName || m.name === idOrName);
+}
+
+async function resolveMissionId(
+  gateway: string,
+  cookie: string,
+  idOrName?: string,
+): Promise<string | undefined> {
+  if (idOrName) {
+    const mission = await resolveMissionByName(gateway, cookie, idOrName);
+    if (!mission) {
+      console.error(`Mission "${idOrName}" not found.`);
+      return undefined;
+    }
+    return mission.id;
+  }
+
+  // Interactive select
+  const missions = await fetchMissions(gateway, cookie);
+  const selected = await selectItem(missions, {
+    message: 'Select a mission:',
+    render: formatMission,
+    emptyMessage: 'No missions found. Create one with `mosaic mission --init`.',
+  });
+  return selected?.id;
+}
+
+async function listMissions(gateway: string, cookie: string) {
+  const missions = await fetchMissions(gateway, cookie);
+  if (missions.length === 0) {
+    console.log('No missions found.');
+    return;
+  }
+  console.log(`Missions (${missions.length}):\n`);
+  for (const m of missions) {
+    const phase = m.phase ? ` [${m.phase}]` : '';
+    console.log(`  ${m.name}  ${m.status}${phase}  ${m.id.slice(0, 8)}`);
+  }
+}
+
+async function showMission(gateway: string, cookie: string, id: string) {
+  try {
+    const mission = await fetchMission(gateway, cookie, id);
+    showMissionDetail(mission);
+  } catch {
+    // Try resolving by name
+    const m = await resolveMissionByName(gateway, cookie, id);
+    if (!m) {
+      console.error(`Mission "${id}" not found.`);
+      process.exit(1);
+    }
+    showMissionDetail(m);
+  }
+}
+
+async function interactiveSelect(gateway: string, cookie: string) {
+  const missions = await fetchMissions(gateway, cookie);
+  const selected = await selectItem(missions, {
+    message: 'Select a mission:',
+    render: formatMission,
+    emptyMessage: 'No missions found. Create one with `mosaic mission --init`.',
+  });
+  if (selected) {
+    showMissionDetail(selected);
+  }
+}
+
+async function initMission(gateway: string, cookie: string) {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    const name = await ask('Mission name: ');
+    if (!name.trim()) {
+      console.error('Name is required.');
+      return;
+    }
+
+    // Project selection
+    const projects = await fetchProjects(gateway, cookie);
+    let projectId: string | undefined;
+    if (projects.length > 0) {
+      const selected = await selectItem(projects, {
+        message: 'Assign to project (required):',
+        render: (p) => `${p.name} (${p.status})`,
+        emptyMessage: 'No projects found.',
+      });
+      if (selected) projectId = selected.id;
+    }
+
+    const description = await ask('Description (optional): ');
+
+    const mission = await createMission(gateway, cookie, {
+      name: name.trim(),
+      projectId,
+      description: description.trim() || undefined,
+      status: 'planning',
+    });
+
+    console.log(`\nMission "${mission.name}" created (${mission.id}).`);
+  } finally {
+    rl.close();
+  }
+}
+
+async function planMission(
+  gateway: string,
+  cookie: string,
+  idOrName: string,
+  _projectIdOrName?: string,
+) {
+  const mission = await resolveMissionByName(gateway, cookie, idOrName);
+  if (!mission) {
+    console.error(`Mission "${idOrName}" not found.`);
+    process.exit(1);
+  }
+
+  console.log(`Planning mission: ${mission.name}\n`);
+
+  try {
+    const { runPrdWizard } = await import('@mosaic/prdy');
+    await runPrdWizard({
+      name: mission.name,
+      projectPath: process.cwd(),
+      interactive: true,
+    });
+  } catch (err) {
+    console.error(`PRD wizard failed: ${err instanceof Error ? err.message : String(err)}`);
+    process.exit(1);
+  }
+}
+
+async function updateMissionWizard(gateway: string, cookie: string, idOrName: string) {
+  const mission = await resolveMissionByName(gateway, cookie, idOrName);
+  if (!mission) {
+    console.error(`Mission "${idOrName}" not found.`);
+    process.exit(1);
+  }
+
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    console.log(`Updating mission: ${mission.name}\n`);
+
+    const name = await ask(`Name [${mission.name}]: `);
+    const description = await ask(`Description [${mission.description ?? 'none'}]: `);
+    const status = await ask(`Status [${mission.status}]: `);
+
+    const updates: Record<string, unknown> = {};
+    if (name.trim()) updates['name'] = name.trim();
+    if (description.trim()) updates['description'] = description.trim();
+    if (status.trim()) updates['status'] = status.trim();
+
+    if (Object.keys(updates).length === 0) {
+      console.log('No changes.');
+      return;
+    }
+
+    const updated = await updateMission(gateway, cookie, mission.id, updates);
+    console.log(`\nMission "${updated.name}" updated.`);
+  } finally {
+    rl.close();
+  }
+}
+
+// ── Task operations ──
+
+async function listTasks(gateway: string, cookie: string, missionId: string) {
+  const tasks = await fetchMissionTasks(gateway, cookie, missionId);
+  if (tasks.length === 0) {
+    console.log('No tasks found.');
+    return;
+  }
+  console.log(`Tasks (${tasks.length}):\n`);
+  for (const t of tasks) {
+    const desc = t.description ? ` — ${t.description.slice(0, 60)}` : '';
+    console.log(`  ${t.id.slice(0, 8)}  ${t.status}${desc}`);
+  }
+}
+
+async function showTask(gateway: string, cookie: string, missionId: string, taskId: string) {
+  const tasks = await fetchMissionTasks(gateway, cookie, missionId);
+  const task = tasks.find((t) => t.id === taskId);
+  if (!task) {
+    console.error(`Task "${taskId}" not found.`);
+    process.exit(1);
+  }
+  showTaskDetail(task);
+}
+
+async function createTaskWizard(gateway: string, cookie: string, missionId: string) {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    const description = await ask('Task description: ');
+    if (!description.trim()) {
+      console.error('Description is required.');
+      return;
+    }
+
+    const status = await ask('Status [not-started]: ');
+
+    const task = await createMissionTask(gateway, cookie, missionId, {
+      description: description.trim(),
+      status: status.trim() || 'not-started',
+    });
+
+    console.log(`\nTask created (${task.id}).`);
+  } finally {
+    rl.close();
+  }
+}
+
+async function updateTaskWizard(
+  gateway: string,
+  cookie: string,
+  missionId: string,
+  taskId: string,
+) {
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  try {
+    const status = await ask('New status: ');
+    const notes = await ask('Notes (optional): ');
+    const pr = await ask('PR (optional): ');
+
+    const updates: Record<string, unknown> = {};
+    if (status.trim()) updates['status'] = status.trim();
+    if (notes.trim()) updates['notes'] = notes.trim();
+    if (pr.trim()) updates['pr'] = pr.trim();
+
+    if (Object.keys(updates).length === 0) {
+      console.log('No changes.');
+      return;
+    }
+
+    const updated = await updateMissionTask(gateway, cookie, missionId, taskId, updates);
+    console.log(`\nTask ${updated.id.slice(0, 8)} updated (${updated.status}).`);
+  } finally {
+    rl.close();
+  }
+}

packages/mosaic/src/commands/prdy.ts

@@ -0,0 +1,55 @@
+import type { Command } from 'commander';
+import { withAuth } from './with-auth.js';
+import { fetchProjects } from '../tui/gateway-api.js';
+
+export function registerPrdyCommand(program: Command) {
+  const cmd = program
+    .command('prdy')
+    .description('PRD wizard — create and manage Product Requirement Documents')
+    .option('-g, --gateway <url>', 'Gateway URL', 'http://localhost:14242')
+    .option('--init [name]', 'Create a new PRD')
+    .option('--update [name]', 'Update an existing PRD')
+    .option('--project <idOrName>', 'Scope to project')
+    .action(
+      async (opts: {
+        gateway: string;
+        init?: string | boolean;
+        update?: string | boolean;
+        project?: string;
+      }) => {
+        // Detect project context when --project flag is provided
+        if (opts.project) {
+          try {
+            const auth = await withAuth(opts.gateway);
+            const projects = await fetchProjects(auth.gateway, auth.cookie);
+            const match = projects.find((p) => p.id === opts.project || p.name === opts.project);
+            if (match) {
+              console.log(`Project context: ${match.name} (${match.id})\n`);
+            }
+          } catch {
+            // Gateway not available — proceed without project context
+          }
+        }
+
+        try {
+          const { runPrdWizard } = await import('@mosaic/prdy');
+          const name =
+            typeof opts.init === 'string'
+              ? opts.init
+              : typeof opts.update === 'string'
+                ? opts.update
+                : 'untitled';
+          await runPrdWizard({
+            name,
+            projectPath: process.cwd(),
+            interactive: true,
+          });
+        } catch (err) {
+          console.error(`PRD wizard failed: ${err instanceof Error ? err.message : String(err)}`);
+          process.exit(1);
+        }
+      },
+    );
+
+  return cmd;
+}

packages/mosaic/src/commands/select-dialog.ts

@@ -0,0 +1,58 @@
+/**
+ * Interactive item selection. Uses @clack/prompts when TTY, falls back to numbered list.
+ */
+export async function selectItem<T>(
+  items: T[],
+  opts: {
+    message: string;
+    render: (item: T) => string;
+    emptyMessage?: string;
+  },
+): Promise<T | undefined> {
+  if (items.length === 0) {
+    console.log(opts.emptyMessage ?? 'No items found.');
+    return undefined;
+  }
+
+  const isTTY = process.stdin.isTTY;
+
+  if (isTTY) {
+    try {
+      const { select } = await import('@clack/prompts');
+      const result = await select({
+        message: opts.message,
+        options: items.map((item, i) => ({
+          value: i,
+          label: opts.render(item),
+        })),
+      });
+
+      if (typeof result === 'symbol') {
+        return undefined;
+      }
+
+      return items[result as number];
+    } catch {
+      // Fall through to non-interactive
+    }
+  }
+
+  // Non-interactive: display numbered list and read a number
+  console.log(`\n${opts.message}\n`);
+  for (let i = 0; i < items.length; i++) {
+    console.log(`  ${i + 1}. ${opts.render(items[i]!)}`);
+  }
+
+  const readline = await import('node:readline');
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  const answer = await new Promise<string>((resolve) => rl.question('\nSelect: ', resolve));
+  rl.close();
+
+  const index = parseInt(answer, 10) - 1;
+  if (isNaN(index) || index < 0 || index >= items.length) {
+    console.error('Invalid selection.');
+    return undefined;
+  }
+
+  return items[index];
+}

packages/mosaic/src/commands/with-auth.ts

@@ -0,0 +1,29 @@
+import type { AuthResult } from '../auth.js';
+
+export interface AuthContext {
+  gateway: string;
+  session: AuthResult;
+  cookie: string;
+}
+
+/**
+ * Load and validate the user's auth session.
+ * Exits with an error message if not signed in or session expired.
+ */
+export async function withAuth(gateway: string): Promise<AuthContext> {
+  const { loadSession, validateSession } = await import('../auth.js');
+
+  const session = loadSession(gateway);
+  if (!session) {
+    console.error('Not signed in. Run `mosaic login` first.');
+    process.exit(1);
+  }
+
+  const valid = await validateSession(gateway, session.cookie);
+  if (!valid) {
+    console.error('Session expired. Run `mosaic login` again.');
+    process.exit(1);
+  }
+
+  return { gateway, session, cookie: session.cookie };
+}

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

@@ -1,4 +1,4 @@
-import { readFileSync, existsSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
 import type { ConfigService } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
@@ -140,6 +140,23 @@ export class FileConfigAdapter implements ConfigService {
       preserve: preservePaths,
       excludeGit: true,
     });
+
+    // Copy default root-level .md files (AGENTS.md, STANDARDS.md, etc.)
+    // from framework/defaults/ into mosaicHome root if they don't exist yet.
+    // These are framework contracts — only written on first install, never
+    // overwritten (user may have customized them).
+    const defaultsDir = join(this.sourceDir, 'defaults');
+    if (existsSync(defaultsDir)) {
+      for (const entry of readdirSync(defaultsDir)) {
+        const dest = join(this.mosaicHome, entry);
+        if (!existsSync(dest)) {
+          const src = join(defaultsDir, entry);
+          if (statSync(src).isFile()) {
+            copyFileSync(src, dest);
+          }
+        }
+      }
+    }
   }
 
   /**

packages/mosaic/src/index.ts

@@ -1,93 +1,11 @@
-#!/usr/bin/env node
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
+export const VERSION = '0.0.0';
 
-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 {
-  checkForUpdate,
   backgroundUpdateCheck,
+  checkForUpdate,
   formatUpdateNotice,
+  getInstallCommand,
   getInstalledVersion,
   getLatestVersion,
   semverLt,
 } from './runtime/update-checker.js';
-export type { UpdateCheckResult } from './runtime/update-checker.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/runtime/update-checker.ts

@@ -1,5 +1,5 @@
 /**
- * Mosaic update checker — compares installed @mosaic/cli version against the
+ * Mosaic update checker — compares the installed Mosaic package against the
  * Gitea npm registry and reports when an upgrade is available.
  *
  * Used by:
@@ -23,8 +23,12 @@ import { join } from 'node:path';
 export interface UpdateCheckResult {
   /** Currently installed version (empty if not found) */
   current: string;
+  /** Currently installed package name */
+  currentPackage?: string;
   /** Latest published version (empty if check failed) */
   latest: string;
+  /** Package that should be installed for the latest version */
+  targetPackage?: string;
   /** True when a newer version is available */
   updateAvailable: boolean;
   /** ISO timestamp of this check */
@@ -36,7 +40,9 @@ export interface UpdateCheckResult {
 // ─── Constants ──────────────────────────────────────────────────────────────
 
 const REGISTRY = 'https://git.mosaicstack.dev/api/packages/mosaic/npm/';
-const CLI_PKG = '@mosaic/cli';
+const MODERN_PKG = '@mosaic/mosaic';
+const LEGACY_PKG = '@mosaic/cli';
+const INSTALLED_PACKAGE_ORDER = [MODERN_PKG, LEGACY_PKG] as const;
 const CACHE_DIR = join(homedir(), '.cache', 'mosaic');
 const CACHE_FILE = join(CACHE_DIR, 'update-check.json');
 const CACHE_TTL_MS = 60 * 60 * 1000; // 1 hour
@@ -122,22 +128,33 @@ export function semverLt(a: string, b: string): boolean {
 
 // ─── Cache ──────────────────────────────────────────────────────────────────
 
-function readCache(): UpdateCheckResult | null {
+/** Cache stores only the latest registry version (the expensive network call).
+ *  The installed version is always checked fresh — it's a local `npm ls`. */
+interface RegistryCache {
+  currentPackage?: string;
+  latest: string;
+  targetPackage?: string;
+  checkedAt: string;
+  registry: string;
+}
+
+function readCache(currentPackage: string): RegistryCache | null {
   try {
     if (!existsSync(CACHE_FILE)) return null;
-    const raw = JSON.parse(readFileSync(CACHE_FILE, 'utf-8')) as UpdateCheckResult;
+    const raw = JSON.parse(readFileSync(CACHE_FILE, 'utf-8')) as RegistryCache;
     const age = Date.now() - new Date(raw.checkedAt).getTime();
     if (age > CACHE_TTL_MS) return null;
+    if ((raw.currentPackage || '') !== currentPackage) return null;
     return raw;
   } catch {
     return null;
   }
 }
 
-function writeCache(result: UpdateCheckResult): void {
+function writeCache(entry: RegistryCache): void {
   try {
     mkdirSync(CACHE_DIR, { recursive: true });
-    writeFileSync(CACHE_FILE, JSON.stringify(result, null, 2) + '\n', 'utf-8');
+    writeFileSync(CACHE_FILE, JSON.stringify(entry, null, 2) + '\n', 'utf-8');
   } catch {
     // Best-effort — cache is not critical
   }
@@ -146,10 +163,10 @@ function writeCache(result: UpdateCheckResult): void {
 // ─── Public API ─────────────────────────────────────────────────────────────
 
 /**
- * Get the currently installed version of @mosaic/cli.
- * Returns empty string if not installed.
+ * Get the currently installed Mosaic package version.
+ * Prefers the consolidated @mosaic/mosaic package over legacy @mosaic/cli.
  */
-export function getInstalledVersion(): string {
+export function getInstalledVersion(): { name: string; version: string } {
   // Fast path: check via package.json require chain
   try {
     const raw = npmExec(`ls -g --depth=0 --json 2>/dev/null`, 3000);
@@ -157,46 +174,96 @@ export function getInstalledVersion(): string {
       const data = JSON.parse(raw) as {
         dependencies?: Record<string, { version?: string }>;
       };
-      return data?.dependencies?.[CLI_PKG]?.version ?? '';
+      for (const pkg of INSTALLED_PACKAGE_ORDER) {
+        const version = data?.dependencies?.[pkg]?.version;
+        if (version) {
+          return { name: pkg, version };
+        }
+      }
     }
   } catch {
     // fall through
   }
-  return '';
+  return { name: '', version: '' };
 }
 
 /**
  * Fetch the latest published version from the Gitea npm registry.
+ * For legacy @mosaic/cli installs, try the legacy package first and fall back
+ * to @mosaic/mosaic to support the CLI -> mosaic package consolidation.
  * Returns empty string on failure.
  */
-export function getLatestVersion(): string {
-  return npmExec(`view ${CLI_PKG} version --registry=${REGISTRY}`);
+export function getLatestVersion(installedPackage = ''): { name: string; version: string } {
+  const candidates =
+    installedPackage === LEGACY_PKG ? [LEGACY_PKG, MODERN_PKG] : [MODERN_PKG, LEGACY_PKG];
+
+  for (const pkg of candidates) {
+    const version = npmExec(`view ${pkg} version --registry=${REGISTRY}`);
+    if (version) {
+      return { name: pkg, version };
+    }
+  }
+
+  return { name: '', version: '' };
+}
+
+export function getInstallCommand(result: Pick<UpdateCheckResult, 'targetPackage'>): string {
+  return `npm i -g ${result.targetPackage || MODERN_PKG}@latest`;
 }
 
 /**
- * Perform an update check — uses cache when fresh, otherwise hits registry.
+ * Perform an update check — uses registry cache when fresh, always checks
+ * installed version fresh (local npm ls is cheap, caching it causes stale
+ * "update available" banners after an upgrade).
  * Never throws.
  */
 export function checkForUpdate(options?: { skipCache?: boolean }): UpdateCheckResult {
+  const currentInfo = getInstalledVersion();
+  const current = currentInfo.version;
+
+  let latestInfo: { name: string; version: string };
+  let checkedAt: string;
+
   if (!options?.skipCache) {
-    const cached = readCache();
-    if (cached) return cached;
+    const cached = readCache(currentInfo.name);
+    if (cached) {
+      latestInfo = {
+        name: cached.targetPackage || MODERN_PKG,
+        version: cached.latest,
+      };
+      checkedAt = cached.checkedAt;
+    } else {
+      latestInfo = getLatestVersion(currentInfo.name);
+      checkedAt = new Date().toISOString();
+      writeCache({
+        currentPackage: currentInfo.name,
+        latest: latestInfo.version,
+        targetPackage: latestInfo.name,
+        checkedAt,
+        registry: REGISTRY,
+      });
+    }
+  } else {
+    latestInfo = getLatestVersion(currentInfo.name);
+    checkedAt = new Date().toISOString();
+    writeCache({
+      currentPackage: currentInfo.name,
+      latest: latestInfo.version,
+      targetPackage: latestInfo.name,
+      checkedAt,
+      registry: REGISTRY,
+    });
   }
 
-  const current = getInstalledVersion();
-  const latest = getLatestVersion();
-  const updateAvailable = !!(current && latest && semverLt(current, latest));
-
-  const result: UpdateCheckResult = {
+  return {
     current,
-    latest,
-    updateAvailable,
-    checkedAt: new Date().toISOString(),
+    currentPackage: currentInfo.name,
+    latest: latestInfo.version,
+    targetPackage: latestInfo.name || MODERN_PKG,
+    updateAvailable: !!(current && latestInfo.version && semverLt(current, latestInfo.version)),
+    checkedAt,
     registry: REGISTRY,
   };
-
-  writeCache(result);
-  return result;
 }
 
 /**
@@ -205,14 +272,21 @@ export function checkForUpdate(options?: { skipCache?: boolean }): UpdateCheckRe
 export function formatUpdateNotice(result: UpdateCheckResult): string {
   if (!result.updateAvailable) return '';
 
+  const installCommand = getInstallCommand(result);
+  const targetChanged =
+    result.currentPackage && result.targetPackage && result.currentPackage !== result.targetPackage;
+
   const lines = [
     '',
     '╭─────────────────────────────────────────────────╮',
     '│                                                 │',
     `│   Update available: ${result.current} → ${result.latest}`.padEnd(50) + '│',
+    ...(targetChanged
+      ? [`│   Package target: ${result.currentPackage} → ${result.targetPackage}`.padEnd(50) + '│']
+      : []),
     '│                                                 │',
     '│   Run:  bash tools/install.sh                   │',
-    '│   Or:   npm i -g @mosaic/cli@latest             │',
+    `│   Or:   ${installCommand}`.padEnd(50) + '│',
     '│                                                 │',
     '╰─────────────────────────────────────────────────╯',
     '',

packages/mosaic/src/tui/app.tsx

@@ -0,0 +1,468 @@
+import React, { useState, useCallback, useEffect, useMemo, useRef } from 'react';
+import { Box, useApp, useInput } from 'ink';
+import type { ParsedCommand } from '@mosaic/types';
+import { TopBar } from './components/top-bar.js';
+import { BottomBar } from './components/bottom-bar.js';
+import { MessageList } from './components/message-list.js';
+import { InputBar } from './components/input-bar.js';
+import { Sidebar } from './components/sidebar.js';
+import { SearchBar } from './components/search-bar.js';
+import { useSocket } from './hooks/use-socket.js';
+import { useGitInfo } from './hooks/use-git-info.js';
+import { useViewport } from './hooks/use-viewport.js';
+import { useAppMode } from './hooks/use-app-mode.js';
+import { useConversations } from './hooks/use-conversations.js';
+import { useSearch } from './hooks/use-search.js';
+import { executeHelp, executeStatus, executeHistory, commandRegistry } from './commands/index.js';
+import { fetchConversationMessages } from './gateway-api.js';
+import { expandFileRefs, hasFileRefs, handleAttachCommand } from './file-ref.js';
+
+export interface TuiAppProps {
+  gatewayUrl: string;
+  conversationId?: string;
+  sessionCookie?: string;
+  initialModel?: string;
+  initialProvider?: string;
+  agentId?: string;
+  agentName?: string;
+  projectId?: string;
+  /** CLI package version passed from the entry point (cli.ts). */
+  version?: string;
+}
+
+export function TuiApp({
+  gatewayUrl,
+  conversationId,
+  sessionCookie,
+  initialModel,
+  initialProvider,
+  agentId,
+  agentName,
+  projectId: _projectId,
+  version = '0.0.0',
+}: TuiAppProps) {
+  const { exit } = useApp();
+  const gitInfo = useGitInfo();
+  const appMode = useAppMode();
+
+  const socket = useSocket({
+    gatewayUrl,
+    sessionCookie,
+    initialConversationId: conversationId,
+    initialModel,
+    initialProvider,
+    agentId,
+  });
+
+  const conversations = useConversations({ gatewayUrl, sessionCookie });
+
+  const viewport = useViewport({ totalItems: socket.messages.length });
+
+  const search = useSearch(socket.messages);
+
+  // Scroll to current match when it changes
+  const currentMatch = search.matches[search.currentMatchIndex];
+  useEffect(() => {
+    if (currentMatch && appMode.mode === 'search') {
+      viewport.scrollTo(currentMatch.messageIndex);
+    }
+  }, [currentMatch, appMode.mode, viewport]);
+
+  // Compute highlighted message indices for MessageList
+  const highlightedMessageIndices = useMemo(() => {
+    if (search.matches.length === 0) return undefined;
+    return new Set(search.matches.map((m) => m.messageIndex));
+  }, [search.matches]);
+
+  const currentHighlightIndex = currentMatch?.messageIndex;
+
+  const [sidebarSelectedIndex, setSidebarSelectedIndex] = useState(0);
+
+  // Controlled input state — held here so Ctrl+C can clear it
+  const [tuiInput, setTuiInput] = useState('');
+  // Ctrl+C double-press: first press with empty input shows hint; second exits
+  const ctrlCPendingExit = useRef(false);
+  // Flag to suppress the character that ink-text-input leaks when a Ctrl+key
+  // combo is handled by the top-level useInput handler (e.g. Ctrl+T → 't').
+  const ctrlJustFired = useRef(false);
+
+  // Wrap sendMessage to expand @file references before sending
+  const sendMessageWithFileRefs = useCallback(
+    (content: string) => {
+      if (!hasFileRefs(content)) {
+        socket.sendMessage(content);
+        return;
+      }
+      void expandFileRefs(content)
+        .then(({ expandedMessage, filesAttached, errors }) => {
+          for (const err of errors) {
+            socket.addSystemMessage(err);
+          }
+          if (filesAttached.length > 0) {
+            socket.addSystemMessage(
+              `📎 Attached ${filesAttached.length} file(s): ${filesAttached.join(', ')}`,
+            );
+          }
+          socket.sendMessage(expandedMessage);
+        })
+        .catch((err: unknown) => {
+          socket.addSystemMessage(
+            `File expansion failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          // Send original message without expansion
+          socket.sendMessage(content);
+        });
+    },
+    [socket],
+  );
+
+  const handleLocalCommand = useCallback(
+    (parsed: ParsedCommand) => {
+      switch (parsed.command) {
+        case 'help':
+        case 'h': {
+          const result = executeHelp(parsed);
+          socket.addSystemMessage(result);
+          break;
+        }
+        case 'status':
+        case 's': {
+          const result = executeStatus(parsed, {
+            connected: socket.connected,
+            model: socket.modelName,
+            provider: socket.providerName,
+            sessionId: socket.conversationId ?? null,
+            tokenCount: socket.tokenUsage.total,
+          });
+          socket.addSystemMessage(result);
+          break;
+        }
+        case 'clear':
+          socket.clearMessages();
+          break;
+        case 'new':
+        case 'n':
+          void conversations
+            .createConversation()
+            .then((conv) => {
+              if (conv) {
+                socket.switchConversation(conv.id);
+                appMode.setMode('chat');
+              }
+            })
+            .catch(() => {
+              socket.addSystemMessage('Failed to create new conversation.');
+            });
+          break;
+        case 'attach': {
+          if (!parsed.args) {
+            socket.addSystemMessage('Usage: /attach <file-path>');
+            break;
+          }
+          void handleAttachCommand(parsed.args)
+            .then(({ content, error }) => {
+              if (error) {
+                socket.addSystemMessage(`Attach error: ${error}`);
+              } else if (content) {
+                // Send the file content as a user message
+                socket.sendMessage(content);
+              }
+            })
+            .catch((err: unknown) => {
+              socket.addSystemMessage(
+                `Attach failed: ${err instanceof Error ? err.message : String(err)}`,
+              );
+            });
+          break;
+        }
+        case 'stop':
+          if (socket.isStreaming && socket.socketRef.current?.connected && socket.conversationId) {
+            socket.socketRef.current.emit('abort', {
+              conversationId: socket.conversationId,
+            });
+            socket.addSystemMessage('Abort signal sent.');
+          } else {
+            socket.addSystemMessage('No active stream to stop.');
+          }
+          break;
+        case 'cost': {
+          const u = socket.tokenUsage;
+          socket.addSystemMessage(
+            `Tokens — input: ${u.input}, output: ${u.output}, total: ${u.total}\nCost: $${u.cost.toFixed(6)}`,
+          );
+          break;
+        }
+        case 'history':
+        case 'hist': {
+          void executeHistory({
+            conversationId: socket.conversationId,
+            gatewayUrl,
+            sessionCookie,
+            fetchMessages: fetchConversationMessages,
+          })
+            .then((result) => {
+              socket.addSystemMessage(result);
+            })
+            .catch((err: unknown) => {
+              const msg = err instanceof Error ? err.message : String(err);
+              socket.addSystemMessage(`Failed to fetch history: ${msg}`);
+            });
+          break;
+        }
+        default:
+          socket.addSystemMessage(`Local command not implemented: /${parsed.command}`);
+      }
+    },
+    [socket],
+  );
+
+  const handleGatewayCommand = useCallback(
+    (parsed: ParsedCommand) => {
+      if (!socket.socketRef.current?.connected) {
+        socket.addSystemMessage('Not connected to gateway. Command cannot be executed.');
+        return;
+      }
+      socket.socketRef.current.emit('command:execute', {
+        conversationId: socket.conversationId ?? '',
+        command: parsed.command,
+        args: parsed.args ?? undefined,
+      });
+    },
+    [socket],
+  );
+
+  const handleSwitchConversation = useCallback(
+    (id: string) => {
+      socket.switchConversation(id);
+      appMode.setMode('chat');
+    },
+    [socket, appMode],
+  );
+
+  const handleDeleteConversation = useCallback(
+    (id: string) => {
+      void conversations
+        .deleteConversation(id)
+        .then((ok) => {
+          if (ok && id === socket.conversationId) {
+            socket.clearMessages();
+          }
+        })
+        .catch(() => {});
+    },
+    [conversations, socket],
+  );
+
+  useInput((ch, key) => {
+    // Ctrl+C: clear input → show hint → second empty press exits
+    if (key.ctrl && ch === 'c') {
+      if (tuiInput) {
+        setTuiInput('');
+        ctrlCPendingExit.current = false;
+      } else if (ctrlCPendingExit.current) {
+        exit();
+      } else {
+        ctrlCPendingExit.current = true;
+        socket.addSystemMessage('Press Ctrl+C again to exit.');
+      }
+      return;
+    }
+    // Any other key resets the pending-exit flag
+    ctrlCPendingExit.current = false;
+    // Ctrl+L: toggle sidebar (refresh on open)
+    if (key.ctrl && ch === 'l') {
+      ctrlJustFired.current = true;
+      queueMicrotask(() => {
+        ctrlJustFired.current = false;
+      });
+      const willOpen = !appMode.sidebarOpen;
+      appMode.toggleSidebar();
+      if (willOpen) {
+        void conversations.refresh();
+      }
+      return;
+    }
+    // Ctrl+N: create new conversation and switch to it
+    if (key.ctrl && ch === 'n') {
+      ctrlJustFired.current = true;
+      queueMicrotask(() => {
+        ctrlJustFired.current = false;
+      });
+      void conversations
+        .createConversation()
+        .then((conv) => {
+          if (conv) {
+            socket.switchConversation(conv.id);
+            appMode.setMode('chat');
+          }
+        })
+        .catch(() => {});
+      return;
+    }
+    // Ctrl+K: toggle search mode
+    if (key.ctrl && ch === 'k') {
+      ctrlJustFired.current = true;
+      queueMicrotask(() => {
+        ctrlJustFired.current = false;
+      });
+      if (appMode.mode === 'search') {
+        search.clear();
+        appMode.setMode('chat');
+      } else {
+        appMode.setMode('search');
+      }
+      return;
+    }
+    // Page Up / Page Down: scroll message history (only in chat mode)
+    if (appMode.mode === 'chat') {
+      if (key.pageUp) {
+        viewport.scrollBy(-viewport.viewportSize);
+      }
+      if (key.pageDown) {
+        viewport.scrollBy(viewport.viewportSize);
+      }
+    }
+    // Ctrl+T: cycle thinking level
+    if (key.ctrl && ch === 't') {
+      ctrlJustFired.current = true;
+      queueMicrotask(() => {
+        ctrlJustFired.current = false;
+      });
+      const levels = socket.availableThinkingLevels;
+      if (levels.length > 0) {
+        const currentIdx = levels.indexOf(socket.thinkingLevel);
+        const nextIdx = (currentIdx + 1) % levels.length;
+        const next = levels[nextIdx];
+        if (next) {
+          socket.setThinkingLevel(next);
+        }
+      }
+      return;
+    }
+    // Escape: return to chat from sidebar/search; in chat, scroll to bottom
+    if (key.escape) {
+      if (appMode.mode === 'search') {
+        search.clear();
+        appMode.setMode('chat');
+      } else if (appMode.mode === 'sidebar') {
+        appMode.setMode('chat');
+      } else if (appMode.mode === 'chat') {
+        viewport.scrollToBottom();
+      }
+    }
+  });
+
+  const inputPlaceholder =
+    appMode.mode === 'sidebar'
+      ? 'focus is on sidebar… press Esc to return'
+      : appMode.mode === 'search'
+        ? 'search mode… press Esc to return'
+        : undefined;
+
+  const isSearchMode = appMode.mode === 'search';
+
+  const messageArea = (
+    <Box flexDirection="column" flexGrow={1}>
+      <MessageList
+        messages={socket.messages}
+        isStreaming={socket.isStreaming}
+        currentStreamText={socket.currentStreamText}
+        currentThinkingText={socket.currentThinkingText}
+        activeToolCalls={socket.activeToolCalls}
+        scrollOffset={viewport.scrollOffset}
+        viewportSize={viewport.viewportSize}
+        isScrolledUp={viewport.isScrolledUp}
+        highlightedMessageIndices={highlightedMessageIndices}
+        currentHighlightIndex={currentHighlightIndex}
+      />
+
+      {isSearchMode && (
+        <SearchBar
+          query={search.query}
+          onQueryChange={search.setQuery}
+          totalMatches={search.totalMatches}
+          currentMatch={search.currentMatchIndex}
+          onNext={search.nextMatch}
+          onPrev={search.prevMatch}
+          onClose={() => {
+            search.clear();
+            appMode.setMode('chat');
+          }}
+          focused={isSearchMode}
+        />
+      )}
+
+      <InputBar
+        value={tuiInput}
+        onChange={(val: string) => {
+          // Suppress the character that ink-text-input leaks when a Ctrl+key
+          // combo fires (e.g. Ctrl+T inserts 't'). The ctrlJustFired ref is
+          // set synchronously in the useInput handler and cleared via a
+          // microtask, so this callback sees it as still true on the same
+          // event-loop tick.
+          if (ctrlJustFired.current) {
+            ctrlJustFired.current = false;
+            return;
+          }
+          setTuiInput(val);
+        }}
+        onSubmit={sendMessageWithFileRefs}
+        onSystemMessage={socket.addSystemMessage}
+        onLocalCommand={handleLocalCommand}
+        onGatewayCommand={handleGatewayCommand}
+        isStreaming={socket.isStreaming}
+        connected={socket.connected}
+        focused={appMode.mode === 'chat'}
+        placeholder={inputPlaceholder}
+        allCommands={commandRegistry.getAll()}
+      />
+    </Box>
+  );
+
+  return (
+    <Box flexDirection="column" height="100%">
+      <Box marginTop={1} />
+      <TopBar
+        gatewayUrl={gatewayUrl}
+        version={version}
+        modelName={socket.modelName}
+        thinkingLevel={socket.thinkingLevel}
+        contextWindow={socket.tokenUsage.contextWindow}
+        agentName={agentName ?? 'default'}
+        connected={socket.connected}
+        connecting={socket.connecting}
+      />
+
+      {appMode.sidebarOpen ? (
+        <Box flexDirection="row" flexGrow={1}>
+          <Sidebar
+            conversations={conversations.conversations}
+            activeConversationId={socket.conversationId}
+            selectedIndex={sidebarSelectedIndex}
+            onSelectIndex={setSidebarSelectedIndex}
+            onSwitchConversation={handleSwitchConversation}
+            onDeleteConversation={handleDeleteConversation}
+            loading={conversations.loading}
+            focused={appMode.mode === 'sidebar'}
+            width={30}
+          />
+          {messageArea}
+        </Box>
+      ) : (
+        <Box flexGrow={1}>{messageArea}</Box>
+      )}
+
+      <BottomBar
+        gitInfo={gitInfo}
+        tokenUsage={socket.tokenUsage}
+        connected={socket.connected}
+        connecting={socket.connecting}
+        modelName={socket.modelName}
+        providerName={socket.providerName}
+        thinkingLevel={socket.thinkingLevel}
+        conversationId={socket.conversationId}
+        routingDecision={socket.routingDecision}
+      />
+    </Box>
+  );
+}

packages/mosaic/src/tui/commands/commands.integration.spec.ts

@@ -0,0 +1,348 @@
+/**
+ * Integration tests for TUI command parsing + registry (P8-019)
+ *
+ * Covers:
+ * - parseSlashCommand() + commandRegistry.find() round-trip for all aliases
+ * - /help, /stop, /cost, /status resolve to 'local' execution
+ * - Unknown commands return null from find()
+ * - Alias resolution: /h → help, /m → model, /n → new, etc.
+ * - filterCommands prefix filtering
+ */
+import { describe, it, expect, beforeEach } from 'vitest';
+import { parseSlashCommand } from './parse.js';
+import { CommandRegistry } from './registry.js';
+import type { CommandDef } from '@mosaic/types';
+
+// ─── Parse + Registry Round-trip ─────────────────────────────────────────────
+
+describe('parseSlashCommand + CommandRegistry — integration', () => {
+  let registry: CommandRegistry;
+
+  // Gateway-style commands to simulate a live manifest
+  const gatewayCommands: CommandDef[] = [
+    {
+      name: 'model',
+      description: 'Switch the active model',
+      aliases: ['m'],
+      args: [{ name: 'model-name', type: 'string', optional: false, description: 'Model name' }],
+      scope: 'core',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'thinking',
+      description: 'Set thinking level',
+      aliases: ['t'],
+      args: [
+        {
+          name: 'level',
+          type: 'enum',
+          optional: false,
+          values: ['none', 'low', 'medium', 'high', 'auto'],
+          description: 'Thinking level',
+        },
+      ],
+      scope: 'core',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'new',
+      description: 'Start a new conversation',
+      aliases: ['n'],
+      scope: 'core',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'agent',
+      description: 'Switch or list available agents',
+      aliases: ['a'],
+      args: [{ name: 'args', type: 'string', optional: true, description: 'list or <agent-id>' }],
+      scope: 'agent',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'preferences',
+      description: 'View or set user preferences',
+      aliases: ['pref'],
+      args: [
+        {
+          name: 'action',
+          type: 'enum',
+          optional: true,
+          values: ['show', 'set', 'reset'],
+          description: 'Action',
+        },
+      ],
+      scope: 'core',
+      execution: 'rest',
+      available: true,
+    },
+    {
+      name: 'gc',
+      description: 'Trigger garbage collection sweep',
+      aliases: [],
+      scope: 'core',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'mission',
+      description: 'View or set active mission',
+      aliases: [],
+      args: [{ name: 'args', type: 'string', optional: true, description: 'status | set <id>' }],
+      scope: 'agent',
+      execution: 'socket',
+      available: true,
+    },
+  ];
+
+  beforeEach(() => {
+    registry = new CommandRegistry();
+    registry.updateManifest({ version: 1, commands: gatewayCommands, skills: [] });
+  });
+
+  // ── parseSlashCommand tests ──
+
+  it('returns null for non-slash input', () => {
+    expect(parseSlashCommand('hello world')).toBeNull();
+    expect(parseSlashCommand('')).toBeNull();
+    expect(parseSlashCommand('model')).toBeNull();
+  });
+
+  it('parses "/model claude-3-opus" → command=model args=claude-3-opus', () => {
+    const parsed = parseSlashCommand('/model claude-3-opus');
+    expect(parsed).not.toBeNull();
+    expect(parsed!.command).toBe('model');
+    expect(parsed!.args).toBe('claude-3-opus');
+    expect(parsed!.raw).toBe('/model claude-3-opus');
+  });
+
+  it('parses "/gc" with no args → command=gc args=null', () => {
+    const parsed = parseSlashCommand('/gc');
+    expect(parsed).not.toBeNull();
+    expect(parsed!.command).toBe('gc');
+    expect(parsed!.args).toBeNull();
+  });
+
+  it('parses "/system you are a helpful assistant" → args contains full text', () => {
+    const parsed = parseSlashCommand('/system you are a helpful assistant');
+    expect(parsed!.command).toBe('system');
+    expect(parsed!.args).toBe('you are a helpful assistant');
+  });
+
+  it('parses "/help" → command=help args=null', () => {
+    const parsed = parseSlashCommand('/help');
+    expect(parsed!.command).toBe('help');
+    expect(parsed!.args).toBeNull();
+  });
+
+  // ── Round-trip: parse then find ──
+
+  it('round-trip: /m → resolves to "model" command via alias', () => {
+    const parsed = parseSlashCommand('/m claude-3-haiku');
+    expect(parsed).not.toBeNull();
+    const cmd = registry.find(parsed!.command);
+    expect(cmd).not.toBeNull();
+    // /m → model (alias map in registry)
+    expect(cmd!.name === 'model' || cmd!.aliases.includes('m')).toBe(true);
+  });
+
+  it('round-trip: /h → resolves to "help" (local command)', () => {
+    const parsed = parseSlashCommand('/h');
+    expect(parsed).not.toBeNull();
+    const cmd = registry.find(parsed!.command);
+    expect(cmd).not.toBeNull();
+    expect(cmd!.name === 'help' || cmd!.aliases.includes('h')).toBe(true);
+  });
+
+  it('round-trip: /n → resolves to "new" via gateway manifest', () => {
+    const parsed = parseSlashCommand('/n');
+    expect(parsed).not.toBeNull();
+    const cmd = registry.find(parsed!.command);
+    expect(cmd).not.toBeNull();
+    expect(cmd!.name === 'new' || cmd!.aliases.includes('n')).toBe(true);
+  });
+
+  it('round-trip: /a → resolves to "agent" via gateway manifest', () => {
+    const parsed = parseSlashCommand('/a list');
+    expect(parsed).not.toBeNull();
+    const cmd = registry.find(parsed!.command);
+    expect(cmd).not.toBeNull();
+    expect(cmd!.name === 'agent' || cmd!.aliases.includes('a')).toBe(true);
+  });
+
+  it('round-trip: /pref → resolves to "preferences" via alias', () => {
+    const parsed = parseSlashCommand('/pref show');
+    expect(parsed).not.toBeNull();
+    const cmd = registry.find(parsed!.command);
+    expect(cmd).not.toBeNull();
+    expect(cmd!.name === 'preferences' || cmd!.aliases.includes('pref')).toBe(true);
+  });
+
+  it('round-trip: /t → resolves to "thinking" via alias', () => {
+    const parsed = parseSlashCommand('/t high');
+    expect(parsed).not.toBeNull();
+    const cmd = registry.find(parsed!.command);
+    expect(cmd).not.toBeNull();
+    expect(cmd!.name === 'thinking' || cmd!.aliases.includes('t')).toBe(true);
+  });
+
+  // ── Local commands resolve to 'local' execution ──
+
+  it('/help resolves to local execution', () => {
+    const cmd = registry.find('help');
+    expect(cmd).not.toBeNull();
+    expect(cmd!.execution).toBe('local');
+  });
+
+  it('/stop resolves to local execution', () => {
+    const cmd = registry.find('stop');
+    expect(cmd).not.toBeNull();
+    expect(cmd!.execution).toBe('local');
+  });
+
+  it('/cost resolves to local execution', () => {
+    const cmd = registry.find('cost');
+    expect(cmd).not.toBeNull();
+    expect(cmd!.execution).toBe('local');
+  });
+
+  it('/status resolves to local execution (TUI local override)', () => {
+    const cmd = registry.find('status');
+    expect(cmd).not.toBeNull();
+    // status is 'local' in the TUI registry (local takes precedence over gateway)
+    expect(cmd!.execution).toBe('local');
+  });
+
+  // ── Unknown commands return null ──
+
+  it('find() returns null for unknown command', () => {
+    expect(registry.find('nonexistent')).toBeNull();
+    expect(registry.find('xyz')).toBeNull();
+    expect(registry.find('')).toBeNull();
+  });
+
+  it('find() returns null when no gateway manifest and command not local', () => {
+    const emptyRegistry = new CommandRegistry();
+    expect(emptyRegistry.find('model')).toBeNull();
+    expect(emptyRegistry.find('gc')).toBeNull();
+  });
+
+  // ── getAll returns combined local + gateway ──
+
+  it('getAll() includes both local and gateway commands', () => {
+    const all = registry.getAll();
+    const names = all.map((c) => c.name);
+    // Local commands
+    expect(names).toContain('help');
+    expect(names).toContain('stop');
+    expect(names).toContain('cost');
+    expect(names).toContain('status');
+    // Gateway commands
+    expect(names).toContain('model');
+    expect(names).toContain('gc');
+  });
+
+  it('getLocalCommands() returns only local commands', () => {
+    const local = registry.getLocalCommands();
+    expect(local.every((c) => c.execution === 'local')).toBe(true);
+    expect(local.some((c) => c.name === 'help')).toBe(true);
+    expect(local.some((c) => c.name === 'stop')).toBe(true);
+  });
+});
+
+// ─── filterCommands (autocomplete) ────────────────────────────────────────────
+
+describe('filterCommands (from CommandAutocomplete)', () => {
+  // Import inline since filterCommands is not exported — replicate the logic here
+  function filterCommands(commands: CommandDef[], query: string): CommandDef[] {
+    if (!query) return commands;
+    const q = query.toLowerCase();
+    return commands.filter(
+      (c) =>
+        c.name.includes(q) ||
+        c.aliases.some((a) => a.includes(q)) ||
+        c.description.toLowerCase().includes(q),
+    );
+  }
+
+  const commands: CommandDef[] = [
+    {
+      name: 'model',
+      description: 'Switch the active model',
+      aliases: ['m'],
+      scope: 'core',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'mission',
+      description: 'View or set active mission',
+      aliases: [],
+      scope: 'agent',
+      execution: 'socket',
+      available: true,
+    },
+    {
+      name: 'help',
+      description: 'Show available commands',
+      aliases: ['h'],
+      scope: 'core',
+      execution: 'local',
+      available: true,
+    },
+    {
+      name: 'gc',
+      description: 'Trigger garbage collection sweep',
+      aliases: [],
+      scope: 'core',
+      execution: 'socket',
+      available: true,
+    },
+  ];
+
+  it('returns all commands when query is empty', () => {
+    expect(filterCommands(commands, '')).toHaveLength(commands.length);
+  });
+
+  it('filters by name prefix "mi" → mission only (not model, as "mi" not in model name or aliases)', () => {
+    const result = filterCommands(commands, 'mi');
+    const names = result.map((c) => c.name);
+    expect(names).toContain('mission');
+    expect(names).not.toContain('gc');
+  });
+
+  it('filters by name prefix "mo" → model only', () => {
+    const result = filterCommands(commands, 'mo');
+    const names = result.map((c) => c.name);
+    expect(names).toContain('model');
+    expect(names).not.toContain('mission');
+    expect(names).not.toContain('gc');
+  });
+
+  it('filters by exact name "gc" → gc only', () => {
+    const result = filterCommands(commands, 'gc');
+    expect(result).toHaveLength(1);
+    expect(result[0]!.name).toBe('gc');
+  });
+
+  it('filters by alias "h" → help', () => {
+    const result = filterCommands(commands, 'h');
+    const names = result.map((c) => c.name);
+    expect(names).toContain('help');
+  });
+
+  it('filters by description keyword "switch" → model', () => {
+    const result = filterCommands(commands, 'switch');
+    const names = result.map((c) => c.name);
+    expect(names).toContain('model');
+  });
+
+  it('returns empty array when no commands match', () => {
+    const result = filterCommands(commands, 'zzznotfound');
+    expect(result).toHaveLength(0);
+  });
+});

packages/mosaic/src/tui/commands/index.ts

@@ -0,0 +1,7 @@
+export { parseSlashCommand } from './parse.js';
+export { commandRegistry, CommandRegistry } from './registry.js';
+export { executeHelp } from './local/help.js';
+export { executeStatus } from './local/status.js';
+export type { StatusContext } from './local/status.js';
+export { executeHistory } from './local/history.js';
+export type { HistoryContext } from './local/history.js';

packages/mosaic/src/tui/commands/local/help.ts

@@ -0,0 +1,19 @@
+import type { ParsedCommand } from '@mosaic/types';
+import { commandRegistry } from '../registry.js';
+
+export function executeHelp(_parsed: ParsedCommand): string {
+  const commands = commandRegistry.getAll();
+  const lines = ['Available commands:', ''];
+
+  for (const cmd of commands) {
+    const aliases =
+      cmd.aliases.length > 0 ? ` (${cmd.aliases.map((a) => `/${a}`).join(', ')})` : '';
+    const argsStr =
+      cmd.args && cmd.args.length > 0
+        ? ' ' + cmd.args.map((a) => (a.optional ? `[${a.name}]` : `<${a.name}>`)).join(' ')
+        : '';
+    lines.push(`  /${cmd.name}${argsStr}${aliases} — ${cmd.description}`);
+  }
+
+  return lines.join('\n').trimEnd();
+}

packages/mosaic/src/tui/commands/local/history.ts

@@ -0,0 +1,53 @@
+import type { ConversationMessage } from '../../gateway-api.js';
+
+const CONTEXT_WINDOW = 200_000;
+const CHARS_PER_TOKEN = 4;
+
+function estimateTokens(messages: ConversationMessage[]): number {
+  const totalChars = messages.reduce((sum, m) => sum + (m.content?.length ?? 0), 0);
+  return Math.round(totalChars / CHARS_PER_TOKEN);
+}
+
+export interface HistoryContext {
+  conversationId: string | undefined;
+  conversationTitle?: string | null;
+  gatewayUrl: string;
+  sessionCookie: string | undefined;
+  fetchMessages: (
+    gatewayUrl: string,
+    sessionCookie: string,
+    conversationId: string,
+  ) => Promise<ConversationMessage[]>;
+}
+
+export async function executeHistory(ctx: HistoryContext): Promise<string> {
+  const { conversationId, conversationTitle, gatewayUrl, sessionCookie, fetchMessages } = ctx;
+
+  if (!conversationId) {
+    return 'No active conversation.';
+  }
+
+  if (!sessionCookie) {
+    return 'Not authenticated — cannot fetch conversation messages.';
+  }
+
+  const messages = await fetchMessages(gatewayUrl, sessionCookie, conversationId);
+
+  const userMessages = messages.filter((m) => m.role === 'user').length;
+  const assistantMessages = messages.filter((m) => m.role === 'assistant').length;
+  const totalMessages = messages.length;
+
+  const estimatedTokens = estimateTokens(messages);
+  const contextPercent = Math.round((estimatedTokens / CONTEXT_WINDOW) * 100);
+
+  const label = conversationTitle ?? conversationId;
+
+  const lines = [
+    `Conversation: ${label}`,
+    `Messages: ${totalMessages} (${userMessages} user, ${assistantMessages} assistant)`,
+    `Estimated tokens: ~${estimatedTokens.toLocaleString()}`,
+    `Context usage: ~${contextPercent}% of ${(CONTEXT_WINDOW / 1000).toFixed(0)}K`,
+  ];
+
+  return lines.join('\n');
+}

packages/mosaic/src/tui/commands/local/status.ts

@@ -0,0 +1,20 @@
+import type { ParsedCommand } from '@mosaic/types';
+
+export interface StatusContext {
+  connected: boolean;
+  model: string | null;
+  provider: string | null;
+  sessionId: string | null;
+  tokenCount: number;
+}
+
+export function executeStatus(_parsed: ParsedCommand, ctx: StatusContext): string {
+  const lines = [
+    `Connection: ${ctx.connected ? 'connected' : 'disconnected'}`,
+    `Model: ${ctx.model ?? 'unknown'}`,
+    `Provider: ${ctx.provider ?? 'unknown'}`,
+    `Session: ${ctx.sessionId ?? 'none'}`,
+    `Tokens (session): ${ctx.tokenCount}`,
+  ];
+  return lines.join('\n');
+}

packages/mosaic/src/tui/commands/parse.ts

@@ -0,0 +1,11 @@
+import type { ParsedCommand } from '@mosaic/types';
+
+export function parseSlashCommand(input: string): ParsedCommand | null {
+  const match = input.match(/^\/([a-z][a-z0-9:_-]*)\s*(.*)?$/i);
+  if (!match) return null;
+  return {
+    command: match[1]!,
+    args: match[2]?.trim() || null,
+    raw: input,
+  };
+}

packages/mosaic/src/tui/commands/registry.ts

@@ -0,0 +1,137 @@
+import type { CommandDef, CommandManifest } from '@mosaic/types';
+
+// Local-only commands (work even when gateway is disconnected)
+const LOCAL_COMMANDS: CommandDef[] = [
+  {
+    name: 'help',
+    description: 'Show available commands',
+    aliases: ['h'],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'stop',
+    description: 'Cancel current streaming response',
+    aliases: [],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'cost',
+    description: 'Show token usage and cost for current session',
+    aliases: [],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'status',
+    description: 'Show connection and session status',
+    aliases: ['s'],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'history',
+    description: 'Show conversation message count and context usage',
+    aliases: ['hist'],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'clear',
+    description: 'Clear the current conversation display',
+    aliases: [],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'attach',
+    description: 'Attach a file to the next message (@file syntax also works inline)',
+    aliases: [],
+    args: [
+      {
+        name: 'path',
+        type: 'string' as const,
+        optional: false,
+        description: 'File path to attach',
+      },
+    ],
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+  {
+    name: 'new',
+    description: 'Start a new conversation',
+    aliases: ['n'],
+    args: undefined,
+    execution: 'local',
+    available: true,
+    scope: 'core',
+  },
+];
+
+const ALIASES: Record<string, string> = {
+  m: 'model',
+  t: 'thinking',
+  a: 'agent',
+  s: 'status',
+  h: 'help',
+  hist: 'history',
+  pref: 'preferences',
+};
+
+export class CommandRegistry {
+  private gatewayManifest: CommandManifest | null = null;
+
+  updateManifest(manifest: CommandManifest): void {
+    this.gatewayManifest = manifest;
+  }
+
+  resolveAlias(command: string): string {
+    return ALIASES[command] ?? command;
+  }
+
+  find(command: string): CommandDef | null {
+    const resolved = this.resolveAlias(command);
+    // Search local first, then gateway manifest
+    const local = LOCAL_COMMANDS.find((c) => c.name === resolved || c.aliases.includes(resolved));
+    if (local) return local;
+    if (this.gatewayManifest) {
+      return (
+        this.gatewayManifest.commands.find(
+          (c) => c.name === resolved || c.aliases.includes(resolved),
+        ) ?? null
+      );
+    }
+    return null;
+  }
+
+  getAll(): CommandDef[] {
+    const gateway = this.gatewayManifest?.commands ?? [];
+    // Local commands take precedence; deduplicate gateway commands that share
+    // a name with a local command to avoid duplicate React keys and confusing
+    // autocomplete entries.
+    const localNames = new Set(LOCAL_COMMANDS.map((c) => c.name));
+    const dedupedGateway = gateway.filter((c) => !localNames.has(c.name));
+    return [...LOCAL_COMMANDS, ...dedupedGateway];
+  }
+
+  getLocalCommands(): CommandDef[] {
+    return LOCAL_COMMANDS;
+  }
+}
+
+export const commandRegistry = new CommandRegistry();

packages/mosaic/src/tui/components/bottom-bar.tsx

@@ -0,0 +1,138 @@
+import React from 'react';
+import { Box, Text } from 'ink';
+import type { RoutingDecisionInfo } from '@mosaic/types';
+import type { TokenUsage } from '../hooks/use-socket.js';
+import type { GitInfo } from '../hooks/use-git-info.js';
+
+export interface BottomBarProps {
+  gitInfo: GitInfo;
+  tokenUsage: TokenUsage;
+  connected: boolean;
+  connecting: boolean;
+  modelName: string | null;
+  providerName: string | null;
+  thinkingLevel: string;
+  conversationId: string | undefined;
+  /** Routing decision info for transparency display (M4-008) */
+  routingDecision?: RoutingDecisionInfo | null;
+}
+
+function formatTokens(n: number): string {
+  if (n >= 1_000_000) return `${(n / 1_000_000).toFixed(1)}M`;
+  if (n >= 1_000) return `${(n / 1_000).toFixed(0)}k`;
+  return String(n);
+}
+
+/** Compact the cwd — replace home with ~ */
+function compactCwd(cwd: string): string {
+  const home = process.env['HOME'] ?? '';
+  if (home && cwd.startsWith(home)) {
+    return '~' + cwd.slice(home.length);
+  }
+  return cwd;
+}
+
+export function BottomBar({
+  gitInfo,
+  tokenUsage,
+  connected,
+  connecting,
+  modelName,
+  providerName,
+  thinkingLevel,
+  conversationId,
+  routingDecision,
+}: BottomBarProps) {
+  const gatewayStatus = connected ? 'Connected' : connecting ? 'Connecting…' : 'Disconnected';
+  const gatewayColor = connected ? 'green' : connecting ? 'yellow' : 'red';
+
+  const hasTokens = tokenUsage.total > 0;
+
+  return (
+    <Box flexDirection="column" paddingX={0} marginTop={0}>
+      {/* Line 0: keybinding hints */}
+      <Box>
+        <Text dimColor>^L sidebar · ^N new · ^K search · ^T thinking · PgUp/Dn scroll</Text>
+      </Box>
+
+      {/* Line 1: blank  ·····  Gateway: Status */}
+      <Box justifyContent="space-between">
+        <Box />
+        <Box>
+          <Text dimColor>Gateway: </Text>
+          <Text color={gatewayColor}>{gatewayStatus}</Text>
+        </Box>
+      </Box>
+
+      {/* Line 2: cwd (branch)  ·····  Session: id */}
+      <Box justifyContent="space-between">
+        <Box>
+          <Text dimColor>{compactCwd(gitInfo.cwd)}</Text>
+          {gitInfo.branch && <Text dimColor> ({gitInfo.branch})</Text>}
+        </Box>
+        <Box>
+          <Text dimColor>
+            {conversationId ? `Session: ${conversationId.slice(0, 8)}` : 'No session'}
+          </Text>
+        </Box>
+      </Box>
+
+      {/* Line 3: token stats  ·····  (provider) model */}
+      <Box justifyContent="space-between" minHeight={1}>
+        <Box>
+          {hasTokens ? (
+            <>
+              <Text dimColor>↑{formatTokens(tokenUsage.input)}</Text>
+              <Text dimColor>{'  '}</Text>
+              <Text dimColor>↓{formatTokens(tokenUsage.output)}</Text>
+              {tokenUsage.cacheRead > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>R{formatTokens(tokenUsage.cacheRead)}</Text>
+                </>
+              )}
+              {tokenUsage.cacheWrite > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>W{formatTokens(tokenUsage.cacheWrite)}</Text>
+                </>
+              )}
+              {tokenUsage.cost > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>${tokenUsage.cost.toFixed(3)}</Text>
+                </>
+              )}
+              {tokenUsage.contextPercent > 0 && (
+                <>
+                  <Text dimColor>{'  '}</Text>
+                  <Text dimColor>
+                    {tokenUsage.contextPercent.toFixed(1)}%/{formatTokens(tokenUsage.contextWindow)}
+                  </Text>
+                </>
+              )}
+            </>
+          ) : (
+            <Text dimColor>↑0 ↓0 $0.000</Text>
+          )}
+        </Box>
+        <Box>
+          <Text dimColor>
+            {providerName ? `(${providerName}) ` : ''}
+            {modelName ?? 'awaiting model'}
+            {thinkingLevel !== 'off' ? ` • ${thinkingLevel}` : ''}
+          </Text>
+        </Box>
+      </Box>
+
+      {/* Line 4: routing transparency (M4-008) — only shown when a routing decision is available */}
+      {routingDecision && (
+        <Box>
+          <Text dimColor>
+            Routed: {routingDecision.model} ({routingDecision.reason})
+          </Text>
+        </Box>
+      )}
+    </Box>
+  );
+}