docs: align guides with current CLI behavior

This commit is contained in:
Dandaedre 2026-09-20 20:50:59 +02:00
parent d9b656f74c
commit 94b3d75b2b
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
7 changed files with 264 additions and 117 deletions

View File

@ -9,23 +9,23 @@ work belongs here before implementation.
- [x] Inventory workspace crates, commands, persistence files, CI, and tests.
- [x] Run the untouched baseline test suite (58 library tests; 0 binary tests).
- [x] Record product and engineering conventions in `AGENTS.md`.
- [ ] Capture baseline `--help` output and exercise a complete temporary-repo
- [x] Capture baseline `--help` output and exercise a complete temporary-repo
workflow; record every command that panics, lies, or mutates unexpectedly.
- [ ] Run formatting and strict Clippy; classify all warnings.
- [ ] Map the current `.epochconfig` / epoch-directory format and its recovery
- [x] Map the current `.epochconfig` / epoch-directory format and its recovery
properties before changing persistence.
## Phase 1 — honest documentation and CLI contract
- [ ] Replace the README's advertised-but-missing commands with a concise,
- [x] Replace the README's advertised-but-missing commands with a concise,
verified capability summary and working quick start.
- [ ] Add `docs/README.md` as the documentation index.
- [ ] Add a command reference generated from verified `--help` behavior.
- [ ] Document the repository layout, identifiers, epochs, persistence, and
- [x] Add `docs/README.md` as the documentation index.
- [x] Add a command reference based on verified `--help` behavior.
- [x] Document the repository layout, identifiers, epochs, persistence, and
manual backup/recovery procedure.
- [ ] Add an architecture guide covering crate boundaries and data flow.
- [ ] Add a compatibility policy for stored data and CLI scripts.
- [ ] Add a roadmap that distinguishes implemented, current-release, planned,
- [x] Add an architecture guide covering crate boundaries and data flow.
- [x] Add a compatibility policy for stored data and CLI scripts.
- [x] Add a roadmap that distinguishes implemented, current-release, planned,
and stretch work.
- [ ] Correct typos, stale rustdoc examples, and misleading comments.
@ -113,6 +113,11 @@ These require user approval and are not part of the current implementation:
- `show` currently prints a randomly generated entity repeatedly and does not
inspect repository data.
- `init` exposes `--force`, but the handler does not use it.
- `epoch diff` and `epoch fsck` panic through `unimplemented!()`.
- `epoch switch --force` is parsed but ignored.
- Entity rendering emits ANSI escapes when stdout is redirected and relies on
several optional Nerd Font glyphs for labels.
- Name generation creates `naming.json` in the process working directory.
- The binary crate currently has no tests; most coverage is parsing/model-level.
- Existing library tests passed on 2026-09-20. Tarpaulin was intentionally not
run because badges are release-only by project policy.

179
README.md
View File

@ -1,138 +1,101 @@
# 📦 Epoch Forge (`epoch_forge`) – *early alpha*
![code coverage](badges/coverage.svg) ![version](badges/version.svg) ![code coverage](badges/test.svg)
# Epoch Forge
![📚 Online Documentation](https://books.dandaedre.com/rust_doc/efo/bin_efo/index.html)
![coverage](badges/coverage.svg) ![version](badges/version.svg) ![tests](badges/test.svg)
> **A Rust-powered CLI for managing fantasy organisations across time.**
> *Think of it as a living, breathing world-state engine that lets you “rewind”, “fast-forward”, and **alter** the history of guilds, towns, wars, and characters.*
Epoch Forge (`efo`) is an early-alpha command-line tool for managing a game's
world or organisation across a sequence of snapshots called **epochs**. It is
designed for people who are comfortable with Git-like concepts: inspect the
current state, advance it, compare it with history, and deliberately discard a
future timeline when needed.
> **Epoch Forge** is a Rust‑powered command‑line tool that lets you build and manipulate a living fantasy world.
> It is **in early alpha** – the API is subject to change, some features are missing, and stability is **not guaranteed**.
The current release manages characters, towns, events, calamities, and blockers
with statistics and relationships. Organisation-agnostic custom fields,
pseudo-staging, complete restore/revert workflows, and a TUI are planned—not
implemented. There is no GUI or web interface.
> **Stats & analytics are not yet implemented** – most commands operate only on the raw data model.
> Epoch Forge is not yet suitable as the only copy of important campaign data.
> Keep the repository in Git or make a directory backup before destructive
> operations. See [Safety and recovery](docs/repository.md#safety-and-recovery).
## ✨ Quick start
## Install
The project currently requires Rust 1.92 or newer:
```bash
# Clone the repository
git clone https://proxy.dandaedre.com/gitea/idle-org/epoch_forge.git
cd epoch_forge
# Build & install the binary
cargo install --locked --path bin_efo
```
# Initialise an empty world (epoch 0)
## Quick start
Start in an empty directory. Epoch Forge stores `.epoch` and `epoch/` in the
current working directory.
```bash
mkdir my-world
cd my-world
efo init
# Add an organisation
efo org add "The Iron Horde"
efo chr add "Aria" --stats strength:12 food:8
efo town add "Durn" --position 12,5
efo status
efo chr show Aria
# Add a town
efo town add "Durn" --stat pop:32
# Inspect the current world state
efo show > world.json
cat world.json
# Show the epoch timeline
efo epoch log
# Create the next scheduled epoch
# Snapshot the current state as the next epoch.
efo epoch summary "The expedition begins"
efo epoch tag beginning
efo epoch next
# Switch back to epoch 5 (if it exists)
efo epoch switch 5
# Tag the current epoch
efo epoch tag milestone1
# Add a short-lived event
efo event add "Storm" \
--duration Duration(1) \
--effect permanent-effect-to-apply \
--stats damage=20
# Compare an entity after editing it in epoch 1.
efo chr edit Aria --prestige-add 2
efo chr diff Aria --epoch-id beginning
efo epoch log
```
> **Tip:** The `show` command can print JSON, which you can pipe to `jq` or any other tooling.
Run `efo --help`, `efo <command> --help`, or see the
[command reference](docs/commands.md) for the complete current interface.
## 🏆 Project Highlights
## Capabilities
| Feature | Description | Where to find it |
|---------|-------------|-----------------|
| **Epoch management** | Switch, advance, or rewind the global timeline | `core::epoch` |
| **Persistence** | JSON/YAML stores, pluggable back-ends | `core::epoch` |
| **Event handling** | Add/remove world-shaping events (storms, festivals, wars) | `core::entities` |
| **Organisation CRUD** | Guilds, factions, corporations | `core::entities` |
| **Character CRUD** | Heroes, villains, NPCs | `core::entities` |
| **Town CRUD** | Villages, cities, trade hubs | `core::entities` |
| **Link network** | Alliances, wars, roads, trade routes | `core::link` |
| **CLI** | `efo` binary with sub-commands | `efo` crate |
| Area | Available now | Not available yet |
|---|---|---|
| Repository | Initialise in the current directory; inspect status | Discovery from child directories; locking; migrations |
| Timeline | Advance, switch, log, tag, summarise, delete future epochs | World diff; integrity repair; branching; atomic restore/revert |
| Entities | Add, edit, list, inspect, diff, and delete five built-in types | Organisations; custom types and custom fields; bulk operations |
| Generation | Generate character, town, event, calamity, blocker, and exotic names | Deterministic seed controls and template packs |
| Interfaces | CLI | TUI (possible stretch goal); GUI/web (out of scope) |
> *Statistics, analytics, and the `act` feature are still a work in progress.*
Some commands in the 0.1.0 parser are known incomplete. `epoch diff`,
`epoch fsck`, and the top-level `show` command are being repaired and should not
be relied upon until their roadmap items are checked. The per-type commands,
such as `efo chr show`, are the supported way to inspect entities.
## Unimplemented / WIP
## Documentation
| Feature | Status | Where it lives |
|---------|--------|----------------|
| **Act** | Planned, not yet implemented | `core::act` |
| **Stats** | Missing – no aggregated data | – |
- [Documentation index](docs/README.md)
- [Commands](docs/commands.md)
- [Repository, persistence, and recovery](docs/repository.md)
- [Architecture and development](docs/architecture.md)
- [Roadmap and proposed stretch goals](docs/roadmap.md)
- [Contributor/agent rules](AGENTS.md) and [working task list](AGENTS-TASKS.md)
## Quick reference table
| Sub‑command | Usage example | What it changes |
|-------------|---------------|-----------------|
| **`init`** | `efo init`<br>`efo init --force` | Creates an empty epoch repository (epoch 0) in the current directory. |
| **`epoch log`** | `efo epoch log --limit 20` | Prints a chronological list of epochs up to the current one. |
| **`epoch switch`** | `efo epoch switch 5` | Sets the current epoch to the specified `<id>` (must already exist). |
| **`epoch next`** | `efo epoch next` | Generates the next scheduled epoch and inserts it. |
| **`epoch reset`** | `efo epoch reset` | Deletes all epochs with an identifier greater than the current one. |
| **`epoch diff`** | `efo epoch diff 2 4` | *Unimplemented* – placeholder for future diffing logic. |
| **`epoch tag`** | `efo epoch tag milestone1` | Adds a unique tag to the current epoch, updating the global tag map. |
| **`epoch fsck`** | `efo epoch fsck` | *Unimplemented* – intended to run a consistency check. |
| **`epoch summary`** | `efo epoch summary "Reached the new frontier"` | Replaces the `summary` field of the current epoch with `<text>`. |
| **`show`** | `efo show` | Prints the current world state (JSON). |
| **`gen`** | `efo gen character -n 5 --short`<br>`efo gen town -n 2`<br>`efo gen event -n 3 --name` | Prints generated names/ideas; useful for scripting. |
| **`chr add`** | `efo chr add "Aria" --pos 5,12 --stats strength=12 agility=9` | Creates a new entity (character, town, event, etc.) and writes the epoch. |
| **`chr del`** | `efo chr del "Aria"` | Removes the matching entity from the epoch. |
| **`chr edit`** | `efo chr edit "Storm" --duration Duration(2)` | Modifies an existing entity’s stats, position, duration, etc. |
| **`chr find`** | `efo chr find "Aria"` | Prints full details of a single entity. |
| **`chr show`** | `efo chr show` | Lists all entities, or `efo chr show "Aria"` shows one in full detail. |
| **`chr diff`** | `efo chr diff "Aria"` | Prints the difference between the current and previous epoch for that entity. |
| **`event add` / `event remove`** | `efo event add ...`<br>`efo event remove ...` | Adds or removes an event. |
| **`org add` / `org remove`** | `efo org add ...`<br>`efo org remove ...` | Manages organisations (guilds, factions). |
| **`town add` / `town remove`** | `efo town add ...`<br>`efo town remove ...` | CRUD for towns. |
| **`monster add` / `monster remove`** | `efo monster add ...`<br>`efo monster remove ...` | CRUD for monsters. |
| **`act`** | *Not yet implemented* | Planned for future action handling. |
> All changes are persisted immediately to the epoch file after the command finishes.
## Contributions & Feedback
Because the project is in early alpha, any feedback, bug reports, or pull requests are welcome.
Please remember that **stability is not guaranteed**, so use it in a versionned environnement.
Happy forging! ✨
## Binary releases
The CLI package is `efo`, in the `bin_efo` workspace member. Release tags follow
its Cargo version (for example, `v0.1.0`). The publisher is invoked from its own
checkout with:
## Development
```bash
./release.sh /path/to/epoch_forge --package efo --tag v0.1.0
cargo fmt --all -- --check
cargo test --workspace --all-targets --all-features --locked
cargo clippy --workspace --all-targets --all-features --locked -- -D warnings
```
The workspace lockfile is tracked. `Cross.toml` selects the tested cross images
for x86-64 musl Linux, AArch64 musl Linux, and x86-64 GNU Windows. The build scripts
work with rustc alone inside cross containers; rustup is not required there.
Tarpaulin and `rust_autobadges` are intentionally release-only. They do not run
in routine CI because of their cost; badge files are refreshed for significant
releases.
Release archives use `efo-{target}-v{version}.tgz` and contain the matching root
directory with `efo` (or `efo.exe`). `SHA256SUMS` accompanies the archives. The
selected package manifest carries cargo-binstall metadata for the Gitea URLs.
After the matching release has been published, install from the local manifest:
## Release archives
```bash
cargo binstall efo --manifest-path bin_efo/Cargo.toml
```
The CLI package is `efo` in `bin_efo`. Release tags follow the Cargo version
(for example `v0.1.0`). Cross-built archives are named
`efo-{target}-v{version}.tgz` and are accompanied by `SHA256SUMS`.
Epoch Forge is licensed under the terms in [LICENSE](LICENSE).

12
docs/README.md Normal file
View File

@ -0,0 +1,12 @@
# Epoch Forge documentation
This documentation describes current executable behavior and labels planned
behavior clearly.
- [Commands](commands.md): verified CLI surface and examples.
- [Repository format](repository.md): files, epochs, compatibility, backup, and recovery.
- [Architecture](architecture.md): crate responsibilities, data flow, and quality gates.
- [Roadmap](roadmap.md): current work and stretch proposals.
Start with the project [README](../README.md). Contributors should also read
[AGENTS.md](../AGENTS.md) and maintain [AGENTS-TASKS.md](../AGENTS-TASKS.md).

26
docs/architecture.md Normal file
View File

@ -0,0 +1,26 @@
# Architecture and development
```text
CLI parsing and rendering (`bin_efo`)
│
▼
domain and persistence (`lib_efo`)
│
▼
`.epoch` and `epoch/*`
```
`bin_efo` defines the Clap command tree and presentation. `lib_efo` owns
entities, statistics, identifiers, epochs, naming, and JSON persistence. New
behavior should be a testable library operation with a thin CLI handler.
The design direction is to make repository paths explicit; replace truncating
writes with temporary-file plus rename; add locking; remove unsafe cache
accessors; separate styling from semantic output; and retain unknown custom
metadata as the model becomes organisation-agnostic.
Library tests currently cover parsing, statistics, display snapshots, and parts
of entity/epoch behavior. CLI integration coverage is the main gap. Routine CI
should run formatting, all-target workspace tests, strict Clippy, and a release
build. Tarpaulin and `rust_autobadges` remain local significant-release-only
tools. See [AGENTS.md](../AGENTS.md) for contributor rules.

55
docs/commands.md Normal file
View File

@ -0,0 +1,55 @@
# 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 `.epoch` and `epoch/0/epochinfo.json`. Although
`--force` is accepted in 0.1.0, it currently has no effect and will not allow
a non-empty directory.
- `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. Its currently accepted `--force` flag has no effect.
- `efo epoch summary TEXT` and `efo epoch tag TAG` annotate the current epoch.
- `efo epoch reset` permanently deletes every epoch after the current one.
`epoch diff` and `epoch fsck` are exposed in 0.1.0 but incomplete and currently
panic. They are current-release defects, not usable capabilities.
## Entities
The built-in nouns are `chr`, `town`, `event`, `calamity`, and `blocker`:
```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. Mutations write the current epoch immediately; staging does
not exist yet.
The top-level `show` command is currently demo output. Use `<noun> show`.
## Generation and output
`efo gen character|town|event|exotic|calamity|blocker` prints generated content.
The first naming operation may unexpectedly create `naming.json` in the current
directory; removal of this side effect is planned.
Output is human-readable Unicode. Some 0.1.0 renderers emit ANSI colour when
redirected and use optional Nerd Font glyphs; these are known accessibility
issues. Stable JSON output is planned. A panic is always a bug.

50
docs/repository.md Normal file
View File

@ -0,0 +1,50 @@
# Repository, persistence, and recovery
## Layout
```text
.
├── .epoch current epoch, build version, global tag map
└── epoch/
├── 0/epochinfo.json complete epoch-0 world snapshot
├── 1/epochinfo.json complete epoch-1 world snapshot
└── …
```
`.epoch` is JSON despite having no extension. Each snapshot stores its ID,
random seed, tags, summary, and arrays of events, characters, towns, calamities,
and blockers. The full world is duplicated per epoch.
Entity commands edit the current snapshot directly. `epoch next` creates a new
snapshot; `epoch switch` only changes the current pointer. `epoch reset` deletes
later directories. This is not yet Git-equivalent: there is no working
tree/index separation, reflog, locking, atomic multi-file transaction, or
built-in undelete.
## Safety and recovery
Keep the directory in Git or copy it before important changes:
```bash
git init
git add .epoch epoch/
git commit -m "backup Epoch Forge world"
```
To revisit prior data without deleting the future:
```bash
efo epoch log
efo epoch switch 0
efo status
```
Back up before `epoch reset`; Epoch Forge cannot recover its deleted folders.
For corruption, stop mutating, copy the complete directory, and restore from a
known-good backup. `epoch fsck` is not usable in 0.1.0.
The config records a writer version, but automatic migrations and unknown-field
retention are not implemented. The intended compatibility policy is that newer
supported binaries migrate without data loss, format changes provide preview
and backup, and future custom fields survive round trips. Current work is
tracked in [the roadmap](roadmap.md).

36
docs/roadmap.md Normal file
View File

@ -0,0 +1,36 @@
# Roadmap
The detailed backlog is [AGENTS-TASKS.md](../AGENTS-TASKS.md).
## Implemented foundation
- Local CLI repository with full-world epoch snapshots.
- Five entity collections with add/edit/show/diff/delete operations.
- Statistics, positions, duration/effects, selected relationships, and random
generation.
- Timeline advance, switch, log, tags, summaries, and explicit future deletion.
## Current release target
The immediate release prioritises trust: truthful help/docs, no user-triggerable
panics, safe initialisation, real `show`, useful read-only `fsck`, world diff,
atomic persistence, CLI workflow tests, accessible output, and clear recovery.
Next comes a reviewed Git-like model for working changes, pseudo-staging,
committed epochs, restore, and revert. Organisation-agnostic custom fields and
types follow, with migrations and unknown-field retention designed first.
## Proposed stretch goals
1. Shell completions and generated man pages.
2. Stable JSON/JSONL output and query/filter expressions.
3. A keyboard-driven TUI over the same domain API (no GUI).
4. Named timeline branches with merge/conflict handling.
5. Setting templates for empires, companies, guilds, and nations.
6. Validation/simulation hooks before committing an epoch.
7. Optional signed snapshots and append-only audit records.
8. Deterministic seeded generation/simulation.
9. A scripting/plugin boundary after persistence is stable.
Completions and structured output are the best first stretch investments. A TUI
and branching should wait until staging, revert, and locking are reliable.