From 9387308532515b87b950ce6fc6ddde912e7d4653 Mon Sep 17 00:00:00 2001
From: Test User <john.david.dalton@gmail.com>
Date: Mon, 13 Apr 2026 17:03:46 -0400
Subject: [PATCH] docs(env): add @example blocks to env module exports

---
 src/env.ts                   |  40 +++++++++
 src/env/ci.ts                |  14 ++++
 src/env/debug.ts             |  13 +++
 src/env/github.ts            |  80 ++++++++++++++++++
 src/env/helpers.ts           |  45 +++++++++++
 src/env/home.ts              |  13 +++
 src/env/locale.ts            |  30 +++++++
 src/env/node-auth-token.ts   |  13 +++
 src/env/node-env.ts          |  13 +++
 src/env/npm.ts               |  50 ++++++++++++
 src/env/path.ts              |  13 +++
 src/env/pre-commit.ts        |  14 ++++
 src/env/rewire.ts            |  38 +++++++++
 src/env/shell.ts             |  13 +++
 src/env/socket-cli-shadow.ts |  43 ++++++++++
 src/env/socket-cli.ts        | 116 ++++++++++++++++++++++++++
 src/env/socket.ts            | 153 +++++++++++++++++++++++++++++++++++
 src/env/temp-dir.ts          |  30 +++++++
 src/env/term.ts              |  13 +++
 src/env/test.ts              |  32 ++++++++
 src/env/windows.ts           |  40 +++++++++
 src/env/xdg.ts               |  30 +++++++
 22 files changed, 846 insertions(+)

diff --git a/src/env.ts b/src/env.ts
index 29607853..a6c0a327 100644
--- a/src/env.ts
+++ b/src/env.ts
@@ -175,6 +175,20 @@ export function createEnvProxy(
 
 /**
  * Convert an environment variable value to a boolean.
+ *
+ * @param value - The value to convert
+ * @param defaultValue - Default when value is null/undefined (default: `false`)
+ * @returns `true` if value is '1' or 'true' (case-insensitive), `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { envAsBoolean } from '@socketsecurity/lib/env'
+ *
+ * envAsBoolean('true')      // true
+ * envAsBoolean('1')         // true
+ * envAsBoolean('false')     // false
+ * envAsBoolean(undefined)   // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsBoolean(value: unknown, defaultValue = false): boolean {
@@ -190,6 +204,19 @@ export function envAsBoolean(value: unknown, defaultValue = false): boolean {
 
 /**
  * Convert an environment variable value to a number.
+ *
+ * @param value - The value to convert
+ * @param defaultValue - Default when value is not a finite number (default: `0`)
+ * @returns The parsed integer, or the default value if parsing fails
+ *
+ * @example
+ * ```typescript
+ * import { envAsNumber } from '@socketsecurity/lib/env'
+ *
+ * envAsNumber('3000')     // 3000
+ * envAsNumber('abc')      // 0
+ * envAsNumber(undefined)  // 0
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsNumber(value: unknown, defaultValue = 0): number {
@@ -203,6 +230,19 @@ export function envAsNumber(value: unknown, defaultValue = 0): number {
 
 /**
  * Convert an environment variable value to a trimmed string.
+ *
+ * @param value - The value to convert
+ * @param defaultValue - Default when value is null/undefined (default: `''`)
+ * @returns The trimmed string value, or the default value
+ *
+ * @example
+ * ```typescript
+ * import { envAsString } from '@socketsecurity/lib/env'
+ *
+ * envAsString('  hello  ')  // 'hello'
+ * envAsString(undefined)    // ''
+ * envAsString(null, 'n/a')  // 'n/a'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsString(value: unknown, defaultValue = ''): string {
diff --git a/src/env/ci.ts b/src/env/ci.ts
index 00f64292..4dfb0186 100644
--- a/src/env/ci.ts
+++ b/src/env/ci.ts
@@ -5,6 +5,20 @@
 
 import { isInEnv } from './rewire'
 
+/**
+ * Returns whether the CI environment variable is set.
+ *
+ * @returns `true` if running in a CI environment, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getCI } from '@socketsecurity/lib/env/ci'
+ *
+ * if (getCI()) {
+ *   console.log('Running in CI')
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getCI(): boolean {
   return isInEnv('CI')
diff --git a/src/env/debug.ts b/src/env/debug.ts
index dcdca89c..4b0d416b 100644
--- a/src/env/debug.ts
+++ b/src/env/debug.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the DEBUG environment variable.
+ *
+ * @returns The debug filter string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getDebug } from '@socketsecurity/lib/env/debug'
+ *
+ * const debug = getDebug()
+ * // e.g. 'socket:*' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getDebug(): string | undefined {
   return getEnvValue('DEBUG')
diff --git a/src/env/github.ts b/src/env/github.ts
index 049751e0..c12e8da1 100644
--- a/src/env/github.ts
+++ b/src/env/github.ts
@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * GITHUB_API_URL environment variable.
  * GitHub API URL (e.g., https://api.github.com).
+ *
+ * @returns The GitHub API URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubApiUrl } from '@socketsecurity/lib/env/github'
+ *
+ * const apiUrl = getGithubApiUrl()
+ * // e.g. 'https://api.github.com' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubApiUrl(): string | undefined {
@@ -17,6 +27,16 @@ export function getGithubApiUrl(): string | undefined {
 /**
  * GITHUB_BASE_REF environment variable.
  * GitHub pull request base branch.
+ *
+ * @returns The pull request base branch name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubBaseRef } from '@socketsecurity/lib/env/github'
+ *
+ * const baseRef = getGithubBaseRef()
+ * // e.g. 'main' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubBaseRef(): string | undefined {
@@ -26,6 +46,16 @@ export function getGithubBaseRef(): string | undefined {
 /**
  * GITHUB_REF_NAME environment variable.
  * GitHub branch or tag name.
+ *
+ * @returns The branch or tag name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRefName } from '@socketsecurity/lib/env/github'
+ *
+ * const refName = getGithubRefName()
+ * // e.g. 'feature/my-branch' or 'v1.0.0'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubRefName(): string | undefined {
@@ -35,6 +65,16 @@ export function getGithubRefName(): string | undefined {
 /**
  * GITHUB_REF_TYPE environment variable.
  * GitHub ref type (branch or tag).
+ *
+ * @returns The ref type ('branch' or 'tag'), or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRefType } from '@socketsecurity/lib/env/github'
+ *
+ * const refType = getGithubRefType()
+ * // e.g. 'branch' or 'tag'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubRefType(): string | undefined {
@@ -44,6 +84,16 @@ export function getGithubRefType(): string | undefined {
 /**
  * GITHUB_REPOSITORY environment variable.
  * GitHub repository name in owner/repo format.
+ *
+ * @returns The repository name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubRepository } from '@socketsecurity/lib/env/github'
+ *
+ * const repo = getGithubRepository()
+ * // e.g. 'SocketDev/socket-cli' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubRepository(): string | undefined {
@@ -53,6 +103,16 @@ export function getGithubRepository(): string | undefined {
 /**
  * GITHUB_SERVER_URL environment variable.
  * GitHub server URL (e.g., https://github.com).
+ *
+ * @returns The GitHub server URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubServerUrl } from '@socketsecurity/lib/env/github'
+ *
+ * const serverUrl = getGithubServerUrl()
+ * // e.g. 'https://github.com' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubServerUrl(): string | undefined {
@@ -62,6 +122,16 @@ export function getGithubServerUrl(): string | undefined {
 /**
  * GITHUB_TOKEN environment variable.
  * GitHub authentication token for API access.
+ *
+ * @returns The GitHub token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGithubToken } from '@socketsecurity/lib/env/github'
+ *
+ * const token = getGithubToken()
+ * // e.g. 'ghp_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGithubToken(): string | undefined {
@@ -71,6 +141,16 @@ export function getGithubToken(): string | undefined {
 /**
  * GH_TOKEN environment variable.
  * Alternative GitHub authentication token for API access (used by GitHub CLI).
+ *
+ * @returns The GH CLI token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getGhToken } from '@socketsecurity/lib/env/github'
+ *
+ * const token = getGhToken()
+ * // e.g. 'gho_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getGhToken(): string | undefined {
diff --git a/src/env/helpers.ts b/src/env/helpers.ts
index d1c308a7..90a47280 100644
--- a/src/env/helpers.ts
+++ b/src/env/helpers.ts
@@ -2,6 +2,22 @@
  * @fileoverview Environment variable type conversion helpers.
  */
 
+/**
+ * Convert an environment variable string to a boolean.
+ *
+ * @param value - The environment variable value to convert
+ * @returns `true` if value is 'true', '1', or 'yes' (case-insensitive), `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { envAsBoolean } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsBoolean('true')      // true
+ * envAsBoolean('1')         // true
+ * envAsBoolean('yes')       // true
+ * envAsBoolean(undefined)   // false
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsBoolean(value: string | undefined): boolean {
   if (!value) {
@@ -11,6 +27,21 @@ export function envAsBoolean(value: string | undefined): boolean {
   return lower === 'true' || lower === '1' || lower === 'yes'
 }
 
+/**
+ * Convert an environment variable string to a number.
+ *
+ * @param value - The environment variable value to convert
+ * @returns The parsed number, or `0` if the value is undefined or not a valid number
+ *
+ * @example
+ * ```typescript
+ * import { envAsNumber } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsNumber('3000')     // 3000
+ * envAsNumber(undefined)  // 0
+ * envAsNumber('abc')      // 0
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsNumber(value: string | undefined): number {
   if (!value) {
@@ -20,6 +51,20 @@ export function envAsNumber(value: string | undefined): number {
   return Number.isNaN(num) ? 0 : num
 }
 
+/**
+ * Convert an environment variable value to a string.
+ *
+ * @param value - The environment variable value to convert
+ * @returns The string value, or an empty string if undefined
+ *
+ * @example
+ * ```typescript
+ * import { envAsString } from '@socketsecurity/lib/env/helpers'
+ *
+ * envAsString('hello')    // 'hello'
+ * envAsString(undefined)  // ''
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function envAsString(value: string | undefined): string {
   return value || ''
diff --git a/src/env/home.ts b/src/env/home.ts
index 1a8e9a22..56d155e5 100644
--- a/src/env/home.ts
+++ b/src/env/home.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the HOME environment variable.
+ *
+ * @returns The user's home directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getHome } from '@socketsecurity/lib/env/home'
+ *
+ * const home = getHome()
+ * // e.g. '/tmp/user' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getHome(): string | undefined {
   return getEnvValue('HOME')
diff --git a/src/env/locale.ts b/src/env/locale.ts
index 45b2965e..f7987f49 100644
--- a/src/env/locale.ts
+++ b/src/env/locale.ts
@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * LANG environment variable.
  * System locale and language settings.
+ *
+ * @returns The system locale string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLang } from '@socketsecurity/lib/env/locale'
+ *
+ * const lang = getLang()
+ * // e.g. 'en_US.UTF-8' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLang(): string | undefined {
@@ -17,6 +27,16 @@ export function getLang(): string | undefined {
 /**
  * LC_ALL environment variable.
  * Override for all locale settings.
+ *
+ * @returns The locale override string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLcAll } from '@socketsecurity/lib/env/locale'
+ *
+ * const lcAll = getLcAll()
+ * // e.g. 'C' or 'en_US.UTF-8'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLcAll(): string | undefined {
@@ -26,6 +46,16 @@ export function getLcAll(): string | undefined {
 /**
  * LC_MESSAGES environment variable.
  * Locale setting for message translations.
+ *
+ * @returns The messages locale string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLcMessages } from '@socketsecurity/lib/env/locale'
+ *
+ * const lcMessages = getLcMessages()
+ * // e.g. 'en_US.UTF-8' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLcMessages(): string | undefined {
diff --git a/src/env/node-auth-token.ts b/src/env/node-auth-token.ts
index 89ff48af..9f4ada3a 100644
--- a/src/env/node-auth-token.ts
+++ b/src/env/node-auth-token.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the NODE_AUTH_TOKEN environment variable.
+ *
+ * @returns The Node.js registry auth token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNodeAuthToken } from '@socketsecurity/lib/env/node-auth-token'
+ *
+ * const token = getNodeAuthToken()
+ * // e.g. 'npm_abc123...' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNodeAuthToken(): string | undefined {
   return getEnvValue('NODE_AUTH_TOKEN')
diff --git a/src/env/node-env.ts b/src/env/node-env.ts
index 4364d4b0..024edfb0 100644
--- a/src/env/node-env.ts
+++ b/src/env/node-env.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the NODE_ENV environment variable.
+ *
+ * @returns The Node.js environment mode, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNodeEnv } from '@socketsecurity/lib/env/node-env'
+ *
+ * const env = getNodeEnv()
+ * // e.g. 'production', 'development', 'test', or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNodeEnv(): string | undefined {
   return getEnvValue('NODE_ENV')
diff --git a/src/env/npm.ts b/src/env/npm.ts
index 6e5bda52..6d72b48e 100644
--- a/src/env/npm.ts
+++ b/src/env/npm.ts
@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * npm_config_registry environment variable.
  * NPM registry URL configured by package managers.
+ *
+ * @returns The configured NPM registry URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmConfigRegistry } from '@socketsecurity/lib/env/npm'
+ *
+ * const registry = getNpmConfigRegistry()
+ * // e.g. 'https://registry.npmjs.org/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNpmConfigRegistry(): string | undefined {
@@ -17,6 +27,16 @@ export function getNpmConfigRegistry(): string | undefined {
 /**
  * npm_config_user_agent environment variable.
  * User agent string set by npm/pnpm/yarn package managers.
+ *
+ * @returns The package manager user agent string, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmConfigUserAgent } from '@socketsecurity/lib/env/npm'
+ *
+ * const ua = getNpmConfigUserAgent()
+ * // e.g. 'pnpm/9.0.0 npm/? node/v20.0.0 darwin arm64'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNpmConfigUserAgent(): string | undefined {
@@ -26,6 +46,16 @@ export function getNpmConfigUserAgent(): string | undefined {
 /**
  * npm_lifecycle_event environment variable.
  * The name of the npm lifecycle event that's currently running.
+ *
+ * @returns The current lifecycle event name, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmLifecycleEvent } from '@socketsecurity/lib/env/npm'
+ *
+ * const event = getNpmLifecycleEvent()
+ * // e.g. 'install', 'postinstall', or 'test'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNpmLifecycleEvent(): string | undefined {
@@ -35,6 +65,16 @@ export function getNpmLifecycleEvent(): string | undefined {
 /**
  * NPM_REGISTRY environment variable.
  * NPM registry URL override.
+ *
+ * @returns The NPM registry URL override, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmRegistry } from '@socketsecurity/lib/env/npm'
+ *
+ * const registry = getNpmRegistry()
+ * // e.g. 'https://registry.npmjs.org/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNpmRegistry(): string | undefined {
@@ -44,6 +84,16 @@ export function getNpmRegistry(): string | undefined {
 /**
  * NPM_TOKEN environment variable.
  * Authentication token for NPM registry access.
+ *
+ * @returns The NPM auth token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getNpmToken } from '@socketsecurity/lib/env/npm'
+ *
+ * const token = getNpmToken()
+ * // e.g. 'npm_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getNpmToken(): string | undefined {
diff --git a/src/env/path.ts b/src/env/path.ts
index 2f7b4508..2db879cf 100644
--- a/src/env/path.ts
+++ b/src/env/path.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the PATH environment variable.
+ *
+ * @returns The system executable search paths, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getPath } from '@socketsecurity/lib/env/path'
+ *
+ * const path = getPath()
+ * // e.g. '/usr/local/bin:/usr/bin:/bin' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getPath(): string | undefined {
   return getEnvValue('PATH')
diff --git a/src/env/pre-commit.ts b/src/env/pre-commit.ts
index 83509061..69fc44c8 100644
--- a/src/env/pre-commit.ts
+++ b/src/env/pre-commit.ts
@@ -6,6 +6,20 @@
 import { envAsBoolean } from './helpers'
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns whether the PRE_COMMIT environment variable is set to a truthy value.
+ *
+ * @returns `true` if running in a pre-commit hook, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getPreCommit } from '@socketsecurity/lib/env/pre-commit'
+ *
+ * if (getPreCommit()) {
+ *   console.log('Running in pre-commit hook')
+ * }
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getPreCommit(): boolean {
   return envAsBoolean(getEnvValue('PRE_COMMIT'))
diff --git a/src/env/rewire.ts b/src/env/rewire.ts
index 025e97ec..db78cccf 100644
--- a/src/env/rewire.ts
+++ b/src/env/rewire.ts
@@ -54,6 +54,16 @@ const sharedOverrides: Map<string, string | undefined> | undefined =
 
 /**
  * Clear a specific environment variable override.
+ *
+ * @param key - The environment variable name to clear
+ *
+ * @example
+ * ```typescript
+ * import { setEnv, clearEnv } from '@socketsecurity/lib/env/rewire'
+ *
+ * setEnv('CI', '1')
+ * clearEnv('CI')
+ * ```
  */
 export function clearEnv(key: string): void {
   sharedOverrides?.delete(key)
@@ -68,6 +78,14 @@ export function clearEnv(key: string): void {
  * 3. process.env (including vi.stubEnv modifications)
  *
  * @internal Used by env getters to support test rewiring
+ *
+ * @example
+ * ```typescript
+ * import { getEnvValue } from '@socketsecurity/lib/env/rewire'
+ *
+ * const value = getEnvValue('NODE_ENV')
+ * // e.g. 'production' or undefined
+ * ```
  */
 export function getEnvValue(key: string): string | undefined {
   // Check isolated overrides first (highest priority - temporary via withEnv)
@@ -87,6 +105,18 @@ export function getEnvValue(key: string): string | undefined {
 
 /**
  * Check if an environment variable has been overridden.
+ *
+ * @param key - The environment variable name to check
+ * @returns `true` if the variable has been overridden, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { setEnv, hasOverride } from '@socketsecurity/lib/env/rewire'
+ *
+ * hasOverride('CI')  // false
+ * setEnv('CI', '1')
+ * hasOverride('CI')  // true
+ * ```
  */
 export function hasOverride(key: string): boolean {
   const isolatedOverrides = isolatedOverridesStorage.getStore()
@@ -102,6 +132,14 @@ export function hasOverride(key: string): boolean {
  * 3. process.env (including vi.stubEnv modifications)
  *
  * @internal Used by env getters to check for key presence (not value truthiness)
+ *
+ * @example
+ * ```typescript
+ * import { isInEnv } from '@socketsecurity/lib/env/rewire'
+ *
+ * isInEnv('PATH')     // true (usually set)
+ * isInEnv('MISSING')  // false
+ * ```
  */
 export function isInEnv(key: string): boolean {
   // Check isolated overrides first (highest priority - temporary via withEnv)
diff --git a/src/env/shell.ts b/src/env/shell.ts
index 72023e93..7ade797c 100644
--- a/src/env/shell.ts
+++ b/src/env/shell.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the SHELL environment variable.
+ *
+ * @returns The user's default shell path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getShell } from '@socketsecurity/lib/env/shell'
+ *
+ * const shell = getShell()
+ * // e.g. '/bin/zsh' or '/bin/bash'
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getShell(): string | undefined {
   return getEnvValue('SHELL')
diff --git a/src/env/socket-cli-shadow.ts b/src/env/socket-cli-shadow.ts
index 5e14170b..c0bc9990 100644
--- a/src/env/socket-cli-shadow.ts
+++ b/src/env/socket-cli-shadow.ts
@@ -10,6 +10,15 @@ import { getEnvValue } from './rewire'
  * Controls Socket CLI shadow mode risk acceptance.
  *
  * @returns Whether to accept all risks in shadow mode
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowAcceptRisks } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * if (getSocketCliShadowAcceptRisks()) {
+ *   console.log('Shadow mode risks accepted')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliShadowAcceptRisks(): boolean {
@@ -20,6 +29,14 @@ export function getSocketCliShadowAcceptRisks(): boolean {
  * API token for Socket CLI shadow mode.
  *
  * @returns Shadow mode API token or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowApiToken } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * const token = getSocketCliShadowApiToken()
+ * // e.g. 'sk_shadow_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliShadowApiToken(): string | undefined {
@@ -30,6 +47,14 @@ export function getSocketCliShadowApiToken(): string | undefined {
  * Binary path for Socket CLI shadow mode.
  *
  * @returns Shadow mode binary path or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowBin } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * const bin = getSocketCliShadowBin()
+ * // e.g. '/usr/local/bin/socket-shadow' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliShadowBin(): string | undefined {
@@ -40,6 +65,15 @@ export function getSocketCliShadowBin(): string | undefined {
  * Controls Socket CLI shadow mode progress display.
  *
  * @returns Whether to show progress in shadow mode
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowProgress } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * if (getSocketCliShadowProgress()) {
+ *   console.log('Shadow mode progress enabled')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliShadowProgress(): boolean {
@@ -50,6 +84,15 @@ export function getSocketCliShadowProgress(): boolean {
  * Controls Socket CLI shadow mode silent operation.
  *
  * @returns Whether shadow mode should operate silently
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliShadowSilent } from '@socketsecurity/lib/env/socket-cli-shadow'
+ *
+ * if (getSocketCliShadowSilent()) {
+ *   console.log('Shadow mode is silent')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliShadowSilent(): boolean {
diff --git a/src/env/socket-cli.ts b/src/env/socket-cli.ts
index 99992f50..b493bf10 100644
--- a/src/env/socket-cli.ts
+++ b/src/env/socket-cli.ts
@@ -10,6 +10,15 @@ import { getEnvValue } from './rewire'
  * Whether to accept all Socket CLI risks (alternative name).
  *
  * @returns Whether to accept all risks
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliAcceptRisks } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliAcceptRisks()) {
+ *   console.log('All risks accepted')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliAcceptRisks(): boolean {
@@ -21,6 +30,14 @@ export function getSocketCliAcceptRisks(): boolean {
  * Checks SOCKET_CLI_API_BASE_URL first, then falls back to legacy SOCKET_SECURITY_API_BASE_URL.
  *
  * @returns API base URL or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiBaseUrl } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const baseUrl = getSocketCliApiBaseUrl()
+ * // e.g. 'https://api.socket.dev' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliApiBaseUrl(): string | undefined {
@@ -36,6 +53,14 @@ export function getSocketCliApiBaseUrl(): string | undefined {
  * Follows the same precedence as v1.x: HTTPS_PROXY → https_proxy → HTTP_PROXY → http_proxy.
  *
  * @returns API proxy URL or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiProxy } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const proxy = getSocketCliApiProxy()
+ * // e.g. 'http://proxy.example.com:8080' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliApiProxy(): string | undefined {
@@ -53,6 +78,14 @@ export function getSocketCliApiProxy(): string | undefined {
  * Timeout in milliseconds for Socket CLI API requests (alternative name).
  *
  * @returns API timeout in milliseconds
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiTimeout } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const timeout = getSocketCliApiTimeout()
+ * // e.g. 30000 or 0 if not set
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliApiTimeout(): number {
@@ -65,6 +98,14 @@ export function getSocketCliApiTimeout(): number {
  * Maintains full v1.x backward compatibility.
  *
  * @returns API token or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliApiToken } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const token = getSocketCliApiToken()
+ * // e.g. a Socket API token string or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliApiToken(): string | undefined {
@@ -81,6 +122,14 @@ export function getSocketCliApiToken(): string | undefined {
  * Set by bootstrap wrappers to pass dlx cache location to CLI.
  *
  * @returns Bootstrap cache directory or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliBootstrapCacheDir } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const cacheDir = getSocketCliBootstrapCacheDir()
+ * // e.g. '/tmp/.socket-cli-cache' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliBootstrapCacheDir(): string | undefined {
@@ -92,6 +141,14 @@ export function getSocketCliBootstrapCacheDir(): string | undefined {
  * Set by bootstrap wrappers (SEA/smol/npm) to pass package spec to CLI.
  *
  * @returns Bootstrap package spec or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliBootstrapSpec } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const spec = getSocketCliBootstrapSpec()
+ * // e.g. '@socketsecurity/cli@^2.0.11' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliBootstrapSpec(): string | undefined {
@@ -102,6 +159,14 @@ export function getSocketCliBootstrapSpec(): string | undefined {
  * Socket CLI configuration file path (alternative name).
  *
  * @returns Config file path or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliConfig } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const config = getSocketCliConfig()
+ * // e.g. '/tmp/project/socket.yml' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliConfig(): string | undefined {
@@ -112,6 +177,14 @@ export function getSocketCliConfig(): string | undefined {
  * Controls Socket CLI fix mode.
  *
  * @returns Fix mode value or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliFix } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const fix = getSocketCliFix()
+ * // e.g. 'true' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliFix(): string | undefined {
@@ -123,6 +196,14 @@ export function getSocketCliFix(): string | undefined {
  * Checks SOCKET_CLI_GITHUB_TOKEN, SOCKET_SECURITY_GITHUB_PAT, then falls back to GITHUB_TOKEN.
  *
  * @returns GitHub token or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliGithubToken } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const token = getSocketCliGithubToken()
+ * // e.g. 'ghp_abc123...' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliGithubToken(): string | undefined {
@@ -137,6 +218,15 @@ export function getSocketCliGithubToken(): string | undefined {
  * Whether to skip Socket CLI API token requirement (alternative name).
  *
  * @returns Whether to skip API token requirement
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliNoApiToken } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliNoApiToken()) {
+ *   console.log('API token requirement skipped')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliNoApiToken(): boolean {
@@ -147,6 +237,15 @@ export function getSocketCliNoApiToken(): boolean {
  * Controls Socket CLI optimization mode.
  *
  * @returns Whether optimization mode is enabled
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliOptimize } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliOptimize()) {
+ *   console.log('Optimization mode enabled')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliOptimize(): boolean {
@@ -158,6 +257,14 @@ export function getSocketCliOptimize(): boolean {
  * Checks SOCKET_CLI_ORG_SLUG first, then falls back to SOCKET_ORG_SLUG.
  *
  * @returns Organization slug or undefined
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliOrgSlug } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * const slug = getSocketCliOrgSlug()
+ * // e.g. 'my-org' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliOrgSlug(): string | undefined {
@@ -168,6 +275,15 @@ export function getSocketCliOrgSlug(): string | undefined {
  * Whether to view all Socket CLI risks (alternative name).
  *
  * @returns Whether to view all risks
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCliViewAllRisks } from '@socketsecurity/lib/env/socket-cli'
+ *
+ * if (getSocketCliViewAllRisks()) {
+ *   console.log('Viewing all risks')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCliViewAllRisks(): boolean {
diff --git a/src/env/socket.ts b/src/env/socket.ts
index 88f743a2..90ebc222 100644
--- a/src/env/socket.ts
+++ b/src/env/socket.ts
@@ -8,6 +8,17 @@ import { getEnvValue } from './rewire'
 /**
  * SOCKET_ACCEPT_RISKS environment variable getter.
  * Whether to accept all Socket Security risks.
+ *
+ * @returns `true` if risks are accepted, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getSocketAcceptRisks } from '@socketsecurity/lib/env/socket'
+ *
+ * if (getSocketAcceptRisks()) {
+ *   console.log('All risks accepted')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketAcceptRisks(): boolean {
@@ -17,6 +28,16 @@ export function getSocketAcceptRisks(): boolean {
 /**
  * SOCKET_API_BASE_URL environment variable getter.
  * Socket Security API base URL.
+ *
+ * @returns The API base URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiBaseUrl } from '@socketsecurity/lib/env/socket'
+ *
+ * const baseUrl = getSocketApiBaseUrl()
+ * // e.g. 'https://api.socket.dev' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketApiBaseUrl(): string | undefined {
@@ -26,6 +47,16 @@ export function getSocketApiBaseUrl(): string | undefined {
 /**
  * SOCKET_API_PROXY environment variable getter.
  * Proxy URL for Socket Security API requests.
+ *
+ * @returns The API proxy URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiProxy } from '@socketsecurity/lib/env/socket'
+ *
+ * const proxy = getSocketApiProxy()
+ * // e.g. 'http://proxy.example.com:8080' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketApiProxy(): string | undefined {
@@ -35,6 +66,16 @@ export function getSocketApiProxy(): string | undefined {
 /**
  * SOCKET_API_TIMEOUT environment variable getter.
  * Timeout in milliseconds for Socket Security API requests.
+ *
+ * @returns The timeout in milliseconds, or `0` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiTimeout } from '@socketsecurity/lib/env/socket'
+ *
+ * const timeout = getSocketApiTimeout()
+ * // e.g. 30000 or 0 if not set
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketApiTimeout(): number {
@@ -44,6 +85,16 @@ export function getSocketApiTimeout(): number {
 /**
  * SOCKET_API_TOKEN environment variable getter.
  * Socket Security API authentication token.
+ *
+ * @returns The API token, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketApiToken } from '@socketsecurity/lib/env/socket'
+ *
+ * const token = getSocketApiToken()
+ * // e.g. a Socket API token string or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketApiToken(): string | undefined {
@@ -53,6 +104,16 @@ export function getSocketApiToken(): string | undefined {
 /**
  * SOCKET_CACACHE_DIR environment variable getter.
  * Overrides the default Socket cacache directory location.
+ *
+ * @returns The cacache directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketCacacheDir } from '@socketsecurity/lib/env/socket'
+ *
+ * const dir = getSocketCacacheDir()
+ * // e.g. '/tmp/.socket-cache' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketCacacheDir(): string | undefined {
@@ -62,6 +123,16 @@ export function getSocketCacacheDir(): string | undefined {
 /**
  * SOCKET_CONFIG environment variable getter.
  * Socket Security configuration file path.
+ *
+ * @returns The config file path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketConfig } from '@socketsecurity/lib/env/socket'
+ *
+ * const config = getSocketConfig()
+ * // e.g. '/tmp/project/socket.yml' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketConfig(): string | undefined {
@@ -71,6 +142,16 @@ export function getSocketConfig(): string | undefined {
 /**
  * SOCKET_DEBUG environment variable getter.
  * Controls Socket-specific debug output.
+ *
+ * @returns The Socket debug filter, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketDebug } from '@socketsecurity/lib/env/socket'
+ *
+ * const debug = getSocketDebug()
+ * // e.g. '*' or 'api' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketDebug(): string | undefined {
@@ -80,6 +161,16 @@ export function getSocketDebug(): string | undefined {
 /**
  * SOCKET_DLX_DIR environment variable getter.
  * Overrides the default Socket DLX directory location.
+ *
+ * @returns The DLX directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketDlxDirEnv } from '@socketsecurity/lib/env/socket'
+ *
+ * const dlxDir = getSocketDlxDirEnv()
+ * // e.g. '/tmp/.socket-dlx' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketDlxDirEnv(): string | undefined {
@@ -89,6 +180,16 @@ export function getSocketDlxDirEnv(): string | undefined {
 /**
  * SOCKET_HOME environment variable getter.
  * Socket Security home directory path.
+ *
+ * @returns The Socket home directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketHome } from '@socketsecurity/lib/env/socket'
+ *
+ * const home = getSocketHome()
+ * // e.g. '/tmp/.socket' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketHome(): string | undefined {
@@ -98,6 +199,17 @@ export function getSocketHome(): string | undefined {
 /**
  * SOCKET_NO_API_TOKEN environment variable getter.
  * Whether to skip Socket Security API token requirement.
+ *
+ * @returns `true` if the API token requirement is skipped, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getSocketNoApiToken } from '@socketsecurity/lib/env/socket'
+ *
+ * if (getSocketNoApiToken()) {
+ *   console.log('API token requirement skipped')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketNoApiToken(): boolean {
@@ -107,6 +219,16 @@ export function getSocketNoApiToken(): boolean {
 /**
  * SOCKET_NPM_REGISTRY environment variable getter.
  * Socket NPM registry URL (alternative name).
+ *
+ * @returns The Socket NPM registry URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketNpmRegistry } from '@socketsecurity/lib/env/socket'
+ *
+ * const registry = getSocketNpmRegistry()
+ * // e.g. 'https://npm.socket.dev/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketNpmRegistry(): string | undefined {
@@ -116,6 +238,16 @@ export function getSocketNpmRegistry(): string | undefined {
 /**
  * SOCKET_ORG_SLUG environment variable getter.
  * Socket Security organization slug identifier.
+ *
+ * @returns The organization slug, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketOrgSlug } from '@socketsecurity/lib/env/socket'
+ *
+ * const slug = getSocketOrgSlug()
+ * // e.g. 'my-org' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketOrgSlug(): string | undefined {
@@ -125,6 +257,16 @@ export function getSocketOrgSlug(): string | undefined {
 /**
  * SOCKET_REGISTRY_URL environment variable getter.
  * Socket Registry URL for package installation.
+ *
+ * @returns The Socket registry URL, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getSocketRegistryUrl } from '@socketsecurity/lib/env/socket'
+ *
+ * const registryUrl = getSocketRegistryUrl()
+ * // e.g. 'https://registry.socket.dev/' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketRegistryUrl(): string | undefined {
@@ -134,6 +276,17 @@ export function getSocketRegistryUrl(): string | undefined {
 /**
  * SOCKET_VIEW_ALL_RISKS environment variable getter.
  * Whether to view all Socket Security risks.
+ *
+ * @returns `true` if viewing all risks, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getSocketViewAllRisks } from '@socketsecurity/lib/env/socket'
+ *
+ * if (getSocketViewAllRisks()) {
+ *   console.log('Viewing all risks')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSocketViewAllRisks(): boolean {
diff --git a/src/env/temp-dir.ts b/src/env/temp-dir.ts
index 90236187..72b14753 100644
--- a/src/env/temp-dir.ts
+++ b/src/env/temp-dir.ts
@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * TEMP environment variable.
  * Windows temporary directory path.
+ *
+ * @returns The Windows temp directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTemp } from '@socketsecurity/lib/env/temp-dir'
+ *
+ * const temp = getTemp()
+ * // e.g. 'C:\\Windows\\Temp' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getTemp(): string | undefined {
@@ -17,6 +27,16 @@ export function getTemp(): string | undefined {
 /**
  * TMP environment variable.
  * Alternative temporary directory path.
+ *
+ * @returns The alternative temp directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTmp } from '@socketsecurity/lib/env/temp-dir'
+ *
+ * const tmp = getTmp()
+ * // e.g. '/tmp' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getTmp(): string | undefined {
@@ -26,6 +46,16 @@ export function getTmp(): string | undefined {
 /**
  * TMPDIR environment variable.
  * Unix/macOS temporary directory path.
+ *
+ * @returns The Unix/macOS temp directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTmpdir } from '@socketsecurity/lib/env/temp-dir'
+ *
+ * const tmpdir = getTmpdir()
+ * // e.g. '/tmp' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getTmpdir(): string | undefined {
diff --git a/src/env/term.ts b/src/env/term.ts
index b6583d32..de0e2f6c 100644
--- a/src/env/term.ts
+++ b/src/env/term.ts
@@ -5,6 +5,19 @@
 
 import { getEnvValue } from './rewire'
 
+/**
+ * Returns the value of the TERM environment variable.
+ *
+ * @returns The terminal type identifier, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getTerm } from '@socketsecurity/lib/env/term'
+ *
+ * const term = getTerm()
+ * // e.g. 'xterm-256color' or undefined
+ * ```
+ */
 /*@__NO_SIDE_EFFECTS__*/
 export function getTerm(): string | undefined {
   return getEnvValue('TERM')
diff --git a/src/env/test.ts b/src/env/test.ts
index 10bf3116..f6ed9ed4 100644
--- a/src/env/test.ts
+++ b/src/env/test.ts
@@ -10,6 +10,16 @@ import { getEnvValue } from './rewire'
 /**
  * JEST_WORKER_ID environment variable.
  * Set when running tests with Jest.
+ *
+ * @returns The Jest worker ID string, or empty string if not set
+ *
+ * @example
+ * ```typescript
+ * import { getJestWorkerId } from '@socketsecurity/lib/env/test'
+ *
+ * const workerId = getJestWorkerId()
+ * // e.g. '1' when running in Jest, or ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getJestWorkerId(): string {
@@ -19,6 +29,17 @@ export function getJestWorkerId(): string {
 /**
  * VITEST environment variable.
  * Set when running tests with Vitest.
+ *
+ * @returns `true` if running in Vitest, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { getVitest } from '@socketsecurity/lib/env/test'
+ *
+ * if (getVitest()) {
+ *   console.log('Running in Vitest')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getVitest(): boolean {
@@ -28,6 +49,17 @@ export function getVitest(): boolean {
 /**
  * Check if code is running in a test environment.
  * Checks NODE_ENV, VITEST, and JEST_WORKER_ID.
+ *
+ * @returns `true` if running in a test environment, `false` otherwise
+ *
+ * @example
+ * ```typescript
+ * import { isTest } from '@socketsecurity/lib/env/test'
+ *
+ * if (isTest()) {
+ *   console.log('Running in test environment')
+ * }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isTest(): boolean {
diff --git a/src/env/windows.ts b/src/env/windows.ts
index 35efc482..fc05dfe1 100644
--- a/src/env/windows.ts
+++ b/src/env/windows.ts
@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * APPDATA environment variable.
  * Points to the Application Data directory on Windows.
+ *
+ * @returns The Windows AppData roaming directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getAppdata } from '@socketsecurity/lib/env/windows'
+ *
+ * const appdata = getAppdata()
+ * // e.g. 'C:\\Users\\Public\\AppData\\Roaming' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getAppdata(): string | undefined {
@@ -17,6 +27,16 @@ export function getAppdata(): string | undefined {
 /**
  * COMSPEC environment variable.
  * Points to the Windows command processor (typically cmd.exe).
+ *
+ * @returns The path to the command processor, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getComspec } from '@socketsecurity/lib/env/windows'
+ *
+ * const comspec = getComspec()
+ * // e.g. 'C:\\Windows\\system32\\cmd.exe' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getComspec(): string | undefined {
@@ -26,6 +46,16 @@ export function getComspec(): string | undefined {
 /**
  * LOCALAPPDATA environment variable.
  * Points to the Local Application Data directory on Windows.
+ *
+ * @returns The Windows local AppData directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getLocalappdata } from '@socketsecurity/lib/env/windows'
+ *
+ * const localAppdata = getLocalappdata()
+ * // e.g. 'C:\\Users\\Public\\AppData\\Local' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getLocalappdata(): string | undefined {
@@ -35,6 +65,16 @@ export function getLocalappdata(): string | undefined {
 /**
  * USERPROFILE environment variable.
  * Windows user home directory path.
+ *
+ * @returns The Windows user profile directory, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getUserprofile } from '@socketsecurity/lib/env/windows'
+ *
+ * const userprofile = getUserprofile()
+ * // e.g. 'C:\\Users\\Public' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getUserprofile(): string | undefined {
diff --git a/src/env/xdg.ts b/src/env/xdg.ts
index 00c81b54..d63c05f1 100644
--- a/src/env/xdg.ts
+++ b/src/env/xdg.ts
@@ -8,6 +8,16 @@ import { getEnvValue } from './rewire'
 /**
  * XDG_CACHE_HOME environment variable.
  * XDG Base Directory specification cache directory.
+ *
+ * @returns The XDG cache directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getXdgCacheHome } from '@socketsecurity/lib/env/xdg'
+ *
+ * const cacheDir = getXdgCacheHome()
+ * // e.g. '/tmp/.cache' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getXdgCacheHome(): string | undefined {
@@ -17,6 +27,16 @@ export function getXdgCacheHome(): string | undefined {
 /**
  * XDG_CONFIG_HOME environment variable.
  * XDG Base Directory specification config directory.
+ *
+ * @returns The XDG config directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getXdgConfigHome } from '@socketsecurity/lib/env/xdg'
+ *
+ * const configDir = getXdgConfigHome()
+ * // e.g. '/tmp/.config' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getXdgConfigHome(): string | undefined {
@@ -26,6 +46,16 @@ export function getXdgConfigHome(): string | undefined {
 /**
  * XDG_DATA_HOME environment variable.
  * Points to the user's data directory on Unix systems.
+ *
+ * @returns The XDG data directory path, or `undefined` if not set
+ *
+ * @example
+ * ```typescript
+ * import { getXdgDataHome } from '@socketsecurity/lib/env/xdg'
+ *
+ * const dataDir = getXdgDataHome()
+ * // e.g. '/tmp/.local/share' or undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getXdgDataHome(): string | undefined {