Document logical prompt profile configuration

docs/troubleshooting.md

@@ -11,6 +11,28 @@ the configured `promptkit` profile or profile source, confirm the exact
 Promptkit asset is available, and supply any reported environment credential.
 Do not add provider keys to YAML. See [configuration](config.md).
 
+## Local profile override is malformed or selects an unexpected model
+
+`promptkit.profile_file` and `promptkit.profile_dir` supply complete profile
+definitions. A same-ID definition replaces the embedded profile, and a malformed
+matching definition fails before collection instead of falling back. Validate
+the selected profile's YAML, ID, backend or endpoint, and model. If the model
+is unexpected, first check the global `promptkit.profile` selection and then
+look for a same-ID definition in the configured file or directory.
+
+The preparation and execution receipts named by run metadata retain the
+selected profile ID and effective backend/model for diagnosis, but not an
+endpoint or credential. See the maintained
+[local `weather-light` profile example](../examples/weather-light-local-profile.yml).
+
+## Local model endpoint is unavailable
+
+An endpoint-only `weather-light` override can pass preflight and still fail
+during provider preparation or execution when the local server is unavailable
+or does not accept the configured model. Start the local server, correct the
+endpoint or model in the profile, and run the command again. Weatherreporter
+does not probe endpoints or automatically use a remote profile instead.
+
 ## Preparation, capacity, or execution fails
 
 A preparation failure occurs before provider work; an execution failure occurs