# Step documents (cp-docs-token)

This step can read and write planner documents through `python3 -m lib.cp_cli`
in step-docs mode (PLN-CLI-16). The mode is active because `CP_DOCS_TOKEN_FILE`
and `CP_DOCS_CA_FILE` are set and the listener URL is in `CP_DOCS_URL`.

## Credential

- The token is a file at `$CP_DOCS_TOKEN_FILE`. cp-cli reads it on every call.
- Never print, copy, log or pass the token on a command line.
- Do not use `~/.cpconfig`; step-docs mode does not read it.

## Allowed commands

Only these commands work; anything else exits 2 `cp_docs_mode_command_not_allowed`:

```
python3 -m lib.cp_cli planner items documents list <item-uuid>
python3 -m lib.cp_cli planner items documents get <item-uuid> <name> [--json]
python3 -m lib.cp_cli planner items documents put <item-uuid> <name> --file <path> (--create-only | --if-match <rev>)
python3 -m lib.cp_cli planner items documents related [--json]
```

Item arguments are full UUIDs. Do not pass a project id.

## Scope

- You may write only documents on this step's own item.
- You may read documents on this step's item, its parent and its siblings.
- `related` prints `item_uuid`, `parent_uuid`, `sibling_uuids` and `siblings_truncated`.

## Writes need a precondition

Exactly one of these is required on every `put` (neither or both exits 2):

- `--create-only` creates a new document (sends `If-None-Match: *`).
- `--if-match <rev>` updates an existing one (sends `If-Match`). Take `<rev>`
  from `get --json` (the ETag revision); surrounding quotes are stripped.

## Errors

- 412 `precondition_failed`: the document changed or already exists. Re-run
  `get --json`, merge your change into the current content, and `put` again
  with the new revision.
- 428 (precondition missing): add `--create-only` or `--if-match`.
- 429 `step_docs_write_budget_exhausted` or `step_docs_rate_limited`: stop
  writing; do not retry in a loop.
- 404 `not_found`, 400 `invalid_document_name`: fix the item uuid or name.