@andresmassello/uscha 1.40.2 → 1.43.0

package/uscha-kit/.claude/skills/uscha-mirador/SKILL.md

@@ -75,23 +75,38 @@ wires the JSON the engine emits into the template. Read-only.
    this for a pure measured view.
 
 4. **Render `mirador.html`** with the standalone renderer — it runs `dashboard --json`,
-   merges the sidecar telemetry if present, injects `const DATA`, and writes the file:
+   merges the sidecar telemetry if present, injects `const DATA`, writes the file, prints its
+   absolute path (`OPEN IT: ...`), and opens it in the default browser. From the project root,
+   with no long paths — `--engine` and `--template` default to the renderer's sibling skill
+   files (kit 1.41.2):
    ```bash
-   python3 <skill-dir>/mirador-render.py --engine <engine> --ledger QA-LEDGER.json \
-       --template <skill-dir>/mirador.template.html --out mirador.html
+   python3 <skill-dir>/mirador-render.py --ledger QA-LEDGER.json
    ```
    The engine stays model-agnostic — telemetry is merged by the renderer (the adapter), NOT
    by `dashboard`. If the ledger is missing, warn and stop (run `uscha-devloop` first). For
    the time-lapse, `qa_ledger.py readiness --record` (opt-in) fills the history prospectively.
 
-5. **Open it** (best-effort; never fail — headless/CI): `start "" mirador.html` (Windows) /
-   `open mirador.html` (macOS) / `xdg-open mirador.html` (Linux). ALWAYS print the absolute
-   path of `mirador.html`.
+5. **Where to look:** the renderer already opened `mirador.html` and printed its absolute path
+   on the `OPEN IT:` line — surface that path to the operator. Pass `--no-open` to write the
+   file without opening a browser (headless/CI, or the watch loop below, which passes it).
+
+## For a human at a terminal: `uscha mirador`
+
+The one-liner above is what THIS skill runs. A human who just wants the dashboard — without a
+Claude Code session — has a zero-friction verb instead (kit 1.43.0): from the project root,
+
+```bash
+uscha mirador            # render + open, defaults to the QA-LEDGER.json convention
+uscha mirador --watch    # live second-screen view (auto-refresh, one self-reloading tab)
+npx @andresmassello/uscha mirador   # same, no install
+```
+
+No python, no paths: the verb resolves the engine, template and ledger on its own.
 
 ## Live second-screen view
 
 For a mirador that updates while you keep coding in the terminal, run the watch loop in a
-spare terminal and open `mirador.html` on a second monitor:
+spare terminal and open `mirador.html` on a second monitor (or just use `uscha mirador --watch`):
 
 ```bash
 # Windows:  powershell -NoProfile -File <skill-dir>\mirador-watch.ps1 -Interval 30

package/uscha-kit/.claude/skills/uscha-mirador/mirador-render.py

@@ -59,15 +59,45 @@ def aggregate_telemetry(path):
             "model": model, "effort": effort, "by_model": by_model}
 
 
+def _json_for_html_script(value):
+    """Serialize JSON without allowing data to terminate the enclosing script."""
+    return (json.dumps(value, ensure_ascii=False)
+            .replace("&", r"\u0026")
+            .replace("<", r"\u003c")
+            .replace(">", r"\u003e")
+            .replace("\u2028", r"\u2028")
+            .replace("\u2029", r"\u2029"))
+
+
+def _open_best_effort(path):
+    """Open the rendered file in the default browser; never fail (headless/CI)."""
+    try:
+        if sys.platform.startswith("win"):
+            os.startfile(path)  # type: ignore[attr-defined]  # Windows-only
+        elif sys.platform == "darwin":
+            subprocess.Popen(["open", path])
+        else:
+            subprocess.Popen(["xdg-open", path])
+    except Exception:
+        pass  # the absolute path was already printed
+
+
 def main():
+    here = os.path.dirname(os.path.abspath(__file__))
     ap = argparse.ArgumentParser(description="render mirador.html from the ledger (+ optional vendor telemetry)")
-    ap.add_argument("--engine", required=True, help="path to qa_ledger.py")
+    # engine + template default to the SIBLING skill files, so from any project you can just
+    # run this script (or `/uscha-mirador`) with no long paths (kit 1.41.2).
+    ap.add_argument("--engine", default=os.path.join(here, os.pardir, "uscha-devloop", "qa_ledger.py"),
+                    help="path to qa_ledger.py (default: the sibling uscha-devloop engine)")
     ap.add_argument("--ledger", default="QA-LEDGER.json")
-    ap.add_argument("--template", required=True, help="path to mirador.template.html")
+    ap.add_argument("--template", default=os.path.join(here, "mirador.template.html"),
+                    help="path to mirador.template.html (default: the sibling template)")
     ap.add_argument("--out", default="mirador.html")
     ap.add_argument("--sidecar", default=os.path.join(".uscha", "telemetry.jsonl"))
     ap.add_argument("--refresh", type=int, default=0,
                     help="if >0, the page auto-reloads every N seconds (live second-screen view)")
+    ap.add_argument("--no-open", action="store_true",
+                    help="write the file but do not open it in a browser")
     args = ap.parse_args()
 
     try:
@@ -93,18 +123,27 @@ def main():
         print(f"[mirador-render] cannot read template {args.template}: {e}", file=sys.stderr)
         return 1
     payload = ("/*MIRADOR_DATA_START*/\nconst DATA = "
-               + json.dumps(data, ensure_ascii=False) + ";\n/*MIRADOR_DATA_END*/")
+               + _json_for_html_script(data) + ";\n/*MIRADOR_DATA_END*/")
     out = re.sub(r"/\*MIRADOR_DATA_START\*/.*?/\*MIRADOR_DATA_END\*/",
                  lambda m: payload, tpl, count=1, flags=re.S)
     if args.refresh and args.refresh > 0:
         # opt-in live reload: a meta-refresh, injected only when watching
         out = out.replace("</head>",
                           f'<meta http-equiv="refresh" content="{args.refresh}">\n</head>', 1)
+    live = bool(args.refresh and args.refresh > 0)
     with open(args.out, "w", encoding="utf-8") as f:
         f.write(out)
     score = (data.get("readiness") or {}).get("score")
-    print(f"[mirador-render] wrote {args.out} (readiness {score}, "
-          f"telemetry {'on' if tel else 'off'}, refresh {args.refresh or 'off'})")
+    out_abs = os.path.abspath(args.out)
+    print(f"[mirador-render] wrote {out_abs}")
+    print(f"[mirador-render]   readiness {score} | telemetry {'on' if tel else 'off'} | "
+          f"refresh {args.refresh or 'off'}")
+    print(f"[mirador-render]   OPEN IT:  {out_abs}")
+    # Auto-open only a ONE-SHOT view. In live mode (--refresh) the page carries its own
+    # meta-refresh and reloads in the SAME tab, so opening on every render cycle would
+    # spawn a new browser tab each time (kit 1.41.3). Open it once by hand and let it live.
+    if not args.no_open and not live:
+        _open_best_effort(out_abs)
     return 0
 
 

package/uscha-kit/.claude/skills/uscha-mirador/mirador-watch.ps1

@@ -16,7 +16,7 @@ $out      = if ($env:OUT)      { $env:OUT }      else { "mirador.html" }
 $py       = if ($env:PYTHON)   { $env:PYTHON }   else { "python" }
 Write-Host "mirador-watch: regenerating $out every ${Interval}s (Ctrl-C to stop). Open $out in a browser."
 while ($true) {
-  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval
+  & $py (Join-Path $here "mirador-render.py") --engine $engine --ledger $ledger --template $template --out $out --refresh $Interval --no-open
   if ($LASTEXITCODE -ne 0) { Write-Host "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying" }
   Start-Sleep -Seconds $Interval
 }

package/uscha-kit/.claude/skills/uscha-mirador/mirador-watch.sh

@@ -20,7 +20,7 @@ command -v "$PY" >/dev/null 2>&1 || PY=python
 echo "mirador-watch: regenerating $OUT every ${INTERVAL}s (Ctrl-C to stop). Open $OUT in a browser."
 while true; do
   "$PY" "$HERE/mirador-render.py" --engine "$ENGINE" --ledger "$LEDGER" \
-    --template "$TEMPLATE" --out "$OUT" --refresh "$INTERVAL" || \
+    --template "$TEMPLATE" --out "$OUT" --refresh "$INTERVAL" --no-open || \
     echo "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying"
   sleep "$INTERVAL"
 done