diff --git a/.github/workflows/deploy-pwa.yml b/.github/workflows/deploy-pwa.yml
index 50764cca..a9b76a99 100644
--- a/.github/workflows/deploy-pwa.yml
+++ b/.github/workflows/deploy-pwa.yml
@@ -15,6 +15,11 @@ on:
         description: Exact oneworks-ai/app commit SHA to build. Overrides source_ref.
         required: false
         type: string
+      dry_run:
+        description: Build and validate without updating the gh-pages branch.
+        required: false
+        default: false
+        type: boolean
 
 permissions:
   contents: write
@@ -51,6 +56,9 @@ jobs:
           fetch-depth: 1
           path: app
 
+      - name: Checkout Avatar SDK source
+        run: git -C app submodule update --init --depth 1 -- assets/avatar
+
       - name: Set up pnpm
         uses: pnpm/action-setup@v4
         with:
@@ -74,12 +82,14 @@ jobs:
           __ONEWORKS_PROJECT_CLIENT_MODE__: standalone
 
       - name: Checkout pages branch
+        if: ${{ github.event_name != 'workflow_dispatch' || !inputs.dry_run }}
         uses: actions/checkout@v4
         with:
           ref: gh-pages
           path: pages
 
       - name: Publish gh-pages branch
+        if: ${{ github.event_name != 'workflow_dispatch' || !inputs.dry_run }}
         env:
           SOURCE_REF: ${{ steps.source.outputs.ref }}
         run: |
diff --git a/AGENTS.md b/AGENTS.md
index d8495308..a6bf4979 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -9,6 +9,7 @@
 
 ## Deployment
 
-- `deploy-pwa.yml` checks out `oneworks-ai/app`, builds `apps/client` with `__ONEWORKS_PROJECT_CLIENT_BASE__=/pwa/`, and deploys the generated static files to GitHub Pages.
+- `deploy-pwa.yml` checks out `oneworks-ai/app`, initializes the required `assets/avatar` SDK submodule before workspace install, builds `apps/client` with `__ONEWORKS_PROJECT_CLIENT_BASE__=/pwa/`, and deploys the generated static files to GitHub Pages.
+- For cross-repository validation before a source PR merges, dispatch the workflow with the exact `source_sha` and `dry_run=true`; this exercises checkout, submodule initialization, install, and production build without updating `gh-pages`.
 - Keep `__ONEWORKS_PROJECT_CLIENT_HOMEPAGE_PREVIEW__=1`; the homepage iframe depends on the preview runtime being present in the official PWA build.
 - Keep `404.html` as a copy of `index.html` so GitHub Pages can serve React Router routes such as `/pwa/session/...` and `/pwa/rooms/...`.