zigmini 0.8.0-beta.3 → 0.8.0-beta.5

package/README.md

@@ -1,241 +1,267 @@
+English | [한국어](README.ko.md)
+
 # zigmini
 
-zigmini는 맥에서 도는 개인 AI 에이전트 게이트웨이입니다. 맥의 웹 화면과 Android 앱에서 에이전트(OMO)와 대화하고, 작업을 맡기고, 알림을 받습니다. 게이트웨이와 브리지는 macOS 로그인 때 launchd가 자동으로 띄웁니다. Docker는 필요하지 않습니다.
+zigmini: a personal AI agent gateway that runs on a Mac. You talk with the agent, give it work and get notifications from the web screen on the Mac and from an Android app. launchd starts the gateway and the bridge automatically when you log in to macOS. Docker is not necessary.
 
-## 요구 사항
+## Requirements
 
-- Apple Silicon(M칩) 맥과 macOS. Intel 맥, Linux, Windows는 지원하지 않습니다.
-- [Bun](https://bun.sh) 1.4.0 이상. 설치에는 Bun만 필요합니다. Node.js와 npm은 필요하지 않습니다.
-- 에이전트가 쓸 모델 계정(예: Claude, ChatGPT 구독). 설치 뒤 로그인합니다.
-- (선택) Android 폰. 앱은 게이트웨이가 직접 제공합니다.
-- (선택) 폰을 밖에서 쓰려면 Tailscale 또는 HTTPS 리버스 프록시가 있는 자기 도메인.
+- A Mac with Apple Silicon (M chip) and macOS. Intel Macs, Linux and Windows are not supported.
+- [Bun](https://bun.sh) 1.4.0 or later. Bun is the only thing the installation needs. Node.js and npm are not necessary.
+- A model account for the agent (for example a Claude or ChatGPT subscription). You log in after the installation.
+- (Optional) An Android phone. The gateway serves the app itself.
+- (Optional) To use the phone away from home: Tailscale, or your own domain with an HTTPS reverse proxy.
 
-## 권한 안내
+## Permission notice
 
-zigmini는 에이전트를 권한 프리셋 `full-access`로 실행합니다. 에이전트는 도구를 쓸 때마다 승인을 받지 않습니다. 셸 명령은 샌드박스 없이 이 macOS 사용자 계정의 권한으로 실행됩니다. 등록한 폰 앱이 보낸 요청도 같은 권한으로 실행됩니다.
+The gateway runs the agent with the permission preset `full-access`. The agent does not ask for approval each time it uses a tool. Shell commands run without a sandbox, with the permissions of this macOS user account. Requests that a registered phone app sends also run with the same permissions.
 
-`zigmini setup`은 설치 전에 권한 안내문 전체를 보여 줍니다. `동의`를 정확히 입력해야만 설치합니다. 다른 입력이나 Enter는 동의 안 함이고, 그러면 아무것도 설치하지 않습니다. 동의를 건너뛰는 옵션은 없습니다. 안내문이 바뀌면 다시 동의할 때까지 게이트웨이가 시작하지 않습니다. 이때는 맥 터미널에서 `zigmini consent`를 실행합니다.
+`zigmini setup` shows the full permission notice before the installation. It installs only when you type `동의` ("I agree") exactly. Any other input or Enter means "I do not agree", and then it installs nothing. There is no option to skip the consent. When the notice changes, the gateway does not start until you agree again. Then run `zigmini consent` in a terminal on the Mac.
 
-## 설치
+## Install
 
-1. Bun 버전을 확인합니다. zigmini에는 Bun `1.4.0` 이상이 필요합니다.
+1. Check the Bun version. The package needs Bun `1.4.0` or later.
    ```sh
    bun --version
    ```
-   - 결과가 `1.4.0` 이상(예: `1.4.2`)이면 8번으로 갑니다.
-   - 결과가 `1.4.0`보다 낮으면(예: `1.3.5`) 2번으로 갑니다.
-   - 결과가 `zsh: command not found: bun`이면 4번으로 갑니다.
-2. Bun의 설치 위치를 확인합니다.
+   - If the result is `1.4.0` or later (for example `1.4.2`), go to step 8.
+   - If the result is lower than `1.4.0` (for example `1.3.5`), go to step 2.
+   - If the result is `zsh: command not found: bun`, go to step 4.
+2. Find where Bun is installed.
    ```sh
    which bun
    ```
-   - 결과가 `/opt/homebrew/bin/bun`이면 Homebrew로 설치한 Bun입니다. `brew upgrade bun`을 실행합니다. 그다음 3번으로 갑니다.
-   - 결과가 `/.bun/bin/bun`으로 끝나면 공식 설치 스크립트로 설치한 Bun입니다. `bun upgrade`를 실행합니다. 그다음 3번으로 갑니다.
-   - 결과가 위 두 경로가 아니면 4번으로 갑니다. 4번은 공식 스크립트로 `~/.bun/bin`에 새 Bun을 설치하고, 6번은 그 폴더를 PATH의 앞에 둡니다.
-3. 1번 명령을 다시 실행합니다.
-   - 결과가 `1.4.0` 이상이면 8번으로 갑니다.
-   - 결과가 여전히 `1.4.0`보다 낮으면 4번으로 갑니다.
-4. (1번 결과가 `zsh: command not found: bun`이거나 2번·3번에서 이리로 왔을 때만) Bun을 공식 설치 스크립트로 설치합니다.
+   - If the result is `/opt/homebrew/bin/bun`, Homebrew installed Bun. Run `brew upgrade bun`. Then go to step 3.
+   - If the result ends with `/.bun/bin/bun`, the official install script installed Bun. Run `bun upgrade`. Then go to step 3.
+   - If the result is neither of the two paths, go to step 4. Step 4 installs a new Bun in `~/.bun/bin` with the official script, and step 6 puts that folder at the front of PATH.
+3. Run the command of step 1 again.
+   - If the result is `1.4.0` or later, go to step 8.
+   - If the result is still lower than `1.4.0`, go to step 4.
+4. (Only when the result of step 1 is `zsh: command not found: bun`, or when step 2 or 3 sent you here) Install Bun with the official install script.
    ```sh
    curl -fsSL https://bun.sh/install | bash
    ```
-   - 이 스크립트는 Bun을 `~/.bun/bin/bun`에 설치합니다.
-   - `~/.zshrc` 파일이 있으면 스크립트는 그 파일 끝에 PATH 설정 줄을 추가하고 `Added "~/.bun/bin" to $PATH in "~/.zshrc"`를 출력합니다.
-   - `~/.zshrc` 파일이 없으면 스크립트는 아무 파일도 바꾸지 않고 `Manually add the directory to ~/.zshrc (or similar):`를 출력합니다. 이때는 새 터미널 창에서도 `bun`을 찾지 못합니다.
-5. `~/.zshrc` 파일이 있는지 확인합니다.
+   - This script installs Bun in `~/.bun/bin/bun`.
+   - If the file `~/.zshrc` exists, the script adds a PATH line at the end of that file and prints `Added "~/.bun/bin" to $PATH in "~/.zshrc"`.
+   - If the file `~/.zshrc` does not exist, the script changes no file and prints `Manually add the directory to ~/.zshrc (or similar):`. Then new terminal windows also do not find `bun`.
+5. Check whether the file `~/.zshrc` exists.
    ```sh
    ls ~/.zshrc
    ```
-   - 결과가 `/.zshrc`로 끝나는 경로 한 줄이면 4번의 스크립트가 PATH 설정 줄을 추가했습니다. 6번으로 갑니다.
-   - 결과가 `No such file or directory`로 끝나면 이 명령으로 PATH 설정 줄을 씁니다. 이 명령은 `~/.zshrc`를 만들고, 스크립트가 쓰는 것과 같은 줄을 씁니다. 이후 새로 여는 터미널 창은 `bun`을 찾습니다. 그다음 6번으로 갑니다.
+   - If the result is one line with a path that ends with `/.zshrc`, the script of step 4 added the PATH line. Go to step 6.
+   - If the result ends with `No such file or directory`, write the PATH line with this command. The command creates `~/.zshrc` and writes the same lines that the script writes. After this, new terminal windows find `bun`. Then go to step 6.
      ```sh
      printf '\n# bun\nexport BUN_INSTALL="$HOME/.bun"\nexport PATH="$BUN_INSTALL/bin:$PATH"\n' >> ~/.zshrc
      ```
-6. 지금 터미널 창에서 Bun 폴더를 PATH에 넣습니다. 이 명령은 지금 터미널 창에만 적용되고 파일을 바꾸지 않습니다.
+6. Put the Bun folder in PATH in the current terminal window. This command applies only to the current terminal window and changes no file.
    ```sh
    export PATH="$HOME/.bun/bin:$PATH"
    ```
-7. 1번 명령을 다시 실행합니다.
-   - 결과가 `1.4.0` 이상이면 8번으로 갑니다.
-   - 결과가 오류이면 설치를 멈춥니다. 4번 스크립트의 출력에서 `error:`로 시작하는 줄을 확인합니다.
-8. zigmini를 설치합니다. 설치 스크립트(postinstall)는 없습니다. 이 단계는 파일만 받습니다.
+7. Run the command of step 1 again.
+   - If the result is `1.4.0` or later, go to step 8.
+   - If the result is an error, stop the installation. Look for lines that start with `error:` in the output of the script of step 4.
+8. Install zigmini. There is no install script (postinstall). This step only downloads the files.
    ```sh
    bun add -g zigmini
    ```
-9. `zigmini` 명령을 찾는지 확인합니다.
+   - Until `zigmini setup` (step 15) has finished, the other commands print `` 아직 설치를 마치지 않았습니다. 먼저 `zigmini setup`을 실행하세요. `` (the installation is not finished yet; run `zigmini setup` first) on the error output. `--version`, `--help`, `setup`, `consent`, `migrate` and `migrate-run` do not print it. `zigmini --help` also says to run setup first.
+9. Check that the shell finds the `zigmini` command.
    ```sh
    zigmini --version
    ```
-   - 결과가 `0.7.0-beta.16`처럼 숫자로 시작하는 버전 한 줄이면 15번으로 갑니다.
-   - 결과가 `zsh: command not found: zigmini`이면 Bun 전역 명령 폴더가 PATH에 없습니다. 10번으로 갑니다.
-10. 지금 터미널 창에서 Bun 전역 명령 폴더를 PATH에 넣습니다. 이 명령은 지금 터미널 창에만 적용되고 파일을 바꾸지 않습니다.
+   - If the result is one version line that starts with a number (for example `0.8.0-beta.3`), go to step 15.
+   - If the result is `zsh: command not found: zigmini`, the Bun global command folder is not in PATH. Go to step 10.
+10. Put the Bun global command folder in PATH in the current terminal window. This command applies only to the current terminal window and changes no file.
     ```sh
     export PATH="$(bun pm bin -g):$PATH"
     ```
-11. `~/.zshrc` 파일이 있는지 확인합니다.
+11. Check whether the file `~/.zshrc` exists.
     ```sh
     ls ~/.zshrc
     ```
-    - 결과가 `/.zshrc`로 끝나는 경로 한 줄이면 12번으로 갑니다.
-    - 결과가 `No such file or directory`로 끝나면 13번으로 갑니다.
-12. `~/.zshrc`에 Bun 전역 명령 폴더가 이미 있는지 확인합니다.
+    - If the result is one line with a path that ends with `/.zshrc`, go to step 12.
+    - If the result ends with `No such file or directory`, go to step 13.
+12. Check whether `~/.zshrc` already contains the Bun global command folder.
     ```sh
     grep -cF "$(bun pm bin -g)" ~/.zshrc
     ```
-    - 결과가 `0`이면 13번으로 갑니다.
-    - 결과가 `1` 이상이면 이 폴더는 이미 `~/.zshrc`에 있습니다. 새로 여는 터미널 창은 이 폴더를 찾습니다. 14번으로 갑니다.
-13. `~/.zshrc` 끝에 Bun 전역 명령 폴더를 PATH에 넣는 줄을 씁니다. 파일이 없으면 이 명령이 파일을 만듭니다. 줄에는 `bun pm bin -g`가 출력한 폴더 경로가 들어갑니다. 이후 새로 여는 터미널 창은 이 폴더를 찾습니다.
+    - If the result is `0`, go to step 13.
+    - If the result is `1` or more, the folder is already in `~/.zshrc`. New terminal windows find it. Go to step 14.
+13. Write a line at the end of `~/.zshrc` that puts the Bun global command folder in PATH. If the file does not exist, this command creates it. The line contains the folder path that `bun pm bin -g` prints. After this, new terminal windows find the folder.
     ```sh
     printf '\nexport PATH="%s:$PATH"\n' "$(bun pm bin -g)" >> ~/.zshrc
     ```
-14. 9번 명령을 다시 실행합니다.
-    - 결과가 숫자로 시작하는 버전 한 줄이면 15번으로 갑니다.
-    - 결과가 여전히 `zsh: command not found: zigmini`이면 설치를 멈춥니다. `ls "$(bun pm bin -g)"`를 실행합니다. 결과에 `zigmini`가 없으면 8번의 `bun add -g zigmini` 출력에서 `error:`로 시작하는 줄을 확인합니다.
-15. 설치를 마칩니다.
+14. Run the command of step 9 again.
+    - If the result is one version line that starts with a number, go to step 15.
+    - If the result is still `zsh: command not found: zigmini`, stop the installation. Run `ls "$(bun pm bin -g)"`. If the result does not contain `zigmini`, look for lines that start with `error:` in the output of `bun add -g zigmini` in step 8.
+15. Finish the installation.
    ```sh
    zigmini setup
    ```
 
-`zigmini setup`은 아래 순서로 진행합니다. 다시 실행해도 됩니다. 이미 끝난 단계는 그대로 둡니다.
+`zigmini setup` does these steps in this order. You can run it again. It keeps the steps that are already done.
 
-1. 권한 안내를 보여 주고 동의를 받습니다.
-2. 홈 폴더 `~/.zigmini`를 만듭니다.
-3. 에이전트 엔진(OMO, omo-ai)의 고정 버전을 내려받아 해시를 확인하고 패치합니다. 엔진 라이선스 요약을 보여 주고 동의(`y`)를 받습니다.
-4. 에이전트 폴더와 모델 계정 로그인 상태를 확인합니다. 기본 에이전트 폴더는 `~/.omo/agent`이고, 같은 폴더를 쓰는 다른 OMO와 로그인 정보를 같이 씁니다. 로그인하지 않았으면 로그인 명령을 출력합니다. 그 명령을 실행한 뒤 `/login`을 입력합니다.
-5. Notion 토큰을 묻습니다(선택). 비우면 일정 기능이 꺼집니다.
-6. 외부 접속 방식을 묻습니다. 아래 "외부 접속"을 보세요.
-7. 게이트웨이와 브리지를 launchd에 등록하고 시작합니다.
-8. 앱 내려받기 QR과 폰 등록 QR을 터미널에 그립니다.
+1. It shows the permission notice and asks for your consent.
+2. It creates the home folder `~/.zigmini`. If the rules file of this installation (`~/.zigmini/rules.md`) does not exist, it creates an empty one. See "Agent rules" below.
+3. It downloads the pinned version of the agent engine (omo-ai), checks its hash and patches it. The package decides the version (`src/engine/compat.json`; engine 5.1.35 at the time of writing). It shows a summary of the engine license and asks for your consent (`y`).
+4. It checks the agent folder and the login state of the model account. The default agent folder is `~/.omo/agent`. Other OMO installations that use the same folder share the login data. If you are not logged in, it prints a login command. Run that command, then type `/login`.
+5. It asks for a Notion token (optional). If you leave it empty, the schedule feature is off.
+6. It asks for the external access method. See "External access" below.
+7. It writes the service settings (`~/.zigmini/config.env`, permission preset `full-access`) and leaves voice off.
+8. It registers the gateway and the bridge with launchd and starts them. It waits until the gateway is ready (up to 600 seconds).
+9. If you picked your own domain, it checks that the domain reaches the app port.
+10. It draws the app download QR code and the phone registration QR code in the terminal.
 
-설치가 끝나면 맥의 브라우저에서 http://127.0.0.1:8700 을 엽니다.
+When the installation is done, open http://127.0.0.1:8700 in a browser on the Mac.
 
-묻지 않고 설치하려면 옵션을 씁니다. 권한 동의는 이때도 입력해야 합니다.
+To install without questions, use the options. You must still type the permission consent.
 ```sh
 zigmini setup --non-interactive --accept-license --access lan
 ```
 
-| 옵션 | 뜻 |
+| Option | Meaning |
 |---|---|
-| `--non-interactive` | 묻지 않습니다 |
-| `--accept-license` | 엔진 라이선스에 동의합니다 |
-| `--agent-dir <경로>` | 공유 `~/.omo/agent` 대신 쓸 전용 에이전트 폴더 |
-| `--notion-token-file <경로>` | Notion 토큰 파일 |
-| `--access <tailscale\|lan\|domain>`, `--domain <https://주소>` | 외부 접속 방식 |
-| `--engine-only` | 엔진 설치 단계만 실행합니다 |
+| `--non-interactive` | Asks nothing |
+| `--accept-license` | Agrees to the engine license |
+| `--agent-dir <경로>` | A dedicated agent folder to use instead of the shared `~/.omo/agent` (`<경로>`: path) |
+| `--notion-token-file <경로>` | The Notion token file (`<경로>`: path) |
+| `--access <tailscale\|lan\|domain>`, `--domain <https://주소>` | The external access method (`<https://주소>`: an https address) |
+| `--engine-only` | Runs only the engine installation step |
 
-## 외부 접속
+## External access
 
-웹 화면은 맥 안(`127.0.0.1`)에서만 열립니다. 폰 앱은 별도의 앱 포트(기본 8701)로 접속합니다. 앱 포트로 가는 길은 세 가지 중 하나를 고릅니다. 고른 주소가 폰 등록 QR에 들어갑니다.
+The web screen opens only inside the Mac (`127.0.0.1`). The phone app connects to a separate app port (default 8701). Pick one of three ways to reach the app port. The phone registration QR code contains the address you pick.
 
-| 방식 | 옵션 | 폰이 쓸 수 있는 곳 | 준비 |
+| Method | Option | Where the phone works | Preparation |
 |---|---|---|---|
-| Tailscale | `--access tailscale` | 어디서나 | 맥과 폰에 Tailscale을 설치하고 같은 계정으로 로그인합니다. Tailscale 관리 화면에서 MagicDNS를 켭니다 |
-| 집 Wi-Fi | `--access lan` | 맥과 같은 네트워크 | 없습니다. 맥의 사설 IP 주소를 씁니다 |
-| 자기 도메인 | `--access domain --domain https://<도메인>` | 어디서나 | 앱 포트로 전달하는 HTTPS 리버스 프록시. `https://` 주소만 받습니다 |
+| Tailscale | `--access tailscale` | Anywhere | Install Tailscale on the Mac and the phone and log in with the same account. Turn on MagicDNS in the Tailscale admin console |
+| Home Wi-Fi | `--access lan` | On the same network as the Mac | None. It uses the private IP address of the Mac |
+| Your own domain | `--access domain --domain https://<도메인>` | Anywhere | An HTTPS reverse proxy that forwards to the app port. Only `https://` addresses are accepted (`<도메인>`: your domain) |
+
+To change it later, run `zigmini setup --access <방식>` again (`<방식>`: method), or change it in "외부 접속" (External access) in the web screen settings. If you pick nothing, the phone cannot connect.
 
-나중에 바꾸려면 `zigmini setup --access <방식>`을 다시 실행하거나, 웹 화면 설정의 "외부 접속"에서 바꿉니다. 고르지 않으면 폰은 접속할 수 없습니다.
+## Phone registration
 
-## 폰 등록
+1. On the phone, scan the app download QR code, download the APK and install it. If Android asks to allow "unknown apps" during the installation, allow it.
+2. On the first screen of the app, push "QR로 등록" (Register with QR) and scan the phone registration QR code.
 
-1. 폰에서 앱 내려받기 QR을 찍어 APK를 받고 설치합니다. 설치할 때 Android가 "출처를 알 수 없는 앱" 허용을 물으면 허용합니다.
-2. 앱 첫 화면에서 폰 등록 QR을 찍습니다.
+The first screen of the app also has the fields "게이트웨이 주소" (gateway address) and "등록 토큰 붙여 넣기" (paste the enrollment token) for a registration without the camera. You can paste into the token field the whole `zigmini://enroll?...` text that the registration QR code contains; then the address in that text is used. The token works only once and only within its time limit.
 
-두 QR은 `zigmini setup`의 마지막에 나옵니다. 다시 만들려면 아래 명령이나 웹 화면 설정의 "기기 등록"·"앱 내려받기"를 씁니다. 게이트웨이가 실행 중이어야 합니다.
+The two QR codes appear at the end of `zigmini setup`. To make them again, use the commands below, or "기기 등록" (Register device) and "앱 내려받기" (Download app) in the web screen settings. The gateway must be running.
 ```sh
-zigmini pair --apk   # 앱 내려받기 QR (유효 10분)
-zigmini pair         # 폰 등록 QR (유효 10분, 한 번 사용)
+zigmini pair --apk   # app download QR code (valid for 10 minutes)
+zigmini pair         # phone registration QR code (valid for 10 minutes, single use)
 ```
 
-앱 하나로 게이트웨이 여러 개를 등록할 수 있습니다. 게이트웨이마다 주소와 인증 값을 따로 저장하고, 모든 게이트웨이의 알림을 받습니다. 알림을 누르면 그 게이트웨이로 바뀝니다. 등록한 기기는 웹 화면 설정의 "등록된 기기"에서 확인합니다.
+One app can register more than one gateway. The app stores the address and the credentials of each gateway separately and receives the notifications of all gateways. When you tap a notification, the app switches to that gateway. You can see the registered devices in "등록된 기기" (Registered devices) in the web screen settings.
 
-## 앱 서명 지문
+## App signing fingerprint
 
-zigmini 패키지에 들어 있는 Android 앱(APK)은 아래 인증서 하나로만 서명되어 있습니다. 받은 APK가 진짜인지 확인하려면 APK 파일에서 서명 인증서의 SHA-256 지문을 읽어 아래 값과 비교합니다. 예: Android SDK의 `apksigner verify --print-certs zigmini.apk` 출력의 `certificate SHA-256 digest`(콜론 없이 소문자로 나옵니다) 또는 JDK의 `keytool -printcert -jarfile zigmini.apk` 출력의 `SHA256`. 인증서가 둘 이상이거나 값이 다르면 설치하지 마세요.
+The Android app (APK) in the `zigmini` package is signed with only the certificate below. To check that an APK you received is genuine, read the SHA-256 fingerprint of the signing certificate from the APK file and compare it with the value below. For example: `certificate SHA-256 digest` in the output of `apksigner verify --print-certs zigmini.apk` from the Android SDK (it is printed in lower case without colons), or `SHA256` in the output of `keytool -printcert -jarfile zigmini.apk` from the JDK. If there is more than one certificate or the value is different, do not install the APK.
 
 ```text
 F0:AB:B3:B2:DC:70:1A:45:19:85:69:7D:58:68:F5:FB:4F:AC:33:4F:D8:6A:68:DD:04:5C:53:B2:5C:94:77:8C
 ```
 
-## 음성
+## User manual
+
+The user manual ([English](docs/manual.md), [한국어](docs/manual.ko.md)) opens from the "매뉴얼" (Manual) button at the top of the web settings dialog, and in the app from the "매뉴얼" button on the connection screen that a short press on the header status tag opens.
+
+## Voice
 
-새 설치에서 음성은 꺼져 있습니다. 음성 인식과 음성 합성을 쓰려면 맥의 웹 화면 위쪽의 "음성 설치" 버튼을 누릅니다. 게이트웨이가 uv, Python 환경, 음성 모델(약 8GB)을 `~/.zigmini/voice`에 내려받습니다. 진행률은 채팅에 나옵니다. 실패하면 같은 버튼으로 실패한 단계부터 다시 시작합니다. 설치가 끝나면 "음성 꺼짐"을 눌러 켭니다. 음성 설치와 켜기·끄기는 맥의 웹 화면에서 합니다.
+In a new installation, voice is off. To use speech recognition and speech synthesis, push the "음성 설치" (Install voice) button at the top of the web screen on the Mac. The button shows the download size. The gateway downloads uv, a Python environment and the voice models (about 8 GB) to `~/.zigmini/voice`. The chat shows the progress. If it fails, the same button starts again from the failed step. When the installation is done, push "음성 꺼짐" (Voice off) to turn voice on. You install voice and turn it on and off only in the web screen on the Mac. The app shows only the voice state. At the top of the web screen you can also turn on the wake word ("호출어"), double-clap detection ("박수 감지") and spoken answers ("음성 답변").
 
-## 업데이트
+## Update
 
-새 버전이 나오면 웹 화면 위쪽에 새 버전 줄이 나옵니다. 업데이트는 웹 화면 설정의 "업데이트" 버튼이나 아래 명령으로 합니다.
+When a new version is available, a new-version line appears at the top of the web screen, and a version notice appears in the app. To update, use the "업데이트" (Update) button in the web screen settings ("지금 확인" (Check now) checks for a new version), the "업데이트" (Update) button of the version notice in the app, or the commands below.
 ```sh
-zigmini update            # latest로 업데이트
-zigmini update <버전>     # 지정한 버전으로 업데이트
+zigmini update            # update to latest
+zigmini update <버전>     # update to the given version (<버전>: version)
 ```
 
-업데이트는 DB를 백업하고, 새 버전을 설치하고, 다시 시작한 뒤 상태를 확인합니다. 확인에 실패하면 이전 버전으로 자동으로 되돌립니다. 권한 안내문이 바뀐 업데이트는 맥에서 새 안내문에 동의한 뒤 진행합니다.
+The update backs up the DB, installs the new version, restarts and then checks the state. If the check fails, it goes back to the previous version automatically. If the update changes the permission notice, agree to the new notice on the Mac first. An update from the app cannot accept a new notice.
 
-새 버전이 무중단 전환을 지원하면(0.8.0-beta.1 다음 버전부터) 진행 중인 턴을 끊지 않습니다.
+The update does not start while a question waits for your answer in the inbox (main and works). Answer or delete the questions in the inbox first. `--force` does not override this.
 
-1. 새 브리지와 OMO(새 실행 세대)가 다른 포트에서 먼저 뜨고 확인을 받습니다. 확인에 실패하면 실행 중인 것은 그대로 두고 설치만 되돌립니다.
-2. 게이트웨이만 다시 시작합니다. 웹과 폰은 수 초 뒤 다시 연결됩니다.
-3. 새 세션은 새 세대에서 열립니다. 이전 세대의 세션은 각자 턴이 끝나면 새 세대로 옮겨집니다.
-4. 이전 세대는 세션이 모두 옮겨지면 끝납니다. 메모리가 충분하면 최대 6시간, 아니면 최대 1시간을 기다립니다. 그때까지 끝나지 않은 턴은 끊깁니다. 마무리되면 main 채팅에 한 줄 알림이 옵니다.
-5. 이전 세대를 정리하는 동안에는 다음 업데이트를 받지 않습니다.
+When a new app version is available, the app shows "새 앱 버전" (new app version) with a "내려받기" (Download) button. The button downloads the APK from the gateway. Android asks for the permission to install unknown apps.
 
-무중단 전환을 지원하지 않는 버전으로 가는 업데이트(0.8.0-beta.1로 가는 업데이트 포함)는 지금처럼 브리지와 게이트웨이를 함께 다시 시작합니다. 이때는 진행 중인 턴이 있으면 업데이트를 시작하지 않습니다. 턴이 끊겨도 되면 `--force`를 붙입니다.
+If the new version supports a zero-downtime switch (versions after 0.8.0-beta.1), the update does not cut the turns in progress.
 
-## 명령
+1. A new bridge and engine (a new runtime generation) start first on other ports and must pass a check. If the check fails, the update keeps the running ones and rolls back only the installation.
+2. Only the gateway restarts. The web and the phone connect again after a few seconds.
+3. New sessions open in the new generation. Each session of the previous generation moves to the new generation when its turn ends.
+4. The previous generation ends when all its sessions have moved. It waits up to 6 hours if there is enough memory, otherwise up to 1 hour. Turns that are not done by then are cut. When the switch is complete, a one-line notice appears in the main chat.
+5. While the previous generation is being cleaned up, the gateway does not accept the next update.
 
-| 명령 | 하는 일 |
+An update to a version that does not support the zero-downtime switch (including the update to 0.8.0-beta.1) restarts the bridge and the gateway together, as before. In that case the update does not start while a turn is in progress. If it is acceptable to cut the turn, add `--force`.
+
+## Commands
+
+| Command | What it does |
 |---|---|
-| `zigmini setup` | 설치합니다 |
-| `zigmini start` | 게이트웨이와 브리지를 launchd에 등록하고 시작합니다 |
-| `zigmini stop` | 게이트웨이와 브리지를 멈춥니다 |
-| `zigmini restart [gateway\|bridge]` | 다시 시작합니다 |
-| `zigmini status` | launchd 상태, health, 권한 동의 상태를 보여 줍니다 |
-| `zigmini doctor [--json] [--fix]` | 전체 상태를 점검합니다 |
-| `zigmini pair [--apk]` | 폰 등록 QR 또는 앱 내려받기 QR을 그립니다 |
-| `zigmini consent` | 권한 안내를 보이고 동의를 기록합니다 |
-| `zigmini update [버전] [--force]` | 업데이트합니다 |
-| `zigmini --version` | 설치된 버전을 출력합니다 |
-| `zigmini --help` | 도움말을 출력합니다 |
-
-채팅에서 `/usage`를 보내면 게이트웨이가 로그인한 모델 계정의 사용량을 바로 답합니다.
-
-## 문제 해결
-
-1. 상태를 봅니다.
+| `zigmini setup` | Installs |
+| `zigmini start` | Registers the gateway and the bridge with launchd and starts them |
+| `zigmini stop` | Stops the gateway and the bridge |
+| `zigmini restart [gateway\|bridge]` | Restarts |
+| `zigmini status` | Shows the launchd state, the health and the permission consent state |
+| `zigmini doctor [--json] [--fix]` | Checks the whole state |
+| `zigmini pair [--apk]` | Draws the phone registration QR code or the app download QR code |
+| `zigmini consent` | Shows the permission notice and records the consent |
+| `zigmini update [버전] [--force]` | Updates (`버전`: version) |
+| `zigmini migrate` | Copies an old Docker installation (`~/.zigmini-gateway`) to the new layout. The old folder is not changed |
+| `zigmini migrate-run` | Waits until idle, stops the old runtime, backs up, runs migrate and setup, then checks. If this fails, it goes back to the old runtime |
+| `zigmini --version` | Prints the installed version |
+| `zigmini --help` | Prints the help |
+
+When you send `/usage` in the chat, the gateway replies at once with the usage of the logged-in model account.
+
+## Agent rules
+
+The bridge appends two rule files after the instructions of each agent session.
+
+- `assets/agent/gateway-rules.md` in the package: rules common to all installations. An update changes it.
+- `~/.zigmini/rules.md`: rules only for this installation (for example the form of address, the language, accounts). You edit it yourself. When the two files conflict, this file wins.
+
+Sessions that open after a change use the new content. To apply it at once, run `zigmini restart bridge` while nothing is running.
+
+## Troubleshooting
+
+1. Look at the state.
    ```sh
    zigmini status
    ```
-2. 전체를 점검합니다. 이상 항목과 할 일이 나옵니다.
+2. Check everything. The output shows the problems and what to do.
    ```sh
    zigmini doctor
    ```
-3. 멈춘 에이전트가 있으면 다시 띄웁니다. `--fix`는 이상 있는 launchd 에이전트만 다시 띄웁니다.
+3. If an agent has stopped, start it again. `--fix` starts again only the launchd agents that have a problem.
    ```sh
    zigmini doctor --fix
    ```
-4. 그래도 안 되면 로그 폴더 `~/.zigmini/logs`를 확인합니다.
+4. If this does not help, look at the log folder `~/.zigmini/logs`.
 
-- 게이트웨이가 시작하지 않고 권한 동의가 없다고 나오면 `zigmini consent`를 실행합니다.
-- 오래된 DB 백업, 쓰지 않는 엔진 버전, 업데이트에서 남은 파일은 웹 화면 설정의 "정리"에서 확인하고, 고른 항목만 지웁니다.
+- If the gateway does not start and reports that there is no permission consent, run `zigmini consent`.
+- Old DB backups, unused engine versions and files left by updates appear in "정리" (Clean up) in the web screen settings. Only the items you select are deleted.
 
-## 제거
+## Uninstall
 
-1. 게이트웨이와 브리지를 멈추고 launchd 등록을 지웁니다.
+1. Stop the gateway and the bridge and remove the launchd registration.
    ```sh
    zigmini stop --uninstall
    ```
-2. 패키지를 지웁니다.
+2. Remove the package.
    ```sh
    bun remove -g zigmini
    ```
-3. 데이터를 지웁니다. 대화 기록, 설정, 엔진, 음성 모델이 모두 지워집니다.
+3. Remove the data. This deletes all conversation history, settings, engines and voice models.
    ```sh
    rm -rf ~/.zigmini
    ```
 
-공유 에이전트 폴더 `~/.omo/agent`는 다른 OMO도 쓰므로 지우지 않습니다.
+Do not delete the shared agent folder `~/.omo/agent`, because other OMO installations also use it.
 
-## 라이선스
+## License
 
-zigmini는 [Sustainable Use License 1.0](LICENSE.md)으로 배포합니다. 개인적이거나 비상업적인 용도, 회사 내부 업무 용도로 쓸 수 있습니다. 판매하거나 유료 서비스로 제공할 수 없습니다. 정확한 조건은 `LICENSE.md`를 보세요.
+This software is distributed under the [Sustainable Use License 1.0](LICENSE.md). You can use it for personal or non-commercial purposes and for internal business purposes of a company. You cannot sell it or offer it as a paid service. For the exact terms, see `LICENSE.md`.
 
-설치 때 받는 엔진 omo-ai와 함께 들어 있는 라이브러리의 라이선스는 [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md)에 있습니다. zigmini는 omo-ai를 패치해 씁니다. 패치한 사본은 수정본입니다.
+The licenses of the engine omo-ai that the installation downloads and of the libraries included with it are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md). This software uses a patched omo-ai. The patched copy is a modified version.

package/assets/agent/gateway-rules.md

@@ -18,3 +18,4 @@ zigmini 패키지 공통 에이전트 규칙입니다. 게이트웨이 브리지
 13. 사용자의 시간 표현은 사용자의 현지 시간으로 해석합니다. 보고하는 시각도 현지 시간으로 씁니다.
 14. 사용자는 게이트웨이 프로필의 닉네임으로 부릅니다.
 15. main은 오래 기다리거나 오래 실행하는 작업(배포, 전체 테스트, 뮤테이션 테스트, 다른 작업 기다리기)을 맡기면, 그 작업의 세션 기록이 30분 넘게 바뀌지 않을 때 main을 깨우는 감시를 직접 겁니다. 작업이 끝나면 감시를 끕니다. 작업의 "기다리는 중"·"진행 중" 보고만 믿지 않습니다. 사용자에게 그렇게 말하기 전에 그 작업의 마지막 기록 시각과 실행 중인 프로세스를 확인합니다. 작업이 멈췄으면 바로 그 작업에 조치를 보내고 사용자에게 알립니다. 작업은 긴 명령을 세션과 분리해 실행하고, 결과 파일을 직접 확인하며, 시간 상한을 겁니다.
+16. 작업 하나에 나눌 수 있는 항목이 여럿이거나(예: 버그 여러 개, 구현·검증·문서 단계) 앞 단계를 기다려야 하는 단계가 있으면, 작업 세션은 mass-ulw 스킬을 씁니다. 작업 세션은 처음에 단계와 하위 작업을 정합니다. 서로 기다릴 필요가 없는 하위 작업은 최대한 병렬로 돌립니다. main은 이런 작업을 맡길 때 작업 지시문에 mass-ulw를 쓰라고 적습니다. 파일 하나 고침, 문서 한 줄 같은 작은 작업에는 mass-ulw를 쓰지 않습니다. 같은 파일을 고치는 하위 작업은 같은 단계에서 함께 돌리지 않습니다. 이런 하위 작업은 각자 worktree를 쓰거나 순서대로 돌립니다. 하위 작업을 병렬로 돌려도 무거운 명령(전체 테스트, 뮤테이션 테스트, 빌드 등)은 그 프로젝트나 설치 규칙이 정한 동시 실행 상한을 지킵니다. 규칙 8의 정리와 규칙 15의 감시는 하위 작업에도 적용합니다. 사용자가 질문만 하면 진행 중인 작업을 mass-ulw로 바꾸지 않습니다(규칙 4).

package/assets/android/zigmini.apk.json

@@ -1,5 +1,5 @@
 {
-  "versionCode": 22,
-  "versionName": "0.8.0-beta.3",
-  "sha256": "819f50b65105dde875324e7dde62635321ee1412ba1e975849a764f10dea3426"
+  "versionCode": 24,
+  "versionName": "0.8.0-beta.5",
+  "sha256": "783c65a373c2b3f7b9f117e66237c6081a85a8f225c7ef9af182049e3a8a5393"
 }

package/assets/build.json

@@ -1 +1 @@
-{"commit":"d6641bcbb5a3d30fe55d94c24f05113f3405518b"}
+{"commit":"6eea099deac067c0e19d44b3bb2890a341438510"}