@caddis/cli 0.3.0 → 0.4.0

package/bundles/codex/.codex/skills/coding/codebase-audit/SKILL.md

@@ -0,0 +1,204 @@
+---
+name: codebase-audit
+context: fork
+description: Systematic codebase audit methodology for unfamiliar codebases before architecture or implementation work. Use for new codebase, unfamiliar codebase, pre-implementation audit, codebase review, technical due diligence, or onboarding to an existing project. Produces AUDIT-FINDINGS.md and QUESTIONS.md. Routes to Architect, Planner, or Code Reviewer agents.
+---
+
+# Codebase Audit Skill
+
+Systematic 6-step audit for entering an unfamiliar codebase before architecture changes, major features, or refactoring. Do not guess patterns — audit first.
+
+## 1. When to Apply This Skill
+
+**Trigger conditions:**
+- "I'm new to this codebase"
+- "Audit this project before we start building"
+- "I need to understand what's here before changing it"
+- "Pre-implementation review"
+- Any major feature in a codebase you haven't worked in this session
+
+**Do not skip the audit** even when the task seems small — hidden coupling causes broken assumptions.
+
+## 2. Audit Scope — 20 Areas
+
+| # | Area | What to Look For |
+|---|---|---|
+| 1 | **Architecture** | Monolith/microservice/monorepo, layer separation, module boundaries |
+| 2 | **Entry Points** | Main files, router setup, CLI entry, exports index |
+| 3 | **Framework & Runtime** | React version, Next.js, FastAPI, Django, Node version, Python version |
+| 4 | **Dependencies** | `package.json`/`pyproject.toml` — packages, versions, peer deps, outdated |
+| 5 | **Code Quality** | Lint config, formatter, TypeScript strict mode, type coverage |
+| 6 | **Testing** | Test runner, coverage %, which layers are tested, missing tests |
+| 7 | **Security Posture** | Auth implementation, env var usage, hardcoded secrets, CORS |
+| 8 | **Documentation** | README completeness, inline comments, API docs |
+| 9 | **Performance Signals** | Caching, lazy loading, database indexes, N+1 queries |
+| 10 | **DevOps / CI** | Build commands, CI config, deployment method, Dockerfile |
+| 11 | **API Design** | REST conventions, versioning, error response format, input validation |
+| 12 | **Data Layer** | ORM vs raw SQL, migration strategy, schema location |
+| 13 | **State Management** | Client state (Zustand, Redux, Context), server state (React Query) |
+| 14 | **Error Handling** | Global error boundary, unhandled promise rejections, logging |
+| 15 | **Environment Config** | `.env.example`, `pydantic-settings`, config validation on startup |
+| 16 | **Dead Code / Tech Debt** | TODOs, commented-out code, unused packages, deprecated calls |
+| 17 | **Naming Conventions** | Consistent file/folder naming, component vs module patterns |
+| 18 | **Shared Libraries** | Utility functions, hooks, services — shared vs duplicated |
+| 19 | **Accessibility** | ARIA usage, keyboard nav, color contrast, skip-nav |
+| 20 | **Observability** | Logging format, tracing, health endpoints, error reporting |
+
+## 3. 6-Step Audit Method
+
+### Step 1 — Map the Repository
+```
+actions:
+  - List top-level directories and understand intent of each
+  - Identify the project type (app, library, monorepo, microservice)
+  - Read README.md fully — note setup instructions, known issues
+  - Check for CONTRIBUTING.md, ARCHITECTURE.md, or ADR folders
+```
+
+### Step 2 — Find Entry Points
+```
+actions:
+  - Identify main application entry (main.py, app.py, src/index.ts, src/main.ts)
+  - Trace the request lifecycle from entry to response (1 complete path)
+  - Identify router/controller/handler layers
+  - Find test entry (jest.config.ts, vite.config.ts, pytest.ini/pyproject.toml)
+  - Find build entry (package.json scripts, Makefile, Dockerfile)
+```
+
+### Step 3 — Dependencies and Versions
+```
+actions:
+  - Read package.json / pyproject.toml — note major dependencies and versions
+  - Check for deprecated or significantly outdated packages
+  - Identify direct vs transitive dependency conflicts
+  - Note peer dependency version mismatches
+  - Check for security advisories (mental note or npm audit / pip-audit)
+```
+
+### Step 4 — Audit by Severity
+```
+For each area in §2, assign:
+  🔴 CRITICAL — Security vulnerability, data loss risk, broken functionality
+  🟡 WARNING  — Performance issue, tech debt, missing validation
+  🟢 NOTE     — Style inconsistency, minor improvement opportunity
+  ⚪ OK       — Meets expectations, no action needed
+```
+
+### Step 5 — Compile Questions
+```
+For every assumption or ambiguity discovered:
+  - Business context: "Why does X exist? Is it still needed?"
+  - Architecture: "Is this pattern intentional or historical?"
+  - Implementation: "Is there a newer pattern preferred for this?"
+  - Scope: "Which areas are off-limits for this change?"
+```
+
+### Step 6 — Write Deliverables
+Write two files in the project root (or `docs/` if it exists):
+- `AUDIT-FINDINGS.md`
+- `QUESTIONS.md`
+
+## 4. Output Templates
+
+### `AUDIT-FINDINGS.md`
+```markdown
+# Codebase Audit Findings
+
+**Project**: [name]
+**Audited**: [date]
+**Scope**: [what was covered]
+
+## Summary
+[2–3 sentence high-level assessment]
+
+## Critical Findings 🔴
+
+### CRIT-001: [Title]
+**File**: `path/to/file.ts` (line N)
+**Issue**: [What is wrong and why]
+**Risk**: [What can go wrong]
+**Recommendation**: [Specific fix]
+
+## Warnings 🟡
+
+### WARN-001: [Title]
+**File**: `path/to/file.py`
+**Issue**: [What needs attention]
+**Recommendation**: [Specific improvement]
+
+## Notes 🟢
+
+- [Minor observations, style, preferences]
+
+## Architecture Overview
+[Brief description of what was found — layers, patterns, notable design decisions]
+
+## Scope for Current Task
+Based on the requested change, these areas are in scope: …
+These areas should NOT be touched: …
+```
+
+### `QUESTIONS.md`
+```markdown
+# Pre-Implementation Questions
+
+**For**: [next agent or human reviewer]
+**Context**: [what we're about to build]
+
+## Blocking Questions (must answer before code changes)
+
+### Q1: [Question]
+**Context**: [why this matters]
+**Impact if wrong**: [what breaks]
+
+### Q2: [Question]
+
+## Advisory Questions (inform decisions but don't block)
+
+### Q3: [Question]
+
+## Assumptions Made
+If we proceed without answers, these assumptions apply:
+- [assumption 1]
+- [assumption 2]
+```
+
+## 5. Severity Tags
+
+| Tag | Code | Meaning |
+|---|---|---|
+| 🔴 Critical | `CRIT-NNN` | Fix before any changes proceed |
+| 🟡 Warning | `WARN-NNN` | Address in current or next sprint |
+| 🟢 Note | `NOTE-NNN` | Backlog item or stylistic observation |
+| ⚪ OK | — | No action needed |
+
+## 6. Handoff Guidance
+
+After completing the audit:
+
+| Finding Type | Route To |
+|---|---|
+| Architecture redesign needed | `@Architect` — provide `AUDIT-FINDINGS.md` |
+| Implementation can proceed with caution | `@Planner` — provide findings + questions |
+| Major quality/security issues | `@Code-Reviewer` + `@Security-Analyst` |
+| Only minor notes, clear path | Proceed directly with `@Implement` or `@Anchor` |
+
+### Prompt template for handoff:
+```
+@[Agent]: I've completed a codebase audit. 
+Findings: [link or inline AUDIT-FINDINGS.md]
+Blocking questions: [key Q from QUESTIONS.md]
+The task is: [original task description]
+Please [design solution / create plan / review / implement] with these findings in mind.
+```
+
+## 7. Checklist
+
+- [ ] README.md read fully
+- [ ] Entry point traced end-to-end (one complete request/render cycle)
+- [ ] All 20 audit areas assessed (even if just ⚪ OK)
+- [ ] Critical findings have file + line citation
+- [ ] `AUDIT-FINDINGS.md` written to disk
+- [ ] `QUESTIONS.md` written to disk
+- [ ] Blocking questions identified separately
+- [ ] Agent handoff prompt prepared

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())