feat(mosaic): add top-level mosaic config command (CU-04-04, CU-04-05)

Adds `mosaic config` command tree with five subcommands (show, get, set,
edit, path) backed by ConfigService; adds minimal get/set/path/readAll
primitives to ConfigService + FileConfigAdapter. Includes Vitest tests.

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

docs/plans/gateway-token-recovery.md

@@ -0,0 +1,193 @@
+# Gateway Admin Token Recovery — Implementation Plan
+
+**Mission:** `cli-unification-20260404`
+**Task:** `CU-03-01` (planning only — no runtime code changes)
+**Status:** Design locked (Session 1) — BetterAuth cookie-based recovery
+
+---
+
+## 1. Problem Statement
+
+The gateway installer strands operators when the admin user exists but the admin
+API token is missing. Concrete trigger:
+
+- `~/.config/mosaic/gateway/meta.json` was deleted / regenerated.
+- The installer was re-run after a previous successful bootstrap.
+
+Flow today (`packages/mosaic/src/commands/gateway/install.ts:375-400`):
+
+1. `bootstrapFirstUser` hits `GET /api/bootstrap/status`.
+2. Server returns `needsSetup: false` because `users` count > 0.
+3. Installer logs `Admin user already exists — skipping setup. (No admin token on file — sign in via the web UI to manage tokens.)` and returns.
+4. The operator now has:
+   - No token in `meta.json`.
+   - No CLI path to mint a new one (`mosaic gateway <anything>` that needs the token fails).
+   - `POST /api/bootstrap/setup` locked out — it only runs when `users` count is zero (`apps/gateway/src/admin/bootstrap.controller.ts:34-37`).
+   - `POST /api/admin/tokens` gated by `AdminGuard` — requires either a bearer token (which they don't have) or a BetterAuth session (which they don't have in the CLI).
+
+Dead end. The web UI is the only escape hatch today, and for headless installs even that may be inaccessible.
+
+## 2. Design Summary
+
+The BetterAuth session cookie is the authority. The operator runs
+`mosaic gateway login` to sign in with email/password, which persists a session
+cookie via `saveSession` (reusing `packages/mosaic/src/auth.ts`). With a valid
+session, `mosaic gateway config recover-token` (stranded-operator entry point)
+and `mosaic gateway config rotate-token` call the existing authenticated admin
+endpoint `POST /api/admin/tokens` using the cookie, then persist the returned
+plaintext to `meta.json` via `writeMeta`. **No new server endpoints are
+required** — `AdminGuard` already accepts BetterAuth session cookies via its
+`validateSession` path (`apps/gateway/src/admin/admin.guard.ts:90-120`).
+
+## 3. Surface Contract
+
+### 3.1 Server — no changes required
+
+| Endpoint                       | Status          | Notes                                                                                                                    |
+| ------------------------------ | --------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| `POST /api/admin/tokens`       | **Reuse as-is** | `admin-tokens.controller.ts:46-72`. Returns `{ id, label, scope, expiresAt, lastUsedAt, createdAt, plaintext }`.         |
+| `GET  /api/admin/tokens`       | **Reuse**       | Useful for `mosaic gateway config tokens list` follow-on (out of scope for CU-03-01, but trivial once auth path exists). |
+| `DELETE /api/admin/tokens/:id` | **Reuse**       | Used by rotate flow for optional old-token revocation.                                                                   |
+| `POST /api/bootstrap/setup`    | **Unchanged**   | Remains first-user-only; not part of recovery.                                                                           |
+
+`AdminGuard.validateSession` takes BetterAuth cookies from `request.raw.headers`
+via `fromNodeHeaders` and calls `auth.api.getSession({ headers })`. It also
+enforces `role === 'admin'`. This is exactly the path the CLI will hit with
+`Cookie: better-auth.session_token=...`.
+
+**Confirmed feasible** during CU-03-01 investigation.
+
+### 3.2 `mosaic gateway login`
+
+Thin wrapper over the existing top-level `mosaic login`
+(`packages/mosaic/src/cli.ts:42-76`) with gateway-specific defaults pulled from
+`readMeta()`.
+
+| Aspect              | Behavior                                                                                                                        |
+| ------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| Default gateway URL | `http://${meta.host}:${meta.port}` from `readMeta()`, fallback `http://localhost:14242`.                                        |
+| Flow                | Prompt email + password -> `signIn()` -> `saveSession()`.                                                                       |
+| Persistence         | `~/.mosaic/session.json` via existing `saveSession` (7-day expiry).                                                             |
+| Decision            | **Thin wrapper**, not alias. Rationale: defaults differ (reads `meta.json`), and discoverability under `mosaic gateway --help`. |
+| Implementation      | Share the sign-in logic by extracting a small `runLogin(gatewayUrl, email?, password?)` helper; both commands call it.          |
+
+### 3.3 `mosaic gateway config rotate-token`
+
+| Aspect       | Behavior                                                                                                                                                                                                                             |
+| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Precondition | Valid session (via `loadSession` + `validateSession`). On failure, print: "Not signed in — run `mosaic gateway login`" and exit non-zero.                                                                                            |
+| Request      | `POST ${gatewayUrl}/api/admin/tokens` with header `Cookie: <session>`, body `{ label: "CLI token (rotated YYYY-MM-DD)" }`.                                                                                                           |
+| On success   | Read meta via `readMeta()`, set `meta.adminToken = plaintext`, `writeMeta(meta)`. Print the token banner (reuse `printAdminTokenBanner` shape).                                                                                      |
+| Old token    | **Optional `--revoke-old`** flag. When set and a previous `meta.adminToken` existed, call `DELETE /api/admin/tokens/:id` after rotation. Requires listing first to find the id; punt to CU-03-02 decision. Document as nice-to-have. |
+| Exit codes   | `0` success; `1` network error; `2` auth error; `3` server rejection.                                                                                                                                                                |
+
+### 3.4 `mosaic gateway config recover-token`
+
+Superset of `rotate-token` with an inline login nudge — the "stranded operator"
+entry point.
+
+| Step | Action                                                                                                                           |
+| ---- | -------------------------------------------------------------------------------------------------------------------------------- |
+| 1    | `readMeta()` — derive gateway URL. If meta is missing entirely, fall back to `--gateway` flag or default.                        |
+| 2    | `loadSession(gatewayUrl)` then `validateSession`. If either fails, prompt inline: email + password -> `signIn` -> `saveSession`. |
+| 3    | `POST /api/admin/tokens` with cookie, label `"Recovered via CLI YYYY-MM-DDTHH:mm"`.                                              |
+| 4    | Persist plaintext to `meta.json` via `writeMeta`.                                                                                |
+| 5    | Print the token banner and next-steps hints (e.g. `mosaic gateway status`).                                                      |
+| 6    | Exit `0`.                                                                                                                        |
+
+Key property: this command is **runnable with nothing but email+password in hand**.
+It assumes the gateway is up but assumes no prior CLI session state.
+
+### 3.5 File touch list (for CU-03-02..05 execution)
+
+| File                                                  | Change                                                                                     |
+| ----------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `packages/mosaic/src/commands/gateway.ts`             | Register `login`, `config recover-token`, `config rotate-token` subcommands under `gw`.    |
+| `packages/mosaic/src/commands/gateway/config.ts`      | Add `runRecoverToken`, `runRotateToken` handlers; export from module.                      |
+| `packages/mosaic/src/commands/gateway/login.ts` (new) | Thin wrapper calling shared `runLogin` helper with meta-derived default URL.               |
+| `packages/mosaic/src/auth.ts`                         | No change expected. Possibly export a `requireSession(gatewayUrl)` helper (reuse pattern). |
+| `packages/mosaic/src/commands/gateway/install.ts`     | `bootstrapFirstUser` branch: "user exists, no token" -> offer recovery (see Section 4).    |
+
+## 4. Installer Fix (CU-03-06 preview)
+
+Current stranding point is `install.ts:388-395`. The fix:
+
+```
+if (!status.needsSetup) {
+  if (meta.adminToken) {
+    // unchanged — happy path
+  } else {
+    // NEW: prompt "Admin exists but no token on file. Recover now? [Y/n]"
+    // If yes -> call runRecoverToken(gatewayUrl) inline (interactive):
+    //   - prompt email + password
+    //   - signIn -> saveSession
+    //   - POST /api/admin/tokens
+    //   - writeMeta(meta) with returned plaintext
+    //   - print banner
+    // If no -> print the current stranded message but include:
+    //   "Run `mosaic gateway config recover-token` when ready."
+  }
+}
+```
+
+Shape notes (actual code lands in CU-03-06):
+
+- Extract the recovery body so it can be called **both** from the standalone
+  command and from `bootstrapFirstUser` without duplicating prompts.
+- Reuse the same `rl` readline interface already open in `bootstrapFirstUser`
+  for the inline prompts.
+- Preserve non-interactive behavior: if `process.stdin.isTTY` is false, skip the
+  prompt and emit the "run recover-token" hint only.
+
+## 5. Test Strategy (CU-03-07 scope)
+
+### 5.1 Happy paths
+
+| Command                               | Scenario                                         | Expected                                                 |
+| ------------------------------------- | ------------------------------------------------ | -------------------------------------------------------- |
+| `mosaic gateway login`                | Valid creds                                      | `session.json` written, 7-day expiry, exit 0             |
+| `mosaic gateway config rotate-token`  | Valid session, server reachable                  | `meta.json` updated, banner printed, new token usable    |
+| `mosaic gateway config recover-token` | No session, valid creds, server reachable        | Prompts for creds, writes session + meta, exit 0         |
+| Installer inline recovery             | Re-run after `meta.json` wipe, operator says yes | Meta restored, banner printed, no manual CLI step needed |
+
+### 5.2 Error paths (must all produce actionable messages and non-zero exit)
+
+| Failure                           | Expected handling                                                                 |
+| --------------------------------- | --------------------------------------------------------------------------------- |
+| Invalid email/password            | BetterAuth 401 surfaced as "Sign-in failed: <server message>", exit 2             |
+| Expired stored session            | Recover command silently re-prompts; rotate command exits 2 with "run login" hint |
+| Gateway down / connection refused | "Could not reach gateway at <url>" exit 1                                         |
+| Server rejects token creation     | Print status + body excerpt, exit 3                                               |
+| Meta file missing (recover)       | Fall back to `--gateway` flag or default; warn that meta will be created          |
+| Non-admin user                    | `AdminGuard` 403 surfaced as "User is not an admin", exit 2                       |
+
+### 5.3 Integration test (recommended)
+
+Spin up gateway in test harness, create admin user via `/api/bootstrap/setup`,
+wipe `meta.json`, invoke `mosaic gateway config recover-token` programmatically,
+assert new `meta.adminToken` works against `GET /api/admin/tokens`.
+
+## 6. Risks & Open Questions
+
+| #   | Item                                                                                                                                                                                    | Severity | Mitigation                                                                                                     |
+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------- |
+| 1   | `AdminGuard.validateSession` calls `getSession` with `fromNodeHeaders(request.raw.headers)`. CLI sends `Cookie:` header only. Confirm BetterAuth reads from `Cookie`, not `Set-Cookie`. | Low      | Confirmed — `mosaic login` + `mosaic tui` already use this flow successfully (`cli.ts:137-181`).               |
+| 2   | Session cookie local expiry (7d) vs BetterAuth server-side expiry may drift.                                                                                                            | Low      | `validateSession` hits `get-session`; handle 401 by re-prompting.                                              |
+| 3   | Label collision / unbounded token growth if operators run `recover-token` repeatedly.                                                                                                   | Low      | Include ISO timestamp in label. Optional `--revoke-old` in CU-03-02. Add `tokens list/prune` later.            |
+| 4   | `mosaic login` exists at top level and `mosaic gateway login` is a wrapper — risk of confusion.                                                                                         | Low      | Document that `gateway login` is the preferred entry for gateway operators; top-level stays for compatibility. |
+| 5   | `meta.json` write is not atomic. Crash between token creation and `writeMeta` leaves an orphan token server-side with no plaintext on disk.                                             | Medium   | Accept for now — re-running `recover-token` mints a fresh token. Document as known limitation.                 |
+| 6   | Non-TTY installer runs (CI, headless provisioners) cannot prompt for creds interactively.                                                                                               | Medium   | Installer inline recovery must skip prompt when `!process.stdin.isTTY`; emit the recover-token hint.           |
+| 7   | If `BETTER_AUTH_SECRET` rotates between login and recover, the session cookie is invalid — user must re-login. Acceptable but surface a clear error.                                    | Low      | Error handler maps 401 on recover -> "Session invalid; re-run `mosaic gateway login`".                         |
+| 8   | No MFA today. When MFA lands, BetterAuth sign-in will return a challenge, not a cookie — recovery UX will need a second prompt step.                                                    | Future   | Out of scope for this mission. Flag for future CLI work.                                                       |
+
+## 7. Downstream Task Hooks
+
+| Task     | Scope                                                                      |
+| -------- | -------------------------------------------------------------------------- |
+| CU-03-02 | Implement `mosaic gateway login` wrapper + shared `runLogin` extraction.   |
+| CU-03-03 | Implement `mosaic gateway config rotate-token`.                            |
+| CU-03-04 | Implement `mosaic gateway config recover-token`.                           |
+| CU-03-05 | Wire commands into `gateway.ts` registration, update `--help` copy.        |
+| CU-03-06 | Installer inline recovery hook in `bootstrapFirstUser`.                    |
+| CU-03-07 | Tests per Section 5.                                                       |
+| CU-03-08 | Docs: update gateway install README + operator runbook with recovery flow. |

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/mosaic/package.json

@@ -27,6 +27,7 @@
     "test": "vitest run --passWithNoTests"
   },
   "dependencies": {
+    "@mosaicstack/brain": "workspace:*",
     "@mosaicstack/config": "workspace:*",
     "@mosaicstack/forge": "workspace:*",
     "@mosaicstack/macp": "workspace:*",

packages/mosaic/src/cli.ts

@@ -2,8 +2,10 @@
 
 import { createRequire } from 'module';
 import { Command } from 'commander';
+import { registerBrainCommand } from '@mosaicstack/brain';
 import { registerQualityRails } from '@mosaicstack/quality-rails';
 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';
@@ -33,7 +35,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 ────────────────────────────
 
@@ -214,7 +232,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')
@@ -310,10 +331,18 @@ registerGatewayCommand(program);
 
 registerAgentCommand(program);
 
+// ─── config ────────────────────────────────────────────────────────────
+
+registerConfigCommand(program);
+
 // ─── mission ───────────────────────────────────────────────────────────
 
 registerMissionCommand(program);
 
+// ─── brain ──────────────────────────────────────────────────────────────
+
+registerBrainCommand(program);
+
 // ─── quality-rails ──────────────────────────────────────────────────────
 
 registerQualityRails(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

@@ -30,6 +30,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();
     });

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.
    */

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
@@ -454,6 +457,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