tribunal-kit 3.0.0 → 4.0.0

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

@@ -1,154 +1,128 @@
----
-name: local-first
-description: 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.
-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
----
-
-# Local-First Architecture — Offline-capable Mastery
-
-> The network is the bottleneck. The database should live on the user's device.
-> Traditional SaaS is Cloud-First. The future of UX is Local-First.
-
----
-
-## 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());
-```
-
----
-
-## 🤖 LLM-Specific Traps (Local-First)
-
-1. **`localStorage` Abuse:** Using `localStorage` as a database. It is synchronous, blocking the main UI thread, and limited to 5MB. Use IndexedDB/SQLite WASM.
-2. **Re-inventing Conflict Logic:** Writing manual "last-write-wins" logic using timestamps (`updatedAt`). In distributed systems, clock drift guarantees this will fail and overwrite data corruptly. Use CRDTs (Yjs/Automerge).
-3. **Optimistic UI as Local-First:** Thinking React Query's `onMutate` rollback logic is local-first architecture. It is not. It is a UX trick masking Cloud-First latency.
-4. **Offline Auth Blindness:** Trying to execute local queries while wrapped in an `AuthGuard` that requires a server-side JWT verification on boot. Auth states must be cached locally to allow offline boots.
-5. **Schema Migration Chaos:** Updating cloud schemas without providing local migration scripts. If the local client SQLite DB schema differs from the Postgres cloud schema, the sync engine will crash silently.
-6. **Background Sync Blocking:** Writing custom `setInterval` sync loops on the main JavaScript thread, causing UI stutter. Sync logic must run in a Web Worker (or Service Worker).
-7. **Ignoring IndexedDB Quotas:** Browsers will unpredictably evict IndexedDB data if the user's disk gets full. Architect apps resolving local data as a cache of the cloud, not as the irrevocable source of truth.
-8. **Heavy Client Boot Times:** Bootstrapping a massive 50MB SQLite WASM database onto the client payload, destroying First Contentful Paint. WASM blobs should be pre-fetched/lazy-loaded.
-9. **Eventual Consistency Panic:** Developing UIs that throw errors if a foreign key relation hasn't synced yet. Local-first UIs must defensively handle partial data relationships seamlessly.
-10. **WebSocket vs Local Priority:** Over-relying on WebSockets connected directly to the server. The UI should strictly read from the Local DB; the Local DB gets updated by the WebSocket.
-
----
-
-## 🏛️ Tribunal Integration
-
-### ✅ Pre-Flight Self-Audit
-```
-✅ Is the UI strictly reading from a local DB instead of HTTP network calls?
-✅ Are background sync tasks isolated in a Web Worker (or managed Sync Engine)?
-✅ Is complex relational data stored in IndexedDB/SQLite (not `localStorage`)?
-✅ Are conflicts resolved using CRDT structures rather than arbitrary timestamp comparisons?
-✅ Have authentication states been cached locally to permit true offline app launches?
-✅ Does the local database schema precisely mirror the required subset of the cloud database?
-✅ Are writes executed locally first, instantly updating the UI?
-✅ Have I utilized established Local-First sync engines (PowerSync, ElectricSQL, Yjs) instead of manual queuing?
-✅ Is the UI built to degrade gracefully if sync relationships are temporarily shattered?
-✅ Is the app's initial WASM/DB payload lazy-loaded to preserve fast initial page loads?
-```
+---
+name: local-first
+description: 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.
+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)
+- ❌ 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
+
+---
+
+
+# Local-First Architecture — Offline-capable Mastery
+
+---
+
+## 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/.agent/skills/mcp-builder/SKILL.md

@@ -1,118 +1,92 @@
----
-name: mcp-builder
-description: Model Context Protocol (MCP) server integration mastery. Building custom MCP servers, standardizing tool exposes, managing standardized communication between large language models and localized datasets, securing boundary contexts, and architecting resource schemas. Use when modifying, extending, or building custom toolsets for AI platforms relying on the MCP standard.
-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
----
-
-# MCP Builder — Context Protocol Mastery
-
-> AI reasoning is infinite. But its access to your localized reality is zero without a bridge.
-> An MCP Server is the high-bandwidth, strictly-schema'd bridge into your secure internal domain.
-
----
-
-## 1. The Anatomy of an MCP Server
-
-The Model Context Protocol (MCP) standardizes how AI agents fetch local data and execute tools.
-A robust MCP server exposes exactly 3 primary concepts:
-1. **Resources:** Read-only data payloads (Logs, local files, database dumps).
-2. **Prompts:** Reusable injected context scaffolding (e.g., "Summarize this log with strict parameters").
-3. **Tools:** Actionable executed capabilities (e.g., "Run Postgres Query", "Restart Server").
-
-```typescript
-// Standardize exposing a Tool securely via an MCP Server Wrapper
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { z } from "zod";
-
-const server = new McpServer({
-  name: "internal-database-auditor",
-  version: "1.0.0",
-});
-
-// Defining a rigorous tool parameter boundary
-server.tool(
-  "query_production_database",
-  "Executes a read-only sanitized query against the production analytical replica.",
-  {
-    table: z.enum(["users", "transactions", "audit_logs"]).describe("The specific table to analyze"),
-    limit: z.number().max(100).default(10).describe("Maximum row returns to prevent context bloat"),
-  },
-  async ({ table, limit }) => {
-    // Execution logic
-    const data = await secureDatabaseClient.query(`SELECT * FROM ${table} LIMIT ${limit}`);
-    return {
-      content: [{ type: "text", text: JSON.stringify(data) }]
-    };
-  }
-);
-```
-
----
-
-## 2. Resource Management vs Tool Management
-
-Do not use a `Tool` to read static data. Do not use a `Resource` to invoke remote actions.
-
-- **Resources (URI based):** Act identically to local files. Exposed explicitly so the AI context manager can read them *before* invoking tools. Use for things like `file:///app/config.json` or `db://schema/users`.
-- **Tools:** Use exclusively when parameterized execution is required dynamically. Tools MUST be accompanied by extremely literal, explicit descriptions, because the LLM uses the description text to map Intent to the Tool execution.
-
----
-
-## 3. Structuring Tool Descriptions (The LLM Gateway)
-
-The LLM decides to fire your tool based entirely on the Description schema.
-If your description is vague, the LLM will hallucinate executions unpredictably.
-
-```typescript
-// ❌ VAGUE (The LLM will guess when to use this, often incorrectly)
-description: "Changes the system status."
-
-// ✅ DETERMINISTIC (The LLM knows the exact boundaries and consequences)
-description: "Transitions the payment processing gateway between 'ACTIVE' and 'MAINTENANCE' modes. Use this ONLY after verifying traffic logs to halt impending queue flooding. Requires Admin clearance."
-```
-
----
-
-## 4. MCP Security Boundaries
-
-An MCP Server gives an external AI execution capability over your shell or database.
-
-- **Never Expose Raw Shells Natively:** Unless deliberately building a high-trust local desktop agent. Expose mapped commands (`execute_npm_build`) instead of raw terminals (`bash_command`).
-- **Enforce Read-Only Defaults:** If creating a database tool, create `query_select_only` separate from `execute_mutation`. Give the AI read-only access.
-- **Context Size Truncation:** If a tool queries a 5GB text log, the AI context window will instantly overflow and crash the session. The MCP logic MUST forcibly truncate outputs before returning.
-
----
-
-## 🤖 LLM-Specific Traps (MCP Integration)
-
-1. **Raw Terminal Chaos:** Exposing a `run_command` MCP tool that blindly executes strings into `child_process.exec()` without any input sanitization, opening massive RCE (Remote Code Execution) vulnerabilities via prompt injection.
-2. **Missing Input Schemas:** The AI defines a tool but accepts an `any` type object as the argument. The LLM will wildly hallucinate keys into the object. You MUST enforce strict Zod boundaries on every incoming payload.
-3. **Massive Output Strings:** A tool returns 200,000 characters of a database dump without pagination or truncation limits, immediately blowing out the 128k context window and terminating the user session silently.
-4. **Action Overlap:** Creating 5 separate tools (`read_file`, `scan_file`, `parse_file`) with nearly identical generic descriptions. The LLM will randomly select between them, destroying deterministic reliability. Consolidate overlapping tool definitions.
-5. **No State Feedback:** A tool mutates user state successfully, but returns an empty string `""` to the LLM. The LLM gets confused and assumes the tool failed, trying to execute it again. Tools must return explicit confirmation states (`"Success: Mutated 5 rows."`).
-6. **Resource Pretending as a Tool:** Building a complex function to "Fetch API Keys config" instead of just exposing the configuration natively as an MCP Resource URI.
-7. **Ignoring Transport Layers:** Assuming standard HTTP routing for MCP implementations instead of using standard STDIO or SSE (Server-Sent Events) transports required by the specific AI host architectures.
-8. **Catch-And-Hide Errors:** Formatting error messages back into the tool response as standard `text`. If an MCP tool errors, it must set `isError: true` so the LLM explicitly recognizes the failure and recalculates.
-9. **Infinite Retry Traps:** The LLM fires a tool wrong, gets an error, and fires it wrong again infinitely. The MCP builder MUST return guided error messages (e.g., "Error: Invalid ID. Valid IDs are 1,2,3") to break the hallucination loop.
-10. **The Universal Fixer Tool:** Defining a massive monolithic `executeTask(prompt)` tool instead of segregating capabilities cleanly into specific atomic tools (`git_commit`, `write_file`, `read_log`).
-
----
-
-## 🏛️ Tribunal Integration
-
-### ✅ Pre-Flight Self-Audit
-```
-✅ Are MCP tools rigidly bounded by strict `.describe()` schemas (Zod or JSON Schema)?
-✅ Has the output payload been aggressively truncated to prevent LLM context-window exhaustion?
-✅ Do the tool operational descriptions explicitly define the exact intent boundaries?
-✅ Are execution errors returned with explicit `isError: true` flags directly to the LLM agent?
-✅ Do error strings contain corrective guidance allowing the LLM to self-correct and retry?
-✅ Has raw RCE shell access been minimized or heavily parameterized to specific execution actions?
-✅ Were static files mapped distinctly as MCP *Resources* rather than invoked as executable *Tools*?
-✅ Does every tool execution return an explicit, verbose success/mutation confirmation string?
-✅ Have duplicated intersecting tool concepts been consolidated to prevent LLM routing confusion?
-✅ Did I select the correct transport mechanism (STDIO vs SSE) required by the host client configuration?
-```
+---
+name: mcp-builder
+description: Model Context Protocol (MCP) server integration mastery. Building custom MCP servers, standardizing tool exposes, managing standardized communication between large language models and localized datasets, securing boundary contexts, and architecting resource schemas. Use when modifying, extending, or building custom toolsets for AI platforms relying on the MCP standard.
+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)
+- ❌ Exposing tools without input validation schemas -> ✅ Every MCP tool MUST have JSON Schema for parameters; the protocol requires it
+- ❌ Returning unstructured strings from tool calls -> ✅ Return structured JSON that the LLM can reliably parse and act on
+- ❌ Not handling tool call timeouts -> ✅ Always set execution timeouts; hanging tools block the entire LLM conversation loop
+
+---
+
+
+# MCP Builder — Context Protocol Mastery
+
+---
+
+## 1. The Anatomy of an MCP Server
+
+The Model Context Protocol (MCP) standardizes how AI agents fetch local data and execute tools.
+A robust MCP server exposes exactly 3 primary concepts:
+1. **Resources:** Read-only data payloads (Logs, local files, database dumps).
+2. **Prompts:** Reusable injected context scaffolding (e.g., "Summarize this log with strict parameters").
+3. **Tools:** Actionable executed capabilities (e.g., "Run Postgres Query", "Restart Server").
+
+```typescript
+// Standardize exposing a Tool securely via an MCP Server Wrapper
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
+
+const server = new McpServer({
+  name: "internal-database-auditor",
+  version: "1.0.0",
+});
+
+// Defining a rigorous tool parameter boundary
+server.tool(
+  "query_production_database",
+  "Executes a read-only sanitized query against the production analytical replica.",
+  {
+    table: z.enum(["users", "transactions", "audit_logs"]).describe("The specific table to analyze"),
+    limit: z.number().max(100).default(10).describe("Maximum row returns to prevent context bloat"),
+  },
+  async ({ table, limit }) => {
+    // Execution logic
+    const data = await secureDatabaseClient.query(`SELECT * FROM ${table} LIMIT ${limit}`);
+    return {
+      content: [{ type: "text", text: JSON.stringify(data) }]
+    };
+  }
+);
+```
+
+---
+
+## 2. Resource Management vs Tool Management
+
+Do not use a `Tool` to read static data. Do not use a `Resource` to invoke remote actions.
+
+- **Resources (URI based):** Act identically to local files. Exposed explicitly so the AI context manager can read them *before* invoking tools. Use for things like `file:///app/config.json` or `db://schema/users`.
+- **Tools:** Use exclusively when parameterized execution is required dynamically. Tools MUST be accompanied by extremely literal, explicit descriptions, because the LLM uses the description text to map Intent to the Tool execution.
+
+---
+
+## 3. Structuring Tool Descriptions (The LLM Gateway)
+
+The LLM decides to fire your tool based entirely on the Description schema.
+If your description is vague, the LLM will hallucinate executions unpredictably.
+
+```typescript
+// ❌ VAGUE (The LLM will guess when to use this, often incorrectly)
+description: "Changes the system status."
+
+// ✅ DETERMINISTIC (The LLM knows the exact boundaries and consequences)
+description: "Transitions the payment processing gateway between 'ACTIVE' and 'MAINTENANCE' modes. Use this ONLY after verifying traffic logs to halt impending queue flooding. Requires Admin clearance."
+```
+
+---
+
+## 4. MCP Security Boundaries
+
+An MCP Server gives an external AI execution capability over your shell or database.
+
+- **Never Expose Raw Shells Natively:** Unless deliberately building a high-trust local desktop agent. Expose mapped commands (`execute_npm_build`) instead of raw terminals (`bash_command`).
+- **Enforce Read-Only Defaults:** If creating a database tool, create `query_select_only` separate from `execute_mutation`. Give the AI read-only access.
+- **Context Size Truncation:** If a tool queries a 5GB text log, the AI context window will instantly overflow and crash the session. The MCP logic MUST forcibly truncate outputs before returning.
+
+---