okstra 0.154.1 → 0.154.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.154.1",
+  "version": "0.154.2",
   "description": "Host-aware multi-provider cross-verification orchestrator runtime and agent skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.154.1",
-  "builtAt": "2026-08-05T18:07:27.600Z",
+  "package": "0.154.2",
+  "builtAt": "2026-08-05T18:59:33.609Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/python/okstra_ctl/report_html/render.py

@@ -24,6 +24,7 @@ from .filters import (
     paragraphs,
 )
 from .models import HtmlRunMeta
+from .report_index import inject_report_index
 from .router import HtmlRenderError, resolve_html_route
 
 
@@ -133,7 +134,8 @@ def render_v2_html_view(
     # threading the index through every macro and call site.
     anchors = anchor_index(data)
     chrome = load_dictionary(lang, HTML_DICTIONARY_REL)
-    env.globals["t"] = make_jinja_global(chrome)
+    translate = make_jinja_global(chrome)
+    env.globals["t"] = translate
     env.filters["code_evidence"] = code_evidence
     env.filters["enum_label"] = lambda value, vocabulary: enum_label(value, vocabulary, chrome)
     env.filters["enum_legend"] = lambda vocabulary: enum_legend(vocabulary, chrome)
@@ -154,7 +156,10 @@ def render_v2_html_view(
         "js": response_js + "\n" + base_js,
     }
     output_path = _html_path(data_path)
-    output_path.write_text(env.get_template(route.template_name).render(**context), encoding="utf-8")
+    document = env.get_template(route.template_name).render(**context)
+    output_path.write_text(
+        inject_report_index(document, label=translate("base.contents")), encoding="utf-8"
+    )
     if context["clarificationItems"]:
         # The footer tells the reader to drop the exported file here, so the
         # directory has to exist before they go looking for it.

package/runtime/python/okstra_ctl/report_html/report_index.py

@@ -0,0 +1,75 @@
+"""Build the reader's index that heads the rendered report.
+
+The index is derived from the rendered document instead of being declared in
+each task template. A template that gains a section gets an index entry with
+it, and there is no second list to keep in step.
+
+Anchors come from the id a section already carries or from its
+``data-report-section`` slug — never from the heading text, which changes with
+the report language and would move every link with it.
+"""
+from __future__ import annotations
+
+import re
+
+# Every section of the human view opens with its own h2. A block that does not
+# is not a place the reader navigates to, so it stays out of the index.
+_SECTION_HEAD_RE = re.compile(
+    r'<section\b(?P<attrs>[^>]*)>(?P<heading_open>\s*<h2[^>]*>)(?P<title>.*?)</h2>',
+    re.DOTALL,
+)
+_MAIN_OPEN_RE = re.compile(r"<main\b[^>]*>")
+_ID_RE = re.compile(r'\bid="([^"]+)"')
+_SLUG_RE = re.compile(r'\bdata-report-section="([^"]+)"')
+_TAG_RE = re.compile(r"<[^>]+>")
+
+INDEX_TITLE_ID = "report-index-title"
+
+
+def _heading_text(title_markup: str) -> str:
+    """The heading's words without the markup a link cannot carry."""
+    return " ".join(_TAG_RE.sub("", title_markup).split())
+
+
+def inject_report_index(document: str, *, label: str) -> str:
+    """Return ``document`` with a section index at the top of ``<main>``.
+
+    Sections that lack both an id and a slug are skipped rather than given a
+    generated anchor: a link whose target moves between renders is worse than
+    an entry the reader never had.
+    """
+    opening = _MAIN_OPEN_RE.search(document)
+    if opening is None:
+        return document
+    head, body = document[: opening.end()], document[opening.end() :]
+    entries: list[tuple[str, str]] = []
+
+    def _anchor_section(match: re.Match[str]) -> str:
+        attrs = match.group("attrs")
+        existing = _ID_RE.search(attrs)
+        if existing:
+            anchor = existing.group(1)
+        else:
+            slug = _SLUG_RE.search(attrs)
+            if slug is None:
+                return match.group(0)
+            anchor = f"section-{slug.group(1)}"
+            # Last, not first: templates lead a section with the attribute the
+            # tests and the validator select it by.
+            attrs = f'{attrs} id="{anchor}"'
+        entries.append((anchor, _heading_text(match.group("title"))))
+        return f'<section{attrs}>{match.group("heading_open")}{match.group("title")}</h2>'
+
+    body = _SECTION_HEAD_RE.sub(_anchor_section, body)
+    if not entries:
+        return document
+    items = "".join(
+        f'<li><a href="#{anchor}">{text}</a></li>' for anchor, text in entries
+    )
+    index = (
+        f'<nav class="report-index" aria-labelledby="{INDEX_TITLE_ID}">'
+        f'<h2 id="{INDEX_TITLE_ID}">{label}</h2>'
+        f"<ol>{items}</ol>"
+        "</nav>"
+    )
+    return f"{head}\n{index}{body}"

package/runtime/templates/reports/html/assets/base.css

@@ -16,6 +16,13 @@ main { display: grid; gap: 1rem; padding-bottom: 3rem; }
 section { padding: 1.4rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 16px; background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
 h2 { margin-top: 0; font-size: 1.45rem; }
 h3 { margin-bottom: .35rem; }
+/* The report opens with what it holds. It scrolls away with the rest rather
+   than sticking: on a phone a pinned index of a dozen sections is the page. */
+nav.report-index { padding: 1.2rem 1.4rem; border: 1px solid color-mix(in srgb, CanvasText 14%, transparent); border-radius: 16px; background: color-mix(in srgb, Canvas 94%, CanvasText 6%); }
+nav.report-index h2 { font-size: .82rem; text-transform: uppercase; letter-spacing: .08em; color: GrayText; margin-bottom: .6rem; }
+nav.report-index ol { margin: 0; padding-left: 1.4rem; columns: 2; column-gap: 2.5rem; }
+nav.report-index li { margin: .2em 0; break-inside: avoid; }
+nav.report-index a { color: inherit; }
 /* One card per row. Fitting three across left each body about sixteen
    characters wide — a third of what reads comfortably — and turned every card
    into a narrow vertical strip. These carry paragraphs, not labels. */
@@ -92,6 +99,6 @@ button:focus-visible { outline: 2px solid Highlight; outline-offset: 2px; }
 button[data-action="export-user-response"] { background: Highlight; border-color: Highlight; color: HighlightText; font-weight: 600; }
 button[data-action="export-user-response"]:hover { background: color-mix(in srgb, Highlight 82%, CanvasText); }
 /* A seven-column table needs 42em of floor, more than a phone can give. */
-@media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } }
+@media (max-width: 640px) { section { padding: 1rem; } .visualization { display: none; } th, td { min-width: 4.5em; } nav.report-index ol { columns: 1; } }
 @media print { .skip-link, script { display: none !important; } body { color: #000; background: #fff; } section { break-inside: avoid; border-color: #bbb; } .visualization-fallback { display: table; } }
 code { font-family: ui-monospace, SFMono-Regular, Menlo, monospace; font-size: .9em; padding: .1em .3em; border-radius: 4px; background: color-mix(in srgb, CanvasText 8%, Canvas); }

package/runtime/templates/reports/html/i18n/en.json

@@ -72,6 +72,7 @@
   },
   "base": {
     "skip-to-report-content": "Skip to report content",
+    "contents": "Contents",
     "task": "Task",
     "task-key": "Task key",
     "written": "Written",

package/runtime/templates/reports/html/i18n/ko.json

@@ -72,6 +72,7 @@
   },
   "base": {
     "skip-to-report-content": "리포트 본문으로 건너뛰기",
+    "contents": "목차",
     "task": "태스크",
     "task-key": "태스크 키",
     "written": "작성",

package/runtime/templates/reports/html/macros/forms.html

@@ -32,7 +32,7 @@
 
 {% macro clarification_responses(items) -%}
 {% if items %}
-<section class="clarification-responses" aria-label="{{ t('macros.forms.questions-waiting-on-you') }}">
+<section class="clarification-responses" data-report-section="clarification-responses" aria-label="{{ t('macros.forms.questions-waiting-on-you') }}">
   <h2>{{ t('macros.forms.count-questions-waiting-on-you') | replace('{count}', items | length) }}</h2>
   <p class="clarification-lede">{{ t('macros.forms.the-code-alone-could-not-settle-these-fill-i') }} <strong>{{ t('macros.forms.export-my-answers') }}</strong> {{ t('macros.forms.at-the-foot-of-the-page') }}</p>
   {% for row in items %}