orca-keychron 0.1.0__tar.gz

orca_keychron-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KMGeon
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

orca_keychron-0.1.0/MANIFEST.in

@@ -0,0 +1,2 @@
+include README.ko.md
+recursive-include assets *.png

orca_keychron-0.1.0/PKG-INFO

@@ -0,0 +1,336 @@
+Metadata-Version: 2.4
+Name: orca-keychron
+Version: 0.1.0
+Summary: Show Orca agent lifecycle states on a Keychron keyboard
+Author: KMGeon
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/KMGeon/orca-keychron
+Project-URL: Repository, https://github.com/KMGeon/orca-keychron
+Project-URL: Issues, https://github.com/KMGeon/orca-keychron/issues
+Keywords: orca,keychron,rgb,ai-agents,developer-tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: MacOS X
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: hidapi>=0.14.0
+Requires-Dist: pynput<1.8,>=1.7.7
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: ruff>=0.6; extra == "dev"
+Dynamic: license-file
+
+<div align="center">
+
+# Orca Keychron
+
+### 10x your Orca agents—without watching every terminal.
+
+Turn your Keychron keyboard into a live command center for every Orca worktree.
+
+![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)
+![Platform: macOS](https://img.shields.io/badge/platform-macOS-000000?logo=apple&logoColor=white)
+![License: MIT](https://img.shields.io/badge/license-MIT-2ea44f)
+
+**English** · [한국어](https://github.com/KMGeon/orca-keychron/blob/main/README.ko.md)
+
+</div>
+
+![Orca agent status rendered on a Keychron keyboard](https://raw.githubusercontent.com/KMGeon/orca-keychron/main/assets/img1.png)
+
+`orca-keychron` maps each Orca worktree to a stable key and renders its agent state with
+per-key RGB. See which agents are working, waiting, blocked, or done—and press one shortcut
+to jump directly to the worktree that needs you.
+
+Any coding agent reported by Orca works automatically, including Codex, Claude Code, Grok,
+local sessions, and agents running on paired hosts. No agent-specific hooks are installed.
+
+> [!IMPORTANT]
+> This project requires a Keychron keyboard whose firmware implements the per-key `KC_RGB`
+> command `0xA8`. It has been verified on the **Keychron Q65 Max**. Other models are detected
+> and tested by the setup command before any persistent service is installed.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KMGeon/orca-keychron/main/assets/img2.png" alt="Orca worktree status lights on a Keychron Q65 Max" width="720">
+</p>
+
+## What it does
+
+- Assigns one stable indicator key to each active Orca worktree.
+- Aggregates multiple agents in the same worktree into one action-oriented state.
+- Opens a worktree's current action target with `Option` plus its indicator key.
+- Includes agents from local and paired Orca hosts by default.
+- Uses the stock Keychron firmware and writes RGB frames to RAM only.
+
+## Status colors
+
+| Orca worktree state | Indicator | What it means |
+|---|---|---|
+| **Working** | 🟡 Yellow | Agent activity is in progress |
+| **Waiting** | 🟠 Orange | An answer or approval is required |
+| **Blocked** | 🔴 Red | The current turn failed or needs recovery |
+| **Done** | 🟢 Green | The worktree is ready for its next task |
+| **Mixed** | 🟣 Magenta | Multiple action states need attention |
+| **Idle** | ⚪ White | The tracked worktree is available |
+
+`working` is background activity and does not create a mixed state by itself. Historical
+`done` rows are ignored until the same pane has first been observed live, preventing stale
+sessions from filling the indicator zone.
+
+## Quick start
+
+### Requirements
+
+- macOS with Python 3.9 or newer
+- [uv](https://docs.astral.sh/uv/) installed
+- Orca running with the `orca` CLI available on `PATH`
+- A compatible Keychron keyboard connected over USB
+
+Most Keychron keyboards do not expose the required raw HID interface over Bluetooth.
+
+### Install
+
+```bash
+uv tool install orca-keychron
+orca-keychron setup
+```
+
+The interactive setup:
+
+1. Verifies the Orca connection.
+2. Detects the keyboard and verifies `KC_RGB` support.
+3. Previews the default indicator zone, then restores the previous lighting.
+4. Saves the keyboard configuration and requests the required macOS permissions.
+5. Installs and starts a per-user login service.
+
+After setup, the indicator starts automatically at login. The default zone is the number
+row: `1 2 3 4 5 6 7 8 9 0 - =`.
+
+### Verify
+
+```bash
+orca-keychron status
+orca-keychron autostart status
+```
+
+`status` reads Orca without touching keyboard lighting. A healthy background installation
+reports `Login autostart installed and loaded`.
+
+### One-off use
+
+Run without keeping the package installed or registering automatic startup:
+
+```bash
+uvx orca-keychron setup --no-autostart
+uvx orca-keychron run
+```
+
+### Upgrade or uninstall
+
+```bash
+# Upgrade
+uv tool upgrade orca-keychron
+
+# Uninstall the service and command
+orca-keychron autostart uninstall
+uv tool uninstall orca-keychron
+```
+
+The saved configuration and logs remain under
+`~/Library/Application Support/orca-keychron/` so an uninstall does not unexpectedly
+delete user data. Remove that directory separately only if you no longer need it.
+
+## Keyboard navigation
+
+Press `Option` plus a lit indicator key while Orca is frontmost to open that worktree's
+current action target. When several agents in the same worktree need attention, repeated
+presses cycle through them in this order:
+
+```text
+blocked → waiting → done
+```
+
+Plain number keys and `Control`, `Command`, or mixed-modifier shortcuts are never
+intercepted. Option-number shortcuts in other frontmost applications pass through
+normally. Pressing an unassigned indicator key while Orca is frontmost does nothing.
+
+## How it works
+
+```text
+Orca-managed agents
+        │ normalized lifecycle state
+        ▼
+orca worktree ps --json
+        │ poll every 0.75 seconds
+        ▼
+stable worktree slot tracker
+        │ aggregate agents per worktree
+        ▼
+indicator renderer + action-target tracker
+        │ KC_RGB raw HID, RAM only
+        ▼
+Keychron per-key RGB
+```
+
+Orca already normalizes agent activity as `working`, `waiting`, `blocked`, and `done`.
+This project consumes that public status surface instead of adding another set of Codex,
+Claude Code, or Grok lifecycle hooks.
+
+A single long-running process polls Orca, owns the keyboard HID handle, updates RGB only
+when the rendered state changes, and checks the selected lighting effect every 10 seconds.
+
+## Configuration
+
+Setup saves configuration to:
+
+```text
+~/Library/Application Support/orca-keychron/config.json
+```
+
+Choose a different indicator zone during setup:
+
+```bash
+orca-keychron setup --leds 1,2,3,4,5,6,7,8,9,10
+```
+
+LED indices are firmware positions, not printed key labels, and can vary by keyboard.
+Setup previews the selected indices before saving them.
+
+Common runtime options:
+
+| Option | Purpose |
+|---|---|
+| `--open-hold 0.3` | Require a short hold before opening a worktree |
+| `--poll-interval 0.75` | Change the Orca status polling interval |
+| `--leds 1,2,3` | Override the saved indicator LED indices |
+| `--host local` | Include only one host; repeat to include several hosts |
+| `--orca-command orca-dev` | Use a different Orca CLI command |
+
+Run `orca-keychron <command> --help` for the complete command reference.
+
+## macOS permissions
+
+Keyboard navigation requires both **Accessibility** and **Input Monitoring** permission.
+Allow the installed Python process or the terminal that runs the indicator under:
+
+```text
+System Settings → Privacy & Security → Accessibility
+System Settings → Privacy & Security → Input Monitoring
+```
+
+Then restart the background service:
+
+```bash
+orca-keychron autostart install
+```
+
+Unsigned Python tools do not have a stable macOS permission identity. If macOS continues
+to report that permission is required, remove the stale entry, add the currently installed
+Python process or terminal again, and reinstall the service. Packaging this project as a
+signed macOS application would be required to remove that platform limitation entirely.
+
+## Protocol and safety
+
+- Discovers Keychron VID `0x3434`, usage page `0xFF60`, and usage `0x61`.
+- Uses VIA channel 3 and per-key effect `23`.
+- Sends full RGB frames to keyboard RAM; it never sends `SaveLedConf`.
+- Keeps LEDs outside the indicator zone off while the indicator is active.
+- Restores the previous effect and brightness when the process stops normally.
+
+Custom RAM-only frame contents from an existing per-key or mixed effect cannot be read
+back from the supported protocol. If you were using one before starting the indicator,
+reapply that lighting profile after stopping it.
+
+The project does not collect telemetry or send agent state to its own network service. It
+invokes the configured Orca CLI and writes only its local configuration and service logs.
+
+Keychron Launcher uses the same raw HID channel. Close long-running Launcher lighting
+animations if either application becomes unresponsive or overwrites the other's colors.
+
+## Troubleshooting
+
+### No lights appear
+
+```bash
+orca-keychron status
+orca-keychron autostart status
+orca-keychron run
+```
+
+Running in the foreground prints the failure immediately. Background logs are stored at:
+
+```text
+~/Library/Application Support/orca-keychron/logs/stdout.log
+~/Library/Application Support/orca-keychron/logs/stderr.log
+```
+
+### No Keychron raw HID interface found
+
+Connect the keyboard directly over USB instead of Bluetooth. Close Keychron Launcher and
+retry. Some docks and KVMs do not forward the required HID interface reliably.
+
+### Firmware does not enable `KC_RGB`
+
+The connected firmware cannot address individual LEDs through command `0xA8`. Standard
+VIA lighting support is not enough. This tool deliberately does not fall back to a
+whole-keyboard effect because that would remove the per-worktree display.
+
+### Option-key navigation does not work
+
+Confirm that the indicator's Python process or terminal has Accessibility and Input
+Monitoring permission, then restart it with:
+
+```bash
+orca-keychron autostart install
+```
+
+### Lighting resets or becomes unresponsive
+
+Close Keychron Launcher animations, reconnect the keyboard over USB, and restart the
+indicator. Only one process should control the raw HID lighting channel at a time.
+
+## Development
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+.venv/bin/ruff check .
+```
+
+Project structure:
+
+```text
+src/orca_keychron/   CLI, Orca integration, navigation, tracking, and HID rendering
+tests/               Unit and behavior tests
+assets/img1.png      Architecture and interaction overview used in this README
+assets/img2.png      Keychron Q65 Max hardware photo used in this README
+```
+
+## Contributing
+
+Bug reports, compatibility results, documentation improvements, and focused pull requests
+are welcome. Fork and clone the repository, create a focused branch, and use the development
+commands above. For hardware reports, include the Keychron model, connection type, macOS
+version, and the output of this read-only probe:
+
+```bash
+orca-keychron probe
+```
+
+Before opening a pull request, run:
+
+```bash
+.venv/bin/pytest
+.venv/bin/ruff check .
+```
+
+Do not include personal Orca state, local paths, or configuration files in issues.
+
+## License
+
+Released under the [MIT License](https://github.com/KMGeon/orca-keychron/blob/main/LICENSE).

orca_keychron-0.1.0/README.ko.md

@@ -0,0 +1,315 @@
+<div align="center">
+
+# Orca Keychron
+
+### 모든 터미널을 지켜보지 않고 Orca 에이전트를 10배 더 효율적으로 운영하세요.
+
+Keychron 키보드를 모든 Orca 워크트리의 실시간 명령 센터로 바꿔보세요.
+
+![Python 3.9+](https://img.shields.io/badge/Python-3.9%2B-3776AB?logo=python&logoColor=white)
+![플랫폼: macOS](https://img.shields.io/badge/platform-macOS-000000?logo=apple&logoColor=white)
+![라이선스: MIT](https://img.shields.io/badge/license-MIT-2ea44f)
+
+[English](https://github.com/KMGeon/orca-keychron/blob/main/README.md) · **한국어**
+
+</div>
+
+![Keychron 키보드에 표시되는 Orca 에이전트 상태](https://raw.githubusercontent.com/KMGeon/orca-keychron/main/assets/img1.png)
+
+`orca-keychron`은 각 Orca 워크트리를 고정된 키에 할당하고 에이전트 상태를 키별
+RGB로 표시합니다. 어떤 에이전트가 작업 중인지, 입력을 기다리는지, 막혔는지 또는
+완료됐는지 확인하고 단축키 한 번으로 바로 해당 워크트리로 이동할 수 있습니다.
+
+Codex, Claude Code, Grok, 로컬 세션, 페어링된 호스트의 에이전트 등 Orca가 표시하는
+모든 코딩 에이전트가 자동으로 연동됩니다. 에이전트별 훅은 별도로 설치하지 않습니다.
+
+> [!IMPORTANT]
+> 이 프로젝트를 사용하려면 Keychron 키보드 펌웨어가 키별 `KC_RGB` 명령 `0xA8`을
+> 지원해야 합니다. **Keychron Q65 Max**에서 검증했습니다. 다른 모델은 영구 서비스를
+> 설치하기 전에 setup 명령이 자동으로 감지하고 지원 여부를 확인합니다.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/KMGeon/orca-keychron/main/assets/img2.png" alt="Keychron Q65 Max에 표시되는 Orca 워크트리 상태 조명" width="720">
+</p>
+
+## 주요 기능
+
+- 활성 Orca 워크트리마다 고정된 상태 표시 키를 하나씩 할당합니다.
+- 같은 워크트리의 여러 에이전트 상태를 행동 중심의 단일 상태로 집계합니다.
+- `Option`과 상태 표시 키를 눌러 해당 워크트리의 현재 작업 대상으로 이동합니다.
+- 기본적으로 로컬 호스트와 페어링된 Orca 호스트의 에이전트를 모두 포함합니다.
+- Keychron 기본 펌웨어를 사용하며 RGB 프레임을 RAM에만 기록합니다.
+
+## 상태 색상
+
+| Orca 워크트리 상태 | 표시 색상 | 의미 |
+|---|---|---|
+| **작업 중(Working)** | 🟡 노란색 | 에이전트가 작업하고 있습니다 |
+| **대기 중(Waiting)** | 🟠 주황색 | 답변이나 승인이 필요합니다 |
+| **차단됨(Blocked)** | 🔴 빨간색 | 현재 작업이 실패했거나 복구가 필요합니다 |
+| **완료(Done)** | 🟢 초록색 | 다음 작업을 받을 준비가 됐습니다 |
+| **혼합(Mixed)** | 🟣 자홍색 | 여러 종류의 상태를 확인해야 합니다 |
+| **유휴(Idle)** | ⚪ 흰색 | 추적 중인 워크트리를 사용할 수 있습니다 |
+
+`working`은 백그라운드 활동으로 취급하므로 그 자체로 혼합 상태를 만들지 않습니다.
+같은 pane이 실제 실행 상태로 한 번 이상 관찰되기 전까지 과거의 `done` 행은 무시하여
+오래된 세션이 상태 표시 영역을 차지하지 않도록 합니다.
+
+## 빠른 시작
+
+### 요구 사항
+
+- Python 3.9 이상이 설치된 macOS
+- [uv](https://docs.astral.sh/uv/) 설치
+- Orca가 실행 중이며 `orca` CLI를 `PATH`에서 사용할 수 있는 환경
+- USB로 연결된 호환 Keychron 키보드
+
+대부분의 Keychron 키보드는 Bluetooth 연결에서 필요한 raw HID 인터페이스를 제공하지
+않습니다.
+
+### 설치
+
+```bash
+uv tool install orca-keychron
+orca-keychron setup
+```
+
+대화형 setup은 다음 작업을 수행합니다.
+
+1. Orca 연결을 확인합니다.
+2. 키보드를 감지하고 `KC_RGB` 지원 여부를 확인합니다.
+3. 기본 상태 표시 영역을 미리 보여준 뒤 기존 조명으로 복원합니다.
+4. 키보드 설정을 저장하고 필요한 macOS 권한을 요청합니다.
+5. 사용자별 로그인 서비스를 설치하고 상태 표시기를 시작합니다.
+
+setup이 끝나면 로그인할 때 상태 표시기가 자동으로 시작됩니다. 기본 영역은 숫자 행
+`1 2 3 4 5 6 7 8 9 0 - =`입니다.
+
+### 확인
+
+```bash
+orca-keychron status
+orca-keychron autostart status
+```
+
+`status`는 키보드 조명을 변경하지 않고 Orca 상태만 읽습니다. 백그라운드 설치가
+정상이면 `Login autostart installed and loaded`가 출력됩니다.
+
+### 일회성 실행
+
+패키지를 계속 설치해 두거나 자동 시작을 등록하지 않고 실행할 수 있습니다.
+
+```bash
+uvx orca-keychron setup --no-autostart
+uvx orca-keychron run
+```
+
+### 업그레이드 또는 제거
+
+```bash
+# 업그레이드
+uv tool upgrade orca-keychron
+
+# 서비스와 명령 제거
+orca-keychron autostart uninstall
+uv tool uninstall orca-keychron
+```
+
+제거 과정에서 사용자 데이터를 예기치 않게 삭제하지 않도록 저장된 설정과 로그는
+`~/Library/Application Support/orca-keychron/`에 남겨둡니다. 더 이상 필요하지 않은
+경우에만 해당 디렉터리를 별도로 삭제하세요.
+
+## 키보드 탐색
+
+Orca가 가장 앞에 있을 때 `Option`과 켜져 있는 상태 표시 키를 함께 누르면 해당
+워크트리의 현재 작업 대상이 열립니다. 같은 워크트리에 확인이 필요한 에이전트가
+여러 개 있으면 키를 반복해서 눌러 다음 순서로 이동할 수 있습니다.
+
+```text
+blocked → waiting → done
+```
+
+일반 숫자 키와 `Control`, `Command` 또는 여러 modifier를 조합한 단축키는 가로채지
+않습니다. 다른 애플리케이션이 가장 앞에 있을 때의 Option-숫자 단축키도 그대로
+전달됩니다. Orca가 가장 앞에 있을 때 할당되지 않은 표시 키를 누르면 아무 동작도
+하지 않습니다.
+
+## 동작 방식
+
+```text
+Orca가 관리하는 에이전트
+        │ 정규화된 생명주기 상태
+        ▼
+orca worktree ps --json
+        │ 0.75초마다 조회
+        ▼
+고정된 워크트리 슬롯 추적기
+        │ 워크트리별 에이전트 집계
+        ▼
+상태 렌더러 + 작업 대상 추적기
+        │ KC_RGB raw HID, RAM 전용
+        ▼
+Keychron 키별 RGB
+```
+
+Orca는 에이전트 활동을 이미 `working`, `waiting`, `blocked`, `done`으로 정규화합니다.
+이 프로젝트는 Codex, Claude Code 또는 Grok 생명주기 훅을 다시 설치하지 않고 Orca가
+공개하는 상태 정보를 사용합니다.
+
+하나의 장기 실행 프로세스가 Orca 상태를 조회하고 키보드 HID 핸들을 소유합니다.
+렌더링된 상태가 바뀔 때만 RGB를 갱신하며 10초마다 선택한 조명 효과를 확인합니다.
+
+## 설정
+
+setup은 다음 위치에 설정을 저장합니다.
+
+```text
+~/Library/Application Support/orca-keychron/config.json
+```
+
+setup에서 다른 상태 표시 영역을 선택할 수 있습니다.
+
+```bash
+orca-keychron setup --leds 1,2,3,4,5,6,7,8,9,10
+```
+
+LED 인덱스는 키에 인쇄된 문자가 아니라 펌웨어 내부 위치이므로 키보드마다 다를 수
+있습니다. setup은 선택한 인덱스를 저장하기 전에 키보드에서 미리 보여줍니다.
+
+자주 사용하는 실행 옵션은 다음과 같습니다.
+
+| 옵션 | 용도 |
+|---|---|
+| `--open-hold 0.3` | 워크트리를 열기 전에 짧게 누르고 있도록 설정합니다 |
+| `--poll-interval 0.75` | Orca 상태 조회 주기를 변경합니다 |
+| `--leds 1,2,3` | 저장된 상태 표시 LED 인덱스를 덮어씁니다 |
+| `--host local` | 특정 호스트만 포함합니다. 여러 호스트를 포함하려면 반복합니다 |
+| `--orca-command orca-dev` | 다른 Orca CLI 명령을 사용합니다 |
+
+전체 명령 안내는 `orca-keychron <command> --help`로 확인할 수 있습니다.
+
+## macOS 권한
+
+키보드 탐색 기능에는 **손쉬운 사용**과 **입력 모니터링** 권한이 모두 필요합니다.
+다음 설정에서 설치된 Python 프로세스 또는 상태 표시기를 실행하는 터미널을
+허용하세요.
+
+```text
+시스템 설정 → 개인정보 보호 및 보안 → 손쉬운 사용
+시스템 설정 → 개인정보 보호 및 보안 → 입력 모니터링
+```
+
+그런 다음 백그라운드 서비스를 다시 시작합니다.
+
+```bash
+orca-keychron autostart install
+```
+
+서명되지 않은 Python 도구는 macOS 권한 식별자가 안정적이지 않습니다. macOS에서
+권한이 계속 필요하다고 표시되면 오래된 항목을 제거하고 현재 설치된 Python 프로세스
+또는 터미널을 다시 추가한 뒤 서비스를 재설치하세요. 이 플랫폼 제약을 완전히
+제거하려면 프로젝트를 서명된 macOS 애플리케이션으로 패키징해야 합니다.
+
+## 프로토콜과 안전성
+
+- Keychron VID `0x3434`, usage page `0xFF60`, usage `0x61`을 탐색합니다.
+- VIA 채널 3과 키별 효과 `23`을 사용합니다.
+- 전체 RGB 프레임을 키보드 RAM에만 전송하며 `SaveLedConf`는 사용하지 않습니다.
+- 상태 표시기가 실행되는 동안 표시 영역 밖의 LED는 끕니다.
+- 프로세스가 정상적으로 종료되면 기존 효과와 밝기를 복원합니다.
+
+지원하는 프로토콜에서는 기존 키별 효과 또는 혼합 효과의 RAM 전용 프레임 내용을
+다시 읽을 수 없습니다. 상태 표시기를 실행하기 전에 이러한 조명을 사용했다면 종료한
+후 해당 조명 프로필을 다시 적용하세요.
+
+이 프로젝트는 텔레메트리를 수집하거나 자체 네트워크 서비스로 에이전트 상태를
+전송하지 않습니다. 설정된 Orca CLI를 호출하고 로컬 설정 및 서비스 로그만 기록합니다.
+
+Keychron Launcher도 같은 raw HID 채널을 사용합니다. 두 애플리케이션 중 하나가
+응답하지 않거나 색상을 덮어쓰면 장시간 실행 중인 Launcher 조명 애니메이션을
+종료하세요.
+
+## 문제 해결
+
+### 불이 들어오지 않는 경우
+
+```bash
+orca-keychron status
+orca-keychron autostart status
+orca-keychron run
+```
+
+포그라운드에서 실행하면 오류가 즉시 출력됩니다. 백그라운드 로그는 다음 위치에
+저장됩니다.
+
+```text
+~/Library/Application Support/orca-keychron/logs/stdout.log
+~/Library/Application Support/orca-keychron/logs/stderr.log
+```
+
+### Keychron raw HID 인터페이스를 찾지 못하는 경우
+
+Bluetooth 대신 USB로 키보드를 직접 연결하세요. Keychron Launcher를 종료한 뒤 다시
+시도하세요. 일부 독과 KVM은 필요한 HID 인터페이스를 안정적으로 전달하지 못합니다.
+
+### 펌웨어에서 `KC_RGB`를 지원하지 않는 경우
+
+연결된 펌웨어가 명령 `0xA8`로 개별 LED를 제어할 수 없는 상태입니다. 일반 VIA 조명
+지원만으로는 충분하지 않습니다. 워크트리별 표시가 사라지는 것을 막기 위해 전체
+키보드 효과로 대체하지 않습니다.
+
+### Option 키 탐색이 동작하지 않는 경우
+
+상태 표시기를 실행하는 Python 프로세스 또는 터미널에 손쉬운 사용과 입력 모니터링
+권한이 있는지 확인한 뒤 다음 명령으로 다시 시작하세요.
+
+```bash
+orca-keychron autostart install
+```
+
+### 조명이 초기화되거나 응답하지 않는 경우
+
+Keychron Launcher 애니메이션을 종료하고 키보드를 USB로 다시 연결한 뒤 상태 표시기를
+재시작하세요. 한 번에 하나의 프로세스만 raw HID 조명 채널을 제어해야 합니다.
+
+## 개발
+
+```bash
+python3 -m venv .venv
+.venv/bin/pip install -e '.[dev]'
+.venv/bin/pytest
+.venv/bin/ruff check .
+```
+
+프로젝트 구조는 다음과 같습니다.
+
+```text
+src/orca_keychron/   CLI, Orca 연동, 탐색, 추적, HID 렌더링
+tests/               단위 테스트와 동작 테스트
+assets/img1.png      이 README에서 사용하는 아키텍처 및 상호작용 이미지
+assets/img2.png      이 README에서 사용하는 Keychron Q65 Max 실물 사진
+```
+
+## 기여하기
+
+버그 제보, 호환성 결과, 문서 개선, 범위가 명확한 pull request를 환영합니다. 저장소를
+fork하고 clone한 뒤 별도 브랜치를 만들고 위의 개발 명령을 사용하세요. 하드웨어 관련
+제보에는 Keychron 모델, 연결 방식, macOS 버전과 다음 읽기 전용 probe 결과를
+포함해 주세요.
+
+```bash
+orca-keychron probe
+```
+
+Pull request를 열기 전에 다음 명령을 실행하세요.
+
+```bash
+.venv/bin/pytest
+.venv/bin/ruff check .
+```
+
+Issue에는 개인 Orca 상태, 로컬 경로 또는 설정 파일을 포함하지 마세요.
+
+## 라이선스
+
+[MIT License](https://github.com/KMGeon/orca-keychron/blob/main/LICENSE)에 따라 배포됩니다.