AGENTS.md

@@ -9,11 +9,13 @@ This file defines the mandatory behavior for all Mosaic agent runtimes.
 Before responding to any user message, you MUST read these files in order:
 
 1. `~/.config/mosaic/SOUL.md`
-2. `~/.config/mosaic/STANDARDS.md`
-3. `~/.config/mosaic/AGENTS.md`
-4. `~/.config/mosaic/guides/E2E-DELIVERY.md`
-5. Project-local `AGENTS.md` (if present)
-6. Runtime-specific reference:
+2. `~/.config/mosaic/USER.md`
+3. `~/.config/mosaic/STANDARDS.md`
+4. `~/.config/mosaic/AGENTS.md`
+5. `~/.config/mosaic/TOOLS.md`
+6. `~/.config/mosaic/guides/E2E-DELIVERY.md`
+7. Project-local `AGENTS.md` (if present)
+8. Runtime-specific reference:
    - Claude: `~/.config/mosaic/runtime/claude/RUNTIME.md`
    - Codex: `~/.config/mosaic/runtime/codex/RUNTIME.md`
    - OpenCode: `~/.config/mosaic/runtime/opencode/RUNTIME.md`

README.md

@@ -4,6 +4,8 @@ Universal agent standards layer for Claude Code, Codex, and OpenCode.
 
 One config, every runtime, same standards.
 
+> **This repository is a generic framework baseline.** No personal data, credentials, user-specific preferences, or machine-specific paths should be committed. All personalization happens at install time via `mosaic init` or by editing files in `~/.config/mosaic/` after installation.
+
 ## Quick Install
 
 ### Mac / Linux
@@ -42,7 +44,10 @@ After install, open a new terminal (or `source ~/.bashrc`) and run:
 mosaic init
 ```
 
-This generates `~/.config/mosaic/SOUL.md` — your agent identity contract. It's loaded into every session regardless of runtime.
+This generates three files loaded into every agent session:
+- `SOUL.md` — agent identity contract (name, style, guardrails)
+- `USER.md` — your user profile (name, timezone, accessibility, preferences)
+- `TOOLS.md` — machine-level tool reference (git providers, credentials, CLI patterns)
 
 ## Launching Agent Sessions
 
@@ -65,7 +70,9 @@ You can still launch runtimes directly (`claude`, `codex`, etc.) — thin runtim
 ```
 ~/.config/mosaic/
 ├── AGENTS.md              ← THE source of truth (all standards, all runtimes)
-├── SOUL.md                ← User identity (generated by mosaic init)
+├── SOUL.md                ← Agent identity (generated by mosaic init)
+├── USER.md                ← User profile and accessibility (generated by mosaic init)
+├── TOOLS.md               ← Machine-level tool reference (generated by mosaic init)
 ├── STANDARDS.md           ← Machine-wide standards
 ├── guides/E2E-DELIVERY.md ← Mandatory E2E software delivery procedure
 ├── guides/PRD.md          ← Mandatory PRD requirements gate before coding
@@ -121,7 +128,7 @@ mosaic upgrade project ... # Project file cleanup mode (see below)
 Upgrade the installed framework in place:
 
 ```bash
-# Default (safe): keep local SOUL.md + memory
+# Default (safe): keep local SOUL.md, USER.md, TOOLS.md + memory
 mosaic upgrade
 
 # Check current/target release info without changing files
@@ -245,7 +252,7 @@ cd ~/src/mosaic-bootstrap && git pull && bash install.sh
 ```
 
 If an existing install is detected, the installer prompts for:
-- `keep` (recommended): preserve local `SOUL.md` and `memory/`
+- `keep` (recommended): preserve local `SOUL.md`, `USER.md`, `TOOLS.md`, and `memory/`
 - `overwrite`: replace everything in `~/.config/mosaic`
 
 Or use the one-liner again — it always pulls the latest:

SOUL.md

@@ -5,14 +5,14 @@ It is loaded globally and applies to all sessions regardless of runtime or proje
 
 ## Identity
 
-You are **Jarvis** in this session.
+You are **Assistant** in this session.
 
 - Runtime (Claude, Codex, OpenCode, etc.) is implementation detail.
 - Role identity: execution partner and visibility engine
 
 If asked "who are you?", answer:
 
-`I am Jarvis, running on <runtime>.`
+`I am Assistant, running on <runtime>.`
 
 ## Behavioral Principles
 
@@ -20,7 +20,7 @@ If asked "who are you?", answer:
 2. Practical execution over abstract planning.
 3. Truthfulness over confidence: state uncertainty explicitly.
 4. Visible state over hidden assumptions.
-5. PDA-friendly language, communication style, and iconography. Avoid overwhelming info and communication style..
+5. Accessibility-aware — see `~/.config/mosaic/USER.md` for user-specific accommodations.
 
 ## Communication Style
 
@@ -42,7 +42,8 @@ If asked "who are you?", answer:
 - Do not perform destructive actions without explicit instruction.
 - Do not silently change intent, scope, or definitions.
 - Do not create fake policy by writing canned responses for every prompt.
-
+- Prefer `trash` over `rm` when available — recoverable beats gone forever.
+- Write decisions and learnings to files — "mental notes" do not survive session restarts.
 
 ## Why This Exists
 

TOOLS.md

@@ -0,0 +1,60 @@
+# Machine-Level Tool Reference
+
+Centralized reference for tools, credentials, and CLI patterns available across all projects.
+Project-specific tooling belongs in the project's `AGENTS.md`, not here.
+
+## Mosaic Git Wrappers (Use First)
+
+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/rails/git/issue-create.sh
+~/.config/mosaic/rails/git/issue-close.sh
+
+# PRs
+~/.config/mosaic/rails/git/pr-create.sh
+~/.config/mosaic/rails/git/pr-merge.sh
+
+# Milestones
+~/.config/mosaic/rails/git/milestone-create.sh
+
+# CI queue guard (required before push/merge)
+~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge
+```
+
+## Code Review (Codex)
+
+```bash
+# Code quality review
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+
+# Security review
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+```
+
+## Git Providers
+
+| Instance | URL | CLI | Purpose |
+|----------|-----|-----|---------|
+| (add your git providers here) | | | |
+
+## Credentials
+
+**Location:** (configure your credential file path)
+
+**Never expose actual values. Never commit credential files.**
+
+## CLI Gotchas
+
+(Add platform-specific CLI gotchas as you discover them. Examples: TTY requirements, default list limits, API fallback patterns.)
+
+## Custom Tools
+
+(Add any machine-specific tools, scripts, or workflows here.)
+
+## Safety Defaults
+
+- Prefer `trash` over `rm` when available — recoverable beats gone forever
+- Never run destructive commands without explicit instruction
+- Write it down — "mental notes" don't survive session restarts; files do

USER.md

@@ -0,0 +1,37 @@
+# User Profile
+
+This file defines user-specific context for all agent sessions.
+It is loaded globally and applies regardless of runtime or project.
+
+> **This file has not been personalized yet.**
+> Run `mosaic init` to set up your user profile, or edit this file directly.
+
+## Identity
+
+- **Name:** (not configured)
+- **Pronouns:** (not configured)
+- **Timezone:** (not configured)
+
+## Background
+
+(Run `mosaic init` or edit this section with your professional background.)
+
+## Accessibility
+
+(Add any neurodivergence accommodations, communication preferences, or accessibility needs here. Agents will adapt their behavior based on this section.)
+
+## Communication Preferences
+
+- Direct and concise
+- No sycophancy
+- Executive summaries and tables for overview
+
+## Personal Boundaries
+
+(Add any personal boundaries or preferences agents should respect.)
+
+## Current Projects
+
+| Project | Stack | Registry |
+|---------|-------|----------|
+| (none configured) | | |

bin/mosaic

@@ -148,6 +148,17 @@ For required push/merge/issue-close/release actions, execute without routine con
 EOF
 
   cat "$MOSAIC_HOME/AGENTS.md"
+
+  if [[ -f "$MOSAIC_HOME/USER.md" ]]; then
+    printf '\n\n# User Profile\n\n'
+    cat "$MOSAIC_HOME/USER.md"
+  fi
+
+  if [[ -f "$MOSAIC_HOME/TOOLS.md" ]]; then
+    printf '\n\n# Machine Tools\n\n'
+    cat "$MOSAIC_HOME/TOOLS.md"
+  fi
+
   printf '\n\n# Runtime-Specific Contract\n\n'
   cat "$runtime_file"
 }

bin/mosaic-doctor

@@ -146,6 +146,8 @@ echo "[mosaic-doctor] Mosaic home: $MOSAIC_HOME"
 
 # Canonical Mosaic checks
 expect_file "$MOSAIC_HOME/STANDARDS.md"
+expect_file "$MOSAIC_HOME/USER.md"
+expect_file "$MOSAIC_HOME/TOOLS.md"
 expect_dir "$MOSAIC_HOME/guides"
 expect_dir "$MOSAIC_HOME/rails"
 expect_dir "$MOSAIC_HOME/rails/quality"

bin/mosaic-init

@@ -1,7 +1,7 @@
 #!/usr/bin/env bash
 set -euo pipefail
 
-# mosaic-init — Interactive SOUL.md generator
+# mosaic-init — Interactive agent identity, user profile, and tool config generator
 #
 # Usage:
 #   mosaic-init                                    # Interactive mode
@@ -10,8 +10,12 @@ set -euo pipefail
 #     --accessibility "ADHD-friendly chunking" --guardrails "Never auto-commit"
 
 MOSAIC_HOME="${MOSAIC_HOME:-$HOME/.config/mosaic}"
-TEMPLATE="$MOSAIC_HOME/templates/SOUL.md.template"
-OUTPUT="$MOSAIC_HOME/SOUL.md"
+SOUL_TEMPLATE="$MOSAIC_HOME/templates/SOUL.md.template"
+USER_TEMPLATE="$MOSAIC_HOME/templates/USER.md.template"
+TOOLS_TEMPLATE="$MOSAIC_HOME/templates/TOOLS.md.template"
+SOUL_OUTPUT="$MOSAIC_HOME/SOUL.md"
+USER_OUTPUT="$MOSAIC_HOME/USER.md"
+TOOLS_OUTPUT="$MOSAIC_HOME/TOOLS.md"
 
 # Defaults
 AGENT_NAME=""
@@ -20,11 +24,28 @@ STYLE=""
 ACCESSIBILITY=""
 CUSTOM_GUARDRAILS=""
 
+# USER.md defaults
+USER_NAME=""
+PRONOUNS=""
+TIMEZONE=""
+BACKGROUND=""
+COMMUNICATION_PREFS=""
+PERSONAL_BOUNDARIES=""
+PROJECTS_TABLE=""
+
+# TOOLS.md defaults
+GIT_PROVIDERS_TABLE=""
+CREDENTIALS_LOCATION=""
+CUSTOM_TOOLS_SECTION=""
+
 usage() {
   cat <<USAGE
 Usage: $(basename "$0") [options]
 
-Generate ~/.config/mosaic/SOUL.md — the universal agent identity contract.
+Generate Mosaic identity and configuration files:
+  - SOUL.md    — Agent identity contract
+  - USER.md    — User profile and accessibility
+  - TOOLS.md   — Machine-level tool reference
 
 Interactive by default. Use flags to skip prompts.
 
@@ -34,12 +55,17 @@ Options:
   --style <style>          Communication style: direct, friendly, or formal
   --accessibility <prefs>  Accessibility preferences (e.g., "ADHD-friendly chunking")
   --guardrails <rules>     Custom guardrails (appended to defaults)
+  --user-name <name>       Your name for USER.md
+  --pronouns <pronouns>    Your pronouns (e.g., "He/Him")
+  --timezone <tz>          Your timezone (e.g., "America/Chicago")
   --non-interactive        Fail if any required value is missing (no prompts)
+  --soul-only              Only generate SOUL.md
   -h, --help               Show help
 USAGE
 }
 
 NON_INTERACTIVE=0
+SOUL_ONLY=0
 
 while [[ $# -gt 0 ]]; do
   case "$1" in
@@ -48,7 +74,11 @@ while [[ $# -gt 0 ]]; do
     --style) STYLE="$2"; shift 2 ;;
     --accessibility) ACCESSIBILITY="$2"; shift 2 ;;
     --guardrails) CUSTOM_GUARDRAILS="$2"; shift 2 ;;
+    --user-name) USER_NAME="$2"; shift 2 ;;
+    --pronouns) PRONOUNS="$2"; shift 2 ;;
+    --timezone) TIMEZONE="$2"; shift 2 ;;
     --non-interactive) NON_INTERACTIVE=1; shift ;;
+    --soul-only) SOUL_ONLY=1; shift ;;
     -h|--help) usage; exit 0 ;;
     *) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
   esac
@@ -85,7 +115,32 @@ prompt_if_empty() {
   eval "$var_name=\"$value\""
 }
 
-echo "[mosaic-init] Generating SOUL.md — your universal agent identity contract"
+prompt_multiline() {
+  local var_name="$1"
+  local prompt_text="$2"
+  local default_value="${3:-}"
+  local current_value="${!var_name}"
+
+  if [[ -n "$current_value" ]]; then
+    return
+  fi
+
+  if [[ $NON_INTERACTIVE -eq 1 ]]; then
+    eval "$var_name=\"$default_value\""
+    return
+  fi
+
+  echo "$prompt_text"
+  printf "(Press Enter to skip, or type your response): "
+  read -r value
+  if [[ -z "$value" ]]; then
+    value="$default_value"
+  fi
+  eval "$var_name=\"$value\""
+}
+
+# ── SOUL.md Generation ────────────────────────────────────────
+echo "[mosaic-init] Generating SOUL.md — agent identity contract"
 echo ""
 
 prompt_if_empty AGENT_NAME "What name should agents use" "Assistant"
@@ -124,25 +179,28 @@ case "$STYLE" in
     BEHAVIORAL_PRINCIPLES="1. Clarity over performance theater.
 2. Practical execution over abstract planning.
 3. Truthfulness over confidence: state uncertainty explicitly.
-4. Visible state over hidden assumptions."
+4. Visible state over hidden assumptions.
+5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations."
     ;;
   friendly)
     BEHAVIORAL_PRINCIPLES="1. Be helpful and approachable while staying efficient.
 2. Provide context and explain reasoning when helpful.
 3. Truthfulness over confidence: state uncertainty explicitly.
-4. Visible state over hidden assumptions."
+4. Visible state over hidden assumptions.
+5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations."
     ;;
   formal)
     BEHAVIORAL_PRINCIPLES="1. Maintain professional, structured communication.
 2. Provide thorough analysis with explicit tradeoffs.
 3. Truthfulness over confidence: state uncertainty explicitly.
-4. Document decisions and rationale clearly."
+4. Document decisions and rationale clearly.
+5. Accessibility-aware — see \`~/.config/mosaic/USER.md\` for user-specific accommodations."
     ;;
 esac
 
 if [[ "$ACCESSIBILITY" != "none" && -n "$ACCESSIBILITY" ]]; then
   BEHAVIORAL_PRINCIPLES="$BEHAVIORAL_PRINCIPLES
-5. $ACCESSIBILITY."
+6. $ACCESSIBILITY."
 fi
 
 # Build communication style section
@@ -175,8 +233,8 @@ if [[ -n "$CUSTOM_GUARDRAILS" ]]; then
 fi
 
 # Verify template exists
-if [[ ! -f "$TEMPLATE" ]]; then
-  echo "[mosaic-init] ERROR: Template not found: $TEMPLATE" >&2
+if [[ ! -f "$SOUL_TEMPLATE" ]]; then
+  echo "[mosaic-init] ERROR: Template not found: $SOUL_TEMPLATE" >&2
   echo "[mosaic-init] Run the Mosaic installer first." >&2
   exit 1
 fi
@@ -194,17 +252,173 @@ awk -v name="$AGENT_NAME" \
       gsub(/\{\{COMMUNICATION_STYLE\}\}/, comms)
       gsub(/\{\{CUSTOM_GUARDRAILS\}\}/, guardrails)
       print
-    }' "$TEMPLATE" > "$OUTPUT"
+    }' "$SOUL_TEMPLATE" > "$SOUL_OUTPUT"
 
 echo ""
-echo "[mosaic-init] Generated: $OUTPUT"
+echo "[mosaic-init] Generated: $SOUL_OUTPUT"
 echo "[mosaic-init] Agent name: $AGENT_NAME"
 echo "[mosaic-init] Style: $STYLE"
 
+if [[ $SOUL_ONLY -eq 1 ]]; then
+  # Push to runtime adapters and exit
+  if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then
+    echo "[mosaic-init] Updating runtime adapters..."
+    "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
+  fi
+  echo "[mosaic-init] Done. Launch with: mosaic claude"
+  exit 0
+fi
+
+# ── USER.md Generation ────────────────────────────────────────
+echo ""
+echo "[mosaic-init] Generating USER.md — user profile"
+echo ""
+
+prompt_if_empty USER_NAME "Your name" ""
+prompt_if_empty PRONOUNS "Your pronouns" "They/Them"
+prompt_if_empty TIMEZONE "Your timezone" "UTC"
+
+prompt_multiline BACKGROUND "Your professional background (brief summary)" "(not configured)"
+
+# Build accessibility section
+ACCESSIBILITY_SECTION=""
+if [[ "$ACCESSIBILITY" != "none" && -n "$ACCESSIBILITY" ]]; then
+  ACCESSIBILITY_SECTION="$ACCESSIBILITY"
+else
+  if [[ $NON_INTERACTIVE -eq 0 ]]; then
+    echo ""
+    prompt_multiline ACCESSIBILITY_SECTION \
+      "Accessibility or neurodivergence accommodations (or press Enter to skip)" \
+      "(No specific accommodations configured. Edit this section to add any.)"
+  else
+    ACCESSIBILITY_SECTION="(No specific accommodations configured. Edit this section to add any.)"
+  fi
+fi
+
+# Build communication preferences
+if [[ -z "$COMMUNICATION_PREFS" ]]; then
+  case "$STYLE" in
+    direct)
+      COMMUNICATION_PREFS="- Direct and concise
+- No sycophancy
+- Executive summaries and tables for overview"
+      ;;
+    friendly)
+      COMMUNICATION_PREFS="- Warm and conversational
+- Explain reasoning when helpful
+- Balance thoroughness with brevity"
+      ;;
+    formal)
+      COMMUNICATION_PREFS="- Professional and structured
+- Thorough explanations with supporting detail
+- Formal tone with explicit recommendations"
+      ;;
+  esac
+fi
+
+prompt_multiline PERSONAL_BOUNDARIES \
+  "Personal boundaries or preferences agents should respect" \
+  "(Edit this section to add any personal boundaries.)"
+
+if [[ -z "$PROJECTS_TABLE" ]]; then
+  PROJECTS_TABLE="| Project | Stack | Registry |
+|---------|-------|----------|
+| (none configured) | | |"
+fi
+
+if [[ ! -f "$USER_TEMPLATE" ]]; then
+  echo "[mosaic-init] WARN: USER.md template not found: $USER_TEMPLATE" >&2
+  echo "[mosaic-init] Skipping USER.md generation." >&2
+else
+  awk -v user_name="$USER_NAME" \
+      -v pronouns="$PRONOUNS" \
+      -v timezone="$TIMEZONE" \
+      -v background="$BACKGROUND" \
+      -v accessibility="$ACCESSIBILITY_SECTION" \
+      -v comms="$COMMUNICATION_PREFS" \
+      -v boundaries="$PERSONAL_BOUNDARIES" \
+      -v projects="$PROJECTS_TABLE" \
+      '{
+        gsub(/\{\{USER_NAME\}\}/, user_name)
+        gsub(/\{\{PRONOUNS\}\}/, pronouns)
+        gsub(/\{\{TIMEZONE\}\}/, timezone)
+        gsub(/\{\{BACKGROUND\}\}/, background)
+        gsub(/\{\{ACCESSIBILITY_SECTION\}\}/, accessibility)
+        gsub(/\{\{COMMUNICATION_PREFS\}\}/, comms)
+        gsub(/\{\{PERSONAL_BOUNDARIES\}\}/, boundaries)
+        gsub(/\{\{PROJECTS_TABLE\}\}/, projects)
+        print
+      }' "$USER_TEMPLATE" > "$USER_OUTPUT"
+
+  echo "[mosaic-init] Generated: $USER_OUTPUT"
+fi
+
+# ── TOOLS.md Generation ───────────────────────────────────────
+echo ""
+echo "[mosaic-init] Generating TOOLS.md — machine-level tool reference"
+echo ""
+
+if [[ -z "$GIT_PROVIDERS_TABLE" ]]; then
+  if [[ $NON_INTERACTIVE -eq 0 ]]; then
+    echo "Git providers (add rows for your Gitea/GitHub/GitLab instances):"
+    printf "Primary git provider URL (or press Enter to skip): "
+    read -r git_url
+    if [[ -n "$git_url" ]]; then
+      printf "Provider name: "
+      read -r git_name
+      printf "CLI tool (tea/gh/glab): "
+      read -r git_cli
+      printf "Purpose: "
+      read -r git_purpose
+      GIT_PROVIDERS_TABLE="| Instance | URL | CLI | Purpose |
+|----------|-----|-----|---------|
+| $git_name | $git_url | \`$git_cli\` | $git_purpose |"
+    else
+      GIT_PROVIDERS_TABLE="| Instance | URL | CLI | Purpose |
+|----------|-----|-----|---------|
+| (add your git providers here) | | | |"
+    fi
+  else
+    GIT_PROVIDERS_TABLE="| Instance | URL | CLI | Purpose |
+|----------|-----|-----|---------|
+| (add your git providers here) | | | |"
+  fi
+fi
+
+prompt_if_empty CREDENTIALS_LOCATION "Credential file path (or 'none')" "none"
+
+if [[ -z "$CUSTOM_TOOLS_SECTION" ]]; then
+  CUSTOM_TOOLS_SECTION="## Custom Tools
+
+(Add any machine-specific tools, scripts, or workflows here.)"
+fi
+
+if [[ ! -f "$TOOLS_TEMPLATE" ]]; then
+  echo "[mosaic-init] WARN: TOOLS.md template not found: $TOOLS_TEMPLATE" >&2
+  echo "[mosaic-init] Skipping TOOLS.md generation." >&2
+else
+  awk -v providers="$GIT_PROVIDERS_TABLE" \
+      -v creds="$CREDENTIALS_LOCATION" \
+      -v custom="$CUSTOM_TOOLS_SECTION" \
+      '{
+        gsub(/\{\{GIT_PROVIDERS_TABLE\}\}/, providers)
+        gsub(/\{\{CREDENTIALS_LOCATION\}\}/, creds)
+        gsub(/\{\{CUSTOM_TOOLS_SECTION\}\}/, custom)
+        print
+      }' "$TOOLS_TEMPLATE" > "$TOOLS_OUTPUT"
+
+  echo "[mosaic-init] Generated: $TOOLS_OUTPUT"
+fi
+
+# ── Finalize ──────────────────────────────────────────────────
+
 # Push to runtime adapters
 if [[ -x "$MOSAIC_HOME/bin/mosaic-link-runtime-assets" ]]; then
+  echo ""
   echo "[mosaic-init] Updating runtime adapters..."
   "$MOSAIC_HOME/bin/mosaic-link-runtime-assets"
 fi
 
+echo ""
 echo "[mosaic-init] Done. Launch with: mosaic claude"
+echo "[mosaic-init] Edit USER.md and TOOLS.md directly for further customization."

install.sh

@@ -4,7 +4,7 @@ set -euo pipefail
 SOURCE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 TARGET_DIR="${MOSAIC_HOME:-$HOME/.config/mosaic}"
 INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}" # prompt|keep|overwrite
-PRESERVE_PATHS=("SOUL.md" "memory")
+PRESERVE_PATHS=("SOUL.md" "USER.md" "TOOLS.md" "memory")
 
 # Colors (disabled if not a terminal)
 if [[ -t 1 ]]; then
@@ -46,7 +46,7 @@ select_install_mode() {
         echo ""
         echo "Existing Mosaic install detected at: $TARGET_DIR"
         echo "Choose reinstall mode:"
-        echo "  1) keep      Keep local files (SOUL.md, memory/) while updating framework"
+        echo "  1) keep      Keep local files (SOUL.md, USER.md, TOOLS.md, memory/) while updating framework"
         echo "  2) overwrite Replace everything in $TARGET_DIR"
         echo "  3) cancel    Abort install"
         printf "Selection [1/2/3] (default: 1): "
@@ -131,7 +131,7 @@ mkdir -p "$TARGET_DIR"
 select_install_mode
 
 if [[ "$INSTALL_MODE" == "keep" ]]; then
-  ok "Install mode: keep local SOUL.md/memory while updating framework"
+  ok "Install mode: keep local SOUL.md/USER.md/TOOLS.md/memory while updating framework"
 else
   ok "Install mode: overwrite existing files"
 fi
@@ -226,7 +226,9 @@ if [[ "$PATH_CHANGED" == "true" ]]; then
 fi
 
 if [[ ! -f "$TARGET_DIR/SOUL.md" ]]; then
-  NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to set up your agent identity (SOUL.md).")
+  NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to set up your agent identity (SOUL.md), user profile (USER.md), and tool config (TOOLS.md).")
+elif grep -q "not configured" "$TARGET_DIR/USER.md" 2>/dev/null; then
+  NEXT_STEPS+=("Run ${CYAN}mosaic init${RESET} to personalize your user profile (USER.md) and tool config (TOOLS.md).")
 fi
 
 if [[ ${#NEXT_STEPS[@]} -gt 0 ]]; then

templates/SOUL.md.template

@@ -35,6 +35,8 @@ If asked "who are you?", answer:
 - Do not perform destructive actions without explicit instruction.
 - Do not silently change intent, scope, or definitions.
 - Do not create fake policy by writing canned responses for every prompt.
+- Prefer `trash` over `rm` when available — recoverable beats gone forever.
+- Write decisions and learnings to files — "mental notes" do not survive session restarts.
 {{CUSTOM_GUARDRAILS}}
 
 ## Why This Exists

templates/TOOLS.md.template

@@ -0,0 +1,56 @@
+# Machine-Level Tool Reference
+
+Centralized reference for tools, credentials, and CLI patterns available across all projects.
+Project-specific tooling belongs in the project's `AGENTS.md`, not here.
+
+## Mosaic Git Wrappers (Use First)
+
+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/rails/git/issue-create.sh
+~/.config/mosaic/rails/git/issue-close.sh
+
+# PRs
+~/.config/mosaic/rails/git/pr-create.sh
+~/.config/mosaic/rails/git/pr-merge.sh
+
+# Milestones
+~/.config/mosaic/rails/git/milestone-create.sh
+
+# CI queue guard (required before push/merge)
+~/.config/mosaic/rails/git/ci-queue-wait.sh --purpose push|merge
+```
+
+## Code Review (Codex)
+
+```bash
+# Code quality review
+~/.config/mosaic/rails/codex/codex-code-review.sh --uncommitted
+
+# Security review
+~/.config/mosaic/rails/codex/codex-security-review.sh --uncommitted
+```
+
+## Git Providers
+
+{{GIT_PROVIDERS_TABLE}}
+
+## Credentials
+
+**Location:** {{CREDENTIALS_LOCATION}}
+
+**Never expose actual values. Never commit credential files.**
+
+## CLI Gotchas
+
+(Add platform-specific CLI gotchas as you discover them.)
+
+{{CUSTOM_TOOLS_SECTION}}
+
+## Safety Defaults
+
+- Prefer `trash` over `rm` when available — recoverable beats gone forever
+- Never run destructive commands without explicit instruction
+- Write it down — "mental notes" don't survive session restarts; files do

templates/USER.md.template

@@ -0,0 +1,30 @@
+# User Profile
+
+This file defines user-specific context for all agent sessions.
+It is loaded globally and applies regardless of runtime or project.
+
+## Identity
+
+- **Name:** {{USER_NAME}}
+- **Pronouns:** {{PRONOUNS}}
+- **Timezone:** {{TIMEZONE}}
+
+## Background
+
+{{BACKGROUND}}
+
+## Accessibility
+
+{{ACCESSIBILITY_SECTION}}
+
+## Communication Preferences
+
+{{COMMUNICATION_PREFS}}
+
+## Personal Boundaries
+
+{{PERSONAL_BOUNDARIES}}
+
+## Current Projects
+
+{{PROJECTS_TABLE}}