diff --git a/.gitignore b/.gitignore
index 6b81c7e..363c897 100644
--- a/.gitignore
+++ b/.gitignore
@@ -2,4 +2,5 @@
 artifacts/
 bin/
 obj/
+.dotnet-cli/
 *.user
\ No newline at end of file
diff --git a/AGENTS.md b/AGENTS.md
index c79d4ca..0ed7395 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -21,6 +21,12 @@ The wrappers cd to the repo root (the test runner must run from the parent
 directory of the test project), export `DOTNET_CLI_HOME`, and invoke
 `mise exec -- dotnet ...`. Do not call bare `dotnet`.
 
+If the first-time-use setup fails with `The file ...
+'.dotnet-cli/.dotnet' already exists` or `Operation not permitted` (some
+agent/sandbox shells block `$HOME/.dotnet-cli`), point the wrapper at a
+repo-local home: `DOTNET_CLI_HOME="$PWD/.dotnet-cli" scripts/dotnet.sh ...`
+(add `.dotnet-cli/` to `.gitignore`).
+
 ## Yaks (task management with yx)
 
 Tasks are managed with the `yx` CLI; yaks live in git (event store), snapshot