Imported from AO-Cyber-Systems/eden-press (AGENTS.md). Install upstream with npx skills add AO-Cyber-Systems/eden-press. Copyright stays with the author.

AGENTS.md — eden-press agent interface

eden-press is a pure-Go CLI: it converts a Marp-compatible Markdown deck to static output with no browser, no Node, and no JavaScript runtime. This document is the scriptable contract an AI agent (or any non-interactive caller) needs to inspect and export a deck without reading the Go source.

The whole surface described here is CI-enforced chromedp-free: scripts/check-no-chromedp.sh scans ./cmd/...'s transitive dependency closure (alongside ./press/..., ./chase/..., ./profiles/..., ./bind/...) and fails the build if chromedp ever appears in it.

Formats (--format)

--format is a persistent flag on every convert invocation (the bare eden-press <in.md> default, and the explicit convert subcommand). It selects what emitFormat emits; --output/-o (registered on convert and watch) selects the destination — a file path, or stdout when unset.

# Inspect a deck's structure (defaults to stdout; pipe into jq/etc.):
eden-press deck.md --format json | jq '.model.outline'

# Export an editable PowerPoint deck, zero Chrome:
eden-press deck.md -o slides.pptx --format pptx

# Export via the explicit "convert" subcommand (identical to the bare default):
eden-press convert deck.md --output slides.pptx --format pptx

PNG/PDF export is intentionally not part of this binary (it requires Chrome); that lives in the separate eden-press-export binary — see "Export (separate binary)" below. preview/watch/serve behavior is unaffected by --format beyond what's documented above.

Export (separate binary)

Raster (PDF/PNG) export lives in cmd/eden-press-export — a SEPARATE, Chrome-requiring binary, not a flag on eden-press. The core eden-press binary documented above stays browserless (html/json/pptx) always; raster export is an opt-in binary you install/build separately. This split is CI-enforced: scripts/check-no-chromedp.sh proves eden-press's own dependency closure never contains chromedp, and separately proves eden-press-export is the ONE cmd/... binary whose closure does.

# PDF: one file, written to -o (defaults to <stem>.pdf for a file input
# with no -o; stdin input requires -o -- there is no filename to derive a
# default from):
eden-press-export deck.md -o out.pdf --format pdf

# PNG: one file per slide, written into the -o DIRECTORY (created if
# missing; "" -> CWD) as <stem>-001.png, <stem>-002.png, ...; -o may also be
# a printf `%03d`-style pattern (e.g. -o "frame-%03d.png") for full control
# over the per-slide filename:
eden-press-export deck.md -o out-dir/ --format png

Chrome discovery (in order): --browser-path <path> > the CHROME_PATH environment variable > PATH auto-detection of a known Chrome/Chromium binary. If none resolves, the command exits 3 with a remedy message naming both --browser-path and CHROME_PATH — see convert/EXPORT.md for the full discovery chain and the pinned-chromedp/headless-shell fallback.

# Copy-paste examples:
eden-press-export deck.md -o out.pdf --format pdf && echo ok || echo "failed: exit $?"
eden-press-export deck.md -o slides/ --format png && echo ok || echo "failed: exit $?"

# No Chrome available -- exits 3 with a remedy, never a stack trace:
eden-press-export deck.md -o out.pdf --format pdf
# stderr: no Chrome/Chromium found for raster export: ...
#   supply one with --browser-path <path> or the CHROME_PATH env var,
#   or install a pinned chromedp/headless-shell (see convert/EXPORT.md)
# exit code: 3

JSON envelope schema (--format json)

{
  "html": "<section>...</section>",
  "css": "/* packed theme CSS */",
  "model": {
    "meta": { "directives": { "theme": "default", "marp": "true" } },
    "sections": [
      {
        "id": 1,
        "attrs": { "class": "lead" },
        "notes": ["speaker note text"],
        "blocks": [
          { "kind": "heading", "text": "Title", "level": 1 },
          { "kind": "paragraph", "text": "Body text." },
          { "kind": "code", "text": "fmt.Println(1)", "language": "go" },
          { "kind": "math", "text": "E=mc^2", "display": true },
          { "kind": "list", "ordered": false, "items": [
            { "text": "item one", "level": 0 }
          ] },
          { "kind": "table",
            "headers": ["Metric", "Q3"],
            "rows": [["p95 latency", "550ms"]],
            "aligns": ["left", "right"] },
          { "kind": "image", "src": "chart.png", "text": "alt text", "title": "Quarterly" },
          { "kind": "quote", "text": "a blockquote" }
        ]
      }
    ],
    "outline": [
      { "sectionId": 1, "level": 1, "text": "Title", "slug": "title" }
    ]
  },
  "comments": ["speaker note text"],
  "meta": { "directives": { "theme": "default", "marp": "true" } }
}

Field notes an agent must get right:

• A code block's raw source, and a math block's raw TeX, both live in block.text — there are no source or tex keys. language accompanies a code block (e.g. "go", "" for an unlabeled fence); display accompanies a math block (true for $$...$$, false for $...$).
• meta (top-level) is a convenience alias identical to model.meta — read either.
• Every field is omitempty: absent when unused (e.g. a paragraph block has no language/display/items; a section with no speaker notes omits notes entirely). Do not assume a key is always present — check for it.
• A table block's payload lives in headers + rows + aligns, never in text. rows is an array of row arrays of cell strings; aligns is one entry per column, each "left"/"right"/"center" or "" when the column declared no alignment. Ragged rows are reported as authored — GFM pads at render time, but the model reports what was written. An image block puts its destination in src, its alt text in text, and its optional ![alt](src "title") third argument in title. A quote block carries its concatenated text in text (multi-paragraph quotes are joined by a blank line; nested quotes are flattened in document order).
• model is exactly chase/model.Document's own schema-v3 JSON shape, reused verbatim; cmd/eden-press itself never imports that package directly (it re-marshals the already-typed value through any), but the wire shape is stable and versioned independently of Marp/goldmark churn.

Exit codes

Error envelope (--format json, on failure)

When --format json is active, any failure prints a JSON object to stderr (never stdout) instead of a plain-text message, and the process exits with the matching code above:

{ "error": { "code": 1, "message": "resolveInput: read file \"deck.md\": open deck.md: no such file or directory" } }

For --format html/--format pptx, a failure prints the same message as plain text to stderr (no JSON wrapping) with the same exit-code contract.

Copy-paste examples

# Pull just the outline (table of contents) as JSON:
eden-press deck.md --format json | jq '.model.outline'

# Export an editable pptx and check the exit code:
eden-press deck.md -o slides.pptx --format pptx && echo ok || echo "failed: exit $?"

# Script-friendly failure handling — write JSON to a file, check exit status:
eden-press deck.md --format json > out.json || echo "failed: exit $?"

# A bad path fails fast with a parseable error, never a stack trace:
eden-press /no/such.md --format json
# stderr: {"error":{"code":1,"message":"resolveInput: ..."}}
# exit code: 1

No browser, no Node, no JavaScript runtime is ever invoked by any of the above — html and json are pure press/, and pptx is pure stdlib OOXML (convert/pptx). This is a CI-enforced invariant (scripts/check-no-chromedp.sh covers ./cmd/...), not just a convention.