docs(ios-qa): document the bridge compatibility preflight and non-SwiftPM fallback

Re-derived from PR #2581 under the generated-file screening rule (template
hunk taken; SKILL.md regenerated). Prevents the agent from inventing project
wiring on apps the bridge doesn't support (ObservableObject-style or
non-SwiftPM apps): the preflight now names the compatibility check and the
manual fallback path.

Co-authored-by: Tim White <itstimwhite@users.noreply.github.com>
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

ios-qa/SKILL.md

@@ -886,7 +886,20 @@ fi
 
 ## Phase 1: Read source, plan codegen
 
-1. Walk the app source (passed as `--source <dir>`) and identify all `@Observable`
+1. Before changing the app or replacing an installed build, verify that the
+   bridge is compatible with the project:
+   - The generator currently supports file-scope `@Observable` classes only;
+     `ObservableObject`, `@StateObject`, and other observation models do not
+     produce accessors.
+   - The documented dependency wiring assumes a SwiftPM app manifest. For an
+     `.xcodeproj` or `.xcworkspace`, do not invent package or target wiring.
+   If either requirement is unmet, stop the bridge bootstrap without modifying
+   the app. Preserve any installed production or TestFlight build. Prefer an
+   existing real-device XCUITest harness; when a separate QA build is needed,
+   use an isolated bundle identifier and non-production entitlements so it can
+   coexist with the production app. Report fixture-driven state, provider UI,
+   and actual external-provider success as distinct evidence tiers.
+2. Walk the app source (passed as `--source <dir>`) and identify all `@Observable`
    classes. Note any property immediately preceded by the generator marker
    comment `// @Snapshotable` — those are the snapshot-eligible fields. The
    marker is a comment so it composes with the `@Observable` macro. Each
@@ -897,7 +910,7 @@ fi
    Optional compositions. Keys must be unique across observable classes.
    Codegen stops with a source diagnostic instead of emitting a broken or
    lossy harness when any of these constraints is violated.
-2. Show the user the accessor list and ask whether to install the DebugBridge
+3. Show the user the accessor list and ask whether to install the DebugBridge
    SPM dependency into their `Package.swift` (one AskUserQuestion).
 
 ## Phase 2: Bootstrap the device bridge

ios-qa/SKILL.md.tmpl

@@ -96,7 +96,20 @@ fi
 
 ## Phase 1: Read source, plan codegen
 
-1. Walk the app source (passed as `--source <dir>`) and identify all `@Observable`
+1. Before changing the app or replacing an installed build, verify that the
+   bridge is compatible with the project:
+   - The generator currently supports file-scope `@Observable` classes only;
+     `ObservableObject`, `@StateObject`, and other observation models do not
+     produce accessors.
+   - The documented dependency wiring assumes a SwiftPM app manifest. For an
+     `.xcodeproj` or `.xcworkspace`, do not invent package or target wiring.
+   If either requirement is unmet, stop the bridge bootstrap without modifying
+   the app. Preserve any installed production or TestFlight build. Prefer an
+   existing real-device XCUITest harness; when a separate QA build is needed,
+   use an isolated bundle identifier and non-production entitlements so it can
+   coexist with the production app. Report fixture-driven state, provider UI,
+   and actual external-provider success as distinct evidence tiers.
+2. Walk the app source (passed as `--source <dir>`) and identify all `@Observable`
    classes. Note any property immediately preceded by the generator marker
    comment `// @Snapshotable` — those are the snapshot-eligible fields. The
    marker is a comment so it composes with the `@Observable` macro. Each
@@ -107,7 +120,7 @@ fi
    Optional compositions. Keys must be unique across observable classes.
    Codegen stops with a source diagnostic instead of emitting a broken or
    lossy harness when any of these constraints is violated.
-2. Show the user the accessor list and ask whether to install the DebugBridge
+3. Show the user the accessor list and ask whether to install the DebugBridge
    SPM dependency into their `Package.swift` (one AskUserQuestion).
 
 ## Phase 2: Bootstrap the device bridge