diff --git a/crates/stellar-scaffold-cli/src/commands/build/mod.rs b/crates/stellar-scaffold-cli/src/commands/build/mod.rs
index 0e7e849f..919d2fd5 100644
--- a/crates/stellar-scaffold-cli/src/commands/build/mod.rs
+++ b/crates/stellar-scaffold-cli/src/commands/build/mod.rs
@@ -33,20 +33,17 @@ pub struct Command {
     /// List package names in order of build
     #[arg(long, visible_alias = "ls")]
     pub list: bool,
-    #[command(flatten)]
-    pub build: build::Cmd,
-    /// Also deploy contracts and generate their clients. Only needed for
-    /// projects on environments.toml; with a version 2 scaffold.yml this
-    /// always happens, as configured there.
+    /// Only compile Wasm binaries; skip client generation even for a version 2 project
+    #[arg(long)]
+    pub compile_only: bool,
+    /// Deprecated for version 2 projects with scaffold.yml: clients are generated by default.
+    /// Use --compile-only to skip deployment and client generation.
     #[arg(long)]
     pub build_clients: bool,
     #[command(flatten)]
     pub build_clients_args: clients::ClientsArgs,
-    /// Only compile, skipping deploys and client generation even for a
-    /// version 2 project. Set by commands that build as one step of their own
-    /// work; users get compile-only from `stellar contract build`.
-    #[arg(skip)]
-    pub compile_only: bool,
+    #[command(flatten)]
+    pub build: build::Cmd,
 }
 
 #[derive(thiserror::Error, Debug)]
@@ -244,7 +241,7 @@ impl Command {
         let is_v2 = v2::is_v2(workspace_root);
         if self.build_clients && is_v2 {
             printer.infoln(
-                "--build-clients is no longer needed: with a version 2 scaffold.yml, build always deploys and generates clients as configured there",
+                "--build-clients is no longer needed: with a version 2 scaffold.yml, build generates clients by default. Skip with --compile-only",
             );
         }
         builds_clients(self.compile_only, self.build_clients, is_v2)
@@ -524,6 +521,31 @@ fn builds_clients(compile_only: bool, flag: bool, is_v2: bool) -> bool {
 #[cfg(test)]
 mod tests {
     use super::builds_clients;
+    use crate::commands::{Cmd, Root};
+    use clap::Parser;
+
+    #[test]
+    fn compile_only_is_a_public_build_flag() {
+        for (args, expected) in [
+            (vec!["stellar-scaffold", "build"], false),
+            (vec!["stellar-scaffold", "build", "--compile-only"], true),
+            (
+                vec![
+                    "stellar-scaffold",
+                    "build",
+                    "--compile-only",
+                    "--build-clients",
+                ],
+                true,
+            ),
+        ] {
+            let root = Root::try_parse_from(args).unwrap();
+            let Cmd::Build(command) = root.cmd else {
+                panic!("expected build command");
+            };
+            assert_eq!(command.compile_only, expected);
+        }
+    }
 
     #[test]
     fn v2_builds_clients_without_the_flag() {
diff --git a/crates/stellar-scaffold-cli/src/commands/mod.rs b/crates/stellar-scaffold-cli/src/commands/mod.rs
index 671973cd..e1dbe7b0 100644
--- a/crates/stellar-scaffold-cli/src/commands/mod.rs
+++ b/crates/stellar-scaffold-cli/src/commands/mod.rs
@@ -93,7 +93,7 @@ pub enum Cmd {
     /// Version of the scaffold-stellar-cli
     Version(version::Cmd),
 
-    /// Build contracts, resolving dependencies in the correct order. If you have an `environments.toml` file, it will also follow its instructions to configure the environment set by the `STELLAR_SCAFFOLD_ENV` environment variable, turning your contracts into frontend packages (JS dependencies).
+    /// Build contracts, resolving dependencies in the correct order; build clients (JS packages) as specified in `scaffold.yml`
     Build(build::Command),
 
     /// generate contracts