diff --git a/CLAUDE.md b/CLAUDE.md
index a114dc02106..4aa4bdc5802 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -9,7 +9,7 @@ All paths below are relative to the git root. When working inside a component, a
 
 `avm-transpiler/` transpiles Noir bytecode to AVM bytecode (Rust). `noir/` is the Noir compiler, a git submodule pointing to noir-lang/noir. `noir-projects/fnd/` holds the protocol circuits and protocol contracts written in Noir.
 
-`l1-contracts/` holds the Solidity L1 rollup contracts (a Foundry project). `bb-pilcom/` is the PIL compiler for AVM relation codegen. `ci3/` contains CI infrastructure scripts.
+`l1-contracts/` holds the Solidity L1 rollup contracts (a Foundry project). `l1-contracts/script/deploy/` is the env-driven deployer for tests, spartan/CLI and testnets; mainnet rollup upgrades use bespoke pinned scripts (`DeployRollupForUpgradeV<N>.s.sol`, for example `DeployRollupForUpgradeV5.s.sol` on the `v5-next` branch and `DeployRollupForUpgradeV6.s.sol`), so its defaults are not mainnet configuration and findings against them are not mainnet findings. `bb-pilcom/` is the PIL compiler for AVM relation codegen. `ci3/` contains CI infrastructure scripts.
 </components>
 
 <build_system>
diff --git a/l1-contracts/script/deploy/DeployAztecL1Contracts.s.sol b/l1-contracts/script/deploy/DeployAztecL1Contracts.s.sol
index 97383d84f0d..a04069f3376 100644
--- a/l1-contracts/script/deploy/DeployAztecL1Contracts.s.sol
+++ b/l1-contracts/script/deploy/DeployAztecL1Contracts.s.sol
@@ -64,6 +64,15 @@ struct DeployAztecL1ContractsOutput {
  * @author Aztec Labs
  * @notice Deploy Aztec L1 contracts. Configuration is read from environment variables.
  * See DeploymentConfiguration and RollupConfiguration for environment variables supported.
+ *
+ * This is the env-driven deployer for tests, the spartan/CLI tooling and testnets: it deploys a
+ * complete L1 set from scratch, including test-only assets and handlers. It is not how mainnet was
+ * deployed: mainnet's one-off contracts (token, GSE, Registry, Governance, GovernanceProposer,
+ * ProtocolTreasury, CoinIssuer) came from the `AztecProtocol/ignition-contracts` deployment, and each
+ * mainnet rollup version is deployed by a bespoke pinned `DeployRollupForUpgradeV<N>.s.sol`. Examples:
+ *   - v5: `DeployRollupForUpgradeV5.s.sol` on the `v5-next` branch
+ *   - v6: `DeployRollupForUpgradeV6.s.sol`
+ * This script's defaults are test-network conveniences, not mainnet configuration.
  */
 contract DeployAztecL1Contracts is Script, Test {
   /// @notice All deployed contract addresses
diff --git a/l1-contracts/script/deploy/DeployRollupForUpgrade.s.sol b/l1-contracts/script/deploy/DeployRollupForUpgrade.s.sol
index 97f1ea3ac2c..963a8256d14 100644
--- a/l1-contracts/script/deploy/DeployRollupForUpgrade.s.sol
+++ b/l1-contracts/script/deploy/DeployRollupForUpgrade.s.sol
@@ -34,6 +34,15 @@ import {IRollupConfiguration, RollupConfiguration} from "./RollupConfiguration.s
 /// GenesisState supplied via environment variables; no archive, checkpoint, message or fee-juice state is
 /// carried over from the canonical rollup, which stays registered under its own version.
 ///
+/// This is the env-driven deployer for tests, the spartan/CLI tooling and testnets. Mainnet upgrades
+/// do not run it: each mainnet rollup version is deployed by a bespoke pinned script,
+/// `DeployRollupForUpgradeV<N>.s.sol`, that hard-codes and re-verifies the configuration of that one
+/// deployment. Examples:
+///   - v5: `DeployRollupForUpgradeV5.s.sol` on the `v5-next` branch
+///   - v6: `DeployRollupForUpgradeV6.s.sol`
+/// The environment-driven inputs consumed here and in `RollupConfiguration` describe a test network,
+/// not mainnet.
+///
 /// For initial L1 deployment, use DeployAztecL1Contracts.s.sol instead.
 ///
 /// See RollupConfiguration.sol for relevant environment variables.
diff --git a/l1-contracts/script/deploy/DeployRollupLib.sol b/l1-contracts/script/deploy/DeployRollupLib.sol
index d6347408a21..bc1ad476810 100644
--- a/l1-contracts/script/deploy/DeployRollupLib.sol
+++ b/l1-contracts/script/deploy/DeployRollupLib.sol
@@ -45,6 +45,12 @@ struct RollupAddressOutput {
 /// @title DeployRollupLib
 /// @author Aztec Labs
 /// @notice Library for deploying rollup contracts. Used by DeployAztecL1Contracts and DeployRollupForUpgrade.
+/// @dev Serves the env-driven deployer for tests, the spartan/CLI tooling and testnets. Mainnet rollup
+/// versions are deployed by bespoke pinned `DeployRollupForUpgradeV<N>.s.sol` scripts that construct the
+/// rollup directly with hard-coded configuration. Examples:
+///   - v5: `DeployRollupForUpgradeV5.s.sol` on the `v5-next` branch
+///   - v6: `DeployRollupForUpgradeV6.s.sol`
+/// The `IRollupConfiguration` values honoured here describe a test network, not mainnet.
 library DeployRollupLib {
   function deployRollup(RollupAddressInput memory input, IRollupConfiguration config)
     internal
diff --git a/l1-contracts/script/deploy/RollupConfiguration.sol b/l1-contracts/script/deploy/RollupConfiguration.sol
index f6730887098..bd167c8f3cf 100644
--- a/l1-contracts/script/deploy/RollupConfiguration.sol
+++ b/l1-contracts/script/deploy/RollupConfiguration.sol
@@ -27,6 +27,15 @@ interface IRollupConfiguration {
   function parseValidators() external view returns (CheatDepositArgs[] memory);
 }
 
+/// @title RollupConfiguration
+/// @author Aztec Labs
+/// @notice Reads rollup deployment configuration from environment variables for the env-driven deployer
+/// used by tests, the spartan/CLI tooling and testnets (`DeployAztecL1Contracts`, `DeployRollupForUpgrade`).
+/// @dev Mainnet rollup versions are deployed by bespoke pinned `DeployRollupForUpgradeV<N>.s.sol` scripts
+/// that hard-code their configuration instead of reading it here. Examples:
+///   - v5: `DeployRollupForUpgradeV5.s.sol` on the `v5-next` branch
+///   - v6: `DeployRollupForUpgradeV6.s.sol`
+/// The environment variables read below describe a test network, not mainnet.
 contract RollupConfiguration is IRollupConfiguration, Test {
   using stdJson for string;
   using SafeCast for uint256;