# Command reference Epoch Forge operates on the current working directory; it does not yet search parent directories. `efo --help` is the authoritative syntax. ## Repository and timeline - `efo init [--force]` creates the format-1.0 manifest, HEAD, index, worktree, and `epoch/0/epochinfo.json`. The normal form requires an empty directory; `--force` permits unrelated existing files but never overwrites `.epoch` or epoch 0. - `efo recover` deterministically rolls back a prepared replacement or verifies a committed one. It is safe to repeat. - `efo lock inspect` reports writer ownership. `efo lock break --yes` removes an abandoned lock only after explicit confirmation; run `efo recover` next. - `efo status [EPOCH_ID]` shows an epoch summary, tags, and entity counts. - `efo epoch log [-c N]` shows epochs around the current epoch. - `efo epoch next` creates and checks out the next snapshot. It refuses while later snapshots exist. - `efo epoch switch ID_OR_TAG` checks out an existing snapshot without deleting later ones. - `efo epoch summary TEXT` and `efo epoch tag TAG` annotate the current epoch. - `efo epoch diff START [END]` reports added, removed, and modified entities. A trailing `!` marks changes considered especially consequential (towns, events, calamities, or statistic/duration changes). `END` defaults to the current epoch. - `efo epoch fsck` performs a read-only consistency check of epoch IDs, tags, and entity UUIDs. It does not repair damage. - `efo prune-future` previews later history; `--yes` moves it to a restorable backup, removes tags into that future, and makes the next commit use the ID immediately after HEAD. Restoring the backup restores its allocator and tags. - `efo reset --hard ID_OR_TAG` previews a destructive rewind. Add `--yes` to align HEAD, index, and worktree to the target and permanently delete every newer epoch. This has no built-in undo; prefer `switch` plus `prune-future` when recovery may be needed. ## Entities The built-in nouns are `org`, `chr`, `town`, `event`, `calamity`, and `blocker`. `character` aliases `chr`; `organization` and `organisation` alias `org`: ```text efo add [NAME | --rng-name] [OPTIONS] efo edit [OPTIONS] efo show [NAME|@UUID] efo diff [--epoch-id ID_OR_TAG] efo del ``` Names match by prefix. `@UUID` is the stable form printed in detailed output; short UUID prefixes are accepted. Avoid ambiguous prefixes. Common add/edit options include `--stats key:value ...`, `--position x,y`, `--duration`, `--bounds`, `--effect`, faction/reach/description/relationship options, and prestige controls. `edit --delta` adds supplied stats rather than replacing them. See nested help (for example `efo chr add --help`) for exact syntax and values. Persistent normalized stats are clamped to `0..=120`; growth and event/blocker modifiers use `-120..=120`; population remains an unbounded non-negative count for persistent entities. Entity mutations edit only the worktree. Use `efo diff`, `efo stage --all`, `efo stage --world`, or `efo stage --kind KIND ID...`, and `efo diff --staged` to prepare history. `efo restore --staged ...` copies HEAD into the index; `efo restore --worktree ...` copies the index into the worktree. Both restore modes require either `--all` or an entity kind and IDs. `efo commit -m MESSAGE` refuses unstaged or empty commits, creates an immutable epoch using a manifest-last transaction, and realigns all three layers. `efo log` shows the resulting parent-linked history newest first. `efo switch ID` requires clean state and changes all layers without reusing epoch IDs. `efo revert ID` applies that epoch's inverse to the worktree for review; it can be undone with `restore --worktree --all`. `revert ID --commit` prints a warning and immediately creates the inverse commit. Overlap with later changes aborts without mutation. `efo prune-future` previews future epochs, while `--yes` moves them into a backup. Restore using the exact command printed after pruning; this also restores the former next-epoch allocator and tags. After pruning, the next epoch allocator remains monotonic, so removed IDs are not reused. `efo reset --hard ID --yes` is the explicitly destructive alternative: it discards transient changes, removes newer epochs without a backup, removes tags that point to them, and restarts the epoch allocator after the retained target. `efo epoch summary` and `efo epoch tag` edit worktree metadata; `stage --world` selects it. `efo epoch next` requires a clean worktree, includes already staged changes, advances entity time, and commits one new monotonic ID. `efo epoch fsck` validates all state layers and every immutable epoch. `efo show` defaults to every collection. `show character`, `show town`, `show event`, `show calamity`, `show organization`, and `show blocker` select one. Filter with `--name TEXT`, `--text TEXT`, or `--position X,Y`; select a committed snapshot with `--epoch ID_OR_TAG`. `--detail short|long|full` controls output density. `efo show epoch` lists committed epoch summaries and accepts the same `--epoch` and detail options. Use ` show IDENTIFIER` for the complete details of one entity by its name or stable ID. ## Roads and travel Spatial changes are preview-first and affect only the worktree with `--apply`: ```text efo travel road-add Haven Northwatch --speed 180 efo travel road-add Haven Northwatch --speed 180 --apply efo travel roads efo travel plan Aria Northwatch --offroad-speed 50 efo travel plan Aria Northwatch --offroad-speed 50 --apply efo travel tick 3 --apply ``` Routing minimizes integer travel ticks with deterministic tie-breaking. Roads carry their own speed; disconnected characters fall back to slower direct travel. Characters have explicit resident, roaming, or travelling state. Use `efo restore --worktree --all` to discard applied simulation changes. ## Event diffusion Events propagate from their map position over the same topology. Roads use their configured speed and direct spatial propagation remains a slower fallback: ```text efo diffuse start Plague --road-speed 100 --direct-speed 25 --expires-after 20 efo diffuse start Plague --road-speed 100 --direct-speed 25 --expires-after 20 --apply efo diffuse tick 3 efo diffuse tick 3 --apply efo diffuse resolve Plague Haven --level good --characters residents efo diffuse resolve Plague Haven --level good --characters residents --apply ``` The preview reports each destination's arrival tick and whether it is reached by road or directly. Persisted frontiers retain an affected set, so applying or previewing the same tick again cannot reach a town twice. Expired state remains inspectable and can be restored, staged, or committed like any other worktree change. Applied ticks leave newly reached towns pending until the game master resolves them. `diffuse resolve` shows colocated or linked blockers as protection context, then previews the town and characters selected by `--characters none|residents|positioned|both`. Protection never silently chooses an outcome: use `--disposition applied|dampened|avoided|destroyed`. Avoided targets are still recorded and cannot be resolved twice. Travelling characters are conservatively excluded because interpolated route positions are not yet stored. One `--apply` writes all target effects and resolution records atomically; normal worktree restore undoes the batch. ## External rolls and game-master adjudication Epoch Forge does not roll or infer an outcome. The player rolls outside the tool, then the game master records the result, interpretation, disposition, and exact stat effects: ```text efo adjudicate preview Plague --target town:Haven --level bad \ --result "d20=4" --disposition dampened --effect health:-8 efo adjudicate apply Plague --target town:Haven --level bad \ --result "d20=4" --disposition dampened --effect health:-8 efo adjudicate list Plague ``` For the common case, omit result, disposition, and effects: ```text efo adjudicate apply Plague --target town:Haven --level bad ``` This uses the configured default effects. The embedded policy progressively dampens its `health:-20` baseline: excellent 0%, good 25%, mid 50%, bad 75%, worsen 90%, and apocalypse 100%. An external `--config` can replace both the baseline and scale. Supplying one or more `--effect` options replaces the defaults completely. `influx` is a visible alias for `adjudicate`. `applied` uses the supplied effects in full, `dampened` applies the configured attenuation, and `avoided` or `destroyed` records zero stat change. Applied rulings are audit records in the worktree. Use `efo restore --worktree --all` to undo the ruling and its effects together; audit records cannot be cleared independently from effects. Each ruling also marks the source event with remaining potency. Later default effects are multiplied by that percentage. A destroyed event has 0% potency, stops an active frontier, and cannot start another diffusion; restore or revert the ruling to recover it. `efo adjudicate list EVENT` displays this state. ## Fights and wars Conflicts are generic multi-side records whose participants remain ordinary entities. Start is preview-first: ```text efo conflict start "Bridge War" --kind war \ --side red:town:Haven --side blue:org:Guild:2 efo conflict start "Bridge War" --kind war \ --side red:town:Haven --side blue:org:Guild:2 --apply ``` Advance one round with exactly one external adjudication per active side: ```text efo conflict advance "Bridge War" \ --side-outcome red:good:applied \ --side-outcome blue:bad:dampened \ --result "players rolled 11 and 4" [--apply] ``` `fight` and `war` are visible aliases for `conflict`. Outcomes reuse the same levels, dispositions, progressive defaults, and explicit `--effect` overrides. `destroyed` removes a participant from this conflict but never deletes its entity. A fight stalemates after one unresolved round; a war stays active until one side remains. Use `conflict show`, `conflict list`, or `conflict end --reason ... [--apply]`. Every mutation affects only the worktree and supports restore, stage, commit, and historical revert. ## Generation and output `efo gen character|town|event|exotic|calamity|blocker` prints generated content without creating or changing repository files. `efo gen world --level event|settlement|region|world --seed N` previews a deterministic generated world using embedded configuration. `--config PATH` selects an editable JSON override. `--apply` explicitly replaces only the worktree; undo it with `efo restore --worktree --all`, or stage and commit it through the ordinary workflow. Output is human-readable Unicode, with Nerd Font icons enabled by default. A portable build replaces those icons with textual/standard-Unicode labels; use `cargo install --path bin_efo --no-default-features`. Stable JSON output is planned. A panic is always a bug.