docs: address deployment review feedback

Author: sumitake

README.md

@@ -207,7 +207,7 @@ flowchart TD
     DeploymentAudience["Configure a compatible OAuth audience"]
     DeploymentClient["Create a TV or Limited Input OAuth client"]
     DeploymentRuntime["Install FFmpeg, Python, and project scripts"]
-    DeploymentConfig["Create private encoder and OAuth files"]
+    DeploymentConfig["Create private encoder, OAuth, and writable service files"]
     DeploymentAuthorize["Authorize the channel account"]
     DeploymentCamera["Configure camera source and ingest profile"]
     DeploymentStreamDecision{"Reusable stream already configured?"}
@@ -233,7 +233,7 @@ flowchart TD
     DeploymentStreamDecision -->|"Yes"| DeploymentValidate
     DeploymentValidate --> DeploymentValidationDecision
     DeploymentValidationDecision -->|"No"| DeploymentDiagnose
-    DeploymentDiagnose --> DeploymentValidate
+    DeploymentDiagnose --> DeploymentStreamDecision
     DeploymentValidationDecision -->|"Yes"| DeploymentEnable
     DeploymentEnable --> DeploymentReboot
     DeploymentReboot --> DeploymentVerify
@@ -318,7 +318,17 @@ YTA_OBS_SCENE_FILE=/home/encoder/.config/obs-studio/basic/scenes/Untitled.json
 YTA_OBS_SOURCE_NAME=Camera RTSP
 ```
 
-The OBS service file supplies the reusable YouTube RTMPS server and stream key. A fresh reusable stream can be provisioned by running the visible test with `--create-stream`; the helper then updates this file before starting the test encoder.
+The OBS service file supplies the reusable YouTube RTMPS server and stream key. It must exist, be writable by the service user, and contain a non-empty `settings.key` before `--create-stream` runs. For a fresh deployment, keep the service disabled and seed a placeholder key:
+
+```json
+{
+  "settings": {
+    "key": "provision-new-stream"
+  }
+}
+```
+
+The placeholder is not a YouTube stream key. `--create-stream` uses it to confirm that no existing stream matches, then replaces it with the new reusable stream key and writes the ingest server before starting the test encoder. A missing file or empty key does not enter the creation path.
 
 ## YouTube API and OAuth Provisioning
 
@@ -431,7 +441,7 @@ If you already have an OBS-compatible `service.json` with a YouTube stream key:
 youtube-autoencoder-api status
 ```
 
-For a fresh setup, make sure the service user can write the configured OBS service file. Then provision the reusable stream through an API-managed visible test after the rest of the encoder config is in place:
+For a fresh setup, create the writable OBS service file with the placeholder `settings.key` shown in the Configuration Model. Then provision the reusable stream through an API-managed visible test after the rest of the encoder config is in place:
 
 ```bash
 YTA_INSTANCE_ID=encoder-hostname youtube-autoencoder-api run-visible-test \

docs/superpowers/plans/2026-07-10-readme-architecture-diagrams.md

@@ -233,7 +233,7 @@ flowchart TD
     DeploymentAudience["Configure a compatible OAuth audience"]
     DeploymentClient["Create a TV or Limited Input OAuth client"]
     DeploymentRuntime["Install FFmpeg, Python, and project scripts"]
-    DeploymentConfig["Create private encoder and OAuth files"]
+    DeploymentConfig["Create private encoder, OAuth, and writable service files"]
     DeploymentAuthorize["Authorize the channel account"]
     DeploymentCamera["Configure camera source and ingest profile"]
     DeploymentStreamDecision{"Reusable stream already configured?"}
@@ -259,7 +259,7 @@ flowchart TD
     DeploymentStreamDecision -->|"Yes"| DeploymentValidate
     DeploymentValidate --> DeploymentValidationDecision
     DeploymentValidationDecision -->|"No"| DeploymentDiagnose
-    DeploymentDiagnose --> DeploymentValidate
+    DeploymentDiagnose --> DeploymentStreamDecision
     DeploymentValidationDecision -->|"Yes"| DeploymentEnable
     DeploymentEnable --> DeploymentReboot
     DeploymentReboot --> DeploymentVerify
@@ -276,7 +276,7 @@ test "$(rg -c '^```mermaid$' README.md)" -eq 3
 test "$(rg -c '^flowchart TB$' README.md)" -eq 1
 test "$(rg -c '^flowchart TD$' README.md)" -eq 1
 test "$(rg -c '^stateDiagram-v2$' README.md)" -eq 1
-rg -n 'DeploymentStreamDecision|DeploymentValidationDecision|remote-management recovery' README.md
+rg -n 'DeploymentStreamDecision|DeploymentValidationDecision|DeploymentDiagnose --> DeploymentStreamDecision|remote-management recovery' README.md
 git diff --check
 ```
 

docs/superpowers/specs/2026-07-10-readme-architecture-diagrams-design.md

@@ -82,7 +82,7 @@ Format: Mermaid `flowchart TD` covering:
 3. Configure an External or otherwise compatible OAuth audience.
 4. Create a TV or Limited Input OAuth client.
 5. Install FFmpeg, Python, and project scripts.
-6. Create private configuration and OAuth files.
+6. Create private configuration, OAuth, and writable service files.
 7. Authorize the channel account and persist the refresh token.
 8. Configure the camera and reusable ingest stream.
 9. Run the visible unlisted validation flow.
@@ -95,6 +95,8 @@ Decision nodes will identify the two operator-significant branches:
 - Existing reusable stream versus provisioning one with `--create-stream`.
 - Validation failure versus successful service enablement.
 
+The detailed README text will state that `--create-stream` requires an existing writable OBS service file with a non-empty placeholder key. A validation failure returns to the reusable-stream decision so provisioning is retried when the prior attempt did not create a stream.
+
 The existing numbered OAuth section remains the source of command and console detail.
 
 ## Mermaid Conventions