@caddis/cli 0.2.1 → 0.2.3

package/bundles/antigravity-plugin/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis",
-  "version": "1.3.40",
+  "version": "1.3.47",
   "description": "caddis — agent-agnostic dev harness as an Antigravity (agy) plugin: TDD skills + commands, single-sourced with the Claude Code plugin."
 }

package/bundles/antigravity-plugin/skills/_registry.md

@@ -16,6 +16,7 @@
 | Code Review | `code-review/` | Automated code review for pull requests using specialized review patterns. Analyzes code for quality, security, performance, and best practices. Use when reviewing code changes, PRs, or doing code audits. |
 | Codebase Audit | `codebase-audit/` | 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. |
 | Cross Review | `cross-review/` | Cross-vendor code review of the current diff — a second-vendor model (DeepSeek/GLM/any OpenAI-compatible endpoint) reviews your changes to catch bugs a same-vendor reviewer misses |
+| Dashboard Perf Sweep | `dashboard-perf-sweep/` | 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. |
 | Error Handling | `error-handling/` | 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. |
 | Fastapi Dev | `fastapi-dev/` | Build FastAPI backends with standard patterns, error handling, and testing |
 | Javascript Typescript | `javascript-typescript/` | JavaScript and TypeScript development with ES6+, Node.js, React, and modern web frameworks. Use for frontend, backend, or full-stack JavaScript/TypeScript projects. |
@@ -46,6 +47,7 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Code Documentation | `code-documentation/` | Writing effective code documentation - API docs, README files, inline comments, and technical guides. Use for documenting codebases, APIs, or writing developer guides. |
+| Explainer Doc | `explainer-doc/` | Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case. |
 | Technical Writing | `technical-writing/` | Technical documentation best practices for READMEs, API docs, architecture docs, runbooks, and developer guides. Use when writing or reviewing documentation, creating onboarding guides, or establishing documentation standards. |
 | Writing Plans | `writing-plans/` | Use when you have a spec or requirements for a multi-step task, before touching code |
 

package/bundles/antigravity-plugin/skills/cross-review/SKILL.md

@@ -17,11 +17,14 @@ overridable via `CADDIS_KEYS_FILE`). If your keys file is populated, no env setu
 Details: the `coding/cross-review` skill and the **Providers & keys** guide.
 
 ## Run it
-The tool ships at `.github/tools/oss_review.py` (stdlib-only, no install):
+Locate the tool (stdlib-only, no install), in order:
+- `.github/tools/oss_review.py` — this project vendors its own copy.
+- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every install has this;
+  use it whenever the project has no local copy).
 ```
-python .github/tools/oss_review.py                     # DeepSeek eyes (default)
-python .github/tools/oss_review.py --provider glm      # GLM eyes
-python .github/tools/oss_review.py --range $ARGUMENTS  # review a git range, e.g. origin/main..HEAD
+python <resolved-path>/oss_review.py                     # DeepSeek eyes (default)
+python <resolved-path>/oss_review.py --provider glm      # GLM eyes
+python <resolved-path>/oss_review.py --range $ARGUMENTS  # review a git range, e.g. origin/main..HEAD
 ```
 Optional: `--base-url <url>`, `--model <id>` (env always overrides the preset).
 **Alternate the provider between reviews** (DeepSeek one diff, GLM the next) — different model

package/bundles/antigravity-plugin/skills/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 rev-sight and serve-sight,
+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? |
+|---|---|---|---|
+| serve-sight | worst >60s, 5 real breaches | recurring full-table aggregation | **YES** |
+| rev-sight (pre-fix) | 14s–60s+ across several endpoints | recurring full-table aggregation | **YES** |
+| appointment-assist | 10.3s | a single ~158MB LOB payload on 9.1k rows, not aggregation | **NO** — SQL aggregate + gzip |
+| nps-lens | 1.9s | cold JSON parse, no DB at all in prod | **NO** — warm the provider |
+| app-sight | 202ms | n/a — never crossed gate 1 | **NO** |
+
+A naive "slow ⇒ recommend rs-kit" tool would have wrongly flagged appointment-assist and nps-lens.
+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 (nps-lens 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, rev-sight R6/P3 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 an
+already-known app and confirm it reproduces the **already-established, human-verified** conclusion:
+**app-sight** (202ms, should conclude "not a candidate") and **serve-sight** (known 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/antigravity-plugin/skills/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/antigravity-plugin/skills/explainer-doc/SKILL.md

@@ -0,0 +1,97 @@
+---
+name: explainer-doc
+context: fork
+description: Write a document that hands off work to a team who did NOT do the investigation — an external vendor, another team, a contractor — and who must be able to act on it alone. Use when the user says "write a spec for the X team", "document this for someone outside the team", "explainer doc", "implementation spec for a vendor", "hand this off to Y", or is about to write a design doc whose primary reader did not live through the debugging/design process. NOT for internal specs where the reader already has full context (use technical-writing or writing-plans instead) — this is specifically for the "stranger must follow it alone" case.
+---
+
+# explainer-doc — write for the reader who has no other context
+
+A spec written by the people who did the investigation is unreadable by the team who must implement
+it. The authors compress away the reasoning, so every design choice looks arbitrary, and the reader
+either follows it blindly or argues with it. **The fix is not "add more detail" — it is to lead with
+*why*, and to make the document survive being read alone.**
+
+Proven in anger on a Genesys→ETL cutover spec handed to an external vendor team. The user's verdict:
+*"nailed it — the document was perfect, simple, this should be the standard for explainer documents."*
+Reference implementation to study: `serve-sight/docs/genesys-cutover/etl-implementation-spec.md` (full
+spec) and `pega-cticallid-change-request.md` (the same pattern compressed to one page for a single ask).
+
+## When this is NOT the right skill
+
+If the reader already lived through the investigation (a teammate, your future self, an internal
+handoff with shared context), use `technical-writing` or `writing-plans` instead — those are lighter
+and don't need the "assume zero shared context" discipline below. Reach for `explainer-doc` specifically
+when the reader is a **stranger to the problem**: an external vendor, a different team, a contractor,
+anyone who will act on the document with no one in the room to ask.
+
+## The shape — in order. The order IS the pattern
+
+Do not reorder these. Each section's position is load-bearing: later sections lean on earlier ones for
+their justification, and a reader working top-to-bottom needs the "why" before the "what."
+
+| § | Section | Why it must come here |
+|---|---|---|
+| 1 | **Why this exists** — what broke, in a diagram | Every later decision is justified by this. Lead with the failure, not the solution. |
+| 2 | **What we're asking for, in one picture** + a size table | The reader decides here whether the ask is reasonable. Include what you are explicitly **not** asking for. |
+| 3 | **Understanding the source data** — the 3-5 things that catch people out | Each one should have already caused a real bug. Not a data dictionary. |
+| 4 | **The one thing that matters most** | Usually not the new build. Say so plainly, with the number that proves it. |
+| 5 | **Where it runs** + access needed | The blocker nobody writes down until the first deploy fails. |
+| 6 | **What to build**, with the reasoning *beside* each choice | Not in an appendix. Next to the DDL / the query / the config. |
+| 6b | **Changes to what already exists** | Always under-specified. Ask "what did I only half-mention?" — this is where the gaps hide. |
+| 7-8 | The actual implementation (extract/build queries, load procedure, etc.) | |
+| 9 | Schedule / retention / first load | The one-off backfill is always forgotten. |
+| 10 | **Validation, with EXPECTED VALUES** | "Run this, expect ~64%" beats "verify the data." |
+| 11 | Priority · acceptance (who signs off) · **what we excluded** | The exclusion list stops speculative building. |
+| 12 | **Glossary** | Every acronym, inline. Not a link. |
+
+Adapt section names to the domain (this table is ETL-flavored from its origin; a UI handoff, an API
+contract, or an infra runbook will rename §6-9) — but keep the **order and the intent of each slot**.
+
+## The ten rules
+
+1. **Self-contained.** If the reader needs another document to follow this one, the document has
+   failed. Companions are optional background, stated as such — never load-bearing.
+2. **Lead with the failure mode, not the solution.** State what actually went wrong, concretely, before
+   proposing anything. Everything cautious later inherits its justification from that paragraph.
+3. **Reasoning beside the artefact, not in an appendix.** "Cluster on the date not the GUID" with the
+   3-row comparison table right there. An appendix is never read.
+4. **Every number carries its measurement date and a way to reproduce it.** "1.4% of reality (measured
+   2026-07-14, `SELECT ...`)" — not "a small fraction."
+5. **Say what you are NOT asking for.** Prevents speculative work and pre-answers "why not X?" before
+   it's asked.
+6. **Name what is not the reader's fault.** If a gap traces to a third system or a decision made
+   elsewhere, say so explicitly. Saves the reader a week of misdirected chasing and buys credibility for
+   the rest of the document.
+7. **Diagrams for the shape, tables for the detail, prose only for judgement.** No diagram should repeat
+   what a table already says better.
+8. **Validation states expected values.** "It ran" and "it is right" must be two different checks — give
+   the reader the number to compare against.
+9. **Route by owner.** If an item belongs to a third team, mark it as theirs, explicitly, in the document
+   — don't let it read as part of the reader's scope.
+10. **Glossary inline.** The reader will not follow a link mid-implementation; every acronym gets defined
+    where it's used, plus a glossary section as the fallback lookup.
+
+## Process
+
+1. **Confirm the reader.** Ask (or infer from context) who this is actually for and how much they
+   already know. If they have real shared context, stop and suggest `technical-writing`/`writing-plans`
+   instead — this skill's discipline is overhead they don't need.
+2. **Draft §1 first, alone, and get it right before writing anything else.** Every other section's
+   justification traces back to it. If you can't state the failure mode plainly and concretely, the
+   rest of the document will inherit that vagueness.
+3. **Write the shape table above as your outline**, adapting section names to the domain, then fill it
+   in top to bottom. Keep reasoning next to the artefact it justifies (rule 3), not in a separate
+   "design decisions" section.
+4. **Before sending, ask the two questions below** — they are an exit gate, not a suggestion.
+
+## The two-question exit gate
+
+Ask both, honestly, before the document ships:
+
+- **"Could someone who has read nothing else follow this end to end?"** If the answer requires "well,
+  they'd also need to know X" — X is either missing or should be a stated, explicit companion doc.
+- **"What did I mention once and never specify?"** This is the question that surfaces the gaps — in the
+  origin case it found an entire missing section (§6b, changes to existing infrastructure) that had been
+  gestured at once and never actually written.
+
+If either question fails, fix the document — don't ship it and hope the reader asks.

package/bundles/antigravity-plugin/skills/feature-plan/SKILL.md

@@ -92,6 +92,15 @@ A tier can be served by an OSS provider instead of Anthropic (cheat sheet:
   (Claude or GLM implemented) or `--provider glm` / a Claude `code-reviewer` pass (DeepSeek-adjacent
   work). Never same-vendor.
 
+### Flag high-risk phases (`risk:` — a marker, not a mechanism)
+Each phase may carry **`risk: normal|high`** (default `normal` — omit the line unless the phase is
+`high`), meaning only "this is a phase where a wrong answer is expensive" — security/authz, a
+correctness-critical algorithm, an ambiguous spec, or an irreversible change. It is **inert**: it
+selects no model, spawns no agents, and implies no fan-out — it exists so the executor can decide **at
+runtime** whether an extra cross-check is worth it. Do not emit orchestration, lane fan-out, or
+`Workflow` scripts from this command; the runtime decision rules and the intent→model map live in one
+place, the `agent-orchestration` skill's *Multi-model fan-out* section.
+
 ## Step 3 — Write the plan to `.caddis/plans/<feature-slug>.md`
 
 Create `.caddis/plans/` if it doesn't exist.
@@ -127,6 +136,7 @@ Creating Model: <model-id>
 **Model:** <tier> (`/model <alias>`) — <one-line rationale tied to this phase's difficulty>
 **Lane:** claude — this session  |  glm-headless — `claude-glm -p "/caddis:implement <this plan's path> — Phase 1 only"`
 **Session:** continue | **fresh** (start a new session for this phase — note why: lane change / heavy context)
+**Risk:** high — token-verification seam; a wrong answer here is a silent auth bypass  *(omit this line when normal)*
 **Goal:** <one sentence>
 **Touches:** `<files>`
 **TDD:**

package/bundles/antigravity-plugin/skills/kb/SKILL.md

@@ -46,8 +46,9 @@ surface the `[DOC-MAP]` "read the index first" pointer for future sessions in th
 
 ## KB note format (OKF-lite — mandatory for every new note)
 
-Every new `.caddis/kb/*.md` note starts with this frontmatter block (`type` is required;
-the rest recommended). `DOC-MAP.md` is the index, not a note — it stays frontmatter-free:
+Every new `.caddis/kb/*.md` note starts with this frontmatter block. **`type` is the only required
+field**; everything else is recommended. `DOC-MAP.md` is the index, not a note — it stays
+frontmatter-free:
 
 ```yaml
 ---
@@ -56,5 +57,18 @@ title: <human title>
 description: <one line — keep it identical to the note's DOC-MAP row description>
 tags: [topic, topic]
 timestamp: 2026-01-01      # ISO date of last substantive update
+# --- OKF v0.2 trust signals (all optional; omit rather than guess) ---
+status: stable             # draft | stable | deprecated  (absent reads as stable)
+stale_after: 2026-12-31    # re-verify by this date; nothing auto-acts on it
+verified:                  # who CONFIRMED it (not who wrote it); append, never rewrite
+  - { by: human:handle, at: 2026-07-28T10:00:00Z }
+generated: { by: caddis/<model-id>, at: 2026-07-28T09:00:00Z }
 ---
 ```
+
+The full schema, the caddis↔OKF `status` mapping, and what caddis deliberately skips from OKF v0.2
+(`sources:`, `Attested Computation`) live in
+[`.github/instructions/document-frontmatter.instructions.md`](../../.github/instructions/document-frontmatter.instructions.md).
+
+**Backward compatible:** an existing note with no trust fields is still correct. Do not bulk-migrate
+old notes — add the fields as notes are next touched.

package/bundles/antigravity-plugin-extras/plugin.json

@@ -1,5 +1,5 @@
 {
   "name": "caddis-extras",
-  "version": "1.3.13",
+  "version": "1.3.20",
   "description": "caddis-extras — the long-tail skills for the Antigravity (agy) caddis plugin; install alongside caddis for the full set."
 }

package/bundles/antigravity-plugin-extras/skills/_registry.md

@@ -136,7 +136,7 @@
 | Skill | Path | When to Use |
 |-------|------|-------------|
 | Agent Md Refactor | `agent-md-refactor/` | Refactor bloated agent instruction files (AGENTS.md, .cursorrules, .github/ files, etc.) to follow progressive disclosure principles. Splits monolithic files into organized, linked documentation. |
-| Agent Orchestration | `agent-orchestration/` | End-to-end blueprint for orchestrating the full agent pipeline — from spec intake through planning, implementation, testing, and debugging |
+| Agent Orchestration | `agent-orchestration/` | End-to-end blueprint for orchestrating the full agent pipeline — from spec intake through planning, implementation, testing, and debugging — plus the multi-model fan-out rules (when a second model is worth it, the intent→model map, and the cost guardrails) |
 | Ask Questions If Underspecified | `asking-questions/` | Clarify requirements before implementing. Do not use automatically, only when invoked explicitly. |
 | Data Contract Pipeline | `data-contract-pipeline/` | **WORKFLOW SKILL** - Build, audit, and validate data-to-UI contracts for apps. Use whenever the user mentions data mapping, UI lineage, DB-to-UI, DisplayDTOs, source-to-screen mapping, data contracts, schema drift, typed API responses, frontend type alignment, mockup grounding, requirements-to-UI mapping, or asks whether a UI is backed by real DB/file data. Works for DBs, JSON, Markdown, CSV, XLSX, YAML, APIs, and UI mockups. |
 | Developer Growth Analysis | `developer-growth-analysis/` | Analyzes your recent Claude Code chat history to identify coding patterns, development gaps, and areas for improvement, curates relevant learning resources from HackerNews, and automatically sends a personalized growth report to your Slack DMs. |

package/bundles/antigravity-plugin-extras/skills/agent-orchestration/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-orchestration
-description: "End-to-end blueprint for orchestrating the full agent pipeline — from spec intake through planning, implementation, testing, and debugging"
+description: "End-to-end blueprint for orchestrating the full agent pipeline — from spec intake through planning, implementation, testing, and debugging — plus the multi-model fan-out rules (when a second model is worth it, the intent→model map, and the cost guardrails)"
 ---
 
 # Agent Orchestration Blueprint
@@ -52,6 +52,11 @@ The operator (human) acts as **orchestrator**. Agents act as an **advisory board
 
 Every stage produces a **persistent artefact** (markdown file, commit, test run) that the next stage can consume without relying on conversation memory. This is what makes multi-session execution reliable.
 
+> The pipeline below is the **sequential** axis — which agent, in what order. There is a second,
+> independent axis: **how many models** work a given stage. That is deliberately rationed — see
+> [Multi-model fan-out](#multi-model-fan-out-the-second-axis-how-many-models) before reaching for a
+> second model.
+
 | Stage | Artefact | Location |
 |-------|----------|----------|
 | Requirements | Spec / feature file | Supplied by operator (e.g. `nextprompt.md`) |
@@ -392,10 +397,138 @@ The plan document should contain **copy-paste prompts** for each phase. This rem
 
 ---
 
+## Multi-model fan-out (the second axis: how many models)
+
+> ### ⚠️ If you are not Claude Code, treat this section as ADVISORY and execute solo.
+> The `Agent` tool, its per-agent `model:` override, the `Workflow` tool, and the `/glm`,
+> `/deepseek`, `/caddis:cross-review` commands described below are **Claude-Code-only**. On Codex,
+> Copilot, Antigravity/agy, or any other host: take the *judgement* from this section — default solo,
+> cheapest deterministic check first, don't trust a single model on a security invariant — and
+> **ignore the mechanics**. Do not attempt to emulate fan-out by hand, do not tell the user to run
+> tools your host does not have, and do not treat the model map below as instructions you can execute.
+> Solo execution is a correct, complete outcome here.
+
+Everything above is *sequential*: one model, one stage at a time, operator in the loop. **Fan-out** —
+running two or more models on the same work and reconciling their output — is a separate axis, and it
+is **expensive in three currencies at once**: provider quota, the orchestrator's own context, and the
+human's attention. It earns its cost rarely. The rules below are ordered; apply them in order.
+
+### Rule 0 — default SOLO
+
+**One model does the work. That is the default and it is right most of the time.** Fan out only when
+the work is genuinely high-risk *or* high-uncertainty:
+
+| Fan out | Stay solo |
+|---|---|
+| Security-sensitive code — authn/authz, crypto, secret handling, input trust boundaries | Boilerplate, CRUD, scaffolding |
+| Correctness-critical algorithms where a subtle wrong answer looks right (concurrency, money, dates/timezones, migrations, dedup/merge logic) | Mechanical refactors with a green suite either side |
+| Ambiguous specs — where the risk is that *everyone* misreads the requirement the same way | Anything a test, type-checker, or linter can decide |
+| Verifying a frontier model's **own** risky output — a model is the worst reviewer of its own reasoning | Work already covered by an existing review gate |
+| Irreversible / wide blast radius — a drop, a flag day, a fleet-wide sweep | Work you can trivially revert |
+
+Two failure modes, both real: **fanning out on size** (a big mechanical task is still solo — split it
+across *sessions*, not models) and **fanning out for reassurance** (a second opinion you have already
+decided to ignore is pure cost).
+
+### Rule 1 — cheapest check first
+
+**Never spend a second model on something a deterministic check can decide.** Climb this ladder and
+stop at the first rung that answers the question:
+
+1. **Tests / types / linters / the build.** If a failing test, `mypy`/`tsc`, or a lint rule confirms
+   the concern, you are done — that is a *fact*, not an opinion, and it costs nothing.
+2. **Read the code.** A targeted grep or a five-line read beats any model's guess about what the code
+   does.
+3. **A subagent on the same model** (`code-reviewer`, `security-analyst`, `anchor`, `preflight`) — a
+   fresh context, not a fresh vendor. Catches most "did we miss something" cases.
+4. **A different tier** — escalate one model tier for the hard part only.
+5. **Cross-vendor.** The last rung, and the rationed one (see the guardrails).
+
+If a deterministic check *can* be written but doesn't exist yet, **write the check** — it is cheaper
+than the model call and it keeps paying.
+
+### Rule 2 — name the INTENT, not the model
+
+Talk about lanes by what they are *for*, so plans, prompts, and reviews survive model releases and the
+LiteLLM cutover. **This table is the single place the intent→model mapping lives** — everything else
+(plans, commands, skills) refers to the intent name and points here.
+
+| Intent | What it's for | Current model | Claude Code mechanics | Cost |
+|---|---|---|---|---|
+| **deepest** | Subtle correctness, security invariants, novel architecture, judgment-heavy seams | `opus` | `/model opus`; `Agent(model: "opus")` | **High** — Anthropic plan quota |
+| **broad** | Wide parallel coverage of a large but not-subtle surface; the workhorse | `sonnet` | `/model sonnet`; `Agent(model: "sonnet")` | Medium — the default; budget for several |
+| **mechanical** | Fully-specced, repeat-of-a-known-pattern, no judgment required | `haiku` | `/model haiku`; `Agent(model: "haiku")` | Low |
+| **cross-vendor-reviewer** | A *different vendor's* blind spots on a diff — **code review only** | `deepseek` (default), `glm` | `/caddis:cross-review`, `/glm`, `/deepseek` | **Scarce** — separate starter-tier subscription, NOT Anthropic quota. Ration it. |
+| **synthesis / long-horizon** | Orchestrating many lanes, or work that can't self-verify across a large codebase | `fable` | `/model fable` | **Very high** — ~2× opus's rate-limit burn. RARE. |
+
+**Update this table, not the callers**, when a model is added, retired, or re-tiered. A plan that says
+"cross-vendor-reviewer" keeps working; a plan that says "deepseek-chat" rots.
+
+### Hard guardrails
+
+These are constraints, not preferences. Each exists because breaking it produced a real cost.
+
+1. **DeepSeek and GLM are the CODE-REVIEW lane, and nothing else.** Map them to cross-vendor review of
+   a diff or a concrete file set. **Never** general audit, research, planning, architecture, or
+   open-ended subagent work — they are unreliable outside that lane, and an unreliable lane's output
+   still costs a full synthesis pass to disprove.
+2. **Ration cross-vendor to ~one consolidated pass per task.** One review of the whole change, not one
+   agent per area. Alternate vendors *between* tasks (DeepSeek this diff, GLM the next) — different
+   families have different blind spots and alternation maximises what the pair catches over time.
+3. **Degrade to solo when a lane's quota is exhausted.** A 402/429/quota error on GLM or DeepSeek is a
+   **downgrade, not a blocker**: log that the cross-vendor pass was skipped, continue with the
+   same-vendor reviewer, and say so in the report. Never stall the task waiting on a rationed lane,
+   and never silently drop the pass — an unrun check that reads as "reviewed" is worse than no check.
+4. **Name the synthesis cost before you add a lane.** N lanes do not cost N model calls — they cost N
+   calls **plus** reconciling N reports, which burns the orchestrator's frontier context (the scarcest
+   thing in the session) **and** the human's attention on the write-up. So:
+   - **Default cap: 3 lanes.** Above that, write the synthesis budget down first — who reconciles, on
+     what model, and what the human is expected to read.
+   - **Hard ceiling ~8**, and only for a one-off audit of a genuinely partitioned surface. The 8-lane
+     migration audit that motivated these rules produced a 272-line report that still needed a human
+     read and a main-thread re-verification of every HIGH finding. That tail is the real cost.
+   - If you cannot say what you would *do differently* based on lane N's output, lane N is not worth
+     running.
+5. **Lanes advise; they do not write.** Fan-out agents are read-only — they return findings, the main
+   thread applies them. This is the same rule as "agents never chain autonomously without review", and
+   it is what keeps parallel lanes from clobbering each other.
+6. **Verify high-severity findings in the main thread before acting.** A finding from a lane is a
+   *claim*. Re-read the cited file/line yourself. Subagent reports are confidently wrong often enough
+   that acting on an unverified HIGH is how fan-out turns into net-negative work.
+
+### Running it — existing mechanisms only
+
+Invent no new machinery. Everything needed already ships:
+
+| Need | Use |
+|---|---|
+| Second opinion, same vendor, fresh context | `Agent` tool → `code-reviewer` / `security-analyst` / `anchor` / `preflight` |
+| A different tier for one lane only | The `Agent` tool's `model:` override (per-agent; does not change the session model) |
+| 2–4 lanes in parallel | Several `Agent` calls **in one message** — they run concurrently. This is enough; you do not need anything heavier. |
+| Deterministic multi-stage orchestration (fan out over a discovered list, loop until dry, adversarial verify stages) | The `Workflow` tool — **only when the human explicitly asks for it**; it can spawn dozens of agents |
+| Cross-vendor review of a diff | `/caddis:cross-review` (or `python .github/tools/oss_review.py --provider deepseek\|glm --range <range>`) |
+| Cross-vendor opinion that needs to read the repo | `/glm <prompt>` or `/deepseek <prompt>` |
+| Cross-vendor one-shot, no repo context | `/ask-glm` / `/ask-deepseek` |
+| Per-phase model + lane assignment in a plan | `/caddis:feature-plan` — every phase already carries **Model**, **Lane**, and a cross-review provider |
+
+**Reviewer rule (standing):** the reviewer is always a different vendor than whoever wrote the code.
+Claude or GLM implemented → DeepSeek reviews (or swap). Never same-vendor.
+
+Full command/billing decision table: `docs/guide/multi-model-workflow.md`.
+
+---
+
 ## Anti-Patterns to Avoid
 
 | ❌ Anti-Pattern | ✅ Instead |
 |----------------|-----------|
+| Fanning out because the task is *big* | Fan out for **risk**, not size — split a big mechanical task across sessions, not models |
+| Spending a cross-vendor pass before the tests have run | Cheapest check first — deterministic gates decide it for free |
+| One cross-vendor agent per area | One consolidated cross-vendor pass per task — the lane is rationed |
+| Using DeepSeek/GLM for audit, research, or planning | Code-review lane only — they are unreliable outside it |
+| Adding an Nth lane without budgeting the synthesis | Cap the lanes; reconciling N reports lands on you *and* the human |
+| Acting on a subagent's HIGH finding as reported | Re-verify it in the main thread against the cited file/line first |
+| Blocking the task when a rationed lane is out of quota | Degrade to solo, log the skipped pass, continue |
 | Jumping straight to code without a plan | Triage → ADR (if needed) → Plan → Implement |
 | Implementing all phases in one session | One phase per session — clean context, focused work |
 | Letting agents edit the plan document | Only the Planner agent (or operator) edits plans |
@@ -493,6 +626,7 @@ A well-orchestrated session should produce:
 | Session continuation context | `.github/skills/workflow/relay/SKILL.md` |
 | Verifying code before committing | `.github/skills/workflow/verification-loop/SKILL.md` |
 | Writing implementation plans | `.github/skills/docs/writing-plans/SKILL.md` |
+| Running the cross-vendor review lane | `.github/skills/coding/cross-review/SKILL.md` |
 | Creating new reusable skills | `.github/skills/workflow/skill-creator/SKILL.md` |
 | Best practices reference | `.github/skills/workflow/best-practices/SKILL.md` |
 

package/bundles/antigravity-plugin-extras/skills/cross-review/SKILL.md

@@ -28,10 +28,13 @@ churn — the preset table in `oss_review.py` is the one place to edit a rename,
 `REVIEW_BASE_URL` always win, so you can point at any new id without touching code.
 
 ## How to run
-From the repo root (the tool ships at `.github/tools/oss_review.py`):
+From the repo root. Locate the tool, in order:
+- `.github/tools/oss_review.py` — this project vendors its own copy.
+- `${CLAUDE_PLUGIN_ROOT}/scripts/oss_review.py` — the plugin-bundled copy (every Claude Code
+  install has this; use it whenever the project has no local copy).
 ```
-python .github/tools/oss_review.py                       # review the working tree (staged+unstaged)
-python .github/tools/oss_review.py --range origin/main..HEAD   # review a branch's commits
+python <resolved-path>/oss_review.py                       # review the working tree (staged+unstaged)
+python <resolved-path>/oss_review.py --range origin/main..HEAD   # review a branch's commits
 ```
 Optional flags: `--cwd <repo>`, `--base-url <url>`, `--model <id>` (override the env).
 

package/bundles/manifest.json

@@ -1,7 +1,7 @@
 {
-  "poolVersion": "1.3.40",
+  "poolVersion": "1.3.47",
   "bundles": {
-    "antigravity-plugin": "1.3.40",
-    "antigravity-plugin-extras": "1.3.13"
+    "antigravity-plugin": "1.3.47",
+    "antigravity-plugin-extras": "1.3.20"
   }
 }

package/dist/cli.js

@@ -5167,7 +5167,7 @@ var claudeAdapter = {
 };
 
 // src/agents/agy.ts
-import { readFileSync as readFileSync2, existsSync as existsSync2 } from "fs";
+import { readFileSync as readFileSync2, existsSync as existsSync2, mkdtempSync, cpSync, rmSync } from "fs";
 import os from "os";
 import path2 from "path";
 init_pkg();
@@ -5239,6 +5239,25 @@ function shortenHome(target) {
   const home = os.homedir();
   return target.startsWith(home) ? path2.join("~", target.slice(home.length)) : target;
 }
+function stageForAgy(bundleDir) {
+  if (!bundleDir.includes("@")) {
+    return { installPath: bundleDir, cleanup: () => {
+    } };
+  }
+  const staged = mkdtempSync(path2.join(os.tmpdir(), "caddis-agy-"));
+  const dest = path2.join(staged, path2.basename(bundleDir));
+  cpSync(bundleDir, dest, { recursive: true });
+  return {
+    installPath: dest,
+    // Best-effort: a stray temp dir left behind is harmless clutter, not a failure.
+    cleanup: () => {
+      try {
+        rmSync(staged, { recursive: true, force: true });
+      } catch {
+      }
+    }
+  };
+}
 async function drive2(_action, options) {
   const detected = await detect2();
   if (!detected.present) {
@@ -5253,12 +5272,12 @@ async function drive2(_action, options) {
       message: `the ${BUNDLE} bundle is missing from this package \u2014 reinstall @caddis/cli`
     };
   }
-  const planned = [{ cmd: BIN2, args: ["plugin", "install", bundle] }];
+  const planned = [{ cmd: BIN2, args: ["plugin", "install", bundle], bundleDir: bundle }];
   const extrasInstalled = extrasStatusFromHome(os.homedir()).installed;
   if (options.extras === true || extrasInstalled) {
     const extrasBundle = bundlePath(EXTRAS_BUNDLE);
     if (extrasBundle) {
-      planned.push({ cmd: BIN2, args: ["plugin", "install", extrasBundle] });
+      planned.push({ cmd: BIN2, args: ["plugin", "install", extrasBundle], bundleDir: extrasBundle });
     } else if (options.extras === true) {
       return {
         ok: false,
@@ -5272,25 +5291,34 @@ async function drive2(_action, options) {
     return {
       ok: true,
       skipped: true,
+      // Show the logical bundle path, not a staged temp copy that was never created.
       steps: planned.map((s) => ({ command: formatCommand(s.cmd, s.args), ok: true, code: null })),
       message: "dry run \u2014 nothing executed"
     };
   }
-  const steps2 = [];
-  for (const step of planned) {
-    const command = formatCommand(step.cmd, step.args);
-    const result = await run(step.cmd, step.args);
-    steps2.push({
-      command,
-      ok: result.ok,
-      code: result.code,
-      output: result.ok ? void 0 : (result.stderr || result.stdout || result.failure || "").trim().split(/\r?\n/).slice(-3).join("\n")
-    });
-    if (!result.ok) {
-      return { ok: false, skipped: false, steps: steps2, message: `\`${command}\` failed` };
+  const cleanups = [];
+  try {
+    const steps2 = [];
+    for (const step of planned) {
+      const command = formatCommand(step.cmd, step.args);
+      const staged = stageForAgy(step.bundleDir);
+      cleanups.push(staged.cleanup);
+      const execArgs = [...step.args.slice(0, -1), staged.installPath];
+      const result = await run(step.cmd, execArgs);
+      steps2.push({
+        command,
+        ok: result.ok,
+        code: result.code,
+        output: result.ok ? void 0 : (result.stderr || result.stdout || result.failure || "").trim().split(/\r?\n/).slice(-3).join("\n")
+      });
+      if (!result.ok) {
+        return { ok: false, skipped: false, steps: steps2, message: `\`${command}\` failed` };
+      }
     }
+    return { ok: true, skipped: false, steps: steps2 };
+  } finally {
+    cleanups.forEach((fn) => fn());
   }
-  return { ok: true, skipped: false, steps: steps2 };
 }
 var agyAdapter = {
   id: "agy",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caddis/cli",
-  "version": "0.2.1",
+  "version": "0.2.3",
   "description": "Install, update and diagnose the caddis dev harness across every coding agent you use (Claude Code, agy/Antigravity, and more).",
   "keywords": [
     "caddis",