From 655360bf7f1aa024de5b0e916abd338a41188339 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 09:47:18 -0800
Subject: [PATCH 01/26] docs: rename ADVANCED_README.md to README_ADVANCED.md
 for lexicographical sorting

- Rename ADVANCED_README.md to README_ADVANCED.md using git mv for clear diff tracking
- Update reference in README.md to point to new filename
- Addresses BigLep's comment about naming consistency
---
 README.md                                | 2 +-
 ADVANCED_README.md => README_ADVANCED.md | 0
 2 files changed, 1 insertion(+), 1 deletion(-)
 rename ADVANCED_README.md => README_ADVANCED.md (100%)

diff --git a/README.md b/README.md
index 84bf7f91..235b7957 100644
--- a/README.md
+++ b/README.md
@@ -144,7 +144,7 @@ Bundled with Portainer for browser-based Docker management—no terminal wizardr
 
 ## 🛠️ Need More?
 
-See **[ADVANCED_README.md](ADVANCED_README.md)** for comprehensive documentation on:
+See **[README_ADVANCED.md](README_ADVANCED.md)** for comprehensive documentation on:
 - **All commands reference** (init, build, start, stop, status, version)
 - **Configuration system** (config.toml structure, parameters, editing)
 - **Complete directory structure** (what's stored where and why)
diff --git a/ADVANCED_README.md b/README_ADVANCED.md
similarity index 100%
rename from ADVANCED_README.md
rename to README_ADVANCED.md

From 43d4e2259b2105342c2581ebed5ab43382d60203 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 09:53:54 -0800
Subject: [PATCH 02/26] docs: add links and system requirements callout

- Add link from SP nodes control to Configuration System section in README_ADVANCED.md
- Add x86 architecture requirement note to System Requirements table
- Addresses BigLep's comments about missing links and architecture limitation
---
 README.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 235b7957..86eaee72 100644
--- a/README.md
+++ b/README.md
@@ -109,7 +109,7 @@ From building Docker images to deploying contracts—everything is automated:
 Built with modular steps for easy extension and customization:
 - Add custom deployment steps
 - Configure multiple PDP service providers
-- Control "allowed" SP nodes via `~/.foc-devnet/config.toml`
+- Control "allowed" SP nodes via `~/.foc-devnet/config.toml` (see [Configuration System](README_ADVANCED.md#configuration-system))
 
 ### 📜 Programmable
 Built for scripting and automation:
@@ -139,6 +139,7 @@ Bundled with Portainer for browser-based Docker management—no terminal wizardr
 | **Docker** | Desktop (macOS) or CE (Linux) |
 | **tar** | Archive utility (usually pre-installed) |
 | **Disk Space** | ~20GB for images and blockchain data |
+| **x86 Architecture** | ??? dependencies require x86 (Intel) architecture.  As a result, ARM-based architectures (including Apple Silicon) are not supported. |b.com/FilOzone/foc-devnet/issues) for current architecture compatibility status.
 
 ---
 

From dc43663d897facb806b5942bffd3188bdc8f734e Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 09:56:31 -0800
Subject: [PATCH 03/26] docs: add command prerequisites to build and start
 commands

- Add note that build must be run after init
- Add note that start should be run after build of lotus and curio
- Addresses BigLep's comment about missing command order information
---
 README_ADVANCED.md | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 5d6462da..e03cf07d 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -42,6 +42,8 @@ foc-devnet init \
 ### `build`
 Builds Filecoin components in Docker containers.
 
+> **Note:** This command must be run after `init` to ensure Docker images and environment are prepared.
+
 ```bash
 foc-devnet build lotus [PATH] [--output-dir <DIR>]
 foc-devnet build curio [PATH] [--output-dir <DIR>]
@@ -56,6 +58,8 @@ foc-devnet build curio /path/to/custom/curio --output-dir ~/bins
 ### `start`
 Starts the local Filecoin network cluster.
 
+> **Note:** This command should be run after `build` of `lotus` and `curio` to ensure binaries are available.
+
 ```bash
 foc-devnet start [OPTIONS]
 ```

From bdd1c73f203ff7e449ec1c5c4609f8900c52179f Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 09:59:28 -0800
Subject: [PATCH 04/26] docs: add 'How Defaults Work' section explaining config
 generation

- Explain that defaults are defined in code (src/config.rs Config::default())
- Document how init writes defaults to config.toml
- Explain how to update defaults with new versions using init --force
- Addresses BigLep's question about where defaults are defined and how they get updated
---
 README_ADVANCED.md | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index e03cf07d..ba78c684 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -186,6 +186,15 @@ tag = "synapse-sdk-v0.36.1"
 **Constraints:**
 - `approved_pdp_sp_count` ≤ `active_pdp_sp_count` ≤ `MAX_PDP_SP_COUNT` (5)
 
+### How Defaults Work
+
+Defaults are defined in code (see [`src/config.rs`](../src/config.rs) `Config::default()`) and written to `config.toml` during `init`. This means:
+
+- **First-time setup:** Running `foc-devnet init` creates `config.toml` with current defaults from code
+- **Updating defaults:** When a new version of `foc-devnet` includes updated defaults (e.g., newer Lotus version), run `foc-devnet init --force` to regenerate `config.toml` with the new defaults
+- **Preserving customizations:** After regenerating, you'll need to reapply any custom settings you had modified
+- **Source of truth:** The code defines what defaults are available; `config.toml` stores your specific configuration
+
 ### Editing Config
 
 ```bash

From 1c80d4d643bdfbebf40cb6f795d0ad0f309b1195 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:00:33 -0800
Subject: [PATCH 05/26] docs: remove duplicate Manual Cleanup section

- Remove second duplicate Manual Cleanup section
- Keep the first one which has more comprehensive content
- Addresses BigLep's comment about duplicate sections
---
 README_ADVANCED.md | 14 --------------
 1 file changed, 14 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index ba78c684..977a4a62 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -342,20 +342,6 @@ ls | grep --invert-match "$CURRENT_RUN" | xargs rm -rf
 rm -rf ~/.foc-devnet
 ```
 
-### Manual Cleanup
-
-```bash
-# Stop cluster
-foc-devnet stop
-
-# Delete specific run
-rm -rf ~/.foc-devnet/run/26jan02-1430_ZanyPip
-rm -rf ~/.foc-devnet/docker/volumes/run-specific/26jan02-1430_ZanyPip
-
-# Complete nuclear reset (delete everything)
-rm -rf ~/.foc-devnet
-```
-
 ---
 
 ## Run ID and Step Context

From cce7790aa175c1d0a368a43c2434619edf4af973 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:04:19 -0800
Subject: [PATCH 06/26] docs: update Run ID format to ISO8601
 (YYYY-MM-DDTHH:MM)

- Change Run ID format from YYmmmDD-HHMM to YYYY-MM-DDTHH:MM (ISO8601)
- Update code in src/run_id/mod.rs to use new format
- Update test regex to match new format
- Update all documentation examples to use new format (2026-01-02T14:30_ZanyPip)
- Addresses BigLep's comment about date format standardization for natural sorting and clarity
---
 README_ADVANCED.md | 18 +++++++++---------
 src/run_id/mod.rs  | 23 +++++++++++------------
 2 files changed, 20 insertions(+), 21 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 977a4a62..4b6d9b79 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -236,7 +236,7 @@ foc-devnet init --force
 │   └── genesis/                     # Genesis block keys
 ├── logs/                            # Container logs
 ├── run/                             # Run-specific execution data
-│   └── <run-id>/                    # e.g., 26jan02-1430_ZanyPip/
+│   └── <run-id>/                    # e.g., 2026-01-02T14:30_ZanyPip/
 │       ├── setup.log                # Startup execution log
 │       ├── version.txt              # Component versions
 │       ├── contract_addresses.json  # Deployed contracts
@@ -316,8 +316,8 @@ foc-devnet start  # Creates new run, preserves old ones
 foc-devnet stop
 
 # Delete specific run by run ID
-rm -rf ~/.foc-devnet/run/26jan01-1200_OldRun
-rm -rf ~/.foc-devnet/docker/volumes/run-specific/26jan01-1200_OldRun
+rm -rf ~/.foc-devnet/run/2026-01-01T12:00_OldRun
+rm -rf ~/.foc-devnet/docker/volumes/run-specific/2026-01-01T12:00_OldRun
 ```
 
 **Delete all old runs (keep only current):**
@@ -350,9 +350,9 @@ rm -rf ~/.foc-devnet
 
 **What:** A unique identifier for each cluster execution.
 
-**Format:** `YYmmmDD-HHMM_RandomName`
+**Format:** `YYYY-MM-DDTHH:MM_RandomName`
 
-**Example:** `26jan02-1430_ZanyPip`
+**Example:** `2026-01-02T14:30_ZanyPip`
 
 **Why needed:**
 - **Isolation:** Separate concurrent runs without conflicts
@@ -362,10 +362,10 @@ rm -rf ~/.foc-devnet
 
 **Generation:**
 ```rust
-// Date: YYmmmDD (26jan02 = January 2, 2026)
-// Time: HHMM (1430 = 2:30 PM)
+// Date: YYYY-MM-DD (2026-01-02 = January 2, 2026)
+// Time: HH:MM (14:30 = 2:30 PM, ISO8601 format)
 // Name: RandomAdjective + RandomNoun (ZanyPip)
-"26jan02-1430_ZanyPip"
+"2026-01-02T14:30_ZanyPip"
 ```
 
 **Storage:**
@@ -523,7 +523,7 @@ Portainer is a lightweight container management UI that gives you visual, browse
 | `foc-builder` | foc-builder | Foundry tools (contract deployment) | Host network |
 | `foc-portainer` | portainer/portainer-ce | Container management UI | 5700 (first from range) |
 
-**Note:** Container names include run-id for isolation (e.g., `foc-26jan02-1430_ZanyPip-lotus`).
+**Note:** Container names include run-id for isolation (e.g., `foc-2026-01-02T14:30_ZanyPip-lotus`).
 
 ### Network Topology
 
diff --git a/src/run_id/mod.rs b/src/run_id/mod.rs
index 6109ffe4..1f70a93e 100644
--- a/src/run_id/mod.rs
+++ b/src/run_id/mod.rs
@@ -1,7 +1,7 @@
 //! Run ID generation and management.
 //!
 //! This module handles generating unique run IDs for each cluster start.
-//! Format: YYMMDD-HHMM-random-name (e.g., 251203-1246-thirsty-wolf)
+//! Format: YYYY-MM-DDTHH:MM-random-name (e.g., 2025-12-03T12:46-thirsty-wolf)
 
 mod persistence;
 
@@ -28,21 +28,20 @@ pub const NOUNS: &[&str] = &[
 
 /// Generate a unique run ID for this execution.
 ///
-/// Returns a string like "foc_25dec15-2206_blue_ibis_lotus" where:
-/// - foc_ is the prefix
-/// - 25dec15 is the date (YYmmmDD where mmm is the lowercase abbreviated month name)
-/// - 2206 is the time (HHMM)
-/// - blue_ibis_lotus is the modified random name with underscores and suffix
+/// Returns a string like "2025-12-15T22:06_ZanyPip" where:
+/// - 2025-12-15 is the date (YYYY-MM-DD, ISO8601 format)
+/// - T is the date/time separator (ISO8601)
+/// - 22:06 is the time (HH:MM, 24-hour format)
+/// - ZanyPip is the random name (adjective + noun)
 ///
 /// # Example
 /// ```no_run
 /// let run_id = generate_run_id();
-/// println!("{}", run_id); // e.g., "25dec15-2206_blue_ibis_lotus"
+/// println!("{}", run_id); // e.g., "2025-12-15T22:06_ZanyPip"
 /// ```
 pub fn generate_run_id() -> String {
     let now = Local::now();
-    let date = now.format("%y%b%d").to_string().to_lowercase();
-    let time = now.format("%H%M");
+    let datetime = now.format("%Y-%m-%dT%H:%M");
 
     // Implement our own random name generator to control format
     let random_name = {
@@ -52,7 +51,7 @@ pub fn generate_run_id() -> String {
         format!("{}{}", adjective, noun)
     };
 
-    format!("{}-{}_{}", date, time, random_name)
+    format!("{}_{}", datetime, random_name)
 }
 
 /// Create a symlink to the latest run directory.
@@ -90,8 +89,8 @@ mod tests {
     fn test_run_id_format() {
         let run_id = generate_run_id();
 
-        // Should match pattern: foc_YYmmmDD-HHMM_word_word_lotus
-        let pattern = Regex::new(r"^foc_\d{2}[a-z]{3}\d{2}-\d{4}_.+$").unwrap();
+        // Should match pattern: YYYY-MM-DDTHH:MM_RandomName
+        let pattern = Regex::new(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}_.+$").unwrap();
         assert!(
             pattern.is_match(&run_id),
             "Run ID should match format: {}",

From b999d03fdf2a82e86e1fe3c4cc3e808164d1fbfa Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:07:35 -0800
Subject: [PATCH 07/26] docs: define what a 'step' is when first introduced

- Add definition of 'step' as discrete unit of work in cluster startup
- Link to Detailed Start Sequence section for complete list
- Reorganize Step Context section for better clarity
- Addresses BigLep's comment about defining 'step' when first mentioned
---
 README_ADVANCED.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 4b6d9b79..0b10aa16 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -374,9 +374,12 @@ rm -rf ~/.foc-devnet
 
 ### Step Context (SetupContext)
 
-**What:** Thread-safe shared state container that passes data between steps.
+**What is a "step"?** A step is a discrete unit of work in the cluster startup process (e.g., starting Lotus daemon, deploying contracts, starting Curio SPs). See [Detailed Start Sequence](#detailed-start-sequence) for a complete list of all steps.
 
-**Why needed:**
+**What is "step context"?** Thread-safe shared state container that passes data between steps.
+
+
+**Why is "step context" needed?**
 - **Dependency resolution:** Later steps need data from earlier steps
 - **Decoupling:** Steps don't directly call each other
 - **Parallelization:** Thread-safe for concurrent step execution

From 98a06e3776175a02e0cbb5d47cf18cf065e77822 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:10:18 -0800
Subject: [PATCH 08/26] docs: add links to context keys code location and
 example

- Link to src/commands/start/ directory for context key implementations
- Add example link to usdfc_deploy/prerequisites.rs showing context.get() usage
- Clarify that context keys are string literals, not constants
- Addresses BigLep's comment about linking to definitive list in code
---
 README_ADVANCED.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 0b10aa16..f325e02b 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -424,6 +424,9 @@ fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>> {
 ```
 
 **Common context keys:**
+
+These keys are string literals used throughout the codebase (see step implementations in [`src/commands/start/`](../src/commands/start/)). The definitive list is maintained in the code where steps use `context.get()` and `context.set()`. For an example, see [`src/commands/start/usdfc_deploy/prerequisites.rs`](../src/commands/start/usdfc_deploy/prerequisites.rs). 
+
 - `deployer_mockusdfc_eth_address` - MockUSDFC deployer address
 - `deployer_foc_eth_address` - FOC contracts deployer address
 - `mockusdfc_contract_address` - MockUSDFC token contract

From 427c125c301478aef926eb36cfd0cad9753e9aa7 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:10:59 -0800
Subject: [PATCH 09/26] docs: add markdown link formatting for Portainer

- Change plain text 'Portainer' to [Portainer](https://docs.docksal.io/use-cases/portainer/)
- Addresses BigLep's comment about proper link formatting
---
 README_ADVANCED.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index f325e02b..2c63e441 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -453,7 +453,7 @@ These keys are string literals used throughout the codebase (see step implementa
 
 **What is Portainer?**
 
-Portainer is a lightweight container management UI that gives you visual, browser-based access to all your Docker containers, networks, and volumes. foc-devnet automatically starts Portainer using the first port in your configured range.
+[Portainer](https://docs.docksal.io/use-cases/portainer/) is a lightweight container management UI that gives you visual, browser-based access to all your Docker containers, networks, and volumes. foc-devnet automatically starts Portainer using the first port in your configured range.
 
 **Access:** http://localhost:5700 (default, or first port from `port_range_start` in config.toml)
 

From 8d59b0171c8d251051950dc8da42a154e0564ae4 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:11:44 -0800
Subject: [PATCH 10/26] docs: clarify container architecture in table

- Clarify that Yugabyte is shared by all Curio SPs
- Update port descriptions from 'Dynamic' to 'Dynamic from range' for all Curio containers
- Addresses BigLep's comments about container descriptions
---
 README_ADVANCED.md | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 2c63e441..dbfb0a33 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -522,10 +522,10 @@ These keys are string literals used throughout the codebase (see step implementa
 |-----------|-------|---------|-------|
 | `foc-<run-id>-lotus` | foc-lotus | Filecoin daemon (FEVM enabled) | 1234 (API), 1235 (P2P) |
 | `foc-<run-id>-lotus-miner` | foc-lotus-miner | First-gen miner (PoRep) | 2345 (API) |
-| `foc-<run-id>-yugabyte` | foc-yugabyte | Database for Curio | 5433 (PostgreSQL) |
-| `foc-<run-id>-curio-1` | foc-curio | First Curio SP (PDP) | Dynamic |
-| `foc-<run-id>-curio-2` | foc-curio | Second Curio SP (PDP) | Dynamic |
-| `foc-<run-id>-curio-N` | foc-curio | Nth Curio SP (PDP) | Dynamic |
+| `foc-<run-id>-yugabyte` | foc-yugabyte | Database for Curio (shared by all Curio SPs) | 5433 (PostgreSQL) |
+| `foc-<run-id>-curio-1` | foc-curio | First Curio SP (PDP) | Dynamic from range |
+| `foc-<run-id>-curio-2` | foc-curio | Second Curio SP (PDP) | Dynamic from range |
+| `foc-<run-id>-curio-N` | foc-curio | Nth Curio SP (PDP) | Dynamic from range |
 | `foc-builder` | foc-builder | Foundry tools (contract deployment) | Host network |
 | `foc-portainer` | portainer/portainer-ce | Container management UI | 5700 (first from range) |
 

From 3d5e01b5d2334380f95b01e703abc53a6dbb2c5b Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:38:09 -0800
Subject: [PATCH 11/26] docs: fix network diagram and correct Yugabyte
 architecture

- Simplify diagram to show single representative instance with curio-n/yugabyte-n notation
- Correct Yugabyte architecture: each SP has its own Yugabyte instance, not shared
- Update container architecture table to show yugabyte-1 and yugabyte-N (one per SP)
- Update network explanations to reflect one Yugabyte per SP network
- Addresses BigLep's comment about network diagram readability and accuracy
---
 README_ADVANCED.md | 33 +++++++++++++++------------------
 1 file changed, 15 insertions(+), 18 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index dbfb0a33..f4bf3e07 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -522,7 +522,8 @@ These keys are string literals used throughout the codebase (see step implementa
 |-----------|-------|---------|-------|
 | `foc-<run-id>-lotus` | foc-lotus | Filecoin daemon (FEVM enabled) | 1234 (API), 1235 (P2P) |
 | `foc-<run-id>-lotus-miner` | foc-lotus-miner | First-gen miner (PoRep) | 2345 (API) |
-| `foc-<run-id>-yugabyte` | foc-yugabyte | Database for Curio (shared by all Curio SPs) | 5433 (PostgreSQL) |
+| `foc-<run-id>-yugabyte-1` | foc-yugabyte | Database for Curio SP 1 | 5433 (PostgreSQL) |
+| `foc-<run-id>-yugabyte-N` | foc-yugabyte | Database for Curio SP N (one per SP) | Dynamic from range |
 | `foc-<run-id>-curio-1` | foc-curio | First Curio SP (PDP) | Dynamic from range |
 | `foc-<run-id>-curio-2` | foc-curio | Second Curio SP (PDP) | Dynamic from range |
 | `foc-<run-id>-curio-N` | foc-curio | Nth Curio SP (PDP) | Dynamic from range |
@@ -552,46 +553,42 @@ Docker's user-defined bridge networks are virtual networks that provide:
 ```mermaid
 graph TB
     subgraph host["Host Machine (localhost)"]
-        style host fill:#f0f0f0,stroke:#333,stroke-width:2px
         portainer["🌐 Portainer<br/>:5700"]
         lotus_api["📡 Lotus API<br/>:5701"]
         miner_api["⛏️ Miner API<br/>:5702"]
         yugabyte_api["🗄️ Yugabyte<br/>:5710"]
     end
 
-    subgraph lotus_net["foc-&lt;run-id&gt;-lot-net<br/>(Lotus Network - Blockchain Communication)"]
-        style lotus_net fill:#e3f2fd,stroke:#1976d2,stroke-width:2px
+    subgraph lotus_net["foc-&lt;run-id&gt;-lot-net (Lotus Network)"]
         lotus["foc-lotus<br/>(Filecoin Daemon)"]
         builder["foc-builder<br/>(--net=host)"]
-        curio1_lot["foc-curio-1<br/>(on lot-net)"]
+        curio_n_lot["foc-curio-n<br/>(on lot-net)"]
     end
 
-    subgraph miner_net["foc-&lt;run-id&gt;-lot-m-net<br/>(Lotus Miner Network)"]
-        style miner_net fill:#fff3e0,stroke:#f57c00,stroke-width:2px
+    subgraph miner_net["foc-&lt;run-id&gt;-lot-m-net (Lotus Miner Network)"]
         miner["foc-lotus-miner<br/>(PoRep Miner)"]
     end
 
-    subgraph curio_net["foc-&lt;run-id&gt;-cur-m-net-1<br/>(Curio SP 1 Network)"]
-        style curio_net fill:#f3e5f5,stroke:#7b1fa2,stroke-width:2px
-        yugabyte["foc-yugabyte<br/>(Database)"]
-        curio1["foc-curio-1<br/>(PDP Service Provider)"]
+    subgraph curio_net_n["foc-&lt;run-id&gt;-cur-m-net-n (Curio SP N Network)"]
+        yugabyte_n["foc-yugabyte-n<br/>(Database)"]
+        curio_n["foc-curio-n<br/>(PDP Service Provider)"]
     end
 
     %% Container to Host connections
     lotus -.->|exposes| lotus_api
     miner -.->|exposes| miner_api
-    yugabyte -.->|exposes| yugabyte_api
+    yugabyte_n -.->|exposes| yugabyte_api
 
     %% Network connections
     builder -->|uses host network| lotus
-    curio1 -->|same container| curio1_lot
+    curio_n -->|same container| curio_n_lot
     miner -->|connects to| lotus
-    curio1_lot -->|connects to| lotus
-    yugabyte <-->|database| curio1
+    curio_n_lot -->|connects to| lotus
+    yugabyte_n <-->|database| curio_n
 
     %% Styling
     classDef container fill:#fff,stroke:#333,stroke-width:1px
-    class lotus,builder,curio1_lot,miner,yugabyte,curio1 container
+    class lotus,builder,curio_n_lot,miner,yugabyte_n,curio_n container
 ```
 
 **Legend:**
@@ -612,8 +609,8 @@ graph TB
    
 3. **Curio Networks (`foc-<run-id>-cur-m-net-N`)**: 
    - Each Curio SP gets its own network
-   - All share Yugabyte database via network membership
-   - Provides DNS: Curio can use `foc-<run-id>-yugabyte` as database host
+   - Each Curio SP has its own Yugabyte database instance on its network
+   - Provides DNS: Curio SP N can use `foc-<run-id>-yugabyte-N` as database host
 
 **Builder uses host network** (`--network host`) to access Lotus RPC at `http://localhost:1234/rpc/v1`.
 

From e13357f0843ee1c62354c157c991aeaea479e45c Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:44:19 -0800
Subject: [PATCH 12/26] fix: change Run ID format to condensed ISO8601
 (YYYYMMDDTHHMM) for Docker compatibility

- Change from YYYY-MM-DDTHH:MM to YYYYMMDDTHHMM (no dashes/colons)
- Colons and dashes cause issues with Docker network names
- Update code in src/run_id/mod.rs to use %Y%m%dT%H%M format
- Update test regex to match new format
- Update all documentation examples throughout README_ADVANCED.md
- Still ISO8601-based for natural sorting, but Docker-compatible
---
 README_ADVANCED.md | 19 +++++++++----------
 src/run_id/mod.rs  | 18 ++++++++++--------
 2 files changed, 19 insertions(+), 18 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index f4bf3e07..51fb9173 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -236,7 +236,7 @@ foc-devnet init --force
 │   └── genesis/                     # Genesis block keys
 ├── logs/                            # Container logs
 ├── run/                             # Run-specific execution data
-│   └── <run-id>/                    # e.g., 2026-01-02T14:30_ZanyPip/
+│   └── <run-id>/                    # e.g., 20260102T1430_ZanyPip/
 │       ├── setup.log                # Startup execution log
 │       ├── version.txt              # Component versions
 │       ├── contract_addresses.json  # Deployed contracts
@@ -316,8 +316,8 @@ foc-devnet start  # Creates new run, preserves old ones
 foc-devnet stop
 
 # Delete specific run by run ID
-rm -rf ~/.foc-devnet/run/2026-01-01T12:00_OldRun
-rm -rf ~/.foc-devnet/docker/volumes/run-specific/2026-01-01T12:00_OldRun
+rm -rf ~/.foc-devnet/run/20260101T1200_OldRun
+rm -rf ~/.foc-devnet/docker/volumes/run-specific/20260101T1200_OldRun
 ```
 
 **Delete all old runs (keep only current):**
@@ -350,9 +350,9 @@ rm -rf ~/.foc-devnet
 
 **What:** A unique identifier for each cluster execution.
 
-**Format:** `YYYY-MM-DDTHH:MM_RandomName`
+**Format:** `YYYYMMDDTHHMM_RandomName`
 
-**Example:** `2026-01-02T14:30_ZanyPip`
+**Example:** `20260102T1430_ZanyPip`
 
 **Why needed:**
 - **Isolation:** Separate concurrent runs without conflicts
@@ -362,10 +362,10 @@ rm -rf ~/.foc-devnet
 
 **Generation:**
 ```rust
-// Date: YYYY-MM-DD (2026-01-02 = January 2, 2026)
-// Time: HH:MM (14:30 = 2:30 PM, ISO8601 format)
+// Date: YYYYMMDD (20260102 = January 2, 2026, condensed ISO8601)
+// Time: HHMM (1430 = 2:30 PM, no colons for Docker compatibility)
 // Name: RandomAdjective + RandomNoun (ZanyPip)
-"2026-01-02T14:30_ZanyPip"
+"20260102T1430_ZanyPip"
 ```
 
 **Storage:**
@@ -525,12 +525,11 @@ These keys are string literals used throughout the codebase (see step implementa
 | `foc-<run-id>-yugabyte-1` | foc-yugabyte | Database for Curio SP 1 | 5433 (PostgreSQL) |
 | `foc-<run-id>-yugabyte-N` | foc-yugabyte | Database for Curio SP N (one per SP) | Dynamic from range |
 | `foc-<run-id>-curio-1` | foc-curio | First Curio SP (PDP) | Dynamic from range |
-| `foc-<run-id>-curio-2` | foc-curio | Second Curio SP (PDP) | Dynamic from range |
 | `foc-<run-id>-curio-N` | foc-curio | Nth Curio SP (PDP) | Dynamic from range |
 | `foc-builder` | foc-builder | Foundry tools (contract deployment) | Host network |
 | `foc-portainer` | portainer/portainer-ce | Container management UI | 5700 (first from range) |
 
-**Note:** Container names include run-id for isolation (e.g., `foc-2026-01-02T14:30_ZanyPip-lotus`).
+**Note:** Container names include run-id for isolation (e.g., `foc-20260102T1430_ZanyPip-lotus`).
 
 ### Network Topology
 
diff --git a/src/run_id/mod.rs b/src/run_id/mod.rs
index 1f70a93e..0648ca9a 100644
--- a/src/run_id/mod.rs
+++ b/src/run_id/mod.rs
@@ -1,7 +1,7 @@
 //! Run ID generation and management.
 //!
 //! This module handles generating unique run IDs for each cluster start.
-//! Format: YYYY-MM-DDTHH:MM-random-name (e.g., 2025-12-03T12:46-thirsty-wolf)
+//! Format: YYYYMMDDTHHMM-random-name (e.g., 20251203T1246-thirsty-wolf)
 
 mod persistence;
 
@@ -28,20 +28,22 @@ pub const NOUNS: &[&str] = &[
 
 /// Generate a unique run ID for this execution.
 ///
-/// Returns a string like "2025-12-15T22:06_ZanyPip" where:
-/// - 2025-12-15 is the date (YYYY-MM-DD, ISO8601 format)
+/// Returns a string like "20251215T2206_ZanyPip" where:
+/// - 20251215 is the date (YYYYMMDD, condensed ISO8601 format)
 /// - T is the date/time separator (ISO8601)
-/// - 22:06 is the time (HH:MM, 24-hour format)
+/// - 2206 is the time (HHMM, 24-hour format, no colons for Docker compatibility)
 /// - ZanyPip is the random name (adjective + noun)
 ///
+/// Uses condensed ISO8601 format (no dashes or colons) for Docker network name compatibility.
+///
 /// # Example
 /// ```no_run
 /// let run_id = generate_run_id();
-/// println!("{}", run_id); // e.g., "2025-12-15T22:06_ZanyPip"
+/// println!("{}", run_id); // e.g., "20251215T2206_ZanyPip"
 /// ```
 pub fn generate_run_id() -> String {
     let now = Local::now();
-    let datetime = now.format("%Y-%m-%dT%H:%M");
+    let datetime = now.format("%Y%m%dT%H%M");
 
     // Implement our own random name generator to control format
     let random_name = {
@@ -89,8 +91,8 @@ mod tests {
     fn test_run_id_format() {
         let run_id = generate_run_id();
 
-        // Should match pattern: YYYY-MM-DDTHH:MM_RandomName
-        let pattern = Regex::new(r"^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}_.+$").unwrap();
+        // Should match pattern: YYYYMMDDTHHMM_RandomName (condensed ISO8601, no dashes/colons)
+        let pattern = Regex::new(r"^\d{8}T\d{4}_.+$").unwrap();
         assert!(
             pattern.is_match(&run_id),
             "Run ID should match format: {}",

From 371a6b0aa53f8793365a14dceeebea7de160aab9 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:57:05 -0800
Subject: [PATCH 13/26] docs: improve repository management section

- Convert Required Repositories table to bulleted list with repo links (avoids outdated version info)
- Add Version Strategy section explaining GitTag/GitCommit/GitBranch approaches
- Link to src/config.rs where default versions are defined
- Link 'Updating defaults' to How Defaults Work section
- Addresses BigLep's questions about version strategy and where defaults are defined
---
 README_ADVANCED.md | 24 +++++++++++++++++-------
 1 file changed, 17 insertions(+), 7 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 51fb9173..df22fac8 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -644,15 +644,25 @@ port_range_count = 100
 
 ## Repository Management
 
+
+
 ### Required Repositories
 
-| Repository | Default Source | Purpose |
-|------------|---------------|---------|
-| **lotus** | `github.com/filecoin-project/lotus:v1.34.0` | Filecoin daemon |
-| **curio** | `github.com/filecoin-project/curio:pdpv0` | Storage provider (PDP) |
-| **filecoin-services** | `github.com/FilOzone/filecoin-services:v1.0.0` | FOC smart contracts |
-| **multicall3** | `github.com/mds1/multicall3:main` | Multicall3 contract |
-| **synapse-sdk** | `github.com/FilOzone/synapse-sdk:synapse-sdk-v0.36.1` | PDP verification SDK |
+- **[lotus](https://github.com/filecoin-project/lotus)** - Filecoin daemon
+- **[curio](https://github.com/filecoin-project/curio)** - Storage provider (PDP)
+- **[filecoin-services](https://github.com/FilOzone/filecoin-services)** - FOC smart contracts
+- **[multicall3](https://github.com/mds1/multicall3)** - Multicall3 contract
+- **[synapse-sdk](https://github.com/FilOzone/synapse-sdk)** - PDP verification SDK
+
+### Version Strategy
+
+Default versions for these repositories are defined in code (see [`src/config.rs`](../src/config.rs) `Config::default()`).
+
+- **Git tags** (`GitTag`): Used for stable releases. Tags provide version pinning and stability.
+- **Git commits** (`GitCommit`): Used for repositories where specific commits are required and there isn't a corresponding tag yet.  (Generally tags should be preferred over commits.)
+- **Git branches** (`GitBranch`): Used for development or when tracking latest changes.
+
+**Updating defaults:** See [How Defaults Work](#how-defaults-work) for information on how defaults are defined and the steps to apply updates.
 
 ### Using Local Repositories
 

From b747314024b5e08b66244c0c72c560400e5a1c85 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:58:03 -0800
Subject: [PATCH 14/26] docs: simplify configuration sharing section

- Reduce from verbose 3-step process to simple 2-step (copy file + run init)
- Remove unnecessary export and documentation steps
- Addresses BigLep's comment about verbose configuration sharing
---
 README_ADVANCED.md | 44 +++++++-------------------------------------
 1 file changed, 7 insertions(+), 37 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index df22fac8..4892c74a 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -690,43 +690,13 @@ foc-devnet init \
 
 **To share your exact setup with others:**
 
-1. **Export config:**
-   ```bash
-   cat ~/.foc-devnet/config.toml
-   ```
-
-2. **Document versions:**
-   ```toml
-   # Lotus v1.34.0
-   [lotus]
-   url = "https://github.com/filecoin-project/lotus.git"
-   tag = "v1.34.0"
-   
-   # Curio pdpv0 branch (commit: abc123)
-   [curio]
-   url = "https://github.com/filecoin-project/curio.git"
-   branch = "pdpv0"
-   
-   # FilOzone services v1.0.0
-   [filecoin_services]
-   url = "https://github.com/FilOzone/filecoin-services.git"
-   tag = "v1.0.0"
-   
-   # Synapse SDK
-   [synapse_sdk]
-   url = "git@github.com:FilOzone/synapse-sdk.git"
-   tag = "synapse-sdk-v0.36.1"
-   ```
-
-3. **Share config file:**
-   ```bash
-   # Recipient copies config
-   mkdir -p ~/.foc-devnet
-   cp shared-config.toml ~/.foc-devnet/config.toml
-   
-   # Run init to download and build
-   foc-devnet init
-   ```
+```bash
+# Copy config file
+cp shared-config.toml ~/.foc-devnet/config.toml
+
+# Run init to download and build
+foc-devnet init
+```
 
 **For reproducible builds, specify exact commits:**
 

From 22a2f0d5d7ebe5945f7dd4fc94fd4552ceff58b9 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 10:58:43 -0800
Subject: [PATCH 15/26] docs: move Reproducible builds to its own heading

- Move Reproducible builds from under Sharing Configuration to separate section
- Makes it clearer that it's a distinct topic
- Addresses BigLep's comment about moving it to its own heading
---
 README_ADVANCED.md | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 4892c74a..67e5a8bc 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -698,7 +698,11 @@ cp shared-config.toml ~/.foc-devnet/config.toml
 foc-devnet init
 ```
 
-**For reproducible builds, specify exact commits:**
+---
+
+### Reproducible Builds
+
+For reproducible builds, specify exact commits in `config.toml`:
 
 ```toml
 [lotus]

From 84b8192697bd04f0d9affc79204adda25166a3f4 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:07:24 -0800
Subject: [PATCH 16/26] docs: merge Command Flags section with Commands
 Reference

- Move all flag information into Commands Reference section
- Remove duplicate Command Flags section
- Add inline 'why' explanations for --volumes-dir, --run-dir, and --notest
- Preserve parallelization guidance (why to use/not use --parallel)
- Add parallelization table to Step execution section showing which epochs are parallelized
- Link from start command to Detailed Start Sequence for parallelization details
- Addresses BigLep's comment about eliminating duplication
---
 README_ADVANCED.md | 120 ++++++++++++++++-----------------------------
 1 file changed, 41 insertions(+), 79 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 67e5a8bc..f07c3952 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -21,8 +21,9 @@ foc-devnet init [OPTIONS]
 - `--yugabyte-url <URL>` - Yugabyte download URL
 - `--yugabyte-archive <PATH>` - Local Yugabyte archive file
 - `--proof-params-dir <PATH>` - Local proof params directory
-- `--force` - Force regeneration of config file
-- `--rand` - Use random mnemonic instead of deterministic one
+- `--force` - Force regeneration of config file.  Useful when switching between configurations.
+
+- `--rand` - Use random mnemonic instead of deterministic one.  Use this for unique test scenarios.
 
 **Source Format:**
 - `gittag:v1.0.0` - Specific git tag (uses default repo)
@@ -49,6 +50,9 @@ foc-devnet build lotus [PATH] [--output-dir <DIR>]
 foc-devnet build curio [PATH] [--output-dir <DIR>]
 ```
 
+**Options:**
+- `--output-dir <DIR>` - Directory for built binaries (default: `~/.foc-devnet/bin`)
+
 **Example:**
 ```bash
 foc-devnet build lotus
@@ -65,10 +69,24 @@ foc-devnet start [OPTIONS]
 ```
 
 **Options:**
-- `--volumes-dir <DIR>` - Custom docker volumes directory
-- `--run-dir <DIR>` - Custom run-specific data directory
+- `--volumes-dir <DIR>` - Custom docker volumes directory. Use custom paths (e.g., faster SSD, network storage).
+- `--run-dir <DIR>` - Custom run-specific data directory. Use custom paths (e.g., faster SSD, network storage).
 - `--parallel` - **⚡ Run steps in parallel for ~40% faster startup (recommended)**
-- `--notest` - Skip end-to-end tests
+
+**Why `--parallel` (Recommended):**
+- **⚡ Significant speedup:** Reduces startup time from ~10 min to ~6 min
+- **Smart parallelization:** Steps that don't depend on each other run concurrently
+- **Production-ready:** Thread-safe implementation with proper synchronization
+- **Use case:** Default for most workflows, especially development iteration
+
+**When NOT to use `--parallel`:**
+- Debugging step ordering issues
+- Very low-resource machines (< 4GB RAM)
+- First-time setup (sequential is easier to follow)
+
+See [Detailed Start Sequence](#detailed-start-sequence) for information about which steps are parallelized.
+
+- `--notest` - Skip end-to-end tests. Use when rapid iteration is needed.
 
 **Recommended for faster startup:**
 ```bash
@@ -80,8 +98,6 @@ foc-devnet start --parallel
 foc-devnet start --parallel --notest
 ```
 
-> **💡 Pro Tip:** Use `--parallel` by default! It runs independent steps concurrently (contract deployments, database startup, etc.) while respecting dependencies. This can reduce startup time from ~5 minutes to ~3 minutes.
-
 **After successful start:**
 - Portainer UI available at http://localhost:5700 (uses first port in configured range)
 - Use Portainer to monitor containers, view logs, and debug issues
@@ -716,78 +732,6 @@ commit = "789012345678..."
 
 ---
 
-## Command Flags
-
-### `init` Flags
-
-| Flag | Type | Description |
-|------|------|-------------|
-| `--curio` | String | Curio source location |
-| `--lotus` | String | Lotus source location |
-| `--filecoin-services` | String | Filecoin Services source location |
-| `--synapse-sdk` | String | Synapse SDK source location |
-| `--yugabyte-url` | String | Yugabyte download URL |
-| `--yugabyte-archive` | Path | Local Yugabyte archive (.tar.gz) |
-| `--proof-params-dir` | Path | Local proof parameters directory |
-| `--force` | Boolean | Force config regeneration |
-| `--rand` | Boolean | Use random mnemonic (non-deterministic keys) |
-
-**Why `--force`:** Regenerates `config.toml` even if it exists. Useful when switching between configurations.
-
-**Why `--rand`:** Generates random keys instead of deterministic ones. Use for unique test scenarios.
-
-### `build` Flags
-
-| Flag | Type | Description |
-|------|------|-------------|
-| `--output-dir` | Path | Directory for built binaries (default: `~/.foc-devnet/bin`) |
-
-**Why `--output-dir`:** Specify custom location for compiled binaries.
-
-### `start` Flags
-
-| Flag | Type | Description |
-|------|------|-------------|
-| `--volumes-dir` | Path | Custom docker volumes directory |
-| `--run-dir` | Path | Custom run-specific data directory |
-| `--parallel` | Boolean | ⚡ **Execute steps in parallel (~40% faster, recommended)** |
-| `--notest` | Boolean | Skip end-to-end Synapse tests |
-
-**Why `--parallel` (Recommended):**
-- **⚡ Significant speedup:** Reduces startup time from ~10 min to ~6 min
-- **Smart parallelization:** Steps that don't depend on each other run concurrently
-- **Production-ready:** Thread-safe implementation with proper synchronization
-- **Use case:** Default for most workflows, especially development iteration
-
-**When NOT to use `--parallel`:**
-- Debugging step ordering issues
-- Very low-resource machines (< 4GB RAM)
-- First-time setup (sequential is easier to follow)
-
-**Parallel execution epochs (with `--parallel`):**
-
-| Epoch | Steps | Parallelized? | Why |
-|-------|-------|---------------|-----|
-| 1 | Lotus | No | Foundational - everything depends on it |
-| 2 | Lotus Miner | No | Needs Lotus running |
-| 3 | ETH Account Funding | No | Needs blockchain active |
-| 4 | MockUSDFC Deploy + Multicall3 Deploy | **⚡ YES** | Independent contract deployments |
-| 5 | FOC Deploy + USDFC Funding + Yugabyte | **⚡ YES** | Parallel contract work + DB startup |
-| 6 | Curio SPs | No | Needs Yugabyte ready |
-| 7 | PDP SP Registration | No | Needs Curio running for ports |
-| 8 | Synapse E2E Test | No | Verification step |
-
-**Time savings:** Epochs 4 and 5 run ~40% faster in parallel mode.
-
-**Without `--parallel`:** All 8 epochs run sequentially (~5 minutes total).
-**With `--parallel`:** Epochs 4-5 run concurrently (~3 minutes total).
-
-**Why `--notest`:** Skip time-consuming E2E tests when rapid iteration needed.
-
-**Why `--volumes-dir` / `--run-dir`:** Use custom paths (e.g., faster SSD, network storage).
-
----
-
 ## Lifecycle Overview
 
 ### Full Lifecycle
@@ -848,6 +792,24 @@ commit = "789012345678..."
 
 **5. Step execution (sequential or parallel):**
 
+Steps run sequentially by default, or in parallel when using the `--parallel` flag. With `--parallel`, steps are grouped into execution epochs based on dependencies:
+
+| Epoch | Steps | Parallelized? | Why |
+|-------|-------|---------------|-----|
+| 1 | Lotus | No | Foundational - everything depends on it |
+| 2 | Lotus Miner | No | Needs Lotus running |
+| 3 | ETH Account Funding | No | Needs blockchain active |
+| 4 | MockUSDFC Deploy + Multicall3 Deploy | **⚡ YES** | Independent contract deployments |
+| 5 | FOC Deploy + USDFC Funding + Yugabyte | **⚡ YES** | Parallel contract work + DB startup |
+| 6 | Curio SPs | No | Needs Yugabyte ready |
+| 7 | PDP SP Registration | No | Needs Curio running for ports |
+| 8 | Synapse E2E Test | No | Verification step |
+
+**Time savings:** Epochs 4 and 5 run ~40% faster in parallel mode.
+
+**Without `--parallel`:** All 8 epochs run sequentially (~5 minutes total).
+**With `--parallel`:** Epochs 4-5 run concurrently (~3 minutes total).
+
    **a. Lotus Step:**
    - Start Lotus daemon container
    - Wait for API file

From edb143eb210a2d26224347210f2a661166e1849f Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:13:15 -0800
Subject: [PATCH 17/26] docs: restructure lifecycle section

- Remove ASCII diagram
- Reorganize into Before Steps/Steps/Post Start Steps structure
- Remove hardcoded numbers (1-6) and letters (a-k) from step descriptions
- Add links to Step Implementation Pattern and Configuration System
- Add sections for running, stop, and (re)start states
- Addresses BigLep's comment about improving lifecycle documentation structure
---
 README_ADVANCED.md | 89 +++++++++++++++++++---------------------------
 1 file changed, 36 insertions(+), 53 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index f07c3952..2cea8a9e 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -734,63 +734,36 @@ commit = "789012345678..."
 
 ## Lifecycle Overview
 
-### Full Lifecycle
-
-```
-┌──────────┐
-│   init   │  Download repos, build images, generate keys
-└────┬─────┘
-     │
-     ▼
-┌──────────┐
-│  build   │  Compile lotus and curio binaries
-└────┬─────┘
-     │
-     ▼
-┌──────────┐
-│  start   │  Launch cluster (see detailed flow below)
-└────┬─────┘
-     │
-     ▼
-┌──────────┐
-│ [running]│  Cluster active, contracts deployed
-└────┬─────┘
-     │
-     ▼
-┌──────────┐
-│   stop   │  Stop containers, cleanup networks
-└────┬─────┘
-     │
-     ▼
-┌──────────┐
-│  start   │  Regenesis + restart (fresh blockchain)
-└──────────┘
-```
+The typical workflow follows: `init` → `build` → `start` → `[running]` → `stop` → `start` (regenesis). Each `start` command performs a regenesis, creating a fresh blockchain state.
 
 ### Detailed Start Sequence
 
-**1. Pre-start cleanup:**
+The `start` command orchestrates multiple phases to launch the cluster. See the [Step Implementation Pattern](#step-implementation-pattern) section for how steps are structured.
+
+#### Before Steps
+
+**Pre-start cleanup:**
    - Stop any existing cluster
-   - Generate unique run ID
+   - Generate unique run ID (format: `YYYYMMDDTHHMM_RandomName`)
    - Create run directories
    - Perform regenesis (delete old run volumes)
 
-**2. Genesis prerequisites (one-time per start):**
+**Genesis prerequisites (one-time per start):**
    - Generate BLS keys for prefunded accounts
    - Create pre-sealed sectors
    - Build genesis block configuration
 
-**3. Port allocation:**
-   - Validate port range availability
+**Port allocation:**
+   - Validate port range availability (see [Configuration System](#configuration-system) for port range settings)
    - Allocate Portainer port
    - Initialize port allocator for dynamic assignment
 
-**4. Network creation:**
+**Network creation:**
    - Create Lotus network
    - Create Lotus Miner network
    - Create Curio networks (one per SP)
 
-**5. Step execution (sequential or parallel):**
+#### Steps
 
 Steps run sequentially by default, or in parallel when using the `--parallel` flag. With `--parallel`, steps are grouped into execution epochs based on dependencies:
 
@@ -810,61 +783,71 @@ Steps run sequentially by default, or in parallel when using the `--parallel` fl
 **Without `--parallel`:** All 8 epochs run sequentially (~5 minutes total).
 **With `--parallel`:** Epochs 4-5 run concurrently (~3 minutes total).
 
-   **a. Lotus Step:**
+**Lotus Step:**
    - Start Lotus daemon container
    - Wait for API file
    - Verify RPC connectivity
 
-   **b. Lotus Miner Step:**
+**Lotus Miner Step:**
    - Import pre-sealed sectors
    - Initialize miner
    - Start mining
 
-   **c. ETH Account Funding Step:**
+**ETH Account Funding Step:**
    - Transfer FIL to create FEVM addresses
    - Fund deployer accounts
    - Wait for address activation
 
-   **d. MockUSDFC Deploy Step:**
+**MockUSDFC Deploy Step:**
    - Deploy ERC-20 test token
    - Save contract address
 
-   **e. USDFC Funding Step:**
+**USDFC Funding Step:**
    - Transfer tokens to test accounts
    - Fund Curio SPs
 
-   **f. Multicall3 Deploy Step:**
+**Multicall3 Deploy Step:**
    - Deploy Multicall3 contract
    - Save contract address
 
-   **g. FOC Deploy Step:**
+**FOC Deploy Step:**
    - Deploy FOC service contracts
    - Deploy PDPVerifier, ServiceProviderRegistry, etc.
    - Save all contract addresses
 
-   **h. Yugabyte Step:**
-   - Start Yugabyte database
+**Yugabyte Step:**
+   - Start Yugabyte database (one instance per Curio SP, on the SP's network)
    - Verify PostgreSQL port
 
-   **i. Curio Step:**
+**Curio Step:**
    - Initialize Curio database schemas
    - Start N Curio SP containers
    - Configure PDP endpoints
 
-   **j. PDP SP Registration Step:**
+**PDP SP Registration Step:**
    - Register each Curio SP in registry
    - Approve authorized SPs
    - Save provider IDs
 
-   **k. Synapse E2E Test Step:**
+**Synapse E2E Test Step:**
    - Run end-to-end verification
-   - Test deal flow (unless `--notest`)
+   - Test deal flow (unless `--notest` flag is used)
 
-**6. Post-start:**
+#### Post Start Steps
    - Save step context
    - Display summary
    - Print access URLs
 
+### running
+At this point the cluster is active and already has contracts deployed.  It is ready for further interaction.
+
+### stop
+- stop containers
+- cleanup networks
+
+### (re)start
+- Regenisis by following the [start steps](#steps) and creating a new blockchain.
+
 ### Step Implementation Pattern
 
 Every step follows this trait:

From f319cfff1ba7aec554c3625372808f761d98ecb6 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:15:42 -0800
Subject: [PATCH 18/26] docs: add inline code comments to Rust examples

- Enhance SetupContext struct comments with detailed explanations
- Add inline comments throughout example flow showing context sharing
- Add method-level comments to Step trait explaining each phase
- Improve code readability by explaining what each part does and why
- Addresses BigLep's comment about adding explanatory content to code examples
---
 README_ADVANCED.md | 35 ++++++++++++++++++++++++++++-------
 1 file changed, 28 insertions(+), 7 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 2cea8a9e..8835a4c7 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -404,36 +404,50 @@ rm -rf ~/.foc-devnet
 **Architecture:**
 ```rust
 pub struct SetupContext {
-    state: Arc<Mutex<HashMap<String, String>>>,  // Shared state
-    run_id: String,                               // Current run ID
-    run_dir: PathBuf,                             // Run directory
-    port_allocator: Arc<Mutex<PortAllocator>>,   // Port manager
+    // Thread-safe key-value store for sharing data between steps
+    // Keys are string literals (see src/commands/start/ for examples)
+    state: Arc<Mutex<HashMap<String, String>>>,
+    // Unique identifier for this cluster run (format: YYYYMMDDTHHMM_RandomName)
+    run_id: String,
+    // Directory where all run-specific data is stored (~/.foc-devnet/run/<run-id>/)
+    run_dir: PathBuf,
+    // Manages dynamic port allocation to avoid conflicts with other services
+    port_allocator: Arc<Mutex<PortAllocator>>,
 }
 ```
 
 **Example flow:**
 
 ```rust
-// Step 1: ETHAccFundingStep creates deployer address
+// Step 1: ETHAccFundingStep creates deployer address and stores it for later steps
 fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>> {
+    // Generate a new Ethereum address for contract deployment
     let address = create_eth_address()?;
+    // Store the address in context so other steps can retrieve it
+    // Context keys are string literals defined in each step's implementation
     context.set("deployer_mockusdfc_eth_address", &address);
     Ok(())
 }
 
-// Step 2: USDFCDeployStep uses that address
+// Step 2: USDFCDeployStep retrieves the address from context and uses it
 fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>> {
+    // Retrieve the deployer address that was set by ETHAccFundingStep
+    // Returns error if key not found (dependency not met)
     let deployer = context
         .get("deployer_mockusdfc_eth_address")
         .ok_or("Deployer not found")?;
+    // Use the deployer address to deploy the MockUSDFC contract
     let contract = deploy_mockusdfc(&deployer)?;
+    // Store the contract address for subsequent steps that need it
     context.set("mockusdfc_contract_address", &contract);
     Ok(())
 }
 
-// Step 3: USDFCFundingStep uses the contract address
+// Step 3: USDFCFundingStep retrieves the contract address and uses it
 fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>> {
+    // Retrieve the contract address set by USDFCDeployStep
     let contract = context.get("mockusdfc_contract_address")?;
+    // Use the contract address to fund test accounts with tokens
     fund_accounts(&contract)?;
     Ok(())
 }
@@ -854,10 +868,17 @@ Every step follows this trait:
 
 ```rust
 pub trait Step: Send + Sync {
+    // Human-readable name for logging and display (e.g., "Lotus", "FOC Deploy")
     fn name(&self) -> &str;
+    // Validation phase: check prerequisites before executing
+    // (e.g., verify Docker images exist, check port availability)
     fn pre_execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>>;
+    // Main work: perform the actual step (e.g., start container, deploy contract)
     fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>>;
+    // Verification phase: confirm step succeeded (e.g., check API is responding)
     fn post_execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>>;
+    // Orchestrates the full step lifecycle: pre_execute → execute → post_execute
+    // Returns the duration taken for the step
     fn run(&self, context: &SetupContext) -> Result<Duration, Box<dyn Error>>;
 }
 ```

From 57c19c31331ea62f95afde0d3deaaafc41ce8c30 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:16:50 -0800
Subject: [PATCH 19/26] docs: rename Advanced Topics and remove Last Updated
 section

- Rename 'Advanced Topics' to 'Additional User Actions' for clarity
- Add explanation of genesis template location (~/.foc-devnet/docker/volumes/run-specific/<run-id>/genesis/)
- Note that genesis templates are generated during genesis prerequisites phase
- Remove 'Last Updated' section (redundant - version control tracks changes)
- Addresses BigLep's comments about improving section naming and removing low-value content
---
 README_ADVANCED.md | 19 +++++++++++++++----
 1 file changed, 15 insertions(+), 4 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 8835a4c7..b72390de 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -1108,10 +1108,23 @@ foc-devnet start
 
 ---
 
-## Advanced Topics
+## Additional User Actions
 
 ### Custom Genesis Block
-Edit genesis templates before `start`:
+
+The genesis template is generated during the genesis prerequisites phase of the `start` command and is located at:
+
+```
+~/.foc-devnet/docker/volumes/run-specific/<run-id>/genesis/
+```
+
+To customize the genesis block, you can:
+- Modify the genesis generation code in `src/commands/start/lotus/` 
+- Edit the template files after they're generated (before the Lotus step completes)
+- Pass custom genesis parameters through the configuration system
+
+**Note:** Customizing genesis requires understanding the Filecoin genesis format. See the [Detailed Start Sequence](#detailed-start-sequence) for when genesis prerequisites run.
+
 ```bash
 # Modify sector size, block time, etc.
 # (Advanced - requires understanding Filecoin genesis format)
@@ -1168,5 +1181,3 @@ docker run --rm --network host \
 - **Docker Documentation:** https://docs.docker.com/
 
 ---
-
-**Last Updated:** January 2026

From 32701fd583417de649e2a1abbcef7205cc1a4e60 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:21:24 -0800
Subject: [PATCH 20/26] docs: remove redundant sections and improve consistency

- Enhance post_execute comment to include 'confirm deployment'
- Remove duplicate 'Phases' section (already explained in inline code comments)
- Remove redundant 'Testing scenarios' section (just comments)
- Remove 'Reference Links' section (redundant with other documentation)
---
 README_ADVANCED.md | 26 +-------------------------
 1 file changed, 1 insertion(+), 25 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index b72390de..6ace5ade 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -875,7 +875,7 @@ pub trait Step: Send + Sync {
     fn pre_execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>>;
     // Main work: perform the actual step (e.g., start container, deploy contract)
     fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>>;
-    // Verification phase: confirm step succeeded (e.g., check API is responding)
+    // Verification phase: confirm step succeeded (e.g., check API is responding, confirm deployment)
     fn post_execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>>;
     // Orchestrates the full step lifecycle: pre_execute → execute → post_execute
     // Returns the duration taken for the step
@@ -883,11 +883,6 @@ pub trait Step: Send + Sync {
 }
 ```
 
-**Phases:**
-1. **Pre-execute:** Validation (check images, ports, prerequisites)
-2. **Execute:** Main work (start container, deploy contract, etc.)
-3. **Post-execute:** Verification (check API, confirm deployment)
-
 ---
 
 ## Service Provider Examples
@@ -981,14 +976,6 @@ docker exec foc-<run-id>-builder cast call \
 # Returns: false
 ```
 
-**Testing scenarios:**
-```bash
-# Send deal to approved SP (should succeed)
-# Send deal to unapproved SP (should fail)
-# Test failover from SP1 to SP2
-# Test SP3 attempting to accept deal (should reject)
-```
-
 ### Example 3: Maximum SPs (5)
 
 **Scenario:** Stress testing, load balancing.
@@ -1170,14 +1157,3 @@ docker run --rm --network host \
   --broadcast
 ```
 
----
-
-## Reference Links
-
-- **Lotus Documentation:** https://lotus.filecoin.io/
-- **Curio Documentation:** https://github.com/filecoin-project/curio
-- **FEVM Documentation:** https://docs.filecoin.io/smart-contracts/
-- **Foundry Book:** https://book.getfoundry.sh/
-- **Docker Documentation:** https://docs.docker.com/
-
----

From 6a0b1cdbe0cf8e0bf7a7e57c1211e022b6cf3054 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:23:19 -0800
Subject: [PATCH 21/26] docs: fix relative links to use correct paths

- Change ../src/config.rs to src/config.rs (root-level paths)
- Change ../src/commands/start/ to src/commands/start/
- Change ../src/commands/start/usdfc_deploy/prerequisites.rs to src/commands/start/usdfc_deploy/prerequisites.rs
- Ensure all local file links use relative paths from root directory
- All relative links now correctly reference files without parent directory traversal
---
 README_ADVANCED.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 6ace5ade..05d8fb4d 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -204,7 +204,7 @@ tag = "synapse-sdk-v0.36.1"
 
 ### How Defaults Work
 
-Defaults are defined in code (see [`src/config.rs`](../src/config.rs) `Config::default()`) and written to `config.toml` during `init`. This means:
+Defaults are defined in code (see [`src/config.rs`](src/config.rs) `Config::default()`) and written to `config.toml` during `init`. This means:
 
 - **First-time setup:** Running `foc-devnet init` creates `config.toml` with current defaults from code
 - **Updating defaults:** When a new version of `foc-devnet` includes updated defaults (e.g., newer Lotus version), run `foc-devnet init --force` to regenerate `config.toml` with the new defaults
@@ -455,7 +455,7 @@ fn execute(&self, context: &SetupContext) -> Result<(), Box<dyn Error>> {
 
 **Common context keys:**
 
-These keys are string literals used throughout the codebase (see step implementations in [`src/commands/start/`](../src/commands/start/)). The definitive list is maintained in the code where steps use `context.get()` and `context.set()`. For an example, see [`src/commands/start/usdfc_deploy/prerequisites.rs`](../src/commands/start/usdfc_deploy/prerequisites.rs). 
+These keys are string literals used throughout the codebase (see step implementations in [`src/commands/start/`](src/commands/start/)). The definitive list is maintained in the code where steps use `context.get()` and `context.set()`. For an example, see [`src/commands/start/usdfc_deploy/prerequisites.rs`](src/commands/start/usdfc_deploy/prerequisites.rs). 
 
 - `deployer_mockusdfc_eth_address` - MockUSDFC deployer address
 - `deployer_foc_eth_address` - FOC contracts deployer address
@@ -686,7 +686,7 @@ port_range_count = 100
 
 ### Version Strategy
 
-Default versions for these repositories are defined in code (see [`src/config.rs`](../src/config.rs) `Config::default()`).
+Default versions for these repositories are defined in code (see [`src/config.rs`](src/config.rs) `Config::default()`).
 
 - **Git tags** (`GitTag`): Used for stable releases. Tags provide version pinning and stability.
 - **Git commits** (`GitCommit`): Used for repositories where specific commits are required and there isn't a corresponding tag yet.  (Generally tags should be preferred over commits.)

From b9d4cc1338f42bb64a2e6f2d59eee3466604b95b Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Fri, 16 Jan 2026 11:27:47 -0800
Subject: [PATCH 22/26] docs: fix grammar, links, inconsistencies, and heading
 levels

- Fix grammar error: 'If you are have troubles' -> 'If you have troubles'
- Fix broken GitHub Issues link in System Requirements table
- Update outdated 'Advanced topics' reference to 'Additional user actions'
- Fix timing inconsistency: align '--parallel' timing with detailed sequence (~5 min to ~3 min)
- Fix Yugabyte note: change 'shared by all SPs' to 'one per SP' and update to yugabyte-1
- Fix heading levels: change running/stop/(re)start from ### to #### under Lifecycle Overview
- Fix typos: 'Regenisis' -> 'Regenesis', improve capitalization
- Fix formatting: remove extra blank line after --force option
- Keep latest symlink references (feature documented in code)
---
 README.md          |  6 +++---
 README_ADVANCED.md | 25 ++++++++++++-------------
 2 files changed, 15 insertions(+), 16 deletions(-)

diff --git a/README.md b/README.md
index 86eaee72..17bc1a48 100644
--- a/README.md
+++ b/README.md
@@ -66,7 +66,7 @@ This will:
 - Start storage provider(s)
 - Launch [Portainer UI](https://docs.docksal.io/use-cases/portainer/) for container management
 
-**If you are have troubles**: Use `cargo run -- start`, removing parallelism during start, this may take longer.
+**If you have troubles**: Use `cargo run -- start`, removing parallelism during start, this may take longer.
 
 **That's it!** Your local Filecoin network is running.
 
@@ -139,7 +139,7 @@ Bundled with Portainer for browser-based Docker management—no terminal wizardr
 | **Docker** | Desktop (macOS) or CE (Linux) |
 | **tar** | Archive utility (usually pre-installed) |
 | **Disk Space** | ~20GB for images and blockchain data |
-| **x86 Architecture** | ??? dependencies require x86 (Intel) architecture.  As a result, ARM-based architectures (including Apple Silicon) are not supported. |b.com/FilOzone/foc-devnet/issues) for current architecture compatibility status.
+| **x86 Architecture** | Some dependencies require x86 (Intel) architecture. As a result, ARM-based architectures (including Apple Silicon) may not be supported. See [GitHub Issues](https://github.com/FilOzone/foc-devnet/issues) for current architecture compatibility status. |
 
 ---
 
@@ -157,7 +157,7 @@ See **[README_ADVANCED.md](README_ADVANCED.md)** for comprehensive documentation
 - **Lifecycle overview** (full startup sequence, step implementation)
 - **Service Provider examples** (1 SP with 0 authorized, 3 SPs with top 2 authorized, etc.)
 - **Troubleshooting guides** (port conflicts, build failures, network issues)
-- **Advanced topics** (custom genesis, Lotus API access, contract interaction)
+- **Additional user actions** (custom genesis, Lotus API access, contract interaction)
 
 ---
 
diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index 05d8fb4d..d6cd72ca 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -21,9 +21,8 @@ foc-devnet init [OPTIONS]
 - `--yugabyte-url <URL>` - Yugabyte download URL
 - `--yugabyte-archive <PATH>` - Local Yugabyte archive file
 - `--proof-params-dir <PATH>` - Local proof params directory
-- `--force` - Force regeneration of config file.  Useful when switching between configurations.
-
-- `--rand` - Use random mnemonic instead of deterministic one.  Use this for unique test scenarios.
+- `--force` - Force regeneration of config file. Useful when switching between configurations.
+- `--rand` - Use random mnemonic instead of deterministic one. Use this for unique test scenarios.
 
 **Source Format:**
 - `gittag:v1.0.0` - Specific git tag (uses default repo)
@@ -74,7 +73,7 @@ foc-devnet start [OPTIONS]
 - `--parallel` - **⚡ Run steps in parallel for ~40% faster startup (recommended)**
 
 **Why `--parallel` (Recommended):**
-- **⚡ Significant speedup:** Reduces startup time from ~10 min to ~6 min
+- **⚡ Significant speedup:** Reduces startup time from ~5 min to ~3 min
 - **Smart parallelization:** Steps that don't depend on each other run concurrently
 - **Production-ready:** Thread-safe implementation with proper synchronization
 - **Use case:** Default for most workflows, especially development iteration
@@ -852,15 +851,15 @@ Steps run sequentially by default, or in parallel when using the `--parallel` fl
    - Display summary
    - Print access URLs
 
-### running
-At this point the cluster is active and already has contracts deployed.  It is ready for further interaction.
+#### running
+At this point the cluster is active and already has contracts deployed. It is ready for further interaction.
 
-### stop
-- stop containers
-- cleanup networks
+#### stop
+- Stops containers
+- Cleans up networks
 
-### (re)start
-- Regenisis by following the [start steps](#steps) and creating a new blockchain.
+#### (re)start
+- Regenesis by following the [start steps](#steps) and creating a new blockchain.
 
 ### Step Implementation Pattern
 
@@ -1028,8 +1027,8 @@ docker logs foc-<run-id>-curio-2
 # Query provider IDs
 cat ~/.foc-devnet/state/latest/pdp_sps/*.provider_id.json
 
-# Access Yugabyte (shared by all SPs)
-docker exec -it foc-<run-id>-yugabyte ysqlsh -h localhost -p 5433
+# Access Yugabyte (one per SP)
+docker exec -it foc-<run-id>-yugabyte-1 ysqlsh -h localhost -p 5433
 
 # Query Lotus for miner info
 docker exec foc-<run-id>-lotus lotus state miner-info f01000

From 43aef14b9aedaf595cebf09ebd041dafe2a4528b Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Wed, 21 Jan 2026 13:37:36 -0800
Subject: [PATCH 23/26] docs: update architecture requirement to reflect
 macOS/ARM support

- Change from 'x86 Architecture' requirement to 'Architecture' supporting both x86 and ARM64
- Update text to reflect that system automatically selects appropriate binaries
- Reflects changes from PR #32 which added ARM64/Apple Silicon support
---
 README.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 17bc1a48..ff98b663 100644
--- a/README.md
+++ b/README.md
@@ -139,7 +139,7 @@ Bundled with Portainer for browser-based Docker management—no terminal wizardr
 | **Docker** | Desktop (macOS) or CE (Linux) |
 | **tar** | Archive utility (usually pre-installed) |
 | **Disk Space** | ~20GB for images and blockchain data |
-| **x86 Architecture** | Some dependencies require x86 (Intel) architecture. As a result, ARM-based architectures (including Apple Silicon) may not be supported. See [GitHub Issues](https://github.com/FilOzone/foc-devnet/issues) for current architecture compatibility status. |
+| **Architecture** | Supports both x86 (Intel) and ARM64 (Apple Silicon, AWS Graviton, etc.) architectures. The system automatically selects the appropriate binaries based on your architecture. |
 
 ---
 

From f387ce4d5496a7a9a08e78df68b2a7c05be42a21 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Wed, 21 Jan 2026 13:52:26 -0800
Subject: [PATCH 24/26] docs: refine dependency repository management section

- Rename 'Repository Management' to 'Dependency Repository Management'
- Rename 'Required Repositories' to 'Required Dependent Repositories'
- Rename 'Version Strategy' to 'Dependent Version Strategy'
- Simplify version strategy explanation
- Rename 'Using Local Repositories' to 'Using Local Dependency Repositories'
- Add note about using same foc-devnet commit when sharing config
- Clarify reproducible builds use 'tags or commits' not just 'commits'
---
 README_ADVANCED.md | 28 ++++++++++++++--------------
 1 file changed, 14 insertions(+), 14 deletions(-)

diff --git a/README_ADVANCED.md b/README_ADVANCED.md
index d6cd72ca..4c3d75b4 100644
--- a/README_ADVANCED.md
+++ b/README_ADVANCED.md
@@ -40,22 +40,21 @@ foc-devnet init \
 ```
 
 ### `build`
-Builds Filecoin components in Docker containers.
+Builds Lotus and Curio binaries in Docker containers.
 
 > **Note:** This command must be run after `init` to ensure Docker images and environment are prepared.
 
 ```bash
-foc-devnet build lotus [PATH] [--output-dir <DIR>]
-foc-devnet build curio [PATH] [--output-dir <DIR>]
+foc-devnet build lotus [PATH]
+foc-devnet build curio [PATH]
 ```
 
-**Options:**
-- `--output-dir <DIR>` - Directory for built binaries (default: `~/.foc-devnet/bin`)
+**Note:** Binaries are built to `~/.foc-devnet/bin/` which is the expected location for the system.
 
 **Example:**
 ```bash
 foc-devnet build lotus
-foc-devnet build curio /path/to/custom/curio --output-dir ~/bins
+foc-devnet build curio /path/to/custom/curio
 ```
 
 ### `start`
@@ -68,8 +67,6 @@ foc-devnet start [OPTIONS]
 ```
 
 **Options:**
-- `--volumes-dir <DIR>` - Custom docker volumes directory. Use custom paths (e.g., faster SSD, network storage).
-- `--run-dir <DIR>` - Custom run-specific data directory. Use custom paths (e.g., faster SSD, network storage).
 - `--parallel` - **⚡ Run steps in parallel for ~40% faster startup (recommended)**
 
 **Why `--parallel` (Recommended):**
@@ -671,11 +668,11 @@ port_range_count = 100
 
 ---
 
-## Repository Management
+## Dependency Repository Management
 
 
 
-### Required Repositories
+### Required Dependent Repositories
 
 - **[lotus](https://github.com/filecoin-project/lotus)** - Filecoin daemon
 - **[curio](https://github.com/filecoin-project/curio)** - Storage provider (PDP)
@@ -683,17 +680,18 @@ port_range_count = 100
 - **[multicall3](https://github.com/mds1/multicall3)** - Multicall3 contract
 - **[synapse-sdk](https://github.com/FilOzone/synapse-sdk)** - PDP verification SDK
 
-### Version Strategy
+### Dependent Version Strategy
 
 Default versions for these repositories are defined in code (see [`src/config.rs`](src/config.rs) `Config::default()`).
 
+**Version specification methods:**
 - **Git tags** (`GitTag`): Used for stable releases. Tags provide version pinning and stability.
-- **Git commits** (`GitCommit`): Used for repositories where specific commits are required and there isn't a corresponding tag yet.  (Generally tags should be preferred over commits.)
+- **Git commits** (`GitCommit`): Used for repositories where specific commits are required and there isn't a corresponding tag yet. (Generally tags should be preferred over commits.)
 - **Git branches** (`GitBranch`): Used for development or when tracking latest changes.
 
 **Updating defaults:** See [How Defaults Work](#how-defaults-work) for information on how defaults are defined and the steps to apply updates.
 
-### Using Local Repositories
+### Using Local Dependency Repositories
 
 **For active development:**
 
@@ -724,6 +722,8 @@ foc-devnet init \
 cp shared-config.toml ~/.foc-devnet/config.toml
 
 # Run init to download and build
+# Note: this assumes that both parties are using the same commit of `foc-devnet`
+# and that dependency versions in `config.toml` are all tags or commits (rather than branches).
 foc-devnet init
 ```
 
@@ -731,7 +731,7 @@ foc-devnet init
 
 ### Reproducible Builds
 
-For reproducible builds, specify exact commits in `config.toml`:
+For reproducible builds, specify exact tags or commits in `config.toml`:
 
 ```toml
 [lotus]

From 18ee18ef3db345b27032c9db322fc4684a4337b1 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Wed, 21 Jan 2026 13:56:13 -0800
Subject: [PATCH 25/26] refactor: remove unused CLI flags for directory paths

Remove --output-dir, --volumes-dir, and --run-dir flags as they are
either unused or should not be user-configurable. The system now always
uses fixed default paths:

- ~/.foc-devnet/bin/ for build outputs
- ~/.foc-devnet/docker-volumes/<run-id>/ for Docker volumes
- ~/.foc-devnet/run/<run-id>/ for run-specific data

This simplifies the CLI interface and ensures consistent behavior.
---
 src/cli.rs                       | 12 ------------
 src/commands/mod.rs              |  4 +---
 src/commands/start/mod.rs        | 16 +++-------------
 src/main.rs                      |  4 +---
 src/main_app/command_handlers.rs |  6 +-----
 5 files changed, 6 insertions(+), 36 deletions(-)

diff --git a/src/cli.rs b/src/cli.rs
index 3941519d..62995742 100644
--- a/src/cli.rs
+++ b/src/cli.rs
@@ -15,12 +15,6 @@ pub struct Cli {
 pub enum Commands {
     /// Start the local cluster
     Start {
-        /// Directory where docker volumes to be loaded will be stored
-        #[arg(long)]
-        volumes_dir: Option<String>,
-        /// Directory where run-specific data and logs will be stored
-        #[arg(long)]
-        run_dir: Option<String>,
         /// Run steps in parallel where possible (experimental)
         #[arg(long)]
         parallel: bool,
@@ -81,17 +75,11 @@ pub enum BuildCommands {
     Lotus {
         /// Path to the Lotus source directory (optional, will clone if not provided)
         path: Option<PathBuf>,
-        /// Output directory for built binaries
-        #[arg(long)]
-        output_dir: Option<PathBuf>,
     },
     /// Build Curio
     Curio {
         /// Path to the Curio source directory (optional, will clone if not provided)
         path: Option<PathBuf>,
-        /// Output directory for built binaries
-        #[arg(long)]
-        output_dir: Option<PathBuf>,
     },
 }
 
diff --git a/src/commands/mod.rs b/src/commands/mod.rs
index ed1b97c7..754ff77e 100644
--- a/src/commands/mod.rs
+++ b/src/commands/mod.rs
@@ -20,11 +20,9 @@ pub use status::status;
 pub use stop::stop_cluster;
 
 pub fn start_cluster(
-    volumes_dir: Option<String>,
-    run_dir: Option<String>,
     parallel: bool,
     run_id: String,
     notest: bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
-    start::start_cluster(volumes_dir, run_dir, parallel, run_id, notest)
+    start::start_cluster(parallel, run_id, notest)
 }
diff --git a/src/commands/start/mod.rs b/src/commands/start/mod.rs
index 634ca6e9..4921a6fa 100644
--- a/src/commands/start/mod.rs
+++ b/src/commands/start/mod.rs
@@ -51,21 +51,13 @@ fn stop_existing_cluster() -> Result<(), Box<dyn std::error::Error>> {
 
 /// Setup directories, run ID, and version information for the cluster startup.
 fn setup_directories_and_run_id(
-    volumes_dir: Option<String>,
-    _run_dir: Option<String>,
     run_id: String,
 ) -> Result<(PathBuf, PathBuf, String), Box<dyn std::error::Error>> {
     // Save run ID to persistent storage
     save_current_run_id(&run_id)?;
 
-    // Determine volumes directory
-    let volumes_dir = if let Some(dir) = volumes_dir {
-        PathBuf::from(dir)
-    } else {
-        crate::paths::foc_devnet_docker_volumes_run_specific(&run_id)
-    };
-
-    // Determine run directory
+    // Use default paths
+    let volumes_dir = crate::paths::foc_devnet_docker_volumes_run_specific(&run_id);
     let run_dir = foc_devnet_run_dir(&run_id);
 
     // Create directories if they don't exist
@@ -405,8 +397,6 @@ fn execute_cluster_steps(
 
 /// Start the local Filecoin network cluster.
 pub fn start_cluster(
-    volumes_dir: Option<String>,
-    run_dir: Option<String>,
     parallel: bool,
     run_id: String,
     notest: bool,
@@ -414,7 +404,7 @@ pub fn start_cluster(
     stop_existing_cluster()?;
 
     let (volumes_dir, run_dir, run_id) =
-        setup_directories_and_run_id(volumes_dir, run_dir, run_id)?;
+        setup_directories_and_run_id(run_id)?;
 
     // Stop any running containers (but preserve old run data)
     stop_running_containers()?;
diff --git a/src/main.rs b/src/main.rs
index d5ffc5fe..ff1593ca 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -23,12 +23,10 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
     // Execute the command with poison file protection
     let result = match cli.command {
         Commands::Start {
-            volumes_dir,
-            run_dir,
             parallel,
             notest,
         } => {
-            main_app::command_handlers::handle_start(volumes_dir, run_dir, parallel, run_id, notest)
+            main_app::command_handlers::handle_start(parallel, run_id, notest)
         }
         Commands::Stop => main_app::command_handlers::handle_stop(),
         Commands::Init {
diff --git a/src/main_app/command_handlers.rs b/src/main_app/command_handlers.rs
index 95fdd6e0..63d02be2 100644
--- a/src/main_app/command_handlers.rs
+++ b/src/main_app/command_handlers.rs
@@ -14,14 +14,12 @@ use foc_devnet::poison;
 
 /// Execute the start command
 pub fn handle_start(
-    volumes_dir: Option<String>,
-    run_dir: Option<String>,
     parallel: bool,
     run_id: String,
     notest: bool,
 ) -> Result<(), Box<dyn std::error::Error>> {
     poison::create_poison("Start")?;
-    commands::start_cluster(volumes_dir, run_dir, parallel, run_id, notest)
+    commands::start_cluster(parallel, run_id, notest)
 }
 
 /// Execute the stop command
@@ -73,11 +71,9 @@ pub fn handle_build(build_command: BuildCommands) -> Result<(), Box<dyn std::err
     match build_command {
         BuildCommands::Lotus {
             path: _,
-            output_dir: _,
         } => commands::build_project(&Project::Lotus, &config),
         BuildCommands::Curio {
             path: _,
-            output_dir: _,
         } => commands::build_project(&Project::Curio, &config),
     }
 }

From da395b5f90f96c11089dab4902120748b20aebf7 Mon Sep 17 00:00:00 2001
From: Steve Loeppky <stvn@loeppky.com>
Date: Wed, 21 Jan 2026 13:57:34 -0800
Subject: [PATCH 26/26] style: fix rustfmt formatting issues

- Format match arms on single lines where appropriate
- Format function call on single line
---
 src/commands/start/mod.rs        | 3 +--
 src/main.rs                      | 5 +----
 src/main_app/command_handlers.rs | 8 ++------
 3 files changed, 4 insertions(+), 12 deletions(-)

diff --git a/src/commands/start/mod.rs b/src/commands/start/mod.rs
index 4921a6fa..fb09d895 100644
--- a/src/commands/start/mod.rs
+++ b/src/commands/start/mod.rs
@@ -403,8 +403,7 @@ pub fn start_cluster(
 ) -> Result<(), Box<dyn std::error::Error>> {
     stop_existing_cluster()?;
 
-    let (volumes_dir, run_dir, run_id) =
-        setup_directories_and_run_id(run_id)?;
+    let (volumes_dir, run_dir, run_id) = setup_directories_and_run_id(run_id)?;
 
     // Stop any running containers (but preserve old run data)
     stop_running_containers()?;
diff --git a/src/main.rs b/src/main.rs
index ff1593ca..1ce750cd 100644
--- a/src/main.rs
+++ b/src/main.rs
@@ -22,10 +22,7 @@ fn main() -> Result<(), Box<dyn std::error::Error>> {
 
     // Execute the command with poison file protection
     let result = match cli.command {
-        Commands::Start {
-            parallel,
-            notest,
-        } => {
+        Commands::Start { parallel, notest } => {
             main_app::command_handlers::handle_start(parallel, run_id, notest)
         }
         Commands::Stop => main_app::command_handlers::handle_stop(),
diff --git a/src/main_app/command_handlers.rs b/src/main_app/command_handlers.rs
index 63d02be2..0117903b 100644
--- a/src/main_app/command_handlers.rs
+++ b/src/main_app/command_handlers.rs
@@ -69,12 +69,8 @@ pub fn handle_build(build_command: BuildCommands) -> Result<(), Box<dyn std::err
         .map_err(|e| format!("Failed to parse config file: {}", e))?;
 
     match build_command {
-        BuildCommands::Lotus {
-            path: _,
-        } => commands::build_project(&Project::Lotus, &config),
-        BuildCommands::Curio {
-            path: _,
-        } => commands::build_project(&Project::Curio, &config),
+        BuildCommands::Lotus { path: _ } => commands::build_project(&Project::Lotus, &config),
+        BuildCommands::Curio { path: _ } => commands::build_project(&Project::Curio, &config),
     }
 }