# Epic CLI — MCP cheat sheet (imagegen → print-ready path)

Condensed contract reference for driving `java-epic-cli.jar` from an agent/MCP
wrapper. Authoritative detail lives in `MANUAL.md`; this sheet covers only what
the raster-art-to-print pipeline needs. All JSON contracts are additive-only.

## Invocation & environment

```
java -Xmx2g -jar java-epic-cli.jar <mode + options>
```

- **JVM**: Temurin/OpenJDK 8, 11, 17, or 23. **Never a JDK 21-line JVM** —
  `--extract-objects` output fragments ~55× there (JDK 21 `Area` regression).
- **CWD is load-bearing**: `aws.ini` / `mysql.ini` resolve from the working
  directory, and a `fonts/` directory in CWD silently repoints font resolution.
  Pin the exec CWD deliberately; fleet convention is `/datahandler/scripts`.
- **Heap**: `-Xmx2g` covers typical imagegen sizes; large rasters scale with
  pixel count.
- **Paths**: `<source>`/`[output]` accept local paths or `s3://bucket/key`.

## Exit codes & error surface

- `0` success. Nonzero = the run **failed**, even if a partial output file
  exists — surface the exit code *and* stderr to the calling model.
- Errors are one-line, prefixed, on stderr (e.g. `not liftable: ...`).
- Report modes print exactly one JSON document on stdout and never modify the
  source. Transform modes with `[output]` omitted overwrite `<source>` in place
  — always pass an explicit output from an MCP.

## The core call: raster → spot-color vector PDF

```
--vectorize --input=art.png --output=art.pdf [options]
```

Traces an anti-aliased raster (exactly what imagegen produces) into a PDF 1.5
where every shape is a flat spot ink — no raster data carried through. Prints a
JSON envelope on stdout: `page`, `spots[]` (name + CMYK), `objects[]`.

Flags that matter most, in order of impact:

| Flag | Default | Use |
|---|---|---|
| `--max-colors=N` | 8 | **Set to the known ink count.** Single best artifact killer. |
| `--colors=SPEC` | discover | Snap to an explicit palette when the job's inks are known. |
| `--dpi=N` | 300 | Assertion about the input raster (sizes the page); not a resample. |
| `--paper=auto\|none` | `none` | `auto` leaves near-white unprinted. Default keeps white — it may be a real plate. |
| `--simplify-curves[=PT]` | off | Illustrator-style smooth cubic outlines (tolerance 0.35pt). Recommended for imagegen. |
| `--simplify=PX` | 0.75 | Polyline vertex shedding (pre-curve). |
| `--min-color-share=F` | 0.005 | Raise to drop trace inks from noisy gradients. |
| `--no-weld` | welding on | Leave off: butting inks are delivered as true kissing-fit seams (trapping is the printer's job). |
| `--no-ai-private` | AI data on | Outputs carry native Illustrator private data by default, so the PDF opens in Illustrator as a native AI doc (real swatches, editable paths). Leave on unless a downstream parser chokes on PieceInfo. |

Anti-aliasing is collapsed into the core inks automatically; `--ink-threshold`
(default 0.45) keeps hairlines alive. Defaults were tuned for AA'd input —
start with just `--max-colors` + `--simplify-curves` and only reach deeper if
the JSON's `spots[]` shows phantom inks.

## Inspection & QA calls

```
--list-spot-colors  art.pdf     # spot inks + CMYK equivalents + utilization
--list-process-colors art.pdf   # CMYK channel usage
--preflight art.pdf             # full production-readiness JSON report
--thin-line=P:N art.pdf         # min stroke/gap width check + overlay PNGs
```

Verify a vectorize round-trip by running `--list-spot-colors` on the output
and diffing against the intended palette.

## Editing calls

```
--swap-spot-colors=SPEC in.pdf out.pdf   # rename inks / replace CMYK fallbacks
--resize=WxH in.pdf out.pdf              # inches; 8.5x or x11 = proportional
--mirror in.pdf out.pdf                  # reverse/film printing
--rotate90|--rotate180|--rotate270
--extract-objects=in.pdf --report=r.json # lift a vector PDF into editable
                                         # objects (exact geometry, no trace);
                                         # add --object-gap=0.3 to split, and
                                         # --with-text for texts[]/stories[]
```

Transform modes chain in the order given in one invocation.

## Landmine summary

1. JDK 21 line — never.
2. CWD: ini resolution + `fonts/` precedence trap.
3. Omitted `[output]` = in-place overwrite.
4. Nonzero exit + stderr = failure regardless of files on disk.
5. A sparser-than-expected report (missing colors, empty thin-line data) means
   a broken/stale jar before it means a clean file — check jar md5 vs repo.
6. `--extract-objects` refuses rasters/gradients (`not liftable:`) unless the
   input is genuinely vector; imagegen output goes through `--vectorize`.

Questions or a file class that traces badly → route to cli-dev with the sample.