cinematic-3d-battle-engine: Instructions file for Codex

AGENTS.md: forking a new battle with an AI agent

This file is the runbook for an AI coding agent (and the human directing it) to fork this template into a new historical battle. Read it fully before starting. The companion references are PLAYBOOK.md (the field-by-field data schema) and data.example.js (a minimal working skeleton to copy).

---

The one rule that overrides everything: do not fabricate history

This template renders a self-playing documentary. A documentary's worth is its truth. So:

• Research and cite real sources first. Before writing any data, gather the real date window, the opposing sides and their forces/commanders, the real geography (place names + coordinates), and the sequence of events, each tied to a source you can name.
• Never invent a unit, a date, a movement, or a position to fill a gap. If a fact is unknown or disputed, say so in notes.caveats. Do not paper over it with a plausible-sounding guess. A beautiful fabricated battle is worthless.
• The engine enforces this: notes.sources is a required field, and the boot validator refuses to start a battle without it. That is a floor, not a substitute for honest sourcing.

If you cannot source a battle to this standard, stop and tell the human. Do not proceed.

Fictional battles: welcome, and held to the same standard

The engine renders fictional battles too (the bundled Example Battle is one), and a fiction does not break the rule above. The line is simple: the rule forbids passing invention off as real history, not invention itself. A fictional battle is fine as long as it is honest about being fictional and is built with the same care as a real one:

• Declare it fictional. Say so plainly in notes (the Example Battle's notes.sources reads "FICTIONAL DEMONSTRATION SCENARIO", which also satisfies the required non-empty sources). Never dress a fiction up as real history, and never attach a real battle's name, date, or place to invented events.
• Stay true to the source material. A fiction still has a source: a novel, a film, a game, an alternate-history premise, or its own established canon. Be accurate to THAT. This is fictional historical accuracy: period-plausible, internally consistent, and faithful to the world it depicts, with the same craft a real battle gets. A lazy, self-contradicting fiction is as worthless as a fabricated history.