tribunal-kit 9.2.4 → 9.2.5

package/skills/local-first/SKILL.md

@@ -1,138 +1,138 @@
----
-name: local-first
-description: "Use when Local-first software architecture mastery. CRDTs (Conflict-free Replicated Data Types), IndexedDB synchronization, sync engines (ElectricSQL, Replicache, PowerSync), offline-capable data fetching, optimistic UI, and SQLite in the browser (WASM). Use when building PWA offline capabilities, rapid UIs, or multiplayer collaborative tools."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - local-first-architecture
-  - react-specialist
-  - baseline-ui
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Local-First Architecture — Offline-capable Mastery
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## Hallucination Traps (Read First)
-
-- ❌ Assuming server data is always newer than local data -> ✅ Conflicts are inevitable; design merge strategy (LWW, CRDTs) before writing code
-- ❌ Using localStorage for anything beyond 5MB -> ✅ Use IndexedDB (via Dexie or idb) for structured local storage; localStorage is synchronous and tiny
-- ❌ Syncing entire datasets on every connection -> ✅ Use incremental sync with watermarks/timestamps to minimize bandwidth
-
----
-
----
-
-## 1. Core Principles of Local-First
-
-In a Cloud-First app (REST/GraphQL), the UI waits for the server.
-In a Local-First app, the UI talks _only_ to a local database. A background engine syncs that database to the cloud when online.
-
-1. **Fast by default**: Zero network latency because reads/writes happen locally.
-2. **Offline works flawlessly**: The app bounds to a local store (SQLite via WASM, IndexedDB).
-3. **Multi-device Sync**: Conflict resolution is handled natively (usually via CRDTs or central conflict ledgers).
-
----
-
-## 2. Sync Engines vs traditional fetching
-
-Do not use React Query / SWR to build local-first. They are HTTP caching mechanisms.
-
-```typescript
-// ❌ CLOUD-FIRST (React Query / Fetch)
-// Fails when offline. Subject to UI latency.
-const { data, isLoading } = useQuery({
-  queryKey: ['todos'],
-  queryFn: () => fetch('/api/todos').then(res => res.json()),
-});
-
-// ✅ LOCAL-FIRST (e.g. PowerSync / ElectricSQL / WatermelonDB)
-// Resolves instantly. Data lives locally. Syncs silently in background.
-import { useQuery } from '@powersync/react';
-
-const { data, isLoading } = useQuery('SELECT * FROM todos ORDER BY created_at DESC');
-
-// Writes are also local First
-const addTodo = async (text: string) => {
-  // Written to the local SQLite WASM database instantly.
-  await localDb.execute('INSERT INTO todos (id, text) VALUES (uuid(), ?)', [text]);
-  // Background worker syncs to Postgres later.
-};
-```
-
----
-
-## 3. Conflict Resolution (CRDTs)
-
-When two users edit the exact same document offline and then reconnect, how is it resolved?
-
-**Conflict-free Replicated Data Types (CRDTs)** automatically merge data without requiring a central server to decide the "winner."
-
-```typescript
-// Yjs - The leading CRDT library for collaborative text/state
-import * as Y from 'yjs';
-import { WebsocketProvider } from 'y-websocket';
-
-const ydoc = new Y.Doc();
-const provider = new WebsocketProvider('wss://sync.example.com', 'room-1', ydoc);
-
-// Shared state array
-const yarray = ydoc.getArray('todos');
-
-// Observe changes (Fires locally and when peers sync)
-yarray.observe(event => {
-  console.log('State updated natively without conflict:', yarray.toArray());
-});
-
-// Insert data (Instantly merges cleanly with remote peers)
-yarray.insert(0, ['Buy milk']);
-```
-
----
-
-## 4. In-Browser Databases
-
-Storing megabytes of relational data in `localStorage` will crash the browser.
-
-| Technology             | Use Case      | Pros                                | Cons                                          |
-| :--------------------- | :------------ | :---------------------------------- | :-------------------------------------------- |
-| **IndexedDB**          | Key-Value     | Native to browser                   | Hideous callback API, weak querying           |
-| **Dexie.js**           | Key-Value     | Wraps IndexedDB with clean Promises | Not relational                                |
-| **SQLite WASM (OPFS)** | Relational    | True SQL in browser                 | Setup complexity (Origin Private File System) |
-| **RxDB**               | NoSQL Offline | Reactive UI out-of-the-box          | Requires learning RxJS/Observables            |
-| **WatermelonDB**       | Relational    | Built for React Native & Web        | Requires native module setup on mobile        |
-
-```typescript
-// Clean IndexedDB Wrapper Example (Dexie)
-import Dexie, { type EntityTable } from 'dexie';
-
-interface Friend {
-  id: number;
-  name: string;
-  age: number;
-}
-
-const db = new Dexie('FriendsDatabase') as Dexie & {
-  friends: EntityTable<Friend, 'id'>;
-};
-
-// Schema configuration
-db.version(1).stores({
-  friends: '++id, name, age', // Primary key and indexed props
-});
-
-// Write to DB instantly
-await db.friends.add({ name: 'Alice', age: 25 });
-
-// Live query natively drives React state without network calls
-import { useLiveQuery } from 'dexie-react-hooks';
-const friends = useLiveQuery(() => db.friends.where('age').above(21).toArray());
-```
+---
+name: local-first
+description: "Use when Local-first software architecture mastery. CRDTs (Conflict-free Replicated Data Types), IndexedDB synchronization, sync engines (ElectricSQL, Replicache, PowerSync), offline-capable data fetching, optimistic UI, and SQLite in the browser (WASM). Use when building PWA offline capabilities, rapid UIs, or multiplayer collaborative tools."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - local-first-architecture
+  - react-specialist
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Local-First Architecture — Offline-capable Mastery
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## Hallucination Traps (Read First)
+
+- ❌ Assuming server data is always newer than local data -> ✅ Conflicts are inevitable; design merge strategy (LWW, CRDTs) before writing code
+- ❌ Using localStorage for anything beyond 5MB -> ✅ Use IndexedDB (via Dexie or idb) for structured local storage; localStorage is synchronous and tiny
+- ❌ Syncing entire datasets on every connection -> ✅ Use incremental sync with watermarks/timestamps to minimize bandwidth
+
+---
+
+---
+
+## 1. Core Principles of Local-First
+
+In a Cloud-First app (REST/GraphQL), the UI waits for the server.
+In a Local-First app, the UI talks _only_ to a local database. A background engine syncs that database to the cloud when online.
+
+1. **Fast by default**: Zero network latency because reads/writes happen locally.
+2. **Offline works flawlessly**: The app bounds to a local store (SQLite via WASM, IndexedDB).
+3. **Multi-device Sync**: Conflict resolution is handled natively (usually via CRDTs or central conflict ledgers).
+
+---
+
+## 2. Sync Engines vs traditional fetching
+
+Do not use React Query / SWR to build local-first. They are HTTP caching mechanisms.
+
+```typescript
+// ❌ CLOUD-FIRST (React Query / Fetch)
+// Fails when offline. Subject to UI latency.
+const { data, isLoading } = useQuery({
+  queryKey: ['todos'],
+  queryFn: () => fetch('/api/todos').then(res => res.json()),
+});
+
+// ✅ LOCAL-FIRST (e.g. PowerSync / ElectricSQL / WatermelonDB)
+// Resolves instantly. Data lives locally. Syncs silently in background.
+import { useQuery } from '@powersync/react';
+
+const { data, isLoading } = useQuery('SELECT * FROM todos ORDER BY created_at DESC');
+
+// Writes are also local First
+const addTodo = async (text: string) => {
+  // Written to the local SQLite WASM database instantly.
+  await localDb.execute('INSERT INTO todos (id, text) VALUES (uuid(), ?)', [text]);
+  // Background worker syncs to Postgres later.
+};
+```
+
+---
+
+## 3. Conflict Resolution (CRDTs)
+
+When two users edit the exact same document offline and then reconnect, how is it resolved?
+
+**Conflict-free Replicated Data Types (CRDTs)** automatically merge data without requiring a central server to decide the "winner."
+
+```typescript
+// Yjs - The leading CRDT library for collaborative text/state
+import * as Y from 'yjs';
+import { WebsocketProvider } from 'y-websocket';
+
+const ydoc = new Y.Doc();
+const provider = new WebsocketProvider('wss://sync.example.com', 'room-1', ydoc);
+
+// Shared state array
+const yarray = ydoc.getArray('todos');
+
+// Observe changes (Fires locally and when peers sync)
+yarray.observe(event => {
+  console.log('State updated natively without conflict:', yarray.toArray());
+});
+
+// Insert data (Instantly merges cleanly with remote peers)
+yarray.insert(0, ['Buy milk']);
+```
+
+---
+
+## 4. In-Browser Databases
+
+Storing megabytes of relational data in `localStorage` will crash the browser.
+
+| Technology             | Use Case      | Pros                                | Cons                                          |
+| :--------------------- | :------------ | :---------------------------------- | :-------------------------------------------- |
+| **IndexedDB**          | Key-Value     | Native to browser                   | Hideous callback API, weak querying           |
+| **Dexie.js**           | Key-Value     | Wraps IndexedDB with clean Promises | Not relational                                |
+| **SQLite WASM (OPFS)** | Relational    | True SQL in browser                 | Setup complexity (Origin Private File System) |
+| **RxDB**               | NoSQL Offline | Reactive UI out-of-the-box          | Requires learning RxJS/Observables            |
+| **WatermelonDB**       | Relational    | Built for React Native & Web        | Requires native module setup on mobile        |
+
+```typescript
+// Clean IndexedDB Wrapper Example (Dexie)
+import Dexie, { type EntityTable } from 'dexie';
+
+interface Friend {
+  id: number;
+  name: string;
+  age: number;
+}
+
+const db = new Dexie('FriendsDatabase') as Dexie & {
+  friends: EntityTable<Friend, 'id'>;
+};
+
+// Schema configuration
+db.version(1).stores({
+  friends: '++id, name, age', // Primary key and indexed props
+});
+
+// Write to DB instantly
+await db.friends.add({ name: 'Alice', age: 25 });
+
+// Live query natively drives React state without network calls
+import { useLiveQuery } from 'dexie-react-hooks';
+const friends = useLiveQuery(() => db.friends.where('age').above(21).toArray());
+```

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

@@ -1,62 +1,62 @@
----
-name: local-first-architecture
-description: "Use when Local-first architecture guidance for instant-feeling web & desktop apps, optimistic updates, IndexedDB sync engines, offline operation, and Conflict-free Replicated Data Types (CRDTs)."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - react-specialist
-  - nextjs-react-expert
-  - baseline-ui
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Local-First Architecture — Instant UI & Sync Engines
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
-## 2026 Local-First Architecture & Sync Invariants
-
-1. **OPFS (Origin Private File System) for WASM SQLite**:
-   Always prefer OPFS sync access handles for SQLite in web workers. It delivers native near-SSD read/write speeds that dwarf standard IndexedDB overhead.
-2. **Idempotency Key Protocol**:
-   Every local mutation must generate an `idempotencyKey` (UUID v7). The server stores processed keys for 24h, discarding replays during network flushes.
-3. **Delta Sync over Full Sync**:
-   Never download entire tables. Use incremental sync cursors (`last_synced_version_id`) and stream compact binary deltas via WebSockets or SSE.
-
-## Hallucination Traps (Read First)
-
-- ❌ Blocking UI render on a remote fetch in a local-first app → ✅ Render local cache immediately; reconcile in background
-- ❌ Mutating server state without an idempotency key → ✅ Flushed network retries will duplicate records
-- ❌ Putting heavy SQLite WASM operations on the browser main thread → ✅ Always run local DB queries inside a Dedicated Web Worker
-- ❌ Storing unindexed large blobs inside IndexedDB → ✅ Store blobs in OPFS; keep metadata in local SQLite/IndexedDB
-
----
-
-## 4 Pillars of Local-First Architecture
-
-### 1. Read & Write Local First
-
-- **Zero Network Latency**: UI queries (`select * from tasks`) run synchronously or near-instantaneously against in-memory or IndexedDB caches.
-- Mutations update the local cache immediately (_optimistic write_), appending a mutation log item to an outbound sync queue.
-
-### 2. Outbound Mutation Queue & Idempotency
-
-- Store mutation logs in a persistent local queue (`IndexedDB` / `SQLite`).
-- Assign every client mutation a unique UUID (`idempotencyKey`).
-- When network connection is restored, flush queue items sequentially with automatic retry on 5xx failures.
-
-### 3. Conflict Resolution (CRDTs & LWW)
-
-- **Last-Write-Wins (LWW)**: Timestamp + Client ID ordering for simple fields.
-- **CRDTs (Yjs / Automerge)**: Conflict-free Replicated Data Types for collaborative text editing and array state.
-
-### 4. Background Delta Streaming
-
-- Receive database updates via WebSockets or Server-Sent Events (SSE) as thin binary deltas (`sync_version > client_version`), applying changes to local storage without re-fetching full datasets.
+---
+name: local-first-architecture
+description: "Use when Local-first architecture guidance for instant-feeling web & desktop apps, optimistic updates, IndexedDB sync engines, offline operation, and Conflict-free Replicated Data Types (CRDTs)."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - react-specialist
+  - nextjs-react-expert
+  - baseline-ui
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Local-First Architecture — Instant UI & Sync Engines
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+## 2026 Local-First Architecture & Sync Invariants
+
+1. **OPFS (Origin Private File System) for WASM SQLite**:
+   Always prefer OPFS sync access handles for SQLite in web workers. It delivers native near-SSD read/write speeds that dwarf standard IndexedDB overhead.
+2. **Idempotency Key Protocol**:
+   Every local mutation must generate an `idempotencyKey` (UUID v7). The server stores processed keys for 24h, discarding replays during network flushes.
+3. **Delta Sync over Full Sync**:
+   Never download entire tables. Use incremental sync cursors (`last_synced_version_id`) and stream compact binary deltas via WebSockets or SSE.
+
+## Hallucination Traps (Read First)
+
+- ❌ Blocking UI render on a remote fetch in a local-first app → ✅ Render local cache immediately; reconcile in background
+- ❌ Mutating server state without an idempotency key → ✅ Flushed network retries will duplicate records
+- ❌ Putting heavy SQLite WASM operations on the browser main thread → ✅ Always run local DB queries inside a Dedicated Web Worker
+- ❌ Storing unindexed large blobs inside IndexedDB → ✅ Store blobs in OPFS; keep metadata in local SQLite/IndexedDB
+
+---
+
+## 4 Pillars of Local-First Architecture
+
+### 1. Read & Write Local First
+
+- **Zero Network Latency**: UI queries (`select * from tasks`) run synchronously or near-instantaneously against in-memory or IndexedDB caches.
+- Mutations update the local cache immediately (_optimistic write_), appending a mutation log item to an outbound sync queue.
+
+### 2. Outbound Mutation Queue & Idempotency
+
+- Store mutation logs in a persistent local queue (`IndexedDB` / `SQLite`).
+- Assign every client mutation a unique UUID (`idempotencyKey`).
+- When network connection is restored, flush queue items sequentially with automatic retry on 5xx failures.
+
+### 3. Conflict Resolution (CRDTs & LWW)
+
+- **Last-Write-Wins (LWW)**: Timestamp + Client ID ordering for simple fields.
+- **CRDTs (Yjs / Automerge)**: Conflict-free Replicated Data Types for collaborative text editing and array state.
+
+### 4. Background Delta Streaming
+
+- Receive database updates via WebSockets or Server-Sent Events (SSE) as thin binary deltas (`sync_version > client_version`), applying changes to local storage without re-fetching full datasets.

package/skills/lottie-animation/SKILL.md

@@ -1,62 +1,62 @@
----
-name: lottie-animation
-description: "Use when Lottie and dotLottie integration, playback control, hover/click triggers, runtime theming, and performance optimization for React/Vue/Web."
-version: 5.0.0
-last-updated: 2026-09-13
-skills:
-  - 60fps-animation
-  - motion-engineering
-  - micro-interaction
-tools: Read, Grep, Glob, Bash, Edit, Write
-scripts-binding:
-  - .agent/scripts/lint_runner.js
-  - .agent/scripts/verify_all.js
----
-
-# Lottie Animation — dotLottie & Runtime Control
-
----
-
-## 🛠️ Technical Architecture & Reference Recipes
-
----
-
----
-
-## 3 Lottie Integration Recipes
-
-### 1. React dotLottie Interactive Player (`@dotlottie/react-player`)
-
-```tsx
-import React, { useRef } from 'react';
-import { DotLottiePlayer, Controls } from '@dotlottie/react-player';
-import '@dotlottie/react-player/dist/index.css';
-
-export function InteractiveLottieIcon() {
-  const lottieRef = useRef<any>(null);
-
-  return (
-    <div
-      onMouseEnter={() => lottieRef.current?.play()}
-      onMouseLeave={() => lottieRef.current?.stop()}
-      className="w-12 h-12 cursor-pointer"
-    >
-      <DotLottiePlayer
-        ref={lottieRef}
-        src="/animations/success-check.lottie"
-        autoplay={false}
-        loop={false}
-      />
-    </div>
-  );
-}
-```
-
-### 2. Runtime Color Injection / Theming
-
-Pass custom CSS variable overrides to dotLottie players to dynamically recolor vector paths at runtime without re-downloading JSON assets.
-
-### 3. Performance & Lazy Loading
-
-- Use `.lottie` (dotLottie format) instead of uncompressed `.json` Lottie files to achieve **80% smaller bundle file sizes**.
-- Lazy-load offscreen Lottie animations using `IntersectionObserver`.
+---
+name: lottie-animation
+description: "Use when Lottie and dotLottie integration, playback control, hover/click triggers, runtime theming, and performance optimization for React/Vue/Web."
+version: 5.0.0
+last-updated: 2026-09-13
+skills:
+  - 60fps-animation
+  - motion-engineering
+  - micro-interaction
+tools: Read, Grep, Glob, Bash, Edit, Write
+scripts-binding:
+  - .agent/scripts/lint_runner.js
+  - .agent/scripts/verify_all.js
+---
+
+# Lottie Animation — dotLottie & Runtime Control
+
+---
+
+## 🛠️ Technical Architecture & Reference Recipes
+
+---
+
+---
+
+## 3 Lottie Integration Recipes
+
+### 1. React dotLottie Interactive Player (`@dotlottie/react-player`)
+
+```tsx
+import React, { useRef } from 'react';
+import { DotLottiePlayer, Controls } from '@dotlottie/react-player';
+import '@dotlottie/react-player/src/index.css';
+
+export function InteractiveLottieIcon() {
+  const lottieRef = useRef<any>(null);
+
+  return (
+    <div
+      onMouseEnter={() => lottieRef.current?.play()}
+      onMouseLeave={() => lottieRef.current?.stop()}
+      className="w-12 h-12 cursor-pointer"
+    >
+      <DotLottiePlayer
+        ref={lottieRef}
+        src="/animations/success-check.lottie"
+        autoplay={false}
+        loop={false}
+      />
+    </div>
+  );
+}
+```
+
+### 2. Runtime Color Injection / Theming
+
+Pass custom CSS variable overrides to dotLottie players to dynamically recolor vector paths at runtime without re-downloading JSON assets.
+
+### 3. Performance & Lazy Loading
+
+- Use `.lottie` (dotLottie format) instead of uncompressed `.json` Lottie files to achieve **80% smaller bundle file sizes**.
+- Lazy-load offscreen Lottie animations using `IntersectionObserver`.