Synthesize

agentii.synthesize

The single-point HTML generation step (spec 046 Q46–Q50): ONE thesis-report.html per thesis, authored from the markdown artifacts and then optimized against real renders. Analysis skills emit markdown only (Q49); the report is assembled here, at the synthesis step, after the cross-stock synthesis (_cross/*_synthesis.md) exists.

When to run

• After the synthesis tasks complete (the _cross/ deliverable is written).
• When converge emits an html_stale finding (sources or template moved).
• On explicit request, or once at thesis completion (Q50 regeneration triggers).

The loop (four steps + optimize)

# 0. RESOLVE the kit root — contracts/kit-root.md. The kit's scripts do NOT ship with
#    the skills, so never assume the CWD is the checkout (`cd agentii-investment-
#    intelligence` was this skill's old step 0, and it only worked for a user sitting
#    in the checkout). This resolver fails loudly rather than guessing:
KIT=""
for c in "${AGENTII_KIT_ROOT:-}" \
         "$(cat "$HOME/.claude/skills/agentii/.kit-root" 2>/dev/null)" \
         "${CLAUDE_PLUGIN_ROOT:-}"; do
  [ -n "$c" ] && [ -f "$c/scripts/agentii_cmd.py" ] && { KIT="$c"; break; }
done
if [ -z "$KIT" ]; then d="$PWD"; while [ "$d" != "/" ]; do
  [ -f "$d/scripts/agentii_cmd.py" ] && { KIT="$d"; break; }; d="$(dirname "$d")"; done; fi
[ -n "$KIT" ] || { echo "agentii kit not found — see contracts/kit-root.md" >&2; exit 1; }

# 1. PACK — deterministic bundle of every source, verbatim (no timestamps),
#    PLUS report/metrics.json (per-ticker key_metrics/conclusions/counts —
#    machine-ready numbers for KPI tiles and kpi_trend charts, RAW values):
python3 "$KIT/scripts/synthesize_report.py" pack --thesis <theses/{nnn}-{slug}>

# 2. AUTHOR — read <thesis>/report-input.md (verbatim sources + citations)
#    and <thesis>/report/metrics.json (numbers). Write
#    <thesis>/report/content.html — the report's actual content is YOUR judgment.

# 2b. SCORE (required — spec 058 FR-065). The blocking gate decides what TEXT can
#     decide; it cannot see whether the report is any good, and "passes the gate"
#     must never be read as "reads well". Run the scorer for the RUBRIC and the
#     MEASURED evidence — the judgement is yours, the measurement is not:
python3 "$KIT/scripts/score_report_readability.py" <thesis-dir>/report/content.html
#     Then read the report and record your total (five criteria, 1–5 each → 1–25)
#     in <thesis-dir>/report/readability.json:
#       {"score": 21, "previous": 18, "explanation": ""}
#     `previous` is the last RELEASED report's score; omit it (or write null) for a
#     first report, which sets its own baseline — no score is chosen in advance.
#     A score BELOW `previous` requires `explanation`, and `assemble` REFUSES the
#     drop without one: FR-065's consequence is that a regression is explained in
#     the deliverable, and a score recorded without consequence is the defect
#     FR-040 forbids. A LOW score is not refused — only an unexplained regression.
#     The score is rendered on the cover beside the pins (T091), so it has a named
#     consumer: the human reviewer.

# 3. ASSEMBLE — validate + inject + gate (advisories on stderr are guidance,
#    the hard gates are silent until they fail):
python3 "$KIT/scripts/synthesize_report.py" assemble --thesis <thesis-dir> --check-only  # fit loop
python3 "$KIT/scripts/synthesize_report.py" assemble --thesis <thesis-dir>               # deliver

# 4. RENDER — Chrome headless → letter PDF → per-page PNGs + manifest.
#    --keep-pdf is REQUIRED for delivery: without it the PDF is written to a temp dir,
#    used for the PNGs, and DELETED. The deliverable is HTML **and** PDF.
python3 "$KIT/scripts/render_report.py" render --thesis <thesis-dir> --keep-pdf

# 5. OPTIMIZE (required, not optional): READ the PNGs page by page, in batches
#    of 3–4. Fix real problems the estimator cannot see — clipped tables, ugly
#    URL wrapping, weak density, orphan headings, oversized tiles. Edit
#    content.html → re-assemble → re-render until EVERY page is visually clean.

Deliverables

Two files, both at the thesis root — report the absolute paths when you finish:

• <thesis-dir>/thesis-report.html
• <thesis-dir>/thesis-report.pdf

The PDF is the deliverable, not a QA by-product. render's docstring frames it as the "visual QA loop" because the PNGs are what the optimize pass reads — but --keep-pdf is what turns its --print-to-pdf output into the artifact a user actually sends to someone, and it belongs beside the HTML rather than in the report/pages/ scratch folder with the PNGs.

Renders never gate CI (Chrome/poppler may be absent) — the author's own visual pass is the gate. assemble --check-only remains the estimator fallback; a missing render is a hard stop for delivery, not a silent skip. render --verify also checks each PNG is letter-width at the requested dpi.

content.html contract (the assembler hard-gates every rule)

You author only the page sequence — a fragment, never a document:

1. One or more <section class="page">…</section> blocks, no nesting. The cover is page 1 and is template-owned: do not author it — the assembler fills kicker / title / claim / pins / universe / generated / TOC, and injects the running sheet head/foot, page marks (NN / TOTAL) and corner registration marks into every page.
2. Fragment only — <!DOCTYPE>, <html>, <head>, <body>, <style>, <script> are rejected. Element whitelist: section h1 h2 h3 p ul ol li table thead tbody tr th td b strong i em code a div span br hr blockquote.
3. No <img> and no id starting cover- or equal to stale-bar.
4. Reserved classes — never emit these (assembler chrome): sheet-head, sheet-foot, reg, cover, page-mark, disclaimer. A collision is a hard validation error, not a warning. The disclaimer page is the newest of these (Q139): one legal tail page, numbered last, injected by synthesize_report.build_html from templates/disclaimer.md — the single source for that text. Do not author it, do not paraphrase it, and do not put a disclaimer in a page of your own. It is deliberately absent from the contents list: it is a legal tail, not a chapter.
5. Citation gate (anti-fabrication): every viewer link you emit must be copied verbatim from report-input.md — the pack's links have the form …/v/{TICKER}/{citation_id}/{N} on the agentii viewer. The assembler rejects any {ticker}/{citation_id} pair it cannot find in the sources, with an offender list. Never invent a citation_id; every [FACT] number you surface keeps its citation link. metrics.json carries NO citation ids — never build viewer links from tiles. Citations that only exist as bare text in the pack (keyword scans like ISRG × ect75 × page1) may be rendered as plain text — do not turn them into fake links.
6. Charts (Q48) are tokens, not images:

   <div data-chart="kpi_trend" data-spec='{"x":["FY2024","FY2025","H1 2026"],"y":[77.7,128.3,96.3]}' data-height="160"></div>

   data-spec is single-quoted JSON (no apostrophes inside). kpi_trend is for non-price structured series (capex trajectories, revenue series) built from metrics.json multi-period keys. football_field {labels,lows,highs}, peer_bars {labels,values}, scatter {x,y}, scenario_tree {edges} remain market-data-only. data-height is your page-budget claim — the overflow estimator counts it exactly, so keep it honest. Research-only theses (market-data stage none) emit only kpi_trend, if anything.

Component rules (v0.3.0 design system)

• KPI tiles: the executive-summary page REQUIRED to open with a .stat-row of 2–4 thesis-level tiles (e.g. artifacts count · key-metrics count · pillars supported · GPT-3.5 window). Per-ticker sections carry 2–4 ticker tiles. Structure: div.stat > div.num + div.lbl + div.sub. Numbers from metrics.json, formatted per style.md: $28.5B (not $28,476M; one decimal for billions, none for millions), 12.4%, +12.4%, 14.2x.
• Badges — two orthogonal axes, never confused:
  • taxonomy (FR-092): [FACT]→.badge-fact, [DEDUCTED]→.badge-deducted, [VIEW]→.badge-view — use on evidence-table rows and claim prose;
  • verdicts: supported→.badge-supported, indeterminate→ .badge-indeterminate, refuted→.badge-refuted — every pillar verdict carries one.
• Timeline: the capability-timeline page uses .timeline with .tl-item blocks — .tl-phase holds the mono phase label, the prose keeps the synthesis's wording with its citations.
• Kickers: every page opens with a .sec-kicker (mono editorial label, e.g. THE CORPUS · 24 ARTIFACTS), never the heading text repeated.