Correct motion and frame system API reference accuracy

docs/motion-planning/reference/_index.md

@@ -9,8 +9,8 @@ description: "Configuration, API, and technical reference for the motion service
 
 The motion service turns a high-level "move to this pose" request into a
 collision-free joint trajectory. This reference documents what you
-configure, what the API exposes, and the formats and algorithms it uses
-under the hood. For conceptual background, see
+configure, what the API exposes, and the formats and algorithms behind
+those requests. For conceptual background, see
 [How motion planning works](/motion-planning/how-planning-works/); for
 task-based guidance, start from the [section landing](/motion-planning/).
 

docs/motion-planning/reference/api.md

@@ -10,7 +10,7 @@ aliases:
   - /appendix/apis/services/motion/
 ---
 
-The motion service exposes the methods below for planning and executing component motion. Most methods are implemented only by module-based motion services. The builtin service supports `Move`, `DoCommand`, and `GetStatus`, and nothing else.
+The motion service exposes the methods below for planning and executing component motion. Most methods are implemented only by module-based motion services. The builtin service implements `Move`, `GetPose` (deprecated), `DoCommand`, and `GetStatus`. `MoveOnMap`, `MoveOnGlobe`, `StopPlan`, `ListPlanStatuses`, and `GetPlan` return a `not supported by builtin` error; module-based motion services implement them.
 
 {{< readfile "/static/include/services/apis/generated/motion-table.md" >}}
 
@@ -25,20 +25,27 @@ Plans and executes a motion to a destination pose. This is the primary method fo
 
 Key parameters:
 
-- `component_name`: the arm or gantry to move
+- `component_name`: the component to move (typically an arm or gantry in this section's examples)
 - `destination`: a `PoseInFrame` specifying the target pose and reference frame
 - `world_state`: optional obstacles and transforms
 - `constraints`: optional linear, orientation, or collision constraints
 
+### MoveOnMap, MoveOnGlobe, StopPlan, ListPlanStatuses, and GetPlan
+
+Navigate mobile bases and manage the resulting plans. The builtin motion service returns a `not supported by builtin` error for each of these methods (for example, `MoveOnMap not supported by builtin`); module-based motion services implement them.
+
 ### GetPose (deprecated)
 
 Returns a component's pose. Deprecated in favor of the robot service's `GetPose`. Python callers still use this motion-service method today; see the [Frame system API reference](/motion-planning/reference/frame-system-api/).
 
 ### DoCommand
 
-Sends arbitrary commands. The builtin motion service supports `"plan"`,
-`"execute"`, and `"executeCheckStart"` commands.
+Sends arbitrary commands. The builtin motion service supports a `"plan"`
+command (returns a trajectory without executing it), an `"execute"` command
+(runs a trajectory; add the `"executeCheckStart"` key to an execute request
+to verify the resource is at the trajectory's start first), and the teleop
+commands (`teleop_start`, `teleop_move`, `teleop_stop`, and `teleop_status`).
 
 ### GetStatus
 
-Returns generic resource status for the motion service. Useful for liveness checks.
+Returns generic resource status for the motion service. `GetStatus` is a common resource RPC, so the generated table above omits it. Use it for liveness checks.

docs/motion-planning/reference/frame-system-api.md

@@ -4,7 +4,7 @@ title: "Frame system API reference"
 weight: 27
 layout: "docs"
 type: "docs"
-description: "The RPCs for querying and transforming frame system poses live on the robot service, not a standalone frame system service."
+description: "Query and transform frame system poses with the robot service RPCs: FrameSystemConfig, GetPose, TransformPose, and TransformPCD."
 ---
 
 The RPCs for querying and transforming frame system poses live on the robot service, not on a dedicated `FrameSystemService`. New users often look for a separate service matching the concept; there is none. All four methods below belong to `RobotService` in `api/proto/viam/robot/v1/robot.proto`.
@@ -16,13 +16,12 @@ The RPCs for querying and transforming frame system poses live on the robot serv
 | `TransformPose`     | Convert a pose between reference frames.                                |
 | `TransformPCD`      | Convert a point cloud between reference frames.                         |
 
-The SDK client classes surface these as methods on the robot or
-machine client object (`machine.transform_pose`, `machine.get_pose`,
-and so on). You do not instantiate a separate frame system client.
+Call these methods directly on the robot or machine client
+(`machine.transform_pose`, `machine.get_pose`, and so on).
 
 ## Service names
 
-You do not reference these names directly when calling the frame system from an SDK. They appear here so you can recognize them in error messages or module configuration: inside RDK, the frame system is registered under `builtin` (the default instance that ships with `viam-server`) and `$framesystem` (the name modules use to resolve a dependency on it). The RPCs on the robot/machine client hit the frame system transparently.
+These names appear in error messages and module configuration: inside RDK, the frame system is registered under `builtin` (the default instance included with `viam-server`) and `$framesystem` (the name modules use to resolve a dependency on it). The RPCs on the robot/machine client hit the frame system transparently.
 
 ## FrameSystemConfig
 
@@ -106,13 +105,11 @@ gripperInWorld, err := machine.GetPose(
 
 ### Python goes through the motion service, Go through the robot service
 
-`GetPose` exists on two services in the proto: the robot service (current) and the motion service (older, deprecated, same parameter shape). The Go SDK surfaces the robot service version as `RobotClient.GetPose`; Go callers go through the robot service. The Python SDK never wrapped the robot service version, so Python callers use `MotionClient.get_pose` and hit the deprecated motion service path.
+`GetPose` exists on two services in the proto: the robot service (current) and the motion service (older, deprecated, same parameter shape). The Go SDK exposes the robot service version as `RobotClient.GetPose`; Go callers go through the robot service. The Python SDK never wrapped the robot service version, so Python callers use `MotionClient.get_pose` and hit the deprecated motion service path.
 
-The two paths return equivalent results today. The underlying API
-surface will eventually consolidate, but until then Python callers
-stay on the motion-service path. The CLI's `print-status`, `get-pose`,
-and `set-pose` commands also invoke the deprecated motion-service
-method internally.
+The two paths return equivalent results. The CLI's `print-status`,
+`get-pose`, and `set-pose` commands also invoke the deprecated
+motion-service method internally.
 
 ## TransformPose
 
@@ -183,8 +180,8 @@ motion to it.
 from viam.proto.common import PoseInFrame, Pose, Transform
 
 # 1. Declare the detected box as a supplemental transform.
-#    The Transform's reference_frame is the parent; the pose is the
-#    box's position in that parent.
+#    The Transform's reference_frame names the new frame (detected-box);
+#    pose_in_observer_frame gives its pose in the parent frame (my-camera).
 detected_box = Transform(
     reference_frame="detected-box",
     pose_in_observer_frame=PoseInFrame(
@@ -245,7 +242,8 @@ arm navigates relative to), pass the same transform on the motion
 
 Transform a point cloud from one reference frame to another. Useful for
 aligning point clouds from multiple cameras into a common frame, or for
-expressing lidar scans in world coordinates.
+expressing lidar scans in world coordinates. The Go client exposes this
+RPC as `TransformPointCloud`.
 
 | Parameter         | Description                                                                        |
 | ----------------- | ---------------------------------------------------------------------------------- |

docs/motion-planning/reference/kinematics.md

@@ -12,9 +12,9 @@ aliases:
 
 A kinematics file describes your arm's physical structure (link lengths, joint axes, joint limits) so the motion planner can solve the inverse kinematics problem: given a target pose, find joint angles that reach it.
 
-{{< alert title="Most arms handle this automatically" color="tip" >}}
+{{< alert title="Most arm modules handle this automatically" color="tip" >}}
 
-Most arm modules in the Viam registry include a kinematics file. For standard
+Most arm modules in the Viam Registry include a kinematics file. For standard
 commercial arms like the UR5e, xArm6, or Viam Arm, the module handles
 kinematics automatically; you do not need to provide or configure a
 kinematics file. Read this page if you are building a custom arm, using a
@@ -75,7 +75,7 @@ Viam supports two kinematics file formats at the API level:
 | **SVA** (Spatial Vector Algebra) | Viam's native JSON format                     | When writing a Viam kinematics file directly.                |
 | **URDF**                         | XML format used by ROS and many manufacturers | When the manufacturer ships a URDF and you want to reuse it. |
 
-`GetKinematics` returns one of these two formats. Viam's SVA schema also accepts Denavit-Hartenberg parameters inline, as a convenience when you are converting a textbook DH table; DH is not a third API-level format.
+`GetKinematics` returns one of these two formats. The same JSON file format also accepts Denavit-Hartenberg (DH) parameters: set `kinematic_param_type` to `"DH"` and supply a `dhParams` array, a convenience when you are converting a textbook DH table. DH is not a third API-level format.
 
 Most registry arm modules use SVA internally. You rarely need to write a
 kinematics file from scratch unless you are building a custom arm.
@@ -93,7 +93,7 @@ kinematics file.
 
 ### 1. Check if your arm has a built-in kinematics file
 
-Most arm modules in the Viam registry ship with a kinematics file built into
+Most arm modules in the Viam Registry include a kinematics file built into
 the module. The module loads and applies the kinematics automatically when
 `viam-server` starts.
 
@@ -190,19 +190,24 @@ Each field:
 - **`links[].id`**: unique name for the link
 - **`links[].parent`**: the joint or frame this link attaches to
 - **`links[].translation`**: offset in mm from the parent's origin
+- **`links[].orientation`**: optional orientation of the link relative to its
+  parent, in any of the
+  [orientation formats](/motion-planning/reference/orientation-vectors/)
 - **`links[].geometry`**: optional collision shape (uses `type`, `x`/`y`/`z` for box, `r` for sphere/capsule/cylinder, `l` for capsule length or cylinder height)
 - **`joints[].id`**: unique name for the joint
 - **`joints[].type`**: `"revolute"` (rotates) or `"prismatic"` (slides)
 - **`joints[].parent`**: the link this joint attaches to
 - **`joints[].axis`**: the axis of rotation or translation (unit vector)
 - **`joints[].min`** / **`joints[].max`**: joint limits in degrees (revolute)
   or mm (prismatic)
+- **`joints[].geometry`**: optional collision shape, prismatic joints only
 - **`joints[].mimic`** (optional): make this joint follow another joint at a
   fixed multiplier and offset, for parallel-jaw grippers and other mechanically
   coupled axes. The mimic object takes `joint` (the source joint's `id`),
   `multiplier`, and `offset`; the joint's value is computed as
-  `multiplier * source_value + offset`. Mimic joints must not declare their own
-  `min`/`max`; the source joint's limits apply.
+  `multiplier * source_value + offset`. An omitted `multiplier` defaults to
+  1.0. Mimic joints must not declare their own `min`/`max`; the source joint's
+  limits apply.
 
 ### 3. Import a URDF file