docs: tighten deployment runbooks

README.md

@@ -6,6 +6,48 @@ documents, blobs, pipes, and future multi-user collaboration.
 This project is not the Ethereum `geth` client. The project and executable are
 still named `geth`.
 
+## First 10 Minutes
+
+Build the single binary, initialize an isolated home, start the daemon, and
+verify the local control path:
+
+```sh
+cargo build -p geth
+export GETH_HOME="$(mktemp -d)"
+printf 'GETH_HOME=%s\n' "$GETH_HOME"
+./target/debug/geth init
+./target/debug/geth daemon run
+```
+
+Keep the daemon running. In a second shell, reuse the printed `GETH_HOME` value:
+
+```sh
+export GETH_HOME="<same directory>"
+./target/debug/geth wait daemon --timeout-ms 30000
+./target/debug/geth status --json
+./target/debug/geth doctor --json
+```
+
+This creates a local-only identity for evaluation. Before enrolling other
+machines, use the owner setup in `geth guide owner-setup`; it records an
+OpenSSH admin public key as the trust anchor and signs the initial keychain
+statements without copying the private key into geth state.
+
+Start with these documents when moving beyond the local smoke test:
+
+- [`docs/architecture.md`](docs/architecture.md): ownership, trust, transport,
+  and module boundaries.
+- [`docs/command-stability.md`](docs/command-stability.md): commands suitable
+  for automation and commands that remain experimental.
+- [`docs/compatibility.md`](docs/compatibility.md): CLI, JSON, protocol, store,
+  and signed-operation compatibility rules.
+- [`docs/automation-examples.md`](docs/automation-examples.md): shell, Python,
+  and user-service examples.
+- [`docs/production-readiness-roadmap.md`](docs/production-readiness-roadmap.md):
+  the pre-deployment gate and its current status.
+- [`docs/dogfood-checklist.md`](docs/dogfood-checklist.md): required
+  two-machine evidence before broader deployment.
+
 ## One Binary
 
 There is one executable: `geth`.
@@ -85,7 +127,7 @@ a binary OpenSSH KRL generated through `ssh-keygen -k`. `geth ssh cert sync
 `geth ssh revocation sync <node-id>` pull certificate-flow and revocation
 metadata from an authorized peer over Iroh.
 
-## MVP Features
+## Current Feature Surface
 
 The bootstrap implementation provides:
 

docs/dogfood-checklist.md

@@ -6,6 +6,34 @@ on two real machines before the first broader deployment. Do not mark the Phase
 10 roadmap item complete until every checkbox here has a date, platform, geth
 version or commit, and evidence note.
 
+Create one evidence directory per run and keep raw JSON, command transcripts,
+and relevant redacted logs there. Do not store bearer tokens, private keys, or
+unencrypted backup contents in the evidence directory. A run is reviewable only
+when its evidence can be tied to the matrix and sign-off records below.
+
+## Evidence Log
+
+Copy this table for each attempt. Use ISO 8601 timestamps and paths or issue
+links that another reviewer can open.
+
+| Field | Machine A | Machine B |
+| --- | --- | --- |
+| Run ID | `<YYYYMMDD-sequence>` | `<same run ID>` |
+| Started at | `<timestamp>` | `<timestamp>` |
+| Platform/architecture | `<value>` | `<value>` |
+| geth version/commit | `<value>` | `<value>` |
+| Install method/artifact checksum | `<value>` | `<value>` |
+| Fresh `GETH_HOME` | `<path or identifier>` | `<path or identifier>` |
+| Command transcript | `<path or link>` | `<path or link>` |
+| JSON and log evidence | `<path or link>` | `<path or link>` |
+| Result | `pass` / `fail` / `incomplete` | `pass` / `fail` / `incomplete` |
+
+Record each failed or skipped step separately:
+
+| Timestamp | Machine | Step | Result | Evidence | Follow-up |
+| --- | --- | --- | --- | --- | --- |
+| `<timestamp>` | `A` / `B` | `<section and command>` | `<result>` | `<path or link>` | `<issue or action>` |
+
 ## Test Matrix
 
 - `[ ]` Machine A platform, architecture, geth version/commit, and install
@@ -80,7 +108,9 @@ On Machine A:
 
 ```sh
 geth kv create prefs
+geth kv set prefs theme dark
 geth document create notes
+geth document set notes '{"purpose":"dogfood"}'
 geth cas add README.md
 geth pipe listen ops
 geth auth grant <worker-node-id> resource:kv:prefs kv.read --signing-key ~/.ssh/id_ed25519 --grant-id dogfood-kv-read
@@ -95,22 +125,45 @@ On Machine B:
 ```sh
 geth auth sync owner
 geth kv sync owner prefs
+geth kv get prefs theme
 geth document sync owner notes
+geth document get notes
 geth cas fetch owner <hash>
 geth pipe send ops "dogfood" --node owner
-geth ssh proxy owner
 geth sync now owner
 geth sync status --json
 ```
 
+Back on Machine A, verify the pipe payload:
+
+```sh
+geth pipe recv ops
+```
+
+Verify the SSH proxy with a bounded OpenSSH probe from Machine B. Replace
+`<ssh-user>` with an account accepted by Machine A's local SSH service:
+
+```sh
+ssh -o BatchMode=yes -o ConnectTimeout=10 \
+  -o 'ProxyCommand=geth ssh proxy owner' \
+  <ssh-user>@owner true
+```
+
+An authentication failure after the SSH handshake is sufficient to prove byte
+transport when Machine A intentionally has no matching SSH credential; record
+the verbose `ssh -v` transcript. A timeout or geth authorization error is not a
+successful proxy check.
+
 Acceptance:
 
 - `[ ]` Auth sync imports the expected grants.
-- `[ ]` KV sync imports `prefs`.
+- `[ ]` KV sync imports `prefs` and Machine B reads `theme=dark`.
-- `[ ]` Document sync imports `notes`.
+- `[ ]` Document sync imports the `{"purpose":"dogfood"}` state.
 - `[ ]` CAS fetch retrieves the expected blob.
-- `[ ]` Pipe send reaches the Machine A daemon-lifetime listener.
+- `[ ]` Pipe send reaches the Machine A listener and `pipe recv` returns the
-- `[ ]` SSH proxy opens only after `ssh_proxy.connect` is granted.
+  exact payload.
+- `[ ]` The bounded SSH probe reaches Machine A's SSH handshake only after
+  `ssh_proxy.connect` is granted.
 - `[ ]` `geth sync status --json` reports healthy or intentionally skipped
   streams with actionable `next_action` values.
 
@@ -186,3 +239,9 @@ Acceptance:
 - `[ ]` Evidence is attached for Machine B.
 - `[ ]` Phase 10 in `docs/production-readiness-roadmap.md` is marked complete
   only after the real-machine evidence is reviewed.
+
+| Role | Name | Timestamp | Run ID | Result |
+| --- | --- | --- | --- | --- |
+| Operator A | `<name>` | `<timestamp>` | `<run ID>` | `<result>` |
+| Operator B | `<name>` | `<timestamp>` | `<run ID>` | `<result>` |
+| Reviewer | `<name>` | `<timestamp>` | `<run ID>` | `approved` / `rejected` |

docs/production-readiness-roadmap.md

@@ -41,6 +41,8 @@ behavior.
     endpoint ownership live outside the main feature handler module.
   - `[x]` Iroh accept-loop and background live-sync task spawning live outside
     the main feature handler module.
+  - `[x]` Graceful shutdown cancels daemon tasks, closes the shared Iroh
+    endpoint explicitly, and removes the local control socket.
   - `[x]` Runtime state is represented by narrow structs with documented
     ownership and locking rules.
   - `[x]` Existing daemon startup and status tests pass unchanged.
@@ -334,6 +336,14 @@ platform/version details, and evidence for this gate. This phase cannot be
 marked complete from local unit or integration tests alone; it requires two real
 machines and tagged pre-release upgrade evidence.
 
+- `[x]` Prepare the dogfood runbook and evidence format.
+  Acceptance criteria:
+  - `[x]` Runbook commands are checked against the current CLI command tree.
+  - `[x]` Positive paths verify transferred data, not only command exit status.
+  - `[x]` Streaming checks are bounded or have explicit completion criteria.
+  - `[x]` Evidence records capture platform, artifact, version, timestamp,
+    result, and follow-up details without collecting private material.
+
 - `[ ]` Complete two-machine dogfood checklist.
   Acceptance criteria:
   - `[ ]` Fresh install works on at least two real machines.

docs/roadmap.md

@@ -1,7 +1,10 @@
 # Roadmap
 
-This roadmap is intended to be checkable. Each item should either be completed
+This is the long-term product and feature roadmap. It is intentionally broader
-with tests/docs or split into smaller items before implementation.
+than the pre-deployment hardening effort, so unchecked items here do not imply
+that a completed production-readiness phase has regressed. Each item should
+either be completed with tests/docs or split into smaller items before
+implementation.
 
 Status markers:
 
@@ -93,10 +96,11 @@ admin devices without depending on one always-online coordination server.
     equivalent to Keyhive/BeeKEM, WireGuard, NetBird, or Tailscale unless those
     properties are actually implemented and tested.
 
-## Prototype Viability Closure Plan
+## Initial Viability Closure Plan
 
-These are the remaining gaps that must close before the prototype is a smooth
+These items established a smooth end-to-end test target for the intended
-end-to-end test target for the intended personal mesh use cases.
+personal mesh use cases. The cross-cutting pre-deployment requirements and the
+remaining real-machine gate are tracked in the production-readiness roadmap.
 
 Implementation order:
 
@@ -168,7 +172,7 @@ Implementation order:
   - `[x]` Tests assert conflicting replicated keychain/auth records do not
     mutate local trust or resource state.
 
-- `[~]` Remote authorization enforcement audit.
+- `[x]` Remote authorization enforcement audit.
   Acceptance criteria:
   - `[x]` Every remote mutable operation has an explicit resource capability
     check before mutating local state or opening a host service, or is
@@ -176,7 +180,7 @@ Implementation order:
   - `[x]` A test-backed remote guard matrix documents the expected guard for
     each remote operation and fails if mutating/service-opening operations rely
     on discovery alone.
-  - `[ ]` Tests cover denied and allowed paths for CAS, KV, DB, document,
+  - `[x]` Tests cover denied and allowed paths for CAS, KV, DB, document,
     pubsub, pipe, SSH proxy/admin shell, SSH cert metadata, and revocations.
   - `[x]` Initial two-daemon denied-mutation coverage exists for remote pubsub
     publish, remote pipe listen, and SSH admin shell.