docs: update CLAUDE.md for unified naming system

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: owengregson

CLAUDE.md

@@ -6,7 +6,7 @@ JS VM obfuscator — compiles JavaScript functions into custom bytecode executed
 
 -   **Build**: `npm run build` (tsup, ESM-only)
 -   **Typecheck**: `npm run typecheck` (tsc --noEmit)
--   **Test**: `npm run test` (vitest, 1882 tests)
+-   **Test**: `npm run test` (vitest, 1913 tests)
 -   **Test watch**: `npm run test:watch`
 -   **Node**: >= 18, **Module**: ESM (`"type": "module"`)
 
@@ -43,10 +43,20 @@ src/
       expressions.ts        Expression compilation (calls, members, operators, etc.)
       classes.ts            Class compilation (methods, properties, inheritance)
 
+  naming/
+    token.ts                NameToken class — opaque handle with fail-fast .name/.toString()
+    scope.ts                NameScope class — child scope with own PRNG, claims tokens
+    registry.ts             NameRegistry class — central coordinator, resolveAll(), alphabet
+    reserved.ts             JS reserved words + excluded names sets
+    claims.ts               Canonical key definitions for RuntimeNames + TempNames scopes
+    setup.ts                Bridge: NameRegistry → RuntimeNames/TempNames (backward compat)
+    compat-types.ts         RuntimeNames and TempNames type interfaces
+    index.ts                Barrel exports
+
   encoding/
-    names.ts                RuntimeNames interface + per-build randomized name generation (LCG PRNG)
+    names.ts                (Legacy) RuntimeNames interface + name generation — being replaced by naming/
     fingerprint.ts          Build-time fingerprint computation
-    decoder.ts              Build-time custom FNV-1a+LCG cipher + custom alphabet encoding + alphabet generation
+    decoder.ts              Build-time custom FNV-1a+LCG cipher + custom alphabet encoding
     rolling-cipher.ts       Build-time rolling cipher encryption + implicit key derivation
 
   ruamvm/
@@ -104,6 +114,7 @@ test/
   security/                 Anti-reversing, string encoding, rolling cipher, VM shielding, new feature tests
   integration/              Real-world patterns (Chrome extension, RuamTester)
   ruamvm/                   AST emitter and transform tests
+  naming/                   Unified naming system tests (NameRegistry, AST integration, setup bridge)
 
 docs/
   v1-transformations.md     Archived v1 pipeline documentation
@@ -119,7 +130,8 @@ docs/
 -   **Per-file opcode shuffle**: Seeded Fisher-Yates (LCG) produces different instruction encodings per build. Seed + shuffle constants live in `constants.ts`.
 -   **Always-binary format**: All bytecode units are serialized to compact binary (`Uint8Array`) and encoded with a per-build shuffled 64-char alphabet (`A-Za-z0-9_$`). Same bit-packing as base64 (3 bytes → 4 chars) but no padding and a randomized alphabet per build. Output looks like random identifier strings. Alphabet generated via Fisher-Yates shuffle seeded from build seed. JSON serialization path has been eliminated. Runtime decoder builds a reverse lookup table from the embedded alphabet string.
 -   **Constant pool string encoding**: All string constants are XOR-encoded with an LCG key stream. Binary format uses `BINARY_TAG_ENCODED_STRING` (tag 11) with uint16 char codes. Decoded at load time by the `strDec` runtime function. When rolling cipher is on, the encoding key is derived implicitly from bytecode metadata (no plaintext seed). Strings remain encoded even after outer encryption is reversed.
--   **Per-build identifier randomization**: All internal VM identifiers (`_vm`, `_BT`, `stack`, etc.) are replaced with random 2-6 char names generated via LCG PRNG (same seed as opcode shuffle). Adaptive retry increases minimum length after collisions. Managed by `RuntimeNames` interface in `encoding/names.ts`.
+-   **Unified naming system** (`naming/`): A central `NameRegistry` + `NameScope` + `NameToken` architecture manages all per-build randomized identifiers. The registry creates scoped name pools, resolves all names collision-free via `resolveAll()`, and produces the encoding alphabet. The `setupRegistry()` function bridges the registry to the existing `RuntimeNames`/`TempNames` interfaces for backward compatibility. AST nodes accept `Name` (NameToken | string) for all identifier positions. Handler locals use `ctx.local("descriptiveName")` pattern (currently pass-through, will be registry-backed). Post-processing `obfuscateLocals` still renames handler-local variables.
+-   **Per-build identifier randomization**: All internal VM identifiers are replaced with random 2-5 char names via the NameRegistry's LCG PRNG (same seed as opcode shuffle). Three length tiers: short (2-3), medium (3-4), long (4-5). Adaptive retry increases length after collisions. The encoding alphabet (64-char, Fisher-Yates shuffled) is also generated by the registry.
 -   **Watermark**: Steganographic — the WATERMARK_MAGIC constant (FNV-1a of "ruam" = `0x2812af9a`) is XOR-folded into the FNV offset basis used for key anchor computation. No visible variable, string, or pattern in output. Verified by comparing key anchor results: using standard FNV basis instead of watermarked basis breaks all rolling cipher decryption.
 -   **Prototypal scope chain**: Scope chain uses `Object.create(parent)` / `Object.getPrototypeOf(scope)` instead of a `{sPar, sVars}` linked list. Variables are own properties on scope objects. `in` operator traverses the prototype chain for reads; `Object.prototype.hasOwnProperty.call` walk for stores. TDZ uses a per-build sentinel object at IIFE scope (identity comparison via `===`). Program scope is `Object.create(null)` with `defineProperty` bindings.
 -   **Array-based stack**: Stack uses native `Array.push()`/`Array.pop()`/`S[S.length-1]` instead of a dedicated stack pointer variable (`S[++P]`/`S[P--]`/`S[P]`). The stack pointer (`stp`) is generated but unused (preserved for LCG sequence stability). Exception handlers save `S.length` as `_sp` and restore via `S.length=_h._sp`. Stack encoding Proxy intercepts `push()` set traps on numeric indices.