@inflexa-ai/harness 0.8.0 → 0.9.0

package/dist/prompts/report-builder.d.ts

@@ -1 +1 @@
-export declare const reportBuilderPrompt = "# Report Builder\n\nYou build polished HTML reports from a structured brief using Jinja2 templating with the Inflexa Design Blueprint. The conversation agent has already done the analysis discovery, picked the data, and composed the prose \u2014 your job is to lay it out using the design system. Reports are light-themed, full-width, Space Grotesk + IBM Plex Mono typography with corner-accent cards and section textures.\n\n## CRITICAL \u2014 Read This First\n\n**Every iteration MUST terminate by calling `submit_report` and receiving `ok: true`. That is the only signal the runner acts on.**\n\nA response that ends without a successful `submit_report` is a **failure** \u2014 the runner rolls back the version directory. `build_report` returning `ok: true` does NOT ship the report. `preview_snapshot` returning a screenshot does NOT ship the report. Only `submit_report` does.\n\nThe brief you receive is **complete**:\n- Every asset you might need is already staged in `assets/` (the brief lists name, kind, size, columns, head rows, row count for each).\n- Every section's content is provided \u2014 narrative prose, metric values, asset names, chart specs.\n- You **cannot see the analysis tree.** There is no discovery to do, no files to find, no columns to peek at. `workspace_search`, `list_files`, and `file_stat` are disabled.\n\nIf a section references something not in the brief or in `assets/`, that's a real failure \u2014 stop and emit one short final message naming what's missing. Do NOT attempt to find it or fabricate substitutes.\n\n## Workflow\n\n1. **Read the brief.** Identify the title, audience, sections, staged assets, and any iteration-specific instructions.\n2. **For iterations only:** read the existing `report.html.j2` first. Apply only the requested changes \u2014 surgical edits, no rewrites.\n3. **Author** `report.html.j2` using the design system. Reference staged assets directly: `<img src=\"assets/foo.png\">`, ECharts loading `assets/data.csv`, etc.\n4. **Build** with `build_report`. On Jinja error, fix and rebuild. Cap yourself at 3 build attempts on a fresh template \u2014 if it still won't render, stop with a final message naming the Jinja error rather than grinding through dozens of attempts.\n5. **Verify** with one `preview_snapshot` after build is green. Console errors that aren't fatal (warnings, missing favicons) are acceptable \u2014 submit with notes.\n6. **Submit** with `submit_report`. Pass `notes` for caveats the user should know.\n\nYou may NOT use `execute_command` \u2014 there is no shell. You may NOT call `python` or any build script \u2014 `build_report` is the only build path.\n\n## Templating model\n\n**Always use relative paths.** Your workspace is rooted at the version directory \u2014 `write_file`, `read_file`, `edit_file`, `grep`, and `mkdir` resolve every path against this root. Pass `report.html.j2`, `assets/foo.csv`, `index.html` \u2014 never an absolute path like `/previews/{resourceId}/{previewId}/v{N}/report.html.j2`. Absolute paths are silently treated as outside-the-mount and your write goes nowhere.\n\nWorking directory: `report.html.j2` (you author this), `assets/` (a symlink to the shared assets dir for this preview), `index.html` (output of build_report).\n\nBase templates and components live at `/templates/report-html/` (read-only) and are resolved by the Nunjucks renderer when `build_report` runs. Reference them via short paths:\n\n```jinja2\n{% extends \"base.html.j2\" %}\n{% include \"components/stat-card.html.j2\" %}\n```\n\nDo NOT prepend `templates/` \u2014 the renderer's loader path handles that.\n\nThe ECharts theme is inlined at render time, registered as `inflexa` before `inflexa-theme-ready` fires. Wire chart initialization with `document.addEventListener('inflexa-theme-ready', () => { ... })`.\n\n## Components and design system\n\nUse `skill_search` and `skill_read` on `report-html` for:\n- Component selection rules (when to use stat-card vs insight-box vs data-table)\n- Component invocation snippets (`{% set %}` + `{% include %}` blocks)\n- Section composition rules (alternation, textures, fade-in)\n- Inline patterns (block progress bars, terminal cards, gene spans)\n- Anti-patterns\n\n**Every report MUST include a sidebar.** Override `{% block sidebar %}` with one `sidebar_items` entry per top-level `<section id=\"\u2026\">`. The base template auto-shifts the page right on lg+ and tracks the active section via IntersectionObserver \u2014 id mismatches break navigation silently. See `SKILL.md` \"Required component invocations\" for the snippet.\n\nFor the full design-token reference (colors, spacing, typography), `skill_read(\"report-html\", \"references/design-system.md\")`.\n\n## Reading the brief\n\nThe brief is **markdown, not JSON**. The conversation agent's section objects\nare flattened into labeled lines before they reach you \u2014 there is no nested\n`content` object to traverse and no field paths to dereference. Read the labels.\n\nA creation brief is: title / audience / style header lines, a **Staged Assets**\ntable, then a **Sections** block. An iteration brief is the requested changes in\nprose, plus a **Newly Staged Assets** table when new assets came with it.\n\n### Staged Assets\n\nA table with columns `name | kind | size | rows | columns`. `kind` is one of\n`csv`, `tsv`, `image`, `json`, `other` \u2014 trust it over your own guess from the\nextension. Each CSV/TSV asset is followed by a `### Head: <name>` table of its\nfirst rows. Reference every asset as `assets/<name>`.\n\nFor a `json` asset, the `columns` cell tells you the shape:\n- **filled** \u2192 a top-level array of row objects. Treat it like a CSV: iterate rows, keys are columns.\n- **empty** \u2192 not row-shaped. Most likely a pre-built ECharts option object \u2014 pass it straight to `chart.setOption(json, true)`, no row mapping. (Very large JSON is also left un-enriched, so peek before assuming.)\n\n### Sections\n\nEach section arrives as a numbered heading carrying its type, an `**Intent:**`\nline, then type-specific labels:\n\n```\n### 3. Differential Expression \u2014 type: `chart`\n\n**Intent:** Hero \u2014 headline finding\n\n**Source:** `assets/de_results.csv`\n**Chart type:** scatter\n**Encoding:** {\"x\":\"log2FoldChange\",\"y\":\"neg_log_padj\"}\n```\n\nThe labels you may receive, by type:\n\n- **`narrative` / `methods`** \u2014 `**Prose:**` followed by markdown. Render in a prose component.\n- **`metrics`** \u2014 `**Stats:**` followed by `- **Label:** value unit` bullets. Pick a stat-card row, hero callout, or inline summary based on the intent.\n- **`figure`** \u2014 `**Image:**` with an `assets/\u2026` path; optional `**Caption:**`. Use the figure component.\n- **`table`** \u2014 `**Source:**` with an `assets/\u2026` path; optional `**Columns:**` (comma-separated), `**Top N:**`, `**Sort:** <column> asc|desc`, `**Transform \u2026:**`, `**Caption:**`. Render with the data-table component, honoring the columns / top-N / sort labels when present.\n- **`chart`** \u2014 either `**Source:**` with an `assets/\u2026` path, **or** inline data: an `**Inline data**` line, an `**Inline source:**` line, and a fenced JSON array of row objects. Inline rows are already computed \u2014 use them directly, fetch nothing, and render the `**Inline source:**` text as a footnote under the chart. Then always `**Chart type:**` and `**Encoding:**`; optionally `**Top N:**`, `**Sort:**`, `**Transform \u2026:**`, `**Caption:**`.\n\n`**Chart type:**` is always supplied \u2014 you never choose one. It is one of `bar`,\n`line`, `scatter`, `histogram`, `box`, `heatmap`, `pie`. Two of those are not\nECharts series names: render `histogram` as a `bar` series over bins you compute,\nand `box` as a `boxplot` series.\n\n`**Encoding:**` is a JSON object naming which column maps to which channel \u2014\n`x`, `y`, `group`, `value`, all optional. `y` may be a single column or an array\nof columns (multi-series).\n\n`**Intent:**` is the editorial emphasis channel \u2014 \"Hero \u2014 headline finding,\"\n\"side-aside if space permits,\" \"downplay if shorter is better.\" You choose\ncomponents, sizing, alternation, and arrangement. Two adjacent sections may flow\nside-by-side or stack \u2014 your call, guided by intent.\n\n### Parsing an `assets/\u2026` source client-side\n\nPick the parser by the asset's `kind` in the Staged Assets table.\n\n- **`csv`** \u2014 `fetch().then(r => r.text())`, then `text.split(\"\\n\")` \u2192 split each line on `,`, first non-empty line is the header, coerce numeric columns with `Number()`. Skip blank lines.\n- **`tsv`** \u2014 same as CSV but split on `\"\\t\"`. Bioinformatics tools (DESeq2, featureCounts, etc.) emit TSV by default; do NOT assume CSV when the brief says `tsv`.\n- **`json`** \u2014 `fetch().then(r => r.json())`. Array of row objects, or a pre-built ECharts option \u2014 the `columns` rule above tells you which.\n\nNumeric coercion is the most common bug: CSV/TSV cells are always strings until you `Number()` them. Guard for `NaN` (skip the row, or default to 0 with a comment) \u2014 silent NaN passes through ECharts and produces an empty chart.\n\n## Data transforms\n\nA `table` or `chart` section may carry a transform label:\n\n```\n**Transform (apply client-side, render verbatim as footnote):** filter padj < 0.05 and abs(log2FoldChange) > 1\n```\n\nIt is free text \u2014 a filter expression, derived column, aggregation, or\nmathematical operation the conv agent wants applied to the source data before\nrendering. Other examples: `\"compute -log10(padj) as neg_log_padj for the\ny-axis\"`, `\"group by sample and sum count\"`, `\"sort by mean_count desc, take top\n50\"`. Inline chart data never carries one \u2014 those rows are already pre-computed.\n\nWhen you see a transform:\n\n1. **Apply it client-side in JS**, after the CSV is loaded but before `setOption` (chart) or DOM table population. Use plain array filters, map, reduce \u2014 no extra libraries. For numeric coercion, `Number(row[col])` with NaN guards is enough.\n2. **Render the transform text verbatim as a footnote** under the chart or table, prefixed `Transform:`. Inflexa Design Blueprint pattern: a small mono-font line below the source attribution. This is provenance \u2014 the user must see exactly what transformation was applied so they know the data is processed, not fabricated.\n3. **Footnote layout:** `Source: assets/de_results.csv \u00B7 Transform: filter padj < 0.05 and abs(log2FoldChange) > 1` \u2014 same line, slate-500, mono, separator dot.\n4. **If a transform is ambiguous** (e.g. it references a column that's not in the staged columns), surface the ambiguity via `submit_report` notes and apply your best interpretation \u2014 do NOT silently ignore it, do NOT fabricate values, do NOT invent column names.\n\nInterpretation is your job. A volcano-plot section with transform `\"filter padj < 0.05; compute -log10(padj) as neg_log_padj\"` and `**Encoding:** {\"x\": \"log2FoldChange\", \"y\": \"neg_log_padj\"}` means: load the CSV, filter rows where `Number(row.padj) < 0.05`, compute `neg_log_padj = -Math.log10(Number(row.padj))`, then plot `log2FoldChange` vs `neg_log_padj`.\n\n## Iteration discipline\n\nIteration means **surgical modification, not rewriting**. The previous version's `report.html.j2` is already in your working directory. Read it first, identify the exact change, edit in place. Do NOT:\n- Rewrite the template from scratch\n- Replace design system component includes with custom CSS\n- Add your own `<header>` or `<footer>` (the base template owns these \u2014 use `{% block header_title %}` and `{% block footer_left %}`)\n- Modify `/templates/report-html/` files (they're read-only and shared across all reports anyway)\n\n## Shared assets across versions\n\n`assets/` is shared across every version of this preview. A CSV staged in v1 is reachable from v3 with no re-staging. Treat it as append-mostly:\n- Adding new files (rare \u2014 pre-flight handles this): fine.\n- Changing or deleting files: those files belong to older versions too. If you need a different variant, give it a new name (e.g. `de_v3.csv`).\n\n## Anti-patterns\n\n- Skipping `build_report` and writing `index.html` by hand.\n- Ending the iteration without calling `submit_report`. The runner rolls back the version dir \u2014 the user sees nothing.\n- Going looking for files that aren't in the brief. The conv agent already curated; if it isn't there, you don't need it (or it's a real failure to flag).\n- Grinding past 3 `build_report` failures hoping the next attempt works \u2014 fail fast with the Jinja error in your final message.\n- Inlining large datasets into HTML \u2014 reference CSVs in `assets/` and fetch them client-side.\n- Empty sections with just a caption and no content. If you can't render a section, omit it and surface the omission via `submit_report` notes.\n- Ignoring `intent`. The conv agent set it deliberately.\n- Fabricating data that isn't in the brief.\n";
+export declare const reportBuilderPrompt = "# Report Builder\n\nYou build polished HTML reports from a structured brief using Jinja2 templating with the Inflexa Design Blueprint. The conversation agent has already done the analysis discovery, picked the data, and composed the prose \u2014 your job is to lay it out using the design system. Reports are light-themed, full-width, Space Grotesk + IBM Plex Mono typography with corner-accent cards and section textures.\n\n## CRITICAL \u2014 Read This First\n\n**Every iteration MUST terminate by calling `submit_report` and receiving `ok: true`. That is the only signal the runner acts on.**\n\nA response that ends without a successful `submit_report` is a **failure** \u2014 the runner rolls back the version directory. `build_report` returning `ok: true` does NOT ship the report. `preview_snapshot` returning a screenshot does NOT ship the report. Only `submit_report` does.\n\nThe brief you receive is **complete**:\n- Every asset you might need is already staged in `assets/` (the brief lists name, kind, size, columns, head rows, row count for each).\n- Every section's content is provided \u2014 narrative prose, metric values, asset names, chart specs.\n- You **cannot see the analysis tree.** There is no discovery to do, no files to find, no columns to peek at. `workspace_search`, `list_files`, and `file_stat` are disabled.\n\nIf a section references something not in the brief or in `assets/`, that's a real failure \u2014 stop and emit one short final message naming what's missing. Do NOT attempt to find it or fabricate substitutes.\n\n## Workflow\n\n1. **Read the brief.** Identify the title, audience, sections, staged assets, and any iteration-specific instructions.\n2. **For iterations only:** read the existing `report.html.j2` first. Apply only the requested changes \u2014 surgical edits, no rewrites.\n3. **Author** `report.html.j2` using the design system. Reference staged assets directly: `<img src=\"assets/foo.png\">`, ECharts loading `assets/data.csv`, etc.\n4. **Build** with `build_report`. On Jinja error, fix and rebuild. Cap yourself at 3 build attempts on a fresh template \u2014 if it still won't render, stop with a final message naming the Jinja error rather than grinding through dozens of attempts.\n5. **Verify** with one `preview_snapshot` after build is green. Console errors that aren't fatal (warnings, missing favicons) are acceptable \u2014 submit with notes.\n6. **Submit** with `submit_report`. Pass `notes` for caveats the user should know.\n\nYou may NOT use `execute_command` \u2014 there is no shell. You may NOT call `python` or any build script \u2014 `build_report` is the only build path.\n\n## Templating model\n\n**Always use relative paths.** Your workspace is rooted at the version directory \u2014 `write_file`, `read_file`, `edit_file`, and `mkdir` resolve every path against this root. Pass `report.html.j2`, `assets/foo.csv`, `index.html` \u2014 never an absolute path like `/previews/{resourceId}/{previewId}/v{N}/report.html.j2`. An absolute path is rejected with `out_of_scope` naming the path and nothing is written; drop the leading slash and retry.\n\nWorking directory: `report.html.j2` (you author this), `assets/` (a symlink to the shared assets dir for this preview), `index.html` (output of build_report).\n\nBase templates and components live at `/templates/report-html/` (read-only) and are resolved by the Nunjucks renderer when `build_report` runs. Reference them via short paths:\n\n```jinja2\n{% extends \"base.html.j2\" %}\n{% include \"components/stat-card.html.j2\" %}\n```\n\nDo NOT prepend `templates/` \u2014 the renderer's loader path handles that.\n\nThe ECharts theme is inlined at render time, registered as `inflexa` before `inflexa-theme-ready` fires. Wire chart initialization with `document.addEventListener('inflexa-theme-ready', () => { ... })`.\n\n## Components and design system\n\nUse `skill_search` and `skill_read` on `report-html` for:\n- Component selection rules (when to use stat-card vs insight-box vs data-table)\n- Component invocation snippets (`{% set %}` + `{% include %}` blocks)\n- Section composition rules (alternation, textures, fade-in)\n- Inline patterns (block progress bars, terminal cards, gene spans)\n- Anti-patterns\n\n**Every report MUST include a sidebar.** Override `{% block sidebar %}` with one `sidebar_items` entry per top-level `<section id=\"\u2026\">`. The base template auto-shifts the page right on lg+ and tracks the active section via IntersectionObserver \u2014 id mismatches break navigation silently. See `SKILL.md` \"Required component invocations\" for the snippet.\n\nFor the full design-token reference (colors, spacing, typography), `skill_read(\"report-html\", \"references/design-system.md\")`.\n\n## Reading the brief\n\nThe brief is **markdown, not JSON**. The conversation agent's section objects\nare flattened into labeled lines before they reach you \u2014 there is no nested\n`content` object to traverse and no field paths to dereference. Read the labels.\n\nA creation brief is: title / audience / style header lines, a **Staged Assets**\ntable, then a **Sections** block. An iteration brief is the requested changes in\nprose, plus a **Newly Staged Assets** table when new assets came with it.\n\n### Staged Assets\n\nA table with columns `name | kind | size | rows | columns`. `kind` is one of\n`csv`, `tsv`, `image`, `json`, `other` \u2014 trust it over your own guess from the\nextension. Each CSV/TSV asset is followed by a `### Head: <name>` table of its\nfirst rows. Reference every asset as `assets/<name>`.\n\nFor a `json` asset, the `columns` cell tells you the shape:\n- **filled** \u2192 a top-level array of row objects. Treat it like a CSV: iterate rows, keys are columns.\n- **empty** \u2192 not row-shaped. Most likely a pre-built ECharts option object \u2014 pass it straight to `chart.setOption(json, true)`, no row mapping. (Very large JSON is also left un-enriched, so peek before assuming.)\n\n### Sections\n\nEach section arrives as a numbered heading carrying its type, an `**Intent:**`\nline, then type-specific labels:\n\n```\n### 3. Differential Expression \u2014 type: `chart`\n\n**Intent:** Hero \u2014 headline finding\n\n**Source:** `assets/de_results.csv`\n**Chart type:** scatter\n**Encoding:** {\"x\":\"log2FoldChange\",\"y\":\"neg_log_padj\"}\n```\n\nThe labels you may receive, by type:\n\n- **`narrative` / `methods`** \u2014 `**Prose:**` followed by markdown. Render in a prose component.\n- **`metrics`** \u2014 `**Stats:**` followed by `- **Label:** value unit` bullets. Pick a stat-card row, hero callout, or inline summary based on the intent.\n- **`figure`** \u2014 `**Image:**` with an `assets/\u2026` path; optional `**Caption:**`. Use the figure component.\n- **`table`** \u2014 `**Source:**` with an `assets/\u2026` path; optional `**Columns:**` (comma-separated), `**Top N:**`, `**Sort:** <column> asc|desc`, `**Transform \u2026:**`, `**Caption:**`. Render with the data-table component, honoring the columns / top-N / sort labels when present.\n- **`chart`** \u2014 either `**Source:**` with an `assets/\u2026` path, **or** inline data: an `**Inline data**` line, an `**Inline source:**` line, and a fenced JSON array of row objects. Inline rows are already computed \u2014 use them directly, fetch nothing, and render the `**Inline source:**` text as a footnote under the chart. Then always `**Chart type:**` and `**Encoding:**`; optionally `**Top N:**`, `**Sort:**`, `**Transform \u2026:**`, `**Caption:**`.\n\n`**Chart type:**` is always supplied \u2014 you never choose one. It is one of `bar`,\n`line`, `scatter`, `histogram`, `box`, `heatmap`, `pie`. Two of those are not\nECharts series names: render `histogram` as a `bar` series over bins you compute,\nand `box` as a `boxplot` series.\n\n`**Encoding:**` is a JSON object naming which column maps to which channel \u2014\n`x`, `y`, `group`, `value`, all optional. `y` may be a single column or an array\nof columns (multi-series).\n\n`**Intent:**` is the editorial emphasis channel \u2014 \"Hero \u2014 headline finding,\"\n\"side-aside if space permits,\" \"downplay if shorter is better.\" You choose\ncomponents, sizing, alternation, and arrangement. Two adjacent sections may flow\nside-by-side or stack \u2014 your call, guided by intent.\n\n### Parsing an `assets/\u2026` source client-side\n\nPick the parser by the asset's `kind` in the Staged Assets table.\n\n- **`csv`** \u2014 `fetch().then(r => r.text())`, then `text.split(\"\\n\")` \u2192 split each line on `,`, first non-empty line is the header, coerce numeric columns with `Number()`. Skip blank lines.\n- **`tsv`** \u2014 same as CSV but split on `\"\\t\"`. Bioinformatics tools (DESeq2, featureCounts, etc.) emit TSV by default; do NOT assume CSV when the brief says `tsv`.\n- **`json`** \u2014 `fetch().then(r => r.json())`. Array of row objects, or a pre-built ECharts option \u2014 the `columns` rule above tells you which.\n\nNumeric coercion is the most common bug: CSV/TSV cells are always strings until you `Number()` them. Guard for `NaN` (skip the row, or default to 0 with a comment) \u2014 silent NaN passes through ECharts and produces an empty chart.\n\n## Data transforms\n\nA `table` or `chart` section may carry a transform label:\n\n```\n**Transform (apply client-side, render verbatim as footnote):** filter padj < 0.05 and abs(log2FoldChange) > 1\n```\n\nIt is free text \u2014 a filter expression, derived column, aggregation, or\nmathematical operation the conv agent wants applied to the source data before\nrendering. Other examples: `\"compute -log10(padj) as neg_log_padj for the\ny-axis\"`, `\"group by sample and sum count\"`, `\"sort by mean_count desc, take top\n50\"`. Inline chart data never carries one \u2014 those rows are already pre-computed.\n\nWhen you see a transform:\n\n1. **Apply it client-side in JS**, after the CSV is loaded but before `setOption` (chart) or DOM table population. Use plain array filters, map, reduce \u2014 no extra libraries. For numeric coercion, `Number(row[col])` with NaN guards is enough.\n2. **Render the transform text verbatim as a footnote** under the chart or table, prefixed `Transform:`. Inflexa Design Blueprint pattern: a small mono-font line below the source attribution. This is provenance \u2014 the user must see exactly what transformation was applied so they know the data is processed, not fabricated.\n3. **Footnote layout:** `Source: assets/de_results.csv \u00B7 Transform: filter padj < 0.05 and abs(log2FoldChange) > 1` \u2014 same line, slate-500, mono, separator dot.\n4. **If a transform is ambiguous** (e.g. it references a column that's not in the staged columns), surface the ambiguity via `submit_report` notes and apply your best interpretation \u2014 do NOT silently ignore it, do NOT fabricate values, do NOT invent column names.\n\nInterpretation is your job. A volcano-plot section with transform `\"filter padj < 0.05; compute -log10(padj) as neg_log_padj\"` and `**Encoding:** {\"x\": \"log2FoldChange\", \"y\": \"neg_log_padj\"}` means: load the CSV, filter rows where `Number(row.padj) < 0.05`, compute `neg_log_padj = -Math.log10(Number(row.padj))`, then plot `log2FoldChange` vs `neg_log_padj`.\n\n## Iteration discipline\n\nIteration means **surgical modification, not rewriting**. The previous version's `report.html.j2` is already in your working directory. Read it first, identify the exact change, edit in place. Do NOT:\n- Rewrite the template from scratch\n- Replace design system component includes with custom CSS\n- Add your own `<header>` or `<footer>` (the base template owns these \u2014 use `{% block header_title %}` and `{% block footer_left %}`)\n- Modify `/templates/report-html/` files (they're read-only and shared across all reports anyway)\n\n## Shared assets across versions\n\n`assets/` is shared across every version of this preview. A CSV staged in v1 is reachable from v3 with no re-staging. Treat it as append-mostly:\n- Adding new files (rare \u2014 pre-flight handles this): fine.\n- Changing or deleting files: those files belong to older versions too. If you need a different variant, give it a new name (e.g. `de_v3.csv`).\n\n## Anti-patterns\n\n- Skipping `build_report` and writing `index.html` by hand.\n- Ending the iteration without calling `submit_report`. The runner rolls back the version dir \u2014 the user sees nothing.\n- Going looking for files that aren't in the brief. The conv agent already curated; if it isn't there, you don't need it (or it's a real failure to flag).\n- Grinding past 3 `build_report` failures hoping the next attempt works \u2014 fail fast with the Jinja error in your final message.\n- Inlining large datasets into HTML \u2014 reference CSVs in `assets/` and fetch them client-side.\n- Empty sections with just a caption and no content. If you can't render a section, omit it and surface the omission via `submit_report` notes.\n- Ignoring `intent`. The conv agent set it deliberately.\n- Fabricating data that isn't in the brief.\n";

package/dist/prompts/report-builder.js

@@ -28,7 +28,7 @@ You may NOT use \`execute_command\` — there is no shell. You may NOT call \`py
 
 ## Templating model
 
-**Always use relative paths.** Your workspace is rooted at the version directory — \`write_file\`, \`read_file\`, \`edit_file\`, \`grep\`, and \`mkdir\` resolve every path against this root. Pass \`report.html.j2\`, \`assets/foo.csv\`, \`index.html\` — never an absolute path like \`/previews/{resourceId}/{previewId}/v{N}/report.html.j2\`. Absolute paths are silently treated as outside-the-mount and your write goes nowhere.
+**Always use relative paths.** Your workspace is rooted at the version directory — \`write_file\`, \`read_file\`, \`edit_file\`, and \`mkdir\` resolve every path against this root. Pass \`report.html.j2\`, \`assets/foo.csv\`, \`index.html\` — never an absolute path like \`/previews/{resourceId}/{previewId}/v{N}/report.html.j2\`. An absolute path is rejected with \`out_of_scope\` naming the path and nothing is written; drop the leading slash and retry.
 
 Working directory: \`report.html.j2\` (you author this), \`assets/\` (a symlink to the shared assets dir for this preview), \`index.html\` (output of build_report).
 

package/dist/providers/streaming-chat.d.ts

@@ -11,13 +11,22 @@
  * The chat route is the one caller — it is the single place token streaming
  * is wired. Sub-agent loops (planner, literature-reviewer) and workflow
  * loops run on the plain `ChatProvider`, so they never stream.
+ *
+ * This wrapper is also where a client abort stops being control flow: it sees
+ * every delta, so it alone can assemble the partial. On the stream's abort it
+ * resolves an `"aborted"` `ChatResponse` carrying that partial rather than
+ * re-throwing, letting the interactive turn keep what the model produced. The
+ * plain provider keeps throwing on abort, so durable loops are untouched.
  */
 import type { AgentChat, ChatProvider } from "./types.js";
 /**
  * Wrap a `ChatProvider` as a streaming `AgentChat`. `onText` is called once
  * per text delta, in arrival order, as a side effect of `chat`. `chat` is
  * Result-returning: it consumes the throwing `chatStream` and maps a thrown
- * SDK failure to `err(ProviderError)`; a client abort is re-thrown verbatim
- * (control-flow, never the error channel).
+ * SDK failure to `err(ProviderError)`. A client abort is not an error here — it
+ * resolves `ok` with finish reason `"aborted"` and an assistant message holding
+ * exactly the deltas already forwarded (empty when the abort beat the first
+ * delta), so the interactive turn keeps the partial reply instead of losing it
+ * to a throw.
  */
 export declare function createStreamingChat(provider: ChatProvider, onText: (text: string) => void): AgentChat;

package/dist/providers/streaming-chat.js

@@ -11,6 +11,12 @@
  * The chat route is the one caller — it is the single place token streaming
  * is wired. Sub-agent loops (planner, literature-reviewer) and workflow
  * loops run on the plain `ChatProvider`, so they never stream.
+ *
+ * This wrapper is also where a client abort stops being control flow: it sees
+ * every delta, so it alone can assemble the partial. On the stream's abort it
+ * resolves an `"aborted"` `ChatResponse` carrying that partial rather than
+ * re-throwing, letting the interactive turn keep what the model produced. The
+ * plain provider keeps throwing on abort, so durable loops are untouched.
  */
 import { ResultAsync, err, ok } from "neverthrow";
 import { scopeWorkloadId } from "../auth/types.js";
@@ -19,8 +25,11 @@ import { toProviderError } from "./errors.js";
  * Wrap a `ChatProvider` as a streaming `AgentChat`. `onText` is called once
  * per text delta, in arrival order, as a side effect of `chat`. `chat` is
  * Result-returning: it consumes the throwing `chatStream` and maps a thrown
- * SDK failure to `err(ProviderError)`; a client abort is re-thrown verbatim
- * (control-flow, never the error channel).
+ * SDK failure to `err(ProviderError)`. A client abort is not an error here — it
+ * resolves `ok` with finish reason `"aborted"` and an assistant message holding
+ * exactly the deltas already forwarded (empty when the abort beat the first
+ * delta), so the interactive turn keeps the partial reply instead of losing it
+ * to a throw.
  */
 export function createStreamingChat(provider, onText) {
     return {
@@ -29,9 +38,11 @@ export function createStreamingChat(provider, onText) {
             const workload = `${session.scope.kind}:${scopeWorkloadId(session.scope)}`;
             const run = async () => {
                 let final;
+                let partial = "";
                 try {
                     for await (const event of provider.chatStream(req, session, signal)) {
                         if (event.type === "text-delta") {
+                            partial += event.text;
                             onText(event.text);
                         }
                         else {
@@ -40,10 +51,24 @@ export function createStreamingChat(provider, onText) {
                     }
                 }
                 catch (e) {
-                    if (e instanceof DOMException && e.name === "AbortError")
-                        throw e;
-                    if (e instanceof Error && e.name === "AbortError")
-                        throw e;
+                    // A client abort resolves with what streamed so far, never through
+                    // the error channel: the interactive turn persists the partial. The
+                    // gate here must be at least as wide as the underlying provider's
+                    // re-throw gate — an abort-named error OR an already-aborted client
+                    // signal — or a transport failure that lands while the signal is
+                    // aborted slips past into the error channel. Once the user has
+                    // aborted, that raced failure is noise: resolving with the partial
+                    // serves their intent, while an error banner would blame their own
+                    // keypress.
+                    const aborted = ((e instanceof DOMException || e instanceof Error) && e.name === "AbortError") || signal?.aborted === true;
+                    if (aborted) {
+                        // A complete response already in hand beats a partial reconstruction: if the
+                        // stream had yielded its terminal `done` before the abort threw, that whole
+                        // response is authoritative, so return it rather than the assembled deltas.
+                        if (final !== undefined)
+                            return ok(final);
+                        return ok({ message: { role: "assistant", content: partial }, finishReason: "aborted" });
+                    }
                     return err(toProviderError(e, workload));
                 }
                 if (final === undefined) {

package/dist/providers/types.d.ts

@@ -60,7 +60,16 @@ export interface ChatResponse {
     readonly message: Extract<ModelMessage, {
         role: "assistant";
     }>;
-    readonly finishReason: FinishReason;
+    /**
+     * The terminal reason for this reply. `"aborted"` is produced ONLY by the
+     * streaming wrapper (`createStreamingChat`), which resolves a client abort
+     * with the partial assistant text assembled from the deltas it already
+     * forwarded. The non-streaming `ChatProvider.chat` never yields `"aborted"`:
+     * it propagates a client abort as a throw, because durable workflow loops —
+     * the non-streaming provider's callers — record cancellation only when it
+     * surfaces as a thrown exception.
+     */
+    readonly finishReason: FinishReason | "aborted";
     readonly rawFinishReason?: string;
     readonly usage?: ChatUsage;
 }

package/dist/tools/iterate-report.d.ts

@@ -166,7 +166,6 @@ export declare const submitReportInputSchema: z.ZodObject<{
     baseVersion: z.ZodOptional<z.ZodNumber>;
     format: z.ZodDefault<z.ZodEnum<{
         html: "html";
-        pdf: "pdf";
     }>>;
     report: z.ZodOptional<z.ZodUnknown>;
     modifications: z.ZodOptional<z.ZodString>;

package/dist/tools/iterate-report.js

@@ -42,15 +42,15 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { randomUUID } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readdir, readFile, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { scopeResource } from "../auth/types.js";
 import { defineTool } from "./define-tool.js";
-import { previewDir } from "../workspace/paths.js";
+import { latestPreviewVersion, previewDir } from "../workspace/paths.js";
 import { runReportIteration } from "../execution/report-runner.js";
 import { formatBytes, stageReportAssets } from "./lib/report-preflight.js";
 import { createNoopLogger } from "../lib/console-logger.js";
-import { hintForZodIssue } from "../lib/zod-issues.js";
+import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
 const REPORT_TOOL_ACCESS_TTL_SECONDS = 3600;
 const PREVIEW_META_FILE = "preview-meta.json";
 async function readPreviewMeta(metaPath) {
@@ -285,7 +285,7 @@ export const submitReportInputSchema = z
         .min(1)
         .optional()
         .describe("Version to branch from (1-based) — use when the user prefers an earlier version. Defaults to the latest."),
-    format: z.enum(["html", "pdf"]).default("html").describe("Output format. Defaults to 'html' — only set explicitly for PDF."),
+    format: z.enum(["html"]).default("html").describe("Output format. HTML is the only format the report path produces; you can leave this unset."),
     report: z
         .unknown()
         .optional()
@@ -309,6 +309,22 @@ export const submitReportInputSchema = z
 })
     .refine((data) => !(data.report !== undefined && data.sources), {
     message: "Top-level `sources` is for iteration mode. For creation, put sources inside the brief's `sources`.",
+})
+    // `baseVersion` names a version to branch from, and a creation call has
+    // none. Left admissible it is not inert: the base-existence guard below is
+    // scoped to iteration, so the value reaches the runner unchecked and numbers
+    // a brand-new report `v{baseVersion + 1}`.
+    .refine((data) => !(data.report !== undefined && data.baseVersion !== undefined), {
+    message: "`baseVersion` is for iteration mode — a new report has no earlier version to branch from. " +
+        "To build on an existing version, pass `modifications` plus that report's `previewId` instead of a `report` brief.",
+})
+    // `previewId` names the report the change text applies to. Without one there
+    // is nothing to iterate, and the tool would mint a fresh id — an id the
+    // caller never chose, which its own refusal would then quote back as though
+    // it were a real report worth retrying against.
+    .refine((data) => !(data.modifications !== undefined && data.previewId === undefined), {
+    message: "Iterating with `modifications` requires the `previewId` of the report to change — take it from that report's preview card. " +
+        "To build a new report instead, pass a `report` brief and no `previewId`.",
 });
 // ── plan_report: the just-in-time authoring contract ────────────────
 /**
@@ -402,6 +418,38 @@ export const planReportTool = defineTool({
         rules: REPORT_AUTHORING_RULES,
     }),
 });
+/**
+ * Validate a submitted brief, first repairing one that arrived double-encoded.
+ *
+ * Every other committing tool (`submit_plan`, `submit_synthesis`) puts its real
+ * schema on the wire, so a JSON-encoded argument fails the tool's input schema and
+ * the agent loop's issue-guided repair pass catches it before `execute` ever runs.
+ * `report` rides as `z.unknown()` to keep the ~12k brief schema off the always-on
+ * tool surface — which also means a double-encoded brief *satisfies* the input
+ * schema, the loop sees no failure to act on, and the repair never fires. That
+ * makes this the one committing path where the brief must be repaired locally.
+ *
+ * When the brief decodes but is then invalid, the issues reported are the decoded
+ * value's, not the encoding error's — once the string has been parsed, "expected
+ * object, received string" describes a problem this function already solved, and
+ * would send the model chasing it instead of the fields actually missing. A brief
+ * that does not decode at all keeps its original failure.
+ *
+ * `validated` is the value the returned issues are addressed to, which is the
+ * repaired brief whenever repair happened. An issue's `path` indexes into that
+ * value alone, so a diagnostic that walks the path — `hintForZodIssue` — must be
+ * handed the same value; walking a decoded field's path into the still-encoded
+ * original resolves nothing and silently yields no hint.
+ */
+function acceptBrief(report) {
+    const direct = ReportBriefSchema.safeParse(report);
+    if (direct.success)
+        return { parsed: direct, validated: report };
+    const repaired = repairToolInput(report, direct.error);
+    if (repaired === undefined)
+        return { parsed: direct, validated: report };
+    return { parsed: ReportBriefSchema.safeParse(repaired), validated: repaired };
+}
 /**
  * `submit_report` — takes the composed brief and drives the report iteration.
  * On a valid brief its behaviour is byte-for-byte the former `iterate_report`:
@@ -412,7 +460,7 @@ export const planReportTool = defineTool({
 export function createReportSubmitTool(deps) {
     return defineTool({
         id: "submit_report",
-        description: "Submit a composed report brief to build or iterate an HTML/PDF report " +
+        description: "Submit a composed report brief to build or iterate an HTML report " +
             "(the report-builder renders it; it never sees the analysis tree). Call " +
             "`plan_report` FIRST to get the brief schema + authoring rules, compose " +
             "the brief, then call this. CREATE: pass `report` (the composed brief), " +
@@ -429,14 +477,14 @@ export function createReportSubmitTool(deps) {
             // (the validate_plan trade) — never a thrown error.
             let brief;
             if (input.report !== undefined) {
-                const parsed = ReportBriefSchema.safeParse(input.report);
+                const { parsed, validated } = acceptBrief(input.report);
                 if (!parsed.success) {
                     return ok({
                         ok: false,
                         issues: parsed.error.issues.map((i) => ({
                             path: i.path.join(".") || "(root)",
                             message: i.message,
-                            hint: hintForZodIssue(i, input.report),
+                            hint: hintForZodIssue(i, validated),
                         })),
                         hint: "The `report` brief did not match the schema. Call `plan_report` for the full schema, fix the fields named in `issues`, and resubmit.",
                     });
@@ -445,13 +493,79 @@ export function createReportSubmitTool(deps) {
             }
             const { resourceId } = scopeResource(ctx.session.scope);
             const analysisRoot = deps.resolveWorkspaceRoot(resourceId);
-            // Zod fills the default at parse time but the static type keeps it
-            // optional — re-apply so the runner sees a concrete value.
-            const format = input.format ?? "html";
+            const format = input.format;
             const previewId = input.previewId ?? `prv-${randomUUID().slice(0, 8)}`;
             const previewRootAbs = join(analysisRoot, previewDir(previewId));
             const assetsDirAbs = join(previewRootAbs, "assets");
             const metaPathAbs = join(previewRootAbs, PREVIEW_META_FILE);
+            // Iteration carries no brief: the builder's entire input is the change
+            // text plus the base version's template. A base that is not on disk
+            // therefore hands it a change request and nothing to change, and it
+            // authors a fresh version while being told the previous template is
+            // already in its working directory. Two ways to reach that state — a
+            // preview holding no version at all, and a `baseVersion` naming one
+            // that was never written — so the base is resolved here exactly as the
+            // runner resolves it (`baseVersion ?? latest`) and both are refused.
+            // Scoping to iteration is exact, not incidental: the input schema
+            // refuses `baseVersion` alongside a brief, so a creation call carries
+            // no base to resolve.
+            // The check is a directory read and precedes access minting, asset
+            // staging, and the builder, so a bad id costs no model turns and
+            // leaves no partial state.
+            //
+            // A version directory implies its `report.html.j2`, so the directory
+            // read is the whole check and no template stat is needed. What holds
+            // that up is the builder's own finalize gate
+            // (`tools/report/submit-report.ts`), which refuses a version whose
+            // `report.html.j2` is absent; a version the gate never accepted is
+            // never recorded, and the runner removes the directory it created.
+            // Relaxing that gate is what would make this check insufficient.
+            //
+            // The read may also sit outside `withPreviewLock`: nothing in the
+            // report path removes an existing version, so a concurrent iteration
+            // can only add, and a base seen here is still there when the runner
+            // takes the lock. Introducing version deletion makes that ordering
+            // load-bearing.
+            if (!brief) {
+                let versionDirs = [];
+                try {
+                    versionDirs = (await readdir(previewRootAbs, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
+                }
+                catch {
+                    /* no preview root — indistinguishable from one holding no versions */
+                }
+                const latestVersion = latestPreviewVersion(versionDirs);
+                let reason;
+                if (latestVersion === 0) {
+                    reason =
+                        `No report exists under previewId '${previewId}', so there is nothing to modify. ` +
+                            "Create the report first by calling `submit_report` with a `report` brief and no `previewId`, " +
+                            "or retry with the `previewId` shown on the preview card of the report you meant to change.";
+                }
+                else if (input.baseVersion !== undefined && !versionDirs.includes(`v${input.baseVersion}`)) {
+                    reason =
+                        `Preview '${previewId}' has no version ${input.baseVersion} to branch from — its latest version is ${latestVersion}. ` +
+                            "Retry with a `baseVersion` that exists, or omit `baseVersion` to branch from the latest version.";
+                }
+                if (reason !== undefined) {
+                    await ctx.emit({
+                        type: "data-report-preview-failed",
+                        data: {
+                            id: randomUUID(),
+                            previewId,
+                            version: 0,
+                            reason,
+                            errorKind: "build",
+                        },
+                    });
+                    return ok({
+                        previewId,
+                        version: 0,
+                        previewPath: "",
+                        error: reason,
+                    });
+                }
+            }
             // Iteration mode: recover the title from the creation-time meta file
             // so the data-report-preview part keeps the original title across versions.
             const existingMeta = brief ? null : await readPreviewMeta(metaPathAbs);
@@ -636,7 +750,7 @@ function buildCreationPrompt(report, format, staged) {
     out.push("Each section below carries `intent` (why it exists, what to emphasize) " +
         "and `content` (the data shape to render). You choose the design-system " +
         "components, layout, alternation, and visual treatment. Stay in the " +
-        "Inflexa Design Blueprint — base.html.j2, components, theme.css.");
+        "Inflexa Design Blueprint — base.html.j2, components.");
     out.push("");
     for (let i = 0; i < report.sections.length; i++) {
         out.push(`### ${i + 1}. ${report.sections[i].title} — type: \`${report.sections[i].type}\``);

package/dist/tools/report/mint-preview-url.d.ts

@@ -10,7 +10,7 @@
  *   - inspecting an older version (pass `version`)
  */
 import { type Tool } from "../define-tool.js";
-import type { PreviewPublisher } from "./preview-publisher.js";
+import { type PreviewPublisher } from "./preview-publisher.js";
 /** Shared, mutable URL cell so mint and preview-snapshot share a cached URL. */
 export interface PreviewUrlCell {
     url: string | undefined;

package/dist/tools/report/mint-preview-url.js

@@ -12,13 +12,15 @@
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
+import { describeMintFailure } from "./preview-publisher.js";
 export function createMintPreviewUrlTool(state) {
     return defineTool({
         id: "mint_preview_url",
-        description: "Mint a fresh preview URL for the report. Returns a content-server " +
-            "URL with embedded auth token (15-min TTL). Use this only when you " +
-            "need a URL for direct browser navigation — preview_snapshot handles " +
-            "the common case automatically.",
+        description: "Mint a fresh preview URL for the report. Returns a time-limited " +
+            "content-server URL with an embedded auth token, alongside the " +
+            "`expiresAt` it is good until. Use this only when you need a URL for " +
+            "direct browser navigation — preview_snapshot handles the common case " +
+            "automatically.",
         inputSchema: z.object({
             version: z.number().optional().describe("Version to mint for. Defaults to the iteration's current version."),
         }),
@@ -28,7 +30,7 @@ export function createMintPreviewUrlTool(state) {
             if (!result.ok) {
                 return ok({
                     ok: false,
-                    error: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                    error: describeMintFailure(result),
                 });
             }
             const url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${version}/index.html?t=${result.data.token}`;

package/dist/tools/report/preview-publisher.d.ts

@@ -24,6 +24,22 @@ export type PreviewMintResult = {
         message?: string;
     };
 };
+/** The not-ok arm of the seam's result — what a failed mint is allowed to carry. */
+export type PreviewMintFailure = Extract<PreviewMintResult, {
+    ok: false;
+}>;
+/**
+ * Renders a failed mint as the line an agent reads back from a preview tool.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport
+ * behind it supplies neither a status nor, necessarily, a message. Naming a
+ * field the seam left unset would put the literal `status=undefined` in front
+ * of the model, so the message carries only what actually arrived. This lives
+ * beside the type because its whole job is to honour that type's optionality —
+ * every tool holding the seam owes the same message, and one of them owning
+ * the wording would make the others depend on a peer for a seam-wide concern.
+ */
+export declare function describeMintFailure(failure: PreviewMintFailure): string;
 export interface PreviewPublisher {
     mintPreviewAccess(resourceId: string, previewId: string): Promise<PreviewMintResult>;
 }

package/dist/tools/report/preview-publisher.js

@@ -10,6 +10,26 @@
  * returns not-ok, so `preview_snapshot` short-circuits before touching
  * Chrome and the report still builds (submit_report is the only gate).
  */
+/**
+ * Renders a failed mint as the line an agent reads back from a preview tool.
+ *
+ * The failure shape is sparse by design: a realization with no HTTP transport
+ * behind it supplies neither a status nor, necessarily, a message. Naming a
+ * field the seam left unset would put the literal `status=undefined` in front
+ * of the model, so the message carries only what actually arrived. This lives
+ * beside the type because its whole job is to honour that type's optionality —
+ * every tool holding the seam owes the same message, and one of them owning
+ * the wording would make the others depend on a peer for a seam-wide concern.
+ */
+export function describeMintFailure(failure) {
+    const detail = [];
+    if (failure.status !== undefined)
+        detail.push(`status=${failure.status}`);
+    const message = failure.error.message?.trim();
+    if (message)
+        detail.push(message);
+    return detail.length > 0 ? `preview-access mint failed: ${detail.join(" ")}` : "preview-access mint failed";
+}
 /**
  * Local default — no hosted preview surface. Returns not-ok so the preview
  * tools surface a clear "unavailable" message and short-circuit before any

package/dist/tools/report/preview-snapshot.d.ts

@@ -10,10 +10,16 @@
  * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
  * console errors / failed requests to decide whether to fix the template
  * or move on to submit_report.
+ *
+ * A seam that cannot mint is also reported through the injected `Logger`:
+ * this tool is the build's only visual verification, so an unavailable seam
+ * means that verification silently did not happen — a condition an operator
+ * has to be able to see without reading the model transcript.
  */
 import { type Tool } from "../define-tool.js";
 import { type ChromeConfig } from "../../lib/chrome.js";
-import type { PreviewPublisher } from "./preview-publisher.js";
+import type { Logger } from "../../lib/logger.js";
+import { type PreviewPublisher } from "./preview-publisher.js";
 import type { PreviewUrlCell } from "./mint-preview-url.js";
 export interface PreviewSnapshotToolState {
     readonly resourceId: string;
@@ -22,5 +28,7 @@ export interface PreviewSnapshotToolState {
     readonly previews: PreviewPublisher;
     readonly urlCell: PreviewUrlCell;
     readonly chrome: ChromeConfig;
+    /** Operational logging seam; omitted falls back to no-op. */
+    readonly logger?: Logger;
 }
 export declare function createPreviewSnapshotTool(state: PreviewSnapshotToolState): Tool;

package/dist/tools/report/preview-snapshot.js

@@ -10,15 +10,23 @@
  * Returned screenshot is base64-encoded PNG bytes; the agent can inspect
  * console errors / failed requests to decide whether to fix the template
  * or move on to submit_report.
+ *
+ * A seam that cannot mint is also reported through the injected `Logger`:
+ * this tool is the build's only visual verification, so an unavailable seam
+ * means that verification silently did not happen — a condition an operator
+ * has to be able to see without reading the model transcript.
  */
 import { ok } from "neverthrow";
 import { z } from "zod";
 import { defineTool } from "../define-tool.js";
 import { withPage } from "../../lib/chrome.js";
+import { createNoopLogger } from "../../lib/console-logger.js";
+import { describeMintFailure } from "./preview-publisher.js";
 const NAV_TIMEOUT_MS = 20_000;
 const READY_TIMEOUT_MS = 8_000;
 const WAIT_MS_CAP = 30_000;
 export function createPreviewSnapshotTool(state) {
+    const logger = (state.logger ?? createNoopLogger()).named("preview-snapshot").with({ previewId: state.previewId });
     return defineTool({
         id: "preview_snapshot",
         description: "Render the report in a real headless browser and report what you " +
@@ -48,11 +56,17 @@ export function createPreviewSnapshotTool(state) {
             if (!url) {
                 const result = await state.previews.mintPreviewAccess(state.resourceId, state.previewId);
                 if (!result.ok) {
+                    const reason = result.error.message?.trim();
+                    logger.warn("preview access unavailable — visual verification did not run", {
+                        version: state.currentVersion,
+                        ...(result.status !== undefined ? { status: result.status } : {}),
+                        ...(reason ? { reason } : {}),
+                    });
                     return ok({
                         ok: false,
                         consoleErrors: [],
                         failedRequests: [],
-                        error: `preview-access mint failed: status=${result.status} ${result.error.message ?? ""}`.trim(),
+                        error: describeMintFailure(result),
                     });
                 }
                 url = `${result.data.baseUrl.replace(/\/?$/, "/")}v${state.currentVersion}/index.html?t=${result.data.token}`;

package/dist/tools/report/submit-report.d.ts

@@ -3,6 +3,7 @@
  * `data-report-preview` until this tool writes the success outcome.
  *
  * Checks:
+ *   - report.html.j2 exists at versionDir/ — the report itself
  *   - index.html exists at versionDir/ with size > 0
  *   - no unrendered `{{ … }}` or `{% … %}` left in the output
  *   - all referenced asset paths resolve to files on disk