Address all PR review comments

- Remove v2 comparisons from what-is-commands-v3.rst
- Update learning curve section to focus on imperative on-ramp
- Remove Java Continuation API implementation detail
- Remove 'Key Improvements Over v2' and 'Comparison' sections
- Update structuring to not recommend RobotContainer pattern
- Add Scheduler parameter note for testing
- Update telemetry to focus on protobuf serialization and AdvantageScope
- Remove CPU usage tracking (not implemented)
- Clarify breakpoint debugging only in sim/unit tests
- Remove incremental migration recommendation from migration guide
- Note vendor library compatibility is up to vendors
- Remove v2 comparisons from mechanisms.rst
- Note automatic mechanism registration
- Document periodic function patterns
- Reorder async-await sections (awaitAll before await)
- Clarify awaitAny cancels other commands

Author: jasondaming

source/docs/software/commandbased/commands-v3/async-await-patterns.rst

@@ -14,18 +14,6 @@
    - High-level mental model for how it works with the scheduler
    - Relationship to coroutines and yield()
 
-## await()
-
-.. todo::
-   Explain the await() function in detail. Cover:
-   - What await(command) does: schedule a command and wait for it to complete
-   - How await() blocks the calling command until the child completes
-   - Requirements and priority handling with awaited commands
-   - What happens if the awaited command is interrupted
-   - What happens if the parent command is interrupted
-   - Return values and status from awaited commands
-   - Examples of await() patterns (describe what examples should show)
-
 ## awaitAll()
 
 .. todo::
@@ -36,15 +24,29 @@
    - Requirements management across multiple parallel commands
    - Error and interruption handling
    - Performance implications of parallel execution
+   - Easier to explain as a blocking version of fork()
    - Examples of awaitAll() patterns (describe what examples should show)
 
+## await()
+
+.. todo::
+   Explain the await() function in detail. Cover:
+   - What await(command) does: schedule a command and wait for it to complete
+   - How await() blocks the calling command until the child completes
+   - Requirements and priority handling with awaited commands
+   - What happens if the awaited command is interrupted
+   - What happens if the parent command is interrupted
+   - Return values and status from awaited commands
+   - Examples of await() patterns (describe what examples should show)
+
 ## awaitAny()
 
 .. todo::
    Explain the awaitAny() function in detail. Cover:
    - What awaitAny(commands) does: wait until any command completes
    - Race condition semantics: which command "wins"
-   - What happens to other commands when one completes
+   - **Important**: awaitAny() cancels all other still-running commands when one completes
+   - Both await functions are blocking
    - Use cases for awaitAny() (timeouts, alternative paths, etc.)
    - How interruption is handled
    - Differences from race groups in composition

source/docs/software/commandbased/commands-v3/mechanisms.rst

@@ -8,11 +8,10 @@
 .. todo::
    Describe how to create a Mechanism class. Cover:
    - Basic Mechanism class structure and constructor
-   - How Mechanisms differ philosophically from v2 Subsystems
    - When to create a Mechanism vs. other organizational patterns
    - Naming conventions for Mechanism classes
    - Where Mechanism classes should live in the project structure
-   - How to register Mechanisms with the command scheduler (if needed)
+   - Note: Mechanisms are automatically registered with the scheduler in the base class constructor
 
 ## Encapsulation Best Practices
 
@@ -40,8 +39,10 @@
 
 .. todo::
    Describe periodic update patterns in Mechanisms. Cover:
-   - Whether Mechanisms have a periodic() method like v2 Subsystems
-   - If not, how to handle periodic updates in v3
+   - Mechanisms don't have a built-in periodic() method
+   - Manual periodic functions can be plumbed if needed using `Scheduler.addPeriodic()`
+   - Alternatively, call periodic functions manually in `robotPeriodic()`
+   - Example patterns for sensor refresh methods
    - When to use periodic updates vs. command-based updates
    - Performance considerations for periodic operations
    - Common patterns like updating telemetry, processing sensor data, safety checks

source/docs/software/commandbased/commands-v3/migration-from-v2.rst

@@ -1,15 +1,14 @@
 # Migrating from Commands v2 to v3
 
 .. todo::
-   This article guides teams through migrating an existing Commands v2 codebase to v3. Migration can be done incrementally, and this article should help teams plan their migration strategy, understand the key differences, and avoid common pitfalls. This is a critical resource for established teams.
+   This article guides teams through migrating an existing Commands v2 codebase to v3. This article should help teams plan their migration strategy, understand the key differences, and avoid common pitfalls. This is a critical resource for established teams.
 
 ## Migration Strategy
 
 .. todo::
    Provide high-level guidance on planning a v2-to-v3 migration. Cover:
    - Should teams migrate? (pros/cons, when to migrate vs. stay on v2)
-   - Migration approaches: full rewrite vs. incremental migration
-   - Incremental migration: v2 and v3 can coexist in the same project
+   - Migration approach: full rewrite recommended
    - What to migrate first (start with simple mechanisms/commands)
    - Testing strategy during migration
    - Timeline considerations (offseason vs. competition season)
@@ -25,7 +24,7 @@
    - Deprecated v2 APIs and their v3 equivalents
    - How to add v3 dependencies to build.gradle/pom.xml
    - Version compatibility and requirements
-   - Vendor library compatibility with v3
+   - Note: Vendor library compatibility with v3 is up to individual vendors
 
 ## Concept Mapping
 

source/docs/software/commandbased/commands-v3/structuring-v3-project.rst

@@ -8,25 +8,33 @@
 .. todo::
    Describe the recommended file and package organization for v3 projects. Cover:
    - Top-level package structure
-   - Where Mechanisms should live
+   - Where Mechanisms should live (mechanisms/ directory with subdirectories per mechanism)
    - Where command functions/classes should be organized
    - Organization of constants and configuration
    - Separation of concerns between different code areas
-   - How v3 structure differs from v2 structure
-   - Example directory tree showing recommended organization
+   - Example directory tree:
+     - Autos.java
+     - ControllerBindings.java
+     - Main.java
+     - Robot.java
+     - mechanisms/
+       - drive/
+         - DriveConstants.java
+         - Drive.java
+       - elevator/
+         - ElevatorConstants.java
+         - Elevator.java
 
-## RobotContainer Design
+## Robot.java and Controller Bindings
 
 .. todo::
-   Explain the role and design of the RobotContainer class. Cover:
-   - What RobotContainer is responsible for in v3
-   - How to structure RobotContainer for maintainability
-   - Mechanism instantiation and initialization
+   Explain the organization of Robot.java and controller bindings. Cover:
+   - Robot.java is the main organization point (not using RobotContainer pattern)
+   - Mechanism instantiation and initialization in Robot.java
+   - ControllerBindings.java for organizing button bindings
+   - Autos.java for autonomous routine organization
    - Controller/joystick setup
-   - Button binding organization
-   - Autonomous routine selection
-   - Patterns for large RobotContainer classes (splitting into methods or subclasses)
-   - Example RobotContainer structure (describe sections, not full implementation)
+   - Patterns for clean organization without RobotContainer
 
 ## Robot.java Setup
 
@@ -37,7 +45,6 @@
    - How v3 uses the scheduler in periodic loops
    - Autonomous vs. teleop initialization
    - Test mode setup for v3
-   - Simulation support hooks
    - What should NOT go in Robot.java (antipatterns)
    - Example Robot.java structure for v3
 
@@ -76,6 +83,7 @@
    - Integration test organization
    - Test utilities and fixtures
    - Mocking Mechanisms and hardware for command tests
+   - **Mechanism testing**: Mechanisms can accept a `Scheduler` parameter in their constructor to avoid shared state in tests
    - Simulation test setup
    - CI/CD integration considerations
    - Example test directory structure

source/docs/software/commandbased/commands-v3/telemetry-and-debugging.rst

@@ -1,46 +1,45 @@
 # Telemetry and Debugging
 
 .. todo::
-   This article covers using v3's enhanced telemetry features and debugging tools to understand and troubleshoot robot behavior. Good telemetry is essential for rapid iteration during competition, and v3 provides improved tools compared to v2.
+   This article covers using v3's telemetry features and debugging tools to understand and troubleshoot robot behavior. Good telemetry is essential for rapid iteration during competition.
 
-## v3 Telemetry Improvements
+## Telemetry Features
 
 .. todo::
-   Overview of telemetry enhancements in v3. Cover:
-   - What telemetry improvements v3 provides over v2
-   - Built-in command scheduler telemetry
+   Overview of telemetry features in v3. Cover:
+   - Telemetry API and Epilogue compatibility (protobuf serialization)
    - Mechanism state visibility
+   - Scheduler events
+     - Detail the subtypes of `SchedulerEvent` and when they are emitted
+     - Add event listeners to listen for them
    - Command lifecycle events
    - Priority and interruption logging
-   - Performance metrics (cycle time, CPU usage)
    - How telemetry integrates with the scheduler
 
-## Dashboard Integration
+## Data Logging and Analysis
 
 .. todo::
-   Explain how to integrate v3 telemetry with dashboards. Cover:
-   - Supported dashboard tools (Shuffleboard, Glass, etc.)
-   - Automatic command scheduler widget/visualization
+   Explain how v3 telemetry works with data logging and analysis tools. Cover:
+   - Protobuf serialization for telemetry data
+   - Integration with AdvantageScope for post-match analysis
+   - Tracking command lifetimes and triggering events
+   - Live or post-match analysis workflows
    - Publishing Mechanism state to Network Tables
-   - Publishing command properties and status
-   - Creating custom dashboard layouts for v3 projects
-   - Live tuning parameters through the dashboard
-   - Remote command triggering from dashboard
-   - Best practices for dashboard organization
+   - Best practices for data logging
 
 ## Debugging Techniques
 
 .. todo::
    Provide techniques for debugging v3 command-based code. Cover:
-   - Using dashboard telemetry to diagnose issues
+   - Using telemetry data to diagnose issues
    - Logging command lifecycle events
    - Tracing command execution flow
    - Debugging priority conflicts
    - Debugging requirement conflicts
    - Debugging trigger bindings that don't fire
    - Debugging commands that don't end/interrupt properly
    - Using simulation for debugging
-   - Breakpoint debugging in IDEs with v3
+   - Breakpoint debugging in IDEs (only in simulation or unit tests, not on running robots)
    - Common debugging patterns and workflows
 
 ## Logging Best Practices

source/docs/software/commandbased/commands-v3/testing-and-simulation.rst

@@ -1,14 +1,13 @@
 # Testing and Simulation
 
 .. todo::
-   This article covers testing commands and mechanisms using both unit tests and simulation. Testing is crucial for reliable robot code, and v3's design makes testing easier than v2. This article should encourage teams to adopt testing practices and show them how.
+   This article covers testing commands and mechanisms using both unit tests and simulation. Testing is crucial for reliable robot code, and v3's design facilitates testing. This article should encourage teams to adopt testing practices and show them how.
 
 ## Why Test Commands
 
 .. todo::
    Make the case for testing command-based code. Cover:
    - Benefits of testing: catch bugs early, enable refactoring, document behavior
-   - Why v3 makes testing easier than v2
    - What aspects of command code can/should be tested
    - Testing pyramid: unit tests, integration tests, simulation tests
    - When to write tests (TDD, after implementation, before competition)

source/docs/software/commandbased/commands-v3/what-is-commands-v3.rst

@@ -6,24 +6,23 @@
 
 .. todo::
    - Recap the command-based pattern (commands + mechanisms for resource management)
-   - Explain what's fundamentally different in v3 vs v2
-   - Why imperative style was chosen over declarative composition
-   - Brief history: evolution from v1 → v2 → v3
+   - Explain the imperative programming style
+   - How v3 enables writing robot code that looks like simple sequential programs
 
-## The Problem v3 Solves
+## Learning Curve and On-Ramp
 
 .. todo::
-   **Learning Curve Issues:**
-   - v2 requires understanding functional composition, decorators, and lambda chaining
-   - New programmers struggle with splitting logic across initialize/execute/isFinished
-   - Common mistake: writing blocking loops in execute() that stall the scheduler
+   **Imperative On-Ramp:**
+   - Commands v3 allows teams to transition from basic imperative code to the command framework
+   - Simple sequential code can be lifted into commands with minimal changes
+   - Example: A basic drive-in-a-square routine can be wrapped in command functions
+   - Changing `Thread.sleep()` to `coroutine.wait()` and direct calls to `coroutine.await()`
+   - This provides a gentle learning curve for teams new to command-based programming
 
    **Code Readability:**
-   - Complex behaviors require deeply nested decorator chains
-   - Hard to see the sequential flow of actions
-   - Difficult to add conditional logic mid-sequence
-
-   **Example comparison:** Show a complex autonomous routine in v2 (decorator chains) vs v3 (sequential imperative code) to illustrate the readability difference.
+   - Write robot actions as sequential steps
+   - Use familiar control flow: loops, if-statements, and function calls
+   - Easy to add delays, loops, and conditions within command logic
 
 ## Core Concepts
 
@@ -39,66 +38,45 @@
 
 .. todo::
    - What are coroutines (functions that can pause and resume)
-   - How Java's ``Continuation`` API enables this (internal implementation detail)
    - Cooperative vs preemptive multitasking
    - Commands must voluntarily yield control
    - The scheduler cannot forcibly suspend commands
 
 ### Mechanisms as Exclusive Resources
 
 .. todo::
-   - Mechanisms represent hardware groupings (like v2 Subsystems)
+   - Mechanisms represent hardware groupings
    - Only one command can require a mechanism at a time
    - Automatic resource conflict detection and resolution
-   - Comparison to v2 Subsystems with key differences
 
 ### Command Priorities
 
 .. todo::
-   - Priority levels replace v2's binary interrupt behavior
+   - Priority levels for controlling command interruption
    - Higher priority commands can interrupt lower priority ones
    - Enables nuanced control (e.g., LED priority ladder for different robot states)
    - Default priorities and when to override them
 
-## Key Improvements Over v2
+## Additional Features
 
-### 1. Natural Sequential Syntax
-
-.. todo::
-   - Write steps in order like a recipe
-   - No need to chain decorators for sequential actions
-   - Easy to add delays, loops, and conditions mid-command
-   - Example: Drive to position with adjustments
-
-### 2. Mandatory Command Naming
+### Mandatory Command Naming
 
 .. todo::
    - All commands must have descriptive names
    - Improves telemetry and debugging
-   - Eliminates vague "SequentialCommandGroup" labels
    - Automatic naming for compositions (e.g., "Step 1 -> Step 2 -> Step 3")
 
-### 3. Eliminated Uncommanded Behavior
-
-.. todo::
-   - v2 issue: nested commands finishing at different times leaves subsystems uncommanded
-   - v2 solution: proxy commands (boilerplate heavy)
-   - v3 solution: child commands use mechanisms without parent requiring them
-   - Child commands cannot interrupt parents
-
-### 4. Enhanced Telemetry
+### Enhanced Telemetry
 
 .. todo::
    - Per-instance command tracking (each execution has unique ID)
    - Clear command hierarchy visualization
-   - Performance metrics per command execution
    - Better dashboard integration
 
-### 5. Inner Trigger Scopes
+### Inner Trigger Scopes
 
 .. todo::
    - Triggers defined inside command bodies are scoped to that command's lifetime
-   - No need for global trigger libraries with conditional checks
    - Cleaner code organization
    - Example: Temporary button binding during a specific command
 
@@ -110,20 +88,6 @@
    - **No unrestricted coroutine usage**: Coroutines only work within command context
    - **Cannot replace periodic loops**: Still need periodic methods for continuous updates
 
-## Comparison: v2 vs v3
-
-.. todo::
-   **When to use v2:**
-   - Need C++/Python support
-   - Team comfortable with functional programming
-   - Existing codebase works well
-
-   **When to use v3:**
-   - Java-only team
-   - Prefer imperative style
-   - Want latest features
-   - Starting fresh for 2027
-
 ## Next Steps
 
 .. todo::