diff --git a/bitcoin-starter/.gitignore b/bitcoin-starter/.gitignore
index ede6f2b..02bf150 100644
--- a/bitcoin-starter/.gitignore
+++ b/bitcoin-starter/.gitignore
@@ -13,5 +13,7 @@
 # rust
 target/
 
-# icp-cli
+# icp-cli local cache (safe to delete, rebuilt on next build/deploy)
 .icp/cache/
+# Do NOT ignore .icp/data/ — it stores mainnet canister ID mappings.
+# See: https://github.com/dfinity/icp-cli/blob/main/docs/concepts/project-model.md#whats-safe-to-delete
diff --git a/bitcoin-starter/.icp/data/.gitkeep b/bitcoin-starter/.icp/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/hello-world/.gitignore b/hello-world/.gitignore
index a048b70..f8d9d7a 100644
--- a/hello-world/.gitignore
+++ b/hello-world/.gitignore
@@ -10,5 +10,7 @@
 # environment variables
 .env
 
-# icp-cli
+# icp-cli local cache (safe to delete, rebuilt on next build/deploy)
 .icp/cache/
+# Do NOT ignore .icp/data/ — it stores mainnet canister ID mappings.
+# See: https://github.com/dfinity/icp-cli/blob/main/docs/concepts/project-model.md#whats-safe-to-delete
diff --git a/hello-world/.icp/data/.gitkeep b/hello-world/.icp/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/motoko/.gitignore b/motoko/.gitignore
index a3057d9..611b208 100644
--- a/motoko/.gitignore
+++ b/motoko/.gitignore
@@ -14,5 +14,7 @@
 .mops
 *.wasm
 
-# icp-cli
+# icp-cli local cache (safe to delete, rebuilt on next build/deploy)
 .icp/cache/
+# Do NOT ignore .icp/data/ — it stores mainnet canister ID mappings.
+# See: https://github.com/dfinity/icp-cli/blob/main/docs/concepts/project-model.md#whats-safe-to-delete
diff --git a/motoko/.icp/data/.gitkeep b/motoko/.icp/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/proxy/.gitignore b/proxy/.gitignore
new file mode 100644
index 0000000..ab65e15
--- /dev/null
+++ b/proxy/.gitignore
@@ -0,0 +1,4 @@
+# icp-cli local cache (safe to delete, rebuilt on next build/deploy)
+.icp/cache/
+# Do NOT ignore .icp/data/ — it stores mainnet canister ID mappings.
+# See: https://github.com/dfinity/icp-cli/blob/main/docs/concepts/project-model.md#whats-safe-to-delete
diff --git a/proxy/.icp/data/.gitkeep b/proxy/.icp/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/rust/.gitignore b/rust/.gitignore
index e47f6fa..02bf150 100644
--- a/rust/.gitignore
+++ b/rust/.gitignore
@@ -13,5 +13,7 @@
 # rust
 target/
 
-# ingore the icp-cli cache
+# icp-cli local cache (safe to delete, rebuilt on next build/deploy)
 .icp/cache/
+# Do NOT ignore .icp/data/ — it stores mainnet canister ID mappings.
+# See: https://github.com/dfinity/icp-cli/blob/main/docs/concepts/project-model.md#whats-safe-to-delete
diff --git a/rust/.icp/data/.gitkeep b/rust/.icp/data/.gitkeep
new file mode 100644
index 0000000..e69de29
diff --git a/static-website/.gitignore b/static-website/.gitignore
index a547bf3..1d639f0 100644
--- a/static-website/.gitignore
+++ b/static-website/.gitignore
@@ -22,3 +22,8 @@ dist-ssr
 *.njsproj
 *.sln
 *.sw?
+
+# icp-cli local cache (safe to delete, rebuilt on next build/deploy)
+.icp/cache/
+# Do NOT ignore .icp/data/ — it stores mainnet canister ID mappings.
+# See: https://github.com/dfinity/icp-cli/blob/main/docs/concepts/project-model.md#whats-safe-to-delete
diff --git a/static-website/.icp/data/.gitkeep b/static-website/.icp/data/.gitkeep
new file mode 100644
index 0000000..e69de29