katalyst-forge 5.2.1__tar.gz → 5.3.0__tar.gz

{katalyst_forge-5.2.1 → katalyst_forge-5.3.0}/CHANGELOG.md

@@ -16,6 +16,24 @@ PyPI package version. A breaking node-type/model change bumps `schema_version`.
 
 ---
 
+## [5.3.0] -- 2026-08-08
+
+### Added
+
+- **The governance half of the Forge run report, as a tile dashboard** (RIC-1624). The pre-RIC-1590 report was described by its own commit as cost *and governance* observability; only the cost half survived the move into the metrics wing. Restored as six tiles, each summarising one concern and linking to a detail view: run spend, rollup agreement, stage coverage, degraded sessions, unpriced models, and spend per model. Adds `metrics/run_health.py` (a pure core computing the session tree, stage attribution, rollup drift, degradation and pricing coverage), `metrics/measurement.py` (a figure that was measured, or an explicit absence, which refuses addition and float coercion), `metrics/tiles.py`, and `metrics/forge_stages.py` (the eleven stage names, previously spelled out in two places). None of it enters `metric_definitions`: a new `opencode-run-health` signal source declares `signal_type: run_health` with no `billing_mode` and no `metric_ref`, and both pipelines filter on `signal_type`.
+- **`optional_fields` awareness for provider-synthesized values**, already shipped in 5.2.0, is now exercised by the run-health source.
+
+### Fixed
+
+- **Bundle content installed into a project is now discoverable** (RIC-1629). The only fallback understood the katalyst-forge working-copy layout, resolving through `__file__.parents[3]`, which inside `site-packages` points at the Python installation rather than at any project. So an installed package could never find content a project had installed correctly, and every invocation needed `FORGE_COST_CONTENT_DIR` set by hand. Resolution order is now explicit argument, environment override, the project's installed taxonomy, then the working-copy layout.
+- **Five dashboard alignment defects** (RIC-1632). A CSS class collision on `.figure` stacked every tile label above its value, because the pre-existing SVG figure rule sets `flex-direction: column` and the tile rule never overrode it. Six tiles rendered as five across plus one orphan of a different height. Sublines floated at five different heights within a row. Numeric table columns sat right-aligned under left-aligned headers. And a drift of `-2E-16` rendered as `$-0.00`, now fixed at `dashboard.to_cents`, the single rounding point, so the text renderer and percentage formatter benefit too; a sign still survives wherever there is a magnitude to describe.
+- **The `kata-tax-writer` Kind Mapping matches the registry** (RIC-1625). Every row paired a CamelCase kind with a `katalyst.taxonomy.plugins.*/v1alpha` apiVersion, and neither is recognised: loaders match lowercase kinds exactly and the parser skips an unknown apiVersion before a loader sees the document. Since the writer is the single writer, every artifact other agents create flowed through it. `plugin-stage` needed `cicd_stage`, the job and workflow templates needed the `cicd_` prefix, and `taxonomy-node` named a kind no creation template emits. Four artifact types were not mis-mapped but unsupported: bounded contexts, aggregates, domain events and glossary terms are fields on a single `business_domain_model` document, which the shared `BDM-` id prefix already implied.
+- **The llm-gateway mapping declares itself unverified** (RIC-1622). Its eight field paths were written by analogy to the OpenCode source rather than read from live gateway output. A `verified_against_provider: false` flag now pairs with a test asserting the provider still raises while it is false, so an unverified mapping cannot quietly begin producing figures.
+
+### Changed
+
+- **Scaffold drift between the authoritative agents and the bundled copies is gated, and the existing drift is resolved** (RIC-1626). Every agent and skill exists twice, and 19 of 52 pairs had diverged with neither copy signposted as authoritative. All twelve substantive divergences turned out to be the scaffold being stale: five carried Stellite guidance, including an instruction to run `kata tax stellite validate`, a command that exists nowhere, and the rest carried the abandoned user-story vocabulary. Three scaffold-only orphans were also removed, among them a whole agent for the deleted Stellite subsystem, which the original pair-based gate could not see.
+
 ## [5.2.1] -- 2026-08-08
 
 ### Fixed

{katalyst_forge-5.2.1 → katalyst_forge-5.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: katalyst-forge
-Version: 5.2.1
+Version: 5.3.0
 Summary: Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)
 Author: eSimplicity
 License: Proprietary

{katalyst_forge-5.2.1 → katalyst_forge-5.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "katalyst-forge"
-version = "5.2.1"
+version = "5.3.0"
 description = "Katalyst Forge: the delivery-lifecycle bundle (node kinds, wings, agents, templates, schemas)"
 license = { text = "Proprietary" }
 requires-python = ">=3.12"

{katalyst_forge-5.2.1 → katalyst_forge-5.3.0}/src/katalyst_forge/metrics/dashboard.py

@@ -37,8 +37,15 @@ UNIT_PERCENTAGE: Final[str] = "percentage"
 
 
 def to_cents(value: Decimal) -> Decimal:
-    """Round to the cent, once, at the point of display."""
-    return value.quantize(CENTS, rounding=ROUND_HALF_UP)
+    """Round to the cent, once, at the point of display.
+
+    A value that rounds away to nothing is returned unsigned. Without this, a
+    drift of -2E-16 formats as "-0.00" and a dashboard shows "$-0.00", which reads
+    as a broken report rather than as two figures agreeing. The sign only survives
+    when there is a magnitude for it to describe.
+    """
+    cents = value.quantize(CENTS, rounding=ROUND_HALF_UP)
+    return abs(cents) if cents == 0 else cents
 
 
 def format_usd(value: Decimal) -> str:

katalyst_forge-5.3.0/src/katalyst_forge/metrics/forge_stages.py

@@ -0,0 +1,61 @@
+"""The canonical Forge lifecycle stages, defined once.
+
+The eleven names were spelled out in the OpenCode stage-matching pattern and
+again in the run report that preceded this module, which is how a stage list
+drifts. Everything that needs them now reads them from here.
+
+The distinction between attributed and executed matters and is kept in the
+vocabulary: a stage is ATTRIBUTED when a session's agent name or title implies
+it. That is a heuristic over names, not evidence that a gate ran, so nothing here
+claims an unobserved stage did not happen.
+"""
+
+from __future__ import annotations
+
+import re
+from typing import Final
+
+__all__ = ("FORGE_STAGES", "STAGE_PATTERN", "infer_stage_from_text")
+
+FORGE_STAGES: Final[tuple[str, ...]] = (
+    "design",
+    "orchestrate",
+    "review",
+    "implement",
+    "qa",
+    "commit",
+    "deploy",
+    "verify",
+    "release",
+    "operate",
+    "feedback",
+)
+
+# The agent form is matched first and separately from the bare word. A session
+# titled "review the PR" is a much weaker signal than an agent literally named
+# kata-forge-review, and the caller is told which one matched so the report can
+# say so instead of presenting both as equal evidence.
+_AGENT_FORM: Final[str] = r"\bkata-forge-([a-z-]+)\b"
+_BARE_WORD: Final[str] = r"\b(" + "|".join(FORGE_STAGES) + r")\b"
+
+STAGE_PATTERN: Final[re.Pattern[str]] = re.compile(f"{_AGENT_FORM}|{_BARE_WORD}", re.IGNORECASE)
+
+
+def infer_stage_from_text(text: str) -> tuple[str | None, bool]:
+    """Return (stage, matched_agent_form).
+
+    matched_agent_form is what lets the report distinguish a stage read off an
+    agent name from one guessed out of prose.
+    """
+    found = STAGE_PATTERN.search(text)
+    if found is None:
+        return None, False
+    agent_form = found.group(1)
+    if agent_form:
+        stage = agent_form.lower()
+        # kata-forge-qa-lead implies the qa stage; keep the longest known prefix.
+        for candidate in FORGE_STAGES:
+            if stage == candidate or stage.startswith(f"{candidate}-"):
+                return candidate, True
+        return None, True
+    return found.group(2).lower(), False

{katalyst_forge-5.2.1 → katalyst_forge-5.3.0}/src/katalyst_forge/metrics/generate_dashboard.py

@@ -14,7 +14,8 @@ from __future__ import annotations
 import argparse
 import os
 import sys
-from collections.abc import Callable, Mapping, Sequence
+import time
+from collections.abc import Callable, Iterator, Mapping, Sequence
 from decimal import Decimal
 from pathlib import Path
 from typing import Final, cast
@@ -29,6 +30,10 @@ from katalyst_forge.metrics.html_report import render_html_report
 from katalyst_forge.metrics.protocols import PriceCatalogue, RoutingPolicy
 from katalyst_forge.metrics.registry import SignalProviderRegistry
 from katalyst_forge.metrics.routing_policy import build_policy
+from katalyst_forge.metrics.run_health import RunHealth, compute_run_health, project_run_health
+
+SIGNAL_TYPE_COST_EVENT: Final[str] = "cost_event"
+SIGNAL_TYPE_RUN_HEALTH: Final[str] = "run_health"
 
 METRIC_DEFINITIONS_FILE: Final[str] = "metric-definitions.yaml"
 SIGNAL_SOURCES_FILE: Final[str] = "signal-sources.yaml"
@@ -71,18 +76,64 @@ def index_by_name(docs: Sequence[Document]) -> dict[str, Document]:
     return indexed
 
 
-def resolve_content_dir(explicit: str | None) -> Path:
+def _taxonomy_roots(start: Path) -> Iterator[Path]:
+    """Yield each .global/taxonomy from start upward, nearest first."""
+    current = start.resolve()
+    for directory in (current, *current.parents):
+        candidate = directory / ".global" / "taxonomy"
+        if candidate.is_dir():
+            yield candidate
+
+
+def _installed_content_dir(start: Path) -> Path | None:
+    """Find bundle content installed into a project's taxonomy.
+
+    The wheel ships templates/creation and templates/scaffolds but not
+    templates/bundles, because the bundle collection is released separately on
+    templates-v* tags. That split is fine; what was not fine is that the only
+    fallback understood the working-copy layout, so an installed package could
+    never find content a project had correctly installed and every invocation
+    needed FORGE_COST_CONTENT_DIR set by hand.
+
+    Matched on the presence of metric-definitions.yaml rather than on a directory
+    name, because the name is a bundle's choice and the file the loader needs is not.
+    """
+    for taxonomy_root in _taxonomy_roots(start):
+        if (taxonomy_root / METRIC_DEFINITIONS_FILE).is_file():
+            return taxonomy_root
+        # One level down covers a bundle installed into its own directory. Kept
+        # shallow on purpose: a deep walk would make the answer depend on unrelated
+        # content that happens to sit nearby.
+        for child in sorted(taxonomy_root.iterdir()):
+            if child.is_dir() and (child / METRIC_DEFINITIONS_FILE).is_file():
+                return child
+    return None
+
+
+def resolve_content_dir(explicit: str | None, *, start: Path | None = None) -> Path:
+    """Resolve the cost-observability content directory.
+
+    Order is explicit argument, environment override, the project's installed
+    taxonomy, then the working-copy layout. The override stays ahead of discovery so
+    a caller can always point at content deliberately.
+    """
     if explicit:
         return Path(explicit)
     from_env = os.environ.get(FORGE_COST_CONTENT_DIR_ENV)
     if from_env:
         return Path(from_env)
+    installed = _installed_content_dir(start if start is not None else Path.cwd())
+    if installed is not None:
+        return installed
     candidate = Path(__file__).resolve().parents[3] / "templates" / "bundles" / "cost-observability"
     if candidate.is_dir():
         return candidate
     raise SystemExit(
-        f"cost-observability content not found; set {FORGE_COST_CONTENT_DIR_ENV} to the "
-        f"directory holding {METRIC_DEFINITIONS_FILE}"
+        f"cost-observability content not found. Looked for {METRIC_DEFINITIONS_FILE} "
+        f"in the nearest .global/taxonomy and one level below it, then in the "
+        f"katalyst-forge working copy. Install the cost-observability bundle into "
+        f"this project, or set {FORGE_COST_CONTENT_DIR_ENV} to the directory "
+        f"holding {METRIC_DEFINITIONS_FILE}"
     )
 
 
@@ -112,6 +163,12 @@ def build_results(
         provider_key = spec.get("provider")
         if not isinstance(provider_key, str):
             continue
+        # Filtered rather than skipped-with-a-warning. A run_health source declares
+        # no billing_mode, so resolve() would raise UnknownBillingModeError, which
+        # build_results would catch and print on every single run. The report would
+        # look fine while emitting a permanent false warning.
+        if spec.get("signal_type") != SIGNAL_TYPE_COST_EVENT:
+            continue
         try:
             factory = active_registry.resolve(provider_key)
             provider = factory(env=provider_env)
@@ -143,6 +200,52 @@ def build_results(
     return results
 
 
+def build_run_health(
+    *,
+    run_id: str,
+    signal_sources: Mapping[str, Document],
+    provider_env: Mapping[str, str],
+    catalogue: PriceCatalogue,
+    now_ms: int | None = None,
+    registry: SignalProviderRegistry | None = None,
+    err: object = None,
+) -> RunHealth | None:
+    """Fetch and compute run health, or None when no run_health source is reachable.
+
+    Returns None rather than an empty RunHealth so the renderer can omit the
+    governance tiles entirely instead of showing six tiles of zeros, which would
+    read as a clean run rather than an unmeasured one.
+    """
+    active_registry = registry if registry is not None else SignalProviderRegistry()
+    stream = err if err is not None else sys.stderr
+
+    for source_name, source_doc in signal_sources.items():
+        spec = _as_mapping(source_doc.get("spec"))
+        if spec.get("signal_type") != SIGNAL_TYPE_RUN_HEALTH:
+            continue
+        provider_key = spec.get("provider")
+        if not isinstance(provider_key, str):
+            continue
+        try:
+            factory = active_registry.resolve(provider_key)
+            provider = factory(env=provider_env)
+            fetch = getattr(provider, "fetch_run_health", None)  # noqa: B009
+            if fetch is None:
+                print(
+                    f"skipping run health source {source_name}: provider "
+                    f"'{provider_key}' does not report run health",
+                    file=stream,  # type: ignore[arg-type]
+                )
+                continue
+            records = fetch(_as_mapping(spec.get("query_config")), run_id=run_id)
+            batch = project_run_health(run_id=run_id, records=records)
+            return compute_run_health(batch, catalogue=catalogue, now_ms=now_ms)
+        except MetricsAdapterError as exc:
+            print(f"skipping run health source {source_name}: {exc}", file=stream)  # type: ignore[arg-type]
+            continue
+    return None
+
+
 def _opencode_catalogue(
     *, signal_sources: Mapping[str, Document], provider_env: Mapping[str, str]
 ) -> PriceCatalogue:
@@ -207,6 +310,14 @@ def main(argv: Sequence[str] | None = None) -> int:
         lambda: _opencode_catalogue(signal_sources=signal_sources, provider_env=provider_env)
     )
 
+    health = build_run_health(
+        run_id=run_id,
+        signal_sources=signal_sources,
+        provider_env=provider_env,
+        catalogue=catalogue,
+        now_ms=int(time.time() * 1000),
+    )
+
     results = build_results(
         run_id=run_id,
         metric_definitions=metric_definitions,
@@ -223,6 +334,7 @@ def main(argv: Sequence[str] | None = None) -> int:
             results=results,
             threshold_profile_doc=threshold_profile,
             units=units,
+            health=health,
         )
     else:
         rendered = render_dashboard(

{katalyst_forge-5.2.1 → katalyst_forge-5.3.0}/src/katalyst_forge/metrics/html_report.py

@@ -24,6 +24,8 @@ from katalyst_forge.metrics.dashboard import (
     evaluate_band,
     format_value,
 )
+from katalyst_forge.metrics.run_health import RunHealth
+from katalyst_forge.metrics.tiles import Tile, build_tiles
 
 SVG_MIN_WIDTH: Final[int] = 1450  # matches .figframe svg min-width in the house skeleton
 FONT_MONO: Final[str] = "ui-monospace,SFMono-Regular,Menlo,Consolas,monospace"
@@ -263,6 +265,8 @@ _STYLE: Final[str] = """
   --ok: #1c6b41; --ok-bg: #e6f4ea;
   --sans: -apple-system, BlinkMacSystemFont, "Segoe UI", "Helvetica Neue", Arial, sans-serif;
   --mono: ui-monospace, SFMono-Regular, "SF Mono", Menlo, Consolas, "Liberation Mono", monospace;
+  --ease: cubic-bezier(0.22, 1, 0.36, 1);
+  --shadow-lg: 0 16px 34px -10px rgba(16,16,24,0.16), 0 6px 14px -6px rgba(16,16,24,0.09);
 }
 @media (prefers-color-scheme: dark) {
   :root {
@@ -302,6 +306,42 @@ h2 { font-size: clamp(21px, 2.2vw, 28px); font-weight: 760; letter-spacing: -0.0
 .pill.warn { background: var(--warn-bg); color: var(--warn); }
 .pill.ok { background: var(--ok-bg); color: var(--ok); }
 footer { margin-top: 50px; border-top: 1px solid var(--rule); padding: 20px 0 48px; font-size: 14px; color: var(--ink-3); }
+
+/* Tile grid. Card treatment follows the platform-briefs house style: mono
+   eyebrow, balanced heading, hover lift, focus-visible ring. Severity colours
+   reuse the ok/warn tokens already defined above, and `absent` deliberately gets
+   the neutral rule colour rather than green, because "not measured" must not
+   read as "measured and fine". */
+.tilegrid{display:grid;grid-template-columns:repeat(3,1fr);grid-auto-rows:1fr;gap:16px;margin:12px 0 8px;}
+@media (max-width:1000px){.tilegrid{grid-template-columns:repeat(2,1fr);}}
+@media (max-width:640px){.tilegrid{grid-template-columns:1fr;}}
+a.tile{display:flex;flex-direction:column;text-decoration:none;background:var(--surface);border:1px solid var(--rule);border-radius:10px;padding:18px 20px;transition:border-color .25s var(--ease),box-shadow .3s var(--ease),transform .3s var(--ease);}
+a.tile:hover{border-color:var(--accent);box-shadow:var(--shadow-lg);transform:translateY(-3px);}
+a.tile:focus-visible{outline:2px solid var(--accent);outline-offset:2px;}
+.tile .k{font-family:var(--mono);font-size:10px;letter-spacing:.08em;text-transform:uppercase;color:var(--accent);margin-bottom:6px;font-weight:500;}
+.tile h3{font-size:17px;font-weight:600;letter-spacing:-0.01em;margin:0 0 10px;color:var(--ink);line-height:1.35;}
+.tile:hover h3{color:var(--accent);}
+.tile .tilefig{display:flex;flex-direction:row;justify-content:space-between;align-items:baseline;gap:10px;margin:5px 0;}
+.tile .tilefig .tilefig-lbl{font-size:12px;color:var(--ink-3);flex:0 1 auto;}
+.tile .tilefig .tilefig-val{font-family:var(--mono);font-size:15px;color:var(--ink);font-weight:600;flex:0 0 auto;white-space:nowrap;}
+.tile .tilefig .tilefig-val.absent{color:var(--ink-3);font-weight:500;font-style:italic;font-size:13px;}
+.tile .meta{font-family:var(--mono);font-size:11px;color:var(--ink-3);margin-top:auto;padding-top:12px;line-height:1.5;}
+.tile.sev-ok{border-left:3px solid var(--ok);}
+.tile.sev-warn{border-left:3px solid var(--warn);}
+.tile.sev-absent{border-left:3px solid var(--rule);}
+.tile.sev-info{border-left:3px solid var(--accent);}
+.detail{margin-top:36px;padding-top:20px;border-top:1px solid var(--rule);scroll-margin-top:20px;}
+.detail h2{font-size:20px;margin:0 0 4px;letter-spacing:-0.015em;}
+.detail .note{font-size:14px;color:var(--ink-2);margin:0 0 14px;}
+.tbl{width:100%;border-collapse:collapse;font-size:13px;margin-top:8px;}
+.tbl th{text-align:left;font-family:var(--mono);font-size:10px;letter-spacing:.06em;text-transform:uppercase;color:var(--ink-3);padding:6px 10px;border-bottom:1px solid var(--rule);font-weight:500;}
+.tbl td{padding:7px 10px;border-bottom:1px solid var(--rule-2);color:var(--ink-2);}
+.tbl td.num{font-family:var(--mono);color:var(--ink);text-align:right;}
+.tbl th.num{text-align:right;}
+.tbl tr:last-child td{border-bottom:none;}
+.basis{font-family:var(--mono);font-size:10px;padding:1px 6px;border-radius:4px;background:var(--surface-2);color:var(--ink-3);}
+.basis.rollup{background:var(--warn-bg);color:var(--warn);}
+.tree{font-family:var(--mono);font-size:12px;line-height:1.9;color:var(--ink-2);}
 """
 
 
@@ -312,6 +352,7 @@ def render_html_report(
     threshold_profile_doc: Mapping[str, object],
     units: Mapping[str, str] | None = None,
     generated: str | None = None,
+    health: RunHealth | None = None,
 ) -> str:
     """Render a standalone HTML report from already-computed metric results.
 
@@ -322,6 +363,32 @@ def render_html_report(
     unit_by_metric = dict(units) if units is not None else {}
     results_by_name = {result.metric_name: result for result in results}
     when = generated if generated is not None else ""
+    # Composed from the parts that exist, so an absent timestamp does not leave a
+    # dangling separator or a sentence with a hole in it.
+    eyebrow = " \u00b7 ".join(
+        part for part in ("Cost observability", f"run {run_id}", when) if part
+    )
+    footer_note = (
+        f"Generated {when}. Internal working document." if when else "Internal working document."
+    )
+
+    # health is optional so a cost-only render stays byte-identical to before.
+    tiles = build_tiles(results=results, health=health) if health is not None else ()
+    tile_grid = _tile_grid(tiles) if tiles else ""
+    details = (
+        "\n".join(
+            (
+                _session_tree_detail(health),
+                _integrity_detail(health),
+                _stage_detail(health),
+                _degraded_detail(health),
+                _unpriced_detail(health),
+                _per_model_detail(health),
+            )
+        )
+        if health is not None
+        else ""
+    )
 
     cards = _metric_cards_section(results, threshold_profile_doc, unit_by_metric)
     metered_figure = _mode_figure(results, BillingMode.METERED, unit_by_metric, 1)
@@ -331,7 +398,7 @@ def render_html_report(
     body = f"""
 <div class="shell">
   <header class="masthead">
-    <div class="eyebrow">Cost observability &middot; run {_escape(run_id)} &middot; {_escape(when)}</div>
+    <div class="eyebrow">{_escape(eyebrow)}</div>
     <h1>Metric results for this run, by billing mode</h1>
     <p class="standfirst">
       Metered spend and subscription-notional allocation are always shown as separate
@@ -339,6 +406,8 @@ def render_html_report(
     </p>
   </header>
 
+{tile_grid}
+
   <section id="summary">
     <div class="sec-kicker">01 &middot; Summary</div>
     <h2>Every metric, split by the billing mode that produced it</h2>
@@ -367,8 +436,10 @@ def render_html_report(
     {routing}
   </section>
 
+{details}
+
   <footer>
-    <div>Generated {_escape(when)}. Internal working document.</div>
+    <div>{_escape(footer_note)}</div>
   </footer>
 </div>
 """
@@ -381,3 +452,182 @@ def render_html_report(
         f"<title>{_escape(title)}</title>\n"
         f"<style>{_STYLE}</style>\n</head>\n<body>\n{body}\n</body>\n</html>\n"
     )
+
+
+# --- Tile grid and detail views (RIC-1624) -----------------------------------
+
+
+def _headline_row(label: str, text: str) -> str:
+    absent = "not measured" in text
+    cls = "tilefig-val absent" if absent else "tilefig-val"
+    return (
+        f'<div class="tilefig"><span class="tilefig-lbl">{_escape(label)}</span>'
+        f'<span class="{cls}">{_escape(text)}</span></div>'
+    )
+
+
+def _tile_html(tile: Tile) -> str:
+    figures = "".join(_headline_row(h.label, h.text) for h in tile.headlines)
+    return (
+        f'      <a class="tile sev-{_escape(tile.severity)}" href="#{_escape(tile.detail_anchor)}">\n'
+        f'        <div class="k">{_escape(tile.eyebrow)}</div>\n'
+        f"        <h3>{_escape(tile.title)}</h3>\n"
+        f"        {figures}\n"
+        f'        <div class="meta">{_escape(tile.subline)}</div>\n'
+        f"      </a>"
+    )
+
+
+def _tile_grid(tiles: Sequence[Tile]) -> str:
+    cards = "\n".join(_tile_html(tile) for tile in tiles)
+    return f'    <div class="tilegrid">\n{cards}\n    </div>'
+
+
+def _detail(anchor: str, title: str, note: str, body: str) -> str:
+    return (
+        f'    <section class="detail" id="{_escape(anchor)}">\n'
+        f"      <h2>{_escape(title)}</h2>\n"
+        f'      <p class="note">{_escape(note)}</p>\n'
+        f"{body}\n"
+        f"    </section>"
+    )
+
+
+def _integrity_detail(health: RunHealth) -> str:
+    integrity = health.integrity
+    rows: list[str] = []
+    for stale in integrity.stale_rollups:
+        direction = "rollup under-reports" if stale.rollup_under_reports else "rollup over-reports"
+        rows.append(
+            f"<tr><td>{_escape(stale.session_id)}</td><td>{_escape(stale.agent or '')}</td>"
+            f'<td class="num">{stale.drift_usd}</td><td>{_escape(direction)}</td></tr>'
+        )
+    table = (
+        '      <table class="tbl"><thead><tr><th>Session</th><th>Agent</th>'
+        '<th class="num">Drift USD</th><th>Direction</th></tr></thead><tbody>'
+        + "".join(rows)
+        + "</tbody></table>"
+        if rows
+        else '      <p class="note">No session drifted by more than a cent.</p>'
+    )
+    note = (
+        "Two figures for the same money, by two routes. They are reported "
+        "separately and never summed, because adding them would double the run. "
+        f"Basis: {integrity.basis}. Messages checked: {integrity.messages_checked}."
+    )
+    return _detail("detail-run-integrity", "Rollup agreement", note, table)
+
+
+def _stage_detail(health: RunHealth) -> str:
+    rows = "".join(
+        f"<tr><td>{_escape(stage)}</td><td>"
+        + ("attributed" if observed else "not attributed")
+        + "</td></tr>"
+        for stage, observed in health.stage_coverage.stages
+    )
+    note = (
+        "A stage is attributed when a session's agent name or title implies it, "
+        "which is a heuristic over names. An unattributed stage is not evidence "
+        "that the stage did not run."
+    )
+    return _detail(
+        "detail-stage-coverage",
+        "Stage coverage",
+        note,
+        '      <table class="tbl"><thead><tr><th>Stage</th><th>Status</th></tr></thead>'
+        f"<tbody>{rows}</tbody></table>",
+    )
+
+
+def _degraded_detail(health: RunHealth) -> str:
+    if not health.degraded_sessions:
+        body = '      <p class="note">Every walked session returned its message list in full.</p>'
+    else:
+        rows = "".join(
+            f"<tr><td>{_escape(d.session_id)}</td><td>{_escape(d.agent or '')}</td>"
+            f"<td>{_escape(d.reason)}</td>"
+            f'<td><span class="basis rollup">{_escape(d.figures_from)}</span></td></tr>'
+            for d in health.degraded_sessions
+        )
+        body = (
+            '      <table class="tbl"><thead><tr><th>Session</th><th>Agent</th>'
+            "<th>Reason</th><th>Figures from</th></tr></thead>"
+            f"<tbody>{rows}</tbody></table>"
+        )
+    note = (
+        "A degraded session is one whose message list could not be read, so its "
+        "cost falls back to the provider's session rollup. Its figures are less "
+        "precise and are labelled accordingly."
+    )
+    return _detail("detail-degraded-sessions", "Degraded sessions", note, body)
+
+
+def _unpriced_detail(health: RunHealth) -> str:
+    if not health.unpriced_models:
+        body = '      <p class="note">Every model used has a catalogue price.</p>'
+    else:
+        rows = "".join(f"<tr><td>{_escape(m)}</td></tr>" for m in health.unpriced_models)
+        body = (
+            '      <table class="tbl"><thead><tr><th>Model</th></tr></thead>'
+            f"<tbody>{rows}</tbody></table>"
+        )
+    note = (
+        "While any model the run used has no catalogue price, the cost figures are "
+        "a floor rather than the full spend. Reported here rather than raised, "
+        "because the cost path refuses to guess a price while this view exists to "
+        "show the gap."
+    )
+    return _detail("detail-unpriced-models", "Unpriced models", note, body)
+
+
+def _per_model_detail(health: RunHealth) -> str:
+    rows = "".join(
+        f"<tr><td>{_escape(r.model_identifier)}</td>"
+        f"<td>{_escape(r.provider_identifier or '')}</td>"
+        f'<td class="num">{r.spend_usd.quantize(Decimal("0.01"))}</td>'
+        f'<td class="num">{r.message_count}</td>'
+        f'<td><span class="basis{" rollup" if r.basis == "rollup" else ""}">'
+        f"{_escape(r.basis)}</span></td></tr>"
+        for r in health.per_model
+    )
+    note = (
+        "A message-basis row is measured per message. A rollup-basis row attributes "
+        "a whole session's rollup to one model, which is a guess when that session "
+        "switched model, so the two bases are never mixed into one subtotal."
+    )
+    return _detail(
+        "detail-per-model-spend",
+        "Spend per model",
+        note,
+        '      <table class="tbl"><thead><tr><th>Model</th><th>Provider</th>'
+        '<th class="num">Spend USD</th><th class="num">Messages</th>'
+        "<th>Basis</th></tr></thead>"
+        f"<tbody>{rows}</tbody></table>",
+    )
+
+
+def _session_tree_detail(health: RunHealth) -> str:
+    lines: list[str] = []
+    for session in health.sessions:
+        indent = "&nbsp;" * (session.depth * 4)
+        stage = f" [{session.stage}]" if session.stage else ""
+        source = "" if session.stage_from_agent or not session.stage else " (from title)"
+        label = session.agent or session.title or session.session_id
+        lines.append(
+            f"{indent}{_escape(label)}{_escape(stage)}{_escape(source)} "
+            f'<span class="basis{" rollup" if session.basis == "rollup" else ""}">'
+            f"{_escape(session.basis)}</span>"
+        )
+    body = '      <div class="tree">' + "<br/>".join(lines) + "</div>"
+    note = (
+        f"{len(health.sessions)} session(s) walked, maximum depth {health.max_depth}. "
+        "The run id names the root of the walked tree."
+    )
+    if health.root_is_not_a_root:
+        note = (
+            f"{note} The supplied run id has a parent of its own, so ancestor "
+            "sessions were not walked and every figure covers an incomplete run scope."
+        )
+    if health.orphan_ids:
+        note = f"{note} {len(health.orphan_ids)} session(s) had a parent outside the walked set."
+    return _detail("detail-cost", "Session tree", note, body)