diff --git a/README.md b/README.md
index 8b46f3b..96085ce 100644
--- a/README.md
+++ b/README.md
@@ -92,6 +92,28 @@ the inter-digit **delay** (0.05–1.0 s, default 0.1) and the optional
 behavior). Both are consumed by `play_media` with
 `media_content_type: channel`.
 
+### YAML seeding (optional, seed-only)
+
+An optional `nvidia_shield:` block in `configuration.yaml` **seeds** an
+interactive setup flow — nothing is created without the user walking the
+standard flow, and pairing stays interactive exactly as with UI setup:
+
+```yaml
+nvidia_shield:
+  - name: Living Room
+    adb_host: 10.0.0.31      # or protocol_host for the PIN-pairing hint
+    adb_port: 5555
+```
+
+`protocol_host` is a prefill hint only (the PIN pairing still happens in
+the flow). Blocks without protocol/adb hosts are ignored with a warning.
+Duplicate guards: a block matching an existing entry's host (or its
+virtual `yaml:…` unique_id) aborts and never re-seeds a UI-configured
+host. Removing the YAML block creates or deletes nothing — entries live
+in the storage registry and require user consent to remove. Deleting/re-
+adding is the only way to move an imported entry between hosts; the UI is
+the contractual path (YAML is the seed, the flow is the truth).
+
 ### Raw `adb_command` service (opt-in)
 
 When enabled in the integration's options (`adb_command_enabled`, **default
diff --git a/custom_components/nvidia_shield/strings.json b/custom_components/nvidia_shield/strings.json
index 24b71e0..96bffed 100644
--- a/custom_components/nvidia_shield/strings.json
+++ b/custom_components/nvidia_shield/strings.json
@@ -62,7 +62,12 @@
       "already_configured": "This Shield entity is already configured.",
       "reauth_successful": "Re-paired successfully.",
       "reauth_entry_missing": "This entry no longer exists.",
-      "zeroconf_no_host": "The discovery event carried no usable address."
+      "zeroconf_no_host": "The discovery event carried no usable address.",
+      "yaml_seed_only": {},
+      "yaml_seed": {
+        "title": "YAML succeeded earlier",
+        "message": "The configuration.yaml nvidia_shield block is seed-only: it starts the standard interactive flow. Removing the YAML block creates or deletes nothing."
+      }
     }
   },
   "options": {
diff --git a/custom_components/nvidia_shield/translations/en.json b/custom_components/nvidia_shield/translations/en.json
index 24b71e0..96bffed 100644
--- a/custom_components/nvidia_shield/translations/en.json
+++ b/custom_components/nvidia_shield/translations/en.json
@@ -62,7 +62,12 @@
       "already_configured": "This Shield entity is already configured.",
       "reauth_successful": "Re-paired successfully.",
       "reauth_entry_missing": "This entry no longer exists.",
-      "zeroconf_no_host": "The discovery event carried no usable address."
+      "zeroconf_no_host": "The discovery event carried no usable address.",
+      "yaml_seed_only": {},
+      "yaml_seed": {
+        "title": "YAML succeeded earlier",
+        "message": "The configuration.yaml nvidia_shield block is seed-only: it starts the standard interactive flow. Removing the YAML block creates or deletes nothing."
+      }
     }
   },
   "options": {