tribunal-kit 4.3.0 → 4.3.1

package/.agent/skills/intelligent-routing/SKILL.md

@@ -164,35 +164,35 @@ This file contains all available skills and workflows as a condensed index for t
 |`web-design-guidelines`|Review UI code for Next-Generation Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".|
 |`webapp-testing`|Web application testing principles. E2E, Playwright, deep audit strategies.|
 |`whimsy-injector`|Micro-delight generator for frontend interfaces. Suggests and implements subtle animations, playful transitions, and interaction polish across any frontend stack.|
-|`workflow-optimizer`|Analyzes agent tool-calling patterns and task execution efficiency to suggest process improvements.|
-|`api-architect`|API contract design agent. Builds robust REST/GraphQL/tRPC endpoints with RFC 9457 error formats, idempotency, pagination, and versioning. Use when designing new API routes or reviewing API contracts.|
-|`resilience-reviewer`|Fault tolerance reviewer. Audits for swallowed errors, naked Promises, missing retries/timeouts, absent circuit breakers, and missing React error boundaries. Use when reviewing backend or full-stack code for reliability.|
-|`schema-reviewer`|Input validation reviewer. Enforces strict Zod/Pydantic validation at all trust boundaries (API, env, query params). Catches `z.any()`, missing `.parse()`, and unvalidated external data. Use when reviewing data ingestion or API input handling.|
-|`gsap-core`|GSAP core animation API — gsap.to(), from(), fromTo(), easing, stagger, defaults, matchMedia(). Use for JavaScript animation with GSAP.|
-|`gsap-scrolltrigger`|GSAP ScrollTrigger plugin — scroll-driven animations, pinning, snapping. Use when building scroll-linked animation.|
-|`gsap-timeline`|GSAP timeline sequencing — Timeline API, position parameters, labels, nesting. Use for multi-step animation choreography.|
-|`gsap-react`|GSAP in React — useGSAP hook, ref-based targeting, cleanup, context scoping. Use when animating React components with GSAP.|
-|`gsap-plugins`|GSAP plugins — Flip, Draggable, MorphSVG, SplitText, MotionPath, DrawSVG. Use for advanced GSAP effects.|
-|`gsap-performance`|GSAP performance — will-change, GPU compositing, lazy MediaQuery, reduced motion. Use when optimizing GSAP animations.|
-|`gsap-utils`|GSAP utility methods — toArray, clamp, mapRange, interpolate, distribute. Use for GSAP helper functions.|
-|`gsap-frameworks`|GSAP framework integration — Vue, Svelte, Astro, Angular, Webflow. Use when integrating GSAP outside React.|
-|`error-resilience`|Error resilience patterns. Retry strategies, circuit breakers, graceful degradation, timeout policies.|
-|`data-validation-schemas`|Data validation with Zod, Pydantic, and JSON Schema. Use when building validation layers.|
-|`monorepo-management`|Monorepo tooling and workspace management. Turborepo, Nx, pnpm workspaces.|
-|`typescript-advanced`|Advanced TypeScript patterns. Generics, conditional types, template literals, discriminated unions.|
-|`game-developer`|Game development orchestrator. Routes to platform-specific skills (Unity/C#, Godot/GDScript, WebGL). Use when building games or game engines.|
-|`documentation-writer`|Technical documentation specialist. README files, API docs, code comments, architecture docs, and AI-friendly documentation. Use when writing or reviewing documentation.|
-|`test-engineer`|Test generation and strategy specialist. Creates tests using the Testing Trophy (unit → integration → E2E). Use when generating tests or designing test architecture.|
-|`qa-automation-engineer`|QA automation specialist. End-to-end testing pipelines, Playwright/Cypress configuration, CI test integration, visual regression. Use when building automated QA systems.|
-|`code-archaeologist`|Legacy code exploration specialist. Navigates unfamiliar codebases, identifies patterns, maps dependencies, documents tribal knowledge. Use when exploring or understanding legacy code.|
-|`project-planner`|Project planning specialist. 4-phase methodology (Analyze → Plan → Solution → Implement). Use when planning features, roadmaps, or multi-step implementations.|
-|`product-manager`|Product strategy specialist. Feature prioritization, roadmap planning, stakeholder alignment, competitive analysis. Use when making product decisions or prioritizing features.|
-|`product-owner`|User story and backlog management specialist. Writing acceptance criteria, sprint planning, backlog grooming. Use when defining user stories or managing backlogs.|
-|`seo-specialist`|SEO optimization specialist. Technical SEO, meta tags, structured data (JSON-LD), Core Web Vitals impact on search ranking, sitemap/robots configuration. Use when optimizing search visibility.|
-|`throughput-optimizer`|Throughput and latency optimization specialist. Load testing, connection pooling, queue management, batch processing, caching strategies. Use when optimizing system throughput or reducing latency.|
-|`vitals-reviewer`|Core Web Vitals specialist. LCP, CLS, INP measurement and optimization, Lighthouse auditing, real user monitoring. Use when auditing or improving web performance metrics.|
-|`penetration-tester`|Penetration testing and red team specialist. MITRE ATT&CK mapping, attack surface analysis, exploitation paths, vulnerability chaining. Use when pen testing applications or assessing attack surfaces.|
-|`db-latency-auditor`|Database performance specialist. Slow query analysis, EXPLAIN ANALYZE, index optimization, N+1 detection, connection pool tuning. Use when debugging database performance issues.|
+|`workflow-optimizer`|Analyzes agent tool-calling patterns and task execution efficiency to suggest process improvements.|
+|`api-architect`|API contract design agent. Builds robust REST/GraphQL/tRPC endpoints with RFC 9457 error formats, idempotency, pagination, and versioning. Use when designing new API routes or reviewing API contracts.|
+|`resilience-reviewer`|Fault tolerance reviewer. Audits for swallowed errors, naked Promises, missing retries/timeouts, absent circuit breakers, and missing React error boundaries. Use when reviewing backend or full-stack code for reliability.|
+|`schema-reviewer`|Input validation reviewer. Enforces strict Zod/Pydantic validation at all trust boundaries (API, env, query params). Catches `z.any()`, missing `.parse()`, and unvalidated external data. Use when reviewing data ingestion or API input handling.|
+|`gsap-core`|GSAP core animation API — gsap.to(), from(), fromTo(), easing, stagger, defaults, matchMedia(). Use for JavaScript animation with GSAP.|
+|`gsap-scrolltrigger`|GSAP ScrollTrigger plugin — scroll-driven animations, pinning, snapping. Use when building scroll-linked animation.|
+|`gsap-timeline`|GSAP timeline sequencing — Timeline API, position parameters, labels, nesting. Use for multi-step animation choreography.|
+|`gsap-react`|GSAP in React — useGSAP hook, ref-based targeting, cleanup, context scoping. Use when animating React components with GSAP.|
+|`gsap-plugins`|GSAP plugins — Flip, Draggable, MorphSVG, SplitText, MotionPath, DrawSVG. Use for advanced GSAP effects.|
+|`gsap-performance`|GSAP performance — will-change, GPU compositing, lazy MediaQuery, reduced motion. Use when optimizing GSAP animations.|
+|`gsap-utils`|GSAP utility methods — toArray, clamp, mapRange, interpolate, distribute. Use for GSAP helper functions.|
+|`gsap-frameworks`|GSAP framework integration — Vue, Svelte, Astro, Angular, Webflow. Use when integrating GSAP outside React.|
+|`error-resilience`|Error resilience patterns. Retry strategies, circuit breakers, graceful degradation, timeout policies.|
+|`data-validation-schemas`|Data validation with Zod, Pydantic, and JSON Schema. Use when building validation layers.|
+|`monorepo-management`|Monorepo tooling and workspace management. Turborepo, Nx, pnpm workspaces.|
+|`typescript-advanced`|Advanced TypeScript patterns. Generics, conditional types, template literals, discriminated unions.|
+|`game-developer`|Game development orchestrator. Routes to platform-specific skills (Unity/C#, Godot/GDScript, WebGL). Use when building games or game engines.|
+|`documentation-writer`|Technical documentation specialist. README files, API docs, code comments, architecture docs, and AI-friendly documentation. Use when writing or reviewing documentation.|
+|`test-engineer`|Test generation and strategy specialist. Creates tests using the Testing Trophy (unit → integration → E2E). Use when generating tests or designing test architecture.|
+|`qa-automation-engineer`|QA automation specialist. End-to-end testing pipelines, Playwright/Cypress configuration, CI test integration, visual regression. Use when building automated QA systems.|
+|`code-archaeologist`|Legacy code exploration specialist. Navigates unfamiliar codebases, identifies patterns, maps dependencies, documents tribal knowledge. Use when exploring or understanding legacy code.|
+|`project-planner`|Project planning specialist. 4-phase methodology (Analyze → Plan → Solution → Implement). Use when planning features, roadmaps, or multi-step implementations.|
+|`product-manager`|Product strategy specialist. Feature prioritization, roadmap planning, stakeholder alignment, competitive analysis. Use when making product decisions or prioritizing features.|
+|`product-owner`|User story and backlog management specialist. Writing acceptance criteria, sprint planning, backlog grooming. Use when defining user stories or managing backlogs.|
+|`seo-specialist`|SEO optimization specialist. Technical SEO, meta tags, structured data (JSON-LD), Core Web Vitals impact on search ranking, sitemap/robots configuration. Use when optimizing search visibility.|
+|`throughput-optimizer`|Throughput and latency optimization specialist. Load testing, connection pooling, queue management, batch processing, caching strategies. Use when optimizing system throughput or reducing latency.|
+|`vitals-reviewer`|Core Web Vitals specialist. LCP, CLS, INP measurement and optimization, Lighthouse auditing, real user monitoring. Use when auditing or improving web performance metrics.|
+|`penetration-tester`|Penetration testing and red team specialist. MITRE ATT&CK mapping, attack surface analysis, exploitation paths, vulnerability chaining. Use when pen testing applications or assessing attack surfaces.|
+|`db-latency-auditor`|Database performance specialist. Slow query analysis, EXPLAIN ANALYZE, index optimization, N+1 detection, connection pool tuning. Use when debugging database performance issues.|
 |`ai-code-reviewer`|AI/LLM integration code reviewer. Hallucinated model names, invented API parameters, prompt injection vulnerabilities, missing rate limits, streaming error handling. Use when reviewing code that calls LLM APIs.|
 
 
@@ -235,4 +235,12 @@ Review these questions before confirming output:
 
 **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
 - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+
+
+## Pre-Flight Checklist
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

package/.agent/skills/knowledge-graph/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: Knowledge Graph Analyzer
+description: Understands the architecture and dependencies of the codebase without token bloat.
+version: 1.0.0
+---
+
+# /graph — Knowledge Graph Skill
+
+Use this skill when the user types `/graph` or when you need to deeply understand the architecture of an unfamiliar codebase without suffering from context-window bloat.
+
+## Pre-Flight Checklist
+Before answering architectural questions or making broad code changes, you must understand the environment.
+- [ ] Have I run the Macro Mapper to get the high-level architecture?
+- [ ] Have I used the Micro Zoomer on the specific files related to the user's request to see their exact signatures?
+
+## Execution Protocol
+
+1. **Step 1: The Macro Map (World View)**
+   Execute the graph builder to map module boundaries. This runs incrementally and respects `.gitignore`.
+   ```bash
+   node .agent/scripts/graph_builder.js
+   ```
+   Read the output file at `.agent/history/architecture-graph.yaml`. **Do NOT try to read every file in the project.** Use this map to identify which files export the functions or components you need.
+
+2. **Step 2: The Micro Zoom (Street View)**
+   Once you know which file to investigate, use the zoomer to get its structural skeleton. This strips out the internal logic and returns only imports, exports, class signatures, and function parameters.
+   ```bash
+   node .agent/scripts/graph_zoom.js --focus <path_to_file>
+   ```
+   *Example: `node .agent/scripts/graph_zoom.js --focus src/components/Button.tsx`*
+
+3. **Step 3: Analyze and Advise**
+   Present the user with your findings. Highlight hidden dependencies, circular imports, or structural insights based on what you discovered in the graphs.
+
+## VBC Protocol (Verification-Before-Completion)
+You are explicitly forbidden from guessing or "hallucinating" what functions, props, or variables exist inside a file. You MUST use the `graph_zoom.js` script to verify a component's exact signature before you attempt to call it, mock it, or rewrite it.

package/.agent/skills/lint-and-validate/SKILL.md

@@ -250,4 +250,12 @@ Review these questions before confirming output:
 
 **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
 - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+
+
+## Pre-Flight Checklist
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

package/.agent/skills/llm-engineering/SKILL.md

@@ -383,4 +383,12 @@ Review these questions before confirming output:
 
 **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
 - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+
+
+## Pre-Flight Checklist
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

package/.agent/skills/local-first/SKILL.md

@@ -167,4 +167,12 @@ Review these questions before confirming output:
 
 **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
 - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+
+
+## Pre-Flight Checklist
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

package/.agent/skills/mcp-builder/SKILL.md

@@ -131,4 +131,12 @@ Review these questions before confirming output:
 
 **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
 - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+
+
+## Pre-Flight Checklist
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.

package/.agent/skills/mobile-design/SKILL.md

@@ -1,216 +1,216 @@
----
-name: mobile-design
-description: Mobile-first design for iOS, Android, Foldables, React Native, Flutter. Touch interaction, haptics, 120Hz performance, on-device AI, spatial UI, Reanimated 3. Use when building mobile UI, animations, or cross-platform apps.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 3.1.0
-last-updated: 2026-04-06
----
-
-# Mobile Design — Dense Reference
-
-## Hallucination Traps (Read First)
-- ❌ `Animated.View` for any animation → ✅ `Reanimated 3` worklets (Animated API is legacy, runs on JS thread)
-- ❌ `ScrollView` for lists → ✅ `FlashList` (Shopify) — ScrollView renders ALL items at once
-- ❌ `estimatedItemSize` optional in FlashList → ✅ **REQUIRED** or you get 0-height items
-- ❌ White backgrounds (`#FFFFFF`) → ✅ OLED: `#000000` true black; off-white: `#FAFAFA`
-- ❌ Linear animations (`easing: linear`) → ✅ Spring physics (`stiffness`, `damping`)
-- ❌ Touch targets < 48px → ✅ Min 48px hitbox (visual size can be smaller via padding)
-- ❌ `useAnimatedStyle` in worklet without `'worklet'` directive → crashes on native thread
-- ❌ iOS: `useSafeAreaInsets()` optional → ✅ Required — screen content goes under dynamic island/home indicator
-- ❌ Android: hardcoded status bar height (24dp) → ✅ `StatusBar.currentHeight` (varies per device)
-- ❌ Platform-specific code with `if (platform === 'ios')` scattered everywhere → ✅ centralize in platform/ files
-- ❌ `console.log` in production → ✅ blocks JS thread — remove before release
-
----
-
-## React Native Performance
-
-### FlashList (Required for Lists)
-```tsx
-import { FlashList } from "@shopify/flash-list";
-<FlashList
-  data={items}
-  renderItem={({ item }) => <ItemCard item={item} />}
-  estimatedItemSize={100}          // REQUIRED — measure actual item height first
-  keyExtractor={(item) => item.id}
-  getItemType={(item) => item.type} // multi-type optimization
-/>
-// ❌ NEVER: <ScrollView>{items.map(...)}</ScrollView> for lists
-// ❌ NEVER: <FlatList> for perf-critical lists — FlashList is 5-10x faster
-```
-
-### Reanimated 3 — Worklet Animations (Required for 120Hz)
-```tsx
-import { useSharedValue, useAnimatedStyle, withSpring, withTiming, runOnJS } from 'react-native-reanimated';
-
-// Shared values run on the UI thread — never on JS thread
-const scale = useSharedValue(1);
-const opacity = useSharedValue(0);
-
-// Animated style — computed on UI thread (no bridge crossing)
-const animatedStyle = useAnimatedStyle(() => ({
-  transform: [{ scale: scale.value }],
-  opacity: opacity.value,
-}));
-
-// Triggers
-const onPress = () => {
-  scale.value = withSpring(0.95, { stiffness: 400, damping: 15 });
-  opacity.value = withTiming(1, { duration: 200 });
-};
-
-// Call JS function from worklet
-const onComplete = () => runOnJS(setVisible)(true);
-scale.value = withSpring(1, {}, onComplete);
-
-// ❌ TRAP: Accessing shared value with .value inside useAnimatedStyle is fine — but inside a gesture handler callback, you need runOnJS to call React setState
-```
-
-### 120Hz Animation Rules
-- ✅ Animate ONLY: `transform` (translateX/Y, scale, rotate), `opacity` — all GPU composited
-- ❌ Never animate: `width`, `height`, `margin`, `padding`, `top/left/bottom/right` — causes layout recalc at 60 times per second → janky, battery draining
-- ✅ Use `withSpring` for all UI interactions (feel alive) — `withTiming` only for intentional timed animations
-- ✅ `Gesture.Pan()` / `Gesture.Tap()` from `react-native-gesture-handler` v2 (not `PanResponder`)
-
----
-
-## Haptics
-```tsx
-import * as Haptics from 'expo-haptics';
-// light → switch toggle, tap feedback
-// medium → selection change, confirm
-// heavy → destructive action, strong confirm
-// notificationAsync('success' | 'warning' | 'error') → operation outcomes
-Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);  // tap, toggle
-Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success); // save complete
-// ❌ Never overuse — haptics must mean something
-// ❌ Haptics not supported on Android emulators — test on device
-```
-
----
-
-## Safe Areas & Platform Layout
-```tsx
-import { useSafeAreaInsets } from 'react-native-safe-area-context';
-import { Platform, StatusBar } from 'react-native';
-
-function Screen() {
-  const insets = useSafeAreaInsets();
-  return (
-    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
-      {/* Content safe from Dynamic Island, home indicator, status bar */}
-    </View>
-  );
-}
-// Android status bar
-const STATUS_BAR_HEIGHT = Platform.OS === 'android' ? StatusBar.currentHeight ?? 24 : 0;
-
-// Foldable/tablet — dual pane
-import { useWindowDimensions } from 'react-native';
-function AdaptiveLayout() {
-  const { width } = useWindowDimensions();
-  const isTablet = width >= 600;
-  return isTablet ? <TwoPaneView /> : <SinglePaneView />;
-}
-```
-
----
-
-## Touch Psychology & Thumb Zones
-- **Thumb zone**: Bottom 40% of screen = primary actions, FABs, CTAs
-- **Dead zone**: Top 25% = destructive/rare actions only
-- **48px minimum hitbox**: Visual icon can be 24px, padding expands hitbox to 48px
-  ```tsx
-  // Magnetic padding — visually small, touch-friendly
-  <TouchableOpacity style={{ padding: 12, margin: -4 }}>
-    <Icon size={24} />
-  </TouchableOpacity>
-  ```
-- **Coyote time**: Allow 100–150ms buffer after button intent registers before processing — prevents mis-taps
-
----
-
-## Navigation (Expo Router / React Navigation)
-```tsx
-// Expo Router v3+ (file-based, recommended)
-// app/(tabs)/_layout.tsx — tab navigator
-// app/[id].tsx — dynamic segment
-// app/(modal)/settings.tsx — modal group
-
-// Stack navigation with gesture
-import { Stack } from 'expo-router';
-<Stack screenOptions={{ headerShown: false, animation: 'slide_from_right' }}>
-  <Stack.Screen name="(tabs)" />
-  <Stack.Screen name="[id]" options={{ presentation: 'modal' }} />
-</Stack>
-
-// Deep linking (Expo Router handles automatically via app.json scheme)
-// ❌ TRAP: Don't use react-navigation Link for deep links in Expo Router — use expo-router Link
-import { Link, useRouter } from 'expo-router';
-const router = useRouter();
-router.push('/user/42');
-```
-
----
-
-## On-Device AI UX Patterns
-- **Zero-wait illusion**: When model runs → immediately show contextual skeleton/partial tokens
-- **Progressive disclosure**: Low confidence → softer UI, soft colors, require confirmation
-- **Streaming UI**: `useEffect` + SSE or `StreamingText` component appending tokens
-- **Local models** (MediaPipe, Core ML, ONNX): always wrap in try/catch — device capability varies
-
----
-
-## Color & Typography
-```tsx
-// OLED-safe dark mode
-const colors = {
-  background: '#000000',    // true black — OLED pixel off
-  surface: '#0A0A0A',       // cards
-  surfaceAlt: '#121212',    // elevated surfaces
-  border: '#1F1F1F',
-  text: '#FFFFFF',
-  textMuted: '#8E8E93',     // iOS system gray
-};
-// Dynamic type (iOS) — always use system font with scalesWithContentSizeCategory
-import { Text } from 'react-native';
-<Text style={{ fontSize: 16, fontFamily: Platform.OS === 'ios' ? 'System' : 'Roboto' }}>
-```
-
----
-
-## Performance Checklist
-| Issue | Fix |
-|-------|-----|
-| JS thread jank | Move ALL animations to Reanimated worklets |
-| Slow list | Replace ScrollView/FlatList with FlashList |
-| Image flicker | `Image` from `expo-image` (faster cache, blurhash) |
-| Re-render cascade | `React.memo` + stable callbacks + Zustand selectors |
-| Large bundle | Dynamic imports + Metro tree shaking |
-| Memory leak | `useEffect` cleanup + cancel animation on unmount |
-
-```tsx
-// Cancel animation on unmount
-useEffect(() => {
-  opacity.value = withTiming(1);
-  return () => cancelAnimation(opacity); // ← critical
-}, []);
-```
-
----
-
-## iOS-Specific
-- **BlurView**: Use `@react-native-community/blur` for frosted glass nav bars/modals
-- **SF Symbols**: Use `@expo/vector-icons/Ionicons` for system-native icons
-- **Haptics**: `expo-haptics` — rich feedback on iOS, limited on Android
-- **Dynamic Island**: Check `insets.top > 50` for Dynamic Island devices
-- **Sheet presentations**: `presentation: 'formSheet'` in Expo Router for iOS bottom sheet native feel
-
-## Android-Specific
-- **Material You**: Use `react-native-paper` for M3 dynamic color theming
-- **Edge-to-edge**: Set `android:windowLayoutInDisplayCutoutMode="shortEdges"` in AndroidManifest
-- **Back gesture prediction**: Wrap routes in `GestureHandlerRootView` at root
-- **Splash**: Use `expo-splash-screen` — never hardcode a delay
+---
+name: mobile-design
+description: Mobile-first design for iOS, Android, Foldables, React Native, Flutter. Touch interaction, haptics, 120Hz performance, on-device AI, spatial UI, Reanimated 3. Use when building mobile UI, animations, or cross-platform apps.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 3.1.0
+last-updated: 2026-04-06
+---
+
+# Mobile Design — Dense Reference
+
+## Hallucination Traps (Read First)
+- ❌ `Animated.View` for any animation → ✅ `Reanimated 3` worklets (Animated API is legacy, runs on JS thread)
+- ❌ `ScrollView` for lists → ✅ `FlashList` (Shopify) — ScrollView renders ALL items at once
+- ❌ `estimatedItemSize` optional in FlashList → ✅ **REQUIRED** or you get 0-height items
+- ❌ White backgrounds (`#FFFFFF`) → ✅ OLED: `#000000` true black; off-white: `#FAFAFA`
+- ❌ Linear animations (`easing: linear`) → ✅ Spring physics (`stiffness`, `damping`)
+- ❌ Touch targets < 48px → ✅ Min 48px hitbox (visual size can be smaller via padding)
+- ❌ `useAnimatedStyle` in worklet without `'worklet'` directive → crashes on native thread
+- ❌ iOS: `useSafeAreaInsets()` optional → ✅ Required — screen content goes under dynamic island/home indicator
+- ❌ Android: hardcoded status bar height (24dp) → ✅ `StatusBar.currentHeight` (varies per device)
+- ❌ Platform-specific code with `if (platform === 'ios')` scattered everywhere → ✅ centralize in platform/ files
+- ❌ `console.log` in production → ✅ blocks JS thread — remove before release
+
+---
+
+## React Native Performance
+
+### FlashList (Required for Lists)
+```tsx
+import { FlashList } from "@shopify/flash-list";
+<FlashList
+  data={items}
+  renderItem={({ item }) => <ItemCard item={item} />}
+  estimatedItemSize={100}          // REQUIRED — measure actual item height first
+  keyExtractor={(item) => item.id}
+  getItemType={(item) => item.type} // multi-type optimization
+/>
+// ❌ NEVER: <ScrollView>{items.map(...)}</ScrollView> for lists
+// ❌ NEVER: <FlatList> for perf-critical lists — FlashList is 5-10x faster
+```
+
+### Reanimated 3 — Worklet Animations (Required for 120Hz)
+```tsx
+import { useSharedValue, useAnimatedStyle, withSpring, withTiming, runOnJS } from 'react-native-reanimated';
+
+// Shared values run on the UI thread — never on JS thread
+const scale = useSharedValue(1);
+const opacity = useSharedValue(0);
+
+// Animated style — computed on UI thread (no bridge crossing)
+const animatedStyle = useAnimatedStyle(() => ({
+  transform: [{ scale: scale.value }],
+  opacity: opacity.value,
+}));
+
+// Triggers
+const onPress = () => {
+  scale.value = withSpring(0.95, { stiffness: 400, damping: 15 });
+  opacity.value = withTiming(1, { duration: 200 });
+};
+
+// Call JS function from worklet
+const onComplete = () => runOnJS(setVisible)(true);
+scale.value = withSpring(1, {}, onComplete);
+
+// ❌ TRAP: Accessing shared value with .value inside useAnimatedStyle is fine — but inside a gesture handler callback, you need runOnJS to call React setState
+```
+
+### 120Hz Animation Rules
+- ✅ Animate ONLY: `transform` (translateX/Y, scale, rotate), `opacity` — all GPU composited
+- ❌ Never animate: `width`, `height`, `margin`, `padding`, `top/left/bottom/right` — causes layout recalc at 60 times per second → janky, battery draining
+- ✅ Use `withSpring` for all UI interactions (feel alive) — `withTiming` only for intentional timed animations
+- ✅ `Gesture.Pan()` / `Gesture.Tap()` from `react-native-gesture-handler` v2 (not `PanResponder`)
+
+---
+
+## Haptics
+```tsx
+import * as Haptics from 'expo-haptics';
+// light → switch toggle, tap feedback
+// medium → selection change, confirm
+// heavy → destructive action, strong confirm
+// notificationAsync('success' | 'warning' | 'error') → operation outcomes
+Haptics.impactAsync(Haptics.ImpactFeedbackStyle.Light);  // tap, toggle
+Haptics.notificationAsync(Haptics.NotificationFeedbackType.Success); // save complete
+// ❌ Never overuse — haptics must mean something
+// ❌ Haptics not supported on Android emulators — test on device
+```
+
+---
+
+## Safe Areas & Platform Layout
+```tsx
+import { useSafeAreaInsets } from 'react-native-safe-area-context';
+import { Platform, StatusBar } from 'react-native';
+
+function Screen() {
+  const insets = useSafeAreaInsets();
+  return (
+    <View style={{ paddingTop: insets.top, paddingBottom: insets.bottom }}>
+      {/* Content safe from Dynamic Island, home indicator, status bar */}
+    </View>
+  );
+}
+// Android status bar
+const STATUS_BAR_HEIGHT = Platform.OS === 'android' ? StatusBar.currentHeight ?? 24 : 0;
+
+// Foldable/tablet — dual pane
+import { useWindowDimensions } from 'react-native';
+function AdaptiveLayout() {
+  const { width } = useWindowDimensions();
+  const isTablet = width >= 600;
+  return isTablet ? <TwoPaneView /> : <SinglePaneView />;
+}
+```
+
+---
+
+## Touch Psychology & Thumb Zones
+- **Thumb zone**: Bottom 40% of screen = primary actions, FABs, CTAs
+- **Dead zone**: Top 25% = destructive/rare actions only
+- **48px minimum hitbox**: Visual icon can be 24px, padding expands hitbox to 48px
+  ```tsx
+  // Magnetic padding — visually small, touch-friendly
+  <TouchableOpacity style={{ padding: 12, margin: -4 }}>
+    <Icon size={24} />
+  </TouchableOpacity>
+  ```
+- **Coyote time**: Allow 100–150ms buffer after button intent registers before processing — prevents mis-taps
+
+---
+
+## Navigation (Expo Router / React Navigation)
+```tsx
+// Expo Router v3+ (file-based, recommended)
+// app/(tabs)/_layout.tsx — tab navigator
+// app/[id].tsx — dynamic segment
+// app/(modal)/settings.tsx — modal group
+
+// Stack navigation with gesture
+import { Stack } from 'expo-router';
+<Stack screenOptions={{ headerShown: false, animation: 'slide_from_right' }}>
+  <Stack.Screen name="(tabs)" />
+  <Stack.Screen name="[id]" options={{ presentation: 'modal' }} />
+</Stack>
+
+// Deep linking (Expo Router handles automatically via app.json scheme)
+// ❌ TRAP: Don't use react-navigation Link for deep links in Expo Router — use expo-router Link
+import { Link, useRouter } from 'expo-router';
+const router = useRouter();
+router.push('/user/42');
+```
+
+---
+
+## On-Device AI UX Patterns
+- **Zero-wait illusion**: When model runs → immediately show contextual skeleton/partial tokens
+- **Progressive disclosure**: Low confidence → softer UI, soft colors, require confirmation
+- **Streaming UI**: `useEffect` + SSE or `StreamingText` component appending tokens
+- **Local models** (MediaPipe, Core ML, ONNX): always wrap in try/catch — device capability varies
+
+---
+
+## Color & Typography
+```tsx
+// OLED-safe dark mode
+const colors = {
+  background: '#000000',    // true black — OLED pixel off
+  surface: '#0A0A0A',       // cards
+  surfaceAlt: '#121212',    // elevated surfaces
+  border: '#1F1F1F',
+  text: '#FFFFFF',
+  textMuted: '#8E8E93',     // iOS system gray
+};
+// Dynamic type (iOS) — always use system font with scalesWithContentSizeCategory
+import { Text } from 'react-native';
+<Text style={{ fontSize: 16, fontFamily: Platform.OS === 'ios' ? 'System' : 'Roboto' }}>
+```
+
+---
+
+## Performance Checklist
+| Issue | Fix |
+|-------|-----|
+| JS thread jank | Move ALL animations to Reanimated worklets |
+| Slow list | Replace ScrollView/FlatList with FlashList |
+| Image flicker | `Image` from `expo-image` (faster cache, blurhash) |
+| Re-render cascade | `React.memo` + stable callbacks + Zustand selectors |
+| Large bundle | Dynamic imports + Metro tree shaking |
+| Memory leak | `useEffect` cleanup + cancel animation on unmount |
+
+```tsx
+// Cancel animation on unmount
+useEffect(() => {
+  opacity.value = withTiming(1);
+  return () => cancelAnimation(opacity); // ← critical
+}, []);
+```
+
+---
+
+## iOS-Specific
+- **BlurView**: Use `@react-native-community/blur` for frosted glass nav bars/modals
+- **SF Symbols**: Use `@expo/vector-icons/Ionicons` for system-native icons
+- **Haptics**: `expo-haptics` — rich feedback on iOS, limited on Android
+- **Dynamic Island**: Check `insets.top > 50` for Dynamic Island devices
+- **Sheet presentations**: `presentation: 'formSheet'` in Expo Router for iOS bottom sheet native feel
+
+## Android-Specific
+- **Material You**: Use `react-native-paper` for M3 dynamic color theming
+- **Edge-to-edge**: Set `android:windowLayoutInDisplayCutoutMode="shortEdges"` in AndroidManifest
+- **Back gesture prediction**: Wrap routes in `GestureHandlerRootView` at root
+- **Splash**: Use `expo-splash-screen` — never hardcode a delay
 
 
 ---
@@ -252,4 +252,12 @@ Review these questions before confirming output:
 
 **CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
 - ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
-- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing tests, compile success, or equivalent proof) that your output works as intended.
+
+
+## Pre-Flight Checklist
+- [ ] Have I reviewed the user's specific constraints and requests?
+- [ ] Have I checked the environment for relevant existing implementations?
+
+## VBC Protocol (Verification-Before-Completion)
+You MUST verify existing code signatures and variables before attempting to modify or call them. No hallucination is permitted.