It complements automated Go tests. The goal is not to restate implementation details, but to preserve the user-visible CLI contract in a form that can be reviewed, extended, and executed manually when needed.

Directory Rules

one folder per command or shared area
each folder keeps a README.md entrypoint
command folders use README.md as an index only
each command test case lives in its own Markdown file named after the case slug
no numeric test IDs
each command case is identified by its concrete file path

Case file naming pattern:

<case-slug>.md

Authoring Principles

focus on externally visible behavior of the CLI
prefer stable command examples that a new agent can replay against a temp database
describe both success shape and failure contract
when a case already exists in automated Go tests, reuse its scenario rather than inventing a new one
keep terminology consistent with command flags and JSON fields exposed by the CLI

Common Execution Model

Most cases in this directory assume the same baseline:

create an isolated temporary directory
choose a database path such as TMPDIR/coord.db
run inbox --db TMPDIR/coord.db --json init
run the target command sequence against that database

Unless a case says otherwise:

commands should use --json
assertions should check both exit code and JSON payload
examples may use explicit --agent, or rely on the root --agent flag when that is the behavior under test

Folder Map

README.md: global conventions and glossary
_shared/README.md: reusable fixtures, JSON assertions, exit codes, payload rules
workflows/README.md: cross-command end-to-end scenarios
per-command folders: command-specific index README.md files plus one case document per test case

Glossary

thread: the durable coordination unit tracked by thread_id
message: an event-bearing entry appended to a thread
artifact: a file attachment associated with a message
read cursor: the per-agent marker used by unread flows
lease: the temporary ownership granted by claim and extended by renew
terminal state: a thread state such as done, failed, or cancelled

Relationship To Automated Tests

The current best executable reference is internal/cli/inbox/integration_test.go.

When this Markdown plan is expanded:

prefer matching an existing automated scenario first
record any additional manual-only contract coverage explicitly in the relevant command case file and keep the folder index synchronized
keep docs/tests/inbox/ROADMAP.md synchronized with authored files and case slugs