docs(book): expand quickstart and clarify chaos

book/src/quickstart.md

@@ -2,10 +2,34 @@
 
 Get a working example running quickly.
 
+## From Scratch (Complete Setup)
+
+If you're starting from zero, here's everything you need:
+
+```bash
+# 1. Install Rust nightly
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+rustup default nightly
+
+# 2. Clone the repository
+git clone https://github.com/logos-blockchain/logos-blockchain-testing.git
+cd logos-blockchain-testing
+
+# 3. Run your first scenario (downloads dependencies automatically)
+POL_PROOF_DEV_MODE=true scripts/run/run-examples.sh -t 60 -v 1 -e 1 host
+```
+
+**First run takes 5-10 minutes** (downloads ~120MB circuit assets, builds binaries).
+
+**Windows users:** Use WSL2 (Windows Subsystem for Linux). Native Windows is not supported.
+
+---
+
 ## Prerequisites
 
+If you already have the repository cloned:
+
 - Rust toolchain (nightly)
-- This repository cloned
 - Unix-like system (tested on Linux and macOS)
 - For Docker Compose examples: Docker daemon running
 - For Docker Desktop on Apple silicon (compose/k8s): set `NOMOS_BUNDLE_DOCKER_PLATFORM=linux/arm64` to avoid slow/fragile amd64 emulation builds
@@ -28,6 +52,8 @@ scripts/run/run-examples.sh -t 60 -v 1 -e 1 host
 
 This handles circuit setup, binary building, and runs a complete scenario: 1 validator + 1 executor, mixed transaction + DA workload (5 tx/block + 1 channel + 1 blob), 60s duration.
 
+**Note:** The DA workload attaches `DaWorkloadExpectation`, and channel/blob publishing is slower than tx submission. If you see `DaWorkloadExpectation` failures, rerun with a longer duration (e.g., `-t 120`), especially on CI or slower machines.
+
 **Alternative:** Direct cargo run (requires manual setup):
 
 ```bash

book/src/scenario-lifecycle.md

@@ -100,10 +100,12 @@ The runner starts traffic and behaviors for the planned duration.
 **Key actions:**
 - Submit transactions at configured rates
 - Disperse and sample DA blobs
-- Trigger chaos events (node restarts, network partitions)
+- Trigger chaos events (node restarts)
 - Run concurrently for the specified duration
 - Observe blocks and metrics in real-time
 
+**Note:** Network partitions/peer blocking are not yet supported by node control; today chaos is restart-based. See [RunContext: BlockFeed & Node Control](node-control.md).
+
 **Duration:** Controlled by `with_run_duration()`
 
 ### 5. Evaluate Expectations

book/src/topology-chaos.md

@@ -4,15 +4,18 @@ This page focuses on cluster manipulation: node control, chaos patterns, and
 what the tooling supports today.
 
 ## Node control availability
-- **Supported**: restart/peer control via `NodeControlHandle` (compose runner).
+- **Supported**: restart control via `NodeControlHandle` (compose runner).
 - **Not supported**: local runner does not expose node control; k8s runner does
   not support it yet.
+- **Not yet supported**: peer blocking/unblocking and network partitions.
+
+See also: [RunContext: BlockFeed & Node Control](node-control.md) for the current node-control API surface and limitations.
 
 ## Chaos patterns to consider
 - **Restarts**: random restarts with minimum delay/cooldown to test recovery.
-- **Partitions**: block/unblock peers to simulate partial isolation, then assert
+- **Partitions (planned)**: block/unblock peers to simulate partial isolation, then assert
   height convergence after healing.
-- **Validator churn**: stop one validator and start another (new key) mid-run to
+- **Validator churn (planned)**: stop one validator and start another (new key) mid-run to
   test membership changes; expect convergence.
 - **Load SLOs**: push tx/DA rates and assert inclusion/availability budgets
   instead of only liveness.