diff --git a/.claude/skills/updating/reference.md b/.claude/skills/updating/reference.md
new file mode 100644
index 0000000..81177af
--- /dev/null
+++ b/.claude/skills/updating/reference.md
@@ -0,0 +1,76 @@
+# updating Reference Documentation
+
+## Table of Contents
+
+1. [How the Update Script Works](#how-the-update-script-works)
+2. [Files Changed After Update](#files-changed-after-update)
+3. [Validation Commands](#validation-commands)
+4. [Troubleshooting](#troubleshooting)
+
+---
+
+## How the Update Script Works
+
+`pnpm run update` runs `scripts/update.mjs` which performs:
+
+```bash
+# 1. Run taze recursively with write mode
+pnpm exec taze -r -w
+
+# 2. Force-update Socket scoped packages (bypasses taze maturity period)
+pnpm update @socketsecurity/* @socketregistry/* @socketbin/* --latest -r
+
+# 3. pnpm install runs automatically to reconcile lockfile
+```
+
+### Repo Structure
+
+- **Single package** (not a monorepo, no `packages/` directory)
+- Dependencies pinned to exact versions in `package.json`
+- Uses `pnpm.overrides` and `pnpm.patchedDependencies` for dependency control
+- Has a `@socketsecurity/lib-stable` self-referencing alias used by the update script itself
+
+---
+
+## Files Changed After Update
+
+- `package.json` - Dependency version pins
+- `pnpm-lock.yaml` - Lock file
+
+---
+
+## Validation Commands
+
+```bash
+# Fix lint issues
+pnpm run fix --all
+
+# Run all checks (lint + type check)
+pnpm run check --all
+
+# Run tests
+pnpm test
+```
+
+---
+
+## Troubleshooting
+
+### taze Fails to Detect Updates
+
+**Cause:** taze has a maturity period for new releases.
+**Solution:** Socket packages are force-updated separately via `pnpm update --latest`.
+
+### Lock File Conflicts
+
+**Solution:**
+```bash
+rm pnpm-lock.yaml
+pnpm install
+```
+
+### Self-Reference Alias
+
+The `@socketsecurity/lib-stable` devDependency points to a published version
+of this package itself. It must remain on a stable release (used by
+`scripts/update.mjs` to avoid circular issues).
diff --git a/package.json b/package.json
index 0e4cf82..2a98485 100644
--- a/package.json
+++ b/package.json
@@ -732,7 +732,7 @@
     "@npmcli/package-json": "7.0.0",
     "@npmcli/promise-spawn": "8.0.3",
     "@socketregistry/is-unicode-supported": "1.0.5",
-    "@socketregistry/packageurl-js": "1.3.5",
+    "@socketregistry/packageurl-js": "1.4.1",
     "@socketregistry/yocto-spinner": "1.0.25",
     "@socketsecurity/lib-stable": "npm:@socketsecurity/lib@5.11.4",
     "@types/node": "24.9.2",
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 65fb18d..2a1c6d0 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -118,8 +118,8 @@ importers:
         specifier: 1.0.5
         version: 1.0.5
       '@socketregistry/packageurl-js':
-        specifier: 1.3.5
-        version: 1.3.5
+        specifier: 1.4.1
+        version: 1.4.1
       '@socketregistry/yocto-spinner':
         specifier: 1.0.25
         version: 1.0.25
@@ -1425,9 +1425,9 @@ packages:
     resolution: {integrity: sha512-l3wz0cknjyGlI2iCyZxp50FJhtUFXkdZR6CfUU7OfNxE7I4CRBdsvORLgV+JPwqQQErRO/CZgKsbDHefd3puYA==}
     engines: {node: '>=18'}
 
-  '@socketregistry/packageurl-js@1.3.5':
-    resolution: {integrity: sha512-Fl4GNUJ/z3IBJBGj4IsJfuRGUBCRMgX0df0mb5x5buaCPDKC+NhMhAFuxpc3viLSHV12CO2rGaNCf4fBYWI0FA==}
-    engines: {node: '>=18', pnpm: '>=10.16.0'}
+  '@socketregistry/packageurl-js@1.4.1':
+    resolution: {integrity: sha512-t/UrOd1DMYXcGuKo2v07WMbuHCMlKBKOriTHu4cn9OIxfj1qWKoF/kpOswGHOWkG5zwj2Ke/2+qLiDugmx5z+A==}
+    engines: {node: '>=18.20.4', pnpm: '>=10.25.0'}
 
   '@socketregistry/yocto-spinner@1.0.25':
     resolution: {integrity: sha512-f8AqJMH1+BL15G6bHDzb1jyY+wW4gOYQs5JumSxmnE/H/+KgqbIZgaPwDdRwoeciDGojoSVrRHiTZjbe7n7dJA==}
@@ -4196,7 +4196,9 @@ snapshots:
 
   '@socketregistry/is-unicode-supported@1.0.5': {}
 
-  '@socketregistry/packageurl-js@1.3.5': {}
+  '@socketregistry/packageurl-js@1.4.1':
+    dependencies:
+      picomatch: 4.0.4
 
   '@socketregistry/yocto-spinner@1.0.25':
     dependencies: