diff --git a/hive-c0re/src/bin/hivectl.rs b/hive-c0re/src/bin/hivectl.rs
index 40a9c81e..1fe74ed1 100644
--- a/hive-c0re/src/bin/hivectl.rs
+++ b/hive-c0re/src/bin/hivectl.rs
@@ -113,6 +113,11 @@ enum Cmd {
         scope: ScopeArgs,
         /// Gracefully quiesce each agent (finish the current turn, drain
         /// the inbox) before stopping, instead of a hard stop.
+        ///
+        /// NOTE: not yet effective — the per-agent quiesce is still being
+        /// implemented (see the graceful-agent-stop tracker), so today
+        /// this falls through to a hard stop. The flag is accepted now so
+        /// the wire/CLI shape is stable when the quiesce lands.
         #[arg(long)]
         graceful: bool,
         /// Path to the hive-c0re host admin socket.