diff --git a/crates/install-wheel-rs/src/linker.rs b/crates/install-wheel-rs/src/linker.rs
index a89a7e438..5eb48195c 100644
--- a/crates/install-wheel-rs/src/linker.rs
+++ b/crates/install-wheel-rs/src/linker.rs
@@ -221,13 +221,18 @@ fn parse_scripts(
 #[cfg_attr(feature = "clap", derive(clap::ValueEnum))]
 #[cfg_attr(feature = "schemars", derive(schemars::JsonSchema))]
 pub enum LinkMode {
-    /// Clone (i.e., copy-on-write) packages from the wheel into the site packages.
+    /// Clone (i.e., copy-on-write) packages from the wheel into the `site-packages` directory.
     Clone,
-    /// Copy packages from the wheel into the site packages.
+    /// Copy packages from the wheel into the `site-packages` directory.
     Copy,
-    /// Hard link packages from the wheel into the site packages.
+    /// Hard link packages from the wheel into the `site-packages` directory.
     Hardlink,
-    /// Symbolically link packages from the wheel into the site packages
+    /// Symbolically link packages from the wheel into the `site-packages` directory.
+    ///
+    /// WARNING: The use of symlinks is discouraged, as they create tight coupling between the
+    /// cache and the target environment. For example, clearing the cache (`uv cache clear`) will
+    /// break all installed packages by way of removing the underlying source files. Use symlinks
+    /// with caution.
     Symlink,
 }
 
diff --git a/docs/settings.md b/docs/settings.md
index 689a9548e..461c783e9 100644
--- a/docs/settings.md
+++ b/docs/settings.md
@@ -285,10 +285,10 @@ Windows.
 
 **Possible values**:
 
-- `"clone"`: Clone (i.e., copy-on-write) packages from the wheel into the site packages
-- `"copy"`: Copy packages from the wheel into the site packages
-- `"hardlink"`: Hard link packages from the wheel into the site packages
-- `"symlink"`: Symbolically link packages from the wheel into the site packages
+- `"clone"`: Clone (i.e., copy-on-write) packages from the wheel into the `site-packages` directory
+- `"copy"`: Copy packages from the wheel into the `site-packages` directory
+- `"hardlink"`: Hard link packages from the wheel into the `site-packages` directory
+- `"symlink"`: Symbolically link packages from the wheel into the `site-packages` directory
 
 **Example usage**:
 
@@ -1524,10 +1524,10 @@ Windows.
 
 **Possible values**:
 
-- `"clone"`: Clone (i.e., copy-on-write) packages from the wheel into the site packages
-- `"copy"`: Copy packages from the wheel into the site packages
-- `"hardlink"`: Hard link packages from the wheel into the site packages
-- `"symlink"`: Symbolically link packages from the wheel into the site packages
+- `"clone"`: Clone (i.e., copy-on-write) packages from the wheel into the `site-packages` directory
+- `"copy"`: Copy packages from the wheel into the `site-packages` directory
+- `"hardlink"`: Hard link packages from the wheel into the `site-packages` directory
+- `"symlink"`: Symbolically link packages from the wheel into the `site-packages` directory
 
 **Example usage**:
 
diff --git a/uv.schema.json b/uv.schema.json
index 51e80b60e..eb8540c17 100644
--- a/uv.schema.json
+++ b/uv.schema.json
@@ -444,28 +444,28 @@
     "LinkMode": {
       "oneOf": [
         {
-          "description": "Clone (i.e., copy-on-write) packages from the wheel into the site packages.",
+          "description": "Clone (i.e., copy-on-write) packages from the wheel into the `site-packages` directory.",
           "type": "string",
           "enum": [
             "clone"
           ]
         },
         {
-          "description": "Copy packages from the wheel into the site packages.",
+          "description": "Copy packages from the wheel into the `site-packages` directory.",
           "type": "string",
           "enum": [
             "copy"
           ]
         },
         {
-          "description": "Hard link packages from the wheel into the site packages.",
+          "description": "Hard link packages from the wheel into the `site-packages` directory.",
           "type": "string",
           "enum": [
             "hardlink"
           ]
         },
         {
-          "description": "Symbolically link packages from the wheel into the site packages",
+          "description": "Symbolically link packages from the wheel into the `site-packages` directory.\n\nWARNING: The use of symlinks is discouraged, as they create tight coupling between the cache and the target environment. For example, clearing the cache (`uv cache clear`) will break all installed packages by way of removing the underlying source files. Use symlinks with caution.",
           "type": "string",
           "enum": [
             "symlink"