adjustments

Author: tac0turtle

docs/concepts/block-lifecycle.md

@@ -433,7 +433,7 @@ For more details on DA integration, see the [Data Availability specification](./
 #### Out-of-Order Chain Blocks on DA
 
 Evolve should support blocks arriving out-of-order on DA, like so:
-![out-of-order blocks](./out-of-order-blocks.png)
+![out-of-order blocks](../reference/specs/out-of-order-blocks.png)
 
 ### Block Sync Service (Syncer Component)
 
@@ -650,7 +650,7 @@ The components communicate through well-defined interfaces:
 
 ### P2P and Synchronization
 
-- Block sync over the P2P network works only when a full node is connected to the P2P network by specifying the initial seeds to connect to via `P2PConfig.Seeds` configuration parameter when starting the full node
+- Block sync over the P2P network works only when a full node is connected to the P2P network by specifying peers via the `P2PConfig.Peers` configuration parameter when starting the full node
 - Node's context is passed down to all components to support graceful shutdown and cancellation
 
 ## Metrics

docs/concepts/data-availability.md

@@ -14,7 +14,7 @@ Evolve uses external DA layers to provide these guarantees, rather than storing
 
 ## How Evolve Handles Data Availability
 
-Evolve is DA-agnostic and can integrate with different DA layers:
+Evolve currently supports two DA modes:
 
 ### Local DA
 
@@ -28,10 +28,6 @@ Evolve is DA-agnostic and can integrate with different DA layers:
 - **Guarantee**: Data availability sampling (DAS)
 - **Latency**: ~12 seconds to finality
 
-### Custom DA
-
-Implement the [DA interface](/reference/interfaces/da) to integrate any DA layer.
-
 ## DA Flow
 
 ```

docs/getting-started/choose-your-path.md

@@ -2,6 +2,8 @@
 
 Evolve supports three execution environments. Your choice depends on your existing codebase, target users, and development resources.
 
+Use this as a decision page, then jump into the selected quickstart.
+
 ## Quick Comparison
 
 |                      | EVM (ev-reth)                      | Cosmos SDK (ev-abci)        | Custom Executor     |

docs/getting-started/custom/quickstart.md

@@ -2,6 +2,8 @@
 
 Build a minimal custom executor to understand how ev-node integrates with execution layers.
 
+This page is a fast entry point. For a method-by-method implementation walkthrough, continue with [Implement Executor Interface](/getting-started/custom/implement-executor).
+
 ## Prerequisites
 
 - Go 1.22+

docs/guides/advanced/forced-inclusion.md

@@ -91,11 +91,11 @@ If a sequencer fails to include forced inclusion transactions past their epoch b
 
 When a malicious sequencer is detected (censoring forced inclusion transactions):
 
-**All nodes must restart the chain in based sequencing mode:**
+Nodes may require a coordinated restart into based sequencing mode, depending on governance and operator policy.
 
 ```bash
-# Restart with based sequencing enabled
-./evnode start --node.aggregator --node.based_sequencer
+# One possible coordinated recovery action
+./evnode start --evnode.node.aggregator --evnode.node.based_sequencer
 ```
 
 **In based sequencing mode:**
@@ -107,10 +107,11 @@ When a malicious sequencer is detected (censoring forced inclusion transactions)
 
 **Important considerations:**
 
+- Operators should agree on the last valid state and restart timing before the cutover.
 - All full nodes should coordinate the switch to based mode
 - The chain continues from the last valid state
 - Users submit transactions directly to the DA layer going forward
-- This is a one-way transition - moving back to single sequencer requires social consensus
+- Returning to single sequencer mode requires explicit governance and operational coordination
 
 See [Based Sequencing documentation](./based.md) for details on operating in this mode.
 

docs/guides/da-layers/celestia.md

@@ -17,9 +17,19 @@ Follow the [Celestia documentation](https://docs.celestia.org/how-to-guides/ligh
 
 **Quick start:**
 
+> Warning: Piping a remote script directly into a shell is a supply-chain risk. Review and verify the installer before execution in production environments.
+
 ```bash
 # Install celestia-node
 curl -sL https://docs.celestia.org/install.sh | bash
+```
+
+Safer flow (download, inspect, then execute):
+
+```bash
+curl -fsSL -o install-celestia.sh https://docs.celestia.org/install.sh
+less install-celestia.sh
+bash install-celestia.sh
 
 # Initialize (choose your network)
 celestia light init --p2p.network mocha
@@ -137,7 +147,7 @@ Search by your namespace or account address to see submitted blobs.
 
 ### Gas Price
 
-By default, ev-node uses automatic gas price detection. You can override this with a manual value if needed:
+By default, ev-node uses automatic gas price detection. Keep the default unless you have an operational reason to override it:
 
 ```bash
 --evnode.da.gas_price 0.01

docs/guides/operations/deployment.md

@@ -4,6 +4,8 @@ description: This page provides an overview of some common ways to deploy chains
 
 # 🚀 Deploying Your Chain
 
+This page is a deployment index. Use it to choose the right deployment guide for your current stage, then follow the linked step-by-step guide.
+
 One of the benefits of building chains with Evolve is the flexibility you have as a developer to choose things like the DA layer, the settlement scheme, and the execution environment.
 
 You can learn more about Evolve architecture [here](../../learn/specs/overview.md).
@@ -40,6 +42,15 @@ Choose the deployment approach that matches your current needs:
 
 - [🌐 Testnet Deployment](./testnet.md) - Deploy on testnet with external DA networks
 
+## ✅ Before You Deploy
+
+Use this checklist before moving from local development to shared environments:
+
+1. Confirm DA connectivity and funding.
+2. Configure monitoring and alerting.
+3. Validate backup and recovery procedures.
+4. Run a multi-node failover drill.
+
 :::warning Disclaimer
 These examples are for educational purposes only. Before deploying your chain for production use you should fully understand the services you are deploying and your choice in deployment method.
 :::

docs/guides/operations/troubleshooting.md

@@ -17,10 +17,17 @@ curl http://localhost:26657/status
 
 ### View Logs
 
-If running ev-node as a systemd service:
+Use the log command that matches your runtime:
 
 ```bash
+# systemd service
 journalctl -u evnode -f
+
+# foreground process
+./evnode start ... 2>&1 | tee evnode.log
+
+# docker container
+docker logs -f <container_name>
 ```
 
 ## Common Issues

docs/guides/running-nodes/full-node.md

@@ -83,6 +83,7 @@ Key points about this command:
 - `chain_id` is generally the `$CHAIN_ID`, which is `gm` in this case.
 - The ports and addresses are different from the sequencer node to avoid conflicts. Not everything may be necessary for your setup.
 - We use the `P2P_ID` environment variable to set the seed node.
+- You can set the same values in your app config file instead of passing every option via CLI flags.
 
 ## Verifying Full Node Operation
 

docs/overview/what-is-evolve.md

@@ -6,13 +6,13 @@ Built on Celestia, Evolve offers L1-level control with L2-level performance.
 
 This isn't a toolkit. It's a launch stack.
 
-No fees. No middlemen. No revenue share.
+No fees, no middlemen, no revenue share.
 
 ## What is Evolve
 
 Evolve is a launch stack for L1s. It gives you full control over execution — without CometBFT, validator ops, or lock-in.
 
-It's [open-source](https://github.com/evstack/ev-node), production-ready, and fully composable.
+Evolve is [open-source](https://github.com/evstack/ev-node), production-ready, and fully composable.
 
 At its core is \`ev-node\`, a modular node that exposes an [Execution interface](https://github.com/evstack/ev-node/blob/main/core/execution/execution.go), — letting you bring any VM or execution logic, including Cosmos SDK or custom-built runtimes.
 
@@ -60,7 +60,7 @@ With Evolve, developers can benefit from:
 
 - **Scalability:** Evolve chains are deployed on specialized data availability layers like Celestia, which directly leverages the scalability of the DA layer. Additionally, chain transactions are executed off-chain rather than on the data availability layer. This means chains have their own dedicated computational resources, rather than sharing computational resources with other applications.
 
-- **Customizability:** Evolve is built as an open source modular framework, to make it easier for developers to reuse the four main components and customize their chains. These components are data availability layers, execution environments, proof systems, and sequencer schemes.
+- **Customizability:** Evolve is built as an open-source modular framework, to make it easier for developers to reuse the four main components and customize their chains. These components are data availability layers, execution environments, proof systems, and sequencer schemes.
 
 - **Faster time-to-market:** Evolve eliminates the need to bootstrap a validator set, manage a consensus network, incur high economic costs, and face other trade-offs that come with deploying a legacy layer 1\. Evolve's goal is to make deploying a chain as easy as it is to deploy a smart contract, cutting the time it takes to bring blockchain products to market from months (or even years) to just minutes.