@yawlabs/tailscale-mcp 0.20.1 → 0.21.0

package/dist/index.js

@@ -3109,9 +3109,28 @@ var require_utils = __commonJS({
     "use strict";
     var isUUID = RegExp.prototype.test.bind(/^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu);
     var isIPv42 = RegExp.prototype.test.bind(/^(?:(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)\.){3}(?:25[0-5]|2[0-4]\d|1\d{2}|[1-9]\d|\d)$/u);
+    var isPort = RegExp.prototype.test.bind(/^\d*$/u);
     var isHexPair = RegExp.prototype.test.bind(/^[\da-f]{2}$/iu);
     var isUnreserved = RegExp.prototype.test.bind(/^[\da-z\-._~]$/iu);
-    var isPathCharacter = RegExp.prototype.test.bind(/^[\da-z\-._~!$&'()*+,;=:@/]$/iu);
+    var isPathCharacter = RegExp.prototype.test.bind(/^[A-Za-z0-9\-._~!$&'()*+,;=:@/]$/u);
+    var isQueryFragmentCharacter = RegExp.prototype.test.bind(/^[A-Za-z0-9\-._~!$&'()*+,;=:@/?]$/u);
+    var isUserinfoCharacter = RegExp.prototype.test.bind(/^[A-Za-z0-9\-._~!$&'()*+,;=:]$/u);
+    var BYTE_HEX = new Array(256);
+    {
+      const HEX_DIGITS = "0123456789ABCDEF";
+      for (let i = 0; i < 256; i++) {
+        BYTE_HEX[i] = "%" + HEX_DIGITS[i >> 4] + HEX_DIGITS[i & 15];
+      }
+    }
+    function percentEncodeNonAscii(cp) {
+      if (cp < 2048) {
+        return BYTE_HEX[192 | cp >> 6] + BYTE_HEX[128 | cp & 63];
+      }
+      if (cp < 65536) {
+        return BYTE_HEX[224 | cp >> 12] + BYTE_HEX[128 | cp >> 6 & 63] + BYTE_HEX[128 | cp & 63];
+      }
+      return BYTE_HEX[240 | cp >> 18] + BYTE_HEX[128 | cp >> 12 & 63] + BYTE_HEX[128 | cp >> 6 & 63] + BYTE_HEX[128 | cp & 63];
+    }
     function stringArrayToHexStripped(input) {
       let acc = "";
       let code = 0;
@@ -3136,91 +3155,105 @@ var require_utils = __commonJS({
       }
       return acc;
     }
+    var isHextet = RegExp.prototype.test.bind(/^[\dA-Fa-f]{1,4}$/);
+    var isIPvFuture = RegExp.prototype.test.bind(/^[vV][\dA-Fa-f]+\.[A-Za-z\d\-._~!$&'()*+,;=:]+$/);
+    var isZoneCharacter = RegExp.prototype.test.bind(/^[A-Za-z\d\-._~]$/);
     var nonSimpleDomain = RegExp.prototype.test.bind(/[^!"$&'()*+,\-.;=_`a-z{}~]/u);
-    function consumeIsZone(buffer) {
-      buffer.length = 0;
-      return true;
-    }
-    function consumeHextets(buffer, address, output) {
-      if (buffer.length) {
-        const hex3 = stringArrayToHexStripped(buffer);
-        if (hex3 !== "") {
-          address.push(hex3);
-        } else {
-          output.error = true;
-          return false;
+    function isZoneIdentifier(zone) {
+      if (zone.length === 0) return false;
+      for (let i = 0; i < zone.length; i++) {
+        if (isZoneCharacter(zone[i])) continue;
+        if (zone[i] === "%" && i + 2 < zone.length && isHexPair(zone.slice(i + 1, i + 3))) {
+          i += 2;
+          continue;
         }
-        buffer.length = 0;
+        return false;
       }
       return true;
     }
-    function getIPV6(input) {
-      let tokenCount = 0;
-      const output = { error: false, address: "", zone: "" };
-      const address = [];
-      const buffer = [];
-      let endipv6Encountered = false;
-      let endIpv6 = false;
-      let consume = consumeHextets;
-      for (let i = 0; i < input.length; i++) {
-        const cursor = input[i];
-        if (cursor === "[" || cursor === "]") {
-          continue;
-        }
-        if (cursor === ":") {
-          if (endipv6Encountered === true) {
-            endIpv6 = true;
-          }
-          if (!consume(buffer, address, output)) {
-            break;
+    function compressIPv6ZeroRun(hextets) {
+      let bestStart = -1;
+      let bestLength = 0;
+      let runStart = -1;
+      let runLength = 0;
+      for (let i = 0; i < hextets.length; i++) {
+        if (hextets[i] === "0") {
+          if (runStart === -1) runStart = i;
+          runLength++;
+          if (runLength > bestLength) {
+            bestLength = runLength;
+            bestStart = runStart;
           }
-          if (++tokenCount > 7) {
-            output.error = true;
-            break;
-          }
-          if (i > 0 && input[i - 1] === ":") {
-            endipv6Encountered = true;
-          }
-          address.push(":");
-          continue;
-        } else if (cursor === "%") {
-          if (!consume(buffer, address, output)) {
-            break;
-          }
-          consume = consumeIsZone;
         } else {
-          buffer.push(cursor);
+          runStart = -1;
+          runLength = 0;
+        }
+      }
+      if (bestLength < 2) return hextets.join(":");
+      const head = hextets.slice(0, bestStart).join(":");
+      const tail = hextets.slice(bestStart + bestLength).join(":");
+      return head + "::" + tail;
+    }
+    function normalizeIPv6Address(input) {
+      const compression = input.indexOf("::");
+      if (compression !== -1 && input.indexOf("::", compression + 1) !== -1) return void 0;
+      const left = compression === -1 ? input.split(":") : input.slice(0, compression).split(":");
+      const right = compression === -1 ? [] : input.slice(compression + 2).split(":");
+      if (compression !== -1) {
+        if (left.length === 1 && left[0] === "") left.length = 0;
+        if (right.length === 1 && right[0] === "") right.length = 0;
+      }
+      const parts = left.concat(right);
+      let hextetCount = 0;
+      for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        if (part === "") return void 0;
+        if (part.indexOf(".") !== -1) {
+          if (i !== parts.length - 1 || compression !== -1 && right.length === 0 || !isIPv42(part)) return void 0;
+          hextetCount += 2;
           continue;
         }
+        if (!isHextet(part)) return void 0;
+        parts[i] = parseInt(part, 16).toString(16);
+        hextetCount++;
       }
-      if (buffer.length) {
-        if (consume === consumeIsZone) {
-          output.zone = buffer.join("");
-        } else if (endIpv6) {
-          address.push(buffer.join(""));
-        } else {
-          address.push(stringArrayToHexStripped(buffer));
-        }
+      if (compression === -1) {
+        if (hextetCount !== 8) return void 0;
+        return compressIPv6ZeroRun(parts);
       }
-      output.address = address.join("");
-      return output;
+      if (hextetCount >= 8) return void 0;
+      const expanded = parts.slice(0, left.length);
+      for (let i = hextetCount; i < 8; i++) expanded.push("0");
+      for (let i = left.length; i < parts.length; i++) expanded.push(parts[i]);
+      return compressIPv6ZeroRun(expanded);
     }
     function normalizeIPv6(host) {
-      if (findToken(host, ":") < 2) {
-        return { host, isIPV6: false };
-      }
-      const ipv63 = getIPV6(host);
-      if (!ipv63.error) {
-        let newHost = ipv63.address;
-        let escapedHost = ipv63.address;
-        if (ipv63.zone) {
-          newHost += "%" + ipv63.zone;
-          escapedHost += "%25" + ipv63.zone;
-        }
-        return { host: newHost, isIPV6: true, escapedHost };
-      } else {
-        return { host, isIPV6: false };
-      }
+      const bracketed = host[0] === "[" && host[host.length - 1] === "]";
+      const hasBracket = host[0] === "[" || host[host.length - 1] === "]";
+      if (hasBracket && !bracketed) return { host, isIPV6: false, error: true };
+      let input = bracketed ? host.slice(1, -1) : host;
+      if (bracketed && isIPvFuture(input)) {
+        input = input.toLowerCase();
+        return { host: `[${input}]`, escapedHost: input, isIPV6: false, isIPVFuture: true };
+      }
+      if (findToken(input, ":") < 2) {
+        return { host, isIPV6: false, error: bracketed };
+      }
+      let zoneIdentifier = "";
+      const zoneSeparator = input.indexOf("%");
+      if (zoneSeparator !== -1) {
+        const separatorLength = input.slice(zoneSeparator, zoneSeparator + 3).toLowerCase() === "%25" ? 3 : 1;
+        zoneIdentifier = input.slice(zoneSeparator + separatorLength);
+        if (!isZoneIdentifier(zoneIdentifier)) return { host, isIPV6: false, error: true };
+        input = input.slice(0, zoneSeparator);
+      }
+      const address = normalizeIPv6Address(input);
+      if (address === void 0) return { host, isIPV6: false, error: true };
+      return {
+        host: address + (zoneIdentifier ? "%" + zoneIdentifier : ""),
+        escapedHost: address + (zoneIdentifier ? "%25" + zoneIdentifier : ""),
+        isIPV6: true
+      };
     }
     function findToken(str, token) {
       let ind = 0;
@@ -3339,7 +3372,8 @@ var require_utils = __commonJS({
     function normalizePathEncoding(input) {
       let output = "";
       for (let i = 0; i < input.length; i++) {
-        if (input[i] === "%" && i + 2 < input.length) {
+        const ch = input[i];
+        if (ch === "%" && i + 2 < input.length) {
           const hex3 = input.slice(i + 1, i + 3);
           if (isHexPair(hex3)) {
             const normalizedHex = hex3.toUpperCase();
@@ -3353,10 +3387,152 @@ var require_utils = __commonJS({
             continue;
           }
         }
-        if (isPathCharacter(input[i])) {
-          output += input[i];
+        if (isPathCharacter(ch)) {
+          output += ch;
+        } else {
+          const code = input.charCodeAt(i);
+          if (code < 128) {
+            output += isEscapeSafe(code) ? ch : BYTE_HEX[code];
+          } else if (code < 55296 || code > 57343) {
+            output += percentEncodeNonAscii(code);
+          } else if (code <= 56319 && i + 1 < input.length) {
+            const low = input.charCodeAt(i + 1);
+            if (low >= 56320 && low <= 57343) {
+              output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+              i++;
+            } else {
+              output += percentEncodeNonAscii(65533);
+            }
+          } else {
+            output += percentEncodeNonAscii(65533);
+          }
+        }
+      }
+      return output;
+    }
+    function serializePathEncoding(input, pathNoScheme = false) {
+      let output = "";
+      let firstSegment = pathNoScheme && input[0] !== "/";
+      for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            output += "%" + hex3.toUpperCase();
+            i += 2;
+            continue;
+          }
+        }
+        if (ch === "/") {
+          firstSegment = false;
+        }
+        if (isPathCharacter(ch) && (ch !== ":" || !firstSegment)) {
+          output += ch;
         } else {
-          output += escape(input[i]);
+          const code = input.charCodeAt(i);
+          if (code < 128) {
+            output += BYTE_HEX[code];
+          } else if (code < 55296 || code > 57343) {
+            output += percentEncodeNonAscii(code);
+          } else if (code <= 56319 && i + 1 < input.length) {
+            const low = input.charCodeAt(i + 1);
+            if (low >= 56320 && low <= 57343) {
+              output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+              i++;
+            } else {
+              output += percentEncodeNonAscii(65533);
+            }
+          } else {
+            output += percentEncodeNonAscii(65533);
+          }
+        }
+      }
+      return output;
+    }
+    function encodeComponent(input, isAllowed) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            output += "%" + hex3.toUpperCase();
+            i += 2;
+            continue;
+          }
+        }
+        if (isAllowed(ch)) {
+          output += ch;
+        } else {
+          const code = input.charCodeAt(i);
+          if (code < 128) {
+            output += BYTE_HEX[code];
+          } else if (code < 55296 || code > 57343) {
+            output += percentEncodeNonAscii(code);
+          } else if (code <= 56319 && i + 1 < input.length) {
+            const low = input.charCodeAt(i + 1);
+            if (low >= 56320 && low <= 57343) {
+              output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+              i++;
+            } else {
+              output += percentEncodeNonAscii(65533);
+            }
+          } else {
+            output += percentEncodeNonAscii(65533);
+          }
+        }
+      }
+      return output;
+    }
+    function encodeUserinfo(input) {
+      return encodeComponent(input, isUserinfoCharacter);
+    }
+    function encodeQuery(input) {
+      return encodeComponent(input, isQueryFragmentCharacter);
+    }
+    function encodeFragment(input) {
+      return encodeComponent(input, isQueryFragmentCharacter);
+    }
+    function isEscapeSafe(cp) {
+      return cp >= 48 && cp <= 57 || cp >= 65 && cp <= 90 || cp >= 97 && cp <= 122 || cp === 42 || cp === 43 || cp === 45 || cp === 46 || cp === 47 || cp === 64 || cp === 95;
+    }
+    function normalizeQueryFragmentEncoding(input) {
+      let output = "";
+      for (let i = 0; i < input.length; i++) {
+        const ch = input[i];
+        if (ch === "%" && i + 2 < input.length) {
+          const hex3 = input.slice(i + 1, i + 3);
+          if (isHexPair(hex3)) {
+            const normalizedHex = hex3.toUpperCase();
+            const decoded = String.fromCharCode(parseInt(normalizedHex, 16));
+            if (isUnreserved(decoded)) {
+              output += decoded;
+            } else {
+              output += "%" + normalizedHex;
+            }
+            i += 2;
+            continue;
+          }
+        }
+        if (isQueryFragmentCharacter(ch)) {
+          output += ch;
+        } else {
+          const code = input.charCodeAt(i);
+          if (code < 128) {
+            output += isEscapeSafe(code) ? ch : BYTE_HEX[code];
+          } else if (code < 55296 || code > 57343) {
+            output += percentEncodeNonAscii(code);
+          } else if (code <= 56319 && i + 1 < input.length) {
+            const low = input.charCodeAt(i + 1);
+            if (low >= 56320 && low <= 57343) {
+              output += percentEncodeNonAscii(65536 + (code - 55296 << 10) + (low - 56320));
+              i++;
+            } else {
+              output += percentEncodeNonAscii(65533);
+            }
+          } else {
+            output += percentEncodeNonAscii(65533);
+          }
         }
       }
       return output;
@@ -3379,14 +3555,18 @@ var require_utils = __commonJS({
     function recomposeAuthority(component) {
       const uriTokens = [];
       if (component.userinfo !== void 0) {
-        uriTokens.push(component.userinfo);
+        uriTokens.push(encodeUserinfo(component.userinfo));
         uriTokens.push("@");
       }
       if (component.host !== void 0) {
-        let host = unescape(component.host);
+        let host = component.host;
         if (!isIPv42(host)) {
-          const ipV6res = normalizeIPv6(host);
-          if (ipV6res.isIPV6 === true) {
+          let ipV6res = normalizeIPv6(host);
+          if (ipV6res.isIPV6 !== true && ipV6res.isIPVFuture !== true) {
+            host = normalizePercentEncoding(host, true);
+            ipV6res = normalizeIPv6(host);
+          }
+          if (ipV6res.isIPV6 === true || ipV6res.isIPVFuture === true) {
             host = `[${ipV6res.escapedHost}]`;
           } else {
             host = reescapeHostDelimiters(host, false);
@@ -3395,8 +3575,12 @@ var require_utils = __commonJS({
         uriTokens.push(host);
       }
       if (typeof component.port === "number" || typeof component.port === "string") {
+        const port = String(component.port);
+        if (!isPort(port)) {
+          throw new TypeError("URI port is malformed.");
+        }
         uriTokens.push(":");
-        uriTokens.push(String(component.port));
+        uriTokens.push(port);
       }
       return uriTokens.length ? uriTokens.join("") : void 0;
     }
@@ -3406,6 +3590,11 @@ var require_utils = __commonJS({
       reescapeHostDelimiters,
       normalizePercentEncoding,
       normalizePathEncoding,
+      serializePathEncoding,
+      normalizeQueryFragmentEncoding,
+      encodeUserinfo,
+      encodeQuery,
+      encodeFragment,
       escapePreservingEscapes,
       removeDotSegments,
       isIPv4: isIPv42,
@@ -3421,7 +3610,7 @@ var require_schemes = __commonJS({
   "node_modules/fast-uri/lib/schemes.js"(exports, module) {
     "use strict";
     var { isUUID } = require_utils();
-    var URN_REG = /([\da-z][\d\-a-z]{0,31}):((?:[\w!$'()*+,\-.:;=@]|%[\da-f]{2})+)/iu;
+    var URN_REG = /^([\da-z][\d\-a-z]{0,31}):((?:[\w!$'()*+,\-./:;=@]|%[\da-f]{2})+)$/iu;
     var supportedSchemeNames = (
       /** @type {const} */
       [
@@ -3482,9 +3671,10 @@ var require_schemes = __commonJS({
         wsComponent.secure = void 0;
       }
       if (wsComponent.resourceName) {
-        const [path, query] = wsComponent.resourceName.split("?");
+        const queryIndex = wsComponent.resourceName.indexOf("?");
+        const path = queryIndex === -1 ? wsComponent.resourceName : wsComponent.resourceName.slice(0, queryIndex);
         wsComponent.path = path && path !== "/" ? path : void 0;
-        wsComponent.query = query;
+        wsComponent.query = queryIndex === -1 ? void 0 : wsComponent.resourceName.slice(queryIndex + 1);
         wsComponent.resourceName = void 0;
       }
       wsComponent.fragment = void 0;
@@ -3496,7 +3686,7 @@ var require_schemes = __commonJS({
         return urnComponent;
       }
       const matches = urnComponent.path.match(URN_REG);
-      if (matches) {
+      if (matches && matches[0] === urnComponent.path) {
         const scheme = options.scheme || urnComponent.scheme || "urn";
         urnComponent.nid = matches[1].toLowerCase();
         urnComponent.nss = matches[2];
@@ -3630,8 +3820,17 @@ var require_schemes = __commonJS({
 var require_fast_uri = __commonJS({
   "node_modules/fast-uri/index.js"(exports, module) {
     "use strict";
-    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, escapePreservingEscapes, reescapeHostDelimiters, isIPv4: isIPv42, nonSimpleDomain } = require_utils();
+    var { normalizeIPv6, removeDotSegments, recomposeAuthority, normalizePercentEncoding, normalizePathEncoding, serializePathEncoding, normalizeQueryFragmentEncoding, encodeQuery, encodeFragment, reescapeHostDelimiters, isIPv4: isIPv42, nonSimpleDomain } = require_utils();
     var { SCHEMES, getSchemeHandler } = require_schemes();
+    var VALID_SCHEME = /^[A-Za-z][A-Za-z0-9+.-]*$/u;
+    var MALFORMED_SCHEME_ERROR = "URI scheme is malformed.";
+    function decodeValidScheme(scheme) {
+      const decodedScheme = unescape(String(scheme));
+      if (!VALID_SCHEME.test(decodedScheme)) {
+        throw new TypeError(MALFORMED_SCHEME_ERROR);
+      }
+      return decodedScheme;
+    }
     function normalize(uri, options) {
       if (typeof uri === "string") {
         uri = /** @type {T} */
@@ -3644,7 +3843,34 @@ var require_fast_uri = __commonJS({
     }
     function resolve(baseURI, relativeURI, options) {
       const schemelessOptions = options ? Object.assign({ scheme: "null" }, options) : { scheme: "null" };
-      const resolved = resolveComponent(parse3(baseURI, schemelessOptions), parse3(relativeURI, schemelessOptions), schemelessOptions, true);
+      const {
+        parsed: baseParsed,
+        malformedAuthorityOrPort: baseMalformed,
+        malformedPercentEncoding: baseMalformedPercentEncoding,
+        malformedSchemeSpecific: baseMalformedSchemeSpecific,
+        malformedHost: baseMalformedHost,
+        malformedScheme: baseMalformedScheme
+      } = parseWithStatus(baseURI, schemelessOptions);
+      const {
+        parsed: relativeParsed,
+        malformedAuthorityOrPort: relativeMalformed,
+        malformedPercentEncoding: relativeMalformedPercentEncoding,
+        malformedSchemeSpecific: relativeMalformedSchemeSpecific,
+        malformedHost: relativeMalformedHost,
+        malformedScheme: relativeMalformedScheme
+      } = parseWithStatus(relativeURI, schemelessOptions);
+      if (baseMalformed || relativeMalformed || baseMalformedPercentEncoding || relativeMalformedPercentEncoding || baseMalformedSchemeSpecific || relativeMalformedSchemeSpecific || baseMalformedHost || relativeMalformedHost || baseMalformedScheme || relativeMalformedScheme) {
+        throw new Error(baseParsed.error || relativeParsed.error || "URI is malformed.");
+      }
+      const resolved = resolveComponent(baseParsed, relativeParsed, schemelessOptions, true);
+      const resolvedSchemeHandler = getSchemeHandler(options && options.scheme || resolved.scheme);
+      const resolvedHost = resolved.host;
+      const resolvedHostIsIP = resolvedHost !== void 0 && resolvedHost !== "" && (isIPv42(resolvedHost) || normalizeIPv6(resolvedHost).isIPV6);
+      canonicalizeHost(resolved, options || {}, resolvedSchemeHandler, resolvedHostIsIP);
+      const encodedASCIIHost = resolvedHost && resolvedHost.indexOf("%") !== -1 && !new RegExp("\\P{ASCII}", "u").test(resolvedHost);
+      if (resolved.error && !encodedASCIIHost) {
+        throw new Error(resolved.error);
+      }
       schemelessOptions.skipEscape = true;
       return serialize(resolved, schemelessOptions);
     }
@@ -3704,7 +3930,7 @@ var require_fast_uri = __commonJS({
     function equal(uriA, uriB, options) {
       const normalizedA = normalizeComparableURI(uriA, options);
       const normalizedB = normalizeComparableURI(uriB, options);
-      return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA.toLowerCase() === normalizedB.toLowerCase();
+      return normalizedA !== void 0 && normalizedB !== void 0 && normalizedA === normalizedB;
     }
     function serialize(cmpts, opts) {
       const component = {
@@ -3725,19 +3951,22 @@ var require_fast_uri = __commonJS({
       };
       const options = Object.assign({}, opts);
       const uriTokens = [];
+      if (component.scheme) {
+        component.scheme = decodeValidScheme(component.scheme);
+      }
       const schemeHandler = getSchemeHandler(options.scheme || component.scheme);
       if (schemeHandler && schemeHandler.serialize) schemeHandler.serialize(component, options);
+      const hasAuthority = component.userinfo !== void 0 || component.host !== void 0 || component.port !== void 0;
+      const pathNoScheme = !options.skipEscape && component.scheme === void 0 && !hasAuthority;
       if (component.path !== void 0) {
         if (!options.skipEscape) {
-          component.path = escapePreservingEscapes(component.path);
-          if (component.scheme !== void 0) {
-            component.path = component.path.split("%3A").join(":");
-          }
+          component.path = serializePathEncoding(component.path, pathNoScheme);
         } else {
           component.path = normalizePercentEncoding(component.path);
         }
       }
       if (options.reference !== "suffix" && component.scheme) {
+        component.scheme = decodeValidScheme(component.scheme);
         uriTokens.push(component.scheme, ":");
       }
       const authority = recomposeAuthority(component);
@@ -3755,20 +3984,25 @@ var require_fast_uri = __commonJS({
         if (!options.absolutePath && (!schemeHandler || !schemeHandler.absolutePath)) {
           s = removeDotSegments(s);
         }
+        if (pathNoScheme) {
+          s = serializePathEncoding(s, true);
+        }
         if (authority === void 0 && s[0] === "/" && s[1] === "/") {
           s = "/%2F" + s.slice(2);
         }
         uriTokens.push(s);
       }
       if (component.query !== void 0) {
-        uriTokens.push("?", component.query);
+        uriTokens.push("?", encodeQuery(component.query));
       }
       if (component.fragment !== void 0) {
-        uriTokens.push("#", component.fragment);
+        uriTokens.push("#", encodeFragment(component.fragment));
       }
       return uriTokens.join("");
     }
     var URI_PARSE = /^(?:([^#/:?]+):)?(?:\/\/((?:([^#/?@]*)@)?(\[[^#/?\]]+\]|[^#/:?]*)(?::(\d*))?))?([^#?]*)(?:\?([^#]*))?(?:#((?:.|[\n\r])*))?/u;
+    var AUTHORITY_PREFIX = /^(?:[^#/:?]+:)?\/\/([^/?#]*)/;
+    var AUTHORITY_INTRODUCER_REGION = /^(?:[^#/:?]+:)?([/\\\t\n\r]*)/;
     function getParseError(parsed, matches) {
       if (matches[2] !== void 0 && parsed.path && parsed.path[0] !== "/") {
         return 'URI path must start with "/" when authority is present.';
@@ -3778,6 +4012,35 @@ var require_fast_uri = __commonJS({
       }
       return void 0;
     }
+    function hasMalformedPercentEncoding(component) {
+      if (component === void 0) return false;
+      let percent = component.indexOf("%");
+      while (percent !== -1) {
+        if (percent + 2 >= component.length || !/^[\da-f]{2}$/iu.test(component.slice(percent + 1, percent + 3))) {
+          return true;
+        }
+        percent = component.indexOf("%", percent + 3);
+      }
+      return false;
+    }
+    function isIPLiteral(host) {
+      return host[0] === "[" && host[host.length - 1] === "]";
+    }
+    function hasMalformedComponentPercentEncoding(matches) {
+      const host = matches[4];
+      return hasMalformedPercentEncoding(matches[3]) || host !== void 0 && !isIPLiteral(host) && hasMalformedPercentEncoding(host) || hasMalformedPercentEncoding(matches[6]) || hasMalformedPercentEncoding(matches[7]) || hasMalformedPercentEncoding(matches[8]);
+    }
+    function canonicalizeHost(parsed, options, schemeHandler, isIP2) {
+      if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport) && parsed.host && !isIPLiteral(parsed.host) && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP2 === false && nonSimpleDomain(parsed.host)) {
+        try {
+          parsed.host = new URL("http://" + parsed.host).hostname;
+        } catch (e) {
+          parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
+          return true;
+        }
+      }
+      return false;
+    }
     function parseWithStatus(uri, opts) {
       const options = Object.assign({}, opts);
       const parsed = {
@@ -3790,6 +4053,11 @@ var require_fast_uri = __commonJS({
         fragment: void 0
       };
       let malformedAuthorityOrPort = false;
+      let malformedPercentEncoding = false;
+      let malformedSchemeSpecific = false;
+      let malformedHost = false;
+      let malformedIPLiteral = false;
+      let malformedScheme = false;
       let isIP2 = false;
       if (options.reference === "suffix") {
         if (options.scheme) {
@@ -3798,6 +4066,25 @@ var require_fast_uri = __commonJS({
           uri = "//" + uri;
         }
       }
+      const authorityMatch = uri.match(AUTHORITY_PREFIX);
+      if (authorityMatch !== null && authorityMatch[1].indexOf("\\") !== -1) {
+        parsed.error = "URI authority must not contain a literal backslash.";
+        malformedAuthorityOrPort = true;
+      }
+      const introducerMatch = uri.match(AUTHORITY_INTRODUCER_REGION);
+      if (introducerMatch !== null) {
+        const region = introducerMatch[1];
+        const normalizedRegion = region.replace(/[\t\n\r]/g, "");
+        if (normalizedRegion.length >= 2) {
+          if (normalizedRegion.slice(0, 2) !== "//") {
+            parsed.error = parsed.error || "URI authority must not contain a literal backslash.";
+            malformedAuthorityOrPort = true;
+          } else if (region.length !== normalizedRegion.length) {
+            parsed.error = parsed.error || "URI authority introducer must not contain whitespace.";
+            malformedAuthorityOrPort = true;
+          }
+        }
+      }
       const matches = uri.match(URI_PARSE);
       if (matches) {
         parsed.scheme = matches[1];
@@ -3807,6 +4094,19 @@ var require_fast_uri = __commonJS({
         parsed.path = matches[6] || "";
         parsed.query = matches[7];
         parsed.fragment = matches[8];
+        if (parsed.scheme !== void 0) {
+          const decodedScheme = unescape(parsed.scheme);
+          if (VALID_SCHEME.test(decodedScheme)) {
+            parsed.scheme = decodedScheme.toLowerCase();
+          } else {
+            parsed.error = parsed.error || MALFORMED_SCHEME_ERROR;
+            malformedScheme = true;
+          }
+        }
+        malformedPercentEncoding = hasMalformedComponentPercentEncoding(matches);
+        if (malformedPercentEncoding) {
+          parsed.error = parsed.error || "URI contains malformed percent-encoding.";
+        }
         if (isNaN(parsed.port)) {
           parsed.port = matches[5];
         }
@@ -3818,9 +4118,16 @@ var require_fast_uri = __commonJS({
         if (parsed.host) {
           const ipv4result = isIPv42(parsed.host);
           if (ipv4result === false) {
+            const bracketedIPLiteral = isIPLiteral(parsed.host);
+            const hasIPLiteralBracket = parsed.host.indexOf("[") !== -1 || parsed.host.indexOf("]") !== -1;
             const ipv6result = normalizeIPv6(parsed.host);
-            parsed.host = ipv6result.host.toLowerCase();
-            isIP2 = ipv6result.isIPV6;
+            isIP2 = ipv6result.isIPV6 || ipv6result.isIPVFuture === true;
+            malformedIPLiteral = hasIPLiteralBracket && (!bracketedIPLiteral || ipv6result.error === true);
+            parsed.host = isIP2 ? ipv6result.host : ipv6result.host.toLowerCase();
+            if (malformedIPLiteral) {
+              parsed.error = parsed.error || "URI host is malformed.";
+              malformedAuthorityOrPort = true;
+            }
           } else {
             isIP2 = true;
           }
@@ -3838,42 +4145,36 @@ var require_fast_uri = __commonJS({
           parsed.error = parsed.error || "URI is not a " + options.reference + " reference.";
         }
         const schemeHandler = getSchemeHandler(options.scheme || parsed.scheme);
-        if (!options.unicodeSupport && (!schemeHandler || !schemeHandler.unicodeSupport)) {
-          if (parsed.host && (options.domainHost || schemeHandler && schemeHandler.domainHost) && isIP2 === false && nonSimpleDomain(parsed.host)) {
-            try {
-              parsed.host = URL.domainToASCII(parsed.host.toLowerCase());
-            } catch (e) {
-              parsed.error = parsed.error || "Host's domain name can not be converted to ASCII: " + e;
-            }
-          }
+        if (!malformedIPLiteral) {
+          malformedHost = canonicalizeHost(parsed, options, schemeHandler, isIP2);
         }
         if (!schemeHandler || schemeHandler && !schemeHandler.skipNormalize) {
           if (uri.indexOf("%") !== -1) {
-            if (parsed.scheme !== void 0) {
-              parsed.scheme = unescape(parsed.scheme);
-            }
-            if (parsed.host !== void 0) {
-              parsed.host = reescapeHostDelimiters(unescape(parsed.host), isIP2);
+            if (parsed.host !== void 0 && !malformedIPLiteral) {
+              const host = isIP2 ? parsed.host : normalizePercentEncoding(parsed.host, true);
+              parsed.host = reescapeHostDelimiters(host, isIP2);
             }
           }
           if (parsed.path) {
             parsed.path = normalizePathEncoding(parsed.path);
           }
+          if (parsed.query) {
+            parsed.query = normalizeQueryFragmentEncoding(parsed.query);
+          }
           if (parsed.fragment) {
-            try {
-              parsed.fragment = encodeURI(decodeURIComponent(parsed.fragment));
-            } catch {
-              parsed.error = parsed.error || "URI malformed";
-            }
+            parsed.fragment = normalizeQueryFragmentEncoding(parsed.fragment);
           }
         }
         if (schemeHandler && schemeHandler.parse) {
           schemeHandler.parse(parsed, options);
+          if (schemeHandler === SCHEMES.urn && parsed.nid === void 0) {
+            malformedSchemeSpecific = true;
+          }
         }
       } else {
         parsed.error = parsed.error || "URI can not be parsed.";
       }
-      return { parsed, malformedAuthorityOrPort };
+      return { parsed, malformedAuthorityOrPort, malformedPercentEncoding, malformedSchemeSpecific, malformedHost, malformedScheme };
     }
     function parse3(uri, opts) {
       return parseWithStatus(uri, opts).parsed;
@@ -3882,20 +4183,28 @@ var require_fast_uri = __commonJS({
       return normalizeStringWithStatus(uri, opts).normalized;
     }
     function normalizeStringWithStatus(uri, opts) {
-      const { parsed, malformedAuthorityOrPort } = parseWithStatus(uri, opts);
+      const { parsed, malformedAuthorityOrPort, malformedPercentEncoding, malformedSchemeSpecific, malformedHost, malformedScheme } = parseWithStatus(uri, opts);
       return {
-        normalized: malformedAuthorityOrPort ? uri : serialize(parsed, opts),
-        malformedAuthorityOrPort
+        normalized: malformedAuthorityOrPort || malformedPercentEncoding || malformedSchemeSpecific || malformedHost || malformedScheme ? uri : serialize(parsed, opts),
+        malformedAuthorityOrPort,
+        malformedPercentEncoding,
+        malformedSchemeSpecific,
+        malformedHost,
+        malformedScheme
       };
     }
     function normalizeComparableURI(uri, opts) {
-      if (typeof uri === "string") {
-        const { normalized, malformedAuthorityOrPort } = normalizeStringWithStatus(uri, opts);
-        return malformedAuthorityOrPort ? void 0 : normalized;
+      if (typeof uri !== "string" && typeof uri !== "object") {
+        return void 0;
       }
-      if (typeof uri === "object") {
-        return serialize(uri, opts);
+      let value;
+      try {
+        value = typeof uri === "string" ? uri : serialize(uri, opts);
+      } catch {
+        return void 0;
       }
+      const { normalized, malformedAuthorityOrPort, malformedPercentEncoding, malformedSchemeSpecific, malformedHost, malformedScheme } = normalizeStringWithStatus(value, opts);
+      return malformedAuthorityOrPort || malformedPercentEncoding || malformedSchemeSpecific || malformedHost || malformedScheme ? void 0 : normalized;
     }
     var fastUri = {
       SCHEMES,
@@ -23045,17 +23354,33 @@ function normalizeObjectSchema(schema) {
   }
   return void 0;
 }
+function getDotPath(path) {
+  if (path.length === 0) {
+    return "object root";
+  }
+  return path.reduce((acc, seg, index) => {
+    if (index === 0) {
+      return String(seg);
+    }
+    if (typeof seg === "number") {
+      return `${acc}[${seg}]`;
+    }
+    return `${acc}.${seg}`;
+  }, "");
+}
 function getParseErrorMessage(error51) {
   if (error51 && typeof error51 === "object") {
+    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
+      return error51.issues.map((i) => {
+        if (!i.path?.length) {
+          return i.message;
+        }
+        return `${i.message} at ${getDotPath(i.path)}`;
+      }).join("\n");
+    }
     if ("message" in error51 && typeof error51.message === "string") {
       return error51.message;
     }
-    if ("issues" in error51 && Array.isArray(error51.issues) && error51.issues.length > 0) {
-      const firstIssue = error51.issues[0];
-      if (firstIssue && typeof firstIssue === "object" && "message" in firstIssue) {
-        return String(firstIssue.message);
-      }
-    }
     try {
       return JSON.stringify(error51);
     } catch {
@@ -29670,16 +29995,7 @@ var Server = class extends Protocol {
     if (!methodSchema) {
       throw new Error("Schema is missing a method literal");
     }
-    let methodValue;
-    if (isZ4Schema(methodSchema)) {
-      const v4Schema = methodSchema;
-      const v4Def = v4Schema._zod?.def;
-      methodValue = v4Def?.value ?? v4Schema.value;
-    } else {
-      const v3Schema = methodSchema;
-      const legacyDef = v3Schema._def;
-      methodValue = legacyDef?.value ?? v3Schema.value;
-    }
+    const methodValue = getLiteralValue(methodSchema);
     if (typeof methodValue !== "string") {
       throw new Error("Schema method literal must be a string");
     }
@@ -30867,8 +31183,17 @@ var EMPTY_COMPLETION_RESULT = {
 import process3 from "node:process";
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/shared/stdio.js
+var STDIO_DEFAULT_MAX_BUFFER_SIZE = 10 * 1024 * 1024;
 var ReadBuffer = class {
+  constructor(options) {
+    this._maxBufferSize = options?.maxBufferSize ?? STDIO_DEFAULT_MAX_BUFFER_SIZE;
+  }
   append(chunk) {
+    const newSize = (this._buffer?.length ?? 0) + chunk.length;
+    if (newSize > this._maxBufferSize) {
+      this.clear();
+      throw new Error(`ReadBuffer exceeded maximum size of ${this._maxBufferSize} bytes`);
+    }
     this._buffer = this._buffer ? Buffer.concat([this._buffer, chunk]) : chunk;
   }
   readMessage() {
@@ -30896,18 +31221,24 @@ function serializeMessage(message) {
 
 // node_modules/@modelcontextprotocol/sdk/dist/esm/server/stdio.js
 var StdioServerTransport = class {
-  constructor(_stdin = process3.stdin, _stdout = process3.stdout) {
+  constructor(_stdin = process3.stdin, _stdout = process3.stdout, options) {
     this._stdin = _stdin;
     this._stdout = _stdout;
-    this._readBuffer = new ReadBuffer();
     this._started = false;
     this._ondata = (chunk) => {
-      this._readBuffer.append(chunk);
-      this.processReadBuffer();
+      try {
+        this._readBuffer.append(chunk);
+        this.processReadBuffer();
+      } catch (error51) {
+        this.onerror?.(error51);
+        this.close().catch(() => {
+        });
+      }
     };
     this._onerror = (error51) => {
       this.onerror?.(error51);
     };
+    this._readBuffer = new ReadBuffer({ maxBufferSize: options?.maxBufferSize });
   }
   /**
    * Starts listening for messages on stdin.
@@ -30966,7 +31297,9 @@ var DEFAULT_429_DELAY_MS = 1e3;
 var MAX_429_DELAY_MS = 3e4;
 var MAX_429_JITTER_MS = 250;
 var MAX_REQUEST_BUDGET_MS = 9e4;
+var GATEWAY_5XX_BUDGET_FRACTION = 0.5;
 var RETRYABLE_METHODS = /* @__PURE__ */ new Set(["GET", "PUT", "DELETE"]);
+var RETRYABLE_STATUSES = /* @__PURE__ */ new Set([429, 502, 503, 504]);
 var oauthToken = null;
 var oauthRefreshPromise = null;
 function getAuthConfig() {
@@ -31020,7 +31353,7 @@ async function getOAuthAccessToken(clientId, clientSecret) {
       });
       if (!res.ok) {
         const body = await res.text();
-        const guidance = res.status === 401 || res.status === 403 ? " Verify TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET, and that the client has the scopes your tools need (https://console.tailscale.com/admin/settings/oauth)." + (oauthTailnet ? ` Targeting tailnet "${oauthTailnet}" via TAILSCALE_OAUTH_TAILNET -- that requires an OAuth client from the CREATING tailnet with the 'all' scope.` : "") : "";
+        const guidance = res.status === 401 || res.status === 403 ? " Verify TAILSCALE_OAUTH_CLIENT_ID and TAILSCALE_OAUTH_CLIENT_SECRET, and that the client has the scopes your tools need (https://console.tailscale.com/admin/settings/trust-credentials)." + (oauthTailnet ? ` Targeting tailnet "${oauthTailnet}" via TAILSCALE_OAUTH_TAILNET -- that requires an OAuth client from the CREATING tailnet with the 'all' scope.` : "") : "";
         throw new Error(`OAuth token exchange failed (${res.status}): ${body}.${guidance}`);
       }
       const data = await res.json();
@@ -31054,6 +31387,7 @@ function getTailnet() {
 function encPath(segment) {
   return encodeURIComponent(segment);
 }
+var DEVICE_ID_HINT = "nodeId from tailscale_list_devices (e.g. nPM2KNuedB21DEVEL); numeric id ok; not the nodeKey.";
 function validateTags(tags) {
   if (!tags || tags.length === 0) return;
   const invalid = tags.filter((t) => !t.startsWith("tag:"));
@@ -31072,6 +31406,7 @@ function validateAndSanitizeDescription(value) {
     `description ${JSON.stringify(value)} contains no valid characters after sanitization. Allowed characters: alphanumeric, spaces, and hyphens (max 50 chars).`
   );
 }
+var OAUTH_SCOPE_TABLE_HEADING = "OAuth scopes by tool group";
 function formatAuthError(status, apiBody) {
   let usingOAuth = false;
   try {
@@ -31080,7 +31415,7 @@ function formatAuthError(status, apiBody) {
     usingOAuth = false;
   }
   const headline = status === 401 ? "Authentication failed (HTTP 401)." : "Authorization failed (HTTP 403): the request was authenticated but not permitted for this resource.";
-  const cause = status === 401 ? usingOAuth ? "  - OAuth client credentials are invalid or lack required scopes" : "  - API key has expired or been revoked" : usingOAuth ? "  - OAuth client is missing a scope required for this endpoint" : "  - API key lacks the permission required for this endpoint";
+  const cause = status === 401 ? usingOAuth ? "  - OAuth client credentials are invalid or lack required scopes" : "  - API key has expired or been revoked" : usingOAuth ? `  - OAuth client is missing a scope required for this endpoint (scopes per tool group: README, "${OAUTH_SCOPE_TABLE_HEADING}")` : "  - API key lacks the permission required for this endpoint";
   const lines = [headline, "", "Possible causes:", cause];
   if (status === 401 && process.platform === "win32" && !usingOAuth) {
     lines.push(
@@ -31091,13 +31426,89 @@ function formatAuthError(status, apiBody) {
       "  2. Set TAILSCALE_API_KEY as a Windows user environment variable (System Properties > Environment Variables)"
     );
   }
-  const link = status === 401 ? "Generate a new key at: https://console.tailscale.com/admin/settings/keys" : usingOAuth ? "Adjust the OAuth client scopes at: https://console.tailscale.com/admin/settings/oauth" : "Adjust the API key permissions at: https://console.tailscale.com/admin/settings/keys";
+  const link = status === 401 ? "Generate a new key at: https://console.tailscale.com/admin/settings/keys" : usingOAuth ? "Adjust the credential's scopes at: https://console.tailscale.com/admin/settings/trust-credentials" : "Adjust the API key permissions at: https://console.tailscale.com/admin/settings/keys";
   lines.push("", link);
   if (apiBody) {
     lines.push("", `API response: ${apiBody}`);
   }
   return lines.join("\n");
 }
+var ERROR_DATA_MAX_LINES = 100;
+var ERROR_DATA_MAX_CHARS = 8e3;
+var ERROR_DATA_MAX_JSON_CHARS = 1e3;
+var SENSITIVE_DATA_KEY = /secret|token|password|credential|key/i;
+function redactSensitive(value) {
+  if (Array.isArray(value)) return value.map(redactSensitive);
+  if (value === null || typeof value !== "object") return value;
+  const out = {};
+  for (const [key, inner] of Object.entries(value)) {
+    out[key] = SENSITIVE_DATA_KEY.test(key) ? "[redacted]" : redactSensitive(inner);
+  }
+  return out;
+}
+function asStringArray(value) {
+  return Array.isArray(value) && value.every((v) => typeof v === "string") ? value : void 0;
+}
+function renderJsonEntry(value) {
+  const json2 = JSON.stringify(redactSensitive(value)) ?? String(value);
+  if (json2.length <= ERROR_DATA_MAX_JSON_CHARS) return json2;
+  return `${json2.slice(0, ERROR_DATA_MAX_JSON_CHARS)}... (${json2.length - ERROR_DATA_MAX_JSON_CHARS} more characters)`;
+}
+function joinErrorDataBlocks(blocks) {
+  const out = [];
+  let lines = 0;
+  let chars = 0;
+  let shown = 0;
+  for (const block of blocks) {
+    const blockChars = block.reduce((n, line) => n + line.length + 1, 0);
+    if (lines + block.length <= ERROR_DATA_MAX_LINES && chars + blockChars <= ERROR_DATA_MAX_CHARS) {
+      out.push(...block);
+      lines += block.length;
+      chars += blockChars;
+      shown++;
+      continue;
+    }
+    if (shown === 0) {
+      const kept = block.slice(0, ERROR_DATA_MAX_LINES);
+      out.push(...kept);
+      if (kept.length < block.length) out.push(`... and ${block.length - kept.length} more lines in this entry`);
+      shown++;
+    }
+    break;
+  }
+  const dropped = blocks.length - shown;
+  if (dropped > 0) out.push(`... and ${dropped} more ${dropped === 1 ? "entry" : "entries"}`);
+  return out.join("\n");
+}
+function formatApiErrorData(data) {
+  if (!Array.isArray(data) || data.length === 0) return "";
+  const blocks = [];
+  for (const entry of data) {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) {
+      blocks.push([renderJsonEntry(entry)]);
+      continue;
+    }
+    const obj = entry;
+    const consumed = /* @__PURE__ */ new Set();
+    const rendered = [];
+    if (typeof obj.user === "string") {
+      consumed.add("user");
+      if (obj.user.length > 0) rendered.push(`For user ${obj.user}:`);
+    }
+    for (const [key, heading] of [
+      ["errors", "Errors found:"],
+      ["warnings", "Warnings found:"]
+    ]) {
+      const items = asStringArray(obj[key]);
+      if (!items) continue;
+      consumed.add(key);
+      if (items.length > 0) rendered.push(heading, ...items.map((item) => `- ${item}`));
+    }
+    if (rendered.length > 0 && Object.keys(obj).every((key) => consumed.has(key))) blocks.push(rendered);
+    else blocks.push([renderJsonEntry(obj)]);
+  }
+  return joinErrorDataBlocks(blocks);
+}
 function extractErrorMessage(body) {
   if (!body) return body;
   const trimmed = body.trim();
@@ -31106,8 +31517,12 @@ function extractErrorMessage(body) {
     const parsed = JSON.parse(trimmed);
     if (parsed && typeof parsed === "object") {
       const obj = parsed;
-      if (typeof obj.message === "string" && obj.message.length > 0) return obj.message;
-      if (typeof obj.error === "string" && obj.error.length > 0) return obj.error;
+      const message = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : typeof obj.error === "string" && obj.error.length > 0 ? obj.error : void 0;
+      if (message !== void 0) {
+        const details = formatApiErrorData(obj.data);
+        return details ? `${message}
+${details}` : message;
+      }
     }
   } catch {
   }
@@ -31205,6 +31620,15 @@ function describeBudgetExhaustion(budgetMs, queuedForMs, lastTransportError) {
   }
   return `Request budget of ${budgetMs}ms exhausted before attempt could begin.`;
 }
+function annotateAmbiguousDelete(error51, status, method, priorGatewayStatus, priorTransportError) {
+  if (status !== 404 || method.toUpperCase() !== "DELETE") return error51;
+  const causes = [];
+  if (priorGatewayStatus !== void 0) causes.push(`returned HTTP ${priorGatewayStatus}`);
+  if (priorTransportError !== void 0) causes.push(`never returned a response (${priorTransportError})`);
+  if (causes.length === 0) return error51;
+  const subject = causes.length > 1 ? "earlier attempts" : "an earlier attempt";
+  return `${error51 || `HTTP ${status}`} (${subject} ${causes.join(" and ")}; the delete may already have succeeded)`;
+}
 async function apiRequest(method, path, body, options) {
   const headers = {};
   if (options?.accept) {
@@ -31238,16 +31662,20 @@ async function apiRequest(method, path, body, options) {
     headers.Authorization = await getAuthHeader();
     let res;
     let lastTransportError;
+    let priorGatewayStatus;
+    let priorTransportError;
+    let budgetMs = requestBudgetMs;
     for (let attempt = 0; attempt <= MAX_429_RETRIES; attempt++) {
-      const remaining = requestBudgetMs - (Date.now() - startedAt);
+      const remaining = budgetMs - (Date.now() - startedAt);
       if (remaining <= 0) {
         return {
           ok: false,
           status: 0,
-          error: describeBudgetExhaustion(requestBudgetMs, queuedForMs, lastTransportError)
+          error: describeBudgetExhaustion(budgetMs, queuedForMs, lastTransportError)
         };
       }
       const attemptTimeoutMs = Math.min(REQUEST_TIMEOUT_MS, remaining);
+      const attemptStartedAt = Date.now();
       let attemptRes;
       try {
         attemptRes = await executeFetch(method, url2, headers, fetchBody, attemptTimeoutMs);
@@ -31259,25 +31687,35 @@ async function apiRequest(method, path, body, options) {
         }
         const delay2 = compute429DelayMs(null, attempt);
         const elapsed3 = Date.now() - startedAt;
-        if (requestBudgetMs - elapsed3 - delay2 <= 0) {
+        if (budgetMs - elapsed3 - delay2 <= 0) {
           return { ok: false, status: 0, error: `${desc}; request budget exhausted before retry.` };
         }
         debugLog(
           `  -> transport error (attempt ${attempt + 1}/${MAX_429_RETRIES + 1}): ${desc}, retrying in ${delay2}ms`
         );
+        priorTransportError = desc;
         await new Promise((r) => setTimeout(r, delay2));
         continue;
       }
       res = attemptRes;
-      if (res.status !== 429 || attempt === MAX_429_RETRIES || !isRetryable) break;
+      if (!RETRYABLE_STATUSES.has(res.status) || attempt === MAX_429_RETRIES || !isRetryable) break;
       const delay = compute429DelayMs(res.headers.get("retry-after"), attempt);
+      const gatewayCeilingMs = Math.min(budgetMs, Math.floor(requestBudgetMs * GATEWAY_5XX_BUDGET_FRACTION));
+      const retryCeilingMs = res.status === 429 ? budgetMs : gatewayCeilingMs;
       const elapsed2 = Date.now() - startedAt;
-      const nextAttemptBudgetMs = requestBudgetMs - elapsed2 - delay;
+      const predictedCostMs = res.status === 429 ? delay : delay + (Date.now() - attemptStartedAt);
+      const nextAttemptBudgetMs = retryCeilingMs - elapsed2 - predictedCostMs;
       if (nextAttemptBudgetMs <= 0) {
-        debugLog(`  -> 429 (attempt ${attempt + 1}), giving up: budget exhausted (${elapsed2}ms + ${delay}ms)`);
+        debugLog(
+          `  -> ${res.status} (attempt ${attempt + 1}), giving up: budget exhausted (${elapsed2}ms + ${predictedCostMs}ms of ${retryCeilingMs}ms)`
+        );
         break;
       }
-      debugLog(`  -> 429 (attempt ${attempt + 1}/${MAX_429_RETRIES + 1}), retrying in ${delay}ms`);
+      debugLog(`  -> ${res.status} (attempt ${attempt + 1}/${MAX_429_RETRIES + 1}), retrying in ${delay}ms`);
+      if (res.status !== 429) {
+        priorGatewayStatus = res.status;
+        budgetMs = retryCeilingMs;
+      }
       await res.text().catch(() => void 0);
       await new Promise((r) => setTimeout(r, delay));
     }
@@ -31293,14 +31731,25 @@ async function apiRequest(method, path, body, options) {
         const rawBody = await response.text();
         if (!response.ok) {
           const error51 = response.status === 401 || response.status === 403 ? formatAuthError(response.status, rawBody) : extractErrorMessage(rawBody);
-          return { ok: false, status: response.status, error: error51, rawBody, etag };
+          return {
+            ok: false,
+            status: response.status,
+            error: annotateAmbiguousDelete(error51, response.status, method, priorGatewayStatus, priorTransportError),
+            rawBody,
+            etag
+          };
         }
         return { ok: true, status: response.status, rawBody, etag };
       }
       if (!response.ok) {
         const errorBody = await response.text();
         const error51 = response.status === 401 || response.status === 403 ? formatAuthError(response.status, errorBody) : extractErrorMessage(errorBody);
-        return { ok: false, status: response.status, error: error51, etag };
+        return {
+          ok: false,
+          status: response.status,
+          error: annotateAmbiguousDelete(error51, response.status, method, priorGatewayStatus, priorTransportError),
+          etag
+        };
       }
       if (response.status === 204 || response.headers.get("content-length") === "0") {
         return { ok: true, status: response.status, etag };
@@ -31334,26 +31783,43 @@ async function apiDelete(path, options) {
 }
 
 // src/cli.ts
+function isWarningsOnly(message, data) {
+  if (!/^warning/i.test(message)) return false;
+  if (!Array.isArray(data) || data.length === 0) return false;
+  return data.every((entry) => {
+    if (entry === null || typeof entry !== "object" || Array.isArray(entry)) return false;
+    const obj = entry;
+    if (!Object.keys(obj).every((key) => key === "user" || key === "warnings")) return false;
+    if (obj.user !== void 0 && typeof obj.user !== "string") return false;
+    return Array.isArray(obj.warnings) && obj.warnings.length > 0 && obj.warnings.every((w) => typeof w === "string");
+  });
+}
 function parseValidationError(rawBody) {
   const trimmed = rawBody?.trim();
-  if (!trimmed) return void 0;
+  if (!trimmed) return { kind: "valid" };
   let parsed;
   try {
     parsed = JSON.parse(trimmed);
   } catch {
-    return trimmed;
+    return { kind: "failure", message: trimmed };
   }
   if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
-    return trimmed;
+    return { kind: "failure", message: trimmed };
   }
   const obj = parsed;
-  if (typeof obj.message === "string" && obj.message.length > 0) return obj.message;
-  if (typeof obj.error === "string" && obj.error.length > 0) return obj.error;
-  return void 0;
+  const message = typeof obj.message === "string" && obj.message.length > 0 ? obj.message : typeof obj.error === "string" && obj.error.length > 0 ? obj.error : void 0;
+  if (message === void 0) return { kind: "valid" };
+  const details = formatApiErrorData(obj.data);
+  return {
+    kind: isWarningsOnly(message, obj.data) ? "warnings" : "failure",
+    message,
+    ...details ? { details } : {}
+  };
 }
 function readPolicyFile(filePath) {
   try {
-    return readFileSync(filePath, "utf-8");
+    const text = readFileSync(filePath, "utf-8");
+    return text.charCodeAt(0) === 65279 ? text.slice(1) : text;
   } catch (err) {
     console.error(`Failed to read ${filePath}: ${err instanceof Error ? err.message : err}`);
     process.exit(1);
@@ -31370,9 +31836,10 @@ async function validatePolicy(policy) {
     console.error(`ACL validation failed: ${validateRes.error}`);
     process.exit(1);
   }
-  const validationError = parseValidationError(validateRes.rawBody);
-  if (validationError) {
-    console.error(`ACL validation failed: ${validationError}`);
+  const validation = parseValidationError(validateRes.rawBody);
+  if (validation.kind !== "valid") {
+    console.error(`ACL validation failed: ${validation.message}${validation.details ? `
+${validation.details}` : ""}`);
     process.exit(1);
   }
 }
@@ -31542,6 +32009,17 @@ function stripEtagFooter(body) {
   }
   return lines.slice(0, cut).join("\n");
 }
+function normalizeIfMatch(etag) {
+  const trimmed = etag.trim();
+  if (trimmed.startsWith("W/")) return trimmed;
+  const inner = trimmed.replace(/^"+|"+$/g, "").trim();
+  if (!inner) {
+    throw new Error(
+      "etag is empty once its quotes are removed -- a value with nothing inside its quotes cannot match any ETag the tailnet holds, so this overwrite would come back 412."
+    );
+  }
+  return `"${inner}"`;
+}
 var aclTools = [
   {
     name: "tailscale_get_acl",
@@ -31574,7 +32052,7 @@ var aclTools = [
   },
   {
     name: "tailscale_update_acl",
-    description: "Update the ACL policy for your tailnet. Accepts the full policy as a string to preserve formatting, comments, and trailing commas (HuJSON). You MUST pass the ETag from tailscale_get_acl to prevent overwriting concurrent changes. Always get the current ACL first, make targeted edits to the text, and pass the full modified text back.",
+    description: "Update the ACL policy for your tailnet. Accepts the full policy as a string to preserve formatting, comments, and trailing commas (HuJSON). You MUST pass the ETag from tailscale_get_acl to prevent overwriting concurrent changes, or `ts-default` for the first write to a tailnet nobody has edited yet. Always get the current ACL first, make targeted edits to the text, and pass the full modified text back.",
     annotations: {
       title: "Update ACL policy",
       readOnlyHint: false,
@@ -31589,7 +32067,9 @@ var aclTools = [
       policy: external_exports.string().describe(
         "The full ACL policy text. Preserve existing formatting, comments, and structure. Only modify the specific parts that need to change."
       ),
-      etag: external_exports.string().trim().min(1, "etag must not be empty -- an empty ETag would send this overwrite with no concurrency guard.").describe("The ETag from tailscale_get_acl. Required to prevent concurrent edit conflicts.")
+      etag: external_exports.string().trim().min(1, "etag must not be empty -- an empty ETag would send this overwrite with no concurrency guard.").describe(
+        "The ETag from tailscale_get_acl (quotes optional -- they are normalized). Required to prevent concurrent edit conflicts. For the FIRST write to a fresh tailnet you may pass `ts-default` instead: the update then succeeds only if the policy file is still Tailscale's untouched default."
+      )
     }),
     // `.trim().min(1)`, not a bare `z.string()`: apiRequest sets If-Match behind
     // `if (options?.ifMatch)`, so an empty etag is falsy there and the header is
@@ -31599,11 +32079,15 @@ var aclTools = [
     // on tailnets.ts's ids: a bare `.min(1)` accepts " ", which is truthy, so the
     // header goes out carrying a precondition that cannot match any real ETag --
     // a confusing 412 instead of a local validation error naming the field.
+    // Quote normalization lives in the handler rather than in the schema because
+    // this is the code that builds the header, and because the handlers are what
+    // the tests call directly -- a transform on the schema would be invisible to
+    // every assertion made at the header.
     handler: async (input) => {
       return apiPost(`/tailnet/${getTailnet()}/acl`, void 0, {
         rawBody: input.policy,
         contentType: "application/hujson",
-        ifMatch: input.etag,
+        ifMatch: normalizeIfMatch(input.etag),
         acceptRaw: true,
         accept: "application/hujson"
       });
@@ -31834,9 +32318,9 @@ function assertRFC3339(value, label) {
   }
 }
 var MAX_LOG_RANGE_MS = 30 * 24 * 60 * 60 * 1e3;
-function assertLogRange(start, end, label) {
+function assertLogRange(start, end, label, nowMs = Date.now()) {
   const startMs = Date.parse(start);
-  const endMs = end ? Date.parse(end) : Date.now();
+  const endMs = end ? Date.parse(end) : nowMs;
   if (endMs < startMs) {
     throw new Error(`${label}: end must be >= start. start=${start} end=${end ?? "<now>"}`);
   }
@@ -31846,10 +32330,14 @@ function assertLogRange(start, end, label) {
     );
   }
 }
+function isoSecond(now) {
+  const pad = (value, width = 2) => String(value).padStart(width, "0");
+  return `${pad(now.getUTCFullYear(), 4)}-${pad(now.getUTCMonth() + 1)}-${pad(now.getUTCDate())}T${pad(now.getUTCHours())}:${pad(now.getUTCMinutes())}:${pad(now.getUTCSeconds())}Z`;
+}
 var auditTools = [
   {
     name: "tailscale_get_audit_log",
-    description: "Get the tailnet audit/configuration log. Shows who changed what and when \u2014 useful for troubleshooting and compliance.",
+    description: "Get the tailnet audit/configuration log. Shows who changed what and when -- useful for troubleshooting and compliance. Optional actor, target and event filters narrow the query server-side, so a targeted question doesn't have to pull the whole window.",
     annotations: {
       title: "Get audit log",
       readOnlyHint: true,
@@ -31857,16 +32345,46 @@ var auditTools = [
       idempotentHint: true,
       openWorldHint: true
     },
+    // The three filters are free strings rather than the spec's 138-value event
+    // enum: that list is still growing (the PAM_* entries are recent), and a
+    // hard enum would make a new event type unqueryable rather than merely
+    // unvalidated. `.trim().min(1)` is the house idiom -- a bare min(1) admits
+    // " ", which goes on the wire as `event=+...` and comes back empty with no
+    // error.
+    //
+    // `.max(1)` for now. The spec declares no style/explode on these array
+    // parameters, so repeated keys are inferred from the OpenAPI default and
+    // nothing upstream corroborates it: neither the Go client nor Terraform
+    // implements this endpoint, and the KB page documents only start and end. A
+    // single value is wire-identical whether the server wants repeated keys or a
+    // comma-joined list, so it cannot under-report; two values under the wrong
+    // guess would return a subset with no error, which in a compliance query
+    // reads as "that change never happened". Lift the cap once a live call
+    // settles it.
     inputSchema: external_exports.object({
       start: external_exports.string().describe("Start time in RFC3339 format (e.g. '2026-04-01T00:00:00Z'). Required."),
-      end: external_exports.string().optional().describe("End time in RFC3339 format. Defaults to now.")
+      end: external_exports.string().optional().describe(
+        "End time in RFC3339 format. Optional: when omitted the tool sends the current time, which Tailscale's API requires."
+      ),
+      actor: external_exports.array(external_exports.string().trim().min(1)).max(1).optional().describe(
+        "Server-side filter: one exact actor ID, or '~text' to wildcard-match a login or display name (e.g. '~bob'). One value per call -- how the API reads a repeated filter key is not verified yet."
+      ),
+      target: external_exports.array(external_exports.string().trim().min(1)).max(1).optional().describe(
+        "Server-side filter: one string, matched against any part of any of an entry's targets (ID or name). One value per call, as for actor."
+      ),
+      event: external_exports.array(external_exports.string().trim().min(1)).max(1).optional().describe(
+        "Server-side filter: one event type from Tailscale's audit event list, e.g. 'TAILNET.UPDATE.ACL', 'TAILNET.UPDATE.DNS_CONFIG', 'NODE.CREATE', 'NODE.DELETE', 'API_KEY.CREATE', 'USER.UPDATE.USER_ROLE', 'WEBHOOK_ENDPOINT.CREATE'. Not a closed set -- the list keeps growing. One value per call, as for actor."
+      )
     }),
     handler: async (input) => {
       assertRFC3339(input.start, "start");
       if (input.end) assertRFC3339(input.end, "end");
-      assertLogRange(input.start, input.end, "tailscale_get_audit_log");
-      const params = new URLSearchParams({ start: input.start });
-      if (input.end) params.set("end", input.end);
+      const wireEnd = input.end ? input.end : isoSecond(/* @__PURE__ */ new Date());
+      assertLogRange(input.start, input.end, "tailscale_get_audit_log", Date.parse(wireEnd));
+      const params = new URLSearchParams({ start: input.start, end: wireEnd });
+      for (const actor of input.actor ?? []) params.append("actor", actor);
+      for (const target of input.target ?? []) params.append("target", target);
+      for (const event of input.event ?? []) params.append("event", event);
       return apiGet(`/tailnet/${getTailnet()}/logging/configuration?${params}`);
     }
   },
@@ -31880,16 +32398,20 @@ var auditTools = [
       idempotentHint: true,
       openWorldHint: true
     },
+    // The spec gives this endpoint no actor/target/event filters -- they are on
+    // the configuration log only.
     inputSchema: external_exports.object({
       start: external_exports.string().describe("Start time in RFC3339 format (e.g. '2026-04-01T00:00:00Z'). Required."),
-      end: external_exports.string().optional().describe("End time in RFC3339 format. Defaults to now.")
+      end: external_exports.string().optional().describe(
+        "End time in RFC3339 format. Optional: when omitted the tool sends the current time, which Tailscale's API requires."
+      )
     }),
     handler: async (input) => {
       assertRFC3339(input.start, "start");
       if (input.end) assertRFC3339(input.end, "end");
-      assertLogRange(input.start, input.end, "tailscale_get_network_flow_logs");
-      const params = new URLSearchParams({ start: input.start });
-      if (input.end) params.set("end", input.end);
+      const wireEnd = input.end ? input.end : isoSecond(/* @__PURE__ */ new Date());
+      assertLogRange(input.start, input.end, "tailscale_get_network_flow_logs", Date.parse(wireEnd));
+      const params = new URLSearchParams({ start: input.start, end: wireEnd });
       return apiGet(`/tailnet/${getTailnet()}/logging/network?${params}`);
     }
   }
@@ -31908,10 +32430,12 @@ function isCidr(s) {
   if (net.isIPv6(addr)) return prefixN <= 128;
   return false;
 }
+var DEVICE_FIELDS_DESC = "Which device fields to return. Tailscale documents exactly two values. 'default' (also what you get when this is omitted) is the limited set: addresses, id, nodeId, user, name, hostname, clientVersion, updateAvailable, os, created, connectedToControl, lastSeen, keyExpiryDisabled, expires, authorized, isExternal, machineKey, nodeKey, blocksIncomingConnections, tailnetLockKey, tailnetLockError, tags, isEphemeral. 'all' adds advertisedRoutes, enabledRoutes, clientConnectivity (endpoints, DERP latency), sshEnabled, distro, multipleConnections and postureIdentity (serial numbers and, where a posture integration collects them, hardware/MAC addresses). Omitting it does NOT return everything.";
+var DEVICE_LAST_SEEN_NOTE = " 'lastSeen' is omitted while a device is connected (connectedToControl: true) and for devices that have never been online -- on a connected device a missing lastSeen means online now, not never seen.";
 var deviceTools = [
   {
     name: "tailscale_list_devices",
-    description: "List all devices in your tailnet with their status, IP addresses, OS, and last seen time.",
+    description: `List all devices in your tailnet with their status, IP addresses, OS, and last seen time.${DEVICE_LAST_SEEN_NOTE}`,
     annotations: {
       title: "List devices",
       readOnlyHint: true,
@@ -31920,11 +32444,9 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      fields: external_exports.string().optional().describe(
-        "Comma-separated list of fields to include. Omit for all fields. Valid fields: addresses, advertisedRoutes, authorized, blocksIncomingConnections, clientConnectivity, clientVersion, connectedToControl, created, distro, enabledRoutes, expires, hostname, id, isExternal, keyExpiryDisabled, lastSeen, machineKey, name, nodeId, nodeKey, os, sshEnabled, tags, tailnetLockError, tailnetLockKey, updateAvailable, user. Use 'all' for every field."
-      ),
-      filters: external_exports.record(external_exports.string(), external_exports.string()).optional().describe(
-        "Server-side filters as key-value pairs. Filter by any top-level device property (e.g. { isEphemeral: 'true', os: 'linux', tags: 'tag:prod' }). Multiple filters are ANDed together."
+      fields: external_exports.string().optional().describe(`${DEVICE_FIELDS_DESC} Any other value is forwarded unvalidated; Tailscale documents none.`),
+      filters: external_exports.record(external_exports.string(), external_exports.union([external_exports.string(), external_exports.array(external_exports.string()).min(1)])).optional().describe(
+        "Server-side filters on top-level device properties, exact match only (e.g. { isEphemeral: 'true', os: 'linux' }). All filters are ANDed. Pass an array to repeat a key: { tags: ['tag:prod', 'tag:subnetrouter'] } sends tags=..&tags=.. and matches devices whose tags contain BOTH. Properties that are complex objects (e.g. clientConnectivity) cannot be filtered; repeating a key on a non-list property is undocumented upstream."
       )
     }),
     handler: async (input) => {
@@ -31937,7 +32459,7 @@ var deviceTools = [
               "filters.fields is not allowed -- use the top-level 'fields' parameter to select which device fields to return."
             );
           }
-          params.set(key, value);
+          for (const one of Array.isArray(value) ? value : [value]) params.append(key, one);
         }
       }
       const qs = params.toString();
@@ -31946,7 +32468,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_get_device",
-    description: "Get detailed information about a specific device by its ID.",
+    description: `Get detailed information about a specific device by its ID. Returns the default field subset unless fields: 'all'.${DEVICE_LAST_SEEN_NOTE}`,
     annotations: {
       title: "Get device",
       readOnlyHint: true,
@@ -31955,10 +32477,14 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID (numeric id or nodeId, NOT the nodeKey)")
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
+      fields: external_exports.enum(["all", "default"]).optional().describe(DEVICE_FIELDS_DESC)
     }),
     handler: async (input) => {
-      return apiGet(`/device/${encPath(input.deviceId)}`);
+      const params = new URLSearchParams();
+      if (input.fields) params.set("fields", input.fields);
+      const qs = params.toString();
+      return apiGet(`/device/${encPath(input.deviceId)}${qs ? `?${qs}` : ""}`);
     }
   },
   {
@@ -31972,7 +32498,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to authorize")
+      deviceId: external_exports.string().describe(`The device ID to authorize. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiPost(`/device/${encPath(input.deviceId)}/authorized`, { authorized: true });
@@ -31989,7 +32515,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to deauthorize")
+      deviceId: external_exports.string().describe(`The device ID to deauthorize. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiPost(`/device/${encPath(input.deviceId)}/authorized`, { authorized: false });
@@ -32006,7 +32532,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to delete")
+      deviceId: external_exports.string().describe(`The device ID to delete. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiDelete(`/device/${encPath(input.deviceId)}`);
@@ -32014,7 +32540,7 @@ var deviceTools = [
   },
   {
     name: "tailscale_rename_device",
-    description: "Set the name of a device in the tailnet.",
+    description: "Set the name of a device in the tailnet, or reset it to its OS hostname.",
     annotations: {
       title: "Rename device",
       readOnlyHint: false,
@@ -32023,8 +32549,10 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to rename"),
-      name: external_exports.string().describe("The new name for the device (FQDN within your tailnet)")
+      deviceId: external_exports.string().describe(`The device ID to rename. ${DEVICE_ID_HINT}`),
+      name: external_exports.string().describe(
+        "New device name: the FQDN (e.g. 'nodename.your-tailnet.ts.net') or just the base name (e.g. 'nodename'). Pass an empty string to reset the name to one generated from the OS hostname (per Tailscale's API spec)."
+      )
     }),
     handler: async (input) => {
       return apiPost(`/device/${encPath(input.deviceId)}/name`, { name: input.name });
@@ -32041,7 +32569,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to expire")
+      deviceId: external_exports.string().describe(`The device ID to expire. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiPost(`/device/${encPath(input.deviceId)}/expire`);
@@ -32058,7 +32586,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID")
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiGet(`/device/${encPath(input.deviceId)}/routes`);
@@ -32077,7 +32605,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
       routes: external_exports.array(external_exports.string().refine(isCidr, { message: "must be a CIDR (e.g. '10.0.0.0/24' or 'fd7a:115c::/48')" })).describe(
         "Full list of CIDR routes to enable (e.g. ['10.0.0.0/24', '192.168.1.0/24']). Replaces existing enabled routes."
       )
@@ -32097,7 +32625,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID")
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiGet(`/device/${encPath(input.deviceId)}/attributes`);
@@ -32114,12 +32642,22 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID"),
-      attributeKey: external_exports.string().describe("The attribute key (must start with 'custom:', e.g. 'custom:lastAuditDate')"),
-      value: external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()]).describe("The attribute value (string, number, or boolean)"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
+      // The length and charset rules below are Tailscale's, and Tailscale is
+      // the one that enforces them -- only the 'custom:' prefix is checked
+      // client-side, because that one is a namespace choice an agent gets
+      // wrong by accident. A local regex for the rest would be one more thing
+      // to drift out of step with the API's own error.
+      attributeKey: external_exports.string().describe(
+        "The attribute key (must start with 'custom:', e.g. 'custom:lastAuditDate'). Max 128 characters including the prefix; letters, numbers, underscores and colons only. Keys are case-sensitive but are checked for uniqueness case-insensitively, so 'custom:MyAttribute' and 'custom:myattribute' cannot both exist in one tailnet."
+      ),
+      value: external_exports.union([external_exports.string(), external_exports.number(), external_exports.boolean()]).describe(
+        "The attribute value: a string (max 50 characters, letters, numbers, underscores and periods only), an integer number (JSON-safe, up to 2^53-1), or a boolean. The type is fixed by the first value written for a key -- every device's value for that key must then be the same type."
+      ),
       expiry: external_exports.string().optional().describe(
         "Optional expiry time in RFC3339 format (e.g. '2026-12-01T00:00:00Z'). Attribute is automatically removed after expiry."
-      )
+      ),
+      comment: external_exports.string().max(200).optional().describe("Optional comment added to the audit log explaining why the attribute is being set (max 200 chars)")
     }),
     handler: async (input) => {
       if (!input.attributeKey.startsWith("custom:")) {
@@ -32127,6 +32665,7 @@ var deviceTools = [
       }
       const body = { value: input.value };
       if (input.expiry !== void 0) body.expiry = input.expiry;
+      if (input.comment !== void 0) body.comment = input.comment;
       return apiPost(`/device/${encPath(input.deviceId)}/attributes/${encPath(input.attributeKey)}`, body);
     }
   },
@@ -32141,7 +32680,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
       attributeKey: external_exports.string().describe("The attribute key to delete (e.g. 'custom:lastAuditDate')")
     }),
     handler: async (input) => {
@@ -32164,7 +32703,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
       tags: external_exports.array(external_exports.string()).describe("Full list of ACL tags (e.g. ['tag:server', 'tag:production']). Replaces all existing tags.")
     }),
     handler: async (input) => {
@@ -32183,7 +32722,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
       ipv4: external_exports.ipv4().describe("The new Tailscale IPv4 address for the device (e.g. '100.64.0.1')")
     }),
     handler: async (input) => {
@@ -32201,7 +32740,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
       keyExpiryDisabled: external_exports.boolean().describe("Whether to disable key expiry for this device")
     }),
     handler: async (input) => {
@@ -32223,7 +32762,7 @@ var deviceTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceIds: external_exports.array(external_exports.string().min(1)).min(1).describe("Device IDs to update"),
+      deviceIds: external_exports.array(external_exports.string().min(1)).min(1).describe("Device IDs to update (nodeIds preferred; legacy numeric ids also work)"),
       authorized: external_exports.boolean().describe("true to authorize, false to deauthorize")
     }),
     handler: async (input) => {
@@ -32276,7 +32815,7 @@ var deviceTools = [
           ])
         )
       ).describe(
-        'Map of device ID to attribute config map (e.g. { "12345": { "custom:compliant": { "value": "true" } }, "67890": { "custom:compliant": { "value": false, "expiry": "2026-12-01T00:00:00Z" } } }). Pass null as the config to delete an attribute.'
+        'Map of device ID to attribute config map (e.g. { "nPM2KNuedB21DEVEL": { "custom:compliant": { "value": "true" } }, "nPpz3VEKzX11DEVEL": { "custom:compliant": { "value": false, "expiry": "2026-12-01T00:00:00Z" } } }). Keys are device IDs, nodeIds preferred. Pass null as the config to delete an attribute.'
       ),
       comment: external_exports.string().max(200).optional().describe("Optional comment added to the audit log explaining why attributes are being set (max 200 chars)")
     }),
@@ -32318,7 +32857,7 @@ var dnsTools = [
   },
   {
     name: "tailscale_set_nameservers",
-    description: "Set the DNS nameservers for your tailnet. Replaces all existing nameservers.",
+    description: "Set the DNS nameservers for your tailnet. Replaces all existing nameservers. Removing every nameserver may also change MagicDNS: the API reference says it is switched off, while Tailscale's current MagicDNS docs say a nameserver is no longer required -- check `magicDNS` in the response.",
     annotations: {
       title: "Set nameservers",
       readOnlyHint: false,
@@ -32387,7 +32926,7 @@ var dnsTools = [
   },
   {
     name: "tailscale_set_split_dns",
-    description: "Set split DNS configuration. Maps domains to specific nameservers. Replaces the entire split DNS configuration.",
+    description: "Set split DNS configuration. Maps domains to specific nameservers. Replaces the entire split DNS configuration: a domain you leave out is removed, and an empty object clears every domain. Per the API reference, setting a domain to null clears that domain's nameservers.",
     annotations: {
       title: "Set split DNS",
       readOnlyHint: false,
@@ -32398,8 +32937,11 @@ var dnsTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      splitDns: external_exports.record(external_exports.string(), external_exports.array(external_exports.string())).describe(
-        'Map of domain to nameserver list (e.g. { "corp.example.com": ["10.0.0.1"], "internal.dev": ["10.0.0.2"] })'
+      // `.nullable()` per the spec's SplitDns schema, which types each value as
+      // an array OR null. Forwarded verbatim below, so null reaches the API as
+      // JSON null rather than being pruned.
+      splitDns: external_exports.record(external_exports.string(), external_exports.array(external_exports.string()).nullable()).describe(
+        'Map of domain to nameserver list, or to null to clear that domain (e.g. { "corp.example.com": ["10.0.0.1"], "old.example.com": null })'
       )
     }),
     handler: async (input) => {
@@ -32423,7 +32965,7 @@ var dnsTools = [
   },
   {
     name: "tailscale_set_dns_preferences",
-    description: "Set DNS preferences for your tailnet, such as enabling or disabling MagicDNS.",
+    description: "Set DNS preferences for your tailnet, such as enabling or disabling MagicDNS. The API reference says enabling can fail when the tailnet has no nameservers; if it does, add one with tailscale_set_nameservers first.",
     annotations: {
       title: "Set DNS preferences",
       readOnlyHint: false,
@@ -32442,7 +32984,7 @@ var dnsTools = [
   },
   {
     name: "tailscale_update_split_dns",
-    description: "Partially update split DNS configuration. Merges the provided domains with the existing config \u2014 only the specified domains are changed, others are untouched. Set a domain's nameservers to an empty array to remove it.",
+    description: "Partially update split DNS configuration. Merges the provided domains with the existing config -- only the specified domains are changed, others are untouched. To remove a domain, set it to null: that is the idiom the API reference documents. An empty array is also accepted and forwarded as-is -- it is what Tailscale's Terraform provider sends.",
     annotations: {
       title: "Update split DNS (partial)",
       readOnlyHint: false,
@@ -32451,8 +32993,11 @@ var dnsTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      splitDns: external_exports.record(external_exports.string(), external_exports.array(external_exports.string())).describe(
-        'Map of domain to nameserver list to merge (e.g. { "new.example.com": ["10.0.0.3"] }). Only specified domains are changed.'
+      // Nullable for the same reason as the PUT sibling above: the spec's
+      // SplitDns body types each value as an array OR null, and null is how it
+      // documents clearing a domain.
+      splitDns: external_exports.record(external_exports.string(), external_exports.array(external_exports.string()).nullable()).describe(
+        'Map of domain to nameserver list to merge, or to null to remove that domain (e.g. { "new.example.com": ["10.0.0.3"], "old.example.com": null }). Only specified domains are changed.'
       )
     }),
     handler: async (input) => {
@@ -32519,7 +33064,7 @@ var inviteTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to list invites for")
+      deviceId: external_exports.string().describe(`The device ID to list invites for. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiGet(`/device/${encPath(input.deviceId)}/device-invites`);
@@ -32536,7 +33081,7 @@ var inviteTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      deviceId: external_exports.string().describe("The device ID to create an invite for"),
+      deviceId: external_exports.string().describe(`The device ID to create an invite for. ${DEVICE_ID_HINT}`),
       multiUse: external_exports.boolean().optional().describe("Whether the invite can be used more than once (default: false)"),
       allowExitNode: external_exports.boolean().optional().describe("Whether the invited device can be used as an exit node (default: false)"),
       email: external_exports.email().optional().describe("Email address to send the invite to")
@@ -32603,7 +33148,7 @@ var inviteTools = [
   // --- User Invites ---
   {
     name: "tailscale_list_user_invites",
-    description: "List all user invites for your tailnet.",
+    description: "List the open (not yet accepted) user invites for your tailnet. Accepted invites are not returned.",
     annotations: {
       title: "List user invites",
       readOnlyHint: true,
@@ -32713,7 +33258,7 @@ var inviteTools = [
 var keyTools = [
   {
     name: "tailscale_list_keys",
-    description: "List keys in your tailnet. By default lists auth keys only. Set 'all' to true to include OAuth clients and federated identities.",
+    description: "List keys in your tailnet: auth keys, API access tokens, OAuth clients and federated identities. Without 'all', what comes back depends on the credential this server runs on -- a user-owned API key sees only that user's keys (including the API access token the server itself is using, keyType 'api'); an OAuth-client token sees the tailnet's OAuth clients; a federated-identity token sees its federated identities. Set 'all' to true for the tailnet-wide list (needs the matching :read scopes; only 'all:read' and 'all' return every API access token).",
     annotations: {
       title: "List keys",
       readOnlyHint: true,
@@ -32722,7 +33267,7 @@ var keyTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      all: external_exports.boolean().optional().describe("When true, returns all key types (auth keys, OAuth clients, federated identities). Default: false")
+      all: external_exports.boolean().optional().describe("When true, list keys tailnet-wide instead of the credential-dependent default set. Default: false")
     }),
     handler: async (input) => {
       const qs = input.all ? "?all=true" : "";
@@ -32731,7 +33276,7 @@ var keyTools = [
   },
   {
     name: "tailscale_get_key",
-    description: "Get details for a specific key (auth key, OAuth client, or federated identity).",
+    description: "Get details for a specific key (auth key, API access token, OAuth client, or federated identity). A revoked or expired key is still returned, with `invalid: true`.",
     annotations: {
       title: "Get key",
       readOnlyHint: true,
@@ -32740,7 +33285,7 @@ var keyTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      keyId: external_exports.string().describe("The key ID (auth key, OAuth client, or federated identity)")
+      keyId: external_exports.string().describe("The key ID (auth key, API access token, OAuth client, or federated identity)")
     }),
     handler: async (input) => {
       return apiGet(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`);
@@ -32748,7 +33293,7 @@ var keyTools = [
   },
   {
     name: "tailscale_create_key",
-    description: "Create a new key in your tailnet. Supports auth keys (for adding devices), OAuth clients (for programmatic API access), and federated identities (for OIDC-based CI/CD access). Returns the key value \u2014 save it immediately, as it cannot be retrieved again.\n\nSECURITY: the response body contains a long-lived credential verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive (do not commit it, avoid re-sharing it in unrelated chat history).\n\nExamples:\n- Auth key: {keyType:'auth', reusable:true, tags:['tag:ci']}\n- OAuth client: {keyType:'client', scopes:['devices:read','dns']}\n- Federated (GitHub Actions): {keyType:'federated', scopes:['devices:read'], issuer:'https://token.actions.githubusercontent.com', subject:'repo:my-org/my-repo:*'}",
+    description: "Create a new key in your tailnet. Supports auth keys (for adding devices), OAuth clients (for programmatic API access), and federated identities (for OIDC-based CI/CD access). Returns the key value -- save it immediately, as it cannot be retrieved again.\n\nSECURITY: the response body contains a long-lived credential verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive (do not commit it, avoid re-sharing it in unrelated chat history).\n\nExamples:\n- Auth key: {keyType:'auth', reusable:true, tags:['tag:ci']}\n- OAuth client: {keyType:'client', scopes:['devices:core:read','dns:read']}\n- Federated (GitHub Actions): {keyType:'federated', scopes:['devices:core:read'], issuer:'https://token.actions.githubusercontent.com', subject:'repo:my-org/my-repo:*'}",
     annotations: {
       title: "Create key",
       readOnlyHint: false,
@@ -32771,7 +33316,9 @@ var keyTools = [
         "ACL tags (must start with 'tag:'). Required for client/federated if scopes include 'devices:core' or 'auth_keys'"
       ),
       // Client + Federated fields
-      scopes: external_exports.array(external_exports.string()).optional().describe("(client/federated) OAuth scopes to grant (e.g. ['devices:read', 'dns', 'acl'])"),
+      scopes: external_exports.array(external_exports.string()).optional().describe(
+        "(client/federated) OAuth scopes to grant (e.g. ['devices:core:read', 'dns:read']). Use the current scope names listed at https://tailscale.com/kb/1623/trust-credentials#scopes; the pre-2024 names such as 'devices:read' and 'acl' are legacy."
+      ),
       // Federated-only fields
       issuer: external_exports.string().optional().describe("(federated only) OIDC issuer URL (e.g. 'https://token.actions.githubusercontent.com')"),
       subject: external_exports.string().optional().describe("(federated only) Expected subject claim, supports * wildcards"),
@@ -32834,7 +33381,7 @@ var keyTools = [
   },
   {
     name: "tailscale_delete_key",
-    description: "Delete a key (auth key, OAuth client, or federated identity). This is irreversible. For auth keys, devices already authenticated are unaffected but no new devices can use it. For OAuth clients and federated identities, any integrations using them lose access immediately.",
+    description: "Delete a key (auth key, API access token, OAuth client, or federated identity). This is irreversible. For auth keys, devices already authenticated are unaffected but no new devices can use it. For OAuth clients and federated identities, any integrations using them lose access immediately. API access tokens are deletable here too: if keyId is the token this server authenticates with -- it shows up in tailscale_list_keys under API-key auth -- the server revokes its own credential and every later call fails with 401 until it is reconfigured.",
     annotations: {
       title: "Delete key",
       readOnlyHint: false,
@@ -32843,7 +33390,7 @@ var keyTools = [
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      keyId: external_exports.string().describe("The key ID to delete (auth key, OAuth client, or federated identity)")
+      keyId: external_exports.string().describe("The key ID to delete (auth key, API access token, OAuth client, or federated identity)")
     }),
     handler: async (input) => {
       return apiDelete(`/tailnet/${getTailnet()}/keys/${encPath(input.keyId)}`);
@@ -32894,12 +33441,15 @@ var keyTools = [
   // tailscale_create_key above: an OAuth client is a machine credential you
   // hold, whereas an OAuth App is a three-legged authorization-code app that
   // lets a THIRD PARTY enroll one device into your tailnet after a user
-  // consents. The only scope it takes today is `auth_keys:create:once`, which
-  // mints exactly one auth key per authorization and returns no refresh token
-  // -- re-authorization is required per device by design.
+  // consents. Tailscale's device-provisioning guide documents one scope,
+  // `auth_keys:create:once`, which mints exactly one auth key per authorization
+  // and returns no refresh token -- re-authorization is required per device by
+  // design. The API reference's own example shows the bare `auth_keys:create`
+  // instead, and the schema restricts neither, so the description names both
+  // sources rather than picking one.
   {
     name: "tailscale_create_oauth_app",
-    description: "Create an OAuth App for device provisioning (Tailscale alpha). Lets a third-party application enroll a device into your tailnet via the authorization-code flow, after a user consents. Returns the app's client secret -- save it immediately, it cannot be retrieved again.\n\nSECURITY: the response body contains a long-lived credential verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.\n\nThe supported scope is 'auth_keys:create:once' (one auth key per authorization, no refresh token). Distinct from tailscale_create_key with keyType='client', which mints a machine-to-machine OAuth client instead.",
+    description: "Create an OAuth App for device provisioning (Tailscale alpha). Lets a third-party application enroll a device into your tailnet via the authorization-code flow, after a user consents. Returns the app's client secret -- save it immediately, it cannot be retrieved again.\n\nSECURITY: the response body contains a long-lived credential verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.\n\nUse scope 'auth_keys:create:once' (one auth key per authorization, no refresh token) -- the scope Tailscale's device-provisioning guide documents. The API reference's example shows 'auth_keys:create'; this tool does not restrict the value. Distinct from tailscale_create_key with keyType='client', which mints a machine-to-machine OAuth client instead.",
     annotations: {
       title: "Create OAuth app",
       readOnlyHint: false,
@@ -32910,7 +33460,9 @@ var keyTools = [
     inputSchema: external_exports.object({
       name: external_exports.string().min(1).describe("Human-readable name for the OAuth app, shown on the consent screen"),
       redirectUris: external_exports.array(external_exports.url()).min(1).describe("Allowed redirect URIs for the authorization-code flow (e.g. ['https://example.com/callback'])"),
-      scopes: external_exports.array(external_exports.string()).min(1).describe("Scopes to grant. Currently 'auth_keys:create:once' is the supported value."),
+      scopes: external_exports.array(external_exports.string()).min(1).describe(
+        "Scopes to grant. Use 'auth_keys:create:once', the scope the device-provisioning guide documents; the API reference's example shows 'auth_keys:create'. Not restricted here."
+      ),
       allowedNodeAttributes: external_exports.array(external_exports.string()).optional().describe("Optional node attributes the app may request when provisioning a device")
     }),
     handler: async (input) => {
@@ -32989,14 +33541,57 @@ import * as net2 from "node:net";
 
 // src/local-cli.ts
 import { execFile as execFileCb } from "node:child_process";
+import { existsSync, readFileSync as readFileSync2 } from "node:fs";
 var DEFAULT_TIMEOUT_MS = 3e4;
 var MAX_BUFFER_BYTES = 10 * 1024 * 1024;
+var DARWIN_CANDIDATES = [
+  "/Applications/Tailscale.app/Contents/MacOS/Tailscale",
+  "/opt/homebrew/bin/tailscale",
+  "/usr/local/bin/tailscale"
+];
+var LINUX_CANDIDATES = ["/usr/bin/tailscale", "/snap/bin/tailscale"];
 var execFileImpl = execFileCb;
-function getBinaryPath() {
-  return process.env.TAILSCALE_BINARY || "tailscale";
+function binaryCandidates(platform) {
+  if (platform === "darwin") return DARWIN_CANDIDATES;
+  if (platform === "linux") return LINUX_CANDIDATES;
+  return [];
+}
+function resolveBinary(platform = process.platform, exists = existsSync) {
+  const override = process.env.TAILSCALE_BINARY;
+  if (override) return override;
+  for (const candidate of binaryCandidates(platform)) {
+    if (exists(candidate)) return candidate;
+  }
+  return "tailscale";
+}
+function looksLikeWsl(platform, procVersion = readProcVersion) {
+  if (platform !== "linux") return false;
+  if (process.env.WSL_DISTRO_NAME) return true;
+  return /microsoft/i.test(procVersion());
+}
+function readProcVersion() {
+  try {
+    return readFileSync2("/proc/version", "utf-8");
+  } catch {
+    return "";
+  }
+}
+function describeMissingBinary(binary, fromEnv, platform, wsl) {
+  if (fromEnv) {
+    const pathNote = platform === "win32" ? `On Windows the value must be a Windows path (C:/Program Files/Tailscale/tailscale.exe), not an MSYS one (/c/...) -- Git Bash rewrites /c/... when you type it at the prompt, but a value read from an MCP client's JSON config or a .env file arrives untranslated.` : `It must be the absolute path of an executable file -- not a directory, and not a shell alias or function.`;
+    return `Could not find the 'tailscale' binary at '${binary}', which is where TAILSCALE_BINARY points. PATH was never consulted, so nothing here is a PATH problem. ${pathNote}`;
+  }
+  if (platform === "darwin") {
+    return `Could not find the 'tailscale' binary in PATH, or at ${DARWIN_CANDIDATES.join(", ")}. A default macOS install keeps the CLI inside the app bundle and puts nothing on PATH, and an MCP client launched from the Dock or Spotlight sees a minimal PATH rather than your shell's. Install Tailscale (https://tailscale.com/download) or set TAILSCALE_BINARY to its absolute path, usually /Applications/Tailscale.app/Contents/MacOS/Tailscale.`;
+  }
+  if (wsl) {
+    return `Could not find the 'tailscale' binary in PATH, or at ${LINUX_CANDIDATES.join(", ")}. This looks like WSL, where the only tailscale in reach is usually the Windows one: a Linux process cannot exec tailscale.exe, and pointing TAILSCALE_BINARY at it would report the WINDOWS host's tailnet rather than this machine's, which is what these tools describe. Install Tailscale inside the distro (https://tailscale.com/download/linux) and run tailscaled there.`;
+  }
+  return `Could not find the 'tailscale' binary in PATH. Install Tailscale (https://tailscale.com/download) or set TAILSCALE_BINARY to its absolute path.`;
 }
 async function runTailscaleCli(args, options = {}) {
-  const binary = getBinaryPath();
+  const binary = resolveBinary();
+  const fromEnv = Boolean(process.env.TAILSCALE_BINARY);
   const timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
   return new Promise((resolve) => {
     execFileImpl(binary, args, { timeout: timeoutMs, maxBuffer: MAX_BUFFER_BYTES }, (err, stdout, stderr) => {
@@ -33007,7 +33602,7 @@ async function runTailscaleCli(args, options = {}) {
         if (errno.code === "ENOENT") {
           resolve({
             ok: false,
-            error: `Could not find the 'tailscale' binary in PATH. Install Tailscale (https://tailscale.com/download) or set TAILSCALE_BINARY to its absolute path.`
+            error: describeMissingBinary(binary, fromEnv, process.platform, looksLikeWsl(process.platform))
           });
           return;
         }
@@ -33063,7 +33658,7 @@ function isValidPingTarget(s) {
 var localCliTools = [
   {
     name: "tailscale_local_status",
-    description: "Get this machine's view of its tailnet -- own connection state, peers it can see, DERP region, MagicDNS suffix, etc. Shells out to the local `tailscale` binary; distinct from `tailscale_status`, which queries the admin API for tailnet-wide info. Requires the tailscale CLI installed locally and TAILSCALE_LOCAL_CLI=1.",
+    description: "Get this machine's view of its tailnet -- own connection state, peers it can see, DERP region, MagicDNS suffix, etc. Shells out to the local `tailscale` binary; distinct from `tailscale_status`, which queries the admin API for tailnet-wide info. Read a peer's path in decision order: direct when `CurAddr` is set, peer-relayed when `PeerRelay` is set, otherwise DERP via the region named in `Relay`. `Relay` is the peer's home DERP region and is populated either way, so a non-empty `Relay` on its own does not mean the traffic is relayed. The `Peer` map is what makes this response scale with the tailnet rather than with the request; `peers` and `activeOnly` narrow it. Requires the tailscale CLI installed locally and TAILSCALE_LOCAL_CLI=1.",
     annotations: {
       title: "Local tailscale status",
       readOnlyHint: true,
@@ -33071,8 +33666,30 @@ var localCliTools = [
       idempotentHint: true,
       openWorldHint: true
     },
-    inputSchema: external_exports.object({}),
-    handler: async () => runTailscaleCli(["status", "--json"], { parseJson: true })
+    inputSchema: external_exports.object({
+      peers: external_exports.boolean().optional().describe(
+        "Set false to omit the `Peer` map (`--peers=false`), leaving this node's own state -- `Self`, `BackendState`, `Health`, `CurrentTailnet` and the rest of the top level. Omit it for the CLI's default, which includes peers."
+      ),
+      activeOnly: external_exports.boolean().optional().describe(
+        "Set true to keep only peers with an active session (`--active`) -- upstream defines that as a packet sent to the peer in roughly the last two minutes. Omit it to get every peer."
+      )
+    }),
+    handler: async (input = {}) => {
+      const args = ["status", "--json"];
+      if (input.peers === false) args.push("--peers=false");
+      if (input.activeOnly) args.push("--active");
+      const result = await runTailscaleCli(args, { parseJson: true });
+      if (!result.ok && result.error?.includes("output limit")) {
+        return { ...result, error: `${result.error} Retry with peers:false or activeOnly:true.` };
+      }
+      if (!result.ok && result.error?.includes("timed out after")) {
+        return {
+          ...result,
+          error: `${result.error}. On a large tailnet this is usually the peer map -- retry with peers:false.`
+        };
+      }
+      return result;
+    }
   },
   {
     name: "tailscale_ping",
@@ -33336,17 +33953,30 @@ var logStreamingTools = [
   },
   {
     name: "tailscale_create_aws_external_id",
-    description: "Create or get an AWS external ID for your tailnet. Used when configuring log streaming to S3 \u2014 the external ID is included in the IAM role trust policy.",
+    description: "Create or get the AWS external ID Tailscale presents when assuming your IAM role for S3 log streaming. Put it in the role trust policy's sts:ExternalId condition, then check it with tailscale_validate_aws_trust_policy.",
     annotations: {
       title: "Create AWS external ID",
       readOnlyHint: false,
       destructiveHint: false,
-      idempotentHint: true,
+      // Not idempotent: a static hint has to hold for every accepted input, and
+      // reusable:false mints a distinct ID by design. Even reusable:true mints
+      // a new one once the previous ID has been linked to an AWS account.
+      idempotentHint: false,
       openWorldHint: true
     },
-    inputSchema: external_exports.object({}),
-    handler: async () => {
-      return apiPost(`/tailnet/${getTailnet()}/aws-external-id`);
+    inputSchema: external_exports.object({
+      reusable: external_exports.boolean().optional().describe(
+        "Default true: Tailscale returns the SAME external ID on repeat calls until that ID has been linked to an AWS account, so asking again does not invalidate the ID already pasted into an IAM trust policy. Set false to force a fresh ID (what Tailscale's Terraform provider does, one ID per resource)."
+      )
+    }),
+    // The flag was previously never sent at all, so the server applied whatever
+    // default it applies to an absent body -- undocumented either way. It now
+    // goes on the wire explicitly, as the Go client always does. The default
+    // lives here rather than in a Zod `.default()` because handlers are called
+    // with the client's raw input, and `??` rather than `||` because false is a
+    // meaningful value.
+    handler: async (input) => {
+      return apiPost(`/tailnet/${getTailnet()}/aws-external-id`, { reusable: input?.reusable ?? true });
     }
   },
   {
@@ -33445,14 +34075,16 @@ var postureTools = [
         "The posture provider slug: falcon (CrowdStrike Falcon), fleet, huntress, intune (Microsoft Intune), jamfpro (Jamf Pro), kandji (Iru, formerly Kandji), kolide (1Password XAM, formerly Kolide), sentinelone"
       ),
       clientId: external_exports.string().optional().describe(
-        "Client ID for the provider (Intune: application UUID; Falcon/Jamf Pro: client id; Fleet/Huntress/Kandji/Kolide/Sentinel One: leave blank)"
+        "Client ID for the provider (Intune: application UUID; Falcon/Jamf Pro: client id; Kandji/Kolide/Sentinel One: leave blank). Fleet and Huntress: Tailscale does not document how their credentials map onto these API fields -- the admin console asks for a Fleet URL + API token (Fleet) and an API key + API secret, plus an optional organization ID (Huntress). Do not assume this can be left blank; confirm the mapping first."
       ),
       clientSecret: external_exports.string().describe(
         "The secret (auth key, token, etc.) used to authenticate with the provider. SENSITIVE: passed straight to Tailscale and not echoed back, but MCP clients may log the input value you supply."
       ),
-      tenantId: external_exports.string().optional().describe("Microsoft Intune directory (tenant) ID. Other providers leave blank."),
+      tenantId: external_exports.string().optional().describe(
+        "Microsoft Intune directory (tenant) ID. Other providers leave blank. Fleet/Huntress: undocumented upstream (see clientId)."
+      ),
       cloudId: external_exports.string().optional().describe(
-        "Identifies which of the provider's clouds to integrate with. Falcon: us-1|us-2|eu-1|us-gov; Intune: global|us-gov; Jamf Pro/Kandji/Sentinel One: FQDN of your subdomain; Kolide: leave blank."
+        "Identifies which of the provider's clouds to integrate with. Falcon: us-1|us-2|eu-1|us-gov; Intune: global|us-gov; Jamf Pro/Kandji/Sentinel One: FQDN of your subdomain; Kolide: leave blank. Fleet/Huntress: undocumented upstream (see clientId)."
       )
     }),
     handler: async (input) => {
@@ -33630,7 +34262,7 @@ var serviceTools = [
     },
     inputSchema: external_exports.object({
       serviceName: external_exports.string().describe("The service name"),
-      deviceId: external_exports.string().describe("The device ID")
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`)
     }),
     handler: async (input) => {
       return apiGet(
@@ -33650,7 +34282,7 @@ var serviceTools = [
     },
     inputSchema: external_exports.object({
       serviceName: external_exports.string().describe("The service name"),
-      deviceId: external_exports.string().describe("The device ID"),
+      deviceId: external_exports.string().describe(`The device ID. ${DEVICE_ID_HINT}`),
       approved: external_exports.boolean().describe("Whether to approve (true) or reject (false) the device")
     }),
     handler: async (input) => {
@@ -33871,17 +34503,24 @@ var tailnetsTools = [
   },
   {
     name: "tailscale_create_org_tailnet",
-    description: "Create a new API-only tailnet in your organization. Returns the tailnet (id, displayName, orgId, dnsName, createdAt) AND a freshly-minted OAuth client for it.\n\nSECURITY: the response body contains that OAuth client's secret verbatim, and it cannot be retrieved again. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.\n\nRequires an OAuth client with the 'tailnets' scope -- an API key will not work. To then operate on the new tailnet, set TAILSCALE_OAUTH_TAILNET to its id and use an OAuth client with the 'all' scope.",
+    description: "Create a new API-only tailnet in your organization. Returns the tailnet (id, displayName, orgId, dnsName, createdAt) AND a freshly-minted OAuth client for it.\n\nSECURITY: the response body contains that OAuth client's secret verbatim, and it cannot be retrieved again. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.\n\nRequires an OAuth client with the 'tailnets' scope -- an API key will not work. To then operate on the new tailnet, set TAILSCALE_OAUTH_TAILNET to its id and use an OAuth client with the 'all' scope.\n\nOrganizations are limited to 10 tailnets including the original unless Tailscale sales has raised the limit.\n\nThe response may include `alreadyExists: true`; Tailscale's spec ALSO documents a 400 for a name already in use and neither has been observed, so after a timeout call tailscale_list_org_tailnets before retrying rather than assuming either.",
     annotations: {
       title: "Create organization tailnet",
       readOnlyHint: false,
       destructiveHint: false,
-      // Each call creates a distinct tailnet; there is no idempotency key.
+      // No idempotency key. The spec's `alreadyExists` field hints that a
+      // duplicate displayName may return the existing tailnet, but the same
+      // spec documents a 400 for that case and neither is observed --
+      // idempotentHint stays false until one is.
       idempotentHint: false,
       openWorldHint: true
     },
     inputSchema: external_exports.object({
-      displayName: external_exports.string().trim().min(1).describe("Human-readable name for the new tailnet"),
+      // No charset regex: the rule below is Tailscale's and Tailscale enforces
+      // it, so a local copy would only drift out of step with its own error.
+      displayName: external_exports.string().trim().min(1).describe(
+        "Human-readable name for the new tailnet. May contain letters, numbers, spaces, apostrophes and hyphens, and must be unique within the organization."
+      ),
       organization: organizationSchema
     }),
     handler: async (input) => {
@@ -34082,11 +34721,12 @@ var STATIC_WEBHOOK_EVENT_TYPES = [
   "subnetIPForwardingNotEnabled",
   "exitNodeIPForwardingNotEnabled"
 ];
+var WEBHOOK_CATEGORY_SUBSCRIPTIONS = ["categoryTailnetManagement", "categoryDeviceMisconfigurations"];
 function getAllowedWebhookEvents() {
   const raw = process.env.TAILSCALE_EXTRA_WEBHOOK_EVENTS;
-  if (!raw) return new Set(STATIC_WEBHOOK_EVENT_TYPES);
+  if (!raw) return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...WEBHOOK_CATEGORY_SUBSCRIPTIONS]);
   const extras = raw.split(",").map((s) => s.trim()).filter(Boolean);
-  return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...extras]);
+  return /* @__PURE__ */ new Set([...STATIC_WEBHOOK_EVENT_TYPES, ...WEBHOOK_CATEGORY_SUBSCRIPTIONS, ...extras]);
 }
 var endpointUrlSchema = external_exports.url().refine((u) => u.startsWith("https://"), "endpointUrl must use https://");
 var webhookSubscriptionsSchema = external_exports.array(external_exports.string().meta({ enum: [...getAllowedWebhookEvents()].sort() })).min(1).superRefine((arr, ctx) => {
@@ -34143,7 +34783,7 @@ var webhookTools = [
   },
   {
     name: "tailscale_create_webhook",
-    description: "Create a new webhook. The response includes the webhook's signing secret -- this is the only opportunity to capture it; save it immediately.\n\nSECURITY: the response body contains the secret verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.",
+    description: "Create a new webhook. The response includes the webhook's signing secret -- this is the only opportunity to capture it; save it immediately. Set providerType when the endpoint is a Slack, Mattermost, Google Chat or Discord incoming-webhook URL, so the events arrive in the format that provider renders.\n\nSECURITY: the response body contains the secret verbatim. MCP clients commonly persist tool responses to logs and conversation transcripts; treat this response as sensitive.",
     annotations: {
       title: "Create webhook",
       readOnlyHint: false,
@@ -34153,13 +34793,20 @@ var webhookTools = [
     },
     inputSchema: external_exports.object({
       endpointUrl: endpointUrlSchema.describe("The HTTPS URL to send webhook events to"),
-      subscriptions: webhookSubscriptionsSchema.describe("Event types to subscribe to (at least one)")
+      providerType: external_exports.enum(["slack", "mattermost", "googlechat", "discord"]).optional().describe(
+        "Format deliveries for a chat provider's incoming-webhook URL. Omit for raw Tailscale JSON -- the default, and what a custom receiver verifying signatures wants. Set once: it cannot be changed after creation."
+      ),
+      subscriptions: webhookSubscriptionsSchema.describe(
+        "Event types to subscribe to (at least one). 'categoryTailnetManagement' and 'categoryDeviceMisconfigurations' subscribe to a whole category, including events Tailscale adds to it later."
+      )
     }),
     handler: async (input) => {
-      return apiPost(`/tailnet/${getTailnet()}/webhooks`, {
+      const body = {
         endpointUrl: input.endpointUrl,
         subscriptions: input.subscriptions
-      });
+      };
+      if (input.providerType !== void 0) body.providerType = input.providerType;
+      return apiPost(`/tailnet/${getTailnet()}/webhooks`, body);
     }
   },
   {
@@ -34175,7 +34822,9 @@ var webhookTools = [
     inputSchema: external_exports.object({
       webhookId: external_exports.string().describe("The webhook ID to update"),
       endpointUrl: endpointUrlSchema.optional().describe("New HTTPS URL to send webhook events to"),
-      subscriptions: webhookSubscriptionsSchema.optional().describe("Updated list of event types to subscribe to (at least one)")
+      subscriptions: webhookSubscriptionsSchema.optional().describe(
+        "Updated list of event types to subscribe to (at least one). 'categoryTailnetManagement' and 'categoryDeviceMisconfigurations' subscribe to a whole category, including events Tailscale adds to it later."
+      )
     }),
     handler: async (input) => {
       const body = {};
@@ -34270,7 +34919,13 @@ var LARGE_RESULT_TOOLS = [
   "tailscale_get_audit_log",
   "tailscale_get_network_flow_logs",
   "tailscale_list_devices",
-  "tailscale_list_users"
+  "tailscale_list_users",
+  // The one opt-in entry: it registers only under TAILSCALE_LOCAL_CLI=1, so a
+  // test comparing this list against a session's `_meta` has to filter it to
+  // the names that session registered. Its payload is the local client's whole
+  // peer map, which scales with the tailnet exactly as the admin reads above
+  // do -- the tool takes `peers` and `activeOnly` for callers who want less.
+  "tailscale_local_status"
 ];
 function buildToolMeta(toolName, options) {
   const meta3 = {};
@@ -34551,7 +35206,26 @@ function buildMetaTools(state) {
 }
 
 // src/index.ts
-var version2 = true ? "0.20.1" : resolveVersionFallback();
+var NODE_MIN = [20, 11, 0];
+function belowNodeFloor(reported) {
+  const found = /(\d+)\.(\d+)\.(\d+)/.exec(reported);
+  if (!found) return false;
+  for (const [i, min] of NODE_MIN.entries()) {
+    const part = Number(found[i + 1]);
+    if (part > min) return false;
+    if (part < min) return true;
+  }
+  return false;
+}
+if (process.versions.oam === void 0 && belowNodeFloor(process.versions.node)) {
+  process.stderr.write(
+    `tailscale-mcp: needs Node ${NODE_MIN.join(".")} or newer, found ${process.versions.node}.
+Install a newer Node (https://nodejs.org/en/download), or point your MCP client's "command" at one.
+`
+  );
+  process.exit(1);
+}
+var version2 = true ? "0.21.0" : resolveVersionFallback();
 var subcommand = process.argv[2];
 var USAGE = `Usage: tailscale-mcp [command]