From 2e0cbb1363193410e09c8e626aa1807383be2b75 Mon Sep 17 00:00:00 2001
From: "google-labs-jules[bot]"
 <161369871+google-labs-jules[bot]@users.noreply.github.com>
Date: Fri, 16 Jan 2026 19:03:35 +0000
Subject: [PATCH] docs: improve JSDoc for NodeVersion methods

Clarify strictness of `is()` and fail-closed behavior of comparison methods to improve Developer Experience (DX).
Initialize `.jules/palette.md` for UX/DX learnings.
---
 .changeset/palette-docs-improvement.md |  5 +++++
 .jules/palette.md                      |  5 +++++
 src/types.ts                           | 20 +++++++++++---------
 3 files changed, 21 insertions(+), 9 deletions(-)
 create mode 100644 .changeset/palette-docs-improvement.md
 create mode 100644 .jules/palette.md

diff --git a/.changeset/palette-docs-improvement.md b/.changeset/palette-docs-improvement.md
new file mode 100644
index 00000000..226260fc
--- /dev/null
+++ b/.changeset/palette-docs-improvement.md
@@ -0,0 +1,5 @@
+---
+"node-version": patch
+---
+
+Improve JSDoc for `is`, `isAtLeast` and other comparison methods to clarify strictness and fail-closed behavior.
diff --git a/.jules/palette.md b/.jules/palette.md
new file mode 100644
index 00000000..3bc48009
--- /dev/null
+++ b/.jules/palette.md
@@ -0,0 +1,5 @@
+# Palette's Journal
+
+## 2026-01-01 - strict vs loose comparison confusion
+**Learning:** Developers might assume `is()` behaves like `isAtLeast()` regarding normalization (e.g. stripping 'v' prefix), but it performs strict equality. This is a potential DX pitfall.
+**Action:** Explicitly document the strictness of `is()` and the fail-closed behavior of comparison methods in JSDoc to prevent confusion.
diff --git a/src/types.ts b/src/types.ts
index 4de06674..3065892c 100644
--- a/src/types.ts
+++ b/src/types.ts
@@ -34,40 +34,42 @@ export interface NodeVersion {
     build: string;
     /**
      * Check if the current Node version is at least the specified version.
-     * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version >= target version.
+     * @param version The version to compare against (e.g., '20.0.0' or 'v20.0.0').
+     * @returns {boolean} True if current version >= target version. Returns false for invalid version strings.
      * @example
      * version.isAtLeast('18.0.0'); // true if current is 20.0.0
      */
     isAtLeast(version: string): boolean;
     /**
-     * Check if the current Node version matches the specified version.
+     * Check if the current Node version exactly matches the specified version.
      * @param version The version to compare against (e.g., '20.0.0').
      * @returns {boolean} True if current version === target version.
+     * @note This performs a strict equality check and does NOT strip 'v' prefixes.
      * @example
      * version.is('20.0.0'); // true if current is 20.0.0
+     * version.is('v20.0.0'); // false if current is 20.0.0
      */
     is(version: string): boolean;
     /**
      * Check if the current Node version is strictly greater than the specified version.
-     * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version > target version.
+     * @param version The version to compare against (e.g., '20.0.0' or 'v20.0.0').
+     * @returns {boolean} True if current version > target version. Returns false for invalid version strings.
      * @example
      * version.isAbove('18.0.0'); // true if current is 20.0.0
      */
     isAbove(version: string): boolean;
     /**
      * Check if the current Node version is strictly less than the specified version.
-     * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version < target version.
+     * @param version The version to compare against (e.g., '20.0.0' or 'v20.0.0').
+     * @returns {boolean} True if current version < target version. Returns false for invalid version strings.
      * @example
      * version.isBelow('22.0.0'); // true if current is 20.0.0
      */
     isBelow(version: string): boolean;
     /**
      * Check if the current Node version is at most the specified version.
-     * @param version The version to compare against (e.g., '20.0.0').
-     * @returns {boolean} True if current version <= target version.
+     * @param version The version to compare against (e.g., '20.0.0' or 'v20.0.0').
+     * @returns {boolean} True if current version <= target version. Returns false for invalid version strings.
      * @example
      * version.isAtMost('22.0.0'); // true if current is 20.0.0
      */