qualia-framework 2.2.0 → 2.4.0

package/framework/hooks/confirm-delete.sh

@@ -20,8 +20,8 @@ block() {
     cat <<EOJSON
 {
   "continue": false,
-  "stopReason": "◆ DESTRUCTIVE GUARD: $1",
-  "systemMessage": "◆ BLOCKED: $1. Find a safer alternative. Explain to the user what was blocked and what safer approach you're using instead."
+  "stopReason": "◆ BLOCKED: That would $1 — finding a safer way",
+  "systemMessage": "◆ BLOCKED: $1. This could cause damage. Find a safer alternative and explain to the user what was blocked and what safer approach you're using instead."
 }
 EOJSON
     exit 2

package/framework/hooks/migration-validate.sh

@@ -32,7 +32,7 @@ check_sql_file() {
         issues=$((issues + 1))
     fi
     if grep -iE '\bCREATE\s+TABLE\b' "$file" > /dev/null 2>&1 && ! grep -iE '\bENABLE\s+ROW\s+LEVEL\s+SECURITY\b' "$file" > /dev/null 2>&1; then
-        q_warn "New table without RLS in ${file}"
+        q_warn "New table needs security rules (RLS) in ${file} — tell Claude: 'add RLS policies to the new table'"
         issues=$((issues + 1))
     fi
     return $issues
@@ -61,7 +61,7 @@ fi
 
 # Warn but don't block — surface via systemMessage
 if $TRIGGERED && [ "$TOTAL" -gt 0 ]; then
-    printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: %d issue(s) found — review carefully"}' "$TOTAL"
+    printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: %d issue(s) found — tell Claude to review and fix the migration warnings before proceeding."}' "$TOTAL"
 elif $TRIGGERED; then
     printf '{"continue":true,"systemMessage":"◆ MIGRATION CHECK: clean"}'
 fi

package/framework/hooks/pre-commit.sh

@@ -28,7 +28,7 @@ SECRETS_PATTERN="(api[_-]?key|apikey|secret[_-]?key|password|passwd|pwd|token|au
 for file in $STAGED_FILES; do
     if [ -f "$file" ] && grep -iE "$SECRETS_PATTERN" "$file" > /dev/null 2>&1; then
         q_fail "Secret in ${file}"
-        FAIL_DETAILS="${FAIL_DETAILS}Potential secret in ${file}. "
+        FAIL_DETAILS="${FAIL_DETAILS}A password or API key was found in ${file} — tell Claude: 'remove the secret and use an environment variable instead.' "
         BLOCKED=true
     fi
 done
@@ -37,7 +37,7 @@ done
 ENV_FILES=$(echo "$STAGED_FILES" | grep -E '\.env($|\.)' | grep -v '.example' | grep -v '.sample' || true)
 if [ -n "$ENV_FILES" ]; then
     q_fail ".env file staged: ${ENV_FILES}"
-    FAIL_DETAILS="${FAIL_DETAILS}.env file staged for commit. "
+    FAIL_DETAILS="${FAIL_DETAILS}.env file contains secrets and shouldn't be committed — tell Claude: 'unstage the .env file.' "
     BLOCKED=true
 fi
 
@@ -70,7 +70,7 @@ if [ -f "tsconfig.json" ]; then
                 touch "$TSC_STAMP"
             else
                 q_fail "TypeScript errors"
-                FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors. Run npx tsc --noEmit. "
+                FAIL_DETAILS="${FAIL_DETAILS}Code errors found — tell Claude: 'fix the TypeScript errors and try committing again.' "
                 BLOCKED=true
             fi
         fi
@@ -82,7 +82,7 @@ if $BLOCKED; then
 {
   "continue": false,
   "stopReason": "◆ Pre-commit: blocked",
-  "systemMessage": "◆ PRE-COMMIT BLOCKED: ${FAIL_DETAILS}Fix issues, stage corrected files, and retry."
+  "systemMessage": "◆ PRE-COMMIT BLOCKED: ${FAIL_DETAILS}Tell Claude to fix these issues and try committing again."
 }
 EOJSON
     exit 2

package/framework/hooks/pre-deploy-gate.sh

@@ -18,6 +18,7 @@ if ! echo "$COMMAND" | grep -qE 'vercel\s+.*--prod|vercel\s+--prod'; then
     exit 0
 fi
 
+
 # Skip if gate was passed recently (within 5 minutes)
 STAMP="/tmp/.deploy-gate-$(echo "$PWD" | md5sum | cut -c1-8)"
 if [ -f "$STAMP" ]; then
@@ -39,7 +40,7 @@ if [ -f "tsconfig.json" ]; then
         q_pass "TypeScript"
     else
         q_fail "TypeScript errors"
-        FAIL_DETAILS="${FAIL_DETAILS}TypeScript errors found. Run npx tsc --noEmit to see details. "
+        FAIL_DETAILS="${FAIL_DETAILS}Code errors found — tell Claude: 'fix the TypeScript errors' before deploying. "
         FAILURES=$((FAILURES + 1))
     fi
 else
@@ -52,7 +53,7 @@ if [ -f ".eslintrc.json" ] || [ -f ".eslintrc.js" ] || [ -f "eslint.config.js" ]
         q_pass "Lint"
     else
         q_fail "Lint errors"
-        FAIL_DETAILS="${FAIL_DETAILS}ESLint errors found. Run npx eslint . to see details. "
+        FAIL_DETAILS="${FAIL_DETAILS}Code quality issues found — tell Claude: 'fix the lint errors' before deploying. "
         FAILURES=$((FAILURES + 1))
     fi
 else
@@ -67,7 +68,7 @@ if [ -f "package.json" ]; then
             q_pass "Tests"
         else
             q_fail "Tests failed"
-            FAIL_DETAILS="${FAIL_DETAILS}Tests failed. Run npm test to see details. "
+            FAIL_DETAILS="${FAIL_DETAILS}Tests are failing — tell Claude: 'fix the failing tests' before deploying. "
             FAILURES=$((FAILURES + 1))
         fi
     else
@@ -75,23 +76,7 @@ if [ -f "package.json" ]; then
     fi
 fi
 
-# ─── Check 4: Build ───
-if [ -f "package.json" ]; then
-    BUILD_SCRIPT=$(node -e "try{console.log(require('./package.json').scripts?.build||'')}catch(e){console.log('')}" 2>/dev/null)
-    if [ -n "$BUILD_SCRIPT" ]; then
-        if npm run build 2>/tmp/build-gate.txt 1>/dev/null; then
-            q_pass "Build"
-        else
-            q_fail "Build failed"
-            FAIL_DETAILS="${FAIL_DETAILS}Build failed. Run npm run build to see errors. "
-            FAILURES=$((FAILURES + 1))
-        fi
-    else
-        q_skip "Build"
-    fi
-fi
-
-# ─── Check 5: Environment ───
+# ─── Check 4: Environment ───
 if [ -f ".env.example" ] && [ ! -f ".env.local" ] && [ ! -f ".env" ]; then
     q_warn "Missing .env.local"
     WARNINGS=$((WARNINGS + 1))
@@ -132,7 +117,7 @@ if [ "$FAILURES" -gt 0 ]; then
 {
   "continue": false,
   "stopReason": "◆ Deploy gate: ${FAILURES} check(s) failed",
-  "systemMessage": "◆ DEPLOY BLOCKED: ${FAILURES} check(s) failed. ${FAIL_DETAILS}Fix and retry vercel --prod."
+  "systemMessage": "◆ DEPLOY BLOCKED: ${FAILURES} check(s) failed. ${FAIL_DETAILS}Fix issues and retry with /ship."
 }
 EOJSON
     exit 2

package/framework/hooks/session-context-loader.sh

@@ -56,7 +56,7 @@ fi
 
 # Check settings.json valid
 if [ -f "$HOME/.claude/settings.json" ]; then
-    node -e "JSON.parse(require('fs').readFileSync('$HOME/.claude/settings.json','utf8'))" 2>/dev/null
+    node -e "JSON.parse(require('fs').readFileSync(require('path').join(require('os').homedir(),'.claude','settings.json'),'utf8'))" 2>/dev/null
     if [ $? -ne 0 ]; then
         ISSUES="${ISSUES}settings.json invalid. "
     fi

package/framework/install.sh

@@ -150,14 +150,13 @@ elif [ ! -f "$CLAUDE_DIR/CLAUDE.md" ]; then
 ## Identity
 **$ROLE_NAME** — Developer at Qualia Solutions.
 
-- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, VAPI, ElevenLabs, Telnyx, Retell AI, OpenRouter
+- Stack: Next.js 16+, React 19, TypeScript, Supabase, Vercel, Retell AI, ElevenLabs, Telnyx, 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
+- Use \`/ship\` to deploy — it runs quality gates, auto-creates feature branches, and deploys
 - Cannot modify the Qualia framework (CLAUDE.md, skills, hooks)
 - Ask Fawzi when unsure about architecture decisions
 
@@ -169,10 +168,16 @@ You are a developer at Qualia Solutions, working under Fawzi Goussous (founder).
 - See \`rules/security.md\` for auth, RLS, Zod, secrets rules
 - See \`rules/frontend.md\` for design standards
 
+## Getting Started
+- Run \`/collab-onboard\` when joining a new project — it explains what's built and how to contribute
+- Onboarding guide: ~/Projects/qualia-erp/docs/trainee-onboarding.md
+
 ## Workflow
 - **MANDATORY FIRST ACTION**: On every session start, invoke the \`qualia-start\` skill before doing anything else.
-- Run \`/qualia-review\` before deploying anything
+- Run \`/qualia-review\` before deploying
 - Run \`/browser-qa\` after frontend changes
+- Run \`/pr\` to submit work for review — never push to main directly
+- Run \`/qualia-idk\` if stuck — it suggests next steps and can escalate to Fawzi
 - Ask for help if stuck — don't guess
 
 ## Qualia Mode (always active)

package/framework/qualia-engine/VERSION

@@ -1 +1 @@
-1.14.0
+2.4.0

package/framework/qualia-engine/templates/projects/ai-agent.md

@@ -74,7 +74,7 @@
 
 ### Phase 4: Admin Panel
 **Goal:** Admin interface for managing the AI agent: prompts, users, analytics
-**Skills:** [@admin-panel, @supabase]
+**Skills:** [@supabase, @frontend-master]
 **Tasks:**
 - Admin auth (role-based, separate from user auth)
 - System prompt editor (CRUD, version history)

package/framework/qualia-engine/templates/projects/voice-agent.md

@@ -1,8 +1,8 @@
 # Project Template: Voice Agent
 
-> Voice AI agent with Supabase Edge Functions, VAPI/Retell AI, and ElevenLabs.
+> Voice AI agent with Supabase Edge Functions, Retell AI, and ElevenLabs.
 
-**Stack:** Supabase Edge Functions (Deno), VAPI / Retell AI, ElevenLabs, TypeScript
+**Stack:** Supabase Edge Functions (Deno), Retell AI, ElevenLabs, TypeScript
 **Phases:** 6
 **Type:** voice-agent
 
@@ -14,7 +14,7 @@
 **Tasks:**
 - Design Supabase schema: calls, call_events, contacts, tools, system_config
 - Create edge function scaffold (Deno, cors headers, error handling)
-- Configure voice provider (VAPI or Retell AI): API keys, assistant creation
+- Configure Retell AI: API keys, agent creation, ElevenLabs voice selection
 - Environment variables in Supabase (voice provider keys, webhook secret)
 - Basic webhook endpoint that receives and logs call events
 - RLS policies on all tables
@@ -32,7 +32,7 @@
 **Skills:** [@voice-agent]
 **Tasks:**
 - Design conversation flow (state machine: greeting → discovery → action → closing)
-- Create VAPI/Retell assistant configuration (system prompt, voice, language)
+- Create Retell AI agent configuration (system prompt, voice, language)
 - Define conversation states and transitions
 - Slot filling logic (extract key info from conversation)
 - Multi-language support (if applicable — e.g., Greek/English/Russian)

package/framework/qualia-engine/templates/roadmap.md

@@ -113,6 +113,16 @@ Phases execute in numeric order: 2 → 2.1 → 2.2 → 3 → 3.1 → 4
 - Progress table updated by execute workflow
 - Plan count can be "TBD" initially, refined during planning
 
+**MANDATORY FINAL PHASES — Every client project must end with these 3 phases:**
+
+| Phase | Name | What it does | Skills used |
+|-------|------|-------------|-------------|
+| N-2 | **Quality Review & Polish** | Code review (`/qualia-review`), design polish (`/critique` → `/polish` → `/harden`), fix all issues. No new features. | @qualia-review, @critique, @polish, @harden |
+| N-1 | **Deploy & Verify** | Deploy to production (`/ship`). Run 5-check post-deploy verification (HTTP 200, auth flow, console errors, API latency, UptimeRobot). | @ship, @deploy-verify |
+| N | **Client Handoff** | Generate client delivery document (`/client-handoff`). Final production audit (`/qualia-production-check`). Hand over credentials, docs, and access. | @client-handoff, @qualia-production-check |
+
+These are NOT optional. The roadmapper must always include them as the final 3 phases. Feature phases come first, then these 3 close out the milestone. An employee following the roadmap will naturally reach client handoff without having to discover it on their own.
+
 **Success criteria:**
 - 2-5 observable behaviors per phase (from user's perspective)
 - Cross-checked against requirements during roadmap creation

package/framework/qualia-engine/templates/state.md

@@ -21,6 +21,7 @@ See: .planning/PROJECT.md (updated [date])
 Phase: [X] of [Y] ([Phase name])
 Plan: [A] of [B] in current phase
 Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete]
+Assigned to: [employee name or "unassigned"]
 Last activity: [YYYY-MM-DD] — [What happened]
 
 Progress: [░░░░░░░░░░] 0%
@@ -69,6 +70,7 @@ None yet.
 ## Session Continuity
 
 Last session: [YYYY-MM-DD HH:MM]
+Last worked by: [employee name]
 Stopped at: [Description of last completed action]
 Resume file: [Path to .continue-here*.md if exists, otherwise "None"]
 ```
@@ -127,6 +129,7 @@ Where we are right now:
 - Phase X of Y — which phase
 - Plan A of B — which plan within phase
 - Status — current state
+- Assigned to — which employee is working on this phase
 - Last activity — what happened most recently
 - Progress bar — visual indicator of overall completion
 

package/framework/qualia-engine/workflows/new-project.md

@@ -13,7 +13,7 @@ Read all files referenced by the invoking prompt's execution_context before star
 **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:**
 
 ```bash
-INIT=$(node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js init new-project)
+INIT=$(node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js init new-project)
 ```
 
 Parse JSON for: `researcher_model`, `synthesizer_model`, `roadmapper_model`, `commit_docs`, `project_exists`, `has_codebase_map`, `planning_exists`, `has_existing_code`, `has_package_file`, `is_brownfield`, `needs_codebase_map`, `has_git`.
@@ -137,7 +137,7 @@ Use AskUserQuestion:
   - "Skip template" — Build roadmap from scratch through full questioning
 
 **If "Use template":**
-1. Read the template: `~/.claude/qualia-engine/templates/projects/{type}.md`
+1. Read the template: `~/.claude/qualia-framework/templates/projects/{type}.md`
 2. Store template choice in memory for Step 8 (roadmap creation)
 3. Set `template_type` = detected type
 4. Set `template_phases` = phases from template file
@@ -225,7 +225,7 @@ Do not compress. Capture everything gathered.
 
 ```bash
 mkdir -p .planning
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: initialize project" --files .planning/PROJECT.md
 ```
 
 ## 5. Workflow Preferences
@@ -342,7 +342,7 @@ Create `.planning/config.json` with all settings:
 **Commit config.json:**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "chore: add project config" --files .planning/config.json
 ```
 
 **Note:** Run `/qualia:settings` anytime to update these preferences.
@@ -430,7 +430,7 @@ Your STACK.md feeds into roadmap creation. Be prescriptive:
 
 <output>
 Write to: .planning/research/STACK.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/STACK.md
+Use template: /home/qualia/.claude/qualia-framework/templates/research-project/STACK.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")
 
@@ -470,7 +470,7 @@ Your FEATURES.md feeds into requirements definition. Categorize clearly:
 
 <output>
 Write to: .planning/research/FEATURES.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/FEATURES.md
+Use template: /home/qualia/.claude/qualia-framework/templates/research-project/FEATURES.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Features research")
 
@@ -510,7 +510,7 @@ Your ARCHITECTURE.md informs phase structure in roadmap. Include:
 
 <output>
 Write to: .planning/research/ARCHITECTURE.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/ARCHITECTURE.md
+Use template: /home/qualia/.claude/qualia-framework/templates/research-project/ARCHITECTURE.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")
 
@@ -550,7 +550,7 @@ Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
 
 <output>
 Write to: .planning/research/PITFALLS.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/PITFALLS.md
+Use template: /home/qualia/.claude/qualia-framework/templates/research-project/PITFALLS.md
 </output>
 ", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")
 ```
@@ -573,7 +573,7 @@ Read these files:
 
 <output>
 Write to: .planning/research/SUMMARY.md
-Use template: /home/qualia/.claude/qualia-engine/templates/research-project/SUMMARY.md
+Use template: /home/qualia/.claude/qualia-framework/templates/research-project/SUMMARY.md
 Commit after writing.
 </output>
 ", subagent_type="qualia-research-synthesizer", model="{synthesizer_model}", description="Synthesize research")
@@ -729,7 +729,7 @@ If "adjust": Return to scoping.
 **Commit requirements:**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: define v1 requirements" --files .planning/REQUIREMENTS.md
 ```
 
 ## 8. Create Roadmap
@@ -765,7 +765,7 @@ Task(prompt="
 
 <template_context>
 Template type: {template_type or 'none'}
-{If template_type is set, inline the full template file content from ~/.claude/qualia-engine/templates/projects/{template_type}.md}
+{If template_type is set, inline the full template file content from ~/.claude/qualia-framework/templates/projects/{template_type}.md}
 </template_context>
 
 <instructions>
@@ -775,8 +775,13 @@ Create roadmap:
 3. Map every v1 requirement to exactly one phase
 4. Derive 2-5 success criteria per phase (observable user behaviors)
 5. Validate 100% coverage
-6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
-7. Return ROADMAP CREATED with summary
+6. **MANDATORY: After all feature phases, add these 3 final phases:**
+   - **Quality Review & Polish** — code review (/qualia-review), design polish (/critique → /polish → /harden), fix all issues. No new features.
+   - **Deploy & Verify** — deploy to production (/ship), 5-check post-deploy verification (HTTP 200, auth, console, latency, UptimeRobot).
+   - **Client Handoff** — generate delivery document (/client-handoff), final production audit (/qualia-production-check), hand over credentials and docs.
+   These 3 phases are NOT optional for client projects. They ensure the project goes from "features done" to "client has their project."
+7. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
+8. Return ROADMAP CREATED with summary
 
 Write files first, then return. This ensures artifacts persist even if context is lost.
 </instructions>
@@ -866,7 +871,7 @@ Use AskUserQuestion:
 **Commit roadmap (after approval):**
 
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "docs: create roadmap ([N] phases)" --files .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
 ```
 
 ## 9. Environment Setup
@@ -969,7 +974,7 @@ This runs ONCE per project. All subsequent `/qualia:execute-phase` runs will hav
 
 **Commit setup:**
 ```bash
-node /home/qualia/.claude/qualia-engine/bin/qualia-tools.js commit "chore: environment setup" --files .env.local supabase/config.toml
+node /home/qualia/.claude/qualia-framework/bin/qualia-tools.js commit "chore: environment setup" --files .env.local supabase/config.toml
 ```
 
 Ensure `.env.local` is in `.gitignore` (create/append if needed).
@@ -1002,14 +1007,10 @@ Present completion with next steps:
 
 **Phase 1: [Phase Name]** — [Goal from ROADMAP.md]
 
-/qualia:discuss-phase 1 — gather context and clarify approach
-
-<sub>/clear first → fresh context window</sub>
-
----
+/qualia-plan-phase 1 — plan the first phase
 
 **Also available:**
-- /qualia:plan-phase 1 — skip discussion, plan directly
+- /qualia-discuss-phase 1 — discuss approach before planning
 
 ───────────────────────────────────────────────────────────────
 ```

package/framework/skills/client-handoff/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: client-handoff
+description: "Generate client-facing project deliverables — handoff document, feature summary, credentials guide, known limitations, and maintenance notes. Use this skill whenever the user says 'handoff', 'client handoff', 'wrap up for client', 'project handoff', 'deliver to client', 'client delivery', 'hand over', or wants to prepare a project for client delivery. Also trigger after milestone completion when next step is client-facing."
+tags: [client, handoff, delivery, documentation]
+---
+
+# Client Handoff — Project Delivery Document Generator
+
+Generate a polished, client-facing HANDOFF.md when a project is ready for delivery. Output is written for non-technical clients.
+
+## Usage
+
+`/client-handoff` — Generate handoff document for the current project
+
+## Process
+
+### Step 1: Load Project Context
+
+Read the following files to build a full picture of what was built and for whom:
+
+- `.planning/PROJECT.md` — project name, client, deploy target
+- `.planning/ROADMAP.md` — what was built (phases)
+- `.planning/REQUIREMENTS.md` — what was requested
+- `.planning/STATE.md` — milestone status
+- Phase `SUMMARY.md` files — what was actually delivered per phase
+- `CHANGELOG.md` — if exists
+- `package.json` — for project name/URLs
+
+Also detect:
+- **Production URL** from Vercel project settings or PROJECT.md
+- **Supabase project ref** (if applicable) — check `.env.local` variable names or PROJECT.md
+- **Auth method** used (email/password, magic link, OAuth, etc.)
+
+If any critical file is missing, note it and proceed with what's available. Do NOT block on missing files.
+
+### Step 2: Generate HANDOFF.md at Project Root
+
+Write the document using this exact structure. All copy must be **plain language** — no jargon, no technical implementation details. Written for someone who has never seen the codebase.
+
+```markdown
+# {Project Name} — Client Handoff
+
+## Live URL
+{production URL}
+
+## What We Built
+{Plain-language summary of features, NOT technical. Written for the client.}
+- Feature 1: {what it does for the user}
+- Feature 2: {what it does for the user}
+...
+
+## How to Use
+{Brief walkthrough of the main user flows — written for someone who's never seen the app}
+
+### For admins (if applicable)
+- How to access the admin panel
+- Key admin actions
+
+## Access & Credentials
+| Service | URL | How to Access |
+|---------|-----|---------------|
+| Website | {url} | Public |
+| Admin Panel | {url}/admin | Login with your email |
+| Supabase Dashboard | https://supabase.com/dashboard/project/{ref} | Fawzi manages access |
+| Vercel Dashboard | vercel.com | Fawzi manages access |
+| Domain/DNS | {registrar} | Client manages |
+
+> **Note:** API keys and database credentials are managed by Qualia Solutions. Contact us if you need access changes.
+
+## Known Limitations
+{Anything that doesn't work yet, scope that was deferred, or edge cases the client should know about}
+
+## Maintenance & Support
+- **Hosting:** Vercel (auto-deploys from GitHub)
+- **Database:** Supabase (managed Postgres)
+- **Monitoring:** UptimeRobot — {monitoring URL if set up}
+- **Updates:** Contact Qualia Solutions for feature requests or bug fixes
+- **Domain renewal:** {who manages it, when it expires if known}
+
+## Technical Reference (for developers)
+- **Stack:** {e.g. Next.js + React + TypeScript + Supabase + Tailwind}
+- **Repo:** {GitHub URL}
+- **Branch:** main
+- **Deploy:** Push to main auto-deploys to Vercel
+```
+
+Adapt the template to the project:
+- Remove sections that don't apply (e.g. no admin panel = skip that subsection)
+- Add sections if needed (e.g. mobile app = add app store links)
+- Adjust the tech stack line to match what was actually used
+- If no Supabase, remove that row from the credentials table
+
+### Step 3: Confirm with User
+
+Display the full generated document and ask:
+
+> "Here's the client handoff document. Review it and let me know if anything needs adjusting before I save it."
+
+Do NOT write the file until the user confirms. Wait for approval or edits.
+
+### Step 4: Save & Commit
+
+After user approval, write `HANDOFF.md` to the project root and commit:
+
+```bash
+git add HANDOFF.md
+git commit -m "docs: add client handoff document"
+```
+
+### Step 5: Route Next Steps
+
+After saving, present options:
+
+> "Handoff document saved. Next steps:"
+> - "Share `HANDOFF.md` content with the client (email, PDF, or portal)"
+> - "Run `/qualia-production-check` to verify everything works before handoff"
+> - "Run `/ship` to deploy any final changes first"
+
+## Guidelines
+
+- **Tone:** Professional but warm. The client is not a developer.
+- **No secrets:** Never include API keys, service role keys, or database passwords in the document.
+- **No jargon:** Avoid terms like "RLS", "middleware", "SSR", "edge functions" in client-facing sections. The Technical Reference section at the bottom is the only place for developer terminology.
+- **Honest about limitations:** If something was descoped or has known issues, say so clearly. Clients respect transparency.
+- **Keep it short:** The document should be scannable in 2 minutes. If a section needs more detail, link to separate docs rather than bloating the handoff.

package/framework/skills/collab-onboard/SKILL.md

@@ -0,0 +1,111 @@
+---
+name: collab-onboard
+description: "Project-specific onboarding for new collaborators — reads .planning/ and codebase to generate orientation: what's built, patterns used, how to contribute, current state. Use this skill whenever the user says 'onboard me', 'new to this project', 'what's been built', 'orient me', 'project overview', 'get me up to speed', 'collab-onboard', or is clearly a new developer joining an existing project. Also trigger when someone asks 'how does this project work' or 'what should I know about this codebase'."
+tags: [onboarding, project, orientation, developer]
+---
+
+## Process
+
+### Step 1: Gather Project Context
+
+Read all of these (skip if missing):
+```bash
+cat .planning/PROJECT.md 2>/dev/null || echo "NO_PROJECT"
+cat .planning/ROADMAP.md 2>/dev/null || echo "NO_ROADMAP"
+cat .planning/STATE.md 2>/dev/null || echo "NO_STATE"
+cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
+```
+
+```bash
+# Project structure
+ls -d app/ src/ pages/ components/ lib/ actions/ hooks/ supabase/ types/ public/ 2>/dev/null
+```
+
+```bash
+# Package info
+node -e "try{const p=require('./package.json');console.log(JSON.stringify({name:p.name,deps:Object.keys(p.dependencies||{}),scripts:Object.keys(p.scripts||{})},null,2))}catch(e){console.log('{}')}" 2>/dev/null
+```
+
+```bash
+# Git history summary
+git log --oneline -20 2>/dev/null
+git shortlog -s -n --all 2>/dev/null | head -5
+```
+
+```bash
+# Check for local CLAUDE.md
+cat CLAUDE.md 2>/dev/null || echo "NO_LOCAL_CLAUDE"
+```
+
+### Step 2: Analyze Codebase
+
+Understand:
+- What framework/stack is used
+- Key directories and their purpose
+- Database tables (from supabase/migrations/ or types/)
+- API routes or server actions
+- Auth pattern used
+- Key environment variables needed
+
+### Step 3: Present Orientation
+
+Output a structured orientation (NOT saved to file — just presented):
+
+```
+◆ PROJECT ORIENTATION
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+  Project    {name}
+  Stack      Next.js + Supabase + Vercel
+  Status     Phase {N}/{total} — {phase name}
+
+── WHAT THIS PROJECT DOES ─────────────────
+  {2-3 sentence plain-language summary}
+
+── WHAT'S BEEN BUILT ──────────────────────
+  ✓ Phase 1: {name} — {1-line summary}
+  ✓ Phase 2: {name} — {1-line summary}
+  ◆ Phase 3: {name} — in progress
+  · Phase 4: {name} — not started
+
+── KEY DIRECTORIES ────────────────────────
+  app/          Pages and routes
+  components/   UI components
+  lib/          Utilities, Supabase clients
+  actions/      Server actions (mutations)
+  supabase/     Migrations and edge functions
+
+── PATTERNS TO FOLLOW ─────────────────────
+  - Server Components by default, 'use client' only for interactivity
+  - Server Actions for all mutations (check auth first)
+  - Supabase server client from lib/supabase/server.ts
+  - RLS on every table — no exceptions
+  - {any project-specific patterns from CLAUDE.md}
+
+── GETTING STARTED ────────────────────────
+  1. npm install
+  2. Copy .env.example to .env.local and fill in values
+  3. supabase start (for local dev) OR use linked project
+  4. npm run dev
+  5. Read .planning/ROADMAP.md for full project plan
+
+── CURRENT WORK ───────────────────────────
+  → Phase {N}: {name}
+  → Status: {planned/executing/verifying}
+  → Next command: /qualia-{action} {N}
+
+── WHO TO ASK ─────────────────────────────
+  Architecture decisions → Fawzi
+  Framework questions → /qualia-help
+  Stuck on anything → /qualia-idk
+```
+
+### Step 4: Offer Deep Dive
+
+> "Want me to explain any specific part in more detail? Options:"
+> - "Walk me through the database schema"
+> - "Explain the auth flow"
+> - "Show me the API/action patterns"
+> - "What's the current phase about?"
+
+Keep it practical. This is for a developer who needs to start contributing today, not a documentation exercise.