// From main.rs
let keyboard_flags = KeyboardEnhancementFlags::DISAMBIGUATE_ESCAPE_CODES
    | KeyboardEnhancementFlags::REPORT_ALTERNATE_KEYS;

┌─────────────┐     ┌──────────────────┐     ┌───────────────────┐     ┌────────┐
│  Terminal   │ ──► │  KeyTranslator   │ ──► │ KeybindingResolver│ ──► │ Action │
│ (raw input) │     │  (calibration)   │     │     (keymap)      │     │        │
└─────────────┘     └──────────────────┘     └───────────────────┘     └────────┘
       │                    │                         │
       │                    │                         │
  "My terminal         "Normalize to              "Map key to
   sends 0x7F"          Backspace"                 action"

Raw Key → Action
0x7F → DeleteBackward

Raw Key → Normalized Key → Keymap → Action
0x7F → Backspace → (keymap lookup) → DeleteBackward

[ FRESH EDITOR INPUT CALIBRATION ]
--------------------------------------------------
STEP 1 / 24 : Calibrating [ BACKSPACE ]
(Group 1: Basic Editing - 1 of 4)

Please press your physical BACKSPACE key now.

 Controls:
 [ s ] Skip this key (keep default)
 [ g ] Skip entire group (Basic Editing)
 [ a ] Abort wizard
--------------------------------------------------
 waiting for input...

[ VERIFICATION MODE ]
--------------------------------------------------
We captured your keys. Let's test them.

== Group 1: Basic Editing ==
 1. [ BACKSPACE ]:       [   ] Waiting...
 2. [ DELETE ]:          [ OK ] Detected!
 3. [ TAB ]:             [SKIP] (using default)
 4. [ SHIFT+TAB ]:       [SKIP] (using default)

== Group 2: Line Navigation ==
 5. [ HOME ]:            [ OK ] Detected!
 6. [ END ]:             [ OK ] Detected!
 7. [ SHIFT+HOME ]:      [   ] Waiting...
 8. [ SHIFT+END ]:       [   ] Waiting...

== Group 3: Word Navigation ==
 9. [ ALT+LEFT ]:        [ OK ] Detected!
10. [ ALT+RIGHT ]:       [ OK ] Detected!
    ... (8 more keys)

== Group 4: Document Navigation == (group skipped)

== Group 5: Emacs-Style == (group skipped)

--------------------------------------------------
COMMANDS:
 [ y ] SAVE these settings and exit
 [ r ] RETRY (restart wizard from beginning)
 [ a ] ABORT (discard all changes)

fresh --calibrate

View
├── ...
├── Settings
├── Calibrate Input Keys...
├── ───────────
└── ...

use crossterm::event::{KeyCode, KeyModifiers, KeyEvent};

pub enum CalibrationStep {
    /// Capturing key for a specific target
    Capture {
        group_idx: usize,  // Index into CALIBRATION_GROUPS
        key_idx: usize,    // Index into group's key list
    },
    /// Verification phase
    Verify,
}

/// What the user's key SHOULD produce (the expected/normalized key)
pub struct ExpectedKey {
    pub code: KeyCode,
    pub modifiers: KeyModifiers,
}

pub struct CalibrationTarget {
    pub name: &'static str,
    pub expected: ExpectedKey,  // What Fresh expects to receive
}

pub struct CalibrationGroup {
    pub name: &'static str,
    pub targets: &'static [CalibrationTarget],
}

// 5 groups, 24 keys total
pub const CALIBRATION_GROUPS: &[CalibrationGroup] = &[
    // Group 1: Basic Editing (4 keys)
    CalibrationGroup {
        name: "Basic Editing",
        targets: &[
            CalibrationTarget { name: "BACKSPACE", expected: ExpectedKey { code: KeyCode::Backspace, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "DELETE", expected: ExpectedKey { code: KeyCode::Delete, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "TAB", expected: ExpectedKey { code: KeyCode::Tab, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "SHIFT+TAB", expected: ExpectedKey { code: KeyCode::BackTab, modifiers: KeyModifiers::SHIFT } },
        ],
    },
    // Group 2: Line Navigation (4 keys)
    CalibrationGroup {
        name: "Line Navigation",
        targets: &[
            CalibrationTarget { name: "HOME", expected: ExpectedKey { code: KeyCode::Home, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "END", expected: ExpectedKey { code: KeyCode::End, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "SHIFT+HOME", expected: ExpectedKey { code: KeyCode::Home, modifiers: KeyModifiers::SHIFT } },
            CalibrationTarget { name: "SHIFT+END", expected: ExpectedKey { code: KeyCode::End, modifiers: KeyModifiers::SHIFT } },
        ],
    },
    // Group 3: Word Navigation (8 keys)
    CalibrationGroup {
        name: "Word Navigation",
        targets: &[
            CalibrationTarget { name: "ALT+LEFT", expected: ExpectedKey { code: KeyCode::Left, modifiers: KeyModifiers::ALT } },
            CalibrationTarget { name: "ALT+RIGHT", expected: ExpectedKey { code: KeyCode::Right, modifiers: KeyModifiers::ALT } },
            CalibrationTarget { name: "ALT+SHIFT+LEFT", expected: ExpectedKey { code: KeyCode::Left, modifiers: KeyModifiers::ALT | KeyModifiers::SHIFT } },
            CalibrationTarget { name: "ALT+SHIFT+RIGHT", expected: ExpectedKey { code: KeyCode::Right, modifiers: KeyModifiers::ALT | KeyModifiers::SHIFT } },
            CalibrationTarget { name: "CTRL+LEFT", expected: ExpectedKey { code: KeyCode::Left, modifiers: KeyModifiers::CONTROL } },
            CalibrationTarget { name: "CTRL+RIGHT", expected: ExpectedKey { code: KeyCode::Right, modifiers: KeyModifiers::CONTROL } },
            CalibrationTarget { name: "CTRL+SHIFT+LEFT", expected: ExpectedKey { code: KeyCode::Left, modifiers: KeyModifiers::CONTROL | KeyModifiers::SHIFT } },
            CalibrationTarget { name: "CTRL+SHIFT+RIGHT", expected: ExpectedKey { code: KeyCode::Right, modifiers: KeyModifiers::CONTROL | KeyModifiers::SHIFT } },
        ],
    },
    // Group 4: Document Navigation (4 keys)
    CalibrationGroup {
        name: "Document Navigation",
        targets: &[
            CalibrationTarget { name: "PAGE UP", expected: ExpectedKey { code: KeyCode::PageUp, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "PAGE DOWN", expected: ExpectedKey { code: KeyCode::PageDown, modifiers: KeyModifiers::NONE } },
            CalibrationTarget { name: "CTRL+HOME", expected: ExpectedKey { code: KeyCode::Home, modifiers: KeyModifiers::CONTROL } },
            CalibrationTarget { name: "CTRL+END", expected: ExpectedKey { code: KeyCode::End, modifiers: KeyModifiers::CONTROL } },
        ],
    },
    // Group 5: Emacs-Style Navigation (4 keys)
    CalibrationGroup {
        name: "Emacs-Style",
        targets: &[
            CalibrationTarget { name: "CTRL+A", expected: ExpectedKey { code: KeyCode::Char('a'), modifiers: KeyModifiers::CONTROL } },
            CalibrationTarget { name: "CTRL+E", expected: ExpectedKey { code: KeyCode::Char('e'), modifiers: KeyModifiers::CONTROL } },
            CalibrationTarget { name: "CTRL+K", expected: ExpectedKey { code: KeyCode::Char('k'), modifiers: KeyModifiers::CONTROL } },
            CalibrationTarget { name: "CTRL+Y", expected: ExpectedKey { code: KeyCode::Char('y'), modifiers: KeyModifiers::CONTROL } },
        ],
    },
];

pub struct CalibrationWizard {
    /// Current step
    step: CalibrationStep,
    /// Translation table: raw terminal event → expected normalized event
    /// Key: what the terminal actually sends
    /// Value: what Fresh expects (the "correct" key)
    pending_translations: HashMap<KeyEvent, KeyEvent>,
    /// Which keys have been verified in the verification phase
    verified: HashSet<usize>,  // Index into flattened key list
    /// Groups that were skipped entirely
    skipped_groups: HashSet<usize>,
}

/// The key translator that applies calibration
pub struct KeyTranslator {
    /// Translation table loaded from config
    translations: HashMap<KeyEvent, KeyEvent>,
}

impl KeyTranslator {
    /// Translate a raw terminal event to a normalized event
    pub fn translate(&self, raw: KeyEvent) -> KeyEvent {
        self.translations.get(&raw).cloned().unwrap_or(raw)
    }
}

{
  "_comment": "Generated by 'Calibrate Input Keys' wizard",
  "_format": "raw_key → expected_key",
  "translations": {
    "Char(0x7f)": "Backspace",
    "Char(0x08)": "Backspace",
    "Alt(b)": "Alt+Left",
    "Esc,[,1,~": "Home"
  }
}

1. Terminal sends raw KeyEvent
2. KeyTranslator.translate(raw) → normalized KeyEvent  ← CALIBRATION
3. KeybindingResolver.resolve(normalized) → Action     ← KEYMAP
4. Editor executes Action

src/
├── input/
│   ├── keybindings.rs           # Add CalibrateInput action
│   ├── key_translator.rs        # NEW: KeyTranslator + load/save calibration
│   └── mod.rs                   # Wire translator into input pipeline
├── app/
│   ├── calibration_wizard.rs    # NEW: Wizard state machine and logic
│   └── mod.rs                   # Integration with Editor
└── view/
    └── ui/
        └── calibration_ui.rs    # NEW: Wizard UI rendering