agent-runtime-framework/harnesses/contexts/cp-docs-token/v1/CLAUDE.md

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.