docs(cmd): pilot the README-prose -> Long migration on app listing

[ZacxDev]

Pilot for the "move the README's command-reference prose into the cobra command
definitions" migration, scoped to one group before touching ~50 command files.
Also records what the scoping measured — including two findings that reverse the
plan's own premise.

This PR has been through an adversarial pre-merge audit. The audit falsified
three of my own claims; the corrections are commits abbdf26, 4429c8b, 953f1d9
and the numbers below are the post-fix, re-measured ones. See "What the audit
caught" at the bottom.

What the measurement found (whole tree, 53 nodes)

Fact	Measured
Nodes carrying an Annotations map	0 of 53
Nodes with NO Long at all	8
Nodes with a Long under 400 chars	16 more
README table cells, 16 matched rows	6,255 chars
Long on those same 16 nodes	19,017 chars

Long is already ~3x richer than the README table for the App-authoring
commands, so that half of the migration was largely already done. The real gap is
the public read-API group (models/images/collections/…), which owns 19 of the
24 empty-or-thin nodes and has no table row at all.

🔴 Annotations cannot reach the docs site — measured, not inferred

The docs generator captures exactly two channels per node (--help and
__complete) and parses the text. Cobra renders Annotations in neither. Probe on
workflows get: the value appears 1x in the binary (strings), 0x in
--help, 0x in __complete; positive control (a word that IS in that help)
1x. Recommendation: drop the Annotations half.

🔴 The blocker — now fixed upstream

gen-appblocks-cli.mjs:781 was description: short || parseLongDescription(help).split('\n')[0] || ''
— it parsed the whole Long and published only the Short. Measured: this PR's
new Long moved cli.json by +926 chars, all of it examples.
Fixed in civitai-developer-docs#49, which publishes longDescription on 52/52
commands (+76.9% artifact). Merge order does not matter — this PR stands alone for
terminal users, and gains a consumer once #49 lands.

What this PR changes — civitai app listing only

• set-icon / set-cover / add-screenshot gained a Long and an Example;
  they had neither, so --help printed a single Short line and the generator
  published a single line too.
• status / rm-screenshot / reorder gained an Example; reorder also states
  the positional-ordering rule.
• The accepted formats and per-kind byte caps appeared nowhere in the help
  surface — only in the README. They are now stated, and computed from
  maxIconBytes/maxCoverBytes/maxScreenshotBytes through the same humanBytes
  the refusal message uses, so --help predicts the error text.
• Three pre-existing body lines running past 80 columns are rewrapped.

--help cost, measured against current origin/main over all 54 captured nodes

47 nodes byte-identical, 7 changed. Tree 100,781 → 104,401 bytes (+3.6%),
1,990 → 2,068 lines (+3.9%).

Attribution was checked rather than assumed: an earlier capture showed 9 nodes
moving, and app metrics + root turned out to have moved under #268 (merged in),
not under this PR.

Guards

Four, none subsuming the others: caps-vs-constants in context (the group's
three caps are asserted next to the kind each applies to); kind-naming (each body
names its own asset and not a differently-capped sibling); formats-vs-decoder (a
real PNG/JPEG/WebP header through appapi.DecodeImageInfo, with a GIF negative
control); completeness (Long+Short+Example on every node, walking the real tree
with a count floor); and a budget (1400 chars / 80 columns, counting runes).

Mutation matrix — 13 killed, 1 declared-equivalent, null mutant survived.
Checksum-gated so a no-op edit reports NOT-APPLIED rather than surviving.

The one that does not die is the kindScreenshot→kindIcon swap, and it is an
equivalent mutant, proven: both render "2.0 MB", so the mutation produces a
different binary and byte-identical help (cmp, with the differing binaries as the
negative control). It becomes observable the moment the caps diverge — measured,
setting maxScreenshotBytes to 3 MiB under that mutation reddens with "does not
quote the cap it enforces (3.0 MB)". It is invisible exactly while it is harmless.

make ci green on the merged tree: 18/18 packages, 0 FAIL.

What the audit caught (all fixed here)

1. A false mechanism claim in shipped help. set-cover said its larger cap was
   "because a cover is stored at full resolution rather than inlined". runSetMedia
   sends cover and screenshot down the identical IngestAssetFullRes path while
   the screenshot keeps the icon's 2 MiB cap. Deleted.
2. A third copy of the exit-code contract. The group body hand-typed "(exit 2)",
   which exitcodes_doc.go exists to prevent, and dropped the exception both
   governed surfaces carry (an unreadable file exits 1 — AGENTS item 24). Verified
   on the binary: oversize/empty/non-image/directory/missing → 2, mode-000 PNG → 1.
   The sentence now names the checks and states no code.
3. Two guard holes, both measured surviving a green suite. humanBytes(icon) and
   humanBytes(screenshot) are the same string, so the group enforced only 2 of 3
   caps; and listingImageFormats was asserted against a Long built by
   interpolating that same constant — a constant compared with itself, which can
   never fail (narrowing it to "png or jpeg" and widening it to claim avif both
   survived). Both closed, both mutants now killed.
4. "Four pre-existing" was three. Corrected in the PR body, the handoff, and the
   guard's own comment, whose provenance claim was also wrong.

One defect found while fixing, not by the audit: the drift check's first GIF control
used gif.Encode, and importing image/gif registers the decoder package-wide,
which changed how generate --image refuses a GIF and reddened three unrelated
tests. The repo's own lockstep guard caught it. The control is hand-built bytes now.

🤖 Generated with Claude Code