qualia-framework 2.1.6 → 2.2.0

package/framework/install.ps1

@@ -0,0 +1,323 @@
+# Qualia Framework v2.0 — Windows Installer (PowerShell)
+# Usage: git clone <repo> && cd qualia-framework && .\install.ps1
+#
+# Requires: Node.js 18+, Claude Code CLI, PowerShell 5.1+, Git Bash (for hooks)
+
+$ErrorActionPreference = "Stop"
+
+$ClaudeDir = "$env:USERPROFILE\.claude"
+$ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
+
+Write-Host ""
+Write-Host "  --- " -ForegroundColor Cyan -NoNewline
+Write-Host "* QUALIA FRAMEWORK v2.0" -ForegroundColor Cyan
+Write-Host ""
+
+# ─── Step 1: Verify source ───
+if (-not (Test-Path "$ScriptDir\skills") -or -not (Test-Path "$ScriptDir\agents")) {
+    Write-Host "  x Run this script from the qualia-framework directory." -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "[1/6] Prerequisites" -ForegroundColor Yellow
+
+# Check Claude Code
+try {
+    $null = Get-Command claude -ErrorAction Stop
+    Write-Host "  + Claude Code CLI" -ForegroundColor Green
+} catch {
+    Write-Host "  x Claude Code CLI not found" -ForegroundColor Red
+    Write-Host "    npm install -g @anthropic-ai/claude-code"
+    exit 1
+}
+
+# Check Node.js
+try {
+    $nodeVersion = node -v
+    Write-Host "  + Node.js $nodeVersion" -ForegroundColor Green
+} catch {
+    Write-Host "  x Node.js not found" -ForegroundColor Red
+    exit 1
+}
+
+# Check Git Bash (required for hooks)
+$gitBash = Get-Command bash -ErrorAction SilentlyContinue
+if ($gitBash) {
+    Write-Host "  + Git Bash found (hooks will work)" -ForegroundColor Green
+} else {
+    Write-Host "  ! Git Bash NOT found — hooks require bash" -ForegroundColor Yellow
+    Write-Host "    Install Git for Windows: https://git-scm.com/download/win"
+    Write-Host "    Hooks will not fire without bash in PATH" -ForegroundColor Yellow
+}
+
+# ─── Step 1b: Role selection ───
+Write-Host ""
+Write-Host "  Who are you?" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "  1) Fawzi (Owner - full access)" -ForegroundColor White
+Write-Host "  2) Employee (Team member)" -ForegroundColor White
+Write-Host ""
+$roleChoice = Read-Host "  Select [1/2]"
+
+switch ($roleChoice) {
+    "1" {
+        $Role = "owner"
+        $RoleName = "Fawzi"
+        Write-Host "  + Owner mode" -ForegroundColor Green
+    }
+    "2" {
+        $RoleName = Read-Host "  Enter your name"
+        $Role = "employee"
+        Write-Host "  + Employee mode - $RoleName" -ForegroundColor Green
+    }
+    default {
+        $Role = "employee"
+        $RoleName = "Team Member"
+        Write-Host "  ! Defaulting to employee mode" -ForegroundColor Yellow
+    }
+}
+Write-Host ""
+
+# ─── Step 2: Create directory structure ───
+Write-Host "[2/6] Directory structure" -ForegroundColor Yellow
+
+$dirs = @(
+    "$ClaudeDir\skills",
+    "$ClaudeDir\agents\teams",
+    "$ClaudeDir\hooks",
+    "$ClaudeDir\rules",
+    "$ClaudeDir\knowledge\retros",
+    "$ClaudeDir\qualia-engine\bin",
+    "$ClaudeDir\qualia-engine\references",
+    "$ClaudeDir\qualia-engine\templates",
+    "$ClaudeDir\qualia-engine\workflows",
+    "$ClaudeDir\projects",
+    "$ClaudeDir\session-env"
+)
+
+foreach ($dir in $dirs) {
+    if (-not (Test-Path $dir)) {
+        New-Item -ItemType Directory -Path $dir -Force | Out-Null
+    }
+}
+Write-Host "  + Ready" -ForegroundColor Green
+
+# ─── Step 3: Copy framework files ───
+Write-Host "[3/6] Installing files" -ForegroundColor Yellow
+
+# Skills
+$skillCount = 0
+Get-ChildItem "$ScriptDir\skills" -Directory | ForEach-Object {
+    $destDir = "$ClaudeDir\skills\$($_.Name)"
+    if (-not (Test-Path $destDir)) { New-Item -ItemType Directory -Path $destDir -Force | Out-Null }
+    Copy-Item "$($_.FullName)\*" $destDir -Recurse -Force -ErrorAction SilentlyContinue
+    $skillCount++
+}
+Write-Host "  + $skillCount skills" -ForegroundColor Green
+
+# Agents
+Copy-Item "$ScriptDir\agents\*.md" "$ClaudeDir\agents\" -Force -ErrorAction SilentlyContinue
+if (Test-Path "$ScriptDir\agents\teams") {
+    Copy-Item "$ScriptDir\agents\teams\*.md" "$ClaudeDir\agents\teams\" -Force -ErrorAction SilentlyContinue
+}
+$agentCount = (Get-ChildItem "$ClaudeDir\agents\*.md" -ErrorAction SilentlyContinue).Count
+Write-Host "  + $agentCount agents" -ForegroundColor Green
+
+# Hooks
+Copy-Item "$ScriptDir\hooks\*.sh" "$ClaudeDir\hooks\" -Force -ErrorAction SilentlyContinue
+$hookCount = (Get-ChildItem "$ClaudeDir\hooks\*.sh" -ErrorAction SilentlyContinue).Count
+Write-Host "  + $hookCount hooks" -ForegroundColor Green
+
+# Qualia Engine
+Copy-Item "$ScriptDir\qualia-engine\*" "$ClaudeDir\qualia-engine\" -Recurse -Force -ErrorAction SilentlyContinue
+Write-Host "  + Qualia engine" -ForegroundColor Green
+
+# Rules
+Copy-Item "$ScriptDir\rules\*.md" "$ClaudeDir\rules\" -Force -ErrorAction SilentlyContinue
+$ruleCount = (Get-ChildItem "$ClaudeDir\rules\*.md" -ErrorAction SilentlyContinue).Count
+Write-Host "  + $ruleCount rules" -ForegroundColor Green
+
+# Knowledge
+Copy-Item "$ScriptDir\knowledge\*.md" "$ClaudeDir\knowledge\" -Force -ErrorAction SilentlyContinue
+$knowledgeCount = (Get-ChildItem "$ClaudeDir\knowledge\*.md" -ErrorAction SilentlyContinue).Count
+Write-Host "  + $knowledgeCount knowledge files" -ForegroundColor Green
+
+# Statusline
+if (Test-Path "$ScriptDir\statusline-command.sh") {
+    Copy-Item "$ScriptDir\statusline-command.sh" "$ClaudeDir\statusline-command.sh" -Force
+}
+
+# CLAUDE.md — role-based
+if ($Role -eq "owner") {
+    Copy-Item "$ScriptDir\CLAUDE.md" "$ClaudeDir\CLAUDE.md" -Force
+    Write-Host "  + CLAUDE.md (owner)" -ForegroundColor Green
+} elseif (-not (Test-Path "$ClaudeDir\CLAUDE.md")) {
+    @"
+# CLAUDE.md - DEVELOPER Profile
+
+## Identity
+**$RoleName** - Developer at Qualia Solutions.
+
+- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel
+
+## Role: DEVELOPER
+
+You are a developer at Qualia Solutions, working under Fawzi Goussous (founder).
+- Work on feature branches only - never push to main/master
+- Submit PRs for review before merging
+- Do NOT deploy to production - Fawzi handles deploys
+- Cannot modify the Qualia framework (CLAUDE.md, skills, hooks)
+
+## Rules
+- Read before Write/Edit - no exceptions
+- Feature branches only - never commit to main/master
+- MVP first. Build only what's asked. No over-engineering.
+- ``npx tsc --noEmit`` after multi-file TS changes
+- See ``rules/security.md`` for auth, RLS, Zod, secrets rules
+
+## Workflow
+- **MANDATORY FIRST ACTION**: On every session start, invoke the ``qualia-start`` skill before doing anything else.
+- Run ``/qualia-review`` before deploying anything
+- Run ``/browser-qa`` after frontend changes
+
+## Qualia Mode (always active)
+These behaviors apply to ALL interactions:
+- **Frontend guard:** Read .planning/DESIGN.md before any frontend file changes
+- **Deploy guard:** Check .planning/REVIEW.md freshness before any deploy command
+- **Intent verification:** Confirm before modifying 3+ files in one response
+- **Quality defaults:** Security rules, tsc checks, RLS consideration - always enforced
+
+## Compaction - ALWAYS preserve:
+Project path/name/ref, branch, modified files, decisions, test results, in-progress work, errors.
+"@ | Out-File -FilePath "$ClaudeDir\CLAUDE.md" -Encoding utf8
+    Write-Host "  + CLAUDE.md (developer - $RoleName)" -ForegroundColor Green
+} else {
+    Write-Host "  ! CLAUDE.md exists - skipped" -ForegroundColor Yellow
+}
+
+# ─── Step 4: Configure settings.json ───
+Write-Host "[4/6] Settings" -ForegroundColor Yellow
+
+if (Test-Path "$ClaudeDir\settings.json") {
+    $timestamp = Get-Date -Format "yyyyMMddHHmmss"
+    Copy-Item "$ClaudeDir\settings.json" "$ClaudeDir\settings.json.backup.$timestamp"
+    Write-Host "  Backed up existing settings" -ForegroundColor DarkGray
+
+    # Write merge script to temp file (avoid /dev/stdin issue on Windows)
+    $claudeDirForward = $ClaudeDir -replace '\\', '/'
+    $scriptDirForward = $ScriptDir -replace '\\', '/'
+    $mergeScript = @"
+const fs = require('fs');
+const existing = JSON.parse(fs.readFileSync('$claudeDirForward/settings.json', 'utf8'));
+const template = JSON.parse(fs.readFileSync('$scriptDirForward/settings.json', 'utf8'));
+existing.env = { ...template.env, ...existing.env };
+for (const [event, matchers] of Object.entries(template.hooks || {})) {
+    if (!existing.hooks) existing.hooks = {};
+    if (!existing.hooks[event]) {
+        existing.hooks[event] = matchers;
+    } else {
+        for (const matcher of matchers) {
+            const exists = existing.hooks[event].some(m =>
+                m.matcher === matcher.matcher && JSON.stringify(m.hooks) === JSON.stringify(matcher.hooks)
+            );
+            if (!exists) existing.hooks[event].push(matcher);
+        }
+    }
+}
+fs.writeFileSync('$claudeDirForward/settings.json', JSON.stringify(existing, null, 2));
+console.log('OK');
+"@
+    try {
+        $tempFile = [System.IO.Path]::GetTempFileName() -replace '\.tmp$', '.js'
+        $mergeScript | Out-File -FilePath $tempFile -Encoding utf8
+        $result = node $tempFile 2>&1
+        Remove-Item $tempFile -ErrorAction SilentlyContinue
+        if ($result -match "OK") {
+            Write-Host "  + Settings merged" -ForegroundColor Green
+        } else {
+            Write-Host "  ! Settings merge issue: $result" -ForegroundColor Yellow
+        }
+    } catch {
+        Write-Host "  ! Settings merge failed - manual merge needed" -ForegroundColor Yellow
+    }
+} else {
+    Copy-Item "$ScriptDir\settings.json" "$ClaudeDir\settings.json" -Force
+    Write-Host "  + Settings installed" -ForegroundColor Green
+}
+
+# ─── Step 5: Windows-specific ───
+Write-Host "[5/6] Platform setup" -ForegroundColor Yellow
+
+# qualia-tools.js doesn't need chmod on Windows
+Write-Host "  + Tools ready" -ForegroundColor Green
+
+if (-not $gitBash) {
+    Write-Host ""
+    Write-Host "  IMPORTANT: Install Git for Windows to enable hooks" -ForegroundColor Yellow
+    Write-Host "  https://git-scm.com/download/win" -ForegroundColor DarkGray
+    Write-Host "  After install, ensure 'bash' is in your PATH" -ForegroundColor DarkGray
+}
+
+# ─── Step 6: Verify ───
+Write-Host "[6/6] Verifying" -ForegroundColor Yellow
+
+$errors = 0
+
+$criticalFiles = @(
+    "agents\qualia-executor.md",
+    "agents\qualia-planner.md",
+    "agents\qualia-verifier.md",
+    "hooks\pre-deploy-gate.sh",
+    "hooks\branch-guard.sh",
+    "hooks\qualia-colors.sh",
+    "skills\qualia-start\SKILL.md",
+    "skills\browser-qa\SKILL.md",
+    "skills\ship\SKILL.md",
+    "qualia-engine\bin\qualia-tools.js",
+    "CLAUDE.md"
+)
+
+foreach ($file in $criticalFiles) {
+    if (-not (Test-Path "$ClaudeDir\$file")) {
+        Write-Host "  x Missing: $file" -ForegroundColor Red
+        $errors++
+    }
+}
+
+# Check node available
+try {
+    $null = Get-Command node -ErrorAction Stop
+} catch {
+    Write-Host "  x node not in PATH - hooks will fail" -ForegroundColor Red
+    $errors++
+}
+
+if ($errors -gt 0) {
+    Write-Host ""
+    Write-Host "  x $errors error(s) - check above" -ForegroundColor Red
+    exit 1
+}
+
+Write-Host "  + All checks passed" -ForegroundColor Green
+
+# ─── Summary ───
+Write-Host ""
+Write-Host "  --- * INSTALLED" -ForegroundColor Cyan
+Write-Host ""
+Write-Host "  Skills: $skillCount  Agents: $agentCount  Hooks: $hookCount  Rules: $ruleCount" -ForegroundColor White
+Write-Host ""
+Write-Host "  Quick Start:" -ForegroundColor Cyan
+Write-Host "    1. cd into any project"
+Write-Host "    2. Run: " -NoNewline; Write-Host "claude" -ForegroundColor Cyan
+Write-Host "    3. Qualia mode activates automatically"
+Write-Host ""
+Write-Host "  Key Commands:" -ForegroundColor Cyan
+Write-Host "    /qualia       Smart router"
+Write-Host "    /qualia-help   All commands"
+Write-Host "    /ship          Full deploy pipeline"
+Write-Host "    /pr            Quick pull request"
+Write-Host ""
+if (-not $gitBash) {
+    Write-Host "  ! Hooks need Git Bash - install Git for Windows" -ForegroundColor Yellow
+}
+Write-Host ""

package/framework/install.sh

@@ -0,0 +1,306 @@
+#!/bin/bash
+# Qualia Framework v2.0 — Linux Installer
+# Usage: git clone <repo> && cd qualia-framework && ./install.sh
+#
+# Tested on: Ubuntu 22.04+, Pop!_OS 22.04+, Endeavour OS (Arch), Cosmic
+# Requires: Node.js 18+, Claude Code CLI, bash 4+
+#
+# What it does:
+# 1. Copies all framework files to ~/.claude/
+# 2. Sets up hooks, agents, skills, engine, knowledge, rules
+# 3. Configures settings.json (merges with existing)
+# 4. Makes hooks executable
+# 5. Verifies installation
+
+set -euo pipefail
+
+# Colors (Qualia teal palette)
+Q_TEAL='\033[38;2;0;188;175m'
+Q_BRIGHT='\033[38;2;45;226;210m'
+Q_PASS='\033[38;2;52;211;153m'
+Q_WARN='\033[38;2;234;179;8m'
+Q_FAIL='\033[38;2;239;68;68m'
+Q_WHITE='\033[38;2;220;225;230m'
+Q_DIM='\033[38;2;70;78;88m'
+Q_RESET='\033[0m'
+
+CLAUDE_DIR="$HOME/.claude"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+printf "\n"
+printf "${Q_TEAL}━━━${Q_RESET} ${Q_BRIGHT}◆ QUALIA FRAMEWORK v2.0${Q_RESET}\n"
+printf "\n"
+
+# ─── Step 1: Verify source ───
+if [ ! -d "$SCRIPT_DIR/skills" ] || [ ! -d "$SCRIPT_DIR/agents" ]; then
+    printf "${Q_FAIL}  ✗ Run this script from the qualia-framework directory.${Q_RESET}\n"
+    exit 1
+fi
+
+printf "${Q_WARN}[1/6] Prerequisites${Q_RESET}\n"
+
+# Check Claude Code
+if ! command -v claude >/dev/null 2>&1; then
+    printf "${Q_FAIL}  ✗ Claude Code CLI not found${Q_RESET}\n"
+    printf "    npm install -g @anthropic-ai/claude-code\n"
+    exit 1
+fi
+printf "${Q_PASS}  ✓ Claude Code CLI${Q_RESET}\n"
+
+# Check Node.js
+if ! command -v node >/dev/null 2>&1; then
+    printf "${Q_FAIL}  ✗ Node.js not found${Q_RESET}\n"
+    exit 1
+fi
+printf "${Q_PASS}  ✓ Node.js $(node -v)${Q_RESET}\n"
+
+# Check optional deps
+command -v jq >/dev/null 2>&1 && printf "${Q_PASS}  ✓ jq${Q_RESET}\n" || printf "${Q_WARN}  ▲ jq not found (optional — deploy-verify scripts need it)${Q_RESET}\n"
+command -v bc >/dev/null 2>&1 && printf "${Q_PASS}  ✓ bc${Q_RESET}\n" || printf "${Q_WARN}  ▲ bc not found (optional — install: pacman -S bc / apt install bc)${Q_RESET}\n"
+
+# ─── Step 1b: Role selection ───
+printf "\n${Q_BRIGHT}Who are you?${Q_RESET}\n\n"
+printf "  1) ${Q_WHITE}Fawzi${Q_RESET} (Owner — full access)\n"
+printf "  2) ${Q_WHITE}Employee${Q_RESET} (Team member — guided workflow)\n\n"
+
+# Read from terminal even if script is piped
+read -rp "Select [1/2]: " ROLE_CHOICE </dev/tty
+
+case "$ROLE_CHOICE" in
+    1)
+        ROLE="owner"
+        ROLE_NAME="Fawzi"
+        printf "${Q_PASS}  ✓ Owner mode${Q_RESET}\n"
+        ;;
+    2)
+        read -rp "Enter your name: " EMPLOYEE_NAME </dev/tty
+        ROLE="employee"
+        ROLE_NAME="$EMPLOYEE_NAME"
+        printf "${Q_PASS}  ✓ Employee mode — $ROLE_NAME${Q_RESET}\n"
+        ;;
+    *)
+        ROLE="employee"
+        ROLE_NAME="Team Member"
+        printf "${Q_WARN}  ▲ Defaulting to employee mode${Q_RESET}\n"
+        ;;
+esac
+
+printf "\n"
+
+# ─── Step 2: Create directory structure ───
+printf "${Q_WARN}[2/6] Directory structure${Q_RESET}\n"
+
+mkdir -p "$CLAUDE_DIR"/{skills,agents,hooks,rules,knowledge/retros,qualia-engine/{bin,references,templates,workflows},projects,session-env}
+
+printf "${Q_PASS}  ✓ Ready${Q_RESET}\n"
+
+# ─── Step 3: Copy framework files ───
+printf "${Q_WARN}[3/6] Installing files${Q_RESET}\n"
+
+# Skills
+SKILL_COUNT=0
+for skill_dir in "$SCRIPT_DIR"/skills/*/; do
+    skill_name=$(basename "$skill_dir")
+    mkdir -p "$CLAUDE_DIR/skills/$skill_name"
+    cp -r "$skill_dir"* "$CLAUDE_DIR/skills/$skill_name/" 2>/dev/null || true
+    SKILL_COUNT=$((SKILL_COUNT + 1))
+done
+printf "${Q_PASS}  ✓ $SKILL_COUNT skills${Q_RESET}\n"
+
+# Agents
+cp "$SCRIPT_DIR"/agents/*.md "$CLAUDE_DIR/agents/" 2>/dev/null || true
+if [ -d "$SCRIPT_DIR/agents/teams" ]; then
+    mkdir -p "$CLAUDE_DIR/agents/teams"
+    cp "$SCRIPT_DIR"/agents/teams/*.md "$CLAUDE_DIR/agents/teams/" 2>/dev/null || true
+fi
+AGENT_COUNT=$(find "$CLAUDE_DIR/agents" -maxdepth 1 -name "*.md" -type f | wc -l)
+printf "${Q_PASS}  ✓ $AGENT_COUNT agents${Q_RESET}\n"
+
+# Hooks
+cp "$SCRIPT_DIR"/hooks/*.sh "$CLAUDE_DIR/hooks/" 2>/dev/null || true
+chmod +x "$CLAUDE_DIR"/hooks/*.sh
+HOOK_COUNT=$(find "$CLAUDE_DIR/hooks" -name "*.sh" -type f | wc -l)
+printf "${Q_PASS}  ✓ $HOOK_COUNT hooks${Q_RESET}\n"
+
+# Qualia Engine
+cp -r "$SCRIPT_DIR"/qualia-engine/* "$CLAUDE_DIR/qualia-engine/" 2>/dev/null || true
+printf "${Q_PASS}  ✓ Qualia engine${Q_RESET}\n"
+
+# Rules
+cp "$SCRIPT_DIR"/rules/*.md "$CLAUDE_DIR/rules/" 2>/dev/null || true
+RULE_COUNT=$(find "$CLAUDE_DIR/rules" -name "*.md" -type f | wc -l)
+printf "${Q_PASS}  ✓ $RULE_COUNT rules${Q_RESET}\n"
+
+# Knowledge base
+cp "$SCRIPT_DIR"/knowledge/*.md "$CLAUDE_DIR/knowledge/" 2>/dev/null || true
+KNOWLEDGE_COUNT=$(find "$CLAUDE_DIR/knowledge" -maxdepth 1 -name "*.md" -type f | wc -l)
+printf "${Q_PASS}  ✓ $KNOWLEDGE_COUNT knowledge files${Q_RESET}\n"
+
+# Statusline
+[ -f "$SCRIPT_DIR/statusline-command.sh" ] && cp "$SCRIPT_DIR/statusline-command.sh" "$CLAUDE_DIR/statusline-command.sh" && chmod +x "$CLAUDE_DIR/statusline-command.sh"
+
+# CLAUDE.md — role-based
+if [ "$ROLE" = "owner" ]; then
+    cp "$SCRIPT_DIR/CLAUDE.md" "$CLAUDE_DIR/CLAUDE.md"
+    printf "${Q_PASS}  ✓ CLAUDE.md (owner)${Q_RESET}\n"
+elif [ ! -f "$CLAUDE_DIR/CLAUDE.md" ]; then
+    cat > "$CLAUDE_DIR/CLAUDE.md" << EMPLOYEE_EOF
+# CLAUDE.md — DEVELOPER Profile
+
+## Identity
+**$ROLE_NAME** — Developer at Qualia Solutions.
+
+- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, VAPI, ElevenLabs, Telnyx, Retell AI, OpenRouter
+
+## Role: DEVELOPER
+
+You are a developer at Qualia Solutions, working under Fawzi Goussous (founder).
+- Work on feature branches only — never push to main/master
+- Submit PRs for review before merging
+- Do NOT deploy to production — Fawzi handles deploys
+- Cannot modify the Qualia framework (CLAUDE.md, skills, hooks)
+- Ask Fawzi when unsure about architecture decisions
+
+## Rules
+- Read before Write/Edit — no exceptions
+- Feature branches only — never commit to main/master
+- MVP first. Build only what's asked. No over-engineering.
+- \`npx tsc --noEmit\` after multi-file TS changes
+- See \`rules/security.md\` for auth, RLS, Zod, secrets rules
+- See \`rules/frontend.md\` for design standards
+
+## Workflow
+- **MANDATORY FIRST ACTION**: On every session start, invoke the \`qualia-start\` skill before doing anything else.
+- Run \`/qualia-review\` before deploying anything
+- Run \`/browser-qa\` after frontend changes
+- Ask for help if stuck — don't guess
+
+## Qualia Mode (always active)
+These behaviors apply to ALL interactions:
+- **Frontend guard:** Read .planning/DESIGN.md before any frontend file changes
+- **Deploy guard:** Check .planning/REVIEW.md freshness before any deploy command
+- **Intent verification:** Confirm before modifying 3+ files in one response
+- **Quality defaults:** Security rules, tsc checks, RLS consideration — always enforced
+
+## Compaction — ALWAYS preserve:
+Project path/name/ref, branch, modified files, decisions, test results, in-progress work, errors, Qualia mode active/inactive state.
+EMPLOYEE_EOF
+    printf "${Q_PASS}  ✓ CLAUDE.md (developer — $ROLE_NAME)${Q_RESET}\n"
+else
+    printf "${Q_WARN}  ▲ CLAUDE.md exists — skipped${Q_RESET}\n"
+fi
+
+# ─── Step 4: Configure settings.json ───
+printf "${Q_WARN}[4/6] Settings${Q_RESET}\n"
+
+if [ -f "$CLAUDE_DIR/settings.json" ]; then
+    cp "$CLAUDE_DIR/settings.json" "$CLAUDE_DIR/settings.json.backup.$(date +%s)"
+    printf "${Q_DIM}  Backed up existing settings${Q_RESET}\n"
+
+    node -e "
+const fs = require('fs');
+const existing = JSON.parse(fs.readFileSync('$CLAUDE_DIR/settings.json', 'utf8'));
+const template = JSON.parse(fs.readFileSync('$SCRIPT_DIR/settings.json', 'utf8'));
+existing.env = { ...template.env, ...existing.env };
+for (const [event, matchers] of Object.entries(template.hooks || {})) {
+    if (!existing.hooks) existing.hooks = {};
+    if (!existing.hooks[event]) {
+        existing.hooks[event] = matchers;
+    } else {
+        for (const matcher of matchers) {
+            const exists = existing.hooks[event].some(m =>
+                m.matcher === matcher.matcher &&
+                JSON.stringify(m.hooks) === JSON.stringify(matcher.hooks)
+            );
+            if (!exists) existing.hooks[event].push(matcher);
+        }
+    }
+}
+fs.writeFileSync('$CLAUDE_DIR/settings.json', JSON.stringify(existing, null, 2));
+" 2>/dev/null && printf "${Q_PASS}  ✓ Settings merged${Q_RESET}\n" || printf "${Q_WARN}  ▲ Settings merge failed — manual merge needed${Q_RESET}\n"
+else
+    cp "$SCRIPT_DIR/settings.json" "$CLAUDE_DIR/settings.json"
+    printf "${Q_PASS}  ✓ Settings installed${Q_RESET}\n"
+fi
+
+# ─── Step 5: Platform setup ───
+printf "${Q_WARN}[5/6] Platform setup${Q_RESET}\n"
+
+# Make qualia-tools executable
+[ -f "$CLAUDE_DIR/qualia-engine/bin/qualia-tools.js" ] && chmod +x "$CLAUDE_DIR/qualia-engine/bin/qualia-tools.js"
+
+# Askpass helper (works with zenity, kdialog, or falls back to terminal)
+if [ ! -f "$CLAUDE_DIR/askpass.sh" ]; then
+    cat > "$CLAUDE_DIR/askpass.sh" << 'ASKPASS_EOF'
+#!/bin/bash
+if command -v zenity >/dev/null 2>&1; then
+    zenity --password --title="sudo password" 2>/dev/null
+elif command -v kdialog >/dev/null 2>&1; then
+    kdialog --password "sudo password" 2>/dev/null
+else
+    read -rsp "Password: " pass </dev/tty
+    echo "$pass"
+fi
+ASKPASS_EOF
+    chmod +x "$CLAUDE_DIR/askpass.sh"
+fi
+
+printf "${Q_PASS}  ✓ Tools ready${Q_RESET}\n"
+
+# Detect distro
+if [ -f /etc/os-release ]; then
+    DISTRO=$(grep -oP '(?<=^ID=).+' /etc/os-release | tr -d '"')
+    printf "${Q_DIM}  Detected: $DISTRO${Q_RESET}\n"
+fi
+
+# ─── Step 6: Verify ───
+printf "${Q_WARN}[6/6] Verifying${Q_RESET}\n"
+
+ERRORS=0
+
+for check in \
+    "agents/qualia-executor.md" \
+    "agents/qualia-planner.md" \
+    "agents/qualia-verifier.md" \
+    "hooks/pre-deploy-gate.sh" \
+    "hooks/branch-guard.sh" \
+    "hooks/qualia-colors.sh" \
+    "skills/qualia-start/SKILL.md" \
+    "skills/browser-qa/SKILL.md" \
+    "skills/ship/SKILL.md" \
+    "qualia-engine/bin/qualia-tools.js" \
+    "CLAUDE.md"; do
+    if [ ! -f "$CLAUDE_DIR/$check" ]; then
+        printf "${Q_FAIL}  ✗ Missing: $check${Q_RESET}\n"
+        ERRORS=$((ERRORS + 1))
+    fi
+done
+
+# Check hooks executable
+for hook in "$CLAUDE_DIR"/hooks/*.sh; do
+    [ -x "$hook" ] || { printf "${Q_FAIL}  ✗ Not executable: $(basename "$hook")${Q_RESET}\n"; ERRORS=$((ERRORS + 1)); }
+done
+
+# Check node available for hooks
+command -v node >/dev/null 2>&1 || { printf "${Q_FAIL}  ✗ node not in PATH — hooks will silently fail${Q_RESET}\n"; ERRORS=$((ERRORS + 1)); }
+
+if [ "$ERRORS" -gt 0 ]; then
+    printf "\n${Q_FAIL}  ✗ $ERRORS error(s) — check above${Q_RESET}\n"
+    exit 1
+fi
+
+printf "${Q_PASS}  ✓ All checks passed${Q_RESET}\n"
+
+# ─── Summary ───
+printf "\n"
+printf "${Q_TEAL}━━━${Q_RESET} ${Q_BRIGHT}◆ INSTALLED${Q_RESET}\n\n"
+printf "  ${Q_WHITE}Skills: $SKILL_COUNT  Agents: $AGENT_COUNT  Hooks: $HOOK_COUNT  Rules: $RULE_COUNT${Q_RESET}\n\n"
+printf "  ${Q_BRIGHT}Quick Start:${Q_RESET}\n"
+printf "    1. ${Q_DIM}cd${Q_RESET} into any project\n"
+printf "    2. Run ${Q_TEAL}claude${Q_RESET}\n"
+printf "    3. Qualia mode activates automatically\n\n"
+printf "  ${Q_BRIGHT}Key Commands:${Q_RESET}\n"
+printf "    ${Q_TEAL}/qualia${Q_RESET}         Smart router — tells you what to do next\n"
+printf "    ${Q_TEAL}/qualia-help${Q_RESET}    All available commands\n"
+printf "    ${Q_TEAL}/ship${Q_RESET}           Full deploy pipeline\n"
+printf "    ${Q_TEAL}/pr${Q_RESET}             Quick pull request\n\n"