json2pptx

Structured presentations from structured data. Define what your slides mean -- json2pptx handles what they look like.

Choose your path

json2pptx has two audiences. Jump straight to yours:

I want to…	Go to
Author a deck semantically — write compact YAML/JSON describing slide intent and content	Semantic Quick Start
Run the raw CLI or Go library — generate decks from compiled PresentationInput JSON in a shell, script, or program	Install → Raw JSON CLI Quick Start
Integrate via MCP — let an AI agent plan, build, validate, and repair decks	Claude Code Integration → MCP Server

New here? The Philosophy and How It Works sections give the mental model first.

Philosophy

PowerPoint is a visual tool. You drag boxes, pick fonts, nudge alignment. This works for one-off decks, but it falls apart when presentations need to be generated programmatically, updated from data, or produced at scale.

json2pptx takes the same approach that LaTeX brought to documents: separate content from presentation. In LaTeX, you declare \section{Introduction} and the typesetter handles margins, fonts, and spacing. In json2pptx, you declare "type": "chart", "chart_value": {...} -- or "pattern": {"name": "kpi-3up", ...} -- and the engine handles layout selection, SVG rendering, shape geometry, contrast correction, and placement.

This is what you mean is what you get for presentations:

• You say "bar chart with Q1-Q4 revenue" -- json2pptx picks the layout, renders the chart as SVG, and places it
• You say "three KPIs across the top" -- a named pattern (kpi-3up) expands into a typed shape grid with the right rhythm
• You say "SWOT analysis" -- the engine generates the diagram with proper quadrant geometry and colors from your theme
• You say "compose a hero stat over a row of icons" -- the compose envelope merges two patterns into one slide

The input is a JSON document. The output is a .pptx file that opens in PowerPoint, Keynote, or Google Slides -- no post-editing required. Templates control the visual identity; your JSON controls the content and structure. Generation is deterministic: same JSON + template + binary version -> byte-identical PPTX.

How It Works

The 3 Inputs

JSON (content) + Template (.pptx)  -->  json2pptx  -->  Presentation (.pptx)

1. Template -- A real PowerPoint file with pre-designed slide layouts, colors, and fonts (e.g., midnight-blue.pptx). You never edit this directly.
2. Semantic spec or raw JSON -- Agents usually write a compact semantic deck spec (kind: kpi_snapshot, kind: decision, etc.). Power users can still write the compiled raw PresentationInput JSON directly.
3. The binary -- json2pptx semantic render compiles semantic specs to raw PresentationInput; json2pptx generate renders raw input. Both paths use the same template analysis, validation, fit checks, contrast correction, and output validator.

Slides, Layouts, and Placeholders

Each slide has a layout (picked by slide_type) and content items targeting placeholders:

{
  "slide_type": "content",
  "content": [
    {"placeholder_id": "title", "type": "text", "text_value": "Revenue"},
    {"placeholder_id": "body",  "type": "chart", "chart_value": {"type": "bar", "data": {"Q1": 12, "Q2": 14}}}
  ]
}

• slide_type -- semantic hint that picks the right layout: title, content, chart, section, two-column, comparison, image, blank, diagram
• placeholder_id -- canonical slot name: title, subtitle, body, body_2. Portable across all templates.
• type -- what kind of content: text, bullets, body_and_bullets, body_and_lead, bullet_groups, table, chart, diagram, image

You don't need to know internal layout IDs. The system resolves them automatically -- the same JSON works with any template.

Three Authoring Levels

Level	When to use	What you write
Semantic deck spec	Default for agents and most new decks	YAML/JSON slide kinds such as kpi_snapshot, chart_insight, comparison, roadmap, decision
Raw placeholders and named patterns	Debugging, advanced automation, or compiled output edits	content[] items plus pattern: {name, values, style} envelopes
Raw shape grid	Custom geometry the semantic compiler and patterns do not cover	shape_grid: {columns, rows, cells} with explicit shapes/tables/icons

You can also combine patterns on one slide with a compose envelope (e.g. a hero stat above a row of icons).

Two Rendering Paths

Path	What	How	Result
Native OOXML shapes	SWOT, Porter's, BMC, pyramids, value chains, panel layouts, KPI dashboards, heatmaps and more	Generated as real PowerPoint shapes	Editable, crisp at any zoom
SVG-rendered visuals	19 chart types and the remaining diagram families	Rendered by the svggen/ module and embedded as native SVG with a PNG fallback (default; --chart-png forces PNG)	High-quality visuals in PowerPoint/Keynote

Diagnostics & Self-Repair

Every generation (and every dry-run) emits structured fit findings (code, severity, action, fix, JSON Pointer path). An agent can call the repair_slide MCP tool with a list of typed fixes (reduce_text, swap_layout, split_at_row, swap_pattern, reshape_grid, set_pattern_style, replace_color, use_semantic_color, ...) to patch a single slide rather than regenerating the whole deck. See docs/FIT_FINDINGS.md and docs/REPAIR_LOOP.md.

Output Validation Guarantee

generate_presentation (MCP) and json2pptx generate (CLI) default to strict output validation: every successful response implies the generated .pptx passed the full OPC + OOXML validator (internal/pptx.ValidateOutputFile) with zero blocking findings. This is the "zero needs repair" contract — PowerPoint and Keynote will not show the "we found a problem with some content" prompt on a strict-mode success. When validation fails, the response is an error envelope {summary, findings[], next_tool_call: {tool: "repair_slide", args_template}} carrying OPC_* / OOXML_* findings with per-finding scope (source / template / generator). See the raw authoring path for the response protocol; use describe_finding for the current code catalog.

Features

• JSON-to-PPTX conversion -- structured slide definitions become polished PowerPoint files
• Bundled templates -- forest-green, midnight-blue, modern-template and warm-coral receive full cross-template test coverage, alongside abstract, blue-corporate, business-template, modern and modern-yellow. A local gitignored templates/p-style.pptx joins cross-template tests when present but is not bundled. Call list_templates (or json2pptx skill-info) for the live list; any .pptx works as a template
• Template-aware layout selection -- picks the right layout based on your content; synthesizes missing standard layouts
• 19 chart types -- bar, grouped_bar, stacked_bar, line, small_multiples, area, stacked_area, pie, donut, scatter, bubble, radar, waterfall, funnel, gauge, treemap, mekko_chart, combo_chart, butterfly_chart
• 21 diagram types -- SWOT, timeline, process flow, pyramid, venn, org chart, Gantt, KPI dashboard, heatmap, fishbone, PESTEL, Porter's Five Forces, value chain, Business Model Canvas, nine box talent, house diagram, panel layout, icon columns/rows, stat cards, matrix 2x2
• Named patterns -- agenda, arch-stack, before-after, bmc-canvas, card-grid, comparison-2col, icon-row, kpi-2up...kpi-6up (parametric), matrix-2x2, process-flow, pull-quote, pyramid, roadmap-phased, stat-hero, swimlane, timeline-horizontal and many more; json2pptx patterns list (or MCP list_patterns) prints the live registry
• Pattern composition (compose) -- 2-4 patterns merged into one slide with vertical/horizontal layout
• Shape grid engine -- consulting-style custom layouts with preset geometries, row/column grids, cell spanning, authoritative bounds
• Tables with auto-pagination (split_slide) -- header rows repeat across continuation slides
• Inline formatting -- <b>bold</b>, <i>italic</i>, <u>underline</u>, <sup>superscript</sup>, <sub>subscript</sub> in text and bullets
• Constrained vs free authoring (design_mode) -- constrained refuses raw hex and absolute font sizes to keep decks on-brand; free unlocks them
• Accent rotation strategies (accent_strategy) -- primary, rotate, or section-keyed
• Style defaults -- deck-level defaults.table_style / defaults.cell_style, swap-only semantics
• Deck structure -- structure block with sections, auto-agenda, cover/closing slides
• Persistent chrome -- footer, header, page numbers, with skip rules
• Theme overrides -- per-deck color and font customization
• Speaker notes, sources, and alt-text -- per-slide metadata, accessibility-aware
• Slide transitions and build animations -- fade, push, wipe, cover, cut; bullet-by-bullet reveal
• Contrast enforcement -- WCAG AA auto-fix on layout backgrounds; warn-only on user-specified shape colors
• Text fit checking (strict_fit: off|warn|strict) -- structured findings; refuse on overflow when strict
• Fit findings + repair loop -- typed diagnostics with JSON Pointer paths; repair_slide patches one slide at a time
• Deterministic visual scoring -- score_deck runs full generation and grades the output 0-100 with a composition axis
• Deck rhythm analysis -- analyze_deck_rhythm reports visual motifs, accent heaviness and content occupancy with measured/estimated/unknown evidence
• Deck planning -- plan_deck turns a brief into a structured slide outline with rhythm rules
• PPTX read-back -- read_presentation extracts placeholders/shapes/tables from an existing PPTX without LibreOffice
• HTTP API -- REST endpoints for programmatic generation
• Semantic compiler -- compact YAML/JSON deck specs compile to raw PresentationInput, render through the existing engine, and return diagnostics mapped back to semantic paths
• MCP server -- Model Context Protocol tools (get_capabilities().mcp_tools_available lists them) for AI-assisted deck creation, validation, planning, recommendation, scoring, and repair, including semantic deck-spec tools and the one-call make_deck cold-start facade
• Claude Code skills -- integrated skills for AI-driven deck generation, template usage, visual QA, and standalone diagram rendering

Installation

Which method should I use?

json2pptx ships several install paths. Pick one by what you have and your platform:

You have	Platform	Recommended command	What it does
Source checkout (cloned repo)	macOS / Linux / WSL2	make install	Builds every binary from source, installs to ~/.local/bin, sets up skills + MCP. Default for source checkouts.
Source checkout, want install options	macOS / Linux / WSL2	./install.sh	Same build + install (same staged skills) as make install, but adds --prefix, --skip-skill, --skip-mcp, --skip-templates, --skip-build flags.
Source checkout	Windows (PowerShell)	.\install.ps1	Builds from source, installs to %LOCALAPPDATA%\json2pptx\bin. Default for Windows source checkouts. Needs Go; no Make/bash.
Prebuilt release archive	macOS / Linux / WSL2	./install.sh (inside the archive)	Copies the bundled binary + templates into place — no Go or Make required.
Prebuilt release archive	Windows	.\install.ps1 (inside the archive)	Copies the bundled binary + templates into place — no Go required.
Any platform, just want the HTTP API	Docker	docker-compose up --build	Runs the API in a container; no local toolchain.

Why are there two scripts named install.sh? The install.sh / install.ps1 in a source checkout compile from source. A release archive ships a different installer — scripts/install-dist.sh / scripts/install-dist.ps1, staged into the archive as install.sh / install.ps1 — that only copies the prebuilt binary and templates and never needs a Go toolchain. Run whichever script is in the tree you downloaded; you do not invoke scripts/install-dist.sh directly.

Binary only? Add --skip-skill --skip-mcp (Unix) or -SkipSkill -SkipMcp (Windows) to any command above to install just the CLI without Claude Code skills or MCP config.

Prerequisites

• Go 1.26.10+ -- download
• Git -- for cloning and version info
• Make -- build automation (see platform notes below)
• librsvg or resvg -- for SVG-to-PNG chart/diagram rendering (optional but recommended)
• LibreOffice + ImageMagick -- only required for pptx2jpg, render_slide_image, and render_deck_thumbnails

macOS

brew install go
brew install librsvg            # recommended for charts/diagrams
brew install --cask libreoffice # only needed for slide-image rendering
brew install imagemagick

git clone https://github.com/sebahrens/json2pptx.git
cd json2pptx
make install

Binaries are installed to ~/.local/bin/. Add to your PATH if needed:

export PATH="$HOME/.local/bin:$PATH"

Linux (including WSL2)

sudo apt update
sudo apt install -y golang-go make librsvg2-bin
# Optional: sudo apt install -y libreoffice imagemagick

git clone https://github.com/sebahrens/json2pptx.git
cd json2pptx
make install

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc
source ~/.bashrc

WSL2 note: Generated .pptx files are accessible from Windows at \\wsl$\<distro>\home\<user>\... or via the output directory you specify.

Windows (native PowerShell)

Install Go using the Windows installer, then:

git clone https://github.com/sebahrens/json2pptx.git
cd json2pptx
.\install.ps1

This builds all binaries, installs them to %LOCALAPPDATA%\json2pptx\bin\, copies templates, installs Claude Code skills, and configures the MCP server. Options:

.\install.ps1 -Prefix "C:\tools"     # Custom install prefix
.\install.ps1 -SkipSkill             # Skip Claude Code skill
.\install.ps1 -SkipMcp               # Skip MCP config
.\install.ps1 -SkipTemplates         # Skip template files

Quick Install Script (macOS / Linux / WSL2)

./install.sh                    # Build + install to ~/.local
./install.sh --prefix /usr/local
./install.sh --skip-skill       # Binary only, no Claude Code skills

Docker (all platforms)

cp .env.example .env
docker-compose up --build

The HTTP API is available at http://localhost:8080.

docker run -d \
  -p 8080:8080 \
  -v ./templates:/app/templates:ro \
  -v ./output:/app/output:rw \
  ghcr.io/sebahrens/json2pptx:main

:main is rebuilt on every push to main. Release tags (:X.Y.Z, :X.Y) and :latest are published only when a vX.Y.Z git tag is pushed (see CHANGELOG.md); until the first release is tagged, :main is the only moving tag.

Quick Start

Semantic Usage (Recommended for Agents)

Write compact YAML that describes slide intent and content; json2pptx chooses patterns, raw layouts, and safe defaults, then renders through the same engine as raw JSON:

meta:
  title: Q2 Business Review
  subtitle: Momentum improving, execution risk remains
  archetype: qbr
  audience: board
  template: midnight-blue

slides:
  - kind: title
    title: Q2 Business Review
    subtitle: Momentum improving, execution risk remains
  - kind: kpi_snapshot
    title: Quarter at a glance
    takeaway: Growth recovered, but margin remains below target.
    kpis:
      - { value: "$12.4M", label: "Revenue" }
      - { value: "61%", label: "Gross margin" }
  - kind: decision
    title: Approve EMEA sales capacity
    takeaway: Add enterprise sales capacity now to convert EMEA pipeline.
    recommendation: Add four enterprise AEs in Q3.
    options:
      - label: Hold current coverage
        detail: Accept slower EMEA conversion.
      - label: Add four enterprise AEs
        detail: Hire in Q3 to convert the EMEA pipeline.
        recommended: true

Deck-level intent lives under meta; each slide is a kind-tagged payload whose remaining fields are that kind's content. Use list_slide_kinds / json2pptx semantic schema for the per-kind fields, and examples/semantic/qbr.yaml for a fuller, test-verified spec.

json2pptx semantic validate --spec qbr.yaml
json2pptx semantic compile --spec qbr.yaml --out qbr.compiled.json
json2pptx semantic render --spec qbr.yaml --out qbr.pptx
json2pptx semantic explain --spec qbr.yaml
json2pptx semantic schema

Semantic diagnostics use paths like slides[1].kpis[0].label; when a raw fit or output finding comes from generated JSON, the semantic compiler maps it back through its source map and only includes the raw JSON pointer as fallback evidence.

Raw JSON CLI Usage

# Generate a deck
json2pptx generate -json examples/varied-pitch-deck.json -output ./output

# Validate without generating
json2pptx validate examples/varied-pitch-deck.json

# Dry-run: show layout selections + fit findings without writing a file
json2pptx generate -dry-run -json examples/varied-pitch-deck.json

# Read JSON from stdin, write structured result to file
cat examples/varied-pitch-deck.json | json2pptx generate -json - -json-output-report result.json

# Override the template specified inside the JSON
json2pptx generate -json examples/varied-pitch-deck.json -template forest-green -output ./output

# Override the deck's design_mode for one run (allow raw hex colors / absolute sizes)
json2pptx generate --design-mode=free -json examples/business-model-canvas.json -output ./output

# Use your own external template
mkdir my-templates && cp /path/to/my-corporate-theme.pptx my-templates/
json2pptx generate \
  -json examples/varied-pitch-deck.json \
  -template my-corporate-theme \
  -templates-dir ./my-templates \
  -output ./output

Example Decks

The repo ships dozens of example decks under examples/ (plus a diagrams/ subdirectory of diagram decks and semantic/ YAML specs). The most useful ones to learn from, in order:

Example	What it shows
examples/basic-deck.json	Hello-world: title, content, bullets, plain placeholders
examples/charts.json	Cleanest reference for chart_value syntax across chart types
examples/shape-grid-panels.json	Easiest entry point to raw shape_grid
examples/patterns-smoke.json	Compact tour of named patterns, callouts, and cell_overrides
examples/varied-pitch-deck.json	Realistic 13-slide pitch -- 10 patterns plus a compose slide combining stat-hero and kpi-3up
examples/sovereign-ai-strategy.json	Flagship 25-slide consulting deck (charts + grids + sources + notes)
examples/business-model-canvas.json	Raw shape_grid BMC with merged rows/columns
examples/consulting-layouts.json	Chevron flows, 2x2 matrices, takeaways, side-by-side
examples/split-slide-vendor-matrix.json	split_slide table pagination with repeated headers
examples/visual-maturity-stress-test.json	Comprehensive grid regression coverage
examples/contrast-fixer-test.json	Contrast autofix on dark/accent fills
examples/full-showcase.json	Mixed traditional slides + several chart types

HTTP API

json2pptx serve                  # default port 8080
json2pptx serve --port 3000

curl -X POST http://localhost:8080/api/v1/convert \
  -H "Content-Type: application/json" \
  -d '{
    "template": "midnight-blue",
    "slides": [
      {"type": "title",   "title": "My Presentation", "content": {"body": "Welcome"}},
      {"type": "content", "title": "Key Points",      "content": {"bullets": ["First point", "Second point"]}}
    ]
  }'

The HTTP convert endpoint takes a simplified text/bullet slide shape (type, title, content.body / content.bullets), not the raw PresentationInput JSON used by the CLI and MCP. See docs/api/README.md.

Claude Code Integration

json2pptx ships with Claude Code skills and an MCP server that let an AI agent plan, create, validate, score, and repair presentations from natural language prompts.

What Gets Installed

make install (or ./install.sh / .\install.ps1) sets up everything. All installers stage the same skill set — every directory under skills/, a generate-deck/references/repository/ snapshot of the docs the skills link to, and links rewritten to resolve inside ~/.claude/skills:

Component	Location	Purpose
MCP server registration	Claude Code user scope (~/.claude.json, via claude mcp add --scope user)	Connects Claude Code to json2pptx tools
generate-deck skill	~/.claude/skills/generate-deck/	4-phase deck workflow (Plan -> Vary -> Render -> Repair)
template-deck skill	~/.claude/skills/template-deck/	Template selection, layouts, and placeholder reference
slide-visual-qa skill	~/.claude/skills/slide-visual-qa/	Composition review + per-slide screenshot inspection
render-diagram skill	~/.claude/skills/render-diagram/	Standalone SVG/PNG charts and diagrams via svggen-mcp

The installers register the MCP server with claude mcp add --scope user json2pptx -- <bin> mcp --templates-dir ~/.json2pptx/templates --output ./output when the claude CLI is on PATH; otherwise they print that command for you to run.

Skip skill installation with --skip-skill (shell) or -SkipSkill (PowerShell).

The skills and that snapshot are embedded in the binary, and every installer runs the same command: json2pptx skill install [--dest DIR] writes the copy that matches the binary (default ~/.claude/skills, or $JSON2PPTX_SKILL_DIR) and ends every Markdown file in a version stamp (<!-- json2pptx-skill schema_version: X.Y.Z -->). json2pptx skill status checks each installed file: missing, unstamped, stamped by an older binary, or (examples, images) different from the shipped bytes. get-started, capabilities, semantic and generate print one line on stderr when the installed skill is older than the binary (they read only the version in the install manifest, generate-deck/.json2pptx-skill.json; a file deleted or edited afterwards shows in skill status) — once per mismatch, remembered in generate-deck/.json2pptx-skill-warned (or the user cache directory when the skill directory is read-only); JSON2PPTX_SKILL_CHECK=off silences it. json2pptx skill cli-map [--tools deckspec|core|all] [--format json|md] prints the MCP-tool → CLI-command table, generated from the tool classifications.

MCP Server

Start manually for debugging:

json2pptx mcp --templates-dir ~/.json2pptx/templates --output ./output

By default the server runs the deckspec tool profile: tools/list advertises only the DeckSpec authoring path (output-schema-free, with the DeckSpec outline in place of the closed per-kind schema). --tools core (alias raw) adds the raw-JSON path; --tools all (or JSON2PPTX_MCP_TOOLS=all) lists the full catalogue below except the folded aliases (recommend_pattern, render_slide_image, repair_slides_batch, get_chart_capabilities, get_diagram_capabilities). Hidden tools stay callable by name. Run go test ./cmd/json2pptx -run 'ToolProfileBudget' -v for current tool counts and wire bytes.

The installer registers this automatically via claude mcp add --scope user. The fastest way to learn the workflow at runtime is the get_started tool: it returns the recommended single-call fast path plus the ordered manual sequence it composes, scoped to brief / revise / validate-only. Each tool carries classification metadata in get_capabilities (kind, phase, cli_counterpart, mcp_only_reason, primitive_alternatives) so agents can pick the right tool without prose-parsing descriptions. The tables below are grouped by the same phase taxonomy get_capabilities reports.

Most MCP tools have a 1:1 CLI counterpart so you can drive the same workflows from a shell; the MCP-only tools below have no direct subcommand (the CLI workaround for each is printed by json2pptx help).

Cold-start fast path — the workflow facades (kind: workflow_facade) that collapse a whole chain into one call:

Tool	Purpose	CLI
make_deck	ONE call from a natural-language outline to a DRAFT, auto-repaired PPTX skeleton (chains plan_deck → expand patterns → auto_repair). Optional wireframe aid, not the recommended content-bearing path. Fills slides with pattern exemplar placeholder content, so the response reports content_status: "exemplar_skeleton" / publishable: false — replace the content and run visual QA before shipping.	MCP-only
auto_repair	Server-side convergence loop (generate → inspect → repair) against a configurable quality gate.	MCP-only

Discovery / introspection (phase: discovery, read-only)

Tool	Purpose	CLI
get_started	Recommended fast path + ordered manual sequence for a task	get-started
get_capabilities	Schema version, tool inventory + classification, deprecations, feature flags, vocabularies	capabilities
list_deck_archetypes	Semantic deck archetypes with default rhythm policies and examples	semantic explain / semantic schema
list_slide_kinds	Semantic slide-kind catalogue with compact examples	semantic schema
get_input_schema	Authoritative JSON Schema for PresentationInput with digest-based caching	input-schema
get_data_format_hints	Full chart/diagram data-shape hints (with digest for caching)	data-format-hints
list_templates	Discover bundled/external templates, layouts, palette, canonical taxonomy	skill-info
get_chart_capabilities	Per-chart limits and label strategy (folded alias: list_templates fields:"full")	capabilities
get_diagram_capabilities	Per-diagram limits and field reference (folded alias: list_templates fields:"full")	capabilities
get_shape_catalog	Preset geometries grouped by use case	shape-catalog
resolve_theme	Resolve theme colors and fonts for a template	resolve-theme
list_icons	Bundled icon names by set	icons
preview_icon	Render a single icon spec to SVG + PNG	preview-icon
list_patterns	Catalog of named patterns grouped by category	patterns list
show_pattern	Pattern contract: use_when, not_when, schema, version	patterns show
table_density_guide	Table density tiers, hard limits, multiline guidance	tables
list_template_settings	List template-side named table/cell styles	template-settings list
examine_template	Deep read-only template capability report (canonical roles, bounds, findings)	examine-template
describe_finding	Resolve a finding code to summary, severity, remediation steps	describe-finding

Plan (phase: plan)

Tool	Purpose	CLI
validate_deck_spec	Validate semantic YAML/JSON and return semantic-path diagnostics	semantic validate
compile_deck_spec	Compile semantic YAML/JSON to raw PresentationInput; full raw JSON is opt-in	semantic compile
explain_deck_spec	Explain archetype, rhythm, density, and pattern/layout choices without rendering	semantic explain
plan_deck	Turn a brief into an ordered slide outline with rhythm rules (template-aware)	plan-deck
recommend_visual	Unified router across placeholder layouts, patterns, charts, diagrams, raw grids	recommend-visual
recommend_pattern	Rank named patterns for a slide intent (folded alias of recommend_visual)	recommend-pattern
validate_pattern	Check pattern values and content fit without returning the expanded grid	patterns validate
expand_pattern	Expand a pattern into a full shape_grid	patterns expand
expand_patterns	Batch-expand N patterns under one template load	MCP-only

Vary (phase: vary)

Tool	Purpose	CLI
analyze_deck_rhythm	Pattern repetition, accent balance, density variance, composition score	analyze-rhythm
score_candidates	Rank candidate slide JSONs for one slot without rendering	score-candidates

Render (phase: render)

Tool	Purpose	CLI
render_deck_spec	Compile and render a semantic deck spec; returns PPTX path, diagnostics, deterministic_ready, and publishable (false until current all-slide visual approval)	semantic render
validate_input	Schema + static checks (+ optional fit_report), no render	validate
preview_presentation_plan	Resolve layouts/placeholders/findings without rendering	preview
preview_slide_wireframe	Annotated per-slide wireframe (SVG + PNG) without LibreOffice	preview-wireframe
validate_presentation_output	Validate a generated PPTX for structural + OOXML correctness	validate-output
generate_presentation	Render a PPTX from JSON; optional fit_report, strict_fit, strict_unknown_keys	generate
make_deck	Cold-start facade (see fast path above)	MCP-only

Repair (phase: repair)

Tool	Purpose	CLI
repair_slide	Apply targeted fixes to one slide without regenerating the deck	repair
repair_slides_batch	Apply fixes to multiple slides in one call (folded alias: one repair_slide call per slide)	MCP-only
propose_repairs	Translate fit/visual-QA findings into ranked repair_slide directives	MCP-only
apply_deck_patch	Pure deck-JSON transform: bounded structural ops (insert/remove/move/replace)	MCP-only
auto_repair	Server-side convergence loop (see fast path above)	MCP-only
inspect_slide_images	Vision/heuristic visual QA of rendered slides with pre-mapped fixes	inspect
submit_visual_review	Record a host/manual all-slide visual review verdict as quality evidence (validated against the current PPTX revision)	MCP-only
render_slide_image	Render one PPTX slide to PNG (folded alias: render_deck_thumbnails slide_indices)	render-slide
render_slide_image_from_json	Render one slide directly from its JSON (requires LibreOffice + ImageMagick)	render-slide-from-json
render_deck_thumbnails	Render all slides to low-res thumbnails (requires LibreOffice + ImageMagick)	render-thumbnails
purge_render_cache	Reclaim the on-disk render cache (renders bound it automatically; this is the deliberate reclaim)	purge-render-cache
read_presentation	Extract placeholders/shapes/tables/notes from an existing PPTX (no LibreOffice)	read
export_deck	Retain a PDF or Markdown speaker-notes handout from an existing PPTX	export
audit_palette	Render to PNG and report ΔE between chart pics and adjacent solid-filled shapes	audit-palette
score_deck	Deterministic 0-100 score with composition axis and a quality gate	score

Settings (phase: settings, gated by JSON2PPTX_ALLOW_SETTINGS_WRITE=1)

Tool	Purpose	CLI
register_template_setting	Persist a named table/cell style	template-settings register
delete_template_setting	Delete a named style	template-settings delete

Example Workflow

Default for content-bearing decks: author real content as a DeckSpec; call list_slide_kinds → validate_deck_spec → render_deck_spec. Revise a DeckSpec with deck_id + patch on validate_deck_spec / render_deck_spec. Use the raw PresentationInput path only when the spec cannot express a needed feature or the source deck is already raw; on that path, inspect chosen patterns with show_pattern / expand_pattern, then call validate_input (with fit_report: true) before generate_presentation. make_deck creates an exemplar skeleton, never a publishable deck. On either path, render every slide of the final revision and inspect its image before approval.

Recommended content-bearing path. Write a compact DeckSpec with the user's real copy, validate it, render it, and inspect the resulting slides:

You:     "Build a board presentation about our Q1 results.
          Include revenue charts, team growth, and strategic priorities.
          Use midnight-blue template, 10 slides."

Claude:  [calls list_slide_kinds -> authors a DeckSpec with the real Q1 figures
          -> validate_deck_spec -> render_deck_spec -> render_deck_thumbnails
          -> inspects every slide and revises any findings]

Raw path (manual primitives). Use this when DeckSpec cannot express a needed feature or the source deck is already raw JSON; this is the sequence get_started returns for task=brief:

Claude:  [calls plan_deck -> structured slide outline]
         [presents outline for approval]
         [generates JSON using card grids for KPIs, bar charts for revenue]
         [calls validate_input -> reads back fit findings]
         [calls score_deck and analyze_deck_rhythm -> spots monotony]
         [calls repair_slide on the two flagged slides]
         [calls generate_presentation -> output/q1-board.pptx]

You:     "Stacked bar for revenue. Add a 2x2 matrix for priorities."

Claude:  [calls repair_slide twice -> patches only the affected slides]
         [regenerates]

JSON Input Format

The authoritative input schema is generated from the Go input structs and published via get_input_schema (MCP) or json2pptx input-schema (CLI) — that is the single source of truth for field names, types, enums, and required-vs-optional flags. For a worked-example walkthrough of every shape (top-level config, slide and content items, shape_grid, compose, charts, diagrams, and named patterns), read docs/INPUT_FORMAT.md; for the named-pattern authoring contract see docs/PATTERNS.md.

A deck is a top-level object with a template and a slides array. Each slide is plain placeholder content, a raw shape_grid, a named pattern, or a compose envelope:

{
  "template": "warm-coral",
  "output_filename": "Q1_Review.pptx",
  "slides": [
    {
      "slide_type": "content",
      "content": [
        {"placeholder_id": "title", "type": "text", "text_value": "Revenue Overview"},
        {"placeholder_id": "body",  "type": "bullets",
         "bullets_value": ["Revenue up <b>25%</b> YoY", "Margins improved to 68%"]}
      ]
    }
  ]
}

The content types, chart types, diagram types, and named patterns are summarized under Features, and each is documented with per-field examples in docs/INPUT_FORMAT.md. Run json2pptx input-schema (or call get_input_schema) for the exhaustive, always-current field reference rather than relying on a copy here.

Templates

Template	Description
forest-green	Clean green corporate theme
midnight-blue	Professional dark blue theme
modern-template	Modern layout with contemporary styling
warm-coral	Warm coral accent theme

Each template provides standard layouts: Title Slide, One Content, Two Content, Section Divider, Closing, and Blank. Missing standard layouts are synthesized at load time.

If templates/p-style.pptx exists locally, the test suite includes it in the template corpus without tracking or embedding it.

json2pptx skill-info --mode=list
json2pptx skill-info --mode=full --template=midnight-blue
json2pptx template-check templates/midnight-blue.pptx     # conformance against docs/TEMPLATE_SPEC.md

Every file shipped under templates/ is gated by internal/template/conformance_corpus_test.go, which runs as part of go test ./... and asserts zero FAIL and zero WARN. See CONTRIBUTING.md → "Adding a Template" for the procedure and the sha256-keyed allow-list mechanism for legacy known-exceptions.

Which template doc should I read?

You want to…	Canonical doc
Use a template from JSON — placeholder IDs, layout tags, layout→slide-type mapping	skills/template-deck/TEMPLATE_GUIDE.md
Author or validate a template — mandatory layouts, theme requirements, conformance checks	docs/TEMPLATE_SPEC.md

Creating a Custom Template

Any .pptx file can serve as a template. Open PowerPoint (or Keynote, Google Slides, LibreOffice Impress), design your slides in Slide Master view, save as .pptx. json2pptx analyzes the layouts at runtime and maps your JSON content to the right placeholders.

Required Layouts (4 minimum)

Layout	Purpose	Placeholders	Maps to slide_type
Title Slide	Opening slide	Title + Subtitle	title
Content	Main content slides	Title + Body	content, chart, diagram
Section Divider	Section breaks	Title (+ optional Body)	section
Closing	Final slide	Title + Subtitle	blank (closing tag)

Layouts are detected by placeholder structure, not by name. A "Two Content" layout and a "Blank" layout are synthesized automatically when missing.

Theme and Colors

json2pptx extracts your template's theme colors (accent1-accent6, dk1, dk2, lt1, lt2) and uses them for native diagram shapes, chart palettes, shape grid fills (via scheme references like "fill": "accent1"), and automatic text contrast correction.

mkdir my-templates && cp my-corporate-theme.pptx my-templates/

json2pptx generate -json examples/basic-deck.json -template my-corporate-theme -templates-dir my-templates
json2pptx validate-template my-templates/my-corporate-theme.pptx
json2pptx skill-info --mode=full --template=my-corporate-theme --templates-dir=my-templates

Tips

• Design in 16:9 aspect ratio
• Edit in Slide Master view, not on individual slides
• Use standard PowerPoint placeholder types (Title, Body, Subtitle), not plain text boxes
• Test classification with json2pptx skill-info --mode=full

CLI

The json2pptx binary is the primary tool: batch converter, HTTP API server, and MCP server.

Subcommands

Run json2pptx help for the authoritative list, or json2pptx <command> -h for per-command flags. A handful of MCP tools have no direct subcommand (e.g. make_deck, auto_repair, apply_deck_patch, repair_slides_batch, expand_patterns, propose_repairs) — json2pptx help prints the CLI workaround for each under "MCP-only tools".

Every command follows one convention (json2pptx help prints it):

• the primary input is the first argument — json2pptx validate deck.json, json2pptx generate deck.json, json2pptx semantic render deck.yaml, json2pptx render-thumbnails deck.pptx (the older --json / --spec / --pptx <file> spellings still work);
• --out <path> names the output file or directory (--output, --output-dir, --out-dir still work);
• --format json|text selects the output shape where a command has both (--json still works);
• -h / --help print to stdout and exit 0, and flags may come before or after the arguments;
• the result — including the path of anything written — is printed on stdout; logs go to stderr, warnings and errors only unless --verbose (or JSON2PPTX_LOG_LEVEL=info) is set;
• a command that answers in JSON and fails always prints one JSON document on stdout: its own failure result, or the finding envelope {subcommand, ok: false, findings: [{code, message}]} for any other error (a missing file, an undefined flag). Slide positions in messages are 1-based when written "slide N" and 0-based when written "index N" or slides[N].

Command	Description
generate	Convert JSON input to PPTX (default if subcommand omitted)
semantic	List slide kinds (semantic kinds [<kind>]), validate, compile, render, explain, and print schema for semantic deck specs
templates	List template names, one line each (under 2 KB)
read	Read PPTX and output extracted content as JSON
export	Export an existing PPTX to PDF or a speaker-notes handout
validate	Validate JSON input without generating (see docs/FIT_FINDINGS.md for -fit-report)
preflight	Run every static check on a deck (stage-based, emits the finding envelope)
validate-output	Check generated PPTX for OOXML correctness
validate-template	Check template compatibility
template-check	Check template conformance against docs/TEMPLATE_SPEC.md
examine-template	Emit a full template capability report (visual + XML + canonical roles)
patterns	List, show, validate, and expand named patterns
icons	Search icons (icons search <term>) or list them (icons list [--names])
preview-icon	Render a single icon spec to SVG + PNG preview
tables	Table style guide and density reference
skill	Install/check bundled agent skills and print the MCP-to-CLI map (install, status, cli-map)
skill-info	Show template capabilities for Claude Code skill integration
capabilities	Show schema version, tools (with classification), features, and vocabularies
get-started	Print the recommended fast path + manual sequence for a task (get-started [brief|revise|validate-only]), with the CLI command for each step
describe-finding	Print the agent-facing description for a single finding code
input-schema	Print the JSON input schema
resolve-theme	Resolve theme colors and fonts for a template
recommend-pattern	Recommend patterns matching an intent
recommend-visual	Recommend visual approaches for a slide intent
plan-deck	Plan a deck outline from a brief
preview	Preview generation plan without rendering
preview-wireframe	Render a slide-plan wireframe (PNG) before generating
preview-patterns	Render every named pattern on each template into a local PNG gallery (the generated slide for its example values)
repair	Apply targeted fixes to a single slide
score	Score a JSON deck spec for visual quality (deterministic)
score-candidates	Rank candidate slides for one slot without rendering
inspect	Run vision-based visual QA on rendered slide images
analyze-rhythm	Analyze deck visual rhythm and pattern repetition
render-slide	Render a single slide to a PNG file (--slide-index N or --slide-id ID, --out slide.png; requires LibreOffice + ImageMagick)
render-slide-from-json	Render one slide directly from JSON to a PNG file (no full deck render)
render-thumbnails	Write every slide as slide-<index>.png into --out and print a manifest (paths, sha256, sizes); --slides 1,costs narrows by index or slide id; --known-hashes skips slides whose content_hash you already hold; --base64 for the old JSON envelope
purge-render-cache	Reclaim the on-disk render cache and stale LibreOffice profile directories
audit-palette	Render PPTX to PNG and report ΔE between chart pics and adjacent solid-filled shapes
template-settings	Manage named styles (list/register/delete)
data-format-hints	Show data format hints for chart/diagram types
shape-catalog	List available preset geometries
serve	Start HTTP API server
mcp	Start MCP server over stdio
version	Show version, commit, and build information

Generate Flags

json2pptx generate -h is authoritative. Fit findings come from json2pptx validate -fit-report (a validate flag, not a generate flag). generate prints a one-line JSON result on stdout (success, output_path, slide_count, content_hash, warnings); --json-output-report <file|-> writes the full report instead. A chart or diagram that fails to render makes generate exit non-zero and leaves no deck, at every --strict-fit level.

Flag	Default	Description
-json	(required)	Path to JSON input file, or - for stdin
-template		Template name (without .pptx)
-templates-dir	./templates	Directory containing templates
-output	./output	Output directory for generated PPTX files (or a .pptx file path, e.g. /tmp/deck.pptx)
-json-output-report		Path for the JSON result report (success, review findings, warnings, quality score) in headless mode
-json-output		DEPRECATED: alias for -json-output-report
-dry-run / -n	false	Validate input and show layout selections without generating
-strict-fit	warn	Text-fit checking mode: off, warn, or strict (refuse on overflow)
-output-validation	strict	Post-generation PPTX validation: off, warn, or strict (fail on blocking findings)
-design-mode		Override the deck's design_mode: constrained or free; empty keeps the JSON setting
-partial	false	Skip failing slides instead of aborting the whole deck
-strict-unknown-keys	false	Treat unknown/misspelled JSON keys as blocking errors instead of warnings
-chart-png	false	DEPRECATED: use PNG instead of native SVG for charts
-verbose	false	Enable verbose output
-config		Path to config file

Companion Tools

See cmd/README.md for the full command index — purpose, a usage example, and the authoritative -h pointer for every binary.

Binary	Purpose
pptx2jpg	Convert PPTX to JPG via LibreOffice (libreoffice or soffice, incl. the macOS app bundle) + pdftoppm (preferred) or ImageMagick
mktemplate	Template authoring helper
templatecaps	Template capabilities inspector
debugcolors	Theme color introspector
validatepptx	Standalone PPTX validator
testkit (alias testrand)	Test toolbox: random deck generation (fuzz harness), visual stress decks, PPTX validation, and visual QA

HTTP API

Method	Path	Description
GET	/api/v1/health	Lightweight liveness check with version info
GET	/api/v1/ready	Check readable templates, writable output, and render dependencies; returns 200 when ready or 503 otherwise
GET	/api/v1/capabilities	Machine-readable HTTP feature boundary (supported fields, MCP-only features, endpoint list)
GET	/api/v1/templates	List available templates
GET	/api/v1/templates/{name}	Template details (layouts, colors, fonts)
GET	/api/v1/slide-types	List supported slide types
POST	/api/v1/convert	Convert JSON slides to PPTX
GET	/api/v1/download/{filename}	Download generated file (expires after 1 hour by default)
GET	/api/v1/thumbnails/{filename}	Render a server-generated PPTX to base64 PNG thumbnails; accepts density, max_slides, and zero-based slide_indices, never arbitrary paths or URLs
GET	/api/v1/patterns	List available named patterns
GET	/api/v1/patterns/{name}	Pattern details and schema
POST	/api/v1/patterns/{name}/validate	Validate input against a pattern's schema
POST	/api/v1/patterns/{name}/expand	Expand a pattern into a shape grid
GET	/api/v1/semantic/schema	Semantic deck-spec JSON Schema
GET	/api/v1/semantic/kinds	Discover semantic kinds, contracts, examples, and budgets; optional kinds, fields, and registered template filters
POST	/api/v1/semantic/validate	Validate semantic YAML/JSON and return semantic diagnostics
POST	/api/v1/semantic/compile	Compile semantic specs to raw PresentationInput JSON
POST	/api/v1/semantic/render	Compile and render semantic specs to PPTX

See docs/api/README.md for complete API documentation.

Convert Request Fields

Field	Required	Description
template	Yes	Template name (without .pptx)
slides	Yes	Array of slide definitions
options.output_format	No	"file" or "base64" (default: "file")
options.svg_scale	No	SVG render scale factor, 0.5-10.0 (default: 2.0)
options.exclude_template_slides	No	Exclude template's built-in slides from output

Convert Response

{
  "success": true,
  "file_url": "/api/v1/download/abc123.pptx",
  "expires_at": "2026-01-17T12:00:00Z",
  "stats": {"slide_count": 10, "processing_time_ms": 1500, "warnings": []}
}

Configuration

Set environment variables directly or via a .env file. See .env.example for the complete reference.

Variable	Default	Description
PORT	8080	HTTP server port
JSON2PPTX_BIND	127.0.0.1	HTTP bind address (Docker explicitly uses 0.0.0.0)
JSON2PPTX_API_TOKEN		Optional bearer token for HTTP requests; environment-only
JSON2PPTX_CORS_ALLOWED_ORIGINS		Comma-separated exact browser origins; CORS disabled when empty, explicit * allows any origin
TEMPLATES_DIR	./templates	Template directory
OUTPUT_DIR	./output	Output directory
LOG_LEVEL	info	debug, info, warn, error
TEMPLATE_VALIDATION_MODE	soft	strict or soft
TEMP_FILE_MAX_AGE	3600	Max age for temp files before cleanup (seconds)
TEMP_CLEANUP_INTERVAL	300	Temp file cleanup interval (seconds)
SVG_STRATEGY	png	png, emf, or native
SVG_SCALE	2.0	Scale factor for PNG conversion
SVG_NATIVE_COMPATIBILITY	warn	warn, fallback, strict, ignore
SVG_PNG_CONVERTER	auto	auto, rsvg-convert, or resvg
ALLOWED_IMAGE_PATHS		Comma-separated local image roots. When set, serve, mcp, generate and semantic render refuse image / background paths outside them (URL downloads stay allowed, and so does the sample screenshot a recommend_visual callout recipe points at — that one file, while it holds the bytes the binary draws). Empty = any path (traversal still rejected). The MCP base_dir argument bounds only relative asset paths; set this to confine absolute ones
JSON2PPTX_ALLOW_SETTINGS_WRITE	0	Set to 1 to enable register_template_setting / delete_template_setting
PPROF_PORT / PPROF_BIND		pprof endpoint

The HTTP API (serve) binds to localhost by default; use --bind or JSON2PPTX_BIND to expose it. Setting JSON2PPTX_API_TOKEN requires Authorization: Bearer <token> on every route except GET/HEAD /api/v1/health, including readiness, downloads, thumbnails, and semantic discovery. An empty token permits unauthenticated access. Allowed CORS preflights need no token; actual requests still require it. Configure browser origins with JSON2PPTX_CORS_ALLOWED_ORIGINS or server.cors_allowed_origins. Use a reverse proxy for TLS and rate limiting when exposing the API remotely; see HTTP access and browser clients for details.

SVG Conversion Strategies

Strategy	Description	Requirements	Compatibility
png	Convert SVG to PNG (default)	rsvg-convert or resvg	Universal
emf	Convert SVG to EMF vector format	Inkscape	PowerPoint 2010+
native	Embed SVG directly with PNG fallback	rsvg-convert or resvg for fallback	PowerPoint 2016+

The strategy governs every svggen chart / diagram: placeholder charts and the diagram cells that patterns and shape_grid embed (e.g. the chart-insights-split chart panel). Under png / emf those are embedded as PNG only, at SVG_SCALE and capped at MAX_PNG_WIDTH. Small shape_grid icons stay native SVG with a PNG fallback.

brew install librsvg          # macOS
apt install librsvg2-bin      # Ubuntu/Debian

Config File

server:
  port: 8080
  read_timeout: 30s     # request headers always time out after 10s, even with read_timeout: 0
  write_timeout: 150s   # raised to at least 2m30s so /convert (2m timeout) can answer with a 504
  max_slides_per_request: 500   # /convert rejects larger decks with 400, counted before AND after auto-pagination
  max_concurrent_converts: 4    # extra concurrent /convert requests get 503 RATE_LIMITED
templates:
  dir: ./templates
  cache_dir: ./cache/templates
storage:
  output_dir: ./output
  file_retention: 1h   # must be positive; the cleaner removes only generated downloads (<32 hex>.pptx)
svg:
  strategy: png
  scale: 2.0
  native_compatibility: warn
  preferred_png_converter: auto

Architecture

cmd/
  json2pptx/        Main CLI + HTTP API + MCP server (the CLI's own --help lists its subcommands; get_capabilities().mcp_tools_available lists the MCP tools and marks the core profile)
  pptx2jpg/         PPTX to image conversion via LibreOffice
  mktemplate/       Template authoring helper
  debugcolors/      Theme color debugging tool
  templatecaps/     Template capabilities inspector
  validatepptx/     Standalone PPTX validator
  testrand/         Test toolbox (builds testkit + testrand: fuzz, visual, validate, qa)
internal/
  api/              HTTP API handlers and routing
  config/           Configuration loading
  diagnostics/      Structured diagnostic envelopes
  generator/        Core PPTX generation engine, contrast, shapes
  jsonschema/       JSON Schema validation
  layout/           Layout selection (heuristic scoring)
  layoutpreview/    Generation plan previewing
  pagination/       Slide pagination and content splitting
  patterns/         Named shape grid pattern registry (`json2pptx patterns list`)
  pipeline/         Generation pipeline orchestration
  pptx/             Low-level OOXML manipulation
  pptxread/         PPTX read-back (for read_presentation)
  render/           Slide-image rendering
  resource/         Embedded resource handling
  safeyaml/         Safe YAML parsing
  shapegrid/        Shape grid layout engine (flex-like rows, authoritative bounds)
  slidepath/        JSON Pointer path helpers
  template/         PPTX template analysis and layout classification
  templatesettings/ Template-side named style sidecars
  textfit/          Text fitting and overflow handling
  testrand/         Random test data generation
  testutil/         Test helpers
  types/            Shared data types and input schema
  utils/            Utilities
  visualqa/         Visual QA agent integration (deterministic + screenshot)
svggen/             SVG chart and diagram generation (separate Go module)
templates/          Built-in PPTX templates (4)
examples/           Example JSON input decks (+ diagrams/ and semantic/ subdirectories)
docs/               Specs: PATTERNS, FIT_FINDINGS, REPAIR_LOOP, INPUT_FORMAT,
                    STYLE_DEFAULTS, TEMPLATE_SPEC, VISUAL_CRITERIA, ...
skills/             Claude Code skills (3)

Pipeline Flow

JSON Input + Template PPTX
        |
        v
  Parse JSON Input + apply deck defaults --> Slides[], Template, ThemeOverride, Defaults, Structure
        |
        v
  Expand structure (sections, auto-agenda, cover/closing) --> flat slide list
        |
        v
  Validate (schema, unknown keys, design_mode rules)
        |
        v
  Analyze Template --> Layouts[], Placeholders[], ThemeColors; synthesize missing layouts
        |
        v
  Resolve patterns/compose --> shape_grid; resolve virtual layout bounds
        |
        v
  Select Layouts and map portable placeholders
        |
        v
  Generate PPTX                                        --> Populated PPTX file
    |-- Charts (svggen)        --> SVG -> PNG/EMF/native
    |-- Diagrams (svggen + native) --> some intercepted as native OOXML shapes
    |-- Tables                  --> with auto-pagination via split_slide
    |-- Shape Grid              --> custom shape layout
    |-- Images                  --> embedded
    '-- Contrast + Text Fit     --> auto-fix or report findings
        |
        v
  Result + FitFindings + ContrastSwaps + ContentHash

Development

Prerequisites

• Go 1.26.10 or later
• golangci-lint (for linting)
• librsvg or resvg (for SVG-to-PNG conversion)

Building

make                 # Build all binaries
make build-race      # Build with race detector
make build-cross     # Cross-compile for all platforms

Testing

make test            # Run all tests
make test-race       # Tests with race detector
make test-cover      # Tests with coverage report
make check           # Build + test + vet
make ci              # Full CI pipeline (fmt + lint + test + vulncheck)

# svggen is a separate Go module
cd svggen && go test ./...
cd svggen && golangci-lint run ./...

Pre-Commit Checklist

1. golangci-lint run ./...
2. cd svggen && golangci-lint run ./...
3. go test ./...
4. cd svggen && go test ./...
5. go build ./cmd/json2pptx

Integration Tests

./tests/integration/run_pptx_tests.sh    # PPTX generation tests
./tests/integration/run_svg_tests.sh     # SVG diagram tests

Distribution

make dist-linux      # Linux amd64 tar.gz
make dist-windows    # Windows amd64 tar.gz
make release         # All platforms (requires clean tree)

Documentation

• get_input_schema (MCP) / json2pptx input-schema (CLI) -- canonical JSON Schema for PresentationInput
• list_deck_archetypes / list_slide_kinds / json2pptx semantic schema -- canonical semantic deck-spec discovery
• docs/SEMANTIC_COMPILER.md -- semantic deck-spec model, compiler stages, source maps, and target architecture
• docs/wiki/README.md -- wiki for agents building consulting-grade decks: the MCP journey, deck archetypes, storyline, slide design rules, the layout catalog, visual vocabulary, the slide-estate / segments guide, split and complex layouts, and playbooks for pitches and deals, risk consulting, technology and data, and risk assurance (each with a rendered example deck under examples/semantic/playbooks/)
• docs/INPUT_FORMAT.md -- tutorial with worked examples
• docs/PATTERNS.md -- named-pattern authoring guide
• docs/FIT_FINDINGS.md -- fit findings catalog and action semantics
• docs/REPAIR_LOOP.md -- structured repair workflow
• docs/STYLE_DEFAULTS.md -- defaults block semantics
• skills/template-deck/TEMPLATE_GUIDE.md -- template usage reference (placeholder IDs, layout tags, layout→slide-type mapping)
• docs/TEMPLATE_SPEC.md -- template authoring & validation spec (mandatory layouts, theme requirements, conformance)
• docs/VISUAL_CRITERIA.md -- composition scoring criteria
• docs/SCHEMA_CHANGELOG.md -- schema/version history
• docs/PATH_GRAMMAR.md -- JSON Pointer path grammar for fit findings
• docs/api/README.md -- HTTP API reference

Contributing

See CONTRIBUTING.md for development setup, code style guidelines, testing requirements, and the pull request process.

Note: Building and testing json2pptx requires no issue-tracker setup. The .beads/ directory you may see is optional, local-only Beads workflow state (gitignored, not present in a fresh clone) — see Beads Workflow (Optional) for when and how to opt in.

License

Licensed under the Apache License, Version 2.0. You may use, modify, and distribute this software freely, including for commercial purposes, provided you include the LICENSE and NOTICE files as required by the license. See LICENSE for the full terms.

Commercial licensing is available for organizations that need different terms (white-label use without attribution, warranty, support/SLA). Contact [email protected].

Third-party license information is documented in LICENSE-THIRD-PARTY.md.