hero_slides

AI-powered slide generation. Generates PNG slide images from markdown using Gemini, exports PDFs, and exposes every AI workflow as a direct CLI command.

Components

Binary	Role
hero_slides	CLI tool — all commands documented here
hero_slides_server	Background RPC server — holds the collection registry, manages generation queues
hero_slides_admin	Web admin UI — browse decks, trigger generation, inspect slides

---

Deck structure

my_deck/
├── .slides                     ← marker file (identifies this directory as a deck)
├── theme.md                    ← visual theme description
├── intent.md                   ← one intent entry per slide (optional)
├── instructions.md             ← AI agent / deck-level instructions (optional)
├── 01_intro.md                 ← slide content files (lowercase, underscores)
├── 02_overview.md
├── metadata.toml               ← SHA-256 change-detection hashes + source image refs
├── slides.pdf                  ← assembled PDF (written by pdf export)
├── output/
│   ├── 01_intro.png            ← generated slide images
│   ├── 02_overview.png
│   └── .versions/
│       ├── 01_intro/
│       │   ├── v001.png
│       │   └── v002.png
│       └── 02_overview/
│           └── v001.png
└── content/
    └── background/             ← AI background context
        ├── company/            ← named folder (selectable via --context)
        │   └── overview.md
        └── market/
            └── report.md

---

Addressing — collection/deck/slide

All commands use a UNC-style address. Names are lowercase identifiers (letters, digits, underscores — no hyphens, no uppercase).

Format	Meaning
collection/deck	A deck within a registered collection
collection/deck/slide	A specific slide (no .md extension)

Examples:

myslides/quarterly_review
myslides/quarterly_review/03_market

Collections are registered with --scan and stored in heroDb. The CLI resolves every address through the registry and gives a clear error if the collection or deck is not found.

---

Service lifecycle

# Start the server + admin UI (registers with hero_proc)
hero_slides --start

# Stop both processes
hero_slides --stop

# Register a collection (works while server is running or directly via heroDb)
hero_slides --scan myslides=/data/presentations

# List registered collections
hero_slides collections

The server must be running (or heroDb must be reachable) for collection registration and address resolution to work.

---

Background context (--context)

Many commands accept --context — a comma-separated list of folder names under content/background/. The AI receives the text from those folders as context.

--context company,market       # include two specific folders
                               # (omit to use all background folders)

---

generate — AI image generation

Generate all slides in a deck

hero_slides generate deck myslides/quarterly_review
hero_slides generate deck myslides/quarterly_review --force

Generates a PNG for every slide that has changed since the last run. --force regenerates everything.

Generate a single slide

hero_slides generate slide myslides/quarterly_review/03_market
hero_slides generate slide myslides/quarterly_review/03_market --force
hero_slides generate slide myslides/quarterly_review/03_market --context company,market

---

content — slide text content

Create new slide content

Generate markdown for a new slide from a title and intent description.

hero_slides content create myslides/quarterly_review \
  --title "Market Overview" \
  --intent "Summarise the key market trends for Q1 2025"

# With a specific slide to pull source images from
hero_slides content create myslides/quarterly_review/03_market \
  --title "Market Overview" \
  --intent "Summarise key Q1 market trends" \
  --context market \
  --out 03_market.md

Output goes to stdout unless --out FILE is given.

Instruct — rewrite existing slide content

Reads the existing .md, applies the AI instruction, writes the result back (or to --out).

hero_slides content instruct myslides/quarterly_review/03_market \
  --instruction "Make it more concise — maximum 4 bullet points"

hero_slides content instruct myslides/quarterly_review/03_market \
  --instruction "Add a competitor comparison table" \
  --context market \
  --out 03_market_draft.md

---

theme — deck visual theme

Extract theme from an image or PDF

Analyzes the visual design and writes theme.md to the deck.

hero_slides theme extract myslides/quarterly_review --from brand_guidelines.pdf
hero_slides theme extract myslides/quarterly_review --from screenshot.png

Supports PNG, JPEG, WebP, GIF, and PDF. Detection is by file extension.

Instruct — modify the existing theme.md

Reads theme.md, applies the instruction, writes back in place.

hero_slides theme instruct myslides/quarterly_review \
  --instruction "Switch to dark mode with blue accents"

hero_slides theme instruct myslides/quarterly_review \
  --instruction "Add a typography section" \
  --context company

---

instructions — deck instructions.md

Reads instructions.md, applies the instruction via AI, writes back. Creates the file if it does not exist.

hero_slides instructions instruct myslides/quarterly_review \
  --instruction "Add a rule: every slide must start with a clear headline question"

hero_slides instructions instruct myslides/quarterly_review \
  --instruction "Rewrite for investor audience, not technical team" \
  --context company

---

pdf — PDF assembly and extraction

Export all slide PNGs to a PDF

hero_slides pdf export myslides/quarterly_review
# Writes: <deck>/slides.pdf

Extract a PDF from the background folder to markdown

Uses AI to produce a companion .md alongside the PDF.

# PDF is in content/background/market/
hero_slides pdf extract myslides/quarterly_review \
  --folder market \
  --file industry_report_2025.pdf

# PDF is in the deck root (omit --folder)
hero_slides pdf extract myslides/quarterly_review \
  --file source_doc.pdf

---

wizard — AI slide planning pass

The wizard proposes or rewrites slide content in bulk from a high-level intent.

Propose new slides

hero_slides wizard myslides/quarterly_review \
  --intent "Create a 5-slide investor pitch: market, product, traction, team, ask" \
  --count 5

hero_slides wizard myslides/quarterly_review \
  --intent "Propose 3 slides for the competitive landscape section" \
  --count 3 \
  --context market \
  --out suggestions.json

Rewrite existing slides

hero_slides wizard myslides/quarterly_review \
  --intent "Tighten the narrative — one clear takeaway per slide" \
  --slides 01_intro,02_market,03_product

Output is a JSON array printed to stdout (or written to --out):

[
  { "slide_name": "01_intro", "content": "..." },
  { "slide_name": "02_market", "content": "..." }
]

---

info — deck summary

hero_slides info myslides/quarterly_review

Prints slide count, generated count, first slide name, theme status, intent status, PDF status, background presence.

---

slides list

hero_slides slides list myslides/quarterly_review

Lists all .md slide files. Marks slides that have a generated PNG with ✓.

---

background list

hero_slides background list myslides/quarterly_review

Lists all folders in content/background/ with file counts.

---

Environment variables

Variable	Purpose
HERO_SOCKET_DIR	Override socket directory (default: $HOME/hero/var/sockets)
RUST_LOG	Log level filter (default: warn, hero_slides* modules at info)

AI credentials are managed by the hero_proc secret store and resolved automatically via AiClient::get().

---

hero_slides_server — --info requirements

lab validates every hero_* binary by running --info after a successful build. The server output must satisfy:

{
  "name": "hero_slides_server",
  "version": "<semver>",
  "description": "<non-empty string>",
  "kind": {
    "server":  true,
    "admin":   false,
    "web":     false,
    "cli":     false,
    "cmdline": false
  },
  "interfaces": {
    "openrpc": true,
    "sse":     true,
    "rest":    false,
    "webui":   false
  },
  "sockets": [
    {
      "type":     "rpc",
      "path":     "<non-empty path>",
      "protocol": "openrpc"
    }
  ],
  "tcp": []
}

Required fields checked by lab:

• name, version, description — non-empty strings
• kind — object with boolean keys: server, admin, web, cli, cmdline
• interfaces — object with boolean keys: openrpc, sse, rest, webui
• sockets — array; each entry must have non-empty string fields type, path, protocol
• tcp — array; each entry must have address (string), port (number), purpose (string)

Extra fields (e.g. dependencies) are ignored by the validator.

---