docs(swiftpm): correct SwiftPM docs to match current scripts

Fix statements in the SwiftPM and ios-prebuild __docs__ that no longer
match the code: CLI options, exit code 2 causes, what sync does and when
it re-runs, which command writes each file, header products, remote mode,
and header sidecar layout. Add an environment variables table.

Author: chrfalch

packages/react-native/scripts/ios-prebuild/__docs__/README.md

@@ -126,11 +126,14 @@ overlay**. The layout contract is defined and validated in code:
   the `React/` and bare-aliased headers into every slice's
   `React.framework/Headers`, and `buildReactNativeHeadersXcframework()`
   assembles the headers-only `ReactNativeHeaders.xcframework` carrying every
-  other namespace (incl. `react/`) plus the third-party dependency namespaces
-  (`folly`, `glog`, `boost`, `fmt`, `double-conversion`, `fast_float`). The
-  Hermes public headers (`<hermes/...>`) are folded in only on the SwiftPM
-  consumer side (`ensureHeadersLayout`); the published prebuild artifact does
-  not yet carry them (TODO in `xcframework.js`).
+  other React Native namespace (incl. `react/`). The third-party dependency
+  namespaces (`folly`, `glog`, `boost`, `fmt`, `double-conversion`,
+  `fast_float`, `SocketRocket`) ship in the separate headers-only
+  `ReactNativeDependenciesHeaders.xcframework` sidecar, built by the
+  dependencies prebuild. The Hermes public headers (`<hermes/...>`) are folded
+  into the published `ReactNativeHeaders` when the hermes-ios headers are
+  staged; without them the compose ships no `hermes/`, unless `--require-hermes`
+  is set, which makes it fail closed.
 
 ### Artifacts
 
@@ -145,9 +148,9 @@ The prebuild (`xcframework.js`) always produces:
   `ReactHeadersTarget/include/React` and rewrites `framework module React` to a
   plain `module React`, vended as the `ReactHeaders` target (see
   `spm-header-paths-contract.md` in the SwiftPM docs).
-- `ReactNativeHeaders.xcframework` — headers-only; carries every other
-  namespace. Consumed by SwiftPM as a `binaryTarget` and by CocoaPods via the
-  `React-Core-prebuilt` pod (headers flattened onto the header search path).
+- `ReactNativeHeaders.xcframework` — headers-only; carries every other React
+  Native namespace. Consumed by SwiftPM as a `binaryTarget` and by CocoaPods via
+  the `React-Core-prebuilt` pod (headers flattened onto the header search path).
 
 ### CocoaPods consumption
 

packages/react-native/scripts/ios-prebuild/__docs__/headers-rules.md

@@ -120,13 +120,14 @@ resolving `<react/...>` through `React.framework` requires case-folding
 `react.framework` → `React.framework`, which only works on case-insensitive
 filesystems. The header-search-path route (R2) is exact everywhere.
 
-**R2 — every other namespace ships in ONE headers-only xcframework,
+**R2 — every other React Native namespace ships in ONE headers-only xcframework,
 `ReactNativeHeaders`.** Namespace dirs at its `Headers/` root: `react/`,
-`yoga/`, `jsi/`, `cxxreact/`, `React_RCTAppDelegate/`, … **including the
-third-party deps namespaces** (folly/glog/boost/fmt/double-conversion/
-fast_float, copied out of the ReactNativeDependencies artifact — which thereby
-becomes binary-only). SPM/Xcode auto-serve a binaryTarget's `Headers/` on the
-consumer's search path, so everything resolves with zero flags.
+`yoga/`, `jsi/`, `cxxreact/`, `React_RCTAppDelegate/`, … The third-party deps
+namespaces (folly, glog, boost, fmt, double-conversion, fast_float,
+SocketRocket) are **not** here: they ship in the headers-only
+`ReactNativeDependenciesHeaders` sidecar built by the deps prebuild. SPM/Xcode
+auto-serve a binaryTarget's `Headers/` on the consumer's search path, so
+everything resolves with zero flags.
 
 **R3 — NO include rewriting, anywhere.** Shipped headers are byte-identical to
 the repo. If a header's includes don't work in the packaged layout, the fix is
@@ -271,11 +272,11 @@ module.
 
 ### `buildReactNativeHeadersXcframework`
 
-1. Stage all R2 entries, then copy the six deps namespaces from
-   `third-party/ReactNativeDependencies.xcframework/Headers`. A declared deps
-   namespace that is missing is a **hard error** — previously a warn-and-ship,
-   which once produced a silently deps-less artifact (1.6 MB instead of 11 MB).
-2. Optionally fold in the `hermes/` public headers (consumer-side compose path).
+1. Stage all R2 entries. The deps namespaces are not copied here; they ship in
+   the `ReactNativeDependenciesHeaders` sidecar, whose namespace guards live in
+   `buildDepsHeadersXcframework` (`headers-xcframework.js`).
+2. Fold in the `hermes/` public headers when they are staged (both the prebuild
+   compose and the consumer-side compose path).
 3. Write the R10 umbrella files, then the R5 module map.
 4. Compile a stub static archive per slice (headers-only artifacts still need a
    library for `xcodebuild -create-xcframework`) and compose the xcframework.
@@ -296,13 +297,16 @@ mtime + hermes presence).
 | `#import <React/RCTMountingManager.h>`                                   | same, **textual** via the R9 entry                                                                                                  | R9     |
 | `#import <react/renderer/...>` (C++)                                     | `ReactNativeHeaders/Headers` search path, textual                                                                                   | R2     |
 | `#import <yoga/Yoga.h>`                                                  | same, **modular** via the yoga R5 module                                                                                            | R2, R5 |
-| `#import <folly/dynamic.h>`                                              | same (deps namespaces relocated here)                                                                                               | R2     |
+| `#import <folly/dynamic.h>`                                              | SwiftPM: the `ReactNativeDependenciesHeaders` sidecar's `Headers/` (deps namespaces are not in `ReactNativeHeaders`)                | R2     |
 | `<React_RCTAppDelegate/React_RCTAppDelegate-umbrella.h>`                 | same, modular                                                                                                                       | R10    |
 | `#import "RCTFabricComponentsPlugins.h"` (quoted, community Fabric pods) | CocoaPods only: re-vended by the `React-RCTFabric` facade into the pod header map (`rncore_facades.rb`, `FACADE_REEXPOSED_HEADERS`) | —      |
 
-- **SwiftPM**: both xcframeworks are plain `.binaryTarget`s; Xcode auto-serves
-  `React.framework`'s `Headers/`+`Modules/` and `ReactNativeHeaders`' `Headers/`
-  (incl. its `module.modulemap`) to dependents. Zero flags.
+- **SwiftPM**: `React.xcframework` is not in the package graph. Its headers are
+  copied into `ReactHeadersTarget/include/React` with the module map rewritten
+  to a plain `module React`, vended as the `ReactHeaders` target. The only
+  `.binaryTarget`s are `ReactNativeHeaders` and
+  `ReactNativeDependenciesHeaders`; Xcode auto-serves their `Headers/` (incl.
+  `module.modulemap`) to dependents. Zero flags.
 - **CocoaPods**: `React-Core-prebuilt`'s `prepare_command` flattens
   `ReactNativeHeaders`' Headers (incl. the module map) into the pod, and the
   React-core pods are installed as dependency-only **facades**
@@ -316,8 +320,8 @@ mtime + hermes presence).
 | R9 allowlist validation           | private header removed/renamed, or bucket drifted                                                                                                      | `validatePrivateReactHeaders`                  |
 | R10 umbrella check                | a probed namespace loses all modular headers                                                                                                           | `planFromInventory`                            |
 | R5 exemption assert               | an invalid-module-identifier namespace gains a modular-candidate header                                                                                | `planFromInventory`                            |
-| Deps namespace guard (missing)    | folly/glog/… not staged at compose time                                                                                                                | `buildReactNativeHeadersXcframework`           |
-| Deps namespace guard (undeclared) | the deps artifact ships a namespace not in `DEPS_NAMESPACES` (new third-party dep)                                                                     | `buildReactNativeHeadersXcframework`           |
+| Deps namespace guard (missing)    | folly/glog/… not staged at compose time                                                                                                                | `buildDepsHeadersXcframework`                  |
+| Deps namespace guard (undeclared) | the deps artifact ships a namespace not in `DEPS_NAMESPACES` (new third-party dep)                                                                     | `buildDepsHeadersXcframework`                  |
 | Include-health ratchet            | a shipped header gains a `notShipped`/`unresolved`/quoted-unresolvable include not in the committed baseline                                           | `headers-verify.js`                            |
 | Structural gate                   | composed module maps/umbrellas differ from the spec render; R9 headers or deps dirs absent                                                             | `headers-verify.js`                            |
 | Compile gates                     | the React module, any R5 namespace module, the R10 umbrella, the R9 textual (Expo-shape) surface, or Swift `RCTBridge.moduleRegistry` fails to compile | `headers-verify.js` (CI: prebuild compose job) |

packages/react-native/scripts/spm/__docs__/README.md

@@ -52,7 +52,7 @@ Three documents cover the design, each owning one area:
 | Document                                                       | Covers                                                                                                                                                                                                                          |
 | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | [spm-scripts.md](./spm-scripts.md)                             | The tool itself: CLI surface, the six-step pipeline, [every file it creates or modifies](./spm-scripts.md#files-the-tool-touches), the two auto-sync hooks, and how Debug/Release flavor selection works.                       |
-| [spm-header-paths-contract.md](./spm-header-paths-contract.md) | How headers and package references resolve. The contract is **zero-`-I`**: no header search paths and no `unsafeFlags` in any generated manifest. Also covers remote mode.                                                      |
+| [spm-header-paths-contract.md](./spm-header-paths-contract.md) | How headers and package references resolve. The contract is **zero-`-I`**: no generated manifest carries a search path into React Native's own headers. Also covers remote mode.                                                |
 | [spm-autolinking-plugins.md](./spm-autolinking-plugins.md)     | The extension seam for frameworks with their own module system (Expo is the first consumer): discovery, the full context/return contract including `flavoredFrameworks`, `watchPaths` and `scriptPhases`, and failure behavior. |
 
 Two ideas explain most of the architecture:
@@ -83,7 +83,8 @@ Two ideas explain most of the architecture:
   local `React-GeneratedCode` package rather than a Pod.
 - **`@react-native-community/cli config`** — supplies the autolinking metadata
   (`autolinking.json`) that the SwiftPM autolinker turns into a `Package.swift`.
-  Overridable via `--configCommand`.
+  Overridable via the `RCT_SPM_AUTOLINKING_CONFIG_COMMAND` environment variable,
+  or `--config-command` when running `setup-apple-spm.js` directly.
 
 ### Uses this
 

packages/react-native/scripts/spm/__docs__/spm-autolinking-plugins.md

@@ -48,6 +48,10 @@ allowlist is required. The deprecated `spm.autolinkingPlugin` in
 `react-native.config.js` is still read — see
 [Migrating from react-native.config.js](spm-scripts.md#where-swiftpm-settings-live).
 
+A dependency that declares a plugin owns its native contribution. React Native
+does not build it as an autolinked target, so it needs no `Package.swift` of its
+own.
+
 **Opt-out escape hatch.** An app can exclude a plugin from its own package.json:
 
 ```json
@@ -149,6 +153,9 @@ with a warning (never fatal), and each non-string / empty / **relative** entry
 is dropped with a warning. Absolute-only, because the generated phase tests
 these paths with no cwd context. The kept paths are folded into
 `<outputDir>/.spm-sync-watch-paths` alongside RN's own, then deduped and sorted.
+Only paths that exist when the sync runs are written; a missing path is dropped
+silently. So the **vanished** check above applies only to paths that existed at
+the last sync.
 
 ### `scriptPhases` — build-time shell phases on the app target
 
@@ -185,9 +192,8 @@ agree nothing is rewritten, which is what keeps an unchanged declaration
 re-syncing to a byte-identical project. The consequence worth knowing: a phase
 you **drag somewhere else in Xcode is moved back** to its declared position on
 the next sync, because the plugin's declaration is the source of truth. Only the
-`id` behaves differently — it is a key, not a label, so renaming it is a remove
-
-- add.
+`id` behaves differently — it is a key, not a label, so renaming it is a
+remove + add.
 
 Phases are injected by `spm add` / `spm update` **only**. The build-time `sync`
 rewrites the sidecar but never touches the `.xcodeproj`, so a newly declared
@@ -292,8 +298,9 @@ wiring, it stays correct across repackaging.
 
 The plugin returns **data** — it never writes into React Native's generated
 tree. RN owns the merge, so a re-sync reproduces the same `Package.swift`
-byte-for-byte (idempotent). Package and product contributions are **deduped by
-name** across plugins.
+byte-for-byte (idempotent). Across plugins, package contributions are **deduped
+by name** and product contributions by **package and name** — the first
+contribution wins.
 
 ## Lifecycle
 
@@ -317,6 +324,12 @@ function, throws, or returns a malformed contribution aborts the run with a
 message identifying the framework. A framework silently dropping its modules (a
 green build missing native code) is worse than a loud stop.
 
+A plugin's host dependency is also a hard error when another library lists it in
+`swiftpmConfig.dependencies` and that library has no `Package.swift` of its own
+(shipped or scaffolded). React Native builds no target for the host, so there is
+nothing to depend on; remove the entry — the plugin already links its products
+into the app.
+
 ## Status & open items (Preview)
 
 - **Implemented & tested:** discovery (transitive + deny-list), invocation,