AI Output Runtime

AI Output Runtime

Emit AIO Markdown whenever you produce structured content for human consumption — reports, comparisons, conclusions, status panels, audit findings — not just when the user names AIO explicitly. Markdown carries the prose; schema-validated JSON blocks carry the structure; a safe runtime renders it all into a polished single-file HTML report. You never write HTML, CSS, or JavaScript.

Output Policy

Default to AIO blocks for these shapes:

• Conclusion / recommendation / verdict → aio:callout@1
• Comparison of options, vendors, or scenarios → aio:table@1 or aio:comparison@1
• Key metrics / status indicators → aio:metric-cards@1 (static) or aio:trend-card@1 (when change matters)
• Risk / finding / issue lists → aio:callout@1 items or aio:table@1
• Trend / proportion → aio:chart@1 · KPI attainment → aio:gauge@1 · conversion → aio:funnel@1 · P&L bridge → aio:waterfall@1 · 2D density → aio:heatmap@1 · 2×2 prioritization → aio:matrix@1 · chronology → aio:timeline@1 · follow-ups → aio:action-items@1 · per-unit state → aio:status-grid@1

Plain Markdown only when the reply is conversational Q&A, a code snippet / debugging help, or the user asked for plain prose. In chat/TTY surfaces that may not render AIO, still emit AIO for structured shapes — it reads as a JSON code block and renders perfectly when later piped through aio render.

Report skeleton for a structured business report: frontmatter (or report-header@1) → 1–2 framing sentences → trend-card@1 headline metrics → status-grid@1 if sub-units have separate state → detail blocks (chart / table / heatmap / funnel / waterfall / matrix) → timeline@1 for what happened → comparison@1 for decisions → action-items@1 → closing callout@1 verdict.

A good AIO report is prose + structured slots, not raw JSON walls: never emit a block without surrounding prose, and if you have more than two blocks in a row with no prose between them, restructure.

Emission economy (saves tokens; rendered output is identical)

• Emit block JSON compact: no indentation, no space after : or ,, at most one items[] / rows[] / series[] element per line — that last rule keeps raw JSON scannable on surfaces that show it. Formatting never survives JSON.parse.
• Prose carries the why — cause, decision, anomaly — never restate figures the adjacent block already shows.
• The runtime auto-inserts a collapsible Executive Summary card at the top, built from the FIRST aio:callout@1 in the document plus the first 4 metric/trend values. Never hand-write a summary section; make your first callout carry the report's takeaway instead. Disable with frontmatter summary: off.
• Omit every field the runtime defaults or derives: trend-card delta direction when it matches the sign of delta.value; gauge min / max / target at their defaults and tone unless overriding the auto tone; format:"number" anywhere (it is the default); heatmap tone:"accent"; matrix bounds at 0/10; funnel step/overall conversion % (auto-computed — don't put them in note); waterfall kind on start/up/down bars and value on explicit subtotal/end bars. Tones on status-grid / timeline / matrix items are data, not decoration — keep those.
• Pure data tables can use the CSV body (aio:table@1:csv, ~20–30% fewer bytes than minified JSON) when no title / subtitle / caption / filterable is needed. Prefer the JSON body when the rendering toolchain may predate v0.6.0 — older runtimes degrade :csv silently to a plain code block.

Hard Rules

• Info strings: aio:name@major (JSON body), plus aio:table@1:csv (CSV body, table only).
• JSON bodies must be valid JSON — no comments, no trailing commas.
• No HTML, CSS, JavaScript, iframes, style attributes, event handlers, template expressions, or custom components. No < or > inside AIO string fields.
• Components in scope — stable: table@1 / metric-cards@1 / callout@1; candidate: chart@1 / trend-card@1 / status-grid@1 / report-header@1 / timeline@1 / action-items@1 / comparison@1 / gauge@1 / funnel@1 / waterfall@1 / heatmap@1 / matrix@1. Never invent component names; content that fits nothing (diagrams, code diffs, …) stays plain Markdown.

Components

The stable trio, in exactly the emission style to imitate:

{"title":"Release health","items":[
{"label":"Recommendation","value":"Adopt","note":"Fits stable scope","tone":"good"},
{"label":"Blockers","value":"0","tone":"neutral"}]}

{"tone":"success","title":"Final recommendation","body":"Adopt AIO for structured reports.","items":["Ship v1 next sprint"]}

callout needs title plus body and/or items — body may be omitted when items is non-empty. tone: info / success / warning / danger.

{"title":"Options","columns":["Option","Benefit","Risk"],"rows":[
["Markdown","Readable","Weak interaction"],
["AIO","Validated structure","Requires runtime"]]}

CSV body for pure data tables — header row becomes columns; quote cells containing , or " (escape embedded quotes by doubling); unquoted true / false / number tokens are typed; raw newlines inside cells are forbidden:

Option,Score,Verdict
Markdown,7,Readable
"AIO, validated",9,Recommended

Frontmatter shortcut: a YAML frontmatter block (title / subtitle / period / author / status / data-as-of / classification / badges) at the very top of the document is automatically turned into an aio:report-header@1 — don't also write the block.

Candidate components — key reference

The CLI rejects any key not listed here (? = optional). For edge-case semantics read SKILL_DIR/specs/<name>-v1.md before emitting anything beyond this table.

format fields accept raw / number / percent / compact / currency:CCY (ISO 4217).

Rendering behavior worth knowing

• Numbers in number-bearing components are locale-formatted via Intl.NumberFormat from the document lang — with no format, numbers get grouped thousands separators (13,620, not 13620). Pass the right --lang (en / zh-CN / ja) so currency separators and decimal marks render correctly. Use format:"raw" only when you explicitly want no formatting.
• The visual system is business-grade out of the box — 1800px wide-screen shell, phone reflow for every component, sticky TOC, per-block CSV export, strict Light/Dark toggle. Nothing to configure.
• Fenced code blocks get dark chrome, a Copy button, and syntax highlighting automatically: json / bash / js / ts / python / yaml / diff are built in, 24 more languages (go, rust, java, sql, …) lazy-load from CDN. --inline-runtime artifacts stay offline-friendly — the CLI inlines every language module the markdown actually uses. Unknown languages fall back to plain monospace, never an error.

Local Tools

Validate, then render:

node SKILL_DIR/scripts/aio.mjs validate report.md
node SKILL_DIR/scripts/aio.mjs render report.md --lang zh-CN

By default the rendered HTML references the runtime via jsDelivr CDN, so the file is portable:

<script src="https://cdn.jsdelivr.net/gh/wxkingstar/ai-output-runtime@v0.6.0/assets/ai-output-runtime.js"></script>

Useful render flags:

• --inline-runtime — offline / file://-friendly artifact (runtime + used language modules inlined).
• --out <file.html> — output path (defaults next to the source).
• --theme dark — start in Dark (default is Light).
• --expire-hours 72 — sticky countdown banner for artifacts delivered as time-limited download links.
• --runtime <url|path> — custom CDN or local runtime override.

Prefer the CDN or --inline-runtime over copying SKILL_DIR/assets/ai-output-runtime.js by hand.