diff --git a/.gitmodules b/.gitmodules
index b4a771b..6745805 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -8,3 +8,6 @@
 [submodule "third-party/speex"]
 	path = third-party/speex
 	url = https://github.com/xiph/speex/
+[submodule "third-party/wireguard-android"]
+	path = third-party/wireguard-android
+	url = https://git.zx2c4.com/wireguard-android
diff --git a/examples/crash_reporter/backend/scripts/gitea/gitea_mirror_lib.sh b/examples/crash_reporter/backend/scripts/gitea/gitea_mirror_lib.sh
index b16519d..faa0699 100755
--- a/examples/crash_reporter/backend/scripts/gitea/gitea_mirror_lib.sh
+++ b/examples/crash_reporter/backend/scripts/gitea/gitea_mirror_lib.sh
@@ -47,36 +47,44 @@ gitea_resolve_push_token() {
     printf '%s' "$GITEA_ADMIN_TOKEN"
     return 0
   fi
+  _admin="$(gitea_pick_owner_username)"
+  [ -n "$_admin" ] || return 1
   _token=""
   _token="$(gitea_cli "admin" "user" "generate-access-token" \
-    "--username" "$GITEA_OWNER" \
+    "--username" "$_admin" \
     "--token-name" "mirror-$$" \
     "--scopes" "all" \
     "--raw" 2>/dev/null)" && [ -n "$_token" ] && printf '%s' "$_token" && return 0
-  _admin="$(gitea_pick_owner_username)"
-  if [ -n "$_admin" ] && [ "$_admin" != "$GITEA_OWNER" ]; then
-    _token="$(gitea_cli "admin" "user" "generate-access-token" \
-      "--username" "$_admin" \
-      "--token-name" "mirror-$$" \
-      "--scopes" "all" \
-      "--raw" 2>/dev/null)" && [ -n "$_token" ] && printf '%s' "$_token" && return 0
-  fi
   return 1
 }
 
 gitea_owner_uid_for() {
+  gitea_entity_uid_for "$1"
+}
+
+# UID for migrate/API owner — user or organization (not the same as /users/{org}).
+gitea_entity_uid_for() {
   _owner="$1"
   command -v curl >/dev/null 2>&1 || return 1
   _token="${GITEA_ADMIN_TOKEN:-}"
   [ -n "$_token" ] || _token="$(gitea_resolve_push_token)" || return 1
   _api="$(gitea_api_base)"
-  _uid="$(curl -sS "$_api/users/$_owner" \
-    -H "Authorization: token $_token" \
-    | awk -F'"' '/"id"/ { print $4; exit }')"
+  _json=""
+  if curl -sS -o /dev/null -w '%{http_code}' "$_api/orgs/$_owner" \
+    -H "Authorization: token $_token" | grep -q '^200'; then
+    _json="$(curl -sS "$_api/orgs/$_owner" -H "Authorization: token $_token")"
+  else
+    _json="$(curl -sS "$_api/users/$_owner" -H "Authorization: token $_token")"
+  fi
+  _uid="$(printf '%s' "$_json" | awk -F'"' '/"id":/ { print $4; exit }')"
   [ -n "$_uid" ] || return 1
   printf '%s' "$_uid"
 }
 
+gitea_owner_is_org() {
+  gitea_org_exists "$1" 2>/dev/null
+}
+
 gitea_create_repo_cli() {
   _owner="$1"
   _repo="$2"
@@ -104,7 +112,7 @@ gitea_migrate_mirror_api() {
   command -v curl >/dev/null 2>&1 || return 1
   _token="${GITEA_ADMIN_TOKEN:-}"
   [ -n "$_token" ] || _token="$(gitea_resolve_push_token)" || return 1
-  _uid="$(gitea_owner_uid_for "$_owner")" || return 1
+  _uid="$(gitea_entity_uid_for "$_owner")" || return 1
 
   _api="$(gitea_api_base)"
   _payload=$(cat <<EOF
@@ -204,7 +212,17 @@ gitea_list_repos_api() {
   fi
   curl -sS "$_list_url" \
     -H "Authorization: token $_token" \
-    | awk -F'"' '/"name":/ { print $4 }'
+    | awk -F'"' '
+      /"name":/ && !/"owner":/ && !/"full_name":/ {
+        for (i = 1; i <= NF; i++) {
+          if ($i == "\"name\":" && $(i+1) ~ /^"/) {
+            gsub(/^"/, "", $(i+1)); gsub(/",?$/, "", $(i+1))
+            if ($(i+1) != "" && $(i+1) != "null") print $(i+1)
+            break
+          }
+        }
+      }
+    '
 }
 
 gitea_repo_get_api() {
@@ -309,6 +327,13 @@ gitea_mirror_pull_repo() {
     printf '[gitea-mirror] migrate rejected for %s/%s but repo missing — trying git push\n' \
       "$_owner" "$_repo" >&2
   fi
+  if gitea_owner_is_org "$_owner"; then
+    printf '[gitea-mirror] API migrate failed for org %s/%s — git push fallback disabled (orgs cannot push-to-create)\n' \
+      "$_owner" "$_repo" >&2
+    printf '[gitea-mirror] Set GITEA_ADMIN_TOKEN or run as root; check [migrations] in app.ini\n' >&2
+    [ -n "$_local_work" ] && gitea_rm_path "$_local_work"
+    return 1
+  fi
   mkdir -p "$_work_dir"
   gitea_mirror_push_git "$_owner" "$_repo" "$_clone_url" "$_work_dir" || _rc=1
   gitea_rm_path "$_work_dir/${_repo}.mirror.git"
diff --git a/examples/crash_reporter/backend/scripts/gitea/gitea_polish_project.sh b/examples/crash_reporter/backend/scripts/gitea/gitea_polish_project.sh
index 71503de..8086c1b 100755
--- a/examples/crash_reporter/backend/scripts/gitea/gitea_polish_project.sh
+++ b/examples/crash_reporter/backend/scripts/gitea/gitea_polish_project.sh
@@ -111,7 +111,7 @@ mirror_submodules_if_missing() {
   fi
 
   _need=0
-  for _sub in libvpx opus speex; do
+  for _sub in libvpx opus speex wireguard-android; do
     gitea_repo_exists_api "$GITEA_ORG" "$_sub" && continue
     _need=1
     break
diff --git a/examples/crash_reporter/backend/scripts/gitea/gitea_submodule_lib.sh b/examples/crash_reporter/backend/scripts/gitea/gitea_submodule_lib.sh
index 41a9ab5..a2e73a5 100644
--- a/examples/crash_reporter/backend/scripts/gitea/gitea_submodule_lib.sh
+++ b/examples/crash_reporter/backend/scripts/gitea/gitea_submodule_lib.sh
@@ -170,10 +170,9 @@ gitea_submodule_collect_entries() {
     gitea_submodule_discover_from_gitmodules "$_repo_dir/.gitmodules" "$_repo_dir" "$_ref" >> "$_work" 2>/dev/null || true
   fi
 
+  # Use defaults only when .gitmodules produced nothing (never merge extras on top).
   if [ ! -s "$_work" ] && [ -n "$_defaults" ] && [ -r "$_defaults" ]; then
     gitea_submodule_load_defaults "$_defaults" "$_repo_dir" "$_ref" >> "$_work" 2>/dev/null || true
-  elif [ -n "$_defaults" ] && [ -r "$_defaults" ]; then
-    gitea_submodule_load_defaults "$_defaults" "$_repo_dir" "$_ref" >> "$_work" 2>/dev/null || true
   fi
 
   awk -F'|' '!seen[$1]++' "$_work"
diff --git a/examples/crash_reporter/backend/scripts/gitea/submodules.defaults.conf b/examples/crash_reporter/backend/scripts/gitea/submodules.defaults.conf
index f4edf04..a1cefbe 100644
--- a/examples/crash_reporter/backend/scripts/gitea/submodules.defaults.conf
+++ b/examples/crash_reporter/backend/scripts/gitea/submodules.defaults.conf
@@ -2,6 +2,7 @@
 # Format: repo_name|upstream_clone_url|submodule_path[|branch]
 # Lines starting with # are ignored. Add local git:// entries at the bottom.
 
+# Fallback only when .gitmodules is missing on BE. Canonical list: .gitmodules in repo.
 libvpx|https://chromium.googlesource.com/webm/libvpx|third-party/libvpx|main
 opus|https://github.com/xiph/opus|third-party/opus
 speex|https://github.com/xiph/speex/|third-party/speex
diff --git a/ndk/README.md b/ndk/README.md
index 9ffd3aa..6af8bfa 100644
--- a/ndk/README.md
+++ b/ndk/README.md
@@ -19,6 +19,7 @@ The app loads `libandroidcast_codecs.so` for availability probes and future soft
    git submodule update --init third-party/libvpx
    git submodule update --init third-party/opus
    git submodule update --init third-party/speex
+   git submodule update --init third-party/wireguard-android
    ```
 
 2. Build static libs per ABI (NDK auto-detected via `scripts/android-ndk.sh`):
diff --git a/scripts/init-wireguard-submodule.sh b/scripts/init-wireguard-submodule.sh
index bf76e3b..c33dbf5 100755
--- a/scripts/init-wireguard-submodule.sh
+++ b/scripts/init-wireguard-submodule.sh
@@ -1,12 +1,13 @@
 #!/usr/bin/env bash
-# Initialize wireguard-android submodule for embedded tunnel (optional but recommended for production WG).
+# Initialize wireguard-android submodule (third-party/wireguard-android in .gitmodules).
 set -euo pipefail
 ROOT="$(cd "$(dirname "$0")/.." && pwd)"
 cd "$ROOT"
-if [[ ! -d third-party/wireguard-android/.git ]]; then
-  git submodule add https://git.zx2c4.com/wireguard-android third-party/wireguard-android || \
-    git clone --depth 1 https://git.zx2c4.com/wireguard-android third-party/wireguard-android
+if ! grep -q 'third-party/wireguard-android' .gitmodules 2>/dev/null; then
+  echo "error: .gitmodules missing third-party/wireguard-android — use repo .gitmodules from git" >&2
+  exit 1
 fi
+git submodule sync third-party/wireguard-android
 git submodule update --init --recursive third-party/wireguard-android
 echo "wireguard-android ready under third-party/wireguard-android"
 echo "Gradle includes :tunnel when third-party/wireguard-android/tunnel exists."
diff --git a/third-party/README.md b/third-party/README.md
index d544821..efe2202 100644
--- a/third-party/README.md
+++ b/third-party/README.md
@@ -1,15 +1,16 @@
 # Third-party vendored dependencies
 
-## wireguard-android (optional Gradle module)
+## wireguard-android (git submodule)
 
-Remote access WireGuard v1 can use the in-app `RemoteAccessVpnService` fallback (TUN only).
-For full userspace WireGuard crypto/data plane, initialize the upstream tunnel library:
+Listed in `.gitmodules` like libvpx/opus/speex. Initialize after clone:
 
 ```bash
+git submodule update --init third-party/wireguard-android
+# or:
 bash scripts/init-wireguard-submodule.sh
 ```
 
-Then build with the `:tunnel` module (auto-included when present):
+Build with the `:tunnel` module (auto-included when present):
 
 - Submodule path: `third-party/wireguard-android/`
 - Gradle module: `third-party/wireguard-android/tunnel`