docs: Incorporate BigLep documentation comments from PR #16 (#33)

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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

* 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)

* 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

* 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)

* 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

* 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'

* 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.

* style: fix rustfmt formatting issues

- Format match arms on single lines where appropriate
- Format function call on single line

Author: BigLep

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.
 
@@ -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,12 +139,13 @@ 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 |
+| **Architecture** | Supports both x86 (Intel) and ARM64 (Apple Silicon, AWS Graviton, etc.) architectures. The system automatically selects the appropriate binaries based on your architecture. |
 
 ---
 
 ## 🛠️ 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)
@@ -156,7 +157,7 @@ See **[ADVANCED_README.md](ADVANCED_README.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)
 
 ---