From 297f8a21a75b6adfc250c7d422b6342fa16ca919 Mon Sep 17 00:00:00 2001
From: James Mackay <NotExpectedYet>
Date: Fri, 9 Oct 2026 07:24:52 +0100
Subject: [PATCH] =?UTF-8?q?docs(readme,strings):=20YAML=20seed-only=20sema?=
 =?UTF-8?q?ntics=20documented=20=E2=80=94=20interactive=20flow,=20duplicat?=
 =?UTF-8?q?e=20guards,=20no=20implicit=20entry=20changes=20on=20block=20re?=
 =?UTF-8?q?moval=20(t30=20U1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 README.md                                     | 22 +++++++++++++++++++
 custom_components/nvidia_shield/strings.json  |  7 +++++-
 .../nvidia_shield/translations/en.json        |  7 +++++-
 3 files changed, 34 insertions(+), 2 deletions(-)

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": {