chore: Fix audit findings and align documentation with implementation

Addressed all findings from external code review to ensure code quality,
documentation accuracy, and polite extension behavior.

Key fixes:
- Removed impolite command registration for 'typescriptHero.imports.organize'
  (we now only register our own 'miniTypescriptHero.imports.organize')
- Fixed documentation drift in README.md, blog-post.md, and CLAUDE.md
- Removed false claims about 'blankLinesAfterImports: legacy' migration
- Corrected merging policy documentation (setting exists, not auto-configured)
- Verified syntax was already correct (audit false alarm on spread operator)

Documentation updates:
- README.md: Updated migration section to reflect actual behavior
  (legacyMode: true for migrated users, not individual setting tweaks)
- blog-post.md: Simplified migration explanation to match implementation
- CLAUDE.md: Fixed configuration list (removed 'legacy' as enum value,
  updated descriptions to match actual behavior)

Testing:
- All 202 tests passing with no regressions
- Command registration removal verified
- Migration behavior validated

Principle applied: Be polite to other extensions
- Only read old TypeScript Hero settings during one-time migration
- Never write to old namespace
- Never register commands in old namespace
- Let users manually update custom keybindings if needed

Code is now clean, consistent, and ready for release.

Author: JohannesHoppe

CLAUDE.md

@@ -269,11 +269,11 @@ All settings are under `miniTypescriptHero.imports.*`:
 12. `mergeImportsFromSameModule` (boolean) - **NEW!** Merge duplicate imports
 
 ### Blank Lines
-13. `blankLinesAfterImports` (one/two/preserve/legacy) - How many blank lines after imports
+13. `blankLinesAfterImports` (one/two/preserve) - How many blank lines after imports (Note: Ignored when legacyMode is enabled)
 
 ### Behavior & Compatibility
 14. `organizeOnSave` (boolean) - Automatically organize imports when saving files
-15. `legacyMode` (boolean) - **INTERNAL!** Replicate old TypeScript Hero bugs exactly (auto-set by migration)
+15. `legacyMode` (boolean) - Replicate old TypeScript Hero behavior exactly (auto-set to `true` for migrated users)
 
 ---
 
@@ -323,11 +323,11 @@ All settings are under `miniTypescriptHero.imports.*`:
 **How**: `src/configuration/settings-migration.ts` runs on activation
 **Preserves**: 100% backward compatibility - users don't notice the change
 
-### 4. Legacy Mode for Blank Lines
-**Why**: Old extension has buggy blank line behavior, but users depend on it
-**How**: `blankLinesAfterImports: 'legacy'` replicates exact old bugs
-**For**: Migrated users get legacy mode automatically
-**New Users**: Get modern 'one' blank line (ESLint/Google standard)
+### 4. Legacy Mode for Complete Backward Compatibility
+**Why**: Old extension has specific behaviors (blank lines, within-group sorting, no merging) that users depend on
+**How**: `legacyMode: true` replicates ALL old behaviors exactly
+**For**: Migrated users get `legacyMode: true` automatically
+**New Users**: Get `legacyMode: false` by default for modern best practices (1 blank line, correct sorting, import merging)
 
 ---
 

CLAUDE_TODO.md

@@ -3467,3 +3467,122 @@ Without `rootDir`, TypeScript can't determine the common ancestor of included fi
 
 **Session Status**: ✅ **All tasks completed successfully!**
 
+
+---
+
+## Session: 2025-10-25 - Audit Findings Review and Cleanup
+
+### 1. Current Work Status
+
+#### ✅ Completed Tasks
+1. **Reviewed audit findings** from external code review
+2. **Verified syntax bug was false alarm** - Code already had correct `[...imp.specifiers]` spread syntax
+3. **Removed impolite command registration** - No longer hijacking `typescriptHero.imports.organize` command
+4. **Decided on merging policy** - Keep `mergeImportsFromSameModule` setting as valuable feature
+5. **Fixed all documentation drift**:
+   - README.md: Removed false claims about `blankLinesAfterImports: "legacy"` migration
+   - blog-post.md: Updated to reflect actual `legacyMode: true` migration behavior
+   - CLAUDE.md: Corrected configuration documentation
+6. **Verified all 202 tests passing** with no regressions
+
+#### 🚫 No In-Progress or Blocked Items
+All audit findings have been addressed successfully.
+
+### 2. Technical Context
+
+#### Files Modified
+1. **src/imports/import-organizer.ts** (lines 42-50)
+   - Removed backward-compatibility alias command `typescriptHero.imports.organize`
+   - Now only registers our own `miniTypescriptHero.imports.organize` command
+   - Reason: Being polite - don't hijack old extension's commands
+
+2. **README.md** (lines 114-119)
+   - Replaced incorrect migration documentation
+   - Removed false claims about `blankLinesAfterImports: "legacy"` value
+   - Removed false claims about intelligent `mergeImportsFromSameModule` migration
+   - Updated to reflect actual behavior: `legacyMode: true` for migrated users
+
+3. **blog-post.md** (line 85)
+   - Updated migration description to mention `legacyMode: true`
+   - Removed incorrect technical details about settings migration
+
+4. **CLAUDE.md** (lines 249-276, 326-330)
+   - Configuration section: Removed "legacy" as enum value for `blankLinesAfterImports`
+   - Updated to show only valid values: "one", "two", "preserve"
+   - Added note that setting is ignored when `legacyMode` is enabled
+   - Updated Technical Decision #4 to reflect complete `legacyMode` behavior
+
+#### Files Created
+None - only modifications to existing files.
+
+#### Temporary/Debug Files
+None created during this session.
+
+### 3. Important Decisions
+
+#### Architecture Choices
+1. **Keep `mergeImportsFromSameModule` setting**
+   - Rationale: Valuable feature that decouples merging from removal
+   - Improvement over old extension's coupled behavior
+   - Already fully implemented with comprehensive tests (tests 41-63)
+   - Default: `true` for all users (new and migrated)
+
+2. **Remove command alias registration**
+   - Principle: Be polite to other extensions
+   - Only read old settings during migration (one-time)
+   - Never write to old namespace
+   - Never register old commands
+
+#### Open Questions
+None - all audit findings resolved.
+
+### 4. Next Steps
+
+#### Immediate TODO
+1. Consider releasing as RC1 after this cleanup
+2. All 202 tests passing, documentation aligned with code
+
+#### Testing Needed
+✅ Already completed - all tests passing:
+- 202 tests passing
+- No regressions from command registration removal
+- All functionality verified
+
+#### Documentation Updates
+✅ All completed:
+- README.md aligned with actual migration behavior
+- blog-post.md updated with correct technical details
+- CLAUDE.md configuration section corrected
+
+### 5. Audit Findings Resolution Summary
+
+**Original Audit Report Findings:**
+
+1. ❌ **Syntax bug `[.imp.specifiers]`** → FALSE ALARM (code was already correct)
+2. ✅ **Impolite command registration** → FIXED (removed alias)
+3. ✅ **Merging policy consistency** → RESOLVED (keep setting, clarify docs)
+4. ✅ **Documentation drift** → FIXED (all docs updated)
+5. ✅ **Manifest issues** → ALREADY CORRECT (no changes needed)
+
+**Test Results:** 202/202 passing ✅
+
+**Code Quality:** Clean, consistent, ready for release ✅
+
+### 6. Key Technical Insights
+
+1. **Migration Strategy is Correct**
+   - Reads old settings once (polite)
+   - Copies to new namespace
+   - Sets `legacyMode: true` for 100% backward compatibility
+   - Never touches old settings again
+
+2. **Documentation Must Match Implementation**
+   - Previous docs claimed migration set `blankLinesAfterImports: "legacy"` (wrong)
+   - Previous docs claimed intelligent `mergeImportsFromSameModule` migration (wrong)
+   - Reality: Migration only sets `legacyMode: true` (simple, clean)
+
+3. **Command Registration Best Practices**
+   - Only register your own commands
+   - Don't create aliases to other extensions' commands
+   - Let users migrate their custom keybindings manually if needed
+

README.md

@@ -111,12 +111,9 @@ Once your settings are migrated, you have two options:
 
 If the old TypeScript Hero extension is still active, you'll see a reminder in the migration notification suggesting you can disable it.
 
-**Blank Line Behavior:** For migrated users, `blankLinesAfterImports` is automatically set to `"legacy"` to preserve the original TypeScript Hero behavior. New users get `"one"` by default (ESLint standard: 1 blank line after imports). You can change this setting anytime in your configuration.
+**Legacy Mode:** For migrated users, `legacyMode` is automatically set to `true` to preserve 100% of the original TypeScript Hero behavior (including blank line handling, within-group sorting, and no import merging). New users get `legacyMode: false` by default for modern best practices. You can change this setting anytime in your configuration.
 
-**Import Merging Behavior:** The migration intelligently configures `mergeImportsFromSameModule` based on your old settings:
-- If you had `disableImportRemovalOnOrganize: true`, merging is disabled (`false`) to preserve the exact old behavior
-- If you had `disableImportRemovalOnOrganize: false` (or default), merging is enabled (`true`) as before
-- This preserves 100% backward compatibility with your existing workflow
+**Import Merging:** By default, `mergeImportsFromSameModule: true` combines duplicate imports from the same module (modern best practice). If you prefer to keep imports separate, set this to `false` in your configuration
 
 ### No Old Settings?
 

blog-post.md

@@ -82,7 +82,7 @@ If you're already using TypeScript Hero, switching is painless:
 3. Your settings automatically migrate (one-time, on first startup)
 4. Done.
 
-All your custom configurations transfer automatically — quote style, semicolons, import grouping rules, blank line handling, everything. The extension preserves your exact behavior by intelligently migrating settings to match the old TypeScript Hero (like `blankLinesAfterImports: "legacy"` and `mergeImportsFromSameModule` based on your removal settings). You can switch to the new defaults anytime you want cleaner, more consistent spacing. You can even keep both extensions installed if you want, but I highly recommend deactivating the old hero because both will fight for the same shortcut. Speaking of which: the keyboard shortcut works exactly the same, `Ctrl+Alt+O` (or `Cmd+Alt+O` on macOS).
+All your custom configurations transfer automatically — quote style, semicolons, import grouping rules, blank line handling, everything. The extension preserves your exact behavior by automatically enabling `legacyMode: true` for migrated users, which replicates 100% of the old TypeScript Hero behavior. You can switch to the new defaults anytime you want cleaner, more consistent spacing. You can even keep both extensions installed if you want, but I highly recommend deactivating the old hero because both will fight for the same shortcut. Speaking of which: the keyboard shortcut works exactly the same, `Ctrl+Alt+O` (or `Cmd+Alt+O` on macOS).
 
 ## A Quick Thank You
 

src/imports/import-organizer.ts

@@ -39,16 +39,6 @@ export class ImportOrganizer implements Disposable {
       ),
     );
 
-    // Register alias for backward compatibility
-    this.disposables.push(
-      commands.registerTextEditorCommand(
-        'typescriptHero.imports.organize',
-        async () => {
-          await this.organizeImportsCommand();
-        },
-      ),
-    );
-
     // Register organize-on-save handler
     this.disposables.push(
       workspace.onWillSaveTextDocument((event: TextDocumentWillSaveEvent) => {