*Epic CLI Manual — [index](../MANUAL.md)*

# 16. For developers

- **Build with `mvn verify`, never `mvn package`.** The fat jar is assembled at `package`,
  but the root-level `java-epic-cli.jar` — the file PHP consumers actually invoke — is only
  refreshed by `post-build.sh`, bound to the `verify` phase. Stopping at `package` ships a
  stale jar silently.
- **Commit source before building. Never build from a dirty tree.** (The `ded7016` incident:
  a jar built from uncommitted source shipped features that later clean rebuilds silently
  dropped.)
- **Contract stability:** flag names/behavior, JSON field names/shapes, and exit codes never
  change without coordination — `php-heatapplied` and `php-driven-arc` parse them directly
  from `Colors.php`, `SheetRuns.php`, `Preflight.php`, and a dozen other call sites.
  Additive fields and warnings are safe; anything else needs the consumers in the loop
  first.
- **Engine parity:** the vendored PDFBox fork is the fleet engine. Gate engine-touching
  changes on the parity battery (see `ENGINE_REWRITE.md`).
- **Deployment:** cli-dev + devops-admin, pending Jesse's explicit approval. No exceptions.
- Key source locations: entry point `src/main/java/com/datahandler/epicenter/cli/Main.java`;
  report models `models/`; flow layout `models/flowlayout/`; compile request models
  `models/compile/`; shared PDF/INI/MySQL/analysis utilities `util/`; spooling `spool/`;
  RVP `com/datahandler/epicenter/rvp/`; AI private-data authoring
  `com/datahandler/epicenter/cli/aiforge/`.

Companion documents: `AGENT_GUIDE.md` (condensed field manual), `MASTER_DERIVATIVES.md`
(derivative-pipeline study and rationale), `ENGINE_REWRITE.md` (vendored-engine history and
parity harness), `CLAUDE.md` (repo working agreement).