Docs: document the --version pin in the SwiftPM scripts doc

The SwiftPM docs still described `--version` as "RN version (default: from
package.json)", which stopped being true once determineVersion started reading
the `artifactsVersionOverride` pin back out of `.spm-injected.json`. Document
the real resolution order and why it matters:

- The `--version` row in "CLI Options" now names all three sources in order —
  the flag, the pin a previous `--version` wrote into the marker, then
  node_modules/react-native/package.json — and says you pass it once.
- A new "Pinning the React Native version" subsection explains the failure the
  pin prevents, which is not self-evident: the resolved version selects which
  artifact slots the project is wired to, so a flagless run falling back to
  package.json re-points the project at different slots while the marker still
  advertises the pinned one. It also states that `deinit` drops the marker and
  with it the pin, so a later `add` resolves package.json again unless you pass
  `--version`.
- The `.spm-injected.json` row in "What to commit" described the marker only as
  a record of the edits `add` made. One appended sentence makes its second role
  visible; the row is otherwise untouched, since sibling PRs edit it too.

No advice to repeat `--version` on every invocation existed in the docs to
correct — that workaround was only ever passed on verbally.

The file is not Prettier-formatted on this branch, so it was deliberately not
reformatted: prose stays wrapped near 80 columns and table rows stay on one
line, matching the surrounding style.

[Internal] - Document the `spm --version` pin and its resolution order

Docs-only change; no code or tests touched. Verified against the branch's own
diff that the marker key is `artifactsVersionOverride` (read by
`readArtifactsVersionOverride` in scripts/spm/generate-spm-xcodeproj.js) and
that `determineVersion` in scripts/setup-apple-spm.js resolves flag → pin →
node_modules/react-native/package.json.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>

Author: chrfalch

packages/react-native/scripts/spm/__doc__/spm-scripts.md

@@ -129,7 +129,7 @@ accepts kebab-case equivalents (e.g. `--skip-codegen`).
 
 | Option | Description |
 |---|---|
-| `--version <ver>` | RN version (default: from package.json) |
+| `--version <ver>` | RN version. Resolved in this order: this flag, then the version a previous `--version` pinned into `.spm-injected.json`, then `node_modules/react-native/package.json`. Pass it once — later runs reuse the pin (see [Pinning the React Native version](#pinning-the-react-native-version)) |
 | `--yes` | Skip the dirty-pbxproj confirmation prompt |
 | `--xcodeproj <path>` | [add] Which `.xcodeproj` to inject into (when several exist) |
 | `--productName <name>` | [add] Which app target to inject into (when several exist) |
@@ -172,6 +172,25 @@ default.
 therefore falls back to the default command unless you pass `--configCommand`
 (or export the env var) again.
 
+### Pinning the React Native version
+
+The resolved version selects **which artifact slots the project is wired to**, so
+it has to stay the same from one run to the next. `--version` is therefore
+recorded in the `.spm-injected.json` marker (as `artifactsVersionOverride`) and
+read back by later runs, which resolve the version in this order:
+
+1. an explicit `--version <ver>`,
+2. the version a previous `--version` pinned into the marker,
+3. `node_modules/react-native/package.json`.
+
+So you pass the flag once, and a later flagless `add`/`update` stays on the slots
+it selected. Without the pin, that flagless run falls back to `package.json` and
+re-points the project at different artifact slots while the marker still
+advertises the pinned version.
+
+`deinit` deletes the marker, and with it the pin — a later `add` resolves
+`node_modules/react-native/package.json` again unless you pass `--version`.
+
 ### Debug/Release flavor is automatic
 
 React Native ships **flavored** prebuilt binaries: the *debug* `React.framework`
@@ -195,7 +214,7 @@ package graph, or require a second build.
 | Path | Commit? | Why |
 |------|---------|-----|
 | `MyApp.xcodeproj/` | Yes | Your project, with SwiftPM injected in place. Holds your signing, capabilities, Build Phases — `add` only adds SwiftPM refs/settings, additively. |
-| `MyApp.xcodeproj/.spm-injected.json` | Yes | Marker recording every edit `add` made, so `deinit` can surgically reverse it and re-runs stay idempotent. Also pins settings later runs and Xcode builds must reuse, such as the [autolinking config command](#the-autolinking-config-command-is-remembered). |
+| `MyApp.xcodeproj/.spm-injected.json` | Yes | Marker recording every edit `add` made, so `deinit` can surgically reverse it and re-runs stay idempotent. Also pins settings later runs and Xcode builds must reuse: the `--version` pin (`artifactsVersionOverride`) that keeps later runs on the same artifact slots, and the [autolinking config command](#the-autolinking-config-command-is-remembered). |
 | `build/generated/` | No | Codegen/autolinking output; regenerated |
 | `build/xcframeworks/` | No | Symlinks to the machine-local artifact cache |
 | `Package.resolved` | No | SwiftPM resolution file; machine-specific |