docs(ax): entry 54 — the tool's key is not the name every other surface shows

[lilyshen0722]

Summary

AX-audit entry for #1403. commonly_read_file 404s with "File not found in this pod" when handed a file's display name instead of its storage key — and every other surface an agent reads hands it the display name.

Why this is an AX entry, not just the issue restated

Two points the issue makes that generalise past this tool:

1. The default path is the failing one. The tool description is accurate ("pass the fileName from commonly_list_files"), but chat upload markers, the successful read's own name field, and any peer's sentence about an attachment all carry the human name. So passing the display name is what an agent naturally does.
2. The error asserts a fact, and the fact is false. "File not found in this pod" is a claim about pod contents, not a hint about vocabulary. A seat acting on it correctly concluded a spec was missing and asked its author to re-send. Same class as Every failure degrades to silence, and silence is indistinguishable from a decision (8 instances, one defect) #1012 — a failure that renders as a decision.

It also records the compounding half: the stated recovery (list files, map name → key) is capped at 25 / 20 entries with no paging and GET /api/pods/:podId/files 401s on a cm_agent_* token — so in a pod producing ~25 attachments in 14 hours, anything older than half a day is unreachable by name and unlistable by key. A teaching error is only teaching if the lesson it points at is reachable.

Type

• Documentation

Related

• Closes nothing; documents commonly_read_file: passing a file's display name 404s with "File not found in this pod" — indistinguishable from a genuinely absent file, and the listings are too truncated to recover the storage key #1403 (which stays open for the fix)
• Prior art: Every failure degrades to silence, and silence is indistinguishable from a decision (8 instances, one defect) #1012

🤖 Generated with Claude Code

[lilyshen0722]

Merge-order note, since this PR is an instance of the thing #1414 is about.

This branch is CLEAN against main and that is not the useful measurement. It appends to the tail of agent-experience-audit.md, and so do the other open AX entries. Measured with git merge-tree --write-tree against each head:

• docs(ax): entry 53 — two green PRs can form a broken contract #1353 — CONFLICT
• docs(ax): entry 52 — the prescribed fix erases the evidence for the warning that prescribed it #1350 — CONFLICT
• docs(ax): entry 48 — a memory tool that offers seven sections and reads back one #1264 — CONFLICT
• docs(ax): consecutive_run_cap composes with the redelivery backlog into a mute #1235 — clean

So whichever of these merges first, the rest need a rebase; mine has no priority claim over any of them. I'm not asking for a merge slot ahead of anyone — land the others first and I'll rebase this one, since a docs entry is the cheapest thing in the set to move.

The numbering has the same shape: entries 45–53 are claimed by open PRs, none merged, so 54 is only free relative to main. If two of these land before this one, the number is wrong and I'll renumber on rebase rather than the reviewer catching it.