reporting

name	reporting
type	capability
description	Assemble charts, tables, and analyst text into a beautiful, branded PDF — either a multi-page portrait report (A4) or a 16:9 landscape presentation deck like Google Slides. Ships page templates (comparison matrix, industry breakdown, full-bleed price chart with technical commentary, data table with commentary) that consume output from the charting, thematic-investing, and sec-filings skills. Remembers your logo and brand colors after first use. Triggers: "generate a PDF report", "turn this analysis into a deck", "make a presentation of these charts", "client-ready report", "export to PDF", "slides comparing these companies", "branded research report", "investment memo PDF".
requires	["analyst-kit-core","charting"]

Preamble (run first)

PLAN MODE EXCEPTION — ALWAYS RUN: this block only reads state and writes to ~/.analyst-kit/.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
if [ ! -x "$_AK/bin/analyst-kit-preamble" ]; then
  for d in ~/.claude/skills/analyst-kit-core .claude/skills/analyst-kit-core ~/.codex/skills/analyst-kit-core .codex/skills/analyst-kit-core; do
    [ -x "$d/bin/analyst-kit-preamble" ] && _AK="$d" && break
  done
  [ -x "$_AK/bin/analyst-kit-preamble" ] || _AK="$(find ~/.claude/plugins -maxdepth 6 -type d -name analyst-kit-core 2>/dev/null | head -1)"
  [ -n "$_AK" ] && { mkdir -p ~/.analyst-kit; printf '%s' "$_AK" > ~/.analyst-kit/core-path; } || true
fi
[ -x "$_AK/bin/analyst-kit-preamble" ] && "$_AK/bin/analyst-kit-preamble" --skill reporting 2>/dev/null || echo "AK_CORE: not found (continue without runtime)"

Read the echoed state and act. Skip ALL bullets below if DEDUP: yes or AK_CORE: not found:

• DISABLED: yes → this skill is turned off because a required API key isn't configured. Do not run it. Tell the user it's off, name the missing key (see MISSING_KEYS), and offer to enable it — either they give you the key now (store it with "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>, which re-enables the skill) or they say "set up analyst-kit" for full setup. Then stop; do not attempt the skill's work.
• First run — ONBOARDED: no → orient the user once, then run "$_AK/bin/analyst-kit-setup" finish (this covers the telemetry notice, so skip the TEL_PROMPTED bullet this turn):
  1. Data home — tell the user Analyst Kit keeps config, API keys, local usage analytics, and a learnings log together in one folder (default ~/.analyst-kit); offer to move it with "$_AK/bin/analyst-kit-setup" home <dir>.
  2. Telemetry (a notice, not a question) — usage telemetry is on by default: only skill name, duration, outcome, and version, tagged with a per-machine device id derived from the hardware/OS, never repo names, paths, tickers, or content; opt out anytime by asking to turn Analyst Kit telemetry off.
  3. Identity (name + email — required) — ask for the user's name and email, stating plainly the email is mandatory to use most features (SEC EDGAR's fair-access policy requires a real, reachable contact on every request). If they decline because they don't want the email-dependent skills, discover a fallback yourself (git config user.email, gh api user, …) and pass it with --fallback in step 5.
  4. Offer full setup — ask if they'd like to configure API keys for all skills now. If yes, Read "$_AK/references/intro.md" and follow it. If no, continue — you'll ask for a key only when a skill needs one.
  5. Run "$_AK/bin/analyst-kit-setup" finish --name "<name>" --email "<email>" (add --fallback for a discovered email; run plain finish only if no email could be found at all). If it echoes INVALID_EMAIL, re-ask and run it again.
• User asks to set up Analyst Kit at any time (e.g. "set up analyst-kit", "help me set up Analyst Kit", "configure all skills") → Read "$_AK/references/intro.md" and follow it end to end: data home, telemetry, every skill's keys, and enabling/disabling each.
• TEL_PROMPTED: no (returning user) → give the telemetry notice once, then run "$_AK/bin/analyst-kit-setup" ack-telemetry.
• If the user asks to turn telemetry off (now or anytime): before flipping it, make a sincere case once — telemetry is what tells the maintainers which skills break, which run slow, and where users get stuck, so keeping it on directly improves their experience; it never includes their data. Offer "$_AK/bin/analyst-kit-config" set telemetry anonymous (drops the device id) as a middle ground. If they still want out, run "$_AK/bin/analyst-kit-config" set telemetry off immediately and without further argument.
• Before running any script that needs an API key: source both the data home's .env and the current directory's .env into the shell so scripts can read stored keys: set -a; [ -f "$AK_HOME/.env" ] && . "$AK_HOME/.env"; [ -f "./.env" ] && . "./.env"; set +a (where $AK_HOME is the path printed on the AK_HOME: line above). Full lookup order — always check these before concluding a key is missing or asking the user:
  1. current shell environment
  2. $AK_HOME/.env (keys stored by analyst-kit-setup)
  3. .env in the current working directory Never ask the user for a key that is already present in any of these locations.
• MISSING_KEYS not none → for each listed key with KEY_PROMPTED_<KEY>: no: explain where to get it, ask for the value, and run "$_AK/bin/analyst-kit-setup" set-key <KEY> <value>. If declined, run "$_AK/bin/analyst-kit-setup" skip-key <KEY> (this disables the skills that need it) and continue — never block the skill.
• UPGRADE: UPGRADE_AVAILABLE <old> <new> → say "Analyst Kit skills is available (you have ) — update?". If yes: Read "$_AK/references/upgrade.md" and follow it. If declined: run "$_AK/bin/analyst-kit-update-check" --snooze <new>.
• LEARNINGS entries shown → these are past mistakes/preferences for this user; respect them and do not repeat logged pitfalls.

Then proceed with the skill. At the very end, run the Completion block at the bottom of this file.

Reporting — storyline → branded PDF

This skill does exactly one job: take a storyline — an ordered set of pages, each with its point, plus the already-generated UI elements (chart contracts) and data (tables, text) — and turn it into a beautiful PDF. It does not decide what the report should say: the storyline arrives pre-decided (from the user, the orchestrating agent, or an upstream skill). Reporting owns only the layout and the rendering.

storyline (pages, each: point + modules + data)
        ─► report contract (JSON)
        ─► bun scripts/render.ts contract.json out/report.pdf

A JSON report contract encodes the storyline against shipped templates. One script assembles a self-contained HTML document (Highcharts vendored from the sibling charting skill, inlined once — no network at render time) and prints it to PDF with Playwright.

Designing a page — think in this order

For every page of the storyline, answer three questions in order:

1. What is the main point of this page? One sentence. It goes in the page's story slot (required on every data page) and renders as a banner under the title — the reader gets the conclusion before the evidence. Put the headline numbers the user actually asked for (entry/exit price, latest YoY, the verdict) in stats chips right below it.
2. Which modules does the point need? Chart, table, commentary, rating matrix, layer cards — pick the template whose modules match.
3. How do the modules arrange? Pick the mode (report = portrait A4 document, presentation = 16:9 deck) and let the template lay the modules out. One point per page — if a page is making two points, split it.

A page with lots of empty space or no story is a page whose point was never decided — fix the storyline, not the CSS.

Style defaults

These are the house style. Apply them on every report unless the user explicitly overrides one for a given report — and a per-report override never changes the defaults themselves.

1. Information-dense. Professional research layout: 10pt body, tight vertical rhythm, evidence (charts/tables) gets the reclaimed space. Never pad a page to fill it. The cover is the one deliberately airy page.
2. Conclusion first. Every data page opens with the story banner, then stats chips carrying the headline numbers the user asked for (entry/exit, latest YoY, the verdict).
3. Levels live on the chart. Any price level the commentary mentions (support, resistance, entry, exit, moving averages) is also drawn on the chart via levels — green for support/entry, red for resistance/exit, gray otherwise.
4. References are always the last page. The renderer appends it automatically from the required top-level references array; every data page cites into it with sources: [n], rendered as linked [n] footnote marks in the footer.
5. One point per page. Two points = two pages. Row caps (7 companies, 10 table rows per slide) are enforced.
6. Modes. report = portrait A4 multi-page document; presentation = 16:9 landscape deck (Google Slides geometry). Default to report unless the user asks for a deck/presentation/slides.
7. Branding. Persisted report-brand/brand.json applies silently; built-in default theme otherwise. Page numbers on (skipped on cover); meta.footer repeats on every page.
8. Charts are print-tuned. No navigator/range selector/animation; vendored Highcharts inlined so the PDF renders offline; chart contracts in, never pre-rendered chart HTML.

When the user overrides ("make it airy", "skip the references page", "no story banners"), honor it for that report only and say so in your summary. The renderer hard-enforces #4 and the story slot — for those, an override means filling them minimally (e.g. a single reference), not skipping them.

Fast path

bun scripts/render.ts report.json out/report.pdf               # the one command
bun scripts/render.ts report.json out/report.html --html-only  # no Playwright needed
bun scripts/render.ts report.json out/report.pdf --keep-html   # keep the HTML beside the PDF
bun scripts/render.ts report.json out/report.pdf --brand x.json # one-off brand override

Minimal contract (templates/examples/ has full ones for both modes):

{
  "meta": { "mode": "report", "title": "Roblox (RBLX) — Bookings vs Revenue" },
  "pages": [
    { "template": "cover", "slots": { "title": "Roblox (RBLX)", "kicker": "Equity Research" } },
    { "template": "price-chart-technicals", "slots": {
        "title": "RBLX — price action",
        "story": "Price is consolidating above the 200-day — the uptrend is intact.",
        "chart": "./out/price-contract.json",
        "levels": [ { "value": 42, "label": "Support $42", "kind": "support" } ],
        "commentary": [ { "heading": "Trend", "body": "Uptrend intact above the 200-day." } ],
        "sources": [1] } }
  ],
  "references": [
    { "label": "Daily OHLC price data, RBLX", "detail": "Exchange consolidated tape" }
  ]
}

• meta.mode: "report" = portrait A4 document · "presentation" = 16:9 landscape deck.
• Paths inside the contract (chart contracts, brand, logo) resolve relative to the contract file.
• meta.footer text repeats on every page; page numbers are automatic (skipped on cover).
• references (top-level) is required — the renderer auto-appends a References page as the always-last page. Pages cite into it with sources: [1, 3] (1-based); citations render as [n] links in the page footer, anchored to the reference entry.

One-time setup

cd <this skill's directory> && bun install && bunx playwright install chromium

render.ts tells you exactly this when Playwright is missing. Environments that already provide browsers via PLAYWRIGHT_BROWSERS_PATH (e.g. the e2e container) skip the browser download. If PDF printing is unavailable, fall back to --html-only and convert with any HTML→PDF tool (the e2e container ships html2pdf).

Branding

Brand config lives in the project working directory at report-brand/brand.json so it survives skill reinstalls and is reused across reports:

{
  "company": "MK Capital",
  "logo": "./logo.png",
  "logoPlacement": "top-left",
  "colors": { "primary": "#1a3c6e", "accent": "#e8a33d", "panel": "#f5f7fa" },
  "footerText": "MK Capital — Confidential"
}

• First use: if ./report-brand/brand.json doesn't exist, ask the user once: "Want branded reports? Upload a logo and tell me your brand colors (or say skip)." On an answer, write report-brand/brand.json and copy the logo file in yourself. On "skip", proceed with the default theme and don't ask again this session.
• Present: use it silently; mention which brand was applied in your summary.
• Per-prompt override ("make this one red"): write a one-off brand JSON and pass --brand; never mutate the persisted file unless the user says to update their brand.
• Precedence: --brand flag > brand (inline object) in contract > brand (path) in contract > ./report-brand/brand.json > built-in default.
• Logo formats: png / jpg / svg / webp; it's inlined as a data URI. Colors omitted from colors fall back to the default palette.

Templates

Template	Required slots	Optional slots	Typical source
cover	title	subtitle, kicker, date	—
comparison	title, story, companies (2–7)	subtitle, stats, takeaway, source	thematic-investing sensitivity / exposure tables
industry-breakdown	title, story, layers (2–9)	subtitle, stats, takeaway, source	thematic-investing value-chain map
price-chart-technicals	title, story, chart, commentary (1–4 blocks)	subtitle, stats, levels, sources	charting price builder + technical-analysis levels
table-commentary	title, story, table, commentary	subtitle, stats, sources	sec-filings KPIs, any tabular data

(references is not a template you place — the renderer always appends it last.)

Slot shapes:

• story — required on every data page. The one-sentence point of the page, conclusion-first (supports **bold**). Renders as a banner under the title.

• stats — [{ "label": "Entry", "value": "$215" }] key-number chips rendered under the story on any template. Put the numbers the user asked for here.

• levels — [{ "value": 215, "label": "Support $215", "kind": "support" }] on price-chart-technicals: horizontal lines drawn on the chart with colored labels. kind: support/entry = green, resistance/exit = red, omitted = gray. Always plot the levels the commentary talks about.

• sources — [1, 3], 1-based indices into the top-level references array; rendered as linked [n] citations in the page footer.

• chart — a path to a charting contract JSON (preferred), or { "image": "chart.png" } as an escape hatch. Never pass charting's pre-rendered HTML pages; reporting renders contracts itself, print-tuned (no navigator/range selector, fixed height, animations off).

• companies — { "name", "ticker", "mechanism", "ratings": { "narrative", "revenue", "profit", "purity" } } with each rating "high" | "medium" | "low" (rendered as colored pills).

• layers — { "name", "role", "scarcity": "scarce" | "contested" | "commoditized", "tickers": ["..."] }, ordered upstream → downstream.

• table — { "columns": ["..."], "rows": [["...", "..."]] }. Cells are pre-formatted strings — format numbers upstream (units, $/%, accounting negatives) per charting's data-unit conventions.

• commentary / takeaway — { "heading", "body" }; body supports **bold**, *italic*, and - bullet lines only.

Default skeleton when the storyline isn't fully specified: cover → one chart page → table-commentary. For "make a deck/presentation", same storyline with meta.mode: "presentation" and one point per slide.

Rules

• Storyline in, PDF out — nothing else. Don't gather data, build charts, or invent narrative here; that happens upstream. If the storyline is missing a page's point, push back upstream rather than padding the page.
• Every data page states its point. story is required; the renderer errors without it. Headline numbers go in stats, not buried in prose.
• Compute upstream, never in prose. Numbers come from the data pipelines (charting's Polars layer, sec-filings extracts) already formatted; this skill only lays them out.
• One point per page/slide. Respect the row caps (7 companies, 10 table rows per slide) — the renderer errors past them; split across pages.
• Information-dense, not airy. These are professional research documents — a half-empty page means the storyline gave that page too little to say.
• Always cite. Top-level references is required (the renderer errors without it); every data page should carry sources: [n] pointing into it. Levels the commentary mentions must also be drawn on the chart via levels.
• Don't hand-write report HTML. If a layout doesn't exist, add a template function to scripts/render.ts and styles to assets/styles.css.
• The renderer fails loudly: unknown templates, missing slots, missing chart contract files, and charts that produced no SVG all exit non-zero — read the message.

Files

• scripts/render.ts — the whole pipeline: contract → HTML → PDF.
• assets/styles.css — page geometry (@page), template layouts, brand CSS variables.
• assets/default-brand.json — fallback brand.
• templates/examples/ — a full report contract and a full presentation contract; copy one as your starting point.

Completion (run last)

Audit before you deliver. If this run produced a research deliverable carrying quantitative or factual claims — a deep dive, thematic/value-chain map, technical call, company wiki, or financial model — you MUST verify it before presenting it. If a research-auditor subagent is available (the analyst-kit plugin ships one), invoke it via the Task tool, handing it the draft and the data artifacts you used; on a runtime without subagents, run the same checks yourself. Resolve every CRITICAL finding and disclose any UNVERIFIED ones; never deliver on a FAIL verdict without fixing it first. Skip this only for pure data-fetch/utility runs with no analytical claims.

PLAN MODE EXCEPTION — ALWAYS RUN: writes only to ~/.analyst-kit/. Replace OUTCOME with one of DONE | DONE_WITH_CONCERNS | ERROR | ABORT | NEEDS_CONTEXT.

_AK="$(cat ~/.analyst-kit/core-path 2>/dev/null)"
[ -x "$_AK/bin/analyst-kit-log" ] && "$_AK/bin/analyst-kit-log" end --skill reporting --outcome OUTCOME 2>/dev/null || true

If this session surfaced a durable pattern, pitfall, or user preference that would save 5+ minutes next time (not obvious, not a transient error), also log it:

"$_AK/bin/analyst-kit-learn" add '{"skill":"reporting","type":"pitfall|pattern|preference","ticker":"<optional>","insight":"<one line>","confidence":7,"ts":"<iso8601 utc>"}'