qualia-framework 3.2.0 → 3.2.1

package/skills/qualia-design/SKILL.md

@@ -25,7 +25,7 @@ node ~/.claude/bin/qualia-ui.js banner design
 cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
 ```
 
-If DESIGN.md exists → use it. If not → use Qualia defaults: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
+If DESIGN.md exists → it is law. Use exact values from sections 1-9 (Visual Theme, Color Palette, Typography, Components, Layout, Depth, Do's/Don'ts, Responsive, Agent Prompt Guide). If not → use Qualia defaults from `rules/frontend.md`: distinctive fonts, sharp accents, layered backgrounds, no card grids, no blue-purple gradients, full-width layouts.
 
 ### 2. Find Target Files
 
@@ -41,19 +41,25 @@ Evaluate each file on: AI slop detection, visual hierarchy, typography, color, s
 
 ### 4. Fix Everything
 
-**Typography:** Replace generic fonts (Inter, Arial) with distinctive ones. Proper type scale, line-height 1.5-1.7 body.
+Use exact values from DESIGN.md when available. Sections map to fixes:
 
-**Color:** Cohesive palette from DESIGN.md or brand. Sharp accent for CTAs. WCAG AA contrast.
+**Typography (§3):** Apply fonts from hierarchy table. Replace any generic fonts (Inter, Arial) with project fonts. Use exact weights, sizes, letter-spacing from the table. Body line-height 1.5-1.7.
 
-**Layout:** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
+**Color (§2):** Apply palette from CSS variables. Replace scattered hex values with `var(--color-*)`. Verify contrast ratios listed in DESIGN.md.
 
-**Spacing:** Consistent scale (8px grid). Generous whitespace between sections, tight within groups.
+**Components (§4):** Match button, card, input, badge specs exactly — padding, radius, shadow, hover states.
 
-**Motion:** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
+**Layout (§5):** Full-width with fluid padding `clamp(1rem, 5vw, 4rem)`. Apply spacing scale. NO hardcoded max-width caps. Prose gets `max-width: 65ch`.
 
-**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on interactive elements.
+**Depth (§6):** Apply shadow levels from elevation table. Use brand-tinted shadows, not neutral gray.
 
-**Responsive:** Mobile-first. Touch targets 44x44px min. Stack on mobile, expand on desktop. No horizontal scroll.
+**Motion (§Motion):** CSS transitions 200-300ms on hover/focus. Staggered entrance animations. `prefers-reduced-motion` respected.
+
+**States:** Loading skeleton/spinner on async ops. Error states on data fetches. Empty states on lists. Hover/focus/active/disabled on every interactive element.
+
+**Responsive (§8):** Apply collapsing strategy from table. Mobile-first. Touch targets 44x44px min. No horizontal scroll.
+
+**Anti-Slop (§12):** Run grep patterns from the detection table. Every match = mandatory fix.
 
 **Kill:** Card grids → varied layouts. Generic heroes → distinctive. Blue-purple gradients → brand colors. Static pages → purposeful motion. Fixed widths → fluid.
 

package/skills/qualia-help/SKILL.md

@@ -0,0 +1,60 @@
+---
+name: qualia-help
+description: "Open the Qualia Framework reference guide in the browser. A beautiful themed HTML page with all commands, rules, services, and the road. Trigger on 'help', 'how does this work', 'show me the commands', 'qualia help', 'reference'."
+---
+
+# /qualia-help — Framework Reference
+
+Opens a Qualia-themed HTML reference guide in your default browser.
+
+## Process
+
+### 1. Generate the HTML
+
+```bash
+# Read the template and inject the current version
+VERSION=$(node -e "console.log(require(require('os').homedir() + '/.claude/.qualia-config.json').version || 'v3')" 2>/dev/null || echo "v3")
+TEMPLATE="$HOME/.claude/qualia-templates/help.html"
+OUTPUT="/tmp/qualia-help.html"
+
+# If template doesn't exist, check the framework install
+if [ ! -f "$TEMPLATE" ]; then
+  TEMPLATE="$(dirname "$(dirname "$(which qualia-framework 2>/dev/null || echo '')")")/templates/help.html"
+fi
+```
+
+### 2. Inject version and open
+
+```bash
+# Replace {{VERSION}} placeholder with actual version
+sed "s/{{VERSION}}/$VERSION/g" "$TEMPLATE" > "$OUTPUT"
+
+# Open in default browser (cross-platform)
+if command -v xdg-open &>/dev/null; then
+  xdg-open "$OUTPUT"          # Linux
+elif command -v open &>/dev/null; then
+  open "$OUTPUT"               # macOS
+elif command -v start &>/dev/null; then
+  start "$OUTPUT"              # Windows (Git Bash)
+else
+  echo "Open this file in your browser: $OUTPUT"
+fi
+```
+
+### 3. Confirm
+
+```bash
+node ~/.claude/bin/qualia-ui.js banner router
+node ~/.claude/bin/qualia-ui.js ok "Reference guide opened in browser"
+node ~/.claude/bin/qualia-ui.js info "File: /tmp/qualia-help.html"
+```
+
+If the browser does not open automatically, tell the user the file path so they can open it manually.
+
+## Notes
+
+- The HTML file is self-contained — no external dependencies except Google Fonts
+- Works offline after first load (fonts cache)
+- Qualia-themed: dark background, teal accents, Outfit + Inter fonts
+- Shows: The Road, all commands grouped, verification scoring, rules, stack, GitHub orgs
+- Version is injected dynamically from .qualia-config.json

package/skills/qualia-learn/SKILL.md

@@ -46,17 +46,40 @@ What did you learn?
 3. Client preference — client-specific requirement
 ```
 
-### 2. Format Entry
+### 2. Check for Duplicates
+
+Before saving, check if a similar entry already exists:
+
+```bash
+# Search for the title (case-insensitive substring match)
+grep -i "{title keywords}" ~/.claude/knowledge/{type}.md 2>/dev/null
+```
+
+If a near-match exists (title is similar to an existing entry):
+- Show the existing entry to the user
+- Ask: "A similar entry exists. Update it, create a new one, or skip?"
+- If update: replace the existing entry. If new: append. If skip: done.
+
+### 3. Format Entry
+
+Each entry gets a unique ID and ISO timestamp for dedup and ordering:
 
 ```markdown
-### {Title} ({date})
+
+---
+
+### {Title}
+**ID:** {random 8-char hex, e.g. a3f7c1e9}
+**Date:** {ISO 8601, e.g. 2026-04-11}
 **Project:** {current project name or "general"}
 **Context:** {brief context — what you were building when you learned this}
 
 {The learning — be specific enough that future-you understands without context}
 ```
 
-### 3. Append to Knowledge File
+### 4. Append to Knowledge File
+
+Append-only — never overwrite the file, always add at the end:
 
 ```bash
 # Append to the right file
@@ -67,7 +90,7 @@ echo "{formatted entry}" >> ~/.claude/knowledge/{type}.md
 - Fix → `~/.claude/knowledge/common-fixes.md`
 - Client pref → `~/.claude/knowledge/client-prefs.md`
 
-### 4. Confirm
+### 5. Confirm
 
 ```
 ⬢ Saved to {file}

package/skills/qualia-polish/SKILL.md

@@ -1,11 +1,24 @@
 ---
 name: qualia-polish
-description: "Design and UX pass — critique, polish, harden. Run after all phases are verified."
+description: "Design and UX pass — anti-AI-slop, genuine craft, responsive, accessible. Run after all phases are verified."
 ---
 
 # /qualia-polish — Design Pass
 
-Run after all feature phases are verified. Makes it look production-ready.
+Makes it look like a human designer built it. Kills AI slop. Run after all feature phases are verified.
+
+## The Standard
+
+Every site Qualia ships must feel **designed, not generated.** AI-generated sites have tells:
+- Identical card grids with rounded corners and soft shadows
+- Blue-purple gradients on everything
+- Inter/system-ui font with no hierarchy
+- Generic hero with centered text and a stock gradient background
+- Fixed-width containers leaving dead space on wide screens
+- No motion, no personality, no opinion
+- Perfect symmetry everywhere (real design has tension)
+
+**Kill all of these.** A Qualia site should make someone ask "who designed this?" — not "which template is this?"
 
 ## Process
 
@@ -19,139 +32,176 @@ node ~/.claude/bin/qualia-ui.js banner polish
 cat .planning/DESIGN.md 2>/dev/null || echo "NO_DESIGN"
 ```
 
-If DESIGN.md exists → use it as the standard. If not → use Qualia defaults from `rules/frontend.md`.
+If DESIGN.md exists → it's the standard. Read ALL 12 sections. Key sections for polish:
+- §1 Visual Theme — the feel and signature details
+- §2 Color Palette — exact hex values, CSS variables, contrast ratios
+- §3 Typography — hierarchy table with exact sizes/weights/spacing
+- §4 Components — exact button/card/input/badge specs
+- §5 Layout — spacing scale, grid strategy
+- §6 Depth & Elevation — shadow levels with exact rgba values
+- §7 Do's/Don'ts — brand-specific guardrails
+- §9 Agent Prompt Guide — quick reference for common patterns
+- §10 Accessibility — WCAG checklist
+- §11 Hardening — stress-test criteria
+- §12 Anti-Slop Detection — grep patterns for automated checks
+
+If no DESIGN.md → use `rules/frontend.md` defaults.
 
 Read EVERY frontend file before modifying. No blind edits.
 
-### 1. Critique (Structured Audit)
-
-Review the entire UI against this checklist. Check each item, note violations with file:line.
-
-**Typography:**
-- [ ] No generic fonts (Inter, Roboto, Arial, system-ui, Space Grotesk)
-- [ ] Proper type scale with clear hierarchy (display → heading → body → caption)
-- [ ] Body text: 16px+, line-height 1.5–1.7
-- [ ] Headings: tighter line-height (1.1–1.3), negative letter-spacing for large sizes
-- [ ] Prose max-width: 65ch
-- [ ] Font weights used for hierarchy (Regular, Medium, Semibold, Bold)
-
-**Color & Contrast:**
-- [ ] Cohesive palette via CSS variables (not scattered hex values)
-- [ ] All text passes WCAG AA contrast (4.5:1 normal, 3:1 large)
-- [ ] CTA buttons use accent color — stand out from the page
-- [ ] No blue-purple gradients, no rainbow palettes
-- [ ] Dark mode: rethought surfaces (not just inverted)
-- [ ] Semantic colors used consistently (success=green, error=red, warning=amber)
-
-**Layout & Spacing:**
-- [ ] Full-width fluid layouts — no hardcoded max-width caps
-- [ ] 8px spacing grid followed consistently
-- [ ] Tight spacing within groups, generous between sections
-- [ ] Fluid padding: `clamp(1rem, 5vw, 4rem)` horizontal
-- [ ] No identical card grids — varied visual hierarchy
-- [ ] No generic heroes — purposeful, distinctive
-
-**Interactive States:**
-- [ ] Every button/link: hover (color shift, 150ms), focus (visible ring), active (press feedback), disabled
-- [ ] Loading: skeleton or spinner on all async operations
-- [ ] Empty: helpful message + action on empty lists/data
-- [ ] Error: user-friendly message + recovery action on failed fetches
-- [ ] Form validation: inline errors with `aria-describedby`
-
-**Motion:**
-- [ ] Hover/focus: 150–200ms transitions
-- [ ] Page load: staggered entrance animations (50–80ms delay)
-- [ ] Expand/collapse: 250ms ease-in-out
-- [ ] `prefers-reduced-motion` respected (no animation for users who opt out)
-- [ ] No jank: transforms and opacity only for animated properties
-
-**Accessibility:**
-- [ ] Semantic HTML: `nav`, `main`, `section`, `article`, `header`, `footer`
-- [ ] One `h1` per page, sequential heading hierarchy
-- [ ] All images: descriptive `alt` (or `alt=""` + `aria-hidden` if decorative)
-- [ ] All form inputs: visible `<label>` with `htmlFor` — not placeholder-only
-- [ ] All interactive elements: keyboard accessible (Tab/Enter/Escape)
-- [ ] Touch targets: 44px minimum
-- [ ] Skip link: `<a href="#main">` as first focusable element
-- [ ] No `outline: none` without focus replacement
-- [ ] `<html lang="en">` set
-- [ ] Color not sole information carrier — icons/text as supplements
-
-**Responsive:**
-- [ ] Mobile-first approach (base styles for mobile, min-width breakpoints for larger)
-- [ ] No horizontal scroll at 320px
-- [ ] Navigation: hamburger on mobile, expanded on desktop
-- [ ] Touch targets adequate on mobile (44px min)
-- [ ] Fluid typography with `clamp()`
-- [ ] Images: `max-width: 100%`, responsive srcset where needed
-- [ ] Tables: card view or horizontal scroll on mobile
-
-**Performance:**
-- [ ] Server Components by default — `'use client'` only when needed
-- [ ] Images via `next/image` with width/height
-- [ ] No barrel file imports — direct imports from source
-- [ ] Heavy components lazy-loaded with `next/dynamic`
-- [ ] Data fetched in parallel, not sequentially
-
-### 2. Fix Everything
-
-Work through violations from the critique. Fix each category:
-
-1. Typography first (sets the visual foundation)
-2. Color & contrast (palette coherence)
-3. Layout & spacing (structural fixes)
-4. Interactive states (loading, empty, error, hover, focus)
-5. Motion (transitions, entrance animations, reduced-motion)
-6. Accessibility (semantic HTML, ARIA, keyboard, labels)
-7. Responsive (mobile breakpoints, fluid sizing)
-8. Performance (quick wins — image optimization, dynamic imports)
-
-### 3. Harden
-
-After polish, stress-test edge cases:
-- Long text content (overflow, truncation, word-break)
-- Extremely long usernames or email addresses
-- Empty data everywhere simultaneously
-- Error state on every fetch simultaneously
-- 320px viewport width
-- Keyboard-only navigation through entire flow
-- Screen reader landmarks check (semantic HTML)
-- Right-to-left text (if i18n is planned)
-- Slow network (loading states visible, no flash of empty content)
-
-### 4. Verify
+### 1. AI Slop Detector
+
+Run these checks first. Any hits = mandatory fixes.
 
 ```bash
-npx tsc --noEmit 2>&1 | head -20
+# Generic fonts (the #1 AI tell)
+grep -rn "Inter\|Roboto\|Arial\|Helvetica\|system-ui\|Space.Grotesk" --include="*.tsx" --include="*.css" --include="*.scss" --include="tailwind*" app/ components/ src/ 2>/dev/null | grep -v node_modules
+
+# Hardcoded max-width containers (screams template)
+grep -rn "max-w-7xl\|max-w-\[1200\|max-w-\[1280\|max-width.*1200\|max-width.*1280" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+
+# Blue-purple gradients
+grep -rn "from-blue.*to-purple\|from-purple.*to-blue\|linear-gradient.*blue.*purple\|linear-gradient.*purple.*blue\|from-indigo.*to-violet" --include="*.tsx" --include="*.css" app/ components/ src/ 2>/dev/null
+
+# Card grid monotony (same card component repeated in a grid)
+grep -rn "grid-cols-3\|grid-cols-4" --include="*.tsx" app/ components/ src/ 2>/dev/null | head -5
+
+# Generic hero patterns
+grep -rn "text-center.*mx-auto\|Hero\|hero" --include="*.tsx" app/ components/ src/ 2>/dev/null | head -5
+
+# Scattered hardcoded colors (no design system)
+grep -rn "text-\[#\|bg-\[#\|border-\[#\|color:.*#\|background:.*#" --include="*.tsx" app/ components/ src/ 2>/dev/null | wc -l
 ```
 
-Fix any TypeScript errors before committing.
+**Every hit gets fixed.** Not flagged — fixed.
+
+### 2. Typography Pass
+
+**Goal:** A reader should feel the type was chosen, not defaulted.
+
+- Pick a distinctive display font. Not Inter, not Roboto, not system. Something with character: Clash Display, Cabinet Grotesk, General Sans, Satoshi, Plus Jakarta Sans, Outfit, Sora, Manrope. Pair with a clean body font.
+- Establish clear hierarchy: display (hero text) → h1 → h2 → h3 → body → caption
+- Body: 16px minimum, line-height 1.5-1.7
+- Headings: tighter line-height (1.1-1.3), negative letter-spacing (-0.02em) for display sizes
+- Weight hierarchy: Regular (400) for body, Medium (500) for labels, Semibold (600) for headings, Bold (700) for display
+- Prose content: `max-width: 65ch`. Everything else: fluid full-width.
+- Use `clamp()` for fluid sizing: `clamp(2rem, 1rem + 3vw, 3.75rem)` for h1
+
+### 3. Color & Surfaces
+
+**Goal:** A palette that looks intentional, not random.
+
+- Define all colors as CSS variables or Tailwind config — zero scattered hex values
+- One dominant brand color. One sharp accent for CTAs that pops against the page.
+- Surfaces: layer them. Background → card → elevated card. Use subtle shade differences, not just white-on-white.
+- Dark mode (if present): rethink surfaces, don't just invert. Slightly reduce contrast. Use darker brand colors, not just white→black swap.
+- Semantic colors with non-color indicators: success (green + checkmark), error (red + icon), warning (amber + triangle)
+- Verify WCAG AA: 4.5:1 for normal text, 3:1 for large text (18px+ bold or 24px+)
+
+### 4. Layout & Spacing
+
+**Goal:** Full-width, fluid, generous. No dead space gutters.
+
+- Full-width layouts with fluid padding: `clamp(1rem, 5vw, 4rem)` horizontal
+- 8px spacing grid: 4, 8, 12, 16, 24, 32, 48, 64, 96
+- Tight spacing within groups (related items). Generous spacing between sections.
+- Break symmetry where it serves the design — offset grids, overlapping elements, diagonal flow
+- Varied layouts: not every section should be a centered-text-with-cards-below. Use side-by-side, staggered, asymmetric, full-bleed.
+- Section spacing: `clamp(2rem, 8vw, 6rem)` vertical padding
+
+### 5. Interactive States
 
-### 5. Commit & Transition
+**Goal:** Every clickable thing responds. Every async operation shows progress.
+
+- **Hover:** color shift or underline within 150ms ease-out. `cursor: pointer` on ALL clickables.
+- **Focus:** visible ring (2px+ offset, contrasting color). Never `outline: none` without replacement.
+- **Active/pressed:** subtle scale down (`transform: scale(0.98)`) or color shift.
+- **Disabled:** opacity 0.5 + `cursor: not-allowed` + `aria-disabled="true"`
+- **Loading:** skeleton shimmer or spinner on every async operation. Never a blank void.
+- **Empty:** helpful message + CTA on empty lists/tables. Not just "No results."
+- **Error:** user-friendly message + recovery action. Not raw error text. Use `aria-live="assertive"`.
+
+### 6. Motion & Personality
+
+**Goal:** The site feels alive, not static. But tasteful — not a circus.
+
+- Page load: stagger children entrance (50-80ms delay between items, `fadeUp` animation, 300ms)
+- Hover transitions: 150-200ms ease-out
+- Section transitions: 300-500ms with `cubic-bezier(0.4, 0, 0.2, 1)`
+- One signature motion that gives the site personality (parallax, scroll-triggered reveal, magnetic buttons, morphing shapes)
+- **Always** `prefers-reduced-motion: reduce` — disable non-essential animation
+- CSS-only for static sites, `motion/react` (formerly Framer Motion) for React
+
+### 7. Accessibility (Non-Negotiable)
+
+- Semantic HTML: `nav`, `main`, `section`, `article`, `header`, `footer` — not div soup
+- One `h1` per page, sequential heading order (no h1 → h3 skip)
+- All images: descriptive `alt` (or `alt=""` + `aria-hidden` if decorative)
+- All form inputs: visible `<label>` with `htmlFor` — not placeholder-only
+- All interactive elements: keyboard accessible (Tab, Enter, Escape, Arrow keys)
+- Touch targets: 44x44px minimum
+- Skip link: `<a href="#main" class="sr-only focus:not-sr-only">` as first focusable element
+- `<html lang="en">` set
+- Color never the sole information carrier — icons, text, patterns as supplements
+- `aria-live="polite"` for toast notifications and dynamic content updates
+
+### 8. Responsive (Mobile-First)
+
+- Base styles for mobile (320px), scale up with `min-width` breakpoints
+- Test at: 320px (small phone), 375px (iPhone), 768px (iPad), 1024px (laptop), 1440px (desktop)
+- No horizontal scroll at any viewport
+- Navigation: hamburger/drawer on mobile, full horizontal on desktop
+- Stack on mobile, expand on desktop
+- Fluid typography with `clamp()`
+- Images: `max-width: 100%`, responsive `srcset`, `next/image` with width/height
+- Tables: card layout or horizontal scroll on mobile
+
+### 9. Harden (Edge Cases)
+
+After all visual work, stress-test:
+- Long text: does a 200-character username break the layout?
+- Empty everywhere: all lists empty, all data missing — does it still make sense?
+- Error everywhere: every fetch fails — are error states visible and helpful?
+- 320px viewport: nothing overflows, nothing clips, nothing overlaps
+- Keyboard only: Tab through the entire app — can you reach everything? Is focus visible?
+- Slow network: are loading states visible? Does content stream in or flash?
+
+### 10. Verify & Ship
+
+```bash
+npx tsc --noEmit 2>&1 | head -20
+```
+
+Fix any TypeScript errors.
 
 ```bash
 git add {changed files}
-git commit -m "polish: design and UX pass — typography, accessibility, responsive, states"
+git commit -m "polish: design pass — typography, color, states, motion, responsive, a11y"
 ```
 
 ```bash
 node ~/.claude/bin/state.js transition --to polished
 ```
-Do NOT manually edit STATE.md or tracking.json — state.js handles both.
-
-### 6. Report
 
 ```bash
 node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js info "Files modified: {N}"
-node ~/.claude/bin/qualia-ui.js ok "Typography — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Color — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Layout — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "States — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Motion — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Accessibility — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Responsive — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Performance — {brief}"
-node ~/.claude/bin/qualia-ui.js ok "Hardening — {brief}"
+node ~/.claude/bin/qualia-ui.js ok "AI slop: killed"
+node ~/.claude/bin/qualia-ui.js ok "Typography: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Color: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Layout: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "States: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Motion: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Accessibility: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Responsive: {brief}"
+node ~/.claude/bin/qualia-ui.js ok "Hardened: {brief}"
 node ~/.claude/bin/qualia-ui.js end "POLISHED" "/qualia-ship"
 ```
+
+## Rules
+
+1. **Read before write.** Understand every file before changing it.
+2. **DESIGN.md is law.** If it exists, follow it. Don't override client decisions.
+3. **Don't break functionality.** Only change styling, never logic.
+4. **AI slop is a bug.** Generic fonts, card grids, blue-purple gradients, centered-everything — treat these as defects, not preferences.
+5. **TypeScript must pass** after every change.
+6. **One commit** at the end — not per category.

package/skills/qualia-report/SKILL.md

@@ -73,26 +73,35 @@ git commit -m "report: session {YYYY-MM-DD}"
 git push
 ```
 
-### 5. Upload to ERP
+### 5. Upload to ERP (if enabled)
 
-**This step is MANDATORY** — the clock-out modal requires the report to be uploaded.
+Read `~/.claude/.qualia-config.json` and check the `erp` object:
+- If `erp.enabled` is `false`, skip this step and print: "ERP upload skipped (disabled in config)."
+- If `erp.enabled` is `true` (default) or the `erp` field is missing (backward compatibility), proceed with the upload.
 
 ```bash
-ERP_URL="https://portal.qualiasolutions.net"
+# Read ERP config
+ERP_URL=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));console.log(c.erp?.url||'https://portal.qualiasolutions.net')}catch{console.log('https://portal.qualiasolutions.net')}")
+ERP_ENABLED=$(node -e "try{const c=JSON.parse(require('fs').readFileSync(require('os').homedir()+'/.claude/.qualia-config.json','utf8'));console.log(c.erp?.enabled!==false)}catch{console.log('true')}")
+
 API_KEY=$(cat ~/.claude/.erp-api-key 2>/dev/null)
 REPORT_FILE=".planning/reports/report-{date}.md"
 EMAIL=$(git config user.email)
 PROJECT=$(basename $(pwd))
 
-curl -s -X POST "$ERP_URL/api/claude/report-upload" \
-  -H "X-API-Key: $API_KEY" \
-  -F "file=@$REPORT_FILE" \
-  -F "employee_email=$EMAIL" \
-  -F "project_name=$PROJECT"
+# Only upload if ERP is enabled
+if [ "$ERP_ENABLED" = "true" ]; then
+  curl -s -X POST "$ERP_URL/api/claude/report-upload" \
+    -H "X-API-Key: $API_KEY" \
+    -F "file=@$REPORT_FILE" \
+    -F "employee_email=$EMAIL" \
+    -F "project_name=$PROJECT"
+fi
 ```
 
 If the upload succeeds, print: "Report uploaded to ERP. You can now clock out."
 If it fails (no API key, network error), print the error and tell the employee to ask Fawzi.
+If ERP is disabled, print: "ERP upload skipped (disabled in config)."
 
 ### 6. Update State