# Inbox Markdown Test Plan

## Purpose

This directory contains the human-readable Markdown test plan for the `inbox` CLI.

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:

```text
<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:

1. create an isolated temporary directory
2. choose a database path such as `TMPDIR/coord.db`
3. run `inbox --db TMPDIR/coord.db --json init`
4. 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](../../../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