docs: --record / --record-topics

[spomichter]

Summary

Docs for --record / --record-topics (#3710).

• docs/usage/recording.md (new): what --record writes and where, choosing streams with --record-topics, dimos mem summary + --replay-db on the result, behaviour notes.
• docs/usage/cli.md: the two flags in the global options table; record → replay example.
• Links from the data-streams index, the Go2 blueprint table, and the relocalization guide's record step.

Test plan

• pre-commit doclinks / em-dash hooks pass on the changed files

[codecov]

❌ 2 Tests Failed:

Tests completed	Failed	Passed	Skipped
4859	2	4857	87

View the top 1 failed test(s) by shortest run time

dimos.e2e_tests.test_manipulation_planning_groups::test_dual_arm_plans_and_dispatches_both_arms_through_control_coordinator

Stack Traces | 120s run time

lcm_spy = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76fe9a89a2d0>
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x76fe98d65580>

    def test_dual_arm_plans_and_dispatches_both_arms_through_control_coordinator(
        lcm_spy: LcmSpy,
        start_blueprint: Callable[..., DimosCliCall],
    ) -> None:
        """Plan one generated plan over both arms and dispatch through one trajectory task."""
>       _start_openarm_mock_planner(start_blueprint, lcm_spy)

lcm_spy    = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76fe9a89a2d0>
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x76fe98d65580>

dimos/e2e_tests/test_manipulation_planning_groups.py:190: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
dimos/e2e_tests/test_manipulation_planning_groups.py:151: in _start_openarm_mock_planner
    lcm_spy.wait_for_saved_topic(JOINT_STATE_TOPIC, timeout=120.0)
        lcm_spy    = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76fe9a89a2d0>
        start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x76fe98d65580>
dimos/e2e_tests/lcm_spy.py:97: in wait_for_saved_topic
    wait_until(
        condition  = <function LcmSpy.wait_for_saved_topic.<locals>.condition at 0x76fe98d65b20>
        self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76fe9a89a2d0>
        timeout    = 120.0
        topic      = '/coordinator_joint_state#sensor_msgs.JointState'
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

predicate = <function LcmSpy.wait_for_saved_topic.<locals>.condition at 0x76fe98d65b20>

    def wait_until(
        predicate: Callable[[], bool],
        *,
        timeout: float,
        interval: float = 0.1,
        message: str | None = None,
    ) -> None:
        """Poll ``predicate`` until it returns truthy or ``timeout`` elapses."""
        deadline = time.monotonic() + timeout
        while time.monotonic() < deadline:
            if predicate():
                return
            time.sleep(interval)
>       raise TimeoutError(message or f"Timed out after {timeout}s waiting for condition")
E       TimeoutError: Timeout waiting for topic /coordinator_joint_state#sensor_msgs.JointState

deadline   = 4341479.677804535
interval   = 0.1
message    = 'Timeout waiting for topic /coordinator_joint_state#sensor_msgs.JointState'
predicate  = <function LcmSpy.wait_for_saved_topic.<locals>.condition at 0x76fe98d65b20>
timeout    = 120.0

.../utils/testing/waiting.py:35: TimeoutError

View the full list of 1 ❄️ flaky test(s)

dimos.e2e_tests.test_manipulation_planning_groups::test_single_arm_plans_and_executes_through_control_coordinator

Flake rate in main: 7.69% (Passed 12 times, Failed 1 times)

Stack Traces | 120s run time

lcm_spy = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76feb855f650>
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x76fe98d645e0>

    def test_single_arm_plans_and_executes_through_control_coordinator(
        lcm_spy: LcmSpy,
        start_blueprint: Callable[..., DimosCliCall],
    ) -> None:
        """Plan with one arm and execute through its trajectory task."""
>       _start_openarm_mock_planner(start_blueprint, lcm_spy)

lcm_spy    = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76feb855f650>
start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x76fe98d645e0>

dimos/e2e_tests/test_manipulation_planning_groups.py:159: 
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 
dimos/e2e_tests/test_manipulation_planning_groups.py:151: in _start_openarm_mock_planner
    lcm_spy.wait_for_saved_topic(JOINT_STATE_TOPIC, timeout=120.0)
        lcm_spy    = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76feb855f650>
        start_blueprint = <function start_blueprint.<locals>.set_name_and_start at 0x76fe98d645e0>
dimos/e2e_tests/lcm_spy.py:97: in wait_for_saved_topic
    wait_until(
        condition  = <function LcmSpy.wait_for_saved_topic.<locals>.condition at 0x76fe98d65260>
        self       = <dimos.e2e_tests.lcm_spy.LcmSpy object at 0x76feb855f650>
        timeout    = 120.0
        topic      = '/coordinator_joint_state#sensor_msgs.JointState'
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ 

predicate = <function LcmSpy.wait_for_saved_topic.<locals>.condition at 0x76fe98d65260>

    def wait_until(
        predicate: Callable[[], bool],
        *,
        timeout: float,
        interval: float = 0.1,
        message: str | None = None,
    ) -> None:
        """Poll ``predicate`` until it returns truthy or ``timeout`` elapses."""
        deadline = time.monotonic() + timeout
        while time.monotonic() < deadline:
            if predicate():
                return
            time.sleep(interval)
>       raise TimeoutError(message or f"Timed out after {timeout}s waiting for condition")
E       TimeoutError: Timeout waiting for topic /coordinator_joint_state#sensor_msgs.JointState

deadline   = 4341359.511604114
interval   = 0.1
message    = 'Timeout waiting for topic /coordinator_joint_state#sensor_msgs.JointState'
predicate  = <function LcmSpy.wait_for_saved_topic.<locals>.condition at 0x76fe98d65260>
timeout    = 120.0

.../utils/testing/waiting.py:35: TimeoutError

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

[greptile-apps]

Greptile Summary

This PR documents global stream recording, topic selection, inspection, and replay, and links the workflow from the CLI, data-stream, Go2, and relocalization guides.

• Adds a dedicated recording guide covering output paths, filtering, replay, and buffering behavior.
• Adds the new global options and a record-to-replay example to the CLI reference.
• Cross-links recording from relevant platform and usage documentation.

Confidence Score: 4/5

The PR needs a documentation correction before merging because the new guide directs users to the wrong pose source and can lead them to a crashing pose-fill invocation.

The recording workflow is otherwise consistent with the CLI and runtime, but pose-fill defaults to odometry and cannot consume the recorded TFMessage stream as the guide claims.

Files Needing Attention: docs/usage/recording.md

Important Files Changed

Filename	Overview
docs/usage/recording.md	Adds the main recording guide, but incorrectly attributes pose-fill behavior to the TF stream.
docs/usage/cli.md	Accurately documents the recording options and record-to-replay command sequence.
docs/capabilities/navigation/relocalization.md	Correctly contrasts explicit Go2 memory recording with global stream recording.
docs/platforms/quadruped/go2/index.md	Adds a valid recording invocation for the registered Go2 navigation blueprint.
docs/usage/data_streams/index.md	Adds a valid link to the new recording guide.

_{Reviews (1): Last reviewed commit: "docs: --record / --record-topics" | Re-trigger Greptile}