# Epic CLI — The Complete Manual

`java-epic-cli.jar` · PDF preflight and print-production toolkit · Maven artifact `com.datahandler.epicenter.cli:epicenter.cli`

This is the index of the full reference for everything the tool does and how to drive each
feature. The content lives in per-chapter files under [`manual/`](manual/) so a reader — human
or agent — can load exactly the chapter they need instead of one 900-line document. It goes
deeper than `AGENT_GUIDE.md` (the condensed field manual for agents) and deeper than the
built-in help (`--help`, `--help=<topic>`), pulling together the option surfaces, the JSON
contracts, the semantics that only live in the code, and the operational knowledge collected
while building it. Where this manual and the jar's built-in help disagree, the jar you are
actually running wins — run `--help=<topic>` to confirm flag details for your build.

**Shortcuts:** driving the jar from an agent/MCP for the imagegen→print path? Start with
[`MANUAL_MCP.md`](MANUAL_MCP.md) (one page). Just need commands to copy? Chapter
[14 — Recipes](manual/14-recipes.md).

## Chapters

| # | Chapter | What's in it |
|---|---|---|
| 1 | [What Epic CLI is](manual/01-what-epic-cli-is.md) | Purpose, the PHP consumers that depend on it, the processing domains at a glance. |
| 2 | [Invocation fundamentals](manual/02-invocation-fundamentals.md) | Java runtime + JDK constraints (no JDK 21), mode grammar and chaining, stdout/stderr/exit-code contract, the built-in help system, S3 paths everywhere. |
| 3 | [Configuration: AWS, MySQL, fonts](manual/03-configuration-aws-mysql-fonts.md) | `aws.ini`/`mysql.ini` CWD resolution, the `--fonts-dir` → `./fonts` → `fonts/legacy` chain and its precedence trap. |
| 4 | [Report modes](manual/04-report-modes.md) | JSON contracts for `--preflight` (master intake), `--list-spot-colors`, `--list-process-colors`, `--thin-line` overlays. |
| 5 | [Transform modes](manual/05-transform-modes.md) | Rotate/mirror/resize/create, `--split` one-PDF-per-page, `--swap-spot-colors` plate renaming that survives Illustrator. |
| 6 | [`--imposition`](manual/06-imposition.md) | Sheet layout from a JSON plan: full plan reference, `pdf_documents` (incl. `recolor`), exit codes. |
| 7 | [`--compile`](manual/07-compile.md) | Artwork Designer layer JSON → separated PDF: request schema, layer types, `live_text`, `variables_xml`, `ai_private` native-Illustrator editing, result contract. |
| 8 | [`--vectorize` / `--rvp`](manual/08-vectorize-rvp.md) | Raster → flat-spot-color vector: how the pipeline thinks, every option (palette, trace, weld, curve fit), the report `objects[]` contract. |
| 9 | [`--extract-objects`](manual/09-extract-objects.md) | Exact vector lift into editable objects; `--with-text` `texts[]`/`stories[]` live-text reporting and `story_index` tagging. |
| 10 | [`--simplify-curves`](manual/10-simplify-curves.md) | Illustrator-style path simplification: algorithm, tolerances, corner survival. |
| 11 | [`--backers`](manual/11-backers.md) | Production backer plates: the plate-expression DSL, geometry/smoothing, the Illustrator AI-graft layer. |
| 12 | [`--derivatives`](manual/12-derivatives.md) | Master derivative batches: package format, binding semantics (JSX v8 parity), engines/flavors, partial-batch result contract. |
| 13 | [`--spool`](manual/13-spool.md) | Print spooling to Windows printers (`--pdf`/`--raw`), stdout contract. |
| 14 | [Recipes](manual/14-recipes.md) | Copy-paste command lines for the common jobs, intake to press. |
| 15 | [Troubleshooting and landmines](manual/15-troubleshooting-and-landmines.md) | Symptom → cause: sparse reports = stale jar, JDK 21 fragmentation, fonts CWD trap, and friends. |
| 16 | [For developers](manual/16-for-developers.md) | Build rules (`mvn verify`, clean tree), repo layout, contract-stability rules. |

## Reading guide

- **Intaking a customer file?** 4 → 15.
- **Making imagegen/raster art print-ready?** 8 → 10 → 4.2. (Or just [`MANUAL_MCP.md`](MANUAL_MCP.md).)
- **Building against the JSON contracts (heatapplied/arc)?** 2 (exit codes) → the chapter for your mode. All report shapes are additive-only contracts.
- **Something looks wrong?** 15 first — especially if a report looks *emptier* than expected.