Add AGENTS.md with repository and build guidance

[mmmarinho]

Summary

Adds a top-level AGENTS.md documenting the repository for AI agents and contributors, derived from an analysis of the codebase.

What it covers

• What this is: ROS 2 (jazzy) ament_cmake package providing the RobotDriverServer / RobotDriverClient ROS-topic pair (C++ + pybind11 Python bindings).
• Repository layout: include/, src/, the pure-Python sas_robot_driver/ wrapper, scripts/, launch/, the pybind11 git submodule, and the docker/ CI build files.
• Build & verify: no local test suite — verification is the docker compose flow used by CI (murilomarinho/sas:jazzy image, colcon build, then running the example script), plus out-of-docker colcon build instructions for a full ROS 2 jazzy workspace with sibling SAS packages, Eigen3, and libdqrobotics.
• Architecture notes: topic prefix pairing, client enablement handshake, mode blacklisting, RobotDriverROS control loop + optional watchdog, the composer node, and the 2025 removal of CoppeliaSim (now in sas_robot_driver_coppeliasim).
• ROS parameters per node (robot_name, joint_limits_min/max, thread_sampling_time_sec, watchdog_period, etc.).
• Conventions: LGPLv3 header blocks + contributors sections, -Wall -Wextra -Wpedantic, the IS_SAS_PYTHON_BUILD dual-compile of client/server sources, the copied pybind11 import block delimiters in CMakeLists.txt, ament_flake8/ament_pep257 linting, and the absence of unit tests.
• Git: jazzy as the development branch, shallow-clone caveat, and the pybind11 submodule init command.

This PR was created by an AI agent (OpenHands) on behalf of the user.

[mmmarinho]

Follow-up on the AGENTS.md PR: removed IS_SAS_PYTHON_BUILD since it is not actually used anywhere.

Findings: the macro was only defined for the pybind11 target in CMakeLists.txt and referenced in a commented-out constructor block in include/sas_robot_driver/sas_robot_driver_server.hpp — no live code path depends on it (grep across src/ and include/ found no active #ifdef/#ifndef usage).

Changes in this commit (005738f):

• CMakeLists.txt — removed the target_compile_definitions(_sas_robot_driver PRIVATE IS_SAS_PYTHON_BUILD) line.
• include/sas_robot_driver/sas_robot_driver_server.hpp — removed the dead commented-out //#ifdef IS_SAS_PYTHON_BUILD block (and its //see the discussion in sas_common... note).
• AGENTS.md — updated the conventions bullet that referenced the macro, so it now just notes the client/server sources are compiled twice (shared lib + pybind11 module).

Build behavior is unchanged; the example nodes and Python bindings are unaffected.

— this comment was added by an AI agent (OpenHands) on behalf of the maintainer.

[mmmarinho]

Follow-up: exposed the mode-blacklist enum to Python.

Background: sas::RobotDriverClient::MODE_BLACKLIST_FLAG is the enum behind the client constructor's blacklisted_modes parameter (used by the C++ watchdog commander to blacklist JOINT_CONTROL), but it had no py::enum_ binding. Since pybind11 had no type caster for it, the blacklisted_modes argument was effectively unusable from Python — only the default empty list worked.

Changes (commit 2f36566):

• src/sas_robot_driver_py.cpp — added a py::enum_<RDC::MODE_BLACKLIST_FLAG> binding exposing JOINT_CONTROL, JOINT_MONITORING, WATCHDOG_CONTROL (mirroring the existing Functionality binding).
• sas_robot_driver/__init__.py — re-export MODE_BLACKLIST_FLAG so from sas_robot_driver import MODE_BLACKLIST_FLAG works.
• AGENTS.md — added MODE_BLACKLIST_FLAG to the documented Python API list.

Verification (in the CI image murilomarinho/sas:jazzy via the docker compose build):

• colcon build succeeds; the sas_robot_driver_interface_example.py flow runs and prints the expected output.
• Runtime check: RobotDriverClient(node, "enum_test", [MODE_BLACKLIST_FLAG.JOINT_CONTROL]) now constructs successfully, and the enum values round-trip (JOINT_CONTROL == 0, WATCHDOG_CONTROL == 2).

— this comment was added by an AI agent (OpenHands) on behalf of the maintainer.

[mmmarinho]

👍