chore: anti-slop cleanup pass over code and docs

docs/README.md

@@ -5,11 +5,10 @@ Alpine-first, and it manages each VM through a small `vm.toml` file instead of
 a system daemon or a virtualization stack like libvirt.
 
 stoat is for developers who want a disposable Linux VM (or a handful of
-persistent ones) on their own machine, driven entirely from the terminal. What
-sets it apart is what it *doesn't* need: no libvirt, no background daemon, no
-database, just a single Go binary that shells out to `qemu-system-x86_64`,
-`qemu-img`, and `ssh`, and a data root of plain files under `~/.stoat` (or
-`$STOAT_HOME`).
+persistent ones) on their own machine, driven entirely from the terminal.
+stoat needs no libvirt, no background daemon, and no database, just a single
+Go binary that shells out to `qemu-system-x86_64`, `qemu-img`, and `ssh`, and
+a data root of plain files under `~/.stoat` (or `$STOAT_HOME`).
 
 New here? Start with [Installation](getting-started/installation.md), then
 [Your first VM](getting-started/first-vm.md).

docs/concepts/access-and-auth.md

@@ -85,20 +85,19 @@ builds a very similar argument list: same host-key options, same
 `-i id_stoat`, same `root@127.0.0.1` target for live VMs, but deliberately
 **omits `BatchMode=yes`**. `Args` (used for unattended provisioning) needs SSH
 to fail immediately rather than block waiting for input that will never come.
-The interactive path hands the terminal to a real, attended `ssh` process, so
-if key auth doesn't work, for instance a disk-mode VM that was installed
+The interactive path hands the terminal to a real, attended `ssh` process.
+If key auth doesn't work, for instance a disk-mode VM that was installed
 manually and never had the key provisioned, SSH is free to fall back to
 prompting for a password at the terminal, the same as running `ssh` by hand.
 
 ## Why host key checking is off
 
 Both paths set `StrictHostKeyChecking=no` and `UserKnownHostsFile=/dev/null`.
-This is deliberate, not a shortcut: live Alpine VMs are rebuilt by stoat
+This is deliberate. live Alpine VMs are rebuilt by stoat
 constantly, and even with the stable guest host key described above, disk and
 cloud VMs generate their own host keys independently. Strict checking would
 mean a stale or mismatched `known_hosts` entry breaking a connection to a VM
-stoat just built, the kind of false alarm host-key checking exists to avoid,
-not the kind it's meant to catch.
+stoat just built: a false alarm, not an actual key mismatch.
 
 ## Passwords: console only, never over SSH
 
@@ -136,7 +135,7 @@ the detail screen:
 and in the log line written when the VM starts, which you can read with
 `stoat logs`.
 
-### Why a fixed default is not a compromise
+### Why a fixed default is safe
 
 You end up at that console precisely when SSH *isn't* working, which is the
 worst possible moment to go and look a credential up. And it is no weaker

docs/concepts/data-root.md

@@ -40,7 +40,7 @@ than an error.
             └── meta-data
 ```
 
-A couple of things worth calling out about that tree:
+Two facts about that tree:
 
 - `isos/` holds both plain ISOs (Alpine) and downloaded cloud images
   (Ubuntu/Debian/Fedora/Arch `.qcow2`/`.img` files). A `cloud` VM's
@@ -81,8 +81,7 @@ Each VM directory holds one `vm.toml`. Every field:
 
 `vm.toml` is a plain TOML file and nothing stops you from editing it directly
 while the VM is stopped: stoat re-reads it fresh every time, there's no
-cache to invalidate. That said, some fields are much safer to touch than
-others:
+cache to invalidate. Some fields are safer to edit than others:
 
 - **Safe-ish**: `ram`, `cpus`, `share`, `recipes` (as long as the filenames
   still exist under `recipes/`), `sshuser`.

docs/concepts/modes-and-backends.md

@@ -10,13 +10,10 @@ related but not the same thing:
   what its start logic checks before launching a VM.
 - **Backend** (`vm.toml`'s `backend` field) records how the create form
   picked recipes and provisioning at creation time. Once the VM exists,
-  nothing at runtime dispatches on this field: it's informational, not
-  load-bearing.
+  nothing at runtime dispatches on this field: it's informational.
 
-If you only remember one thing from this page: **`disk` mode gives you no
-SSH access until you install an OS yourself and tell stoat so.** That single
-fact trips up more people than everything else in this tool combined, so it
-gets its own section below.
+**`disk` mode gives you no SSH access until you install an OS yourself and
+tell stoat so.** See the section below.
 
 ## The three modes
 
@@ -27,7 +24,7 @@ into RAM: the root filesystem is an Alpine initramfs overlay, and nothing
 about it is written anywhere persistent. Stop or reboot the VM and you get a
 clean slate next time.
 
-What makes `live` mode useful rather than just a toy: every time you start
+What makes `live` mode useful: every time you start
 one, stoat builds a small Alpine overlay tarball (an "apkovl") and hands it to
 the guest as a fake FAT disk over `-virtfs`/vvfat. That overlay bakes in:
 

docs/concepts/networking-and-sharing.md

@@ -63,9 +63,6 @@ Whether the share actually gets *mounted* inside the guest depends on mode:
 
 ## Sharing a binary built on the host: the musl/glibc trap
 
-This is the single most confusing failure mode around the share feature, so
-it gets called out explicitly.
-
 If you build a binary on a typical glibc-based Linux host (Arch, Fedora,
 Ubuntu, Debian) and drop it into your shared directory expecting to run it
 straight from `/mnt/host` inside an **Alpine** guest (the default for `live`

docs/design/core-api.md

@@ -157,7 +157,7 @@ The TUI keeps its prompt and passes the answer. The MCP server requires the agen
 
 ## 7. Convenience operations
 
-These are the "quick VM-based testing" features that make stoat pleasant rather than merely functional. All are cheap because of what QEMU and qcow2 already give us.
+These are the "quick VM-based testing" features that make stoat pleasant to use. All are cheap because of what QEMU and qcow2 already give us.
 
 | Operation | Signature | Why it earns a slot |
 |---|---|---|
@@ -282,7 +282,7 @@ The mechanism that does work is `security_model=mapped-xattr`, which stores *"ui
 
 ### 10.3 MCP tool taxonomy
 
-Three classes, annotated honestly and, crucially, enforced independently of whether the client honours the annotation.
+Three classes, annotated honestly and enforced independently of whether the client honours the annotation.
 
 | Class | Tools | Annotations | Server-side rule |
 |---|---|---|---|

docs/design/guest-subsystem.md

@@ -358,11 +358,11 @@ These are requirements the TUI never forced, and each one is a real change:
 
 **Declarative creation.** One `Create(Spec)` call, no multi-step form state. Everything the form asks for either has a default or is in the `Spec`.
 
-**Recipe metadata becomes load-bearing.** §5's `# stoat:os` / `# stoat:requires`, enforced at selection, is *optional politeness* for a human who can read a black screen and *mandatory* for an agent that cannot. `Create` returns `ErrRecipeNotApplicable` rather than producing a VM that boots broken. This is the strongest argument for the departure from prior art in §2.
+**Recipe metadata now gates VM creation.** §5's `# stoat:os` / `# stoat:requires`, enforced at selection, is *optional politeness* for a human who can read a black screen and *mandatory* for an agent that cannot. `Create` returns `ErrRecipeNotApplicable` rather than producing a VM that boots broken. This is the strongest argument for the departure from prior art in §2.
 
 **Cancellation.** Every operation takes a `context.Context`. Downloads and boot-waits are long; an agent that abandons a task must be able to stop them. Today `esc` leaves a download goroutine running (a known open item).
 
-### 9.5 Concurrency: new, and load-bearing
+### 9.5 Concurrency: new, and required once a second caller exists
 
 A TUI has one user doing one thing. An MCP server plus a TUI plus a CLI can act **at the same time**, and two current mechanisms are not safe under that:
 
@@ -407,6 +407,6 @@ If any of these needs logic that is not already in `core`, the layering is wrong
 ## 10. Risks
 
 - **This is a real refactor**, touching `qemu`, `cloudinit`, `apkovl`, `recipes`, `iso` and `tui`. The mitigation is that behaviour must not change except where a bug is named here: existing tests are the contract, and any test that needs updating is a signal to stop and check rather than to edit.
-- **`Backend.Prepare`'s call frequency differs by backend** (apkovl every boot; cloudinit once, ever). That asymmetry is load-bearing: a cloud VM whose seed is rebuilt would have its instance identity change under it. The interface hides it, which is right, but the implementations must be explicit about it and tested for it.
+- **`Backend.Prepare`'s call frequency differs by backend** (apkovl every boot; cloudinit once, ever). A cloud VM whose seed is rebuilt would have its instance identity change under it. The interface hides it, which is right, but the implementations must be explicit about it and tested for it.
 - **`cloud-init schema` may be absent** on the host (Arch does not install cloud-init by default). Validation must degrade to "not checked", never to "assumed valid".
 - **The merge-semantics change is silent when wrong.** Packages that quietly stop being installed look like a recipe bug, not a merge bug. Needs a direct test.

docs/design/tui-migration-draft.md

@@ -440,7 +440,7 @@ original and is fine), `vmlist.go`'s delegate and every width constant,
 `app.go`'s `View`/`newView`/`renderModal` compositing, `list.go brokenReason`,
 `access.go`'s `shortenPath`/`joinAccess`.
 
-**Every width constant is load-bearing and has a story:** `listWidth = 60`
+**Every width constant has a story:** `listWidth = 60`
 (sized to a running row), `formContentWidth = 72` (sized to fit 80 columns),
 `byoFileWidth = 24`, `imageMetaWidth = 11` (sized to `"13 (trixie)"`),
 `modalSizeWidth = 9` (sized to `"~66.0 MiB"`), `accessWidth = 40`,

docs/recipe-authoring-spec.md

@@ -20,9 +20,8 @@ and survives upgrades.
 named `mything.alpine.sh` and it appears in the picker for Alpine VMs. No code
 required. Any "creator" competes with `$EDITOR` on a path that already works.
 
-So the question is not "can we add a creator" but "what does a creator do that
-`vim ~/.stoat/recipes/x.alpine.sh` doesn't". Three honest candidates below,
-smallest first.
+The question is what a creator does that `vim ~/.stoat/recipes/x.alpine.sh`
+doesn't. Candidates below, smallest first.
 
 ---
 

docs/reference/cli.md

@@ -399,7 +399,7 @@ broken vm: /home/user/.stoat/vms/oldvm
 partial download: /home/user/.stoat/isos/ubuntu-24.04.iso.part
 ```
 
-`--broken` additionally considers VMs whose `vm.toml` won't parse for removal; `--images` additionally considers downloaded images no VM refers to. Without either, `prune` only reports partial downloads by default (broken VMs and orphaned images need to be asked for explicitly). Printing an identical list for the dry run and the real run is deliberate: the two are meant to be readable as the same thing, one with the deletions actually applied.
+`--broken` also considers VMs whose `vm.toml` won't parse for removal; `--images` also considers downloaded images no VM refers to. Without either, `prune` only reports partial downloads by default (broken VMs and orphaned images need to be asked for explicitly). Printing an identical list for the dry run and the real run is deliberate: the two are meant to be readable as the same thing, one with the deletions actually applied.
 
 **Exit codes:** 0 on success, including "nothing to prune"; 1 if pruning fails.
 
@@ -567,7 +567,7 @@ A usage error (2) always prints both the specific complaint and the full usage t
 ## Scripting
 
 - **`-q`, `--quiet`, `--no-interactive`** are three names for the same flag, present on every subcommand. Where it has an effect, it suppresses the "in-progress" chatter (`starting work...`, `provisioning work...`, ...); final results and all errors print regardless of this flag.
-- **`rm`** additionally treats `--no-interactive`/`-q`/`--json` as "there is no one to answer a confirmation prompt": without `-y` it refuses rather than blocking on stdin.
+- **`rm`** also treats `--no-interactive`/`-q`/`--json` as "there is no one to answer a confirmation prompt": without `-y` it refuses rather than blocking on stdin.
 - **`--json`** is the machine-readable mode: one JSON object per line on stdout, errors included, implying `--quiet` and never prompting. See [json.md](json.md) for the wire format.
 - **`NO_COLOR`** (any non-empty value) disables ANSI color in `ls`'s output.
 - Color is also **disabled automatically whenever stdout is not a terminal** (checked via `os.ModeCharDevice`), so piping `stoat ls` into `awk`, `grep`, or a file never carries escape codes even without setting `NO_COLOR`. Only `ls`'s `STATE` column is ever colored.

docs/reference/json.md

@@ -48,8 +48,7 @@ Four rules make it work:
 Rule 3 is not a preference. A consumer that must merge two pipes to
 reconstruct one result will eventually interleave them wrong, and a naive
 `subprocess` read of two pipes in sequence deadlocks when either buffer fills.
-The error envelope is the answer to the question that was asked, not a
-diagnostic.
+The error envelope answers the question that was asked.
 
 ## The envelope