qualia-framework 3.1.0 → 3.2.0

package/rules/infrastructure.md

@@ -1,87 +0,0 @@
----
-globs: ["*.env*", "vercel.json", "next.config.*", "supabase/**", "railway.*"]
----
-
-# Infrastructure & Services
-
-Standard services across all Qualia projects. Use these unless the project explicitly specifies otherwise.
-
-## Database: Supabase (every project)
-- Every project uses Supabase for auth, database, and storage
-- **CLI:** `npx supabase` — migrations, type generation, local dev
-- **MCP:** Supabase MCP server is available in Claude Code for direct database operations
-- Always enable RLS on every table (see `rules/security.md`)
-- Use `lib/supabase/server.ts` for server-side, `lib/supabase/client.ts` for client-side
-- Run `npx supabase gen types` after schema changes
-- Migrations go in `supabase/migrations/` — never edit production directly
-
-## AI Models: OpenRouter (every project)
-- Use OpenRouter API for all LLM calls — it routes to the best-suited model per task
-- API key env var: `OPENROUTER_API_KEY`
-- Don't have a key? Ask Fawzi for one
-- Never hardcode a specific model provider (OpenAI, Anthropic, etc.) directly — always go through OpenRouter
-- Exception: if a client specifically requires a direct provider integration
-
-## Voice AI: Retell AI + ElevenLabs
-- **Retell AI** — primary voice agent platform. API key: `RETELL_API_KEY`
-- **ElevenLabs** — voice synthesis, cloning, streaming. API key: `ELEVENLABS_API_KEY`
-- **Telnyx** — telephony/SIP for voice agent phone numbers. API key: `TELNYX_API_KEY`
-- For new voice projects, default to Retell AI + ElevenLabs unless client specifies otherwise
-
-## Compute: Vercel + Railway
-- **Vercel** — primary hosting for all Next.js projects. Deploy via CLI only (see below)
-- **Railway** — secondary compute for long-running agents, background jobs, and agentic workloads that exceed Vercel's function timeout
-- **Railway CLI:** `railway` — deploy, logs, env management
-- **Railway MCP:** Railway MCP server is available in Claude Code for project management
-- Railway projects use Nixpacks (auto-detected) — check for `railway.json` or `railway.toml`
-
-## MCP Servers (available in Claude Code)
-- **Supabase MCP** — database queries, table management, migrations from within Claude Code
-- **Railway MCP** — project deployment, logs, environment variables from within Claude Code
-- **next-devtools MCP** — runtime error visibility for Next.js 16+ dev servers (optional, added by framework install)
-
-## CLIs (must be installed)
-- `npx supabase` — Supabase CLI (database, migrations, types)
-- `railway` — Railway CLI (deploy, logs, env)
-- `vercel` — Vercel CLI (deploy, env, link)
-- `gh` — GitHub CLI (PRs, issues, repos)
-
-## GitHub Organizations
-- **QualiasolutionsCY** — primary org for all Qualia Solutions projects
-- **SakaniQualia** — org for Sakani-related projects (real estate platform)
-- All repos are private by default
-- Branch protection: main/master require PR reviews (enforced by framework guards)
-
-## Vercel Teams (admin knowledge)
-- Qualia operates across **3 Vercel teams** — projects are distributed across them
-- Check which team a project belongs to before deploying: `vercel whoami` and `vercel link`
-- If a project isn't linked, link it first: `vercel link`
-
-## Deployment Rules
-- **NO auto-deploys from GitHub pushes** — all Vercel projects have GitHub integration auto-deploy DISABLED
-- Deploys happen ONLY via `vercel --prod` through the CLI (or `/qualia-ship`)
-- This is intentional — we control when things go live, not git push triggers
-- If you find a project with auto-deploy enabled, disable it: Vercel Dashboard → Project Settings → Git → Disable "Automatic Deployments"
-
-## Required Environment Variables (typical project)
-
-```bash
-# Supabase (every project)
-NEXT_PUBLIC_SUPABASE_URL=
-NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY=
-SUPABASE_SERVICE_ROLE_KEY=          # NEVER in client code
-
-# AI (if applicable)
-OPENROUTER_API_KEY=                 # ask Fawzi if you don't have one
-
-# Voice (if applicable)
-RETELL_API_KEY=
-ELEVENLABS_API_KEY=
-TELNYX_API_KEY=
-
-# Deployment
-VERCEL_ORG_ID=                      # from vercel link
-VERCEL_PROJECT_ID=                  # from vercel link
-```
-
-Always use `vercel env pull` to sync env vars locally. Never create `.env` manually from scratch.

package/skills/qualia-help/SKILL.md

@@ -1,60 +0,0 @@
----
-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-test/SKILL.md

@@ -1,134 +0,0 @@
----
-name: qualia-test
-description: "Generate or run tests for client projects. Trigger on 'write tests', 'add tests', 'test this', 'run tests', 'test coverage', 'need tests for'."
----
-
-# /qualia-test — Test Generator
-
-Generate tests for client project code. Detect framework, classify targets, write tests, run them.
-
-## Usage
-
-- `/qualia-test` — Generate tests for recently changed files
-- `/qualia-test {file}` — Generate tests for a specific file
-- `/qualia-test --run` — Run existing tests and report
-- `/qualia-test --coverage` — Run with coverage report
-
-## Process
-
-```bash
-node ~/.claude/bin/qualia-ui.js banner test
-```
-
-### 1. Detect Test Framework
-
-```bash
-node -e "
-const p=JSON.parse(require('fs').readFileSync('package.json','utf8'));
-const d={...p.dependencies,...p.devDependencies};
-console.log(JSON.stringify({
-  vitest: !!d.vitest,
-  jest: !!d.jest,
-  playwright: !!d['@playwright/test'],
-  testing_library: !!d['@testing-library/react']
-}))
-"
-```
-
-If no test framework found, install vitest (lighter than jest for Next.js/Vite):
-
-```bash
-npm install -D vitest @testing-library/react @testing-library/jest-dom jsdom
-```
-
-Add to `vitest.config.ts` if it doesn't exist:
-```typescript
-import { defineConfig } from 'vitest/config'
-import react from '@vitejs/plugin-react'
-
-export default defineConfig({
-  plugins: [react()],
-  test: {
-    environment: 'jsdom',
-    setupFiles: ['./vitest.setup.ts'],
-  },
-})
-```
-
-### 2. Find Targets
-
-If specific file given → use that.
-If `--run` → skip to step 4.
-Otherwise find recently changed untested files:
-
-```bash
-# Files changed in last 5 commits that don't have tests
-git diff --name-only HEAD~5 --diff-filter=AM -- '*.ts' '*.tsx' 2>/dev/null | grep -v "test\|spec\|__test__\|\.d\.ts" | head -10
-```
-
-### 3. Generate Tests
-
-For each target file, classify it and generate the appropriate test:
-
-**API route** (`app/api/**/route.ts`):
-- Test each exported handler (GET, POST, PUT, DELETE)
-- Test with valid input → expected response
-- Test with invalid input → 400 error
-- Test without auth → 401 (if auth is required)
-
-**Server action** (has `"use server"`):
-- Test each exported function
-- Test with valid args → expected result
-- Test with invalid args → error handling
-
-**React component** (`*.tsx` with JSX):
-- Test rendering without crashing
-- Test interactive elements (clicks, form submissions)
-- Test loading, error, and empty states if they exist
-- Test accessibility (role, aria-label presence)
-
-**Utility function** (`lib/*.ts`, `utils/*.ts`):
-- Test each exported function with normal input
-- Test edge cases: empty, null, undefined, boundary values
-- Test error cases: invalid input, missing data
-
-Write test file next to the source: `{file}.test.ts` or `{file}.test.tsx`.
-
-### 4. Run Tests
-
-```bash
-# Vitest
-npx vitest run --reporter=verbose 2>&1 | tail -30
-
-# Or Jest
-npx jest --verbose 2>&1 | tail -30
-
-# Coverage (if --coverage flag)
-npx vitest run --coverage 2>&1 | tail -30
-```
-
-### 5. Report
-
-```bash
-node ~/.claude/bin/qualia-ui.js divider
-node ~/.claude/bin/qualia-ui.js info "Files tested: {N}"
-node ~/.claude/bin/qualia-ui.js ok "Passing: {pass}/{total}"
-node ~/.claude/bin/qualia-ui.js end "TESTS DONE"
-```
-
-If any tests fail, show the failures and offer to fix them.
-
-### 6. Commit
-
-```bash
-git add {test files}
-git commit -m "test: add tests for {files}"
-```
-
-## Rules
-
-1. **Test behavior, not implementation.** Don't test internal state — test what the user/caller sees.
-2. **No snapshot tests.** They're brittle and meaningless.
-3. **No mocking unless necessary.** Test real behavior. Mock only external services (APIs, databases).
-4. **Each test file is self-contained.** No shared mutable state between tests.
-5. **Name tests as sentences.** `it("returns 401 when user is not authenticated")` not `it("test auth")`.