tribunal-kit 2.4.5 → 3.0.0

package/.agent/skills/server-management/SKILL.md

@@ -1,212 +1,190 @@
----
-name: server-management
-description: Server management principles and decision-making. Process management, monitoring strategy, and scaling decisions. Teaches thinking, not commands.
-allowed-tools: Read, Write, Edit, Glob, Grep
-version: 1.0.0
-last-updated: 2026-03-12
-applies-to-model: gemini-2.5-pro, claude-3-7-sonnet
----
-
-# Server Management Principles
-
-> A server you can't observe is a server you can't operate.
-> Monitoring is not optional — it is how you find out about problems before your users do.
-
----
-
-## Process Management
-
-Never run Node.js or Python processes directly in production with `node app.js`. Use a process manager.
-
-| Tool | Best For | Why |
-|---|---|---|
-| PM2 | Single-server Node.js | Auto-restart, log rotation, cluster mode |
-| systemd | Linux servers, any language | Native to most Linux distros, reliable |
-| Supervisor | Python, Ruby, any language | Simple config, battle-tested |
-| Docker (+restart policy) | Containerized apps | Portable, consistent across environments |
-
-**Core requirement:** If the process crashes, it restarts automatically. If it can't restart, you are alerted.
-
-```bash
-# PM2 example — stays running, auto-restarts, survives reboots
-pm2 start app.js --name "api" --instances max
-pm2 save
-pm2 startup  # generates the command to run at boot
-```
-
----
-
-## What to Monitor
-
-The minimum viable monitoring stack:
-
-| Signal | What To Alert On |
-|---|---|
-| Process health | Process is not running |
-| Response time | P95 latency > SLA threshold |
-| Error rate | Error rate > 2x baseline |
-| Disk usage | > 80% full |
-| Memory | Growing without bound (memory leak) |
-| CPU | Sustained > 80% for more than 5 minutes |
-
-**Alert on symptoms, not just causes.** "Error rate spiked" is a better alert than "CPU is high" — users don't feel CPU, they feel slow responses and errors.
-
----
-
-## Log Management
-
-Logs are useless without structure. Structured logs can be queried and aggregated.
-
-```ts
-// ❌ Unstructured — hard to query
-console.log(`User ${userId} failed to login at ${new Date()}`);
-
-// ✅ Structured — can be filtered, aggregated, alerted on
-logger.warn('login_failed', {
-  userId,
-  ip: req.ip,
-  reason: 'invalid_password',
-  timestamp: new Date().toISOString(),
-});
-```
-
-**Log levels, used correctly:**
-- `ERROR` — something failed that requires attention
-- `WARN` — something unexpected but non-fatal happened
-- `INFO` — key business events (user registered, payment processed)
-- `DEBUG` — useful for troubleshooting, never on in production by default
-
-**Never log:**
-- Passwords, tokens, or full credit card numbers
-- PII without a documented retention policy
-- Full request bodies on auth endpoints
-
----
-
-## Scaling Decision Framework
-
-Before scaling, answer:
-
-**Is the bottleneck identified?**
-- Profile first. Is it CPU, memory, database, or network?
-- Scaling horizontally when the bottleneck is a single database query helps nothing.
-
-| Bottleneck | Scaling Approach |
-|---|---|
-| CPU-bound app logic | Horizontal scale (more instances) |
-| Memory limit | Vertical scale (more RAM per instance) |
-| I/O-bound (DB, external calls) | Connection pooling, caching, async patterns |
-| Database reads | Read replicas, query optimization, caching |
-| Database writes | Sharding, write queuing, schema redesign |
-
-**Cached responses don't need scaling.** Add caching before adding instances.
-
----
-
-## Nginx Configuration Essentials
-
-```nginx
-server {
-  listen 80;
-  server_name example.com;
-  
-  # Redirect HTTP → HTTPS
-  return 301 https://$host$request_uri;
-}
-
-server {
-  listen 443 ssl;
-  server_name example.com;
-
-  # Security headers
-  add_header X-Frame-Options DENY;
-  add_header X-Content-Type-Options nosniff;
-  add_header Strict-Transport-Security "max-age=31536000" always;
-
-  # Proxy to Node.js app
-  location / {
-    proxy_pass http://127.0.0.1:3000;
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-Proto https;
-  }
-
-  # Serve static files directly (don't proxy to Node)
-  location /static/ {
-    root /var/www/myapp;
-    expires 1y;
-    add_header Cache-Control "public, immutable";
-  }
-}
-```
-
----
-
-## Backup Strategy
-
-The 3-2-1 rule:
-- **3** copies of data
-- **2** on different storage media
-- **1** offsite (different data center, cloud region)
-
-Test restores on a schedule — a backup you've never restored is a backup you don't know works.
-
----
-
-## Output Format
-
-When this skill produces a recommendation or design decision, structure your output as:
-
-```
-━━━ Server Management Recommendation ━━━━━━━━━━━━━━━━
-Decision:    [what was chosen / proposed]
-Rationale:   [why — one concise line]
-Trade-offs:  [what is consciously accepted]
-Next action: [concrete next step for the user]
-─────────────────────────────────────────────────
-Pre-Flight:  ✅ All checks passed
-             or ❌ [blocking item that must be resolved first]
-```
-
-
-
----
-
-## 🤖 LLM-Specific Traps
-
-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.
-
----
-
-## 🏛️ 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.
+---
+name: server-management
+description: Production Linux server administration mastery. Systemd services, Nginx reverse proxy architecture, UFW firewalls, SSH key security, cron scheduling, log rotation, and server hardening. Use when configuring bare-metal, VPS instances, or reviewing deployment architecture.
+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
+---
+
+# Server Management — Production Linux Mastery
+
+> Never run a web server as root. Never expose raw ports securely.
+> A naked Node/Python process dies silently. A systemd service acts as its immortal guardian.
+
+---
+
+## 1. Systemd Service Architecture (Process Guard)
+
+Do not use `pm2`, `forever`, or custom `screen` sessions attached to SSH panels for server orchestration. Linux provides an enterprise-grade init system natively: systemd.
+
+```ini
+# /etc/systemd/system/myapp.service
+
+[Unit]
+Description=My Application Node.js Server
+Documentation=https://example.com/docs
+After=network.target postgresql.service # Ensure DB and Network start first
+
+[Service]
+Type=simple
+User=appuser     # NEVER run as root
+Group=appuser
+WorkingDirectory=/var/www/myapp
+
+# Explicitly declare environment limits and variables
+Environment=NODE_ENV=production
+Environment=PORT=3000
+EnvironmentFile=/var/www/myapp/.env
+
+# The execution target
+ExecStart=/usr/bin/node /var/www/myapp/build/index.js
+
+# Immortal behavior: Restart strictly on failure
+Restart=on-failure
+RestartSec=5
+
+# Security Hardening
+NoNewPrivileges=yes
+PrivateTmp=yes
+RestrictAddressFamilies=AF_INET AF_INET6 AF_UNIX
+
+[Install]
+WantedBy=multi-user.target
+```
+
+**Commands:**
+`sudo systemctl daemon-reload`
+`sudo systemctl enable myapp`
+`sudo systemctl start myapp`
+`journalctl -u myapp -f` (Follow logs seamlessly)
+
+---
+
+## 2. Nginx Reverse Proxy Architecture
+
+You must shield your internal application framework (Node/Python/Ruby) behind Nginx. Nginx handles SSL termination, static file caching, and DDOS mitigation.
+
+```nginx
+# /etc/nginx/sites-available/myapp.com
+
+server {
+    listen 80;
+    server_name api.myapp.com;
+    
+    # Force SSL Redirect
+    return 301 https://$host$request_uri;
+}
+
+server {
+    listen 443 ssl http2;
+    server_name api.myapp.com;
+
+    # SSL Certs (Let's Encrypt / Certbot)
+    ssl_certificate /etc/letsencrypt/live/api.myapp.com/fullchain.pem;
+    ssl_certificate_key /etc/letsencrypt/live/api.myapp.com/privkey.pem;
+
+    # Modern Security Headers
+    add_header Strict-Transport-Security "max-age=63072000" always;
+    add_header X-Content-Type-Options nosniff;
+    add_header X-Frame-Options DENY;
+
+    # GZIP Compression
+    gzip on;
+    gzip_types text/plain application/json;
+
+    location / {
+        # Proxy traffic to internal local process
+        proxy_pass http://127.0.0.1:3000;
+        
+        # Forward original IP and Protocol for rate limiters
+        proxy_set_header Host $host;
+        proxy_set_header X-Real-IP $remote_addr;
+        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+        proxy_set_header X-Forwarded-Proto $scheme;
+
+        # WebSocket support (Required for GraphQL subscriptions, TRPC, Socket.io)
+        proxy_http_version 1.1;
+        proxy_set_header Upgrade $http_upgrade;
+        proxy_set_header Connection "upgrade";
+    }
+}
+```
+
+---
+
+## 3. Server Hardening Fundamentals
+
+### SSH Security (`/etc/ssh/sshd_config`)
+```bash
+PermitRootLogin no           # Kill direct root login attacks immediately
+PasswordAuthentication no    # Enforce SSH key-based login ONLY
+Port 2022                    # (Optional) Obscurity defense against automated script-kiddie scanners
+```
+
+### Uncomplicated Firewall (UFW)
+A naked server with all ports open is a honeypot.
+```bash
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow 22/tcp      # Allow SSH
+sudo ufw allow 80/tcp      # Allow HTTP
+sudo ufw allow 443/tcp     # Allow HTTPS
+sudo ufw enable
+```
+
+### Fail2Ban
+Automatically bans IPs attempting brute force credential filling after 5 bad attempts.
+
+---
+
+## 4. Log Rotation (Prevent Disk Full Outages)
+
+A server will inevitably crash when `/var/log` consumes 100% of the disk.
+
+```bash
+# /etc/logrotate.d/myapp
+
+/var/www/myapp/logs/*.log {
+    daily                # Rotate every day
+    missingok            # Ignore if file is missing
+    rotate 14            # Keep 14 days of history
+    compress             # Gzip old logs
+    delaycompress        # Don't compress the one created yesterday
+    notifempty           # Do nothing if log is empty
+    copytruncate         # Copy then clear (avoids disrupting Node's open file handles)
+}
+```
+
+---
+
+## 🤖 LLM-Specific Traps (Server Management)
+
+1. **PM2 Fallacy:** AI frequently defaults to `pm2 start app.js` for production deployments. Demand raw `systemd`. It ensures startup order (Wait for network) and unified journalctl logging.
+2. **Root Execution:** Suggesting `ExecStart=npm start` under the `User=root` directive. The application process should operate under a restricted `appuser` daemon tier.
+3. **Missing Proxy Headers:** AI writing basic Nginx configs but omitting `X-Forwarded-For`. This causes the internal App to log all requests as coming from "127.0.0.1", instantly breaking IP Rate limiters.
+4. **WebSocket Blocking:** Forgetting to pass `Upgrade` headers in Nginx proxy setups, breaking realtime web applications silently.
+5. **Naked Node Ports:** Instructing users to run `node index.js` on `port 80`. Never natively bind unprivileged web processes to port 80. Bind to 3000 locally and use reverse proxy routing.
+6. **Firewall Blindness:** Assuming Docker auto-secures ports. Executing `docker run -p 8080:80` on Ubuntu completely bypasses UFW restrictions through iptables hooks, exposing the database to the internet. Always bind `127.0.0.1:8080:80`.
+7. **Password SSH Prompts:** Creating automation scripts utilizing raw passwords (e.g., `sshpass`). Always assume ed25519 identity keyfiles for automated CI deployments.
+8. **Log Rotation Void:** Neglecting log rotation in custom bash script loops, guaranteeing a 100% disk usage outage 3 months later.
+9. **GZIP Assumption:** Forgetting to enable `gzip on` in Nginx resulting in 10MB JSON payloads saturating the virtual server network adapter.
+10. **In-place Nginx Modding:** Editing `/etc/nginx/nginx.conf` directly instead of writing symlinks between the `sites-available` and `sites-enabled` architecture.
+
+---
+
+## 🏛️ Tribunal Integration
+
+### ✅ Pre-Flight Self-Audit
+```
+✅ Are persistent services orchestrated securely via `systemd` (not PM2)?
+✅ Does the systemd service explicitly execute as a non-root `appuser`?
+✅ Is the internal application shielded by an Nginx/Caddy reverse proxy?
+✅ Does the reverse proxy explicitly forward realtime `Upgrade` (WebSocket) headers?
+✅ Does the reverse proxy forward IP integrity headers (`X-Forwarded-For`)?
+✅ Has SSH `PasswordAuthentication` been disabled defensively?
+✅ Is UFW configured to strictly deny all incoming non-essential ports?
+✅ If suggesting Docker, are database/internal ports scoped to `127.0.0.1:X:Y`?
+✅ Have manual application log files been mapped in `logrotate.d`?
+✅ Has `PermitRootLogin` been set to `no`?
+```

package/.agent/skills/shadcn-ui-expert/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: shadcn-ui-expert
+description: shadcn/ui mastery. Installation, customization via tailwind.config, component extraction, state management with Radix Primitives, theme variables (CSS custom properties), dark mode implementations, and overriding default designs. Use when building or modifying shadcn/ui components in React/Next.js projects.
+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
+---
+
+# shadcn/ui Expert — Component Architecture Mastery
+
+> shadcn/ui is NOT a component library. It is a collection of re-usable components that you copy and paste into your apps.
+> You own the code. You own the styling. You own the accessibility.
+
+---
+
+## 1. Core Architecture
+
+shadcn/ui leverages two layers:
+1. **Radix UI Primitives**: Headless, fully accessible functionality (Focus management, ARIA, Keyboard nav).
+2. **Tailwind CSS**: The styling layer mapped over the headless components.
+
+```typescript
+// ❌ BAD: Re-inventing the wheel for accessibility
+const Select = ({ options }) => {
+  const [open, setOpen] = useState(false)
+  return <div onClick={() => setOpen(!open)}>...</div> // Breaks keyboard/screen readers
+}
+
+// ✅ GOOD: Using shadcn (Radix under the hood)
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from "@/components/ui/select"
+
+export function MySelect() {
+  return (
+    <Select>
+      <SelectTrigger className="w-[180px]">
+        <SelectValue placeholder="Theme" />
+      </SelectTrigger>
+      <SelectContent>
+        <SelectItem value="light">Light</SelectItem>
+        <SelectItem value="dark">Dark</SelectItem>
+      </SelectContent>
+    </Select>
+  )
+}
+```
+
+---
+
+## 2. Component Modification (You Own The Code)
+
+Do not treat `components/ui/*` as an immutable black box. You are *supposed* to modify them.
+
+### Adding Variants via `cva` (Class Variance Authority)
+
+```typescript
+import { cva, type VariantProps } from "class-variance-authority"
+
+// Adding a new "ghost-rounded" variant to the Button component
+const buttonVariants = cva(
+  "inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium transition-colors...",
+  {
+    variants: {
+      variant: {
+        default: "bg-primary text-primary-foreground shadow hover:bg-primary/90",
+        destructive: "bg-destructive text-destructive-foreground shadow-sm hover:bg-destructive/90",
+        outline: "border border-input bg-background shadow-sm hover:bg-accent hover:text-accent-foreground",
+        // YOUR CUSTOM VARIANT:
+        "ghost-rounded": "bg-transparent hover:bg-accent hover:text-accent-foreground rounded-full px-6",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+)
+```
+
+---
+
+## 3. Theming & Dark Mode (CSS Variables)
+
+shadcn/ui manages themes explicitly through CSS custom properties (variables), not Tailwind config hardcoding.
+
+```css
+/* app/globals.css */
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    /* ... */
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    --card: 222.2 84% 4.9%;
+    --primary: 217.2 91.2% 59.8%;
+    /* ... */
+  }
+}
+```
+
+Implementation with Tailwind v4 CSS-first configuration:
+```css
+/* Note how standard colors map directly to the CSS vars */
+@theme {
+  --color-background: hsl(var(--background));
+  --color-foreground: hsl(var(--foreground));
+  --color-primary: hsl(var(--primary));
+  --color-primary-foreground: hsl(var(--primary-foreground));
+  --radius-lg: var(--radius);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-sm: calc(var(--radius) - 4px);
+}
+```
+
+---
+
+## 4. Using the `cn` Utility
+
+The `cn` utility combines `clsx` (conditional classes) and `tailwind-merge` (fixing class conflicts).
+
+```typescript
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+
+// ❌ BAD: String concatenation breeds conflicts
+// hover:bg-blue-500 will fail if className contains hover:bg-red-500 earlier
+const className = `px-4 py-2 bg-blue-500 hover:bg-blue-600 ${props.className}`
+
+// ✅ GOOD: cn resolves conflicts correctly
+const className = cn("px-4 py-2 bg-blue-500 hover:bg-blue-600", props.className)
+```
+
+---
+
+## 5. Next.js App Router Integration
+
+### Modals / Dialogs inside Server Components
+Radix primitives (Dialog, Select, etc.) utilize React context and side effects. They must be Client Components.
+
+```typescript
+// ❌ BAD: Server Component trying to use a shadcn Dialog directly with state
+export default function Page() {
+  const [open, setOpen] = useState(false); // ERROR
+  return <Dialog open={open}>...</Dialog>
+}
+
+// ✅ GOOD: Extract the interactive part to a Client Component
+import { MyDialogComponent } from "./MyDialogComponent" // "use client" inside
+
+export default async function Page() {
+  const data = await fetchDb(); // Server Component fetches data
+  return <MyDialogComponent data={data} /> // Passes data to interactive client component
+}
+```
+
+---
+
+## 🤖 LLM-Specific Traps (shadcn/ui)
+
+1. **Treating it like an NPM Package:** AI asks to run `npm install shadcn-ui`. It's `npx shadcn@latest add [component]`. Components live in your tree (`components/ui`), not in `node_modules`.
+2. **Missing the `cn` utility:** AI writes generic template literals for className overrides, guaranteeing Tailwind specificity conflicts. Always import and wrap overrides in `cn()`.
+3. **Hardcoding Colors:** AI writes `bg-blue-500` inside standard components. shadcn demands semantic variables: `bg-primary`, `bg-accent`, `text-muted-foreground`.
+4. **Server Component Conflicts:** AI inserts interactive shadcn components (Dialog, Tabs, Accordion) directly into Next.js Server Components without creating a `"use client"` wrapper boundary.
+5. **Radix Primitive Ignorance:** AI attempts to pass `onClick` or `onChange` to headless wrapper elements like `<Select>` instead of `<SelectValue>` or tracking state properly via the `onValueChange` prop of the root component.
+6. **Forgetting `asChild`:** When wrapping existing buttons or links in shadcn Triggers, AI forgets the `asChild` prop, resulting in invalid HTML (e.g., `<button><button>click</button></button>`).
+7. **Modifying `node_modules/@radix-ui`:** AI tries to fix Radix a11y bugs by editing node_modules. Modify your local wrappers in `components/ui`, never Radix internals.
+8. **Broken Form Integration:** AI tries to manually string together standard React state with shadcn inputs. You MUST use `<Form>`, `<FormField>`, `<FormItem>`, and `react-hook-form` logic for proper shadcn forms.
+9. **Tailwind Class Order:** AI doesn't understand that `tailwind-merge` resolves conflicts from left to right. Overriding classes must be passed at the *end* of the `cn()` arguments.
+10. **Theme Variable Format:** AI writes `--primary: #3b82f6`. shadcn/ui CSS custom properties are strictly HSL scalar values WITHOUT the `hsl()` wrapper inside the root definition: `--primary: 221.2 83.2% 53.3%;`.
+
+---
+
+## 🏛️ Tribunal Integration
+
+### ✅ Pre-Flight Self-Audit
+```
+✅ Are interactive shadcn components safely inside "use client" boundaries?
+✅ Are classes merged dynamically using the `cn()` utility?
+✅ Are colors utilizing standard semantic vars (`bg-primary`) rather than hardcoded colors?
+✅ Did I remember the `asChild` prop when wrapping links/buttons in Triggers?
+✅ Are forms correctly using `react-hook-form` via the `<Form>` and `<FormField>` components?
+✅ Are CSS theme root variables using raw HSL scalar values?
+✅ Am I modifying the local `components/ui/*` files if new variants are needed?
+✅ Have I respected Radix a11y primitives (not inventing my own onClick focus handling)?
+✅ Are component variants properly declared using `cva`?
+✅ Did I pass user-supplied `className` props at the END of the `cn()` function to allow overrides?
+```