@caddis/cli 0.3.0 → 0.4.1

package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: dashboard-perf-sweep
+context: fork
+description: Re-measure an app's dashboard/API endpoints for load-time regressions and decide, with a documented checklist (not a black-box verdict), whether a slow one is a candidate for the rs-kit summary-table refresher pattern — or needs an index, keyset paging, gzip, or nothing at all. Use when the user says "sweep dashboard performance", "check if this app needs rs-kit", "re-measure the perf tracker", "is this endpoint a refresher candidate", or when a dashboard-performance-tracker.md is stale and needs re-validating. Read-only by default (dev servers only; prod requires an explicit opt-in and human confirmation) and human-invoked, never scheduled -- it surfaces candidates, it does not enroll them.
+---
+
+# dashboard-perf-sweep — re-measure, then judge the shape, not just the time
+
+Today an app "earns" the rs-kit refresher pattern only when someone happens to be doing unrelated
+work on it, hits a slow page, and measures it properly. That worked for a couple of apps in the
+fleet, but a snapshot measurement goes stale — a page added last month, or a table that crossed a
+growth threshold since, has no mechanism to surface itself. This skill re-measures on demand.
+
+**What already exists and must NOT be rebuilt:** every app in the fleet has its own
+`.caddis/kb/dashboard-performance-tracker.md` with real baseline measurements. The gap this closes
+is **re-measurement and re-judgment**, not first-time discovery.
+
+## Explicit scope guardrails — do not relax without a new conversation
+
+- **Read-only except the final tracker update.** No code changes, no schema changes, ever. The only
+  write this skill makes is a diffable update to the target app's own `dashboard-performance-tracker.md`.
+- **Dev by default.** Measuring against prod requires an explicit opt-in flag from the user AND, per
+  this project's convention for risky/hard-to-reverse actions, confirmation before hitting a live
+  service.
+- **Human-invoked, not scheduled.** Run this when a person chooses to — never wire it into a cron job
+  or background automation. It surfaces candidates; it does not enroll them.
+- **rs-kit is one of several possible recommendations, never the only output.** The checklist below
+  must be able to conclude "needs an index," "needs keyset paging," "needs gzip/trimmed fields,"
+  "not currently a candidate" — recommending rs-kit only for the specific aggregation shape.
+
+## The decision model — two gates, not one number
+
+**Gate 1 — time (mechanical).** `DASHBOARD-PERFORMANCE-STANDARD.md` Rule 6: the first, uncached load
+of any dashboard endpoint must finish in **under ~1 second**. The harness script below applies this
+gate automatically per endpoint. Passing gate 1 does **not** mean rs-kit — it just means "look closer."
+
+**Gate 2 — shape (judgment, applied by you the agent, never automated).** rs-kit fixes exactly one
+shape: a query that recomputes `O(all rows ever stored)` per request, against data that keeps
+growing. Time alone is not sufficient evidence — the fleet's own history proves it:
+
+| App | Cold time | Root cause | rs-kit? |
+|---|---|---|---|
+| App A | worst >60s, 5 real breaches | recurring full-table aggregation | **YES** |
+| App B (pre-fix) | 14s–60s+ across several endpoints | recurring full-table aggregation | **YES** |
+| App C | 10.3s | a single ~158MB LOB payload on 9.1k rows, not aggregation | **NO** — SQL aggregate + gzip |
+| App D | 1.9s | cold JSON parse, no DB at all in prod | **NO** — warm the provider |
+| App E | 202ms | n/a — never crossed gate 1 | **NO** |
+
+A naive "slow ⇒ recommend rs-kit" tool would have wrongly flagged App C and App D. That already
+happened once before the shape distinction was made explicit — don't repeat it.
+
+## Step 1 — build the endpoint list for this app
+
+The tracker files are semi-structured (page names + backtick route fragments in a markdown table),
+not a clean machine-parseable list — extract the list yourself, per app, each run:
+
+1. Read the target app's `.caddis/kb/dashboard-performance-tracker.md` — pull every "Page / endpoint"
+   entry, in particular anything marked ⏳ pending or not re-measured recently.
+2. If the app has a `UI_PAGE_GUIDE.md` (check root and `docs/reference/`), cross-check it for pages
+   **not yet in the tracker** — this is what catches drift, not just re-running the same old list. Not
+   every app has one; if it's missing, say so explicitly rather than silently only using the tracker.
+3. Write the result as a JSON file matching the harness's input shape:
+   ```json
+   [
+     {"name": "Historical Trends chart", "method": "GET", "path": "/api/trends/daily"},
+     {"name": "IW grid", "method": "POST", "path": "/raworkbench/investigation/query", "json": {}}
+   ]
+   ```
+4. Confirm with the user (or the app's own `run`/`webapp-testing` conventions) how to reach the dev
+   instance safely, and what auth the endpoints need (open / token / session cookie) — pass it via
+   `--header`.
+
+## Step 2 — start the dev server, then run the harness
+
+Use the app's own `run` skill/convention to start it — this skill does not start dev servers itself,
+only measures an already-reachable URL.
+
+**Use `127.0.0.1`, never the hostname `localhost`, in `--base-url`.** On Windows, Python's `urllib`
+resolves `localhost` dual-stack (tries IPv6 `::1` first) and can add a **spurious, rock-steady
+~1000ms** to every single request — cold *and* warm, on every endpoint including the framework's own
+static docs page. It looks exactly like a real, uniform perf problem (equal cold/warm, present on
+trivial routes too) and is not one. This cost real time during this skill's own validation (§
+Validating below) before `127.0.0.1` was substituted and the true numbers — sub-15ms — appeared. If a
+sweep ever comes back with a suspiciously uniform floor across unrelated endpoints, first time a
+`/docs` or `/openapi.json` route on the same base URL before trusting the data.
+
+```bash
+python <skill-dir>/scripts/perf_sweep.py --base-url http://127.0.0.1:<port> --endpoints endpoints.json
+python <skill-dir>/scripts/perf_sweep.py --base-url http://127.0.0.1:<port> --endpoints endpoints.json \
+  --header "Cookie: session=..." --output report.json
+```
+
+Cold = first request after the dev server's fresh start (or right after a cache-bust if it can't be
+restarted cheaply); warm = the immediate second request. The report flags gate-1 breaches and prints
+the cold/warm ratio — a big ratio with no cache in between already points at a query-shape problem,
+not a cache-TTL one. **A page that errors or times out is a finding, not a script failure** — it's
+printed as `[ERROR]`, never silently dropped.
+
+## Step 3 — apply the gate-2 checklist to every gate-1 breach
+
+Force these questions, in order, for each slow endpoint — don't skip to a verdict:
+
+1. **Does response size explain most of the time** (large payload, not a slow query)? → not rs-kit;
+   recommend trimming fields / gzip / virtualization.
+2. **Is the slow part parsing/serialization, not the DB round-trip?** → not rs-kit; recommend
+   caching/warming the parsed form (App D precedent).
+3. **Does the query scale with total stored rows rather than the response size** — read the actual
+   SQL/query plan, not just the timing — **and is the same aggregation recomputed per request on data
+   that keeps growing?** → candidate for rs-kit.
+4. **Is it slow only at deep pagination (OFFSET)?** → not rs-kit; recommend keyset paging
+   (`exception_id`-style cursor, App B precedent).
+5. **Is a specific WHERE clause unseekable** (function-wrapped column, NVARCHAR/VARCHAR param
+   mismatch)? → not rs-kit; recommend an index or a param-type fix.
+
+Link findings to real fleet precedent (the table above, the `nvarchar-param-varchar-column-scan`
+pattern, the keyset-paging work) rather than describing fixes in the abstract — every category here
+has already been solved once in this fleet.
+
+## Step 4 — update the tracker, diffably
+
+Update the target app's own `dashboard-performance-tracker.md` in place with the new measurements and
+verdicts, so drift becomes visible over time in the diff. Never silently overwrite it without the user
+being able to see a before/after. Print a summary alongside the file edit.
+
+## Validating this skill against known ground truth
+
+Before trusting a new app's output, or after changing the checklist, run the sweep against two
+already-known apps in your fleet and confirm it reproduces the **already-established, human-verified**
+conclusion for each: one that's genuinely fast (should conclude "not a candidate") and one with a
+known aggregation breach (should conclude "aggregation-shaped, rs-kit candidate" for the pages
+already identified). If the output disagrees with the known-good conclusion for either, that's a
+checklist bug — fix the checklist, don't rationalize the disagreement away.

package/bundles/codex/.codex/skills/coding/dashboard-perf-sweep/scripts/perf_sweep.py

@@ -0,0 +1,249 @@
+#!/usr/bin/env python3
+"""Cold/warm HTTP timing harness for the dashboard-perf-sweep skill.
+
+Given a base URL and a list of endpoints, measures a COLD request (first hit) and a WARM
+request (immediately after) per endpoint, safely: a timeout or connection error on one endpoint
+is recorded as a finding, never a crash of the whole sweep (DASHBOARD-PERFORMANCE-STANDARD.md
+Rule 6 gate-1 mechanics; the huge cold/warm gap without a cache in between is itself diagnostic
+of a query-shape problem, not a cache-TTL one).
+
+This harness does NOT start dev servers or know anything about a specific app -- that's the
+`run` skill's job. It only measures a URL that is already reachable. stdlib-only (urllib), no
+install, matching the other caddis tool scripts (oss_review.py etc.).
+
+CLI:
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json --output report.json
+  python perf_sweep.py --base-url http://localhost:8000 --endpoints endpoints.json --gate1-seconds 1.0
+
+endpoints.json shape (a JSON list):
+  [
+    {"name": "Historical Trends chart", "method": "GET", "path": "/api/trends/daily"},
+    {"name": "IW grid", "method": "POST", "path": "/raworkbench/investigation/query",
+     "json": {"filters": {}}, "headers": {"Authorization": "Bearer ..."}}
+  ]
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import time
+import urllib.error
+import urllib.request
+from dataclasses import asdict, dataclass, field
+from typing import Any
+
+DEFAULT_TIMEOUT_SECONDS = 30.0
+DEFAULT_GATE1_SECONDS = 1.0  # DASHBOARD-PERFORMANCE-STANDARD.md Rule 6
+
+
+@dataclass
+class RequestResult:
+    ok: bool
+    status: int | None = None
+    elapsed_ms: float | None = None
+    error: str | None = None
+
+
+@dataclass
+class EndpointResult:
+    name: str
+    method: str
+    path: str
+    cold: RequestResult
+    warm: RequestResult | None = None
+    gate1_breach: bool = False
+
+
+@dataclass
+class SweepReport:
+    base_url: str
+    gate1_seconds: float
+    endpoints: list[EndpointResult] = field(default_factory=list)
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "base_url": self.base_url,
+            "gate1_seconds": self.gate1_seconds,
+            "endpoints": [
+                {
+                    "name": e.name,
+                    "method": e.method,
+                    "path": e.path,
+                    "cold": asdict(e.cold),
+                    "warm": asdict(e.warm) if e.warm else None,
+                    "gate1_breach": e.gate1_breach,
+                }
+                for e in self.endpoints
+            ],
+        }
+
+
+def _do_request(
+    url: str,
+    method: str,
+    *,
+    json_body: dict[str, Any] | None = None,
+    headers: dict[str, str] | None = None,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+) -> RequestResult:
+    """One timed HTTP request. Never raises -- a timeout/connection/HTTP error becomes a
+    RequestResult with ok=False and a human-readable error, which is itself a sweep finding."""
+    data = None
+    req_headers = dict(headers or {})
+    if json_body is not None:
+        data = json.dumps(json_body).encode("utf-8")
+        req_headers.setdefault("Content-Type", "application/json")
+
+    req = urllib.request.Request(url, data=data, headers=req_headers, method=method)
+    start = time.perf_counter()
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            resp.read()
+            elapsed_ms = (time.perf_counter() - start) * 1000.0
+            return RequestResult(ok=True, status=resp.status, elapsed_ms=elapsed_ms)
+    except urllib.error.HTTPError as exc:
+        # An HTTP error status still completed a round trip -- timing is a real finding.
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, status=exc.code, elapsed_ms=elapsed_ms, error=f"HTTP {exc.code}")
+    except urllib.error.URLError as exc:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, elapsed_ms=elapsed_ms, error=f"connection error: {exc.reason}")
+    except TimeoutError:
+        elapsed_ms = (time.perf_counter() - start) * 1000.0
+        return RequestResult(ok=False, elapsed_ms=elapsed_ms, error=f"timeout after {timeout}s")
+
+
+def sweep_endpoint(
+    base_url: str,
+    endpoint: dict[str, Any],
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    gate1_seconds: float = DEFAULT_GATE1_SECONDS,
+    warm: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> EndpointResult:
+    method = endpoint.get("method", "GET").upper()
+    path = endpoint["path"]
+    url = base_url.rstrip("/") + path
+    headers = dict(extra_headers or {})
+    headers.update(endpoint.get("headers", {}))
+    json_body = endpoint.get("json")
+
+    cold = _do_request(url, method, json_body=json_body, headers=headers, timeout=timeout)
+    warm_result = None
+    if warm:
+        warm_result = _do_request(url, method, json_body=json_body, headers=headers, timeout=timeout)
+
+    gate1_breach = bool(cold.ok and cold.elapsed_ms is not None and cold.elapsed_ms / 1000.0 > gate1_seconds)
+    return EndpointResult(
+        name=endpoint.get("name", path),
+        method=method,
+        path=path,
+        cold=cold,
+        warm=warm_result,
+        gate1_breach=gate1_breach,
+    )
+
+
+def sweep(
+    base_url: str,
+    endpoints: list[dict[str, Any]],
+    *,
+    timeout: float = DEFAULT_TIMEOUT_SECONDS,
+    gate1_seconds: float = DEFAULT_GATE1_SECONDS,
+    warm: bool = True,
+    extra_headers: dict[str, str] | None = None,
+) -> SweepReport:
+    report = SweepReport(base_url=base_url, gate1_seconds=gate1_seconds)
+    for endpoint in endpoints:
+        report.endpoints.append(
+            sweep_endpoint(
+                base_url,
+                endpoint,
+                timeout=timeout,
+                gate1_seconds=gate1_seconds,
+                warm=warm,
+                extra_headers=extra_headers,
+            )
+        )
+    return report
+
+
+def format_report(report: SweepReport) -> str:
+    lines = [f"Sweep: {report.base_url}  (gate 1 = {report.gate1_seconds}s cold, uncached)", ""]
+    for e in report.endpoints:
+        if not e.cold.ok:
+            lines.append(f"  [ERROR]  {e.method:5s} {e.path:45s}  {e.cold.error}")
+            continue
+        flag = "SLOW " if e.gate1_breach else "     "
+        cold_s = f"{e.cold.elapsed_ms:8.1f}ms"
+        warm_s = f"{e.warm.elapsed_ms:8.1f}ms" if e.warm and e.warm.ok else "n/a"
+        gap = ""
+        if e.warm and e.warm.ok and e.cold.elapsed_ms and e.warm.elapsed_ms:
+            ratio = e.cold.elapsed_ms / max(e.warm.elapsed_ms, 0.01)
+            if ratio > 3:
+                gap = f"  (cold/warm {ratio:.1f}x -- likely query-shape, not cache-TTL)"
+        lines.append(f"  {flag}{e.method:5s} {e.path:45s}  cold={cold_s}  warm={warm_s}{gap}")
+    breaches = [e for e in report.endpoints if e.gate1_breach]
+    errors = [e for e in report.endpoints if not e.cold.ok]
+    problems = breaches + errors
+    lines.append("")
+    lines.append(
+        f"{len(problems)}/{len(report.endpoints)} endpoint(s) have a problem "
+        f"({len(breaches)} slow, {len(errors)} errored/timed out -- a timeout is a WORSE "
+        f"signal than a gate-1 breach, not a lesser one)."
+    )
+    if problems:
+        lines.append("Not itself a rs-kit verdict -- apply the shape checklist (SKILL.md) next.")
+    return "\n".join(lines)
+
+
+def _parse_header(value: str) -> tuple[str, str]:
+    if ":" not in value:
+        raise argparse.ArgumentTypeError(f"--header must be 'Key: Value', got {value!r}")
+    key, _, val = value.partition(":")
+    return key.strip(), val.strip()
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter)
+    parser.add_argument("--base-url", required=True, help="e.g. http://localhost:8703")
+    parser.add_argument("--endpoints", required=True, help="path to a JSON file (see module docstring)")
+    parser.add_argument("--timeout", type=float, default=DEFAULT_TIMEOUT_SECONDS)
+    parser.add_argument("--gate1-seconds", type=float, default=DEFAULT_GATE1_SECONDS)
+    parser.add_argument("--no-warm", action="store_true", help="skip the warm (second) request")
+    parser.add_argument("--header", action="append", default=[], type=_parse_header,
+                         help="extra header applied to every request, repeatable: --header 'Cookie: session=...'")
+    parser.add_argument("--output", help="also write the JSON report to this path")
+    args = parser.parse_args(argv)
+
+    with open(args.endpoints, encoding="utf-8") as f:
+        endpoints = json.load(f)
+    if not isinstance(endpoints, list):
+        print(f"[FAIL] {args.endpoints} must contain a JSON list of endpoint objects", file=sys.stderr)
+        return 2
+
+    report = sweep(
+        args.base_url,
+        endpoints,
+        timeout=args.timeout,
+        gate1_seconds=args.gate1_seconds,
+        warm=not args.no_warm,
+        extra_headers=dict(args.header),
+    )
+
+    print(format_report(report))
+    if args.output:
+        with open(args.output, "w", encoding="utf-8") as f:
+            json.dump(report.to_dict(), f, indent=2)
+        print(f"\nWrote {args.output}")
+
+    breaches = [e for e in report.endpoints if e.gate1_breach]
+    errors = [e for e in report.endpoints if not e.cold.ok]
+    return 1 if (breaches or errors) else 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/bundles/codex/.codex/skills/coding/error-handling/SKILL.md

@@ -0,0 +1,260 @@
+---
+name: error-handling
+description: Error handling patterns for Python and TypeScript applications. Use when designing error hierarchies, implementing retry logic, building error boundaries, or establishing logging strategies. Covers custom exceptions, result types, circuit breakers, and user-facing error messages.
+---
+
+# Error Handling Skill
+
+Errors are not exceptional — they are part of the contract. This skill defines how to classify, propagate, and recover from errors consistently.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- Designing error handling for a new service or feature
+- "How should we handle errors in this module?"
+- Building retry logic or circuit breakers
+- Reviewing code with bare `except:` or swallowed errors
+- Establishing error handling conventions for a project
+
+## 2. Error Classification
+
+Every error falls into one of three categories. Handle each differently.
+
+| Category | Retryable? | User Action? | Example |
+|----------|-----------|-------------|---------|
+| **Transient** | Yes | None (auto-retry) | Network timeout, DB connection dropped, rate limit |
+| **Operational** | No | Inform user | Invalid input, resource not found, insufficient permissions |
+| **Fatal** | No | Alert team | Corrupted state, config missing, unrecoverable assertion |
+
+## 3. Python Exception Hierarchy
+
+Build domain-specific exceptions. Never raise raw `Exception`.
+
+```python
+class AppError(Exception):
+    """Base error for the application."""
+    def __init__(self, message: str, code: str | None = None):
+        self.message = message
+        self.code = code or self.__class__.__name__
+        super().__init__(self.message)
+
+# Operational errors (expected, handled gracefully)
+class NotFoundError(AppError):
+    """Resource does not exist."""
+
+class ValidationError(AppError):
+    """Input validation failed."""
+
+class AuthorizationError(AppError):
+    """User not authorized for this action."""
+
+# Transient errors (retry-eligible)
+class TransientError(AppError):
+    """Temporary failure — safe to retry."""
+
+class ExternalServiceError(TransientError):
+    """External API call failed."""
+
+class DatabaseConnectionError(TransientError):
+    """Database connection lost."""
+```
+
+### Usage Patterns
+
+```python
+# ✅ GOOD: Specific exception with context
+def get_user(user_id: str) -> User:
+    user = repo.find_by_id(user_id)
+    if user is None:
+        raise NotFoundError(f"User {user_id} not found")
+    return user
+
+# ✅ GOOD: Catch specific, re-raise as domain error
+def fetch_external_data(url: str) -> dict:
+    try:
+        response = httpx.get(url, timeout=10)
+        response.raise_for_status()
+        return response.json()
+    except httpx.TimeoutException as e:
+        raise ExternalServiceError(f"Timeout calling {url}") from e
+    except httpx.HTTPStatusError as e:
+        raise ExternalServiceError(f"HTTP {e.response.status_code} from {url}") from e
+
+# ❌ BAD: Bare except swallows everything
+try:
+    result = process()
+except:
+    pass
+
+# ❌ BAD: Catching too broadly
+try:
+    result = process()
+except Exception:
+    logger.error("Something went wrong")
+    return None  # Hides the real error
+```
+
+## 4. TypeScript Error Patterns
+
+### Result Type (for expected failures)
+
+```typescript
+type Result<T, E = Error> =
+  | { ok: true; value: T }
+  | { ok: false; error: E };
+
+function parseConfig(raw: string): Result<Config, ValidationError> {
+  try {
+    const parsed = JSON.parse(raw);
+    if (!isValidConfig(parsed)) {
+      return { ok: false, error: new ValidationError("Invalid config shape") };
+    }
+    return { ok: true, value: parsed as Config };
+  } catch {
+    return { ok: false, error: new ValidationError("Invalid JSON") };
+  }
+}
+
+// Usage — caller must handle both cases
+const result = parseConfig(rawInput);
+if (!result.ok) {
+  showError(result.error.message);
+  return;
+}
+useConfig(result.value);
+```
+
+### Error Boundaries (React)
+
+```tsx
+'use client';
+import { Component, type ReactNode } from 'react';
+
+interface Props { children: ReactNode; fallback: ReactNode; }
+interface State { hasError: boolean; }
+
+export class ErrorBoundary extends Component<Props, State> {
+  state: State = { hasError: false };
+
+  static getDerivedStateFromError(): State {
+    return { hasError: true };
+  }
+
+  componentDidCatch(error: Error, info: React.ErrorInfo) {
+    console.error('Component error:', error, info.componentStack);
+    // Report to error tracking service
+  }
+
+  render() {
+    return this.state.hasError ? this.props.fallback : this.props.children;
+  }
+}
+```
+
+## 5. Retry with Exponential Backoff
+
+```python
+import asyncio
+import random
+from loguru import logger
+
+async def retry_with_backoff(
+    fn,
+    max_retries: int = 3,
+    base_delay: float = 1.0,
+    max_delay: float = 30.0,
+    retryable_exceptions: tuple = (TransientError,),
+):
+    """Retry a function with exponential backoff and jitter."""
+    for attempt in range(max_retries + 1):
+        try:
+            return await fn()
+        except retryable_exceptions as e:
+            if attempt == max_retries:
+                logger.error(f"All {max_retries} retries exhausted: {e}")
+                raise
+            delay = min(base_delay * (2 ** attempt), max_delay)
+            jitter = random.uniform(0, delay * 0.1)
+            logger.warning(f"Attempt {attempt + 1} failed: {e}. Retrying in {delay:.1f}s")
+            await asyncio.sleep(delay + jitter)
+```
+
+## 6. FastAPI Error Handling
+
+```python
+from fastapi import FastAPI, Request
+from fastapi.responses import JSONResponse
+from loguru import logger
+
+app = FastAPI()
+
+@app.exception_handler(NotFoundError)
+async def not_found_handler(request: Request, exc: NotFoundError):
+    return JSONResponse(status_code=404, content={"error": exc.code, "message": exc.message})
+
+@app.exception_handler(ValidationError)
+async def validation_handler(request: Request, exc: ValidationError):
+    return JSONResponse(status_code=422, content={"error": exc.code, "message": exc.message})
+
+@app.exception_handler(AuthorizationError)
+async def auth_handler(request: Request, exc: AuthorizationError):
+    return JSONResponse(status_code=403, content={"error": exc.code, "message": exc.message})
+
+@app.exception_handler(Exception)
+async def unhandled_handler(request: Request, exc: Exception):
+    logger.exception(f"Unhandled error on {request.method} {request.url}")
+    # Never expose internal details to the client
+    return JSONResponse(status_code=500, content={"error": "InternalError", "message": "An internal error occurred."})
+```
+
+## 7. Logging Errors Correctly
+
+```python
+from loguru import logger
+
+# ✅ GOOD: Log with context, not just the message
+logger.error(f"Failed to process order {order_id}: {e}", order_id=order_id, customer_id=customer_id)
+
+# ✅ GOOD: Use exception() to capture stack trace
+try:
+    process_order(order)
+except Exception as e:
+    logger.exception(f"Order processing failed for {order.id}")
+    raise
+
+# ❌ BAD: Logging sensitive data
+logger.error(f"Auth failed for {username} with password {password}")
+
+# ❌ BAD: Logging without context
+logger.error("Something failed")
+```
+
+## 8. Error Message Guidelines
+
+| Audience | Include | Exclude |
+|----------|---------|---------|
+| **End user** | What happened, what to do next | Stack traces, internal IDs, SQL errors |
+| **Developer (logs)** | Full context, request ID, stack trace | User passwords, tokens, PII |
+| **API consumer** | Error code, human message, field-level detail | Server internals, file paths |
+
+```python
+# User-facing message
+"Unable to load your dashboard. Please try again in a few minutes."
+
+# API response
+{"error": "ValidationError", "message": "Email format is invalid", "field": "email"}
+
+# Log entry
+"Validation failed on POST /api/users: email='not-an-email' — rejected by regex validator"
+```
+
+## 9. Anti-Patterns
+
+| Anti-Pattern | Problem | Fix |
+|---|---|---|
+| Bare `except:` / `except Exception:` | Catches KeyboardInterrupt, SystemExit | Catch specific exceptions |
+| `return None` on error | Caller has no idea what went wrong | Raise typed exception |
+| Logging and re-raising | Double logging, noisy | Log at the boundary, not at every layer |
+| String error codes | Typos, no autocomplete | Enum or class-based error codes |
+| Swallowing errors in background tasks | Silent failures, data loss | Log + alert + dead-letter queue |
+| Generic "Something went wrong" | User can't self-serve | Specific message + action hint |