docs: update and consolidate documentation

- Add critical rule about shell: WIN32 pattern to CLAUDE.md
- Update README with Socket Badge and coverage badges
- Consolidate getting started documentation
- Remove redundant documentation files (test-helpers.md, http-utilities.md, etc.)
- Update package testing documentation
- Improve registry README with current practices
- Standardize bullet points to tiny middle dot

Author: jdalton

CLAUDE.md

@@ -172,76 +172,13 @@ If anything breaks:
 - **Coverage**: MANDATORY - never decrease, always maintain/increase
 - **c8 ignore**: Must include reason ending with period
 
-#### Test Helpers (`test/utils/`)
+#### Test Helpers
 
-**NPM Package Helper** (`npm-package-helper.mts`)
-```typescript
-import { setupNpmPackageTest } from '../utils/npm-package-helper.mts'
-
-// Replaces ~15-20 lines of boilerplate per test
-const { module: assert, pkgPath, skip, eco, sockRegPkgName } =
-  await setupNpmPackageTest(__filename)
-
-describe(`${eco} > ${sockRegPkgName}`, { skip }, () => {
-  it('should work', () => {
-    expect(assert).toBeDefined()
-  })
-})
-```
-
-**Temp File Helper** (`temp-file-helper.mts`)
-```typescript
-import { withTempDir, withTempFile, runWithTempDir } from '../utils/temp-file-helper.mts'
-
-// Temp directory with cleanup
-const { path: tmpDir, cleanup } = await withTempDir('test-prefix-')
-try {
-  // Use tmpDir...
-} finally {
-  await cleanup()
-}
-
-// Or with callback (auto cleanup):
-await runWithTempDir(async (tmpDir) => {
-  // Use tmpDir... cleanup happens automatically
-}, 'test-prefix-')
-
-// Temp file
-const { path: tmpFile, cleanup } = await withTempFile('content', {
-  extension: '.json',
-  prefix: 'config-'
-})
-```
-
-**Platform Test Helpers** (`platform-test-helpers.mts`)
-```typescript
-import { platform, itOnWindows, itOnUnix, normalizePath } from '../utils/platform-test-helpers.mts'
-
-describe('cross-platform tests', () => {
-  itOnWindows('should handle Windows paths', () => {
-    expect(path.sep).toBe('\\')
-  })
-
-  itOnUnix('should handle Unix paths', () => {
-    expect(path.sep).toBe('/')
-  })
-
-  it('should compare paths cross-platform', () => {
-    expectNormalizedPath('C:\\Users\\test', '/c/Users/test')
-  })
-})
-```
-
-**Assertion Helpers** (`assertion-helpers.mts`)
-```typescript
-import { expectString, expectFrozen, expectHasProperties } from '../utils/assertion-helpers.mts'
-
-it('should validate config', () => {
-  expectString(config.apiKey)
-  expectFrozen(config)
-  expectHasProperties(config, ['apiKey', 'baseUrl', 'timeout'])
-})
-```
+Test helpers available in `test/utils/`:
+- `setupNpmPackageTest()` - NPM package test boilerplate (npm-package-helper.mts)
+- `withTempDir/withTempFile/runWithTempDir()` - Temp file management (temp-file-helper.mts)
+- `itOnWindows/itOnUnix/normalizePath()` - Platform-specific tests (platform-test-helpers.mts)
+- `expectString/expectFrozen/expectHasProperties()` - Assertions (assertion-helpers.mts)
 
 #### Running Tests
 - **All tests**: `pnpm test`
@@ -250,20 +187,6 @@ it('should validate config', () => {
 - **Coverage**: `pnpm run cover`
 - **NPM packages**: `node scripts/test-npm-packages.mjs` (long-running)
 
-#### Migration Guide
-See `test/utils/TEST_HELPERS_README.md` for:
-- Detailed usage examples (before/after patterns)
-- Migration strategy and phases
-- Potential line savings per helper
-- Best practices and patterns
-
-#### Best Practices
-- **Use helpers**: setupNpmPackageTest(), withTempDir(), itOnWindows(), etc.
-- **Auto cleanup**: Always use cleanup functions for temp resources
-- **Platform-aware**: Use platform helpers for cross-platform tests
-- **Descriptive names**: Clear test names for coverage reports
-- **Combine helpers**: Mix helpers for maximum impact
-
 ### Vitest Memory Optimization
 - **Pool**: `pool: 'forks'`, `singleFork: true`, `maxForks: 1`, `isolate: true`
 - **Timeouts**: `testTimeout: 60_000, hookTimeout: 60_000`
@@ -451,6 +374,18 @@ Decision tree:
 - **Order**: Alphabetical; private first, then exported
 - **Await in loops**: Add `// eslint-disable-next-line no-await-in-loop` when intentional
 - **Process spawning**: Use `@socketsecurity/registry/lib/spawn` not `child_process.spawn`
+- **spawn() with shell: WIN32**: 🚨 NEVER change `shell: WIN32` to `shell: true`
+  - `shell: WIN32` is the correct cross-platform pattern (enables shell on Windows, disables on Unix)
+  - If spawn fails with ENOENT, the issue is NOT the shell parameter
+  - Fix by properly separating command and arguments instead:
+    ```javascript
+    // WRONG - passing full command as string
+    spawn('python3 -m module arg1 arg2', [], { shell: WIN32 })
+
+    // CORRECT - separate command and args
+    spawn('python3', ['-m', 'module', 'arg1', 'arg2'], { shell: WIN32 })
+    ```
+  - This pattern is canonical across all Socket Security codebases
 - **Working directory**: 🚨 NEVER use `process.chdir()` - use `{ cwd }` options and absolute paths instead
   - Breaks tests, worker threads, and causes race conditions
   - Always pass `{ cwd: absolutePath }` to spawn/exec/fs operations

README.md

@@ -1,19 +1,20 @@
 # @socketregistry
 
-[![CI - SocketDev/socket-registry](https://github.com/SocketDev/socket-registry/actions/workflows/_local-not-for-reuse-ci.yml/badge.svg)](https://github.com/SocketDev/socket-registry/actions/workflows/_local-not-for-reuse-ci.yml)
+[![Socket Badge](https://socket.dev/api/badge/npm/package/@socketsecurity/registry)](https://socket.dev/npm/package/@socketsecurity/registry)
+[![CI](https://github.com/SocketDev/socket-registry/actions/workflows/_local-not-for-reuse-ci.yml/badge.svg)](https://github.com/SocketDev/socket-registry/actions/workflows/_local-not-for-reuse-ci.yml)
+![Coverage](https://img.shields.io/badge/coverage-99.10%25-brightgreen)
 
 [![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)
 
-> Optimized package overrides for improved security, performance, and
-> compatibility with [Socket Optimize](https://socket.dev/features/optimize).
+Optimized package overrides for [Socket Optimize](https://socket.dev/features/optimize).
 
 <img src="./socket-optimize-hero.png" height="272px" width="576px" alt="npx socket optimize">
 
 ## Quick Start
 
 ```bash
-npx socket optimize
+pnpm dlx socket optimize
 ```
 
 This command analyzes your dependencies and suggests optimized replacements from
@@ -32,13 +33,6 @@ Original Package          Socket Override
   Tuneup   🔧  →  Fix CVEs, maintain compatibility
 ```
 
-**Four types of improvements:**
-
-- **Cleanup** ✨ — Reduce dependencies and replace polyfills with built-in equivalents
-- **Levelup** 🧩 — Add new features and leverage modern platform APIs
-- **Speedup** ⚡ — Boost performance with optimized implementations
-- **Tuneup** 🔧 — Address CVEs in outdated or unmaintained packages
-
 ## Quality Standards
 
 All overrides in this registry:
@@ -52,17 +46,6 @@ All overrides in this registry:
 - Support current and [LTS](https://nodejs.org/en/about/previous-releases) Node
   versions
 
-## Using the Registry Library
-
-Install the registry support package for programmatic access to metadata and
-helper methods:
-
-```bash
-pnpm install @socketsecurity/registry
-```
-
-See the [registry README](./registry/README.md) for API documentation.
-
 ## Contributing
 
 Create a new override in three steps:
@@ -74,24 +57,6 @@ Install       →     Generate      →     Complete
 pnpm install    make:npm-override    Fill TODOs + Test
 ```
 
-**Detailed workflow:**
-
-1. **Install dependencies:**
-   ```bash
-   pnpm install
-   ```
-
-2. **Run the wizard:**
-   ```bash
-   pnpm run make:npm-override [<package-name>]
-   ```
-
-3. **Complete the override:**
-   - Follow the prompts to scaffold your override
-   - Fill in all `TODO:` commented sections
-   - Run tests with `pnpm test`
-   - Commit and send a pull request
-
-**Need help?** See [docs/getting-started.md](./docs/getting-started.md) for comprehensive guide.
+## License
 
-Inspired by [e18e](https://e18e.dev/).
+MIT