# LESSONS.md - RateRight Growth Engine > Hard-won knowledge from 30 years construction + 4 months coding. Read before every session. Last Updated: Jan 31, 2026 (BUG #27 - Voice Assistant manual stop fix) --- ## 🤖 VPS Claude Code Setup ### Claude Code CLI as Root = Blocked - **`--dangerously-skip-permissions` won't run as root** - Security feature in Claude Code - **Solution:** Create non-root user `ccuser` for CC to run as - **Setup:** `useradd -m ccuser`, copy claude binary + credentials, run via `su - ccuser -c "claude ..."` ### Clawdbot Config Format is Strict - **Don't invent keys** - `"use_for"`, `"routing"` are not recognized - **Model format:** `"models": {"anthropic/model-name": {"alias": "name"}}` - **Always backup before changing:** `cp clawdbot.json clawdbot.json.bak` - **Restart required:** `systemctl restart clawdbot` after config changes ### Model IDs Change - **`claude-3-5-sonnet-20241022` → 404 error** - Model was deprecated - **Use latest:** `claude-sonnet-4-20250514` or check Anthropic docs - **Clawdbot needs `anthropic/` prefix:** `"anthropic/claude-sonnet-4-20250514"` ### CC + Clawdbot Architecture ``` Clawdbot (API, 24/7) Claude Code (Max plan, on-demand) │ │ │ Operations │ Code work │ - Briefs │ - Git commits │ - Monitoring │ - Bug fixes │ - Notion sync │ - Deploys │ │ └─── trigger-cc.sh ─────────┘ (delegates code tasks) ``` ### VPS Non-Root User for CC - **User:** `ccuser` at `/home/ccuser` - **Claude binary:** `/home/ccuser/.local/bin/claude` - **Credentials:** `/home/ccuser/.claude/` - **Repo:** `/home/ccuser/rateright-growth` - **Config:** `/home/ccuser/config.env` (Notion keys, etc.) ### Frontend Supabase Auth - Build-Time Env Vars - **VITE_SUPABASE_URL** and **VITE_SUPABASE_ANON_KEY** must be in `admin/.env` at BUILD time - These get baked into the JS bundle - not read at runtime - **Railway deployment:** Add VITE_* variables to Railway dashboard env vars (see docs/RAILWAY-ENV-SETUP.md) - **Railway runs `npm run build` automatically** - Nixpacks detects build script and runs it with Railway env vars - **Not just backend vars:** Railway needs BOTH `SUPABASE_URL` (backend runtime) AND `VITE_SUPABASE_URL` (frontend build) - **Verify fix:** `grep "supabase.co" public/assets/index*.js` should find the URL - **Don't mark Done until tested** - wait for Railway deploy, then test login ### Railway Nixpacks Auto-Rebuilds Frontend (P0 Jan 31) - **Railway's Nixpacks builder auto-runs `npm run build`** if build script exists in package.json - Our build script: `cd admin && npm install && npm run build && cp -r dist/* ../public/` - **Problem:** Railway doesn't have VITE_* env vars, so rebuilt frontend has NO Supabase credentials - **Symptom:** Auth works locally, breaks in production (different JS file hashes in public/) - **Fix:** Set explicit `buildCommand` in `railway.json` to skip frontend rebuild: ```json "build": { "builder": "NIXPACKS", "buildCommand": "npm install" } ``` - **Pattern:** Pre-build frontend locally with correct `.env`, commit to `public/`, let Railway just install deps ### Verify Frontend Build Has Credentials (Jan 31) - **Don't assume old builds are valid** - Just because `public/` has files doesn't mean they have credentials - **Check BOTH URL and anon key:** ```bash # Check URL grep "memscjotxrzqnhrvnnkc.supabase.co" public/assets/index-*.js # Check anon key (first part of JWT) grep "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9" public/assets/index-*.js ``` - **If either is missing:** Rebuild frontend: `cd admin && npm run build`, then copy `dist/*` to `public/` - **Stale builds accumulate** - Multiple `index-*.js` files in `public/assets/` means old builds weren't cleaned up - **Clean before copy:** `rm -rf public/assets public/index.html` before copying new build - **File hash changes = new build** - If `index-BmHVaqEO.js` becomes `index-M3mvPwS8.js`, credentials may differ ### VPS Memory Management - **4GB RAM + 2GB swap** is minimum for CC + MCP servers - If CC freezes: check `free -h` - likely out of memory - Added swap: `fallocate -l 2G /swapfile && mkswap && swapon` (persistent via /etc/fstab) - Consider upgrading to 8GB RAM when budget allows --- ## 🔧 /fix Workflow When user says `/fix`: 1. **Read** `.claude/context.md` + `docs/LESSONS.md` 2. **Read Slack** #growth-alerts for bug reports 3. **Investigate** - trace the bug, find root cause 4. **Plan** - identify the fix (0.1% solution) 5. **Fix** - implement the fix 6. **Test** - verify it works 7. **Deploy** - commit, push, update docs (LESSONS.md, SYSTEM-INTEL.md) **No questions. No explanations. Just fix.** --- ## 🚨 CRITICAL (Read First) ### Self-Improvement Protocol - **AUTOMATIC: "Is there a lesson here?"** - After EVERY fix, discovery, or workaround, immediately ask yourself: "Is there a lesson here?" Don't wait for the user to prompt you. If you had to figure something out, future sessions need to know it. - **Documenting isn't enough** - When you discover a gotcha, ask: "What config/code/data needs to change so this CAN'T happen again?" Don't just add to LESSONS.md - update the actual system. Example: Wrong Notion IDs → don't just document the right ones → add them to CLAUDE.md where they'll be used. - **Three-layer capture** - Every lesson should be: (1) Fixed in the system, (2) Documented in LESSONS.md, (3) Logged to Notion for pattern analysis. If you only do one, the lesson is incomplete. - **Agents must share knowledge** - If CC learns something, Clawdbot needs to see it too (and vice versa). The VPS syncs the git repo every 30 min. Both read from `docs/LESSONS.md` + Notion. Don't create separate knowledge silos. ### Context Management - **Small batches only** - 4-5 fixes max per prompt. 8+ fixes = context loss risk - **Plan files save you** - Always save state to plan file before context compacts - **Push after each step** - Commit after each completed step, not at the end - **Never trust "I'll remember"** - Write it down or lose it ### Tailwind Compilation - **NEVER use dynamic classes** - `bg-${color}-500` won't compile in production - **Use static classes with conditionals** - `score > 70 ? 'bg-green-500' : 'bg-gray-500'` - **Test production build** - `npm run build` catches what dev mode misses ### Import Paths - **Service files use `../config/database`** - Always `const { supabase } = require('../config/database')` in `src/services/` files - **Never `require('./supabase')`** - This file doesn't exist; causes server startup crash - **Route files also use `../config/database`** - Same pattern in `src/routes/` - **Test startup after adding new files** - `node --check src/index.js` catches missing modules ### Database Safety - **Always `IF NOT EXISTS`** - Every ALTER TABLE, every CREATE, every time - **Update PENDING_MIGRATIONS.md immediately** - Mark ⬜ pending, user marks ✅ after running - **Error handling on every DB op** - Supabase fails silently otherwise - **Never hard delete leads** - Soft delete with `deleted_at` column - **Check errors on insert/update** - `const { error } = await supabase.insert(...)` then handle it ### Phone Lookup Queries MUST Filter Deleted Leads (Jan 30) - **Bug:** When a lead is soft-deleted and re-created with the same phone, `maybeSingle()` throws PGRST116 (multiple rows) - **Silent failure:** Code was ignoring PGRST116 error, resulting in `lead = null` even though active lead exists - **Fix:** Always add `.is('deleted_at', null)` BEFORE `.or(phone.eq.format1,...)` in phone lookups - **Affected files:** `webhooks.js` (inbound SMS), `voice.js` (inbound calls) - **Broader pattern:** Any query using `maybeSingle()` on a table with soft deletes MUST filter `deleted_at` - **Call list gotcha:** Also need `.not('phone', 'is', null)` to filter leads without phone numbers ### React Patterns (from Jan 19 audit) - **Array keys from content, not index** - Use `key={item.id}` or `key={item}` for strings, not `key={idx}` - **Optional chaining everywhere** - `businessIntel?.hiring_needs?.looking_for` not `businessIntel.hiring_needs.looking_for` - **Promise.allSettled for batch ops** - One failure shouldn't kill the whole batch - **Error state in components** - Users need to know when things fail, not just see empty UI ### TDZ (Temporal Dead Zone) in useCallback - Jan 26 - **NEVER reference later-defined callbacks in dependency arrays** - Causes TDZ crash at runtime - **Bad:** `const selectAll = useCallback(() => {...}, [filterBySearch])` when `filterBySearch` defined 100 lines later - **Fix:** Inline the logic instead of referencing the function, or move the dependency earlier in file - **Why:** Dependency array is evaluated at definition time, not execution time - variable must exist ### API Rate Limiting - **Expensive AI endpoints need `expensiveAiLimiter`** - GPT-4o calls cost money, protect them - **Check all POST endpoints for rate limits** - Easy to forget on new endpoints ### The 200 Hour Rule - **Document everything as you go** - You WILL lose context - **If it's not in a .md file, it doesn't exist** - Memory is unreliable - **Evidence archive before fixes** - Screenshot/save state before changing anything ### Investigation Before Planning - **Always verify user reports** - Screenshots can be outdated; the actual code may be more complete - **Audit first, plan second** - Read all related files before assuming something is broken - **Check what API returns** - Data often exists server-side but isn't displayed client-side - **Count what's working vs missing** - Frame the gap, not the whole feature (e.g., "5/17 issues missing" not "17 issues") ### Debugging "Not Working" Features When user says "X isn't showing/working": 1. **Trace the data flow** - Where is data created? Stored? Fetched? Displayed? 2. **Check field names at each step** - camelCase vs snake_case mismatches are common 3. **Verify API select includes all needed fields** - Frontend can't show what API doesn't return 4. **Look for multiple data sources** - Same concept may be stored in different places (e.g., buyingSignal in communication.metadata AND buying_signals in lead.metadata) 5. **Add fallback detection** - If data might come from multiple sources, check all of them --- ## Database / Supabase ### Patterns That Work - Perplexity caching: 30-day cache in `company_intel` table - Soft deletes: `deleted_at` column, filter with `WHERE deleted_at IS NULL` - Realtime subscriptions: `RealtimeContext.jsx` pattern - Phone numbers: E.164 Australian format (+614...) - `supabaseAdmin` client for server-side auth validation ### Gotchas - **Notion MCP uses different IDs than URLs** - The database ID in Notion URLs (e.g., `7129fca3-14a4-48a7-8de6-7e14a880823d`) is NOT what the MCP needs. Use `API-post-search` to find the `data_source_id` (e.g., `6ede5973-7f70-4814-bdaa-711934c18194`). The URL ID is `database_id`, but MCP queries need `data_source_id`. Search by name first, then use the ID from results. - Race conditions on callback creation - check exists before insert - RLS policies can silently block operations - test with actual user tokens - Realtime only fires on tables with replication enabled - Large result sets need pagination - don't fetch all leads at once - **Storage buckets can't be created via SQL** - Database tables (voicemail_recordings, voicemail_drops) can be migrated but Storage buckets must be created via Supabase Storage API or Dashboard. Check for missing buckets when features fail with "Storage bucket not configured" - **Realtime debugging:** Check browser console for `[Realtime] Communications channel: SUBSCRIBED`. If not subscribed, WebSocket connection failed. - **Realtime race condition:** Subscription connects asynchronously after page load. Messages arriving in the first few seconds may be missed. Hard refresh reconnects. - **Use `gen_random_uuid()` not `uuid_generate_v4()`** - The uuid-ossp extension may not be enabled; gen_random_uuid() is built-in to PostgreSQL 13+ - **`new Date(null)` = epoch (1970)** - Always guard date calculations with year checks (>= 2020). Null dates show as "491295 hrs overdue" (56 years!) - **Callback `scheduled_at` can be null** - SMS auto-callbacks don't always set a date. Guard with `if (date.getFullYear() >= 2020)` - **"Save" buttons failing silently** - Often means columns don't exist in DB. Check schema matches what code is trying to save. Example: Intel Edit modal failed because `user_notes`, `manually_updated` columns were never created. - **Division by zero in UI calculations** - Always check denominator > 0 before calculating percentages. Example: `script.times_replied / script.times_used` crashes when `times_used = 0` - **API select must include all needed fields** - If frontend needs `lead.metadata`, the backend query MUST include `metadata` in the select. Example: `sms.js:1084` was missing `metadata` so `conv.lead.metadata` was always undefined. Fix: `.select('...fields, metadata')` - **Type field conventions in communications table** - Use `type: 'sms_outbound'` NOT `type: 'sms'` for outbound messages. The conversations endpoint filters by `type IN ('sms_inbound', 'sms_outbound')`. Using `type: 'sms'` means messages won't appear in the inbox! - **Metadata field naming inconsistency** - Communication uses `metadata.buyingSignal` (camelCase) with `level` field. Lead uses `metadata.buying_signals` (snake_case array) with `type` field. Always check both: `latestSignal?.type === 'high' || latestSignal?.level === 'high'` - **UI forms that "don't save"** - Trace the save handler: does it actually call an API to persist data? Example: `PostCallSummarySheet` generated AI summaries but never called `callsApi.log()` - user feedback was lost. Always verify `handleSave/handleComplete` functions include the actual API call. - **Silent database insert failures** - Always capture the result of `.insert()` calls: `const { error } = await supabase.from('table').insert({...})`. Without error capture, inserts can fail silently (SMS sent via Twilio but not logged to DB). Example: playbook.js sent messages but never showed in chat history because communications insert wasn't verified. - **Backend/Frontend category mismatch** - If backend sends category values that frontend doesn't render, items disappear. Example: Backend sent `acknowledgment` category for SMS triage, but frontend `categoryOrder` only had `['buying_signal', 'callback_request', 'question', 'positive', 'other']` - conversations with `acknowledgment` never appeared. Fix: Map unknown categories to a catch-all like 'other'. - **leads table has no `name` or `trade` columns** - Use `first_name, last_name` instead of `name`. Trade comes from `metadata.trade`. Query `.select('id, name, trade')` will fail. For search, use `.or('first_name.ilike.%query%,last_name.ilike.%query%')`. **IMPORTANT:** When fixing a column name error, grep the ENTIRE codebase - the same wrong column is often used in multiple files (qualityAudit.js, sequenceProcessor.js, sequences.js, activation.js, activationAI.js all had this bug). - **Phone normalization double-prefix bug** - If a phone number is already E.164 format (`+61451415169`), don't re-add country code. Bug: `+61${normalizedPhone.slice(1)}` turns `+61451415169` into `+6161451415169`. Fix: Use normalized phone directly, it's already correct format. - **RLS blocks backend reads AND writes** - Tables with RLS enabled block ALL backend operations (not just writes). The anon key can't read sequences, enrollments, dossiers, etc. **ALWAYS use `supabaseAdmin || supabase` pattern for any table with RLS.** This bit us multiple times: sequences API returned empty, dossier SELECT returned null then INSERT failed. If an API returns empty/null when data exists, check RLS first. - **Race condition on upsert patterns** - SELECT then INSERT can fail if another process creates the row between queries. Example: Dossier GET checks if exists, gets null (RLS), tries INSERT, fails with duplicate key (call log already created it). Fix: Catch error code `23505` (duplicate key) and re-SELECT. - **Auto-enrollment needs backend trigger** - Don't rely on frontend UI for critical automations. If user closes app before selecting sequence, automation fails. Put auto-enrollment in backend call log endpoint: `if (outcome === 'no_answer') { enrollInSequence() }`. - **Check table name conflicts before migration** - Before creating new tables, grep existing schema files. Example: `daily_metrics` already existed with different columns (calls/sms/leads), so intelligence system metrics table was renamed to `intelligence_daily_metrics`. Migration will fail if table exists with different schema - the `IF NOT EXISTS` clause doesn't save you when columns differ. - **Frontend build fails on missing npm packages** - If a hook imports a library (e.g., `uuid` in `useIntelligenceTracking.js`), it MUST be in `admin/package.json`. Build works locally if you ran `npm install` but Railway builds from scratch. Error: `Rollup failed to resolve import "uuid"`. Fix: `cd admin && npm install uuid --save`. - **Internal job triggers bypass auth** - Jobs API requires Supabase JWT which is hard to get externally. Added `/api/jobs/internal/:jobName` route with `X-Internal-Key` header auth for cron/admin use. Example: `curl -X POST -H "X-Internal-Key: KEY" https://api/jobs/internal/excellenceReport`. - **Scheduled jobs can infinite loop** - If a setTimeout-based job scheduler calculates 0ms delay, it runs immediately and reschedules itself, causing infinite spam. Example: Prompt evolution job was spamming Slack every second. Fix: (1) Add rate limiting to Slack service (max 1 msg/sec), (2) Disable problematic job until root cause fixed. Always add safeguards to scheduled job functions. - **Rep performance needs handled_by column** - The `communications` table needs a top-level `handled_by UUID` column (not just in metadata) for efficient querying by rep. Call logging must set this when recording calls. Migration: `ALTER TABLE communications ADD COLUMN IF NOT EXISTS handled_by UUID` + backfill from `metadata->>'handled_by'` or `metadata->>'user_id'`. - **Phone normalization must apply when sending by leadId** - The `/api/sms/send` endpoint normalized phone numbers when passed directly (`phone` param), but NOT when looking up from lead record (`leadId` param). Bug: Leads with `phone: '0412345678'` would fail because `+610412345678` (12 digits) isn't valid E.164. Fix: Apply `normalizeAustralianPhone(lead.phone)` to the phone from lead record, not just direct phone input. Always normalize at point of use, not just point of entry. - **Check ALL job files for RLS** - Job files (`src/jobs/`) run without user context. If they use `supabase` instead of `supabaseAdmin`, RLS silently returns empty results — no error, just 0 records. Bug: `sequenceProcessor.js` and `scheduledSms.js` used anon key, RLS blocked reads, jobs appeared to work but processed nothing. Fix: Grep all job files for `require('../config/database')` and ensure they use `supabaseAdmin || supabase` pattern. This is the THIRD time RLS has blocked backend operations — always check job files after adding RLS policies. - **Express route shadowing with `:id` params** - Routes with dynamic params like `/:id` will catch ALL requests if placed before specific routes. Bug: `/api/leads/assignments` was returning "Invalid lead ID format" because `/:id` route (line 891) came BEFORE `/assignments`. The word "assignments" was being treated as an ID. Fix: Move specific routes (like `/search`, `/assignments`) BEFORE dynamic `/:id` routes. Route order in Express matters! Rule: Static paths first, dynamic params last. - **Supabase silently returns empty on non-existent columns** - If you SELECT or filter on a column that doesn't exist, Supabase returns empty results with NO error. Bug: Team stats showed 0 calls because queries used `created_by` column which doesn't exist on `communications` table - actual columns are `handled_by` and `user_id`. Fix: Always verify column names against actual schema. Use `\d table_name` in psql or check Supabase Table Editor. Test queries manually before shipping. This is insidious because everything "works" (no crashes) but data is wrong. - **Voice Assistant SILENCE_TIMEOUT too aggressive** - VoiceAssistant.jsx has a 5-second silence timeout that stops the mic if no speech is detected. Web Speech API `onresult` only fires when speech is RECOGNIZED, not when audio is received. If user hesitates or speaks unclearly, timeout triggers before they finish. Bug: Mic "cuts out after 5 seconds". Fix: Increase `SILENCE_TIMEOUT` from 5000 to 15000ms (15 seconds). Also check button label matches behavior (was "Hold and Speak" but actually tap-to-toggle). - **Hardcoded API key fallbacks are security risks** - Pattern `const KEY = process.env.KEY || 'default-key'` exposes the default in source code. If code is on public GitHub and env var isn't set in prod, anyone can use the default key. Bug: `src/routes/jobs.js` had `INTERNAL_JOB_KEY || 'growth-engine-internal-2024'` allowing anyone to trigger internal jobs. Fix: Remove fallback, fail fast if env var not set, generate secure random key for production. - **Migrations can exist but never be applied** - A migration SQL file in `supabase/` doesn't mean the table exists. If migration isn't tracked in PENDING_MIGRATIONS.md, it may have been forgotten. Bug: `dev_queue` table migration existed but was never run - bug/feature reports silently failed. Fix: Always add migrations to PENDING_MIGRATIONS.md immediately when creating them, even if you plan to run them right away. - **Mobile bottom padding with large sticky headers** - Standard `pb-24` (96px) may not be enough when page has large sticky header taking up viewport space. Combined with 80px BottomNav and iOS safe-area, content can be cut off. Bug: Leads page couldn't scroll to bottom - had 220px sticky header + BottomNav. Fix: Use `pb-32` (128px) for pages with substantial sticky headers. Test on actual mobile devices. - **iOS Safari PWA blocks Web Speech API** - `webkitSpeechRecognition in window` returns true on iOS Safari PWA, but `recognition.start()` fails silently or throws. Bug: Voice Assistant worked in Safari browser but not when installed as PWA. Fix: Wrap `recognition.start()` in try-catch and fall back to Whisper transcription (MediaRecorder + backend API). Also handle onerror events with 'not-allowed' or 'service-not-allowed' by falling back to Whisper. Pattern: Always have a fallback when using browser APIs that might be restricted in PWA/WebView contexts. - **Android Chrome Web Speech API ends after 3-5 seconds** - Even with `recognition.continuous = true`, Android Chrome fires `onend` after detecting a brief pause in speech. Bug: Voice Assistant cut out after 3-5 seconds on Android. Fix: Track `commandProcessedRef` and `manualStopRef` refs. In `onend`, if neither is true, call `recognition.start()` to restart. Pattern: Don't trust `continuous` mode on mobile browsers - always implement auto-restart logic in `onend` handler. - **Web Speech API - manual stop discards interim transcripts** - When user manually stops recognition before getting a final result (`isFinal=true`), the interim transcript is lost. Bug: Saying "Mark hot" then tapping stop button = nothing happened. Fix: Store current transcript in a ref (`currentTranscriptRef`). In `onend`, if `manualStopRef=true` AND transcript exists but not processed, call `processCommand()`. Pattern: Always save transcript state and handle manual stop as a valid "finalize now" signal. ### Migration Protocol (CLI - Preferred) 1. Write SQL in `supabase/[feature]-migration.sql` 2. Run `npx supabase migration new [name]` 3. Copy content to new migration file 4. Run `npx supabase db push --linked` 5. Mark ✅ in `supabase/PENDING_MIGRATIONS.md` 6. Verify with `npx supabase migration list --linked` **IMPORTANT:** CC has direct DB access - always use CLI, don't ask user to run SQL manually! ### CLI Commands That Work ```bash npx supabase migration list --linked # Check applied migrations npx supabase db push --linked # Apply pending migrations npx supabase migration new [name] # Create new migration file npx supabase inspect db table-sizes --linked # Check table sizes npx supabase migration repair --status reverted --linked # Reset failed migration ``` **Does NOT exist:** `npx supabase db execute --linked` - use `db push` instead ### Migration Workflow (Quick Reference) ```bash # 1. Create migration file npx supabase migration new lead_dossier # 2. Write SQL to the created file in supabase/migrations/ # 3. Push to remote database npx supabase db push --linked # 4. Verify npx supabase migration list --linked ``` **Gotcha:** `db push` may fail with 502 on first try - just retry, usually works second time ### Migration Recovery If a migration fails partway through: 1. Check what columns/tables were created before failure 2. Run `npx supabase migration repair --status reverted --linked` 3. Fix the migration SQL 4. Re-run `npx supabase db push --linked` ### Extending Existing Tables Before using CREATE TABLE, check if table exists: - **Wrong:** `CREATE TABLE scripts (...)` when scripts table already exists - **Right:** `ALTER TABLE scripts ADD COLUMN IF NOT EXISTS new_col TYPE` - Always read existing schema before writing migrations ### Migration Protocol (Manual - Fallback) 1. Write SQL in `supabase/[feature]-migration.sql` 2. Add entry to `supabase/PENDING_MIGRATIONS.md` with ⬜ 3. Show SQL to user 4. User runs in Supabase SQL Editor 5. User marks ✅ in PENDING_MIGRATIONS.md 6. Then test the feature --- ## Frontend / React ### Patterns That Work - `ErrorBoundary` wrapper on App.jsx - catches crashes gracefully - Time-aware UI components (morning/work/evening modes) - React Query for caching - implemented in performance session - Code splitting with lazy imports for faster page loads - 44px minimum tap targets for mobile - `useClickOutside` hook for dropdown dismissal - **Status badges on mobile should be icon-only** - Full text badges take too much space. Use `hidden md:inline` for text, show only icon on mobile. Position `bottom-20 right-3` to stay above nav. ### Gotchas - **Tailwind v4 Spacing: Use `gap-*` not `space-y-*` for Flex** - Tailwind CSS v4 changed how `space-y-*` works (uses `:not(:last-child)` instead of `* + *`, and `:where()` with 0 specificity). In flex contexts, `space-y-*` can behave unexpectedly. **Pattern:** Always use `flex flex-col gap-*` instead of `space-y-*` for vertical spacing. Example: Desktop sidebar nav items had no visible gap despite `space-y-4`. Multiple fix attempts failed. Root cause: Tailwind v4's changed implementation. Fix: `