0.1.14 — every artifact names its format, and - reads stdin

Every report now carries formatVersion. It is the first field under data, its value is the string "0", and it names the shape of the report document, as kitVersion names the kit that wrote it. When a run read a declaration or a recorded batch, the report echoes that document's own formatVersion as declaration.formatVersion and recordedSurfaces.formatVersion; both documents have always required the field, so the echo is present whenever the block is. A parser that refuses unknown keys breaks on these three additions. Fields are appended within a major and never renamed or removed, so tolerate unknown keys rather than pin to a key list.

acc report and acc compare refuse a report whose formatVersion is a major they do not know. The refusal is a usage error at exit 2, with details.reason unknown-format-major and two strings, details.formatVersion and details.understood, naming the document's major and this kit's. Nothing of the refused document reaches stdout. A report written before this release has no formatVersion and is still read, because every such file was written under major 0; the text prelude of acc report says format: not recorded for it and format: 0 for a report that carries the field.

The promised surface gains a row. formatVersion on the report, the declaration and a recorded batch, and a reader's refusal of a major it does not know, are on the stable side of the README's table; bumping a major is a breaking change. The unstable side is the shape within a major. The decision is the wiki page docs/wiki/decisions/every-artifact-names-its-format.md.

- names stdin on every file option:

• acc check --declaration - and acc check --recorded-surfaces -, one of them per run.
• acc probe-plan --declaration - and acc probe-plan --paths -. A source read from stdin is not in the tree, so the harness excludes no source file from its dirt check.
• acc report -. The rendering's source: line says /dev/stdin.
• acc compare - other.json, one of the reports. Its label in the comparison is stdin.

Each is refused when stdin is a terminal, at exit 2, reason stdin-is-a-terminal, before anything is read. Naming - twice in one invocation of check or compare is refused the same way, reason stdin-named-twice, also before anything is read. An invocation that passed a file literally named - now reads stdin instead; name that file ./-. The --help text of each option says that - reads stdin.

A /dev/fd/N path that does not exist gets a different hint. Under bunx, a descriptor opened by process substitution, --declaration <(your-cli schema), does not reach the process. The not_found error at exit 5 is unchanged; its hint now says the descriptor never arrived and names the two ways out: pipe the document and pass -, or run the installed bin, ./node_modules/.bin/acc.

The guide "How to establish your target is safe to check" has a fourth question: where the tool finds the tree it works on. A tool that resolves its root from its own install location, a marker file or a build-time path is not moved by the temporary working directory the probes run in, and the guide gives a hand run against the real tree for that case. The acc skill counts four questions with it.

The guide "How to derive your surface from one registry" changes its round trip to your-cli schema | acc check ./your-cli --declaration - and says what bunx does with a substituted descriptor. Its trap section adds that a help row declared and left permissive is listed as NOT COMPARED while the disagreement count stays 0, so the fix for such a help goes in the tool, not the declaration.

The pdocs adopter report, docs/reports/2026-09-07-the-pdocs-adopter-report.md, records the four findings from issue #49 and what was done about each.

0.1.14 (2026-09-08)

Features

• report: every artifact names its format, and a reader refuses a major it does not know (b478a4e)
• report: every artifact the kit writes names its format, and - reads a document from stdin (139b561)

Bug Fixes

• cli: a descriptor that never arrived is named as one, and - reads stdin (cdd138d)
• compare: compare reads - from stdin too, so the descriptor hint is true everywhere (d05b455)