@andresmassello/uscha 1.40.1

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

@@ -0,0 +1,161 @@
+---
+name: uscha-discovery
+description: >
+  Front of the methodology for greenfield work. From a general idea (plus optional
+  reference docs, URLs, PDFs, or an existing codebase), grill the user ONE question at
+  a time — each with your recommended answer — PROPOSING the system shape (domain model,
+  API/operation surface, architecture options) so the human approves instead of authors.
+  Write the spec package (CONTEXT.md, SPEC.md, docs/adr/*.md, ACCEPTANCE.md, RISKS.md,
+  HANDOFF.md) directly to the repo as decisions crystallize. Invoke for "discovery",
+  "modelá esto desde una idea", "solo tengo la idea, no sé el cómo todavía".
+allowed-tools: Read, Write, Glob, Grep, WebFetch
+disable-model-invocation: false
+---
+
+# discovery — from a bare idea to a writable spec package
+
+The human brings the idea, the constraints and the reference material. **You bring the
+shape.** Your job is to interrogate until there is a shared system shape, and to write
+the documents as you go — not to ask the human to design the system for you.
+
+## Non-negotiable principles
+
+1. **One question at a time, each WITH your recommended answer.** This is the inversion
+   that makes discovery work: you propose (entities, endpoints, architecture, a default
+   decision), the human confirms or corrects. Never dump a list of 20 questions, and
+   never ask the human to supply structure you can propose yourself.
+2. **Explore instead of asking.** If a reference doc/URL/PDF, the existing codebase, or
+   an existing `CONTEXT.md`/`docs/adr/` can answer a question, read it first. Only ask
+   the human what genuinely requires their judgment.
+3. **Propose the shape.** From the idea + references, propose the core entities, the
+   operation/API surface, and 2–3 architecture options with trade-offs. Walk the design
+   tree branch by branch, resolving dependencies between decisions one at a time.
+4. **Grill, don't agree.** Surface contradictions, fuzzy/overloaded terms, missing
+   failure modes and unstated constraints. A discovery where you agreed with everything
+   failed.
+5. **Write files lazily and inline.** Create a file only when you have something real to
+   write, and update it the moment a decision crystallizes — don't batch to the end.
+
+## Inputs
+
+- **The idea** (required): what the human wants to achieve. It doesn't have to be
+  complete or well-formed.
+- **Reference material** (optional): manuals, PDFs, URLs, API specs. Read them with
+  WebFetch/Read before proposing — they are how you propose an accurate shape.
+- **Existing codebase** (optional): if present, explore it; respect `CONTEXT.md` and
+  existing ADRs.
+
+## Domain awareness (explore first)
+
+- Look for `CONTEXT.md` (domain glossary), `CONSTITUTION.md` (project invariants) and
+  `docs/adr/` and read them. The CONSTITUTION constrains every shape you propose — never
+  propose anything that would violate it.
+- **Sharpen fuzzy language.** When the human uses a vague or overloaded term, propose a
+  precise canonical term: "You say 'account' — the Customer or the User? They're different things."
+- **Maintain a glossary in `CONTEXT.md`**, updated inline as each term is resolved. Only
+  terms meaningful to domain experts; don't couple it to implementation details.
+
+## The grilling agenda (walk the tree, propose at each step)
+
+Resolve these in order; for each, propose first, then ask. Skip what references already
+answer.
+
+0. **Project name (first).** The very first thing you ask: "What do we call this?" Write the
+   answer to `uscha.config.json` as `"project": "<name>"` (create the config if absent). The
+   mirador shows it prominently at the top and the dashboard reads it from there; if unset it
+   falls back to the joined repo names.
+1. **Purpose / value / why now.** What job does this remove? Cost of not doing it?
+2. **Domain model.** Propose the core entities and their relationships. ("From the domain
+   I deduce these core entities: … do they work for you, or is one missing?")
+3. **Operation / API surface.** Propose the endpoints/operations and their
+   contracts (idempotency, status codes).
+4. **Big decisions (→ ADR).** Propose 2–3 architecture options with trade-offs and
+   a recommended default: persistence, protocol, idempotency, sync/async, multi-tenancy.
+5. **Behavior and dirty cases.** Happy path, then failures, retries, partial states,
+   concurrency, what must NOT happen.
+6. **Inviolable constraints (→ `CONSTITUTION.md`).** Domain + security + operation
+   rules that can't be broken (money to the cent, no numbering gaps, never cross
+   environments, secrets never logged, auth). Write/extend `CONSTITUTION.md` with these —
+   one invariant per line, with a CWE reference where it maps. They feed the severity gate
+   downstream, and a breach is a BLOCKER, never a trade-off.
+7. **Out of scope.** Explicit boundaries with forward references.
+8. **Acceptance / Definition of Done.** Concrete, checkable criteria + success metrics.
+9. **Quality bar (→ config, kit 1.17.0).** "What level of quality is ENOUGH here, and which
+   dimensions are negotiable (coverage, perf, security)?" Propose thresholds fit for
+   the risk profile (a payments core is not an internal dashboard). What the human
+   declares goes into `uscha.config.json` (`defaults.coverage_threshold`,
+   `defaults.readiness_caps`, `defaults.simplicity`) — a declared threshold reads as
+   **requerimiento (config)** in the engine's output; an undeclared one stays a kit
+   default (opinion) and is labeled as such. Declaring is committing the config.
+10. **Residual risks and dependencies.** What's uncertain, what must exist first.
+    For each HIGH-uncertainty risk, ask (kit 1.19.0, Tip 21 'Prototype to Learn'):
+    "Does it warrant a time-boxed spike before freezing the SPEC?" A spike runs on a
+    `spike/*` branch and its ONLY legitimate output is an **ADR with lessons**
+    (facts that feed the SPEC) — never mergeable code. The contract is executable:
+    `phase --require pr-ready` refuses any `spike/*` branch, INV-GOLDEN-01 style.
+
+## Files to write (lazily, inline)
+
+- **`CONTEXT.md`** — domain glossary; create on first resolved term, update as you go.
+- **`CONSTITUTION.md`** — project invariants no ADR/SPEC may violate (security with CWE
+  refs, domain rules, operation). Create/extend from the "restricciones inviolables" step.
+  This is the layer above the ADRs; a breach is a BLOCKER finding downstream.
+- **`DOMAIN-MODEL.md`** — the proposed core entities and their relationships (the "shape"
+  you proposed and the human approved). Distinct from the glossary: this is the model, not
+  the vocabulary.
+- **`SPEC.md`** — objective/value, risk, scope/out-of-scope, behavior,
+  inputs/outputs/errors, acceptance, test plan, operation, rollback.
+- **`docs/adr/ADR-NNN-<slug>.md`** — one per durable decision. Format: Status
+  (proposed/accepted/**experiment**/deprecated/superseded) · Context · Alternatives · Decision ·
+  Consequences · **Implementation Plan** (affected paths, patterns to follow, tests to
+  write) · **Verification** (`- [ ]` checkboxes a coding agent can check). The
+  Implementation Plan makes the ADR an executable spec: the agent implements it without
+  asking follow-ups. Number from the highest existing ADR. Use `Status: Experiment` only
+  for a bounded, reversible hypothesis that needs real feedback; include `Hypothesis`,
+  `Feedback Signal`, `Review By` or `Review Trigger`, `Promote Criteria`, and
+  `Rollback / Supersede Criteria`.
+- **`ACCEPTANCE.md`** — Definition of Done as `- [ ]` checkboxes + success metrics. This
+  is the file the readiness KPI measures downstream. Give EVERY criterion a stable
+  traceable ID: `- [ ] AC-01 — when X then Y` (sequential, never reused). Downstream,
+  a criterion only closes MEASURED when a green testcase carries its tag in the name
+  (`test_ac1_x` / `testAC01X` / `"AC-01: ..."`) — write criteria so each one is
+  coverable by at least one named test.
+- **`RISKS.md`** — residual risks, assumptions, points needing human approval.
+- **`HANDOFF.md`** — what to read before coding + hard "no hacer" rules + required evidence.
+
+## Offer ADRs sparingly
+
+Only write an ADR when ALL three hold (otherwise it's noise that buries the important ones):
+1. **Hard to reverse** — changing your mind later has real cost.
+2. **Surprising without context** — a future reader will wonder "why this way?".
+3. **A real trade-off** — there were genuine alternatives and you chose one for reasons.
+
+## Convergence — finish when
+
+A shared system shape exists: entities, operations and big decisions taken (or recorded
+as explicit assumptions), every failure mode has defined behavior, out-of-scope is
+explicit, and the DoD is checkable. State plainly that it converged, then write/finalize
+the package and the handoff.
+
+## Handoff
+
+End with the implementation handoff (works for a human, an agent, or CI):
+
+> "Read CONTEXT.md, SPEC.md, docs/adr/*.md and ACCEPTANCE.md. Before touching code:
+> 1) summarize the expected behavior, 2) flag ambiguities or contradictions,
+> 3) propose a file plan + tests. Implement only the SPEC's scope. Do not change
+> contracts outside the SPEC, and do not edit the SPEC to make your implementation look correct."
+
+Flow: `/uscha-discovery` (idea → package) → `/uscha-devloop` (build + QA + evidence) → human gate.
+
+## Relationship to adr-refine
+
+`uscha-discovery` is the greenfield front: you only have an idea, so the skill PROPOSES the
+shape. `uscha-adr-refine` is the same interview applied to a KNOWN feature where the shape is
+already clear and you only need precision. Both emit the same package; pick by starting
+point.
+
+## Tracked-markdown protocol
+
+If a target `.md` already exists and is tracked, ask for its current version before
+overwriting — never silently replace real progress.

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

@@ -0,0 +1,145 @@
+---
+name: uscha-mirador
+description: >
+  Bird's-eye status view ("mirador") of a spec-loop project: one glance at
+  readiness, sub-scores, the phase path, invariants, QA loops and a readiness
+  time-lapse. Runs `qa_ledger.py dashboard --json` (read-only, deterministic,
+  zero LLM narration), injects that JSON into mirador.template.html, writes
+  mirador.html at the project root and opens it. The skill WIRES, it does not
+  calculate — every number comes from the ledger (truth-pass: a field with no
+  source shows null and the template degrades, never invented). Invoke for
+  "mirador", "vista de estado", "bird's-eye", "dashboard del proyecto".
+allowed-tools: Read, Write, Glob, Grep, Bash
+---
+
+# uscha-mirador — bird's-eye status view
+
+Paints the REAL state of the project at a glance. It does not narrate or estimate: it
+wires the JSON the engine emits into the template. Read-only.
+
+## Contract
+
+- **Source of truth:** `qa_ledger.py dashboard --json` — aggregates ONLY state the
+  ledger already has (readiness, subscores, phases, specs, adrs, inv, layers, loops,
+  snapshots, evidence). A field with no source comes out `null`/`[]`; the template
+  degrades. **A datum is never invented.**
+- **Template:** `mirador.template.html` (in this folder). The data block lives between
+  `/*MIRADOR_DATA_START*/` and `/*MIRADOR_DATA_END*/`; the sample `const DATA` it ships
+  with is the **offline fallback**. The skill replaces ONLY that region; it does not
+  touch the rest of the HTML.
+- **Project name (top):** the mirador shows the project name prominently at the top, from
+  `config.project` in `uscha.config.json` (set it in `uscha-discovery`); if unset, it falls
+  back to the joined repo names (truth-pass — no invented name).
+- **Execution policy (bird's-eye):** `dashboard --json` also exposes
+  `execution_policy` plus `phase.execution` for each trail node. This is routing metadata
+  from `config.defaults.execution_policy` (`method`, `tier`, `model`, `effort`,
+  `uncorrelated`), not a score. The template renders it as a separate panel so the human
+  sees which methodology/model/effort is selected per phase without mixing it into
+  readiness.
+- **Discovery intake:** `dashboard --json` carries `discovery_intake` from readiness:
+  open `production_findings`, `spec_doubts`, and `spec_change_requests`. The current template keeps the top-level
+  verdict honest through readiness/caps; future panels may render the intake directly.
+- **ADR experiments:** ADR rows may carry `adr_status: "experiment"`, `review_by`,
+  `review_trigger`, `experiment_valid`, `experiment_missing`, and `expired`; top-level
+  `adr_experiments` summarizes open/malformed/expired experiments. This is advisory
+  visibility for measured hypotheses, not readiness scoring.
+- **Session telemetry (optional, vendor-reported):** if `.uscha/telemetry.jsonl` exists,
+  the skill aggregates it and MERGES a `telemetry` object into `DATA`. This is the ONE
+  panel that is **narrated by the vendor (Claude Code), not measured by the engine** —
+  tokens, wall time, model, effort — so it renders in a **segregated strip** labeled as
+  such, never mixed with the measured panels. `dashboard --json` NEVER emits it; it enters
+  only through this adapter. Absent file → no strip (degrades). This is the doctrinal
+  line: telemetry is neither a fact-gate nor a guess-advisor, so it must not dilute
+  *measured beats narrated*.
+
+## Flow
+
+1. **Resolve the engine.** Use the first one that exists:
+   - `./.claude/skills/uscha-devloop/qa_ledger.py` (per-project install)
+   - `~/plugins/uscha/skills/uscha-devloop/qa_ledger.py` (Codex plugin install)
+   - `~/.codex/skills/uscha-devloop/qa_ledger.py` (Codex raw-skills install)
+   - `~/.claude/skills/uscha-devloop/qa_ledger.py` (Claude global install)
+
+2. **Resolve the ledger.** `QA-LEDGER.json` in the cwd (or the `--ledger` the user
+   points to). If it does not exist, warn: you have to run `uscha-devloop` (or
+   `qa_ledger.py init`) first — with no ledger there is no state to look at.
+
+   (`<skill-dir>` below = this folder: `.claude/skills/uscha-mirador/` per-project, or `~/plugins/uscha/skills/uscha-mirador/` / `~/.codex/skills/uscha-mirador/` / `~/.claude/skills/uscha-mirador/` global.)
+
+3. **(Optional) record this session's telemetry.** For the vendor-telemetry strip, append
+   the current Claude Code session to the sidecar:
+   ```bash
+   python3 <skill-dir>/telemetry-extract.py <path-to-CC-transcript.jsonl>
+   ```
+   It **upserts by session** (safe to re-run — a watch loop won't inflate the totals). Skip
+   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:
+   ```bash
+   python3 <skill-dir>/mirador-render.py --engine <engine> --ledger QA-LEDGER.json \
+       --template <skill-dir>/mirador.template.html --out mirador.html
+   ```
+   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`.
+
+## 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:
+
+```bash
+# Windows:  powershell -NoProfile -File <skill-dir>\mirador-watch.ps1 -Interval 30
+# Unix:     bash <skill-dir>/mirador-watch.sh 30
+```
+
+It re-renders `mirador.html` every N seconds (default 30) from the current ledger, rendered
+with a matching `<meta http-equiv="refresh">` so the open page reloads on its own — **no
+server**. It is only as live as the **ledger**: the picture changes at the dev-loop's
+measured checkpoints (snapshots, gates, `readiness --record`), not per keystroke. Honest by
+design — it shows measured state, which changes at measured moments.
+
+## Session telemetry — sidecar contract
+
+`.uscha/telemetry.jsonl` is an **append-only** file, one JSON object per session/run:
+
+```jsonl
+{"at": "2026-07-05T23:40:00Z", "model": "claude-opus-4-8", "tokens_in": 240000, "tokens_out": 41000, "ms": 4200000, "by_model": [{"model": "claude-opus-4-8", "tokens_in": 240000, "tokens_out": 41000}], "note": "mirador build"}
+```
+
+`effort` and `note` are **optional** and are NOT produced by `telemetry-extract.py` (a Claude
+Code transcript carries no reliable effort label) — add them by hand if you want them; the
+strip shows `—` when `effort` is absent. `by_model` is per-**tokens** (session-level `ms` only).
+
+- **Who writes it:** the AGENT / operator, NEVER the engine (the engine is model-agnostic
+  and cannot see tokens). Two honest sources:
+  - **`telemetry-extract.py <transcript.jsonl>`** (shipped in this skill folder): parses a
+    Claude Code session transcript — each assistant turn carries a `usage` block
+    (`input_tokens` / `cache_*_input_tokens` / `output_tokens`) and a `model` — sums per
+    model, computes wall time from the timestamps, and appends one line (with a `by_model`
+    breakdown). Real, vendor-native data. Best-effort: unknown/older schemas degrade, never
+    crash; no usage found → nothing appended.
+  - **Manual append**: paste the session's numbers from Claude Code's own cost view.
+- **Persistence:** the file itself IS the history (portable, diffable, greppable). Add it to
+  the project's `.gitignore` — it is per-machine telemetry, not repo state. (A pure-client
+  alternative is `localStorage` inside `mirador.html`, but the sidecar survives regeneration,
+  so it is the default.)
+- **Boundary (non-negotiable):** this is the ONLY place vendor-narrated numbers enter the
+  mirador. They are shown, never gated, never fed into readiness — telemetry answers "what
+  did it cost", the measured panels answer "is it correct". Keep them apart.
+
+## Rules
+
+- **Zero computation in the skill.** The numbers come from the ledger. If a panel looks
+  empty, it's because the engine doesn't have that source yet (truth-pass), not because
+  painting it was missed.
+- **Read-only.** The skill does not run gates or modify the ledger. `dashboard` is
+  read-only; the only one that writes (opt-in) is `readiness --record`, and that is the
+  loop's decision, not this skill's.
+- **`mirador.html` is a generated artifact** — suggest adding it to the project's
+  `.gitignore`; it regenerates whenever you want.

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

@@ -0,0 +1,112 @@
+#!/usr/bin/env python3
+"""mirador-render.py -- render mirador.html from the live ledger (uscha-kit 1.34.0).
+
+Standalone renderer used by the uscha-mirador skill AND by mirador-watch (the live
+second-screen loop). It:
+  1. runs `qa_ledger.py dashboard --json` (read-only engine call),
+  2. if the telemetry sidecar exists, aggregates it (per-model merge) and merges a
+     `telemetry` object into DATA -- vendor-reported, NEVER from the engine,
+  3. injects `const DATA` between the template's markers and writes mirador.html.
+
+The engine stays model-agnostic: telemetry is merged HERE, in the adapter, never in
+qa_ledger.py.
+
+Usage:
+  python3 mirador-render.py --engine <qa_ledger.py> --ledger QA-LEDGER.json \
+      --template mirador.template.html --out mirador.html \
+      [--sidecar .uscha/telemetry.jsonl] [--refresh 30]
+"""
+import argparse
+import json
+import os
+import re
+import subprocess
+import sys
+
+
+def aggregate_telemetry(path):
+    """Sum the sidecar's per-session lines into one telemetry object, merging by_model
+    (tokens per model) across sessions. Returns None if the file is absent/empty."""
+    if not path or not os.path.isfile(path):
+        return None
+    lines = []
+    for line in open(path, encoding="utf-8"):
+        line = line.strip()
+        if not line:
+            continue
+        try:
+            lines.append(json.loads(line))
+        except ValueError:
+            continue
+    if not lines:
+        return None
+    tin = sum(l.get("tokens_in") or 0 for l in lines)
+    tout = sum(l.get("tokens_out") or 0 for l in lines)
+    ms = sum(l.get("ms") or 0 for l in lines)
+    by = {}
+    for l in lines:
+        for m in l.get("by_model") or []:
+            agg = by.setdefault(m.get("model", "unknown"), [0, 0])
+            agg[0] += m.get("tokens_in") or 0
+            agg[1] += m.get("tokens_out") or 0
+    by_model = [{"model": k, "tokens_in": v[0], "tokens_out": v[1]}
+                for k, v in sorted(by.items())]
+    effort = next((l.get("effort") for l in reversed(lines) if l.get("effort")), None)
+    model = (by_model[0]["model"] if len(by_model) == 1
+             else "+".join(m["model"] for m in by_model) if by_model else None)
+    return {"source": "Claude Code", "sessions": len(lines),
+            "tokens_in": tin, "tokens_out": tout, "ms": ms or None,
+            "model": model, "effort": effort, "by_model": by_model}
+
+
+def main():
+    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")
+    ap.add_argument("--ledger", default="QA-LEDGER.json")
+    ap.add_argument("--template", required=True, help="path to mirador.template.html")
+    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)")
+    args = ap.parse_args()
+
+    try:
+        raw = subprocess.check_output(
+            [sys.executable, args.engine, "dashboard", "--ledger", args.ledger, "--json"],
+            text=True, encoding="utf-8")
+    except (subprocess.CalledProcessError, OSError) as e:
+        print(f"[mirador-render] dashboard failed: {e}", file=sys.stderr)
+        return 1
+    try:
+        data = json.loads(raw)
+    except ValueError as e:
+        print(f"[mirador-render] dashboard returned invalid JSON: {e}", file=sys.stderr)
+        return 1
+
+    tel = aggregate_telemetry(args.sidecar)
+    if tel:
+        data["telemetry"] = tel  # vendor-reported, merged in the adapter -- never by the engine
+
+    try:
+        tpl = open(args.template, encoding="utf-8").read()
+    except OSError as e:
+        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*/")
+    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)
+    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'})")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -0,0 +1,22 @@
+# mirador-watch.ps1 -- live second-screen mirador (uscha-kit 1.34.0), Windows.
+# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
+# with a meta-refresh at the same interval, so a browser open on it updates on its own.
+#
+# Usage (run in a spare terminal, from the project root):
+#   powershell -NoProfile -File <kit>\.claude\skills\uscha-mirador\mirador-watch.ps1 [-Interval 30]
+# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
+#
+# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
+param([int]$Interval = 30)
+$here     = Split-Path -Parent $MyInvocation.MyCommand.Path
+$engine   = if ($env:ENGINE)   { $env:ENGINE }   else { Join-Path $here "..\uscha-devloop\qa_ledger.py" }
+$ledger   = if ($env:LEDGER)   { $env:LEDGER }   else { "QA-LEDGER.json" }
+$template = if ($env:TEMPLATE) { $env:TEMPLATE } else { Join-Path $here "mirador.template.html" }
+$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
+  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

@@ -0,0 +1,26 @@
+#!/usr/bin/env bash
+# mirador-watch.sh -- live second-screen mirador (uscha-kit 1.34.0).
+# Regenerates mirador.html every N seconds from the current ledger; the page is rendered
+# with a meta-refresh at the same interval, so a browser open on it updates on its own.
+#
+# Usage (run in a spare terminal, from the project root):
+#   bash <kit>/.claude/skills/uscha-mirador/mirador-watch.sh [interval_seconds]
+# then open mirador.html in a browser on your second screen. Ctrl-C to stop.
+#
+# Overridable via env: ENGINE, LEDGER, TEMPLATE, OUT, PYTHON.
+set -u
+HERE="$(cd "$(dirname "$0")" && pwd)"
+INTERVAL="${1:-30}"
+ENGINE="${ENGINE:-$HERE/../uscha-devloop/qa_ledger.py}"
+LEDGER="${LEDGER:-QA-LEDGER.json}"
+TEMPLATE="${TEMPLATE:-$HERE/mirador.template.html}"
+OUT="${OUT:-mirador.html}"
+PY="${PYTHON:-python3}"
+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" || \
+    echo "mirador-watch: render failed (ledger missing? run uscha-devloop first) -- retrying"
+  sleep "$INTERVAL"
+done