docs(README): 'Migrating from UUID v4' section

Author: dingosky

README.md

@@ -28,6 +28,7 @@ randId()
   - [Overkill and Under Specify](#Overkill)
 - [Efficiencies](#Efficiencies)
 - [tl;dr](#tl;dr)
+- [Migrating from UUID v4](#UUIDv4Migration)
 
 ## <a name="Overview"></a>Overview
 
@@ -55,6 +56,63 @@ Random string generation can be thought of as a _transformation_ of some random
 
 [TOC](#TOC)
 
+### <a name="UUIDv4Migration"></a>Migrating from UUID v4
+
+- UUID v4 has 122 bits of entropy (36 chars with hyphens; 32 hex chars without). Default `puid-js` IDs are ~132 bits in 22 URL/file-safe chars.
+
+Replace uuidv4() one-off
+
+```js
+// before
+import { v4 as uuidv4 } from 'uuid'
+const id = uuidv4()
+
+// after
+import { generate, Chars } from 'puid-js'
+// ≈132 bits, 22 chars, URL/file-safe
+const id = generate({ chars: Chars.Safe64 })
+
+// hex-like (32 chars, 128 bits)
+const hexId = generate({ bits: 128, chars: Chars.HexUpper })
+```
+
+Use a generator in hot paths
+
+```js
+import { puid, Chars } from 'puid-js'
+
+// explicit bits (≈ UUID v4 or better)
+const { generator: id128 } = puid({ bits: 128, chars: Chars.Safe64 })
+
+// or size by total/risk (10M IDs, 1e-12 repeat risk)
+const { generator: sized } = puid({ total: 1e7, risk: 1e12, chars: Chars.Safe64 })
+
+const id = id128()
+```
+
+Browser
+
+```js
+import { generate, Chars } from 'puid-js/web'
+const id = generate({ chars: Chars.Safe64 })
+```
+
+Error handling for generate()
+
+```js
+try {
+  generate({ total: 1000 }) // invalid: missing risk
+} catch (err) {
+  // handle invalid config
+}
+```
+
+Notes
+- If your DB/validators assume UUID format/length, update to accept generic ID strings. Default Safe64 is 22 chars; HexUpper at 128 bits is 32 chars.
+- Charset guidance: Safe64 (shortest URL/file-safe), Hex/HexUpper (compat), Safe32/WordSafe32 (human-friendlier).
+
+And remember, you rarely need the 122-bytes of entropy provided by UUID, and you certainly never need the inefficiency of the string representation!
+
 ### <a name="Usage"></a>Usage
 
 Creating a random ID generator using `puid-js` is as simple as: