diff --git a/crates/vtracer-cli/src/main.rs b/crates/vtracer-cli/src/main.rs
index a2a218a..8ec31a4 100644
--- a/crates/vtracer-cli/src/main.rs
+++ b/crates/vtracer-cli/src/main.rs
@@ -120,7 +120,7 @@ struct Args {
     #[arg(long)]
     adaptive_t: Option<f64>,
 
-    /// Watershed clustering: hierarchy cut level (0..=255, higher = more regions).
+    /// Watershed clustering: hierarchy cut level (default 128; higher = more regions, uncapped).
     #[arg(long, value_parser = clap::value_parser!(u32))]
     watershed_detail: Option<u32>,
 }
diff --git a/crates/vtracer-py/README.md b/crates/vtracer-py/README.md
index d9bf3eb..40b1ebc 100644
--- a/crates/vtracer-py/README.md
+++ b/crates/vtracer-py/README.md
@@ -88,7 +88,7 @@ properties, plus the presets `Config.bw()`, `Config.poster()`, `Config.photo()`:
 | `adaptive` | `False` | bw: Bradley–Roth adaptive thresholding |
 | `adaptive_window` | `0` | bw adaptive: window px (`0` = auto) |
 | `adaptive_t` | `15.0` | bw adaptive: % below local mean |
-| `watershed_detail` | `128` | watershed: hierarchy cut level 0..=255 |
+| `watershed_detail` | `128` | watershed: hierarchy cut level (higher = more regions, uncapped) |
 
 Each `Config` has `convert_file(input, output)`, `convert_bytes(data, format=None) -> str`,
 and `convert_pixels(rgba, width, height) -> str`.
diff --git a/crates/vtracer-py/vtracer.pyi b/crates/vtracer-py/vtracer.pyi
index ed62d53..b974c30 100644
--- a/crates/vtracer-py/vtracer.pyi
+++ b/crates/vtracer-py/vtracer.pyi
@@ -27,7 +27,7 @@ class Config:
         adaptive: bool = False,                # bw: Bradley–Roth adaptive
         adaptive_window: int = 0,              # bw adaptive: window px (0 = auto)
         adaptive_t: float = 15.0,              # bw adaptive: % below local mean
-        watershed_detail: int = 128,           # watershed: cut level 0..=255
+        watershed_detail: int = 128,           # watershed: cut level (higher = more regions, uncapped)
     ) -> None: ...
 
     @staticmethod
diff --git a/crates/vtracer/src/config.rs b/crates/vtracer/src/config.rs
index cd26f0b..90fa1ad 100644
--- a/crates/vtracer/src/config.rs
+++ b/crates/vtracer/src/config.rs
@@ -131,8 +131,9 @@ pub struct Config {
     pub binary_adaptive_window: u32,
     /// Adaptive sensitivity `t`: percent below the local mean (default 15).
     pub binary_adaptive_t: f64,
-    /// Watershed clustering: where to cut the hierarchy (0..=255). Higher
-    /// keeps more regions; 0 collapses the image to a single region.
+    /// Watershed clustering: where to cut the hierarchy. Higher keeps more
+    /// regions (each +25.5 roughly doubles the region count); 0 collapses the
+    /// image to a single region. Uncapped.
     pub watershed_detail: u32,
 }
 
diff --git a/nodejs/README.md b/nodejs/README.md
index 64f76b8..3bcd75e 100644
--- a/nodejs/README.md
+++ b/nodejs/README.md
@@ -74,7 +74,7 @@ for the seam-free mosaic), `mode` (`"pixel" | "polygon" | "spline"`),
 simplification tolerance in px, try 1–2.5), `pathPrecision`, `palette` (list of
 `#rrggbb`), `maxColors`, `optimize` (`0 | 1 | 2`), `binaryThreshold` /
 `adaptive` / `adaptiveWindow` / `adaptiveT` (binary mode), `watershedDetail`
-(0..=255).
+(default 128; higher = more regions, uncapped).
 
 ## Build from source
 
diff --git a/nodejs/index.d.ts b/nodejs/index.d.ts
index da75884..c16d104 100644
--- a/nodejs/index.d.ts
+++ b/nodejs/index.d.ts
@@ -30,7 +30,7 @@ export interface Options {
   adaptiveWindow?: number;
   /** Adaptive sensitivity: percent below the local mean (default 15). */
   adaptiveT?: number;
-  /** Watershed clustering: hierarchy cut level 0..=255 (higher = more regions, default 128). */
+  /** Watershed clustering: hierarchy cut level (default 128; higher = more regions, uncapped). */
   watershedDetail?: number;
 }
 
diff --git a/nodejs/src/lib.rs b/nodejs/src/lib.rs
index ce80c80..c89b778 100644
--- a/nodejs/src/lib.rs
+++ b/nodejs/src/lib.rs
@@ -40,8 +40,9 @@ struct Options {
     adaptive_window: Option<u32>,
     /// Adaptive sensitivity: percent below the local mean (default 15).
     adaptive_t: Option<f64>,
-    /// Watershed clustering: hierarchy cut level (0..=255).
-    watershed_detail: Option<u8>,
+    /// Watershed clustering: hierarchy cut level (default 128; higher = more
+    /// regions, uncapped).
+    watershed_detail: Option<u32>,
     /// One of "bw" | "poster" | "photo"; applied before the other fields.
     preset: Option<String>,
 }