Workflow and Roles

Pages move through a fixed four-state machine: draft → review → published → archived. The state machine is hard-coded and not configurable. Published is the default status. Only the legal next states for the current status render as contextual buttons, so an author cannot, for example, archive a draft or publish without going through review.

The six legal transitions are:

Current status	Available transitions
draft	Submit for review (→ review)
review	Approve (→ published), Send back (→ draft)
published	Unpublish (→ draft), Archive (→ archived)
archived	Restore (→ draft)

Each button posts to POST /_admin/transitions/{path} with the target status. The handler validates the target against the state machine. An illegal edge (unknown target, or an edge not allowed from the current state) is refused with 400 Bad Request and a Cannot transition from X to Y. message. On a legal transition the new status is swapped into the frontmatter and written through the same save chokepoint a normal edit uses, and a workflow_transition audit entry is appended with from / to fields.

Publish gate

Transitions to published re-run validation against the freshly-read on-disk frontmatter — first per-field rules, then cross-field model rules. Only Error-severity issues block the publish; warnings pass. If any errors exist the write is refused. Every other edge ignores validation errors; the gate applies to the publish step only.

Per-model review requirement

A document model can declare requires_review: true. When set, pages of that model must pass through the Review state before being published: a direct draft → published attempt is refused (422 Unprocessable Entity) with the message “This model requires editorial review. Submit for review, then approve.” The state machine never offers the direct edge anyway, so the flag mainly provides a clearer, actionable error for tooling that bypasses the UI.

Publisher role is read-only

On a deployment running in the Publisher server role, the transition handler returns 403 Forbidden before any I/O, with the notice “This is a publisher. Edits happen on the upstream author.” Publisher installs render the transition buttons disabled.

Draft and Review pages are hidden from the public unless drafts are explicitly shown; Published pages are publicly visible (subject to date constraints); Archived pages are hidden from listings but remain accessible by direct URL.