docs: fix README, CONTRIBUTING, and AGENTS drift

AGENTS.md

@@ -18,18 +18,28 @@ pluto/
     build-proto/           # Protobuf/build-time code generation
     cli/                   # `pluto` CLI binary and command wiring
     cluster/               # Cluster types and helpers
+    consensus/             # QBFT consensus protocol implementation
     core/                  # Core domain logic
     crypto/                # Cryptographic primitives and helpers
     dkg/                   # Distributed key generation logic
+    eth1wrap/              # Execution-layer (eth1) client wrapper
     eth2api/               # Beacon-node API client types/helpers
     eth2util/              # Ethereum consensus utility code
+    featureset/            # Feature flag management
+    frost/                 # FROST threshold signature implementation
+    infosync/              # Peer info synchronisation protocol
     k1util/                # Secp256k1 utilities
     p2p/                   # P2P networking (libp2p)
+    parsigex/              # Partial-signature exchange protocol
     peerinfo/              # Peer info utilities
+    priority/              # Priority queue / duty prioritisation
     relay-server/          # Relay server implementation
+    ssz/                   # SSZ serialisation helpers
     testutil/              # Test helpers/fixtures (workspace-internal)
     tracing/               # Observability/tracing utilities
+  scripts/                 # Helper shell scripts (cluster comparison, DKG runner, etc.)
   test-infra/              # Docker-compose and local infra for integration testing/observability
+  third_party/             # Vendored third-party code (e.g. patched libp2p multistream-select)
   deny.toml                # `cargo deny` policy
   rust-toolchain.toml      # Rust toolchain pin
   rustfmt.toml             # Formatting rules

CONTRIBUTING.md

@@ -10,7 +10,9 @@ The easiest way to set up the development environment is using [Nix](https://nix
 nix develop
 ```
 
-This automatically provides all required dependencies (Rust toolchain, Protobuf, oas3-gen, cargo-deny, cargo-machete) and configures git hooks.
+This automatically provides the auxiliary dependencies (Protobuf, Go, oas3-gen, cargo-deny, cargo-machete) and configures git hooks.
+
+> **Note:** `nix develop` does **not** manage the Rust toolchain. The toolchain is pinned in `rust-toolchain.toml` and must be installed separately via [rustup](https://rustup.rs/). After installing rustup, run `rustup show` once in the repo root to install the pinned toolchain automatically. The nightly toolchain is also required for `rustfmt` — install it with `rustup toolchain install nightly`.
 
 ### Manual Setup
 
@@ -29,6 +31,8 @@ Then install the pre-push git hook:
 git config core.hooksPath .githooks
 ```
 
+The pre-push hook (`.githooks/pre-push`) runs the full quality-gate sequence in order: `cargo deny check`, `cargo machete`, `cargo +nightly fmt --all -- --check`, `cargo clippy --locked --all-targets --all-features -- -D warnings`, and `cargo test --locked --workspace --all-features`. All checks must pass before a push is accepted.
+
 ## Building
 To build the project with all its crates, run:
 
@@ -43,6 +47,8 @@ To run all tests - unit and integration - run:
 cargo test --workspace --all-features
 ```
 
+> **Note:** `--all-features` enables the `integration` feature in `crates/eth2api`, which uses [testcontainers](https://github.com/testcontainers/testcontainers-rs) and therefore requires a **running Docker daemon**. Without Docker the integration tests will fail with opaque errors. Smoke tests that invoke Go tooling (e.g. `create-cluster-compare.sh`) additionally require [Go](https://go.dev/dl/) to be installed.
+
 ## Running the Rust Documentation Locally
 To build the documentation locally:
 
@@ -102,9 +108,9 @@ This command will open a browser page that contains a graphic representation of
 
 ### Dhat
 We can add Dhat as a dependency:
-```rust
+```toml
 [dependencies]
-dhat = "latest"
+dhat = "0.3"
 
 [features]
 dhat-heap = []

README.md

@@ -22,16 +22,39 @@ The important sections are [intro](https://docs.obol.org/learn/charon),
 
 ## Version compatibility
 
-Considering [semver](https://semver.org) as the project's versioning scheme, two given versions of Charon are:
+Pluto tracks [Charon](https://github.com/ObolNetwork/charon/) parity: the workspace version reflects the Charon release that Pluto aims to be compatible with.
+
+Following [semver](https://semver.org), two given versions of Pluto are:
  - **compatible** if their `MAJOR` number is the same, `MINOR` and `PATCH` numbers differ
  - **incompatible** if their `MAJOR` number differs
 
-There are several reasons to justify a new `MAJOR` release, for example:
- - a new Ethereum hardfork
- - an old Ethereum hardfork is removed due to network inactivity
- - modifications to the internal P2P network or consensus mechanism requiring deep changes to the codebase
+Reasons for a new `MAJOR` release include a new Ethereum hardfork, removal of an old hardfork, or breaking changes to the internal P2P network or consensus mechanism.
+
+The `pluto dkg` subcommand is **more restrictive**: all peers must run matching `MAJOR` and `MINOR` versions for the DKG ceremony; patch versions may differ, though running the latest patch is recommended.
+
+## Build / Run / Test
+
+**Docker (pre-built image):**
+```sh
+docker pull ghcr.io/nethermindeth/pluto:latest
+docker run --rm ghcr.io/nethermindeth/pluto:latest pluto --help
+```
+
+**Build from source:**
+```sh
+cargo build --release --workspace
+```
+
+**Run tests:**
+```sh
+cargo test --workspace --all-features   # requires a running Docker daemon
+```
 
-The `charon dkg` subcommand **is more restrictive** than this general compatibility promise; all peers should use matching `MAJOR` and `MINOR` versions of Charon for the DKG process, patch versions may differ though it is recommended to use the latest patch of any version.
+**Local cluster with test-infra:**
+```sh
+cd test-infra
+docker compose up
+```
 
 ## Examples
 
@@ -40,9 +63,14 @@ Examples are located in crate-specific example folders:
 - [Relay Server](crates/relay-server/examples/relay_server.rs)
 - [Peerinfo](crates/peerinfo/examples/peerinfo.rs)
 - [P2P](crates/p2p/examples/p2p.rs)
+- [P2P Bootnode](crates/p2p/examples/bootnode.rs)
 - [Quic Upgrade](crates/p2p/examples/quic_upgrade.rs)
 - [Metrics](crates/p2p/examples/metrics.rs)
 - [Tracing](crates/tracing/examples/basic.rs)
+- [Consensus (QBFT)](crates/consensus/examples/qbft.rs)
+- [DKG Broadcast](crates/dkg/examples/bcast.rs)
+- [DKG Sync](crates/dkg/examples/sync.rs)
+- [Parsigex](crates/parsigex/examples/parsigex.rs)
 
 ## License
 

crates/cli/src/cli.rs

@@ -51,7 +51,7 @@ pub enum Commands {
 
     #[command(
         about = "Start a libp2p relay server",
-        long_about = "Starts a libp2p circuit relay that charon clients can use to discover and connect to their peers."
+        long_about = "Starts a libp2p circuit relay that Pluto clients can use to discover and connect to their peers."
     )]
     Relay(Box<RelayArgs>),
 
@@ -110,7 +110,7 @@ pub struct AlphaArgs {
 pub enum AlphaCommands {
     #[command(
         about = "Test subcommands provide test suite to evaluate current cluster setup",
-        long_about = "Test subcommands provide test suite to evaluate current cluster setup. The full validator stack can be tested - charon peers, consensus layer, validator client, MEV. Current machine's infra can be examined as well."
+        long_about = "Test subcommands provide test suite to evaluate current cluster setup. The full validator stack can be tested - Pluto peers, consensus layer, validator client, MEV. Current machine's infra can be examined as well."
     )]
     Test(Box<TestArgs>),
 }
@@ -127,31 +127,31 @@ pub struct TestArgs {
 pub enum TestCommands {
     #[command(
         about = "Run multiple tests towards peer nodes",
-        long_about = "Run multiple tests towards peer nodes. Verify that Charon can efficiently interact with Validator Client."
+        long_about = "Run multiple tests towards peer nodes. Verify that Pluto can efficiently interact with Validator Client."
     )]
     Peers(TestPeersArgs),
 
     #[command(
         about = "Run multiple tests towards beacon nodes",
-        long_about = "Run multiple tests towards beacon nodes. Verify that Charon can efficiently interact with Beacon Node(s)."
+        long_about = "Run multiple tests towards beacon nodes. Verify that Pluto can efficiently interact with Beacon Node(s)."
     )]
     Beacon(TestBeaconArgs),
 
     #[command(
         about = "Run multiple tests towards validator client",
-        long_about = "Run multiple tests towards validator client. Verify that Charon can efficiently interact with its validator client."
+        long_about = "Run multiple tests towards validator client. Verify that Pluto can efficiently interact with its validator client."
     )]
     Validator(TestValidatorArgs),
 
     #[command(
         about = "Run multiple tests towards MEV relays",
-        long_about = "Run multiple tests towards MEV relays. Verify that Charon can efficiently interact with MEV relay(s)."
+        long_about = "Run multiple tests towards MEV relays. Verify that Pluto can efficiently interact with MEV relay(s)."
     )]
     Mev(TestMevArgs),
 
     #[command(
         about = "Run multiple hardware and internet connectivity tests",
-        long_about = "Run multiple hardware and internet connectivity tests. Verify that Charon is running on host with sufficient capabilities."
+        long_about = "Run multiple hardware and internet connectivity tests. Verify that Pluto is running on host with sufficient capabilities."
     )]
     Infra(TestInfraArgs),
 
@@ -182,7 +182,7 @@ pub enum CreateCommands {
 
     #[command(
         about = "Create private keys and configuration files needed to run a distributed validator cluster locally",
-        long_about = "Creates a local charon cluster configuration including validator keys, charon p2p keys, cluster-lock.json and deposit-data.json file(s). See flags for supported features."
+        long_about = "Creates a local cluster configuration including validator keys, Pluto p2p keys, cluster-lock.json and deposit-data.json file(s). See flags for supported features."
     )]
     Cluster(Box<CreateClusterArgs>),
 }

crates/cli/src/commands/run.rs

@@ -117,7 +117,7 @@ pub struct RunPrivKeyArgs {
         long = "private-key-file",
         env = "CHARON_PRIVATE_KEY_FILE",
         default_value = ".charon/charon-enr-private-key",
-        help = "The path to the pluto enr private key file."
+        help = "The path to the charon-enr-private-key file (Charon-compatible filename preserved for interoperability)."
     )]
     pub private_key_file: String,
 

crates/cluster/src/lib.rs

@@ -1,8 +1,8 @@
-//! # Charon Cluster
+//! # Pluto Cluster
 //!
-//! Cluster management and coordination for Charon distributed validator nodes.
+//! Cluster management and coordination for Pluto distributed validator nodes.
 //! This crate handles the formation, management, and coordination of validator
-//! clusters in the Charon network.
+//! clusters in the Pluto network.
 
 /// `Definition` type representing the intended cluster configuration
 /// (operators, validators, fork version) with EIP-712 hashing and verification.

crates/tracing/src/lib.rs

@@ -1,6 +1,6 @@
-//! # Charon Observability
+//! # Pluto Observability
 //!
-//! Observability and monitoring utilities for the Charon distributed validator
+//! Observability and monitoring utilities for the Pluto distributed validator
 //! node. This crate provides logging, metrics, tracing, and monitoring
 //! capabilities for tracking and debugging validator operations.