diff --git a/hive-c0re/src/auto_update.rs b/hive-c0re/src/auto_update.rs
index fe0f60ab..9e13990a 100644
--- a/hive-c0re/src/auto_update.rs
+++ b/hive-c0re/src/auto_update.rs
@@ -72,6 +72,10 @@ pub fn agent_config_pending(name: &str, deployed_sha: Option<&str>) -> bool {
 /// the container rebuild. Pass `false` only for meta-update cascade
 /// rebuilds, where re-locking would revert the bump the cascade just
 /// committed (see `lifecycle::rebuild`).
+///
+/// # Errors
+///
+/// Propagates errors from `coord.ensure_runtime` and `lifecycle::rebuild`.
 pub async fn rebuild_agent(
     coord: &Arc<Coordinator>,
     name: &str,
diff --git a/hive-c0re/src/lifecycle.rs b/hive-c0re/src/lifecycle.rs
index 077c0879..12d614b0 100644
--- a/hive-c0re/src/lifecycle.rs
+++ b/hive-c0re/src/lifecycle.rs
@@ -409,6 +409,18 @@ pub async fn destroy(name: &str) -> Result<()> {
     Ok(())
 }
 
+/// Rebuild `name`'s container: sync the meta flake, optionally re-lock
+/// the agent's input, then re-apply + restart via `nixos-container`.
+///
+/// When `relock` is `true` the agent's meta input is bumped to whatever
+/// `applied/<n>/main` points at before the build. Pass `false` for
+/// meta-update cascade rebuilds, where re-locking would revert the bump
+/// the cascade just committed (see the inline note below).
+///
+/// # Errors
+///
+/// Propagates errors from meta-flake sync / lock-update and the
+/// `nixos-container` apply + restart shellouts.
 pub async fn rebuild(
     name: &str,
     hive: &HiveEnv,