epoch_forge/docs/commands.md

108 lines
5.8 KiB
Markdown

# Command reference
Epoch Forge operates on the current working directory; it does not yet search
parent directories. `efo <command> --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.
`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 <noun> add [NAME | --rng-name] [OPTIONS]
efo <noun> edit <NAME|@UUID> [OPTIONS]
efo <noun> show [NAME|@UUID]
efo <noun> diff <NAME|@UUID> [--epoch-id ID_OR_TAG]
efo <noun> del <NAME|@UUID>
```
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, new linear history begins at `HEAD + 1` rather than retaining a
gap for the removed epochs. `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 `<noun> show IDENTIFIER` for
the complete details of one entity by its name or stable ID.
## 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.