qualia-framework 2.1.0

package/framework/skills/distill/SKILL.md

@@ -0,0 +1,149 @@
+---
+name: distill
+description: Strip designs to their essence by removing unnecessary complexity. Great design is simple, powerful, and clean.
+user-invokable: true
+args:
+  - name: target
+    description: The feature or component to distill (optional)
+    required: false
+---
+
+Remove unnecessary complexity from designs, revealing the essential elements and creating clarity through ruthless simplification.
+
+## MANDATORY PREPARATION
+
+### Read DESIGN.md (Authoritative Source)
+
+Before any context gathering, check for the project's design decisions file:
+
+```bash
+cat .planning/DESIGN.md 2>/dev/null
+```
+
+**If DESIGN.md exists:** This is the authoritative source for all design decisions in this project. Use its palette, typography, spacing, component, and motion decisions as your foundation. Do NOT override these decisions unless the user explicitly asks. Reference specific DESIGN.md decisions in your output (e.g., "Per DESIGN.md, the primary color is...").
+
+**If DESIGN.md does not exist:** Proceed with normal context gathering below. Consider suggesting the user run `/qualia:discuss-phase` to establish design decisions.
+
+### Context Gathering (Do This First)
+
+You cannot do a great job without having necessary context, such as target audience (critical), desired use-cases (critical), and understanding what's truly essential vs nice-to-have for this product.
+
+Attempt to gather these from the current thread or codebase.
+
+1. If you don't find *exact* information and have to infer from existing design and functionality, you MUST STOP and STOP and call the AskUserQuestionTool to clarify. whether you got it right.
+2. Otherwise, if you can't fully infer or your level of confidence is medium or lower, you MUST STOP and call the AskUserQuestionTool to clarify. clarifying questions first to complete your context.
+
+Do NOT proceed until you have answers. Simplifying the wrong things destroys usability.
+
+### Use frontend-master skill
+
+Use the frontend-master skill for design principles and anti-patterns. Do NOT proceed until it has executed and you know all DO's and DON'Ts.
+
+---
+
+## Assess Current State
+
+Analyze what makes the design feel complex or cluttered:
+
+1. **Identify complexity sources**:
+   - **Too many elements**: Competing buttons, redundant information, visual clutter
+   - **Excessive variation**: Too many colors, fonts, sizes, styles without purpose
+   - **Information overload**: Everything visible at once, no progressive disclosure
+   - **Visual noise**: Unnecessary borders, shadows, backgrounds, decorations
+   - **Confusing hierarchy**: Unclear what matters most
+   - **Feature creep**: Too many options, actions, or paths forward
+
+2. **Find the essence**:
+   - What's the primary user goal? (There should be ONE)
+   - What's actually necessary vs nice-to-have?
+   - What can be removed, hidden, or combined?
+   - What's the 20% that delivers 80% of value?
+
+If any of these are unclear from the codebase, STOP and call the AskUserQuestionTool to clarify.
+
+**CRITICAL**: Simplicity is not about removing features - it's about removing obstacles between users and their goals. Every element should justify its existence.
+
+## Plan Simplification
+
+Create a ruthless editing strategy:
+
+- **Core purpose**: What's the ONE thing this should accomplish?
+- **Essential elements**: What's truly necessary to achieve that purpose?
+- **Progressive disclosure**: What can be hidden until needed?
+- **Consolidation opportunities**: What can be combined or integrated?
+
+**IMPORTANT**: Simplification is hard. It requires saying no to good ideas to make room for great execution. Be ruthless.
+
+## Simplify the Design
+
+Systematically remove complexity across these dimensions:
+
+### Information Architecture
+- **Reduce scope**: Remove secondary actions, optional features, redundant information
+- **Progressive disclosure**: Hide complexity behind clear entry points (accordions, modals, step-through flows)
+- **Combine related actions**: Merge similar buttons, consolidate forms, group related content
+- **Clear hierarchy**: ONE primary action, few secondary actions, everything else tertiary or hidden
+- **Remove redundancy**: If it's said elsewhere, don't repeat it here
+
+### Visual Simplification
+- **Reduce color palette**: Use 1-2 colors plus neutrals, not 5-7 colors
+- **Limit typography**: One font family, 3-4 sizes maximum, 2-3 weights
+- **Remove decorations**: Eliminate borders, shadows, backgrounds that don't serve hierarchy or function
+- **Flatten structure**: Reduce nesting, remove unnecessary containers—never nest cards inside cards
+- **Remove unnecessary cards**: Cards aren't needed for basic layout; use spacing and alignment instead
+- **Consistent spacing**: Use one spacing scale, remove arbitrary gaps
+
+### Layout Simplification
+- **Linear flow**: Replace complex grids with simple vertical flow where possible
+- **Remove sidebars**: Move secondary content inline or hide it
+- **Full-width**: Use available space generously instead of complex multi-column layouts
+- **Consistent alignment**: Pick left or center, stick with it
+- **Generous white space**: Let content breathe, don't pack everything tight
+
+### Interaction Simplification
+- **Reduce choices**: Fewer buttons, fewer options, clearer path forward (paradox of choice is real)
+- **Smart defaults**: Make common choices automatic, only ask when necessary
+- **Inline actions**: Replace modal flows with inline editing where possible
+- **Remove steps**: Can signup be one step instead of three? Can checkout be simplified?
+- **Clear CTAs**: ONE obvious next step, not five competing actions
+
+### Content Simplification
+- **Shorter copy**: Cut every sentence in half, then do it again
+- **Active voice**: "Save changes" not "Changes will be saved"
+- **Remove jargon**: Plain language always wins
+- **Scannable structure**: Short paragraphs, bullet points, clear headings
+- **Essential information only**: Remove marketing fluff, legalese, hedging
+- **Remove redundant copy**: No headers restating intros, no repeated explanations, say it once
+
+### Code Simplification
+- **Remove unused code**: Dead CSS, unused components, orphaned files
+- **Flatten component trees**: Reduce nesting depth
+- **Consolidate styles**: Merge similar styles, use utilities consistently
+- **Reduce variants**: Does that component need 12 variations, or can 3 cover 90% of cases?
+
+**NEVER**:
+- Remove necessary functionality (simplicity ≠ feature-less)
+- Sacrifice accessibility for simplicity (clear labels and ARIA still required)
+- Make things so simple they're unclear (mystery ≠ minimalism)
+- Remove information users need to make decisions
+- Eliminate hierarchy completely (some things should stand out)
+- Oversimplify complex domains (match complexity to actual task complexity)
+
+## Verify Simplification
+
+Ensure simplification improves usability:
+
+- **Faster task completion**: Can users accomplish goals more quickly?
+- **Reduced cognitive load**: Is it easier to understand what to do?
+- **Still complete**: Are all necessary features still accessible?
+- **Clearer hierarchy**: Is it obvious what matters most?
+- **Better performance**: Does simpler design load faster?
+
+## Document Removed Complexity
+
+If you removed features or options:
+- Document why they were removed
+- Consider if they need alternative access points
+- Note any user feedback to monitor
+
+Remember: You have great taste and judgment. Simplification is an act of confidence - knowing what to keep and courage to remove the rest. As Antoine de Saint-Exupéry said: "Perfection is achieved not when there is nothing more to add, but when there is nothing left to take away."

package/framework/skills/docs-lookup/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: docs-lookup
+description: Fetch up-to-date library and framework documentation on demand. Supplements Context7 MCP with zero context overhead. Activates automatically when working with external libraries.
+tags: [documentation, libraries, frameworks, reference]
+---
+
+# Docs Lookup (Supplements Context7 MCP)
+
+When you need library/framework documentation, fetch it on demand instead of loading MCP tools every session.
+
+## How to Fetch Docs
+
+Use these methods in order of preference:
+
+### 1. LLMs.txt (Best for major frameworks)
+
+Many frameworks publish LLM-optimized docs. Fetch directly:
+
+```
+WebFetch: https://supabase.com/llms/cli.txt        — Supabase CLI
+WebFetch: https://nextjs.org/llms.txt               — Next.js
+WebFetch: https://ui.shadcn.com/llms.txt            — shadcn/ui
+WebFetch: https://tailwindcss.com/llms.txt          — Tailwind CSS
+WebFetch: https://vercel.com/llms.txt               — Vercel
+WebFetch: https://docs.stripe.com/llms.txt          — Stripe
+```
+
+### 2. WebSearch (Best for specific questions)
+
+```
+WebSearch: "Next.js 16 server actions authentication 2026"
+WebSearch: "supabase realtime subscription React hook"
+WebSearch: "VAPI assistant webhook configuration"
+```
+
+### 3. Official Docs via WebFetch
+
+```
+WebFetch: https://react.dev/reference/react/use
+WebFetch: https://supabase.com/docs/guides/auth
+WebFetch: https://docs.vapi.ai/assistants
+```
+
+### 4. Package README (npm)
+
+```
+WebFetch: https://www.npmjs.com/package/[package-name]
+```
+
+## When to Activate
+
+This skill triggers when you:
+- Write code using external libraries or frameworks
+- Need to check API signatures or method parameters
+- See unfamiliar library patterns in existing code
+- Need version-specific behavior (breaking changes, new APIs)
+- Are about to suggest an API call and aren't 100% sure of the signature
+
+## IMPORTANT
+
+- DO NOT hallucinate API signatures. If unsure, look it up first.
+- Prefer llms.txt endpoints — they're concise and LLM-optimized
+- Use WebSearch for the latest (training data may be stale)
+- Fetch BEFORE writing code, not after getting errors
+
+## Fawzi's Stack Quick Reference
+
+| Tech | Docs |
+|------|------|
+| Next.js | `nextjs.org/llms.txt` |
+| React | `react.dev/reference` |
+| Supabase | `supabase.com/llms/cli.txt` |
+| Tailwind | `tailwindcss.com/llms.txt` |
+| shadcn/ui | `ui.shadcn.com/llms.txt` |
+| Vercel | `vercel.com/llms.txt` |
+| VAPI | `docs.vapi.ai` |
+| ElevenLabs | `elevenlabs.io/docs` |
+| Telnyx | `developers.telnyx.com` |

package/framework/skills/fcm-notifications/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: fcm-notifications
+description: "Firebase Cloud Messaging (FCM) push notifications — device token management, topic subscriptions, notification payloads, background handlers, in-app notification system, and notification preferences. Use whenever implementing push notifications, device registration, notification sending from backend, in-app notification feeds, or notification preferences. Triggers on: push notification, FCM, Firebase Cloud Messaging, notification, device token, notification feed, alert, in-app notification, notification preferences."
+tags: [notifications, fcm, firebase, push]
+---
+
+## Architecture
+
+```
+Mobile App                    Backend (NestJS)              Firebase
+─────────                    ────────────────              ────────
+1. Request permission
+2. Get device token    ──→   3. Store token in DB
+                             4. On event (dues, ticket)
+                             5. Build notification     ──→  6. FCM sends push
+7. Receive push
+8. Show/handle
+```
+
+## Device Token Management (Backend)
+
+- Store device tokens per user (user can have multiple devices)
+- Table: `device_token` (user_id, token, platform, created_at, last_used_at)
+- Update token on every app launch (tokens can change)
+- Clean up stale tokens (FCM returns errors for invalid tokens)
+- Delete tokens on logout
+
+## Sending Notifications (Backend - NestJS)
+
+```typescript
+@Injectable()
+export class NotificationService {
+  async send(userId: string, notification: NotificationPayload) {
+    const tokens = await this.getActiveTokens(userId);
+    if (tokens.length === 0) return;
+
+    // Store in-app notification regardless of push
+    await this.createInAppNotification(userId, notification);
+
+    // Send push via FCM
+    const message = {
+      tokens: tokens.map(t => t.token),
+      notification: {
+        title: this.i18n.resolve(notification.titleKey, userId),
+        body: this.i18n.resolve(notification.bodyKey, userId),
+      },
+      data: notification.data, // Custom payload for app handling
+    };
+
+    const response = await this.fcm.sendEachForMulticast(message);
+    await this.handleFailedTokens(response, tokens);
+  }
+}
+```
+
+## Notification Payload Structure
+
+```typescript
+interface NotificationPayload {
+  titleKey: string;        // i18n message key
+  bodyKey: string;         // i18n message key
+  type: NotificationType;  // For routing in-app
+  data: {
+    entityType: string;    // 'ticket', 'dues', 'guard_task', etc.
+    entityId: string;
+    buildingId?: string;
+    unitId?: string;
+  };
+}
+```
+
+- Use message_keys for title/body (resolved to user's locale before sending)
+- Include routing data so app can navigate to relevant screen on tap
+
+## Topic Subscriptions
+
+- Subscribe users to building-level topics: `building_{buildingId}`
+- Use for building-wide announcements
+- Subscribe on building join, unsubscribe on leave
+- Alternative to fetching all member tokens for broadcast
+
+## In-App Notification System
+
+- `notification` table: user_id, type, title_key, body_key, data, read_at, created_at
+- Separate from push — push is delivery mechanism, in-app is persistence
+- Unread count badge
+- Mark as read (individual or bulk)
+- Notification feed screen with infinite scroll
+
+## Notification Types (by domain)
+
+- DUES_GENERATED — new dues cycle obligation
+- DUES_LATE — obligation transitioned to late
+- CREDIT_TOPUP_APPROVED/REJECTED — BM reviewed top-up
+- TICKET_CREATED/UPDATED/ASSIGNED — ticket state changes
+- GUARD_TASK_REMINDER — T-15m before scheduled task
+- GUARD_TASK_ASSIGNED — new task assigned
+- GUARD_INVITE — invitation to be building guard
+- SUBSCRIPTION_EXPIRING — trial/subscription about to expire
+- DOCUMENT_APPROVED/REJECTED — document review outcome
+- CLAIM_APPROVED/REJECTED — unit claim review outcome
+
+## Mobile Integration (React Native Expo)
+
+- `expo-notifications` for handling both push and local
+- Request permission on first relevant action (not on app launch)
+- Register device token with backend after permission granted
+- Handle notification tap: navigate to relevant screen using data payload
+- Background notification handler for silent updates
+- Notification categories for actionable notifications (approve/reject)
+
+## Preferences
+
+- User can toggle notification types on/off
+- Store in user_notification_preferences table
+- Backend checks preferences before sending
+- Some notifications are mandatory (security alerts, subscription changes)
+
+## Testing
+
+- Use FCM test mode for development
+- Mock NotificationService in unit tests
+- Test token cleanup on invalid responses
+- Test preference filtering
+- Test i18n resolution for different locales