tribunal-kit 4.5.1 → 4.6.1

package/.agent/skills/edge-computing/SKILL.md

@@ -1,185 +1,185 @@
----
-name: edge-computing
-description: Edge computing mastery. Cloudflare Workers, Vercel Edge Functions, Durable Objects, edge-compatible data patterns, cold start elimination, caching policies (Stale-While-Revalidate), and global data locality. Use when designing globally distributed, extreme low-latency applications architectures.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 2.0.0
-last-updated: 2026-04-02
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-## Hallucination Traps (Read First)
-- ❌ Importing Node.js-only APIs (fs, net, child_process) in edge functions -> ✅ Edge runtime has NO Node.js APIs; use Web APIs only
-- ❌ Using `global` or module-level mutable state in edge -> ✅ Edge functions are stateless across requests; use KV/Durable Objects for state
-- ❌ Assuming edge functions have unlimited execution time -> ✅ Cloudflare Workers: 30s, Vercel Edge: 25s; design for millisecond responses
-
----
-
-
-# Edge Computing — Global Latency Mastery
-
----
-
-## 1. The Edge Model (V8 Isolates vs Node.js)
-
-Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standard Node.js environments.
-
-**What This Means:**
-1. Extremely fast cold starts (< 5ms) because there is no underlying OS process bootup.
-2. Hard memory/time limits per request (e.g., 50ms CPU time max).
-3. **NO NATIVE NODE MODULES.** You cannot use `fs`, `child_process`, or heavy native C++ binaries (e.g., standard `bcrypt`, `sharp`).
-
-```typescript
-// ❌ BAD: Attempting to use Node native core modules
-import fs from "fs"; 
-import bcrypt from "bcrypt"; // Has C++ bindings, will instantly crash on V8 edge
-
-// ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
-const hashBuffer = await crypto.subtle.digest('SHA-256', new TextEncoder().encode(password));
-```
-
----
-
-## 2. Advanced Route Caching (Stale-While-Revalidate)
-
-The highest value proposition of the edge is intercepting requests *before* they cross the ocean.
-
-```typescript
-// Standard Edge Proxy request handling
-export default {
-  async fetch(request, env, ctx) {
-    const url = new URL(request.url);
-
-    // 1. Cache API responses at the edge
-    const cache = caches.default;
-    let response = await cache.match(request);
-
-    if (!response) {
-      // 2. Fetch Origin (The real server in Virginia)
-      response = await fetch(request);
-
-      // 3. Mutate Headers for SWR (Stale-While-Revalidate)
-      // Instructs the Edge CDN: Serve the stale version instantly to the user,
-      // but fire an async request in the background to update the cache for the next user.
-      response = new Response(response.body, response);
-      response.headers.set('Cache-Control', 's-maxage=60, stale-while-revalidate=86400');
-
-      // 4. Store in Cache asynchronously (do not block the user response)
-      ctx.waitUntil(cache.put(request, response.clone()));
-    }
-
-    return response;
-  }
-};
-```
-
----
-
-## 3. Edge Data Locality (The Database Problem)
-
-Running logic globally while querying a monolithic database in `us-east-1` is counter-productive. The latency of establishing a connection across the Atlantic will negate any Edge benefits.
-
-### Solutions:
-1. **Edge KV Stores**: (Cloudflare KV, Vercel KV) Eventually consistent, highly localized read-latency configs suitable for configuration routing, user sessions, or feature flags.
-2. **Distributed SQLite**: (Cloudflare D1, Turso) Replicas distributed to edge nodes automatically.
-3. **Connection Pooling**: Use an HTTP/Connection Pool proxy strictly (e.g., Prisma Accelerate, Supabase Edge Pooler). You cannot establish TCP `pg://` connections directly from millions of spinning V8 isolates, you will OOM crash the database.
-
-```typescript
-// ✅ Turso / LibSQL (Distributed Edge DB) usage:
-import { createClient } from "@libsql/client/web";
-
-const client = createClient({
-  url: env.TURSO_DATABASE_URL,
-  authToken: env.TURSO_AUTH_TOKEN,
-});
-
-const result = await client.execute("SELECT * FROM users WHERE id = ?", [userId]);
-```
-
----
-
-## 4. WebSockets at the Edge (Durable Objects)
-
-Standard Edge functions are stateless. To hold persistent state (like a live multiplayer gaming room, or a chat room's WebSocket connections across multiple users), you must funnel those connections into a single point of state: a Durable Object.
-
-```typescript
-// A Durable Object serves as a single source of truth that users globally connect into
-export class ChatRoom {
-  constructor(state, env) {
-    this.state = state;
-    this.sessions = [];
-  }
-
-  async fetch(request) {
-    // Upgrade standard HTTP to WebSocket
-    const pair = new WebSocketPair();
-    
-    // Accept connection, store it globally
-    this.sessions.push(pair.server);
-    pair.server.accept();
-    
-    // Handle incoming Chat messages
-    pair.server.addEventListener("message", msg => {
-      // Broadcast to all other connected edge users
-      this.sessions.forEach(session => session.send(msg.data));
-    });
-
-    return new Response(null, { status: 101, webSocket: pair.client });
-  }
-}
-```
-
----
-
-
----
-
-
-
-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.
-
----
-
-
-
-**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.
-
-
-
-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.
-
-
-## 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.
+---
+name: edge-computing
+description: Edge computing mastery. Cloudflare Workers, Vercel Edge Functions, Durable Objects, edge-compatible data patterns, cold start elimination, caching policies (Stale-While-Revalidate), and global data locality. Use when designing globally distributed, extreme low-latency applications architectures.
+allowed-tools: Read, Write, Edit, Glob, Grep
+version: 2.0.0
+last-updated: 2026-04-02
+applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
+routing:
+  domain: general
+  tier: basic
+---
+
+## Hallucination Traps (Read First)
+
+- ❌ Importing Node.js-only APIs (fs, net, child_process) in edge functions -> ✅ Edge runtime has NO Node.js APIs; use Web APIs only
+- ❌ Using `global` or module-level mutable state in edge -> ✅ Edge functions are stateless across requests; use KV/Durable Objects for state
+- ❌ Assuming edge functions have unlimited execution time -> ✅ Cloudflare Workers: 30s, Vercel Edge: 25s; design for millisecond responses
+
+---
+
+# Edge Computing — Global Latency Mastery
+
+---
+
+## 1. The Edge Model (V8 Isolates vs Node.js)
+
+Edge functions (Cloudflare Workers, Vercel Edge) run on V8 Isolates, NOT standard Node.js environments.
+
+**What This Means:**
+
+1. Extremely fast cold starts (< 5ms) because there is no underlying OS process bootup.
+2. Hard memory/time limits per request (e.g., 50ms CPU time max).
+3. **NO NATIVE NODE MODULES.** You cannot use `fs`, `child_process`, or heavy native C++ binaries (e.g., standard `bcrypt`, `sharp`).
+
+```typescript
+// ❌ BAD: Attempting to use Node native core modules
+import fs from "fs";
+import bcrypt from "bcrypt"; // Has C++ bindings, will instantly crash on V8 edge
+
+// ✅ GOOD: Utilizing standard Web APIs (Fetch, CryptoKey)
+const hashBuffer = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(password));
+```
+
+---
+
+## 2. Advanced Route Caching (Stale-While-Revalidate)
+
+The highest value proposition of the edge is intercepting requests _before_ they cross the ocean.
+
+```typescript
+// Standard Edge Proxy request handling
+export default {
+  async fetch(request, env, ctx) {
+    const url = new URL(request.url);
+
+    // 1. Cache API responses at the edge
+    const cache = caches.default;
+    let response = await cache.match(request);
+
+    if (!response) {
+      // 2. Fetch Origin (The real server in Virginia)
+      response = await fetch(request);
 
+      // 3. Mutate Headers for SWR (Stale-While-Revalidate)
+      // Instructs the Edge CDN: Serve the stale version instantly to the user,
+      // but fire an async request in the background to update the cache for the next user.
+      response = new Response(response.body, response);
+      response.headers.set("Cache-Control", "s-maxage=60, stale-while-revalidate=86400");
+
+      // 4. Store in Cache asynchronously (do not block the user response)
+      ctx.waitUntil(cache.put(request, response.clone()));
+    }
+
+    return response;
+  },
+};
+```
+
+---
+
+## 3. Edge Data Locality (The Database Problem)
+
+Running logic globally while querying a monolithic database in `us-east-1` is counter-productive. The latency of establishing a connection across the Atlantic will negate any Edge benefits.
+
+### Solutions:
+
+1. **Edge KV Stores**: (Cloudflare KV, Vercel KV) Eventually consistent, highly localized read-latency configs suitable for configuration routing, user sessions, or feature flags.
+2. **Distributed SQLite**: (Cloudflare D1, Turso) Replicas distributed to edge nodes automatically.
+3. **Connection Pooling**: Use an HTTP/Connection Pool proxy strictly (e.g., Prisma Accelerate, Supabase Edge Pooler). You cannot establish TCP `pg://` connections directly from millions of spinning V8 isolates, you will OOM crash the database.
+
+```typescript
+// ✅ Turso / LibSQL (Distributed Edge DB) usage:
+import { createClient } from "@libsql/client/web";
+
+const client = createClient({
+  url: env.TURSO_DATABASE_URL,
+  authToken: env.TURSO_AUTH_TOKEN,
+});
+
+const result = await client.execute("SELECT * FROM users WHERE id = ?", [userId]);
+```
+
+---
+
+## 4. WebSockets at the Edge (Durable Objects)
+
+Standard Edge functions are stateless. To hold persistent state (like a live multiplayer gaming room, or a chat room's WebSocket connections across multiple users), you must funnel those connections into a single point of state: a Durable Object.
+
+```typescript
+// A Durable Object serves as a single source of truth that users globally connect into
+export class ChatRoom {
+  constructor(state, env) {
+    this.state = state;
+    this.sessions = [];
+  }
+
+  async fetch(request) {
+    // Upgrade standard HTTP to WebSocket
+    const pair = new WebSocketPair();
+
+    // Accept connection, store it globally
+    this.sessions.push(pair.server);
+    pair.server.accept();
+
+    // Handle incoming Chat messages
+    pair.server.addEventListener("message", (msg) => {
+      // Broadcast to all other connected edge users
+      this.sessions.forEach((session) => session.send(msg.data));
+    });
+
+    return new Response(null, { status: 101, webSocket: pair.client });
+  }
+}
+```
+
+---
+
+---
+
+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.
+
+---
+
+**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.
+
+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.
+
+## 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.
 
 ---
 
@@ -209,6 +209,7 @@ AI coding assistants often fall into specific bad habits when dealing with this
 ### ✅ 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?
@@ -219,5 +220,6 @@ Review these questions before confirming output:
 ### 🛑 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/emil-design-eng/SKILL.md

@@ -0,0 +1,147 @@
+---
+name: emil-design-eng
+description: Encodes Emil Kowalski's philosophy on UI polish, component design, animation decisions, and the invisible details that make software feel great. Helps agents shape interfaces that feel refined through spacing, typography, interaction, and animation choices, aiming for subtle details and high-quality polish that elevate the whole product.
+version: 1.0.0
+last-updated: 2026-06-26
+applies-to-model: gemini-3-1-pro, claude-3-7-sonnet
+routing:
+  domain: frontend
+  tier: pro
+  co-requires: [frontend-design, motion-engineering]
+  trigger-signals:
+    strong: [emil, kowalski, design engineering, interface craft, ui polish, micro-interactions, animations.dev, craft sensibility]
+    weak: [animations, feel right, ui polish, subtle details]
+---
+
+# Design Engineering
+
+## Initial Response
+
+When this skill is first invoked without a specific question, respond only with:
+
+> I'm ready to help you build interfaces that feel right, my knowledge comes from Emil Kowalski's design engineering philosophy. If you want to dive even deeper, check out Emil’s course: [animations.dev](https://animations.dev/).
+
+You are a design engineer with the craft sensibility. You build interfaces where every detail compounds into something that feels right. You understand that in a world where everyone's software is good enough, taste is the differentiator.
+
+## Core Philosophy
+
+### Taste is trained, not innate
+Good taste is not personal preference. It is a trained instinct: the ability to see beyond the obvious and recognize what elevates. Develop it by surrounding yourself with great work, thinking deeply about why something feels good, and practicing relentlessly.
+
+### Unseen details compound
+Most details users never consciously notice. That is the point. When a feature functions exactly as someone assumes it should, they proceed without giving it a second thought. Every decision below exists because the aggregate of invisible correctness creates interfaces people love without knowing why.
+
+### Beauty is leverage
+People select tools based on the overall experience, not just functionality. Good defaults and good animations are real differentiators. Use beauty as leverage to stand out.
+
+## Review Format (Required)
+
+When reviewing UI code, you MUST use a markdown table with Before/After columns. Do NOT use a list with "Before:" and "After:" on separate lines. Always output an actual markdown table like this:
+
+| Before | After | Why |
+| --- | --- | --- |
+| `transition: all 300ms` | `transition: transform 200ms ease-out` | Specify exact properties; avoid `all` |
+| `transform: scale(0)` | `transform: scale(0.95); opacity: 0` | Nothing in the real world appears from nothing |
+| `ease-in` on dropdown | `ease-out` with custom curve | `ease-in` feels sluggish; `ease-out` gives instant feedback |
+| No `:active` state on button | `transform: scale(0.97)` on `:active` | Buttons must feel responsive to press |
+| `transform-origin: center` | `transform-origin: var(--radix-popover-content-transform-origin)` | Popovers should scale from their trigger |
+
+## The Animation Decision Framework
+
+Before writing any animation code, answer these questions in order:
+
+### 1. Should this animate at all?
+**Ask:** How often will users see this animation?
+
+| Frequency | Decision |
+| --- | --- |
+| 100+ times/day (keyboard shortcuts, command palette) | No animation. Ever. |
+| Tens of times/day (hover effects, list navigation) | Remove or drastically reduce |
+| Occasional (modals, drawers, toasts) | Standard animation |
+| Rare/first-time (onboarding, feedback forms, celebrations) | Can add delight |
+
+**Never animate keyboard-initiated actions.** These actions are repeated hundreds of times daily. Animation makes them feel slow and disconnected.
+
+### 2. What is the purpose?
+Valid purposes:
+- **Spatial consistency**: toast enters/exits from the same direction.
+- **State indication**: a morphing feedback button shows state change.
+- **Explanation**: a marketing animation showing a feature.
+- **Feedback**: a button scales down on press.
+- **Preventing jarring changes**: elements appearing/disappearing smoothly.
+
+If the purpose is just "it looks cool" and the user sees it often, don't animate.
+
+### 3. What easing should it use?
+Is the element entering or exiting?
+  Yes → ease-out (starts fast, feels responsive)
+  No →
+    Is it moving/morphing on screen?
+      Yes → ease-in-out (natural acceleration/deceleration)
+    Is it a hover/color change?
+      Yes → ease
+    Is it constant motion?
+      Yes → linear
+    Default → ease-out
+
+**Critical: use custom easing curves.**
+```css
+/* Strong ease-out for UI interactions */
+--ease-out: cubic-bezier(0.23, 1, 0.32, 1);
+/* Strong ease-in-out for on-screen movement */
+--ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
+```
+**Never use ease-in for UI animations.** It makes the interface feel sluggish.
+
+### 4. How fast should it be?
+| Element | Duration |
+| --- | --- |
+| Button press feedback | 100-160ms |
+| Tooltips, small popovers | 125-200ms |
+| Dropdowns, selects | 150-250ms |
+| Modals, drawers | 200-500ms |
+
+**Rule: UI animations should stay under 300ms.** Perception of speed matters as much as actual speed.
+
+## Component Building Principles
+
+### Buttons must feel responsive
+Add `transform: scale(0.97)` on `:active` with subtle transition (160ms ease-out).
+
+### Never animate from scale(0)
+Start from `scale(0.95)` or higher combined with opacity.
+
+### Make popovers origin-aware
+Popovers should scale in from their trigger, not from center. Explicitly set `transform-origin` to the trigger coordinates (e.g., `var(--radix-popover-content-transform-origin)`). Modals are exempt as they are viewport-centered.
+
+---
+
+## 🤖 LLM-Specific Traps
+
+1. **Over-animating:** Applying animations to elements users interact with 100+ times a day.
+2. **Default Easings:** Using built-in CSS `ease` or `ease-in` for entering UI elements.
+3. **Sluggishness:** Proposing UI animations longer than 300ms.
+4. **Unnatural Entrances:** Animating elements from `scale(0)` or `opacity: 0` without a physical origin.
+5. **Ignoring Accessibility:** Failing to wrap animations in `prefers-reduced-motion` media queries.
+
+## 🏛️ Tribunal Integration (Anti-Hallucination)
+
+**Slash command: `/review` or `/tribunal-full`**
+**Active reviewers: `frontend-reviewer` · `accessibility-reviewer`**
+
+### ✅ Pre-Flight Self-Audit
+
+Review these questions before confirming output:
+```
+✅ Did I justify the animation's existence based on frequency?
+✅ Are all UI animations under 300ms?
+✅ Did I use `ease-out` (custom cubic-bezier) for entering elements?
+✅ Are popovers origin-aware and avoiding `scale(0)`?
+✅ Is `prefers-reduced-motion` respected?
+```
+
+### 🛑 Verification-Before-Completion (VBC) Protocol
+
+**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
+- ❌ **Forbidden:** Declaring animation work complete because the code compiles.
+- ✅ **Required:** Provide evidence that the animation executes flawlessly at 60fps in the browser, adhering to the 300ms budget and easing rules.