From 9ceee70553503375531a92e70dbf2c982ff3aa2a Mon Sep 17 00:00:00 2001
From: mukunda katta <mukunda.vjcs6@gmail.com>
Date: Thu, 14 May 2026 19:29:30 -0700
Subject: [PATCH] Clarify selected API docs

---
 doc/api/fs.md       | 26 ++++++++++++++++++++------
 doc/api/globals.md  | 13 +++++++++++++
 doc/api/packages.md |  6 ++++++
 3 files changed, 39 insertions(+), 6 deletions(-)

diff --git a/doc/api/fs.md b/doc/api/fs.md
index c5e908aaa39f6c..347cbaafaa2dab 100644
--- a/doc/api/fs.md
+++ b/doc/api/fs.md
@@ -7925,6 +7925,20 @@ Objects returned from [`fs.statfs()`][] and its synchronous counterpart are of
 this type. If `bigint` in the `options` passed to those methods is `true`, the
 numeric values will be `bigint` instead of `number`.
 
+The block counts are expressed in units of `statfs.bsize`, which is reported in
+bytes. For example, to calculate available space:
+
+```mjs
+import { statfs } from 'node:fs/promises';
+
+const stats = await statfs('/tmp');
+const availableBytes = stats.bavail * stats.bsize;
+const totalBytes = stats.blocks * stats.bsize;
+const availableFiles = stats.ffree;
+
+console.log({ availableBytes, totalBytes, availableFiles });
+```
+
 ```console
 StatFs {
   type: 1397114950,
@@ -7963,7 +7977,7 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks available to unprivileged users.
+Free blocks available to unprivileged users, in units of `statfs.bsize`.
 
 #### `statfs.bfree`
 
@@ -7975,7 +7989,7 @@ added:
 
 * Type: {number|bigint}
 
-Free blocks in file system.
+Free blocks in the file system, in units of `statfs.bsize`.
 
 #### `statfs.blocks`
 
@@ -7987,7 +8001,7 @@ added:
 
 * Type: {number|bigint}
 
-Total data blocks in file system.
+Total data blocks in the file system, in units of `statfs.bsize`.
 
 #### `statfs.bsize`
 
@@ -7999,7 +8013,7 @@ added:
 
 * Type: {number|bigint}
 
-Optimal transfer block size.
+Optimal transfer block size, in bytes.
 
 #### `statfs.frsize`
 
@@ -8009,7 +8023,7 @@ added: v26.1.0
 
 * Type: {number|bigint}
 
-Fundamental file system block size.
+Fundamental file system block size, in bytes.
 
 #### `statfs.ffree`
 
@@ -8045,7 +8059,7 @@ added:
 
 * Type: {number|bigint}
 
-Type of file system.
+Operating system-specific numeric file system type.
 
 ### Class: `fs.Utf8Stream`
 
diff --git a/doc/api/globals.md b/doc/api/globals.md
index a70442f1bb91ec..cf60ab45f79395 100644
--- a/doc/api/globals.md
+++ b/doc/api/globals.md
@@ -567,6 +567,19 @@ The implementation is based upon [undici](https://undici.nodejs.org), an HTTP/1.
 written from scratch for Node.js. You can figure out which version of `undici` is bundled
 in your Node.js process reading the `process.versions.undici` property.
 
+### Node.js-specific behavior
+
+The Node.js implementation is intentionally close to the browser standard, but
+it runs outside a browser context and includes some Node.js-specific behavior:
+
+* Cookie storage is not provided by Node.js. To preserve cookies across
+  requests, manage `Cookie` and `Set-Cookie` headers manually or use a separate
+  cookie store.
+* Header handling is not constrained by the browser forbidden request-header
+  rules.
+* Request and response bodies can be backed by Node.js streams and other
+  async iterable sources supported by undici.
+
 ### Custom dispatcher
 
 You can use a custom dispatcher to dispatch requests passing it in fetch's options object.
diff --git a/doc/api/packages.md b/doc/api/packages.md
index 429b1b19b90801..716e36a516c28f 100644
--- a/doc/api/packages.md
+++ b/doc/api/packages.md
@@ -720,6 +720,12 @@ least specific in object order_.
 
 Using the `"import"` and `"require"` conditions can lead to some hazards,
 which are further explained in [the dual CommonJS/ES module packages section][].
+If a package wants to avoid the dual package hazard in Node.js while still
+providing an ES module build for non-Node.js environments, consider using
+`"node"` and `"default"` conditions instead. For example, the `"node"`
+condition can point to a single CommonJS implementation for Node.js, while the
+`"default"` condition points to an ES module implementation for browsers or
+other JavaScript runtimes.
 
 The `"node-addons"` condition can be used to provide an entry point which
 uses native C++ addons. However, this condition can be disabled via the