two docs described the sync and the release as they were an hour ago

README's verb list still said `kuma sync` converges, which stopped being
the whole story when both syncs lost their argument list. `--help` and
concepts.md were updated with that change; the one-line summary a reader
skims first was not.

CONTRIBUTING's release steps omitted the lock. Cargo.lock records the
workspace member's own version, so bumping Cargo.toml alone leaves the
two disagreeing and every `--locked` call fails, which is most of CI.
That is not a hypothetical: it happened on the v0.3.0 bump and only a
local rehearsal caught it before the push. The example version moves to
v0.4.0 too, since quoting the release that already exists reads like a
record rather than an instruction.

Deliberately not changed: the `kuma diff` transcript in concepts.md
still reads "converge now; otherwise the boot/daily run picks this up",
because that is inspect.rs:365 verbatim. Editing the doc alone would
make it misquote real output, and the affordance is contextual advice
about resolving the drift on screen rather than a description of
everything sync does.

Author: Letdown2491

CONTRIBUTING.md

@@ -29,16 +29,22 @@ A separate job runs `cargo audit` against the committed `Cargo.lock`, on every
 push and again weekly, because a dependency becomes vulnerable when the
 advisory lands rather than when someone next touches the tree.
 
-**Cutting a release.** Bump `version` in `Cargo.toml`, commit it, then tag:
+**Cutting a release.** Bump `version` in `Cargo.toml`, refresh the lock,
+commit both, then tag:
 
 ```console
-$ git tag -a v0.3.0 -m "kuma v0.3.0"
-$ git push origin v0.3.0
+$ cargo update -p kuma --offline   # Cargo.lock records kuma's own version
+$ git tag -a v0.4.0 -m "kuma v0.4.0"
+$ git push origin v0.4.0
 ```
 
-The tag and `Cargo.toml` have to agree. The release workflow checks and
-fails rather than publishing a binary whose own `--version` contradicts the
-release it sits in.
+`Cargo.lock` is not optional here. It carries the workspace member's version
+too, so bumping only `Cargo.toml` leaves the lock disagreeing and every
+`--locked` call fails, which is most of CI.
+
+The tag and `Cargo.toml` have to agree as well. The release workflow checks
+and fails rather than publishing a binary whose own `--version` contradicts
+the release it sits in.
 
 Push to `main` first and let it go green. A push that touches anything
 other than documentation refreshes the rolling `latest` prerelease, and it

README.md

@@ -141,7 +141,7 @@ $ kuma capture                             # declare what this machine already r
 $ kuma check                               # validate the declaration, build nothing
 $ kuma diff                                # drift: kuma.toml vs image vs machine
 $ kuma doctor                              # machine health, /etc drift, snapshots, GPU, disk
-$ kuma sync                                # converge flatpaks and brew now
+$ kuma sync                                # converge, and update everything installed
 $ kuma snapshot                            # the btrfs snapshots this machine has taken
 $ kuma snapshot --restore ~/notes.md       # bring a path back (dry run; --yes writes)
 $ kuma update --check                      # has the locked base moved?