diff --git a/.gitmodules b/.gitmodules
index 0825f6e02..749ce2556 100644
--- a/.gitmodules
+++ b/.gitmodules
@@ -5,7 +5,15 @@
 	# skip it so a fresh OSS clone needs no credentials (#1443). Maintainers
 	# opt in — see CLAUDE.md → "Development Skills".
 	update = none
-	fetchRecurseSubmodules = true
+	# `on-demand` (not `true`): `true` unconditionally tries to recurse-fetch
+	# this submodule on every `git fetch`/`git pull`, even when it was never
+	# checked out — which fails with "Could not access submodule '.claude'"
+	# for anyone (or any self-hosting agent) without trinity-dev credentials.
+	# `on-demand` still auto-updates it for maintainers who HAVE it checked
+	# out (a submodule-bump commit triggers the fetch), matching the
+	# documented "handles git pull automatically" behavior in CLAUDE.md —
+	# it just stops trying for everyone who doesn't have it initialized.
+	fetchRecurseSubmodules = on-demand
 [submodule "src/backend/enterprise"]
 	path = src/backend/enterprise
 	url = git@github.com:Abilityai/trinity-enterprise.git
diff --git a/CLAUDE.md b/CLAUDE.md
index 3b740ff3a..6b2e53cfc 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -77,7 +77,7 @@ git submodule update --init .claude           # now actually clones (needs trini
 git config submodule.recurse true             # auto-syncs .claude when switching branches
 ```
 
-The config line must come **first** — with the `update = none` default, a plain `--init` is skipped, and **any** init path (plain `--init`, `--init --checkout`, `clone --recurse-submodules`) copies `none` into your local config, so *future* updates keep skipping until the override is set. Without `submodule.recurse true`, switching branches will leave `.claude` stale and skills will disappear. The `fetchRecurseSubmodules = true` in `.gitmodules` handles `git pull` automatically, but branch switching requires the local config above. (Clones initialized before #1443 already carry the `update = checkout` local override — no action needed.)
+The config line must come **first** — with the `update = none` default, a plain `--init` is skipped, and **any** init path (plain `--init`, `--init --checkout`, `clone --recurse-submodules`) copies `none` into your local config, so *future* updates keep skipping until the override is set. Without `submodule.recurse true`, switching branches will leave `.claude` stale and skills will disappear. The `fetchRecurseSubmodules = on-demand` in `.gitmodules` handles `git pull` automatically once `.claude` is checked out (a submodule-bump commit triggers the fetch), but branch switching requires the local config above. (Clones initialized before #1443 already carry the `update = checkout` local override — no action needed. `on-demand`, not `true`: `true` unconditionally tries to recurse-fetch `.claude` even when it was never checked out, which fails with "Could not access submodule '.claude'" for anyone — human or self-hosting agent — without `trinity-dev` credentials.)
 
 ### External contributors