PRIMARY path to close a Grove goal: this is the ONLY tool that covers an acceptance criterion. Attach binary evidence (screenshot, log dump, API response, export) to an AC — call it once per criterion to satisfy the close gate. The subordinate goal-add-evidence-text only adds context for proofs with NO bytes (URLs to permanent external sources, manual repro descriptions) and does NOT cover an AC. Caption is optional but strongly recommended: state what the file captures and the reproduction conditions (URL/commit/session/inputs) so a third reviewer can reproduce.
⚠ PICK THE RIGHT TRANSPORT BEFORE YOU CALL THIS TOOL ⚠
• BEST for ANY file > ~1 KB raw — and the ONLY no-token path, so use it in a claude.ai / hosted-agent session that has no raw X-Auth-Token → call the sibling MCP tool `goal-request-upload` with this same criterionId. It returns a one-time {uploadUrl, expiresAt}; then stream the raw bytes with a single PUT: `curl -sS --fail --upload-file "/abs/path/to/file.png" "<uploadUrl>"` (optionally add -H "X-Content-Sha256: <hex sha256>" so corruption fails fast). No base64, no token — the signed ?t= ticket in the URL is the only credential, single-use, criterion-scoped. The PUT response is the same evidence JSON this tool returns.
• ALTERNATIVELY, if you DO have the raw X-Auth-Token in your shell → the `planner-attach.sh` helper (zero-install bash, binary-safe).
The MCP base64 path below is unreliable for non-trivial files: long string arguments get truncated or whitespace-corrupted on the agent side BEFORE the JSON-RPC request is sent. Measured 2026-05-20 on prod: a 4 KB PNG arrived at the server as 1874 decoded bytes (file_hash_mismatch); a 2 KB payload arrived with stray whitespace (failed base64_decode). The server itself accepts up to 25 MiB raw — the bottleneck is the agent-side serialisation of contentBase64, NOT the server.
planner-attach.sh COPY-PASTE RECIPE (replace 3 placeholders, run in your shell):
curl -sS https://planner.monopoly-gold.com/api/cli/planner-attach.sh \
| PLANNER_TOKEN="<same X-Auth-Token you use for MCP>" bash -s -- \
--criterion-id "<CRITERION_UUID>" \
--file "/abs/path/to/file.png" \
--caption "what is captured and the repro conditions" \
--created-by "<your agent id>"
Where to get each value:
- PLANNER_TOKEN: the very same token that is already in your MCP config under the X-Auth-Token header for the `planner` server. NOT a separate credential.
- CRITERION_UUID: the AC id you got from goal-get / goal-list. Same UUID you would pass to this MCP tool.
- file path: absolute path on YOUR (agent) machine — the script reads it locally and streams multipart. The planner server never sees your filesystem.
The helper computes SHA-256 itself and ships it as `contentSha256`, so any in-flight corruption fails fast with HTTP 400 instead of poisoning the evidence row. Output on stdout is the same JSON shape this MCP tool returns; non-zero exit means HTTP ≥ 400 (stderr explains).
Without curl/bash? Fall back to raw multipart: POST https://planner.monopoly-gold.com/api/criteria/<id>/evidence/file, header X-Auth-Token, form fields file=@..., contentSha256=..., caption, createdBy.
• File ≤ ~1 KB raw → this MCP tool is fine. ALWAYS pass `contentSha256` (hex SHA-256 of raw bytes BEFORE base64). Without it, a silently truncated PNG looks valid to the MIME sniffer; the server cannot distinguish a truncated 4 KB PNG from a valid 1 KB one and the vision judge burns ~30s on broken bytes. With the hash, the server fast-fails with error=file_hash_mismatch and points back here at the multipart endpoint.
Validates MIME whitelist (png/jpeg/webp/gif/pdf/txt/json/zip), per-file size cap (ATTACHMENTS_MAX_FILE_BYTES, default 25 MiB), per-project attachments quota. Returns evidence record + file URL + serverSha256.
