Document machine-wide resource name uniqueness

docs/hardware/configure-hardware.md

@@ -111,7 +111,13 @@ If it shows as offline, verify that `viam-server` is running on your machine.
    motor", "xArm6"). The search covers all available models and fragments.
 4. Give your component a **name** and click **Add to machine**. The name is how
    you reference it in code and configuration, so keep it short,
-   descriptive, and unique on this machine.
+   descriptive, and unique on this machine. See [Resource names](#resource-names).
+
+#### Resource names
+
+Starting with `viam-server` v1.6.0, every component and service on a machine needs a name that is unique across the whole machine, even when two resources use different APIs. For example, you can't name both a camera and a sensor `billing`. This includes resources from [remote parts](/hardware/multi-machine/add-a-remote-part/) and fragments. The name `builtin` is reserved for the default services.
+
+If names collide, `viam-server` logs an error and doesn't build the conflicting local resources. Anything that depends on them is also unavailable until you rename one. If a remote resource has the same name as a local resource, the local resource wins and the remote one is hidden from the machine's resource list. If two remotes export the same name, both are hidden. To avoid collisions with remote resources, [set a prefix](/hardware/multi-machine/add-a-remote-part/#3-optional-set-a-prefix) on the remote.
 
 ### 3. Configure attributes
 

docs/hardware/machine-configuration.md

@@ -26,7 +26,7 @@ fields:
 
 | Field        | What it does                                                                                                                                                                     |
 | ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `name`       | A unique name for this component on this machine. Your code references the component by this name.                                                                               |
+| `name`       | A name for this component, unique across the machine ([details](/hardware/configure-hardware/#resource-names)). Your code references the component by this name.                 |
 | `api`        | The component type, in the form `rdk:component:<type>` (for example, `rdk:component:arm`).                                                                                       |
 | `model`      | The specific implementation, in the form `namespace:family:name` (for example, `viam:ufactory:xArm6`). Built-in models use `rdk:builtin:name` (for example, `rdk:builtin:gpio`). |
 | `attributes` | Model-specific settings that control how to connect to the hardware and how it should behave.                                                                                    |

docs/hardware/multi-machine/add-a-remote-part.md

@@ -62,8 +62,11 @@ The remote part is now part of your machine's configuration.
 
 ## 3. Optional: set a prefix
 
-If you connect multiple remotes and some export components with the same names, add a `prefix` to the remote config.
+Resource names must be unique across the whole machine, including resources from remotes.
+If a remote resource has the same name as a local resource, the local one wins and the remote one is hidden. If two remotes export the same name, both are hidden.
+Add a `prefix` to the remote config to prevent this.
 The prefix is prepended to every resource name coming from that remote.
+See [Resource names](/hardware/configure-hardware/#resource-names).
 
 Prefixes are concatenated directly, with no separator.
 To keep names readable, end your prefix with `-` or `_`:

docs/hardware/multi-machine/overview.md

@@ -85,7 +85,7 @@ If you configured a prefix on the remote, it is prepended to every remote resour
 gripper = Gripper.from_robot(machine, "end-effectorgripper")
 ```
 
-When two connected parts export resources with the same name, a prefix disambiguates them.
+Resource names must be unique across the whole machine. When a remote resource has the same name as a local one, the local resource wins and the remote one is hidden. When two remotes export the same name, both are hidden. A prefix prevents this. See [Resource names](/hardware/configure-hardware/#resource-names).
 
 ## What happens on disconnect
 

docs/monitor/troubleshoot.md

@@ -140,6 +140,8 @@ If you set your own start and end times, the button copies a link to that range
 The default log level is `Info`.
 If you are not seeing helpful logs, enable debug logging.
 
+If a resource you configured is missing or unavailable, search the logs for `Resource name`. Two resources sharing a name can stop both from building. See [Resource names](/hardware/configure-hardware/#resource-names).
+
 #### Enable debug logging
 
 **For all resources on the machine**, add `"debug": true` to the JSON configuration: