From c7f363b2d20075c45106ade6c5705a94bfb511b7 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason.woltje@uscllc.com>
Date: Tue, 17 Feb 2026 14:12:02 -0600
Subject: [PATCH] migrate mosaic home to xdg config path

---
 AUDIT-2026-02-17-framework-consistency.md     |  16 +--
 README.md                                     |  82 ++++++------
 STANDARDS.md                                  |  22 ++--
 adapters/claude.md                            |   6 +-
 adapters/codex.md                             |   2 +-
 adapters/generic.md                           |   2 +-
 bin/mosaic-bootstrap-repo                     |  14 +--
 bin/mosaic-doctor                             |   2 +-
 bin/mosaic-link-runtime-assets                |   2 +-
 bin/mosaic-migrate-local-skills               |   4 +-
 bin/mosaic-orchestrator-matrix-consume        |   2 +-
 bin/mosaic-orchestrator-matrix-cycle          |   2 +-
 bin/mosaic-orchestrator-matrix-publish        |   2 +-
 bin/mosaic-orchestrator-run                   |   2 +-
 bin/mosaic-prune-legacy-runtime               |   4 +-
 bin/mosaic-quality-apply                      |   2 +-
 bin/mosaic-quality-verify                     |   2 +-
 bin/mosaic-sync-skills                        |  10 +-
 bin/mosaic-upgrade-slaves                     |   4 +-
 guides/authentication.md                      |   2 +-
 guides/backend.md                             |   6 +-
 guides/bootstrap.md                           |  42 +++----
 guides/code-review.md                         |   2 +-
 guides/frontend.md                            |   4 +-
 guides/infrastructure.md                      |   2 +-
 guides/orchestrator.md                        |  20 +--
 guides/qa-testing.md                          |   2 +-
 install.sh                                    |   4 +-
 profiles/README.md                            |   6 +-
 rails/bootstrap/agent-lint.sh                 |   6 +-
 rails/bootstrap/agent-upgrade.sh              |   6 +-
 rails/bootstrap/init-project.sh               |   8 +-
 rails/bootstrap/init-repo-labels.sh           |   2 +-
 rails/codex/README.md                         |  30 ++---
 rails/orchestrator-matrix/README.md           |  10 +-
 rails/qa/qa-hook-handler.sh                   |   2 +-
 rails/qa/qa-hook-stdin.sh                     |   6 +-
 rails/qa/qa-hook-wrapper.sh                   |   2 +-
 rails/qa/qa-queue-monitor.sh                  |   2 +-
 rails/qa/remediation-hook-handler.sh          |   2 +-
 rails/quality/README.md                       |   6 +-
 rails/quality/scripts/install.sh              |   2 +-
 runtime/claude/CLAUDE.md                      | 118 +++++++++---------
 runtime/claude/settings.json                  |   2 +-
 runtime/opencode/AGENTS.md                    |   8 +-
 skills-local/mosaic-standards/SKILL.md        |   4 +-
 skills-local/setup-cicd/SKILL.md              |   6 +-
 templates/agent/AGENTS.md.template            |   4 +-
 templates/agent/CLAUDE.md.template            |  22 ++--
 templates/agent/SPEC.md                       |   6 +-
 templates/agent/fragments/code-review.md      |   6 +-
 .../agent/fragments/conditional-loading.md    |  22 ++--
 .../agent/projects/django/AGENTS.md.template  |   4 +-
 .../agent/projects/django/CLAUDE.md.template  |  14 +--
 .../projects/nestjs-nextjs/AGENTS.md.template |   4 +-
 .../projects/nestjs-nextjs/CLAUDE.md.template |  20 +--
 .../python-fastapi/CLAUDE.md.template         |  24 ++--
 .../python-library/CLAUDE.md.template         |  18 +--
 .../projects/typescript/AGENTS.md.template    |   2 +-
 .../projects/typescript/CLAUDE.md.template    |  20 +--
 60 files changed, 330 insertions(+), 330 deletions(-)

diff --git a/AUDIT-2026-02-17-framework-consistency.md b/AUDIT-2026-02-17-framework-consistency.md
index c5c27c1..cb99368 100644
--- a/AUDIT-2026-02-17-framework-consistency.md
+++ b/AUDIT-2026-02-17-framework-consistency.md
@@ -4,7 +4,7 @@ Date: 2026-02-17
 Scope:
 - `~/src/mosaic-bootstrap`
 - `~/src/agent-skills`
-- Installed runtime check: `~/.mosaic`
+- Installed runtime check: `~/.config/mosaic`
 
 ## Findings
 
@@ -31,7 +31,7 @@ Updated:
 - `rails/qa/qa-queue-monitor.sh`
 
 Change:
-- Standardized handler paths to `~/.mosaic/rails/qa/...`.
+- Standardized handler paths to `~/.config/mosaic/rails/qa/...`.
 
 ### MF-002 + MF-003 (conditional loading/context detection)
 Updated:
@@ -42,7 +42,7 @@ Updated:
 Change:
 - Detection now recognizes both legacy and Mosaic patterns:
   - `agent-guides` (legacy compatibility)
-  - `~/.mosaic/guides`
+  - `~/.config/mosaic/guides`
   - `Conditional Loading`
   - `Conditional Context`
 
@@ -58,8 +58,8 @@ Updated:
 - `skills/pr-reviewer/SKILL.md`
 
 Change:
-- Replaced all `~/.claude/scripts/git/...` with `~/.mosaic/rails/git/...`.
-- Replaced `~/.claude/skills/...` with `~/.mosaic/skills/...`.
+- Replaced all `~/.claude/scripts/git/...` with `~/.config/mosaic/rails/git/...`.
+- Replaced `~/.claude/skills/...` with `~/.config/mosaic/skills/...`.
 
 ### MF-006 (worktree skill docs hierarchy)
 Updated:
@@ -84,7 +84,7 @@ Updated:
 - `skills/systematic-debugging/CREATION-LOG.md`
 
 Change:
-- Standardized references to `~/.mosaic/skills`.
+- Standardized references to `~/.config/mosaic/skills`.
 - Removed stale Claude-only wording.
 
 ## Residual Legacy References (Intentional)
@@ -109,7 +109,7 @@ These are required to support existing Claude runtime integration while keeping
 Executed checks:
 - `rg -n "~/.claude|\\.claude/|agent-guides" ~/src/agent-skills -S`
   - Result: no matches after remediation.
-- `rg -n "~/.mosaic/rails/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
+- `rg -n "~/.config/mosaic/rails/(qa-hook|remediation-hook|qa-queue-monitor)" ~/src/mosaic-bootstrap -S`
   - Result: no invalid old-style QA rail paths remain.
 - Installed runtime validation:
-  - `~/.mosaic` contains `rails/git`, `rails/portainer`, `rails/cicd`, `skills`, and `bin` tooling.
+  - `~/.config/mosaic` contains `rails/git`, `rails/portainer`, `rails/cicd`, `skills`, and `bin` tooling.
diff --git a/README.md b/README.md
index a55c0cd..3e54f6b 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,6 @@
 # Mosaic Agent Framework
 
-`~/.mosaic` is the universal userspace standards layer (master) for all agent runtimes.
+`~/.config/mosaic` is the universal userspace standards layer (master) for all agent runtimes.
 
 ## Install Master Layer
 
@@ -13,15 +13,15 @@ bash ~/src/mosaic-bootstrap/install.sh
 
 ## What It Provides
 
-- Shared standards document: `~/.mosaic/STANDARDS.md`
-- Shared operational guides: `~/.mosaic/guides/`
-- Shared quality rails/scripts: `~/.mosaic/rails/`
-- Shared runtime-neutral presets/profiles: `~/.mosaic/profiles/`
-- Runtime adapter docs: `~/.mosaic/adapters/`
-- Runtime overlays: `~/.mosaic/runtime/`
-- Shared wrapper commands: `~/.mosaic/bin/`
-- Canonical skills directory: `~/.mosaic/skills`
-- Local cross-runtime skills: `~/.mosaic/skills-local`
+- Shared standards document: `~/.config/mosaic/STANDARDS.md`
+- Shared operational guides: `~/.config/mosaic/guides/`
+- Shared quality rails/scripts: `~/.config/mosaic/rails/`
+- Shared runtime-neutral presets/profiles: `~/.config/mosaic/profiles/`
+- Runtime adapter docs: `~/.config/mosaic/adapters/`
+- Runtime overlays: `~/.config/mosaic/runtime/`
+- Shared wrapper commands: `~/.config/mosaic/bin/`
+- Canonical skills directory: `~/.config/mosaic/skills`
+- Local cross-runtime skills: `~/.config/mosaic/skills-local`
 
 ## Universal Skills
 
@@ -31,7 +31,7 @@ The installer syncs skills from:
 
 into:
 
-- `~/.mosaic/skills`
+- `~/.config/mosaic/skills`
 
 Then links each skill into runtime directories:
 
@@ -39,51 +39,51 @@ Then links each skill into runtime directories:
 - `~/.codex/skills`
 - `~/.config/opencode/skills`
 
-Local skills under `~/.mosaic/skills-local` are also linked into runtimes.
+Local skills under `~/.config/mosaic/skills-local` are also linked into runtimes.
 
 Manual commands:
 
 ```bash
-~/.mosaic/bin/mosaic-sync-skills
-~/.mosaic/bin/mosaic-sync-skills --link-only
+~/.config/mosaic/bin/mosaic-sync-skills
+~/.config/mosaic/bin/mosaic-sync-skills --link-only
 ```
 
 ## Runtime Compatibility Sync
 
 Installer syncs runtime overlays as regular files (not symlinks):
 
-- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.mosaic/runtime/claude/...`
-- `~/.config/opencode/AGENTS.md` <- `~/.mosaic/runtime/opencode/AGENTS.md`
+- `~/.claude/{CLAUDE.md,settings.json,hooks-config.json,context7-integration.md}` <- `~/.config/mosaic/runtime/claude/...`
+- `~/.config/opencode/AGENTS.md` <- `~/.config/mosaic/runtime/opencode/AGENTS.md`
 
 Legacy symlink trees under `~/.claude` for migrated guides/scripts/templates/presets are pruned during sync.
 
 Run manually:
 
 ```bash
-~/.mosaic/bin/mosaic-link-runtime-assets
-~/.mosaic/bin/mosaic-migrate-local-skills --apply
+~/.config/mosaic/bin/mosaic-link-runtime-assets
+~/.config/mosaic/bin/mosaic-migrate-local-skills --apply
 ```
 
 Prune migrated legacy backups from runtime folders (dry-run by default):
 
 ```bash
-~/.mosaic/bin/mosaic-prune-legacy-runtime --runtime claude
-~/.mosaic/bin/mosaic-prune-legacy-runtime --runtime claude --apply
+~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude
+~/.config/mosaic/bin/mosaic-prune-legacy-runtime --runtime claude --apply
 ```
 
 Clean empty legacy runtime directories:
 
 ```bash
-~/.mosaic/bin/mosaic-clean-runtime --runtime claude
-~/.mosaic/bin/mosaic-clean-runtime --runtime claude --apply
-~/.mosaic/bin/mosaic-clean-runtime --runtime claude --all-empty --apply
+~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude
+~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude --apply
+~/.config/mosaic/bin/mosaic-clean-runtime --runtime claude --all-empty --apply
 ```
 
 Audit runtime drift:
 
 ```bash
-~/.mosaic/bin/mosaic-doctor
-~/.mosaic/bin/mosaic-doctor --fail-on-warn
+~/.config/mosaic/bin/mosaic-doctor
+~/.config/mosaic/bin/mosaic-doctor --fail-on-warn
 ```
 
 Opt-out during install:
@@ -97,9 +97,9 @@ MOSAIC_SKIP_SKILLS_SYNC=1 bash ~/src/mosaic-bootstrap/install.sh
 Inside any compatible repository:
 
 ```bash
-~/.mosaic/bin/mosaic-session-start
-~/.mosaic/bin/mosaic-critical
-~/.mosaic/bin/mosaic-session-end
+~/.config/mosaic/bin/mosaic-session-start
+~/.config/mosaic/bin/mosaic-critical
+~/.config/mosaic/bin/mosaic-session-end
 ```
 
 Wrapper commands call local repo scripts under `scripts/agent/`.
@@ -108,18 +108,18 @@ Wrapper commands call local repo scripts under `scripts/agent/`.
 
 Mosaic includes vendored quality-rails templates and scripts at:
 
-- `~/.mosaic/rails/quality/`
+- `~/.config/mosaic/rails/quality/`
 
 Apply to a repo:
 
 ```bash
-~/.mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
+~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/repo
 ```
 
 Verify enforcement:
 
 ```bash
-~/.mosaic/bin/mosaic-quality-verify --target /path/to/repo
+~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/repo
 ```
 
 Templates currently supported:
@@ -132,16 +132,16 @@ Templates currently supported:
 
 Mosaic includes a runtime-agnostic orchestrator rail at:
 
-- `~/.mosaic/rails/orchestrator-matrix/`
+- `~/.config/mosaic/rails/orchestrator-matrix/`
 
 Run from a bootstrapped repo:
 
 ```bash
-~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
-~/.mosaic/bin/mosaic-orchestrator-run --once
-~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
-~/.mosaic/bin/mosaic-orchestrator-matrix-publish
-~/.mosaic/bin/mosaic-orchestrator-matrix-consume
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
+~/.config/mosaic/bin/mosaic-orchestrator-run --once
+~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
 ```
 
 The controller reads/writes repo-local state in `.mosaic/orchestrator/` and emits
@@ -152,13 +152,13 @@ structured events to `.mosaic/orchestrator/events.ndjson` for Matrix bridge cons
 Attach any repository/workspace to the master layer:
 
 ```bash
-~/.mosaic/bin/mosaic-bootstrap-repo /path/to/repo
+~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo
 ```
 
 Attach and apply quality rails in one step:
 
 ```bash
-~/.mosaic/bin/mosaic-bootstrap-repo --quality-template typescript-node /path/to/repo
+~/.config/mosaic/bin/mosaic-bootstrap-repo --quality-template typescript-node /path/to/repo
 ```
 
 This creates/updates:
@@ -172,11 +172,11 @@ This creates/updates:
 Preview upgrades (dry-run):
 
 ```bash
-~/.mosaic/bin/mosaic-upgrade-slaves
+~/.config/mosaic/bin/mosaic-upgrade-slaves
 ```
 
 Apply upgrades:
 
 ```bash
-~/.mosaic/bin/mosaic-upgrade-slaves --apply
+~/.config/mosaic/bin/mosaic-upgrade-slaves --apply
 ```
diff --git a/STANDARDS.md b/STANDARDS.md
index d0dfd79..9d8a585 100644
--- a/STANDARDS.md
+++ b/STANDARDS.md
@@ -3,7 +3,7 @@
 This file is the canonical standards contract for agent sessions on this machine.
 
 Master/slave model:
-- Master: `~/.mosaic` (this framework)
+- Master: `~/.config/mosaic` (this framework)
 - Slave: each repo bootstrapped via `mosaic-bootstrap-repo`
 
 ## Execution Model
@@ -12,16 +12,16 @@ Master/slave model:
 2. Load project-local `AGENTS.md` next.
 3. Respect repository-specific tooling and workflows.
 4. Use lifecycle scripts when available (`scripts/agent/*.sh`).
-5. Use shared rails/guides from `~/.mosaic` as canonical references.
+5. Use shared rails/guides from `~/.config/mosaic` as canonical references.
 
 ## Non-Negotiables
 
 - Data files are authoritative; generated views are derived artifacts.
 - Pull before edits when collaborating in shared repos.
 - Run validation checks before claiming completion.
-- Apply quality rails from `~/.mosaic/rails/` when relevant (review, QA, git workflow).
-- For project-level mechanical enforcement templates, use `~/.mosaic/rails/quality/` via `~/.mosaic/bin/mosaic-quality-apply`.
-- For runtime-agnostic delegation/orchestration, use `~/.mosaic/rails/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
+- Apply quality rails from `~/.config/mosaic/rails/` when relevant (review, QA, git workflow).
+- For project-level mechanical enforcement templates, use `~/.config/mosaic/rails/quality/` via `~/.config/mosaic/bin/mosaic-quality-apply`.
+- For runtime-agnostic delegation/orchestration, use `~/.config/mosaic/rails/orchestrator-matrix/` with repo-local `.mosaic/orchestrator/` state.
 - Avoid hardcoded secrets and token leakage in remotes/commits.
 - Do not perform destructive git/file actions without explicit instruction.
 
@@ -44,15 +44,15 @@ If a repo does not expose these scripts, run equivalent local workflow commands
 
 All runtime adapters should inject:
 
-- `~/.mosaic/STANDARDS.md`
+- `~/.config/mosaic/STANDARDS.md`
 - project `AGENTS.md`
 
 before task execution.
 
 Runtime-compatible guides and rails are hosted at:
 
-- `~/.mosaic/guides/`
-- `~/.mosaic/rails/`
-- `~/.mosaic/profiles/` (runtime-neutral domain/workflow/stack presets)
-- `~/.mosaic/runtime/` (runtime-specific overlays)
-- `~/.mosaic/skills-local/` (local private skills shared across runtimes)
+- `~/.config/mosaic/guides/`
+- `~/.config/mosaic/rails/`
+- `~/.config/mosaic/profiles/` (runtime-neutral domain/workflow/stack presets)
+- `~/.config/mosaic/runtime/` (runtime-specific overlays)
+- `~/.config/mosaic/skills-local/` (local private skills shared across runtimes)
diff --git a/adapters/claude.md b/adapters/claude.md
index 4c73539..ae8d94a 100644
--- a/adapters/claude.md
+++ b/adapters/claude.md
@@ -4,14 +4,14 @@ Use this adapter when running Claude CLI sessions.
 
 ## Required Context
 
-1. `~/.mosaic/STANDARDS.md`
+1. `~/.config/mosaic/STANDARDS.md`
 2. `<repo>/AGENTS.md`
 
 ## Command Wrapper
 
-Use wrapper commands from `~/.mosaic/bin/` for lifecycle rituals.
+Use wrapper commands from `~/.config/mosaic/bin/` for lifecycle rituals.
 
 ## Migration Note
 
 Project-local `.claude/commands/*.md` should call `scripts/agent/*.sh` so behavior stays runtime-neutral.
-Guides and rails should resolve to `~/.mosaic/guides` and `~/.mosaic/rails` (linked into `~/.claude` for compatibility).
+Guides and rails should resolve to `~/.config/mosaic/guides` and `~/.config/mosaic/rails` (linked into `~/.claude` for compatibility).
diff --git a/adapters/codex.md b/adapters/codex.md
index dada518..0609a3b 100644
--- a/adapters/codex.md
+++ b/adapters/codex.md
@@ -4,7 +4,7 @@ Use this adapter when running Codex CLI sessions.
 
 ## Required Context
 
-1. `~/.mosaic/STANDARDS.md`
+1. `~/.config/mosaic/STANDARDS.md`
 2. `<repo>/AGENTS.md`
 
 ## Runtime Behavior
diff --git a/adapters/generic.md b/adapters/generic.md
index e47a9d7..548946a 100644
--- a/adapters/generic.md
+++ b/adapters/generic.md
@@ -4,7 +4,7 @@ For runtimes without a first-class adapter yet.
 
 ## Required Context
 
-1. Load `~/.mosaic/STANDARDS.md`
+1. Load `~/.config/mosaic/STANDARDS.md`
 2. Load project `AGENTS.md`
 
 ## Minimal Contract
diff --git a/bin/mosaic-bootstrap-repo b/bin/mosaic-bootstrap-repo
index 429ffd1..90dae9e 100755
--- a/bin/mosaic-bootstrap-repo
+++ b/bin/mosaic-bootstrap-repo
@@ -27,12 +27,12 @@ if [[ ! -d "$TARGET_DIR" ]]; then
   exit 1
 fi
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 TEMPLATE_ROOT="$MOSAIC_HOME/templates/repo"
 
 if [[ ! -d "$TEMPLATE_ROOT" ]]; then
   echo "[mosaic] Missing templates at $TEMPLATE_ROOT" >&2
-  echo "[mosaic] Install or refresh framework: ~/.mosaic/install.sh" >&2
+  echo "[mosaic] Install or refresh framework: ~/.config/mosaic/install.sh" >&2
   exit 1
 fi
 
@@ -74,7 +74,7 @@ if [[ ! -f "$TARGET_DIR/AGENTS.md" ]]; then
 
 ## Standards Load Order
 
-1. `~/.mosaic/STANDARDS.md`
+1. `~/.config/mosaic/STANDARDS.md`
 2. `AGENTS.md` (this file)
 3. `.mosaic/repo-hooks.sh`
 
@@ -88,8 +88,8 @@ bash scripts/agent/session-end.sh
 
 ## Shared Rails
 
-- Quality and orchestration guides: `~/.mosaic/guides/`
-- Shared automation rails: `~/.mosaic/rails/`
+- Quality and orchestration guides: `~/.config/mosaic/guides/`
+- Shared automation rails: `~/.config/mosaic/rails/`
 
 ## Repo-Specific Notes
 
@@ -103,8 +103,8 @@ fi
 
 echo "[mosaic] Repo bootstrap complete: $TARGET_DIR"
 echo "[mosaic] Next: edit $TARGET_DIR/.mosaic/repo-hooks.sh with project workflows"
-echo "[mosaic] Optional: apply quality rails via ~/.mosaic/bin/mosaic-quality-apply --template <template> --target $TARGET_DIR"
-echo "[mosaic] Optional: run orchestrator rail via ~/.mosaic/bin/mosaic-orchestrator-matrix-cycle"
+echo "[mosaic] Optional: apply quality rails via ~/.config/mosaic/bin/mosaic-quality-apply --template <template> --target $TARGET_DIR"
+echo "[mosaic] Optional: run orchestrator rail via ~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle"
 
 if [[ -n "$QUALITY_TEMPLATE" ]]; then
   if [[ -x "$MOSAIC_HOME/bin/mosaic-quality-apply" ]]; then
diff --git a/bin/mosaic-doctor b/bin/mosaic-doctor
index 734a746..10247ea 100755
--- a/bin/mosaic-doctor
+++ b/bin/mosaic-doctor
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 FAIL_ON_WARN=0
 VERBOSE=0
 
diff --git a/bin/mosaic-link-runtime-assets b/bin/mosaic-link-runtime-assets
index 09cd418..877915b 100755
--- a/bin/mosaic-link-runtime-assets
+++ b/bin/mosaic-link-runtime-assets
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 backup_stamp="$(date +%Y%m%d%H%M%S)"
 
 copy_file_managed() {
diff --git a/bin/mosaic-migrate-local-skills b/bin/mosaic-migrate-local-skills
index 823a6ca..e3597d1 100755
--- a/bin/mosaic-migrate-local-skills
+++ b/bin/mosaic-migrate-local-skills
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 APPLY=0
 
 usage() {
@@ -9,7 +9,7 @@ usage() {
 Usage: $(basename "$0") [--apply]
 
 Migrate runtime-local skill directories (e.g. ~/.claude/skills/jarvis) to Mosaic-managed
-skills by replacing local directories with symlinks to ~/.mosaic/skills-local.
+skills by replacing local directories with symlinks to ~/.config/mosaic/skills-local.
 
 Default mode is dry-run.
 USAGE
diff --git a/bin/mosaic-orchestrator-matrix-consume b/bin/mosaic-orchestrator-matrix-consume
index 21fd8d3..9658794 100755
--- a/bin/mosaic-orchestrator-matrix-consume
+++ b/bin/mosaic-orchestrator-matrix-consume
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 BRIDGE="$MOSAIC_HOME/rails/orchestrator-matrix/transport/matrix_transport.py"
 
 if [[ ! -f "$BRIDGE" ]]; then
diff --git a/bin/mosaic-orchestrator-matrix-cycle b/bin/mosaic-orchestrator-matrix-cycle
index 164d5cf..aa04896 100755
--- a/bin/mosaic-orchestrator-matrix-cycle
+++ b/bin/mosaic-orchestrator-matrix-cycle
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 
 consume="$MOSAIC_HOME/bin/mosaic-orchestrator-matrix-consume"
 run="$MOSAIC_HOME/bin/mosaic-orchestrator-run"
diff --git a/bin/mosaic-orchestrator-matrix-publish b/bin/mosaic-orchestrator-matrix-publish
index f438480..005591b 100755
--- a/bin/mosaic-orchestrator-matrix-publish
+++ b/bin/mosaic-orchestrator-matrix-publish
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 BRIDGE="$MOSAIC_HOME/rails/orchestrator-matrix/transport/matrix_transport.py"
 
 if [[ ! -f "$BRIDGE" ]]; then
diff --git a/bin/mosaic-orchestrator-run b/bin/mosaic-orchestrator-run
index 9e934e0..178aa6c 100755
--- a/bin/mosaic-orchestrator-run
+++ b/bin/mosaic-orchestrator-run
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 CTRL="$MOSAIC_HOME/rails/orchestrator-matrix/controller/mosaic_orchestrator.py"
 
 if [[ ! -f "$CTRL" ]]; then
diff --git a/bin/mosaic-prune-legacy-runtime b/bin/mosaic-prune-legacy-runtime
index a409e1b..b402c21 100755
--- a/bin/mosaic-prune-legacy-runtime
+++ b/bin/mosaic-prune-legacy-runtime
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 RUNTIME="claude"
 APPLY=0
 
@@ -10,7 +10,7 @@ usage() {
 Usage: $(basename "$0") [options]
 
 Remove legacy runtime files that were preserved as *.mosaic-bak-* after Mosaic linking.
-Only removes backups when the active file is a symlink to ~/.mosaic.
+Only removes backups when the active file is a symlink to ~/.config/mosaic.
 
 Options:
   --runtime <name>   Runtime to prune (default: claude)
diff --git a/bin/mosaic-quality-apply b/bin/mosaic-quality-apply
index 8535f07..98fd1ae 100755
--- a/bin/mosaic-quality-apply
+++ b/bin/mosaic-quality-apply
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 TARGET_DIR="$(pwd)"
 TEMPLATE=""
 
diff --git a/bin/mosaic-quality-verify b/bin/mosaic-quality-verify
index 423882d..c52ca1a 100755
--- a/bin/mosaic-quality-verify
+++ b/bin/mosaic-quality-verify
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 TARGET_DIR="$(pwd)"
 
 usage() {
diff --git a/bin/mosaic-sync-skills b/bin/mosaic-sync-skills
index 3dd6197..68abc18 100755
--- a/bin/mosaic-sync-skills
+++ b/bin/mosaic-sync-skills
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 SKILLS_REPO_URL="${MOSAIC_SKILLS_REPO_URL:-https://git.mosaicstack.dev/mosaic/agent-skills.git}"
 SKILLS_REPO_DIR="${MOSAIC_SKILLS_REPO_DIR:-$MOSAIC_HOME/sources/agent-skills}"
 MOSAIC_SKILLS_DIR="$MOSAIC_HOME/skills"
@@ -14,17 +14,17 @@ usage() {
   cat <<USAGE
 Usage: $(basename "$0") [options]
 
-Sync canonical skills into ~/.mosaic/skills and link all Mosaic skills into runtime skill directories.
+Sync canonical skills into ~/.config/mosaic/skills and link all Mosaic skills into runtime skill directories.
 
 Options:
-  --link-only     Skip git clone/pull and only relink from ~/.mosaic/{skills,skills-local}
+  --link-only     Skip git clone/pull and only relink from ~/.config/mosaic/{skills,skills-local}
   --no-link       Sync canonical skills but do not update runtime links
   -h, --help      Show help
 
 Env:
-  MOSAIC_HOME               Default: ~/.mosaic
+  MOSAIC_HOME               Default: ~/.config/mosaic
   MOSAIC_SKILLS_REPO_URL    Default: https://git.mosaicstack.dev/mosaic/agent-skills.git
-  MOSAIC_SKILLS_REPO_DIR    Default: ~/.mosaic/sources/agent-skills
+  MOSAIC_SKILLS_REPO_DIR    Default: ~/.config/mosaic/sources/agent-skills
 USAGE
 }
 
diff --git a/bin/mosaic-upgrade-slaves b/bin/mosaic-upgrade-slaves
index 7b75eef..6b18f8b 100755
--- a/bin/mosaic-upgrade-slaves
+++ b/bin/mosaic-upgrade-slaves
@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.mosaic}"
+MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 BOOTSTRAP_CMD="$MOSAIC_HOME/bin/mosaic-bootstrap-repo"
 
 roots=("$HOME/src")
@@ -45,7 +45,7 @@ done
 
 if [[ ! -x "$BOOTSTRAP_CMD" ]]; then
   echo "[mosaic-upgrade] Missing bootstrap command: $BOOTSTRAP_CMD" >&2
-  echo "[mosaic-upgrade] Install/refresh framework first: ~/.mosaic/install.sh" >&2
+  echo "[mosaic-upgrade] Install/refresh framework first: ~/.config/mosaic/install.sh" >&2
   exit 1
 fi
 
diff --git a/guides/authentication.md b/guides/authentication.md
index 73ec044..9ae2e8f 100644
--- a/guides/authentication.md
+++ b/guides/authentication.md
@@ -1,7 +1,7 @@
 # Authentication & Authorization Guide
 
 ## Before Starting
-1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
+1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
 2. Review existing auth implementation in codebase
 3. Review Vault secrets structure: `docs/vault-secrets-structure.md`
 
diff --git a/guides/backend.md b/guides/backend.md
index de9dab6..6931282 100644
--- a/guides/backend.md
+++ b/guides/backend.md
@@ -1,7 +1,7 @@
 # Backend Development Guide
 
 ## Before Starting
-1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
+1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
 2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
 3. Review API contracts and database schema
 
@@ -47,7 +47,7 @@
 - Use project's established auth pattern
 - Validate tokens on every request
 - Check permissions before operations
-- See `~/.mosaic/guides/authentication.md` for details
+- See `~/.config/mosaic/guides/authentication.md` for details
 
 ## Testing Requirements (TDD)
 1. Write tests BEFORE implementation
@@ -73,7 +73,7 @@ class TestResourceEndpoint:
 
 ## Code Style
 - Follow Google Style Guide for your language
-- **TypeScript: Follow `~/.mosaic/guides/typescript.md` — MANDATORY**
+- **TypeScript: Follow `~/.config/mosaic/guides/typescript.md` — MANDATORY**
 - Use linter/formatter from project configuration
 - Keep functions focused and small
 - Document complex business logic
diff --git a/guides/bootstrap.md b/guides/bootstrap.md
index 018a90d..e109020 100644
--- a/guides/bootstrap.md
+++ b/guides/bootstrap.md
@@ -15,7 +15,7 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
 
 ```bash
 # Automated bootstrap (recommended)
-~/.mosaic/rails/bootstrap/init-project.sh \
+~/.config/mosaic/rails/bootstrap/init-project.sh \
   --name "my-project" \
   --type "nestjs-nextjs" \
   --repo "https://git.mosaicstack.dev/owner/repo"
@@ -24,8 +24,8 @@ This guide covers how to bootstrap a project so AI agents (Claude, Codex, etc.)
 export PROJECT_NAME="My Project"
 export PROJECT_DESCRIPTION="What this project does"
 export TASK_PREFIX="MP"
-envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
-envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
+envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
+envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
 ```
 
 ---
@@ -86,12 +86,12 @@ export TASK_PREFIX="MP"
 
 # Use tech-stack-specific template if available
 TYPE=$(detect_project_type)
-TEMPLATE_DIR="$HOME/.mosaic/templates/agent/projects/$TYPE"
+TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
 
 if [[ -d "$TEMPLATE_DIR" ]]; then
   envsubst < "$TEMPLATE_DIR/CLAUDE.md.template" > CLAUDE.md
 else
-  envsubst < "$HOME/.mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
+  envsubst < "$HOME/.config/mosaic/templates/agent/CLAUDE.md.template" > CLAUDE.md
 fi
 ```
 
@@ -116,7 +116,7 @@ export LINT_COMMAND="ruff check ."
 export TYPECHECK_COMMAND="mypy ."
 export QUALITY_GATES="ruff check . && mypy . && pytest tests/"
 
-envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
+envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
 ```
 
 ### Required Sections
@@ -141,12 +141,12 @@ The `AGENTS.md` file contains agent-specific patterns, gotchas, and orchestrator
 
 ```bash
 TYPE=$(detect_project_type)
-TEMPLATE_DIR="$HOME/.mosaic/templates/agent/projects/$TYPE"
+TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent/projects/$TYPE"
 
 if [[ -d "$TEMPLATE_DIR" ]]; then
   envsubst < "$TEMPLATE_DIR/AGENTS.md.template" > AGENTS.md
 else
-  envsubst < "$HOME/.mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
+  envsubst < "$HOME/.config/mosaic/templates/agent/AGENTS.md.template" > AGENTS.md
 fi
 ```
 
@@ -175,10 +175,10 @@ mkdir -p docs/reports
 
 ```bash
 # Use the init script
-~/.mosaic/rails/bootstrap/init-repo-labels.sh
+~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
 
 # Or manually create standard labels
-~/.mosaic/rails/git/issue-create.sh  # (labels are created on first use)
+~/.config/mosaic/rails/git/issue-create.sh  # (labels are created on first use)
 ```
 
 ### Standard Labels
@@ -198,7 +198,7 @@ mkdir -p docs/reports
 Create the first milestone for MVP:
 
 ```bash
-~/.mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
+~/.config/mosaic/rails/git/milestone-create.sh -t "0.1.0" -d "MVP - Minimum Viable Product"
 ```
 
 ---
@@ -210,8 +210,8 @@ Create the first milestone for MVP:
 ```bash
 # Copy Codex review pipeline
 mkdir -p .woodpecker/schemas
-cp ~/.mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
-cp ~/.mosaic/rails/codex/schemas/*.json .woodpecker/schemas/
+cp ~/.config/mosaic/rails/codex/woodpecker/codex-review.yml .woodpecker/
+cp ~/.config/mosaic/rails/codex/schemas/*.json .woodpecker/schemas/
 
 # Add codex_api_key secret to Woodpecker CI dashboard
 ```
@@ -243,7 +243,7 @@ grep -c "Code Review" CLAUDE.md
 eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
 
 # Test Codex review (if configured)
-~/.mosaic/rails/codex/codex-code-review.sh --help
+~/.config/mosaic/rails/codex/codex-code-review.sh --help
 ```
 
 ---
@@ -254,15 +254,15 @@ eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
 
 | Template | Path | Purpose |
 |----------|------|---------|
-| `CLAUDE.md.template` | `~/.mosaic/templates/agent/` | Generic project CLAUDE.md |
-| `AGENTS.md.template` | `~/.mosaic/templates/agent/` | Generic agent context |
+| `CLAUDE.md.template` | `~/.config/mosaic/templates/agent/` | Generic project CLAUDE.md |
+| `AGENTS.md.template` | `~/.config/mosaic/templates/agent/` | Generic agent context |
 
 ### Tech-Stack Templates
 
 | Stack | Path | Includes |
 |-------|------|----------|
-| NestJS + Next.js | `~/.mosaic/templates/agent/projects/nestjs-nextjs/` | CLAUDE.md, AGENTS.md |
-| Django | `~/.mosaic/templates/agent/projects/django/` | CLAUDE.md, AGENTS.md |
+| NestJS + Next.js | `~/.config/mosaic/templates/agent/projects/nestjs-nextjs/` | CLAUDE.md, AGENTS.md |
+| Django | `~/.config/mosaic/templates/agent/projects/django/` | CLAUDE.md, AGENTS.md |
 
 ### Orchestrator Templates
 
@@ -305,7 +305,7 @@ eval "$(grep -A1 'Quality Gates' CLAUDE.md | tail -1)"
 Full project bootstrap with interactive and flag-based modes:
 
 ```bash
-~/.mosaic/rails/bootstrap/init-project.sh \
+~/.config/mosaic/rails/bootstrap/init-project.sh \
   --name "My Project" \
   --type "nestjs-nextjs" \
   --repo "https://git.mosaicstack.dev/owner/repo" \
@@ -318,7 +318,7 @@ Full project bootstrap with interactive and flag-based modes:
 Initialize standard labels and MVP milestone:
 
 ```bash
-~/.mosaic/rails/bootstrap/init-repo-labels.sh
+~/.config/mosaic/rails/bootstrap/init-repo-labels.sh
 ```
 
 ---
@@ -335,4 +335,4 @@ After bootstrapping, verify:
 - [ ] Quality gates run successfully
 - [ ] `.env.example` exists (if project uses env vars)
 - [ ] CI/CD pipeline configured (if using Woodpecker/GitHub Actions)
-- [ ] Codex review scripts accessible (`~/.mosaic/rails/codex/`)
+- [ ] Codex review scripts accessible (`~/.config/mosaic/rails/codex/`)
diff --git a/guides/code-review.md b/guides/code-review.md
index 8d5c7b5..aa2e95c 100644
--- a/guides/code-review.md
+++ b/guides/code-review.md
@@ -64,7 +64,7 @@
 ### Getting Context
 ```bash
 # List the issue being addressed
-~/.mosaic/rails/git/issue-list.sh -i {issue-number}
+~/.config/mosaic/rails/git/issue-list.sh -i {issue-number}
 
 # View the changes
 git diff main...HEAD
diff --git a/guides/frontend.md b/guides/frontend.md
index 60be386..509330c 100644
--- a/guides/frontend.md
+++ b/guides/frontend.md
@@ -1,7 +1,7 @@
 # Frontend Development Guide
 
 ## Before Starting
-1. Check assigned issue in git repo: `~/.mosaic/rails/git/issue-list.sh -a @me`
+1. Check assigned issue in git repo: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
 2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
 3. Review existing components and patterns in the codebase
 
@@ -49,7 +49,7 @@ describe('ComponentName', () => {
 
 ## Code Style
 - Follow Google JavaScript/TypeScript Style Guide
-- **TypeScript: Follow `~/.mosaic/guides/typescript.md` — MANDATORY**
+- **TypeScript: Follow `~/.config/mosaic/guides/typescript.md` — MANDATORY**
 - Use ESLint/Prettier configuration from project
 - Prefer functional components over class components (React)
 - TypeScript strict mode is REQUIRED, not optional
diff --git a/guides/infrastructure.md b/guides/infrastructure.md
index d1a8b53..45f68ec 100644
--- a/guides/infrastructure.md
+++ b/guides/infrastructure.md
@@ -1,7 +1,7 @@
 # Infrastructure & DevOps Guide
 
 ## Before Starting
-1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
+1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
 2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
 3. Review existing infrastructure configuration
 
diff --git a/guides/orchestrator.md b/guides/orchestrator.md
index 5b74e4c..29e89cd 100644
--- a/guides/orchestrator.md
+++ b/guides/orchestrator.md
@@ -50,8 +50,8 @@ Choose one delegation mode at session start:
 Matrix rail mode commands:
 
 ```bash
-~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
-~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
+~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
 ```
 
 In Matrix rail mode, keep `docs/tasks.md` as canonical project tracking and use
@@ -186,7 +186,7 @@ Use these heuristics based on task type:
 Create ONE issue per phase using git scripts:
 
 ```bash
-~/.mosaic/rails/git/issue-create.sh \
+~/.config/mosaic/rails/git/issue-create.sh \
   -t "Phase 1: Critical Security Fixes" \
   -b "$(cat <<'EOF'
 ## Findings
@@ -309,10 +309,10 @@ Run review when the worker's result includes code changes (commits). Skip for ta
 cd {project_path}
 
 # Code quality review
-~/.mosaic/rails/codex/codex-code-review.sh -b {base_branch} -o /tmp/review-{task_id}.json
+~/.config/mosaic/rails/codex/codex-code-review.sh -b {base_branch} -o /tmp/review-{task_id}.json
 
 # Security review
-~/.mosaic/rails/codex/codex-security-review.sh -b {base_branch} -o /tmp/security-{task_id}.json
+~/.config/mosaic/rails/codex/codex-security-review.sh -b {base_branch} -o /tmp/security-{task_id}.json
 ```
 
 ### Step 2: Parse Review Results
@@ -373,7 +373,7 @@ Review the code changes on branch {branch} against {base_branch}.
    - Security (OWASP Top 10, secrets, injection)
    - Testing (coverage, quality)
    - Code quality (complexity, duplication)
-3. Reference: ~/.mosaic/guides/code-review.md
+3. Reference: ~/.config/mosaic/guides/code-review.md
 
 Report findings as JSON:
 ```json
@@ -448,8 +448,8 @@ Construct this from the task row and pass to worker via Task tool:
 ## Git Scripts
 
 For issue/PR/milestone operations, use scripts (NOT raw tea/gh):
-- `~/.mosaic/rails/git/issue-view.sh -i {N}`
-- `~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B develop`
+- `~/.config/mosaic/rails/git/issue-view.sh -i {N}`
+- `~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Desc" -B develop`
 
 Standard git commands (pull, commit, push, checkout) are fine.
 
@@ -706,7 +706,7 @@ Next: MS-SEC-004
 
 ### Cross-Project Learnings
 
-Universal heuristics are maintained in `~/.mosaic/guides/orchestrator-learnings.md`.
+Universal heuristics are maintained in `~/.config/mosaic/guides/orchestrator-learnings.md`.
 After completing a milestone, review variance patterns and propose updates to the universal guide.
 
 ---
@@ -858,7 +858,7 @@ Remediate findings from the codebase review.
 - Task prefix: {PREFIX} (e.g., MS, UC)
 
 ## Protocol
-Read ~/.mosaic/guides/orchestrator.md for full instructions.
+Read ~/.config/mosaic/guides/orchestrator.md for full instructions.
 
 ## Start
 Bootstrap from the review report, then execute until complete.
diff --git a/guides/qa-testing.md b/guides/qa-testing.md
index e849057..4b230f0 100644
--- a/guides/qa-testing.md
+++ b/guides/qa-testing.md
@@ -1,7 +1,7 @@
 # QA & Testing Guide
 
 ## Before Starting
-1. Check assigned issue: `~/.mosaic/rails/git/issue-list.sh -a @me`
+1. Check assigned issue: `~/.config/mosaic/rails/git/issue-list.sh -a @me`
 2. Create scratchpad: `docs/scratchpads/{issue-number}-{short-name}.md`
 3. Review existing test structure and patterns
 
diff --git a/install.sh b/install.sh
index 02ab3e5..1f254a1 100755
--- a/install.sh
+++ b/install.sh
@@ -2,7 +2,7 @@
 set -euo pipefail
 
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TARGET_DIR="${MOSAIC_HOME:-$HOME/.mosaic}"
+TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 
 mkdir -p "$TARGET_DIR"
 
@@ -39,7 +39,7 @@ fi
 
 echo "[mosaic-install] Running health audit"
 if ! "$TARGET_DIR/bin/mosaic-doctor"; then
-  echo "[mosaic-install] WARNING: doctor reported issues (run ~/.mosaic/bin/mosaic-doctor --fail-on-warn)" >&2
+  echo "[mosaic-install] WARNING: doctor reported issues (run ~/.config/mosaic/bin/mosaic-doctor --fail-on-warn)" >&2
 fi
 
 echo "[mosaic-install] Add to PATH: export PATH=\"$TARGET_DIR/bin:$PATH\""
diff --git a/profiles/README.md b/profiles/README.md
index 630be3d..5c43691 100644
--- a/profiles/README.md
+++ b/profiles/README.md
@@ -10,12 +10,12 @@ Profiles are runtime-neutral context packs that can be consumed by any agent run
 
 ## Runtime Split
 
-- Runtime-neutral content belongs here under `~/.mosaic/profiles`.
-- Runtime-specific settings belong under `~/.mosaic/runtime/<runtime>/...`.
+- Runtime-neutral content belongs here under `~/.config/mosaic/profiles`.
+- Runtime-specific settings belong under `~/.config/mosaic/runtime/<runtime>/...`.
 
 Current runtime overlay example:
 
-- `~/.mosaic/runtime/claude/settings-overlays/jarvis-ralph.json`
+- `~/.config/mosaic/runtime/claude/settings-overlays/jarvis-ralph.json`
 
 ## Claude Compatibility
 
diff --git a/rails/bootstrap/agent-lint.sh b/rails/bootstrap/agent-lint.sh
index 762b012..6e08ab3 100755
--- a/rails/bootstrap/agent-lint.sh
+++ b/rails/bootstrap/agent-lint.sh
@@ -105,7 +105,7 @@ check_agents_md() {
 # Check conditional loading/context (references guides or conditional section)
 check_conditional_loading() {
   local claude_md="$1/CLAUDE.md"
-  [[ -f "$claude_md" ]] && grep -qi "agent-guides\|~/.mosaic/guides\|conditional.*loading\|conditional.*documentation\|conditional.*context" "$claude_md" 2>/dev/null
+  [[ -f "$claude_md" ]] && grep -qi "agent-guides\|~/.config/mosaic/guides\|conditional.*loading\|conditional.*documentation\|conditional.*context" "$claude_md" 2>/dev/null
 }
 
 # Check quality gates
@@ -214,9 +214,9 @@ JSONEOF
 
   if $FIX_HINT && ! $JSON_OUTPUT; then
     if [[ "$has_claude" == "MISS" || "$has_agents" == "MISS" ]]; then
-      echo "    ${DIM}Fix: ~/.mosaic/rails/bootstrap/init-project.sh --name \"$name\" --type auto${NC}"
+      echo "    ${DIM}Fix: ~/.config/mosaic/rails/bootstrap/init-project.sh --name \"$name\" --type auto${NC}"
     elif [[ "$has_guides" == "MISS" ]]; then
-      echo "    ${DIM}Fix: ~/.mosaic/rails/bootstrap/agent-upgrade.sh $dir --section conditional-loading${NC}"
+      echo "    ${DIM}Fix: ~/.config/mosaic/rails/bootstrap/agent-upgrade.sh $dir --section conditional-loading${NC}"
     fi
   fi
 
diff --git a/rails/bootstrap/agent-upgrade.sh b/rails/bootstrap/agent-upgrade.sh
index c642503..6c30acb 100755
--- a/rails/bootstrap/agent-upgrade.sh
+++ b/rails/bootstrap/agent-upgrade.sh
@@ -18,8 +18,8 @@ set -euo pipefail
 
 # Defaults
 SRC_DIR="$HOME/src"
-FRAGMENTS_DIR="$HOME/.mosaic/templates/agent/fragments"
-TEMPLATES_DIR="$HOME/.mosaic/templates/agent"
+FRAGMENTS_DIR="$HOME/.config/mosaic/templates/agent/fragments"
+TEMPLATES_DIR="$HOME/.config/mosaic/templates/agent"
 DRY_RUN=false
 ALL_PROJECTS=false
 TARGET_PATH=""
@@ -135,7 +135,7 @@ inject_fragment() {
   # Determine detection pattern for this fragment
   local detect_pattern
   case "$fragment_name" in
-    conditional-loading) detect_pattern="agent-guides\|~/.mosaic/guides\|Conditional.*Loading\|Conditional.*Documentation\|Conditional.*Context" ;;
+    conditional-loading) detect_pattern="agent-guides\|~/.config/mosaic/guides\|Conditional.*Loading\|Conditional.*Documentation\|Conditional.*Context" ;;
     commit-format) detect_pattern="<type>.*#issue\|Types:.*feat.*fix" ;;
     secrets) detect_pattern="NEVER hardcode secrets\|\.env.example.*committed" ;;
     multi-agent) detect_pattern="Multi-Agent Coordination\|pull --rebase.*before" ;;
diff --git a/rails/bootstrap/init-project.sh b/rails/bootstrap/init-project.sh
index 8a3eb3d..202585e 100755
--- a/rails/bootstrap/init-project.sh
+++ b/rails/bootstrap/init-project.sh
@@ -8,8 +8,8 @@
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-TEMPLATE_DIR="$HOME/.mosaic/templates/agent"
-GIT_SCRIPT_DIR="$HOME/.mosaic/rails/git"
+TEMPLATE_DIR="$HOME/.config/mosaic/templates/agent"
+GIT_SCRIPT_DIR="$HOME/.config/mosaic/rails/git"
 
 # Defaults
 PROJECT_NAME=""
@@ -373,7 +373,7 @@ echo "Created docs/scratchpads/, docs/reports/, docs/templates/"
 
 # Set up CI/CD pipeline
 if [[ "$SKIP_CI" != true ]]; then
-    CODEX_DIR="$HOME/.mosaic/rails/codex"
+    CODEX_DIR="$HOME/.config/mosaic/rails/codex"
     if [[ -d "$CODEX_DIR/woodpecker" ]]; then
         mkdir -p .woodpecker/schemas
         cp "$CODEX_DIR/woodpecker/codex-review.yml" .woodpecker/
@@ -386,7 +386,7 @@ fi
 
 # Generate Docker build/push/link pipeline steps
 if [[ "$CICD_DOCKER" == true ]]; then
-    CICD_SCRIPT="$HOME/.mosaic/rails/cicd/generate-docker-steps.sh"
+    CICD_SCRIPT="$HOME/.config/mosaic/rails/cicd/generate-docker-steps.sh"
     if [[ -x "$CICD_SCRIPT" ]]; then
         # Parse org and repo from git remote
         CICD_REGISTRY=""
diff --git a/rails/bootstrap/init-repo-labels.sh b/rails/bootstrap/init-repo-labels.sh
index d888810..0a093b2 100755
--- a/rails/bootstrap/init-repo-labels.sh
+++ b/rails/bootstrap/init-repo-labels.sh
@@ -7,7 +7,7 @@
 set -e
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-GIT_SCRIPT_DIR="$HOME/.mosaic/rails/git"
+GIT_SCRIPT_DIR="$HOME/.config/mosaic/rails/git"
 source "$GIT_SCRIPT_DIR/detect-platform.sh"
 
 SKIP_MILESTONE=false
diff --git a/rails/codex/README.md b/rails/codex/README.md
index 4f27533..dd1bf96 100644
--- a/rails/codex/README.md
+++ b/rails/codex/README.md
@@ -50,45 +50,45 @@ Security vulnerability review focusing on:
 
 ```bash
 # Code review
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 ### Review a Pull Request
 
 ```bash
 # Review and post findings as a PR comment
-~/.mosaic/rails/codex/codex-code-review.sh -n 42
+~/.config/mosaic/rails/codex/codex-code-review.sh -n 42
 
 # Security review and post to PR
-~/.mosaic/rails/codex/codex-security-review.sh -n 42
+~/.config/mosaic/rails/codex/codex-security-review.sh -n 42
 ```
 
 ### Review Against Base Branch
 
 ```bash
 # Code review changes vs main
-~/.mosaic/rails/codex/codex-code-review.sh -b main
+~/.config/mosaic/rails/codex/codex-code-review.sh -b main
 
 # Security review changes vs develop
-~/.mosaic/rails/codex/codex-security-review.sh -b develop
+~/.config/mosaic/rails/codex/codex-security-review.sh -b develop
 ```
 
 ### Review a Specific Commit
 
 ```bash
-~/.mosaic/rails/codex/codex-code-review.sh -c abc123f
-~/.mosaic/rails/codex/codex-security-review.sh -c abc123f
+~/.config/mosaic/rails/codex/codex-code-review.sh -c abc123f
+~/.config/mosaic/rails/codex/codex-security-review.sh -c abc123f
 ```
 
 ### Save Results to File
 
 ```bash
 # Save JSON output
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted -o review-results.json
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted -o security-results.json
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted -o review-results.json
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted -o security-results.json
 ```
 
 ## Options
@@ -113,12 +113,12 @@ Automated PR reviews in CI pipelines.
 
 1. **Copy the pipeline template to your repo:**
    ```bash
-   cp ~/.mosaic/rails/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
+   cp ~/.config/mosaic/rails/codex/woodpecker/codex-review.yml your-repo/.woodpecker/
    ```
 
 2. **Copy the schemas directory:**
    ```bash
-   cp -r ~/.mosaic/rails/codex/schemas your-repo/.woodpecker/
+   cp -r ~/.config/mosaic/rails/codex/schemas your-repo/.woodpecker/
    ```
 
 3. **Add Codex API key to Woodpecker:**
@@ -203,7 +203,7 @@ Automated PR reviews in CI pipelines.
 
 ## Platform Support
 
-Works with both **GitHub** and **Gitea** via the shared `~/.mosaic/rails/git/` infrastructure:
+Works with both **GitHub** and **Gitea** via the shared `~/.config/mosaic/rails/git/` infrastructure:
 - Auto-detects platform from git remote
 - Posts PR comments using `gh` (GitHub) or `tea` (Gitea)
 - Unified interface across both platforms
@@ -260,6 +260,6 @@ For best results, use `gpt-5.2-codex` or newer for strongest review accuracy.
 
 ## See Also
 
-- `~/.mosaic/guides/code-review.md` — Manual code review checklist
-- `~/.mosaic/rails/git/` — Git helper scripts (issue/PR management)
+- `~/.config/mosaic/guides/code-review.md` — Manual code review checklist
+- `~/.config/mosaic/rails/git/` — Git helper scripts (issue/PR management)
 - OpenAI Codex CLI docs: https://developers.openai.com/codex/cli/
diff --git a/rails/orchestrator-matrix/README.md b/rails/orchestrator-matrix/README.md
index f498456..a860e97 100644
--- a/rails/orchestrator-matrix/README.md
+++ b/rails/orchestrator-matrix/README.md
@@ -35,26 +35,26 @@ The controller expects this layout in each bootstrapped repo:
 From a bootstrapped repo:
 
 ```bash
-~/.mosaic/bin/mosaic-orchestrator-matrix-cycle
-~/.mosaic/bin/mosaic-orchestrator-run --once
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle
+~/.config/mosaic/bin/mosaic-orchestrator-run --once
 ```
 
 Continuous loop:
 
 ```bash
-~/.mosaic/bin/mosaic-orchestrator-run --poll-sec 10
+~/.config/mosaic/bin/mosaic-orchestrator-run --poll-sec 10
 ```
 
 Publish new orchestrator events to Matrix:
 
 ```bash
-~/.mosaic/bin/mosaic-orchestrator-matrix-publish
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-publish
 ```
 
 Consume Matrix task messages into `tasks.json`:
 
 ```bash
-~/.mosaic/bin/mosaic-orchestrator-matrix-consume
+~/.config/mosaic/bin/mosaic-orchestrator-matrix-consume
 ```
 
 ## Matrix Note
diff --git a/rails/qa/qa-hook-handler.sh b/rails/qa/qa-hook-handler.sh
index 4e55aff..5c70492 100755
--- a/rails/qa/qa-hook-handler.sh
+++ b/rails/qa/qa-hook-handler.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Universal QA hook handler with robust error handling
-# Location: ~/.mosaic/rails/qa/qa-hook-handler.sh
+# Location: ~/.config/mosaic/rails/qa/qa-hook-handler.sh
 
 # Don't exit on unset variables initially to handle missing params gracefully
 set -eo pipefail
diff --git a/rails/qa/qa-hook-stdin.sh b/rails/qa/qa-hook-stdin.sh
index a20d500..04dfe51 100755
--- a/rails/qa/qa-hook-stdin.sh
+++ b/rails/qa/qa-hook-stdin.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # QA Hook handler that reads from stdin
-# Location: ~/.mosaic/rails/qa/qa-hook-stdin.sh
+# Location: ~/.config/mosaic/rails/qa/qa-hook-stdin.sh
 
 set -eo pipefail
 
@@ -51,9 +51,9 @@ if ! [[ "$FILE_PATH" =~ \.(ts|tsx|js|jsx|mjs|cjs)$ ]]; then
 fi
 
 # Call the main QA handler with extracted parameters
-if [ -f ~/.mosaic/rails/qa/qa-hook-handler.sh ]; then
+if [ -f ~/.config/mosaic/rails/qa/qa-hook-handler.sh ]; then
     echo "[$(date '+%Y-%m-%d %H:%M:%S')] Calling QA handler for $FILE_PATH" >> "$LOG_FILE"
-    ~/.mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH" 2>&1 | tee -a "$LOG_FILE"
+    ~/.config/mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH" 2>&1 | tee -a "$LOG_FILE"
 else
     echo "[$(date '+%Y-%m-%d %H:%M:%S')] [ERROR] QA handler script not found" >> "$LOG_FILE"
 fi
diff --git a/rails/qa/qa-hook-wrapper.sh b/rails/qa/qa-hook-wrapper.sh
index d3d24a3..c3df942 100755
--- a/rails/qa/qa-hook-wrapper.sh
+++ b/rails/qa/qa-hook-wrapper.sh
@@ -13,7 +13,7 @@ echo "[$(date '+%Y-%m-%d %H:%M:%S')] Hook wrapper called: tool=$TOOL_NAME file=$
 
 # Call the actual QA handler if we have a file
 if [ -n "$FILE_PATH" ]; then
-    ~/.mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH"
+    ~/.config/mosaic/rails/qa/qa-hook-handler.sh "$TOOL_NAME" "$FILE_PATH"
 else
     echo "[$(date '+%Y-%m-%d %H:%M:%S')] No file path available for QA check" >> logs/qa-automation.log 2>/dev/null || true
 fi
diff --git a/rails/qa/qa-queue-monitor.sh b/rails/qa/qa-queue-monitor.sh
index 267ce47..9145910 100755
--- a/rails/qa/qa-queue-monitor.sh
+++ b/rails/qa/qa-queue-monitor.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Monitor QA queues with graceful handling of missing directories
-# Location: ~/.mosaic/rails/qa/qa-queue-monitor.sh
+# Location: ~/.config/mosaic/rails/qa/qa-queue-monitor.sh
 
 PROJECT_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || pwd)
 
diff --git a/rails/qa/remediation-hook-handler.sh b/rails/qa/remediation-hook-handler.sh
index 1b8fbb8..84a561b 100755
--- a/rails/qa/remediation-hook-handler.sh
+++ b/rails/qa/remediation-hook-handler.sh
@@ -1,6 +1,6 @@
 #!/bin/bash
 # Universal remediation hook handler with error recovery
-# Location: ~/.mosaic/rails/qa/remediation-hook-handler.sh
+# Location: ~/.config/mosaic/rails/qa/remediation-hook-handler.sh
 
 set -euo pipefail
 
diff --git a/rails/quality/README.md b/rails/quality/README.md
index f1120ac..44fa030 100644
--- a/rails/quality/README.md
+++ b/rails/quality/README.md
@@ -19,7 +19,7 @@ Based on real-world validation of 50 issues in a production codebase:
 ### New Project
 ```bash
 # Apply template from Mosaic
-~/.mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project
+~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/project
 
 # Install dependencies
 cd /path/to/project
@@ -29,13 +29,13 @@ npm install
 npx husky install
 
 # Verify enforcement is working
-~/.mosaic/bin/mosaic-quality-verify --target /path/to/project
+~/.config/mosaic/bin/mosaic-quality-verify --target /path/to/project
 ```
 
 ### Existing Project
 ```bash
 # Same as above - works for new or existing projects
-~/.mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
+~/.config/mosaic/bin/mosaic-quality-apply --template typescript-node --target /path/to/existing-project
 ```
 
 ## 🛡️ What You Get
diff --git a/rails/quality/scripts/install.sh b/rails/quality/scripts/install.sh
index fb85610..87a50fa 100755
--- a/rails/quality/scripts/install.sh
+++ b/rails/quality/scripts/install.sh
@@ -71,5 +71,5 @@ echo ""
 echo "Next steps:"
 echo "1. Install dependencies: npm install"
 echo "2. Initialize husky: npx husky install"
-echo "3. Run verification: ~/.mosaic/bin/mosaic-quality-verify --target $TARGET_DIR"
+echo "3. Run verification: ~/.config/mosaic/bin/mosaic-quality-verify --target $TARGET_DIR"
 echo ""
diff --git a/runtime/claude/CLAUDE.md b/runtime/claude/CLAUDE.md
index fa69d36..b35559f 100644
--- a/runtime/claude/CLAUDE.md
+++ b/runtime/claude/CLAUDE.md
@@ -1,10 +1,10 @@
 # Mosaic Universal Standards (Machine-Wide)
 
 Before applying any runtime-specific guidance in this file, load and apply:
-- `~/.mosaic/STANDARDS.md`
+- `~/.config/mosaic/STANDARDS.md`
 - project-local `AGENTS.md`
 
-`~/.mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
+`~/.config/mosaic` is the canonical cross-agent standards layer. This `CLAUDE.md` is an adapter layer for Claude-specific capabilities only.
 
 ---
 
@@ -17,11 +17,11 @@ Before applying any runtime-specific guidance in this file, load and apply:
 
 ## Skills System
 
-**Skills are available in `~/.mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
+**Skills are available in `~/.config/mosaic/skills/`.** Skills are instruction packages that provide domain expertise from `mosaic/agent-skills` plus local Mosaic skills.
 
 **Load a skill by reading its SKILL.md:**
 ```
-Read ~/.mosaic/skills/<skill-name>/SKILL.md
+Read ~/.config/mosaic/skills/<skill-name>/SKILL.md
 ```
 
 ### Skill Dispatch Table — Load the right skills for your task
@@ -66,7 +66,7 @@ Read ~/.mosaic/skills/<skill-name>/SKILL.md
 
 When spawning workers via `claude -p`, include skill loading in the kickstart:
 ```bash
-claude -p "Read ~/.mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
+claude -p "Read ~/.config/mosaic/skills/nestjs-best-practices/SKILL.md then implement..."
 ```
 
 For Ralph prd.json stories, add a `skills` field:
@@ -118,7 +118,7 @@ claude -p "Implement US-001 from prd.json following Ralph pattern"
 2. Convert to Ralph: `Load the ralph skill and convert tasks/prd-[name].md to prd.json`
 3. Run Ralph: `./scripts/ralph/ralph.sh`
 
-**For full Ralph guide:** `~/.mosaic/guides/ralph-autonomous.md`
+**For full Ralph guide:** `~/.config/mosaic/guides/ralph-autonomous.md`
 
 ## AGENTS.md Pattern
 
@@ -148,40 +148,40 @@ When starting work on a **new project** that lacks `CLAUDE.md` or `AGENTS.md`, b
 
 ```bash
 # Automated (recommended)
-~/.mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
+~/.config/mosaic/rails/bootstrap/init-project.sh --name "Project Name" --type auto
 
 # Or manually with templates
 export PROJECT_NAME="Project Name" PROJECT_DESCRIPTION="What it does" TASK_PREFIX="PN"
-envsubst < ~/.mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
-envsubst < ~/.mosaic/templates/agent/AGENTS.md.template > AGENTS.md
+envsubst < ~/.config/mosaic/templates/agent/CLAUDE.md.template > CLAUDE.md
+envsubst < ~/.config/mosaic/templates/agent/AGENTS.md.template > AGENTS.md
 ```
 
 **Available project types:** `nestjs-nextjs`, `django`, `typescript`, `python-fastapi`, `python-library`, `generic` (auto-detected from project files).
 
-**Templates:** `~/.mosaic/templates/agent/` (generic) and `~/.mosaic/templates/agent/projects/<type>/` (tech-stack specific).
+**Templates:** `~/.config/mosaic/templates/agent/` (generic) and `~/.config/mosaic/templates/agent/projects/<type>/` (tech-stack specific).
 
-**Fragments:** `~/.mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
+**Fragments:** `~/.config/mosaic/templates/agent/fragments/` — Reusable sections (conditional-loading, commit-format, secrets, multi-agent, code-review).
 
-**Full guide:** `~/.mosaic/guides/bootstrap.md`
+**Full guide:** `~/.config/mosaic/guides/bootstrap.md`
 
 ### Agent Configuration Health
 
 ```bash
 # Audit all projects for missing CLAUDE.md, AGENTS.md, agent-guide references
-~/.mosaic/rails/bootstrap/agent-lint.sh
+~/.config/mosaic/rails/bootstrap/agent-lint.sh
 
 # Audit with fix suggestions
-~/.mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
+~/.config/mosaic/rails/bootstrap/agent-lint.sh --verbose --fix-hint
 
 # Non-destructively upgrade existing projects (inject missing sections)
-~/.mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run   # Preview
-~/.mosaic/rails/bootstrap/agent-upgrade.sh --all             # Apply
+~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all --dry-run   # Preview
+~/.config/mosaic/rails/bootstrap/agent-upgrade.sh --all             # Apply
 
 # Upgrade a single project
-~/.mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
+~/.config/mosaic/rails/bootstrap/agent-upgrade.sh ~/src/my-project
 ```
 
-**Spec:** `~/.mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
+**Spec:** `~/.config/mosaic/templates/agent/SPEC.md` — Defines Tier 1/2/3 requirements for well-configured projects.
 
 ## Issue Tracking (Git-Based)
 
@@ -210,7 +210,7 @@ Use consistent labels across projects:
 - Post-release: `X.0.0` for breaking changes
 
 ### Git Scripts (PREFERRED for Gitea/GitHub operations)
-Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHub):
+Cross-platform helpers at `~/.config/mosaic/rails/git/` (work with both Gitea and GitHub):
 
 **Why use these scripts?**
 - ✅ Auto-detect platform (Gitea vs GitHub)
@@ -220,37 +220,37 @@ Cross-platform helpers at `~/.mosaic/rails/git/` (work with both Gitea and GitHu
 
 **Issues:**
 ```bash
-~/.mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
-~/.mosaic/rails/git/issue-list.sh -s open -l "bug"
-~/.mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration"  # Works with milestone names!
-~/.mosaic/rails/git/issue-view.sh -i 42                         # View issue details
-~/.mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
-~/.mosaic/rails/git/issue-assign.sh -i 42 -a "username"
-~/.mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
-~/.mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
-~/.mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
+~/.config/mosaic/rails/git/issue-create.sh -t "Title" -l "label" -m "0.2.0"
+~/.config/mosaic/rails/git/issue-list.sh -s open -l "bug"
+~/.config/mosaic/rails/git/issue-list.sh -m "M6-AgentOrchestration"  # Works with milestone names!
+~/.config/mosaic/rails/git/issue-view.sh -i 42                         # View issue details
+~/.config/mosaic/rails/git/issue-edit.sh -i 42 -t "New Title" -l "labels"
+~/.config/mosaic/rails/git/issue-assign.sh -i 42 -a "username"
+~/.config/mosaic/rails/git/issue-comment.sh -i 42 -c "Comment text"
+~/.config/mosaic/rails/git/issue-close.sh -i 42 [-c "Closing comment"]
+~/.config/mosaic/rails/git/issue-reopen.sh -i 42 [-c "Reopening reason"]
 ```
 
 **Pull Requests:**
 ```bash
-~/.mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
-~/.mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
-~/.mosaic/rails/git/pr-list.sh -s open
-~/.mosaic/rails/git/pr-view.sh -n 42                                    # View PR details
-~/.mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
-~/.mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
-~/.mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
-~/.mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
-~/.mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch]                         # Get PR diff
-~/.mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json]                  # Get PR metadata as JSON
+~/.config/mosaic/rails/git/pr-create.sh -t "Title" -b "Description" -i 42
+~/.config/mosaic/rails/git/pr-create.sh -t "Title" -B main -H feature-branch
+~/.config/mosaic/rails/git/pr-list.sh -s open
+~/.config/mosaic/rails/git/pr-view.sh -n 42                                    # View PR details
+~/.config/mosaic/rails/git/pr-review.sh -n 42 -a approve [-c "LGTM"]
+~/.config/mosaic/rails/git/pr-review.sh -n 42 -a request-changes -c "Fix X"
+~/.config/mosaic/rails/git/pr-merge.sh -n 42 -m squash -d
+~/.config/mosaic/rails/git/pr-close.sh -n 42 [-c "Closing reason"]
+~/.config/mosaic/rails/git/pr-diff.sh -n 42 [-o diff.patch]                         # Get PR diff
+~/.config/mosaic/rails/git/pr-metadata.sh -n 42 [-o metadata.json]                  # Get PR metadata as JSON
 ```
 
 **Milestones:**
 ```bash
-~/.mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
-~/.mosaic/rails/git/milestone-create.sh --list
-~/.mosaic/rails/git/milestone-list.sh [-s open|closed|all]
-~/.mosaic/rails/git/milestone-close.sh -t "0.2.0"
+~/.config/mosaic/rails/git/milestone-create.sh -t "0.2.0" -d "Description"
+~/.config/mosaic/rails/git/milestone-create.sh --list
+~/.config/mosaic/rails/git/milestone-list.sh [-s open|closed|all]
+~/.config/mosaic/rails/git/milestone-close.sh -t "0.2.0"
 ```
 
 **NOTE:** These scripts handle the Gitea `--milestones` (plural) syntax automatically. Always prefer these over raw `tea` or `gh` commands.
@@ -303,7 +303,7 @@ woodpecker secret rm <owner/repo> -n KEY         # Delete secret
 **Setup command:** `woodpecker setup --server https://ci.mosaicstack.dev --token "YOUR_TOKEN"`
 
 ### Portainer Scripts
-CLI tools for managing Portainer stacks at `~/.mosaic/rails/portainer/`.
+CLI tools for managing Portainer stacks at `~/.config/mosaic/rails/portainer/`.
 
 **Setup:**
 ```bash
@@ -345,9 +345,9 @@ endpoint-list.sh -f json                             # JSON format
 
 **Common Workflow (CI/CD redeploy):**
 ```bash
-~/.mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
-~/.mosaic/rails/portainer/stack-status.sh -n myapp && \
-~/.mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
+~/.config/mosaic/rails/portainer/stack-redeploy.sh -n myapp -p && \
+~/.config/mosaic/rails/portainer/stack-status.sh -n myapp && \
+~/.config/mosaic/rails/portainer/stack-logs.sh -n myapp -s api -t 50
 ```
 
 ### Git Worktrees
@@ -398,7 +398,7 @@ git worktree remove ../my-app_worktrees/42-fix-login
 - Never disable lint rules (`eslint-disable`, `noqa`, `nolint`)
 - Never leave warnings — warnings are errors you haven't fixed yet
 - If you touched a file, you own its lint violations (Campsite Rule)
-- If unsure what linter the project uses, read the `lint` skill: `~/.mosaic/skills/lint/SKILL.md`
+- If unsure what linter the project uses, read the `lint` skill: `~/.config/mosaic/skills/lint/SKILL.md`
 
 ### Code Style
 Follow [Google Style Guides](https://github.com/google/styleguide) for all languages.
@@ -443,30 +443,30 @@ When working on issue #N, create `docs/scratchpads/N-short-name.md`:
 
 | Task Type | Guide |
 |-----------|-------|
-| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous task completion | `~/.mosaic/guides/orchestrator.md` |
-| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
-| Frontend development | `~/.mosaic/guides/frontend.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
-| CI/CD pipelines & Docker builds | `~/.mosaic/guides/ci-cd-pipelines.md` |
-| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous task completion | `~/.config/mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
+| Frontend development | `~/.config/mosaic/guides/frontend.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
+| CI/CD pipelines & Docker builds | `~/.config/mosaic/guides/ci-cd-pipelines.md` |
+| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
 | Secrets management | See section below |
 
 **Project-specific skills:**
 
 | Project | Skill |
 |---------|-------|
-| jetrich/jarvis | `~/.mosaic/skills/jarvis/SKILL.md` |
+| jetrich/jarvis | `~/.config/mosaic/skills/jarvis/SKILL.md` |
 
 ## Secrets Management
 
 **NEVER hardcode secrets in the codebase.** Choose the appropriate method based on your environment.
 
 ### If Using Vault
-See `~/.mosaic/guides/vault-secrets.md` for the canonical structure and rules.
+See `~/.config/mosaic/guides/vault-secrets.md` for the canonical structure and rules.
 
 Quick reference:
 ```
diff --git a/runtime/claude/settings.json b/runtime/claude/settings.json
index 9db8b74..61c4d64 100644
--- a/runtime/claude/settings.json
+++ b/runtime/claude/settings.json
@@ -7,7 +7,7 @@
         "hooks": [
           {
             "type": "command",
-            "command": "~/.mosaic/rails/qa/qa-hook-stdin.sh",
+            "command": "~/.config/mosaic/rails/qa/qa-hook-stdin.sh",
             "timeout": 60
           }
         ]
diff --git a/runtime/opencode/AGENTS.md b/runtime/opencode/AGENTS.md
index dfcef4e..3816380 100644
--- a/runtime/opencode/AGENTS.md
+++ b/runtime/opencode/AGENTS.md
@@ -1,7 +1,7 @@
 # Mosaic Runtime Adapter — OpenCode
 
 Load and apply in this order:
-1. `~/.mosaic/STANDARDS.md`
+1. `~/.config/mosaic/STANDARDS.md`
 2. repo-local `AGENTS.md` (and `SOUL.md` when present)
 
 This file is an OpenCode adapter layer. It does not replace project guidance.
@@ -10,19 +10,19 @@ This file is an OpenCode adapter layer. It does not replace project guidance.
 
 - OpenCode sessions may not expose a native subagent/background task primitive in all deployments.
 - When native subagent delegation is unavailable, use Mosaic's deterministic orchestrator rail:
-  - `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
+  - `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
 - Keep repo task tracking in `docs/tasks.md` as the canonical human-readable state.
 - Keep machine transport/controller state in `.mosaic/orchestrator/`.
 
 ## Fallback Delegation Mode (No Native Subagents)
 
 1. Bootstrap repo if needed:
-   - `~/.mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
+   - `~/.config/mosaic/bin/mosaic-bootstrap-repo /path/to/repo`
 2. Configure `.mosaic/orchestrator/config.json`:
    - set `"enabled": true`
    - set `"worker.command_template"` to your OpenCode worker command
 3. Queue work items in `.mosaic/orchestrator/tasks.json` (or via Matrix command ingestion).
 4. Run deterministic ticks:
-   - `~/.mosaic/bin/mosaic-orchestrator-matrix-cycle`
+   - `~/.config/mosaic/bin/mosaic-orchestrator-matrix-cycle`
 
 This preserves rails enforcement (`quality_gates`) even without runtime-native subagent features.
diff --git a/skills-local/mosaic-standards/SKILL.md b/skills-local/mosaic-standards/SKILL.md
index 2648a6d..29a3e07 100644
--- a/skills-local/mosaic-standards/SKILL.md
+++ b/skills-local/mosaic-standards/SKILL.md
@@ -7,7 +7,7 @@ description: Load machine-wide Mosaic standards and enforce the repository lifec
 
 ## Load Order
 
-1. `~/.mosaic/STANDARDS.md`
+1. `~/.config/mosaic/STANDARDS.md`
 2. Repository `AGENTS.md`
 3. Repo-local `.mosaic/repo-hooks.sh` when present
 
@@ -25,7 +25,7 @@ If wrappers are available, you may use:
 
 ## Enforcement Rules
 
-- Treat `~/.mosaic` as canonical for shared guides, rails, profiles, and skills.
+- Treat `~/.config/mosaic` as canonical for shared guides, rails, profiles, and skills.
 - Do not edit generated project views directly when the repo defines canonical data sources.
 - Pull/rebase before edits in shared repositories.
 - Run project verification commands before claiming completion.
diff --git a/skills-local/setup-cicd/SKILL.md b/skills-local/setup-cicd/SKILL.md
index 101c00e..3c7b8a9 100644
--- a/skills-local/setup-cicd/SKILL.md
+++ b/skills-local/setup-cicd/SKILL.md
@@ -7,7 +7,7 @@ description: "Configure CI/CD Docker build, push, and package linking for a proj
 
 Configure Docker build, registry push, and package linking for a Woodpecker CI pipeline using Kaniko and Gitea's container registry.
 
-**Before starting:** Read `~/.mosaic/guides/ci-cd-pipelines.md` for deep background on the patterns used here.
+**Before starting:** Read `~/.config/mosaic/guides/ci-cd-pipelines.md` for deep background on the patterns used here.
 
 **Reference implementation:** `~/src/mosaic-stack/.woodpecker.yml`
 
@@ -140,7 +140,7 @@ Ask these questions with lettered options (user can respond "1A, 2B, 3C"):
 If the project's `.woodpecker.yml` doesn't already have a `kaniko_setup` anchor in its `variables:` section, add it:
 
 ```bash
-~/.mosaic/rails/cicd/generate-docker-steps.sh --kaniko-setup-only --registry REGISTRY_HOST
+~/.config/mosaic/rails/cicd/generate-docker-steps.sh --kaniko-setup-only --registry REGISTRY_HOST
 ```
 
 This outputs:
@@ -158,7 +158,7 @@ Add this to the existing `variables:` block at the top of `.woodpecker.yml`.
 Use the generator script with the user's answers:
 
 ```bash
-~/.mosaic/rails/cicd/generate-docker-steps.sh \
+~/.config/mosaic/rails/cicd/generate-docker-steps.sh \
   --registry REGISTRY \
   --org ORG \
   --repo REPO \
diff --git a/templates/agent/AGENTS.md.template b/templates/agent/AGENTS.md.template
index 68a4a63..1150222 100644
--- a/templates/agent/AGENTS.md.template
+++ b/templates/agent/AGENTS.md.template
@@ -51,8 +51,8 @@ When completing an orchestrated task:
 
 ### Post-Coding Review
 After implementing changes, the orchestrator will run:
-1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
 
diff --git a/templates/agent/CLAUDE.md.template b/templates/agent/CLAUDE.md.template
index bb8ddf2..9c5293f 100644
--- a/templates/agent/CLAUDE.md.template
+++ b/templates/agent/CLAUDE.md.template
@@ -24,14 +24,14 @@ git push
 
 | Task Type | Guide |
 |-----------|-------|
-| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| Frontend development | `~/.mosaic/guides/frontend.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
-| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| Frontend development | `~/.config/mosaic/guides/frontend.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
+| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
 
 ## Technology Stack
 
@@ -123,16 +123,16 @@ After completing code changes, run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.
 
 ### Review Checklist
-See `~/.mosaic/guides/code-review.md` for the full review checklist.
+See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
 
 ## Secrets Management
 
diff --git a/templates/agent/SPEC.md b/templates/agent/SPEC.md
index 0d5aad7..e33fc4c 100644
--- a/templates/agent/SPEC.md
+++ b/templates/agent/SPEC.md
@@ -6,7 +6,7 @@
 
 ### Tier 1 (Required — blocks audit pass)
 
-1. **Conditional Documentation Loading** — Table linking to `~/.mosaic/guides/`
+1. **Conditional Documentation Loading** — Table linking to `~/.config/mosaic/guides/`
 2. **Quality Gates** — Bash commands that must pass before commit (build, test, lint, typecheck)
 3. **Build/Test/Lint commands** — How to build, test, and lint the project
 
@@ -56,13 +56,13 @@ The `agent-lint.sh` tool checks for these markers:
 |-------|---------------|
 | CLAUDE.md exists | File present at project root |
 | AGENTS.md exists | File present at project root |
-| Conditional context/loading | CLAUDE.md contains `~/.mosaic/guides` or `Conditional` + `Loading/Context` |
+| Conditional context/loading | CLAUDE.md contains `~/.config/mosaic/guides` or `Conditional` + `Loading/Context` |
 | Quality gates | CLAUDE.md contains `Quality Gates` or quality commands (test, lint, typecheck) |
 | Monorepo sub-agents | Each app/package dir with own manifest has AGENTS.md |
 
 ## Fragment Sources
 
-Shared sections are maintained in `~/.mosaic/templates/agent/fragments/`:
+Shared sections are maintained in `~/.config/mosaic/templates/agent/fragments/`:
 
 | Fragment | Injects Section |
 |----------|----------------|
diff --git a/templates/agent/fragments/code-review.md b/templates/agent/fragments/code-review.md
index 8b15c76..9d965e4 100644
--- a/templates/agent/fragments/code-review.md
+++ b/templates/agent/fragments/code-review.md
@@ -4,11 +4,11 @@ After completing code changes, run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.
-See `~/.mosaic/guides/code-review.md` for the full review checklist.
+See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
diff --git a/templates/agent/fragments/conditional-loading.md b/templates/agent/fragments/conditional-loading.md
index e47c232..b5951e9 100644
--- a/templates/agent/fragments/conditional-loading.md
+++ b/templates/agent/fragments/conditional-loading.md
@@ -4,14 +4,14 @@
 
 | Task Type | Guide |
 |-----------|-------|
-| Bootstrapping a new project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
-| Frontend development | `~/.mosaic/guides/frontend.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
-| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
-| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |
+| Bootstrapping a new project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
+| Frontend development | `~/.config/mosaic/guides/frontend.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
+| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
+| Secrets management (Vault) | `~/.config/mosaic/guides/vault-secrets.md` |
diff --git a/templates/agent/projects/django/AGENTS.md.template b/templates/agent/projects/django/AGENTS.md.template
index 2c57edb..9c7fc34 100644
--- a/templates/agent/projects/django/AGENTS.md.template
+++ b/templates/agent/projects/django/AGENTS.md.template
@@ -52,8 +52,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
 
 ### Post-Coding Review
 After implementing changes, the orchestrator will run:
-1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
 
diff --git a/templates/agent/projects/django/CLAUDE.md.template b/templates/agent/projects/django/CLAUDE.md.template
index a810f51..34c9983 100644
--- a/templates/agent/projects/django/CLAUDE.md.template
+++ b/templates/agent/projects/django/CLAUDE.md.template
@@ -6,11 +6,11 @@
 
 | When working on... | Load this guide |
 |---|---|
-| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
 
 ## Technology Stack
 
@@ -135,10 +135,10 @@ After completing code changes, run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 ## Issue Tracking
diff --git a/templates/agent/projects/nestjs-nextjs/AGENTS.md.template b/templates/agent/projects/nestjs-nextjs/AGENTS.md.template
index 4615648..fd0d21c 100644
--- a/templates/agent/projects/nestjs-nextjs/AGENTS.md.template
+++ b/templates/agent/projects/nestjs-nextjs/AGENTS.md.template
@@ -56,8 +56,8 @@ Use `${TASK_PREFIX}` for orchestrated tasks (e.g., `${TASK_PREFIX}-SEC-001`).
 
 ### Post-Coding Review
 After implementing changes, the orchestrator will run:
-1. **Codex code review** — `~/.mosaic/rails/codex/codex-code-review.sh --uncommitted`
-2. **Codex security review** — `~/.mosaic/rails/codex/codex-security-review.sh --uncommitted`
+1. **Codex code review** — `~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted`
+2. **Codex security review** — `~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted`
 3. If blockers/critical findings: remediation task created
 4. If clean: task marked done
 
diff --git a/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template b/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
index e608922..373b8be 100644
--- a/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
+++ b/templates/agent/projects/nestjs-nextjs/CLAUDE.md.template
@@ -6,14 +6,14 @@
 
 | When working on... | Load this guide |
 |---|---|
-| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Frontend development | `~/.mosaic/guides/frontend.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
-| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Frontend development | `~/.config/mosaic/guides/frontend.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
+| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
 
 ## Technology Stack
 
@@ -166,10 +166,10 @@ After completing code changes, run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 ## Issue Tracking
diff --git a/templates/agent/projects/python-fastapi/CLAUDE.md.template b/templates/agent/projects/python-fastapi/CLAUDE.md.template
index 0456777..f6514b2 100644
--- a/templates/agent/projects/python-fastapi/CLAUDE.md.template
+++ b/templates/agent/projects/python-fastapi/CLAUDE.md.template
@@ -9,15 +9,15 @@
 
 | Task Type | Guide |
 |-----------|-------|
-| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| Authentication/Authorization | `~/.mosaic/guides/authentication.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
-| Infrastructure/DevOps | `~/.mosaic/guides/infrastructure.md` |
-| Secrets management (Vault) | `~/.mosaic/guides/vault-secrets.md` |
+| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| Authentication/Authorization | `~/.config/mosaic/guides/authentication.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
+| Infrastructure/DevOps | `~/.config/mosaic/guides/infrastructure.md` |
+| Secrets management (Vault) | `~/.config/mosaic/guides/vault-secrets.md` |
 
 ## Technology Stack
 
@@ -112,11 +112,11 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
 After completing code changes, run independent reviews:
 
 ```bash
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
-See `~/.mosaic/guides/code-review.md` for the full review checklist.
+See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
 
 ## Secrets Management
 
diff --git a/templates/agent/projects/python-library/CLAUDE.md.template b/templates/agent/projects/python-library/CLAUDE.md.template
index b97e7a6..76d731a 100644
--- a/templates/agent/projects/python-library/CLAUDE.md.template
+++ b/templates/agent/projects/python-library/CLAUDE.md.template
@@ -9,12 +9,12 @@
 
 | Task Type | Guide |
 |-----------|-------|
-| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
-| Backend/API development | `~/.mosaic/guides/backend.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
+| Backend/API development | `~/.config/mosaic/guides/backend.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
 
 ## Technology Stack
 
@@ -102,11 +102,11 @@ Types: `feat`, `fix`, `docs`, `test`, `refactor`, `chore`
 After completing code changes, run independent reviews:
 
 ```bash
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
-See `~/.mosaic/guides/code-review.md` for the full review checklist.
+See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
 
 ## Secrets Management
 
diff --git a/templates/agent/projects/typescript/AGENTS.md.template b/templates/agent/projects/typescript/AGENTS.md.template
index c3660a6..d376855 100644
--- a/templates/agent/projects/typescript/AGENTS.md.template
+++ b/templates/agent/projects/typescript/AGENTS.md.template
@@ -6,7 +6,7 @@
 ## Codebase Patterns
 
 - TypeScript strict mode enabled — no `any`, no implicit types
-- See `~/.mosaic/guides/typescript.md` for mandatory TypeScript rules
+- See `~/.config/mosaic/guides/typescript.md` for mandatory TypeScript rules
 <!-- Add project-specific patterns as you discover them -->
 
 ## Common Gotchas
diff --git a/templates/agent/projects/typescript/CLAUDE.md.template b/templates/agent/projects/typescript/CLAUDE.md.template
index 46880fa..5b38ed6 100644
--- a/templates/agent/projects/typescript/CLAUDE.md.template
+++ b/templates/agent/projects/typescript/CLAUDE.md.template
@@ -9,13 +9,13 @@
 
 | Task Type | Guide |
 |-----------|-------|
-| Bootstrapping this project | `~/.mosaic/guides/bootstrap.md` |
-| Orchestrating autonomous tasks | `~/.mosaic/guides/orchestrator.md` |
-| Ralph autonomous development | `~/.mosaic/guides/ralph-autonomous.md` |
-| Frontend development | `~/.mosaic/guides/frontend.md` |
-| TypeScript strict typing | `~/.mosaic/guides/typescript.md` |
-| Code review | `~/.mosaic/guides/code-review.md` |
-| QA/Testing | `~/.mosaic/guides/qa-testing.md` |
+| Bootstrapping this project | `~/.config/mosaic/guides/bootstrap.md` |
+| Orchestrating autonomous tasks | `~/.config/mosaic/guides/orchestrator.md` |
+| Ralph autonomous development | `~/.config/mosaic/guides/ralph-autonomous.md` |
+| Frontend development | `~/.config/mosaic/guides/frontend.md` |
+| TypeScript strict typing | `~/.config/mosaic/guides/typescript.md` |
+| Code review | `~/.config/mosaic/guides/code-review.md` |
+| QA/Testing | `~/.config/mosaic/guides/qa-testing.md` |
 
 ## Technology Stack
 
@@ -93,14 +93,14 @@ After completing code changes, run independent reviews:
 
 ```bash
 # Code quality review (Codex)
-~/.mosaic/rails/codex/codex-code-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
 
 # Security review (Codex)
-~/.mosaic/rails/codex/codex-security-review.sh --uncommitted
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
 ```
 
 **Fallback:** If Codex is unavailable, use Claude's built-in review skills.
-See `~/.mosaic/guides/code-review.md` for the full review checklist.
+See `~/.config/mosaic/guides/code-review.md` for the full review checklist.
 
 ## Secrets Management