remove internal API

Author: neos-builder

content/docs/advanced-examples.mdx

@@ -52,8 +52,8 @@ impl StateMachineNode {
 impl Node for StateMachineNode {
     fn name(&self) -> &'static str { "StateMachineNode" }
 
-    fn init(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info("State machine initialized - starting in IDLE state");
+    fn init(&mut self) -> Result<()> {
+        hlog!(info, "State machine initialized - starting in IDLE state");
         Ok(())
     }
 
@@ -107,26 +107,22 @@ impl Node for StateMachineNode {
 
         // Log state transitions
         if self.state != prev_state {
-            if let Some(ref mut c) = ctx {
-                c.log_info(&format!(
-                    "State transition: {:?} -> {:?}",
-                    prev_state, self.state
-                ));
-            }
+            hlog!(info, "State transition: {:?} -> {:?}",
+                prev_state, self.state);
         }
     }
 
-    fn shutdown(&mut self, ctx: &mut NodeInfo) -> Result<()> {
+    fn shutdown(&mut self) -> Result<()> {
         // Ensure robot is stopped
-        self.cmd_pub.send(CmdVel::zero(), &mut None).ok();
-        ctx.log_info("State machine shutdown");
+        self.cmd_pub.send(CmdVel::zero()).ok();
+        hlog!(info, "State machine shutdown");
         Ok(())
     }
 }
 
 fn main() -> Result<()> {
     let mut scheduler = Scheduler::new();
-    scheduler.add(Box::new(StateMachineNode::new()?), 0, Some(true));
+    scheduler.add(StateMachineNode::new()?).order(0).done();
     scheduler.run()?;
     Ok(())
 }
@@ -177,8 +173,8 @@ impl EmergencyStopNode {
 impl Node for EmergencyStopNode {
     fn name(&self) -> &'static str { "EmergencyStop" }
 
-    fn init(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info(" Emergency stop system online - CRITICAL priority");
+    fn init(&mut self) -> Result<()> {
+        hlog!(info, " Emergency stop system online - CRITICAL priority");
         Ok(())
     }
 
@@ -189,25 +185,17 @@ impl Node for EmergencyStopNode {
         if let Some(battery) = self.battery_sub.recv() {
             if battery.is_critical() {  // Below 10%
                 should_stop = true;
-                if let Some(ref mut c) = ctx {
-                    c.log_error(&format!(
-                        " CRITICAL: Battery at {:.0}% - EMERGENCY STOP!",
-                        battery.percentage
-                    ));
-                }
+                hlog!(error, " CRITICAL: Battery at {:.0}% - EMERGENCY STOP!",
+                    battery.percentage);
             }
         }
 
         // Check obstacle distance
         if let Some(min_dist) = self.lidar_sub.recv() {
             if min_dist < 0.2 {  // 20cm
                 should_stop = true;
-                if let Some(ref mut c) = ctx {
-                    c.log_error(&format!(
-                        " CRITICAL: Obstacle at {:.2}m - EMERGENCY STOP!",
-                        min_dist
-                    ));
-                }
+                hlog!(error, " CRITICAL: Obstacle at {:.2}m - EMERGENCY STOP!",
+                    min_dist);
             }
         }
 
@@ -218,10 +206,10 @@ impl Node for EmergencyStopNode {
         }
     }
 
-    fn shutdown(&mut self, ctx: &mut NodeInfo) -> Result<()> {
+    fn shutdown(&mut self) -> Result<()> {
         // Always activate estop on shutdown
-        self.estop_pub.send(true, &mut None).ok();
-        ctx.log_warning("Emergency stop system offline");
+        self.estop_pub.send(true).ok();
+        hlog!(warn, "Emergency stop system offline");
         Ok(())
     }
 }
@@ -248,8 +236,8 @@ impl MotorController {
 impl Node for MotorController {
     fn name(&self) -> &'static str { "MotorController" }
 
-    fn init(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info("Motor controller online - HIGH priority");
+    fn init(&mut self) -> Result<()> {
+        hlog!(info, "Motor controller online - HIGH priority");
         Ok(())
     }
 
@@ -258,12 +246,10 @@ impl Node for MotorController {
         if let Some(estop) = self.estop_sub.recv() {
             if estop != self.estop_active {
                 self.estop_active = estop;
-                if let Some(ctx) = ctx {
-                    if estop {
-                        ctx.log_warning("Motors DISABLED - emergency stop active");
-                    } else {
-                        ctx.log_info("Motors ENABLED - emergency stop cleared");
-                    }
+                if estop {
+                    hlog!(warn, "Motors DISABLED - emergency stop active");
+                } else {
+                    hlog!(info, "Motors ENABLED - emergency stop cleared");
                 }
             }
         }
@@ -277,20 +263,15 @@ impl Node for MotorController {
         // Process normal commands
         if let Some(cmd) = self.cmd_sub.recv() {
             self.motor_pub.send(cmd).ok();
-
-            if let Some(ref mut c) = ctx {
-                c.log_debug(&format!(
-                    "Motors: linear={:.2}, angular={:.2}",
-                    cmd.linear, cmd.angular
-                ));
-            }
+            hlog!(debug, "Motors: linear={:.2}, angular={:.2}",
+                cmd.linear, cmd.angular);
         }
     }
 
-    fn shutdown(&mut self, ctx: &mut NodeInfo) -> Result<()> {
+    fn shutdown(&mut self) -> Result<()> {
         // Stop motors
-        self.motor_pub.send(CmdVel::zero(), &mut None).ok();
-        ctx.log_info("Motor controller stopped");
+        self.motor_pub.send(CmdVel::zero()).ok();
+        hlog!(info, "Motor controller stopped");
         Ok(())
     }
 }
@@ -313,52 +294,44 @@ impl LoggerNode {
 impl Node for LoggerNode {
     fn name(&self) -> &'static str { "Logger" }
 
-    fn init(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info(" Logger online - BACKGROUND priority");
+    fn init(&mut self) -> Result<()> {
+        hlog!(info, " Logger online - BACKGROUND priority");
         Ok(())
     }
 
     fn tick(&mut self) {
         // Log velocity commands
         if let Some(cmd) = self.cmd_sub.recv() {
-            if let Some(ref mut c) = ctx {
-                c.log_debug(&format!(
-                    "LOG: cmd_vel({:.2}, {:.2})",
-                    cmd.linear, cmd.angular
-                ));
-            }
+            hlog!(debug, "LOG: cmd_vel({:.2}, {:.2})",
+                cmd.linear, cmd.angular);
         }
 
         // Log battery state
         if let Some(battery) = self.battery_sub.recv() {
-            if let Some(ref mut c) = ctx {
-                c.log_debug(&format!(
-                    "LOG: battery({:.1}V, {:.0}%)",
-                    battery.voltage, battery.percentage
-                ));
-            }
+            hlog!(debug, "LOG: battery({:.1}V, {:.0}%)",
+                battery.voltage, battery.percentage);
         }
 
         // In production: write to file, database, etc.
     }
 
-    fn shutdown(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info("Logger stopped");
+    fn shutdown(&mut self) -> Result<()> {
+        hlog!(info, "Logger stopped");
         Ok(())
     }
 }
 
 fn main() -> Result<()> {
     let mut scheduler = Scheduler::new();
 
-    // PRIORITY 0 (Critical): Safety runs FIRST
-    scheduler.add(Box::new(EmergencyStopNode::new()?), 0, Some(true));
+    // Order 0 (Critical): Safety runs FIRST
+    scheduler.add(EmergencyStopNode::new()?).order(0).done();
 
-    // PRIORITY 1 (High): Control runs SECOND
-    scheduler.add(Box::new(MotorController::new()?), 1, Some(true));
+    // Order 1 (High): Control runs SECOND
+    scheduler.add(MotorController::new()?).order(1).done();
 
-    // PRIORITY 4 (Background): Logging runs LAST
-    scheduler.add(Box::new(LoggerNode::new()?), 4, Some(true));
+    // Order 4 (Background): Logging runs LAST
+    scheduler.add(LoggerNode::new()?).order(4).done();
 
     scheduler.run()?;
     Ok(())
@@ -552,8 +525,8 @@ impl TempSensor {
 impl Node for TempSensor {
     fn name(&self) -> &'static str { "RustTempSensor" }
 
-    fn init(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info("Rust sensor online - high performance mode");
+    fn init(&mut self) -> Result<()> {
+        hlog!(info, "Rust sensor online - high performance mode");
         Ok(())
     }
 
@@ -562,22 +535,20 @@ impl Node for TempSensor {
         let temp = 20.0 + (self.counter.sin() * 5.0);
         self.temp_pub.send(temp).ok();
 
-        if let Some(ref mut c) = ctx {
-            c.log_debug(&format!("Rust: {:.2}°C", temp));
-        }
+        hlog!(debug, "Rust: {:.2}°C", temp);
 
         self.counter += 0.1;
     }
 
-    fn shutdown(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info("Rust sensor offline");
+    fn shutdown(&mut self) -> Result<()> {
+        hlog!(info, "Rust sensor offline");
         Ok(())
     }
 }
 
 fn main() -> Result<()> {
     let mut scheduler = Scheduler::new();
-    scheduler.add(Box::new(TempSensor::new()?), 0, Some(true));
+    scheduler.add(TempSensor::new()?).order(0).done();
     scheduler.run()
 }
 ```
@@ -628,24 +599,22 @@ impl Node for Actuator {
 
     fn tick(&mut self) {
         if let Some(cmd) = self.cmd_sub.recv() {
-            if let Some(ctx) = ctx {
-                let action = if cmd > 0.5 { "COOLING" } else { "IDLE" };
-                ctx.log_info(&format!("Actuator: {}", action));
-            }
+            let action = if cmd > 0.5 { "COOLING" } else { "IDLE" };
+            hlog!(info, "Actuator: {}", action);
         }
     }
 
-    fn shutdown(&mut self, ctx: &mut NodeInfo) -> Result<()> {
-        ctx.log_info("Actuator stopped");
+    fn shutdown(&mut self) -> Result<()> {
+        hlog!(info, "Actuator stopped");
         Ok(())
     }
 }
 
 fn main() -> Result<()> {
     let mut scheduler = Scheduler::new();
-    scheduler.add(Box::new(Actuator {
+    scheduler.add(Actuator {
         cmd_sub: Topic::new("actuator_cmd")?,
-    }), 0, Some(true));
+    }).order(0).done();
     scheduler.run()
 }
 ```

content/docs/advanced/blackbox.mdx

@@ -6,6 +6,20 @@ weight: 30
 
 # BlackBox Flight Recorder
 
+<Callout type="info" title="Do I Need This?">
+
+**For most users: Not initially.** BlackBox is for when you need to understand crashes and failures.
+
+**When this page IS useful:**
+- Robot crashes and you need to know what led up to it
+- Running long-term deployments and need audit logs
+- Investigating intermittent failures
+- Compliance requirements for event logging
+
+**Quick answer:** Add BlackBox once your robot runs well. It's like dashcam footage: unnecessary until something goes wrong.
+
+</Callout>
+
 The BlackBox flight recorder provides continuous event logging in a circular buffer for post-mortem analysis. Like an aircraft flight recorder, it captures all significant events leading up to failures for debugging and incident investigation.
 
 ## Overview

content/docs/advanced/checkpoint.mdx

@@ -6,6 +6,19 @@ weight: 46
 
 # Checkpoint System
 
+<Callout type="info" title="Do I Need This?">
+
+**For most users: Not initially.** Checkpointing is for long-running systems that need recovery.
+
+**When this page IS useful:**
+- Robot runs for hours/days and must recover from crashes
+- Training ML models and need to save progress
+- Complex state that's expensive to rebuild from scratch
+
+**Quick answer:** If restarting your robot is quick and easy, skip this. Add checkpointing when downtime matters.
+
+</Callout>
+
 The Checkpoint System provides periodic state snapshots that can be used to recover from crashes or rollback to known-good states. This is essential for long-running robotics applications that need fault tolerance.
 
 ## Overview

content/docs/advanced/circuit-breaker.mdx

@@ -6,6 +6,19 @@ weight: 32
 
 # Circuit Breaker
 
+<Callout type="info" title="Do I Need This?">
+
+**For most users: Not initially.** Circuit breakers add resilience but also complexity.
+
+**When this page IS useful:**
+- A sensor or node occasionally fails/hangs
+- You need graceful degradation when hardware is unreliable
+- Building long-running systems that must stay up
+
+**Quick answer:** Start without it. Add circuit breakers when you have specific reliability problems to solve.
+
+</Callout>
+
 The circuit breaker pattern prevents cascading failures by temporarily disabling failing nodes. When a node fails repeatedly, the circuit "opens" to stop calling it, giving it time to recover.
 
 ## Overview