Polish first-run operator workflow

README.md

@@ -447,9 +447,82 @@ operation log, not yet a CRDT or Keyhive-style convergent authority.
 The daemon also runs best-effort live sync for imported peers. `geth sync now
 [node]` triggers the same sync pass immediately, and `geth sync status` reports
 the last local attempt, success, cursor, import count, rejection count, and
-error per peer stream. Keychain and auth sync now use per-peer high-water
-cursors, while receivers still verify every imported signed operation before it
-can affect the reduced keychain or authorization views.
+error per peer stream. `geth sync status --json` also includes per-stream
+`state`, `stale`, `stale_after_ms`, and `next_action` fields so smoke tests can
+fail on stale or failed streams. Keychain and auth sync now use per-peer
+high-water cursors, while receivers still verify every imported signed operation
+before it can affect the reduced keychain or authorization views.
+
+## Two-Machine Smoke Test
+
+Use two terminals or machines with different `GETH_HOME` values.
+
+Owner machine:
+
+```sh
+export GETH_HOME=/tmp/geth-owner
+geth init --admin-key ~/.ssh/id_ed25519_sk.pub \
+  --signing-key ~/.ssh/id_ed25519_sk \
+  --node-name owner
+geth daemon run
+geth peer export --out /tmp/owner.peer.json
+```
+
+New node:
+
+```sh
+export GETH_HOME=/tmp/geth-node
+geth init
+geth daemon run
+geth keychain init --admin-key ~/.ssh/id_ed25519_sk.pub
+geth peer import /tmp/owner.peer.json
+geth node enroll request --node-name workstation \
+  --capability resource:cas:local=cas.fetch \
+  --capability resource:kv:notes=kv.read \
+  --capability resource:document:notes=document.read \
+  --capability resource:db:notes=db.sync \
+  --capability resource:ssh-proxy:local=ssh_proxy.connect \
+  --out /tmp/workstation-enrollment.json
+geth node enroll submit owner --path /tmp/workstation-enrollment.json
+```
+
+Owner machine:
+
+```sh
+geth node enroll list --status pending
+geth node enroll approve <request-id> --signing-key ~/.ssh/id_ed25519_sk
+geth node grant workstation resource:ssh-proxy:local ssh_proxy.connect \
+  --signing-key ~/.ssh/id_ed25519_sk
+echo "hello geth" > /tmp/hello-geth.txt
+geth cas add /tmp/hello-geth.txt
+geth kv create notes
+geth kv set notes greeting "hello geth"
+geth document create notes
+geth document set notes '{"greeting":"hello geth"}'
+geth ssh cert requests
+```
+
+New node:
+
+```sh
+geth sync now owner
+geth sync status --json
+geth peer ping owner
+geth cas fetch owner <hash-from-owner-cas-add>
+geth kv sync owner notes
+geth kv get notes greeting
+geth document sync owner notes
+geth document get notes
+geth db add notes /path/to/crsqlite-notes.sqlite
+geth db sync owner notes
+geth ssh cert request --public-key ~/.ssh/id_ed25519.pub --principal "$USER"
+geth ssh cert sync owner
+geth ssh proxy owner
+```
+
+If a command fails, the daemon error includes a `next:` line for common recovery
+paths such as importing a peer card, running `auth explain`, granting a missing
+capability, or creating/registering a missing resource.
 
 ## Authorization Direction