doc: document --permission-audit audit mode behavior

Expand the documentation for the --permission-audit flag, which was
fixed in 51c09ea to no longer throw ERR_ACCESS_DENIED on denied
operations. The previous docs only had a two-sentence description in
cli.md and no mention in the permissions guide or process.permission
API docs.

- permissions.md: add enforce vs audit mode overview, a new
  "Audit Mode" subsection listing the diagnostics channel names
  (node:permission-model:*) and the { permission, resource } message
  shape, and a usage example. Update the Runtime API section to
  mention both --permission and --permission-audit.
- cli.md: expand the --permission-audit section to clarify that
  --permission is not required, --allow-* flags are not needed,
  errors are not thrown, and --permission takes precedence when both
  are set. Add a cross-reference from --permission to
  --permission-audit.
- process.md: note that process.permission is available under both
  flags, and clarify permission.has() and permission.drop() behavior
  in audit mode.
- node.1: regenerated via `make node.1`.

Refs: #64426
Signed-off-by: Adrian Estrada <edsadr@gmail.com>
PR-URL: #64791
Reviewed-By: Aviv Keller <me@aviv.sh>
Reviewed-By: Rafael Gonzaga <rafael.nunu@hotmail.com>
Reviewed-By: Marco Ippolito <marcoippolito54@gmail.com>
Reviewed-By: Luigi Pinca <luigipinca@gmail.com>

Author: edsadr

doc/api/cli.md

@@ -2316,6 +2316,9 @@ changes:
 Enable the Permission Model for current process. When enabled, the
 following permissions are restricted:
 
+> See also [`--permission-audit`](#--permission-audit) for an audit-only mode
+> that logs violations without denying access.
+
 * File System - manageable through
   [`--allow-fs-read`][], [`--allow-fs-write`][] flags
 * Network - manageable through [`--allow-net`][] flag
@@ -2331,9 +2334,22 @@ following permissions are restricted:
 added: v25.8.0
 -->
 
-Enable audit only for the permission model. When enabled, permission checks
-are performed but access is not denied. Instead, a warning is emitted for
-each permission violation via diagnostics channel.
+Enable audit mode for the permission model. When enabled, permission checks
+are performed but access is **not** denied — no `ERR_ACCESS_DENIED` error is
+thrown. Instead, each permission violation is published through the
+`node:diagnostics_channel` module, and execution continues normally.
+
+This flag does not require [`--permission`](#--permission) to be specified. The
+`--allow-*` flags are not needed in audit mode, since no
+access is denied.
+
+Audit mode is useful for discovering what permissions your application
+requires before deploying with [`--permission`](#--permission). See the
+[Permission Model][] documentation for the list of diagnostics channel names
+and the message format.
+
+If both [`--permission`](#--permission) and `--permission-audit` are specified,
+`--permission` takes precedence and the Permission Model runs in enforce mode.
 
 ### `--preserve-symlinks`
 

doc/api/permissions.md

@@ -48,6 +48,17 @@ will restrict access to all available permissions.
 The available permissions are documented by the [`--permission`][]
 flag.
 
+The Permission Model has two operational modes:
+
+* **Enforce mode** (default when using [`--permission`][]): Access is denied and
+  an `ERR_ACCESS_DENIED` error is thrown for any operation the process has not
+  been granted permission to perform.
+* **Audit mode** (when using [`--permission-audit`][]): Permission checks are
+  performed and violations are published through the diagnostics channel, but
+  access is **not** denied. Execution continues normally. This mode is useful
+  for discovering what permissions your application requires before deploying
+  with enforce mode.
+
 When starting Node.js with `--permission`,
 the ability to access the file system through the `fs` module, access the network,
 spawn processes, use `node:worker_threads`, use native addons, use WASI, use
@@ -77,8 +88,8 @@ flag. For WASI, use the [`--allow-wasi`][] flag. For FFI, use the
 #### Runtime API
 
 When enabling the Permission Model through the [`--permission`][]
-flag a new property `permission` is added to the `process` object.
-This property contains the following functions:
+or [`--permission-audit`][] flags, a new property `permission` is added to the
+`process` object. This property contains the following functions:
 
 ##### `permission.has(scope[, reference])`
 
@@ -127,6 +138,56 @@ process.permission.has('fs.read', '/etc/myapp/config.json'); // false
 process.permission.drop('child');