amanuensis/README.AMANUENSIS.md

# Technical information

## The Amanuensis config directory

TODO

## Life cycle of a Lexicon game

Games can only be created by the administrator. When a game is created, its name, editor, and prompt are specified. The state of the game follows a simple state machine:

* When a game is initialized, the `turn.current` setting is null. As long as the current turn of a lexicon is null, it is considered to be in a **pre-game** state. In this state, all settings can be changed by the editor. Once the editor enables `join.open`, players can join. While the game is in the pre-game state, players can create characters.

* When the editor begins the game, `turn.current` is set to `turn.start`. Both of these settings are locked. Once `turn.current` is non-null, the game has entered the **ongoing** state. Character creation is no longer available. Players will be given access to the editor, and they can begin writing and submitting articles. While the game is in this state, it transitions from each turn to the next turn, incrementing `turn.current`. The turn-by-turn state machine is covered just below.

* When `turn.current` exceeds `turn.max`. the lexicon is **completed**. Players are unable to further affect the lexicon.

### Article workflow

The article writing workflow proceeds through the following states:

* Active: When a player creates a draft, it is initialized with this state.
  Players can view and edit their active drafts. Admins can view all active
  drafts. Active drafts occupy an index slot in the lexicon, but the title is
  elided.

  Players can mark their active drafts as ready for publication, which
  transitions the draft to the Ready state. If `publish.notify.editor_on_ready`
  is true, the editor will be notified.

* Ready: Players can view but not edit their ready drafts. Editors and admins
  can view all ready drafts. The editor's session page lists all ready drafts
  for that lexicon. Ready drafts occupy an index slot with an elided title.

  A player can unready a ready draft, which transitions it to the Active state.

  The editor can approve a ready draft, which transitions it to the Locked
  state, or reject it, which transitions it to the Active state and includes a
  message from the editor to the player who owns it. If either
  `publish.notify.player_on_reject` or `publish.notify.player_on_accept` is true,
  the player will be notified in that case.

* Locked: Players can view but not edit their locked drafts. Editors and admins
  admins can view all locked drafts. The editor's session page lists all
  locked drafts for that lexicon. Locked drafts occupy an index slot with an
  elided title.

Turn publishing can be attempted by executing the `lexicon-publish-turn` command.
Automatic publishing is controlled by two settings: `asap` and `deadlines`.

* `asap`: If `publish.asap` is true, when the editor approves a draft, Amanuensis
  will check if each character has a locked draft. If so, publishing will be
  attempted immediately.

* `deadlines`: `publish.deadlines` should be a crontab-format time specification.
  This will be prepended to the publish command and inserted into the user
  crontab. The command uses `--as-deadline` to differentiate scheduled publish
  attempts from manual ones. If `publish.deadlines` is empty, no crontab entry
  will be used.

Whenever publishing is attempted, either internally via asap or externally via
invocation by command line or cron job, Amanuensis checks if every character in
the lexicon has a locked draft. If so, the turn is published. If not, publish
behavior follows two settings: `quorum` and `block_on_ready`.

* `quorum`: If `publish.quorum` is defined, then Amanuensis will check if there are
  at least that many locked articles. If there are, then turn
  publishing will proceed with just those articles. If there are not, but there
  are enough ready articles to make quorum and `--as-deadline` was specified, then
  the editor will be notified that they are blocking the turn. If there are not
  enough ready articles to make quorum and `--as-deadline` was specified, then
  players with characters without ready articles will be notified that they are
  blocking the turn.

* `block_on_ready`: If `publish.block_on_ready` is true, then turn publishing will
  fail if any character missing a locked article has a ready article. The
  editor will be notified that they are blocking the turn.

* `--force` can be specified to lexicon-publish-turn to skip both quorum and
  ready checks.