the README teaches a defect and hides four flags

[haribo]

Why

Three statements in the user-facing docs, each verified against the code.

1. README.md:214 teaches the defect of #486. The tutorial def is:

def install(pkg: str) as root {
  observe {
    return state(installed: shell { dpkg -s "$pkg" >/dev/null 2>&1 }.exit == 0)
  }

The real apt.install carries, in its own source, the reason that is wrong:

dpkg -s was the wrong question: it exits 0 for a package in state rc — removed
without --purge, so its record and config files survive while its binaries are gone —
and the def then reported already on a host where the package was not installed.

So the README hands a newcomer, as the model to copy, the exact observe that cost #486 —
the first instance of the class this project has now paid for six times.

2. Four real flags are documented nowhere. --json, --parallel, --limit appear in
neither README.md nor docs/language.md, and -v only as a badge URL. All four are
accepted by run.

3. README.md:160 is stale. "at-rest secrecy is not yet solved" — ADR-0025 put the
workdir on tmpfs precisely so that "secret plaintext … never touch persistent disk: not in
a root-filesystem backup, not in a disk snapshot, and not recoverable by undelete." What
remains true is the sentence before it: root on the target can read the secret in memory and
in the process environment. The limit is real; its name is wrong.

Not in this issue

• docs/design/inventory.md was corrected in the README and inventory design doc contradict the binary #602 and carries its superseded note.
• docs/dogfood.md is a dated report of an experiment, not a document that drifts. An
  external review called it stale; it is not, it is history, and history is allowed to
  describe a world the code has left.
• language.md having no chapter for on, parallel or the inventory is real but larger
  than a correction: those live in docs/design/orchestration.md, so it is a question of
  what the language spec is for. Its own header declares only as <user> as missing, which
  understates it — worth its own issue.

Build

• Replace the README's dpkg -s example. The point it illustrates (an observe that asks a
  question) does not need the wrong question — command -v, or the real apt.install
  spelling, teaches the same thing without teaching the bug.
• Document --json, --parallel, --limit, -v where the other flags are.
• Rewrite the secrecy limit to say what is actually unsolved: a secret in memory and in the
  environment on the target, readable by root there.

Validation

• grep -n "dpkg -s" README.md returns nothing.
• Every flag runCmd registers appears in README.md — checked by loop against the source,
  not by eye.
• grep -n "at-rest secrecy is not yet solved" README.md returns nothing, and what replaces
  it does not contradict ADR-0025.

[haribo]

Audit against the current code and docs

All three claims confirmed.

1. README.md:214 is return state(installed: shell { dpkg -s "$pkg" >/dev/null 2>&1 }.exit == 0).
The real def, internal/std/apt/install.shellf:5-14, replaced exactly that line and carries the
reason in its source: dpkg -s exits 0 for a package in state rc, so the def reported
already on a host where the package was gone — and the answer was stable, so both runs of
the idempotence sweep agreed (#486). The README hands that question to a newcomer as the model.

2. cmd/shellf/main.go:156-174 — runCmd registers 14 flags. The table at
README.md:344-354 lists 9. The four missing are --json (main.go:164), -v (:165),
--parallel (:172) and --limit (:174). Nothing else is missing, and nothing listed is
gone. grep over docs/ finds none of them either — the only hit is an unrelated
docs/adr/0046-mit-license.md.

The 14th is --check (main.go:168), registered with an empty usage string so it stays out
of -h: it exists only to tell an operator that the flag is now --dry-run (ADR-0035). It must
stay undocumented, which is a caveat for this issue's Validation loop — "every flag runCmd
registers appears in README.md" would demand a row for a flag whose whole purpose is to not
have one.

3. README.md:158-160 says "the secret still reaches the target (in the request file,
0600, and the process env) — root there can read it; at-rest secrecy is not yet solved."
ADR-0025 is titled "Secrets at rest: deposit the workdir on tmpfs", its status line reads
"Closes the at-rest residual left open by ADR-0018", and §1 says the plaintext therefore
"never touch[es] persistent disk: not in a root-filesystem backup, not in a disk snapshot, and
not recoverable by undelete." The sentence before it in the README is the part that is still
true, and ADR-0025's own Consequences say so: "root on the target reads tmpfs and /proc in
real time."

One precision the issue does not carry, and the fix must: ADR-0025 §3 falls back to /tmp
when /dev/shm is not writable, and the run proceeds with the old residual. A replacement
saying flatly "the secret never touches disk" would be wrong on such a host.

One correction to the Build section

command -v, or the real apt.install spelling, teaches the same thing without teaching the
bug.

command -v "$pkg" is a second wrong question wearing a different hat: the def's parameter is a
package name, and a package is not always a binary of the same name — apt.install("curl")
would work by luck, apt.install("ca-certificates") would never converge. The example should
carry the spelling the stdlib actually ships,
dpkg-query -W -f='${Status}' "$pkg" | grep -q '^install ok installed', which is both correct
and the thing a reader will meet in the source.

Found on the way, not in this issue

README.md:39 tells a newcomer to gh release download v0.10.0 — three releases behind. Not a
false statement (the paragraph is about SHA256SUMS, published from v0.10.0), but the copyable
line installs an old binary. Worth its own issue if the fix is to be more than a bump.

[haribo]

Delivered in #645, squashed to 6616a2f on develop.

• The def example carries apt.install's real observe plus the paragraph that makes it a
  lesson. Not command -v, which this issue proposed and which is a second wrong question —
  the parameter is a package name, so it would work for curl and never converge for
  ca-certificates.
• --json, -v, --parallel, --limit are in the flag table, with a line saying which
  command takes what. --check stays out, deliberately.
• The secrets note states the live-root limit and keeps ADR-0025 §3's /tmp fallback.

Validation

The example was extracted from README.md verbatim into a project and run against a real
Debian target — nothing validates README snippets today:

1. dry-run, host without nano    would.installed
2. apply                         ok.installed
3. re-apply                      ok.already
4. apt-get remove nano (no --purge)
   dpkg -s still exits 0 (the trap)     dpkg-query → deinstall ok config-files
5. dry-run again                 would.installed     ← the old spelling said `already` here

The flag claim is checked by loop against cmd/shellf/main.go: every flag runCmd,
statusCmd and cleanCmd register appears in README.md, check excepted.
grep -c "at-rest secrecy is not yet solved" README.md → 0.