I am not sure if integer is a good example here. That also opens the question what makes this a parameter of type since there needs to be some magic to convert the type solely based on its value which has problems on its own.

Therefore I would suggest to simply use a string value here.

Hmm, I agree with using a string value to simplify the example but I also think that parameter value syntax cannot be left out of a command line specification. Here, just like when parameter files are parsed in rcl and when launch substitutions occur in Node parameters, we delegate on YAML format rules for type inference based on values. Whether that's a good call or not is likely worth a separate discussion.

Maybe add a short section about the implementation. Basically where the extraction from argc / argv happens and that all remaining arguments are still available for the user code to process.

That makes sense. It also raises an interesting question. Assuming extraction happens in rcl, should we support arguments specific to upper layers e.g. rclcpp or rclpy? Those would have to be available unparsed, separate from user defined arguments.

We could, but they could live in between the --ros-args and --, and rcl could just ignore them and leave them in a "left over args" output. Then rclcpp and/or rclpy can use those arguments or make warnings/errors because there are unknown parameters left over.