Improve README value proposition and clarity

- Enhance opening description with clear benefits
- Add 'Why use this?' section with emojis for scannability
- Fix pnpm overrides syntax (use pnpm.overrides field)
- Reorganize usage examples by use case (Parse/Build/Constructor/Convert)
- Make examples more concise and scannable

Author: jdalton

README.md

@@ -6,24 +6,27 @@
 [![Follow @SocketSecurity](https://img.shields.io/twitter/follow/SocketSecurity?style=social)](https://twitter.com/SocketSecurity)
 [![Follow @socket.dev on Bluesky](https://img.shields.io/badge/[email protected]?style=social&logo=bluesky)](https://bsky.app/profile/socket.dev)
 
-TypeScript-first Package URL parser. Drop-in replacement for [`packageurl-js`](https://socket.dev/npm/package/packageurl-js).
+TypeScript-first Package URL (purl) parser and builder. **Drop-in replacement** for [`packageurl-js`](https://socket.dev/npm/package/packageurl-js) with better types and zero dependencies.
 
-- TypeScript support
-- Zero dependencies
-- [Package URL spec](https://github.com/package-url/purl-spec) compliant
-- Builder pattern API
+**Why use this?**
+- 🎯 **TypeScript-first**: Full type safety and IntelliSense
+- 📦 **Zero dependencies**: No supply chain bloat
+- ✅ **Spec compliant**: Implements [Package URL specification](https://github.com/package-url/purl-spec)
+- 🔨 **Builder API**: Fluent, ecosystem-specific builders
 
 ## Installation
 
 ```sh
 pnpm install @socketregistry/packageurl-js
 ```
 
-**Package override** (recommended):
+**Package override** (recommended for drop-in replacement):
 ```json
 {
-  "overrides": {
-    "packageurl-js": "npm:@socketregistry/packageurl-js@^1"
+  "pnpm": {
+    "overrides": {
+      "packageurl-js": "npm:@socketregistry/packageurl-js@^1"
+    }
   }
 }
 ```
@@ -32,49 +35,57 @@ pnpm install @socketregistry/packageurl-js
 
 ## Usage
 
+**Parse existing purls:**
 ```javascript
-import { PackageURL, PackageURLBuilder, UrlConverter } from '@socketregistry/packageurl-js'
+import { PackageURL } from '@socketregistry/packageurl-js'
 
-// Parse from string
 const purl = PackageURL.fromString('pkg:npm/[email protected]')
 console.log(purl.name)      // 'lodash'
+console.log(purl.version)   // '4.17.21'
+```
 
-// Create from components
-const newPurl = new PackageURL('npm', null, 'express', '4.18.2')
-// -> 'pkg:npm/[email protected]'
+**Build new purls (recommended):**
+```javascript
+import { PackageURLBuilder } from '@socketregistry/packageurl-js'
 
-// Builder pattern - ecosystem-specific builders
-const npmPurl = PackageURLBuilder
-  .npm()
-  .name('lodash')
-  .version('4.17.21')
-  .build()
+// npm packages
+PackageURLBuilder.npm().name('lodash').version('4.17.21').build()
 // -> 'pkg:npm/[email protected]'
 
-const pythonPurl = PackageURLBuilder
-  .pypi()
-  .name('requests')
-  .version('2.28.1')
-  .build()
+// Python packages
+PackageURLBuilder.pypi().name('requests').version('2.28.1').build()
 // -> 'pkg:pypi/[email protected]'
 
-const javaPurl = PackageURLBuilder
-  .maven()
+// Maven with namespace and qualifiers
+PackageURLBuilder.maven()
   .namespace('org.springframework')
   .name('spring-core')
   .version('5.3.21')
   .qualifier('classifier', 'sources')
   .build()
 // -> 'pkg:maven/org.springframework/[email protected]?classifier=sources'
+```
+
+**Constructor API:**
+```javascript
+import { PackageURL } from '@socketregistry/packageurl-js'
+
+new PackageURL('npm', null, 'express', '4.18.2')
+// -> 'pkg:npm/[email protected]'
 
-// Subpaths for packages like npm/@babel/runtime
-const subpathPurl = new PackageURL('npm', '@babel', 'runtime', '7.18.6', null, 'helpers/typeof.js')
+// With namespace and subpath
+new PackageURL('npm', '@babel', 'runtime', '7.18.6', null, 'helpers/typeof.js')
 // -> 'pkg:npm/%40babel/[email protected]#helpers/typeof.js'
+```
 
-// URL conversion
-const repoUrl = UrlConverter.toRepositoryUrl(purl)
+**Convert to URLs:**
+```javascript
+import { UrlConverter } from '@socketregistry/packageurl-js'
+
+UrlConverter.toRepositoryUrl(purl)
 // -> 'https://github.com/lodash/lodash'
-const downloadUrl = UrlConverter.toDownloadUrl(purl)
+
+UrlConverter.toDownloadUrl(purl)
 // -> 'https://registry.npmjs.org/lodash/-/lodash-4.17.21.tgz'
 ```