tribunal-kit 2.4.6 → 3.1.0

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

@@ -1,203 +1,120 @@
 ---
 name: local-first
-description: Local-first software principles. Offline-capable apps, CRDTs, sync engines (ElectricSQL, Replicache, Zero), conflict resolution, and the migration path from REST-first to local-first architecture. Use when building apps that need offline support, fast UI, or collaborative editing.
+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: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# Local-First Software Principles
-
-> In a local-first app, the network is an enhancement, not a requirement.
-> The app works fully offline. Sync happens in the background when possible.
+# Local-First Architecture — Offline-capable Mastery
 
 ---
 
-## The Local-First Promise
+## 1. Core Principles of Local-First
 
-Local-first apps satisfy all of these simultaneously — traditional web apps satisfy none:
+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.
 
-```
-✅ Fast UI       — reads from local replica, never waits for network
-✅ Offline use   — full functionality without internet
-✅ Collaboration — multiple users edit the same data
-✅ Privacy       — data lives on device by default
-✅ Longevity     — app works even if vendor servers go down
-```
+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).
 
 ---
 
-## Architecture Spectrum
+## 2. Sync Engines vs traditional fetching
 
-```
-REST-First (most apps today):
-  Client → HTTP → Server → DB
-  Offline: ❌  Speed: Network-bound  Collaboration: Manual
+Do not use React Query / SWR to build local-first. They are HTTP caching mechanisms.
 
-Optimistic UI (halfway):
-  Client → Local cache → HTTP → Server → DB
-  Offline: Partial  Speed: Fast for reads  Collaboration: Conflict-prone
+```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:
-  Client → Local replica (SQLite/CRDT) → Sync engine ↔ Server → DB
-  Offline: ✅  Speed: Instant  Collaboration: ✅ via CRDTs
-```
+// ✅ LOCAL-FIRST (e.g. PowerSync / ElectricSQL / WatermelonDB)
+// Resolves instantly. Data lives locally. Syncs silently in background.
+import { useQuery } from '@powersync/react';
 
----
-
-## Sync Engine Selection
+const { data, isLoading } = useQuery('SELECT * FROM todos ORDER BY created_at DESC');
 
-Choose based on your database, team size, and product requirements:
-
-| Engine | Sync Model | Database | Best For |
-|---|---|---|---|
-| **ElectricSQL** | Postgres → SQLite on client | PostgreSQL only | Postgres-native teams |
-| **Replicache** | Mutation log + pull | Any backend | Custom sync logic needed |
-| **Zero (Rocicorp)** | Reactive queries | PostgreSQL | Real-time apps, Figma-speed UIs |
-| **Liveblocks** | CRDT + storage API | Managed | Collaborative SaaS (no own server) |
-| **Yjs + y-indexeddb** | CRDT + local persistence | Any | Text editing, whiteboard |
+// 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.
+}
+```
 
 ---
 
-## CRDT Choices
-
-CRDTs (Conflict-free Replicated Data Types) resolve concurrent edits mathematically — no server arbitration needed:
+## 3. Conflict Resolution (CRDTs)
 
-| CRDT Type | Use For | Library |
-|---|---|---|
-| **LWW Register** | Scalar values (settings, status) | Built-in or custom |
-| **G-Counter** | Incrementing counters (likes, views) | Custom |
-| **OR-Set** | Sets that support add + remove | Yjs `Y.Array` |
-| **Y.Text** | Collaborative rich text | Yjs |
-| **Y.Map** | Shared key-value state | Yjs |
+When two users edit the exact same document offline and then reconnect, how is it resolved?
 
-```ts
-import * as Y from 'yjs';
-import { IndexeddbPersistence } from 'y-indexeddb';
+**Conflict-free Replicated Data Types (CRDTs)** automatically merge data without requiring a central server to decide the "winner."
 
-const doc = new Y.Doc();
+```typescript
+// Yjs - The leading CRDT library for collaborative text/state
+import * as Y from 'yjs'
+import { WebsocketProvider } from 'y-websocket'
 
-// Persist to IndexedDB — survives page reload, works offline
-new IndexeddbPersistence('my-doc-id', doc);
+const ydoc = new Y.Doc()
+const provider = new WebsocketProvider('wss://sync.example.com', 'room-1', ydoc)
 
-// Shared text — any concurrent edits from any user auto-merge
-const text = doc.getText('content');
-text.insert(0, 'Hello ');  // User A
-text.insert(6, 'World');   // User B — concurrent, no conflict
-// Result: "Hello World" — always correct, always the same
-```
-
----
+// Shared state array
+const yarray = ydoc.getArray('todos')
 
-## Optimistic UI Patterns
+// Observe changes (Fires locally and when peers sync)
+yarray.observe(event => {
+  console.log("State updated natively without conflict:", yarray.toArray())
+})
 
-Before full local-first, optimistic UI gives most of the speed benefit:
-
-```ts
-// ❌ Pessimistic — user waits for server response before any UI update
-async function likePost(postId: string) {
-  const updated = await api.likePost(postId);  // 200ms wait → UI freezes
-  setPost(updated);
-}
-
-// ✅ Optimistic — update UI immediately, sync in background
-async function likePost(postId: string) {
-  // 1. Instant UI update
-  setPost(prev => ({ ...prev, likes: prev.likes + 1, liked: true }));
-
-  try {
-    // 2. Sync to server in background
-    await api.likePost(postId);
-  } catch {
-    // 3. Rollback on failure
-    setPost(prev => ({ ...prev, likes: prev.likes - 1, liked: false }));
-    toast.error('Failed to like post');
-  }
-}
+// Insert data (Instantly merges cleanly with remote peers)
+yarray.insert(0, ['Buy milk'])
 ```
 
 ---
 
-## Conflict Resolution Strategies
+## 4. In-Browser Databases
 
-When two users edit the same data offline and then sync:
+Storing megabytes of relational data in `localStorage` will crash the browser.
 
-| Strategy | When to Use | Downside |
-|---|---|---|
-| **Last-Write-Wins (LWW)** | Settings, preferences | Concurrent edits silently overwrite each other |
-| **First-Write-Wins** | Booking/reservation slots | Rejecters unhappy, complex UX |
-| **CRDT merge** | Text, lists, collaborative state | Complex to implement from scratch — use Yjs |
-| **3-way merge** | Code files, configs | Requires common ancestor to compute diff |
-| **User-prompted resolution** | Critical data (contracts) | Adds friction but preserves intent |
+|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|
 
----
-
-## Migration Path: REST → Local-First
-
-Don't try to go from REST to full local-first in one step:
+```typescript
+// Clean IndexedDB Wrapper Example (Dexie)
+import Dexie, { type EntityTable } from 'dexie';
 
-```
-Phase 1: Optimistic UI
-  → Client mutates locally, syncs async
-  → Easy win: 200ms → 0ms perceived latency
-  → Risk: conflicts on concurrent updates
-
-Phase 2: Offline Detection + Queue
-  → Queue mutations when offline
-  → Apply queue on reconnect
-  → Risk: conflict ordering
-
-Phase 3: CRDT-backed Shared State
-  → Replace mutable shared data with CRDTs
-  → Full offline + collaboration
-  → No more conflicts
-```
+interface Friend {
+  id: number;
+  name: string;
+  age: number;
+}
 
----
+const db = new Dexie('FriendsDatabase') as Dexie & {
+  friends: EntityTable<Friend, 'id'>;
+};
 
-## Output Format
+// Schema configuration
+db.version(1).stores({
+  friends: '++id, name, age' // Primary key and indexed props
+});
 
-When this skill produces or reviews code, structure your output as follows:
+// 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());
 ```
-━━━ Local First Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Local First
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
 
 ---
-
-## 🏛️ Tribunal Integration (Anti-Hallucination)
-
-**Slash command: `/tribunal-backend`**
-**Active reviewers: `logic` · `security`**
-
-### ❌ Forbidden AI Tropes in Local-First
-
-1. **Treating CRDTs as magic** — CRDTs solve concurrent edits to shared state, not schema migrations or access control.
-2. **Inventing CRDT libraries** — `crdt-js`, `conflict-free`, `local-sync` are not real packages. Yjs, Automerge, and Loro are the real libraries.
-3. **Skipping conflict detection in LWW** — Last-Write-Wins silently drops data. Always make the conflict resolution strategy explicit and communicate it to the user.
-4. **Local storage for everything** — `localStorage` is synchronous, has a 5MB limit, and is not available in workers. Use IndexedDB via Dexie or Origin Private File System.
-
-### ✅ Pre-Flight Self-Audit
-
-```
-✅ Is the conflict resolution strategy explicit and documented?
-✅ Are only real CRDT libraries used (Yjs, Automerge, Loro)?
-✅ Is offline state persisted to IndexedDB, not localStorage?
-✅ Is the sync queue replay idempotent (safe to process the same mutation twice)?
-✅ Does the UI clearly communicate offline/syncing/synced state to the user?
-```

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

@@ -1,224 +1,84 @@
 ---
 name: mcp-builder
-description: MCP (Model Context Protocol) server building principles. Tool design, resource patterns, best practices.
+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: 1.0.0
-last-updated: 2026-03-12
+version: 2.0.0
+last-updated: 2026-04-02
 applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
 ---
 
-# MCP Server Development
-
-> An MCP server exposes capabilities to AI assistants.
-> Design tools the way you design a good API: clear contracts, predictable behavior, honest errors.
-
----
-
-## What MCP Servers Do
-
-An MCP (Model Context Protocol) server gives an AI assistant structured access to:
-
-- **Tools** — actions the AI can invoke (run a query, send a message, fetch data)
-- **Resources** — data the AI can read (files, database records, API responses)
-- **Prompts** — reusable prompt templates with parameters
-
----
-
-## Tool Design Principles
-
-### 1. One tool, one responsibility
-
-A tool that does two things is a tool that confuses the model. Split tools when they serve different goals.
-
-```ts
-// ❌ Ambiguous — does it list AND filter?
-{ name: "get_users", description: "Get users, optionally filtered by role" }
-
-// ✅ Separate concerns
-{ name: "list_users", description: "List all users with pagination" }
-{ name: "find_users_by_role", description: "Find users matching a specific role" }
-```
-
-### 2. Descriptions are the interface
-
-The AI reads descriptions to decide which tool to call. Write them for the AI, not for humans.
-
-- State exactly what the tool does in plain terms
-- State what the tool returns
-- State when NOT to use it if there's common confusion
-
-```ts
-{
-  name: "search_products",
-  description: "Search products by keyword. Returns an array of matching product records " +
-    "with id, name, price, and stock. Use this for keyword search, not for fetching a " +
-    "specific product by ID — use get_product_by_id for that."
-}
-```
-
-### 3. Input schemas are contracts
-
-Every tool input must have a JSON Schema definition with:
-- Required vs. optional fields clearly marked
-- Descriptions on each field
-- Sensible defaults on optional fields
-
-```ts
-inputSchema: {
-  type: "object",
-  required: ["query"],
-  properties: {
-    query: {
-      type: "string",
-      description: "Search keyword. Minimum 2 characters."
-    },
-    limit: {
-      type: "number",
-      description: "Maximum results to return. Default: 10. Max: 100.",
-      default: 10
-    }
-  }
-}
-```
-
-### 4. Errors must be informative
-
-When a tool fails, the AI needs to understand what went wrong and whether to retry.
-
-```ts
-// ❌ Useless error
-throw new Error("Failed");
-
-// ✅ Actionable error
-return {
-  isError: true,
-  content: [{
-    type: "text",
-    text: "Product search failed: the search index is temporarily unavailable. " +
-          "Try again in a few seconds or use list_products for unfiltered results."
-  }]
-};
-```
+# MCP Builder — Context Protocol Mastery
 
 ---
 
-## Resource Design
+## 1. The Anatomy of an MCP Server
 
-Resources give the AI read-only access to data. Use them for content the AI needs to understand context, not for actions.
+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").
 
-```ts
-server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
-  const uri = request.params.uri;
+```typescript
+// Standardize exposing a Tool securely via an MCP Server Wrapper
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { z } from "zod";
 
-  if (uri.startsWith("product://")) {
-    const id = uri.replace("product://", "");
-    const product = await db.products.findById(id);
+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 {
-      contents: [{
-        uri,
-        mimeType: "application/json",
-        text: JSON.stringify(product, null, 2)
-      }]
+      content: [{ type: "text", text: JSON.stringify(data) }]
     };
   }
-});
+);
 ```
 
 ---
 
-## Security Rules
+## 2. Resource Management vs Tool Management
 
-MCP servers execute with user-level permissions and may have access to sensitive systems:
+Do not use a `Tool` to read static data. Do not use a `Resource` to invoke remote actions.
 
-- **Never trust tool arguments without validation** — the AI can be prompted to send malicious input
-- **Parameterize all database queries** — treat tool input as untrusted user input
-- **Scope API keys narrowly** — the MCP server should have the minimum permissions needed
-- **Log tool invocations** — especially for tools that write data or delete records
-- **Rate limit tool calls** — prevent runaway AI loops from hammering backends
+- **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.
 
 ---
 
-## Configuration Template
-
-```json
-{
-  "mcpServers": {
-    "your-server": {
-      "command": "npx",
-      "args": ["-y", "your-mcp-package"],
-      "env": {
-        "API_KEY": "${YOUR_API_KEY}"
-      }
-    }
-  }
-}
-```
-
-Place in `~/.cursor/mcp.json` (Cursor) or `~/.gemini/antigravity/mcp_config.json` (Antigravity).
-
----
+## 3. Structuring Tool Descriptions (The LLM Gateway)
 
-## Output Format
+The LLM decides to fire your tool based entirely on the Description schema.
+If your description is vague, the LLM will hallucinate executions unpredictably.
 
-When this skill produces or reviews code, structure your output as follows:
+```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."
 ```
-━━━ Mcp Builder Report ━━━━━━━━━━━━━━━━━━━━━━━━
-Skill:       Mcp Builder
-Language:    [detected language / framework]
-Scope:       [N files · N functions]
-─────────────────────────────────────────────────
-✅ Passed:   [checks that passed, or "All clean"]
-⚠️  Warnings: [non-blocking issues, or "None"]
-❌ Blocked:  [blocking issues requiring fix, or "None"]
-─────────────────────────────────────────────────
-VBC status:  PENDING → VERIFIED
-Evidence:    [test output / lint pass / compile success]
-```
-
-**VBC (Verification-Before-Completion) is mandatory.**
-Do not mark status as VERIFIED until concrete terminal evidence is provided.
-
-
 
 ---
 
-## 🤖 LLM-Specific Traps
+## 4. MCP Security Boundaries
 
-AI coding assistants often fall into specific bad habits when dealing with this domain. These are strictly forbidden:
+An MCP Server gives an external AI execution capability over your shell or database.
 
-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.
+- **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.
 
 ---
-
-## 🏛️ 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.