pm docs --add silently stores a malformed path where pm files --add correctly errors on the same input #1000

Summary

pm files --add and pm docs --add document the same --add <value> contract ("CSV/markdown pairs"), but handle an unrecognized key differently: files rejects it with an excellent error, and docs silently accepts it, storing the entire string as the path.

For an agent this is the worst possible split, because the strict sibling teaches the wrong lesson about the lenient one.

Reproduction

Fresh pm init project, pm-cli 2026.8.13:

pm files pm-xxxx --add "README.md=user guide"

Error: Command failed
What happened:
  --add does not recognize key "README.md". Allowed keys: path, scope, note.

Exit 2. This is a genuinely good error — it names the bad key and enumerates the allowed ones.

Same shape, sibling command:

pm docs pm-xxxx --add "https://example.com/x=some note"

Exit 0, no warning. Stored:

docs[1]{path,scope}:
  "https://example.com/x=some note",project

The note is glued onto the URL and the entry is now a permanent, committed link to a path that does not exist. The correct invocation is --add "path=https://example.com/x" --note "some note", but nothing in the output suggests the first form was wrong.

Why this costs agent time specifically

An agent writing a batch of links has no reason to suspect the two commands disagree. What actually happened here: I linked files and docs in one batch, files errored so I corrected the syntax, and I reasonably assumed the docs call in the same batch had also failed loudly if it were wrong. It had not — it silently wrote a malformed path that I only caught by re-reading the .toon afterwards.

The failure is silent, committed, and only visible by reading back the stored record. That inverts the usual guarantee that a non-zero exit is how you learn you got the syntax wrong.

Requests

1. Make docs --add reject an unrecognized key exactly the way files --add already does. The files error text is the model — it names the offending key and lists path, scope, note.
2. If leniency is intentional for bare values (a plain path with no =), keep that, but only for values containing no =. A value with an = whose left side is not an allowed key is a syntax error, not a path.
3. Consider naming consistency while touching this: files, docs, notes are plural, test is singular. pm test --add-json vs pm files --add is another spot where sibling commands diverge in a way agents have to memorize rather than infer.

Related

pm test --add has the adjacent hazard: the cohort convention command: "name=<title>,result=pass" embeds both , and =, so --add misparses it and --add-json is the only safe form. Same root cause — a CSV-ish --add parser meeting values that legitimately contain its delimiters.

Environment

pm-cli 2026.8.13, Node 22, Linux. Reproduced in a scratch pm init project with isolated HOME.