diff --git a/docs/projects.md b/docs/projects.md
index a8dc605..bfe2473 100644
--- a/docs/projects.md
+++ b/docs/projects.md
@@ -30,6 +30,15 @@ default_engine = "codex"       # optional, per-project override
 worktree_base = "master"       # optional, base for new branches
 ```
 
+Note on `worktrees_dir`:
+
+- The default `.worktrees` lives inside the repo root. You'll see it as an
+  untracked directory (with nested git worktrees) unless you ignore it.
+- Options:
+  - add `.worktrees/` to your repo `.gitignore`, or
+  - set `worktrees_dir` to a path outside the repo (e.g. `~/.takopi/worktrees/<alias>`).
+  - add it to `.git/info/exclude` if you prefer a local-only ignore.
+
 Validation rules:
 
 - `projects` is optional.
diff --git a/readme.md b/readme.md
index 4069112..2ae466f 100644
--- a/readme.md
+++ b/readme.md
@@ -100,6 +100,10 @@ default_engine = "codex"
 worktree_base = "master"
 ```
 
+note: the default `worktrees_dir` lives inside the repo, so `.worktrees/` will
+show up as untracked unless you ignore it (add to `.gitignore` or
+`.git/info/exclude`), or set `worktrees_dir` to a path outside the repo.
+
 ## usage
 
 start takopi in the repo you want to work on: