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 {
diff --git a/src/packages/edit.ts b/src/packages/edit.ts
index 2daa81c7..16b20182 100644
--- a/src/packages/edit.ts
+++ b/src/packages/edit.ts
@@ -167,6 +167,13 @@ function getUtil() {
 
 /**
  * Get the EditablePackageJson class for package.json manipulation.
+ *
+ * @example
+ * ```typescript
+ * const EditablePackageJson = getEditablePackageJsonClass()
+ * const pkg = await EditablePackageJson.load('/tmp/my-project')
+ * console.log(pkg.content.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getEditablePackageJsonClass(): EditablePackageJsonConstructor {
@@ -467,6 +474,11 @@ export function getEditablePackageJsonClass(): EditablePackageJsonConstructor {
 
 /**
  * Convert a package.json object to an editable instance.
+ *
+ * @example
+ * ```typescript
+ * const editable = pkgJsonToEditable({ name: 'my-pkg', version: '1.0.0' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function pkgJsonToEditable(
@@ -485,6 +497,14 @@ export function pkgJsonToEditable(
 
 /**
  * Convert package.json to editable instance with file persistence.
+ *
+ * @example
+ * ```typescript
+ * const editable = await toEditablePackageJson(
+ *   { name: 'my-pkg', version: '1.0.0' },
+ *   { path: '/tmp/my-project' }
+ * )
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function toEditablePackageJson(
@@ -519,6 +539,14 @@ export async function toEditablePackageJson(
 
 /**
  * Convert package.json to editable instance with file persistence synchronously.
+ *
+ * @example
+ * ```typescript
+ * const editable = toEditablePackageJsonSync(
+ *   { name: 'my-pkg', version: '1.0.0' },
+ *   { path: '/tmp/my-project' }
+ * )
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function toEditablePackageJsonSync(
diff --git a/src/packages/exports.ts b/src/packages/exports.ts
index 0b9528ea..9a1a122e 100644
--- a/src/packages/exports.ts
+++ b/src/packages/exports.ts
@@ -9,6 +9,13 @@ import { isObject, isObjectObject } from '../objects'
 
 /**
  * Find types definition for a specific subpath in package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': { types: './dist/index.d.ts', import: './dist/index.js' } }
+ * const types = findTypesForSubpath(exports, './dist/index.js')
+ * // types === './dist/index.d.ts'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function findTypesForSubpath(
@@ -53,6 +60,12 @@ export function findTypesForSubpath(
 
 /**
  * Get subpaths from package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': './index.js', './utils': './utils.js' }
+ * getSubpaths(exports) // ['.', './utils']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getSubpaths(entryExports: unknown): string[] {
@@ -67,6 +80,12 @@ export function getSubpaths(entryExports: unknown): string[] {
 
 /**
  * Get file paths from package exports.
+ *
+ * @example
+ * ```typescript
+ * const exports = { '.': './dist/index.js', './utils': './dist/utils.js' }
+ * getExportFilePaths(exports) // ['./dist/index.js', './dist/utils.js']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getExportFilePaths(entryExports: unknown): string[] {
@@ -119,6 +138,12 @@ export function getExportFilePaths(entryExports: unknown): string[] {
 
 /**
  * Check if package exports use conditional patterns (e.g., import/require).
+ *
+ * @example
+ * ```typescript
+ * isConditionalExports({ import: './index.mjs', require: './index.cjs' }) // true
+ * isConditionalExports({ '.': './index.js' })                            // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isConditionalExports(entryExports: unknown): boolean {
@@ -145,6 +170,12 @@ export function isConditionalExports(entryExports: unknown): boolean {
 
 /**
  * Check if package exports use subpath patterns (keys starting with '.').
+ *
+ * @example
+ * ```typescript
+ * isSubpathExports({ '.': './index.js', './utils': './utils.js' }) // true
+ * isSubpathExports({ import: './index.mjs' })                     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isSubpathExports(entryExports: unknown): boolean {
@@ -165,6 +196,15 @@ export function isSubpathExports(entryExports: unknown): boolean {
 
 /**
  * Normalize package.json exports field to canonical format.
+ *
+ * @example
+ * ```typescript
+ * resolvePackageJsonEntryExports('./index.js')
+ * // { '.': './index.js' }
+ *
+ * resolvePackageJsonEntryExports({ '.': './index.js' })
+ * // { '.': './index.js' }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolvePackageJsonEntryExports(entryExports: unknown): unknown {
diff --git a/src/packages/licenses.ts b/src/packages/licenses.ts
index 01ffb99e..bcd20730 100644
--- a/src/packages/licenses.ts
+++ b/src/packages/licenses.ts
@@ -74,6 +74,13 @@ export interface LicenseVisitor {
 
 /**
  * Collect licenses that are incompatible (copyleft).
+ *
+ * @example
+ * ```typescript
+ * const nodes = [{ license: 'MIT' }, { license: 'GPL-3.0' }]
+ * const incompatible = collectIncompatibleLicenses(nodes)
+ * // incompatible contains only the GPL-3.0 node
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function collectIncompatibleLicenses(
@@ -91,6 +98,12 @@ export function collectIncompatibleLicenses(
 
 /**
  * Collect warnings from license nodes.
+ *
+ * @example
+ * ```typescript
+ * const nodes = [{ license: 'UNLICENSED' }]
+ * collectLicenseWarnings(nodes) // ['Package is unlicensed']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function collectLicenseWarnings(licenseNodes: LicenseNode[]): string[] {
@@ -112,6 +125,13 @@ export function collectLicenseWarnings(licenseNodes: LicenseNode[]): string[] {
 
 /**
  * Create an AST node from a raw node.
+ *
+ * @example
+ * ```typescript
+ * const raw = { license: 'MIT' }
+ * const node = createAstNode(raw)
+ * // node.type === 'License'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createAstNode(rawNode: SpdxAstNode): InternalAstNode {
@@ -122,6 +142,17 @@ export function createAstNode(rawNode: SpdxAstNode): InternalAstNode {
 
 /**
  * Create a binary operation AST node.
+ *
+ * @example
+ * ```typescript
+ * const raw = {
+ *   left: { license: 'MIT' },
+ *   conjunction: 'OR' as const,
+ *   right: { license: 'Apache-2.0' }
+ * }
+ * const node = createBinaryOperationNode(raw)
+ * // node.type === 'BinaryOperation'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createBinaryOperationNode(
@@ -156,6 +187,12 @@ export function createBinaryOperationNode(
 
 /**
  * Create a license AST node.
+ *
+ * @example
+ * ```typescript
+ * const node = createLicenseNode({ license: 'MIT' })
+ * // node.type === 'License' && node.license === 'MIT'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createLicenseNode(
@@ -170,6 +207,12 @@ export function createLicenseNode(
 
 /**
  * Parse an SPDX license expression into an AST.
+ *
+ * @example
+ * ```typescript
+ * const ast = parseSpdxExp('MIT OR Apache-2.0')
+ * // ast is a BinaryOperation node with MIT and Apache-2.0 leaves
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function parseSpdxExp(spdxExp: string): SpdxAstNode | undefined {
@@ -184,6 +227,12 @@ export function parseSpdxExp(spdxExp: string): SpdxAstNode | undefined {
 
 /**
  * Parse package license field into structured license nodes.
+ *
+ * @example
+ * ```typescript
+ * const nodes = resolvePackageLicenses('MIT', '/tmp/my-project')
+ * // [{ license: 'MIT' }]
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolvePackageLicenses(
@@ -238,6 +287,16 @@ export function resolvePackageLicenses(
 
 /**
  * Traverse SPDX license AST and invoke visitor callbacks for each node.
+ *
+ * @example
+ * ```typescript
+ * const ast = parseSpdxExp('MIT OR Apache-2.0')
+ * const licenses: string[] = []
+ * if (ast) {
+ *   visitLicenses(ast, { License(node) { licenses.push(node.license) } })
+ * }
+ * // licenses === ['MIT', 'Apache-2.0']
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function visitLicenses(ast: SpdxAstNode, visitor: LicenseVisitor): void {
diff --git a/src/packages/manifest.ts b/src/packages/manifest.ts
index 304d945d..66c69f53 100644
--- a/src/packages/manifest.ts
+++ b/src/packages/manifest.ts
@@ -32,6 +32,14 @@ const pkgScopePrefixRegExp = /^@socketregistry\//
 
 /**
  * Create a package.json object for a Socket registry package.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = createPackageJson('is-number', 'packages/npm/is-number', {
+ *   version: '1.0.0',
+ *   description: 'Check if a value is a number'
+ * })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function createPackageJson(
@@ -125,6 +133,11 @@ export function createPackageJson(
 
 /**
  * Fetch the manifest for a package.
+ *
+ * @example
+ * ```typescript
+ * const manifest = await fetchPackageManifest('lodash@4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function fetchPackageManifest(
@@ -170,6 +183,11 @@ export async function fetchPackageManifest(
 
 /**
  * Fetch the packument (package document) for a package.
+ *
+ * @example
+ * ```typescript
+ * const packument = await fetchPackagePackument('lodash')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function fetchPackagePackument(
diff --git a/src/packages/normalize.ts b/src/packages/normalize.ts
index 15560ac7..112b07a7 100644
--- a/src/packages/normalize.ts
+++ b/src/packages/normalize.ts
@@ -25,6 +25,12 @@ function getEscapedScopeRegExp(): RegExp {
 
 /**
  * Normalize a package.json object with standard npm package normalization.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = { name: 'my-pkg', version: '1.0.0' }
+ * const normalized = normalizePackageJson(pkgJson)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function normalizePackageJson(
@@ -67,6 +73,12 @@ export function normalizePackageJson(
 
 /**
  * Extract escaped scope from a Socket registry package name.
+ *
+ * @example
+ * ```typescript
+ * resolveEscapedScope('babel__core') // 'babel__'
+ * resolveEscapedScope('lodash')      // undefined
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolveEscapedScope(
@@ -79,6 +91,11 @@ export function resolveEscapedScope(
 
 /**
  * Resolve original package name from Socket registry package name.
+ *
+ * @example
+ * ```typescript
+ * resolveOriginalPackageName('@socketregistry/is-number') // 'is-number'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolveOriginalPackageName(sockRegPkgName: string): string {
@@ -93,6 +110,11 @@ export function resolveOriginalPackageName(sockRegPkgName: string): string {
 
 /**
  * Convert escaped scope to standard npm scope format.
+ *
+ * @example
+ * ```typescript
+ * unescapeScope('babel__') // '@babel'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function unescapeScope(escapedScope: string): string {
diff --git a/src/packages/operations.ts b/src/packages/operations.ts
index 6ecdc075..d1114d0b 100644
--- a/src/packages/operations.ts
+++ b/src/packages/operations.ts
@@ -54,6 +54,11 @@ const fetcher = makeFetchHappen.defaults({
 
 /**
  * Extract a package to a destination directory.
+ *
+ * @example
+ * ```typescript
+ * await extractPackage('lodash@4.17.21', { dest: '/tmp/lodash' })
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function extractPackage(
@@ -104,6 +109,11 @@ export async function extractPackage(
 
 /**
  * Find package extensions for a given package.
+ *
+ * @example
+ * ```typescript
+ * const extensions = findPackageExtensions('my-pkg', '1.0.0')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function findPackageExtensions(
@@ -134,6 +144,13 @@ export function findPackageExtensions(
 
 /**
  * Get the release tag for a version.
+ *
+ * @example
+ * ```typescript
+ * getReleaseTag('lodash@latest')    // 'latest'
+ * getReleaseTag('@scope/pkg@beta')  // 'beta'
+ * getReleaseTag('lodash')           // ''
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getReleaseTag(spec: string): string {
@@ -157,6 +174,11 @@ export function getReleaseTag(spec: string): string {
 
 /**
  * Pack a package tarball using pacote.
+ *
+ * @example
+ * ```typescript
+ * const tarball = await packPackage('lodash@4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function packPackage(
@@ -177,6 +199,12 @@ export async function packPackage(
 
 /**
  * Read and parse a package.json file asynchronously.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = await readPackageJson('/tmp/my-project')
+ * console.log(pkgJson?.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function readPackageJson(
@@ -205,6 +233,12 @@ export async function readPackageJson(
 
 /**
  * Read and parse package.json from a file path synchronously.
+ *
+ * @example
+ * ```typescript
+ * const pkgJson = readPackageJsonSync('/tmp/my-project')
+ * console.log(pkgJson?.name)
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function readPackageJsonSync(
@@ -237,6 +271,11 @@ export function readPackageJsonSync(
 
 /**
  * Resolve GitHub tarball URL for a package specifier.
+ *
+ * @example
+ * ```typescript
+ * const url = await resolveGitHubTgzUrl('my-pkg@1.0.0', '/tmp/my-project')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function resolveGitHubTgzUrl(
@@ -300,6 +339,12 @@ export async function resolveGitHubTgzUrl(
 
 /**
  * Resolve full package name from a PURL object with custom delimiter.
+ *
+ * @example
+ * ```typescript
+ * resolvePackageName({ name: 'core', namespace: '@babel' })  // '@babel/core'
+ * resolvePackageName({ name: 'lodash' })                     // 'lodash'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolvePackageName(
@@ -312,6 +357,12 @@ export function resolvePackageName(
 
 /**
  * Convert npm package name to Socket registry format with delimiter.
+ *
+ * @example
+ * ```typescript
+ * resolveRegistryPackageName('@babel/core') // 'babel__core'
+ * resolveRegistryPackageName('lodash')      // 'lodash'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function resolveRegistryPackageName(pkgName: string): string {
diff --git a/src/packages/provenance.ts b/src/packages/provenance.ts
index 8e2ca7ed..f27b475f 100644
--- a/src/packages/provenance.ts
+++ b/src/packages/provenance.ts
@@ -145,6 +145,12 @@ function isTrustedPublisher(value: unknown): boolean {
 
 /**
  * Convert raw attestation data to user-friendly provenance details.
+ *
+ * @example
+ * ```typescript
+ * const details = getProvenanceDetails(attestationData)
+ * // { level: 'trusted', repository: '...', commitSha: '...' }
+ * ```
  */
 export function getProvenanceDetails(attestationData: unknown): unknown {
   const attestations = getAttestations(attestationData)
@@ -208,6 +214,11 @@ export function getProvenanceDetails(attestationData: unknown): unknown {
 
 /**
  * Fetch package provenance information from npm registry.
+ *
+ * @example
+ * ```typescript
+ * const provenance = await fetchPackageProvenance('lodash', '4.17.21')
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export async function fetchPackageProvenance(
diff --git a/src/packages/specs.ts b/src/packages/specs.ts
index d37ba0d7..1d040a96 100644
--- a/src/packages/specs.ts
+++ b/src/packages/specs.ts
@@ -9,6 +9,12 @@ import { isNonEmptyString } from '../strings'
 
 /**
  * Extract user and project from GitHub repository URL.
+ *
+ * @example
+ * ```typescript
+ * getRepoUrlDetails('https://github.com/lodash/lodash.git')
+ * // { user: 'lodash', project: 'lodash' }
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function getRepoUrlDetails(repoUrl: string = ''): {
@@ -28,6 +34,12 @@ export function getRepoUrlDetails(repoUrl: string = ''): {
 
 /**
  * Generate GitHub API URL for a tag reference.
+ *
+ * @example
+ * ```typescript
+ * gitHubTagRefUrl('lodash', 'lodash', 'v4.17.21')
+ * // 'https://api.github.com/repos/lodash/lodash/git/ref/tags/v4.17.21'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function gitHubTagRefUrl(
@@ -40,6 +52,12 @@ export function gitHubTagRefUrl(
 
 /**
  * Generate GitHub tarball download URL for a commit SHA.
+ *
+ * @example
+ * ```typescript
+ * gitHubTgzUrl('lodash', 'lodash', 'abc123')
+ * // 'https://github.com/lodash/lodash/archive/abc123.tar.gz'
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function gitHubTgzUrl(
@@ -52,6 +70,12 @@ export function gitHubTgzUrl(
 
 /**
  * Check if a package specifier is a GitHub tarball URL.
+ *
+ * @example
+ * ```typescript
+ * isGitHubTgzSpec('https://github.com/user/repo/archive/abc123.tar.gz') // true
+ * isGitHubTgzSpec('lodash@4.17.21')                                     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isGitHubTgzSpec(spec: unknown, where?: string): boolean {
@@ -70,6 +94,12 @@ export function isGitHubTgzSpec(spec: unknown, where?: string): boolean {
 
 /**
  * Check if a package specifier is a GitHub URL with committish.
+ *
+ * @example
+ * ```typescript
+ * isGitHubUrlSpec('github:user/repo#v1.0.0') // true
+ * isGitHubUrlSpec('lodash@4.17.21')           // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isGitHubUrlSpec(spec: unknown, where?: string): boolean {
diff --git a/src/packages/validation.ts b/src/packages/validation.ts
index 4d7f326e..1155eadc 100644
--- a/src/packages/validation.ts
+++ b/src/packages/validation.ts
@@ -6,6 +6,12 @@ import validateNpmPackageName from '../external/validate-npm-package-name'
 
 /**
  * Check if package name is a blessed Socket.dev package.
+ *
+ * @example
+ * ```typescript
+ * isBlessedPackageName('@socketregistry/is-number') // true
+ * isBlessedPackageName('lodash')                    // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isBlessedPackageName(name: unknown): boolean {
@@ -21,6 +27,12 @@ export function isBlessedPackageName(name: unknown): boolean {
 
 /**
  * Check if a type string represents a registry fetcher type.
+ *
+ * @example
+ * ```typescript
+ * isRegistryFetcherType('range')   // true
+ * isRegistryFetcherType('git')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isRegistryFetcherType(type: string): boolean {
@@ -33,6 +45,12 @@ export function isRegistryFetcherType(type: string): boolean {
 
 /**
  * Check if a package name is valid according to npm naming rules.
+ *
+ * @example
+ * ```typescript
+ * isValidPackageName('my-package')   // true
+ * isValidPackageName('.invalid')     // false
+ * ```
  */
 /*@__NO_SIDE_EFFECTS__*/
 export function isValidPackageName(name: string): boolean {