@inflexa-ai/harness 0.23.0 → 0.25.0

package/dist/execution/report-render.d.ts

@@ -1,39 +0,0 @@
-/**
- * Report renderer — Node-side Nunjucks render of v{N}/report.html.j2 to v{N}/index.html.
- *
- * Stateless pure module: no harness imports, no env reads at import time,
- * safe to run standalone in tests.
- */
-export interface RenderReportOptions {
-    versionDir: string;
-    templatesDir: string;
-}
-export interface RenderReportResult {
-    ok: boolean;
-    indexBytes: number;
-    error?: {
-        kind: "missing-template" | "syntax" | "runtime";
-        message: string;
-        line?: number;
-        snippet?: string;
-    };
-}
-/**
- * Render `${versionDir}/report.html.j2` to `${versionDir}/index.html`.
- *
- * Loader resolution order: [versionDir, templatesDir]. `report.html.j2`
- * lives in versionDir; `extends "base.html.j2"` and `include "components/..."`
- * resolve from templatesDir. Autoescape is OFF — templates own escaping.
- *
- * `${templatesDir}/echarts-theme.json` is read, parsed, re-stringified, and
- * passed as `echarts_theme` (a JSON string) for safe inlining inside a
- * `<script>` block.
- *
- * Returns `{ ok: true, indexBytes }` on success. On failure, returns
- * `{ ok: false, indexBytes: 0, error }` with `error.kind`:
- *   - "missing-template" — `report.html.j2` (or any `extends`/`include` target)
- *      not found by either loader. Message identifies the missing path.
- *   - "syntax" — Nunjucks parse error in any loaded template.
- *   - "runtime" — anything else thrown during render or write.
- */
-export declare function renderReport(opts: RenderReportOptions): Promise<RenderReportResult>;

package/dist/execution/report-render.js

@@ -1,98 +0,0 @@
-/**
- * Report renderer — Node-side Nunjucks render of v{N}/report.html.j2 to v{N}/index.html.
- *
- * Stateless pure module: no harness imports, no env reads at import time,
- * safe to run standalone in tests.
- */
-import { readFile, writeFile } from "node:fs/promises";
-import { join } from "node:path";
-import nunjucks from "nunjucks";
-/**
- * Render `${versionDir}/report.html.j2` to `${versionDir}/index.html`.
- *
- * Loader resolution order: [versionDir, templatesDir]. `report.html.j2`
- * lives in versionDir; `extends "base.html.j2"` and `include "components/..."`
- * resolve from templatesDir. Autoescape is OFF — templates own escaping.
- *
- * `${templatesDir}/echarts-theme.json` is read, parsed, re-stringified, and
- * passed as `echarts_theme` (a JSON string) for safe inlining inside a
- * `<script>` block.
- *
- * Returns `{ ok: true, indexBytes }` on success. On failure, returns
- * `{ ok: false, indexBytes: 0, error }` with `error.kind`:
- *   - "missing-template" — `report.html.j2` (or any `extends`/`include` target)
- *      not found by either loader. Message identifies the missing path.
- *   - "syntax" — Nunjucks parse error in any loaded template.
- *   - "runtime" — anything else thrown during render or write.
- */
-export async function renderReport(opts) {
-    const { versionDir, templatesDir } = opts;
-    let echartsThemeJson;
-    try {
-        const raw = await readFile(join(templatesDir, "echarts-theme.json"), "utf8");
-        echartsThemeJson = JSON.stringify(JSON.parse(raw));
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        const kind = isNotFound(err) ? "missing-template" : "runtime";
-        return {
-            ok: false,
-            indexBytes: 0,
-            error: { kind, message: `failed to load echarts-theme.json: ${msg}` },
-        };
-    }
-    const env = new nunjucks.Environment(new nunjucks.FileSystemLoader([versionDir, templatesDir], {
-        noCache: true,
-    }), { autoescape: false, throwOnUndefined: false });
-    let html;
-    try {
-        html = env.render("report.html.j2", { echarts_theme: echartsThemeJson });
-    }
-    catch (err) {
-        return { ok: false, indexBytes: 0, error: classifyNunjucksError(err) };
-    }
-    try {
-        const indexPath = join(versionDir, "index.html");
-        await writeFile(indexPath, html, "utf8");
-        return { ok: true, indexBytes: Buffer.byteLength(html, "utf8") };
-    }
-    catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        return {
-            ok: false,
-            indexBytes: 0,
-            error: { kind: "runtime", message: `failed to write index.html: ${msg}` },
-        };
-    }
-}
-function isNotFound(err) {
-    if (!err || typeof err !== "object")
-        return false;
-    const code = err.code;
-    return code === "ENOENT";
-}
-function classifyNunjucksError(err) {
-    const message = err instanceof Error ? err.message : String(err);
-    if (/template not found/i.test(message)) {
-        return { kind: "missing-template", message };
-    }
-    // Nunjucks tags parse errors with "Template render error" + "expected" /
-    // "unexpected" / "parseError" markers; the Template error carries lineno.
-    const lineno = err?.lineno;
-    const colno = err?.colno;
-    const line = typeof lineno === "number" ? lineno : undefined;
-    const isSyntax = /parseError|expected|unexpected token|unexpected end of/i.test(message) || /Template render error.*line \d+/i.test(message);
-    if (isSyntax) {
-        const snippet = extractSnippet(message, line, typeof colno === "number" ? colno : undefined);
-        return snippet ? { kind: "syntax", message, line, snippet } : line !== undefined ? { kind: "syntax", message, line } : { kind: "syntax", message };
-    }
-    return line !== undefined ? { kind: "runtime", message, line } : { kind: "runtime", message };
-}
-function extractSnippet(message, line, col) {
-    if (!line)
-        return undefined;
-    const m = message.split("\n").find((l) => l.trim().length > 0 && !/^\s*at\s/.test(l));
-    if (!m)
-        return undefined;
-    return col !== undefined ? `${m} (col ${col})` : m;
-}

package/dist/execution/report-runner.d.ts

@@ -1,111 +0,0 @@
-/**
- * Report runner — orchestrates an iterative report build entirely in the
- * Cortex Node process. No sandbox, no Python.
- *
- * Lifecycle:
- *  1. Resolve version (latest + 1, or baseVersion + 1)
- *  2. Prepare version dir (mkdir, copy v{base}/report.html.j2, symlink ../assets)
- *  3. Construct the 4 custom report tools + the in-process versionFs surface;
- *     all of them close over the iteration's preview-dir state and a single
- *     `outcome: ReportOutcome | undefined` variable (the closure-state
- *     closure-state capture — see design.md Decision #9, mirrors
- *     `harness/tools/research/generate-plan.ts`'s
- *     `PlannerOutcome` capture).
- *  4. Build the `report-builder` AgentDefinition with that tool roster and
- *     drive it via `runAgent` + `passthroughStep`.
- *  5. Verify the closure-captured `outcome` is `{ ok: true, ... }` (else
- *     classify the failure, roll back the version dir, return a structured
- *     failure).
- *  6. Return success or a structured failure.
- *
- * Concurrency: per-previewId serialization via `withPreviewLock` so two
- * iterations on the same preview don't race on shared assets/.
- *
- * Billing: the report-builder's LLM calls flow through the `ChatProvider`
- * seam with `forSubAgent(session, REPORT_BUILDER_AGENT_ID)` — the provider's
- * lazy `resolveBilling` fires at the call site. No ALS, no fetch-patch
- * (Decision #6).
- *
- * Preview surface: the `preview_snapshot` and `mint_preview_url` tools mint
- * a content-server URL through the injected `PreviewPublisher` seam. The
- * managed publisher owns the short-lived host credential; the local default
- * returns "unavailable" so the report still builds without a hosted preview.
- */
-import type { Pool } from "pg";
-import { type RequestSession } from "../auth/types.js";
-import type { EmitFn } from "../loop/types.js";
-import type { ChatProvider } from "../providers/types.js";
-import type { PreviewPublisher } from "../tools/report/preview-publisher.js";
-import type { ChromeConfig } from "../lib/chrome.js";
-import type { Logger } from "../lib/logger.js";
-import type { UsageRecorder } from "../billing/usage-recorder.js";
-import type { AgentRunUsage } from "../loop/metrics.js";
-export interface ReportRunnerDeps {
-    /** Operational logging seam; omitted falls back to no-op. */
-    readonly logger?: Logger;
-    readonly provider: ChatProvider;
-    readonly pool: Pool;
-    /** Model id — provenance / metric label; provider owns the wire model. */
-    readonly model: string;
-    /** Root templates dir; `report-html` is joined onto it. */
-    readonly templatesDir: string;
-    /** Skills root; the report-builder gets read-only `report-html` skill tools. */
-    readonly skillsDir: string;
-    readonly chrome: ChromeConfig;
-    /** LLM usage-accounting seam for the report-builder loop; omitted falls back to the no-op recorder. */
-    readonly usageRecorder?: UsageRecorder;
-}
-export interface ReportRunnerOptions {
-    readonly resourceId: string;
-    /** Absolute host root of the analysis's workspace tree (previews live inside it). */
-    readonly workspaceRoot: string;
-    readonly previews: PreviewPublisher;
-    /** Preview group ID. Auto-generated by the tool layer if not provided. */
-    readonly previewId: string;
-    /** Base version to iterate from. Defaults to latest. */
-    readonly baseVersion?: number;
-    /**
-     * Format the preview was built as. The tool boundary admits only `"html"`,
-     * so no other value can reach a live iteration; the union stays wide because
-     * previews persisted with a broader vocabulary must still parse. Read this
-     * field as a record of what a preview is, not as a request for a renderer.
-     */
-    readonly format: "html" | "pdf";
-    /** Prompt for the report-builder agent. */
-    readonly prompt: string;
-    /** Live chat session — derives the child agent's session via forSubAgent. */
-    readonly session: RequestSession;
-    /** Cancellation signal — propagates to the agent stream. */
-    readonly signal: AbortSignal;
-    /** Event sink — forwarded to the agent loop. */
-    readonly emit: EmitFn;
-    /**
-     * The calling turn's usage accumulator (`ctx.turnUsage`), so the
-     * report-builder loop's tokens land in the turn total its root reports.
-     */
-    readonly turnUsage?: AgentRunUsage;
-    /**
-     * The dispatching tool call's id (`ctx.invocationId`), which discriminates
-     * the builder loop's usage record keys from those of a sibling iteration
-     * dispatched in the same round — same frame, same call path, same
-     * loop-local step names.
-     */
-    readonly invocationId?: string;
-}
-export type ReportRunnerResult = {
-    ok: true;
-    previewId: string;
-    version: number;
-    previewPath: string;
-    durationMs: number;
-    /** Caveats surfaced by the agent via submit_report. */
-    notes: readonly string[];
-} | {
-    ok: false;
-    previewId: string;
-    version: number;
-    reason: string;
-    errorKind: "render" | "submit" | "build" | "timeout" | "internal";
-    durationMs: number;
-};
-export declare function runReportIteration(deps: ReportRunnerDeps, opts: ReportRunnerOptions): Promise<ReportRunnerResult>;

package/dist/execution/report-runner.js

@@ -1,230 +0,0 @@
-/**
- * Report runner — orchestrates an iterative report build entirely in the
- * Cortex Node process. No sandbox, no Python.
- *
- * Lifecycle:
- *  1. Resolve version (latest + 1, or baseVersion + 1)
- *  2. Prepare version dir (mkdir, copy v{base}/report.html.j2, symlink ../assets)
- *  3. Construct the 4 custom report tools + the in-process versionFs surface;
- *     all of them close over the iteration's preview-dir state and a single
- *     `outcome: ReportOutcome | undefined` variable (the closure-state
- *     closure-state capture — see design.md Decision #9, mirrors
- *     `harness/tools/research/generate-plan.ts`'s
- *     `PlannerOutcome` capture).
- *  4. Build the `report-builder` AgentDefinition with that tool roster and
- *     drive it via `runAgent` + `passthroughStep`.
- *  5. Verify the closure-captured `outcome` is `{ ok: true, ... }` (else
- *     classify the failure, roll back the version dir, return a structured
- *     failure).
- *  6. Return success or a structured failure.
- *
- * Concurrency: per-previewId serialization via `withPreviewLock` so two
- * iterations on the same preview don't race on shared assets/.
- *
- * Billing: the report-builder's LLM calls flow through the `ChatProvider`
- * seam with `forSubAgent(session, REPORT_BUILDER_AGENT_ID)` — the provider's
- * lazy `resolveBilling` fires at the call site. No ALS, no fetch-patch
- * (Decision #6).
- *
- * Preview surface: the `preview_snapshot` and `mint_preview_url` tools mint
- * a content-server URL through the injected `PreviewPublisher` seam. The
- * managed publisher owns the short-lived host credential; the local default
- * returns "unavailable" so the report still builds without a hosted preview.
- */
-import { copyFile, mkdir, readdir, rm, stat, symlink } from "node:fs/promises";
-import { join } from "node:path";
-import { forSubAgent } from "../auth/types.js";
-import { runToTerminal } from "../loop/run-to-terminal.js";
-import { passthroughStep } from "../loop/run-step.js";
-import { previewVersionDir, previewDir, latestPreviewVersion } from "../workspace/paths.js";
-import { withPreviewLock } from "../tools/lib/preview-lock.js";
-import { createBuildReportTool, createSubmitReportTool, createMintPreviewUrlTool, createPreviewSnapshotTool, createVersionFsTools, } from "../tools/report/index.js";
-import { createReportBuilderAgent, REPORT_BUILDER_AGENT_ID, REPORT_BUILDER_SKILLS } from "../agents/report-builder.js";
-import { createSkillTools } from "../tools/sandbox/skills.js";
-import { createNoopLogger } from "../lib/console-logger.js";
-const REPORT_AGENT_MAX_STEPS = 75;
-export async function runReportIteration(deps, opts) {
-    const logger = (deps.logger ?? createNoopLogger()).named("report-runner").with({ previewId: opts.previewId });
-    const startTime = performance.now();
-    return withPreviewLock(opts.previewId, async () => {
-        // ── Resolve version directories ───────────────────────────────
-        const previewRootAbs = join(opts.workspaceRoot, previewDir(opts.previewId));
-        let existingVersions = [];
-        try {
-            existingVersions = (await readdir(previewRootAbs, { withFileTypes: true })).filter((d) => d.isDirectory()).map((d) => d.name);
-        }
-        catch {
-            /* dir doesn't exist yet */
-        }
-        const latestVer = latestPreviewVersion(existingVersions);
-        const baseVer = opts.baseVersion ?? latestVer;
-        const newVersion = Math.max(latestVer, baseVer) + 1;
-        const versionDirRel = previewVersionDir(opts.previewId, newVersion);
-        const versionDirAbs = join(opts.workspaceRoot, versionDirRel);
-        const assetsDirAbs = join(previewRootAbs, "assets");
-        // ── Prepare directories ───────────────────────────────────────
-        try {
-            await mkdir(versionDirAbs, { recursive: true });
-            await mkdir(assetsDirAbs, { recursive: true });
-            if (baseVer > 0) {
-                const baseTemplate = join(opts.workspaceRoot, previewVersionDir(opts.previewId, baseVer), "report.html.j2");
-                try {
-                    await copyFile(baseTemplate, join(versionDirAbs, "report.html.j2"));
-                }
-                catch (err) {
-                    const code = err.code;
-                    if (code !== "ENOENT")
-                        throw err;
-                    // Base version has no template — agent will author from scratch.
-                }
-            }
-            // Symlink assets/ → ../assets so templates can reference assets/foo.csv
-            // and the content-server resolves them through the version-dir prefix.
-            const assetsSymlink = join(versionDirAbs, "assets");
-            try {
-                await symlink("../assets", assetsSymlink, "dir");
-            }
-            catch (err) {
-                const code = err.code;
-                if (code !== "EEXIST")
-                    throw err;
-            }
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            return failure(opts.previewId, newVersion, `prepareVersionDir failed: ${msg}`, "internal", startTime);
-        }
-        // ── Closure-captured terminal-tool state (Decision #9) ─────────
-        let outcome;
-        const urlCell = { url: undefined, expiresAt: undefined };
-        const templatesDir = join(deps.templatesDir, "report-html");
-        const buildReportTool = createBuildReportTool({
-            versionDir: versionDirAbs,
-            templatesDir,
-        });
-        const submitReportTool = createSubmitReportTool({
-            versionDir: versionDirAbs,
-            assetsDir: assetsDirAbs,
-            setOutcome: (v) => {
-                outcome = v;
-            },
-        });
-        const tools = [
-            buildReportTool,
-            submitReportTool,
-            createMintPreviewUrlTool({
-                resourceId: opts.resourceId,
-                previewId: opts.previewId,
-                currentVersion: newVersion,
-                previews: opts.previews,
-                urlCell,
-            }),
-            createPreviewSnapshotTool({
-                resourceId: opts.resourceId,
-                previewId: opts.previewId,
-                currentVersion: newVersion,
-                previews: opts.previews,
-                urlCell,
-                chrome: deps.chrome,
-                logger,
-            }),
-            ...createVersionFsTools({ versionDir: versionDirAbs }),
-            ...Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: [...REPORT_BUILDER_SKILLS] })),
-        ];
-        const agent = createReportBuilderAgent({ model: deps.model, tools });
-        // The agent's runaway-guard takes precedence over the per-iteration cap.
-        const cappedAgent = {
-            ...agent,
-            maxIterations: Math.min(agent.maxIterations, REPORT_AGENT_MAX_STEPS),
-        };
-        const childSession = forSubAgent(opts.session, REPORT_BUILDER_AGENT_ID);
-        let agentError;
-        try {
-            await runToTerminal(cappedAgent, [{ role: "user", content: opts.prompt }], childSession, {
-                provider: deps.provider,
-                signal: opts.signal,
-                emit: opts.emit,
-                runStep: passthroughStep,
-                resolved: () => outcome !== undefined,
-                usageRecorder: deps.usageRecorder,
-                // Fold the builder's calls into the turn total the root loop reports.
-                turnUsage: opts.turnUsage,
-                invocationId: opts.invocationId,
-            }, {
-                tools: [buildReportTool, submitReportTool],
-                nudge: "You stopped without calling submit_report, so this report version " +
-                    "was not recorded. Build the report if needed, then call " +
-                    "submit_report now to finalize it.",
-            });
-        }
-        catch (err) {
-            agentError = err instanceof Error ? err.message : String(err);
-        }
-        // ── Phantom-success guard ──────────────────────────────────────
-        // submit-report claims ok but index.html doesn't exist or is empty.
-        let phantomSuccess = false;
-        if (outcome?.ok === true && !agentError) {
-            try {
-                const indexStat = await stat(join(versionDirAbs, "index.html"));
-                if (!indexStat.isFile() || indexStat.size === 0)
-                    phantomSuccess = true;
-            }
-            catch {
-                phantomSuccess = true;
-            }
-        }
-        if (!outcome || agentError || phantomSuccess) {
-            logger.warn("report.agent.finish", { version: newVersion, submitted: outcome?.ok === true, phantom: phantomSuccess, agentError });
-            const { reason, errorKind } = classifyFailure({
-                phantomSuccess,
-                agentError,
-                outcome,
-            });
-            // Roll back the version dir (assets are shared — leave them alone).
-            try {
-                await rm(versionDirAbs, { recursive: true, force: true });
-            }
-            catch (err) {
-                logger.error("rollback failed", { versionDirAbs, ...logger.errorFields(err) });
-            }
-            return failure(opts.previewId, newVersion, reason, errorKind, startTime);
-        }
-        const durationMs = Math.round(performance.now() - startTime);
-        return {
-            ok: true,
-            previewId: opts.previewId,
-            version: newVersion,
-            previewPath: `v${newVersion}/index.html`,
-            durationMs,
-            notes: outcome.notes,
-        };
-    });
-}
-function failure(previewId, version, reason, errorKind, startTime) {
-    return {
-        ok: false,
-        previewId,
-        version,
-        reason,
-        errorKind,
-        durationMs: Math.round(performance.now() - startTime),
-    };
-}
-function classifyFailure(s) {
-    if (s.phantomSuccess) {
-        return {
-            reason: "submit_report claimed ok but index.html is missing or empty",
-            errorKind: "build",
-        };
-    }
-    if (s.agentError) {
-        return {
-            reason: s.agentError,
-            errorKind: /timeout/i.test(s.agentError) ? "timeout" : "submit",
-        };
-    }
-    return {
-        reason: "agent did not call submit_report — terminal outcome was never recorded",
-        errorKind: "submit",
-    };
-}

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

@@ -1 +0,0 @@
-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";