fix(installer): preserve credentials dir and seed STANDARDS.md on install

- Add credentials/ to PRESERVE_PATHS so rsync --delete doesn't wipe
  user credential stores on framework upgrades
- Add AGENTS.md and STANDARDS.md to PRESERVE_PATHS to protect
  user-customized copies from being deleted during sync
- Seed AGENTS.md and STANDARDS.md from defaults/ on first install
  (previously only existed in defaults/ but never copied to framework root)
- Create credentials/ directory during install (alongside memory/)

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

docs/scratchpads/tools-md-seeding-20260411.md

@@ -1,110 +0,0 @@
-# Hotfix Scratchpad — `install.sh` does not seed `TOOLS.md`
-
-- **Issue:** mosaicstack/stack#457
-- **Branch:** `fix/tools-md-seeding`
-- **Type:** Out-of-mission hotfix (not part of Install UX v2 mission)
-- **Started:** 2026-04-11
-- **Ships in:** `@mosaicstack/mosaic` 0.0.30
-
-## Objective
-
-Ensure `~/.config/mosaic/TOOLS.md` is created on every supported install path so the mandatory AGENTS.md load order actually resolves. The load order lists `TOOLS.md` at position 5 but the bash installer never seeds it.
-
-## Root cause
-
-`packages/mosaic/framework/install.sh:228-236` — the post-sync "Seed defaults" loop explicitly lists `AGENTS.md STANDARDS.md`:
-
-```bash
-DEFAULTS_DIR="$TARGET_DIR/defaults"
-if [[ -d "$DEFAULTS_DIR" ]]; then
-  for default_file in AGENTS.md STANDARDS.md; do    # ← missing TOOLS.md
-    if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then
-      cp "$DEFAULTS_DIR/$default_file" "$TARGET_DIR/$default_file"
-      ok "Seeded $default_file from defaults"
-    fi
-  done
-fi
-```
-
-`TOOLS.md` is listed in `PRESERVE_PATHS` (line 24) but never created in the first place. A fresh bootstrap install via `tools/install.sh → framework/install.sh` leaves `~/.config/mosaic/TOOLS.md` absent, and the agent load order then points at a missing file.
-
-### Secondary: TypeScript `syncFramework` is too greedy
-
-`packages/mosaic/src/config/file-adapter.ts:133-160` — `FileConfigAdapter.syncFramework` correctly seeds TOOLS.md, but it does so by iterating _every_ file in `framework/defaults/`:
-
-```ts
-for (const entry of readdirSync(defaultsDir)) {
-  const dest = join(this.mosaicHome, entry);
-  if (!existsSync(dest)) {
-    copyFileSync(join(defaultsDir, entry), dest);
-  }
-}
-```
-
-`framework/defaults/` contains:
-
-```
-AGENTS.md
-AUDIT-2026-02-17-framework-consistency.md
-README.md
-SOUL.md        ← hardcoded "Jarvis"
-STANDARDS.md
-TOOLS.md
-USER.md
-```
-
-So on a fresh install the TS wizard would silently copy the `Jarvis`-flavored `SOUL.md` + placeholder `USER.md` + internal `AUDIT-*.md` and `README.md` into the user's mosaic home before `mosaic init` ever prompts them. That's a latent identity bug as well as a root-clutter bug — the wizard's own stages are responsible for generating `SOUL.md`/`USER.md` via templates.
-
-### Tertiary: stale `TOOLS.md.template`
-
-`packages/mosaic/framework/templates/TOOLS.md.template` still references `~/.config/mosaic/rails/git/…` and `~/.config/mosaic/rails/codex/…`. The `rails/` tree was renamed to `tools/` in the v1→v2 migration (see `run_migrations` in `install.sh`, which removes the old `rails/` symlink). Any user who does run `mosaic init` ends up with a `TOOLS.md` that points to paths that no longer exist.
-
-## Scope of this fix
-
-1. **`packages/mosaic/framework/install.sh`** — extend the explicit seed list to include `TOOLS.md`.
-2. **`packages/mosaic/src/config/file-adapter.ts`** — restrict `syncFramework` defaults-seeding to an explicit whitelist (`AGENTS.md`, `STANDARDS.md`, `TOOLS.md`) so the TS wizard never accidentally seeds `SOUL.md`/`USER.md`/`README.md`/`AUDIT-*.md` into the mosaic home.
-3. **`packages/mosaic/framework/templates/TOOLS.md.template`** — replace `rails/` with `tools/` in the wrapper-path examples (minimal surgical fix; full template modernization is out of scope for a 0.0.30 hotfix).
-4. **Regression test** — unit test around `FileConfigAdapter.syncFramework` that runs against a tmpdir fixture asserting:
-   - `TOOLS.md` is seeded when absent
-   - `AGENTS.md` / `STANDARDS.md` are still seeded when absent
-   - `SOUL.md` / `USER.md` are **not** seeded from `defaults/` (the wizard stages own those)
-   - Existing root files are not clobbered.
-
-Out of scope (tracked separately / future work):
-
-- Regenerating `defaults/SOUL.md` and `defaults/USER.md` so they no longer contain Jarvis-specific content.
-- Fully modernizing `TOOLS.md.template` to match the rich canonical `defaults/TOOLS.md` reference.
-- `issue-create.sh` / `pr-create.sh` `eval` bugs (already captured to OpenBrain from the prior hotfix).
-
-## Plan / checklist
-
-- [ ] Branch `fix/tools-md-seeding` from `main` (at `b2cbf89`)
-- [ ] File Gitea issue (direct API; wrappers broken for bodies with backticks)
-- [ ] Scratchpad created (this file)
-- [ ] `install.sh` seed loop extended to `AGENTS.md STANDARDS.md TOOLS.md`
-- [ ] `file-adapter.ts` seeding restricted to explicit whitelist
-- [ ] `TOOLS.md.template` `rails/` → `tools/`
-- [ ] Regression test added (`file-adapter.test.ts`) — failing first, then green
-- [ ] `pnpm --filter @mosaicstack/mosaic run typecheck` green
-- [ ] `pnpm --filter @mosaicstack/mosaic run lint` green
-- [ ] `pnpm --filter @mosaicstack/mosaic exec vitest run` — new test green, no new failures beyond the known pre-existing `uninstall.spec.ts:138`
-- [ ] Repo baselines: `pnpm typecheck` / `pnpm lint` / `pnpm format:check`
-- [ ] Independent code review (`feature-dev:code-reviewer`, sonnet tier)
-- [ ] Commit + push
-- [ ] PR opened via Gitea API
-- [ ] CI queue guard cleared (bypass local `ci-queue-wait.sh` if stale origin URL breaks it; query Gitea API directly)
-- [ ] CI green on PR
-- [ ] PR merged (squash)
-- [ ] CI green on main
-- [ ] Issue closed with link to merge commit
-- [ ] `chore/release-mosaic-0.0.30` branch bumps `packages/mosaic/package.json` 0.0.29 → 0.0.30
-- [ ] Release PR opened + merged
-- [ ] `.woodpecker/publish.yml` auto-publishes to Gitea npm registry
-- [ ] Publish verified (`npm view @mosaicstack/mosaic version` or registry check)
-
-## Risks / blockers
-
-- `ci-queue-wait.sh` wrapper may still crash on stale `origin` URL (captured in OpenBrain from prior hotfix). Workaround: query Gitea API directly for running/queued pipelines.
-- `issue-create.sh` / `pr-create.sh` `eval` bugs. Workaround: Gitea API direct call.
-- `uninstall.spec.ts:138` is a pre-existing failure on main; not this change's problem.
-- Publish flow is fire-and-forget on main push — if `publish.yml` fails, rollback means republishing a follow-up patch, not reverting the version bump.

docs/scratchpads/yolo-runtime-initial-arg-20260411.md

@@ -1,114 +0,0 @@
-# Hotfix Scratchpad — `mosaic yolo <runtime>` passes runtime name as initial user message
-
-- **Issue:** mosaicstack/stack#454
-- **Branch:** `fix/yolo-runtime-initial-arg`
-- **Type:** Out-of-mission hotfix (not part of Install UX v2 mission)
-- **Started:** 2026-04-11
-
-## Objective
-
-Stop `mosaic yolo <runtime>` from passing the runtime name (`claude`, `codex`, etc.) as the initial user message to the underlying CLI. Restore the mission-auto-prompt path for yolo launches.
-
-## Root cause (confirmed)
-
-`packages/mosaic/src/commands/launch.ts:779` — the `yolo <runtime>` action handler:
-
-```ts
-.action((runtime: string, _opts: unknown, cmd: Command) => {
-  // ... validate runtime ...
-  launchRuntime(runtime as RuntimeName, cmd.args, true);
-});
-```
-
-Commander.js includes declared positional arguments in `cmd.args`. For `mosaic yolo claude`:
-
-- `runtime` (destructured) = `"claude"`
-- `cmd.args` = `["claude"]` — the same value
-
-`launchRuntime` treats `["claude"]` as excess positional args, and for the `claude` case that becomes the initial user message. As a secondary consequence, `hasMissionNoArgs` evaluates false, so the mission-auto-prompt path is bypassed too.
-
-## Live reproduction (intercepted claude binary)
-
-```
-$ PATH=/tmp/fake-claude-bin:$PATH mosaic yolo claude
-[mosaic] Launching Claude Code in YOLO mode...
-argv[1]: --dangerously-skip-permissions
-argv[2]: --append-system-prompt
-argv[3] (len=25601): # ACTIVE MISSION — HARD GATE ...
-argv[4]: claude                                       ← the bug
-```
-
-Non-yolo variant `mosaic claude` is clean:
-
-```
-argv[1]: --append-system-prompt
-argv[2]: <prompt>
-argv[3]: Active mission detected: MVP. Read the mission state files and report status.
-```
-
-## Plan
-
-1. Refactor `launch.ts`: extract `registerRuntimeLaunchers(program, handler)` with an injectable handler so commander wiring is testable without spawning subprocesses. `registerLaunchCommands` delegates to it with `launchRuntime` as the handler.
-2. Fix: in the `yolo <runtime>` action, pass `cmd.args.slice(1)` instead of `cmd.args`.
-3. Add `packages/mosaic/src/commands/launch.spec.ts`:
-   - Failing-first reproducer: parse `['node','x','yolo','claude']` and assert handler receives `extraArgs=[]` and `yolo=true`.
-   - Regression test: parse `['node','x','claude']` asserts handler receives `extraArgs=[]` and `yolo=false`.
-   - Excess args: parse `['node','x','yolo','claude','--print','hi']` asserts handler receives `extraArgs=['--print','hi']` (with `--print` kept because `allowUnknownOption` is true).
-   - Excess args non-yolo: parse `['node','x','claude','--print','hi']` asserts `extraArgs=['--print','hi']`.
-   - Reject unknown runtime under yolo.
-4. Run typecheck, lint, format:check, vitest for `@mosaicstack/mosaic`.
-5. Independent code review (feature-dev:code-reviewer subagent, sonnet tier).
-6. Commit → push → PR via wrappers → merge → CI green → close issue #454.
-7. Release decision (`mosaic-v0.0.30`) deferred to Jason after merge.
-
-## Framework compliance sub-findings (out-of-scope; to capture in OpenBrain after)
-
-- `~/.config/mosaic/tools/git/issue-create.sh` uses `eval` on `$BODY`; arbitrary bodies with backticks, `$`, or parens break catastrophically.
-- `gitea_issue_create_api` fallback uses `curl -fsS` without `-L`; after the `mosaicstack/mosaic-stack → mosaicstack/stack` rename, the API redirect is not followed and the fallback silently fails.
-- Local repo `origin` remote still points at old `mosaic/mosaic-stack.git` slug. Not touched here per git-config safety rule.
-- `~/.config/mosaic/TOOLS.md` referenced by the global load order but does not exist on disk.
-
-These will be captured to OpenBrain after the hotfix merges so they don't get lost, and filed as separate tracking items.
-
-## Progress checkpoints
-
-- [x] Branch created (`fix/yolo-runtime-initial-arg`)
-- [x] Issue #454 opened
-- [x] Scratchpad scaffolded
-- [x] Failing test added (red)
-- [x] Refactor + fix applied
-- [x] Tests green (launch.spec.ts 11/11)
-- [x] Baselines green (typecheck, lint, format:check, vitest — pre-existing `uninstall.spec.ts:138` failure on branch main acknowledged, not caused by this change)
-- [x] Code review pass (feature-dev:code-reviewer, sonnet — no blockers)
-- [x] Commit + push (commit 1dd4f59)
-- [x] PR opened (mosaicstack/stack#455)
-- [x] CI queue guard cleared (no pending pipelines pre-push or pre-merge)
-- [x] PR merged (squash merge commit b2cec8c6bac29336a6cdcdb4f19806f7b5fa0054)
-- [x] CI green on main (`ci/woodpecker/push/ci` + `ci/woodpecker/push/publish` both success on merge commit)
-- [x] Issue #454 closed
-- [x] Scratchpad final evidence entry
-
-## Tests run
-
-- `pnpm --filter @mosaicstack/mosaic run typecheck` → green
-- `pnpm --filter @mosaicstack/mosaic run lint` → green
-- `pnpm --filter @mosaicstack/mosaic exec prettier --check "src/**/*.ts"` → green
-- `pnpm --filter @mosaicstack/mosaic exec vitest run src/commands/launch.spec.ts` → 11/11 pass
-- `pnpm --filter @mosaicstack/mosaic exec vitest run` → 270/271 pass (1 pre-existing `uninstall.spec.ts:138` EACCES failure, confirmed on the branch before this change)
-- `pnpm typecheck` (repo) → green
-- `pnpm lint` (repo) → green
-- `pnpm format:check` (repo) → green (after prettier-writing the scratchpad)
-
-## Risks / blockers
-
-None expected. Refactor is small and the Commander API is stable. Test needs `exitOverride()` to prevent `process.exit` on invalid runtime.
-
-## Final verification evidence
-
-- PR: mosaicstack/stack#455 — state `closed`, merged.
-- Merge commit: `b2cec8c6bac29336a6cdcdb4f19806f7b5fa0054` (squash to `main`).
-- Post-merge CI (main @ b2cec8c6): `ci/woodpecker/push/ci` = success, `ci/woodpecker/push/publish` = success. (`ci/woodpecker/tag/publish` was last observed as a pre-existing failure on the prior release tag and is unrelated to this change.)
-- Issue mosaicstack/stack#454 closed with a comment linking the merge commit.
-- Launch regression suite: `launch.spec.ts` 11/11 pass on main.
-- Baselines on main after merge are inherited from the PR CI run.
-- Release decision (`mosaicstack/mosaic` 0.0.30) intentionally deferred to the user — the fix is now sitting on main awaiting a release cut.

packages/mosaic/framework/install.sh

@@ -222,17 +222,12 @@ sync_framework
 mkdir -p "$TARGET_DIR/memory"
 mkdir -p "$TARGET_DIR/credentials"
 
-# Seed defaults — copy framework contract files from defaults/ to framework
-# root if not already present. These ship with sensible defaults but must
+# Seed defaults — copy from defaults/ to framework root if not already present.
+# These are user-editable files that ship with sensible defaults but should
 # never be overwritten once the user has customized them.
-#
-# This list must match the framework-contract whitelist in
-# packages/mosaic/src/config/file-adapter.ts (FileConfigAdapter.syncFramework).
-# SOUL.md and USER.md are intentionally NOT seeded here — they are generated
-# by `mosaic init` from templates with user-supplied values.
 DEFAULTS_DIR="$TARGET_DIR/defaults"
 if [[ -d "$DEFAULTS_DIR" ]]; then
-  for default_file in AGENTS.md STANDARDS.md TOOLS.md; do
+  for default_file in AGENTS.md STANDARDS.md; do
     if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then
       cp "$DEFAULTS_DIR/$default_file" "$TARGET_DIR/$default_file"
       ok "Seeded $default_file from defaults"

packages/mosaic/framework/templates/TOOLS.md.template

@@ -5,32 +5,32 @@ Project-specific tooling belongs in the project's `AGENTS.md`, not here.
 
 ## Mosaic Git Wrappers (Use First)
 
-Mosaic wrappers at `~/.config/mosaic/tools/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
+Mosaic wrappers at `~/.config/mosaic/rails/git/*.sh` handle platform detection and edge cases. Always use these before raw CLI commands.
 
 ```bash
 # Issues
-~/.config/mosaic/tools/git/issue-create.sh
-~/.config/mosaic/tools/git/issue-close.sh
+~/.config/mosaic/rails/git/issue-create.sh
+~/.config/mosaic/rails/git/issue-close.sh
 
 # PRs
-~/.config/mosaic/tools/git/pr-create.sh
-~/.config/mosaic/tools/git/pr-merge.sh
+~/.config/mosaic/rails/git/pr-create.sh
+~/.config/mosaic/rails/git/pr-merge.sh
 
 # Milestones
-~/.config/mosaic/tools/git/milestone-create.sh
+~/.config/mosaic/rails/git/milestone-create.sh
 
 # CI queue guard (required before push/merge)
-~/.config/mosaic/tools/git/ci-queue-wait.sh --purpose push|merge
+~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge
 ```
 
 ## Code Review (Codex)
 
 ```bash
 # Code quality review
-~/.config/mosaic/tools/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review
-~/.config/mosaic/tools/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 ## Git Providers

packages/mosaic/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mosaicstack/mosaic",
-  "version": "0.0.30",
+  "version": "0.0.28",
   "repository": {
     "type": "git",
     "url": "https://git.mosaicstack.dev/mosaicstack/stack.git",

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

@@ -1,111 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach, type MockInstance } from 'vitest';
-import { Command } from 'commander';
-import { registerRuntimeLaunchers, type RuntimeLaunchHandler } from './launch.js';
-
-/**
- * Tests for the commander wiring between `mosaic <runtime>` / `mosaic yolo <runtime>`
- * subcommands and the internal `launchRuntime` dispatcher.
- *
- * Regression target: see mosaicstack/stack#454 — before the fix, `mosaic yolo claude`
- * passed the literal string "claude" as an excess positional argument to the
- * underlying CLI, which Claude Code then interpreted as the first user message.
- *
- * The bug existed because Commander.js includes declared positional arguments
- * (here `<runtime>`) in `cmd.args` alongside any true excess args. The action
- * handler must slice them off before forwarding.
- */
-
-function buildProgram(handler: RuntimeLaunchHandler): Command {
-  const program = new Command();
-  program.exitOverride(); // prevent process.exit on parse errors
-  registerRuntimeLaunchers(program, handler);
-  return program;
-}
-
-// `process.exit` returns `never`, so vi.spyOn demands a replacement with the
-// same signature. We throw from the mock to short-circuit into test-land.
-const exitThrows = (): never => {
-  throw new Error('process.exit called');
-};
-
-describe('registerRuntimeLaunchers — non-yolo subcommands', () => {
-  let mockExit: MockInstance<typeof process.exit>;
-
-  beforeEach(() => {
-    // process.exit is called when the yolo action rejects an invalid runtime.
-    // Stub it so the assertion catches the rejection instead of terminating
-    // the test runner.
-    mockExit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
-  });
-
-  afterEach(() => {
-    mockExit.mockRestore();
-  });
-
-  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
-    'forwards %s with empty extraArgs and yolo=false',
-    (runtime) => {
-      const handler = vi.fn();
-      const program = buildProgram(handler);
-      program.parse(['node', 'mosaic', runtime]);
-
-      expect(handler).toHaveBeenCalledTimes(1);
-      expect(handler).toHaveBeenCalledWith(runtime, [], false);
-    },
-  );
-
-  it('forwards excess args after a non-yolo runtime subcommand', () => {
-    const handler = vi.fn();
-    const program = buildProgram(handler);
-    program.parse(['node', 'mosaic', 'claude', '--print', 'hello']);
-
-    expect(handler).toHaveBeenCalledWith('claude', ['--print', 'hello'], false);
-  });
-});
-
-describe('registerRuntimeLaunchers — yolo <runtime>', () => {
-  let mockExit: MockInstance<typeof process.exit>;
-  let mockError: MockInstance<typeof console.error>;
-
-  beforeEach(() => {
-    mockExit = vi.spyOn(process, 'exit').mockImplementation(exitThrows);
-    mockError = vi.spyOn(console, 'error').mockImplementation(() => {});
-  });
-
-  afterEach(() => {
-    mockExit.mockRestore();
-    mockError.mockRestore();
-  });
-
-  it.each(['claude', 'codex', 'opencode', 'pi'] as const)(
-    'does NOT pass the runtime name as an extra arg (regression #454) for yolo %s',
-    (runtime) => {
-      const handler = vi.fn();
-      const program = buildProgram(handler);
-      program.parse(['node', 'mosaic', 'yolo', runtime]);
-
-      expect(handler).toHaveBeenCalledTimes(1);
-      // The critical assertion: extraArgs must be empty, not [runtime].
-      // Before the fix, cmd.args was [runtime] and the runtime name leaked
-      // through to the underlying CLI as an initial positional argument.
-      expect(handler).toHaveBeenCalledWith(runtime, [], true);
-    },
-  );
-
-  it('forwards true excess args after a yolo runtime', () => {
-    const handler = vi.fn();
-    const program = buildProgram(handler);
-    program.parse(['node', 'mosaic', 'yolo', 'claude', '--print', 'hi']);
-
-    expect(handler).toHaveBeenCalledWith('claude', ['--print', 'hi'], true);
-  });
-
-  it('rejects an unknown runtime under yolo without invoking the handler', () => {
-    const handler = vi.fn();
-    const program = buildProgram(handler);
-
-    expect(() => program.parse(['node', 'mosaic', 'yolo', 'bogus'])).toThrow('process.exit called');
-    expect(handler).not.toHaveBeenCalled();
-    expect(mockExit).toHaveBeenCalledWith(1);
-  });
-});

packages/mosaic/src/commands/launch.ts

@@ -757,23 +757,8 @@ function runUpgrade(args: string[]): never {
 
 // ─── Commander registration ─────────────────────────────────────────────────
 
-/**
- * Handler invoked when a runtime subcommand (`<runtime>` or `yolo <runtime>`)
- * is parsed. Exposed so tests can exercise the commander wiring without
- * spawning subprocesses.
- */
-export type RuntimeLaunchHandler = (
-  runtime: RuntimeName,
-  extraArgs: string[],
-  yolo: boolean,
-) => void;
-
-/**
- * Wire `<runtime>` and `yolo <runtime>` subcommands onto `program` using a
- * pluggable launch handler. Separated from `registerLaunchCommands` so tests
- * can inject a spy and verify argument forwarding.
- */
-export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunchHandler): void {
+export function registerLaunchCommands(program: Command): void {
+  // Runtime launchers
   for (const runtime of ['claude', 'codex', 'opencode', 'pi'] as const) {
     program
       .command(runtime)
@@ -781,10 +766,11 @@ export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunc
       .allowUnknownOption(true)
       .allowExcessArguments(true)
       .action((_opts: unknown, cmd: Command) => {
-        handler(runtime, cmd.args, false);
+        launchRuntime(runtime, cmd.args, false);
       });
   }
 
+  // Yolo mode
   program
     .command('yolo <runtime>')
     .description('Launch a runtime in dangerous-permissions mode (claude|codex|opencode|pi)')
@@ -798,20 +784,7 @@ export function registerRuntimeLaunchers(program: Command, handler: RuntimeLaunc
         );
         process.exit(1);
       }
-      // Commander includes declared positional arguments (`<runtime>`) in
-      // `cmd.args` alongside any trailing excess args. Slice off the first
-      // element so we forward only true excess args — otherwise the runtime
-      // name leaks into the underlying CLI as an initial positional arg,
-      // which Claude Code interprets as the first user message.
-      // Regression test: launch.spec.ts, issue mosaicstack/stack#454.
-      handler(runtime as RuntimeName, cmd.args.slice(1), true);
-    });
-}
-
-export function registerLaunchCommands(program: Command): void {
-  // Runtime launchers + yolo mode wired to the real process-replacing launcher.
-  registerRuntimeLaunchers(program, (runtime, extraArgs, yolo) => {
-    launchRuntime(runtime, extraArgs, yolo);
+      launchRuntime(runtime as RuntimeName, cmd.args, true);
     });
 
   // Coord (mission orchestrator)

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

@@ -1,134 +0,0 @@
-import { describe, it, expect, beforeEach, afterEach } from 'vitest';
-import { mkdtempSync, mkdirSync, writeFileSync, rmSync, readFileSync, existsSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-import { FileConfigAdapter, DEFAULT_SEED_FILES } from './file-adapter.js';
-
-/**
- * Regression tests for the `FileConfigAdapter.syncFramework` seed behavior.
- *
- * Background: the bash installer (`framework/install.sh`) and this TS wizard
- * path both seed framework-contract files from `framework/defaults/` into the
- * user's mosaic home on first install. Before this fix:
- *
- *   - The bash installer only seeded `AGENTS.md` and `STANDARDS.md`, leaving
- *     `TOOLS.md` missing despite it being listed as mandatory in the
- *     AGENTS.md load order (position 5).
- *   - The TS wizard iterated every file in `defaults/` and copied it to the
- *     mosaic home root — including `defaults/SOUL.md` (hardcoded "Jarvis"),
- *     `defaults/USER.md` (placeholder), and internal framework files like
- *     `README.md` and `AUDIT-*.md`. That clobbered the identity flow on
- *     fresh installs and leaked framework-internal clutter into the user's
- *     home directory.
- *
- * This suite pins the whitelist and the preservation semantics so both
- * regressions stay fixed.
- */
-
-function makeFixture(): { sourceDir: string; mosaicHome: string; defaultsDir: string } {
-  const root = mkdtempSync(join(tmpdir(), 'mosaic-file-adapter-'));
-  const sourceDir = join(root, 'source');
-  const mosaicHome = join(root, 'mosaic-home');
-  const defaultsDir = join(sourceDir, 'defaults');
-
-  mkdirSync(defaultsDir, { recursive: true });
-  mkdirSync(mosaicHome, { recursive: true });
-
-  // Framework-contract defaults we expect the wizard to seed.
-  writeFileSync(join(defaultsDir, 'AGENTS.md'), '# AGENTS default\n');
-  writeFileSync(join(defaultsDir, 'STANDARDS.md'), '# STANDARDS default\n');
-  writeFileSync(join(defaultsDir, 'TOOLS.md'), '# TOOLS default\n');
-
-  // Non-contract files we must NOT seed on first install.
-  writeFileSync(join(defaultsDir, 'SOUL.md'), '# SOUL default (should not be seeded)\n');
-  writeFileSync(join(defaultsDir, 'USER.md'), '# USER default (should not be seeded)\n');
-  writeFileSync(join(defaultsDir, 'README.md'), '# README (framework-internal)\n');
-  writeFileSync(
-    join(defaultsDir, 'AUDIT-2026-02-17-framework-consistency.md'),
-    '# Audit snapshot\n',
-  );
-
-  return { sourceDir, mosaicHome, defaultsDir };
-}
-
-describe('FileConfigAdapter.syncFramework — defaults seeding', () => {
-  let fixture: ReturnType<typeof makeFixture>;
-
-  beforeEach(() => {
-    fixture = makeFixture();
-  });
-
-  afterEach(() => {
-    rmSync(join(fixture.sourceDir, '..'), { recursive: true, force: true });
-  });
-
-  it('seeds the three framework-contract files on a fresh mosaic home', async () => {
-    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
-
-    await adapter.syncFramework('fresh');
-
-    for (const name of DEFAULT_SEED_FILES) {
-      expect(existsSync(join(fixture.mosaicHome, name))).toBe(true);
-    }
-    expect(readFileSync(join(fixture.mosaicHome, 'TOOLS.md'), 'utf-8')).toContain(
-      '# TOOLS default',
-    );
-  });
-
-  it('does NOT seed SOUL.md or USER.md from defaults/ (wizard stages own those)', async () => {
-    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
-
-    await adapter.syncFramework('fresh');
-
-    // SOUL.md and USER.md live in defaults/ for historical reasons, but they
-    // are template-rendered per-user by the wizard stages. Seeding them here
-    // would clobber the identity flow and leak placeholder content.
-    expect(existsSync(join(fixture.mosaicHome, 'SOUL.md'))).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'USER.md'))).toBe(false);
-  });
-
-  it('does NOT seed README.md or AUDIT-*.md from defaults/', async () => {
-    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
-
-    await adapter.syncFramework('fresh');
-
-    expect(existsSync(join(fixture.mosaicHome, 'README.md'))).toBe(false);
-    expect(existsSync(join(fixture.mosaicHome, 'AUDIT-2026-02-17-framework-consistency.md'))).toBe(
-      false,
-    );
-  });
-
-  it('preserves existing contract files — never overwrites user customization', async () => {
-    // Also plant a root-level AGENTS.md in sourceDir so that `syncDirectory`
-    // itself (not just the seed loop) has something to try to overwrite.
-    // Without this, the test would silently pass even if preserve semantics
-    // were broken in syncDirectory.
-    writeFileSync(join(fixture.sourceDir, 'AGENTS.md'), '# shipped AGENTS from source root\n');
-
-    writeFileSync(join(fixture.mosaicHome, 'TOOLS.md'), '# user-customized TOOLS\n');
-    writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n');
-
-    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
-    await adapter.syncFramework('keep');
-
-    expect(readFileSync(join(fixture.mosaicHome, 'TOOLS.md'), 'utf-8')).toBe(
-      '# user-customized TOOLS\n',
-    );
-    expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe(
-      '# user-customized AGENTS\n',
-    );
-    // And the missing contract file still gets seeded.
-    expect(readFileSync(join(fixture.mosaicHome, 'STANDARDS.md'), 'utf-8')).toContain(
-      '# STANDARDS default',
-    );
-  });
-
-  it('is a no-op for seeding when defaults/ dir does not exist', async () => {
-    rmSync(fixture.defaultsDir, { recursive: true });
-
-    const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir);
-    await expect(adapter.syncFramework('fresh')).resolves.toBeUndefined();
-
-    expect(existsSync(join(fixture.mosaicHome, 'TOOLS.md'))).toBe(false);
-  });
-});

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

@@ -1,19 +1,5 @@
-import { readFileSync, existsSync, statSync, copyFileSync } from 'node:fs';
+import { readFileSync, existsSync, readdirSync, statSync, copyFileSync } from 'node:fs';
 import { join } from 'node:path';
-
-/**
- * Framework-contract files that `syncFramework` seeds from `framework/defaults/`
- * into the mosaic home root on first install. These are the only files the
- * wizard is allowed to touch as a one-time seed — SOUL.md and USER.md are
- * generated from templates by their respective wizard stages with
- * user-supplied values, and anything else under `defaults/` (README.md,
- * audit snapshots, etc.) is framework-internal and must not leak into the
- * user's mosaic home.
- *
- * This list must match the explicit seed loop in
- * packages/mosaic/framework/install.sh.
- */
-export const DEFAULT_SEED_FILES = ['AGENTS.md', 'STANDARDS.md', 'TOOLS.md'] as const;
 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';
@@ -145,24 +131,9 @@ export class FileConfigAdapter implements ConfigService {
   }
 
   async syncFramework(action: InstallAction): Promise<void> {
-    // Must match PRESERVE_PATHS in packages/mosaic/framework/install.sh so
-    // the bash and TS install paths have the same upgrade-preservation
-    // semantics. Contract files (AGENTS.md, STANDARDS.md, TOOLS.md) are
-    // seeded from defaults/ on first install and preserved thereafter;
-    // identity files (SOUL.md, USER.md) are generated by wizard stages and
-    // must never be touched by the framework sync.
     const preservePaths =
       action === 'keep' || action === 'reconfigure'
-        ? [
-            'AGENTS.md',
-            'SOUL.md',
-            'USER.md',
-            'TOOLS.md',
-            'STANDARDS.md',
-            'memory',
-            'sources',
-            'credentials',
-          ]
+        ? ['SOUL.md', 'USER.md', 'TOOLS.md', 'memory']
         : [];
 
     syncDirectory(this.sourceDir, this.mosaicHome, {
@@ -170,26 +141,23 @@ export class FileConfigAdapter implements ConfigService {
       excludeGit: true,
     });
 
-    // Copy framework-contract files (AGENTS.md, STANDARDS.md, TOOLS.md)
-    // from framework/defaults/ into the mosaic home root if they don't
-    // exist yet. These are written on first install only and are never
-    // overwritten afterwards — the user may have customized them.
-    //
-    // SOUL.md and USER.md are deliberately NOT seeded here. They are
-    // generated from templates by the soul/user wizard stages with
-    // user-supplied values; seeding them from defaults would clobber the
-    // identity flow and leak placeholder content into the mosaic home.
+    // Copy default root-level .md files (AGENTS.md, STANDARDS.md, etc.)
+    // from framework/defaults/ into mosaicHome root if they don't exist yet.
+    // These are framework contracts — only written on first install, never
+    // overwritten (user may have customized them).
     const defaultsDir = join(this.sourceDir, 'defaults');
     if (existsSync(defaultsDir)) {
-      for (const entry of DEFAULT_SEED_FILES) {
-        const src = join(defaultsDir, entry);
+      for (const entry of readdirSync(defaultsDir)) {
         const dest = join(this.mosaicHome, entry);
-        if (existsSync(dest)) continue;
-        if (!existsSync(src) || !statSync(src).isFile()) continue;
+        if (!existsSync(dest)) {
+          const src = join(defaultsDir, entry);
+          if (statSync(src).isFile()) {
             copyFileSync(src, dest);
           }
         }
       }
+    }
+  }
 
   async readAll(): Promise<ResolvedConfig> {
     const [soul, user, tools] = await Promise.all([