diff --git a/specs/GH10388/product.md b/specs/GH10388/product.md
new file mode 100644
index 0000000000..e7aa8346a7
--- /dev/null
+++ b/specs/GH10388/product.md
@@ -0,0 +1,27 @@
+# GH-10388: Hide Mouse Cursor While Typing on macOS
+
+## Summary
+
+Warp should match normal macOS text-entry behavior: while the user types in a terminal window, the mouse cursor hides until the mouse moves. The behavior is enabled by default on macOS and can be disabled from Settings.
+
+## Behavior
+
+1. On macOS, typing in a Warp terminal window hides the mouse cursor by default.
+
+2. The cursor reappears when the user moves the mouse.
+
+3. Warp exposes a Settings -> Features -> Terminal Input toggle labeled `Hide mouse cursor while typing`.
+
+4. When the toggle is on, typing hides the cursor until mouse movement.
+
+5. When the toggle is off, typing leaves the cursor visible.
+
+6. Toggling the setting applies without restarting Warp and updates currently open windows.
+
+7. New, restored, transferred, and Quake Mode windows use the current setting value when they are created.
+
+8. The setting is macOS-only; non-macOS platforms do not show the setting and get no behavior change.
+
+9. The setting is a public preference at `terminal.input.hide_cursor_while_typing` and syncs per platform.
+
+10. Text input and mouse interactions otherwise behave as they do today, including keybindings, dead keys, IME composition, selection, dragging, scrolling, hover states, and cursor restoration on mouse movement.
diff --git a/specs/GH10388/tech.md b/specs/GH10388/tech.md
new file mode 100644
index 0000000000..1a57d81559
--- /dev/null
+++ b/specs/GH10388/tech.md
@@ -0,0 +1,59 @@
+# GH-10388: Tech Spec - Hide Mouse Cursor While Typing on macOS
+
+## Context
+
+See `specs/GH10388/product.md` for the desired behavior. The implementation touches the existing settings, Settings UI, window creation, and macOS host-view paths:
+
+- `app/src/settings/input.rs:35` defines `InputSettings` and the metadata used for TOML, platform support, visibility, and sync.
+- `app/src/settings_view/features_page.rs:216`, `features_page.rs:565`, and `features_page.rs:2602` show the existing Terminal Input command-palette, action, and widget patterns.
+- `crates/warpui_core/src/core/mod.rs:164`, `crates/warpui_core/src/core/app.rs:2299`, and `crates/warpui_core/src/platform/mod.rs:96` thread window options into platform windows.
+- `app/src/root_view.rs:1178` creates regular window options; nearby restored, transferred, and Quake Mode paths build their own `AddWindowOptions`.
+- `crates/warpui/src/platform/mac/objc/host_view.m:161` handles AppKit key-down events, and `crates/warpui/src/platform/mac/window.rs:482` stores per-window macOS state.
+
+The prototype branch `gh-10388/hide-cursor-while-typing` already validated this approach.
+
+## Proposed changes
+
+1. Add `InputSettings::hide_cursor_while_typing`:
+   - TOML path: `terminal.input.hide_cursor_while_typing`
+   - Default: `true`
+   - Supported platforms: `SupportedPlatforms::MAC`
+   - Sync: `SyncToCloud::PerPlatform(RespectUserSyncSetting::Yes)`
+   - Public setting
+
+2. Add a Settings -> Features -> Terminal Input toggle:
+   - Label: `Hide mouse cursor while typing`
+   - `FeaturesPageAction::ToggleHideCursorWhileTyping`
+   - Matching command-palette toggle binding, context flag, widget, and telemetry action
+   - Platform-gated through the setting metadata
+
+3. Thread the value into platform windows:
+   - Add `hide_cursor_while_typing` to `AddWindowOptions` and `WindowOptions`.
+   - Initialize all app window creation paths from `InputSettings`.
+   - Add a default no-op `set_hide_cursor_while_typing(bool)` method to the platform `Window` trait.
+
+4. Implement the macOS behavior:
+   - Store the value in macOS `WindowState`.
+   - Add an Obj-C-callable Rust helper that returns the window state's current value.
+   - In `host_view.m` `keyDownImpl`, call `[NSCursor setHiddenUntilMouseMoves:YES]` only when the setting is enabled.
+
+5. Apply setting changes live:
+   - Subscribe each `RootView` to `InputSettingsChangedEvent::HideCursorWhileTyping`.
+   - On change, update that root view's platform window through `set_hide_cursor_while_typing`.
+
+## Testing and validation
+
+Add a focused settings metadata test for default value, TOML path, public/private status, macOS-only support, and per-platform sync mode.
+
+Run:
+
+- `cargo test -p warp settings::input::tests::hide_cursor_while_typing_metadata_matches_macos_toggle_contract`
+- `cargo test -p warp settings::schema_validation_tests::file_defaults_validate_against_schema`
+
+Manual macOS validation:
+
+1. Default on: typing hides the cursor and mouse movement restores it.
+2. Toggle off: typing leaves the cursor visible.
+3. Toggle changes apply to existing windows without restart.
+4. Newly opened regular and Quake Mode windows use the current setting.
+5. Basic text input, IME/dead-key composition, selection, dragging, scrolling, and hover behavior still work.