feat(macp): add registerMacpCommand for mosaic macp CLI surface

Adds mosaic macp tasks list|submit|gate|events tail subcommands to
@mosaicstack/macp, wires registerMacpCommand into the root mosaic CLI,
and ships a smoke test asserting command structure without touching disk
or starting an event emitter. Ref CU-05-08.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

packages/brain/package.json

@@ -22,7 +22,8 @@
   },
   "dependencies": {
     "@mosaicstack/db": "workspace:^",
-    "@mosaicstack/types": "workspace:*"
+    "@mosaicstack/types": "workspace:*",
+    "commander": "^13.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

packages/brain/src/cli.spec.ts

@@ -0,0 +1,95 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { registerBrainCommand } from './cli.js';
+
+/**
+ * Smoke test: verifies the command tree is correctly registered.
+ * No database connection is opened — we only inspect Commander metadata.
+ */
+describe('registerBrainCommand', () => {
+  function buildProgram(): Command {
+    const program = new Command('mosaic');
+    // Prevent Commander from calling process.exit on parse errors during tests.
+    program.exitOverride();
+    registerBrainCommand(program);
+    return program;
+  }
+
+  it('registers a top-level "brain" command', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain');
+    expect(brainCmd).toBeDefined();
+  });
+
+  it('registers "brain projects" with "list" and "create" subcommands', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const projectsCmd = brainCmd.commands.find((c) => c.name() === 'projects');
+    expect(projectsCmd).toBeDefined();
+
+    const subNames = projectsCmd!.commands.map((c) => c.name());
+    expect(subNames).toContain('list');
+    expect(subNames).toContain('create');
+  });
+
+  it('registers "brain missions" with "list" subcommand', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const missionsCmd = brainCmd.commands.find((c) => c.name() === 'missions');
+    expect(missionsCmd).toBeDefined();
+
+    const subNames = missionsCmd!.commands.map((c) => c.name());
+    expect(subNames).toContain('list');
+  });
+
+  it('registers "brain tasks" with "list" subcommand', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const tasksCmd = brainCmd.commands.find((c) => c.name() === 'tasks');
+    expect(tasksCmd).toBeDefined();
+
+    const subNames = tasksCmd!.commands.map((c) => c.name());
+    expect(subNames).toContain('list');
+  });
+
+  it('registers "brain conversations" with "list" subcommand', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const conversationsCmd = brainCmd.commands.find((c) => c.name() === 'conversations');
+    expect(conversationsCmd).toBeDefined();
+
+    const subNames = conversationsCmd!.commands.map((c) => c.name());
+    expect(subNames).toContain('list');
+  });
+
+  it('"brain projects list" accepts --db and --limit options', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const projectsCmd = brainCmd.commands.find((c) => c.name() === 'projects')!;
+    const listCmd = projectsCmd.commands.find((c) => c.name() === 'list')!;
+
+    const optionNames = listCmd.options.map((o) => o.long);
+    expect(optionNames).toContain('--db');
+    expect(optionNames).toContain('--limit');
+  });
+
+  it('"brain missions list" accepts --project option', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const missionsCmd = brainCmd.commands.find((c) => c.name() === 'missions')!;
+    const listCmd = missionsCmd.commands.find((c) => c.name() === 'list')!;
+
+    const optionNames = listCmd.options.map((o) => o.long);
+    expect(optionNames).toContain('--project');
+  });
+
+  it('"brain tasks list" accepts --project option', () => {
+    const program = buildProgram();
+    const brainCmd = program.commands.find((c) => c.name() === 'brain')!;
+    const tasksCmd = brainCmd.commands.find((c) => c.name() === 'tasks')!;
+    const listCmd = tasksCmd.commands.find((c) => c.name() === 'list')!;
+
+    const optionNames = listCmd.options.map((o) => o.long);
+    expect(optionNames).toContain('--project');
+  });
+});

packages/brain/src/cli.ts

@@ -0,0 +1,142 @@
+import type { Command } from 'commander';
+import { createDb, type DbHandle } from '@mosaicstack/db';
+import { createBrain } from './brain.js';
+
+/**
+ * Build and attach the `brain` subcommand tree onto an existing Commander program.
+ * Uses the caller's Command instance to avoid cross-package Commander version mismatches.
+ */
+export function registerBrainCommand(parent: Command): void {
+  const brain = parent.command('brain').description('Inspect and manage brain data stores');
+
+  // ─── shared DB option helper ─────────────────────────────────────────────
+
+  function addDbOption(cmd: Command): Command {
+    return cmd.option(
+      '--db <connection-string>',
+      'PostgreSQL connection string (overrides MOSAIC_DB_URL)',
+    );
+  }
+
+  function resolveDb(opts: { db?: string }): ReturnType<typeof createBrain> {
+    const connectionString = opts.db ?? process.env['MOSAIC_DB_URL'];
+    if (!connectionString) {
+      console.error('No DB connection string provided. Pass --db <url> or set MOSAIC_DB_URL.');
+      process.exit(1);
+    }
+    const handle: DbHandle = createDb(connectionString);
+    return createBrain(handle.db);
+  }
+
+  // ─── projects ────────────────────────────────────────────────────────────
+
+  const projects = brain.command('projects').description('Manage projects');
+
+  addDbOption(
+    projects
+      .command('list')
+      .description('List all projects')
+      .option('--limit <n>', 'Maximum number of results', '50'),
+  ).action(async (opts: { db?: string; limit: string }) => {
+    const b = resolveDb(opts);
+    const limit = parseInt(opts.limit, 10);
+    const rows = await b.projects.findAll();
+    const sliced = rows.slice(0, limit);
+    if (sliced.length === 0) {
+      console.log('No projects found.');
+      return;
+    }
+    for (const p of sliced) {
+      console.log(`${p.id}  ${p.name}`);
+    }
+  });
+
+  addDbOption(
+    projects
+      .command('create <name>')
+      .description('Create a new project')
+      .requiredOption('--owner-id <id>', 'Owner user ID'),
+  ).action(async (name: string, opts: { db?: string; ownerId: string }) => {
+    const b = resolveDb(opts);
+    const created = await b.projects.create({
+      name,
+      ownerId: opts.ownerId,
+      ownerType: 'user',
+    });
+    console.log(`Created project: ${created.id}  ${created.name}`);
+  });
+
+  // ─── missions ────────────────────────────────────────────────────────────
+
+  const missions = brain.command('missions').description('Manage missions');
+
+  addDbOption(
+    missions
+      .command('list')
+      .description('List all missions')
+      .option('--limit <n>', 'Maximum number of results', '50')
+      .option('--project <id>', 'Filter by project ID'),
+  ).action(async (opts: { db?: string; limit: string; project?: string }) => {
+    const b = resolveDb(opts);
+    const limit = parseInt(opts.limit, 10);
+    const rows = opts.project
+      ? await b.missions.findByProject(opts.project)
+      : await b.missions.findAll();
+    const sliced = rows.slice(0, limit);
+    if (sliced.length === 0) {
+      console.log('No missions found.');
+      return;
+    }
+    for (const m of sliced) {
+      console.log(`${m.id}  ${m.name}`);
+    }
+  });
+
+  // ─── tasks ────────────────────────────────────────────────────────────────
+
+  const tasks = brain.command('tasks').description('Manage generic tasks');
+
+  addDbOption(
+    tasks
+      .command('list')
+      .description('List all tasks')
+      .option('--limit <n>', 'Maximum number of results', '50')
+      .option('--project <id>', 'Filter by project ID'),
+  ).action(async (opts: { db?: string; limit: string; project?: string }) => {
+    const b = resolveDb(opts);
+    const limit = parseInt(opts.limit, 10);
+    const rows = opts.project ? await b.tasks.findByProject(opts.project) : await b.tasks.findAll();
+    const sliced = rows.slice(0, limit);
+    if (sliced.length === 0) {
+      console.log('No tasks found.');
+      return;
+    }
+    for (const t of sliced) {
+      console.log(`${t.id}  ${t.title}  [${t.status}]`);
+    }
+  });
+
+  // ─── conversations ────────────────────────────────────────────────────────
+
+  const conversations = brain.command('conversations').description('Manage conversations');
+
+  addDbOption(
+    conversations
+      .command('list')
+      .description('List conversations for a user')
+      .option('--limit <n>', 'Maximum number of results', '50')
+      .requiredOption('--user-id <id>', 'User ID to scope the query'),
+  ).action(async (opts: { db?: string; limit: string; userId: string }) => {
+    const b = resolveDb(opts);
+    const limit = parseInt(opts.limit, 10);
+    const rows = await b.conversations.findAll(opts.userId);
+    const sliced = rows.slice(0, limit);
+    if (sliced.length === 0) {
+      console.log('No conversations found.');
+      return;
+    }
+    for (const c of sliced) {
+      console.log(`${c.id}  ${c.title ?? '(untitled)'}`);
+    }
+  });
+}

packages/brain/src/index.ts

@@ -1,4 +1,5 @@
 export { createBrain, type Brain } from './brain.js';
+export { registerBrainCommand } from './cli.js';
 export {
   createProjectsRepo,
   type ProjectsRepo,

packages/forge/package.json

@@ -26,8 +26,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
-    "@mosaicstack/macp": "workspace:*",
-    "commander": "^13.0.0"
+    "@mosaicstack/macp": "workspace:*"
   },
   "devDependencies": {
     "@types/node": "^22.0.0",

packages/forge/src/cli.spec.ts

@@ -1,57 +0,0 @@
-import { Command } from 'commander';
-import { describe, expect, it } from 'vitest';
-
-import { registerForgeCommand } from './cli.js';
-
-describe('registerForgeCommand', () => {
-  it('registers a "forge" command on the parent program', () => {
-    const program = new Command();
-    registerForgeCommand(program);
-
-    const forgeCmd = program.commands.find((c) => c.name() === 'forge');
-    expect(forgeCmd).toBeDefined();
-  });
-
-  it('registers the four required subcommands under forge', () => {
-    const program = new Command();
-    registerForgeCommand(program);
-
-    const forgeCmd = program.commands.find((c) => c.name() === 'forge');
-    expect(forgeCmd).toBeDefined();
-
-    const subNames = forgeCmd!.commands.map((c) => c.name());
-
-    expect(subNames).toContain('run');
-    expect(subNames).toContain('status');
-    expect(subNames).toContain('resume');
-    expect(subNames).toContain('personas');
-  });
-
-  it('registers "personas list" as a subcommand of "forge personas"', () => {
-    const program = new Command();
-    registerForgeCommand(program);
-
-    const forgeCmd = program.commands.find((c) => c.name() === 'forge');
-    const personasCmd = forgeCmd!.commands.find((c) => c.name() === 'personas');
-    expect(personasCmd).toBeDefined();
-
-    const personasSubNames = personasCmd!.commands.map((c) => c.name());
-    expect(personasSubNames).toContain('list');
-  });
-
-  it('does not modify the parent program name or description', () => {
-    const program = new Command('mosaic');
-    program.description('Mosaic Stack CLI');
-    registerForgeCommand(program);
-
-    expect(program.name()).toBe('mosaic');
-    expect(program.description()).toBe('Mosaic Stack CLI');
-  });
-
-  it('can be called multiple times without throwing', () => {
-    const program = new Command();
-    expect(() => {
-      registerForgeCommand(program);
-    }).not.toThrow();
-  });
-});

packages/forge/src/cli.ts

@@ -1,280 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-import type { Command } from 'commander';
-
-import { classifyBrief } from './brief-classifier.js';
-import { STAGE_LABELS, STAGE_SEQUENCE } from './constants.js';
-import { getEffectivePersonas, loadBoardPersonas } from './persona-loader.js';
-import { generateRunId, getPipelineStatus, loadManifest, runPipeline } from './pipeline-runner.js';
-import type { PipelineOptions, RunManifest, TaskExecutor } from './types.js';
-
-// ---------------------------------------------------------------------------
-// Stub executor — used when no real executor is wired at CLI invocation time.
-// ---------------------------------------------------------------------------
-
-const stubExecutor: TaskExecutor = {
-  async submitTask(task) {
-    console.log(`  [forge] stage submitted: ${task.id} (${task.title})`);
-  },
-  async waitForCompletion(taskId, _timeoutMs) {
-    console.log(`  [forge] stage complete:  ${taskId}`);
-    return {
-      task_id: taskId,
-      status: 'completed' as const,
-      completed_at: new Date().toISOString(),
-      exit_code: 0,
-      gate_results: [],
-    };
-  },
-  async getTaskStatus(_taskId) {
-    return 'completed' as const;
-  },
-};
-
-// ---------------------------------------------------------------------------
-// Helpers
-// ---------------------------------------------------------------------------
-
-function formatDuration(startedAt?: string, completedAt?: string): string {
-  if (!startedAt || !completedAt) return '-';
-  const ms = new Date(completedAt).getTime() - new Date(startedAt).getTime();
-  const secs = Math.round(ms / 1000);
-  return secs < 60 ? `${secs}s` : `${Math.floor(secs / 60)}m${secs % 60}s`;
-}
-
-function printManifestTable(manifest: RunManifest): void {
-  console.log(`\nRun ID : ${manifest.runId}`);
-  console.log(`Status : ${manifest.status}`);
-  console.log(`Brief  : ${manifest.brief}`);
-  console.log(`Class  : ${manifest.briefClass} (${manifest.classSource})`);
-  console.log(`Updated: ${manifest.updatedAt}`);
-  console.log('');
-  console.log('Stage'.padEnd(22) + 'Status'.padEnd(14) + 'Duration');
-  console.log('-'.repeat(50));
-  for (const stage of STAGE_SEQUENCE) {
-    const s = manifest.stages[stage];
-    if (!s) continue;
-    const label = (STAGE_LABELS[stage] ?? stage).padEnd(22);
-    const status = s.status.padEnd(14);
-    const dur = formatDuration(s.startedAt, s.completedAt);
-    console.log(`${label}${status}${dur}`);
-  }
-  console.log('');
-}
-
-function resolveRunDir(runId: string, projectRoot?: string): string {
-  const root = projectRoot ?? process.cwd();
-  return path.join(root, '.forge', 'runs', runId);
-}
-
-function listRecentRuns(projectRoot?: string): void {
-  const root = projectRoot ?? process.cwd();
-  const runsDir = path.join(root, '.forge', 'runs');
-
-  if (!fs.existsSync(runsDir)) {
-    console.log('No runs found. Run `mosaic forge run` to start a pipeline.');
-    return;
-  }
-
-  const entries = fs
-    .readdirSync(runsDir)
-    .filter((name) => fs.statSync(path.join(runsDir, name)).isDirectory())
-    .sort()
-    .reverse()
-    .slice(0, 10);
-
-  if (entries.length === 0) {
-    console.log('No runs found.');
-    return;
-  }
-
-  console.log('\nRecent runs:');
-  console.log('Run ID'.padEnd(22) + 'Status'.padEnd(14) + 'Brief');
-  console.log('-'.repeat(70));
-
-  for (const runId of entries) {
-    const runDir = path.join(runsDir, runId);
-    try {
-      const manifest = loadManifest(runDir);
-      const status = manifest.status.padEnd(14);
-      const brief = path.basename(manifest.brief);
-      console.log(`${runId.padEnd(22)}${status}${brief}`);
-    } catch {
-      console.log(`${runId.padEnd(22)}${'(unreadable)'.padEnd(14)}`);
-    }
-  }
-  console.log('');
-}
-
-// ---------------------------------------------------------------------------
-// Register function
-// ---------------------------------------------------------------------------
-
-/**
- * Register forge subcommands on an existing Commander program.
- * Mirrors the pattern used by registerQualityRails in @mosaicstack/quality-rails.
- */
-export function registerForgeCommand(parent: Command): void {
-  const forge = parent.command('forge').description('Run and manage Forge pipelines');
-
-  // ── forge run ────────────────────────────────────────────────────────────
-
-  forge
-    .command('run')
-    .description('Run a Forge pipeline from a brief markdown file')
-    .requiredOption('--brief <path>', 'Path to the brief markdown file')
-    .option('--run-id <id>', 'Override the auto-generated run ID')
-    .option('--resume', 'Resume an existing run instead of starting a new one', false)
-    .option('--config <path>', 'Path to forge config file (.forge/config.yaml)')
-    .option('--codebase <path>', 'Codebase root to pass to the pipeline', process.cwd())
-    .option('--dry-run', 'Print planned stages without executing', false)
-    .action(
-      async (opts: {
-        brief: string;
-        runId?: string;
-        resume: boolean;
-        config?: string;
-        codebase: string;
-        dryRun: boolean;
-      }) => {
-        const briefPath = path.resolve(opts.brief);
-
-        if (!fs.existsSync(briefPath)) {
-          console.error(`[forge] brief not found: ${briefPath}`);
-          process.exitCode = 1;
-          return;
-        }
-
-        const briefContent = fs.readFileSync(briefPath, 'utf-8');
-        const briefClass = classifyBrief(briefContent);
-        const projectRoot = opts.codebase;
-
-        if (opts.resume) {
-          const runId = opts.runId ?? generateRunId();
-          const runDir = resolveRunDir(runId, projectRoot);
-          console.log(`[forge] resuming run: ${runId}`);
-          const { resumePipeline } = await import('./pipeline-runner.js');
-          const result = await resumePipeline(runDir, stubExecutor);
-          console.log(`[forge] pipeline complete: ${result.runId}`);
-          return;
-        }
-
-        const pipelineOptions: PipelineOptions = {
-          briefClass,
-          codebase: projectRoot,
-          dryRun: opts.dryRun,
-          executor: stubExecutor,
-        };
-
-        if (opts.dryRun) {
-          const { stagesForClass } = await import('./brief-classifier.js');
-          const stages = stagesForClass(briefClass);
-          console.log(`[forge] dry-run — brief class: ${briefClass}`);
-          console.log('[forge] planned stages:');
-          for (const stage of stages) {
-            console.log(`  - ${stage}  (${STAGE_LABELS[stage] ?? stage})`);
-          }
-          return;
-        }
-
-        console.log(`[forge] starting pipeline for brief: ${briefPath}`);
-        console.log(`[forge] classified as: ${briefClass}`);
-
-        try {
-          const result = await runPipeline(briefPath, projectRoot, pipelineOptions);
-          console.log(`[forge] pipeline complete: ${result.runId}`);
-          console.log(`[forge] run directory: ${result.runDir}`);
-        } catch (err) {
-          console.error(
-            `[forge] pipeline failed: ${err instanceof Error ? err.message : String(err)}`,
-          );
-          process.exitCode = 1;
-        }
-      },
-    );
-
-  // ── forge status ─────────────────────────────────────────────────────────
-
-  forge
-    .command('status [runId]')
-    .description('Show the status of a pipeline run (omit runId to list recent runs)')
-    .option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
-    .action(async (runId: string | undefined, opts: { project: string }) => {
-      if (!runId) {
-        listRecentRuns(opts.project);
-        return;
-      }
-
-      const runDir = resolveRunDir(runId, opts.project);
-      try {
-        const manifest = getPipelineStatus(runDir);
-        printManifestTable(manifest);
-      } catch (err) {
-        console.error(
-          `[forge] could not load run "${runId}": ${err instanceof Error ? err.message : String(err)}`,
-        );
-        process.exitCode = 1;
-      }
-    });
-
-  // ── forge resume ─────────────────────────────────────────────────────────
-
-  forge
-    .command('resume <runId>')
-    .description('Resume a stopped or failed pipeline run')
-    .option('--project <path>', 'Project root (defaults to cwd)', process.cwd())
-    .action(async (runId: string, opts: { project: string }) => {
-      const runDir = resolveRunDir(runId, opts.project);
-
-      if (!fs.existsSync(runDir)) {
-        console.error(`[forge] run not found: ${runDir}`);
-        process.exitCode = 1;
-        return;
-      }
-
-      console.log(`[forge] resuming run: ${runId}`);
-
-      try {
-        const { resumePipeline } = await import('./pipeline-runner.js');
-        const result = await resumePipeline(runDir, stubExecutor);
-        console.log(`[forge] pipeline complete: ${result.runId}`);
-        console.log(`[forge] run directory: ${result.runDir}`);
-      } catch (err) {
-        console.error(`[forge] resume failed: ${err instanceof Error ? err.message : String(err)}`);
-        process.exitCode = 1;
-      }
-    });
-
-  // ── forge personas ────────────────────────────────────────────────────────
-
-  const personas = forge.command('personas').description('Manage Forge board personas');
-
-  personas
-    .command('list')
-    .description('List configured board personas')
-    .option(
-      '--project <path>',
-      'Project root for persona overrides (defaults to cwd)',
-      process.cwd(),
-    )
-    .option('--board-dir <path>', 'Override the board agents directory')
-    .action((opts: { project: string; boardDir?: string }) => {
-      const effectivePersonas = opts.boardDir
-        ? loadBoardPersonas(opts.boardDir)
-        : getEffectivePersonas(opts.project);
-
-      if (effectivePersonas.length === 0) {
-        console.log('[forge] no board personas configured.');
-        return;
-      }
-
-      console.log(`\nBoard personas (${effectivePersonas.length}):\n`);
-      console.log('Slug'.padEnd(24) + 'Name');
-      console.log('-'.repeat(50));
-      for (const p of effectivePersonas) {
-        console.log(`${p.slug.padEnd(24)}${p.name}`);
-      }
-      console.log('');
-    });
-}

packages/forge/src/index.ts

@@ -80,6 +80,3 @@ export {
   resumePipeline,
   getPipelineStatus,
 } from './pipeline-runner.js';
-
-// CLI
-export { registerForgeCommand } from './cli.js';

packages/log/package.json

@@ -23,7 +23,6 @@
   },
   "dependencies": {
     "@mosaicstack/db": "workspace:*",
-    "commander": "^13.0.0",
     "drizzle-orm": "^0.45.1"
   },
   "devDependencies": {

packages/log/src/cli.spec.ts

@@ -1,68 +0,0 @@
-import { Command } from 'commander';
-import { describe, it, expect } from 'vitest';
-
-import { registerLogCommand } from './cli.js';
-
-function buildTestProgram(): Command {
-  const program = new Command('mosaic');
-  program.exitOverride(); // prevent process.exit in tests
-  registerLogCommand(program);
-  return program;
-}
-
-describe('registerLogCommand', () => {
-  it('registers a "log" subcommand on the parent', () => {
-    const program = buildTestProgram();
-    const names = program.commands.map((c) => c.name());
-    expect(names).toContain('log');
-  });
-
-  it('log command has tail, search, export, and level subcommands', () => {
-    const program = buildTestProgram();
-    const logCmd = program.commands.find((c) => c.name() === 'log');
-    expect(logCmd).toBeDefined();
-    const subNames = logCmd!.commands.map((c) => c.name());
-    expect(subNames).toContain('tail');
-    expect(subNames).toContain('search');
-    expect(subNames).toContain('export');
-    expect(subNames).toContain('level');
-  });
-
-  it('tail subcommand has expected options', () => {
-    const program = buildTestProgram();
-    const logCmd = program.commands.find((c) => c.name() === 'log')!;
-    const tailCmd = logCmd.commands.find((c) => c.name() === 'tail')!;
-    const optionNames = tailCmd.options.map((o) => o.long);
-    expect(optionNames).toContain('--agent');
-    expect(optionNames).toContain('--level');
-    expect(optionNames).toContain('--category');
-    expect(optionNames).toContain('--tier');
-    expect(optionNames).toContain('--limit');
-    expect(optionNames).toContain('--db');
-  });
-
-  it('search subcommand accepts a positional query argument', () => {
-    const program = buildTestProgram();
-    const logCmd = program.commands.find((c) => c.name() === 'log')!;
-    const searchCmd = logCmd.commands.find((c) => c.name() === 'search')!;
-    // Commander stores positional args in _args
-    const argNames = searchCmd.registeredArguments.map((a) => a.name());
-    expect(argNames).toContain('query');
-  });
-
-  it('export subcommand accepts a positional path argument', () => {
-    const program = buildTestProgram();
-    const logCmd = program.commands.find((c) => c.name() === 'log')!;
-    const exportCmd = logCmd.commands.find((c) => c.name() === 'export')!;
-    const argNames = exportCmd.registeredArguments.map((a) => a.name());
-    expect(argNames).toContain('path');
-  });
-
-  it('level subcommand accepts a positional level argument', () => {
-    const program = buildTestProgram();
-    const logCmd = program.commands.find((c) => c.name() === 'log')!;
-    const levelCmd = logCmd.commands.find((c) => c.name() === 'level')!;
-    const argNames = levelCmd.registeredArguments.map((a) => a.name());
-    expect(argNames).toContain('level');
-  });
-});

packages/log/src/cli.ts

@@ -1,177 +0,0 @@
-import { writeFileSync } from 'node:fs';
-
-import type { Command } from 'commander';
-
-import type { LogCategory, LogLevel, LogTier } from './agent-logs.js';
-
-interface FilterOptions {
-  agent?: string;
-  level?: string;
-  category?: string;
-  tier?: string;
-  limit?: string;
-  db?: string;
-}
-
-function parseLimit(raw: string | undefined, defaultVal = 50): number {
-  if (!raw) return defaultVal;
-  const n = parseInt(raw, 10);
-  return Number.isFinite(n) && n > 0 ? n : defaultVal;
-}
-
-function buildQuery(opts: FilterOptions) {
-  return {
-    ...(opts.agent ? { sessionId: opts.agent } : {}),
-    ...(opts.level ? { level: opts.level as LogLevel } : {}),
-    ...(opts.category ? { category: opts.category as LogCategory } : {}),
-    ...(opts.tier ? { tier: opts.tier as LogTier } : {}),
-    limit: parseLimit(opts.limit),
-  };
-}
-
-async function openDb(connectionString: string) {
-  const { createDb } = await import('@mosaicstack/db');
-  return createDb(connectionString);
-}
-
-function resolveConnectionString(opts: FilterOptions): string | undefined {
-  return opts.db ?? process.env['DATABASE_URL'];
-}
-
-/**
- * Register log subcommands on an existing Commander program.
- * This avoids cross-package Commander version mismatches by using the
- * caller's Command instance directly.
- */
-export function registerLogCommand(parent: Command): void {
-  const log = parent.command('log').description('Query and manage agent logs');
-
-  // ─── tail ───────────────────────────────────────────────────────────────
-
-  log
-    .command('tail')
-    .description('Tail recent agent logs')
-    .option('--agent <id>', 'Filter by agent/session ID')
-    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
-    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
-    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
-    .option('--limit <n>', 'Number of logs to return (default 50)', '50')
-    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
-    .action(async (opts: FilterOptions) => {
-      const connStr = resolveConnectionString(opts);
-      if (!connStr) {
-        console.error('Database connection required: use --db or set DATABASE_URL');
-        process.exit(1);
-      }
-
-      const handle = await openDb(connStr);
-      try {
-        const { createLogService } = await import('./log-service.js');
-        const svc = createLogService(handle.db);
-        const query = buildQuery(opts);
-
-        const logs = await svc.logs.query(query);
-        if (logs.length === 0) {
-          console.log('No logs found.');
-          return;
-        }
-        for (const entry of logs) {
-          const ts = new Date(entry.createdAt).toISOString();
-          console.log(`[${ts}] [${entry.level}] [${entry.category}] ${entry.content}`);
-        }
-      } finally {
-        await handle.close();
-      }
-    });
-
-  // ─── search ─────────────────────────────────────────────────────────────
-
-  log
-    .command('search <query>')
-    .description('Full-text search over agent logs')
-    .option('--agent <id>', 'Filter by agent/session ID')
-    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
-    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
-    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
-    .option('--limit <n>', 'Number of logs to return (default 50)', '50')
-    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
-    .action(async (query: string, opts: FilterOptions) => {
-      const connStr = resolveConnectionString(opts);
-      if (!connStr) {
-        console.error('Database connection required: use --db or set DATABASE_URL');
-        process.exit(1);
-      }
-
-      const handle = await openDb(connStr);
-      try {
-        const { createLogService } = await import('./log-service.js');
-        const svc = createLogService(handle.db);
-        const baseQuery = buildQuery(opts);
-
-        const logs = await svc.logs.query(baseQuery);
-        const lowerQ = query.toLowerCase();
-        const matched = logs.filter(
-          (e) =>
-            e.content.toLowerCase().includes(lowerQ) ||
-            (e.metadata != null && JSON.stringify(e.metadata).toLowerCase().includes(lowerQ)),
-        );
-
-        if (matched.length === 0) {
-          console.log('No matching logs found.');
-          return;
-        }
-        for (const entry of matched) {
-          const ts = new Date(entry.createdAt).toISOString();
-          console.log(`[${ts}] [${entry.level}] [${entry.category}] ${entry.content}`);
-        }
-      } finally {
-        await handle.close();
-      }
-    });
-
-  // ─── export ─────────────────────────────────────────────────────────────
-
-  log
-    .command('export <path>')
-    .description('Export matching logs to an NDJSON file')
-    .option('--agent <id>', 'Filter by agent/session ID')
-    .option('--level <level>', 'Filter by log level (debug|info|warn|error)')
-    .option('--category <cat>', 'Filter by category (decision|tool_use|learning|error|general)')
-    .option('--tier <tier>', 'Filter by tier (hot|warm|cold)')
-    .option('--limit <n>', 'Number of logs to export (default 50)', '50')
-    .option('--db <connection-string>', 'Database connection string (or set DATABASE_URL)')
-    .action(async (outputPath: string, opts: FilterOptions) => {
-      const connStr = resolveConnectionString(opts);
-      if (!connStr) {
-        console.error('Database connection required: use --db or set DATABASE_URL');
-        process.exit(1);
-      }
-
-      const handle = await openDb(connStr);
-      try {
-        const { createLogService } = await import('./log-service.js');
-        const svc = createLogService(handle.db);
-        const query = buildQuery(opts);
-
-        const logs = await svc.logs.query(query);
-        const ndjson = logs.map((e) => JSON.stringify(e)).join('\n');
-        writeFileSync(outputPath, ndjson, 'utf8');
-        console.log(`Exported ${logs.length} log(s) to ${outputPath}`);
-      } finally {
-        await handle.close();
-      }
-    });
-
-  // ─── level ──────────────────────────────────────────────────────────────
-
-  log
-    .command('level <level>')
-    .description('Set runtime log level for the connected log service')
-    .action((level: string) => {
-      void level;
-      console.log(
-        'Runtime log level adjustment is not supported in current mode (DB-backed log service).',
-      );
-      process.exitCode = 0;
-    });
-}

packages/memory/src/index.ts

@@ -1,4 +1,5 @@
 export { createMemory, type Memory } from './memory.js';
+export { registerMemoryCommand } from './cli.js';
 export {
   createPreferencesRepo,
   type PreferencesRepo,

packages/mosaic/package.json

@@ -27,11 +27,15 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/macp": "workspace:*",
+    "@mosaicstack/memory": "workspace:*",
     "@mosaicstack/prdy": "workspace:*",
     "@mosaicstack/quality-rails": "workspace:*",
+    "@mosaicstack/queue": "workspace:*",
+    "@mosaicstack/storage": "workspace:*",
     "@mosaicstack/types": "workspace:*",
     "@clack/prompts": "^0.9.1",
     "commander": "^13.0.0",

packages/mosaic/src/cli.ts

@@ -2,10 +2,14 @@
 
 import { createRequire } from 'module';
 import { Command } from 'commander';
-import { registerForgeCommand } from '@mosaicstack/forge';
-import { registerQualityRails } from '@mosaicstack/quality-rails';
+import { registerBrainCommand } from '@mosaicstack/brain';
 import { registerMacpCommand } from '@mosaicstack/macp';
+import { registerMemoryCommand } from '@mosaicstack/memory';
+import { registerQualityRails } from '@mosaicstack/quality-rails';
+import { registerQueueCommand } from '@mosaicstack/queue';
+import { registerStorageCommand } from '@mosaicstack/storage';
 import { registerAgentCommand } from './commands/agent.js';
+import { registerConfigCommand } from './commands/config.js';
 import { registerMissionCommand } from './commands/mission.js';
 // prdy is registered via launch.ts
 import { registerLaunchCommands } from './commands/launch.js';
@@ -35,7 +39,23 @@ try {
 
 const program = new Command();
 
-program.name('mosaic').description('Mosaic Stack CLI').version(CLI_VERSION);
+program
+  .name('mosaic')
+  .description('Mosaic Stack CLI')
+  .version(CLI_VERSION)
+  .configureHelp({ sortSubcommands: true })
+  .addHelpText(
+    'after',
+    `
+Command Groups:
+
+  Runtime:    tui, login, sessions
+  Gateway:    gateway
+  Framework:  agent, bootstrap, coord, doctor, init, launch, mission, prdy, seq, sync, upgrade, wizard, yolo
+  Platform:   update
+  Runtimes:   claude, codex, opencode, pi
+`,
+  );
 
 // ─── runtime launchers + framework commands ────────────────────────────
 
@@ -216,7 +236,10 @@ program
 
 // ─── sessions ───────────────────────────────────────────────────────────
 
-const sessionsCmd = program.command('sessions').description('Manage active agent sessions');
+const sessionsCmd = program
+  .command('sessions')
+  .description('Manage active agent sessions')
+  .configureHelp({ sortSubcommands: true });
 
 sessionsCmd
   .command('list')
@@ -312,22 +335,38 @@ registerGatewayCommand(program);
 
 registerAgentCommand(program);
 
+// ─── config ────────────────────────────────────────────────────────────
+
+registerConfigCommand(program);
+
 // ─── mission ───────────────────────────────────────────────────────────
 
 registerMissionCommand(program);
 
+// ─── brain ──────────────────────────────────────────────────────────────
+
+registerBrainCommand(program);
+
 // ─── macp ────────────────────────────────────────────────────────────────
 
 registerMacpCommand(program);
 
-// ─── forge ───────────────────────────────────────────────────────────────
-
-registerForgeCommand(program);
-
 // ─── quality-rails ──────────────────────────────────────────────────────
 
 registerQualityRails(program);
 
+// ─── memory ──────────────────────────────────────────────────────────────
+
+registerMemoryCommand(program);
+
+// ─── queue ───────────────────────────────────────────────────────────────
+
+registerQueueCommand(program);
+
+// ─── storage ─────────────────────────────────────────────────────────────
+
+registerStorageCommand(program);
+
 // ─── update ─────────────────────────────────────────────────────────────
 
 program

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

@@ -0,0 +1,289 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { Command } from 'commander';
+import { registerConfigCommand } from './config.js';
+
+// ── helpers ──────────────────────────────────────────────────────────────────
+
+/** Build a fresh Command tree with the config command registered. */
+function buildProgram(): Command {
+  const program = new Command();
+  program.exitOverride(); // prevent process.exit during tests
+  registerConfigCommand(program);
+  return program;
+}
+
+/** Locate the 'config' command registered on the root program. */
+function getConfigCmd(program: Command): Command {
+  const found = program.commands.find((c) => c.name() === 'config');
+  if (!found) throw new Error('config command not found');
+  return found;
+}
+
+// ── subcommand registration ───────────────────────────────────────────────────
+
+describe('registerConfigCommand', () => {
+  it('registers a "config" command on the program', () => {
+    const program = buildProgram();
+    const names = program.commands.map((c) => c.name());
+    expect(names).toContain('config');
+  });
+
+  it('registers exactly the five required subcommands', () => {
+    const program = buildProgram();
+    const config = getConfigCmd(program);
+    const subs = config.commands.map((c) => c.name()).sort();
+    expect(subs).toEqual(['edit', 'get', 'path', 'set', 'show']);
+  });
+});
+
+// ── mock config service ───────────────────────────────────────────────────────
+
+const mockSoul = {
+  agentName: 'TestBot',
+  roleDescription: 'test role',
+  communicationStyle: 'direct' as const,
+};
+const mockUser = { userName: 'Tester', pronouns: 'they/them', timezone: 'UTC' };
+const mockTools = { credentialsLocation: '/dev/null' };
+
+const mockSvc = {
+  readSoul: vi.fn().mockResolvedValue(mockSoul),
+  readUser: vi.fn().mockResolvedValue(mockUser),
+  readTools: vi.fn().mockResolvedValue(mockTools),
+  writeSoul: vi.fn().mockResolvedValue(undefined),
+  writeUser: vi.fn().mockResolvedValue(undefined),
+  writeTools: vi.fn().mockResolvedValue(undefined),
+  syncFramework: vi.fn().mockResolvedValue(undefined),
+  readAll: vi.fn().mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools }),
+  getValue: vi.fn().mockResolvedValue('TestBot'),
+  setValue: vi.fn().mockResolvedValue('OldBot'),
+  getConfigPath: vi
+    .fn()
+    .mockImplementation((section?: string) =>
+      section
+        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
+        : '/home/user/.config/mosaic',
+    ),
+  isInitialized: vi.fn().mockReturnValue(true),
+};
+
+// Mock the config-service module so commands use our mock.
+vi.mock('../config/config-service.js', () => ({
+  createConfigService: vi.fn(() => mockSvc),
+}));
+
+// Also mock child_process for the edit command.
+vi.mock('node:child_process', () => ({
+  spawnSync: vi.fn().mockReturnValue({ status: 0, error: undefined }),
+}));
+
+// ── config show ───────────────────────────────────────────────────────────────
+
+describe('config show', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.clearAllMocks();
+    mockSvc.isInitialized.mockReturnValue(true);
+    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  it('calls readAll() and prints a table by default', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'show']);
+    expect(mockSvc.readAll).toHaveBeenCalledOnce();
+    // Should have printed something
+    expect(consoleSpy).toHaveBeenCalled();
+  });
+
+  it('prints JSON when --format json is passed', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'show', '--format', 'json']);
+    expect(mockSvc.readAll).toHaveBeenCalledOnce();
+    // Verify JSON was logged
+    const allOutput = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
+    expect(allOutput).toContain('"agentName"');
+  });
+});
+
+// ── config get ────────────────────────────────────────────────────────────────
+
+describe('config get', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.clearAllMocks();
+    mockSvc.isInitialized.mockReturnValue(true);
+    mockSvc.getValue.mockResolvedValue('TestBot');
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  it('delegates to getValue() with the provided key', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
+    expect(mockSvc.getValue).toHaveBeenCalledWith('soul.agentName');
+  });
+
+  it('prints the returned value', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'get', 'soul.agentName']);
+    expect(consoleSpy).toHaveBeenCalledWith('TestBot');
+  });
+});
+
+// ── config set ────────────────────────────────────────────────────────────────
+
+describe('config set', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.clearAllMocks();
+    mockSvc.isInitialized.mockReturnValue(true);
+    mockSvc.setValue.mockResolvedValue('OldBot');
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  it('delegates to setValue() with key and value', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
+    expect(mockSvc.setValue).toHaveBeenCalledWith('soul.agentName', 'NewBot');
+  });
+
+  it('prints old and new values', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'set', 'soul.agentName', 'NewBot']);
+    const output = consoleSpy.mock.calls.map((c) => c[0] as string).join('\n');
+    expect(output).toContain('OldBot');
+    expect(output).toContain('NewBot');
+  });
+});
+
+// ── config path ───────────────────────────────────────────────────────────────
+
+describe('config path', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.clearAllMocks();
+    mockSvc.getConfigPath.mockImplementation((section?: string) =>
+      section
+        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
+        : '/home/user/.config/mosaic',
+    );
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  it('prints the mosaicHome directory when no section is specified', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'path']);
+    expect(mockSvc.getConfigPath).toHaveBeenCalledWith();
+    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic');
+  });
+
+  it('prints the section file path when --section is given', async () => {
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'path', '--section', 'soul']);
+    expect(mockSvc.getConfigPath).toHaveBeenCalledWith('soul');
+    expect(consoleSpy).toHaveBeenCalledWith('/home/user/.config/mosaic/SOUL.md');
+  });
+});
+
+// ── config edit ───────────────────────────────────────────────────────────────
+
+describe('config edit', () => {
+  let consoleSpy: ReturnType<typeof vi.spyOn>;
+  let spawnSyncMock: ReturnType<typeof vi.fn>;
+
+  beforeEach(async () => {
+    consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => undefined);
+    vi.clearAllMocks();
+    mockSvc.isInitialized.mockReturnValue(true);
+    mockSvc.readAll.mockResolvedValue({ soul: mockSoul, user: mockUser, tools: mockTools });
+    mockSvc.getConfigPath.mockImplementation((section?: string) =>
+      section
+        ? `/home/user/.config/mosaic/${section.toUpperCase()}.md`
+        : '/home/user/.config/mosaic',
+    );
+
+    // Re-import to get the mock reference
+    const cp = await import('node:child_process');
+    spawnSyncMock = cp.spawnSync as ReturnType<typeof vi.fn>;
+    spawnSyncMock.mockReturnValue({ status: 0, error: undefined });
+  });
+
+  afterEach(() => {
+    consoleSpy.mockRestore();
+  });
+
+  it('calls spawnSync with the editor binary and config path', async () => {
+    process.env['EDITOR'] = 'nano';
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      'nano',
+      ['/home/user/.config/mosaic'],
+      expect.objectContaining({ stdio: 'inherit' }),
+    );
+    delete process.env['EDITOR'];
+  });
+
+  it('falls back to "vi" when EDITOR is not set', async () => {
+    delete process.env['EDITOR'];
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'edit']);
+    expect(spawnSyncMock).toHaveBeenCalledWith('vi', expect.any(Array), expect.any(Object));
+  });
+
+  it('opens the section-specific file when --section is provided', async () => {
+    process.env['EDITOR'] = 'code';
+    const program = buildProgram();
+    await program.parseAsync(['node', 'mosaic', 'config', 'edit', '--section', 'soul']);
+    expect(spawnSyncMock).toHaveBeenCalledWith(
+      'code',
+      ['/home/user/.config/mosaic/SOUL.md'],
+      expect.any(Object),
+    );
+    delete process.env['EDITOR'];
+  });
+});
+
+// ── not-initialized guard ────────────────────────────────────────────────────
+
+describe('not-initialized guard', () => {
+  let consoleErrorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => undefined);
+    vi.clearAllMocks();
+    mockSvc.isInitialized.mockReturnValue(false);
+  });
+
+  afterEach(() => {
+    consoleErrorSpy.mockRestore();
+    mockSvc.isInitialized.mockReturnValue(true);
+  });
+
+  it('prints a helpful message when config is missing (show)', async () => {
+    const program = buildProgram();
+    // process.exit is intercepted; catch the resulting error from exitOverride
+    await expect(program.parseAsync(['node', 'mosaic', 'config', 'show'])).rejects.toThrow();
+    expect(consoleErrorSpy).toHaveBeenCalledWith(expect.stringContaining('mosaic wizard'));
+  });
+});

packages/mosaic/src/commands/config.ts

@@ -0,0 +1,206 @@
+import { spawnSync } from 'node:child_process';
+import type { Command } from 'commander';
+import { createConfigService } from '../config/config-service.js';
+import { DEFAULT_MOSAIC_HOME } from '../constants.js';
+
+/**
+ * Resolve mosaicHome from the MOSAIC_HOME env var or the default constant.
+ */
+function getMosaicHome(): string {
+  return process.env['MOSAIC_HOME'] ?? DEFAULT_MOSAIC_HOME;
+}
+
+/**
+ * Guard: print an error and exit(1) if config has not been initialised.
+ */
+function assertInitialized(svc: ReturnType<typeof createConfigService>): void {
+  if (!svc.isInitialized()) {
+    console.error('No config found — run `mosaic wizard` first.');
+    process.exit(1);
+  }
+}
+
+/**
+ * Flatten a nested object into dotted-key rows for table display.
+ */
+function flattenConfig(obj: Record<string, unknown>, prefix = ''): Array<[string, string]> {
+  const rows: Array<[string, string]> = [];
+  for (const [k, v] of Object.entries(obj)) {
+    const key = prefix ? `${prefix}.${k}` : k;
+    if (v !== null && typeof v === 'object' && !Array.isArray(v)) {
+      rows.push(...flattenConfig(v as Record<string, unknown>, key));
+    } else {
+      rows.push([key, v === undefined || v === null ? '' : String(v)]);
+    }
+  }
+  return rows;
+}
+
+/**
+ * Print rows as a padded ASCII table.
+ */
+function printTable(rows: Array<[string, string]>): void {
+  if (rows.length === 0) {
+    console.log('(no config values)');
+    return;
+  }
+  const maxKey = Math.max(...rows.map(([k]) => k.length));
+  const header = `${'Key'.padEnd(maxKey)}  Value`;
+  const divider = '-'.repeat(header.length);
+  console.log(header);
+  console.log(divider);
+  for (const [k, v] of rows) {
+    console.log(`${k.padEnd(maxKey)}  ${v}`);
+  }
+}
+
+export function registerConfigCommand(program: Command): void {
+  const cmd = program
+    .command('config')
+    .description('Manage Mosaic framework configuration')
+    .configureHelp({ sortSubcommands: true });
+
+  // ── config show ─────────────────────────────────────────────────────────
+
+  cmd
+    .command('show')
+    .description('Print the current resolved config')
+    .option('-f, --format <format>', 'Output format: table or json', 'table')
+    .action(async (opts: { format: string }) => {
+      const mosaicHome = getMosaicHome();
+      const svc = createConfigService(mosaicHome, mosaicHome);
+      assertInitialized(svc);
+
+      const config = await svc.readAll();
+
+      if (opts.format === 'json') {
+        console.log(JSON.stringify(config, null, 2));
+        return;
+      }
+
+      // Default: table
+      const rows = flattenConfig(config as unknown as Record<string, unknown>);
+      printTable(rows);
+    });
+
+  // ── config get <key> ────────────────────────────────────────────────────
+
+  cmd
+    .command('get <key>')
+    .description('Print a single config value (supports dotted keys, e.g. soul.agentName)')
+    .action(async (key: string) => {
+      const mosaicHome = getMosaicHome();
+      const svc = createConfigService(mosaicHome, mosaicHome);
+      assertInitialized(svc);
+
+      const value = await svc.getValue(key);
+      if (value === undefined) {
+        console.error(`Key "${key}" not found.`);
+        process.exit(1);
+      }
+      if (typeof value === 'object') {
+        console.log(JSON.stringify(value, null, 2));
+      } else {
+        console.log(String(value));
+      }
+    });
+
+  // ── config set <key> <value> ────────────────────────────────────────────
+
+  cmd
+    .command('set <key> <value>')
+    .description(
+      'Set a config value and persist (supports dotted keys, e.g. soul.agentName "Jarvis")',
+    )
+    .action(async (key: string, value: string) => {
+      const mosaicHome = getMosaicHome();
+      const svc = createConfigService(mosaicHome, mosaicHome);
+      assertInitialized(svc);
+
+      let previous: unknown;
+      try {
+        previous = await svc.setValue(key, value);
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+
+      const prevStr = previous === undefined ? '(unset)' : String(previous);
+      console.log(`${key}`);
+      console.log(`  old: ${prevStr}`);
+      console.log(`  new: ${value}`);
+    });
+
+  // ── config edit ─────────────────────────────────────────────────────────
+
+  cmd
+    .command('edit')
+    .description('Open the config directory in $EDITOR (or vi)')
+    .option('-s, --section <section>', 'Open a specific section file: soul | user | tools')
+    .action(async (opts: { section?: string }) => {
+      const mosaicHome = getMosaicHome();
+      const svc = createConfigService(mosaicHome, mosaicHome);
+      assertInitialized(svc);
+
+      const editor = process.env['EDITOR'] ?? 'vi';
+
+      let targetPath: string;
+      if (opts.section) {
+        const validSections = ['soul', 'user', 'tools'] as const;
+        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
+          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
+          process.exit(1);
+        }
+        targetPath = svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools');
+      } else {
+        targetPath = svc.getConfigPath();
+      }
+
+      const result = spawnSync(editor, [targetPath], { stdio: 'inherit' });
+
+      if (result.error) {
+        console.error(`Failed to open editor: ${result.error.message}`);
+        process.exit(1);
+      }
+
+      if (result.status !== 0) {
+        console.error(`Editor exited with code ${String(result.status ?? 1)}`);
+        process.exit(result.status ?? 1);
+      }
+
+      // Re-read after edit and report any issues
+      try {
+        await svc.readAll();
+        console.log('Config looks valid.');
+      } catch (err) {
+        console.error('Warning: config may have validation issues:');
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
+  // ── config path ─────────────────────────────────────────────────────────
+
+  cmd
+    .command('path')
+    .description('Print the active config directory path (for scripting)')
+    .option(
+      '-s, --section <section>',
+      'Print path for a specific section file: soul | user | tools',
+    )
+    .action(async (opts: { section?: string }) => {
+      const mosaicHome = getMosaicHome();
+      const svc = createConfigService(mosaicHome, mosaicHome);
+
+      if (opts.section) {
+        const validSections = ['soul', 'user', 'tools'] as const;
+        if (!validSections.includes(opts.section as (typeof validSections)[number])) {
+          console.error(`Invalid section "${opts.section}". Choose: soul, user, tools`);
+          process.exit(1);
+        }
+        console.log(svc.getConfigPath(opts.section as 'soul' | 'user' | 'tools'));
+      } else {
+        console.log(svc.getConfigPath());
+      }
+    });
+}

packages/mosaic/src/commands/gateway.ts

@@ -6,6 +6,7 @@ import {
   stopDaemon,
   waitForHealth,
 } from './gateway/daemon.js';
+import { getGatewayUrl } from './gateway/login.js';
 
 interface GatewayParentOpts {
   host: string;
@@ -30,6 +31,7 @@ export function registerGatewayCommand(program: Command): void {
     .option('-h, --host <host>', 'Gateway host', 'localhost')
     .option('-p, --port <port>', 'Gateway port', '14242')
     .option('-t, --token <token>', 'Admin API token')
+    .configureHelp({ sortSubcommands: true })
     .action(() => {
       gw.outputHelp();
     });
@@ -118,9 +120,28 @@ export function registerGatewayCommand(program: Command): void {
       await runStatus(opts);
     });
 
+  // ─── login ──────────────────────────────────────────────────────────────
+
+  gw.command('login')
+    .description('Sign in to the gateway (defaults to URL from meta.json)')
+    .option('-g, --gateway <url>', 'Gateway URL (overrides meta.json)')
+    .option('-e, --email <email>', 'Email address')
+    .option('-p, --password <password>', 'Password')
+    .action(async (cmdOpts: { gateway?: string; email?: string; password?: string }) => {
+      const { runLogin } = await import('./gateway/login.js');
+      const url = getGatewayUrl(cmdOpts.gateway);
+      try {
+        await runLogin({ gatewayUrl: url, email: cmdOpts.email, password: cmdOpts.password });
+      } catch (err) {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+      }
+    });
+
   // ─── config ─────────────────────────────────────────────────────────────
 
-  gw.command('config')
+  const configCmd = gw
+    .command('config')
     .description('View or modify gateway configuration')
     .option('--set <KEY=VALUE>', 'Set a configuration value')
     .option('--unset <KEY>', 'Remove a configuration key')
@@ -130,6 +151,24 @@ export function registerGatewayCommand(program: Command): void {
       await runConfig(cmdOpts);
     });
 
+  configCmd
+    .command('rotate-token')
+    .description('Mint a new admin token using the stored BetterAuth session')
+    .option('-g, --gateway <url>', 'Gateway URL (overrides meta.json)')
+    .action(async (cmdOpts: { gateway?: string }) => {
+      const { runRotateToken } = await import('./gateway/token-ops.js');
+      await runRotateToken(cmdOpts.gateway);
+    });
+
+  configCmd
+    .command('recover-token')
+    .description('Recover an admin token — prompts for login if no valid session exists')
+    .option('-g, --gateway <url>', 'Gateway URL (overrides meta.json)')
+    .action(async (cmdOpts: { gateway?: string }) => {
+      const { runRecoverToken } = await import('./gateway/token-ops.js');
+      await runRecoverToken(cmdOpts.gateway);
+    });
+
   // ─── logs ───────────────────────────────────────────────────────────────
 
   gw.command('logs')

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

@@ -388,10 +388,32 @@ async function bootstrapFirstUser(
     if (!status.needsSetup) {
       if (meta.adminToken) {
         console.log('Admin user already exists (token on file).');
-      } else {
-        console.log('Admin user already exists — skipping setup.');
-        console.log('(No admin token on file — sign in via the web UI to manage tokens.)');
+        return;
       }
+
+      // Admin user exists but no token — offer inline recovery when interactive.
+      console.log('Admin user already exists but no admin token is on file.');
+
+      if (process.stdin.isTTY) {
+        const answer = (await prompt(rl, 'Run token recovery now? [Y/n] ')).trim().toLowerCase();
+        if (answer === '' || answer === 'y' || answer === 'yes') {
+          console.log();
+          try {
+            const { ensureSession, mintAdminToken, persistToken } = await import('./token-ops.js');
+            const cookie = await ensureSession(baseUrl);
+            const label = `CLI recovery token (${new Date().toISOString().slice(0, 16).replace('T', ' ')})`;
+            const minted = await mintAdminToken(baseUrl, cookie, label);
+            persistToken(baseUrl, minted);
+          } catch (err) {
+            console.error(
+              `Token recovery failed: ${err instanceof Error ? err.message : String(err)}`,
+            );
+          }
+          return;
+        }
+      }
+
+      console.log('No admin token on file. Run: mosaic gateway config recover-token');
       return;
     }
   } catch {

packages/mosaic/src/commands/gateway/login.spec.ts

@@ -0,0 +1,87 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// Mock auth module
+vi.mock('../../auth.js', () => ({
+  signIn: vi.fn(),
+  saveSession: vi.fn(),
+}));
+
+// Mock daemon to avoid file-system reads
+vi.mock('./daemon.js', () => ({
+  readMeta: vi.fn().mockReturnValue({
+    host: 'localhost',
+    port: 14242,
+    version: '1.0.0',
+    installedAt: '',
+    entryPoint: '',
+  }),
+}));
+
+import { runLogin, getGatewayUrl } from './login.js';
+import { signIn, saveSession } from '../../auth.js';
+import { readMeta } from './daemon.js';
+
+const mockSignIn = vi.mocked(signIn);
+const mockSaveSession = vi.mocked(saveSession);
+const mockReadMeta = vi.mocked(readMeta);
+
+describe('getGatewayUrl', () => {
+  it('returns override URL when provided', () => {
+    expect(getGatewayUrl('http://my-gateway:9999')).toBe('http://my-gateway:9999');
+  });
+
+  it('builds URL from meta.json when no override given', () => {
+    mockReadMeta.mockReturnValueOnce({
+      host: 'myhost',
+      port: 8080,
+      version: '1.0.0',
+      installedAt: '',
+      entryPoint: '',
+    });
+    expect(getGatewayUrl()).toBe('http://myhost:8080');
+  });
+
+  it('falls back to default when meta is null', () => {
+    mockReadMeta.mockReturnValueOnce(null);
+    expect(getGatewayUrl()).toBe('http://localhost:14242');
+  });
+});
+
+describe('runLogin', () => {
+  const consoleLogSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('calls signIn and saveSession on success', async () => {
+    const fakeAuth = {
+      cookie: 'better-auth.session_token=abc',
+      userId: 'u1',
+      email: 'admin@test.com',
+    };
+    mockSignIn.mockResolvedValueOnce(fakeAuth);
+
+    await runLogin({
+      gatewayUrl: 'http://localhost:14242',
+      email: 'admin@test.com',
+      password: 'password123',
+    });
+
+    expect(mockSignIn).toHaveBeenCalledWith(
+      'http://localhost:14242',
+      'admin@test.com',
+      'password123',
+    );
+    expect(mockSaveSession).toHaveBeenCalledWith('http://localhost:14242', fakeAuth);
+    expect(consoleLogSpy).toHaveBeenCalledWith(expect.stringContaining('admin@test.com'));
+  });
+
+  it('propagates signIn errors', async () => {
+    mockSignIn.mockRejectedValueOnce(new Error('Sign-in failed (401): invalid credentials'));
+
+    await expect(
+      runLogin({ gatewayUrl: 'http://localhost:14242', email: 'bad@test.com', password: 'wrong' }),
+    ).rejects.toThrow('Sign-in failed (401)');
+  });
+});

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

@@ -0,0 +1,39 @@
+import { createInterface } from 'node:readline';
+import { signIn, saveSession } from '../../auth.js';
+import { readMeta } from './daemon.js';
+
+/**
+ * Shared login helper used by both `mosaic login` and `mosaic gateway login`.
+ * Prompts for email/password if not supplied, signs in, and persists the session.
+ */
+export async function runLogin(opts: {
+  gatewayUrl: string;
+  email?: string;
+  password?: string;
+}): Promise<void> {
+  let email = opts.email;
+  let password = opts.password;
+
+  if (!email || !password) {
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+    if (!email) email = await ask('Email: ');
+    if (!password) password = await ask('Password: ');
+    rl.close();
+  }
+
+  const auth = await signIn(opts.gatewayUrl, email, password);
+  saveSession(opts.gatewayUrl, auth);
+  console.log(`Signed in as ${auth.email} (${opts.gatewayUrl})`);
+}
+
+/**
+ * Derive the gateway base URL from meta.json with a fallback.
+ */
+export function getGatewayUrl(overrideUrl?: string): string {
+  if (overrideUrl) return overrideUrl;
+  const meta = readMeta();
+  if (meta) return `http://${meta.host}:${meta.port.toString()}`;
+  return 'http://localhost:14242';
+}

packages/mosaic/src/commands/gateway/recover-token.spec.ts

@@ -0,0 +1,176 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+
+vi.mock('../../auth.js', () => ({
+  loadSession: vi.fn(),
+  validateSession: vi.fn(),
+  signIn: vi.fn(),
+  saveSession: vi.fn(),
+}));
+
+vi.mock('./daemon.js', () => ({
+  readMeta: vi.fn(),
+  writeMeta: vi.fn(),
+}));
+
+vi.mock('./login.js', () => ({
+  getGatewayUrl: vi.fn().mockReturnValue('http://localhost:14242'),
+}));
+
+// Mock readline so tests don't block on stdin
+vi.mock('node:readline', () => ({
+  createInterface: vi.fn().mockReturnValue({
+    question: vi.fn((_q: string, cb: (a: string) => void) => cb('test-input')),
+    close: vi.fn(),
+  }),
+}));
+
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+import { runRecoverToken, ensureSession } from './token-ops.js';
+import { loadSession, validateSession, signIn, saveSession } from '../../auth.js';
+import { readMeta, writeMeta } from './daemon.js';
+
+const mockLoadSession = vi.mocked(loadSession);
+const mockValidateSession = vi.mocked(validateSession);
+const mockSignIn = vi.mocked(signIn);
+const mockSaveSession = vi.mocked(saveSession);
+const mockReadMeta = vi.mocked(readMeta);
+const mockWriteMeta = vi.mocked(writeMeta);
+
+const baseUrl = 'http://localhost:14242';
+const fakeCookie = 'better-auth.session_token=sess123';
+const fakeToken = {
+  id: 'tok-1',
+  label: 'CLI recovery token (2026-04-04 12:00)',
+  plaintext: 'abcdef1234567890',
+};
+const fakeMeta = {
+  version: '1.0.0',
+  installedAt: '',
+  entryPoint: '',
+  host: 'localhost',
+  port: 14242,
+};
+
+describe('ensureSession', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('returns cookie from stored session when valid', async () => {
+    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
+    mockValidateSession.mockResolvedValueOnce(true);
+
+    const cookie = await ensureSession(baseUrl);
+    expect(cookie).toBe(fakeCookie);
+    expect(mockSignIn).not.toHaveBeenCalled();
+  });
+
+  it('prompts for credentials and signs in when stored session is invalid', async () => {
+    mockLoadSession.mockReturnValueOnce({ cookie: 'old-cookie', userId: 'u1', email: 'a@b.com' });
+    mockValidateSession.mockResolvedValueOnce(false);
+    const newAuth = { cookie: fakeCookie, userId: 'u2', email: 'a@b.com' };
+    mockSignIn.mockResolvedValueOnce(newAuth);
+
+    const cookie = await ensureSession(baseUrl);
+    expect(cookie).toBe(fakeCookie);
+    expect(mockSaveSession).toHaveBeenCalledWith(baseUrl, newAuth);
+  });
+
+  it('prompts for credentials when no session exists', async () => {
+    mockLoadSession.mockReturnValueOnce(null);
+    const newAuth = { cookie: fakeCookie, userId: 'u2', email: 'a@b.com' };
+    mockSignIn.mockResolvedValueOnce(newAuth);
+
+    const cookie = await ensureSession(baseUrl);
+    expect(cookie).toBe(fakeCookie);
+    expect(mockSignIn).toHaveBeenCalled();
+  });
+
+  it('exits non-zero when signIn fails', async () => {
+    mockLoadSession.mockReturnValueOnce(null);
+    mockSignIn.mockRejectedValueOnce(new Error('Sign-in failed (401): bad creds'));
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+    const consoleErrorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+
+    await expect(ensureSession(baseUrl)).rejects.toThrow('process.exit(2)');
+    expect(processExitSpy).toHaveBeenCalledWith(2);
+
+    processExitSpy.mockRestore();
+    consoleErrorSpy.mockRestore();
+  });
+});
+
+describe('runRecoverToken', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  it('prompts for login, mints a token, and persists it when no session exists', async () => {
+    mockLoadSession.mockReturnValueOnce(null);
+    const newAuth = { cookie: fakeCookie, userId: 'u2', email: 'admin@test.com' };
+    mockSignIn.mockResolvedValueOnce(newAuth);
+    mockReadMeta.mockReturnValue(fakeMeta);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => fakeToken,
+    });
+
+    await runRecoverToken();
+
+    expect(mockSignIn).toHaveBeenCalled();
+    expect(mockFetch).toHaveBeenCalledWith(
+      `${baseUrl}/api/admin/tokens`,
+      expect.objectContaining({ method: 'POST' }),
+    );
+    expect(mockWriteMeta).toHaveBeenCalledWith(
+      expect.objectContaining({ adminToken: fakeToken.plaintext }),
+    );
+  });
+
+  it('skips login when a valid session exists and mints a recovery token', async () => {
+    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
+    mockValidateSession.mockResolvedValueOnce(true);
+    mockReadMeta.mockReturnValue(fakeMeta);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => fakeToken,
+    });
+
+    await runRecoverToken();
+
+    expect(mockSignIn).not.toHaveBeenCalled();
+    expect(mockWriteMeta).toHaveBeenCalledWith(
+      expect.objectContaining({ adminToken: fakeToken.plaintext }),
+    );
+  });
+
+  it('uses label containing "recovery token"', async () => {
+    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
+    mockValidateSession.mockResolvedValueOnce(true);
+    mockReadMeta.mockReturnValue(fakeMeta);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => fakeToken,
+    });
+
+    await runRecoverToken();
+
+    const call = mockFetch.mock.calls[0] as [string, RequestInit];
+    const body = JSON.parse(call[1].body as string) as { label: string };
+    expect(body.label).toMatch(/CLI recovery token/);
+  });
+});

packages/mosaic/src/commands/gateway/rotate-token.spec.ts

@@ -0,0 +1,205 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+
+// ─── Mocks ──────────────────────────────────────────────────────────────────
+
+vi.mock('../../auth.js', () => ({
+  loadSession: vi.fn(),
+  validateSession: vi.fn(),
+  signIn: vi.fn(),
+  saveSession: vi.fn(),
+}));
+
+vi.mock('./daemon.js', () => ({
+  readMeta: vi.fn(),
+  writeMeta: vi.fn(),
+}));
+
+vi.mock('./login.js', () => ({
+  getGatewayUrl: vi.fn().mockReturnValue('http://localhost:14242'),
+}));
+
+// Mock global fetch
+const mockFetch = vi.fn();
+vi.stubGlobal('fetch', mockFetch);
+
+import { runRotateToken, mintAdminToken, persistToken } from './token-ops.js';
+import { loadSession, validateSession } from '../../auth.js';
+import { readMeta, writeMeta } from './daemon.js';
+
+const mockLoadSession = vi.mocked(loadSession);
+const mockValidateSession = vi.mocked(validateSession);
+const mockReadMeta = vi.mocked(readMeta);
+const mockWriteMeta = vi.mocked(writeMeta);
+
+const baseUrl = 'http://localhost:14242';
+const fakeCookie = 'better-auth.session_token=sess123';
+const fakeToken = {
+  id: 'tok-1',
+  label: 'CLI rotated token (2026-04-04)',
+  plaintext: 'abcdef1234567890',
+};
+const fakeMeta = {
+  version: '1.0.0',
+  installedAt: '',
+  entryPoint: '',
+  host: 'localhost',
+  port: 14242,
+};
+
+describe('mintAdminToken', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('calls the admin tokens endpoint with the session cookie and returns the token', async () => {
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => fakeToken,
+    });
+
+    const result = await mintAdminToken(baseUrl, fakeCookie, fakeToken.label);
+
+    expect(mockFetch).toHaveBeenCalledWith(
+      `${baseUrl}/api/admin/tokens`,
+      expect.objectContaining({
+        method: 'POST',
+        headers: expect.objectContaining({ Cookie: fakeCookie }),
+      }),
+    );
+    expect(result).toEqual(fakeToken);
+  });
+
+  it('exits 2 on 401 from the server', async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 401, text: async () => 'Unauthorized' });
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+
+    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(2)');
+    expect(processExitSpy).toHaveBeenCalledWith(2);
+    processExitSpy.mockRestore();
+  });
+
+  it('exits 2 on 403 from the server', async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 403, text: async () => 'Forbidden' });
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+
+    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(2)');
+    expect(processExitSpy).toHaveBeenCalledWith(2);
+    processExitSpy.mockRestore();
+  });
+
+  it('exits 3 on other non-ok status', async () => {
+    mockFetch.mockResolvedValueOnce({ ok: false, status: 500, text: async () => 'Internal Error' });
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+
+    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(3)');
+    expect(processExitSpy).toHaveBeenCalledWith(3);
+    processExitSpy.mockRestore();
+  });
+
+  it('exits 1 on network error', async () => {
+    mockFetch.mockRejectedValueOnce(new Error('connection refused'));
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+
+    await expect(mintAdminToken(baseUrl, fakeCookie, 'label')).rejects.toThrow('process.exit(1)');
+    expect(processExitSpy).toHaveBeenCalledWith(1);
+    processExitSpy.mockRestore();
+  });
+});
+
+describe('persistToken', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  it('writes the new token to meta.json', () => {
+    mockReadMeta.mockReturnValueOnce(fakeMeta);
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    persistToken(baseUrl, fakeToken);
+
+    expect(mockWriteMeta).toHaveBeenCalledWith(
+      expect.objectContaining({ adminToken: fakeToken.plaintext }),
+    );
+    consoleSpy.mockRestore();
+  });
+
+  it('prints a masked preview of the token', () => {
+    mockReadMeta.mockReturnValueOnce(fakeMeta);
+    const consoleSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+
+    persistToken(baseUrl, fakeToken);
+
+    const allOutput = consoleSpy.mock.calls.map((c) => c.join(' ')).join('\n');
+    expect(allOutput).toContain('abcdef12...');
+    consoleSpy.mockRestore();
+  });
+});
+
+describe('runRotateToken', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+    vi.spyOn(console, 'error').mockImplementation(() => {});
+    vi.spyOn(console, 'log').mockImplementation(() => {});
+  });
+
+  it('exits 2 when there is no stored session', async () => {
+    mockLoadSession.mockReturnValueOnce(null);
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+
+    await expect(runRotateToken()).rejects.toThrow('process.exit(2)');
+    expect(processExitSpy).toHaveBeenCalledWith(2);
+    processExitSpy.mockRestore();
+  });
+
+  it('exits 2 when session is invalid', async () => {
+    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
+    mockValidateSession.mockResolvedValueOnce(false);
+    const processExitSpy = vi
+      .spyOn(process, 'exit')
+      .mockImplementation((_code?: number | string | null | undefined) => {
+        throw new Error(`process.exit(${String(_code)})`);
+      });
+
+    await expect(runRotateToken()).rejects.toThrow('process.exit(2)');
+    expect(processExitSpy).toHaveBeenCalledWith(2);
+    processExitSpy.mockRestore();
+  });
+
+  it('mints and persists a new token when session is valid', async () => {
+    mockLoadSession.mockReturnValueOnce({ cookie: fakeCookie, userId: 'u1', email: 'a@b.com' });
+    mockValidateSession.mockResolvedValueOnce(true);
+    mockReadMeta.mockReturnValue(fakeMeta);
+    mockFetch.mockResolvedValueOnce({
+      ok: true,
+      status: 200,
+      json: async () => fakeToken,
+    });
+
+    await runRotateToken();
+
+    expect(mockWriteMeta).toHaveBeenCalledWith(
+      expect.objectContaining({ adminToken: fakeToken.plaintext }),
+    );
+  });
+});

packages/mosaic/src/commands/gateway/token-ops.ts

@@ -0,0 +1,149 @@
+import { createInterface } from 'node:readline';
+import { loadSession, validateSession, signIn, saveSession } from '../../auth.js';
+import { readMeta, writeMeta } from './daemon.js';
+import { getGatewayUrl } from './login.js';
+
+interface MintedToken {
+  id: string;
+  label: string;
+  plaintext: string;
+}
+
+/**
+ * Call POST /api/admin/tokens with the session cookie and return the minted token.
+ * Exits the process on network or auth errors.
+ */
+export async function mintAdminToken(
+  gatewayUrl: string,
+  cookie: string,
+  label: string,
+): Promise<MintedToken> {
+  let res: Response;
+  try {
+    res = await fetch(`${gatewayUrl}/api/admin/tokens`, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        Cookie: cookie,
+        Origin: gatewayUrl,
+      },
+      body: JSON.stringify({ label, scope: 'admin' }),
+    });
+  } catch (err) {
+    console.error(
+      `Could not reach gateway at ${gatewayUrl}: ${err instanceof Error ? err.message : String(err)}`,
+    );
+    process.exit(1);
+  }
+
+  if (res.status === 401 || res.status === 403) {
+    console.error(
+      `Session rejected by the gateway (${res.status.toString()}) — your session may be expired.`,
+    );
+    console.error('Run: mosaic gateway login');
+    process.exit(2);
+  }
+
+  if (!res.ok) {
+    const body = await res.text().catch(() => '');
+    console.error(
+      `Gateway rejected token creation (${res.status.toString()}): ${body.slice(0, 200)}`,
+    );
+    process.exit(3);
+  }
+
+  const data = (await res.json()) as { id: string; label: string; plaintext: string };
+  return { id: data.id, label: data.label, plaintext: data.plaintext };
+}
+
+/**
+ * Persist the new token into meta.json and print the confirmation banner.
+ */
+export function persistToken(gatewayUrl: string, minted: MintedToken): void {
+  const meta = readMeta() ?? {
+    version: 'unknown',
+    installedAt: new Date().toISOString(),
+    entryPoint: '',
+    host: new URL(gatewayUrl).hostname,
+    port: parseInt(new URL(gatewayUrl).port || '14242', 10),
+  };
+
+  writeMeta({ ...meta, adminToken: minted.plaintext });
+
+  const preview = `${minted.plaintext.slice(0, 8)}...`;
+  console.log();
+  console.log(`Token minted:  ${minted.label}`);
+  console.log(`Preview:       ${preview}`);
+  console.log('Token saved to meta.json. Use it with admin endpoints.');
+}
+
+/**
+ * Require a valid session for the given gateway URL.
+ * Returns the session cookie or exits if not authenticated.
+ */
+export async function requireSession(gatewayUrl: string): Promise<string> {
+  const session = loadSession(gatewayUrl);
+  if (session) {
+    const valid = await validateSession(gatewayUrl, session.cookie);
+    if (valid) return session.cookie;
+  }
+  console.error('Not signed in or session expired.');
+  console.error('Run: mosaic gateway login');
+  process.exit(2);
+}
+
+/**
+ * Ensure a valid session for the gateway, prompting for credentials if needed.
+ * On sign-in failure, prints the error and exits non-zero.
+ * Returns the session cookie.
+ */
+export async function ensureSession(gatewayUrl: string): Promise<string> {
+  // Try the stored session first
+  const session = loadSession(gatewayUrl);
+  if (session) {
+    const valid = await validateSession(gatewayUrl, session.cookie);
+    if (valid) return session.cookie;
+    console.log('Stored session is invalid or expired. Please sign in again.');
+  } else {
+    console.log(`No session found for ${gatewayUrl}. Please sign in.`);
+  }
+
+  // Prompt for credentials
+  const rl = createInterface({ input: process.stdin, output: process.stdout });
+  const ask = (q: string): Promise<string> => new Promise((resolve) => rl.question(q, resolve));
+
+  const email = (await ask('Email: ')).trim();
+  const password = (await ask('Password: ')).trim();
+  rl.close();
+
+  const auth = await signIn(gatewayUrl, email, password).catch((err: unknown) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(2);
+  });
+
+  saveSession(gatewayUrl, auth);
+  console.log(`Signed in as ${auth.email}`);
+  return auth.cookie;
+}
+
+/**
+ * `mosaic gateway config rotate-token` — requires an existing valid session.
+ */
+export async function runRotateToken(gatewayUrl?: string): Promise<void> {
+  const url = getGatewayUrl(gatewayUrl);
+  const cookie = await requireSession(url);
+  const label = `CLI rotated token (${new Date().toISOString().slice(0, 10)})`;
+  const minted = await mintAdminToken(url, cookie, label);
+  persistToken(url, minted);
+}
+
+/**
+ * `mosaic gateway config recover-token` — prompts for login if no session exists.
+ */
+export async function runRecoverToken(gatewayUrl?: string): Promise<void> {
+  const url = getGatewayUrl(gatewayUrl);
+  const cookie = await ensureSession(url);
+  const label = `CLI recovery token (${new Date().toISOString().slice(0, 16).replace('T', ' ')})`;
+  const minted = await mintAdminToken(url, cookie, label);
+  persistToken(url, minted);
+}

packages/mosaic/src/commands/mission.ts

@@ -47,6 +47,7 @@ export function registerMissionCommand(program: Command) {
     .option('--update <idOrName>', 'Update a mission')
     .option('--project <idOrName>', 'Scope to project')
     .argument('[id]', 'Show mission detail by ID')
+    .configureHelp({ sortSubcommands: true })
     .action(
       async (
         id: string | undefined,

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

@@ -1,6 +1,16 @@
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { FileConfigAdapter } from './file-adapter.js';
 
+/** Supported top-level config sections for dotted-key access. */
+export type ConfigSection = 'soul' | 'user' | 'tools';
+
+/** A resolved view of all config sections, keyed by section name. */
+export interface ResolvedConfig {
+  soul: SoulConfig;
+  user: UserConfig;
+  tools: ToolsConfig;
+}
+
 /**
  * ConfigService interface — abstracts config read/write operations.
  * Currently backed by FileConfigAdapter (writes .md files from templates).
@@ -16,6 +26,35 @@ export interface ConfigService {
   writeTools(config: ToolsConfig): Promise<void>;
 
   syncFramework(action: InstallAction): Promise<void>;
+
+  /**
+   * Return the resolved (merged) config across all sections.
+   */
+  readAll(): Promise<ResolvedConfig>;
+
+  /**
+   * Read a single value by dotted key (e.g. "soul.agentName").
+   * Returns undefined if the key doesn't exist.
+   */
+  getValue(dottedKey: string): Promise<unknown>;
+
+  /**
+   * Set a single value by dotted key (e.g. "soul.agentName") and persist.
+   * Returns the previous value (or undefined).
+   */
+  setValue(dottedKey: string, value: string): Promise<unknown>;
+
+  /**
+   * Return the filesystem path for a given config section file.
+   * When no section is provided, returns the mosaicHome directory.
+   */
+  getConfigPath(section?: ConfigSection): string;
+
+  /**
+   * Returns true if the mosaicHome directory exists and at least one
+   * config file (SOUL.md, USER.md, TOOLS.md) is present.
+   */
+  isInitialized(): boolean;
 }
 
 export function createConfigService(mosaicHome: string, sourceDir: string): ConfigService {

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

@@ -1,6 +1,6 @@
 import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-import type { ConfigService } from './config-service.js';
+import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js';
 import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js';
 import { soulSchema, userSchema, toolsSchema } from './schemas.js';
 import { renderTemplate } from '../template/engine.js';
@@ -159,6 +159,73 @@ export class FileConfigAdapter implements ConfigService {
     }
   }
 
+  async readAll(): Promise<ResolvedConfig> {
+    const [soul, user, tools] = await Promise.all([
+      this.readSoul(),
+      this.readUser(),
+      this.readTools(),
+    ]);
+    return { soul, user, tools };
+  }
+
+  async getValue(dottedKey: string): Promise<unknown> {
+    const parts = dottedKey.split('.');
+    const section = parts[0] ?? '';
+    const field = parts.slice(1).join('.');
+    const config = await this.readAll();
+    if (!this.isValidSection(section)) return undefined;
+    const sectionData = config[section as ConfigSection] as Record<string, unknown>;
+    return field ? sectionData[field] : sectionData;
+  }
+
+  async setValue(dottedKey: string, value: string): Promise<unknown> {
+    const parts = dottedKey.split('.');
+    const section = parts[0] ?? '';
+    const field = parts.slice(1).join('.');
+    if (!this.isValidSection(section) || !field) {
+      throw new Error(
+        `Invalid key "${dottedKey}". Use format <section>.<field> (e.g. soul.agentName).`,
+      );
+    }
+
+    const previous = await this.getValue(dottedKey);
+
+    if (section === 'soul') {
+      const current = await this.readSoul();
+      await this.writeSoul({ ...current, [field]: value });
+    } else if (section === 'user') {
+      const current = await this.readUser();
+      await this.writeUser({ ...current, [field]: value });
+    } else {
+      const current = await this.readTools();
+      await this.writeTools({ ...current, [field]: value });
+    }
+
+    return previous;
+  }
+
+  getConfigPath(section?: ConfigSection): string {
+    if (!section) return this.mosaicHome;
+    const fileMap: Record<ConfigSection, string> = {
+      soul: join(this.mosaicHome, 'SOUL.md'),
+      user: join(this.mosaicHome, 'USER.md'),
+      tools: join(this.mosaicHome, 'TOOLS.md'),
+    };
+    return fileMap[section];
+  }
+
+  isInitialized(): boolean {
+    return (
+      existsSync(join(this.mosaicHome, 'SOUL.md')) ||
+      existsSync(join(this.mosaicHome, 'USER.md')) ||
+      existsSync(join(this.mosaicHome, 'TOOLS.md'))
+    );
+  }
+
+  private isValidSection(s: string): s is ConfigSection {
+    return s === 'soul' || s === 'user' || s === 'tools';
+  }
+
   /**
    * Look for template in source dir first, then mosaic home.
    */

packages/storage/package.json

@@ -23,7 +23,8 @@
   "dependencies": {
     "@electric-sql/pglite": "^0.2.17",
     "@mosaicstack/db": "workspace:^",
-    "@mosaicstack/types": "workspace:*"
+    "@mosaicstack/types": "workspace:*",
+    "commander": "^13.0.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0",

packages/storage/src/cli.spec.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from 'vitest';
+import { Command } from 'commander';
+import { registerStorageCommand } from './cli.js';
+
+describe('registerStorageCommand', () => {
+  function buildProgram(): Command {
+    const program = new Command();
+    program.exitOverride(); // prevent process.exit in tests
+    registerStorageCommand(program);
+    return program;
+  }
+
+  it('registers a "storage" command on the parent', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage');
+    expect(storageCmd).toBeDefined();
+  });
+
+  it('registers "storage status" subcommand', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const statusCmd = storageCmd.commands.find((c) => c.name() === 'status');
+    expect(statusCmd).toBeDefined();
+  });
+
+  it('registers "storage tier" subcommand group', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const tierCmd = storageCmd.commands.find((c) => c.name() === 'tier');
+    expect(tierCmd).toBeDefined();
+  });
+
+  it('registers "storage tier show" subcommand', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const tierCmd = storageCmd.commands.find((c) => c.name() === 'tier')!;
+    const showCmd = tierCmd.commands.find((c) => c.name() === 'show');
+    expect(showCmd).toBeDefined();
+  });
+
+  it('registers "storage tier switch" subcommand', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const tierCmd = storageCmd.commands.find((c) => c.name() === 'tier')!;
+    const switchCmd = tierCmd.commands.find((c) => c.name() === 'switch');
+    expect(switchCmd).toBeDefined();
+  });
+
+  it('registers "storage export" subcommand', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const exportCmd = storageCmd.commands.find((c) => c.name() === 'export');
+    expect(exportCmd).toBeDefined();
+  });
+
+  it('registers "storage import" subcommand', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const importCmd = storageCmd.commands.find((c) => c.name() === 'import');
+    expect(importCmd).toBeDefined();
+  });
+
+  it('registers "storage migrate" subcommand', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const migrateCmd = storageCmd.commands.find((c) => c.name() === 'migrate');
+    expect(migrateCmd).toBeDefined();
+  });
+
+  it('has all required subcommands in a single assertion', () => {
+    const program = buildProgram();
+    const storageCmd = program.commands.find((c) => c.name() === 'storage')!;
+    const topLevel = storageCmd.commands.map((c) => c.name());
+    expect(topLevel).toContain('status');
+    expect(topLevel).toContain('tier');
+    expect(topLevel).toContain('export');
+    expect(topLevel).toContain('import');
+    expect(topLevel).toContain('migrate');
+
+    const tierCmd = storageCmd.commands.find((c) => c.name() === 'tier')!;
+    const tierSubcmds = tierCmd.commands.map((c) => c.name());
+    expect(tierSubcmds).toContain('show');
+    expect(tierSubcmds).toContain('switch');
+  });
+});

packages/storage/src/cli.ts

@@ -0,0 +1,256 @@
+import type { Command } from 'commander';
+
+/**
+ * Reads the DATABASE_URL environment variable and redacts the password portion.
+ */
+function redactedConnectionString(): string | null {
+  const url = process.env['DATABASE_URL'];
+  if (!url) return null;
+  try {
+    const parsed = new URL(url);
+    if (parsed.password) {
+      parsed.password = '***';
+    }
+    return parsed.toString();
+  } catch {
+    // Not a valid URL — redact anything that looks like :password@
+    return url.replace(/:([^@/]+)@/, ':***@');
+  }
+}
+
+/**
+ * Determine the active storage tier from the environment.
+ * Looks at DATABASE_URL; if absent or set to a pglite path, treats tier as pglite.
+ */
+function activeTier(): 'postgres' | 'pglite' {
+  const url = process.env['DATABASE_URL'];
+  if (url && url.startsWith('postgres')) return 'postgres';
+  return 'pglite';
+}
+
+/**
+ * Return a human-readable config source description.
+ */
+function configSource(): string {
+  if (process.env['DATABASE_URL']) return 'env:DATABASE_URL';
+  const pgliteDir = process.env['PGLITE_DATA_DIR'];
+  if (pgliteDir) return `env:PGLITE_DATA_DIR (${pgliteDir})`;
+  return 'default (no DATABASE_URL set)';
+}
+
+/**
+ * Register storage subcommands on an existing Commander program.
+ * Follows the registerQualityRails pattern — uses the caller's Command
+ * instance to avoid cross-package Commander version mismatches.
+ */
+export function registerStorageCommand(parent: Command): void {
+  const storage = parent
+    .command('storage')
+    .description('Inspect and manage Mosaic storage configuration');
+
+  // ── storage status ───────────────────────────────────────────────────────
+
+  storage
+    .command('status')
+    .description('Show the configured storage tier and whether the adapter is reachable')
+    .action(async () => {
+      const tier = activeTier();
+      const source = configSource();
+      const connStr = tier === 'postgres' ? redactedConnectionString() : null;
+
+      console.log(`[storage] tier: ${tier}`);
+      console.log(`[storage] config source: ${source}`);
+
+      if (tier === 'postgres' && connStr) {
+        console.log(`[storage] connection: ${connStr}`);
+        try {
+          const { createDb, sql } = await import('@mosaicstack/db');
+          const url = process.env['DATABASE_URL'] ?? '';
+          const handle = createDb(url);
+          await handle.db.execute(sql`SELECT 1`);
+          await handle.close();
+          console.log('[storage] reachable: yes');
+        } catch (err) {
+          console.log(
+            `[storage] reachable: no (${err instanceof Error ? err.message : String(err)})`,
+          );
+        }
+      } else {
+        const dataDir = process.env['PGLITE_DATA_DIR'] ?? ':memory:';
+        console.log(`[storage] data dir: ${dataDir}`);
+        console.log('[storage] reachable: pglite is always local — no network check needed');
+      }
+    });
+
+  // ── storage tier ─────────────────────────────────────────────────────────
+
+  const tier = storage.command('tier').description('Inspect or switch the storage tier');
+
+  tier
+    .command('show')
+    .description('Print the active storage tier and its config source')
+    .action(() => {
+      const activeTierValue = activeTier();
+      const source = configSource();
+      console.log(`[storage] active tier: ${activeTierValue}`);
+      console.log(`[storage] config source: ${source}`);
+    });
+
+  tier
+    .command('switch <tier>')
+    .description('Switch storage tier between pglite and postgres')
+    .action((newTier: string) => {
+      const validTiers = ['pglite', 'postgres'];
+      if (!validTiers.includes(newTier)) {
+        console.error(
+          `[storage] unknown tier: ${newTier}. Valid options: ${validTiers.join(', ')}`,
+        );
+        process.exitCode = 1;
+        return;
+      }
+
+      console.log(`[storage] tier switch requested: ${newTier}`);
+      console.log('');
+      console.log('Mosaic storage tier is controlled by environment variables.');
+      console.log('Automatic config-file mutation is not supported — set the variable manually.');
+      console.log('');
+
+      if (newTier === 'postgres') {
+        console.log('To switch to postgres:');
+        console.log('  1. Set DATABASE_URL in your environment or .env file:');
+        console.log('       export DATABASE_URL="postgresql://user:pass@localhost:5432/mosaic"');
+        console.log('  2. Run migrations:');
+        console.log('       pnpm --filter @mosaicstack/db db:migrate');
+        console.log('  3. Restart the gateway.');
+      } else {
+        console.log('To switch to pglite:');
+        console.log('  1. Unset DATABASE_URL (or set it to a pglite path):');
+        console.log('       unset DATABASE_URL');
+        console.log('       # optionally: export PGLITE_DATA_DIR=/path/to/pglite/data');
+        console.log('  2. Restart the gateway.');
+        console.log('  Note: pglite uses an in-process database — no migrations needed.');
+      }
+    });
+
+  // ── storage export ───────────────────────────────────────────────────────
+
+  storage
+    .command('export <path>')
+    .description('Dump the active storage contents to a file')
+    .action((outputPath: string) => {
+      const currentTier = activeTier();
+
+      if (currentTier === 'postgres') {
+        const redacted = redactedConnectionString() ?? '<DATABASE_URL>';
+        console.log('[storage] export for postgres tier');
+        console.log('');
+        console.log('postgres export is not yet wired in the CLI — use pg_dump directly:');
+        console.log('');
+        console.log(`  pg_dump "${redacted}" > ${outputPath}`);
+        console.log('');
+        console.log('Or with Docker:');
+        console.log(
+          `  docker exec <postgres-container> pg_dump -U <user> <dbname> > ${outputPath}`,
+        );
+        process.exitCode = 0;
+      } else {
+        const dataDir = process.env['PGLITE_DATA_DIR'];
+        console.log('[storage] export for pglite tier');
+        console.log('');
+        console.log(
+          'pglite export is not yet wired in the CLI — copy the data directory directly:',
+        );
+        console.log('');
+        if (dataDir) {
+          console.log(`  cp -r ${dataDir} ${outputPath}`);
+        } else {
+          console.log(
+            '  PGLITE_DATA_DIR is not set; the database is in-memory and cannot be exported.',
+          );
+          console.log('  Set PGLITE_DATA_DIR to a persistent path before running export.');
+        }
+        process.exitCode = 0;
+      }
+    });
+
+  // ── storage import ───────────────────────────────────────────────────────
+
+  storage
+    .command('import <path>')
+    .description('Restore storage contents from a previously exported file')
+    .action((inputPath: string) => {
+      const currentTier = activeTier();
+
+      if (currentTier === 'postgres') {
+        const redacted = redactedConnectionString() ?? '<DATABASE_URL>';
+        console.log('[storage] import for postgres tier');
+        console.log('');
+        console.log('postgres import is not yet wired in the CLI — use psql directly:');
+        console.log('');
+        console.log(`  psql "${redacted}" < ${inputPath}`);
+        process.exitCode = 0;
+      } else {
+        const dataDir = process.env['PGLITE_DATA_DIR'];
+        console.log('[storage] import for pglite tier');
+        console.log('');
+        console.log(
+          'pglite import is not yet wired in the CLI — restore the data directory directly:',
+        );
+        console.log('');
+        if (dataDir) {
+          console.log(`  rm -rf ${dataDir} && cp -r ${inputPath} ${dataDir}`);
+          console.log('  Then restart the gateway.');
+        } else {
+          console.log(
+            '  PGLITE_DATA_DIR is not set; set it to a persistent path before running import.',
+          );
+        }
+        process.exitCode = 0;
+      }
+    });
+
+  // ── storage migrate ──────────────────────────────────────────────────────
+
+  storage
+    .command('migrate')
+    .description(
+      'Run database migrations (thin wrapper — delegates to pnpm db:migrate or prints the command)',
+    )
+    .option('--run', 'Actually execute the migration command via shell')
+    .action(async (opts: { run?: boolean }) => {
+      const currentTier = activeTier();
+
+      if (currentTier === 'pglite') {
+        console.log('[storage] pglite tier detected');
+        console.log(
+          'pglite runs schema setup automatically on first connection via adapter.migrate().',
+        );
+        console.log('No separate migration step is required.');
+        return;
+      }
+
+      const migrateCmd = 'pnpm --filter @mosaicstack/db db:migrate';
+      console.log('[storage] postgres tier detected');
+      console.log(`Migration command: ${migrateCmd}`);
+      console.log('');
+
+      if (opts.run) {
+        console.log('Running migrations...');
+        const { execSync } = await import('node:child_process');
+        try {
+          execSync(migrateCmd, { stdio: 'inherit' });
+          console.log('[storage] migrations complete.');
+        } catch (err) {
+          console.error(
+            `[storage] migration failed: ${err instanceof Error ? err.message : String(err)}`,
+          );
+          process.exitCode = 1;
+        }
+      } else {
+        console.log('To run migrations, execute:');
+        console.log(`  ${migrateCmd}`);
+        console.log('');
+        console.log('Or pass --run to have this command execute it for you.');
+      }
+    });
+}

packages/storage/src/index.ts

@@ -2,6 +2,7 @@ export type { StorageAdapter, StorageConfig } from './types.js';
 export { createStorageAdapter, registerStorageAdapter } from './factory.js';
 export { PostgresAdapter } from './adapters/postgres.js';
 export { PgliteAdapter } from './adapters/pglite.js';
+export { registerStorageCommand } from './cli.js';
 
 import { registerStorageAdapter } from './factory.js';
 import { PostgresAdapter } from './adapters/postgres.js';

pnpm-lock.yaml

@@ -294,6 +294,9 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
+      commander:
+        specifier: ^13.0.0
+        version: 13.1.0
     devDependencies:
       typescript:
         specifier: ^5.8.0
@@ -382,9 +385,6 @@ importers:
       '@mosaicstack/macp':
         specifier: workspace:*
         version: link:../macp
-      commander:
-        specifier: ^13.0.0
-        version: 13.1.0
     devDependencies:
       '@types/node':
         specifier: ^22.0.0
@@ -404,9 +404,6 @@ importers:
       '@mosaicstack/db':
         specifier: workspace:*
         version: link:../db
-      commander:
-        specifier: ^13.0.0
-        version: 13.1.0
       drizzle-orm:
         specifier: ^0.45.1
         version: 0.45.1(@electric-sql/pglite@0.2.17)(@opentelemetry/api@1.9.0)(@types/better-sqlite3@7.6.13)(@types/pg@8.15.6)(better-sqlite3@12.8.0)(kysely@0.28.11)(postgres@3.4.8)
@@ -467,6 +464,9 @@ importers:
       '@clack/prompts':
         specifier: ^0.9.1
         version: 0.9.1
+      '@mosaicstack/brain':
+        specifier: workspace:*
+        version: link:../brain
       '@mosaicstack/config':
         specifier: workspace:*
         version: link:../config
@@ -476,12 +476,21 @@ importers:
       '@mosaicstack/macp':
         specifier: workspace:*
         version: link:../macp
+      '@mosaicstack/memory':
+        specifier: workspace:*
+        version: link:../memory
       '@mosaicstack/prdy':
         specifier: workspace:*
         version: link:../prdy
       '@mosaicstack/quality-rails':
         specifier: workspace:*
         version: link:../quality-rails
+      '@mosaicstack/queue':
+        specifier: workspace:*
+        version: link:../queue
+      '@mosaicstack/storage':
+        specifier: workspace:*
+        version: link:../storage
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
@@ -603,6 +612,9 @@ importers:
       '@mosaicstack/types':
         specifier: workspace:*
         version: link:../types
+      commander:
+        specifier: ^13.0.0
+        version: 13.1.0
     devDependencies:
       typescript:
         specifier: ^5.8.0
@@ -650,10 +662,10 @@ importers:
     dependencies:
       '@mariozechner/pi-agent-core':
         specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
       '@mariozechner/pi-ai':
         specifier: ^0.63.1
-        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
+        version: 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
       '@sinclair/typebox':
         specifier: ^0.34.41
         version: 0.34.48
@@ -7028,12 +7040,6 @@ snapshots:
       '@jridgewell/gen-mapping': 0.3.13
       '@jridgewell/trace-mapping': 0.3.31
 
-  '@anthropic-ai/sdk@0.73.0(zod@3.25.76)':
-    dependencies:
-      json-schema-to-ts: 3.1.1
-    optionalDependencies:
-      zod: 3.25.76
-
   '@anthropic-ai/sdk@0.73.0(zod@4.3.6)':
     dependencies:
       json-schema-to-ts: 3.1.1
@@ -8375,18 +8381,6 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
-    dependencies:
-      '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)
-    transitivePeerDependencies:
-      - '@modelcontextprotocol/sdk'
-      - aws-crt
-      - bufferutil
-      - supports-color
-      - utf-8-validate
-      - ws
-      - zod
-
   '@mariozechner/pi-agent-core@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
     dependencies:
       '@mariozechner/pi-ai': 0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)
@@ -8435,30 +8429,6 @@ snapshots:
       - ws
       - zod
 
-  '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@3.25.76)':
-    dependencies:
-      '@anthropic-ai/sdk': 0.73.0(zod@3.25.76)
-      '@aws-sdk/client-bedrock-runtime': 3.1008.0
-      '@google/genai': 1.45.0(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))
-      '@mistralai/mistralai': 1.14.1
-      '@sinclair/typebox': 0.34.48
-      ajv: 8.18.0
-      ajv-formats: 3.0.1(ajv@8.18.0)
-      chalk: 5.6.2
-      openai: 6.26.0(ws@8.20.0)(zod@3.25.76)
-      partial-json: 0.1.7
-      proxy-agent: 6.5.0
-      undici: 7.24.3
-      zod-to-json-schema: 3.25.1(zod@3.25.76)
-    transitivePeerDependencies:
-      - '@modelcontextprotocol/sdk'
-      - aws-crt
-      - bufferutil
-      - supports-color
-      - utf-8-validate
-      - ws
-      - zod
-
   '@mariozechner/pi-ai@0.63.2(@modelcontextprotocol/sdk@1.28.0(zod@4.3.6))(ws@8.20.0)(zod@4.3.6)':
     dependencies:
       '@anthropic-ai/sdk': 0.73.0(zod@4.3.6)
@@ -12834,11 +12804,6 @@ snapshots:
     dependencies:
       mimic-function: 5.0.1
 
-  openai@6.26.0(ws@8.20.0)(zod@3.25.76):
-    optionalDependencies:
-      ws: 8.20.0
-      zod: 3.25.76
-
   openai@6.26.0(ws@8.20.0)(zod@4.3.6):
     optionalDependencies:
       ws: 8.20.0