tribunal-kit 4.0.0 → 4.2.0

package/.agent/skills/whimsy-injector/SKILL.md

@@ -273,3 +273,45 @@ Every file with animations MUST include:
 - **Verify `will-change` usage** — only apply to actively animating elements, remove after animation completes.
 
 ---
+
+
+---
+
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ Forbidden AI Tropes
+
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**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.

package/.agent/skills/workflow-optimizer/SKILL.md

@@ -177,3 +177,45 @@ Before analyzing, check for these common quick wins:
 - **Acknowledge uncertainty**: "Cannot determine if calls 3-5 had data dependency — may be correctly sequential."
 
 ---
+
+
+---
+
+## 🤖 LLM-Specific Traps
+
+AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+
+1. **Over-engineering:** Proposing complex abstractions or distributed systems when a simpler approach suffices.
+2. **Hallucinated Libraries/Methods:** Using non-existent methods or packages. Always `// VERIFY` or check `package.json` / `requirements.txt`.
+3. **Skipping Edge Cases:** Writing the "happy path" and ignoring error handling, timeouts, or data validation.
+4. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+5. **Silent Degradation:** Catching and suppressing errors without logging or re-raising.
+
+---
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `logic-reviewer` · `security-auditor`**
+
+### ❌ Forbidden AI Tropes
+
+1. **Blind Assumptions:** Never make an assumption without documenting it clearly with `// VERIFY: [reason]`.
+2. **Silent Degradation:** Catching and suppressing errors without logging or handling.
+3. **Context Amnesia:** Forgetting the user's constraints and offering generic advice instead of tailored solutions.
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I rely ONLY on real, verified tools and methods?
+✅ Is this solution appropriately scoped to the user's constraints?
+✅ Did I handle potential failure modes and edge cases?
+✅ Have I avoided generic boilerplate that doesn't add value?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**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.

package/.agent/workflows/tribunal-backend.md

@@ -1,5 +1,5 @@
 ---
-description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Type Safety reviewers. Use for API routes, server logic, auth code, middleware, Server Actions, and any server-side business logic.
+description: Backend-specific Tribunal. Runs Logic + Security + Dependency + Type Safety + Resilience + Schema reviewers. Use for API routes, server logic, auth code, middleware, Server Actions, and any server-side business logic.
 ---
 
 # /tribunal-backend — Backend Code Audit
@@ -20,7 +20,7 @@ $ARGUMENTS
 
 ---
 
-## 4 Active Reviewers (All Run Simultaneously)
+## 6 Active Reviewers (All Run Simultaneously)
 
 ### precedence-reviewer    → Checks local repo Case Law for past rejections
 logic-reviewer
@@ -50,6 +50,17 @@ logic-reviewer
 - Unsafe type assertions (`as User` without runtime check)
 - Return type mismatches
 
+### schema-reviewer
+- Missing input validation on req.body/req.query
+- Validation applied client-side only
+- Loosely defined Zod/Pydantic schemas
+
+### resilience-reviewer
+- Swallowed errors (empty catch blocks)
+- Missing timeouts on network fetches
+- Unhandled Promise rejections
+- Missing retries for temporal network failures
+
 ---
 
 ## Verdict System

package/.agent/workflows/tribunal-full.md

@@ -1,8 +1,8 @@
 ---
-description: Run ALL 11 Tribunal reviewer agents simultaneously. Maximum hallucination coverage. Use before merging any AI-generated code, before production deployments, or when maximum confidence is required.
+description: Run ALL 16 Tribunal reviewer agents simultaneously. Maximum hallucination coverage. Use before merging any AI-generated code, before production deployments, or when maximum confidence is required.
 ---
 
-# /tribunal-full — Complete 11-Reviewer Audit
+# /tribunal-full — Complete 16-Reviewer Audit
 
 $ARGUMENTS
 
@@ -20,17 +20,19 @@ $ARGUMENTS
 
 ---
 
-## 11 Reviewers — All Active Simultaneously
+## 16 Reviewers — All Active Simultaneously
 
 ```
 Tier 1: Always active (universal concerns)
 ├── precedence-reviewer    → Checks local repo Case Law for past rejections
 ├── logic-reviewer         → Hallucinated methods, impossible logic, undefined refs
-└── security-auditor       → OWASP 2025, injection, JWT, SSRF, IDOR
+├── security-auditor       → OWASP 2025, injection, JWT, SSRF, IDOR
+└── resilience-reviewer    → Swallowed errors, unhandled rejections, missing retries
 
 Tier 2: Code quality
 ├── dependency-reviewer    → Fabricated packages, supply chain, version compatibility
 ├── type-safety-reviewer   → 'any' epidemic, Zod parse vs cast, unguarded access
+├── schema-reviewer        → Missing input validation, loose schemas, raw req.body
 └── sql-reviewer           → Injection, N+1, missing indexes, unscoped mutations
 
 Tier 3: Domain-specific
@@ -40,6 +42,11 @@ Tier 3: Domain-specific
 ├── ai-code-reviewer       → Model name hallucinations, prompt injection, cost explosion
 ├── test-coverage-reviewer → Happy path only, brittle selectors, missing edge cases
 └── accessibility-reviewer → WCAG 2.2 AA, ARIA misuse, focus management, live regions
+
+Tier 4: Performance Swarm (token-scoped specialists)
+├── vitals-reviewer        → Frontend CWV depth: Suspense waterfalls, paint jank, animation leaks
+├── db-latency-auditor     → DB layer: N+1, unbounded queries, unindexed WHERE, pool config
+└── throughput-optimizer   → Server runtime: event-loop blocks, serialized awaits, memory leaks
 ```
 
 ---
@@ -50,9 +57,9 @@ Not all 11 reviewers produce meaningful findings on all code types. Active revie
 
 |Code Under Review|Critical Reviewers|
 |:---|:---|
-|REST API route|logic, security, dependency, type-safety, sql|
-|React component|logic, frontend, accessibility, type-safety|
-|Database query|logic, security, sql|
+|REST API route|logic, security, dependency, type-safety, sql, schema, resilience|
+|React component|logic, frontend, accessibility, type-safety, resilience|
+|Database query|logic, security, sql, resilience|
 |AI LLM integration|logic, security, ai-code, dependency|
 |Test file|test-coverage, logic|
 |React Native / Expo|mobile, logic, security, performance|
@@ -64,7 +71,7 @@ Not all 11 reviewers produce meaningful findings on all code types. Active revie
 ## Verdict Aggregation
 
 ```
-All 11 verdicts are collected. Aggregated result:
+All 16 verdicts are collected. Aggregated result:
 
 If ANY reviewer = ❌ REJECTED → Global verdict: ❌ REJECTED (must fix before Human Gate)
 If any reviewer = ⚠️ WARNING  → Global verdict: ⚠️ WARNINGS (proceed with attention)

package/.agent/workflows/tribunal-speed.md

@@ -0,0 +1,183 @@
+---
+description: Full-stack parallel performance audit. Runs 3 scoped specialists simultaneously — vitals-reviewer (Frontend CWV), db-latency-auditor (SQL/ORM), throughput-optimizer (Node.js server) — then synthesizes a single ranked report. Maximum 5 AI calls regardless of project size. Use when full-stack performance profiling is needed.
+---
+
+# /tribunal-speed — Full-Stack Performance Swarm
+
+$ARGUMENTS
+
+---
+
+## When to Use /tribunal-speed
+
+|Use `/tribunal-speed` when...|Use something else when...|
+|:---|:---|
+|Full-stack performance audit needed|Frontend only → `/tribunal-performance`|
+|Changes span UI + DB + Server layers|Single file review → `/review`|
+|Pre-deploy performance validation|Security-focused → `/tribunal-full`|
+|Investigating end-to-end latency|Architecture planning → `/plan`|
+|Need scoped specialist depth (not generic)|Quick generic check → `/tribunal-performance`|
+
+---
+
+## Architecture: 3-Phase Fan-Out (5 AI Calls Max)
+
+```
+Phase 1 — File Classification (1 call)
+│
+│  Classify all submitted files into:
+│  ├── Frontend  (.tsx, .jsx, .css, .module.css)
+│  ├── Database  (.sql, schema.prisma, files with prisma./db./drizzle(/knex()
+│  └── Server    (.ts/.js in /api, /server, /lib, /utils, /routes, /middleware)
+│
+│  Files that don't match any category → skip (not performance-relevant)
+│
+▼
+Phase 2 — Parallel Specialist Audit (3 concurrent calls)
+│
+│  ┌──────────────────────┬──────────────────────┬───────────────────────┐
+│  │  vitals-reviewer     │  db-latency-auditor  │  throughput-optimizer │
+│  │                      │                      │                      │
+│  │  Receives ONLY       │  Receives ONLY       │  Receives ONLY       │
+│  │  Frontend files      │  Database files      │  Server files        │
+│  │                      │                      │                      │
+│  │  Checks:             │  Checks:             │  Checks:             │
+│  │  - LCP blockers      │  - N+1 queries       │  - Event-loop blocks │
+│  │  - INP violations    │  - Missing LIMIT     │  - Serialized awaits │
+│  │  - CLS triggers      │  - Unindexed WHERE   │  - Memory leaks      │
+│  │  - Suspense waterfalls│  - SELECT * abuse   │  - Missing Workers   │
+│  │  - Paint jank        │  - Pool config       │  - Streaming gaps    │
+│  │  - Animation leaks   │  - Wide transactions │  - No keep-alive     │
+│  └──────────────────────┴──────────────────────┴───────────────────────┘
+│
+│  Each specialist returns findings in its verdict format.
+│  allSettled — one specialist failure does NOT block siblings.
+│
+▼
+Phase 3 — Synthesis (1 call)
+│
+│  Merges 3 specialist reports into a single ranked issue list.
+│  Priority: Critical → High → Medium → Low
+│  Each issue tagged with: [AGENT] [FILE:LINE] [IMPACT METRIC] [FIX]
+│
+▼
+Human Gate — Final report shown
+Y = acknowledge | N = discard | R = re-audit with different scope
+```
+
+**Total cost: 5 AI calls maximum** — predictable, repeatable, project-size-independent.
+
+---
+
+## Token Discipline Rules
+
+```
+Rule 1: Each specialist reads ONLY its scoped files — never the full project
+Rule 2: If a category has zero files, that specialist is skipped (saves 1 call)
+Rule 3: File contents are trimmed to relevant sections via targeted grep
+Rule 4: Synthesis call receives only verdict summaries, not full file contents
+```
+
+---
+
+## 3 Specialist Agents
+
+### vitals-reviewer (Frontend)
+- **Scope:** `.tsx`, `.jsx`, `.css`, `.module.css`
+- **Metrics:** INP, LCP, CLS, FCP
+- **Key patterns:** React 19 `use()` waterfalls, non-passive listeners, missing `content-visibility`, `useGSAP` leaks, View Transitions jank, Suspense placement
+
+### db-latency-auditor (Database)
+- **Scope:** `.sql`, `schema.prisma`, files with `prisma.`, `db.`, `drizzle(`, `knex(`
+- **Metrics:** Query count, query latency, connection overhead
+- **Key patterns:** N+1 queries, missing LIMIT, unindexed WHERE, SELECT *, no connection pooling, over-scoped transactions, mass assignment
+
+### throughput-optimizer (Server)
+- **Scope:** `.ts/.js` in `/api`, `/server`, `/lib`, `/utils`, `/routes`, `/middleware`
+- **Metrics:** RPS, p95 latency, memory usage
+- **Key patterns:** Sync `fs.*`, serialized `await` loops, global Map without TTL, no Worker Threads for CPU ops, buffer bloat, missing keep-alive
+
+---
+
+## Synthesis Output Format
+
+```
+━━━ Tribunal Speed: Full-Stack Performance Audit ━━━━━━━━━━━━━━
+
+Specialists dispatched: 3 | Completed: 3 | Skipped: 0
+
+━━━ Critical Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[CRITICAL] throughput-optimizer | api/orders.ts:47
+Pattern: SERIALIZED-AWAIT
+Issue:   await inside for-loop serializes 5 DB calls (1500ms vs 300ms parallel)
+Fix:     const results = await Promise.all(ids.map(id => fetchOrder(id)));
+Impact:  -1200ms p95 API latency
+
+[CRITICAL] db-latency-auditor | lib/users.ts:23
+Pattern: N+1
+Issue:   findMany in loop generates 101 queries for 100 users
+Fix:     Use prisma.user.findMany({ include: { posts: true } })
+Impact:  101 queries → 1 query
+
+━━━ High Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[HIGH] vitals-reviewer | components/Hero.tsx:12
+Pattern: LCP
+Issue:   Hero image without priority prop — browser discovers it late
+Fix:     Add priority={true} to next/image component
+Impact:  LCP improvement ~500ms
+
+━━━ Medium Issues ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+[MEDIUM] vitals-reviewer | app/feed/page.tsx:89
+Pattern: CLS
+Issue:   Feed items missing content-visibility: auto
+Fix:     Add content-visibility: auto; contain-intrinsic-size: auto 200px;
+Impact:  Reduced off-screen rendering cost
+
+━━━ Summary ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Total issues:  7 (2 Critical, 2 High, 3 Medium)
+AI calls used: 5
+Token budget:  Within scope (specialists read only categorized files)
+
+━━━ Human Gate ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+Acknowledged?  Y = close | R = re-audit different scope
+```
+
+---
+
+## Specialist Failure Handling
+
+```
+If a specialist fails after 3 retries:
+  → Log failure with agent name + error
+  → Continue with remaining specialists
+  → Include "[SPECIALIST FAILED]" in synthesis report
+  → Never silently skip — always visible in output
+```
+
+---
+
+## Versus Other Commands
+
+|Command|Agents|Depth|When to Use|
+|:---|:---|:---|:---|
+|`/tribunal-performance`|logic + performance-reviewer|Generic CWV check|Quick single-file perf scan|
+|`/tribunal-speed`|vitals + db-latency + throughput|Deep 3-domain parallel|Full-stack perf audit|
+|`/tribunal-full`|All 14 agents|Everything|Maximum coverage (security + perf + all)|
+|`/performance-benchmarker`|Lighthouse + bundle|Measurement only|Get actual scores, not code review|
+
+---
+
+## Usage Examples
+
+```
+/tribunal-speed the entire checkout flow (UI + API + DB queries)
+/tribunal-speed all files changed in this PR for performance regression
+/tribunal-speed the dashboard page end-to-end (data fetch + render + DB)
+/tribunal-speed the search feature: autocomplete UI + search API + query plan
+```
+
+---

package/bin/tribunal-kit.js

@@ -142,16 +142,16 @@ function compareSemver(a, b) {
 }
 
 /**
- * Fetch the latest version from GitHub Releases.
- * Returns the version string (e.g. '2.4.0') or null on failure.
+ * Fetch the latest version from npm registry.
+ * Returns the version string (e.g. '4.0.0') or null on failure.
  */
 function fetchLatestVersion() {
     return new Promise((resolve) => {
         const req = https.get(
-            'https://api.github.com/repos/Harmitx7/tribunal-kit/releases/latest',
+            'https://registry.npmjs.org/tribunal-kit/latest',
             {
                 headers: {
-                    'Accept': 'application/vnd.github.v3+json',
+                    'Accept': 'application/json',
                     'User-Agent': `tribunal-kit/${CURRENT_VERSION}`
                 },
                 timeout: 5000
@@ -162,8 +162,7 @@ function fetchLatestVersion() {
                 res.on('end', () => {
                     try {
                         const json = JSON.parse(data);
-                        // GitHub tags usually have a 'v' prefix (e.g., 'v2.4.0')
-                        const version = json.tag_name ? json.tag_name.replace(/^v/, '') : null;
+                        const version = json.version || null;
                         resolve(version);
                     } catch {
                         resolve(null);
@@ -207,9 +206,9 @@ async function autoUpdateCheck(originalArgs) {
     log('');
 
     try {
-        // Build the command pulling directly from GitHub
+        // Build the command pulling from npm registry
         const args = originalArgs.join(' ');
-        const cmd = `npx -y github:Harmitx7/tribunal-kit#v${latestVersion} ${args}`;
+        const cmd = `npx -y tribunal-kit@${latestVersion} ${args}`;
 
         execSync(cmd, {
             stdio: 'inherit',
@@ -422,7 +421,7 @@ function cmdInit(flags) {
             console.log(plainRow(`  Next steps:`, s => c('gray', s)));
             console.log(stepRow('/generate',      'Generate code with anti-hallucination'));
             console.log(stepRow('/review',         'Audit existing code for issues'));
-            console.log(stepRow('/tribunal-full',  'Run all 11 reviewers in parallel'));
+            console.log(stepRow('/tribunal-full',  'Run all 14 reviewers in parallel'));
             console.log(plainRow('', () => ''));
             console.log(`  ${c('cyan', '╚' + '═'.repeat(W) + '╝')}`);
             console.log();
@@ -581,6 +580,10 @@ function cmdCase(flags) {
         log(`  ${c('cyan', 'add'.padEnd(10))}  ${c('gray', 'Record a new Case Law rejection pattern')}`);
         log(`  ${c('cyan', 'search'.padEnd(10))}  ${c('gray', 'Search existing cases (e.g., search "query")')}`);
         log(`  ${c('cyan', 'list'.padEnd(10))}  ${c('gray', 'List all recorded case law')}`);
+        log(`  ${c('cyan', 'show'.padEnd(10))}  ${c('gray', 'Show full diff for a case (e.g., show --id 1)')}`);
+        log(`  ${c('cyan', 'stats'.padEnd(10))}  ${c('gray', 'Show case law stats by domain/verdict')}`);
+        log(`  ${c('cyan', 'export'.padEnd(10))}  ${c('gray', 'Export all cases to Markdown')}`);
+        log(`  ${c('cyan', 'overrule'.padEnd(10))}  ${c('gray', 'Overrule a past precedent (e.g., overrule --id 1)')}`);
         console.log();
         process.exit(1);
     }
@@ -668,7 +671,7 @@ function cmdHelp() {
     log(cmd('update', 'Re-install to get latest version'));
     log(cmd('status', 'Check if .agent/ is installed'));
     log(cmd('learn',  'Evolve project idioms based on git diffs'));
-    log(cmd('case',   'Manage Case Law precedents (add, search, list)'));
+    log(cmd('case',   'Manage Case Law precedents (add, search, list, show, stats, overrule)'));
     log(cmd('hook',   'Install pre-push git hook for auto-learning'));
     console.log();
     log(bold('  Options'));
@@ -694,6 +697,10 @@ function cmdHelp() {
     log(ex('npx tribunal-kit case add'));
     log(ex('npx tribunal-kit case search "useEffect"'));
     log(ex('npx tribunal-kit case list'));
+    log(ex('npx tribunal-kit case show --id 1'));
+    log(ex('npx tribunal-kit case stats'));
+    log(ex('npx tribunal-kit case export'));
+    log(ex('npx tribunal-kit case overrule --id 1'));
     log(ex('npx tribunal-kit hook'));
     console.log();
 }

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "tribunal-kit",
-    "version": "4.0.0",
-    "description": "Anti-Hallucination AI Agent Kit — 34 specialist agents, 26 slash commands, Swarm/Supervisor engine, and Supreme Court Tribunal review pipeline.",
+    "version": "4.2.0",
+    "description": "Anti-Hallucination AI Agent Kit — 37 specialist agents, 31 slash commands, Performance Swarm engine, and Supreme Court Tribunal review pipeline.",
     "keywords": [
         "ai",
         "ai-agent",
@@ -70,5 +70,8 @@
         "collectCoverageFrom": [
             "bin/**/*.js"
         ]
+    },
+    "dependencies": {
+        "tribunal-kit": "^4.0.0"
     }
 }

package/.agent/skills/gsap-expert/SKILL.md

@@ -1,194 +0,0 @@
----
-name: gsap-expert
-description: GreenSock Animation Platform (GSAP 3.12+) mastery. Core tweens, timelines, ScrollTrigger, ScrollSmoother, plugins, React useGSAP hook, responsive animations, performance. Use when building scroll-driven animations, complex sequencing, SVG morphing, or any animation beyond CSS capabilities.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 3.2.0
-last-updated: 2026-04-07
-applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
----
-
-# GSAP Expert — 3.12+ Dense Reference
-
-## Hallucination Traps (Read First)
-- ❌ `gsap.registerPlugin(ScrollTrigger)` optional → ✅ **REQUIRED** before any use — must call before component mounts
-- ❌ `easeInOut`, `Power2.easeOut` (GSAP 2 syntax) → ✅ `"power2.inOut"` (string, GSAP 3)
-- ❌ `raw useEffect` for GSAP in React → ✅ `useGSAP` from `@gsap/react` — handles cleanup automatically
-- ❌ Timeline position as 2nd arg → ✅ position is the **3rd** arg: `tl.to(el, { x: 100 }, "<")`
-- ❌ `markers: true` in production → ✅ Debug only — never ship. `gsap.config({ markers: false })`
-- ❌ Animate `width`, `height`, `top`, `left` → ✅ Only `x`, `y`, `scale`, `rotation`, `opacity` (GPU composited)
-- ❌ 1 ScrollTrigger per list item → ✅ Use `ScrollTrigger.batch()` for lists — 1 battery per N items
-- ❌ `dependencies` option spelled `deps` → ✅ option is `dependencies` (not `deps`)
-- ❌ GSAP in Next.js Server Components → ✅ Always `"use client"` — GSAP is browser-only
-
----
-
-## Core Tweens
-
-```javascript
-gsap.to(".box", { x: 100, opacity: 1, duration: 1, ease: "power2.out" });
-gsap.from(".box", { y: -50, opacity: 0, duration: 0.8 });
-gsap.fromTo(".box", { x: -100 }, { x: 0, duration: 1, ease: "expo.out" });
-gsap.set(".box", { transformOrigin: "center center", willChange: "transform" });
-
-// Stagger (multiple elements)
-gsap.from(".item", { opacity: 0, y: 30, stagger: 0.08, ease: "power3.out" });
-gsap.from(".item", { opacity: 0, stagger: { each: 0.1, from: "center", grid: "auto" } });
-```
-
----
-
-## Timelines
-
-```javascript
-const tl = gsap.timeline({ defaults: { ease: "power2.out", duration: 0.6 } });
-
-tl.from(".hero-title", { y: 60, opacity: 0 })
-  .from(".hero-sub",   { y: 40, opacity: 0 }, "-=0.4")   // overlap 0.4s
-  .from(".hero-cta",   { scale: 0.9, opacity: 0 }, "<0.1") // 0.1s after prev starts
-  .to(".hero-img",     { x: 0, opacity: 1 }, 0.3);        // absolute 0.3s into tl
-
-// Position symbols:
-// "<"      → same start time as previous tween
-// ">"      → after previous ends
-// "-=0.5"  → 0.5s before previous ends (overlap)
-// "+=0.5"  → 0.5s after previous ends (gap)
-// "2"      → absolute 2s from timeline start
-
-// Runtime control
-tl.play(); tl.pause(); tl.reverse(); tl.seek(1.5); tl.timeScale(2); // 2x speed
-```
-
----
-
-## ScrollTrigger
-
-```javascript
-import { gsap } from "gsap";
-import { ScrollTrigger } from "gsap/ScrollTrigger";
-gsap.registerPlugin(ScrollTrigger); // REQUIRED — call once at module level
-
-// Basic scroll-triggered animation
-gsap.from(".section", {
-  scrollTrigger: {
-    trigger: ".section",
-    start: "top 80%",   // "triggerEdge viewportEdge"
-    end: "bottom 20%",
-    scrub: 1,           // smooth scrubbing (seconds to catch up) | true = instant
-    pin: true,          // pin element during scroll
-    anticipatePin: 1,   // prevents jump on pin
-    markers: false,     // NEVER true in production
-  },
-  y: 100, opacity: 0,
-});
-
-// Batch — for lists (1 ST instance per group, not per item)
-ScrollTrigger.batch(".card", {
-  onEnter: (elements) => gsap.from(elements, { opacity: 0, y: 40, stagger: 0.08 }),
-  start: "top 85%",
-});
-
-// Pin + scrub storytelling
-const tl = gsap.timeline({
-  scrollTrigger: { trigger: ".scene", pin: true, scrub: true, end: "+=3000" }
-});
-tl.from(".layer-1", { x: -200 }).from(".layer-2", { x: 200 }, "<");
-
-// Cleanup — MANDATORY on SPA route unmount
-ScrollTrigger.killAll(); // in component cleanup / router onChange
-```
-
----
-
-## React Integration (`useGSAP`)
-
-```tsx
-import { useGSAP } from "@gsap/react";
-import { gsap } from "gsap";
-import { ScrollTrigger } from "gsap/ScrollTrigger";
-import { useRef } from "react";
-
-gsap.registerPlugin(ScrollTrigger); // once, outside component
-
-export function HeroSection() {
-  const container = useRef<HTMLDivElement>(null);
-
-  useGSAP(() => {
-    // ✅ All GSAP code here is automatically scoped & cleaned up
-    gsap.from(".hero-title", { y: 60, opacity: 0, duration: 0.8 });
-
-    gsap.from(".hero-card", {
-      scrollTrigger: { trigger: ".hero-card", start: "top 80%" },
-      y: 40, opacity: 0, stagger: 0.1,
-    });
-  }, { scope: container, dependencies: [] }); // re-runs when dependencies change
-
-  return <div ref={container}><h1 className="hero-title">...</h1></div>;
-}
-
-// With cleanup for dynamic content:
-useGSAP(() => {
-  const ctx = gsap.context(() => {
-    gsap.from(".item", { opacity: 0, stagger: 0.05 });
-  }, container);
-  return () => ctx.revert(); // explicit cleanup if needed beyond useGSAP scope
-}, { scope: container, dependencies: [items] });
-```
-
----
-
-## Responsive Animations (`gsap.matchMedia`)
-
-```javascript
-// Replaces window.matchMedia listeners + resize handlers
-const mm = gsap.matchMedia();
-
-mm.add("(min-width: 768px)", () => {
-  gsap.to(".sidebar", { x: 0, duration: 0.5 });
-  // Return cleanup function
-  return () => gsap.set(".sidebar", { x: -300 });
-});
-
-mm.add("(max-width: 767px)", () => {
-  gsap.to(".mobile-menu", { y: 0, duration: 0.4 });
-});
-
-// In React — use inside useGSAP
-useGSAP(() => {
-  const mm = gsap.matchMedia();
-  mm.add("(prefers-reduced-motion: no-preference)", () => {
-    gsap.from(".hero", { y: 100, duration: 1 });
-  });
-  mm.add("(prefers-reduced-motion: reduce)", () => {
-    gsap.set(".hero", { opacity: 1 }); // instant, no animation
-  });
-});
-```
-
----
-
-## Plugin Reference
-
-| Plugin | Use For | Registration |
-|--------|---------|-------------|
-| `ScrollTrigger` | Scroll-driven animations | `gsap.registerPlugin(ScrollTrigger)` |
-| `ScrollSmoother` | Smooth native scroll momentum | Requires `ScrollTrigger` + Club GSAP |
-| `Flip` | Stateful layout morphing (FLIP technique) | `gsap.registerPlugin(Flip)` |
-| `Draggable` | Interactive drag/sort/resize | `gsap.registerPlugin(Draggable)` |
-| `SplitText` | Character/word/line text splits | Call `.revert()` after use to prevent SEO damage |
-| `DrawSVG` | SVG stroke-dasharray animations | Club GSAP |
-| `MorphSVG` | SVG path morphing | Club GSAP |
-| `ScrollToPlugin` | Programmatic scroll-to | `gsap.registerPlugin(ScrollToPlugin)` |
-
----
-
-## Performance Rules
-
-```
-✅ Animate: x, y, scale, rotation, skewX/Y, opacity (GPU composited transforms)
-❌ Never:   width, height, top, left, padding, margin (triggers layout/paint)
-✅ Use willChange: "transform" on elements that will animate
-✅ overwrite: "auto" to kill conflicting tweens automatically
-✅ ScrollTrigger.batch() for lists — NOT 1 instance per item
-✅ gsap.ticker.lagSmoothing(0) in high-framerate contexts (optional)
-❌ Don't animate SVG path 'd' attribute directly — use MorphSVG plugin
-```