diff --git a/web/.npmignore b/web/.npmignore
index 1f678285..07fd3765 100644
--- a/web/.npmignore
+++ b/web/.npmignore
@@ -26,6 +26,7 @@ build/
 *.tmp
 .DS_Store
 node_modules/
+!node_modules/authenticate-pam/
 pnpm-lock.yaml
 
 # Native build scripts - not needed for npm package
diff --git a/web/docs/npm.md b/web/docs/npm.md
index cc5e37a0..06176644 100644
--- a/web/docs/npm.md
+++ b/web/docs/npm.md
@@ -379,6 +379,41 @@ The npm package works seamlessly alongside the Mac app:
 **Cause**: Network issues or unsupported platform/Node version
 **Result**: Automatic fallback to source compilation
 
+#### npm_config_prefix Conflict with NVM
+**Error**: Global npm installs fail or install to wrong location when using NVM
+**Symptoms**: 
+- `npm install -g` installs packages to system location instead of NVM directory
+- Command not found errors after global install
+- Permission errors during global installation
+
+**Cause**: The `npm_config_prefix` environment variable overrides NVM's per-version npm configuration
+
+**Detection**: VibeTunnel's postinstall script will warn if this conflict is detected:
+```
+⚠️  Detected npm_config_prefix conflict with NVM
+   npm_config_prefix: /usr/local
+   NVM Node path: /home/user/.nvm/versions/node/v20.19.4/bin/node
+   This may cause npm global installs to fail or install in wrong location.
+```
+
+**Solution**: Unset the conflicting environment variable:
+```bash
+unset npm_config_prefix
+```
+
+**Permanent fix**: Remove or comment out `npm_config_prefix` settings in:
+- `~/.bashrc`
+- `~/.bash_profile` 
+- `~/.profile`
+- `/etc/profile`
+- CI/CD environment configurations
+
+**Common sources of this issue**:
+- Previous system-wide npm installations
+- Docker containers with npm pre-installed
+- CI/CD environments with global npm configuration
+- Package managers that set global npm prefix
+
 ### Debugging Installation
 ```bash
 # Verbose npm install
diff --git a/web/scripts/postinstall-npm.js b/web/scripts/postinstall-npm.js
index 157d4686..8409e831 100755
--- a/web/scripts/postinstall-npm.js
+++ b/web/scripts/postinstall-npm.js
@@ -12,6 +12,22 @@ const os = require('os');
 
 console.log('Setting up native modules for VibeTunnel...');
 
+// Check for npm_config_prefix conflict with NVM
+if (process.env.npm_config_prefix && process.env.NVM_DIR) {
+  const nvmNodeVersion = process.execPath;
+  const npmPrefix = process.env.npm_config_prefix;
+  
+  // Check if npm_config_prefix conflicts with NVM path
+  if (!nvmNodeVersion.includes(npmPrefix) && nvmNodeVersion.includes('.nvm')) {
+    console.warn('⚠️  Detected npm_config_prefix conflict with NVM');
+    console.warn(`   npm_config_prefix: ${npmPrefix}`);
+    console.warn(`   NVM Node path: ${nvmNodeVersion}`);
+    console.warn('   This may cause npm global installs to fail or install in wrong location.');
+    console.warn('   Run: unset npm_config_prefix');
+    console.warn('   Then reinstall VibeTunnel for proper NVM compatibility.');
+  }
+}
+
 // Check if we're in development (has src directory) or npm install
 const isDevelopment = fs.existsSync(path.join(__dirname, '..', 'src'));