docs: reconcile port/unimplemented/absolute claims + storage caveats (7.2, 7.5, 7.6, 5.3, 5.6)

7.2 — cli.md notes the port is operator-chosen (loti init suggests 7000, the examples
use it; the sim uses a fixed 666) rather than implying a single canonical port.
7.5 — cli.md flags node start / --reference / config as planned-not-built and marks the
node-start transcript accordingly, so the command reference isn't read as all-implemented.
7.6 — README calls discoveries best-effort (can abort/expire/undetermined); the
'prove bounds for any event' goal is what a *found* chain guarantees, not that one is
always findable.
5.3 — cli.md: only clock-event storage is ring-pruned; published-event content is a
separate, unpruned store (a heavy publisher's disk grows), reported by db stat. Also
fixed the undefined 'a' in the precision formula to 1/C (matching theory.md).
5.6 — embedded.md documents that safe-mode per-commit fsync runs on the single reactor
thread and stalls networking under storage latency; lazy mode moves it off the hot path.

Author: levy

README.md

@@ -45,7 +45,11 @@ Start here depending on what you want:
 - **Event chain** — a hash-linked sequence `lowerBound · event · upperBound` that starts and
   ends at the querying node's own clock events and passes through the target event. It is a
   proof of that node's time bounds for the event.
-- **Discoveries** — three queries a node's *daemon* can run:
+- **Discoveries** — three queries a node's *daemon* can run. Each is **best-effort**: it succeeds
+  when a chain can be reconstructed and reverse-links have been learned, and otherwise aborts or
+  expires (an order query can also return `undetermined`). The "prove bounds for any event" goal
+  above is what a *found* chain guarantees; finding one is not guaranteed for every event at every
+  moment.
   - **event chain discovery** — reconstruct the enclosing chain for an event (routed to the
     event's creator and back, accreting each hop's clock events);
   - **event bounds discovery** — the enclosing chain's endpoint timestamps `(lower, upper)`;

doc/cli.md

@@ -99,11 +99,13 @@ verify offline** — plus persistence. All of the daemon promotions above are im
 **Retention.** `lotid` runs a fixed default schedule of several independent clock chains at
 geometrically spaced intervals (fastest first) instead of one; every published event pins into
 every chain at creation, and each chain is ring-pruned to a fixed capacity after each tick, so
-clock-event storage is **bounded** rather than growing with wall-clock time. This retires the
+**clock-event** storage is **bounded** rather than growing with wall-clock time. (Published-event
+*content* is a separate store and is **not** ring-pruned — a heavy publisher's disk still grows
+with what it publishes; `db stat` reports the event count.) This retires the
 earlier rule *local events and the local clock chain are never dropped*: the invariant now is
 that the local clock chain is never dropped **below the coarsest retained resolution** — every
-event stays boundable, at a precision that degrades to roughly `a/C` of its age (`C` = clock
-events kept per chain) rather than being lost. `db gc` from [Storage &
+event within the horizon stays boundable, at a precision that degrades to roughly `1/C` of its
+age (`C` = clock events kept per chain) rather than being lost. `db gc` from [Storage &
 maintenance](#storage--maintenance) is implemented — it re-asserts every chain's ring cap
 (normally a no-op, since the same pruning already runs after every clock tick); `db verify` is
 not implemented.
@@ -192,11 +194,17 @@ Human-readable tables by default; `--json` emits stable machine JSON. Standard e
 | `loti version` | Client + daemon version, protocol version, build info. |
 | `loti config get <key>` / `set <key> <value>` / `list` | Read/update configuration; `set` may require `loti node restart` for some keys (flagged in output). |
 
+The command tables above document the full **intended** surface; several rows — `node
+start`/`restart`, `config get/set/list`, and the `--reference <node>` flag — are **planned, not
+yet built** (see [Implementation status](#implementation-status-mvp)). Today you start the node by
+running `lotid` directly (see the Quickstart), and a proof is always anchored in the local node.
+The console transcripts below illustrate the intended experience, including planned commands.
+
 ```console
 $ loti init
 identity  node:9f3a…c1   (ed25519)
 home      ~/.loti
-$ loti node start
+$ loti node start   # planned; today run `lotid …` directly
 lotid started (pid 4821), listening udp/:4666, control ~/.loti/control.sock
 $ loti status
 node        node:9f3a…c1
@@ -433,7 +441,7 @@ loti verify order.loti
 | `home` | `~/.loti` | State directory. |
 | `identity.key` | `key.pem` | Signing key path. |
 | `identity.sign_events` | `true` | Sign published events. |
-| `network.listen` | `udp://:4666` | P2P transport bind address. |
+| `network.listen` | `udp://:4666` | P2P transport bind address. The port is operator-chosen (there is no protocol-mandated port); `loti init` suggests `7000` and the real-node quickstarts use it, while the OMNeT++ simulation uses a fixed `666`. |
 | `network.control` | `control.sock` | Local RPC socket for `loti`. |
 | `clock.interval` | `1s` | Clock-event creation interval. |
 | `discovery.expiry` | `1s`→`30s` | Discovery timeout before abort (raise for real WANs). |

doc/embedded.md

@@ -160,6 +160,13 @@ The database stays **crash-consistent** either way (LMDB is copy-on-write; witho
 window**: a crash in lazy mode may lose up to the last `<interval>` of commits — never the
 database's integrity. A clean shutdown and the `save` command always force a final flush.
 
+There is a second reason to prefer lazy mode on slow or high-latency storage: the daemon is
+single-threaded, so in the default **safe** mode the per-commit `fsync` runs *on the reactor
+thread* — while it blocks, no packets or control commands are serviced. On a busy SD card or
+network-backed disk that stall is visible. `--store-sync-interval > 0` moves the flush to a
+periodic timer, so a storage-latency spike no longer blocks networking. (Moving `fsync` to a
+background thread is a possible future improvement.)
+
 | `--store-sync-interval` | Behaviour | Crash risk |
 |---|---|---|
 | `0` (default) | fsync every commit | none (fully durable) |