docs: add mode selection guidance for mirror resolver and thin

1 files changed, 43 insertions, 17 deletions

diff --git a/README.md b/README.md
index a92449a..65864ac 100644
--- a/README.md
+++ b/README.md
@@ -196,23 +196,6 @@ See [`config.default.yaml`](./config.default.yaml). Core knobs:
 - `rate_limit.*`
 - `request_timeout`
 
-## Thin Mode Tradeoffs
-
-Thin mode is designed for minimal disk usage and on-demand verification:
-
-- No `/export` polling or global ingest loop.
-- No operation block archive or full historical index.
-- DID state is fetched per DID from upstream (`/{did}/log`), fully signature/prev verified locally, then cached in Pebble.
-- Cache persistence scales with requested DID count, not total PLC history.
-- Checkpoint proofs are not available in thin mode: `GET /did/{did}/proof` returns `501 Not Implemented`.
-
-Example thin-mode run:
-
-```bash
-PLUTIA_MODE=thin task build
-./bin/plutia serve --config=config.default.yaml
-```
-
 ### Example `docker-compose.yml`
 
 ```yaml
@@ -235,6 +218,49 @@ services:
 - Keep the same `mode` per data directory across restarts.
 - Upgrade binaries first in staging, then production using the same on-disk data.
 
+## Which Mode Should I Run?
+
+| Mode | Disk Usage (at current PLC size) | CPU Usage | Ingestion Behavior | Verification Guarantees | Historical Archive? | Checkpoint Proof Support? | Recommended For |
+|---|---|---|---|---|---|---|---|
+| `mirror` | ~1.17 KB/op (~100 GB at current PLC head) | High sustained | Continuous full replay + polling | Full chain verification at ingest (`verify=full`), deterministic state, signed checkpoints | Yes | Yes | Independent mirrors, auditors, proof-serving infrastructure |
+| `resolver` | ~0.8 KB/op (~60–70 GB at current PLC head) | Medium to high sustained | Continuous replay + polling, state-only storage | Full verification supported; stores resolved state without full block archive | No | No | Operators who want full verification with lower storage overhead |
+| `thin` | ~475 bytes per cached DID (scales with active usage, not global PLC size) | Low idle, bursty on requests | No global replay; fetches and verifies per DID on demand | Full chain verification per requested DID (signature + prev-link), cache-backed | No | No | Edge deployments, small VPS instances, low-disk resolvers |
+
+### Mirror Mode
+
+- Maintains a full operation archive and materialized state.
+- Generates signed checkpoints and supports proof serving.
+- Preserves full DID audit history.
+- Operates with the highest autonomy because it does not depend on upstream for resolved DIDs once ingested.
+- Has the largest disk footprint.
+
+### Resolver Mode
+
+- Replays and verifies the global stream, but does not keep historical op blocks.
+- Supports full verification policies while reducing storage versus mirror mode.
+- Maintains current resolved state for all ingested DIDs.
+- Offers a balanced operational profile for most self-hosted operators.
+
+### Thin Mode
+
+- Fetches DID logs from upstream on demand and verifies them locally.
+- Stores only verified latest DID state plus cache metadata.
+- Uses minimal disk and scales with active DID usage, not total PLC history.
+- Depends on upstream availability at request time.
+- Does not support checkpoint inclusion proofs.
+
+### Quick Recommendations
+
+- `< 10 GB` available disk: run `thin`.
+- `20–80 GB` available disk: run `resolver`.
+- `100 GB+` available disk: run `mirror`.
+
+### Security Tradeoffs
+
+- `thin` mode still verifies signature chains and prev linkage, but resolution depends on upstream availability for cache misses or refreshes.
+- `mirror` mode is the most self-contained because it stores full verified history locally and can serve proofs from local checkpoints.
+- `resolver` mode sits between the two: it verifies globally like mirror mode but does not retain a full historical archive for proof reconstruction.
+
 ## Mirror Comparison
 
 Use: