# keymander (kmd)

**키보드 하나로 모든 것을 지휘한다** — 하나의 키맵, 세 개의 OS, 홈로우 위의 손.

[English README](README.md) · 상세 레퍼런스(검색 모드, 명령어 표, 설정)는 영어
README에 있습니다. 이 문서는 keymander의 이야기와 체험 코스입니다.

---

## 손이 키보드를 떠나는 순간을 세어본 적 있나요?

앱 하나 열려고 마우스로 손이 이동합니다. 화살표 키 하나 때문에 오른손이
홈로우를 떠납니다. 집에서는 `Cmd+Space`, 회사에서는 `Alt+Space`, 리눅스
서버에서는 또 다른 키 — 하나의 뇌가 세 벌의 근육 기억을 유지해야 합니다.

keymander는 이 세 가지 "이탈"을 없애려고 만들어졌습니다.

1. **마우스로의 이탈.** 앱, 파일, 폴더, 웹 검색까지 플로팅 검색바 하나로
   소환합니다. 클릭이 정말 피할 수 없을 때는 홀드 레이어로 **포인터 자체를
   키보드로** 움직입니다.
2. **홈로우로부터의 이탈.** 화살표, Home/End, PageUp/Down, 심지어 Ctrl까지 —
   Vim과 HHKB에서 영감을 받은 홀드 레이어와 탭-홀드 키로 손을 움직이지 않고
   모두 닿습니다.
3. **OS 사이의 이탈.** Windows, macOS, Linux에서 같은 키맵, 같은 런처, 같은
   손가락 움직임. 어디에 앉든 손은 이미 알고 있습니다.

이 모든 것이 ~3MB 단일 바이너리 하나에 들어 있습니다. Electron 없음, 런타임
없음, 요란한 설치 과정 없음.

## 철학

- **One keymap, three OSes.** 어떤 기계 앞에 앉아도 손은 같은 언어를 씁니다.
  이것이 이 프로젝트가 존재하는 이유입니다.
- **Hands on home row.** 이동, 편집, 실행, 포인팅까지 홀드 레이어로 —
  손가락이 여행하지 않습니다. 그리고 모든 기본 배치를 관통하는 인체공학
  원칙 하나: **레이어를 홀드하는 손과 조작하는 손은 항상 다릅니다.** 왼손
  새끼 `CapsLock` 홀드 + 오른손 HJKL 이동, 오른엄지 `RAlt` 홀드 + 왼손 ESDF
  포인터. 한 손으로 쥐어짜는 배치는 없습니다.
- **One binary, no ceremony.** 포터블 설치, SQLite + TOML 파일 하나, 즉시
  시작, 5MB 미만 RAM.

## 첫 60초

```bash
# 1. 설치 (macOS / Linux — Windows·소스 빌드는 영어 README 참고)
brew install bullpae/tap/keymander
#    ↳ 최신 Homebrew가 서드파티 탭 신뢰를 요구하며 거부하면:
#      brew trust bullpae/tap 실행 후 재시도

# 2. 런처 소환
kmd-desktop

# 3. 아무거나 몇 글자 입력 — 앱, 파일, 폴더 — 그리고 Enter
```

이게 전부입니다: **소환 → 입력 → Enter**. keymander의 나머지 모든 기능은 이
루프를 더 많은 대상(웹, AI, 이모지, 셸, 번역)에 적용한 것이고, 그동안 손이
움직이지 않게 해주는 키맵입니다.

즉시 소환하려면 전역 핫키에 `kmd-desktop`을 연결하세요 (권장: `Alt+Space` —
OS별 설정은 [영어 README](README.md#setting-up-a-global-hotkey) 참고).

## 미션: 홈로우를 떠나지 않는 하루

기능 목록을 읽는 것으로는 아무것도 몸에 붙지 않습니다. 손가락이 의도를
느껴야 합니다. 아래 미션은 전부 실제 작업 상황입니다. 직접 해보고, 셀프
체크로 확인하세요.

먼저 키맵을 켭니다 (미션 2~4에 필요):

```bash
kmd keymap init vim-nav    # vim-nav 프리셋 설치
kmd keymap start           # 시작 (kanata 백엔드)
```

> 백엔드: [kanata](https://github.com/jtroo/kanata)는 세 OS 모두에서 동작하며
> Linux에서는 유일한 경로입니다. Windows/macOS에서는 내장 데몬
> (`kmd daemon start`)이 kanata 없이 같은 매핑을 네이티브로 제공합니다.

### 미션 1 — 찾지 말고 소환하라

*상황: Firefox, 지난달 받은 PDF, GitHub 저장소 페이지가 필요하다.*

| 할 일 | 키 |
|----|------|
| 앱 열기 | `Alt+Space` → `fire` → `Enter` |
| 확장자로 파일 찾기 | `Alt+Space` → `.pdf` → `↓` `Enter` |
| GitHub 검색 | `Alt+Space` → `@gh keymander` → `Enter` |

**셀프 체크:** 마우스에 손이 갔는가? 탐색기를 열었는가? 아니라면 — 미션 성공.

### 미션 2 — 화살표 키 없는 화살표

*상황: 문서를 편집하며 커서를 움직여야 한다.*

| 할 일 | 키 |
|----|------|
| 커서 이동 | `CapsLock` 홀드 + `H J K L` |
| 페이지 위/아래 | `CapsLock` 홀드 + `N` / `M` |
| 단어 점프, 줄 처음/끝 | `CapsLock` 홀드 + `I` / `O` (더블탭 = 줄 처음/끝) |
| 지우기 (Backspace / Delete) | `CapsLock` 홀드 + `.` / `/` |

**왜 이 배치인가:** 왼손이 홀드하고 오른손이 움직입니다 — Vim의 홈로우
포지션을, 에디터만이 아니라 *모든* 앱에서.

**셀프 체크:** 오른손이 화살표 구역으로 이동했는가? 이제 다시는 그럴 필요가
없습니다.

### 미션 3 — 레이어는 CapsLock, 한/영은 제자리에

*상황: 방금 그 HJKL 레이어, 그리고 하루 종일 누르는 한/영 전환.*

| 할 일 | 키 |
|----|------|
| nav 레이어 (미션 2 전부) | `CapsLock` 홀드 |
| 한/영 전환 | `RAlt` 짧게 탭 — 한국어 키보드의 물리 한/영 자리 |

키보드에서 가장 좋은 자리(홈로우, 왼쪽 새끼손가락)가 더 이상 잠금 키로
낭비되지 않습니다. 트리거가 modifier가 아니므로 앱들의 `Alt`/`Ctrl` 단축키를
하나도 가리지 않습니다 — vim-nav를 켠 채로 한글 워드의 `Alt+Shift+N`도
그대로 동작합니다. 한/영은 수십 년 근육기억 그대로 스페이스바 오른쪽
(`RAlt` = 한국어 키보드의 한/영 키)이고, macOS에서도 같은 자리(오른쪽
Option)로 통일됩니다. CapsLock을 실수로 짧게 스쳐도 아무 일도 일어나지
않습니다. HHKB식 Ctrl 모드탭(탭=Caps/홀드=Ctrl)을 쓰고 싶다면 트리거를
`LAlt`로 되돌리면 살아납니다 (docs/13).

**셀프 체크:** Shift 누르려다 CapsLock을 스쳐서 대문자가 쏟아진 적 있는가?
이제 그 키는 홀드 전용이라 사고 칠 방법이 없습니다.

> 한/영 탭을 아주 빠르게 연타하면 두 번째 탭(300ms 내)은 무시됩니다 —
> 전환 겹침으로 인한 오동작을 막는 의도된 안전장치입니다 (docs/13).

### 미션 4 — 마우스 없는 클릭

*상황: 다이얼로그가 떴다. 버튼 하나만 누르면 된다. 팔 전체를 옮길 가치가
없다.*

| 할 일 | 키 |
|----|------|
| 포인터 이동 | `RAlt` 홀드(오른엄지) + `E S D F`(왼손, 홈포지션 유지) |
| 좌클릭 / 우클릭 | `W` / `R` — 이동 클러스터의 왼쪽/오른쪽 |
| 휠 위 / 아래 | `T` / `G` — 위 키는 위로, 아래 키는 아래로 |
| 드래그 | `Space` 홀드 (엄지 담당이라 이동 손가락과 안 겹침) |
| 정밀 모드 | + `LShift` 홀드 |

**왜 이 배치인가:** 실제 마우스 사용의 대부분은 *이동해서 클릭* — 목표까지
가서 활성화하는 것입니다. 그래서 이동은 가속형이고(조준할 땐 느리게 시작,
멀리 갈 땐 빠르게 램프), 클릭과 휠은 이동 키를 기준으로 공간적으로
대응합니다(왼쪽 키=왼쪽 버튼, 위 키=위로 스크롤). 홀드하는 엄지(오른손)는
이동 키(왼손)를 절대 겸하지 않고, `RAlt`를 짧게 탭하면 한/영 전환 —
홀드일 때만 레이어가 열립니다 (미션 3).

**셀프 체크:** 다이얼로그를 닫았고, 손은 키보드를 떠나지 않았다.

### 미션 5 — 다른 기계, 같은 손

*상황: Mac에서 Windows 노트북으로 옮겨 앉거나, 온종일 Linux에 SSH로 접속하는
날.*

다른 OS에서 미션 1~4를 반복하세요. 같은 키, 같은 레이어, 같은 근육 기억.
이 미션이 keymander의 존재 이유입니다.

**승급 규칙 (vimtutor 방식):** 미션 1~4를 실제 작업 흐름으로 3일 연속, 실행과
이동에서 마우스를 0번 잡고 완수하세요. 연습처럼 느껴지지 않는 순간이
졸업입니다.

> **예고: `kmd dojo`** — 이 미션들을 TUI 안에서 시간 측정·점수·콤보가 있는
> 연습 라운드로 바꿔주는 인터랙티브 트레이너를 준비 중입니다.
> ([계획 문서](docs/10_dojo_plan.md))

---

## 더 알아보기

- **전체 기능·명령어·설정 레퍼런스**: [영어 README](README.md)
- **설치 채널별 파일 위치·포터블 모드**: [영어 README — Install layout](README.md#install-layout-by-channel)
- **설정 파일 상세**: [config reference](docs/06_config_reference.md)
- **릴리스 이력**: [CHANGELOG.md](CHANGELOG.md)

## License

MIT