tribunal-kit 4.0.1 → 4.3.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.
 
 ---
+
+
+---
+
+
+
+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.

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."
 
 ---
+
+
+---
+
+
+
+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.

package/.agent/workflows/audit.md

@@ -26,25 +26,25 @@ Security failures early in the pipeline halt subsequent steps. Lint/test failure
 
 ```
 Priority 1 — Security (HALT if critical finding)
-  python .agent/scripts/security_scan.py .
+  node .agent/scripts/security_scan.js .
 
 Priority 2 — Dependencies (HALT if exploitable CVE found)
-  python .agent/scripts/dependency_analyzer.py . --audit
+  node .agent/scripts/dependency_analyzer.js . --audit
 
 Priority 3 — Type Checking (CONTINUE but flag)
   npx tsc --noEmit
 
 Priority 4 — Lint (CONTINUE but flag as deployment blocker)
-  python .agent/scripts/lint_runner.py .
+  node .agent/scripts/lint_runner.js .
 
 Priority 5 — Schema Validation (CONTINUE but flag)
-  python .agent/scripts/schema_validator.py .
+  node .agent/scripts/schema_validator.js .
 
 Priority 6 — Tests (CONTINUE but mark incomplete)
-  python .agent/scripts/test_runner.py . --coverage
+  node .agent/scripts/test_runner.js . --coverage
 
 Priority 7 — Bundle Analysis (INFORM only)
-  python .agent/scripts/bundle_analyzer.py . --build
+  node .agent/scripts/bundle_analyzer.js . --build
 ```
 
 ### Cascade Failure Rules

package/.agent/workflows/deploy.md

@@ -34,7 +34,7 @@ Every step is logged. Every step has a rollback path. No surprises.
 # T-minus safety sequence (in exact order)
 
 # 1. Security: halt on critical
-python .agent/scripts/security_scan.py . --level=critical
+node .agent/scripts/security_scan.js . --level=critical
 
 # 2. Dependencies: no exploitable CVEs
 npm audit --audit-level=high

package/.agent/workflows/generate.md

@@ -25,6 +25,14 @@ $ARGUMENTS
 Your request
     │
     ▼
+[Phase 6] Context Broker — Skill Selection
+├── Scores all 90+ skills against your task keywords
+├── Level 0 (Essential): top skills — full content, injected first
+├── Level 1 (Supplementary): medium relevance — key rules only
+├── Level 2 (Available): listed for reference only
+└── Large models: Essential + Supplementary | Small models: Essential only
+    │
+    ▼
 Context scan (MANDATORY before first line of code)
 ├── Read package.json → verify all imports exist
 ├── Read tsconfig.json → understand strictness, paths aliases
@@ -39,7 +47,17 @@ Maker generates at temperature 0.1
 └── No full application generation — modules only
     │
     ▼
-Reviewers run in parallel (auto-selected by keyword)
+[Phase 6] Inner-Loop Validator (AUTO — runs before you see the code)
+├── Scans generated snippet for OWASP patterns (critical/high/medium/low)
+├── Runs structural heuristics (empty catch, throw strings, env without fallback)
+├── Verdict: APPROVED / WARNING / REJECTED
+│   ├── APPROVED → continues to Tribunal Review
+│   ├── WARNING  → noted, continues with flag
+│   └── REJECTED → Maker auto-corrects (up to 2 inner-loop attempts)
+└── Only clean code reaches the Tribunal reviewers
+    │
+    ▼
+Tribunal Reviewers run in parallel (auto-selected by keyword)
     │
     ▼
 Human Gate — verdicts shown + unified diff
@@ -84,13 +102,14 @@ security-auditor   → OWASP vulnerabilities, hardcoded secrets, injection
 |:---|:---|
 | `api`, `route`, `endpoint`, `handler`, `server action` | `dependency-reviewer` + `type-safety-reviewer` |
 | `sql`, `query`, `database`, `prisma`, `drizzle`, `orm` | `sql-reviewer` |
-| `component`, `hook`, `react`, `vue`, `jsx`, `tsx` | `frontend-reviewer` + `type-safety-reviewer` |
-| `animation`, `gsap`, `framer`, `motion`, `scroll` | `frontend-reviewer` + `performance-reviewer` |
+| `component`, `hook`, `react`, `vue`, `jsx`, `tsx` | `frontend-reviewer` + `type-safety-reviewer` + `ui-ux-auditor` |
+| `ui`, `design`, `landing`, `page`, `layout`, `style`, `css` | `ui-ux-auditor` + `accessibility-reviewer` |
+| `animation`, `gsap`, `framer`, `motion`, `scroll` | `frontend-reviewer` + `performance-reviewer` + `ui-ux-auditor` |
 | `test`, `spec`, `vitest`, `jest`, `playwright` | `test-coverage-reviewer` |
 | `slow`, `optimize`, `cache`, `performance`, `bundle` | `performance-reviewer` |
 | `mobile`, `react native`, `expo` | `mobile-reviewer` |
 | `llm`, `openai`, `anthropic`, `gemini`, `embedding`, `ai` | `ai-code-reviewer` |
-| `aria`, `wcag`, `a11y`, `accessibility` | `accessibility-reviewer` |
+| `aria`, `wcag`, `a11y`, `accessibility` | `accessibility-reviewer` + `ui-ux-auditor` |
 | `import`, `package`, `npm`, `require` | `dependency-reviewer` |
 
 > For maximum safety on critical code: use `/tribunal-full` for all 11 reviewers simultaneously.
@@ -136,8 +155,6 @@ Write to disk?  Y = approve | N = discard | R = revise with feedback
 
 ---
 
-## Cross-Workflow Navigation
-
 | After /generate shows... | Go to |
 |:---|:---|
 | Multiple files need changing | `/enhance` for impact-zone analysis |

package/.agent/workflows/session.md

@@ -23,11 +23,11 @@ $ARGUMENTS
 ## Execution
 
 ```bash
-python .agent/scripts/session_manager.py save
-python .agent/scripts/session_manager.py restore
-python .agent/scripts/session_manager.py status
-python .agent/scripts/session_manager.py new
-python .agent/scripts/session_manager.py list
+node .agent/scripts/session_manager.js save
+node .agent/scripts/session_manager.js restore
+node .agent/scripts/session_manager.js status
+node .agent/scripts/session_manager.js new
+node .agent/scripts/session_manager.js list
 ```
 
 ---

package/.agent/workflows/swarm.md

@@ -1,5 +1,5 @@
 ---
-description: Multi-Agent Swarm Orchestration. Supervisor decomposes a complex goal into sub-tasks, dispatches to specialist Workers via structured JSON contracts, collects results via allSettled fan-in, and synthesizes a unified deliverable. Validates payloads via swarm_dispatcher.py before dispatch.
+description: Multi-Agent Swarm Orchestration. Supervisor decomposes a complex goal into sub-tasks, dispatches to specialist Workers via structured JSON contracts, collects results via allSettled fan-in, and synthesizes a unified deliverable. Validates payloads via swarm_dispatcher.js before dispatch.
 ---
 
 # /swarm — Multi-Agent Swarm Execution
@@ -69,7 +69,7 @@ Every worker receives a structured JSON contract (not natural language):
 Before dispatching, validate all worker contracts:
 
 ```bash
-python .agent/scripts/swarm_dispatcher.py --file payload.json
+node .agent/scripts/swarm_dispatcher.js --file payload.json
 ```
 
 If validation passes → dispatch workers in parallel.

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/README.md

@@ -7,14 +7,14 @@
 
   [![NPM](https://img.shields.io/npm/v/tribunal-kit?style=for-the-badge&logo=npm&logoColor=white)](https://www.npmjs.com/package/tribunal-kit)
   [![License](https://img.shields.io/badge/License-MIT-8b5cf6?style=for-the-badge)](LICENSE)
-  [![Version](https://img.shields.io/badge/Version-4.0.0_Supreme_Court-black?style=for-the-badge)](CHANGELOG.md)
+  [![Version](https://img.shields.io/badge/Version-4.2.0_Supreme_Court-black?style=for-the-badge)](CHANGELOG.md)
 </div>
 
 
 <br><br>
 
 > 🚨 **AI GENERATES CODE. TRIBUNAL ENSURES IT WORKS.**  
-> A plug-in `.agent/` intelligence payload that upgrades your IDE with **32 specialist agents**, **25 slash commands**, **8 parallel Tribunal reviewers**, and a core **Swarm/Supervisor** engine.
+> A plug-in `.agent/` intelligence payload that upgrades your IDE with **41 specialist agents**, **31 slash commands**, **16 parallel Tribunal reviewers**, and a core **Swarm/Supervisor** engine.
 
 ---
 
@@ -30,7 +30,63 @@ npx tribunal-kit init
 ```
 *(Installs the `.agent/` architecture directly. No bloat. Pure capability.)*
 
-> ⚠️ **CRITICAL PATH WARNING:** Do **not** let your IDE ignore the agents. If using Cursor or Windsurf, keep `.agent/` **out** of `.gitignore` so the IDE can index the commands. Use `.git/info/exclude` instead.
+<details>
+<summary><b>📺 Quick Demo — What happens when you run it</b></summary>
+<br>
+
+```
+$ npx tribunal-kit init
+
+  ████████╗██████╗ ██╗██████╗ ██╗   ██╗███╗   ██╗ █████╗ ██╗
+  ╚══██╔══╝██╔══██╗██║██╔══██╗██║   ██║████╗  ██║██╔══██╗██║
+     ██║   ██████╔╝██║██████╔╝██║   ██║██╔██╗ ██║███████║██║
+     ██║   ██╔══██╗██║██╔══██╗██║   ██║██║╚██╗██║██╔══██║██║
+     ██║   ██║  ██║██║██████╔╝╚██████╔╝██║ ╚████║██║  ██║███████╗
+     ╚═╝   ╚═╝  ╚═╝╚═╝╚═════╝  ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═╝╚══════╝
+
+  ╔══════════════════════════════════════════════════════════════╗
+  ║              Anti-Hallucination Agent System                ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+  ✔ Installed → .agent/
+
+  ╔══════════════════════════════════════════════════════════════╗
+  ║  🤖  Agents         40 installed                            ║
+  ║  ⚡  Workflows       31 installed                            ║
+  ║  🧠  Skills          90 installed                            ║
+  ║  🔧  Scripts         27 installed                            ║
+  ╚══════════════════════════════════════════════════════════════╝
+
+  ✔ 700+ files installed. 16 parallel Tribunal reviewers armed.
+
+$ npx tribunal-kit status
+
+  ✔ Installed at .agent/
+  🤖  agents         40 files
+  ⚡  workflows      31 files
+  🧠  skills         90 files
+  🔧  scripts        27 files
+```
+
+> 💡 **Lighter install?** Use `npx tribunal-kit init --minimal` for just 13 core agents + 15 essential skills.
+
+</details>
+
+> ✅ **IDE Auto-Detection:** `init` automatically generates bridge files for every major AI coding IDE:
+>
+> | IDE | Bridge File Generated |
+> | :--- | :--- |
+> | **Cursor** | `.cursorrules` |
+> | **Windsurf** | `.windsurfrules` |
+> | **Gemini / Antigravity** | `.gemini/settings.json` + `.gemini/GEMINI.md` |
+> | **GitHub Copilot** | `.github/copilot-instructions.md` |
+> | **Claude** | `.claude/CLAUDE.md` |
+>
+> Bridge files are never overwritten on re-init — your customizations are safe.
+
+**Prerequisites:** Node.js ≥ 18 • Python ≥ 3.10 *(optional — required for utility scripts like `checklist.py`, `security_scan.py`)*
+
+> 💡 **Shorthand alias:** You can use `tk` instead of `tribunal-kit` for all commands (e.g., `tk init`, `tk status`).
 
 <br>
 
@@ -79,10 +135,10 @@ You no longer need to write manual rules. The system reads your Git commits, str
 
 | System Asset | Count | Operational Scope |
 | :--- | :---: | :--- |
-| 🤖 **Agents** | `33` | Specialist personas (Security, DB Architect, DevOps Responder, QA Engineer) |
-| 🧠 **Skills** | `77` | Domain modules (Edge Computing, Red Team Tactics, GSAP, Framer Motion) |
-| ⚡ **Workflows** | `30` | Slash command procedures including `/swarm`, `/tribunal-full`, `/ui-ux-pro-max` |
-| 🛠️ **Scripts** | `16` | CI/CD, linting, payload dispatching, security scanning, test suite runners |
+| 🤖 **Agents** | `40` | Specialist personas — 16 reviewers + 24 domain specialists |
+| 🧠 **Skills** | `90` | Domain modules (Edge Computing, Red Team Tactics, GSAP, Framer Motion, TypeScript Advanced) |
+| ⚡ **Workflows** | `31` | Slash command procedures including `/swarm`, `/tribunal-full`, `/ui-ux-pro-max` |
+| 🛠️ **Scripts** | `25` | CI/CD, linting, payload dispatching, security scanning, case law, skill evolution |
 
 
 <br>
@@ -112,7 +168,7 @@ Unleash parallel reviewers on existing code.
 | Command | Action |
 | :--- | :--- |
 | <code>/review</code> | Audit code for silent degradation and logic holes. |
-| <code>/tribunal-full</code> | Unleash **ALL 11** reviewers simultaneously. Maximum scrutiny. |
+| <code>/tribunal-full</code> | Unleash **ALL 16** reviewers simultaneously. Maximum scrutiny. |
 | <code>/tribunal-backend</code> | Summons <code>[ Logic + Security + Dependency + Types ]</code> |
 | <code>/tribunal-frontend</code> | Summons <code>[ Logic + Security + Frontend + Types ]</code> |
 | <code>/tribunal-database</code> | Summons <code>[ Logic + Security + SQL ]</code> |