diff --git a/.gitignore b/.gitignore
index 2fda639..62c412c 100644
--- a/.gitignore
+++ b/.gitignore
@@ -43,5 +43,16 @@ CLAUDE.local.md
 # Agent-instruction sync cache (machine-specific absolute paths; regenerated locally)
 .sync-agents-cache.json
 
+# Worktrees Claude Code creates for parallel sessions and isolated subagents.
+# Only this subdirectory: the rest of `.claude/` is tracked, because the rules
+# under it are part of the repository.
+#
+# They sit inside the working tree rather than beside it. `git clean -xdf` leaves them
+# alone: git's nested-repository guard resolves a gitfile too, so it reports "Skipping
+# repository .claude/worktrees/<slug>" and the contents survive. `git clean -xdff` does
+# not skip them, and wipes a live worktree while `.git/worktrees/<slug>` survives,
+# leaving a registration that `git worktree prune` then has to clear.
+.claude/worktrees/
+
 # Local development path wiring (never committed; breaks CI which has no sibling paths)
 pubspec_overrides.yaml
diff --git a/.worktreeinclude b/.worktreeinclude
new file mode 100644
index 0000000..1c9f3cf
--- /dev/null
+++ b/.worktreeinclude
@@ -0,0 +1,21 @@
+# Gitignored files copied into every worktree Claude Code creates, for `--worktree`,
+# for `EnterWorktree`, and for a subagent with `isolation: worktree`.
+#
+# A worktree is a fresh checkout, so `pubspec_overrides.yaml` is absent from it, and
+# its absence fails silently rather than loudly: the siblings resolve from pub.dev
+# instead of the working trees beside this one, `flutter pub get` succeeds, and the
+# suite then passes against the PUBLISHED packages while the diff under review is of
+# the local ones. An unreleased sibling API is where that bites.
+#
+# `.gitignore` syntax, and only files that match AND are gitignored are copied, so a
+# tracked file can never be duplicated by this list.
+#
+# The paths inside `pubspec_overrides.yaml` have to be ABSOLUTE for this to work.
+# Worktrees live under `.claude/worktrees/<slug>`, so a relative `../magic` resolves
+# to `.claude/worktrees/magic`, which does not exist, and version solving fails on
+# the first path dependency.
+#
+# NOT processed when a WorktreeCreate hook replaces the default git logic; such a
+# hook has to copy these itself.
+
+pubspec_overrides.yaml
diff --git a/CLAUDE.md b/CLAUDE.md
index 50abc74..a820391 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -91,6 +91,7 @@ Every `setUp()` MUST call `MagicApp.reset()` + `Magic.flush()` — it clears the
 | `ValidatesRequests` import | From `lib/src/concerns/`, not `http/` |
 | Web vs mobile DB | Web = in-memory SQLite (needs `web/sqlite3.wasm`), mobile = file-based |
 | `MagicResponse.errors` format | Parses Laravel's `{"errors": {"field": ["msg"]}}` |
+| Relative paths in `pubspec_overrides.yaml` | Use ABSOLUTE ones. `.worktreeinclude` copies that file into worktrees under `.claude/worktrees/<slug>`, where `../magic_starter` resolves to `.claude/worktrees/magic_starter` and version solving fails on the first path dependency |
 
 ## Branching & release