feat(mosaic): add auth command and stage parallel agent changes

Picks up auth command and spec written by parallel agent, and updated mosaic cli.ts wiring from parallel development during cli-unification. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
feat(forge): add registerForgeCommand for mosaic forge CLI surface
2026-04-05 00:58:03 -05:00 · 2026-04-05 00:58:03 -05:00 · 2026-04-05 05:57:22 +00:00 · 2026-04-05 05:48:13 +00:00 · 2026-04-05 05:44:06 +00:00 · 2026-04-05 05:43:49 +00:00
265 changed files with 7217 additions and 2447 deletions
--- a/.env.example
+++ b/.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) ───────────────────────────────
--- a/.npmrc
+++ b/.npmrc
@@ -1 +1 @@
-@mosaic:registry=https://git.mosaicstack.dev/api/packages/mosaic/npm/
+@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/
--- a/.woodpecker/ci.yml
+++ b/.woodpecker/ci.yml
@@ -59,7 +59,7 @@ steps:
          sleep 1
        done
      # Run migrations (DATABASE_URL is set in environment above)
-      - pnpm --filter @mosaic/db run db:migrate
+      - pnpm --filter @mosaicstack/db run db:migrate
      # Run all tests
      - pnpm test
    depends_on:
--- a/.woodpecker/publish.yml
+++ b/.woodpecker/publish.yml
@@ -33,32 +33,61 @@ steps:
      - *enable_pnpm
      # Configure auth for Gitea npm registry
      - |
-        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 non-private packages to Gitea (--no-git-checks skips dirty/branch checks in CI)
-      # --filter excludes gateway (published to npmjs instead) and 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"
+        echo "//git.mosaicstack.dev/api/packages/mosaicstack/npm/:_authToken=$NPM_TOKEN" > ~/.npmrc
+        echo "@mosaicstack:registry=https://git.mosaicstack.dev/api/packages/mosaicstack/npm/" >> ~/.npmrc
+      # Publish non-private packages to Gitea.
+      #
+      # The only publish failure we tolerate is "version already exists" —
+      # that legitimately happens when only some packages were bumped in
+      # the merge. Any other failure (registry 404, auth error, network
+      # error) MUST fail the pipeline loudly: the previous
+      # `|| echo "... continuing"` fallback silently hid a 404 from the
+      # Gitea org rename and caused every @mosaicstack/* publish to fall
+      # on the floor while CI still reported green.
+      - |
+        # Portable sh (Alpine ash) — avoid bashisms like PIPESTATUS.
+        set +e
+        pnpm --filter "@mosaicstack/*" --filter "!@mosaicstack/web" publish --no-git-checks --access public >/tmp/publish.log 2>&1
+        EXIT=$?
+        set -e
+        cat /tmp/publish.log
+        if [ "$EXIT" -eq 0 ]; then
+          echo "[publish] all packages published successfully"
+          exit 0
+        fi
+        # Hard registry / auth / network errors → fatal. Match npm's own
+        # error lines specifically to avoid false positives on arbitrary
+        # log text that happens to contain "E404" etc.
+        if grep -qE "npm (error|ERR!) code (E404|E401|ENEEDAUTH|ECONNREFUSED|ETIMEDOUT|ENOTFOUND)" /tmp/publish.log; then
+          echo "[publish] FATAL: registry/auth/network error detected — failing pipeline" >&2
+          exit 1
+        fi
+        # Only tolerate the explicit "version already published" case.
+        # npm returns this as E403 with body "You cannot publish over..."
+        # or EPUBLISHCONFLICT depending on version.
+        if grep -qE "EPUBLISHCONFLICT|You cannot publish over|previously published" /tmp/publish.log; then
+          echo "[publish] some packages already at this version — continuing (non-fatal)"
+          exit 0
+        fi
+        echo "[publish] FATAL: publish failed with unrecognized error — failing pipeline" >&2
+        exit 1
    depends_on:
      - build

-  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]
+  # 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
@@ -74,12 +103,12 @@ steps:
      - mkdir -p /kaniko/.docker
      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
      - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaic/mosaic-stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/mosaic-stack/gateway:sha-${CI_COMMIT_SHA:0:7}"
        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/gateway:latest"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/gateway:latest"
        fi
        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/gateway:$CI_COMMIT_TAG"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/gateway:$CI_COMMIT_TAG"
        fi
        /kaniko/executor --context . --dockerfile docker/gateway.Dockerfile $DESTINATIONS
    depends_on:
@@ -99,12 +128,12 @@ steps:
      - mkdir -p /kaniko/.docker
      - echo "{\"auths\":{\"git.mosaicstack.dev\":{\"username\":\"$REGISTRY_USER\",\"password\":\"$REGISTRY_PASS\"}}}" > /kaniko/.docker/config.json
      - |
-        DESTINATIONS="--destination git.mosaicstack.dev/mosaic/mosaic-stack/web:sha-${CI_COMMIT_SHA:0:7}"
+        DESTINATIONS="--destination git.mosaicstack.dev/mosaicstack/mosaic-stack/web:sha-${CI_COMMIT_SHA:0:7}"
        if [ "$CI_COMMIT_BRANCH" = "main" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/web:latest"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/web:latest"
        fi
        if [ -n "$CI_COMMIT_TAG" ]; then
-          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaic/mosaic-stack/web:$CI_COMMIT_TAG"
+          DESTINATIONS="$DESTINATIONS --destination git.mosaicstack.dev/mosaicstack/mosaic-stack/web:$CI_COMMIT_TAG"
        fi
        /kaniko/executor --context . --dockerfile docker/web.Dockerfile $DESTINATIONS
    depends_on:
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,11 +21,11 @@ Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo
 | `apps/web`         | Next.js dashboard               | React 19, Tailwind               |
 | `packages/types`   | Shared TypeScript contracts     | class-validator                  |
 | `packages/db`      | Drizzle ORM schema + migrations | drizzle-orm, postgres            |
-| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaic/db          |
-| `packages/brain`   | Data layer (PG-backed)          | @mosaic/db                       |
+| `packages/auth`    | BetterAuth configuration        | better-auth, @mosaicstack/db     |
+| `packages/brain`   | Data layer (PG-backed)          | @mosaicstack/db                  |
 | `packages/queue`   | Valkey task queue + MCP         | ioredis                          |
-| `packages/coord`   | Mission coordination            | @mosaic/queue                    |
-| `packages/cli`     | Unified CLI + Pi TUI            | Ink, Pi SDK                      |
+| `packages/coord`   | Mission coordination            | @mosaicstack/queue               |
+| `packages/mosaic`  | Unified `mosaic` CLI + TUI      | Ink, Pi SDK, commander           |
 | `plugins/discord`  | Discord channel plugin          | discord.js                       |
 | `plugins/telegram` | Telegram channel plugin         | Telegraf                         |

@@ -33,9 +33,9 @@ Mosaic Stack is a self-hosted, multi-user AI agent platform. TypeScript monorepo

 1. Gateway is the single API surface — all clients connect through it
 2. Pi SDK is ESM-only — gateway and CLI must use ESM
-3. Socket.IO typed events defined in `@mosaic/types` enforce compile-time contracts
+3. Socket.IO typed events defined in `@mosaicstack/types` enforce compile-time contracts
 4. OTEL auto-instrumentation loads before NestJS bootstrap
-5. BetterAuth manages auth tables; schema defined in `@mosaic/db`
+5. BetterAuth manages auth tables; schema defined in `@mosaicstack/db`
 6. Docker Compose provides PG (5433), Valkey (6380), OTEL Collector (4317/4318), Jaeger (16686)
 7. Explicit `@Inject()` decorators required in NestJS (tsx/esbuild doesn't emit decorator metadata)

--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10,7 +10,7 @@ Self-hosted, multi-user AI agent platform. TypeScript monorepo.
 - **Web**: Next.js 16 + React 19 (`apps/web`)
 - **ORM**: Drizzle ORM + PostgreSQL 17 + pgvector (`packages/db`)
 - **Auth**: BetterAuth (`packages/auth`)
- **Agent**: Pi SDK (`packages/agent`, `packages/cli`)
+- **Agent**: Pi SDK (`packages/agent`, `packages/mosaic`)
 - **Queue**: Valkey 8 (`packages/queue`)
 - **Build**: pnpm workspaces + Turborepo
 - **CI**: Woodpecker CI
@@ -26,13 +26,13 @@ pnpm test             # Vitest (all packages)
 pnpm build            # Build all packages

 # Database
-pnpm --filter @mosaic/db db:push      # Push schema to PG (dev)
-pnpm --filter @mosaic/db db:generate  # Generate migrations
-pnpm --filter @mosaic/db db:migrate   # Run migrations
+pnpm --filter @mosaicstack/db db:push      # Push schema to PG (dev)
+pnpm --filter @mosaicstack/db db:generate  # Generate migrations
+pnpm --filter @mosaicstack/db db:migrate   # Run migrations

 # Dev
 docker compose up -d                  # Start PG, Valkey, OTEL, Jaeger
-pnpm --filter @mosaic/gateway exec tsx src/main.ts  # Start gateway
+pnpm --filter @mosaicstack/gateway exec tsx src/main.ts  # Start gateway
 ```

 ## Conventions
--- a/README.md
+++ b/README.md
@@ -13,9 +13,9 @@ bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/mai
 This installs both components:

 | Component               | What                                                             | Where                |
-| --------------- | ----------------------------------------------------- | -------------------- |
+| ----------------------- | ---------------------------------------------------------------- | -------------------- |
 | **Framework**           | Bash launcher, guides, runtime configs, tools, skills            | `~/.config/mosaic/`  |
-| **@mosaic/cli** | TUI, gateway client, wizard, auto-updater             | `~/.npm-global/bin/` |
+| **@mosaicstack/mosaic** | Unified `mosaic` CLI — TUI, gateway client, wizard, auto-updater | `~/.npm-global/bin/` |

 After install, set up your agent identity:

@@ -26,7 +26,7 @@ mosaic init          # Interactive wizard
 ### Requirements

 - Node.js ≥ 20
- npm (for global @mosaic/cli install)
+- npm (for global @mosaicstack/mosaic install)
 - One or more runtimes: [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Codex](https://github.com/openai/codex), [OpenCode](https://opencode.ai), or [Pi](https://github.com/mariozechner/pi-coding-agent)

 ## Usage
@@ -86,7 +86,7 @@ docker compose up -d
 pnpm install

 # Run migrations
-pnpm --filter @mosaic/db run db:migrate
+pnpm --filter @mosaicstack/db run db:migrate

 # Start all services in dev mode
 pnpm dev
@@ -163,7 +163,7 @@ mosaic-stack/

 - **Gateway is the single API surface** — all clients (TUI, web, Discord, Telegram) connect through it
 - **ESM everywhere** — `"type": "module"`, `.js` extensions in imports, NodeNext resolution
- **Socket.IO typed events** — defined in `@mosaic/types`, enforced at compile time
+- **Socket.IO typed events** — defined in `@mosaicstack/types`, enforced at compile time
 - **OTEL auto-instrumentation** — loads before NestJS bootstrap
 - **Explicit `@Inject()` decorators** — required since tsx/esbuild doesn't emit decorator metadata

--- a/apps/gateway/package.json
+++ b/apps/gateway/package.json
@@ -1,6 +1,11 @@
 {
-  "name": "@mosaic/gateway",
-  "version": "0.0.2",
+  "name": "@mosaicstack/gateway",
+  "version": "0.0.6",
+  "repository": {
+    "type": "git",
+    "url": "https://git.mosaicstack.dev/mosaicstack/mosaic-stack.git",
+    "directory": "apps/gateway"
+  },
  "type": "module",
  "main": "dist/main.js",
  "bin": {
@@ -10,7 +15,7 @@
    "dist"
  ],
  "publishConfig": {
-    "registry": "https://registry.npmjs.org/",
+    "registry": "https://git.mosaicstack.dev/api/packages/mosaicstack/npm/",
    "access": "public"
  },
  "scripts": {
@@ -23,28 +28,28 @@
  "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:^",
+    "@mosaicstack/auth": "workspace:^",
+    "@mosaicstack/brain": "workspace:^",
+    "@mosaicstack/config": "workspace:^",
+    "@mosaicstack/coord": "workspace:^",
+    "@mosaicstack/db": "workspace:^",
+    "@mosaicstack/discord-plugin": "workspace:^",
+    "@mosaicstack/log": "workspace:^",
+    "@mosaicstack/memory": "workspace:^",
+    "@mosaicstack/queue": "workspace:^",
+    "@mosaicstack/storage": "workspace:^",
+    "@mosaicstack/telegram-plugin": "workspace:^",
+    "@mosaicstack/types": "workspace:^",
    "@nestjs/common": "^11.0.0",
    "@nestjs/core": "^11.0.0",
    "@nestjs/platform-fastify": "^11.0.0",
    "@nestjs/platform-socket.io": "^11.0.0",
    "@nestjs/throttler": "^6.5.0",
    "@nestjs/websockets": "^11.0.0",
-    "@opentelemetry/auto-instrumentations-node": "^0.71.0",
+    "@opentelemetry/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",
--- a/apps/gateway/src/tests/conversation-persistence.test.ts
+++ b/apps/gateway/src/tests/conversation-persistence.test.ts
@@ -12,7 +12,7 @@ import { BadRequestException, NotFoundException } from '@nestjs/common';
 import { describe, expect, it, vi, beforeEach } from 'vitest';
 import type { ConversationHistoryMessage } from '../agent/agent.service.js';
 import { ConversationsController } from '../conversations/conversations.controller.js';
-import type { Message } from '@mosaic/brain';
+import type { Message } from '@mosaicstack/brain';

 // ---------------------------------------------------------------------------
 // Shared test data
--- a/apps/gateway/src/tests/cross-user-isolation.test.ts
+++ b/apps/gateway/src/tests/cross-user-isolation.test.ts
@@ -18,13 +18,13 @@
 */

 import { afterAll, beforeAll, beforeEach, describe, expect, it } from 'vitest';
-import { createDb } from '@mosaic/db';
-import { createConversationsRepo } from '@mosaic/brain';
-import { createAgentsRepo } from '@mosaic/brain';
-import { createPreferencesRepo, createInsightsRepo } from '@mosaic/memory';
-import { users, conversations, messages, agents, preferences, insights } from '@mosaic/db';
-import { eq } from '@mosaic/db';
-import type { DbHandle } from '@mosaic/db';
+import { createDb } from '@mosaicstack/db';
+import { createConversationsRepo } from '@mosaicstack/brain';
+import { createAgentsRepo } from '@mosaicstack/brain';
+import { createPreferencesRepo, createInsightsRepo } from '@mosaicstack/memory';
+import { users, conversations, messages, agents, preferences, insights } from '@mosaicstack/db';
+import { eq } from '@mosaicstack/db';
+import type { DbHandle } from '@mosaicstack/db';

 // ─── Fixed IDs so the afterAll cleanup is deterministic ──────────────────────

--- a/apps/gateway/src/admin/admin-health.controller.ts
+++ b/apps/gateway/src/admin/admin-health.controller.ts
@@ -1,6 +1,6 @@
 import { Controller, Get, Inject, UseGuards } from '@nestjs/common';
-import { sql, type Db } from '@mosaic/db';
-import { createQueue } from '@mosaic/queue';
+import { sql, type Db } from '@mosaicstack/db';
+import { createQueue } from '@mosaicstack/queue';
 import { DB } from '../database/database.module.js';
 import { AgentService } from '../agent/agent.service.js';
 import { ProviderService } from '../agent/provider.service.js';
--- a/apps/gateway/src/admin/admin-tokens.controller.ts
+++ b/apps/gateway/src/admin/admin-tokens.controller.ts
@@ -11,7 +11,7 @@ import {
  UseGuards,
 } from '@nestjs/common';
 import { randomBytes, createHash } from 'node:crypto';
-import { eq, type Db, adminTokens } from '@mosaic/db';
+import { eq, type Db, adminTokens } from '@mosaicstack/db';
 import { v4 as uuid } from 'uuid';
 import { DB } from '../database/database.module.js';
 import { AdminGuard } from './admin.guard.js';
--- a/apps/gateway/src/admin/admin.controller.ts
+++ b/apps/gateway/src/admin/admin.controller.ts
@@ -13,8 +13,8 @@ import {
  Post,
  UseGuards,
 } from '@nestjs/common';
-import { eq, type Db, users as usersTable } from '@mosaic/db';
-import type { Auth } from '@mosaic/auth';
+import { eq, type Db, users as usersTable } from '@mosaicstack/db';
+import type { Auth } from '@mosaicstack/auth';
 import { AUTH } from '../auth/auth.tokens.js';
 import { DB } from '../database/database.module.js';
 import { AdminGuard } from './admin.guard.js';
--- a/apps/gateway/src/admin/admin.guard.ts
+++ b/apps/gateway/src/admin/admin.guard.ts
@@ -8,9 +8,9 @@ import {
 } 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, adminTokens, users as usersTable } from '@mosaic/db';
+import type { Auth } from '@mosaicstack/auth';
+import type { Db } from '@mosaicstack/db';
+import { eq, adminTokens, users as usersTable } from '@mosaicstack/db';
 import type { FastifyRequest } from 'fastify';
 import { AUTH } from '../auth/auth.tokens.js';
 import { DB } from '../database/database.module.js';
--- a/apps/gateway/src/admin/bootstrap.controller.ts
+++ b/apps/gateway/src/admin/bootstrap.controller.ts
@@ -8,8 +8,8 @@ import {
  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 { count, eq, type Db, users as usersTable, adminTokens } from '@mosaicstack/db';
+import type { Auth } from '@mosaicstack/auth';
 import { v4 as uuid } from 'uuid';
 import { AUTH } from '../auth/auth.tokens.js';
 import { DB } from '../database/database.module.js';
--- a/apps/gateway/src/agent/tests/provider-adapters.test.ts
+++ b/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());
 }

 // ---------------------------------------------------------------------------
--- a/apps/gateway/src/agent/tests/routing.service.test.ts
+++ b/apps/gateway/src/agent/tests/routing.service.test.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach, vi } from 'vitest';
 import { RoutingService } from '../routing.service.js';
-import type { ModelInfo } from '@mosaic/types';
+import type { ModelInfo } from '@mosaicstack/types';

 const mockModels: ModelInfo[] = [
  {
--- a/apps/gateway/src/agent/adapters/anthropic.adapter.ts
+++ b/apps/gateway/src/agent/adapters/anthropic.adapter.ts
@@ -7,7 +7,7 @@ import type {
  IProviderAdapter,
  ModelInfo,
  ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';

 /**
 * Anthropic provider adapter.
--- a/apps/gateway/src/agent/adapters/ollama.adapter.ts
+++ b/apps/gateway/src/agent/adapters/ollama.adapter.ts
@@ -6,7 +6,7 @@ import type {
  IProviderAdapter,
  ModelInfo,
  ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';

 /** Embedding models that Ollama ships with out of the box */
 const OLLAMA_EMBEDDING_MODELS: ReadonlyArray<{
--- a/apps/gateway/src/agent/adapters/openai.adapter.ts
+++ b/apps/gateway/src/agent/adapters/openai.adapter.ts
@@ -7,7 +7,7 @@ import type {
  IProviderAdapter,
  ModelInfo,
  ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';

 /**
 * OpenAI provider adapter.
--- a/apps/gateway/src/agent/adapters/openrouter.adapter.ts
+++ b/apps/gateway/src/agent/adapters/openrouter.adapter.ts
@@ -6,7 +6,7 @@ import type {
  IProviderAdapter,
  ModelInfo,
  ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';

 const OPENROUTER_BASE_URL = 'https://openrouter.ai/api/v1';

--- a/apps/gateway/src/agent/adapters/zai.adapter.ts
+++ b/apps/gateway/src/agent/adapters/zai.adapter.ts
@@ -6,7 +6,7 @@ import type {
  IProviderAdapter,
  ModelInfo,
  ProviderHealth,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 import { getModelCapability } from '../model-capabilities.js';

 /**
--- a/apps/gateway/src/agent/agent-configs.controller.ts
+++ b/apps/gateway/src/agent/agent-configs.controller.ts
@@ -13,7 +13,7 @@ import {
  Post,
  UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
--- a/apps/gateway/src/agent/agent.service.ts
+++ b/apps/gateway/src/agent/agent.service.ts
@@ -7,8 +7,8 @@ import {
  type AgentSessionEvent,
  type ToolDefinition,
 } from '@mariozechner/pi-coding-agent';
-import type { Brain } from '@mosaic/brain';
-import type { Memory } from '@mosaic/memory';
+import type { Brain } from '@mosaicstack/brain';
+import type { Memory } from '@mosaicstack/memory';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { MEMORY } from '../memory/memory.tokens.js';
 import { EmbeddingService } from '../memory/embedding.service.js';
--- a/apps/gateway/src/agent/model-capabilities.ts
+++ b/apps/gateway/src/agent/model-capabilities.ts
@@ -1,4 +1,4 @@
-import type { ModelCapability } from '@mosaic/types';
+import type { ModelCapability } from '@mosaicstack/types';

 /**
 * Comprehensive capability matrix for all target models.
--- a/apps/gateway/src/agent/provider-credentials.service.ts
+++ b/apps/gateway/src/agent/provider-credentials.service.ts
@@ -1,7 +1,7 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
 import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
-import type { Db } from '@mosaic/db';
-import { providerCredentials, eq, and } from '@mosaic/db';
+import type { Db } from '@mosaicstack/db';
+import { providerCredentials, eq, and } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import type { ProviderCredentialSummaryDto } from './provider-credentials.dto.js';

--- a/apps/gateway/src/agent/provider.service.ts
+++ b/apps/gateway/src/agent/provider.service.ts
@@ -14,7 +14,7 @@ import type {
  ModelInfo,
  ProviderHealth,
  ProviderInfo,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 import {
  AnthropicAdapter,
  OllamaAdapter,
@@ -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 = [
--- a/apps/gateway/src/agent/providers.controller.ts
+++ b/apps/gateway/src/agent/providers.controller.ts
@@ -1,5 +1,5 @@
 import { Body, Controller, Delete, Get, Inject, Param, Post, UseGuards } from '@nestjs/common';
-import type { RoutingCriteria } from '@mosaic/types';
+import type { RoutingCriteria } from '@mosaicstack/types';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
 import { ProviderService } from './provider.service.js';
--- a/apps/gateway/src/agent/routing.service.ts
+++ b/apps/gateway/src/agent/routing.service.ts
@@ -1,6 +1,6 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import type { ModelInfo } from '@mosaic/types';
-import type { RoutingCriteria, RoutingResult, CostTier } from '@mosaic/types';
+import type { ModelInfo } from '@mosaicstack/types';
+import type { RoutingCriteria, RoutingResult, CostTier } from '@mosaicstack/types';
 import { ProviderService } from './provider.service.js';

 /** Per-million-token cost thresholds for tier classification */
--- a/apps/gateway/src/agent/routing/default-rules.ts
+++ b/apps/gateway/src/agent/routing/default-rules.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
-import { routingRules, type Db, sql } from '@mosaic/db';
+import { routingRules, type Db, sql } from '@mosaicstack/db';
 import { DB } from '../../database/database.module.js';
 import type { RoutingCondition, RoutingAction } from './routing.types.js';

--- a/apps/gateway/src/agent/routing/routing-engine.service.ts
+++ b/apps/gateway/src/agent/routing/routing-engine.service.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import { routingRules, type Db, and, asc, eq, or } from '@mosaic/db';
+import { routingRules, type Db, and, asc, eq, or } from '@mosaicstack/db';
 import { DB } from '../../database/database.module.js';
 import { ProviderService } from '../provider.service.js';
 import { classifyTask } from './task-classifier.js';
--- a/apps/gateway/src/agent/routing/routing.controller.ts
+++ b/apps/gateway/src/agent/routing/routing.controller.ts
@@ -13,7 +13,7 @@ import {
  Post,
  UseGuards,
 } from '@nestjs/common';
-import { routingRules, type Db, and, asc, eq, or, inArray } from '@mosaic/db';
+import { routingRules, type Db, and, asc, eq, or, inArray } from '@mosaicstack/db';
 import { DB } from '../../database/database.module.js';
 import { AuthGuard } from '../../auth/auth.guard.js';
 import { CurrentUser } from '../../auth/current-user.decorator.js';
--- a/apps/gateway/src/agent/routing/routing.types.ts
+++ b/apps/gateway/src/agent/routing/routing.types.ts
@@ -1,7 +1,7 @@
 /**
 * Routing engine types — M4-002 (condition types) and M4-003 (action types).
 *
- * These types are re-exported from `@mosaic/types` for shared use across packages.
+ * These types are re-exported from `@mosaicstack/types` for shared use across packages.
 */

 // ─── Classification primitives ───────────────────────────────────────────────
@@ -23,7 +23,7 @@ export type Domain = 'frontend' | 'backend' | 'devops' | 'docs' | 'general';

 /**
 * Cost tier for model selection.
- * Extends the existing `CostTier` in `@mosaic/types` with `local` for self-hosted models.
+ * Extends the existing `CostTier` in `@mosaicstack/types` with `local` for self-hosted models.
 */
 export type CostTier = 'cheap' | 'standard' | 'premium' | 'local';

--- a/apps/gateway/src/agent/tools/brain-tools.ts
+++ b/apps/gateway/src/agent/tools/brain-tools.ts
@@ -1,6 +1,6 @@
 import { Type } from '@sinclair/typebox';
 import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';

 export function createBrainTools(brain: Brain): ToolDefinition[] {
  const listProjects: ToolDefinition = {
--- a/apps/gateway/src/agent/tools/memory-tools.ts
+++ b/apps/gateway/src/agent/tools/memory-tools.ts
@@ -1,7 +1,7 @@
 import { Type } from '@sinclair/typebox';
 import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
-import type { Memory } from '@mosaic/memory';
-import type { EmbeddingProvider } from '@mosaic/memory';
+import type { Memory } from '@mosaicstack/memory';
+import type { EmbeddingProvider } from '@mosaicstack/memory';

 /**
 * Create memory tools bound to the session's authenticated userId.
--- a/apps/gateway/src/auth/auth.controller.ts
+++ b/apps/gateway/src/auth/auth.controller.ts
@@ -1,6 +1,6 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { toNodeHandler } from 'better-auth/node';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
 import type { NestFastifyApplication } from '@nestjs/platform-fastify';
 import { AUTH } from './auth.tokens.js';

--- a/apps/gateway/src/auth/auth.guard.ts
+++ b/apps/gateway/src/auth/auth.guard.ts
@@ -6,7 +6,7 @@ import {
  UnauthorizedException,
 } from '@nestjs/common';
 import { fromNodeHeaders } from 'better-auth/node';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
 import type { FastifyRequest } from 'fastify';
 import { AUTH } from './auth.tokens.js';

--- a/apps/gateway/src/auth/auth.module.ts
+++ b/apps/gateway/src/auth/auth.module.ts
@@ -1,6 +1,6 @@
 import { Global, Module } from '@nestjs/common';
-import { createAuth, type Auth } from '@mosaic/auth';
-import type { Db } from '@mosaic/db';
+import { createAuth, type Auth } from '@mosaicstack/auth';
+import type { Db } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import { AUTH } from './auth.tokens.js';
 import { SsoController } from './sso.controller.js';
@@ -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],
--- a/apps/gateway/src/auth/sso.controller.ts
+++ b/apps/gateway/src/auth/sso.controller.ts
@@ -1,5 +1,5 @@
 import { Controller, Get } from '@nestjs/common';
-import { buildSsoDiscovery, type SsoProviderDiscovery } from '@mosaic/auth';
+import { buildSsoDiscovery, type SsoProviderDiscovery } from '@mosaicstack/auth';

@Controller('api/sso/providers')
 export class SsoController {
--- a/apps/gateway/src/brain/brain.module.ts
+++ b/apps/gateway/src/brain/brain.module.ts
@@ -1,6 +1,6 @@
 import { Global, Module } from '@nestjs/common';
-import { createBrain, type Brain } from '@mosaic/brain';
-import type { Db } from '@mosaic/db';
+import { createBrain, type Brain } from '@mosaicstack/brain';
+import type { Db } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import { BRAIN } from './brain.tokens.js';

--- a/apps/gateway/src/chat/chat.gateway.ts
+++ b/apps/gateway/src/chat/chat.gateway.ts
@@ -11,15 +11,15 @@ import {
 } from '@nestjs/websockets';
 import { Server, Socket } from 'socket.io';
 import type { AgentSessionEvent } from '@mariozechner/pi-coding-agent';
-import type { Auth } from '@mosaic/auth';
-import type { Brain } from '@mosaic/brain';
+import type { Auth } from '@mosaicstack/auth';
+import type { Brain } from '@mosaicstack/brain';
 import type {
  SetThinkingPayload,
  SlashCommandPayload,
  SystemReloadPayload,
  RoutingDecisionInfo,
  AbortPayload,
-} from '@mosaic/types';
+} from '@mosaicstack/types';
 import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
 import { BRAIN } from '../brain/brain.tokens.js';
--- a/apps/gateway/src/commands/command-executor-p8012.spec.ts
+++ b/apps/gateway/src/commands/command-executor-p8012.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { CommandExecutorService } from './command-executor.service.js';
-import type { SlashCommandPayload } from '@mosaic/types';
+import type { SlashCommandPayload } from '@mosaicstack/types';

 // Minimal mock implementations
 const mockRegistry = {
--- a/apps/gateway/src/commands/command-executor.service.ts
+++ b/apps/gateway/src/commands/command-executor.service.ts
@@ -1,7 +1,7 @@
 import { forwardRef, Inject, Injectable, Logger, Optional } from '@nestjs/common';
-import type { QueueHandle } from '@mosaic/queue';
-import type { Brain } from '@mosaic/brain';
-import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaic/types';
+import type { QueueHandle } from '@mosaicstack/queue';
+import type { Brain } from '@mosaicstack/brain';
+import type { SlashCommandPayload, SlashCommandResultPayload } from '@mosaicstack/types';
 import { AgentService } from '../agent/agent.service.js';
 import { ChatGateway } from '../chat/chat.gateway.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
--- a/apps/gateway/src/commands/command-registry.service.spec.ts
+++ b/apps/gateway/src/commands/command-registry.service.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, beforeEach } from 'vitest';
 import { CommandRegistryService } from './command-registry.service.js';
-import type { CommandDef } from '@mosaic/types';
+import type { CommandDef } from '@mosaicstack/types';

 const mockCmd: CommandDef = {
  name: 'test',
--- a/apps/gateway/src/commands/command-registry.service.ts
+++ b/apps/gateway/src/commands/command-registry.service.ts
@@ -1,5 +1,5 @@
 import { Injectable, type OnModuleInit } from '@nestjs/common';
-import type { CommandDef, CommandManifest } from '@mosaic/types';
+import type { CommandDef, CommandManifest } from '@mosaicstack/types';

@Injectable()
 export class CommandRegistryService implements OnModuleInit {
--- a/apps/gateway/src/commands/commands.integration.spec.ts
+++ b/apps/gateway/src/commands/commands.integration.spec.ts
@@ -13,7 +13,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { CommandRegistryService } from './command-registry.service.js';
 import { CommandExecutorService } from './command-executor.service.js';
-import type { SlashCommandPayload } from '@mosaic/types';
+import type { SlashCommandPayload } from '@mosaicstack/types';

 // ─── Mocks ───────────────────────────────────────────────────────────────────

--- a/apps/gateway/src/commands/commands.module.ts
+++ b/apps/gateway/src/commands/commands.module.ts
@@ -1,5 +1,5 @@
 import { forwardRef, Inject, Module, type OnApplicationShutdown } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaic/queue';
+import { createQueue, type QueueHandle } from '@mosaicstack/queue';
 import { ChatModule } from '../chat/chat.module.js';
 import { GCModule } from '../gc/gc.module.js';
 import { ReloadModule } from '../reload/reload.module.js';
--- a/apps/gateway/src/config/config.module.ts
+++ b/apps/gateway/src/config/config.module.ts
@@ -1,5 +1,5 @@
 import { Global, Module } from '@nestjs/common';
-import { loadConfig, type MosaicConfig } from '@mosaic/config';
+import { loadConfig, type MosaicConfig } from '@mosaicstack/config';

 export const MOSAIC_CONFIG = 'MOSAIC_CONFIG';

--- a/apps/gateway/src/conversations/conversations.controller.ts
+++ b/apps/gateway/src/conversations/conversations.controller.ts
@@ -15,7 +15,7 @@ import {
  Query,
  UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
--- a/apps/gateway/src/coord/coord.service.ts
+++ b/apps/gateway/src/coord/coord.service.ts
@@ -8,7 +8,7 @@ import {
  type MissionStatusSummary,
  type MissionTask,
  type TaskDetail,
-} from '@mosaic/coord';
+} from '@mosaicstack/coord';
 import { promises as fs } from 'node:fs';
 import path from 'node:path';

--- a/apps/gateway/src/database/database.module.ts
+++ b/apps/gateway/src/database/database.module.ts
@@ -1,7 +1,10 @@
+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 { createStorageAdapter, type StorageAdapter } from '@mosaic/storage';
-import type { MosaicConfig } from '@mosaic/config';
+import { createDb, createPgliteDb, type Db, type DbHandle } from '@mosaicstack/db';
+import { createStorageAdapter, type StorageAdapter } from '@mosaicstack/storage';
+import type { MosaicConfig } from '@mosaicstack/config';
 import { MOSAIC_CONFIG } from '../config/config.module.js';

 export const DB_HANDLE = 'DB_HANDLE';
@@ -13,8 +16,14 @@ export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
  providers: [
    {
      provide: DB_HANDLE,
-      useFactory: (config: MosaicConfig): DbHandle =>
-        createDb(config.storage.type === 'postgres' ? config.storage.url : undefined),
+      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],
    },
    {
--- a/apps/gateway/src/gc/gc.module.ts
+++ b/apps/gateway/src/gc/gc.module.ts
@@ -1,5 +1,5 @@
 import { Module, type OnApplicationShutdown, Inject } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaic/queue';
+import { createQueue, type QueueHandle } from '@mosaicstack/queue';
 import { SessionGCService } from './session-gc.service.js';
 import { REDIS } from './gc.tokens.js';

--- a/apps/gateway/src/gc/session-gc.service.spec.ts
+++ b/apps/gateway/src/gc/session-gc.service.spec.ts
@@ -1,7 +1,7 @@
 import { describe, it, expect, vi, beforeEach } from 'vitest';
 import { Logger } from '@nestjs/common';
-import type { QueueHandle } from '@mosaic/queue';
-import type { LogService } from '@mosaic/log';
+import type { QueueHandle } from '@mosaicstack/queue';
+import type { LogService } from '@mosaicstack/log';
 import { SessionGCService } from './session-gc.service.js';

 type MockRedis = {
--- a/apps/gateway/src/gc/session-gc.service.ts
+++ b/apps/gateway/src/gc/session-gc.service.ts
@@ -1,6 +1,6 @@
 import { Inject, Injectable, Logger, type OnModuleInit } from '@nestjs/common';
-import type { QueueHandle } from '@mosaic/queue';
-import type { LogService } from '@mosaic/log';
+import type { QueueHandle } from '@mosaicstack/queue';
+import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
 import { REDIS } from './gc.tokens.js';

--- a/apps/gateway/src/log/log.controller.ts
+++ b/apps/gateway/src/log/log.controller.ts
@@ -1,5 +1,5 @@
 import { Body, Controller, Get, Inject, Param, Post, Query, UseGuards } from '@nestjs/common';
-import type { LogService } from '@mosaic/log';
+import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from './log.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import type { IngestLogDto, QueryLogsDto } from './log.dto.js';
--- a/apps/gateway/src/log/log.module.ts
+++ b/apps/gateway/src/log/log.module.ts
@@ -1,6 +1,6 @@
 import { Global, Module } from '@nestjs/common';
-import { createLogService, type LogService } from '@mosaic/log';
-import type { Db } from '@mosaic/db';
+import { createLogService, type LogService } from '@mosaicstack/log';
+import type { Db } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';
 import { LOG_SERVICE } from './log.tokens.js';
 import { LogController } from './log.controller.js';
--- a/apps/gateway/src/log/summarization.service.ts
+++ b/apps/gateway/src/log/summarization.service.ts
@@ -1,11 +1,11 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import type { LogService } from '@mosaic/log';
-import type { Memory } from '@mosaic/memory';
+import type { LogService } from '@mosaicstack/log';
+import type { Memory } from '@mosaicstack/memory';
 import { LOG_SERVICE } from './log.tokens.js';
 import { MEMORY } from '../memory/memory.tokens.js';
 import { EmbeddingService } from '../memory/embedding.service.js';
-import type { Db } from '@mosaic/db';
-import { sql, summarizationJobs } from '@mosaic/db';
+import type { Db } from '@mosaicstack/db';
+import { sql, summarizationJobs } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';

 const SUMMARIZATION_PROMPT = `You are a knowledge extraction assistant. Given the following agent interaction logs, extract the key decisions, learnings, and patterns. Output a concise summary (2-4 sentences) that captures the most important information for future reference. Focus on actionable insights, not raw events.
--- a/apps/gateway/src/main.ts
+++ b/apps/gateway/src/main.ts
@@ -19,7 +19,7 @@ import { NestFactory } from '@nestjs/core';
 import { Logger, ValidationPipe } from '@nestjs/common';
 import { FastifyAdapter, type NestFastifyApplication } from '@nestjs/platform-fastify';
 import helmet from '@fastify/helmet';
-import { listSsoStartupWarnings } from '@mosaic/auth';
+import { listSsoStartupWarnings } from '@mosaicstack/auth';
 import { AppModule } from './app.module.js';
 import { mountAuthHandler } from './auth/auth.controller.js';
 import { mountMcpHandler } from './mcp/mcp.controller.js';
@@ -59,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}`);
 }
--- a/apps/gateway/src/mcp/mcp.controller.ts
+++ b/apps/gateway/src/mcp/mcp.controller.ts
@@ -1,7 +1,7 @@
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { Logger } from '@nestjs/common';
 import { fromNodeHeaders } from 'better-auth/node';
-import type { Auth } from '@mosaic/auth';
+import type { Auth } from '@mosaicstack/auth';
 import type { NestFastifyApplication } from '@nestjs/platform-fastify';
 import type { McpService } from './mcp.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
--- a/apps/gateway/src/mcp/mcp.service.ts
+++ b/apps/gateway/src/mcp/mcp.service.ts
@@ -3,8 +3,8 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
 import { randomUUID } from 'node:crypto';
 import { z } from 'zod';
-import type { Brain } from '@mosaic/brain';
-import type { Memory } from '@mosaic/memory';
+import type { Brain } from '@mosaicstack/brain';
+import type { Memory } from '@mosaicstack/memory';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { MEMORY } from '../memory/memory.tokens.js';
 import { EmbeddingService } from '../memory/embedding.service.js';
--- a/apps/gateway/src/memory/embedding.service.ts
+++ b/apps/gateway/src/memory/embedding.service.ts
@@ -1,5 +1,5 @@
 import { Injectable, Logger } from '@nestjs/common';
-import type { EmbeddingProvider } from '@mosaic/memory';
+import type { EmbeddingProvider } from '@mosaicstack/memory';

 // ---------------------------------------------------------------------------
 // Environment-driven configuration
--- a/apps/gateway/src/memory/memory.controller.ts
+++ b/apps/gateway/src/memory/memory.controller.ts
@@ -12,7 +12,7 @@ import {
  Query,
  UseGuards,
 } from '@nestjs/common';
-import type { Memory } from '@mosaic/memory';
+import type { Memory } from '@mosaicstack/memory';
 import { MEMORY } from './memory.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
--- a/apps/gateway/src/memory/memory.module.ts
+++ b/apps/gateway/src/memory/memory.module.ts
@@ -5,10 +5,10 @@ import {
  createMemoryAdapter,
  type MemoryAdapter,
  type MemoryConfig,
-} from '@mosaic/memory';
-import type { Db } from '@mosaic/db';
-import type { StorageAdapter } from '@mosaic/storage';
-import type { MosaicConfig } from '@mosaic/config';
+} from '@mosaicstack/memory';
+import type { Db } from '@mosaicstack/db';
+import type { StorageAdapter } from '@mosaicstack/storage';
+import type { MosaicConfig } from '@mosaicstack/config';
 import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { DB, STORAGE_ADAPTER } from '../database/database.module.js';
 import { MEMORY } from './memory.tokens.js';
--- a/apps/gateway/src/missions/missions.controller.ts
+++ b/apps/gateway/src/missions/missions.controller.ts
@@ -12,7 +12,7 @@ import {
  Post,
  UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
--- a/apps/gateway/src/plugin/plugin.module.ts
+++ b/apps/gateway/src/plugin/plugin.module.ts
@@ -6,8 +6,8 @@ import {
  type OnModuleDestroy,
  type OnModuleInit,
 } from '@nestjs/common';
-import { DiscordPlugin } from '@mosaic/discord-plugin';
-import { TelegramPlugin } from '@mosaic/telegram-plugin';
+import { DiscordPlugin } from '@mosaicstack/discord-plugin';
+import { TelegramPlugin } from '@mosaicstack/telegram-plugin';
 import { PluginService } from './plugin.service.js';
 import type { IChannelPlugin } from './plugin.interface.js';
 import { PLUGIN_REGISTRY } from './plugin.tokens.js';
@@ -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[] = [];
--- a/apps/gateway/src/preferences/preferences.service.spec.ts
+++ b/apps/gateway/src/preferences/preferences.service.spec.ts
@@ -1,6 +1,6 @@
 import { describe, it, expect, vi } from 'vitest';
 import { PreferencesService, PLATFORM_DEFAULTS, IMMUTABLE_KEYS } from './preferences.service.js';
-import type { Db } from '@mosaic/db';
+import type { Db } from '@mosaicstack/db';

 /**
 * Build a mock Drizzle DB where the select chain supports:
--- a/apps/gateway/src/preferences/preferences.service.ts
+++ b/apps/gateway/src/preferences/preferences.service.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import { eq, and, sql, type Db, preferences as preferencesTable } from '@mosaic/db';
+import { eq, and, sql, type Db, preferences as preferencesTable } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';

 export const PLATFORM_DEFAULTS: Record<string, unknown> = {
--- a/apps/gateway/src/preferences/system-override.service.ts
+++ b/apps/gateway/src/preferences/system-override.service.ts
@@ -1,5 +1,5 @@
 import { Injectable, Logger } from '@nestjs/common';
-import { createQueue, type QueueHandle } from '@mosaic/queue';
+import { createQueue, type QueueHandle } from '@mosaicstack/queue';

 const SESSION_SYSTEM_KEY = (sessionId: string) => `mosaic:session:${sessionId}:system`;
 const SESSION_SYSTEM_FRAGMENTS_KEY = (sessionId: string) =>
--- a/apps/gateway/src/projects/projects.controller.ts
+++ b/apps/gateway/src/projects/projects.controller.ts
@@ -13,7 +13,7 @@ import {
  Post,
  UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
--- a/apps/gateway/src/queue/queue.module.ts
+++ b/apps/gateway/src/queue/queue.module.ts
@@ -1,6 +1,6 @@
 import { Global, Module } from '@nestjs/common';
-import { createQueueAdapter, type QueueAdapter } from '@mosaic/queue';
-import type { MosaicConfig } from '@mosaic/config';
+import { createQueueAdapter, type QueueAdapter } from '@mosaicstack/queue';
+import type { MosaicConfig } from '@mosaicstack/config';
 import { MOSAIC_CONFIG } from '../config/config.module.js';
 import { QueueService } from './queue.service.js';

--- a/apps/gateway/src/queue/queue.service.ts
+++ b/apps/gateway/src/queue/queue.service.ts
@@ -7,7 +7,7 @@ import {
  type OnModuleDestroy,
 } from '@nestjs/common';
 import { Queue, Worker, type Job, type ConnectionOptions } from 'bullmq';
-import type { LogService } from '@mosaic/log';
+import type { LogService } from '@mosaicstack/log';
 import { LOG_SERVICE } from '../log/log.tokens.js';
 import type { JobDto, JobStatus } from './queue-admin.dto.js';

--- a/apps/gateway/src/reload/reload.controller.ts
+++ b/apps/gateway/src/reload/reload.controller.ts
@@ -1,5 +1,5 @@
 import { Controller, HttpCode, HttpStatus, Inject, Post, UseGuards } from '@nestjs/common';
-import type { SystemReloadPayload } from '@mosaic/types';
+import type { SystemReloadPayload } from '@mosaicstack/types';
 import { AdminGuard } from '../admin/admin.guard.js';
 import { ChatGateway } from '../chat/chat.gateway.js';
 import { ReloadService } from './reload.service.js';
--- a/apps/gateway/src/reload/reload.service.ts
+++ b/apps/gateway/src/reload/reload.service.ts
@@ -5,7 +5,7 @@ import {
  type OnApplicationBootstrap,
  type OnApplicationShutdown,
 } from '@nestjs/common';
-import type { SystemReloadPayload } from '@mosaic/types';
+import type { SystemReloadPayload } from '@mosaicstack/types';
 import { CommandRegistryService } from '../commands/command-registry.service.js';
 import { isMosaicPlugin } from './mosaic-plugin.interface.js';

--- a/apps/gateway/src/skills/skills.service.ts
+++ b/apps/gateway/src/skills/skills.service.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable } from '@nestjs/common';
-import { eq, type Db, skills } from '@mosaic/db';
+import { eq, type Db, skills } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';

 type Skill = typeof skills.$inferSelect;
--- a/apps/gateway/src/tasks/tasks.controller.ts
+++ b/apps/gateway/src/tasks/tasks.controller.ts
@@ -14,7 +14,7 @@ import {
  Query,
  UseGuards,
 } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { AuthGuard } from '../auth/auth.guard.js';
 import { CurrentUser } from '../auth/current-user.decorator.js';
--- a/apps/gateway/src/workspace/project-bootstrap.service.ts
+++ b/apps/gateway/src/workspace/project-bootstrap.service.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import type { Brain } from '@mosaic/brain';
+import type { Brain } from '@mosaicstack/brain';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { PluginService } from '../plugin/plugin.service.js';
 import { WorkspaceService } from './workspace.service.js';
--- a/apps/gateway/src/workspace/teams.service.ts
+++ b/apps/gateway/src/workspace/teams.service.ts
@@ -1,5 +1,5 @@
 import { Inject, Injectable, Logger } from '@nestjs/common';
-import { eq, and, type Db, teams, teamMembers, projects } from '@mosaic/db';
+import { eq, and, type Db, teams, teamMembers, projects } from '@mosaicstack/db';
 import { DB } from '../database/database.module.js';

@Injectable()
--- a/apps/gateway/tsconfig.typecheck.json
+++ b/apps/gateway/tsconfig.typecheck.json
@@ -4,15 +4,15 @@
    "rootDir": "../..",
    "baseUrl": ".",
    "paths": {
-      "@mosaic/auth": ["../../packages/auth/src/index.ts"],
-      "@mosaic/brain": ["../../packages/brain/src/index.ts"],
-      "@mosaic/coord": ["../../packages/coord/src/index.ts"],
-      "@mosaic/db": ["../../packages/db/src/index.ts"],
-      "@mosaic/log": ["../../packages/log/src/index.ts"],
-      "@mosaic/memory": ["../../packages/memory/src/index.ts"],
-      "@mosaic/types": ["../../packages/types/src/index.ts"],
-      "@mosaic/discord-plugin": ["../../plugins/discord/src/index.ts"],
-      "@mosaic/telegram-plugin": ["../../plugins/telegram/src/index.ts"]
+      "@mosaicstack/auth": ["../../packages/auth/src/index.ts"],
+      "@mosaicstack/brain": ["../../packages/brain/src/index.ts"],
+      "@mosaicstack/coord": ["../../packages/coord/src/index.ts"],
+      "@mosaicstack/db": ["../../packages/db/src/index.ts"],
+      "@mosaicstack/log": ["../../packages/log/src/index.ts"],
+      "@mosaicstack/memory": ["../../packages/memory/src/index.ts"],
+      "@mosaicstack/types": ["../../packages/types/src/index.ts"],
+      "@mosaicstack/discord-plugin": ["../../plugins/discord/src/index.ts"],
+      "@mosaicstack/telegram-plugin": ["../../plugins/telegram/src/index.ts"]
    }
  }
 }
--- a/apps/web/next.config.ts
+++ b/apps/web/next.config.ts
@@ -2,7 +2,7 @@ import type { NextConfig } from 'next';

 const nextConfig: NextConfig = {
  output: 'standalone',
-  transpilePackages: ['@mosaic/design-tokens'],
+  transpilePackages: ['@mosaicstack/design-tokens'],

  // Enable gzip/brotli compression for all responses.
  compress: true,
--- a/apps/web/package.json
+++ b/apps/web/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@mosaic/web",
+  "name": "@mosaicstack/web",
  "version": "0.0.2",
  "private": true,
  "scripts": {
@@ -12,7 +12,7 @@
    "start": "next start"
  },
  "dependencies": {
-    "@mosaic/design-tokens": "workspace:^",
+    "@mosaicstack/design-tokens": "workspace:^",
    "better-auth": "^1.5.5",
    "clsx": "^2.1.0",
    "next": "^16.0.0",
--- a/apps/web/playwright.config.ts
+++ b/apps/web/playwright.config.ts
@@ -5,9 +5,9 @@ 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
+ * Run with:   pnpm --filter @mosaicstack/web test:e2e
 */
 export default defineConfig({
  testDir: './e2e',
--- a/apps/web/src/lib/api.ts
+++ b/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;
--- a/apps/web/src/lib/auth-client.ts
+++ b/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()],
 });

--- a/apps/web/src/lib/socket.ts
+++ b/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;

--- a/docs/MISSION-MANIFEST.md
+++ b/docs/MISSION-MANIFEST.md
@@ -1,70 +1,70 @@
-# Mission Manifest — Harness Foundation
+# Mission Manifest — CLI Unification & E2E First-Run

 > Persistent document tracking full mission scope, status, and session history.
 > Updated by the orchestrator at each phase transition and milestone completion.

 ## Mission

-**ID:** harness-20260321
-**Statement:** Transform Mosaic Stack from a functional demo into a real multi-provider, task-routing AI harness. Persist all conversations, integrate frontier LLM providers (Anthropic, OpenAI, OpenRouter, Z.ai, Ollama), build granular task-aware agent routing, harden agent sessions, replace cron with BullMQ, and design the channel protocol for future Matrix/remote integration.
-**Phase:** Complete
-**Current Milestone:** All milestones done
-**Progress:** 7 / 7 milestones
-**Status:** complete
-**Last Updated:** 2026-03-22 UTC
+**ID:** cli-unification-20260404
+**Statement:** Transform the Mosaic CLI from a partially-duplicated, manually-assembled experience into a single cohesive entry point that installs, configures, and controls the entire Mosaic system. Every Mosaic package gets first-class CLI surface. The first-run experience works end-to-end with no manual stitching. Gateway token recovery is possible without the web UI. Opt-in telemetry uses the published telemetry clients.
+**Phase:** Execution
+**Current Milestone:** cu-m03 / cu-m04 / cu-m05 (parallel-eligible)
+**Progress:** 2 / 8 milestones
+**Status:** active
+**Last Updated:** 2026-04-04

 ## Success Criteria

- [x] AC-1: Send messages in TUI → restart TUI → resume conversation → agent has full history and context
- [x] AC-2: Route a coding task to Claude Opus 4.6, a simple question to Haiku, a summarization to GLM-5 — all via granular routing rules
- [x] AC-3: Two users exist, User A's memory searches never return User B's data
- [x] AC-4: `/model claude-sonnet-4-6` in TUI switches the active model for subsequent messages
- [x] AC-5: `/agent coding-agent` in TUI switches to a different agent with different system prompt and tools
- [x] AC-6: BullMQ jobs execute on schedule, failures retry with backoff, admin can inspect via `/api/admin/jobs`
- [x] AC-7: Channel protocol document exists with Matrix integration points defined, reviewed, and approved
- [x] AC-8: Embeddings run on Ollama local models (no external API dependency for vector operations)
- [x] AC-9: All five providers (Anthropic, OpenAI, OpenRouter, Z.ai, Ollama) connect, list models, and complete chat requests
- [x] AC-10: Routing transparency — TUI displays which model was selected and the routing reason for each response
+- [ ] AC-1: Fresh machine `bash <(curl …install.sh)` → single command lands on a working authenticated gateway with a usable admin token; no secondary manual wizards required
+- [ ] AC-2: `mosaic --help` lists every sub-package as a top-level command and is alphabetized for readability
+- [ ] AC-3: `mosaic auth`, `mosaic brain`, `mosaic forge`, `mosaic log`, `mosaic macp`, `mosaic memory`, `mosaic queue`, `mosaic storage`, `mosaic telemetry` each expose at least one working subcommand that exercises the underlying package
+- [ ] AC-4: Gateway admin token can be rotated or recovered from the CLI alone — operator is never stranded because the web UI is inaccessible
+- [ ] AC-5: `mosaic telemetry` uses the published `@mosaicstack/telemetry-client-js` (from the Gitea npm registry); local OTEL stays for wide-event logging / post-mortems; remote upload is opt-in and disabled by default
+- [ ] AC-6: Install → wizard → gateway install → TUI verification flow is a single cohesive path with clear state transitions and no dead ends
+- [ ] AC-7: `@mosaicstack/mosaic` is the sole `mosaic` binary owner; `@mosaicstack/cli` is gone from the repo and all docs
+- [ ] AC-8: All milestones ship as merged PRs with green CI, closed issues, and updated release notes

 ## Milestones

 | #   | ID     | Name                                                                     | Status      | Branch                             | Issue | Started    | Completed  |
-| --- | ------ | ---------------------------------- | ------ | ------ | --------- | ---------- | ---------- |
-| 1   | ms-166 | Conversation Persistence & Context | done   | —      | #224–#231 | 2026-03-21 | 2026-03-21 |
-| 2   | ms-167 | Security & Isolation               | done   | —      | #232–#239 | 2026-03-21 | 2026-03-21 |
-| 3   | ms-168 | Provider Integration               | done   | —      | #240–#251 | 2026-03-21 | 2026-03-22 |
-| 4   | ms-169 | Agent Routing Engine               | done   | —      | #252–#264 | 2026-03-22 | 2026-03-22 |
-| 5   | ms-170 | Agent Session Hardening            | done   | —      | #265–#272 | 2026-03-22 | 2026-03-22 |
-| 6   | ms-171 | Job Queue Foundation               | done   | —      | #273–#280 | 2026-03-22 | 2026-03-22 |
-| 7   | ms-172 | Channel Protocol Design            | done   | —      | #281–#288 | 2026-03-22 | 2026-03-22 |
+| --- | ------ | ------------------------------------------------------------------------ | ----------- | ---------------------------------- | ----- | ---------- | ---------- |
+| 1   | cu-m01 | Kill legacy @mosaicstack/cli package                                     | done        | chore/remove-cli-package-duplicate | #398  | 2026-04-04 | 2026-04-04 |
+| 2   | cu-m02 | Archive stale mission state + scaffold new mission                       | done        | docs/mission-cli-unification       | #399  | 2026-04-04 | 2026-04-04 |
+| 3   | cu-m03 | Fix gateway bootstrap token recovery (server + CLI paths)                | not-started | —                                  | —     | —          | —          |
+| 4   | cu-m04 | Alphabetize + group `mosaic --help` output                               | not-started | —                                  | —     | —          | —          |
+| 5   | cu-m05 | Sub-package CLI surface (auth/brain/forge/log/macp/memory/queue/storage) | not-started | —                                  | —     | —          | —          |
+| 6   | cu-m06 | `mosaic telemetry` — local OTEL + opt-in remote upload                   | not-started | —                                  | —     | —          | —          |
+| 7   | cu-m07 | Unified first-run UX (install.sh → wizard → gateway → TUI)               | not-started | —                                  | —     | —          | —          |
+| 8   | cu-m08 | Docs refresh + release tag                                               | not-started | —                                  | —     | —          | —          |

 ## Deployment

 | Target               | URL       | Method                                          |
-| -------------------- | --------- | -------------------------- |
-| Docker Compose (dev) | localhost | docker compose up          |
-| Production           | TBD       | Docker Swarm via Portainer |
+| -------------------- | --------- | ----------------------------------------------- |
+| Local tier (default) | localhost | `mosaic gateway install` — pglite + local queue |
+| Team tier            | any host  | `mosaic gateway install` — PG + Valkey          |
+| Docker Compose (dev) | localhost | `docker compose up` for PG/Valkey/OTEL/Jaeger   |

 ## Coordination

- **Primary Agent:** claude-opus-4-6
- **Sibling Agents:** sonnet (workers), haiku (verification)
- **Shared Contracts:** docs/PRD-Harness_Foundation.md, docs/TASKS.md
+- **Primary Agent:** claude-opus-4-6[1m]
+- **Sibling Agents:** sonnet (standard implementation), haiku (status/explore/verify), codex (coding-heavy tasks)
+- **Shared Contracts:** `docs/PRD.md` (existing v0.1.0 PRD — still the long-term target), this manifest, `docs/TASKS.md`, `docs/scratchpads/cli-unification-20260404.md`

 ## Token Budget

 | Metric | Value  |
 | ------ | ------ |
-| Budget | —      |
-| Used   | ~2.5M  |
+| Budget | TBD    |
+| Used   | ~80K   |
 | Mode   | normal |

 ## Session History

 | Session | Runtime         | Started    | Duration  | Ended Reason | Last Task                                                    |
-| ------- | --------------- | ---------- | -------- | ------------ | ----------------- |
-| 1       | claude-opus-4-6 | 2026-03-21 | ~6h      | complete     | M7-008 — all done |
+| ------- | --------------- | ---------- | --------- | ------------ | ------------------------------------------------------------ |
+| 1       | claude-opus-4-6 | 2026-04-04 | in-flight | —            | cu-m01 + cu-m02 merged (#398, #399); open questions resolved |

 ## Scratchpad

-Path: `docs/scratchpads/harness-20260321.md`
+Path: `docs/scratchpads/cli-unification-20260404.md`
--- a/docs/PERFORMANCE.md
+++ b/docs/PERFORMANCE.md
@@ -153,7 +153,7 @@ for any `<Image>` components added in the future.

 ```bash
 # Run the DB migration (requires a live DB)
-pnpm --filter @mosaic/db exec drizzle-kit migrate
+pnpm --filter @mosaicstack/db exec drizzle-kit migrate

 # Or, in Docker/Swarm — migrations run automatically on gateway startup
 # via runMigrations() in packages/db/src/migrate.ts
--- a/docs/PRD-TUI_Improvements.md
+++ b/docs/PRD-TUI_Improvements.md
@@ -57,7 +57,7 @@ Multi-panel layout with keyboard navigation.

 - **Ink 5** (React for CLI) — already in deps
 - **Component architecture** — break monolithic `app.tsx` into composable components
- **Typed Socket.IO events** — leverage `@mosaic/types` `ServerToClientEvents` / `ClientToServerEvents`
+- **Typed Socket.IO events** — leverage `@mosaicstack/types` `ServerToClientEvents` / `ClientToServerEvents`
 - **Local state only** (Wave 1) — cwd/branch read from `process.cwd()` and `git` at startup
 - **Gateway metadata** (future) — extend socket handshake or add REST endpoint for model info, token usage

--- a/docs/PRD.md
+++ b/docs/PRD.md
@@ -8,7 +8,7 @@
 - **Best-Guess Mode:** true
 - Repo (target): `git.mosaicstack.dev/mosaic/mosaic-stack`
 - Baseline: `~/src/jarvis-old` (jarvis v0.2.0)
- Package source: `~/src/mosaic-mono-v0` (@mosaic/\* packages)
+- Package source: `~/src/mosaic-mono-v0` (@mosaicstack/\* packages)
 - Agent harness: [pi](https://github.com/badlogic/pi-mono) (v0.57.1)
 - Remote control reference: [OpenClaw](https://github.com/openclaw/openclaw) (upstream, canonical)

@@ -16,7 +16,7 @@

 ## Problem Statement

-Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and Next.js frontend. It handles chat, projects, tasks, and LLM routing but lacks orchestration depth, agent coordination, shared memory, and remote access. The Mosaic framework (`~/.config/mosaic`) provides agent guides, shell-based orchestration tools, and quality rails — but these are loose scripts, not an integrated platform. The `@mosaic/*` packages in mosaic-mono-v0 began consolidating these into TypeScript packages (brain, queue, coord, cli, prdy, quality-rails) but have no UI, no auth, and no agent runtime integration.
+Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and Next.js frontend. It handles chat, projects, tasks, and LLM routing but lacks orchestration depth, agent coordination, shared memory, and remote access. The Mosaic framework (`~/.config/mosaic`) provides agent guides, shell-based orchestration tools, and quality rails — but these are loose scripts, not an integrated platform. The `@mosaicstack/*` packages in mosaic-mono-v0 began consolidating these into TypeScript packages (brain, queue, coord, cli, prdy, quality-rails) but have no UI, no auth, and no agent runtime integration.

 **The gap:** Three codebases with overlapping concerns, no unified runtime, no remote control surface (Discord/Telegram), no gateway orchestrator, and a Python backend that doesn't align with the target TypeScript-everywhere stack.

@@ -32,7 +32,7 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 4. **Gateway orchestrator** — Central routing layer that dispatches tasks to appropriate agents based on capability, cost, and context
 5. **Shared memory** — PostgreSQL canonical store + vector DB for semantic search + tiered log summarization to prevent context creep
 6. **Multi-user with SSO** — BetterAuth with Authentik/WorkOS/Keycloak SSO, RBAC for family/team/business use
-7. **Full @mosaic/\* package integration** — brain, queue, coord, mosaic, prdy, quality-rails, cli all integrated
+7. **Full @mosaicstack/\* package integration** — brain, queue, coord, mosaic, prdy, quality-rails, cli all integrated
 8. **Extensible** — MCP capability, skill import interface, plugin architecture for LLM providers and remote channels

 ---
@@ -44,7 +44,7 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 1. Chat/conversation UI (web) — carry forward from jarvis-old, rewrite frontend to work with new backend
 2. Pi TUI integration — terminal-based agent interaction using Pi SDK
 3. Web dashboard — settings, task management, projects, PRDs, missions, agent status
-4. Gateway orchestrator (`@mosaic/gateway`) — central dispatch for agent tasks with routing logic
+4. Gateway orchestrator (`@mosaicstack/gateway`) — central dispatch for agent tasks with routing logic
 5. Task management — CRUD, kanban, mission-scoped tasks, dependency tracking
 6. Project management — projects, milestones, PRDs linked to missions
 7. Shared memory system — learned preferences, behaviors, defaults; tiered storage with summarization
@@ -55,13 +55,13 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 12. Agent routing — task-based model/provider selection (cost/capability matrix)
 13. MCP capability — server and client, tool registration
 14. Skill import interface — browse, install, manage agent skills
-15. `@mosaic/brain` — structured data layer (migrated to PG + vector DB backend)
-16. `@mosaic/queue` — Valkey-backed task queue with MCP tools
-17. `@mosaic/coord` — mission coordination engine
-18. `@mosaic/mosaic` — install wizard / bootstrap
-19. `@mosaic/prdy` — PRD wizard
-20. `@mosaic/quality-rails` — code quality scaffolder
-21. `@mosaic/cli` — unified `mosaic` CLI
+15. `@mosaicstack/brain` — structured data layer (migrated to PG + vector DB backend)
+16. `@mosaicstack/queue` — Valkey-backed task queue with MCP tools
+17. `@mosaicstack/coord` — mission coordination engine
+18. `@mosaicstack/mosaic` — install wizard / bootstrap
+19. `@mosaicstack/prdy` — PRD wizard
+20. `@mosaicstack/quality-rails` — code quality scaffolder
+21. `@mosaicstack/cli` — unified `mosaic` CLI
 22. Docker Compose deployment + bare-metal capability
 23. Agent log service — ingest, parse, tier, summarize agent interaction logs

@@ -94,14 +94,14 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 │       └──────────────┴───────┬───────┴────────────────┘          │
 │                              │                                   │
 │                    ┌─────────▼──────────┐                        │
-│                    │  @mosaic/gateway   │  ← Central Orchestrator│
+│                    │  @mosaicstack/gateway   │  ← Central Orchestrator│
 │                    │  (NestJS+Fastify)  │                        │
 │                    └────┬────┬────┬─────┘                        │
 │                         │    │    │                               │
 │          ┌──────────────┤    │    ├──────────────┐               │
 │          │              │    │    │              │               │
 │  ┌───────▼──────┐ ┌────▼────▼──┐ │  ┌───────────▼────────┐     │
-│  │ @mosaic/brain│ │ @mosaic/   │ │  │ Agent Pool         │     │
+│  │ @mosaicstack/brain│ │ @mosaicstack/   │ │  │ Agent Pool         │     │
 │  │ (Data Layer) │ │ queue      │ │  │ (Pi SDK sessions)  │     │
 │  └───────┬──────┘ └────────────┘ │  │ - Anthropic        │     │
 │          │                       │  │ - Codex            │     │
@@ -111,12 +111,12 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and
 │  └──────────────┴───────────┘    │  │ - llama.cpp        │     │
 │                                  │  └────────────────────┘     │
 │                    ┌─────────────▼──────┐                       │
-│                    │  @mosaic/coord     │                        │
+│                    │  @mosaicstack/coord     │                        │
 │                    │  Mission lifecycle │                        │
 │                    └────────────────────┘                        │
 │                                                                  │
 │  ┌──────────────┐  ┌──────────────┐  ┌──────────────────┐      │
-│  │ @mosaic/cli  │  │ @mosaic/prdy │  │ @mosaic/         │      │
+│  │ @mosaicstack/cli  │  │ @mosaicstack/prdy │  │ @mosaicstack/         │      │
 │  │              │  │              │  │ quality-rails    │      │
 │  └──────────────┘  └──────────────┘  └──────────────────┘      │
 │                                                                  │
@@ -130,20 +130,20 @@ Jarvis (v0.2.0) is a self-hosted AI assistant with a Python FastAPI backend and

 | Layer              | Technology                           | Rationale                                                                                                   |
 | ------------------ | ------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
-| **Web Frontend**   | Next.js 16 + React 19 + Tailwind CSS | SSR, RSC; design tokens from @mosaic/design-tokens (mosaic-stack-website)                                   |
+| **Web Frontend**   | Next.js 16 + React 19 + Tailwind CSS | SSR, RSC; design tokens from @mosaicstack/design-tokens (mosaic-stack-website)                              |
 | **API / Gateway**  | NestJS + Fastify adapter             | Module system, DI, guards/interceptors for complex gateway; Fastify performance underneath                  |
 | **Agent Runtime**  | Pi SDK (embedded)                    | Extensible harness with tools, skills, session management                                                   |
 | **TUI**            | Pi interactive mode                  | Native terminal agent interaction                                                                           |
 | **Auth**           | BetterAuth + SSO adapters            | Multi-user RBAC with Authentik/WorkOS/Keycloak                                                              |
 | **Database**       | PostgreSQL 17 + pgvector             | Canonical store; pgvector for embedding search                                                              |
-| **Vector DB**      | pgvector + VectorStore interface     | pgvector for v0.1.0; `VectorStore` abstraction in @mosaic/memory makes Qdrant a drop-in later               |
-| **Cache / Queue**  | Valkey 8                             | Redis-compatible; proven in @mosaic/queue                                                                   |
+| **Vector DB**      | pgvector + VectorStore interface     | pgvector for v0.1.0; `VectorStore` abstraction in @mosaicstack/memory makes Qdrant a drop-in later          |
+| **Cache / Queue**  | Valkey 8                             | Redis-compatible; proven in @mosaicstack/queue                                                              |
 | **ORM**            | Drizzle ORM                          | TypeScript-native, lightweight, good migration story                                                        |
-| **Validation**     | Zod                                  | Already used across @mosaic/\* packages                                                                     |
+| **Validation**     | Zod                                  | Already used across @mosaicstack/\* packages                                                                |
 | **Build**          | pnpm workspaces + Turborepo          | Proven in both jarvis-old and mosaic-mono-v0                                                                |
 | **Testing**        | Vitest + Playwright                  | Unit/integration via Vitest, E2E via Playwright                                                             |
 | **Remote Control** | Discord.js + Telegraf                | Inspired by OpenClaw plugin architecture                                                                    |
-| **MCP**            | @modelcontextprotocol/sdk            | Already used in @mosaic/brain and @mosaic/queue                                                             |
+| **MCP**            | @modelcontextprotocol/sdk            | Already used in @mosaicstack/brain and @mosaicstack/queue                                                   |
 | **Container**      | Docker Compose                       | Self-hosted; bare-metal also supported                                                                      |
 | **CI**             | Woodpecker CI                        | Existing infrastructure at git.mosaicstack.dev                                                              |
 | **Observability**  | OpenTelemetry + SigNoz               | Wide-event logging from day one; OTEL auto-instrumentation for NestJS/PG/HTTP; SigNoz as all-in-one backend |
@@ -158,12 +158,12 @@ The jarvis-old FastAPI backend is not carried forward as code. Its domain logic
 Instead of a custom LLM provider abstraction (jarvis-old's `BaseLLMProvider`), Pi SDK manages agent sessions. Pi handles model selection, tool calling, context management, and compaction. The gateway dispatches work to Pi sessions configured with appropriate providers.

 **AD-3: Gateway as the central nervous system (NestJS + Fastify adapter)**
-`@mosaic/gateway` is the single API surface. The web app, TUI, Discord, and Telegram all talk to the gateway. The gateway routes to brain (data), queue (coordination), agent pool (LLM work), and coord (mission lifecycle). This replaces the direct FastAPI-to-DB pattern from jarvis-old.
+`@mosaicstack/gateway` is the single API surface. The web app, TUI, Discord, and Telegram all talk to the gateway. The gateway routes to brain (data), queue (coordination), agent pool (LLM work), and coord (mission lifecycle). This replaces the direct FastAPI-to-DB pattern from jarvis-old.

-NestJS was chosen over raw Fastify because the gateway is inherently complex — it hosts channel plugins, agent pool management, routing engine, WebSocket hub, MCP server, auth middleware, and integrates brain, queue, memory, and log services. NestJS provides the module system, dependency injection, guards, and interceptors needed to organize this cleanly. NestJS uses Fastify as its HTTP adapter, so Fastify's performance is preserved. This also aligns with the stated stack preference in USER.md ("NestJS API + Next.js web"). @mosaic/brain's existing Fastify code migrates naturally into a NestJS module with Fastify adapter.
+NestJS was chosen over raw Fastify because the gateway is inherently complex — it hosts channel plugins, agent pool management, routing engine, WebSocket hub, MCP server, auth middleware, and integrates brain, queue, memory, and log services. NestJS provides the module system, dependency injection, guards, and interceptors needed to organize this cleanly. NestJS uses Fastify as its HTTP adapter, so Fastify's performance is preserved. This also aligns with the stated stack preference in USER.md ("NestJS API + Next.js web"). @mosaicstack/brain's existing Fastify code migrates naturally into a NestJS module with Fastify adapter.

 **AD-4: Brain migrates from JSON files to PostgreSQL**
-`@mosaic/brain` currently uses a JSON file store. For Mosaic Stack, brain's data model (tasks, projects, events, agents, missions, tickets) moves to PostgreSQL via Drizzle ORM. Brain's REST + MCP interface is preserved — only the storage backend changes.
+`@mosaicstack/brain` currently uses a JSON file store. For Mosaic Stack, brain's data model (tasks, projects, events, agents, missions, tickets) moves to PostgreSQL via Drizzle ORM. Brain's REST + MCP interface is preserved — only the storage backend changes.

 **AD-5: Tiered memory with summarization**
 Agent interaction logs are ingested into a log service. Raw logs are stored short-term. A summarization pipeline (using a cheap LLM) periodically compresses logs into structured insights stored in the vector DB. This prevents unbounded log growth while preserving searchable context.
@@ -189,8 +189,8 @@ The gateway includes a cron scheduler for recurring tasks: log summarization run
 **AD-12: Web search tool (DuckDuckGo MCP)**
 Agent sessions include a web search tool for information retrieval. DuckDuckGo via MCP server is the primary option (privacy-respecting, no API key required). Falls back to other search MCP providers if configured. Registered as a standard MCP tool available to all agent sessions.

-**AD-13: Design system from @mosaic/design-tokens**
-The web dashboard uses the Mosaic Stack design system established in `mosaic-stack-website`. The `@mosaic/design-tokens` package provides CSS custom properties, Tailwind preset, and TS color/font/radius exports. Dark theme default with light theme support. Fonts: Outfit (sans), Fira Code (mono). Color palette: deep blue-grays with blue/purple/teal accents.
+**AD-13: Design system from @mosaicstack/design-tokens**
+The web dashboard uses the Mosaic Stack design system established in `mosaic-stack-website`. The `@mosaicstack/design-tokens` package provides CSS custom properties, Tailwind preset, and TS color/font/radius exports. Dark theme default with light theme support. Fonts: Outfit (sans), Fira Code (mono). Color palette: deep blue-grays with blue/purple/teal accents.

 **AD-14: Multi-tier deployment readiness**
 Code is structured assuming eventual multi-node deployment with dedicated roles (gateway nodes, agent worker nodes, brain/DB nodes). Packages communicate via well-defined APIs (HTTP/WS/MCP), not in-process calls where avoidable. Service boundaries are clean: gateway is stateless (state in PG/Valkey), agent pool can scale independently, brain is a separate service. v0.1.0 runs single-node; the architecture doesn't fight horizontal scaling later.
@@ -205,25 +205,25 @@ Code is structured assuming eventual multi-node deployment with dedicated roles
 mosaic-mono-v1/
 ├── apps/
 │   ├── web/                    Next.js 16 web dashboard
-│   └── gateway/                @mosaic/gateway — NestJS API + WebSocket
+│   └── gateway/                @mosaicstack/gateway — NestJS API + WebSocket
 ├── packages/
-│   ├── types/                  @mosaic/types — shared type contracts
-│   ├── brain/                  @mosaic/brain — data layer (PG-backed)
-│   ├── queue/                  @mosaic/queue — Valkey task queue + MCP
-│   ├── coord/                  @mosaic/coord — mission coordination
-│   ├── mosaic/                 @mosaic/mosaic — install wizard
-│   ├── prdy/                   @mosaic/prdy — PRD wizard
-│   ├── quality-rails/          @mosaic/quality-rails — code quality scaffolder
-│   ├── cli/                    @mosaic/cli — unified CLI
-│   ├── auth/                   @mosaic/auth — BetterAuth config + SSO adapters
-│   ├── db/                     @mosaic/db — Drizzle schema, migrations, connection
-│   ├── agent/                  @mosaic/agent — Pi SDK integration, agent pool manager
-│   ├── memory/                 @mosaic/memory — tiered memory + summarization service
-│   ├── log/                    @mosaic/log — agent log ingest + processing
-│   └── design-tokens/          @mosaic/design-tokens — CSS vars, Tailwind preset, colors
+│   ├── types/                  @mosaicstack/types — shared type contracts
+│   ├── brain/                  @mosaicstack/brain — data layer (PG-backed)
+│   ├── queue/                  @mosaicstack/queue — Valkey task queue + MCP
+│   ├── coord/                  @mosaicstack/coord — mission coordination
+│   ├── mosaic/                 @mosaicstack/mosaic — install wizard
+│   ├── prdy/                   @mosaicstack/prdy — PRD wizard
+│   ├── quality-rails/          @mosaicstack/quality-rails — code quality scaffolder
+│   ├── cli/                    @mosaicstack/cli — unified CLI
+│   ├── auth/                   @mosaicstack/auth — BetterAuth config + SSO adapters
+│   ├── db/                     @mosaicstack/db — Drizzle schema, migrations, connection
+│   ├── agent/                  @mosaicstack/agent — Pi SDK integration, agent pool manager
+│   ├── memory/                 @mosaicstack/memory — tiered memory + summarization service
+│   ├── log/                    @mosaicstack/log — agent log ingest + processing
+│   └── design-tokens/          @mosaicstack/design-tokens — CSS vars, Tailwind preset, colors
 ├── plugins/
-│   ├── discord/                @mosaic/discord-plugin — Discord channel
-│   └── telegram/               @mosaic/telegram-plugin — Telegram channel
+│   ├── discord/                @mosaicstack/discord-plugin — Discord channel
+│   └── telegram/               @mosaicstack/telegram-plugin — Telegram channel
 ├── docker/
 │   ├── gateway.Dockerfile
 │   ├── web.Dockerfile
@@ -244,7 +244,7 @@ mosaic-mono-v1/

 ### Package Responsibilities

-#### `apps/gateway` — @mosaic/gateway (NEW — critical path)
+#### `apps/gateway` — @mosaicstack/gateway (NEW — critical path)

 The central nervous system. All clients connect here. Built with NestJS (Fastify adapter).

@@ -303,7 +303,7 @@ Carried forward from jarvis-old with significant refactoring.
 - User management (admin RBAC panel)
 - Auth pages (login, SSO redirect, registration)

-#### `packages/types` — @mosaic/types
+#### `packages/types` — @mosaicstack/types

 Migrated from mosaic-mono-v0. Extended with:

@@ -313,7 +313,7 @@ Migrated from mosaic-mono-v0. Extended with:
 - Memory types (preference, insight, summary)
 - Plugin channel types (Discord, Telegram message mapping)

-#### `packages/brain` — @mosaic/brain
+#### `packages/brain` — @mosaicstack/brain

 Migrated from mosaic-mono-v0. **Storage backend changes from JSON to PostgreSQL.**

@@ -324,7 +324,7 @@ Migrated from mosaic-mono-v0. **Storage backend changes from JSON to PostgreSQL.
 - New: computed endpoints (today, stale, stats, search, audit) run against PG
 - New: appreciation collection preserved for family use

-#### `packages/queue` — @mosaic/queue
+#### `packages/queue` — @mosaicstack/queue

 Migrated from mosaic-mono-v0 with minimal changes.

@@ -332,7 +332,7 @@ Migrated from mosaic-mono-v0 with minimal changes.
 - MCP server with 8 tools
 - Used by gateway for agent task dispatch and coordination

-#### `packages/coord` — @mosaic/coord
+#### `packages/coord` — @mosaicstack/coord

 Migrated from mosaic-mono-v0.

@@ -342,7 +342,7 @@ Migrated from mosaic-mono-v0.
 - Continuation prompt generation
 - Integration with gateway for mission-driven orchestration

-#### `packages/db` — @mosaic/db (NEW)
+#### `packages/db` — @mosaicstack/db (NEW)

 Shared database package.

@@ -351,7 +351,7 @@ Shared database package.
 - Connection pool configuration
 - Shared by gateway, brain, auth, memory

-#### `packages/auth` — @mosaic/auth (NEW)
+#### `packages/auth` — @mosaicstack/auth (NEW)

 Authentication and authorization.

@@ -361,7 +361,7 @@ Authentication and authorization.
 - API key generation for brain/MCP access
 - Session management middleware

-#### `packages/agent` — @mosaic/agent (NEW — critical path)
+#### `packages/agent` — @mosaicstack/agent (NEW — critical path)

 Pi SDK integration layer.

@@ -372,7 +372,7 @@ Pi SDK integration layer.
 - Skill management — loads and configures Pi skills for agent sessions
 - Session lifecycle — create, monitor, complete, fail, timeout

-#### `packages/memory` — @mosaic/memory (NEW)
+#### `packages/memory` — @mosaicstack/memory (NEW)

 Tiered memory system.

@@ -382,7 +382,7 @@ Tiered memory system.
 - Summarization pipeline — compress raw logs into structured insights
 - Memory API — used by gateway and agent sessions

-#### `packages/log` — @mosaic/log (NEW)
+#### `packages/log` — @mosaicstack/log (NEW)

 Agent log service.

@@ -392,7 +392,7 @@ Agent log service.
 - Summarization trigger — invokes cheap LLM to compress aging logs
 - Retention policy — configurable TTLs per tier

-#### `packages/mosaic` — @mosaic/mosaic
+#### `packages/mosaic` — @mosaicstack/mosaic

 Migrated from mosaic-mono-v0, updated for v1.

@@ -400,7 +400,7 @@ Migrated from mosaic-mono-v0, updated for v1.
 - Detects existing installations, offers upgrade path
 - Configures `~/.config/mosaic/` with guides, tools, runtime configs

-#### `packages/prdy` — @mosaic/prdy
+#### `packages/prdy` — @mosaicstack/prdy

 Migrated from mosaic-mono-v0.

@@ -408,7 +408,7 @@ Migrated from mosaic-mono-v0.
 - Template-based PRD creation with Zod validation
 - CLI integration via `mosaic prdy`

-#### `packages/quality-rails` — @mosaic/quality-rails
+#### `packages/quality-rails` — @mosaicstack/quality-rails

 Migrated from mosaic-mono-v0.

@@ -416,15 +416,15 @@ Migrated from mosaic-mono-v0.
 - Generates ESLint, tsconfig, Woodpecker, husky, lint-staged configs
 - Supports project types: monorepo, typescript-node, nextjs

-#### `packages/cli` — @mosaic/cli
+#### `packages/cli` — @mosaicstack/cli

 Migrated from mosaic-mono-v0, extended.

 - Unified `mosaic` binary
 - Subcommands: `mosaic coord`, `mosaic prdy`, `mosaic queue`, `mosaic quality`, `mosaic gateway`, `mosaic brain`
- Plugin discovery for installed @mosaic/\* packages
+- Plugin discovery for installed @mosaicstack/\* packages

-#### `plugins/discord` — @mosaic/discord-plugin (NEW — high priority)
+#### `plugins/discord` — @mosaicstack/discord-plugin (NEW — high priority)

 Discord remote control channel. Architecture inspired by OpenClaw (https://github.com/openclaw/openclaw).

@@ -436,7 +436,7 @@ Discord remote control channel. Architecture inspired by OpenClaw (https://githu
 - Bot pairing and permission management (Discord user → Mosaic user mapping)
 - DM support for private conversations

-#### `plugins/telegram` — @mosaic/telegram-plugin (NEW)
+#### `plugins/telegram` — @mosaicstack/telegram-plugin (NEW)

 Telegram remote control channel.

@@ -547,7 +547,7 @@ Telegram remote control channel.
 - WebSocket hub — real-time updates for chat, agent status, notifications
 - Rate limiting and request validation

-### FR-3: Agent Pool (@mosaic/agent)
+### FR-3: Agent Pool (@mosaicstack/agent)

 - Manage concurrent Pi SDK sessions
 - Provider configuration: API key management, endpoint URLs, model lists
@@ -582,7 +582,7 @@ Telegram remote control channel.
 - Mission CRUD (linked to project and PRD)
 - Mission tasks with phases, dependencies, ordering
 - Mission summary with computed progress
- Mission coordination via @mosaic/coord
+- Mission coordination via @mosaicstack/coord
 - Active mission dashboard in web UI

 ### FR-7: Memory System
@@ -844,7 +844,7 @@ Telegram remote control channel.
 - [ ] Database migrations run automatically on first start
 - [ ] `.env.example` documents all required configuration

-### AC-11: @mosaic/\* Packages
+### AC-11: @mosaicstack/\* Packages

 - [ ] All 7 migrated packages build, pass tests, and integrate with gateway
 - [ ] `mosaic` CLI provides subcommands for each package
@@ -870,7 +870,7 @@ Telegram remote control channel.

 | Risk                                               | Likelihood | Impact | Mitigation                                                                               |
 | -------------------------------------------------- | ---------- | ------ | ---------------------------------------------------------------------------------------- |
-| Pi SDK API instability (pre-1.0)                   | Medium     | High   | Pin version, abstract behind @mosaic/agent interface                                     |
+| Pi SDK API instability (pre-1.0)                   | Medium     | High   | Pin version, abstract behind @mosaicstack/agent interface                                |
 | Brain PG migration complexity                      | Medium     | Medium | Preserve Brain REST/MCP API contract; only storage changes                               |
 | Discord plugin complexity (OpenClaw has ~60 files) | Medium     | Medium | Start minimal (DM + mention in channel), single-guild only; expand iteratively post-beta |
 | LLM provider subscription auth varies by provider  | Medium     | Medium | Abstract behind provider interface; implement per-provider adapters                      |
@@ -882,7 +882,7 @@ Telegram remote control channel.

 | #   | Question                                                                 | Priority | Status                                                                                                                                                                                                       |
 | --- | ------------------------------------------------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 1   | Pi SDK version to pin for v0.1.0?                                        | High     | ✅ Resolved — Pin `@mariozechner/pi-coding-agent@~0.57.1` (current stable). Abstract behind `@mosaic/agent` interface to insulate from breaking changes. Bump deliberately after testing.                    |
+| 1   | Pi SDK version to pin for v0.1.0?                                        | High     | ✅ Resolved — Pin `@mariozechner/pi-coding-agent@~0.57.1` (current stable). Abstract behind `@mosaicstack/agent` interface to insulate from breaking changes. Bump deliberately after testing.               |
 | 2   | Authentik vs WorkOS vs Keycloak — which SSO provider to implement first? | Medium   | ✅ Resolved — Authentik first (already in Jason's infrastructure)                                                                                                                                            |
 | 3   | Vector DB: pgvector sufficient or need Qdrant from the start?            | Medium   | ✅ Resolved — pgvector with VectorStore interface abstraction. Qdrant drops in later if needed.                                                                                                              |
 | 4   | Summarization LLM: which model for log compression?                      | Medium   | ✅ Resolved — Haiku-tier default with structured output guardrails, configurable via routing engine.                                                                                                         |
@@ -910,9 +910,9 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
 ### Phase 0: Foundation (v0.0.1)

 - Scaffold monorepo (pnpm + turbo + tsconfig + eslint + vitest)
- `@mosaic/types` — migrate and extend from v0
- `@mosaic/db` — Drizzle schema, PG connection, migrations
- `@mosaic/auth` — BetterAuth setup with email/password
+- `@mosaicstack/types` — migrate and extend from v0
+- `@mosaicstack/db` — Drizzle schema, PG connection, migrations
+- `@mosaicstack/auth` — BetterAuth setup with email/password
 - OTEL foundation — `@opentelemetry/sdk-node` setup, SigNoz in docker-compose, trace propagation wired
 - Docker Compose (PG 17 + Valkey + SigNoz)
 - CI pipeline (Woodpecker)
@@ -921,19 +921,19 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.
 ### Phase 1: Core API (v0.0.2)

 - `apps/gateway` — NestJS server (Fastify adapter), auth middleware, health endpoints
- `@mosaic/brain` — migrate from v0, swap JSON store for PG via @mosaic/db
- `@mosaic/queue` — migrate from v0 (minimal changes)
+- `@mosaicstack/brain` — migrate from v0, swap JSON store for PG via @mosaicstack/db
+- `@mosaicstack/queue` — migrate from v0 (minimal changes)
 - Gateway routes: conversations, tasks, projects, missions
 - WebSocket server for chat streaming
 - Basic agent dispatch (single provider, no routing)

 ### Phase 2: Agent Layer (v0.0.3)

- `@mosaic/agent` — Pi SDK integration, agent pool manager
+- `@mosaicstack/agent` — Pi SDK integration, agent pool manager
 - Multi-provider support (Anthropic + Ollama minimum)
 - Agent routing engine (cost/capability matrix)
 - Tool registration (brain, queue, memory tools injected into agent sessions)
- `@mosaic/coord` — migrate from v0, integrate with gateway
+- `@mosaicstack/coord` — migrate from v0, integrate with gateway

 ### Phase 3: Web Dashboard (v0.0.4)

@@ -946,25 +946,25 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.

 ### Phase 4: Memory & Intelligence (v0.0.5)

- `@mosaic/memory` — preference store, insight store, semantic search
- `@mosaic/log` — log ingest, parsing, tiered storage
+- `@mosaicstack/memory` — preference store, insight store, semantic search
+- `@mosaicstack/log` — log ingest, parsing, tiered storage
 - Summarization pipeline
 - Memory integration into agent sessions
 - Skill management interface (web UI + CLI)

 ### Phase 5: Remote Control (v0.0.6)

- `@mosaic/discord-plugin` — Discord channel plugin
- `@mosaic/telegram-plugin` — Telegram channel plugin
+- `@mosaicstack/discord-plugin` — Discord channel plugin
+- `@mosaicstack/telegram-plugin` — Telegram channel plugin
 - Plugin host in gateway
 - SSO configuration (Authentik)

 ### Phase 6: CLI & Tools (v0.0.7)

- `@mosaic/cli` — unified CLI with all subcommands
- `@mosaic/prdy` — migrate from v0
- `@mosaic/quality-rails` — migrate from v0
- `@mosaic/mosaic` — install wizard updated for v1
+- `@mosaicstack/cli` — unified CLI with all subcommands
+- `@mosaicstack/prdy` — migrate from v0
+- `@mosaicstack/quality-rails` — migrate from v0
+- `@mosaicstack/mosaic` — install wizard updated for v1
 - Pi TUI integration (`mosaic tui`)

 ### Phase 7: Polish & Beta (v0.0.8 → v0.1.0)
@@ -982,11 +982,11 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.

 ## Assumptions

-1. RESOLVED: **pgvector is sufficient** for semantic search at v0.1.0 scale (personal/family/team = thousands to low hundreds-of-thousands of vectors). `@mosaic/memory` defines a `VectorStore` interface with pgvector as the default adapter. The interface boundary makes Qdrant a drop-in migration if PG resource contention or scale demands it later. Zero additional infrastructure for v0.1.0. Rationale: Reduces ops burden; pgvector HNSW indexes are fast at this scale; interface abstraction costs almost nothing now.
+1. RESOLVED: **pgvector is sufficient** for semantic search at v0.1.0 scale (personal/family/team = thousands to low hundreds-of-thousands of vectors). `@mosaicstack/memory` defines a `VectorStore` interface with pgvector as the default adapter. The interface boundary makes Qdrant a drop-in migration if PG resource contention or scale demands it later. Zero additional infrastructure for v0.1.0. Rationale: Reduces ops burden; pgvector HNSW indexes are fast at this scale; interface abstraction costs almost nothing now.

 2. RESOLVED: **Authentik is the first SSO provider** — confirmed, already running in Jason's infrastructure. WorkOS and Keycloak adapters follow in Phase 7.

-3. RESOLVED: **NestJS with Fastify adapter for the gateway.** The gateway's complexity (plugin host, agent pool, routing engine, WebSocket hub, MCP server, auth, brain/queue/memory/log integration) warrants NestJS's module system, DI, and guards. Fastify performance preserved via adapter. Aligns with USER.md stated stack ("NestJS API + Next.js web"). @mosaic/brain's Fastify code migrates into a NestJS module.
+3. RESOLVED: **NestJS with Fastify adapter for the gateway.** The gateway's complexity (plugin host, agent pool, routing engine, WebSocket hub, MCP server, auth, brain/queue/memory/log integration) warrants NestJS's module system, DI, and guards. Fastify performance preserved via adapter. Aligns with USER.md stated stack ("NestJS API + Next.js web"). @mosaicstack/brain's Fastify code migrates into a NestJS module.

 4. RESOLVED: **OpenTelemetry from Phase 0.** Wide-event logging is required from the start. OTEL auto-instrumentation for NestJS/PG/HTTP via `@opentelemetry/sdk-node`. SigNoz as the all-in-one OTEL backend (single Docker service). Every significant operation emits structured events with rich context. Custom spans for agent dispatch, routing decisions, memory writes. Rationale: Retrofitting observability is painful; baking it in from day one means consistent instrumentation across all services.

@@ -1002,4 +1002,4 @@ All work is **alpha** (< 0.1.0) until Jason approves 0.1.0 beta release.

 10. ASSUMPTION: **Conversations and messages get their own PG tables** (not stored in brain's entity model). They follow a chat-specific schema with proper foreign keys to users and projects. Rationale: Chat has different access patterns (streaming, pagination, search) than brain entities.

-11. RESOLVED: **Pi handles all target LLM providers natively.** Anthropic, OpenAI/Codex, Z.ai, Ollama, LM Studio, and llama.cpp are all supported via Pi's built-in providers or `models.json` configuration with `openai-completions` API type. No custom provider adapters needed in @mosaic/agent — only configuration management.
+11. RESOLVED: **Pi handles all target LLM providers natively.** Anthropic, OpenAI/Codex, Z.ai, Ollama, LM Studio, and llama.cpp are all supported via Pi's built-in providers or `models.json` configuration with `openai-completions` API type. No custom provider adapters needed in @mosaicstack/agent — only configuration management.
--- a/docs/SSO-PROVIDERS.md
+++ b/docs/SSO-PROVIDERS.md
@@ -108,4 +108,4 @@ The web login page renders provider buttons from `NEXT_PUBLIC_*_ENABLED` flags.

 ## Failure mode

-Provider config is optional, but partial config is rejected at startup. If any provider-specific env var is present without the full required set, `@mosaic/auth` throws a bootstrap error with the missing keys instead of silently registering a broken provider.
+Provider config is optional, but partial config is rejected at startup. If any provider-specific env var is present without the full required set, `@mosaicstack/auth` throws a bootstrap error with the missing keys instead of silently registering a broken provider.
--- a/docs/TASKS-TUI_Improvements.md
+++ b/docs/TASKS-TUI_Improvements.md
@@ -91,15 +91,15 @@ packages/cli/src/tui/

 ```bash
 cd /home/jwoltje/src/mosaic-mono-v1-worktrees/tui-improvements
-pnpm --filter @mosaic/cli exec tsx src/cli.ts tui
+pnpm --filter @mosaicstack/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

 ```bash
-pnpm --filter @mosaic/cli typecheck && pnpm --filter @mosaic/cli lint
-pnpm --filter @mosaic/gateway typecheck && pnpm --filter @mosaic/gateway lint
-pnpm --filter @mosaic/types typecheck
+pnpm --filter @mosaicstack/cli typecheck && pnpm --filter @mosaicstack/cli lint
+pnpm --filter @mosaicstack/gateway typecheck && pnpm --filter @mosaicstack/gateway lint
+pnpm --filter @mosaicstack/types typecheck
 ```
--- a/docs/TASKS.md
+++ b/docs/TASKS.md
@@ -1,30 +1,90 @@
-# Tasks — Storage Abstraction Retrofit
+# Tasks — CLI Unification & E2E First-Run

 > 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)
+> **Mission:** cli-unification-20260404
+> **Schema:** `| id | status | description | issue | agent | branch | depends_on | estimate | notes |`
+> **Status values:** `not-started` | `in-progress` | `done` | `blocked` | `failed` | `needs-qa`
+> **Agent values:** `codex` | `sonnet` | `haiku` | `opus` | `glm-5` | `—` (auto)

-| 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          | —      |
+## Milestone 1 — Kill legacy @mosaicstack/cli (done)
+
+| id       | status | description                                                       | issue | agent | branch                             | depends_on | estimate | notes                       |
+| -------- | ------ | ----------------------------------------------------------------- | ----- | ----- | ---------------------------------- | ---------- | -------- | --------------------------- |
+| CU-01-01 | done   | Delete packages/cli directory; update workspace + docs references | #398  | opus  | chore/remove-cli-package-duplicate | —          | 5K       | Merged c39433c3. 6685 LOC−. |
+
+## Milestone 2 — Archive stale mission + scaffold new mission (done)
+
+| id       | status | description                                                        | issue | agent | branch                       | depends_on | estimate | notes                             |
+| -------- | ------ | ------------------------------------------------------------------ | ----- | ----- | ---------------------------- | ---------- | -------- | --------------------------------- |
+| CU-02-01 | done   | Move stale MISSION-MANIFEST / TASKS / PRD-Harness to docs/archive/ | #399  | opus  | docs/mission-cli-unification | CU-01-01   | 3K       | Harness + storage missions done.  |
+| CU-02-02 | done   | Scaffold new MISSION-MANIFEST.md, TASKS.md, scratchpad             | #399  | opus  | docs/mission-cli-unification | CU-02-01   | 5K       | This file + manifest + scratchpad |
+| CU-02-03 | done   | PR review, merge, branch cleanup                                   | #399  | opus  | docs/mission-cli-unification | CU-02-02   | 2K       | Merged as 6f15a84c                |
+
+## Milestone 3 — Gateway bootstrap token recovery
+
+| id       | status      | description                                                                                    | issue | agent  | branch | depends_on | estimate | notes                         |
+| -------- | ----------- | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----------------------------- |
+| CU-03-01 | not-started | Implementation plan for BetterAuth-cookie recovery flow (decision locked 2026-04-04)           | —     | opus   | —      | CU-02-03   | 4K       | Design locked; plan-only task |
+| CU-03-02 | not-started | Server: add recovery/rotate endpoint on apps/gateway/src/admin (gated by design from CU-03-01) | —     | sonnet | —      | CU-03-01   | 12K      |                               |
+| CU-03-03 | not-started | CLI: `mosaic gateway login` — interactive BetterAuth sign-in, persist session                  | —     | sonnet | —      | CU-03-02   | 10K      |                               |
+| CU-03-04 | not-started | CLI: `mosaic gateway config rotate-token` — mint new admin token via authenticated API         | —     | sonnet | —      | CU-03-03   | 8K       |                               |
+| CU-03-05 | not-started | CLI: `mosaic gateway config recover-token` — execute the recovery flow from CU-03-01           | —     | sonnet | —      | CU-03-03   | 10K      |                               |
+| CU-03-06 | not-started | Install UX: fix the "user exists, no token" dead-end in runInstall bootstrapFirstUser path     | —     | sonnet | —      | CU-03-05   | 8K       |                               |
+| CU-03-07 | not-started | Tests: integration tests for each recovery path (happy + error)                                | —     | sonnet | —      | CU-03-06   | 10K      |                               |
+| CU-03-08 | not-started | Code review + remediation                                                                      | —     | haiku  | —      | CU-03-07   | 4K       |                               |
+
+## Milestone 4 — `mosaic --help` alphabetize + grouping
+
+| id       | status      | description                                                                                                                                                                                                     | issue | agent  | branch | depends_on | estimate | notes                           |
+| -------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------------------- |
+| CU-04-01 | not-started | Enable `configureHelp({ sortSubcommands: true })` on root program and each subgroup                                                                                                                             | —     | sonnet | —      | CU-02-03   | 3K       |                                 |
+| CU-04-02 | not-started | Group commands into sections (Runtime, Gateway, Framework, Platform) in help output                                                                                                                             | —     | sonnet | —      | CU-04-01   | 5K       |                                 |
+| CU-04-03 | not-started | Verify help snapshots render readably; update any docs with stale output                                                                                                                                        | —     | haiku  | —      | CU-04-02   | 3K       |                                 |
+| CU-04-04 | not-started | Top-level `mosaic config` command — `show`, `get <key>`, `set <key> <val>`, `edit`, `path` — wraps packages/mosaic/src/config/config-service.ts (framework/agent config; distinct from `mosaic gateway config`) | —     | sonnet | —      | CU-02-03   | 10K      | New scope (decision 2026-04-04) |
+| CU-04-05 | not-started | Tests + code review for CU-04-04                                                                                                                                                                                | —     | haiku  | —      | CU-04-04   | 4K       |                                 |
+
+## Milestone 5 — Sub-package CLI surface
+
+> Pattern: each sub-package exports `register<Name>Command(program: Command)` co-located with the library code (proven by `@mosaicstack/quality-rails`). Wire into `packages/mosaic/src/cli.ts`.
+
+| id       | status      | description                                                                                               | issue | agent  | branch | depends_on | estimate | notes               |
+| -------- | ----------- | --------------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ------------------- |
+| CU-05-01 | not-started | `mosaic forge` — subcommands: `run`, `status`, `resume`, `personas list`                                  | —     | sonnet | —      | CU-02-03   | 18K      | User priority       |
+| CU-05-02 | not-started | `mosaic storage` — subcommands: `status`, `tier show`, `tier switch`, `export`, `import`, `migrate`       | —     | sonnet | —      | CU-02-03   | 15K      |                     |
+| CU-05-03 | not-started | `mosaic queue` — subcommands: `list`, `stats`, `pause/resume`, `jobs tail`, `drain`                       | —     | sonnet | —      | CU-02-03   | 12K      |                     |
+| CU-05-04 | not-started | `mosaic memory` — subcommands: `search`, `stats`, `insights list`, `preferences list`                     | —     | sonnet | —      | CU-02-03   | 12K      |                     |
+| CU-05-05 | not-started | `mosaic brain` — subcommands: `projects list/create`, `missions list`, `tasks list`, `conversations list` | —     | sonnet | —      | CU-02-03   | 15K      |                     |
+| CU-05-06 | not-started | `mosaic auth` — subcommands: `users list/create/delete`, `sso list`, `sso test`, `sessions list`          | —     | sonnet | —      | CU-03-03   | 15K      | needs gateway login |
+| CU-05-07 | not-started | `mosaic log` — subcommands: `tail`, `search`, `export`, `level <level>`                                   | —     | sonnet | —      | CU-02-03   | 10K      |                     |
+| CU-05-08 | not-started | `mosaic macp` — subcommands: `tasks list`, `submit`, `gate`, `events tail`                                | —     | sonnet | —      | CU-02-03   | 12K      |                     |
+| CU-05-09 | not-started | Wire all eight `register<Name>Command` calls into packages/mosaic/src/cli.ts                              | —     | haiku  | —      | CU-05-01…8 | 3K       |                     |
+| CU-05-10 | not-started | Integration test: `mosaic <cmd> --help` exits 0 for every new command                                     | —     | haiku  | —      | CU-05-09   | 5K       |                     |
+
+## Milestone 6 — `mosaic telemetry`
+
+| id       | status      | description                                                                                       | issue | agent  | branch | depends_on | estimate | notes                                          |
+| -------- | ----------- | ------------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ---------------------------------------------- |
+| CU-06-01 | not-started | Add `@mosaicstack/telemetry-client-js` as dependency of `@mosaicstack/mosaic` from Gitea registry | —     | sonnet | —      | CU-02-03   | 3K       |                                                |
+| CU-06-02 | not-started | `mosaic telemetry local` — status, tail, Jaeger link (wraps existing apps/gateway/src/tracing.ts) | —     | sonnet | —      | CU-06-01   | 8K       |                                                |
+| CU-06-03 | not-started | `mosaic telemetry` — status, opt-in, opt-out, test, upload (uses telemetry-client-js)             | —     | sonnet | —      | CU-06-01   | 12K      | Dry-run mode when server endpoint not yet live |
+| CU-06-04 | not-started | Persistent consent state in mosaic config; disabled by default                                    | —     | sonnet | —      | CU-06-03   | 5K       |                                                |
+| CU-06-05 | not-started | Tests + code review                                                                               | —     | haiku  | —      | CU-06-04   | 5K       |                                                |
+
+## Milestone 7 — Unified first-run UX
+
+| id       | status      | description                                                                                    | issue | agent  | branch | depends_on | estimate | notes |
+| -------- | ----------- | ---------------------------------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
+| CU-07-01 | not-started | tools/install.sh: after npm install, hand off to `mosaic wizard` then `mosaic gateway install` | —     | sonnet | —      | CU-03-06   | 10K      |       |
+| CU-07-02 | not-started | `mosaic wizard` and `mosaic gateway install` coordination: shared state, no duplicate prompts  | —     | sonnet | —      | CU-07-01   | 12K      |       |
+| CU-07-03 | not-started | Post-install verification step: "gateway healthy, tui connects, admin token on file"           | —     | sonnet | —      | CU-07-02   | 8K       |       |
+| CU-07-04 | not-started | End-to-end test on a clean container from scratch                                              | —     | haiku  | —      | CU-07-03   | 8K       |       |
+
+## Milestone 8 — Docs + release
+
+| id       | status      | description                                                            | issue | agent  | branch | depends_on | estimate | notes |
+| -------- | ----------- | ---------------------------------------------------------------------- | ----- | ------ | ------ | ---------- | -------- | ----- |
+| CU-08-01 | not-started | Update README.md with new command tree, install flow, and feature list | —     | sonnet | —      | CU-07-04   | 8K       |       |
+| CU-08-02 | not-started | Update docs/guides/user-guide.md with all new sub-package commands     | —     | sonnet | —      | CU-08-01   | 10K      |       |
+| CU-08-03 | not-started | Version bump `@mosaicstack/mosaic`, publish to Gitea registry          | —     | opus   | —      | CU-08-02   | 3K       |       |
+| CU-08-04 | not-started | Release notes, tag `v0.1.0-rc.N`, publish release on Gitea             | —     | opus   | —      | CU-08-03   | 3K       |       |
--- a/docs/archive/missions/harness-20260321/MISSION-MANIFEST.md
+++ b/docs/archive/missions/harness-20260321/MISSION-MANIFEST.md
@@ -0,0 +1,70 @@
+# Mission Manifest — Harness Foundation
+
+> Persistent document tracking full mission scope, status, and session history.
+> Updated by the orchestrator at each phase transition and milestone completion.
+
+## Mission
+
+**ID:** harness-20260321
+**Statement:** Transform Mosaic Stack from a functional demo into a real multi-provider, task-routing AI harness. Persist all conversations, integrate frontier LLM providers (Anthropic, OpenAI, OpenRouter, Z.ai, Ollama), build granular task-aware agent routing, harden agent sessions, replace cron with BullMQ, and design the channel protocol for future Matrix/remote integration.
+**Phase:** Complete
+**Current Milestone:** All milestones done
+**Progress:** 7 / 7 milestones
+**Status:** complete
+**Last Updated:** 2026-03-22 UTC
+
+## Success Criteria
+
+- [x] AC-1: Send messages in TUI → restart TUI → resume conversation → agent has full history and context
+- [x] AC-2: Route a coding task to Claude Opus 4.6, a simple question to Haiku, a summarization to GLM-5 — all via granular routing rules
+- [x] AC-3: Two users exist, User A's memory searches never return User B's data
+- [x] AC-4: `/model claude-sonnet-4-6` in TUI switches the active model for subsequent messages
+- [x] AC-5: `/agent coding-agent` in TUI switches to a different agent with different system prompt and tools
+- [x] AC-6: BullMQ jobs execute on schedule, failures retry with backoff, admin can inspect via `/api/admin/jobs`
+- [x] AC-7: Channel protocol document exists with Matrix integration points defined, reviewed, and approved
+- [x] AC-8: Embeddings run on Ollama local models (no external API dependency for vector operations)
+- [x] AC-9: All five providers (Anthropic, OpenAI, OpenRouter, Z.ai, Ollama) connect, list models, and complete chat requests
+- [x] AC-10: Routing transparency — TUI displays which model was selected and the routing reason for each response
+
+## Milestones
+
+| #   | ID     | Name                               | Status | Branch | Issue     | Started    | Completed  |
+| --- | ------ | ---------------------------------- | ------ | ------ | --------- | ---------- | ---------- |
+| 1   | ms-166 | Conversation Persistence & Context | done   | —      | #224–#231 | 2026-03-21 | 2026-03-21 |
+| 2   | ms-167 | Security & Isolation               | done   | —      | #232–#239 | 2026-03-21 | 2026-03-21 |
+| 3   | ms-168 | Provider Integration               | done   | —      | #240–#251 | 2026-03-21 | 2026-03-22 |
+| 4   | ms-169 | Agent Routing Engine               | done   | —      | #252–#264 | 2026-03-22 | 2026-03-22 |
+| 5   | ms-170 | Agent Session Hardening            | done   | —      | #265–#272 | 2026-03-22 | 2026-03-22 |
+| 6   | ms-171 | Job Queue Foundation               | done   | —      | #273–#280 | 2026-03-22 | 2026-03-22 |
+| 7   | ms-172 | Channel Protocol Design            | done   | —      | #281–#288 | 2026-03-22 | 2026-03-22 |
+
+## Deployment
+
+| Target               | URL       | Method                     |
+| -------------------- | --------- | -------------------------- |
+| Docker Compose (dev) | localhost | docker compose up          |
+| Production           | TBD       | Docker Swarm via Portainer |
+
+## Coordination
+
+- **Primary Agent:** claude-opus-4-6
+- **Sibling Agents:** sonnet (workers), haiku (verification)
+- **Shared Contracts:** docs/PRD-Harness_Foundation.md, docs/TASKS.md
+
+## Token Budget
+
+| Metric | Value  |
+| ------ | ------ |
+| Budget | —      |
+| Used   | ~2.5M  |
+| Mode   | normal |
+
+## Session History
+
+| Session | Runtime         | Started    | Duration | Ended Reason | Last Task         |
+| ------- | --------------- | ---------- | -------- | ------------ | ----------------- |
+| 1       | claude-opus-4-6 | 2026-03-21 | ~6h      | complete     | M7-008 — all done |
+
+## Scratchpad
+
+Path: `docs/scratchpads/harness-20260321.md`
--- a/docs/archive/missions/harness-20260321/PRD.md
+++ b/docs/archive/missions/harness-20260321/PRD.md
--- a/docs/archive/missions/storage-abstraction/TASKS.md
+++ b/docs/archive/missions/storage-abstraction/TASKS.md
@@ -0,0 +1,30 @@
+# 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  | 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 @mosaicstack/queue: wrap ioredis as BullMQ adapter      | 3K     |
+| SA-P2-002 | done        | sonnet | Create @mosaicstack/storage: wrap Drizzle as Postgres adapter    | 6K     |
+| SA-P2-003 | done        | sonnet | Refactor @mosaicstack/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          | —      |
--- a/docs/design/storage-abstraction-middleware.md
+++ b/docs/design/storage-abstraction-middleware.md
@@ -12,9 +12,9 @@ context: Agents coupled directly to infrastructure backends, bypassing intended
 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 |
+| `@mosaicstack/queue` | `ioredis` hardcoded | Interface → BullMQ OR local-files |
+| `@mosaicstack/db` | Drizzle + Postgres hardcoded | Interface → Postgres OR SQLite OR JSON/MD |
+| `@mosaicstack/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.

@@ -46,15 +46,15 @@ The gateway imports the interface, not the backend. At startup it reads config a

 ```typescript
 // What should have happened:
-gateway/queue.service.ts → @mosaic/queue (interface) → queue.adapter.ts
+gateway/queue.service.ts → @mosaicstack/queue (interface) → queue.adapter.ts

 // What actually happened:
-gateway/queue.service.ts → @mosaic/queue → ioredis (hardcoded)
+gateway/queue.service.ts → @mosaicstack/queue → ioredis (hardcoded)
 ```

 ## The Current State Analysis

-### `@mosaic/queue` (packages/queue/src/queue.ts)
+### `@mosaicstack/queue` (packages/queue/src/queue.ts)

 ```typescript
 import Redis from 'ioredis'; // ← Direct import of backend
@@ -68,7 +68,7 @@ export function createQueue(config?: QueueConfig): QueueHandle {

 **Problem:** `ioredis` is imported in the package, not the adapter interface. Consumers cannot swap backends.

-### `@mosaic/db` (packages/db/src/client.ts)
+### `@mosaicstack/db` (packages/db/src/client.ts)

 ```typescript
 import { drizzle, type PostgresJsDatabase } from 'drizzle-orm/postgres-js';
@@ -84,10 +84,10 @@ export function createDb(url?: string): DbHandle {

 **Problem:** Drizzle + Postgres is hardcoded. No SQLite, JSON, or file-based options.

-### `@mosaic/memory` (packages/memory/src/memory.ts)
+### `@mosaicstack/memory` (packages/memory/src/memory.ts)

 ```typescript
-import type { Db } from '@mosaic/db'; // ← Depends on Drizzle/PG
+import type { Db } from '@mosaicstack/db'; // ← Depends on Drizzle/PG

 export function createMemory(db: Db): Memory {
  return {
@@ -97,7 +97,7 @@ export function createMemory(db: Db): Memory {
 }
 ```

-**Problem:** Memory package is tightly coupled to `@mosaic/db` (which is Postgres-only). No alternative storage backends.
+**Problem:** Memory package is tightly coupled to `@mosaicstack/db` (which is Postgres-only). No alternative storage backends.

 ## The Target Interfaces

@@ -361,7 +361,7 @@ Automated equivalent to Claude Code's "Dream: Memory Consolidation" cycle
 **Implementation:**

 ```typescript
-// In @mosaic/dream (new package)
+// In @mosaicstack/dream (new package)
 export async function runDreamCycle(config: DreamConfig): Promise<DreamResult> {
  const memory = await loadMemoryAdapter(config.storage);

@@ -420,7 +420,7 @@ export async function runDreamCycle(config: DreamConfig): Promise<DreamResult> {
 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
+5. Deprecate direct `@mosaicstack/db` imports

 #### 2.3 Memory Refactor

@@ -488,7 +488,7 @@ packages/
 │   │   ├── types.ts           # StorageAdapter interface
 │   │   ├── index.ts           # Factory function
 │   │   └── adapters/
-│   │       ├── postgres.ts    # MOVED from @mosaic/db
+│   │       ├── postgres.ts    # MOVED from @mosaicstack/db
 │   │       ├── sqlite.ts      # NEW: SQLite adapter
 │   │       └── files.ts       # NEW: JSON/MD adapter
 │   └── package.json
@@ -530,9 +530,9 @@ packages/

 ## 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
+1. **`@mosaicstack/db`** → **`@mosaicstack/storage`** (with migration guide)
+2. Direct `ioredis` imports → Use `@mosaicstack/queue` factory
+3. Direct `pgvector` queries → Use `@mosaicstack/memory` factory
 4. Gateway startup now requires storage config (defaults to local)

 ## Non-Breaking Migration Path
--- a/docs/guides/admin-guide.md
+++ b/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

--- a/docs/guides/deployment.md
+++ b/docs/guides/deployment.md
@@ -61,7 +61,7 @@ pnpm install
 ### 4. Initialize the database

 ```bash
-pnpm --filter @mosaic/db db:migrate
+pnpm --filter @mosaicstack/db db:migrate
 ```

 ### 5. Build all packages
@@ -73,7 +73,7 @@ pnpm build
 ### 6. Start the gateway

 ```bash
-pnpm --filter @mosaic/gateway dev
+pnpm --filter @mosaicstack/gateway dev
 ```

 Or for production (after build):
@@ -86,10 +86,10 @@ node apps/gateway/dist/main.js

 ```bash
 # Development
-pnpm --filter @mosaic/web dev
+pnpm --filter @mosaicstack/web dev

 # Production (after build)
-pnpm --filter @mosaic/web start
+pnpm --filter @mosaicstack/web start
 ```

 The web app runs on port `3000` by default.
@@ -157,7 +157,7 @@ pnpm build
 ### Step 5 — Run database migrations

 ```bash
-pnpm --filter @mosaic/db db:migrate
+pnpm --filter @mosaicstack/db db:migrate
 ```

 ### Step 6 — Start the gateway
@@ -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.

--- a/docs/guides/dev-guide.md
+++ b/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
@@ -129,7 +129,7 @@ The gateway loads `.env` from the monorepo root via `dotenv` at startup
 ### 4. Push the Database Schema

 ```bash
-pnpm --filter @mosaic/db db:push
+pnpm --filter @mosaicstack/db db:push
 ```

 This applies the Drizzle schema directly to the database (development only; use
@@ -138,15 +138,15 @@ migrations in production).
 ### 5. Start the Gateway

 ```bash
-pnpm --filter @mosaic/gateway exec tsx src/main.ts
+pnpm --filter @mosaicstack/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

 ```bash
-pnpm --filter @mosaic/web dev
+pnpm --filter @mosaicstack/web dev
 ```

 The web app starts on port `3000` by default.
@@ -359,7 +359,7 @@ The `insights` table uses a `vector(1536)` column (pgvector) for semantic search
 Apply schema changes directly to the dev database (no migration files created):

 ```bash
-pnpm --filter @mosaic/db db:push
+pnpm --filter @mosaicstack/db db:push
 ```

 ### Generating Migrations
@@ -367,7 +367,7 @@ pnpm --filter @mosaic/db db:push
 For production-safe, versioned changes:

 ```bash
-pnpm --filter @mosaic/db db:generate
+pnpm --filter @mosaicstack/db db:generate
 ```

 This creates a new SQL migration file in `packages/db/drizzle/`.
@@ -375,7 +375,7 @@ This creates a new SQL migration file in `packages/db/drizzle/`.
 ### Running Migrations

 ```bash
-pnpm --filter @mosaic/db db:migrate
+pnpm --filter @mosaicstack/db db:migrate
 ```

 ### Drizzle Config
@@ -387,15 +387,15 @@ directory are defined there.

 1. Add the table definition to `packages/db/src/schema.ts`.
 2. Export it from `packages/db/src/index.ts`.
-3. Run `pnpm --filter @mosaic/db db:push` (dev) or
-   `pnpm --filter @mosaic/db db:generate && pnpm --filter @mosaic/db db:migrate`
+3. Run `pnpm --filter @mosaicstack/db db:push` (dev) or
+   `pnpm --filter @mosaicstack/db db:generate && pnpm --filter @mosaicstack/db db:migrate`
   (production).

 ---

 ## 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

--- a/docs/guides/user-guide.md
+++ b/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)

@@ -160,12 +160,12 @@ The `mosaic` CLI provides a terminal interface to the same gateway API.

 ### Installation

-The CLI ships as part of the `@mosaic/cli` package:
+The CLI ships as part of the `@mosaicstack/mosaic` package:

 ```bash
 # From the monorepo root
-pnpm --filter @mosaic/cli build
-node packages/cli/dist/cli.js --help
+pnpm --filter @mosaicstack/mosaic build
+node packages/mosaic/dist/cli.js --help
 ```

 Or if installed globally:
@@ -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`) |
--- a/docs/plans/2026-03-13-gateway-security-hardening.md
+++ b/docs/plans/2026-03-13-gateway-security-hardening.md
@@ -23,7 +23,7 @@

 **Step 2: Run test to verify it fails**

-Run: `pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`
+Run: `pnpm --filter @mosaicstack/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`

 Expected: FAIL on current DTO/helper mismatch.

@@ -56,7 +56,7 @@ Run the same command and require green.

 **Step 3: Run targeted tests**

-Run: `pnpm --filter @mosaic/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`
+Run: `pnpm --filter @mosaicstack/gateway test -- src/chat/__tests__/chat-security.test.ts src/__tests__/resource-ownership.test.ts`

 Expected: PASS.

--- a/Show More
+++ b/Show More
Author	SHA1	Message	Date
Jarvis	9b5ecc0171	feat(mosaic): add auth command and stage parallel agent changes All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details Picks up auth command and spec written by parallel agent, and updated mosaic cli.ts wiring from parallel development during cli-unification. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-05 00:58:03 -05:00
Jarvis	a00325da0e	feat(forge): add registerForgeCommand for mosaic forge CLI surface Adds mosaic forge run\|status\|resume\|personas list subcommands to @mosaicstack/forge, wires registerForgeCommand into the root mosaic CLI, and ships a smoke test asserting command structure. Ref CU-05-01 cli-unification-20260404. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>	2026-04-05 00:58:03 -05:00
jason.woltje	4ebce3422d	feat(log): mosaic log CLI surface (#407 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 05:57:22 +00:00
jason.woltje	751e0ee330	feat(storage): mosaic storage CLI surface (#405 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 05:48:13 +00:00
jason.woltje	54b2920ef3	feat(memory): mosaic memory CLI surface (#406 ) Some checks failed ci/woodpecker/push/ci Pipeline failed Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 05:44:06 +00:00
jason.woltje	5917016509	feat(mosaic): gateway token recovery via BetterAuth cookie (#411 ) Some checks are pending ci/woodpecker/push/ci Pipeline is pending Details ci/woodpecker/push/publish Pipeline is pending Details	2026-04-05 05:43:49 +00:00
jason.woltje	7b4f1d249d	feat(mosaic): top-level mosaic config command (#408 ) Some checks failed ci/woodpecker/push/publish Pipeline failed Details ci/woodpecker/push/ci Pipeline failed Details	2026-04-05 05:37:05 +00:00
jason.woltje	5425f9268e	feat(queue): mosaic queue CLI surface (#404 ) Some checks failed ci/woodpecker/push/publish Pipeline failed Details ci/woodpecker/push/ci Pipeline failed Details	2026-04-05 05:27:59 +00:00
jason.woltje	febd866098	feat(brain): mosaic brain CLI surface (#403 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 05:20:44 +00:00
jason.woltje	2446593fff	feat(mosaic): alphabetize and group mosaic --help output (#402 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 05:12:32 +00:00
jason.woltje	651426cf2e	docs(plan): gateway admin token recovery flow (#401 ) Some checks failed ci/woodpecker/push/publish Pipeline failed Details ci/woodpecker/push/ci Pipeline failed Details	2026-04-05 05:11:33 +00:00
jason.woltje	cf46f6e0ae	docs: capture planning decisions + session 1 handoff (#400 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 04:57:00 +00:00
jason.woltje	6f15a84ccf	docs: archive stale mission, scaffold CLI unification mission (#399 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 04:47:54 +00:00
jason.woltje	c39433c361	chore: remove legacy @mosaicstack/cli package (#398 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 04:39:46 +00:00
jason.woltje	257796ce87	Merge pull request 'chore: bump @mosaicstack/mosaic to 0.0.21 for republish' (#397 ) from chore/bump-mosaic-0.0.21 into main All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 04:12:05 +00:00
Jarvis	2357602f50	chore: bump @mosaicstack/mosaic to 0.0.21 for publish All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details	2026-04-04 23:09:52 -05:00
jason.woltje	1230f6b984	ci: fail publish pipeline loudly on registry/auth/network errors (#396 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 03:58:35 +00:00
jason.woltje	14b775f1b9	Merge pull request 'fix: populate KNOWN_PACKAGES for mosaic update command' (#395 ) from fix/populate-known-packages-list into main Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details Reviewed-on: mosaicstack/mosaic-stack#395	2026-04-05 03:52:57 +00:00
Jarvis	c7691d9807	fix: populate KNOWN_PACKAGES with all workspace packages for 'mosaic update' All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details - Remove @mosaicstack/cli (absorbed into @mosaicstack/mosaic) - Add all 21 remaining workspace packages so the multi-package update checker actually covers every published package	2026-04-04 22:49:45 -05:00
jason.woltje	9a53d55678	Merge pull request 'fix: update Gitea org references from mosaic/ to mosaicstack/' (#394 ) from fix/gitea-org-rename into main All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details Reviewed-on: mosaicstack/mosaic-stack#394	2026-04-05 03:35:11 +00:00
Jarvis	31008ef7ff	fix: update Gitea org references from mosaic/ to mosaicstack/ All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details - Update all package.json repo URLs (mosaic/mosaic-stack → mosaicstack/mosaic-stack) - Update npm registry URLs (/api/packages/mosaic/npm → /api/packages/mosaicstack/npm) - Update woodpecker publish destinations - Update tools/install.sh registry and repo base URLs	2026-04-04 22:31:20 -05:00
jason.woltje	621ab260c0	fix(mosaic): resumable gateway install + prominent admin token (#393 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details ci/woodpecker/manual/publish Pipeline failed Details ci/woodpecker/manual/ci Pipeline failed Details	2026-04-05 03:19:07 +00:00
jason.woltje	2b1840214e	Merge pull request 'fix: rename @mosaic/* packages to @mosaicstack/*' (#392 ) from fix/rename-mosaic-scope-391 into main Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 03:11:55 +00:00
Jarvis	5cfccc2ead	fix(mosaic): remove unused hasUpdate variable in formatAllPackagesTable All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details Fixes lint error: @typescript-eslint/no-unused-vars on hasUpdate	2026-04-04 22:01:01 -05:00
Jarvis	774b76447d	fix: rename all packages from @mosaic/* to @mosaicstack/* Some checks failed ci/woodpecker/pr/ci Pipeline failed Details ci/woodpecker/push/ci Pipeline failed Details - Updated all package.json name fields and dependency references - Updated all TypeScript/JavaScript imports - Updated .woodpecker/publish.yml filters and registry paths - Updated tools/install.sh scope default - Updated .npmrc registry paths (worktree + host) - Enhanced update-checker.ts with checkForAllUpdates() multi-package support - Updated CLI update command to show table of all packages - Added KNOWN_PACKAGES, formatAllPackagesTable, getInstallAllCommand - Marked checkForUpdate() with @deprecated JSDoc Closes #391	2026-04-04 21:43:23 -05:00
jason.woltje	80994bdc8e	fix(packages): bump db/memory/queue for PGlite + adapter factories (#389 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 02:20:23 +00:00
jason.woltje	2e31626f87	fix: simplify updater to @mosaic/mosaic only, add explicit tea repo/login flags (#388 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 02:09:23 +00:00
jason.woltje	255ba46a4d	fix(packages): republish @mosaic/config and bump dependents (#386 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 01:56:57 +00:00
jason.woltje	10285933a0	fix: retarget updater to @mosaic/mosaic (#384 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-05 01:52:30 +00:00
jason.woltje	543388e18b	fix(mosaic): resolve framework scripts via import.meta.url (#385 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details Fixes #383 — resolveTool now uses fileURLToPath(import.meta.url). Adds package.json/framework subpath exports. Bumps @mosaic/mosaic to 0.0.18.	2026-04-05 01:41:46 +00:00
jason.woltje	07a1f5d594	Merge pull request 'feat(mosaic): merge @mosaic/cli into @mosaic/mosaic' (#381 ) from fix/merge-cli-into-mosaic into main All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 01:11:33 +00:00
Jarvis	c6fc090c98	feat(mosaic): merge @mosaic/cli into @mosaic/mosaic All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/pr/ci Pipeline was successful Details @mosaic/mosaic is now the single package providing both: - 'mosaic' binary (CLI: yolo, coord, prdy, tui, gateway, etc.) - 'mosaic-wizard' binary (installation wizard) Changes: - Move packages/cli/src/* into packages/mosaic/src/ - Convert dynamic @mosaic/mosaic imports to static relative imports - Add CLI deps (ink, react, socket.io-client, @mosaic/config) to mosaic - Add jsx: react-jsx to mosaic's tsconfig - Exclude packages/cli from workspace (pnpm-workspace.yaml) - Update install.sh to install @mosaic/mosaic instead of @mosaic/cli - Bump version to 0.0.17 This eliminates the circular dependency between @mosaic/cli and @mosaic/mosaic that was blocking the build graph.	2026-04-04 20:07:27 -05:00
jason.woltje	9723b6b948	chore: bump @mosaic/cli and @mosaic/mosaic to 0.0.16 (#379 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-05 00:52:09 +00:00
jason.woltje	c0d0fd44b7	refactor(storage): replace better-sqlite3 with PGlite adapter (#378 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-04 21:58:14 +00:00
jason.woltje	30c0fb1308	fix: remediate npm deprecation warnings in @mosaic/gateway 0.0.3 (#377 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-04 21:03:54 +00:00
jason.woltje	26fac4722f	fix: gateway install preserves npm prefix via registry flag (#376 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-04 20:36:15 +00:00
jason.woltje	e3f64c79d9	chore: move gateway default port from 4000 to 14242 (#375 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-04 20:17:40 +00:00
jason.woltje	cbd5e8c626	fix: scope Gitea registry to @mosaic packages only (#374 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-04 19:09:14 +00:00
jason.woltje	7560c7dee7	fix: gateway install uses Gitea registry instead of npmjs (#373 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-04 18:59:40 +00:00
jason.woltje	982a0e8f83	chore: bump @mosaic/mosaic and @mosaic/cli to 0.0.11 (#372 ) All checks were successful ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline was successful Details	2026-04-04 18:47:03 +00:00
jason.woltje	fc7fa11923	feat: local tier gateway with PGlite + Gitea-only publishing (#371 ) Some checks failed ci/woodpecker/push/ci Pipeline was successful Details ci/woodpecker/push/publish Pipeline failed Details	2026-04-04 18:39:20 +00:00