diff --git a/.github/workflows/build-samples-todoapp-uno.yml b/.github/workflows/build-samples-todoapp-uno.yml
index e8b1f1e..06eda0e 100644
--- a/.github/workflows/build-samples-todoapp-uno.yml
+++ b/.github/workflows/build-samples-todoapp-uno.yml
@@ -57,18 +57,50 @@ jobs:
 
   ios-maccatalyst:
     # iOS and Mac Catalyst builds both require Xcode, which is only available on macOS runners.
-    runs-on: macos-latest
+    # Pinned to macos-15 (rather than macos-latest) while that label migrates to macos-26
+    # (see https://github.com/actions/runner-images/issues/14167, rollout through
+    # 2026-07-15): macos-latest can currently land on either image at random, each with a
+    # different default Xcode (16.4 vs 26.4.1), and macos-15's *default* Xcode (16.4) doesn't
+    # match what any currently-published net10.0 iOS SDK pack requires (see WorkloadSetVersion
+    # below) - so this job also explicitly selects a non-default Xcode already installed on
+    # the image (see the "Select Xcode" step) to match. See
+    # https://github.com/CommunityToolkit/Datasync/issues/529 and #559. Revisit this whole job
+    # once we deliberately upgrade to a newer, Xcode-26-compatible workload set.
+    runs-on: macos-15
+    env:
+      # `dotnet workload install ios maccatalyst` alone always resolves the newest published
+      # Microsoft.iOS.Sdk.net10.0_* pack. As of workload set 10.0.108, that's 26.5.10284,
+      # which requires Xcode 26.5 - not installed on macos-15 (even as a non-default Xcode).
+      # Pinning to 10.0.107 (the last set before the iOS/MacCatalyst/macOS/tvOS manifest moved
+      # to the 26.4/26.5 pack line; see workload-set history for package id
+      # Microsoft.NET.Workloads.10.0.100 on nuget.org) resolves 26.2.10233 instead, which
+      # requires Xcode 26.3 - installed (non-default) on macos-15 as of image 20260629.0276.1
+      # (see the "Select Xcode" step below). `--version` pins only this job's
+      # `dotnet workload install` invocation and the `restore`/`build` steps that follow it in
+      # the same runner - it's intentionally not a repo-wide global.json pin, which would
+      # force every `dotnet` invocation in the whole repo (including samples with no workload
+      # dependency at all) to require this exact workload version to already be installed,
+      # breaking them on a fresh runner.
+      WorkloadSetVersion: '10.0.107'
+      RequiredXcodeVersion: '26.3'
     steps:
       - name: Checkout Repository
         uses: actions/checkout@v7
 
+      - name: Select Xcode ${{ env.RequiredXcodeVersion }}
+        # macos-15 defaults to Xcode 16.4, which doesn't satisfy what the pinned iOS/Mac
+        # Catalyst workload (see WorkloadSetVersion above) requires. Xcode 26.3 is already
+        # installed on the image, just not selected by default - so switch to it explicitly
+        # rather than installing anything extra.
+        run: sudo xcode-select -s /Applications/Xcode_${{ env.RequiredXcodeVersion }}.app
+
       - name: Setup .NET
         uses: actions/setup-dotnet@v5
         with:
           dotnet-version: ${{ env.DOTNET_VERSION }}
 
       - name: Install iOS and Mac Catalyst workloads
-        run: dotnet workload install ios maccatalyst
+        run: dotnet workload install ios maccatalyst --version ${{ env.WorkloadSetVersion }}
 
       - name: Restore Uno project (iOS TFM only)
         run: dotnet restore ${{ env.UnoProjectFile }} -p:TargetFramework=${{ env.iOSTargetFramework }}
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..84ba8c2
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,39 @@
+# Agent Notes
+
+Guidance for coding agents working in this repository.
+
+## Testing samples
+
+The `samples/` directory contains many platform-specific projects (Blazor WASM,
+MAUI, Uno, Avalonia, WPF, WinUI3, MVC, etc.). Most of these require platform
+SDKs, mobile workloads, or OS-specific tooling (e.g. Windows, iOS/Android
+workloads, WinUI3) that are **not** guaranteed to be installed in an agent's
+local environment. Do not assume `dotnet build`/`dotnet workload` for these
+projects will succeed locally, and do not spend time trying to install missing
+workloads just to validate a samples change.
+
+The proper way to validate a change to anything under `samples/` is:
+
+1. Push your branch to your local fork (`origin`), not upstream.
+2. Trigger the `Build Samples` GitHub Actions workflow via `workflow_dispatch`
+   against that branch, e.g.:
+
+   ```sh
+   git push -u origin <branch>
+   gh workflow run "Build Samples" --repo <your-fork> --ref <branch>
+   ```
+
+3. Poll the run (`gh run list` / `gh run view <run-id>`) until it completes,
+   and review the per-job results — in particular the job(s) relevant to the
+   sample(s) you changed, plus the `all-samples-built` aggregation job.
+
+This builds every sample on its correct runner/OS/toolchain in CI, which is
+far more reliable than trying to reproduce that locally.
+
+**Timing:** a full `Build Samples` run across all sample projects takes
+approximately **6 minutes** end-to-end. Individual jobs (e.g.
+`todoapp-blazor-wasm`) typically finish in well under a minute, but slower
+jobs (Windows, Uno iOS/maccatalyst) can take several minutes each, and they
+run in parallel. Plan polling/wait times accordingly — don't assume the run
+is stuck if it's still going after a minute or two; do check back in if it
+hasn't completed after ~6-8 minutes.