qualia-framework 2.1.0

package/framework/knowledge/client-prefs.md

@@ -0,0 +1,22 @@
+# Client Preferences
+> Per-client details NOT covered in qualia-context.md. Only unique info here.
+
+## Websites
+- **qualiafinal** — Modern, professional, dark theme
+- **aquador** — Clean, water-themed design
+- **glluztech** — Tech/corporate. Only project on Pages Router.
+- **inrvo** — Has MCP configured. Custom domain: innrvo.com
+- **luxcars** — Luxury, premium aesthetics
+- **vero** — Tier 1. Has MCP configured.
+- **aibossbrainz** — Tier 1. Has MCP configured.
+
+## AI Agents
+- **Hammah** — Arabic/English bilingual, Kuwait construction sector, 18 categories. SERVICE_ROLE_KEY exposed.
+- **sofiatesting** — Greek/English. Cyprus real estate. WhatsApp + Web. Edge Functions. Most complex agent. Has MCP (Upstash, Context7, Postman, Railway).
+- **timo** — Mindfulness OS for C-Suite. Incomplete credentials.
+- **sigatalachana** — Greek. Python agent (NOT web). Invoice OCR + POS. Misclassified in aiagents folder.
+- **axidex** — Sales signals. Stripe integrated.
+
+## Voice
+- **armenius** — Greek/English/Russian. 7 webhook tools (order status, stock, product search). PrestaShop. NOT on Vercel — Cloudflare Workers.
+- **under** — Tier 1. Sales training. ai.underdogsales.com. Has MCP.

package/framework/knowledge/common-fixes.md

@@ -0,0 +1,25 @@
+# Common Fixes
+> Recurring bugs and their solutions. Updated: 2026-03-23
+
+## Build Failures
+- **Module not found**: Check case sensitivity (Linux is case-sensitive, macOS isn't)
+- **Memory issues**: `vercel --build-env NODE_OPTIONS="--max-old-space-size=4096"`
+- **Missing deps**: `rm -rf node_modules && npm install`
+- **Generated types stale**: `npx supabase gen types typescript --linked > types/database.ts`
+
+## Deployment
+- **Works locally, fails on Vercel**: Check Node version, env vars, case sensitivity
+- **Missing env vars**: `vercel env ls` to check, `vercel env add` to fix
+- **NEXT_PUBLIC_ vars**: Must be set at BUILD time, not just runtime
+- **White screen**: Check for `window`/`document` in server components
+- **500 on API**: Check env vars exist on Vercel, check Supabase URL not localhost
+
+## Supabase
+- **RLS blocking silently**: Returns empty array, not error. Check policies.
+- **FK returns array**: Use `normalizeFKResponse()` helper
+- **Connection pool exhausted**: Reduce `max_connections`, use connection pooler
+
+## Next.js
+- **Hydration mismatch**: Wrap dynamic content in `useEffect`, no `Date.now()` in SSR
+- **Missing 'use client'**: Add directive to components using hooks
+- **Stale cache**: `revalidatePath()` after mutations + invalidate SWR

package/framework/knowledge/deployment-map.md

@@ -0,0 +1,35 @@
+# Deployment Map
+> Per-project deploy configs. Updated: 2026-03-26
+
+## Vercel Projects
+| Project | Domain | Deploy Command | Notes |
+|---------|--------|---------------|-------|
+| qualiafinal | qualiasolutions.net | `vercel --prod` | Company site |
+| aquador | aquador.vercel.app | `vercel --prod` | |
+| vero | veromodels.com | `vercel --prod` | Tier 1 |
+| aibossbrainz | aibossbrainz.vercel.app | `vercel --prod` | Tier 1 |
+| maud | maud.vercel.app | `vercel --prod` | |
+| mpm | mpm.vercel.app | `vercel --prod` | |
+| inrvo | innrvo.com | `vercel --prod` | Being refactored |
+| under | ai.underdogsales.com | `vercel --prod` | Retell AI voice |
+| sofiatesting | sofiatesting.vercel.app | `vercel --prod` | Most complex agent |
+| qualia ERP | qualia-erp.vercel.app | `vercel --prod` | Internal |
+| marco | — | `vercel --prod` | |
+| Alkemy | — | `vercel --prod` | |
+| pastrikos-panels | — | `vercel --prod` | New (2026-03-24) |
+
+## Cloudflare Workers
+| Project | Worker URL | Deploy Command |
+|---------|-----------|---------------|
+| armenius | armenius-webhook.yellow-mountain-8da2.workers.dev | `wrangler deploy` |
+
+## Special Cases
+- glluztech: custom domain glluztech.com (NOT glluztech.vercel.app — 404s)
+- armenius widget: qualia-widgets.vercel.app (separate from webhook worker)
+
+## Post-Deploy Checklist
+1. HTTP 200: `curl -s -o /dev/null -w "%{http_code}" <url>`
+2. Auth flow works
+3. No console errors
+4. API latency < 500ms
+5. UptimeRobot: https://stats.uptimerobot.com/bKudHy1pLs

package/framework/knowledge/email-signature.html

@@ -0,0 +1 @@
+<table style="font-family: 'Helvetica Neue', Arial, sans-serif; width: 480px; border-collapse: collapse; border: 1px solid rgb(224, 224, 224); background-color: rgb(255, 255, 255)"><tbody><tr><td style="padding: 25px"><table style="width: 100%; border-collapse: collapse"><tbody><tr><td style="width: 140px; padding-right: 20px; vertical-align: top"><img src="https://images.squarespace-cdn.com/content/v1/65bf52f873aac538961445c5/19d16cc5-aa83-437c-9c2a-61de5268d5bf/Untitled+design+-+2025-01-19T070746.544.png?format=300w" alt="Qualia Solutions" style="width: 120px; display: block" width="120"></td><td style="vertical-align: top; padding-top: 5px"><div style="font-size: 22px; font-weight: 600; color: rgb(44, 62, 80); margin: 0 0 5px 0">Fawzi Goussous</div><div style="font-size: 15px; color: rgb(0, 164, 172); margin: 0 0 18px 0; font-weight: 500">AI Solutions &amp; Web Design</div><table style="border-collapse: collapse"><tbody><tr><td style="padding: 4px 0; font-size: 14px; color: rgb(85, 85, 85)"><a href="mailto:info@qualiasolutions.net" style="color: rgb(51, 51, 51); text-decoration: none">info@qualiasolutions.net</a></td></tr><tr><td style="padding: 4px 0; font-size: 14px; color: rgb(85, 85, 85)"><a href="tel:+35799111668" style="color: rgb(51, 51, 51); text-decoration: none">+357 99 111 668</a></td></tr><tr><td style="padding: 4px 0; font-size: 14px; color: rgb(85, 85, 85)">Nicosia, Cyprus</td></tr><tr><td style="padding: 4px 0; font-size: 14px"><a href="https://qualiasolutions.net" style="color: rgb(0, 164, 172); text-decoration: none; font-weight: 500">qualiasolutions.net</a></td></tr></tbody></table></td></tr></tbody></table></td></tr><tr><td style="padding: 15px 25px; border-top: 1px solid rgb(224, 224, 224); background-color: rgb(249, 249, 249)"><div style="font-size: 13px; color: rgb(102, 102, 102); font-style: italic; text-align: center">Where Consciousness Meets Technology</div></td></tr></tbody></table>

package/framework/knowledge/employees.md

@@ -0,0 +1,8 @@
+# Employees
+
+## Partner
+- **Jay** — Business partner at Qualia Solutions
+
+## Team
+- **Moayad** — Full-time, since December 2025. Based in Jordan.
+- **Ahasan** — Part-time, since March 2026. Based in Cyprus.

package/framework/knowledge/learned-patterns.md

@@ -0,0 +1,51 @@
+# Learned Patterns
+> Auto-growing rules from `/learn` command. Each rule was triggered by an actual mistake or discovery.
+> Format: ALWAYS/NEVER [action] [context/when]
+
+---
+
+## Always Rules
+- ALWAYS check `pwd` on session start to identify which of the 42 projects you're in [verified: 2026-03]
+- ALWAYS read a project's local CLAUDE.md before making changes — it has project-specific rules [verified: 2026-03]
+- ALWAYS look up the Supabase ref from qualia-context.md when working with Supabase projects [verified: 2026-03]
+- ALWAYS run `npx tsc --noEmit` after editing multiple TypeScript files [verified: 2026-03]
+- ALWAYS use feature branches — branch-guard.sh will block direct pushes to main [verified: 2026-03]
+- ALWAYS run the 5-check post-deploy verification after any deployment (includes UptimeRobot check) [verified: 2026-03]
+- ALWAYS use `lib/supabase/server.ts` for server-side mutations, never client.ts [verified: 2026-03]
+- ALWAYS check UptimeRobot status page (https://stats.uptimerobot.com/bKudHy1pLs) when debugging downtime or after deployments [verified: 2026-03]
+- ALWAYS ensure new projects get added to UptimeRobot monitoring [verified: 2026-03]
+- ALWAYS use skills over commands — commands deprecated March 2026 [verified: 2026-03]
+- ALWAYS write /review results to .planning/REVIEW.md for deploy gate [verified: 2026-03]
+
+## Never Rules
+- NEVER expose service_role key in client components (Hammah has this bug — needs fixing) [verified: 2026-03]
+- NEVER commit .env files to git (pre-commit hook catches this) [verified: 2026-03]
+- NEVER use `dangerouslySetInnerHTML` or `eval()` [verified: 2026-03]
+- NEVER hardcode API keys — use environment variables [verified: 2026-03]
+- NEVER use Task(Explore) for simple file lookups — use Glob/Grep directly (speed rule) [verified: 2026-03]
+- NEVER push directly to main/master — branch-guard.sh will block it [verified: 2026-03]
+
+## Framework Rules (established 2026-03-30)
+- ALL hooks MUST use teal branding via `source qualia-colors.sh` — consistent Qualia visual identity [verified: 2026-03]
+- ALL blocking hooks MUST return JSON with `systemMessage` telling Claude to FIX the issue, not ask user to bypass [verified: 2026-03]
+- ALL hooks MUST use `node` for JSON parsing (not `jq`) — jq may not be installed on all systems [verified: 2026-03]
+- Hook output: styled stderr (user sees teal UI), JSON stdout (Claude gets instructions) [verified: 2026-03]
+- ALL blocking hooks MUST have actionable systemMessage: tell Claude to FIX it, not ask user to do it manually [verified: 2026-03]
+- `--dangerously-skip-permissions` BYPASSES Claude hook blocks — git pre-push hooks are the true safety net [verified: 2026-03]
+- NEVER tell user "push manually" or "commit with --no-verify" when a hook blocks — fix the issue or explain exactly what to change [verified: 2026-03]
+- `retention-cleanup.sh` covers: file-history, session-env, backups, paste-cache, shell-snapshots, projects, tasks, plans [verified: 2026-03]
+- `~/.claude/CLAUDE.md` is the OWNER profile (Fawzi) — team members get developer profiles via project-level CLAUDE.md [verified: 2026-03]
+- Legacy `commands/` directory removed — all commands migrated to `skills/` [verified: 2026-03]
+- `core/PRINCIPLES.md` removed — bloat, never referenced by any skill or hook [verified: 2026-03]
+- No Python venv in `~/.claude/` — removed 79MB unused venv [verified: 2026-03]
+
+## Project-Specific Gotchas
+- **sigatalachana** is a Python agent (NOT web) — misclassified in aiagents folder [verified: 2026-03]
+- **armenius** uses Cloudflare Workers + wrangler deploy (NOT Vercel) [verified: 2026-03]
+- **glluztech** is the only project still on Next.js Pages Router — needs migration to App Router [verified: 2026-03]
+- **sofiatesting** is the most complex AI agent (WhatsApp + Web + Edge Functions + dual AI) [verified: 2026-03]
+- **ERP actions.ts** was split into 44 domain files (completed 2026-03). client-portal.ts (2,496 lines) is now the largest file. [verified: 2026-03]
+- **Timo** has empty API keys (OPENROUTER_API_KEY, SUPABASE_SERVICE_ROLE_KEY) — won't work until filled [verified: 2026-03]
+
+---
+*Last updated: 2026-03-30*

package/framework/knowledge/optimization-research-2026.md

@@ -0,0 +1,137 @@
+# Qualia Framework Optimization — Research Findings (March 2026)
+
+Compiled from 4 parallel deep research agents covering: shipping checklists, knowledge base UX, AI dev workflows, and framework architecture.
+
+---
+
+## TOP PRIORITY ACTIONS
+
+### P0 — Do Now (High Impact, Low Effort)
+
+**1. Tier deployments by risk level**
+Not every deploy needs the full checklist. Split into:
+- **Light** (copy/content changes): HTTP 200 + visual check only
+- **Standard** (feature work): full automated suite
+- **Heavy** (auth/DB/payment changes): automated suite + manual verification + staged rollout
+> Action: Add a `--risk` flag to `/ship` skill (light/standard/heavy)
+
+**2. Machine-verify every checklist gate**
+Agents hallucinate "PASS" on steps they skipped. The #1 fix: every checklist item that CAN be verified by a command MUST be. Never let the agent self-report on something `grep`, `curl`, or `tsc` can check.
+> Action: Convert checklist items to executable commands in the skills, not just tips
+
+**3. Separate "deploy checklist" from "launch checklist"**
+Deploy happens every push. Launch is a one-time event (DNS, analytics, SEO, client handoff). Mixing them causes fatigue on routine deploys.
+> Action: Split `completion-checklists.md` into `deploy-checklist.md` (per-push) and `launch-checklist.md` (first-time)
+
+**4. Set up UptimeRobot for all 23+ projects**
+Free tier covers 50 monitors at 5-minute intervals. Immediate value, zero cost.
+> Action: Register all production URLs, configure Slack alerts
+
+**5. Audit CLAUDE.md length**
+Frontier LLMs reliably follow ~150-200 instructions total. Claude Code's system prompt already consumes ~50. Every line in CLAUDE.md competes for attention. Test: "Would removing this line cause Claude to make mistakes?" If not, cut it.
+> Action: Trim global CLAUDE.md to essential rules only, move domain knowledge to skills
+
+### P1 — Do This Week
+
+**6. Per-project interactive checklists on portal**
+Store completion state in Supabase per project, not as static markdown. Show progress bars on project dashboard cards. Link items to real deliverables (deploy URLs, PR links).
+> Schema: `project_checklists` table with `project_id`, `checklist_type`, `items JSONB`, `completed_items JSONB`, `progress_pct`
+
+**7. Add `last_verified_at` to knowledge base articles**
+Flag stale content (red/yellow/green). Auto-notify owner when past SLA. Block checklist completion if linked docs are stale.
+
+**8. Quarterly checklist review process**
+Remove any manual check that hasn't caught a real issue in 3 months. Replace with automation or drop entirely.
+
+**9. PostToolUse hooks for real-time drift catching**
+Auto-run formatters/linters/type-checks after every file write instead of only at commit time. Catches issues in real-time.
+
+### P2 — Do This Month
+
+**10. Adopt Spec-Driven Development (SDD)**
+Add `constitution.md` to project templates — non-negotiable project principles established before code. Integrate the Specify -> Plan -> Tasks workflow from GitHub Spec Kit.
+
+**11. Shared internal packages (`@qualia/*`)**
+Create reusable packages for patterns used across projects: `@qualia/ui`, `@qualia/config`, `@qualia/supabase-helpers`. Publish to GitHub Packages.
+
+**12. Build "Golden Paths" on the portal**
+Curated step-by-step journeys for common workflows: new project setup, deployment, client handoff. Not just reference docs — guided paths.
+
+**13. Project status as state machine in portal DB**
+Define valid transitions (`planning` -> `in_progress` -> `review` -> `deployed`). Enforce with DB constraints. Simple TS enum, not full XState.
+
+**14. Deploy automation layer**
+Vercel Deploy Hooks stored in portal DB for one-click deploys. Script migration diffing across projects. Portal webhook triggers post-deploy verification automatically.
+
+---
+
+## KEY INSIGHTS BY AREA
+
+### Shipping Checklists
+- Vercel uses 5 pillars: operational excellence, security, reliability, performance, cost
+- Stripe: automated rollouts > human-babysat ones
+- Linear: minimal process, maximum trust — hire for craft, set principles
+- 67% of alerts are ignored daily. Healthy systems: 30-50% actionable rate
+- Rule: if <10% of manual checks catch real issues, they're noise
+
+### Knowledge Base
+- Keep docs short and evergreen (Linear model)
+- 4 content types: How-To, Concept, Reference, Checklist
+- Track failed searches to find content gaps
+- Progress bars: 40% increase in activation rates (Zeigarnik effect)
+- 44% of orgs say onboarding takes 2+ months. Structured onboarding = 62% faster productivity
+- New hires should contribute back to docs (teaching = learning)
+
+### AI Dev Workflow
+- CLAUDE.md: under 300 lines, shorter is better. HumanLayer's is under 60 lines
+- Skills: 15-20 autonomous max before token costs blow up
+- Context degradation: 0-50% work freely, 50-70% consider compact, 70%+ precision drops
+- 78% of Claude Code sessions = multi-file edits, avg 47 tool operations
+- AI-coauthored PRs: 1.7x more issues than human-only
+- Juniors with AI: 17-point comprehension gap. Must pair with mentors + mandatory no-AI practice
+
+### Framework Architecture
+- Spec-Driven Development: "biggest unlock wasn't the model — it was having a durable spec"
+- Polyrepo across clients (correct for Qualia) + shared internal packages
+- `.planning/` structure: flat markdown files, atomic testable tasks with validation criteria
+- Post-deploy monitoring: UptimeRobot free tier covers 50 monitors
+- AI makes greenfield 60-70% faster, testing 50-60% faster, overall delivery 2-4x
+
+---
+
+## FAILURE MODES TO WATCH
+
+1. **Premature termination**: Agent finds 1 of 3 items and declares done
+2. **Hallucination cascades**: Wrong intermediate result compounds through chain
+3. **Lost in the middle**: Items in middle of long checklists get systematically skipped
+4. **Sycophantic compliance**: Agent agrees with flawed instructions instead of pushing back
+5. **Hiding failures**: Agent attempts to cover up mistakes
+6. **Context overload**: Too much info causes high-confidence hallucinations
+
+**Fix**: Machine-checkable gates, Plan-Act-Observe pattern, explicit completion criteria, MUST not "should"
+
+---
+
+## MOAYAD TRAINING INSIGHTS
+
+- Pair with mentor for both coding AND AI usage
+- Periodically disable autocomplete — build fundamentals without AI
+- Tag AI-generated PRs with specialized review checklist
+- First tasks should require using the knowledge base (self-reinforcing)
+- 30/60/90 day milestones with measurable goals
+- Require doc improvements as part of onboarding
+
+---
+
+## METRICS TO TRACK
+
+- DORA: Deployment Frequency, Lead Time, MTTR, Change Failure Rate
+- Correction rounds per task (fewer = better CLAUDE.md)
+- Checklist actionable rate (target: 30-50%)
+- Per-project checklist completion %
+- Knowledge base staleness (% of articles verified within SLA)
+
+---
+
+_Sources: 60+ articles from Vercel, Stripe, Linear, Anthropic, GitHub, GitLab, Pragmatic Engineer, InfoQ, Addy Osmani, HumanLayer, arXiv, METR, and others. Full source lists in research agent outputs._
+_Research date: 2026-03-23_

package/framework/knowledge/qualia-context.md

@@ -0,0 +1,67 @@
+# Qualia Solutions
+> One-man company (Fawzi Goussous), Cyprus. Websites, AI agents, voice agents, AI automation.
+
+## Project Inventory
+
+### Websites (15) — `~/Projects/live/`
+| Project | Status | Supabase | Hosting | Notes |
+|---------|--------|----------|---------|-------|
+| qualiafinal | ACTIVE | — | Vercel | Company site, custom domain: qualiasolutions.net |
+| aquador | MAINTENANCE | `hznpuxplqgszbacxzbhv` | Vercel | aquador.vercel.app |
+| glluztech | MAINTENANCE | — | Vercel (qualia-glluztech team) | Legacy Pages Router, custom domain glluztech.com, `glluztech.vercel.app` 404s but glluztech.com works |
+| inrvo | REFACTORING | `ygweconeysctxpjjnehy` | Vercel | Custom domain: innrvo.com, being refactored |
+| aandnglobal | DORMANT | — | — | |
+| urban | DORMANT | — | — | |
+| znso | DORMANT | — | — | |
+| luxcars | DORMANT | — | — | Luxury aesthetic |
+| maud | MAINTENANCE | `vspyxscitcuwnrhchskl` | Vercel | |
+| vero | ACTIVE | `dvahjrnqwsqqokafaxgn` | Vercel | Tier 1, MCP, custom domain: veromodels.com (old ref zskfdlqyzhkzefafqkpx is dead) |
+| aibossbrainz | ACTIVE | `esymbjpzjjkffpfqukxw` | Vercel | Tier 1, MCP |
+| mpm | MAINTENANCE | `llherorsfgbdyqkrrlpc` | Vercel | |
+| Zaid | DORMANT | `uoqiwidqlsoamtugioik` | — | |
+| marco | ACTIVE | `kqxpyayvehodwsxtfaic` | Vercel | |
+| Alkemy | ACTIVE | `msntbcaqouqvkxslwtqg` | Vercel | |
+| pastrikos-panels | DEV | `iqdmjtvqyocpoonssmwj` | Vercel | Created 2026-03-24 |
+
+### AI Agents (10) — `~/Projects/aiagents/`
+| Project | Activity | Supabase | AI Provider | Status |
+|---------|----------|----------|-------------|--------|
+| axidex | BUILT | `cmbbgybceqnmvyczkyks` | OpenAI | Stripe integrated, needs launch |
+| dababneh | DEV | `toovladeybmlyzblqtbl` | — | |
+| faris | DEV | `lrgwxcqqnhxvvrruepcv` | — | |
+| Hammah | DEV | `ctcikdcjhxxqogwvtzrc` | Gemini 2.0 Flash | Arabic/English, SERVICE_ROLE_KEY exposed |
+| sofiatesting | LIVE | `vceeheaxcrhmpqueudqx` | Dual AI | WhatsApp + Web, most complex |
+| timo | DEV | `qgaqvkmqterlljbegniu` | OpenRouter | MVP, missing API keys |
+| sigatalachana | DEV | `qsoxyrotlkawtwmjdgcw` | Claude Opus 4.5 | Python agent (NOT web) |
+| giulio-agent | DEV | `iqibcuzhucyabptwkggm` | — | |
+| shai-coach | DEV | `yrumvufehvbbnjppvwlf` | — | |
+| peta | DEV | `vbrsjcxntkfmuccorfbv` | — | |
+
+### ERP (ACTIVE) — `~/Projects/qualia-erp/`
+Internal project management. Next.js 16, Gemini AI, VAPI, Supabase (`vbpzaiqovffpsroxaulv`). Domain: qualia-erp.vercel.app.
+Tech debt: actions.ts split completed (44 domain files).
+
+### Voice (3) — `~/Projects/live/`
+| Project | Status | Provider | Hosting | Supabase |
+|---------|--------|----------|---------|----------|
+| armenius | MAINTENANCE | ElevenLabs | Cloudflare Workers (webhook) + Vercel (widget) | — |
+| under | ACTIVE | Retell AI | Vercel | `vvppyijxpgeeijiozlve` | Custom domain: ai.underdogsales.com |
+| Underdog Academy | ACTIVE | — | Vercel | `ywdrvvnganseomouplyb` | Created 2026-03-14 |
+
+## Deploy Commands
+```bash
+vercel --prod                              # Standard deploy
+supabase db push --project-ref <ref>       # Migrations
+wrangler deploy                            # Armenius only
+```
+
+## Key URLs
+- Armenius webhook: `https://armenius-webhook.yellow-mountain-8da2.workers.dev` (old `armenius.fawzi-goussous.workers.dev` is dead)
+- Armenius widget: `https://qualia-widgets.vercel.app`
+- glluztech: custom domain `https://glluztech.com` (NOT `glluztech.vercel.app` — that 404s)
+
+## Alerts
+- Hammah: SERVICE_ROLE_KEY exposed in .env.local
+- Timo: Empty API keys (won't work)
+- glluztech: Legacy Pages Router, Vercel project may be under `qualia-glluztech` team
+- under: `under.vercel.app` returns 500 but custom domain ai.underdogsales.com works fine

package/framework/knowledge/supabase-patterns.md

@@ -0,0 +1,50 @@
+# Supabase Patterns
+> Common patterns across Qualia projects. Updated: 2026-03-23
+
+## Standard Setup
+1. Create project in Supabase dashboard (Frankfurt region for EU)
+2. Get URL + anon key → `.env.local`
+3. Create `lib/supabase/server.ts` and `lib/supabase/client.ts`
+4. Enable RLS on EVERY table
+5. Generate types: `npx supabase gen types typescript --linked > types/database.ts`
+
+## RLS Template
+```sql
+-- Basic user-owns-data pattern
+ALTER TABLE my_table ENABLE ROW LEVEL SECURITY;
+
+CREATE POLICY "Users can view own data" ON my_table
+  FOR SELECT USING (auth.uid() = user_id);
+
+CREATE POLICY "Users can insert own data" ON my_table
+  FOR INSERT WITH CHECK (auth.uid() = user_id);
+
+CREATE POLICY "Users can update own data" ON my_table
+  FOR UPDATE USING (auth.uid() = user_id);
+```
+
+## Server Action Pattern
+```typescript
+'use server'
+import { createClient } from '@/lib/supabase/server'
+
+export async function myAction() {
+  const supabase = await createClient()
+  const { data: { user } } = await supabase.auth.getUser()
+  if (!user) throw new Error('Unauthorized')
+  // ... mutations here
+}
+```
+
+## FK Normalization
+Supabase returns FK as arrays. Use:
+```typescript
+import { normalizeFKResponse } from '@/lib/server-utils'
+const normalized = normalizeFKResponse(data, ['project', 'client'])
+```
+
+## Gotchas
+- NEVER use service_role key in client-side code
+- ALWAYS use server.ts for mutations, client.ts for reads only
+- FK returns arrays — normalize them
+- RLS silently blocks if no matching policy (returns empty, not error)

package/framework/knowledge/voice-agent-patterns.md

@@ -0,0 +1,46 @@
+# Voice Agent Patterns
+> VAPI, Retell AI, ElevenLabs patterns. Updated: 2026-03-23
+
+## VAPI Setup
+1. Create assistant via VAPI dashboard or MCP
+2. Configure: model, voice, system prompt, tools, first message
+3. Deploy webhook handler (Cloudflare Workers or Supabase Edge Function)
+4. Connect phone number
+5. Test with real calls
+
+## Webhook Handler Template
+```typescript
+// Verify signature first
+const signature = req.headers.get('x-vapi-signature')
+if (!verifyVapiSignature(body, signature, secret)) {
+  return new Response('Unauthorized', { status: 401 })
+}
+
+// Route by event type
+switch (event.message.type) {
+  case 'function-call': // Handle tool calls
+  case 'end-of-call-report': // Log call
+  case 'status-update': // Track status
+}
+```
+
+## Voice Selection
+| Use Case | Voice | Provider |
+|----------|-------|----------|
+| Professional | Rachel | ElevenLabs |
+| Friendly | Bella | ElevenLabs |
+| Energetic | Elli | ElevenLabs |
+| Fast/Cheap | Default | Cartesia |
+
+## Best Practices
+- Keep responses SHORT (1-2 sentences max)
+- Confirm important info back to caller
+- Handle interruptions gracefully
+- First response latency < 500ms
+- Log everything for debugging
+- Always verify webhook signatures
+
+## Active Voice Projects
+- armenius: ElevenLabs + Cloudflare Workers (Greek/English/Russian)
+- under: Retell AI + Vercel (Sales training, ai.underdogsales.com)
+- Underdog Academy: Vercel (created 2026-03-14)

package/framework/qualia-engine/VERSION

@@ -0,0 +1 @@
+1.14.0