fix(mosaic): wizard integration test — templates path after monorepo migration

Templates moved from packages/mosaic/templates/ to
packages/mosaic/framework/templates/ in #345. The test's
existsSync guard silently skipped the copy, causing writeSoul
to early-return without writing SOUL.md.

README.md

@@ -1,244 +0,0 @@
-# Mosaic Stack
-
-Self-hosted, multi-user AI agent platform. One config, every runtime, same standards.
-
-Mosaic gives you a unified launcher for Claude Code, Codex, OpenCode, and Pi — injecting consistent system prompts, guardrails, skills, and mission context into every session. A NestJS gateway provides the API surface, a Next.js dashboard gives you the UI, and a plugin system connects Discord, Telegram, and more.
-
-## Quick Install
-
-```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
-```
-
-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/` |
-
-After install, set up your agent identity:
-
-```bash
-mosaic init          # Interactive wizard
-```
-
-### Requirements
-
-- Node.js ≥ 20
-- npm (for global @mosaic/cli 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
-
-### Launching Agent Sessions
-
-```bash
-mosaic pi                    # Launch Pi with Mosaic injection
-mosaic claude                # Launch Claude Code with Mosaic injection
-mosaic codex                 # Launch Codex with Mosaic injection
-mosaic opencode              # Launch OpenCode with Mosaic injection
-
-mosaic yolo claude           # Claude with dangerous-permissions mode
-mosaic yolo pi               # Pi in yolo mode
-```
-
-The launcher verifies your config, checks for `SOUL.md`, injects your `AGENTS.md` standards into the runtime, and forwards all arguments.
-
-### TUI & Gateway
-
-```bash
-mosaic tui                   # Interactive TUI connected to the gateway
-mosaic login                 # Authenticate with a gateway instance
-mosaic sessions list         # List active agent sessions
-```
-
-### Management
-
-```bash
-mosaic doctor                # Health audit — detect drift and missing files
-mosaic sync                  # Sync skills from canonical source
-mosaic update                # Check for and install CLI updates
-mosaic wizard                # Full guided setup wizard
-mosaic bootstrap <path>      # Bootstrap a repo with Mosaic standards
-mosaic coord init            # Initialize a new orchestration mission
-mosaic prdy init             # Create a PRD via guided session
-```
-
-## Development
-
-### Prerequisites
-
-- Node.js ≥ 20
-- pnpm 10.6+
-- Docker & Docker Compose
-
-### Setup
-
-```bash
-git clone git@git.mosaicstack.dev:mosaic/mosaic-stack.git
-cd mosaic-stack
-
-# Start infrastructure (Postgres, Valkey, Jaeger)
-docker compose up -d
-
-# Install dependencies
-pnpm install
-
-# Run migrations
-pnpm --filter @mosaic/db run db:migrate
-
-# Start all services in dev mode
-pnpm dev
-```
-
-### Infrastructure
-
-Docker Compose provides:
-
-| Service               | Port      | Purpose                |
-| --------------------- | --------- | ---------------------- |
-| PostgreSQL (pgvector) | 5433      | Primary database       |
-| Valkey                | 6380      | Task queue + caching   |
-| Jaeger                | 16686     | Distributed tracing UI |
-| OTEL Collector        | 4317/4318 | Telemetry ingestion    |
-
-### Quality Gates
-
-```bash
-pnpm typecheck               # TypeScript type checking (all packages)
-pnpm lint                    # ESLint (all packages)
-pnpm test                    # Vitest (all packages)
-pnpm format:check            # Prettier check
-pnpm format                  # Prettier auto-fix
-```
-
-### CI
-
-Woodpecker CI runs on every push:
-
-- `pnpm install --frozen-lockfile`
-- Database migration against a fresh Postgres
-- `pnpm test` (Turbo-orchestrated across all packages)
-
-npm packages are published to the Gitea package registry on main merges.
-
-## Architecture
-
-```
-mosaic-stack/
-├── apps/
-│   ├── gateway/             NestJS API + WebSocket hub (Fastify, Socket.IO, OTEL)
-│   └── web/                 Next.js dashboard (React 19, Tailwind)
-├── packages/
-│   ├── cli/                 Mosaic CLI — TUI, gateway client, wizard
-│   ├── mosaic/              Framework — wizard, runtime detection, update checker
-│   ├── types/               Shared TypeScript contracts (Socket.IO typed events)
-│   ├── db/                  Drizzle ORM schema + migrations (pgvector)
-│   ├── auth/                BetterAuth configuration
-│   ├── brain/               Data layer (PG-backed)
-│   ├── queue/               Valkey task queue + MCP
-│   ├── coord/               Mission coordination
-│   ├── forge/               Multi-stage AI pipeline (intake → board → plan → code → review)
-│   ├── macp/                MACP protocol — credential resolution, gate runner, events
-│   ├── agent/               Agent session management
-│   ├── memory/              Agent memory layer
-│   ├── log/                 Structured logging
-│   ├── prdy/                PRD creation and validation
-│   ├── quality-rails/       Quality templates (TypeScript, Next.js, monorepo)
-│   └── design-tokens/       Shared design tokens
-├── plugins/
-│   ├── discord/             Discord channel plugin (discord.js)
-│   ├── telegram/            Telegram channel plugin (Telegraf)
-│   ├── macp/                OpenClaw MACP runtime plugin
-│   └── mosaic-framework/    OpenClaw framework injection plugin
-├── tools/
-│   └── install.sh           Unified installer (framework + npm CLI)
-├── scripts/agent/           Agent session lifecycle scripts
-├── docker-compose.yml       Dev infrastructure
-└── .woodpecker/             CI pipeline configs
-```
-
-### Key Design Decisions
-
-- **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
-- **OTEL auto-instrumentation** — loads before NestJS bootstrap
-- **Explicit `@Inject()` decorators** — required since tsx/esbuild doesn't emit decorator metadata
-
-### Framework (`~/.config/mosaic/`)
-
-The framework is the bash-based standards layer installed to every developer machine:
-
-```
-~/.config/mosaic/
-├── AGENTS.md              ← Central standards (loaded into every runtime)
-├── SOUL.md                ← Agent identity (name, style, guardrails)
-├── USER.md                ← User profile (name, timezone, preferences)
-├── TOOLS.md               ← Machine-level tool reference
-├── bin/mosaic             ← Unified launcher (claude, codex, opencode, pi, yolo)
-├── guides/                ← E2E delivery, orchestrator protocol, PRD, etc.
-├── runtime/               ← Per-runtime configs (claude/, codex/, opencode/, pi/)
-├── skills/                ← Universal skills (synced from agent-skills repo)
-├── tools/                 ← Tool suites (orchestrator, git, quality, prdy, etc.)
-└── memory/                ← Persistent agent memory (preserved across upgrades)
-```
-
-### Forge Pipeline
-
-Forge is a multi-stage AI pipeline for autonomous feature delivery:
-
-```
-Intake → Discovery → Board Review → Planning (3 stages) → Coding → Review → Remediation → Test → Deploy
-```
-
-Each stage has a dispatch mode (`exec` for research/review, `yolo` for coding), quality gates, and timeouts. The board review uses multiple AI personas (CEO, CTO, CFO, COO + specialists) to evaluate briefs before committing resources.
-
-## Upgrading
-
-Run the installer again — it handles upgrades automatically:
-
-```bash
-bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)
-```
-
-Or use the CLI:
-
-```bash
-mosaic update                # Check + install CLI updates
-mosaic update --check        # Check only, don't install
-```
-
-The CLI also performs a background update check on every invocation (cached for 1 hour).
-
-### Installer Flags
-
-```bash
-bash tools/install.sh --check        # Version check only
-bash tools/install.sh --framework    # Framework only (skip npm CLI)
-bash tools/install.sh --cli          # npm CLI only (skip framework)
-bash tools/install.sh --ref v1.0     # Install from a specific git ref
-```
-
-## Contributing
-
-```bash
-# Create a feature branch
-git checkout -b feat/my-feature
-
-# Make changes, then verify
-pnpm typecheck && pnpm lint && pnpm test && pnpm format:check
-
-# Commit (husky runs lint-staged automatically)
-git commit -m "feat: description of change"
-
-# Push and create PR
-git push -u origin feat/my-feature
-```
-
-DTOs go in `*.dto.ts` files at module boundaries. Scratchpads (`docs/scratchpads/`) are mandatory for non-trivial tasks. See `AGENTS.md` for the full standards reference.
-
-## License
-
-Proprietary — all rights reserved.

apps/gateway/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/gateway",
-  "version": "0.0.2",
+  "version": "0.0.0",
   "private": true,
   "type": "module",
   "main": "dist/main.js",
@@ -19,14 +19,12 @@
     "@modelcontextprotocol/sdk": "^1.27.1",
     "@mosaic/auth": "workspace:^",
     "@mosaic/brain": "workspace:^",
-    "@mosaic/config": "workspace:^",
     "@mosaic/coord": "workspace:^",
     "@mosaic/db": "workspace:^",
     "@mosaic/discord-plugin": "workspace:^",
     "@mosaic/log": "workspace:^",
     "@mosaic/memory": "workspace:^",
     "@mosaic/queue": "workspace:^",
-    "@mosaic/storage": "workspace:^",
     "@mosaic/telegram-plugin": "workspace:^",
     "@mosaic/types": "workspace:^",
     "@nestjs/common": "^11.0.0",

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

@@ -23,7 +23,6 @@ import { createFileTools } from './tools/file-tools.js';
 import { createGitTools } from './tools/git-tools.js';
 import { createShellTools } from './tools/shell-tools.js';
 import { createWebTools } from './tools/web-tools.js';
-import { createSearchTools } from './tools/search-tools.js';
 import type { SessionInfoDto, SessionMetrics } from './session.dto.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
 import { PreferencesService } from '../preferences/preferences.service.js';
@@ -147,7 +146,6 @@ export class AgentService implements OnModuleDestroy {
       ...createGitTools(sandboxDir),
       ...createShellTools(sandboxDir),
       ...createWebTools(),
-      ...createSearchTools(),
     ];
   }
 

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

@@ -190,169 +190,5 @@ export function createFileTools(baseDir: string): ToolDefinition[] {
     },
   };
 
-  const editFileTool: ToolDefinition = {
+  return [readFileTool, writeFileTool, listDirectoryTool];
-    name: 'fs_edit_file',
-    label: 'Edit File',
-    description:
-      'Make targeted text replacements in a file. Each edit replaces an exact match of oldText with newText. ' +
-      'All edits are matched against the original file content (not incrementally). ' +
-      'Each oldText must be unique in the file and edits must not overlap.',
-    parameters: Type.Object({
-      path: Type.String({
-        description: 'File path (relative to sandbox base or absolute within it)',
-      }),
-      edits: Type.Array(
-        Type.Object({
-          oldText: Type.String({
-            description: 'Exact text to find and replace (must be unique in the file)',
-          }),
-          newText: Type.String({ description: 'Replacement text' }),
-        }),
-        { description: 'One or more targeted replacements', minItems: 1 },
-      ),
-    }),
-    async execute(_toolCallId, params) {
-      const { path, edits } = params as {
-        path: string;
-        edits: Array<{ oldText: string; newText: string }>;
-      };
-
-      let safePath: string;
-      try {
-        safePath = guardPath(path, baseDir);
-      } catch (err) {
-        if (err instanceof SandboxEscapeError) {
-          return {
-            content: [{ type: 'text' as const, text: `Error: ${err.message}` }],
-            details: undefined,
-          };
-        }
-        return {
-          content: [{ type: 'text' as const, text: `Error: ${String(err)}` }],
-          details: undefined,
-        };
-      }
-
-      try {
-        const info = await stat(safePath);
-        if (!info.isFile()) {
-          return {
-            content: [{ type: 'text' as const, text: `Error: path is not a file: ${path}` }],
-            details: undefined,
-          };
-        }
-        if (info.size > MAX_READ_BYTES) {
-          return {
-            content: [
-              {
-                type: 'text' as const,
-                text: `Error: file too large for editing (${info.size} bytes, limit ${MAX_READ_BYTES} bytes)`,
-              },
-            ],
-            details: undefined,
-          };
-        }
-      } catch (err) {
-        return {
-          content: [{ type: 'text' as const, text: `Error reading file: ${String(err)}` }],
-          details: undefined,
-        };
-      }
-
-      let content: string;
-      try {
-        content = await readFile(safePath, { encoding: 'utf8' });
-      } catch (err) {
-        return {
-          content: [{ type: 'text' as const, text: `Error reading file: ${String(err)}` }],
-          details: undefined,
-        };
-      }
-
-      // Validate all edits before applying any
-      const errors: string[] = [];
-      for (let i = 0; i < edits.length; i++) {
-        const edit = edits[i]!;
-        const occurrences = content.split(edit.oldText).length - 1;
-        if (occurrences === 0) {
-          errors.push(`Edit ${i + 1}: oldText not found in file`);
-        } else if (occurrences > 1) {
-          errors.push(`Edit ${i + 1}: oldText matches ${occurrences} locations (must be unique)`);
-        }
-      }
-
-      // Check for overlapping edits
-      if (errors.length === 0) {
-        const positions = edits.map((edit, i) => ({
-          index: i,
-          start: content.indexOf(edit.oldText),
-          end: content.indexOf(edit.oldText) + edit.oldText.length,
-        }));
-        positions.sort((a, b) => a.start - b.start);
-        for (let i = 1; i < positions.length; i++) {
-          if (positions[i]!.start < positions[i - 1]!.end) {
-            errors.push(
-              `Edits ${positions[i - 1]!.index + 1} and ${positions[i]!.index + 1} overlap`,
-            );
-          }
-        }
-      }
-
-      if (errors.length > 0) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Edit validation failed:\n${errors.join('\n')}`,
-            },
-          ],
-          details: undefined,
-        };
-      }
-
-      // Apply edits: process from end to start to preserve positions
-      const positions = edits.map((edit) => ({
-        edit,
-        start: content.indexOf(edit.oldText),
-      }));
-      positions.sort((a, b) => b.start - a.start); // reverse order
-
-      let result = content;
-      for (const { edit } of positions) {
-        result = result.replace(edit.oldText, edit.newText);
-      }
-
-      if (Buffer.byteLength(result, 'utf8') > MAX_WRITE_BYTES) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Error: resulting file too large (limit ${MAX_WRITE_BYTES} bytes)`,
-            },
-          ],
-          details: undefined,
-        };
-      }
-
-      try {
-        await writeFile(safePath, result, { encoding: 'utf8' });
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `File edited successfully: ${path} (${edits.length} edit(s) applied)`,
-            },
-          ],
-          details: undefined,
-        };
-      } catch (err) {
-        return {
-          content: [{ type: 'text' as const, text: `Error writing file: ${String(err)}` }],
-          details: undefined,
-        };
-      }
-    },
-  };
-
-  return [readFileTool, writeFileTool, listDirectoryTool, editFileTool];
 }

apps/gateway/src/agent/tools/index.ts

@@ -2,7 +2,6 @@ export { createBrainTools } from './brain-tools.js';
 export { createCoordTools } from './coord-tools.js';
 export { createFileTools } from './file-tools.js';
 export { createGitTools } from './git-tools.js';
-export { createSearchTools } from './search-tools.js';
 export { createShellTools } from './shell-tools.js';
 export { createWebTools } from './web-tools.js';
 export { createSkillTools } from './skill-tools.js';

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

@@ -1,496 +0,0 @@
-import { Type } from '@sinclair/typebox';
-import type { ToolDefinition } from '@mariozechner/pi-coding-agent';
-
-const DEFAULT_TIMEOUT_MS = 15_000;
-const MAX_RESULTS = 10;
-const MAX_RESPONSE_BYTES = 256 * 1024; // 256 KB
-
-// ─── Provider helpers ────────────────────────────────────────────────────────
-
-interface SearchResult {
-  title: string;
-  url: string;
-  snippet: string;
-}
-
-interface SearchResponse {
-  provider: string;
-  query: string;
-  results: SearchResult[];
-  error?: string;
-}
-
-async function fetchWithTimeout(
-  url: string,
-  init: RequestInit,
-  timeoutMs: number,
-): Promise<Response> {
-  const controller = new AbortController();
-  const timer = setTimeout(() => controller.abort(), timeoutMs);
-  try {
-    return await fetch(url, { ...init, signal: controller.signal });
-  } finally {
-    clearTimeout(timer);
-  }
-}
-
-async function readLimited(response: Response): Promise<string> {
-  const reader = response.body?.getReader();
-  if (!reader) return '';
-  const chunks: Uint8Array[] = [];
-  let total = 0;
-  while (true) {
-    const { done, value } = await reader.read();
-    if (done) break;
-    total += value.length;
-    if (total > MAX_RESPONSE_BYTES) {
-      chunks.push(value.subarray(0, MAX_RESPONSE_BYTES - (total - value.length)));
-      reader.cancel();
-      break;
-    }
-    chunks.push(value);
-  }
-  const combined = new Uint8Array(chunks.reduce((a, c) => a + c.length, 0));
-  let offset = 0;
-  for (const chunk of chunks) {
-    combined.set(chunk, offset);
-    offset += chunk.length;
-  }
-  return new TextDecoder().decode(combined);
-}
-
-// ─── Brave Search ────────────────────────────────────────────────────────────
-
-async function searchBrave(query: string, limit: number): Promise<SearchResponse> {
-  const apiKey = process.env['BRAVE_API_KEY'];
-  if (!apiKey) return { provider: 'brave', query, results: [], error: 'BRAVE_API_KEY not set' };
-
-  try {
-    const params = new URLSearchParams({
-      q: query,
-      count: String(Math.min(limit, 20)),
-    });
-    const res = await fetchWithTimeout(
-      `https://api.search.brave.com/res/v1/web/search?${params}`,
-      { headers: { 'X-Subscription-Token': apiKey, Accept: 'application/json' } },
-      DEFAULT_TIMEOUT_MS,
-    );
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      return { provider: 'brave', query, results: [], error: `HTTP ${res.status}: ${body}` };
-    }
-    const data = (await res.json()) as {
-      web?: { results?: Array<{ title: string; url: string; description: string }> };
-    };
-    const results: SearchResult[] = (data.web?.results ?? []).slice(0, limit).map((r) => ({
-      title: r.title,
-      url: r.url,
-      snippet: r.description,
-    }));
-    return { provider: 'brave', query, results };
-  } catch (err) {
-    return {
-      provider: 'brave',
-      query,
-      results: [],
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-// ─── Tavily Search ───────────────────────────────────────────────────────────
-
-async function searchTavily(query: string, limit: number): Promise<SearchResponse> {
-  const apiKey = process.env['TAVILY_API_KEY'];
-  if (!apiKey) return { provider: 'tavily', query, results: [], error: 'TAVILY_API_KEY not set' };
-
-  try {
-    const res = await fetchWithTimeout(
-      'https://api.tavily.com/search',
-      {
-        method: 'POST',
-        headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({
-          api_key: apiKey,
-          query,
-          max_results: Math.min(limit, 10),
-          include_answer: false,
-        }),
-      },
-      DEFAULT_TIMEOUT_MS,
-    );
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      return { provider: 'tavily', query, results: [], error: `HTTP ${res.status}: ${body}` };
-    }
-    const data = (await res.json()) as {
-      results?: Array<{ title: string; url: string; content: string }>;
-    };
-    const results: SearchResult[] = (data.results ?? []).slice(0, limit).map((r) => ({
-      title: r.title,
-      url: r.url,
-      snippet: r.content,
-    }));
-    return { provider: 'tavily', query, results };
-  } catch (err) {
-    return {
-      provider: 'tavily',
-      query,
-      results: [],
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-// ─── SearXNG (self-hosted) ───────────────────────────────────────────────────
-
-async function searchSearxng(query: string, limit: number): Promise<SearchResponse> {
-  const baseUrl = process.env['SEARXNG_URL'];
-  if (!baseUrl) return { provider: 'searxng', query, results: [], error: 'SEARXNG_URL not set' };
-
-  try {
-    const params = new URLSearchParams({
-      q: query,
-      format: 'json',
-      pageno: '1',
-    });
-    const res = await fetchWithTimeout(
-      `${baseUrl.replace(/\/$/, '')}/search?${params}`,
-      { headers: { Accept: 'application/json' } },
-      DEFAULT_TIMEOUT_MS,
-    );
-    if (!res.ok) {
-      const body = await res.text().catch(() => '');
-      return { provider: 'searxng', query, results: [], error: `HTTP ${res.status}: ${body}` };
-    }
-    const data = (await res.json()) as {
-      results?: Array<{ title: string; url: string; content: string }>;
-    };
-    const results: SearchResult[] = (data.results ?? []).slice(0, limit).map((r) => ({
-      title: r.title,
-      url: r.url,
-      snippet: r.content,
-    }));
-    return { provider: 'searxng', query, results };
-  } catch (err) {
-    return {
-      provider: 'searxng',
-      query,
-      results: [],
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-// ─── DuckDuckGo (lite HTML endpoint) ─────────────────────────────────────────
-
-async function searchDuckDuckGo(query: string, limit: number): Promise<SearchResponse> {
-  try {
-    // Use the DuckDuckGo Instant Answer API (JSON, free, no key)
-    const params = new URLSearchParams({
-      q: query,
-      format: 'json',
-      no_html: '1',
-      skip_disambig: '1',
-    });
-    const res = await fetchWithTimeout(
-      `https://api.duckduckgo.com/?${params}`,
-      { headers: { Accept: 'application/json' } },
-      DEFAULT_TIMEOUT_MS,
-    );
-    if (!res.ok) {
-      return {
-        provider: 'duckduckgo',
-        query,
-        results: [],
-        error: `HTTP ${res.status}`,
-      };
-    }
-    const text = await readLimited(res);
-    const data = JSON.parse(text) as {
-      AbstractText?: string;
-      AbstractURL?: string;
-      AbstractSource?: string;
-      RelatedTopics?: Array<{
-        Text?: string;
-        FirstURL?: string;
-        Result?: string;
-        Topics?: Array<{ Text?: string; FirstURL?: string }>;
-      }>;
-    };
-
-    const results: SearchResult[] = [];
-
-    // Main abstract result
-    if (data.AbstractText && data.AbstractURL) {
-      results.push({
-        title: data.AbstractSource ?? 'DuckDuckGo Abstract',
-        url: data.AbstractURL,
-        snippet: data.AbstractText,
-      });
-    }
-
-    // Related topics
-    for (const topic of data.RelatedTopics ?? []) {
-      if (results.length >= limit) break;
-      if (topic.Text && topic.FirstURL) {
-        results.push({
-          title: topic.Text.slice(0, 120),
-          url: topic.FirstURL,
-          snippet: topic.Text,
-        });
-      }
-      // Sub-topics
-      for (const sub of topic.Topics ?? []) {
-        if (results.length >= limit) break;
-        if (sub.Text && sub.FirstURL) {
-          results.push({
-            title: sub.Text.slice(0, 120),
-            url: sub.FirstURL,
-            snippet: sub.Text,
-          });
-        }
-      }
-    }
-
-    return { provider: 'duckduckgo', query, results: results.slice(0, limit) };
-  } catch (err) {
-    return {
-      provider: 'duckduckgo',
-      query,
-      results: [],
-      error: err instanceof Error ? err.message : String(err),
-    };
-  }
-}
-
-// ─── Provider resolution ─────────────────────────────────────────────────────
-
-type SearchProvider = 'brave' | 'tavily' | 'searxng' | 'duckduckgo' | 'auto';
-
-function getAvailableProviders(): SearchProvider[] {
-  const available: SearchProvider[] = [];
-  if (process.env['BRAVE_API_KEY']) available.push('brave');
-  if (process.env['TAVILY_API_KEY']) available.push('tavily');
-  if (process.env['SEARXNG_URL']) available.push('searxng');
-  // DuckDuckGo is always available (no API key needed)
-  available.push('duckduckgo');
-  return available;
-}
-
-async function executeSearch(
-  provider: SearchProvider,
-  query: string,
-  limit: number,
-): Promise<SearchResponse> {
-  switch (provider) {
-    case 'brave':
-      return searchBrave(query, limit);
-    case 'tavily':
-      return searchTavily(query, limit);
-    case 'searxng':
-      return searchSearxng(query, limit);
-    case 'duckduckgo':
-      return searchDuckDuckGo(query, limit);
-    case 'auto': {
-      // Try providers in priority order: Brave > Tavily > SearXNG > DuckDuckGo
-      const available = getAvailableProviders();
-      for (const p of available) {
-        const result = await executeSearch(p, query, limit);
-        if (!result.error && result.results.length > 0) return result;
-      }
-      // Fall back to DuckDuckGo if everything failed
-      return searchDuckDuckGo(query, limit);
-    }
-  }
-}
-
-function formatSearchResults(response: SearchResponse): string {
-  const lines: string[] = [];
-  lines.push(`Search provider: ${response.provider}`);
-  lines.push(`Query: "${response.query}"`);
-
-  if (response.error) {
-    lines.push(`Error: ${response.error}`);
-  }
-
-  if (response.results.length === 0) {
-    lines.push('No results found.');
-  } else {
-    lines.push(`Results (${response.results.length}):\n`);
-    for (let i = 0; i < response.results.length; i++) {
-      const r = response.results[i]!;
-      lines.push(`${i + 1}. ${r.title}`);
-      lines.push(`   URL: ${r.url}`);
-      lines.push(`   ${r.snippet}`);
-      lines.push('');
-    }
-  }
-  return lines.join('\n');
-}
-
-// ─── Tool exports ────────────────────────────────────────────────────────────
-
-export function createSearchTools(): ToolDefinition[] {
-  const webSearch: ToolDefinition = {
-    name: 'web_search',
-    label: 'Web Search',
-    description:
-      'Search the web using configured search providers. ' +
-      'Supports Brave, Tavily, SearXNG, and DuckDuckGo. ' +
-      'Use "auto" provider to pick the best available. ' +
-      'DuckDuckGo is always available as a fallback (no API key needed).',
-    parameters: Type.Object({
-      query: Type.String({ description: 'Search query' }),
-      provider: Type.Optional(
-        Type.String({
-          description:
-            'Search provider: "auto" (default), "brave", "tavily", "searxng", or "duckduckgo"',
-        }),
-      ),
-      limit: Type.Optional(
-        Type.Number({ description: `Max results to return (default 5, max ${MAX_RESULTS})` }),
-      ),
-    }),
-    async execute(_toolCallId, params) {
-      const { query, provider, limit } = params as {
-        query: string;
-        provider?: string;
-        limit?: number;
-      };
-
-      const effectiveProvider = (provider ?? 'auto') as SearchProvider;
-      const validProviders = ['auto', 'brave', 'tavily', 'searxng', 'duckduckgo'];
-      if (!validProviders.includes(effectiveProvider)) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Invalid provider "${provider}". Valid: ${validProviders.join(', ')}`,
-            },
-          ],
-          details: undefined,
-        };
-      }
-
-      const effectiveLimit = Math.min(Math.max(limit ?? 5, 1), MAX_RESULTS);
-
-      try {
-        const response = await executeSearch(effectiveProvider, query, effectiveLimit);
-        return {
-          content: [{ type: 'text' as const, text: formatSearchResults(response) }],
-          details: undefined,
-        };
-      } catch (err) {
-        return {
-          content: [
-            {
-              type: 'text' as const,
-              text: `Search failed: ${err instanceof Error ? err.message : String(err)}`,
-            },
-          ],
-          details: undefined,
-        };
-      }
-    },
-  };
-
-  const webSearchNews: ToolDefinition = {
-    name: 'web_search_news',
-    label: 'Web Search (News)',
-    description:
-      'Search for recent news articles. Uses Brave News API if available, falls back to standard search with news keywords.',
-    parameters: Type.Object({
-      query: Type.String({ description: 'News search query' }),
-      limit: Type.Optional(
-        Type.Number({ description: `Max results (default 5, max ${MAX_RESULTS})` }),
-      ),
-    }),
-    async execute(_toolCallId, params) {
-      const { query, limit } = params as { query: string; limit?: number };
-      const effectiveLimit = Math.min(Math.max(limit ?? 5, 1), MAX_RESULTS);
-
-      // Try Brave News API first (dedicated news endpoint)
-      const braveKey = process.env['BRAVE_API_KEY'];
-      if (braveKey) {
-        try {
-          const newsParams = new URLSearchParams({
-            q: query,
-            count: String(effectiveLimit),
-          });
-          const res = await fetchWithTimeout(
-            `https://api.search.brave.com/res/v1/news/search?${newsParams}`,
-            {
-              headers: {
-                'X-Subscription-Token': braveKey,
-                Accept: 'application/json',
-              },
-            },
-            DEFAULT_TIMEOUT_MS,
-          );
-          if (res.ok) {
-            const data = (await res.json()) as {
-              results?: Array<{
-                title: string;
-                url: string;
-                description: string;
-                age?: string;
-              }>;
-            };
-            const results: SearchResult[] = (data.results ?? [])
-              .slice(0, effectiveLimit)
-              .map((r) => ({
-                title: r.title + (r.age ? ` (${r.age})` : ''),
-                url: r.url,
-                snippet: r.description,
-              }));
-            const response: SearchResponse = { provider: 'brave-news', query, results };
-            return {
-              content: [{ type: 'text' as const, text: formatSearchResults(response) }],
-              details: undefined,
-            };
-          }
-        } catch {
-          // Fall through to generic search
-        }
-      }
-
-      // Fallback: standard search with "news" appended
-      const newsQuery = `${query} news latest`;
-      const response = await executeSearch('auto', newsQuery, effectiveLimit);
-      return {
-        content: [{ type: 'text' as const, text: formatSearchResults(response) }],
-        details: undefined,
-      };
-    },
-  };
-
-  const searchProviders: ToolDefinition = {
-    name: 'web_search_providers',
-    label: 'List Search Providers',
-    description: 'List the currently available and configured web search providers.',
-    parameters: Type.Object({}),
-    async execute() {
-      const available = getAvailableProviders();
-      const allProviders = [
-        { name: 'brave', configured: !!process.env['BRAVE_API_KEY'], envVar: 'BRAVE_API_KEY' },
-        { name: 'tavily', configured: !!process.env['TAVILY_API_KEY'], envVar: 'TAVILY_API_KEY' },
-        { name: 'searxng', configured: !!process.env['SEARXNG_URL'], envVar: 'SEARXNG_URL' },
-        { name: 'duckduckgo', configured: true, envVar: '(none — always available)' },
-      ];
-
-      const lines = ['Search providers:\n'];
-      for (const p of allProviders) {
-        const status = p.configured ? '✓ configured' : '✗ not configured';
-        lines.push(`  ${p.name}: ${status} (${p.envVar})`);
-      }
-      lines.push(`\nActive providers for "auto" mode: ${available.join(', ')}`);
-      return {
-        content: [{ type: 'text' as const, text: lines.join('\n') }],
-        details: undefined,
-      };
-    },
-  };
-
-  return [webSearch, webSearchNews, searchProviders];
-}

apps/gateway/src/app.module.ts

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

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

@@ -18,7 +18,6 @@ import type {
   SlashCommandPayload,
   SystemReloadPayload,
   RoutingDecisionInfo,
-  AbortPayload,
 } from '@mosaic/types';
 import { AgentService, type ConversationHistoryMessage } from '../agent/agent.service.js';
 import { AUTH } from '../auth/auth.tokens.js';
@@ -326,38 +325,6 @@ export class ChatGateway implements OnGatewayInit, OnGatewayConnection, OnGatewa
     });
   }
 
-  @SubscribeMessage('abort')
-  async handleAbort(
-    @ConnectedSocket() client: Socket,
-    @MessageBody() data: AbortPayload,
-  ): Promise<void> {
-    const conversationId = data.conversationId;
-    this.logger.log(`Abort requested by ${client.id} for conversation ${conversationId}`);
-
-    const session = this.agentService.getSession(conversationId);
-    if (!session) {
-      client.emit('error', {
-        conversationId,
-        error: 'No active session to abort.',
-      });
-      return;
-    }
-
-    try {
-      await session.piSession.abort();
-      this.logger.log(`Agent session ${conversationId} aborted successfully`);
-    } catch (err) {
-      this.logger.error(
-        `Failed to abort session ${conversationId}`,
-        err instanceof Error ? err.stack : String(err),
-      );
-      client.emit('error', {
-        conversationId,
-        error: 'Failed to abort the agent operation.',
-      });
-    }
-  }
-
   @SubscribeMessage('command:execute')
   async handleCommandExecute(
     @ConnectedSocket() client: Socket,

apps/gateway/src/commands/command-executor-p8012.spec.ts

@@ -82,7 +82,6 @@ function buildService(): CommandExecutorService {
     mockBrain as never,
     null,
     mockChatGateway as never,
-    null,
   );
 }
 

apps/gateway/src/commands/command-executor.service.ts

@@ -7,7 +7,6 @@ import { ChatGateway } from '../chat/chat.gateway.js';
 import { SessionGCService } from '../gc/session-gc.service.js';
 import { SystemOverrideService } from '../preferences/system-override.service.js';
 import { ReloadService } from '../reload/reload.service.js';
-import { McpClientService } from '../mcp-client/mcp-client.service.js';
 import { BRAIN } from '../brain/brain.tokens.js';
 import { COMMANDS_REDIS } from './commands.tokens.js';
 import { CommandRegistryService } from './command-registry.service.js';
@@ -29,9 +28,6 @@ export class CommandExecutorService {
     @Optional()
     @Inject(forwardRef(() => ChatGateway))
     private readonly chatGateway: ChatGateway | null,
-    @Optional()
-    @Inject(McpClientService)
-    private readonly mcpClient: McpClientService | null,
   ) {}
 
   async execute(payload: SlashCommandPayload, userId: string): Promise<SlashCommandResultPayload> {
@@ -109,8 +105,6 @@ export class CommandExecutorService {
           };
         case 'tools':
           return await this.handleTools(conversationId, userId);
-        case 'mcp':
-          return await this.handleMcp(args ?? null, conversationId);
         case 'reload': {
           if (!this.reloadService) {
             return {
@@ -495,92 +489,4 @@ export class CommandExecutorService {
       conversationId,
     };
   }
-
-  private async handleMcp(
-    args: string | null,
-    conversationId: string,
-  ): Promise<SlashCommandResultPayload> {
-    if (!this.mcpClient) {
-      return {
-        command: 'mcp',
-        conversationId,
-        success: false,
-        message: 'MCP client service is not available.',
-      };
-    }
-
-    const action = args?.trim().split(/\s+/)[0] ?? 'status';
-
-    switch (action) {
-      case 'status':
-      case 'servers': {
-        const statuses = this.mcpClient.getServerStatuses();
-        if (statuses.length === 0) {
-          return {
-            command: 'mcp',
-            conversationId,
-            success: true,
-            message:
-              'No MCP servers configured. Set MCP_SERVERS env var to connect external tool servers.',
-          };
-        }
-        const lines = ['MCP Server Status:\n'];
-        for (const s of statuses) {
-          const status = s.connected ? '✓ connected' : '✗ disconnected';
-          lines.push(`  ${s.name}: ${status}`);
-          lines.push(`    URL: ${s.url}`);
-          lines.push(`    Tools: ${s.toolCount}`);
-          if (s.error) lines.push(`    Error: ${s.error}`);
-          lines.push('');
-        }
-        const tools = this.mcpClient.getToolDefinitions();
-        if (tools.length > 0) {
-          lines.push(`Total bridged tools: ${tools.length}`);
-          lines.push(`Tool names: ${tools.map((t) => t.name).join(', ')}`);
-        }
-        return {
-          command: 'mcp',
-          conversationId,
-          success: true,
-          message: lines.join('\n'),
-        };
-      }
-
-      case 'reconnect': {
-        const serverName = args?.trim().split(/\s+/).slice(1).join(' ');
-        if (!serverName) {
-          return {
-            command: 'mcp',
-            conversationId,
-            success: false,
-            message: 'Usage: /mcp reconnect <server-name>',
-          };
-        }
-        try {
-          await this.mcpClient.reconnectServer(serverName);
-          return {
-            command: 'mcp',
-            conversationId,
-            success: true,
-            message: `MCP server "${serverName}" reconnected successfully.`,
-          };
-        } catch (err) {
-          return {
-            command: 'mcp',
-            conversationId,
-            success: false,
-            message: `Failed to reconnect MCP server "${serverName}": ${err instanceof Error ? err.message : String(err)}`,
-          };
-        }
-      }
-
-      default:
-        return {
-          command: 'mcp',
-          conversationId,
-          success: false,
-          message: `Unknown MCP action: "${action}". Use: /mcp status, /mcp servers, /mcp reconnect <name>`,
-        };
-    }
-  }
 }

apps/gateway/src/commands/command-registry.service.ts

@@ -260,23 +260,6 @@ export class CommandRegistryService implements OnModuleInit {
         execution: 'socket',
         available: true,
       },
-      {
-        name: 'mcp',
-        description: 'Manage MCP server connections (status/reconnect/servers)',
-        aliases: [],
-        args: [
-          {
-            name: 'action',
-            type: 'enum',
-            optional: true,
-            values: ['status', 'reconnect', 'servers'],
-            description: 'Action: status (default), reconnect <name>, servers',
-          },
-        ],
-        scope: 'agent',
-        execution: 'socket',
-        available: true,
-      },
       {
         name: 'reload',
         description: 'Soft-reload gateway plugins and command manifest (admin)',

apps/gateway/src/commands/commands.integration.spec.ts

@@ -65,7 +65,6 @@ function buildExecutor(registry: CommandRegistryService): CommandExecutorService
     mockBrain as never,
     null, // reloadService (optional)
     null, // chatGateway (optional)
-    null, // mcpClient (optional)
   );
 }
 

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

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

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

@@ -1,42 +1,28 @@
 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 { MOSAIC_CONFIG } from '../config/config.module.js';
 
 export const DB_HANDLE = 'DB_HANDLE';
 export const DB = 'DB';
-export const STORAGE_ADAPTER = 'STORAGE_ADAPTER';
 
 @Global()
 @Module({
   providers: [
     {
       provide: DB_HANDLE,
-      useFactory: (config: MosaicConfig): DbHandle =>
+      useFactory: (): DbHandle => createDb(),
-        createDb(config.storage.type === 'postgres' ? config.storage.url : undefined),
-      inject: [MOSAIC_CONFIG],
     },
     {
       provide: DB,
       useFactory: (handle: DbHandle): Db => handle.db,
       inject: [DB_HANDLE],
     },
-    {
-      provide: STORAGE_ADAPTER,
-      useFactory: (config: MosaicConfig): StorageAdapter => createStorageAdapter(config.storage),
-      inject: [MOSAIC_CONFIG],
-    },
   ],
-  exports: [DB, STORAGE_ADAPTER],
+  exports: [DB],
 })
 export class DatabaseModule implements OnApplicationShutdown {
-  constructor(
+  constructor(@Inject(DB_HANDLE) private readonly handle: DbHandle) {}
-    @Inject(DB_HANDLE) private readonly handle: DbHandle,
-    @Inject(STORAGE_ADAPTER) private readonly storageAdapter: StorageAdapter,
-  ) {}
 
   async onApplicationShutdown(): Promise<void> {
-    await Promise.all([this.handle.close(), this.storageAdapter.close()]);
+    await this.handle.close();
   }
 }

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

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

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

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

apps/web/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/web",
-  "version": "0.0.2",
+  "version": "0.0.0",
   "private": true,
   "scripts": {
     "build": "next build",

docs/TASKS.md

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

docs/design/storage-abstraction-middleware.md

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

mosaic.config.json

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

package.json

@@ -23,10 +23,5 @@
     "turbo": "^2.0.0",
     "typescript": "^5.8.0",
     "vitest": "^2.0.0"
-  },
-  "pnpm": {
-    "onlyBuiltDependencies": [
-      "better-sqlite3"
-    ]
   }
 }

packages/agent/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/agent",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/auth/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/auth",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/brain/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/brain",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/cli/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/cli",
-  "version": "0.0.10",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -14,7 +14,7 @@
     }
   },
   "scripts": {
-    "build": "tsc -p tsconfig.build.json",
+    "build": "tsc",
     "dev": "tsx src/cli.ts",
     "lint": "eslint src",
     "typecheck": "tsc --noEmit",
@@ -22,7 +22,6 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.9.0",
-    "@mosaic/config": "workspace:^",
     "@mosaic/mosaic": "workspace:^",
     "@mosaic/prdy": "workspace:^",
     "@mosaic/quality-rails": "workspace:^",

packages/cli/src/cli.ts

@@ -2,12 +2,10 @@
 
 import { createRequire } from 'module';
 import { Command } from 'commander';
-import { registerQualityRails } from '@mosaic/quality-rails';
+import { createQualityRailsCli } from '@mosaic/quality-rails';
 import { registerAgentCommand } from './commands/agent.js';
 import { registerMissionCommand } from './commands/mission.js';
-// prdy is registered via launch.ts
+import { registerPrdyCommand } from './commands/prdy.js';
-import { registerLaunchCommands } from './commands/launch.js';
-import { registerGatewayCommand } from './commands/gateway.js';
 
 const _require = createRequire(import.meta.url);
 const CLI_VERSION: string = (_require('../package.json') as { version: string }).version;
@@ -24,10 +22,6 @@ const program = new Command();
 
 program.name('mosaic').description('Mosaic Stack CLI').version(CLI_VERSION);
 
-// ─── runtime launchers + framework commands ────────────────────────────
-
-registerLaunchCommands(program);
-
 // ─── login ──────────────────────────────────────────────────────────────
 
 program
@@ -291,10 +285,6 @@ sessionsCmd
     }
   });
 
-// ─── gateway ──────────────────────────────────────────────────────────
-
-registerGatewayCommand(program);
-
 // ─── agent ─────────────────────────────────────────────────────────────
 
 registerAgentCommand(program);
@@ -303,9 +293,17 @@ registerAgentCommand(program);
 
 registerMissionCommand(program);
 
+// ─── prdy ──────────────────────────────────────────────────────────────
+
+registerPrdyCommand(program);
+
 // ─── quality-rails ──────────────────────────────────────────────────────
 
-registerQualityRails(program);
+const qrWrapper = createQualityRailsCli();
+const qrCmd = qrWrapper.commands.find((c) => c.name() === 'quality-rails');
+if (qrCmd !== undefined) {
+  program.addCommand(qrCmd as unknown as Command);
+}
 
 // ─── update ─────────────────────────────────────────────────────────────
 

packages/cli/src/commands/gateway.ts

@@ -1,198 +0,0 @@
-import { createInterface } from 'node:readline';
-import { spawn } from 'node:child_process';
-import { existsSync, mkdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
-import { dirname, resolve } from 'node:path';
-import type { Command } from 'commander';
-import {
-  DEFAULT_LOCAL_CONFIG,
-  DEFAULT_TEAM_CONFIG,
-  loadConfig,
-  type MosaicConfig,
-  type StorageTier,
-} from '@mosaic/config';
-
-function ask(rl: ReturnType<typeof createInterface>, question: string): Promise<string> {
-  return new Promise((res) => rl.question(question, res));
-}
-
-async function runInit(opts: { tier?: string; output: string }): Promise<void> {
-  const outputPath = resolve(opts.output);
-  let tier: StorageTier;
-
-  if (opts.tier) {
-    if (opts.tier !== 'local' && opts.tier !== 'team') {
-      console.error(`Invalid tier "${opts.tier}" — expected "local" or "team"`);
-      process.exit(1);
-    }
-    tier = opts.tier;
-  } else {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const answer = await ask(rl, 'Select tier (local/team) [local]: ');
-    rl.close();
-    const trimmed = answer.trim().toLowerCase();
-    tier = trimmed === 'team' ? 'team' : 'local';
-  }
-
-  let config: MosaicConfig;
-
-  if (tier === 'local') {
-    config = DEFAULT_LOCAL_CONFIG;
-  } else {
-    const rl = createInterface({ input: process.stdin, output: process.stdout });
-    const dbUrl = await ask(
-      rl,
-      'DATABASE_URL [postgresql://mosaic:mosaic@localhost:5432/mosaic]: ',
-    );
-    const valkeyUrl = await ask(rl, 'VALKEY_URL [redis://localhost:6379]: ');
-    rl.close();
-
-    config = {
-      ...DEFAULT_TEAM_CONFIG,
-      storage: {
-        type: 'postgres',
-        url: dbUrl.trim() || 'postgresql://mosaic:mosaic@localhost:5432/mosaic',
-      },
-      queue: {
-        type: 'bullmq',
-        url: valkeyUrl.trim() || 'redis://localhost:6379',
-      },
-    };
-  }
-
-  writeFileSync(outputPath, JSON.stringify(config, null, 2) + '\n');
-  console.log(`\nWrote ${outputPath}`);
-  console.log('\nNext steps:');
-  console.log('  1. Review the generated config');
-  console.log('  2. Run: pnpm --filter @mosaic/gateway exec tsx src/main.ts');
-}
-
-const PID_FILE = resolve(process.cwd(), '.mosaic/gateway.pid');
-
-function writePidFile(pid: number): void {
-  const dir = dirname(PID_FILE);
-  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
-  writeFileSync(PID_FILE, String(pid));
-}
-
-function readPidFile(): number | null {
-  if (!existsSync(PID_FILE)) return null;
-  const raw = readFileSync(PID_FILE, 'utf-8').trim();
-  const pid = Number(raw);
-  return Number.isFinite(pid) ? pid : null;
-}
-
-function isProcessRunning(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function printConfigSummary(config: MosaicConfig): void {
-  console.log(`  Tier:    ${config.tier}`);
-  console.log(`  Storage: ${config.storage.type}`);
-  console.log(`  Queue:   ${config.queue.type}`);
-  console.log(`  Memory:  ${config.memory.type}`);
-}
-
-export function registerGatewayCommand(program: Command): void {
-  const gateway = program.command('gateway').description('Gateway management commands');
-
-  gateway
-    .command('init')
-    .description('Generate a mosaic.config.json for the gateway')
-    .option('--tier <tier>', 'Storage tier: local or team (skips interactive prompt)')
-    .option('--output <path>', 'Output file path', './mosaic.config.json')
-    .action(async (opts: { tier?: string; output: string }) => {
-      await runInit(opts);
-    });
-
-  gateway
-    .command('start')
-    .description('Start the Mosaic gateway process')
-    .option('--port <port>', 'Port to listen on (overrides config)')
-    .option('--daemon', 'Run in background and write PID to .mosaic/gateway.pid')
-    .action((opts: { port?: string; daemon?: boolean }) => {
-      const config = loadConfig();
-      const port = opts.port ?? '4000';
-
-      console.log('Starting gateway…');
-      printConfigSummary(config);
-      console.log(`  Port:    ${port}`);
-
-      const entryPoint = resolve(process.cwd(), 'apps/gateway/src/main.ts');
-      const env = { ...process.env, GATEWAY_PORT: port };
-
-      if (opts.daemon) {
-        const child = spawn('npx', ['tsx', entryPoint], {
-          env,
-          stdio: 'ignore',
-          detached: true,
-        });
-
-        child.unref();
-
-        if (child.pid) {
-          writePidFile(child.pid);
-          console.log(`\nGateway started in background (PID ${child.pid})`);
-          console.log(`PID file: ${PID_FILE}`);
-        }
-      } else {
-        const child = spawn('npx', ['tsx', entryPoint], {
-          env,
-          stdio: 'inherit',
-        });
-
-        child.on('exit', (code) => {
-          process.exit(code ?? 0);
-        });
-      }
-    });
-
-  gateway
-    .command('stop')
-    .description('Stop the running gateway process')
-    .action(() => {
-      const pid = readPidFile();
-
-      if (pid === null) {
-        console.error('No PID file found at', PID_FILE);
-        process.exit(1);
-      }
-
-      if (!isProcessRunning(pid)) {
-        console.log(`Process ${pid} is not running. Removing stale PID file.`);
-        unlinkSync(PID_FILE);
-        return;
-      }
-
-      process.kill(pid, 'SIGTERM');
-      unlinkSync(PID_FILE);
-      console.log(`Gateway stopped (PID ${pid})`);
-    });
-
-  gateway
-    .command('status')
-    .description('Show gateway process status')
-    .action(() => {
-      const config = loadConfig();
-      const pid = readPidFile();
-
-      if (pid !== null && isProcessRunning(pid)) {
-        console.log('Gateway: running');
-        console.log(`  PID:     ${pid}`);
-      } else {
-        console.log('Gateway: stopped');
-        if (pid !== null) {
-          console.log(`  (stale PID file for ${pid})`);
-          unlinkSync(PID_FILE);
-        }
-      }
-
-      console.log('');
-      console.log('Config:');
-      printConfigSummary(config);
-    });
-}

packages/cli/src/commands/launch.ts

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

packages/cli/src/tui/app.tsx

@@ -15,7 +15,6 @@ import { useConversations } from './hooks/use-conversations.js';
 import { useSearch } from './hooks/use-search.js';
 import { executeHelp, executeStatus, executeHistory, commandRegistry } from './commands/index.js';
 import { fetchConversationMessages } from './gateway-api.js';
-import { expandFileRefs, hasFileRefs, handleAttachCommand } from './file-ref.js';
 
 export interface TuiAppProps {
   gatewayUrl: string;
@@ -86,36 +85,6 @@ export function TuiApp({
   // combo is handled by the top-level useInput handler (e.g. Ctrl+T → 't').
   const ctrlJustFired = useRef(false);
 
-  // Wrap sendMessage to expand @file references before sending
-  const sendMessageWithFileRefs = useCallback(
-    (content: string) => {
-      if (!hasFileRefs(content)) {
-        socket.sendMessage(content);
-        return;
-      }
-      void expandFileRefs(content)
-        .then(({ expandedMessage, filesAttached, errors }) => {
-          for (const err of errors) {
-            socket.addSystemMessage(err);
-          }
-          if (filesAttached.length > 0) {
-            socket.addSystemMessage(
-              `📎 Attached ${filesAttached.length} file(s): ${filesAttached.join(', ')}`,
-            );
-          }
-          socket.sendMessage(expandedMessage);
-        })
-        .catch((err: unknown) => {
-          socket.addSystemMessage(
-            `File expansion failed: ${err instanceof Error ? err.message : String(err)}`,
-          );
-          // Send original message without expansion
-          socket.sendMessage(content);
-        });
-    },
-    [socket],
-  );
-
   const handleLocalCommand = useCallback(
     (parsed: ParsedCommand) => {
       switch (parsed.command) {
@@ -154,36 +123,9 @@ export function TuiApp({
               socket.addSystemMessage('Failed to create new conversation.');
             });
           break;
-        case 'attach': {
-          if (!parsed.args) {
-            socket.addSystemMessage('Usage: /attach <file-path>');
-            break;
-          }
-          void handleAttachCommand(parsed.args)
-            .then(({ content, error }) => {
-              if (error) {
-                socket.addSystemMessage(`Attach error: ${error}`);
-              } else if (content) {
-                // Send the file content as a user message
-                socket.sendMessage(content);
-              }
-            })
-            .catch((err: unknown) => {
-              socket.addSystemMessage(
-                `Attach failed: ${err instanceof Error ? err.message : String(err)}`,
-              );
-            });
-          break;
-        }
         case 'stop':
-          if (socket.isStreaming && socket.socketRef.current?.connected && socket.conversationId) {
+          // Currently no stop mechanism exposed — show feedback
-            socket.socketRef.current.emit('abort', {
+          socket.addSystemMessage('Stop is not available for the current session.');
-              conversationId: socket.conversationId,
-            });
-            socket.addSystemMessage('Abort signal sent.');
-          } else {
-            socket.addSystemMessage('No active stream to stop.');
-          }
           break;
         case 'cost': {
           const u = socket.tokenUsage;
@@ -406,7 +348,7 @@ export function TuiApp({
           }
           setTuiInput(val);
         }}
-        onSubmit={sendMessageWithFileRefs}
+        onSubmit={socket.sendMessage}
         onSystemMessage={socket.addSystemMessage}
         onLocalCommand={handleLocalCommand}
         onGatewayCommand={handleGatewayCommand}

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

@@ -56,22 +56,6 @@ const LOCAL_COMMANDS: CommandDef[] = [
     available: true,
     scope: 'core',
   },
-  {
-    name: 'attach',
-    description: 'Attach a file to the next message (@file syntax also works inline)',
-    aliases: [],
-    args: [
-      {
-        name: 'path',
-        type: 'string' as const,
-        optional: false,
-        description: 'File path to attach',
-      },
-    ],
-    execution: 'local',
-    available: true,
-    scope: 'core',
-  },
   {
     name: 'new',
     description: 'Start a new conversation',

packages/cli/src/tui/file-ref.ts

@@ -1,202 +0,0 @@
-/**
- * File reference expansion for TUI chat input.
- *
- * Detects @path/to/file patterns in user messages, reads the file contents,
- * and inlines them as fenced code blocks in the message.
- *
- * Supports:
- *   - @relative/path.ts
- *   - @./relative/path.ts
- *   - @/absolute/path.ts
- *   - @~/home-relative/path.ts
- *
- * Also provides an /attach <path> command handler.
- */
-
-import { readFile, stat } from 'node:fs/promises';
-import { resolve, extname, basename } from 'node:path';
-import { homedir } from 'node:os';
-
-const MAX_FILE_SIZE = 256 * 1024; // 256 KB
-const MAX_FILES_PER_MESSAGE = 10;
-
-/**
- * Regex to detect @file references in user input.
- * Matches @<path> where path starts with /, ./, ~/, or a word char,
- * and continues until whitespace or end of string.
- * Excludes @mentions that look like usernames (no dots/slashes).
- */
-const FILE_REF_PATTERN = /(?:^|\s)@((?:\.{0,2}\/|~\/|[a-zA-Z0-9_])[^\s]+)/g;
-
-interface FileRefResult {
-  /** The expanded message text with file contents inlined */
-  expandedMessage: string;
-  /** Files that were successfully read */
-  filesAttached: string[];
-  /** Errors encountered while reading files */
-  errors: string[];
-}
-
-function resolveFilePath(ref: string): string {
-  if (ref.startsWith('~/')) {
-    return resolve(homedir(), ref.slice(2));
-  }
-  return resolve(process.cwd(), ref);
-}
-
-function getLanguageHint(filePath: string): string {
-  const ext = extname(filePath).toLowerCase();
-  const map: Record<string, string> = {
-    '.ts': 'typescript',
-    '.tsx': 'typescript',
-    '.js': 'javascript',
-    '.jsx': 'javascript',
-    '.py': 'python',
-    '.rb': 'ruby',
-    '.rs': 'rust',
-    '.go': 'go',
-    '.java': 'java',
-    '.c': 'c',
-    '.cpp': 'cpp',
-    '.h': 'c',
-    '.hpp': 'cpp',
-    '.cs': 'csharp',
-    '.sh': 'bash',
-    '.bash': 'bash',
-    '.zsh': 'zsh',
-    '.fish': 'fish',
-    '.json': 'json',
-    '.yaml': 'yaml',
-    '.yml': 'yaml',
-    '.toml': 'toml',
-    '.xml': 'xml',
-    '.html': 'html',
-    '.css': 'css',
-    '.scss': 'scss',
-    '.md': 'markdown',
-    '.sql': 'sql',
-    '.graphql': 'graphql',
-    '.dockerfile': 'dockerfile',
-    '.tf': 'terraform',
-    '.vue': 'vue',
-    '.svelte': 'svelte',
-  };
-  return map[ext] ?? '';
-}
-
-/**
- * Check if the input contains any @file references.
- */
-export function hasFileRefs(input: string): boolean {
-  FILE_REF_PATTERN.lastIndex = 0;
-  return FILE_REF_PATTERN.test(input);
-}
-
-/**
- * Expand @file references in a message by reading file contents
- * and appending them as fenced code blocks.
- */
-export async function expandFileRefs(input: string): Promise<FileRefResult> {
-  const refs: string[] = [];
-  FILE_REF_PATTERN.lastIndex = 0;
-  let match;
-  while ((match = FILE_REF_PATTERN.exec(input)) !== null) {
-    const ref = match[1]!;
-    if (!refs.includes(ref)) {
-      refs.push(ref);
-    }
-  }
-
-  if (refs.length === 0) {
-    return { expandedMessage: input, filesAttached: [], errors: [] };
-  }
-
-  if (refs.length > MAX_FILES_PER_MESSAGE) {
-    return {
-      expandedMessage: input,
-      filesAttached: [],
-      errors: [`Too many file references (${refs.length}). Maximum is ${MAX_FILES_PER_MESSAGE}.`],
-    };
-  }
-
-  const filesAttached: string[] = [];
-  const errors: string[] = [];
-  const attachments: string[] = [];
-
-  for (const ref of refs) {
-    const filePath = resolveFilePath(ref);
-    try {
-      const info = await stat(filePath);
-      if (!info.isFile()) {
-        errors.push(`@${ref}: not a file`);
-        continue;
-      }
-      if (info.size > MAX_FILE_SIZE) {
-        errors.push(
-          `@${ref}: file too large (${(info.size / 1024).toFixed(0)} KB, limit ${MAX_FILE_SIZE / 1024} KB)`,
-        );
-        continue;
-      }
-      const content = await readFile(filePath, 'utf8');
-      const lang = getLanguageHint(filePath);
-      const name = basename(filePath);
-      attachments.push(`\n📎 ${ref} (${name}):\n\`\`\`${lang}\n${content}\n\`\`\``);
-      filesAttached.push(ref);
-    } catch (err) {
-      const msg = err instanceof Error ? err.message : String(err);
-      // Only report meaningful errors — ENOENT is common for false @mention matches
-      if (msg.includes('ENOENT')) {
-        // Check if this looks like a file path (has extension or slash)
-        if (ref.includes('/') || ref.includes('.')) {
-          errors.push(`@${ref}: file not found`);
-        }
-        // Otherwise silently skip — likely an @mention, not a file ref
-      } else {
-        errors.push(`@${ref}: ${msg}`);
-      }
-    }
-  }
-
-  if (attachments.length === 0) {
-    return { expandedMessage: input, filesAttached, errors };
-  }
-
-  const expandedMessage = input + '\n' + attachments.join('\n');
-  return { expandedMessage, filesAttached, errors };
-}
-
-/**
- * Handle the /attach <path> command.
- * Reads a file and returns the content formatted for inclusion in the chat.
- */
-export async function handleAttachCommand(
-  args: string,
-): Promise<{ content: string; error?: string }> {
-  const filePath = args.trim();
-  if (!filePath) {
-    return { content: '', error: 'Usage: /attach <file-path>' };
-  }
-
-  const resolved = resolveFilePath(filePath);
-  try {
-    const info = await stat(resolved);
-    if (!info.isFile()) {
-      return { content: '', error: `Not a file: ${filePath}` };
-    }
-    if (info.size > MAX_FILE_SIZE) {
-      return {
-        content: '',
-        error: `File too large (${(info.size / 1024).toFixed(0)} KB, limit ${MAX_FILE_SIZE / 1024} KB)`,
-      };
-    }
-    const content = await readFile(resolved, 'utf8');
-    const lang = getLanguageHint(resolved);
-    const name = basename(resolved);
-    return {
-      content: `📎 Attached file: ${name} (${filePath})\n\`\`\`${lang}\n${content}\n\`\`\``,
-    };
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    return { content: '', error: `Failed to read file: ${msg}` };
-  }
-}

packages/cli/tsconfig.build.json

@@ -1,4 +0,0 @@
-{
-  "extends": "./tsconfig.json",
-  "exclude": ["node_modules", "dist", "src/**/*.test.ts", "src/**/*.spec.ts"]
-}

packages/config/package.json

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

packages/config/src/index.ts

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

packages/config/src/mosaic-config.ts

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

packages/config/tsconfig.json

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

packages/coord/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/coord",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/db/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/db",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/design-tokens/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/design-tokens",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/forge/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/forge",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/log/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/log",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/macp/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/macp",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

packages/memory/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/memory",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -18,7 +18,6 @@
   },
   "dependencies": {
     "@mosaic/db": "workspace:*",
-    "@mosaic/storage": "workspace:*",
     "@mosaic/types": "workspace:*",
     "drizzle-orm": "^0.45.1"
   },

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

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

packages/memory/src/adapters/keyword.ts

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

packages/memory/src/adapters/pgvector.ts

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

packages/memory/src/factory.ts

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

packages/memory/src/index.ts

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

packages/memory/src/types.ts

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

packages/mosaic/__tests__/platform/file-ops.test.ts

@@ -1,88 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import {
-  mkdtempSync,
-  mkdirSync,
-  writeFileSync,
-  readFileSync,
-  existsSync,
-  chmodSync,
-  rmSync,
-} from 'node:fs';
-import { join } from 'node:path';
-import { tmpdir } from 'node:os';
-import { syncDirectory } from '../../src/platform/file-ops.js';
-
-describe('syncDirectory', () => {
-  let tmpDir: string;
-
-  beforeEach(() => {
-    tmpDir = mkdtempSync(join(tmpdir(), 'mosaic-file-ops-'));
-  });
-
-  afterEach(() => {
-    rmSync(tmpDir, { recursive: true, force: true });
-  });
-
-  it('is a no-op when source and target are the same path', () => {
-    const dir = join(tmpDir, 'same');
-    mkdirSync(dir, { recursive: true });
-    writeFileSync(join(dir, 'file.txt'), 'hello');
-    // Should not throw even with read-only files
-    const gitDir = join(dir, '.git', 'objects', 'pack');
-    mkdirSync(gitDir, { recursive: true });
-    const packFile = join(gitDir, 'pack-abc.idx');
-    writeFileSync(packFile, 'data');
-    chmodSync(packFile, 0o444);
-
-    expect(() => syncDirectory(dir, dir)).not.toThrow();
-  });
-
-  it('skips nested .git directories when excludeGit is true', () => {
-    const src = join(tmpDir, 'src');
-    const dest = join(tmpDir, 'dest');
-
-    // Create source with a nested .git
-    mkdirSync(join(src, 'sources', 'skills', '.git', 'objects'), { recursive: true });
-    writeFileSync(join(src, 'sources', 'skills', '.git', 'objects', 'pack.idx'), 'git-data');
-    writeFileSync(join(src, 'sources', 'skills', 'SKILL.md'), 'skill content');
-    writeFileSync(join(src, 'README.md'), 'readme');
-
-    syncDirectory(src, dest, { excludeGit: true });
-
-    // .git contents should NOT be copied
-    expect(existsSync(join(dest, 'sources', 'skills', '.git'))).toBe(false);
-    // Normal files should be copied
-    expect(readFileSync(join(dest, 'sources', 'skills', 'SKILL.md'), 'utf-8')).toBe(
-      'skill content',
-    );
-    expect(readFileSync(join(dest, 'README.md'), 'utf-8')).toBe('readme');
-  });
-
-  it('copies nested .git directories when excludeGit is false', () => {
-    const src = join(tmpDir, 'src');
-    const dest = join(tmpDir, 'dest');
-
-    mkdirSync(join(src, 'sub', '.git'), { recursive: true });
-    writeFileSync(join(src, 'sub', '.git', 'HEAD'), 'ref: refs/heads/main');
-
-    syncDirectory(src, dest, { excludeGit: false });
-
-    expect(readFileSync(join(dest, 'sub', '.git', 'HEAD'), 'utf-8')).toBe('ref: refs/heads/main');
-  });
-
-  it('respects preserve option', () => {
-    const src = join(tmpDir, 'src');
-    const dest = join(tmpDir, 'dest');
-
-    mkdirSync(src, { recursive: true });
-    mkdirSync(dest, { recursive: true });
-    writeFileSync(join(src, 'SOUL.md'), 'new soul');
-    writeFileSync(join(dest, 'SOUL.md'), 'old soul');
-    writeFileSync(join(src, 'README.md'), 'new readme');
-
-    syncDirectory(src, dest, { preserve: ['SOUL.md'] });
-
-    expect(readFileSync(join(dest, 'SOUL.md'), 'utf-8')).toBe('old soul');
-    expect(readFileSync(join(dest, 'README.md'), 'utf-8')).toBe('new readme');
-  });
-});

packages/mosaic/__tests__/stages/detect-install.test.ts

@@ -65,36 +65,4 @@ describe('detectInstallStage', () => {
     expect(state.installAction).toBe('keep');
     expect(state.soul.agentName).toBe('TestAgent');
   });
-
-  it('pre-populates state when reconfiguring', async () => {
-    mkdirSync(join(tmpDir, 'bin'), { recursive: true });
-    writeFileSync(join(tmpDir, 'SOUL.md'), 'You are **Jarvis** in this session.');
-    writeFileSync(join(tmpDir, 'USER.md'), '**Name:** TestUser');
-
-    const p = new HeadlessPrompter({
-      'What would you like to do?': 'reconfigure',
-    });
-    const state = createState(tmpDir);
-    await detectInstallStage(p, state, mockConfig);
-
-    expect(state.installAction).toBe('reconfigure');
-    // Existing values loaded as defaults for reconfiguration
-    expect(state.soul.agentName).toBe('TestAgent');
-    expect(state.user.userName).toBe('TestUser');
-  });
-
-  it('does not pre-populate state on fresh reset', async () => {
-    mkdirSync(join(tmpDir, 'bin'), { recursive: true });
-    writeFileSync(join(tmpDir, 'SOUL.md'), 'You are **Jarvis** in this session.');
-
-    const p = new HeadlessPrompter({
-      'What would you like to do?': 'reset',
-    });
-    const state = createState(tmpDir);
-    await detectInstallStage(p, state, mockConfig);
-
-    expect(state.installAction).toBe('reset');
-    // Reset should NOT load existing values
-    expect(state.soul.agentName).toBeUndefined();
-  });
 });

packages/mosaic/framework/bin/mosaic

@@ -0,0 +1,849 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+# mosaic — Unified agent launcher and management CLI
+#
+# AGENTS.md is the global policy source for all agent sessions.
+# The launcher injects a composed runtime contract (AGENTS + runtime reference).
+#
+# Usage:
+#   mosaic claude [args...]       Launch Claude Code with runtime contract injected
+#   mosaic opencode [args...]     Launch OpenCode with runtime contract injected
+#   mosaic codex [args...]        Launch Codex with runtime contract injected
+#   mosaic yolo <runtime> [args...]  Launch runtime in dangerous-permissions mode
+#   mosaic --yolo <runtime> [args...]  Alias for yolo
+#   mosaic init [args...]         Generate SOUL.md interactively
+#   mosaic doctor [args...]       Health audit
+#   mosaic sync [args...]         Sync skills
+#   mosaic seq [subcommand]       sequential-thinking MCP management (check/fix/start)
+#   mosaic bootstrap <path>       Bootstrap a repo
+#   mosaic upgrade release         Upgrade installed Mosaic release
+#   mosaic upgrade check           Check release upgrade status (no changes)
+#   mosaic upgrade project [args]  Upgrade project-local stale files
+
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
+VERSION="0.1.0"
+
+usage() {
+  cat <<USAGE
+mosaic $VERSION — Unified agent launcher
+
+Usage: mosaic <command> [args...]
+
+Agent Launchers:
+  pi [args...]           Launch Pi with runtime contract injected (recommended)
+  claude [args...]       Launch Claude Code with runtime contract injected
+  opencode [args...]     Launch OpenCode with runtime contract injected
+  codex [args...]        Launch Codex with runtime contract injected
+  yolo <runtime> [args...]  Dangerous mode for claude|codex|opencode|pi
+  --yolo <runtime> [args...] Alias for yolo
+
+Management:
+  init [args...]         Generate SOUL.md (agent identity contract)
+  doctor [args...]       Audit runtime state and detect drift
+  sync [args...]         Sync skills from canonical source
+  seq [subcommand]       sequential-thinking MCP management:
+                         check [--runtime <r>] [--strict]
+                         fix [--runtime <r>]
+                         start
+  bootstrap <path>       Bootstrap a repo with Mosaic standards
+  upgrade [mode] [args]  Upgrade release (default) or project files
+  upgrade check          Check release upgrade status (no changes)
+  release-upgrade [...]  Upgrade installed Mosaic release
+  project-upgrade [...]  Clean up stale SOUL.md/CLAUDE.md in a project
+
+PRD:
+  prdy <subcommand>      PRD creation and validation
+                         init    Create docs/PRD.md via guided runtime session
+                         update  Update existing PRD via guided runtime session
+                         validate Check PRD completeness (bash-only)
+                         status  Quick PRD health check (one-liner)
+
+Coordinator (r0):
+  coord <subcommand>     Manual coordinator tools
+                         init    Initialize a new mission
+                         mission Show mission progress dashboard
+                         status  Check agent session health
+                         continue Generate continuation prompt
+                         run     Generate context and launch selected runtime
+                         resume  Crash recovery
+
+Options:
+  -h, --help             Show this help
+  -v, --version          Show version
+
+All arguments after the command are forwarded to the target CLI.
+USAGE
+}
+
+# Pre-flight checks
+check_mosaic_home() {
+  if [[ ! -d "$MOSAIC_HOME" ]]; then
+    echo "[mosaic] ERROR: ~/.config/mosaic not found." >&2
+    echo "[mosaic] Install with: bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)" >&2
+    exit 1
+  fi
+}
+
+check_agents_md() {
+  if [[ ! -f "$MOSAIC_HOME/AGENTS.md" ]]; then
+    echo "[mosaic] ERROR: ~/.config/mosaic/AGENTS.md not found." >&2
+    echo "[mosaic] Re-run the installer: bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)" >&2
+    exit 1
+  fi
+}
+
+check_soul() {
+  if [[ ! -f "$MOSAIC_HOME/SOUL.md" ]]; then
+    echo "[mosaic] SOUL.md not found. Running mosaic init..."
+    "$MOSAIC_HOME/bin/mosaic-init"
+  fi
+}
+
+check_runtime() {
+  local cmd="$1"
+  if ! command -v "$cmd" >/dev/null 2>&1; then
+    echo "[mosaic] ERROR: '$cmd' not found in PATH." >&2
+    echo "[mosaic] Install $cmd before launching." >&2
+    exit 1
+  fi
+}
+
+check_sequential_thinking() {
+  local runtime="${1:-all}"
+  local checker="$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking"
+  if [[ ! -x "$checker" ]]; then
+    echo "[mosaic] ERROR: sequential-thinking checker missing: $checker" >&2
+    exit 1
+  fi
+  if ! "$checker" --check --runtime "$runtime" >/dev/null 2>&1; then
+    echo "[mosaic] ERROR: sequential-thinking MCP is required but not configured." >&2
+    echo "[mosaic] Fix config: $checker --runtime $runtime" >&2
+    echo "[mosaic] Or run: mosaic seq fix --runtime $runtime" >&2
+    echo "[mosaic] Manual server start: mosaic seq start" >&2
+    exit 1
+  fi
+}
+
+runtime_contract_path() {
+  local runtime="$1"
+  case "$runtime" in
+    claude) echo "$MOSAIC_HOME/runtime/claude/RUNTIME.md" ;;
+    codex) echo "$MOSAIC_HOME/runtime/codex/RUNTIME.md" ;;
+    opencode) echo "$MOSAIC_HOME/runtime/opencode/RUNTIME.md" ;;
+    pi) echo "$MOSAIC_HOME/runtime/pi/RUNTIME.md" ;;
+    *)
+      echo "[mosaic] ERROR: unsupported runtime '$runtime' for runtime contract." >&2
+      exit 1
+      ;;
+  esac
+}
+
+build_runtime_prompt() {
+  local runtime="$1"
+  local runtime_file
+  runtime_file="$(runtime_contract_path "$runtime")"
+  if [[ ! -f "$runtime_file" ]]; then
+    echo "[mosaic] ERROR: runtime contract not found: $runtime_file" >&2
+    exit 1
+  fi
+
+  # Inject active mission context FIRST so the agent sees it immediately
+  local mission_file=".mosaic/orchestrator/mission.json"
+  if [[ -f "$mission_file" ]] && command -v jq &>/dev/null; then
+    local m_status
+    m_status="$(jq -r '.status // "inactive"' "$mission_file" 2>/dev/null)"
+    if [[ "$m_status" == "active" || "$m_status" == "paused" ]]; then
+      local m_name m_id m_count m_completed
+      m_name="$(jq -r '.name // "unnamed"' "$mission_file")"
+      m_id="$(jq -r '.mission_id // ""' "$mission_file")"
+      m_count="$(jq '.milestones | length' "$mission_file")"
+      m_completed="$(jq '[.milestones[] | select(.status == "completed")] | length' "$mission_file")"
+
+      cat <<MISSION_EOF
+# ACTIVE MISSION — HARD GATE (Read Before Anything Else)
+
+An active orchestration mission exists in this project. This is a BLOCKING requirement.
+
+**Mission:** $m_name
+**ID:** $m_id
+**Status:** $m_status
+**Milestones:** $m_completed / $m_count completed
+
+## MANDATORY — Before ANY Response to the User
+
+You MUST complete these steps before responding to any user message, including simple greetings:
+
+1. Read \`~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md\` (mission lifecycle protocol)
+2. Read \`docs/MISSION-MANIFEST.md\` for full mission scope, milestones, and success criteria
+3. Read the latest scratchpad in \`docs/scratchpads/\` for session history, decisions, and corrections
+4. Read \`docs/TASKS.md\` for current task state (what is done, what is next)
+5. After reading all four, acknowledge the mission state to the user before proceeding
+
+If the user gives a task, execute it within the mission context. If no task is given, present mission status and ask how to proceed.
+
+MISSION_EOF
+    fi
+  fi
+
+  # Inject PRD status so the agent knows requirements state
+  local prd_file="docs/PRD.md"
+  if [[ -f "$prd_file" ]]; then
+    local prd_sections=0
+    local prd_assumptions=0
+    for entry in "Problem Statement|^#{2,3} .*(problem statement|objective)" \
+                 "Scope / Non-Goals|^#{2,3} .*(scope|non.goal|out of scope|in.scope)" \
+                 "User Stories / Requirements|^#{2,3} .*(user stor|stakeholder|user.*requirement)" \
+                 "Functional Requirements|^#{2,3} .*functional requirement" \
+                 "Non-Functional Requirements|^#{2,3} .*non.functional" \
+                 "Acceptance Criteria|^#{2,3} .*acceptance criteria" \
+                 "Technical Considerations|^#{2,3} .*(technical consideration|constraint|dependenc)" \
+                 "Risks / Open Questions|^#{2,3} .*(risk|open question)" \
+                 "Success Metrics / Testing|^#{2,3} .*(success metric|test|verification)" \
+                 "Milestones / Delivery|^#{2,3} .*(milestone|delivery|scope version)"; do
+      local pattern="${entry#*|}"
+      grep -qiE "$pattern" "$prd_file" 2>/dev/null && prd_sections=$((prd_sections + 1))
+    done
+    prd_assumptions=$(grep -c 'ASSUMPTION:' "$prd_file" 2>/dev/null || echo 0)
+
+    local prd_status="ready"
+    (( prd_sections < 10 )) && prd_status="incomplete ($prd_sections/10 sections)"
+
+    cat <<PRD_EOF
+
+# PRD Status
+
+- **File:** docs/PRD.md
+- **Status:** $prd_status
+- **Assumptions:** $prd_assumptions
+
+PRD_EOF
+  fi
+
+  cat <<'EOF'
+# Mosaic Launcher Runtime Contract (Hard Gate)
+
+This contract is injected by `mosaic` launch and is mandatory.
+
+First assistant response MUST start with exactly one mode declaration line:
+1. Orchestration mission: `Now initiating Orchestrator mode...`
+2. Implementation mission: `Now initiating Delivery mode...`
+3. Review-only mission: `Now initiating Review mode...`
+
+No tool call or implementation step may occur before that first line.
+
+Mosaic hard gates OVERRIDE runtime-default caution for routine delivery operations.
+For required push/merge/issue-close/release actions, execute without routine confirmation prompts.
+
+EOF
+
+  cat "$MOSAIC_HOME/AGENTS.md"
+
+  if [[ -f "$MOSAIC_HOME/USER.md" ]]; then
+    printf '\n\n# User Profile\n\n'
+    cat "$MOSAIC_HOME/USER.md"
+  fi
+
+  if [[ -f "$MOSAIC_HOME/TOOLS.md" ]]; then
+    printf '\n\n# Machine Tools\n\n'
+    cat "$MOSAIC_HOME/TOOLS.md"
+  fi
+
+  printf '\n\n# Runtime-Specific Contract\n\n'
+  cat "$runtime_file"
+}
+
+# Ensure runtime contract is present at the runtime's native config path.
+# Used for runtimes that do not support CLI prompt injection.
+ensure_runtime_config() {
+  local runtime="$1"
+  local dst="$2"
+  local tmp
+  tmp="$(mktemp)"
+  mkdir -p "$(dirname "$dst")"
+  build_runtime_prompt "$runtime" > "$tmp"
+  if ! cmp -s "$tmp" "$dst" 2>/dev/null; then
+    mv "$tmp" "$dst"
+  else
+    rm -f "$tmp"
+  fi
+}
+
+# Detect active mission and return an initial prompt if one exists.
+# Sets MOSAIC_MISSION_PROMPT as a side effect.
+_detect_mission_prompt() {
+  MOSAIC_MISSION_PROMPT=""
+  local mission_file=".mosaic/orchestrator/mission.json"
+  if [[ -f "$mission_file" ]] && command -v jq &>/dev/null; then
+    local m_status
+    m_status="$(jq -r '.status // "inactive"' "$mission_file" 2>/dev/null)"
+    if [[ "$m_status" == "active" || "$m_status" == "paused" ]]; then
+      local m_name
+      m_name="$(jq -r '.name // "unnamed"' "$mission_file")"
+      MOSAIC_MISSION_PROMPT="Active mission detected: ${m_name}. Read the mission state files and report status."
+    fi
+  fi
+}
+
+# Write a session lock if an active mission exists in the current directory.
+# Called before exec so $$ captures the PID that will become the agent process.
+_write_launcher_session_lock() {
+  local runtime="$1"
+  local mission_file=".mosaic/orchestrator/mission.json"
+  local lock_file=".mosaic/orchestrator/session.lock"
+
+  # Only write lock if mission exists and is active
+  [[ -f "$mission_file" ]] || return 0
+  command -v jq &>/dev/null || return 0
+
+  local m_status
+  m_status="$(jq -r '.status // "inactive"' "$mission_file" 2>/dev/null)"
+  [[ "$m_status" == "active" || "$m_status" == "paused" ]] || return 0
+
+  local session_id
+  session_id="${runtime}-$(date +%Y%m%d-%H%M%S)-$$"
+
+  jq -n \
+    --arg sid "$session_id" \
+    --arg rt "$runtime" \
+    --arg pid "$$" \
+    --arg ts "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+    --arg pp "$(pwd)" \
+    --arg mid "" \
+    '{
+      session_id: $sid,
+      runtime: $rt,
+      pid: ($pid | tonumber),
+      started_at: $ts,
+      project_path: $pp,
+      milestone_id: $mid
+    }' > "$lock_file"
+}
+
+# Clean up session lock on exit (covers normal exit + signals).
+# Registered via trap after _write_launcher_session_lock succeeds.
+_cleanup_session_lock() {
+  rm -f ".mosaic/orchestrator/session.lock" 2>/dev/null
+}
+
+# Launcher functions
+launch_claude() {
+  check_mosaic_home
+  check_agents_md
+  check_soul
+  check_runtime "claude"
+  check_sequential_thinking "claude"
+
+  _check_resumable_session
+
+  # Claude supports --append-system-prompt for direct injection
+  local runtime_prompt
+  runtime_prompt="$(build_runtime_prompt "claude")"
+
+  # If active mission exists and no user prompt was given, inject initial prompt
+  _detect_mission_prompt
+  _write_launcher_session_lock "claude"
+  trap _cleanup_session_lock EXIT INT TERM
+  if [[ -n "$MOSAIC_MISSION_PROMPT" && $# -eq 0 ]]; then
+    echo "[mosaic] Launching Claude Code (active mission detected)..."
+    exec claude --append-system-prompt "$runtime_prompt" "$MOSAIC_MISSION_PROMPT"
+  else
+    echo "[mosaic] Launching Claude Code..."
+    exec claude --append-system-prompt "$runtime_prompt" "$@"
+  fi
+}
+
+launch_opencode() {
+  check_mosaic_home
+  check_agents_md
+  check_soul
+  check_runtime "opencode"
+  check_sequential_thinking "opencode"
+
+  _check_resumable_session
+
+  # OpenCode reads from ~/.config/opencode/AGENTS.md
+  ensure_runtime_config "opencode" "$HOME/.config/opencode/AGENTS.md"
+  _write_launcher_session_lock "opencode"
+  trap _cleanup_session_lock EXIT INT TERM
+  echo "[mosaic] Launching OpenCode..."
+  exec opencode "$@"
+}
+
+launch_codex() {
+  check_mosaic_home
+  check_agents_md
+  check_soul
+  check_runtime "codex"
+  check_sequential_thinking "codex"
+
+  _check_resumable_session
+
+  # Codex reads from ~/.codex/instructions.md
+  ensure_runtime_config "codex" "$HOME/.codex/instructions.md"
+  _detect_mission_prompt
+  _write_launcher_session_lock "codex"
+  trap _cleanup_session_lock EXIT INT TERM
+  if [[ -n "$MOSAIC_MISSION_PROMPT" && $# -eq 0 ]]; then
+    echo "[mosaic] Launching Codex (active mission detected)..."
+    exec codex "$MOSAIC_MISSION_PROMPT"
+  else
+    echo "[mosaic] Launching Codex..."
+    exec codex "$@"
+  fi
+}
+
+launch_pi() {
+  check_mosaic_home
+  check_agents_md
+  check_soul
+  check_runtime "pi"
+  # Pi has native thinking levels — no sequential-thinking gate required
+
+  _check_resumable_session
+
+  local runtime_prompt
+  runtime_prompt="$(build_runtime_prompt "pi")"
+
+  # Build skill args from Mosaic skills directories (canonical + local)
+  local -a skill_args=()
+  for skills_root in "$MOSAIC_HOME/skills" "$MOSAIC_HOME/skills-local"; do
+    [[ -d "$skills_root" ]] || continue
+    for skill_dir in "$skills_root"/*/; do
+      [[ -f "${skill_dir}SKILL.md" ]] && skill_args+=(--skill "$skill_dir")
+    done
+  done
+
+  # Load Mosaic extension if present
+  local -a ext_args=()
+  local mosaic_ext="$MOSAIC_HOME/runtime/pi/mosaic-extension.ts"
+  [[ -f "$mosaic_ext" ]] && ext_args=(--extension "$mosaic_ext")
+
+  _detect_mission_prompt
+  _write_launcher_session_lock "pi"
+  trap _cleanup_session_lock EXIT INT TERM
+  if [[ -n "$MOSAIC_MISSION_PROMPT" && $# -eq 0 ]]; then
+    echo "[mosaic] Launching Pi (active mission detected)..."
+    exec pi --append-system-prompt "$runtime_prompt" \
+       "${skill_args[@]}" "${ext_args[@]}" "$MOSAIC_MISSION_PROMPT"
+  else
+    echo "[mosaic] Launching Pi..."
+    exec pi --append-system-prompt "$runtime_prompt" \
+       "${skill_args[@]}" "${ext_args[@]}" "$@"
+  fi
+}
+
+launch_yolo() {
+  if [[ $# -eq 0 ]]; then
+    echo "[mosaic] ERROR: yolo requires a runtime (claude|codex|opencode|pi)." >&2
+    echo "[mosaic] Example: mosaic yolo claude" >&2
+    exit 1
+  fi
+
+  local runtime="$1"
+  shift
+
+  case "$runtime" in
+    claude)
+      check_mosaic_home
+      check_agents_md
+      check_soul
+      check_runtime "claude"
+      check_sequential_thinking "claude"
+
+      # Claude uses an explicit dangerous permissions flag.
+      local runtime_prompt
+      runtime_prompt="$(build_runtime_prompt "claude")"
+
+      _detect_mission_prompt
+      _write_launcher_session_lock "claude"
+      trap _cleanup_session_lock EXIT INT TERM
+      if [[ -n "$MOSAIC_MISSION_PROMPT" && $# -eq 0 ]]; then
+        echo "[mosaic] Launching Claude Code in YOLO mode (active mission detected)..."
+        exec claude --dangerously-skip-permissions --append-system-prompt "$runtime_prompt" "$MOSAIC_MISSION_PROMPT"
+      else
+        echo "[mosaic] Launching Claude Code in YOLO mode (dangerous permissions enabled)..."
+        exec claude --dangerously-skip-permissions --append-system-prompt "$runtime_prompt" "$@"
+      fi
+      ;;
+    codex)
+      check_mosaic_home
+      check_agents_md
+      check_soul
+      check_runtime "codex"
+      check_sequential_thinking "codex"
+
+      # Codex reads instructions.md from ~/.codex and supports a direct dangerous flag.
+      ensure_runtime_config "codex" "$HOME/.codex/instructions.md"
+      _detect_mission_prompt
+      _write_launcher_session_lock "codex"
+      trap _cleanup_session_lock EXIT INT TERM
+      if [[ -n "$MOSAIC_MISSION_PROMPT" && $# -eq 0 ]]; then
+        echo "[mosaic] Launching Codex in YOLO mode (active mission detected)..."
+        exec codex --dangerously-bypass-approvals-and-sandbox "$MOSAIC_MISSION_PROMPT"
+      else
+        echo "[mosaic] Launching Codex in YOLO mode (dangerous permissions enabled)..."
+        exec codex --dangerously-bypass-approvals-and-sandbox "$@"
+      fi
+      ;;
+    opencode)
+      check_mosaic_home
+      check_agents_md
+      check_soul
+      check_runtime "opencode"
+      check_sequential_thinking "opencode"
+
+      # OpenCode defaults to allow-all permissions unless user config restricts them.
+      ensure_runtime_config "opencode" "$HOME/.config/opencode/AGENTS.md"
+      _write_launcher_session_lock "opencode"
+      trap _cleanup_session_lock EXIT INT TERM
+      echo "[mosaic] Launching OpenCode in YOLO mode..."
+      exec opencode "$@"
+      ;;
+    pi)
+      # Pi has no permission restrictions — yolo is identical to normal launch
+      launch_pi "$@"
+      ;;
+    *)
+      echo "[mosaic] ERROR: Unsupported yolo runtime '$runtime'. Use claude|codex|opencode|pi." >&2
+      exit 1
+      ;;
+  esac
+}
+
+# Delegate to existing scripts
+run_init() {
+  # Prefer wizard if Node.js and bundle are available
+  local wizard_bin="$MOSAIC_HOME/dist/mosaic-wizard.mjs"
+  if command -v node >/dev/null 2>&1 && [[ -f "$wizard_bin" ]]; then
+    exec node "$wizard_bin" "$@"
+  fi
+  # Fallback to legacy bash wizard
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-init" "$@"
+}
+
+run_doctor() {
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-doctor" "$@"
+}
+
+run_sync() {
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-sync-skills" "$@"
+}
+
+run_seq() {
+  check_mosaic_home
+  local checker="$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking"
+  local action="${1:-check}"
+
+  case "$action" in
+    check)
+      shift || true
+      exec "$checker" --check "$@"
+      ;;
+    fix|apply)
+      shift || true
+      exec "$checker" "$@"
+      ;;
+    start)
+      shift || true
+      check_runtime "npx"
+      echo "[mosaic] Starting sequential-thinking MCP server..."
+      exec npx -y @modelcontextprotocol/server-sequential-thinking "$@"
+      ;;
+    *)
+      echo "[mosaic] ERROR: Unknown seq subcommand '$action'." >&2
+      echo "[mosaic] Use: mosaic seq check|fix|start" >&2
+      exit 1
+      ;;
+  esac
+}
+
+run_coord() {
+  check_mosaic_home
+  local runtime="claude"
+  local runtime_flag=""
+  local yolo_flag=""
+  local -a coord_args=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --claude|--codex|--pi)
+        local selected_runtime="${1#--}"
+        if [[ -n "$runtime_flag" ]] && [[ "$runtime" != "$selected_runtime" ]]; then
+          echo "[mosaic] ERROR: --claude, --codex, and --pi are mutually exclusive for 'mosaic coord'." >&2
+          exit 1
+        fi
+        runtime="$selected_runtime"
+        runtime_flag="$1"
+        shift
+        ;;
+      --yolo)
+        yolo_flag="--yolo"
+        shift
+        ;;
+      *)
+        coord_args+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  local subcmd="${coord_args[0]:-help}"
+  if (( ${#coord_args[@]} > 1 )); then
+    set -- "${coord_args[@]:1}"
+  else
+    set --
+  fi
+
+  local tool_dir="$MOSAIC_HOME/tools/orchestrator"
+
+  case "$subcmd" in
+    status|session)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/session-status.sh" "$@"
+      ;;
+    init)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/mission-init.sh" "$@"
+      ;;
+    mission|progress)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/mission-status.sh" "$@"
+      ;;
+    continue|next)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/continue-prompt.sh" "$@"
+      ;;
+    run|start)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/session-run.sh" ${yolo_flag:+"$yolo_flag"} "$@"
+      ;;
+    smoke|test)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/smoke-test.sh" "$@"
+      ;;
+    resume|recover)
+      MOSAIC_COORD_RUNTIME="$runtime" exec bash "$tool_dir/session-resume.sh" "$@"
+      ;;
+    help|*)
+      cat <<COORD_USAGE
+mosaic coord — r0 manual coordinator tools
+
+Commands:
+  init --name <name> [opts]   Initialize a new mission
+  mission [--project <path>]  Show mission progress dashboard
+  status [--project <path>]   Check agent session health
+  continue [--project <path>] Generate continuation prompt for next session
+  run [--project <path>]      Generate context and launch selected runtime
+  smoke                       Run orchestration behavior smoke checks
+  resume [--project <path>]   Crash recovery (detect dirty state, generate fix)
+
+Runtime:
+  --claude                    Use Claude runtime hints/prompts (default)
+  --codex                     Use Codex runtime hints/prompts
+  --pi                        Use Pi runtime hints/prompts
+  --yolo                      Launch runtime in dangerous/skip-permissions mode (run only)
+
+Examples:
+  mosaic coord init --name "Security Fix" --milestones "Critical,High,Medium"
+  mosaic coord mission
+  mosaic coord --codex mission
+  mosaic coord --pi run
+  mosaic coord continue --copy
+  mosaic coord run
+  mosaic coord run --codex
+  mosaic coord --yolo run
+  mosaic coord smoke
+  mosaic coord continue --codex --copy
+
+COORD_USAGE
+      ;;
+  esac
+}
+
+# Resume advisory — prints warning if active mission or stale session detected
+_check_resumable_session() {
+  local mission_file=".mosaic/orchestrator/mission.json"
+  local lock_file=".mosaic/orchestrator/session.lock"
+
+  command -v jq &>/dev/null || return 0
+
+  if [[ -f "$lock_file" ]]; then
+    local pid
+    pid="$(jq -r '.pid // 0' "$lock_file" 2>/dev/null)"
+    if [[ -n "$pid" ]] && [[ "$pid" != "0" ]] && ! kill -0 "$pid" 2>/dev/null; then
+      # Stale lock from a dead session — clean it up
+      rm -f "$lock_file"
+      echo "[mosaic] Cleaned up stale session lock (PID $pid no longer running)."
+      echo ""
+    fi
+  elif [[ -f "$mission_file" ]]; then
+    local status
+    status="$(jq -r '.status // "inactive"' "$mission_file" 2>/dev/null)"
+    if [[ "$status" == "active" ]]; then
+      echo "[mosaic] Active mission detected. Generate continuation prompt with:"
+      echo "[mosaic]   mosaic coord continue"
+      echo ""
+    fi
+  fi
+}
+
+run_prdy() {
+  check_mosaic_home
+  local runtime="claude"
+  local runtime_flag=""
+  local -a prdy_args=()
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --claude|--codex|--pi)
+        local selected_runtime="${1#--}"
+        if [[ -n "$runtime_flag" ]] && [[ "$runtime" != "$selected_runtime" ]]; then
+          echo "[mosaic] ERROR: --claude, --codex, and --pi are mutually exclusive for 'mosaic prdy'." >&2
+          exit 1
+        fi
+        runtime="$selected_runtime"
+        runtime_flag="$1"
+        shift
+        ;;
+      *)
+        prdy_args+=("$1")
+        shift
+        ;;
+    esac
+  done
+
+  local subcmd="${prdy_args[0]:-help}"
+  if (( ${#prdy_args[@]} > 1 )); then
+    set -- "${prdy_args[@]:1}"
+  else
+    set --
+  fi
+
+  local tool_dir="$MOSAIC_HOME/tools/prdy"
+
+  case "$subcmd" in
+    init)
+      MOSAIC_PRDY_RUNTIME="$runtime" exec bash "$tool_dir/prdy-init.sh" "$@"
+      ;;
+    update)
+      MOSAIC_PRDY_RUNTIME="$runtime" exec bash "$tool_dir/prdy-update.sh" "$@"
+      ;;
+    validate|check)
+      MOSAIC_PRDY_RUNTIME="$runtime" exec bash "$tool_dir/prdy-validate.sh" "$@"
+      ;;
+    status)
+      exec bash "$tool_dir/prdy-status.sh" "$@"
+      ;;
+    help|*)
+      cat <<PRDY_USAGE
+mosaic prdy — PRD creation and validation tools
+
+Commands:
+  init [--project <path>] [--name <feature>]   Create docs/PRD.md via guided runtime session
+  update [--project <path>]                    Update existing docs/PRD.md via guided runtime session
+  validate [--project <path>]                  Check PRD completeness against Mosaic guide (bash-only)
+  status [--project <path>] [--format short|json]  Quick PRD health check (one-liner)
+
+Runtime:
+  --claude                    Use Claude runtime (default)
+  --codex                     Use Codex runtime
+  --pi                        Use Pi runtime
+
+Examples:
+  mosaic prdy init --name "User Authentication"
+  mosaic prdy update
+  mosaic prdy --pi init --name "User Authentication"
+  mosaic prdy --codex init --name "User Authentication"
+  mosaic prdy validate
+
+Output location: docs/PRD.md (per Mosaic PRD guide)
+
+PRDY_USAGE
+      ;;
+  esac
+}
+
+run_bootstrap() {
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-bootstrap-repo" "$@"
+}
+
+run_release_upgrade() {
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-release-upgrade" "$@"
+}
+
+run_project_upgrade() {
+  check_mosaic_home
+  exec "$MOSAIC_HOME/bin/mosaic-upgrade" "$@"
+}
+
+run_upgrade() {
+  check_mosaic_home
+
+  # Default: upgrade installed release
+  if [[ $# -eq 0 ]]; then
+    run_release_upgrade
+  fi
+
+  case "$1" in
+    release)
+      shift
+      run_release_upgrade "$@"
+      ;;
+    check)
+      shift
+      run_release_upgrade --dry-run "$@"
+      ;;
+    project)
+      shift
+      run_project_upgrade "$@"
+      ;;
+
+    # Backward compatibility for historical project-upgrade usage.
+    --all|--root)
+      run_project_upgrade "$@"
+      ;;
+    --dry-run|--ref|--keep|--overwrite|-y|--yes)
+      run_release_upgrade "$@"
+      ;;
+    -*)
+      run_release_upgrade "$@"
+      ;;
+    *)
+      run_project_upgrade "$@"
+      ;;
+  esac
+}
+
+# Main router
+if [[ $# -eq 0 ]]; then
+  usage
+  exit 0
+fi
+
+command="$1"
+shift
+
+case "$command" in
+  pi)         launch_pi "$@" ;;
+  claude)     launch_claude "$@" ;;
+  opencode)   launch_opencode "$@" ;;
+  codex)      launch_codex "$@" ;;
+  yolo|--yolo) launch_yolo "$@" ;;
+  init)       run_init "$@" ;;
+  doctor)     run_doctor "$@" ;;
+  sync)       run_sync "$@" ;;
+  seq)        run_seq "$@" ;;
+  bootstrap)  run_bootstrap "$@" ;;
+  prdy)       run_prdy "$@" ;;
+  coord)      run_coord "$@" ;;
+  upgrade)    run_upgrade "$@" ;;
+  release-upgrade) run_release_upgrade "$@" ;;
+  project-upgrade) run_project_upgrade "$@" ;;
+  help|-h|--help)  usage ;;
+  version|-v|--version) echo "mosaic $VERSION" ;;
+  *)
+    echo "[mosaic] Unknown command: $command" >&2
+    echo "[mosaic] Run 'mosaic --help' for usage." >&2
+    exit 1
+    ;;
+esac

packages/mosaic/framework/bin/mosaic-bootstrap-repo

@@ -113,8 +113,8 @@ echo "[mosaic] Optional: run orchestrator rail via ~/.config/mosaic/bin/mosaic-o
 echo "[mosaic] Optional: run detached orchestrator via bash $TARGET_DIR/scripts/agent/orchestrator-daemon.sh start"
 
 if [[ -n "$QUALITY_TEMPLATE" ]]; then
-  if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-quality-apply" ]]; then
+  if [[ -x "$MOSAIC_HOME/bin/mosaic-quality-apply" ]]; then
-    "$MOSAIC_HOME/tools/_scripts/mosaic-quality-apply" --template "$QUALITY_TEMPLATE" --target "$TARGET_DIR"
+    "$MOSAIC_HOME/bin/mosaic-quality-apply" --template "$QUALITY_TEMPLATE" --target "$TARGET_DIR"
     if [[ -f "$TARGET_DIR/.mosaic/quality-rails.yml" ]]; then
       sed -i "s/^enabled:.*/enabled: true/" "$TARGET_DIR/.mosaic/quality-rails.yml"
       sed -i "s/^template:.*/template: \"$QUALITY_TEMPLATE\"/" "$TARGET_DIR/.mosaic/quality-rails.yml"

packages/mosaic/framework/bin/mosaic-doctor

@@ -165,18 +165,18 @@ expect_dir "$MOSAIC_HOME/profiles"
 expect_dir "$MOSAIC_HOME/templates/agent"
 expect_dir "$MOSAIC_HOME/skills"
 expect_dir "$MOSAIC_HOME/skills-local"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets"
+expect_file "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-ensure-sequential-thinking"
+expect_file "$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-sync-skills"
+expect_file "$MOSAIC_HOME/bin/mosaic-sync-skills"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-projects"
+expect_file "$MOSAIC_HOME/bin/mosaic-projects"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-quality-apply"
+expect_file "$MOSAIC_HOME/bin/mosaic-quality-apply"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-quality-verify"
+expect_file "$MOSAIC_HOME/bin/mosaic-quality-verify"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-run"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-run"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-sync-tasks"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-sync-tasks"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-drain"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-drain"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-matrix-publish"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-publish"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-matrix-consume"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-consume"
-expect_file "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-matrix-cycle"
+expect_file "$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-cycle"
 expect_file "$MOSAIC_HOME/tools/git/ci-queue-wait.sh"
 expect_file "$MOSAIC_HOME/tools/git/pr-ci-wait.sh"
 expect_file "$MOSAIC_HOME/tools/orchestrator-matrix/transport/matrix_transport.py"
@@ -215,8 +215,8 @@ check_runtime_contract_file "$HOME/.config/opencode/AGENTS.md" "$MOSAIC_HOME/run
 check_runtime_contract_file "$HOME/.codex/instructions.md" "$MOSAIC_HOME/runtime/codex/instructions.md" "codex"
 
 # Sequential-thinking MCP hard requirement.
-if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-ensure-sequential-thinking" ]]; then
+if [[ -x "$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking" ]]; then
-  if "$MOSAIC_HOME/tools/_scripts/mosaic-ensure-sequential-thinking" --check >/dev/null 2>&1; then
+  if "$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking" --check >/dev/null 2>&1; then
     pass "sequential-thinking MCP configured and available"
   else
     warn "sequential-thinking MCP missing or misconfigured"
@@ -422,8 +422,8 @@ with open('$pi_settings_file', 'w') as f:
   fi
 
   # 4. Run link-runtime-assets if available
-  if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets" ]]; then
+  if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then
-    "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets" >/dev/null 2>&1 && fix "Re-ran mosaic-link-runtime-assets"
+    "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" >/dev/null 2>&1 && fix "Re-ran mosaic-link-runtime-assets"
   fi
 
   echo "[mosaic-doctor] fixes=$fix_count"

packages/mosaic/framework/bin/mosaic-init

@@ -60,14 +60,12 @@ Options:
   --timezone <tz>          Your timezone (e.g., "America/Chicago")
   --non-interactive        Fail if any required value is missing (no prompts)
   --soul-only              Only generate SOUL.md
-  --force                  Overwrite existing files without prompting
   -h, --help               Show help
 USAGE
 }
 
 NON_INTERACTIVE=0
 SOUL_ONLY=0
-FORCE=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -81,7 +79,6 @@ while [[ $# -gt 0 ]]; do
     --timezone) TIMEZONE="$2"; shift 2 ;;
     --non-interactive) NON_INTERACTIVE=1; shift ;;
     --soul-only) SOUL_ONLY=1; shift ;;
-    --force) FORCE=1; shift ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
   esac
@@ -142,134 +139,6 @@ prompt_multiline() {
   eval "$var_name=\"$value\""
 }
 
-# ── Existing file detection ────────────────────────────────────
-
-detect_existing_config() {
-  local found=0
-  local existing_files=()
-
-  [[ -f "$SOUL_OUTPUT" ]] && { found=1; existing_files+=("SOUL.md"); }
-  [[ -f "$USER_OUTPUT" ]] && { found=1; existing_files+=("USER.md"); }
-  [[ -f "$TOOLS_OUTPUT" ]] && { found=1; existing_files+=("TOOLS.md"); }
-
-  if [[ $found -eq 0 || $FORCE -eq 1 ]]; then
-    return 0  # No existing files or --force: proceed with fresh install
-  fi
-
-  echo "[mosaic-init] Existing configuration detected:"
-  for f in "${existing_files[@]}"; do
-    echo "  ✓ $f"
-  done
-
-  # Show current agent name if SOUL.md exists
-  if [[ -f "$SOUL_OUTPUT" ]]; then
-    local current_name
-    current_name=$(grep -oP 'You are \*\*\K[^*]+' "$SOUL_OUTPUT" 2>/dev/null || true)
-    if [[ -n "$current_name" ]]; then
-      echo "  Agent: $current_name"
-    fi
-  fi
-  echo ""
-
-  if [[ $NON_INTERACTIVE -eq 1 ]]; then
-    echo "[mosaic-init] Existing config found. Use --force to overwrite in non-interactive mode."
-    exit 0
-  fi
-
-  echo "What would you like to do?"
-  echo "  1) keep       — Keep existing files, skip init (default)"
-  echo "  2) import     — Import values from existing files as defaults, then regenerate"
-  echo "  3) overwrite  — Start fresh, overwrite all files"
-  printf "Choose [1/2/3]: "
-  read -r choice
-
-  case "${choice:-1}" in
-    1|keep)
-      echo "[mosaic-init] Keeping existing configuration."
-      # Still push to runtime adapters in case framework was updated
-      if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets" ]]; then
-        echo "[mosaic-init] Updating runtime adapters..."
-        "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets"
-      fi
-      echo "[mosaic-init] Done. Launch with: mosaic claude"
-      exit 0
-      ;;
-    2|import)
-      echo "[mosaic-init] Importing values from existing files as defaults..."
-      import_existing_values
-      ;;
-    3|overwrite)
-      echo "[mosaic-init] Starting fresh install..."
-      # Back up existing files
-      local ts
-      ts=$(date +%Y%m%d%H%M%S)
-      for f in "${existing_files[@]}"; do
-        local src="$MOSAIC_HOME/$f"
-        if [[ -f "$src" ]]; then
-          cp "$src" "${src}.bak.${ts}"
-          echo "  Backed up $f → ${f}.bak.${ts}"
-        fi
-      done
-      ;;
-    *)
-      echo "[mosaic-init] Invalid choice. Keeping existing configuration."
-      exit 0
-      ;;
-  esac
-}
-
-import_existing_values() {
-  # Import SOUL.md values
-  if [[ -f "$SOUL_OUTPUT" ]]; then
-    local content
-    content=$(cat "$SOUL_OUTPUT")
-
-    if [[ -z "$AGENT_NAME" ]]; then
-      AGENT_NAME=$(echo "$content" | grep -oP 'You are \*\*\K[^*]+' 2>/dev/null || true)
-    fi
-    if [[ -z "$ROLE_DESCRIPTION" ]]; then
-      ROLE_DESCRIPTION=$(echo "$content" | grep -oP 'Role identity: \K.+' 2>/dev/null || true)
-    fi
-    if [[ -z "$STYLE" ]]; then
-      if echo "$content" | grep -q 'Be direct, concise'; then
-        STYLE="direct"
-      elif echo "$content" | grep -q 'Be warm and conversational'; then
-        STYLE="friendly"
-      elif echo "$content" | grep -q 'Use professional, structured'; then
-        STYLE="formal"
-      fi
-    fi
-  fi
-
-  # Import USER.md values
-  if [[ -f "$USER_OUTPUT" ]]; then
-    local content
-    content=$(cat "$USER_OUTPUT")
-
-    if [[ -z "$USER_NAME" ]]; then
-      USER_NAME=$(echo "$content" | grep -oP '\*\*Name:\*\* \K.+' 2>/dev/null || true)
-    fi
-    if [[ -z "$PRONOUNS" ]]; then
-      PRONOUNS=$(echo "$content" | grep -oP '\*\*Pronouns:\*\* \K.+' 2>/dev/null || true)
-    fi
-    if [[ -z "$TIMEZONE" ]]; then
-      TIMEZONE=$(echo "$content" | grep -oP '\*\*Timezone:\*\* \K.+' 2>/dev/null || true)
-    fi
-  fi
-
-  # Import TOOLS.md values
-  if [[ -f "$TOOLS_OUTPUT" ]]; then
-    local content
-    content=$(cat "$TOOLS_OUTPUT")
-
-    if [[ -z "$CREDENTIALS_LOCATION" ]]; then
-      CREDENTIALS_LOCATION=$(echo "$content" | grep -oP '\*\*Location:\*\* \K.+' 2>/dev/null || true)
-    fi
-  fi
-}
-
-detect_existing_config
-
 # ── SOUL.md Generation ────────────────────────────────────────
 echo "[mosaic-init] Generating SOUL.md — agent identity contract"
 echo ""
@@ -392,9 +261,9 @@ echo "[mosaic-init] Style: $STYLE"
 
 if [[ $SOUL_ONLY -eq 1 ]]; then
   # Push to runtime adapters and exit
-  if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets" ]]; then
+  if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then
     echo "[mosaic-init] Updating runtime adapters..."
-    "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets"
+    "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
   fi
   echo "[mosaic-init] Done. Launch with: mosaic claude"
   exit 0
@@ -544,10 +413,10 @@ fi
 # ── Finalize ──────────────────────────────────────────────────
 
 # Push to runtime adapters
-if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets" ]]; then
+if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then
   echo ""
   echo "[mosaic-init] Updating runtime adapters..."
-  "$MOSAIC_HOME/tools/_scripts/mosaic-link-runtime-assets"
+  "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
 fi
 
 echo ""

packages/mosaic/framework/bin/mosaic-link-runtime-assets

@@ -128,8 +128,8 @@ fi
 # Pi extension is loaded via --extension flag in the mosaic launcher.
 # Do NOT copy into ~/.pi/agent/extensions/ — that causes duplicate loading.
 
-if [[ -x "$MOSAIC_HOME/tools/_scripts/mosaic-ensure-sequential-thinking" ]]; then
+if [[ -x "$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking" ]]; then
-  "$MOSAIC_HOME/tools/_scripts/mosaic-ensure-sequential-thinking"
+  "$MOSAIC_HOME/bin/mosaic-ensure-sequential-thinking"
 fi
 
 echo "[mosaic-link] Runtime assets synced (non-symlink mode)"

packages/mosaic/framework/bin/mosaic-orchestrator-drain

@@ -2,8 +2,8 @@
 set -euo pipefail
 
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
-sync_cmd="$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-sync-tasks"
+sync_cmd="$MOSAIC_HOME/bin/mosaic-orchestrator-sync-tasks"
-run_cmd="$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-run"
+run_cmd="$MOSAIC_HOME/bin/mosaic-orchestrator-run"
 
 do_sync=1
 poll_sec=15

packages/mosaic/framework/bin/mosaic-orchestrator-matrix-cycle

@@ -3,9 +3,9 @@ set -euo pipefail
 
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 
-consume="$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-matrix-consume"
+consume="$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-consume"
-run="$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-run"
+run="$MOSAIC_HOME/bin/mosaic-orchestrator-run"
-publish="$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-matrix-publish"
+publish="$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-publish"
 
 for cmd in "$consume" "$run" "$publish"; do
   if [[ ! -x "$cmd" ]]; then

packages/mosaic/framework/bin/mosaic-projects

@@ -151,7 +151,7 @@ case "$cmd" in
       [[ -n "$quality_template" ]] && args+=(--quality-template "$quality_template")
       args+=("$repo")
       echo "[mosaic-projects] bootstrap: $repo"
-      "$MOSAIC_HOME/tools/_scripts/mosaic-bootstrap-repo" "${args[@]}"
+      "$MOSAIC_HOME/bin/mosaic-bootstrap-repo" "${args[@]}"
       add_repo "$repo" || true
     done
     ;;
@@ -193,7 +193,7 @@ case "$cmd" in
             drain)
               args=(--poll-sec "$poll_sec")
               [[ $no_sync -eq 1 ]] && args+=(--no-sync)
-              "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-drain" "${args[@]}"
+              "$MOSAIC_HOME/bin/mosaic-orchestrator-drain" "${args[@]}"
               ;;
             status)
               echo "[mosaic-projects] no daemon script in repo; run from bootstrapped repo or re-bootstrap"

packages/mosaic/framework/bin/mosaic-sync-skills

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

packages/mosaic/framework/bin/mosaic-upgrade-slaves

@@ -2,7 +2,7 @@
 set -euo pipefail
 
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
-BOOTSTRAP_CMD="$MOSAIC_HOME/tools/_scripts/mosaic-bootstrap-repo"
+BOOTSTRAP_CMD="$MOSAIC_HOME/bin/mosaic-bootstrap-repo"
 
 roots=("$HOME/src")
 apply=0

packages/mosaic/framework/bin/mosaic-wizard

@@ -12,7 +12,7 @@ fi
 
 if [[ ! -f "$WIZARD_BIN" ]]; then
   echo "[mosaic-wizard] ERROR: Wizard bundle not found." >&2
-  echo "[mosaic-wizard] Re-install with: npm install -g @mosaic/mosaic" >&2
+  echo "[mosaic-wizard] Run 'pnpm build' in the mosaic-bootstrap repo, or re-install Mosaic." >&2
   exit 1
 fi
 

packages/mosaic/framework/bin/mosaic.ps1

@@ -0,0 +1,437 @@
+# mosaic.ps1 — Unified agent launcher and management CLI (Windows)
+#
+# AGENTS.md is the global policy source for all agent sessions.
+# The launcher injects a composed runtime contract (AGENTS + runtime reference).
+#
+# Usage:
+#   mosaic claude [args...]       Launch Claude Code with runtime contract injected
+#   mosaic opencode [args...]     Launch OpenCode with runtime contract injected
+#   mosaic codex [args...]        Launch Codex with runtime contract injected
+#   mosaic yolo <runtime> [args...]  Launch runtime in dangerous-permissions mode
+#   mosaic --yolo <runtime> [args...]  Alias for yolo
+#   mosaic init [args...]         Generate SOUL.md interactively
+#   mosaic doctor [args...]       Health audit
+#   mosaic sync [args...]         Sync skills
+$ErrorActionPreference = "Stop"
+
+$MosaicHome = if ($env:MOSAIC_HOME) { $env:MOSAIC_HOME } else { Join-Path $env:USERPROFILE ".config\mosaic" }
+$Version = "0.1.0"
+
+function Show-Usage {
+    Write-Host @"
+mosaic $Version - Unified agent launcher
+
+Usage: mosaic <command> [args...]
+
+Agent Launchers:
+  claude [args...]       Launch Claude Code with runtime contract injected
+  opencode [args...]     Launch OpenCode with runtime contract injected
+  codex [args...]        Launch Codex with runtime contract injected
+  yolo <runtime> [args...]  Dangerous mode for claude|codex|opencode
+  --yolo <runtime> [args...] Alias for yolo
+
+Management:
+  init [args...]         Generate SOUL.md (agent identity contract)
+  doctor [args...]       Audit runtime state and detect drift
+  sync [args...]         Sync skills from canonical source
+  bootstrap <path>       Bootstrap a repo with Mosaic standards
+  upgrade [mode] [args]  Upgrade release (default) or project files
+  upgrade check          Check release upgrade status (no changes)
+  release-upgrade [...]  Upgrade installed Mosaic release
+  project-upgrade [...]  Clean up stale SOUL.md/CLAUDE.md in a project
+
+Options:
+  -h, --help             Show this help
+  -v, --version          Show version
+"@
+}
+
+function Assert-MosaicHome {
+    if (-not (Test-Path $MosaicHome)) {
+        Write-Host "[mosaic] ERROR: ~/.config/mosaic not found." -ForegroundColor Red
+        Write-Host "[mosaic] Install with: bash <(curl -fsSL https://git.mosaicstack.dev/mosaic/mosaic-stack/raw/branch/main/tools/install.sh)"
+        exit 1
+    }
+}
+
+function Assert-AgentsMd {
+    $agentsPath = Join-Path $MosaicHome "AGENTS.md"
+    if (-not (Test-Path $agentsPath)) {
+        Write-Host "[mosaic] ERROR: ~/.config/mosaic/AGENTS.md not found." -ForegroundColor Red
+        Write-Host "[mosaic] Re-run the installer."
+        exit 1
+    }
+}
+
+function Assert-Soul {
+    $soulPath = Join-Path $MosaicHome "SOUL.md"
+    if (-not (Test-Path $soulPath)) {
+        Write-Host "[mosaic] SOUL.md not found. Running mosaic init..."
+        & (Join-Path $MosaicHome "bin\mosaic-init.ps1")
+    }
+}
+
+function Assert-Runtime {
+    param([string]$Cmd)
+    if (-not (Get-Command $Cmd -ErrorAction SilentlyContinue)) {
+        Write-Host "[mosaic] ERROR: '$Cmd' not found in PATH." -ForegroundColor Red
+        Write-Host "[mosaic] Install $Cmd before launching."
+        exit 1
+    }
+}
+
+function Assert-SequentialThinking {
+    $checker = Join-Path $MosaicHome "bin\mosaic-ensure-sequential-thinking.ps1"
+    if (-not (Test-Path $checker)) {
+        Write-Host "[mosaic] ERROR: sequential-thinking checker missing: $checker" -ForegroundColor Red
+        exit 1
+    }
+    try {
+        & $checker -Check *>$null
+    }
+    catch {
+        Write-Host "[mosaic] ERROR: sequential-thinking MCP is required but not configured." -ForegroundColor Red
+        Write-Host "[mosaic] Run: $checker"
+        exit 1
+    }
+}
+
+function Get-ActiveMission {
+    $missionFile = Join-Path (Get-Location) ".mosaic\orchestrator\mission.json"
+    if (-not (Test-Path $missionFile)) {
+        return $null
+    }
+
+    try {
+        $mission = Get-Content $missionFile -Raw | ConvertFrom-Json
+    }
+    catch {
+        return $null
+    }
+
+    $status = [string]$mission.status
+    if ([string]::IsNullOrWhiteSpace($status)) {
+        $status = "inactive"
+    }
+    if ($status -ne "active" -and $status -ne "paused") {
+        return $null
+    }
+
+    $name = [string]$mission.name
+    if ([string]::IsNullOrWhiteSpace($name)) {
+        $name = "unnamed"
+    }
+
+    $id = [string]$mission.mission_id
+    if ([string]::IsNullOrWhiteSpace($id)) {
+        $id = ""
+    }
+
+    $milestones = @($mission.milestones)
+    $milestoneCount = $milestones.Count
+    $milestoneCompleted = @($milestones | Where-Object { $_.status -eq "completed" }).Count
+
+    return [PSCustomObject]@{
+        Name = $name
+        Id = $id
+        Status = $status
+        MilestoneCount = $milestoneCount
+        MilestoneCompleted = $milestoneCompleted
+    }
+}
+
+function Get-MissionContractBlock {
+    $mission = Get-ActiveMission
+    if ($null -eq $mission) {
+        return ""
+    }
+
+    return @"
+# ACTIVE MISSION — HARD GATE (Read Before Anything Else)
+
+An active orchestration mission exists in this project. This is a BLOCKING requirement.
+
+**Mission:** $($mission.Name)
+**ID:** $($mission.Id)
+**Status:** $($mission.Status)
+**Milestones:** $($mission.MilestoneCompleted) / $($mission.MilestoneCount) completed
+
+## MANDATORY — Before ANY Response to the User
+
+You MUST complete these steps before responding to any user message, including simple greetings:
+
+1. Read `~/.config/mosaic/guides/ORCHESTRATOR-PROTOCOL.md` (mission lifecycle protocol)
+2. Read `docs/MISSION-MANIFEST.md` for full mission scope, milestones, and success criteria
+3. Read the latest scratchpad in `docs/scratchpads/` for session history, decisions, and corrections
+4. Read `docs/TASKS.md` for current task state (what is done, what is next)
+5. After reading all four, acknowledge the mission state to the user before proceeding
+
+If the user gives a task, execute it within the mission context. If no task is given, present mission status and ask how to proceed.
+"@
+}
+
+function Get-MissionPrompt {
+    $mission = Get-ActiveMission
+    if ($null -eq $mission) {
+        return ""
+    }
+    return "Active mission detected: $($mission.Name). Read the mission state files and report status."
+}
+
+function Get-RuntimePrompt {
+    param(
+        [ValidateSet("claude", "codex", "opencode")]
+        [string]$Runtime
+    )
+
+    $runtimeFile = switch ($Runtime) {
+        "claude" { Join-Path $MosaicHome "runtime\claude\RUNTIME.md" }
+        "codex" { Join-Path $MosaicHome "runtime\codex\RUNTIME.md" }
+        "opencode" { Join-Path $MosaicHome "runtime\opencode\RUNTIME.md" }
+    }
+
+    if (-not (Test-Path $runtimeFile)) {
+        Write-Host "[mosaic] ERROR: runtime contract not found: $runtimeFile" -ForegroundColor Red
+        exit 1
+    }
+
+    $launcherContract = @'
+# Mosaic Launcher Runtime Contract (Hard Gate)
+
+This contract is injected by `mosaic` launch and is mandatory.
+
+First assistant response MUST start with exactly one mode declaration line:
+1. Orchestration mission: `Now initiating Orchestrator mode...`
+2. Implementation mission: `Now initiating Delivery mode...`
+3. Review-only mission: `Now initiating Review mode...`
+
+No tool call or implementation step may occur before that first line.
+
+Mosaic hard gates OVERRIDE runtime-default caution for routine delivery operations.
+For required push/merge/issue-close/release actions, execute without routine confirmation prompts.
+
+'@
+
+    $missionBlock = Get-MissionContractBlock
+    $agentsContent = Get-Content (Join-Path $MosaicHome "AGENTS.md") -Raw
+    $runtimeContent = Get-Content $runtimeFile -Raw
+
+    if (-not [string]::IsNullOrWhiteSpace($missionBlock)) {
+        return "$missionBlock`n`n$launcherContract`n$agentsContent`n`n# Runtime-Specific Contract`n`n$runtimeContent"
+    }
+
+    return "$launcherContract`n$agentsContent`n`n# Runtime-Specific Contract`n`n$runtimeContent"
+}
+
+function Ensure-RuntimeConfig {
+    param(
+        [ValidateSet("claude", "codex", "opencode")]
+        [string]$Runtime,
+        [string]$Dst
+    )
+
+    $parent = Split-Path $Dst -Parent
+    if (-not (Test-Path $parent)) { New-Item -ItemType Directory -Path $parent -Force | Out-Null }
+
+    $runtimePrompt = Get-RuntimePrompt -Runtime $Runtime
+    $tmp = [System.IO.Path]::GetTempFileName()
+    Set-Content -Path $tmp -Value $runtimePrompt -Encoding UTF8 -NoNewline
+
+    $srcHash = (Get-FileHash $tmp -Algorithm SHA256).Hash
+    $dstHash = if (Test-Path $Dst) { (Get-FileHash $Dst -Algorithm SHA256).Hash } else { "" }
+    if ($srcHash -ne $dstHash) {
+        Copy-Item $tmp $Dst -Force
+        Remove-Item $tmp -Force
+    }
+    else {
+        Remove-Item $tmp -Force
+    }
+}
+
+function Invoke-Yolo {
+    param([string[]]$YoloArgs)
+
+    if ($YoloArgs.Count -lt 1) {
+        Write-Host "[mosaic] ERROR: yolo requires a runtime (claude|codex|opencode)." -ForegroundColor Red
+        Write-Host "[mosaic] Example: mosaic yolo claude"
+        exit 1
+    }
+
+    $runtime = $YoloArgs[0]
+    $tail = if ($YoloArgs.Count -gt 1) { @($YoloArgs[1..($YoloArgs.Count - 1)]) } else { @() }
+
+    switch ($runtime) {
+        "claude" {
+            Assert-MosaicHome
+            Assert-AgentsMd
+            Assert-Soul
+            Assert-Runtime "claude"
+            Assert-SequentialThinking
+            $agentsContent = Get-RuntimePrompt -Runtime "claude"
+            Write-Host "[mosaic] Launching Claude Code in YOLO mode (dangerous permissions enabled)..."
+            & claude --dangerously-skip-permissions --append-system-prompt $agentsContent @tail
+            return
+        }
+        "codex" {
+            Assert-MosaicHome
+            Assert-AgentsMd
+            Assert-Soul
+            Assert-Runtime "codex"
+            Assert-SequentialThinking
+            Ensure-RuntimeConfig -Runtime "codex" -Dst (Join-Path $env:USERPROFILE ".codex\instructions.md")
+            $missionPrompt = Get-MissionPrompt
+            if (-not [string]::IsNullOrWhiteSpace($missionPrompt) -and $tail.Count -eq 0) {
+                Write-Host "[mosaic] Launching Codex in YOLO mode (active mission detected)..."
+                & codex --dangerously-bypass-approvals-and-sandbox $missionPrompt
+            }
+            else {
+                Write-Host "[mosaic] Launching Codex in YOLO mode (dangerous permissions enabled)..."
+                & codex --dangerously-bypass-approvals-and-sandbox @tail
+            }
+            return
+        }
+        "opencode" {
+            Assert-MosaicHome
+            Assert-AgentsMd
+            Assert-Soul
+            Assert-Runtime "opencode"
+            Assert-SequentialThinking
+            Ensure-RuntimeConfig -Runtime "opencode" -Dst (Join-Path $env:USERPROFILE ".config\opencode\AGENTS.md")
+            Write-Host "[mosaic] Launching OpenCode in YOLO mode..."
+            & opencode @tail
+            return
+        }
+        default {
+            Write-Host "[mosaic] ERROR: Unsupported yolo runtime '$runtime'. Use claude|codex|opencode." -ForegroundColor Red
+            exit 1
+        }
+    }
+}
+
+if ($args.Count -eq 0) {
+    Show-Usage
+    exit 0
+}
+
+$command = $args[0]
+$remaining = if ($args.Count -gt 1) { @($args[1..($args.Count - 1)]) } else { @() }
+
+switch ($command) {
+    "claude" {
+        Assert-MosaicHome
+        Assert-AgentsMd
+        Assert-Soul
+        Assert-Runtime "claude"
+        Assert-SequentialThinking
+        # Claude supports --append-system-prompt for direct injection
+        $agentsContent = Get-RuntimePrompt -Runtime "claude"
+        Write-Host "[mosaic] Launching Claude Code..."
+        & claude --append-system-prompt $agentsContent @remaining
+    }
+    "opencode" {
+        Assert-MosaicHome
+        Assert-AgentsMd
+        Assert-Soul
+        Assert-Runtime "opencode"
+        Assert-SequentialThinking
+        # OpenCode reads from ~/.config/opencode/AGENTS.md
+        Ensure-RuntimeConfig -Runtime "opencode" -Dst (Join-Path $env:USERPROFILE ".config\opencode\AGENTS.md")
+        Write-Host "[mosaic] Launching OpenCode..."
+        & opencode @remaining
+    }
+    "codex" {
+        Assert-MosaicHome
+        Assert-AgentsMd
+        Assert-Soul
+        Assert-Runtime "codex"
+        Assert-SequentialThinking
+        # Codex reads from ~/.codex/instructions.md
+        Ensure-RuntimeConfig -Runtime "codex" -Dst (Join-Path $env:USERPROFILE ".codex\instructions.md")
+        $missionPrompt = Get-MissionPrompt
+        if (-not [string]::IsNullOrWhiteSpace($missionPrompt) -and $remaining.Count -eq 0) {
+            Write-Host "[mosaic] Launching Codex (active mission detected)..."
+            & codex $missionPrompt
+        }
+        else {
+            Write-Host "[mosaic] Launching Codex..."
+            & codex @remaining
+        }
+    }
+    "yolo" {
+        Invoke-Yolo -YoloArgs $remaining
+    }
+    "--yolo" {
+        Invoke-Yolo -YoloArgs $remaining
+    }
+    "init" {
+        Assert-MosaicHome
+        & (Join-Path $MosaicHome "bin\mosaic-init.ps1") @remaining
+    }
+    "doctor" {
+        Assert-MosaicHome
+        & (Join-Path $MosaicHome "bin\mosaic-doctor.ps1") @remaining
+    }
+    "sync" {
+        Assert-MosaicHome
+        & (Join-Path $MosaicHome "bin\mosaic-sync-skills.ps1") @remaining
+    }
+    "bootstrap" {
+        Assert-MosaicHome
+        Write-Host "[mosaic] NOTE: mosaic-bootstrap-repo requires bash. Use Git Bash or WSL." -ForegroundColor Yellow
+        & (Join-Path $MosaicHome "bin\mosaic-bootstrap-repo") @remaining
+    }
+    "upgrade" {
+        Assert-MosaicHome
+        if ($remaining.Count -eq 0) {
+            & (Join-Path $MosaicHome "bin\mosaic-release-upgrade.ps1")
+            break
+        }
+
+        $mode = $remaining[0]
+        $tail = if ($remaining.Count -gt 1) { $remaining[1..($remaining.Count - 1)] } else { @() }
+
+        switch -Regex ($mode) {
+            "^release$" {
+                & (Join-Path $MosaicHome "bin\mosaic-release-upgrade.ps1") @tail
+            }
+            "^check$" {
+                & (Join-Path $MosaicHome "bin\mosaic-release-upgrade.ps1") -DryRun @tail
+            }
+            "^project$" {
+                Write-Host "[mosaic] NOTE: mosaic-upgrade requires bash. Use Git Bash or WSL." -ForegroundColor Yellow
+                & (Join-Path $MosaicHome "bin\mosaic-upgrade") @tail
+            }
+            "^(--all|--root)$" {
+                Write-Host "[mosaic] NOTE: mosaic-upgrade requires bash. Use Git Bash or WSL." -ForegroundColor Yellow
+                & (Join-Path $MosaicHome "bin\mosaic-upgrade") @remaining
+            }
+            "^(--dry-run|--ref|--keep|--overwrite|-y|--yes)$" {
+                & (Join-Path $MosaicHome "bin\mosaic-release-upgrade.ps1") @remaining
+            }
+            "^-.*" {
+                & (Join-Path $MosaicHome "bin\mosaic-release-upgrade.ps1") @remaining
+            }
+            default {
+                Write-Host "[mosaic] NOTE: treating positional argument as project path." -ForegroundColor Yellow
+                Write-Host "[mosaic] NOTE: mosaic-upgrade requires bash. Use Git Bash or WSL." -ForegroundColor Yellow
+                & (Join-Path $MosaicHome "bin\mosaic-upgrade") @remaining
+            }
+        }
+    }
+    "release-upgrade" {
+        Assert-MosaicHome
+        & (Join-Path $MosaicHome "bin\mosaic-release-upgrade.ps1") @remaining
+    }
+    "project-upgrade" {
+        Assert-MosaicHome
+        Write-Host "[mosaic] NOTE: mosaic-upgrade requires bash. Use Git Bash or WSL." -ForegroundColor Yellow
+        & (Join-Path $MosaicHome "bin\mosaic-upgrade") @remaining
+    }
+    { $_ -in "help", "-h", "--help" } { Show-Usage }
+    { $_ -in "version", "-v", "--version" } { Write-Host "mosaic $Version" }
+    default {
+        Write-Host "[mosaic] Unknown command: $command" -ForegroundColor Red
+        Write-Host "[mosaic] Run 'mosaic --help' for usage."
+        exit 1
+    }
+}

packages/mosaic/framework/install.sh

@@ -1,32 +1,12 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# ─── Mosaic Framework Installer ──────────────────────────────────────────────
-#
-# Installs/upgrades the framework DATA to ~/.config/mosaic/.
-# No executables are placed on PATH — the mosaic npm CLI is the only binary.
-#
-# Called by tools/install.sh (the unified installer). Can also be run directly.
-#
-# Environment:
-#   MOSAIC_HOME              — target directory (default: ~/.config/mosaic)
-#   MOSAIC_INSTALL_MODE      — prompt|keep|overwrite (default: prompt)
-#   MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING — 1 to bypass MCP check
-#   MOSAIC_SKIP_SKILLS_SYNC  — 1 to skip skill sync
-# ──────────────────────────────────────────────────────────────────────────────
-
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
-INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}"
+INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}" # prompt|keep|overwrite
+PRESERVE_PATHS=("SOUL.md" "USER.md" "TOOLS.md" "memory")
 
-# Files preserved across upgrades (never overwritten)
+# Colors (disabled if not a terminal)
-PRESERVE_PATHS=("SOUL.md" "USER.md" "TOOLS.md" "memory" "sources")
-
-# Current framework schema version — bump this when the layout changes.
-# The migration system uses this to run upgrade steps.
-FRAMEWORK_VERSION=2
-
-# ─── colours ──────────────────────────────────────────────────────────────────
 if [[ -t 1 ]]; then
   GREEN='\033[0;32m' YELLOW='\033[0;33m' RED='\033[0;31m'
   CYAN='\033[0;36m' BOLD='\033[1m' RESET='\033[0m'
@@ -39,29 +19,9 @@ warn() { echo -e "  ${YELLOW}⚠${RESET} $1" >&2; }
 fail() { echo -e "  ${RED}✗${RESET} $1" >&2; }
 step() { echo -e "\n${BOLD}$1${RESET}"; }
 
-# ─── helpers ──────────────────────────────────────────────────────────────────
-
 is_existing_install() {
   [[ -d "$TARGET_DIR" ]] || return 1
-  [[ -f "$TARGET_DIR/AGENTS.md" || -f "$TARGET_DIR/SOUL.md" ]]
+  [[ -f "$TARGET_DIR/bin/mosaic" || -f "$TARGET_DIR/AGENTS.md" || -f "$TARGET_DIR/SOUL.md" ]]
-}
-
-installed_framework_version() {
-  local vf="$TARGET_DIR/.framework-version"
-  if [[ -f "$vf" ]]; then
-    cat "$vf" 2>/dev/null || echo "0"
-  else
-    # No version file = legacy install (version 0 or 1)
-    if [[ -d "$TARGET_DIR/bin" ]]; then
-      echo "1"   # Has bin/ → pre-migration legacy
-    else
-      echo "0"   # Fresh or unknown
-    fi
-  fi
-}
-
-write_framework_version() {
-  echo "$FRAMEWORK_VERSION" > "$TARGET_DIR/.framework-version"
 }
 
 select_install_mode() {
@@ -79,22 +39,33 @@ select_install_mode() {
   fi
 
   case "$INSTALL_MODE" in
-    keep|overwrite) ;;
+    keep|overwrite)
+      ;;
     prompt)
       if [[ -t 0 ]]; then
         echo ""
         echo "Existing Mosaic install detected at: $TARGET_DIR"
-        echo "  1) keep      Update framework, preserve local files (SOUL.md, USER.md, etc.)"
+        echo "Choose reinstall mode:"
-        echo "  2) overwrite Replace everything"
+        echo "  1) keep      Keep local files (SOUL.md, USER.md, TOOLS.md, memory/) while updating framework"
-        echo "  3) cancel    Abort"
+        echo "  2) overwrite Replace everything in $TARGET_DIR"
+        echo "  3) cancel    Abort install"
         printf "Selection [1/2/3] (default: 1): "
         read -r selection
+
         case "${selection:-1}" in
-          1|k|K|keep) INSTALL_MODE="keep" ;;
+          1|k|K|keep|KEEP) INSTALL_MODE="keep" ;;
-          2|o|O|overwrite) INSTALL_MODE="overwrite" ;;
+          2|o|O|overwrite|OVERWRITE) INSTALL_MODE="overwrite" ;;
-          *) fail "Install cancelled."; exit 1 ;;
+          3|c|C|cancel|CANCEL|n|N|no|NO)
+            fail "Install cancelled."
+            exit 1
+            ;;
+          *)
+            warn "Unrecognized selection '$selection'; defaulting to keep."
+            INSTALL_MODE="keep"
+            ;;
         esac
       else
+        warn "Existing install detected without interactive input; defaulting to keep local files."
         INSTALL_MODE="keep"
       fi
       ;;
@@ -112,9 +83,10 @@ sync_framework() {
   fi
 
   if command -v rsync >/dev/null 2>&1; then
-    local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version")
+    local rsync_args=(-a --delete --exclude ".git")
 
     if [[ "$INSTALL_MODE" == "keep" ]]; then
+      local path
       for path in "${PRESERVE_PATHS[@]}"; do
         rsync_args+=(--exclude "$path")
       done
@@ -124,10 +96,10 @@ sync_framework() {
     return
   fi
 
-  # Fallback: cp-based sync
   local preserve_tmp=""
   if [[ "$INSTALL_MODE" == "keep" ]]; then
     preserve_tmp="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-preserve-XXXXXX")"
+    local path
     for path in "${PRESERVE_PATHS[@]}"; do
       if [[ -e "$TARGET_DIR/$path" ]]; then
         mkdir -p "$preserve_tmp/$(dirname "$path")"
@@ -136,11 +108,12 @@ sync_framework() {
     done
   fi
 
-  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" -exec rm -rf {} +
+  find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" -exec rm -rf {} +
   cp -R "$SOURCE_DIR"/. "$TARGET_DIR"/
   rm -rf "$TARGET_DIR/.git"
 
   if [[ -n "$preserve_tmp" ]]; then
+    local path
     for path in "${PRESERVE_PATHS[@]}"; do
       if [[ -e "$preserve_tmp/$path" ]]; then
         rm -rf "$TARGET_DIR/$path"
@@ -152,133 +125,136 @@ sync_framework() {
   fi
 }
 
-# ═══════════════════════════════════════════════════════════════════════════════
-# Migrations — run sequentially from the installed version to FRAMEWORK_VERSION
-# ═══════════════════════════════════════════════════════════════════════════════
-
-run_migrations() {
-  local from_version
-  from_version="$(installed_framework_version)"
-
-  if [[ "$from_version" -ge "$FRAMEWORK_VERSION" ]]; then
-    return  # Already current
-  fi
-
-  step "Running migrations (v${from_version} → v${FRAMEWORK_VERSION})"
-
-  # ── Migration: v0/v1 → v2 ─────────────────────────────────────────────────
-  # Remove bin/ directory — all executables now live in the npm CLI.
-  # Scripts that were in bin/ are now in tools/_scripts/.
-  if [[ "$from_version" -lt 2 ]]; then
-    if [[ -d "$TARGET_DIR/bin" ]]; then
-      ok "Removing legacy bin/ directory (executables now in npm CLI)"
-      rm -rf "$TARGET_DIR/bin"
-    fi
-
-    # Remove old mosaic PATH entry from shell profiles
-    for profile in "$HOME/.bashrc" "$HOME/.zshrc" "$HOME/.profile"; do
-      if [[ -f "$profile" ]] && grep -qF "$TARGET_DIR/bin" "$profile"; then
-        # Remove the PATH line and the comment above it
-        sed -i.mosaic-migration-bak \
-          -e "\|# Mosaic agent framework|d" \
-          -e "\|$TARGET_DIR/bin|d" \
-          "$profile"
-        ok "Cleaned up old PATH entry from $(basename "$profile")"
-        rm -f "${profile}.mosaic-migration-bak"
-      fi
-    done
-
-    # Remove stale rails/ symlink
-    if [[ -L "$TARGET_DIR/rails" ]]; then
-      rm -f "$TARGET_DIR/rails"
-    fi
-  fi
-
-  # ── Future migrations go here ──────────────────────────────────────────────
-  # if [[ "$from_version" -lt 3 ]]; then
-  #   ...
-  # fi
-}
-
-# ═══════════════════════════════════════════════════════════════════════════════
-# Main
-# ═══════════════════════════════════════════════════════════════════════════════
-
 step "Installing Mosaic framework"
 
 mkdir -p "$TARGET_DIR"
 select_install_mode
 
 if [[ "$INSTALL_MODE" == "keep" ]]; then
-  ok "Install mode: keep local files (SOUL.md, USER.md, TOOLS.md, memory/)"
+  ok "Install mode: keep local SOUL.md/USER.md/TOOLS.md/memory while updating framework"
 else
-  ok "Install mode: overwrite"
+  ok "Install mode: overwrite existing files"
 fi
 
 sync_framework
 
-# Ensure memory directory exists
+# Ensure memory directory exists (preserved across upgrades, may not exist on fresh install)
 mkdir -p "$TARGET_DIR/memory"
 
+chmod +x "$TARGET_DIR"/bin/*
+chmod +x "$TARGET_DIR"/install.sh
+
 # Ensure tool scripts are executable
 find "$TARGET_DIR/tools" -name "*.sh" -exec chmod +x {} + 2>/dev/null || true
-find "$TARGET_DIR/tools/_scripts" -type f -exec chmod +x {} + 2>/dev/null || true
 
-ok "Framework synced to $TARGET_DIR"
+# Create backward-compat symlink: rails/ → tools/
+if [[ -d "$TARGET_DIR/tools" ]]; then
+  if [[ -d "$TARGET_DIR/rails" ]] && [[ ! -L "$TARGET_DIR/rails" ]]; then
+    rm -rf "$TARGET_DIR/rails"
+  fi
+  ln -sfn "tools" "$TARGET_DIR/rails"
+fi
 
-# Run migrations before post-install (migrations may remove old bin/ etc.)
+ok "Framework installed to $TARGET_DIR"
-run_migrations
 
 step "Post-install tasks"
 
-SCRIPTS="$TARGET_DIR/tools/_scripts"
+if "$TARGET_DIR/bin/mosaic-link-runtime-assets" >/dev/null 2>&1; then
-
-if [[ -x "$SCRIPTS/mosaic-link-runtime-assets" ]]; then
-  if "$SCRIPTS/mosaic-link-runtime-assets" >/dev/null 2>&1; then
   ok "Runtime assets linked"
 else
   warn "Runtime asset linking failed (non-fatal)"
 fi
-fi
 
-if [[ -x "$SCRIPTS/mosaic-ensure-sequential-thinking" ]]; then
+if "$TARGET_DIR/bin/mosaic-ensure-sequential-thinking" >/dev/null 2>&1; then
-  if "$SCRIPTS/mosaic-ensure-sequential-thinking" >/dev/null 2>&1; then
   ok "sequential-thinking MCP configured"
 else
   if [[ "${MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING:-0}" == "1" ]]; then
-      warn "sequential-thinking MCP setup bypassed (MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING=1)"
+    warn "sequential-thinking MCP setup failed but bypassed (MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING=1)"
   else
     fail "sequential-thinking MCP setup failed (hard requirement)."
+    fail "Set MOSAIC_ALLOW_MISSING_SEQUENTIAL_THINKING=1 only for temporary bypass scenarios."
     exit 1
   fi
 fi
+
+if "$TARGET_DIR/bin/mosaic-ensure-excalidraw" >/dev/null 2>&1; then
+  ok "excalidraw MCP configured"
+else
+  warn "excalidraw MCP setup failed (non-fatal) — run 'mosaic-ensure-excalidraw' to retry"
 fi
 
-if [[ -x "$SCRIPTS/mosaic-ensure-excalidraw" ]]; then
+if [[ "${MOSAIC_SKIP_SKILLS_SYNC:-0}" == "1" ]]; then
-  "$SCRIPTS/mosaic-ensure-excalidraw" >/dev/null 2>&1 && ok "excalidraw MCP configured" || warn "excalidraw MCP setup failed (non-fatal)"
+  ok "Skills sync skipped (MOSAIC_SKIP_SKILLS_SYNC=1)"
+else
+  if "$TARGET_DIR/bin/mosaic-sync-skills" >/dev/null 2>&1; then
+    ok "Skills synced"
+  else
+    warn "Skills sync failed (non-fatal)"
+  fi
 fi
 
-if [[ "${MOSAIC_SKIP_SKILLS_SYNC:-0}" != "1" ]] && [[ -x "$SCRIPTS/mosaic-sync-skills" ]]; then
+if "$TARGET_DIR/bin/mosaic-migrate-local-skills" --apply >/dev/null 2>&1; then
-  "$SCRIPTS/mosaic-sync-skills" >/dev/null 2>&1 && ok "Skills synced" || warn "Skills sync failed (non-fatal)"
+  ok "Local skills migrated"
+else
+  warn "Local skill migration failed (non-fatal)"
 fi
 
-if [[ -x "$SCRIPTS/mosaic-migrate-local-skills" ]]; then
+if "$TARGET_DIR/bin/mosaic-doctor" >/dev/null 2>&1; then
-  "$SCRIPTS/mosaic-migrate-local-skills" --apply >/dev/null 2>&1 && ok "Local skills migrated" || warn "Local skill migration failed (non-fatal)"
+  ok "Health audit passed"
+else
+  warn "Health audit reported issues — run 'mosaic doctor' for details"
 fi
 
-if [[ -x "$SCRIPTS/mosaic-doctor" ]]; then
+step "PATH configuration"
-  "$SCRIPTS/mosaic-doctor" >/dev/null 2>&1 && ok "Health audit passed" || warn "Health audit reported issues — run 'mosaic doctor' for details"
+
+PATH_LINE="export PATH=\"$TARGET_DIR/bin:\$PATH\""
+
+# Find the right shell profile
+if [[ -n "${ZSH_VERSION:-}" ]] || [[ "$(basename "${SHELL:-}")" == "zsh" ]]; then
+  SHELL_PROFILE="$HOME/.zshrc"
+elif [[ -f "$HOME/.bashrc" ]]; then
+  SHELL_PROFILE="$HOME/.bashrc"
+elif [[ -f "$HOME/.profile" ]]; then
+  SHELL_PROFILE="$HOME/.profile"
+else
+  SHELL_PROFILE="$HOME/.profile"
 fi
 
-# Write version stamp AFTER everything succeeds
+PATH_CHANGED=false
-write_framework_version
+if grep -qF "$TARGET_DIR/bin" "$SHELL_PROFILE" 2>/dev/null; then
+  ok "Already in PATH via $SHELL_PROFILE"
+else
+  {
+    echo ""
+    echo "# Mosaic agent framework"
+    echo "$PATH_LINE"
+  } >> "$SHELL_PROFILE"
+  ok "Added to PATH in $SHELL_PROFILE"
+  PATH_CHANGED=true
+fi
 
 # ── Summary ──────────────────────────────────────────────────
 echo ""
-echo -e "${GREEN}${BOLD}  Mosaic framework installed.${RESET}"
+echo -e "${GREEN}${BOLD}  Mosaic installed successfully.${RESET}"
 echo ""
 
+# Collect next steps
+NEXT_STEPS=()
+
+if [[ "$PATH_CHANGED" == "true" ]]; then
+  NEXT_STEPS+=("Run ${CYAN}source $SHELL_PROFILE${RESET} or log out and back in to activate PATH.")
+fi
+
 if [[ ! -f "$TARGET_DIR/SOUL.md" ]]; then
-  echo -e "  Run ${CYAN}mosaic init${RESET} to set up your agent identity."
+  NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to set up your agent identity (SOUL.md), user profile (USER.md), and tool config (TOOLS.md).")
+elif grep -q "not configured" "$TARGET_DIR/USER.md" 2>/dev/null; then
+  NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to personalize your user profile (USER.md) and tool config (TOOLS.md).")
+fi
+
+if [[ ${#NEXT_STEPS[@]} -gt 0 ]]; then
+  echo -e "  ${BOLD}Next steps:${RESET}"
+  for i in "${!NEXT_STEPS[@]}"; do
+    echo -e "  $((i+1)). ${NEXT_STEPS[$i]}"
+  done
   echo ""
 fi

packages/mosaic/framework/templates/repo/scripts/agent/orchestrator-daemon.sh

@@ -69,12 +69,12 @@ case "$cmd" in
       echo "[agent-framework] orchestrator already running (pid=$(cat "$PID_FILE"))"
       exit 0
     fi
-    nohup "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-drain" --poll-sec "$poll_sec" $sync_arg >"$LOG_FILE" 2>&1 &
+    nohup "$MOSAIC_HOME/bin/mosaic-orchestrator-drain" --poll-sec "$poll_sec" $sync_arg >"$LOG_FILE" 2>&1 &
     echo "$!" > "$PID_FILE"
     echo "[agent-framework] orchestrator started (pid=$!, log=$LOG_FILE)"
     ;;
   drain)
-    exec "$MOSAIC_HOME/tools/_scripts/mosaic-orchestrator-drain" --poll-sec "$poll_sec" $sync_arg
+    exec "$MOSAIC_HOME/bin/mosaic-orchestrator-drain" --poll-sec "$poll_sec" $sync_arg
     ;;
   stop)
     if ! is_running; then

packages/mosaic/framework/tools/orchestrator/session-run.sh

@@ -80,11 +80,11 @@ echo -e "${C_CYAN}Capsule:${C_RESET} $(next_task_capsule_path "$PROJECT")"
 
 cd "$PROJECT"
 if [[ "$YOLO" == true ]]; then
-  exec mosaic yolo "$runtime" "$launch_prompt"
+  exec "$MOSAIC_HOME/bin/mosaic" yolo "$runtime" "$launch_prompt"
 elif [[ "$runtime" == "claude" ]]; then
-  exec mosaic claude "$launch_prompt"
+  exec "$MOSAIC_HOME/bin/mosaic" claude "$launch_prompt"
 elif [[ "$runtime" == "codex" ]]; then
-  exec mosaic codex "$launch_prompt"
+  exec "$MOSAIC_HOME/bin/mosaic" codex "$launch_prompt"
 fi
 
 echo -e "${C_RED}Unsupported coord runtime: $runtime${C_RESET}" >&2

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/mosaic",
-  "version": "0.0.10",
+  "version": "0.0.1-alpha.1",
   "description": "Mosaic agent framework — installation wizard and meta package",
   "type": "module",
   "main": "dist/index.js",

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

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

packages/mosaic/src/constants.ts

@@ -1,7 +1,7 @@
 import { homedir } from 'node:os';
 import { join } from 'node:path';
 
-export const VERSION = '0.0.2';
+export const VERSION = '0.1.0';
 
 export const DEFAULT_MOSAIC_HOME = join(homedir(), '.config', 'mosaic');
 

packages/mosaic/src/index.ts

@@ -1,6 +1,5 @@
 #!/usr/bin/env node
-import { existsSync } from 'node:fs';
+import { resolve } from 'node:path';
-import { dirname, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import { Command } from 'commander';
@@ -50,14 +49,7 @@ program
   .action(async (opts: Record<string, string | boolean | undefined>) => {
     try {
       const mosaicHome = (opts['mosaicHome'] as string) ?? DEFAULT_MOSAIC_HOME;
-      // Default source to the framework/ dir bundled in this npm package.
+      const sourceDir = (opts['sourceDir'] as string | undefined) ?? mosaicHome;
-      // This ensures syncFramework copies AGENTS.md, STANDARDS.md, guides/, etc.
-      // Falls back to mosaicHome if the bundled dir doesn't exist (shouldn't happen).
-      const pkgRoot = dirname(fileURLToPath(import.meta.url));
-      const bundledFramework = resolve(pkgRoot, '..', 'framework');
-      const sourceDir =
-        (opts['sourceDir'] as string | undefined) ??
-        (existsSync(bundledFramework) ? bundledFramework : mosaicHome);
 
       const prompter = opts['nonInteractive'] ? new HeadlessPrompter() : new ClackPrompter();
 

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

@@ -9,7 +9,7 @@ import {
   unlinkSync,
   statSync,
 } from 'node:fs';
-import { dirname, join, relative, resolve } from 'node:path';
+import { dirname, join, relative } from 'node:path';
 
 const MAX_BACKUPS = 3;
 
@@ -68,9 +68,6 @@ export function syncDirectory(
   target: string,
   options: { preserve?: string[]; excludeGit?: boolean } = {},
 ): void {
-  // Guard: source and target are the same directory — nothing to sync
-  if (resolve(source) === resolve(target)) return;
-
   const preserveSet = new Set(options.preserve ?? []);
 
   // Collect files from source
@@ -80,10 +77,9 @@ export function syncDirectory(
     const stat = statSync(src);
     if (stat.isDirectory()) {
       const relPath = relative(relBase, src);
-      const dirName = relPath.split('/').pop() ?? '';
 
-      // Skip any .git directory (top-level or nested, e.g. sources/agent-skills/.git)
+      // Skip .git
-      if (options.excludeGit && (dirName === '.git' || relPath.includes('/.git'))) return;
+      if (options.excludeGit && relPath === '.git') return;
 
       // Skip preserved paths at top level
       if (preserveSet.has(relPath) && existsSync(dest)) return;
@@ -95,9 +91,6 @@ export function syncDirectory(
     } else {
       const relPath = relative(relBase, src);
 
-      // Skip files inside .git directories
-      if (options.excludeGit && relPath.includes('/.git/')) return;
-
       // Skip preserved files at top level
       if (preserveSet.has(relPath) && existsSync(dest)) return;
 

packages/mosaic/src/runtime/update-checker.ts

@@ -122,18 +122,10 @@ export function semverLt(a: string, b: string): boolean {
 
 // ─── Cache ──────────────────────────────────────────────────────────────────
 
-/** Cache stores only the latest registry version (the expensive network call).
+function readCache(): UpdateCheckResult | null {
- *  The installed version is always checked fresh — it's a local `npm ls`. */
-interface RegistryCache {
-  latest: string;
-  checkedAt: string;
-  registry: string;
-}
-
-function readCache(): RegistryCache | null {
   try {
     if (!existsSync(CACHE_FILE)) return null;
-    const raw = JSON.parse(readFileSync(CACHE_FILE, 'utf-8')) as RegistryCache;
+    const raw = JSON.parse(readFileSync(CACHE_FILE, 'utf-8')) as UpdateCheckResult;
     const age = Date.now() - new Date(raw.checkedAt).getTime();
     if (age > CACHE_TTL_MS) return null;
     return raw;
@@ -142,10 +134,10 @@ function readCache(): RegistryCache | null {
   }
 }
 
-function writeCache(entry: RegistryCache): void {
+function writeCache(result: UpdateCheckResult): void {
   try {
     mkdirSync(CACHE_DIR, { recursive: true });
-    writeFileSync(CACHE_FILE, JSON.stringify(entry, null, 2) + '\n', 'utf-8');
+    writeFileSync(CACHE_FILE, JSON.stringify(result, null, 2) + '\n', 'utf-8');
   } catch {
     // Best-effort — cache is not critical
   }
@@ -182,40 +174,29 @@ export function getLatestVersion(): string {
 }
 
 /**
- * Perform an update check — uses registry cache when fresh, always checks
+ * Perform an update check — uses cache when fresh, otherwise hits registry.
- * installed version fresh (local npm ls is cheap, caching it causes stale
- * "update available" banners after an upgrade).
  * Never throws.
  */
 export function checkForUpdate(options?: { skipCache?: boolean }): UpdateCheckResult {
-  const current = getInstalledVersion();
-
-  let latest: string;
-  let checkedAt: string;
-
   if (!options?.skipCache) {
     const cached = readCache();
-    if (cached) {
+    if (cached) return cached;
-      latest = cached.latest;
-      checkedAt = cached.checkedAt;
-    } else {
-      latest = getLatestVersion();
-      checkedAt = new Date().toISOString();
-      writeCache({ latest, checkedAt, registry: REGISTRY });
-    }
-  } else {
-    latest = getLatestVersion();
-    checkedAt = new Date().toISOString();
-    writeCache({ latest, checkedAt, registry: REGISTRY });
   }
 
-  return {
+  const current = getInstalledVersion();
+  const latest = getLatestVersion();
+  const updateAvailable = !!(current && latest && semverLt(current, latest));
+
+  const result: UpdateCheckResult = {
     current,
     latest,
-    updateAvailable: !!(current && latest && semverLt(current, latest)),
+    updateAvailable,
-    checkedAt,
+    checkedAt: new Date().toISOString(),
     registry: REGISTRY,
   };
+
+  writeCache(result);
+  return result;
 }
 
 /**

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

@@ -87,9 +87,7 @@ export async function detectInstallStage(
     ],
   });
 
-  if (state.installAction === 'keep' || state.installAction === 'reconfigure') {
+  if (state.installAction === 'keep') {
-    // Load existing values — for 'keep' they're final, for 'reconfigure'
-    // they become pre-populated defaults so the user can tweak them.
     state.soul = await config.readSoul();
     state.user = await config.readUser();
     state.tools = await config.readTools();

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

@@ -24,18 +24,6 @@ export async function soulSetupStage(p: WizardPrompter, state: WizardState): Pro
         return undefined;
       },
     });
-  } else if (state.installAction === 'reconfigure') {
-    // Show existing value as default so the user can accept or change it
-    state.soul.agentName = await p.text({
-      message: 'What name should agents use?',
-      placeholder: state.soul.agentName,
-      defaultValue: state.soul.agentName,
-      validate: (v) => {
-        if (v.length === 0) return 'Name cannot be empty';
-        if (v.length > 50) return 'Name must be under 50 characters';
-        return undefined;
-      },
-    });
   }
 
   if (state.mode === 'advanced') {
@@ -50,7 +38,7 @@ export async function soulSetupStage(p: WizardPrompter, state: WizardState): Pro
     state.soul.roleDescription ??= DEFAULTS.roleDescription;
   }
 
-  if (!state.soul.communicationStyle || state.installAction === 'reconfigure') {
+  if (!state.soul.communicationStyle) {
     state.soul.communicationStyle = await p.select<CommunicationStyle>({
       message: 'Communication style',
       options: [
@@ -58,7 +46,7 @@ export async function soulSetupStage(p: WizardPrompter, state: WizardState): Pro
         { value: 'friendly', label: 'Friendly', hint: 'Warm but efficient, conversational' },
         { value: 'formal', label: 'Formal', hint: 'Professional, structured, thorough' },
       ],
-      initialValue: state.soul.communicationStyle ?? 'direct',
+      initialValue: 'direct',
     });
   }
 

packages/prdy/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/prdy",
-  "version": "0.0.2",
+  "version": "0.0.1-alpha.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "exports": {

packages/quality-rails/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaic/quality-rails",
-  "version": "0.0.3",
+  "version": "0.0.1-alpha.1",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -17,7 +17,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "commander": "^13.0.0"
+    "commander": "^12.0.0"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",