zigmini 0.8.0-beta.6 → 0.9.0-beta.1

package/README.ko.md

@@ -8,7 +8,8 @@ zigmini는 맥에서 도는 개인 AI 에이전트 게이트웨이입니다. 맥
 
 - Apple Silicon(M칩) 맥과 macOS. Intel 맥, Linux, Windows는 지원하지 않습니다.
 - [Bun](https://bun.sh) 1.4.0 이상. 설치에는 Bun만 필요합니다. Node.js와 npm은 필요하지 않습니다.
-- 에이전트가 쓸 모델 계정(예: Claude, ChatGPT 구독). 설치 뒤 로그인합니다.
+- Bun으로 전역 설치한 에이전트 엔진 명령 `omo`(패키지 `omo-ai`). 필수입니다. 없으면 모델 계정에 로그인할 수 없고 게이트웨이가 동작하지 않습니다. 설치 15~18번에서 설치합니다.
+- 에이전트가 쓸 모델 계정(예: Claude, ChatGPT 구독). `zigmini setup` 전에 `omo`로 로그인합니다.
 - (선택) Android 폰. 앱은 게이트웨이가 직접 제공합니다.
 - (선택) 폰을 밖에서 쓰려면 Tailscale 또는 HTTPS 리버스 프록시가 있는 자기 도메인.
 
@@ -64,12 +65,12 @@ zigmini는 에이전트를 권한 프리셋 `full-access`로 실행합니다.
    ```sh
    bun add -g zigmini
    ```
-   - `zigmini setup`(15번)을 마칠 때까지 다른 명령은 오류 출력에 `` 아직 설치를 마치지 않았습니다. 먼저 `zigmini setup`을 실행하세요. ``를 보여 줍니다. `--version`, `--help`, `setup`, `consent`, `migrate`, `migrate-run`은 이 줄을 보여 주지 않습니다. `zigmini --help`도 먼저 setup을 실행하라고 안내합니다.
+   - `zigmini setup`(19번)을 마칠 때까지 다른 명령은 오류 출력에 `` 아직 설치를 마치지 않았습니다. 먼저 `zigmini setup`을 실행하세요. ``를 보여 줍니다. `--version`, `--help`, `setup`, `consent`, `migrate`, `migrate-run`은 이 줄을 보여 주지 않습니다. `zigmini --help`도 먼저 setup을 실행하라고 안내합니다.
 9. `zigmini` 명령을 찾는지 확인합니다.
    ```sh
    zigmini --version
    ```
-   - 결과가 숫자로 시작하는 버전 한 줄(예: `0.8.0-beta.3`)이면 15번으로 갑니다.
+   - 결과가 숫자로 시작하는 버전 한 줄(예: `0.9.0-beta.1`)이면 15번으로 갑니다.
    - 결과가 `zsh: command not found: zigmini`이면 Bun 전역 명령 폴더가 PATH에 없습니다. 10번으로 갑니다.
 10. 지금 터미널 창에서 Bun 전역 명령 폴더를 PATH에 넣습니다. 이 명령은 지금 터미널 창에만 적용되고 파일을 바꾸지 않습니다.
     ```sh
@@ -94,23 +95,45 @@ zigmini는 에이전트를 권한 프리셋 `full-access`로 실행합니다.
 14. 9번 명령을 다시 실행합니다.
     - 결과가 숫자로 시작하는 버전 한 줄이면 15번으로 갑니다.
     - 결과가 여전히 `zsh: command not found: zigmini`이면 설치를 멈춥니다. `ls "$(bun pm bin -g)"`를 실행합니다. 결과에 `zigmini`가 없으면 8번의 `bun add -g zigmini` 출력에서 `error:`로 시작하는 줄을 확인합니다.
-15. 설치를 마칩니다.
-   ```sh
-   zigmini setup
-   ```
+15. 에이전트 엔진 `omo-ai`를 전역 설치합니다. 필수 단계입니다. `omo-ai` 설치와 모델 계정 로그인이 없으면 게이트웨이가 동작하지 않습니다. 15~18번을 건너뛰면 `zigmini setup`이 전역 `omo`를 직접 설치하고 로그인 단계에서 기다리지만, 로그인은 직접 해야 합니다. 그래도 여기의 단계를 먼저 합니다. 버전은 게이트웨이가 고정한 stock 버전에 맞춥니다(`src/engine/compat.json`의 `omo`, 0.9.0-beta.1은 5.1.44이며 설치된 릴리스는 자체 고정값을 유지합니다).
+    ```sh
+    bun add -g omo-ai@5.1.44
+    ```
+16. 셸이 `omo` 명령을 찾는지 확인합니다. 결과는 버전 한 줄이어야 합니다.
+    ```sh
+    omo --version
+    ```
+17. `omo`를 실행합니다.
+    ```sh
+    omo
+    ```
+18. `omo`에서 `/login`을 입력해 모델 계정에 로그인합니다. 그다음 `omo`를 끝냅니다. 로그인 정보는 에이전트 폴더 `~/.omo/agent`에 저장되고, 게이트웨이도 같은 폴더를 씁니다.
+19. 설치를 마칩니다.
+    ```sh
+    zigmini setup
+    ```
 
 `zigmini setup`은 아래 순서로 진행합니다. 다시 실행해도 됩니다. 이미 끝난 단계는 그대로 둡니다.
 
-1. 권한 안내를 보여 주고 동의를 받습니다.
-2. 홈 폴더 `~/.zigmini`를 만듭니다. 이 설치의 규칙 파일(`~/.zigmini/rules.md`)이 없으면 빈 파일을 만듭니다. 아래 "에이전트 규칙"을 보세요.
-3. 에이전트 엔진(omo-ai)의 고정 버전을 내려받아 해시를 확인하고 패치합니다. 버전은 패키지가 정합니다(`src/engine/compat.json`, 이 문서를 쓸 때 엔진 5.1.35). 엔진 라이선스 요약을 보여 주고 동의(`y`)를 받습니다.
-4. 에이전트 폴더와 모델 계정 로그인 상태를 확인합니다. 기본 에이전트 폴더는 `~/.omo/agent`이고, 같은 폴더를 쓰는 다른 OMO와 로그인 정보를 같이 씁니다. 로그인하지 않았으면 로그인 명령을 출력합니다. 그 명령을 실행한 뒤 `/login`을 입력합니다.
-5. Notion 토큰을 묻습니다(선택). 비우면 일정 기능이 꺼집니다.
-6. 외부 접속 방식을 묻습니다. 아래 "외부 접속"을 보세요.
-7. 서비스 설정(`~/.zigmini/config.env`, 권한 프리셋 `full-access`)을 쓰고 음성은 꺼 둡니다.
-8. 게이트웨이와 브리지를 launchd에 등록하고 시작합니다. 게이트웨이가 준비될 때까지 기다립니다(최대 600초).
-9. 자기 도메인을 골랐으면 그 도메인이 앱 포트에 닿는지 확인합니다.
-10. 앱 내려받기 QR과 폰 등록 QR을 터미널에 그립니다.
+1. 언어를 묻습니다: `Language / 언어 [1] English [2] 한국어`. 그 뒤의 안내는 모두 고른 언어로 나옵니다. 고른 언어는 `~/.zigmini/language`에 저장되고 `zigmini setup --access`, `zigmini pair`, `zigmini start`·`restart`의 준비 대기도 이 언어를 씁니다. `--lang en|ko`로 묻지 않고 정할 수 있습니다. 묻지 않는 설치(`--non-interactive`)는 저장된 언어, 없으면 시스템 언어(`LANG`이 `ko…`이면 한국어), 그것도 없으면 영어를 씁니다.
+2. 권한 안내를 보여 주고 동의를 받습니다.
+3. 홈 폴더 `~/.zigmini`를 만듭니다. 이 설치의 규칙 파일(`~/.zigmini/rules.md`)이 없으면 빈 파일을 만듭니다. 아래 "에이전트 규칙"을 보세요.
+4. 에이전트 엔진(omo-ai)의 고정 버전을 내려받아 해시를 확인하고 패치합니다. 버전은 패키지가 정합니다(`src/engine/compat.json`, 이 문서를 쓸 때 엔진 5.1.44). 엔진 라이선스 요약을 보여 주고 동의(`y`)를 받습니다.
+5. 전역 `omo` 명령을 `bun add -g omo-ai@<버전>`으로 설치합니다. 버전은 고정 엔진과 같은 stock 버전입니다. 전역 `omo`가 이미 그 버전이면 설치를 건너뜁니다. 다른 버전이면 `<버전>으로 덮어쓸까요? (y/N)`를 묻습니다. 묻지 않는 설치는 있는 버전을 유지합니다. 설치에 실패하면 고정 엔진의 긴 명령을 로그인 명령으로 보여 줍니다.
+6. 에이전트 폴더와 모델 계정 로그인 상태를 확인합니다. 기본 에이전트 폴더는 `~/.omo/agent`이고, 같은 폴더를 쓰는 다른 OMO와 로그인 정보를 같이 씁니다. 로그인하지 않았으면 아래 상자를 보이고 기다립니다.
+   ```text
+   ========================================
+   모델 계정에 로그인하세요: 터미널에서 `omo`를 실행한 뒤 `/login`을 입력합니다.
+   ========================================
+   로그인한 뒤 Enter로 다시 확인하세요. 건너뛰려면 s를 입력하세요:
+   ```
+   다른 터미널에서 로그인한 뒤 Enter를 누릅니다. 모델 계정이 확인될 때까지 다시 확인합니다. 시간 상한은 없습니다. `s`를 입력하면 `경고: 로그인하기 전까지 게이트웨이가 채팅에 답하지 않습니다.`를 보이고 넘어갑니다. `--agent-dir`을 쓰면 상자의 명령은 `env OMO_CODING_AGENT_DIR=<경로> omo`입니다. 묻지 않는 설치는 상자만 보이고 넘어갑니다.
+7. Notion 토큰을 묻습니다(선택). 비우면 일정 기능이 꺼집니다.
+8. 외부 접속 방식을 묻습니다. 아래 "외부 접속"을 보세요.
+9. 서비스 설정(`~/.zigmini/config.env`, 권한 프리셋 `full-access`)을 쓰고 음성은 꺼 둡니다.
+10. 게이트웨이와 브리지를 launchd에 등록하고 시작합니다. 게이트웨이가 준비될 때까지 기다립니다(최대 600초). health 응답 없이 기다리는 동안 launchd 상태(pid, 마지막 종료 코드)와 게이트웨이 로그 마지막 줄을 보입니다. 엔진 연결이 계속 끊겨 있으면 브리지 로그 마지막 줄과 `zigmini setup --engine-only --accept-license` 명령을 보입니다.
+11. 자기 도메인을 골랐으면 그 도메인이 앱 포트에 닿는지 확인합니다.
+12. 터미널에는 QR을 그리지 않습니다. 터미널 글꼴 때문에 카메라가 QR을 읽지 못하는 경우가 많기 때문입니다. 대신 웹 화면에서 QR을 찍으라고 안내합니다(아래 "폰 등록"). 외부 접속을 고르지 않았으면 먼저 `zigmini setup --access <tailscale|lan|domain>`을 실행하라고 안내합니다.
 
 설치가 끝나면 맥의 브라우저에서 http://127.0.0.1:8700 을 엽니다.
 
@@ -121,6 +144,7 @@ zigmini setup --non-interactive --accept-license --access lan
 
 | 옵션 | 뜻 |
 |---|---|
+| `--lang <en\|ko>` | 마법사와 CLI 안내의 언어 |
 | `--non-interactive` | 묻지 않습니다 |
 | `--accept-license` | 엔진 라이선스에 동의합니다 |
 | `--agent-dir <경로>` | 공유 `~/.omo/agent` 대신 쓸 전용 에이전트 폴더 |
@@ -142,12 +166,14 @@ zigmini setup --non-interactive --accept-license --access lan
 
 ## 폰 등록
 
+맥에서 http://127.0.0.1:8700 을 열고 "설정"을 엽니다. 앱 내려받기 QR은 "앱 내려받기"에, 폰 등록 QR은 "기기 등록"에 있습니다. 외부 접속 방식을 먼저 골라야 합니다("외부 접속" 참고).
+
 1. 폰에서 앱 내려받기 QR을 찍어 APK를 받고 설치합니다. 설치할 때 Android가 "출처를 알 수 없는 앱" 허용을 물으면 허용합니다.
 2. 앱 첫 화면에서 "QR로 등록"을 눌러 폰 등록 QR을 찍습니다.
 
 앱 첫 화면에는 카메라 없이 등록하는 "게이트웨이 주소"와 "등록 토큰 붙여 넣기" 칸도 있습니다. 토큰 칸에는 등록 QR이 담은 `zigmini://enroll?...` 글 전체를 붙여 넣을 수 있습니다. 이때는 그 글의 주소를 씁니다. 토큰은 한 번만, 유효 시간 안에서만 쓸 수 있습니다.
 
-두 QR은 `zigmini setup`의 마지막에 나옵니다. 다시 만들려면 아래 명령이나 웹 화면 설정의 "기기 등록"·"앱 내려받기"를 씁니다. 게이트웨이가 실행 중이어야 합니다.
+웹 화면 설정이 기본 방법입니다. 아래 명령은 같은 QR을 터미널에 그립니다. 터미널 글꼴에 따라 QR이 깨질 수 있습니다. 게이트웨이가 실행 중이어야 합니다. 외부 접속을 고르지 않았으면 먼저 `zigmini setup --access <tailscale|lan|domain>`을 실행하라고 안내합니다.
 ```sh
 zigmini pair --apk   # 앱 내려받기 QR (유효 10분)
 zigmini pair         # 폰 등록 QR (유효 10분, 한 번 사용)
@@ -155,6 +181,8 @@ zigmini pair         # 폰 등록 QR (유효 10분, 한 번 사용)
 
 앱 하나로 게이트웨이 여러 개를 등록할 수 있습니다. 게이트웨이마다 주소와 인증 값을 따로 저장하고, 모든 게이트웨이의 알림을 받습니다. 알림을 누르면 그 게이트웨이로 바뀝니다. 등록한 기기는 웹 화면 설정의 "등록된 기기"에서 확인합니다.
 
+웹 설정이나 앱 작업 상태 화면(헤더의 지그를 눌러 엶)에서 앱 알림 수준을 고릅니다. 기본값은 "확인함 알림만"입니다. "모든 답장 알림"은 확인함 알림과 함께 작업 세션을 포함한 에이전트의 완성 답장마다 알립니다. 두 화면은 같은 게이트웨이 저장값을 바꿉니다. 다른 게이트웨이의 값은 바뀌지 않습니다. 일정과 명시적으로 요청한 알림은 이 설정과 별개입니다. 알림은 진동만 사용합니다. 새 게이트웨이와 새 앱이 필요합니다.
+
 ## 앱 서명 지문
 
 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`. 인증서가 둘 이상이거나 값이 다르면 설치하지 마세요.
@@ -167,10 +195,41 @@ 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
 
 사용자 매뉴얼([한국어](docs/manual.ko.md), [English](docs/manual.md))은 웹 설정 창 위쪽의 "매뉴얼" 버튼과, 앱 헤더의 상태 태그를 짧게 눌러 여는 연결 화면의 "매뉴얼" 버튼으로 봅니다.
 
+## 0.9.0-beta.1의 새 기능
+
+0.9.0-beta.1(2026-10-28 KST, Android `versionCode` 27)은 엔진 `5.1.44-zgw`(OMO 5.1.44, senpi 2026.10.21-3, 대화 스키마 7)를 선택합니다. 전체 노트는 [docs/releases/0.9.0-beta.1.ko.md](docs/releases/0.9.0-beta.1.ko.md)에 있습니다.
+
+- **채팅 도식:** 웹과 Android 앱이 답변의 `zigmini-diagram` 블록을 그립니다.
+- **보안 확인함과 정확값 허용:** 보안검사로 보류한 항목이 웹과 앱의 확인함에 나옵니다. 보내기를 고르면 게이트웨이가 표시한 정확값을 설치별 목록에 기억합니다. 기억한 값은 설정에서 보고 지웁니다.
+- **알림 설정:** 웹 설정이나 앱 설정 화면에서 "확인함 알림만"과 "모든 답장 알림" 중 하나를 고릅니다. "모든 답장 알림" 저장의 HTTP 500 오류를 고쳤습니다.
+- **화면 수정:** 웹 이동 버튼이 메시지를 가리지 않고, Android 헤더에 모델 선택기 자리가 남습니다.
+
+릴리스 발행은 맥과 폰을 바꾸지 않습니다. 맥은 "업데이트" 또는 `zigmini update`를 실행할 때까지 설치된 게이트웨이와 엔진을 유지합니다. 폰은 새 APK를 설치할 때까지 기존 앱을 유지합니다.
+
+남은 문제: 버그 80(Android 참조 밀기, 요구사항만 기록), 버그 184(Android 음성 버튼 잘림, 미확정), 버그 205(Git 객체 검사 범위만 바꿈, 과거 14922건은 기록으로 남고 GitHub 지원 요청은 보류), 버그 212(변이 기록 작성기 미수정). 진단 보고와 수신 서버는 이번 릴리스에 없습니다.
+
+## 완료 답변 통계
+
+웹 채팅과 새 Android 앱은 완료 답변 아래에 엔진이 측정한 TPS(초당 토큰 수),
+모델 처리 시간, 캐시 적중률을 표시합니다. 통계는 도구 호출 전후의 모델 응답을
+합친 한 응답 턴의 값입니다. 모델 처리 시간에는 도구 실행 시간이 들어가지
+않으며, 전체 대기 시간이 아닙니다. 없는 측정값은 생략합니다. 측정한 생성
+시간의 합계가 500ms보다 짧으면 TPS를 생략합니다. 통계는 답변 본문·복사·알림과
+분리합니다. 함께 제공하는 엔진 패치가 필요합니다. 이전 엔진과 게이트웨이가
+게시한 작업 보고에는 추정값을 붙이지 않습니다.
+
 ## 음성
 
 새 설치에서 음성은 꺼져 있습니다. 음성 인식과 음성 합성을 쓰려면 맥의 웹 화면 위쪽의 "음성 설치" 버튼을 누릅니다. 버튼에 내려받을 크기가 보입니다. 게이트웨이가 uv, Python 환경, 음성 모델(약 8GB)을 `~/.zigmini/voice`에 내려받습니다. 진행률은 채팅에 나옵니다. 실패하면 같은 버튼으로 실패한 단계부터 다시 시작합니다. 설치가 끝나면 "음성 꺼짐"을 눌러 켭니다. 음성 설치와 켜기·끄기는 맥의 웹 화면에서 합니다. 앱은 음성 상태만 보여 줍니다. 웹 화면 위쪽에서 "호출어", "박수 감지"(박수 두 번), "음성 답변"도 켭니다.
 
+## 보안검사
+
+게이트웨이는 메시지를 엔진에 넘기기 전에, 공개되면 맥·서버·계정 공격의 단서가 되는 값이 있는지 검사합니다. 대상은 비밀키, 토큰·API 키, 비밀번호·쿠키·인증 값, 홈 폴더 경로, 내부 IP·호스트 이름, 이메일 주소, 전화번호, 기기 식별값입니다. 엔진으로 가는 모든 사용자 글을 검사합니다. 웹 채팅, 앱, 음성 입력, 참조한 메시지, 확인함 답의 자유 입력이 모두 포함됩니다. 검사는 게이트웨이 메모리 안에서만 돌고 네트워크와 디스크를 쓰지 않습니다. 일반 메시지는 1ms보다 훨씬 짧게 걸립니다.
+
+값이 나오면 게이트웨이가 메시지를 보류하고 보내지 않습니다. 엔진이 아니라 게이트웨이가 웹과 앱에 "보안검사 결과" 카드를 직접 보여 줍니다. 카드에는 걸린 값마다 종류, 실제 값, 메시지 안의 줄과 칸이 보이고 "이 값들을 노출해도 되겠습니까?"라고 묻습니다. "보내기"를 누르면 원래 메시지를 그대로 엔진에 보냅니다. "보내지 않기"를 누르면 메시지를 버리고, 웹은 글을 입력창에 되돌려 고칠 수 있게 합니다. 걸린 값은 엔진, 엔진 세션 파일, 대화 기록, 로그에 들어가지 않습니다. 보류한 메시지는 게이트웨이 메모리에만 있습니다. 게이트웨이가 다시 시작하면 보내지 않고 버리며, 웹 카드에 그렇게 표시됩니다.
+
+보안검사는 기본으로 켜져 있습니다. 웹 설정의 "보안검사 켜짐/꺼짐" 버튼으로 끄고 켭니다. 설정은 `~/.zigmini/data/security-check`에 저장되어 재시작 뒤에도 유지됩니다. 끄면 검사 없이 바로 엔진에 보냅니다. 검사가 찾는 종류의 목록은 [docs/security-check.md](docs/security-check.md)에 있습니다.
+
 ## 업데이트
 
 새 버전이 나오면 웹 화면 위쪽에 새 버전 줄이 나오고, 앱에도 버전 알림이 나옵니다. 업데이트는 웹 화면 설정의 "업데이트" 버튼("지금 확인"은 새 버전을 확인합니다), 앱 버전 알림의 "업데이트" 버튼, 또는 아래 명령으로 합니다.
@@ -199,9 +258,10 @@ zigmini update <버전>     # 지정한 버전으로 업데이트
 
 | 명령 | 하는 일 |
 |---|---|
-| `zigmini setup` | 설치합니다 |
+| `zigmini setup` | 설치합니다. `--engine-only`는 엔진만 설치하고, `--access <방식>`은 외부 접속만 바꿉니다 |
 | `zigmini start` | 게이트웨이와 브리지를 launchd에 등록하고 시작합니다 |
 | `zigmini stop` | 게이트웨이와 브리지를 멈춥니다 |
+| `zigmini stop --uninstall` | 멈추고 이 패키지의 launchd plist를 모두 지웁니다 |
 | `zigmini restart [gateway\|bridge]` | 다시 시작합니다 |
 | `zigmini status` | launchd 상태, health, 권한 동의 상태를 보여 줍니다 |
 | `zigmini doctor [--json] [--fix]` | 전체 상태를 점검합니다 |
@@ -242,6 +302,17 @@ zigmini update <버전>     # 지정한 버전으로 업데이트
 4. 그래도 안 되면 로그 폴더 `~/.zigmini/logs`를 확인합니다.
 
 - 게이트웨이가 시작하지 않고 권한 동의가 없다고 나오면 `zigmini consent`를 실행합니다.
+
+### 알려진 설치 문제
+
+아래 우회 방법을 씁니다.
+
+- **마법사가 "게이트웨이 준비를 기다리는 중"에서 "health 응답 없음"만 보입니다.** 게이트웨이가 웹 포트에서 응답하지 않습니다. 원인은 아직 찾지 못했습니다. 마법사는 기다리는 동안 launchd 상태와 로그 마지막 줄을 보이고, 600초 뒤 멈춥니다. `zigmini status`와 `zigmini doctor`를 실행하고 `~/.zigmini/logs/gateway.log`, `~/.zigmini/logs/bridge.log`를 봅니다. 엔진이 없거나 깨졌으면 `zigmini setup --engine-only --accept-license`로 엔진만 다시 설치하고 `zigmini doctor --fix`를 실행합니다.
+- **폰이 접속하지 못하거나 QR을 쓸 수 없습니다.** 외부 접속을 고르지 않아서 앱 포트가 꺼져 있습니다. 방식을 고른 뒤 웹 화면 설정에서 QR을 찍습니다.
+  ```sh
+  zigmini setup --access lan   # 또는 tailscale, domain --domain https://<도메인>
+  ```
+- **설치 뒤 에이전트가 답하지 않습니다.** 모델 계정에 로그인하지 않았습니다(예: 로그인 단계에서 `s`를 입력함). 설치 15~18번(`bun add -g omo-ai@5.1.44`, `omo`, `/login`)을 합니다. 그 뒤 `zigmini setup`을 다시 실행합니다. "모델 계정: 로그인됨"이 나오고, 이미 끝난 단계는 유지됩니다. `--agent-dir`을 쓰면 `OMO_CODING_AGENT_DIR=<경로> omo`로 실행해야 그 폴더에 로그인됩니다.
 - 오래된 DB 백업, 쓰지 않는 엔진 버전, 업데이트에서 남은 파일은 웹 화면 설정의 "정리"에서 확인하고, 고른 항목만 지웁니다.
 
 ## 제거

package/README.md

@@ -8,7 +8,8 @@ zigmini: a personal AI agent gateway that runs on a Mac. You talk with the agent
 
 - 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.
+- The agent engine command `omo` (package `omo-ai`), installed globally with Bun. It is required: without it you cannot log in to the model account, and the gateway does not work. Install steps 15 to 18 install it.
+- A model account for the agent (for example a Claude or ChatGPT subscription). You log in with `omo` before `zigmini setup`.
 - (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.
 
@@ -64,12 +65,12 @@ The gateway runs the agent with the permission preset `full-access`. The agent d
    ```sh
    bun add -g 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.
+   - Until `zigmini setup` (step 19) 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
    ```
-   - 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 one version line that starts with a number (for example `0.9.0-beta.1`), 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
@@ -94,23 +95,45 @@ The gateway runs the agent with the permission preset `full-access`. The agent d
 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
-   ```
+15. Install the agent engine `omo-ai` globally. This step is required: without the `omo-ai` installation and the model account login, the gateway does not work. If you skip steps 15 to 18, `zigmini setup` installs the global `omo` itself and stops at the login step, but you must still log in. Do the steps here anyway. Use the stock version that the gateway pins (`omo` in `src/engine/compat.json`; 5.1.44 in 0.9.0-beta.1; installed releases keep their own pin).
+    ```sh
+    bun add -g omo-ai@5.1.44
+    ```
+16. Check that the shell finds the `omo` command. The result must be one version line.
+    ```sh
+    omo --version
+    ```
+17. Start `omo`.
+    ```sh
+    omo
+    ```
+18. In `omo`, type `/login` and log in to the model account. Then quit `omo`. The login is stored in the agent folder `~/.omo/agent`, and the gateway uses the same folder.
+19. Finish the installation.
+    ```sh
+    zigmini setup
+    ```
 
 `zigmini setup` does these steps in this order. You can run it again. It keeps the steps that are already done.
 
-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.
+1. It asks for the language: `Language / 언어 [1] English [2] 한국어`. All later messages use this language. The choice is saved in `~/.zigmini/language` and used by `zigmini setup --access`, `zigmini pair` and the ready wait of `zigmini start` and `restart`. `--lang en|ko` picks it without the question. Without a question (`--non-interactive`) the saved language is used, else the system language (`LANG`, `ko…` means Korean), else English.
+2. It shows the permission notice and asks for your consent.
+3. 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.
+4. 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.44 at the time of writing). It shows a summary of the engine license and asks for your consent (`y`).
+5. It installs the global `omo` command with `bun add -g omo-ai@<version>`, the same stock version as the pinned engine. If the global `omo` already has this version, it skips the installation. If it has another version, it asks `Replace it with <version>? (y/N)`; without a question it keeps the installed one. If the installation fails, it shows the long command of the pinned engine for the login instead.
+6. 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 shows this box and waits:
+   ```text
+   ========================================
+   Run `omo` in a terminal and type `/login`.
+   ========================================
+   After logging in, press Enter to check again; type s to skip:
+   ```
+   Log in in another terminal, then press Enter. It checks again until a model account is found. There is no time limit. If you type `s`, it shows `Warning: Until you log in, the gateway will not answer chats.` and goes on. With `--agent-dir`, the command in the box is `env OMO_CODING_AGENT_DIR=<경로> omo` (`<경로>`: path). Without a question it only prints the box and goes on.
+7. It asks for a Notion token (optional). If you leave it empty, the schedule feature is off.
+8. It asks for the external access method. See "External access" below.
+9. It writes the service settings (`~/.zigmini/config.env`, permission preset `full-access`) and leaves voice off.
+10. It registers the gateway and the bridge with launchd and starts them. It waits until the gateway is ready (up to 600 seconds). While it waits without a health response, it shows the launchd state (pid, last exit code) and the last line of the gateway log. If the engine stays disconnected, it shows the last line of the bridge log and the command `zigmini setup --engine-only --accept-license`.
+11. If you picked your own domain, it checks that the domain reaches the app port.
+12. It does not draw QR codes in the terminal, because terminal fonts often break them for the camera. It tells you to open the web screen and scan the QR codes there (see "Phone registration" below). If you picked no external access method, it first tells you to run `zigmini setup --access <tailscale|lan|domain>`.
 
 When the installation is done, open http://127.0.0.1:8700 in a browser on the Mac.
 
@@ -121,6 +144,7 @@ zigmini setup --non-interactive --accept-license --access lan
 
 | Option | Meaning |
 |---|---|
+| `--lang <en\|ko>` | The language of the wizard and the CLI messages |
 | `--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) |
@@ -142,12 +166,14 @@ To change it later, run `zigmini setup --access <방식>` again (`<방식>`: met
 
 ## Phone registration
 
+Open http://127.0.0.1:8700 on the Mac and open "설정" (Settings). The app download QR code is in "앱 내려받기" (Download app), and the phone registration QR code is in "기기 등록" (Register device). An external access method must be picked first (see "External access").
+
 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.
 
 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.
 
-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.
+The web screen settings are the recommended way. The commands below draw the same QR codes in the terminal; some terminal fonts break them. The gateway must be running. If no external access method is picked, they tell you to run `zigmini setup --access <tailscale|lan|domain>` first.
 ```sh
 zigmini pair --apk   # app download QR code (valid for 10 minutes)
 zigmini pair         # phone registration QR code (valid for 10 minutes, single use)
@@ -155,6 +181,8 @@ zigmini pair         # phone registration QR code (valid for 10 minutes, single
 
 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.
 
+Choose the app notification level in web settings or the app's work status screen (tap Zig in the header). "확인함 알림만" (Inbox notifications only) is the default. "모든 답장 알림" (All reply notifications) also alerts for each completed agent reply, including replies from work sessions. Both screens change the same saved gateway setting. Other gateways keep their own values. Schedule reminders and explicit notifications are independent of this setting. Notifications remain vibration-only. This feature needs the updated gateway and app.
+
 ## App signing fingerprint
 
 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.
@@ -167,10 +195,42 @@ 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
 
 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.
 
+## What's new in 0.9.0-beta.1
+
+Release 0.9.0-beta.1 (2026-10-28 KST, Android `versionCode` 27) selects engine `5.1.44-zgw` (OMO 5.1.44, senpi 2026.10.21-3, thread schema 7). Full notes: [docs/releases/0.9.0-beta.1.md](docs/releases/0.9.0-beta.1.md).
+
+- **Diagrams in chat:** the web and the Android app draw `zigmini-diagram` blocks in answers.
+- **Security inbox and exact-value consent:** held security-check items appear in the web and app inbox. When you send one, the gateway remembers the exact displayed values for that installation. You can review and remove them in the settings.
+- **Notification settings:** choose "확인함 알림만" (Inbox notifications only) or "모든 답장 알림" (All reply notifications) in the web settings or the app settings screen. Saving "All reply notifications" no longer fails with HTTP 500.
+- **UI fixes:** the web scroll buttons no longer cover messages, and the Android header keeps room for the model picker.
+
+Publishing a release doesn't change your Mac or phone. The Mac keeps its installed gateway and engine until you run "업데이트" (Update) or `zigmini update`, and the phone keeps its app until you install the new APK.
+
+Still open: bug 80 (Android reference swipe, only requirements recorded), bug 184 (Android voice button clipping, unconfirmed), bug 205 (only the Git-object scope changed; the 14922 historical findings stay recorded and the GitHub support request stays deferred) and bug 212 (the mutation-record writer is not fixed). Diagnostic reports and the receiver server aren't part of this release.
+
+## Completed-answer statistics
+
+The web chat and updated Android app show available engine measurements below a
+completed answer: TPS (tokens per second), model processing time and cache hit
+percentage. These describe the response turn, including model calls around
+tools. Model processing time excludes tool execution and is not total waiting
+time. Missing measurements are omitted; TPS is omitted when the combined
+measured generation time is shorter than 500 ms. Statistics are separate from answer
+text, copies and notifications. They require the accompanying engine patch;
+older engines and gateway-published work reports do not get estimated values.
+
 ## 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 ("음성 답변").
 
+## Security check
+
+Before the gateway hands a message to the engine, it checks the message for values that would help someone reach or attack your Mac, servers or accounts: private keys, tokens and API keys, passwords, cookies and authorization values, home folder paths, internal IP addresses and host names, email addresses, phone numbers and device ids. The check covers every way user text reaches the engine: the web chat, the app, voice input, referenced messages and free-text answers in the inbox. It runs in gateway memory, with no network or disk access, in well under a millisecond for an ordinary message.
+
+When it finds something, the gateway holds the message and does not send it. The gateway itself (not the engine) shows a "보안검사 결과" (security check result) card on the web and in the app. The card lists each value with its kind and its line and column in the message, and asks whether these values may be exposed. "보내기" (send) sends the original message to the engine unchanged. "보내지 않기" (don't send) drops it, and the web puts the text back into the input box so you can fix it. The values never reach the engine, its session files, the conversation history or the logs. Held messages live only in gateway memory: a gateway restart drops them without sending them, and the web card then says so.
+
+The check is on by default. Turn it off or on with "보안검사 켜짐/꺼짐" (Security check on/off) in the web settings. The setting is stored in `~/.zigmini/data/security-check` and survives a restart. With the check off, messages go to the engine without a check. The list of kinds that the check finds is in [docs/security-check.md](docs/security-check.md).
+
 ## 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.
@@ -199,9 +259,10 @@ An update to a version that does not support the zero-downtime switch (including
 
 | Command | What it does |
 |---|---|
-| `zigmini setup` | Installs |
+| `zigmini setup` | Installs. `--engine-only` installs only the engine, `--access <방식>` changes only the external access (`<방식>`: method) |
 | `zigmini start` | Registers the gateway and the bridge with launchd and starts them |
 | `zigmini stop` | Stops the gateway and the bridge |
+| `zigmini stop --uninstall` | Stops them and removes all launchd plists of this package |
 | `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 |
@@ -242,6 +303,17 @@ Sessions that open after a change use the new content. To apply it at once, run
 4. If this does not help, look at the log folder `~/.zigmini/logs`.
 
 - If the gateway does not start and reports that there is no permission consent, run `zigmini consent`.
+
+### Known installation problems
+
+Use these workarounds.
+
+- **The wizard shows only "no health response" in "Waiting for the gateway".** The gateway does not answer on the web port. The cause is not found yet. The wizard now shows the launchd state and the last log lines while it waits, and stops after 600 seconds. Run `zigmini status` and `zigmini doctor`, and read `~/.zigmini/logs/gateway.log` and `~/.zigmini/logs/bridge.log`. If the engine is missing or broken, install only the engine again with `zigmini setup --engine-only --accept-license`, then run `zigmini doctor --fix`.
+- **The phone cannot connect, or the QR codes are not available.** You did not pick an external access method, so the app port is off. Pick a method, then scan the QR codes in the web screen settings:
+  ```sh
+  zigmini setup --access lan   # or tailscale, or domain --domain https://<도메인>
+  ```
+- **After the installation the agent does not answer.** The model account is not logged in (for example you typed `s` at the login step). Do install steps 15 to 18 (`bun add -g omo-ai@5.1.44`, `omo`, `/login`). Then run `zigmini setup` again. It shows "Model accounts: logged in" and keeps the steps that are already done. If you use `--agent-dir`, start `omo` with `OMO_CODING_AGENT_DIR=<경로> omo` so that it logs in to that folder.
 - 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

package/assets/agent/gateway-request-rules.md

@@ -0,0 +1,3 @@
+사용자에게 보여 주는 모든 답변과 설명은 ASD-STE100의 명확한 기술문서 작성 원칙을 따른다. 짧은 능동문을 쓰고, 한 문장에는 한 가지 내용만 담는다. 주체·대상·행동을 명확히 밝히고, 같은 대상에는 같은 용어를 쓴다.
+
+흐름이나 구조를 설명할 때 도식이 도움이 되면 `docs/manual.md`의 `zigmini-diagram` 형식으로 함께 표시한다.

package/assets/agent/gateway-rules.md

@@ -19,3 +19,9 @@ zigmini 패키지 공통 에이전트 규칙입니다. 게이트웨이 브리지
 14. 사용자는 게이트웨이 프로필의 닉네임으로 부릅니다.
 15. main은 오래 기다리거나 오래 실행하는 작업(배포, 전체 테스트, 뮤테이션 테스트, 다른 작업 기다리기)을 맡기면, 그 작업의 세션 기록이 30분 넘게 바뀌지 않을 때 main을 깨우는 감시를 직접 겁니다. 작업이 끝나면 감시를 끕니다. 작업의 "기다리는 중"·"진행 중" 보고만 믿지 않습니다. 사용자에게 그렇게 말하기 전에 그 작업의 마지막 기록 시각과 실행 중인 프로세스를 확인합니다. 작업이 멈췄으면 바로 그 작업에 조치를 보내고 사용자에게 알립니다. 작업은 긴 명령을 세션과 분리해 실행하고, 결과 파일을 직접 확인하며, 시간 상한을 겁니다.
 16. 작업 하나에 나눌 수 있는 항목이 여럿이거나(예: 버그 여러 개, 구현·검증·문서 단계) 앞 단계를 기다려야 하는 단계가 있으면, 작업 세션은 mass-ulw 스킬을 씁니다. 작업 세션은 처음에 단계와 하위 작업을 정합니다. 서로 기다릴 필요가 없는 하위 작업은 최대한 병렬로 돌립니다. main은 이런 작업을 맡길 때 작업 지시문에 mass-ulw를 쓰라고 적습니다. 파일 하나 고침, 문서 한 줄 같은 작은 작업에는 mass-ulw를 쓰지 않습니다. 같은 파일을 고치는 하위 작업은 같은 단계에서 함께 돌리지 않습니다. 이런 하위 작업은 각자 worktree를 쓰거나 순서대로 돌립니다. 하위 작업을 병렬로 돌려도 무거운 명령(전체 테스트, 뮤테이션 테스트, 빌드 등)은 그 프로젝트나 설치 규칙이 정한 동시 실행 상한을 지킵니다. 규칙 8의 정리와 규칙 15의 감시는 하위 작업에도 적용합니다. 사용자가 질문만 하면 진행 중인 작업을 mass-ulw로 바꾸지 않습니다(규칙 4).
+17. 모든 사용자용 글(main 답변, 작업 보고, 프리코멘트, 확인함 질문)에 ASD-STE100의 명확한 기술 글쓰기 원칙을 적용합니다.
+   - 사용자가 요청하거나 설정한 언어로 씁니다. 특정 언어를 강제하거나 영어 통제 어휘를 다른 언어에 그대로 적용하지 않습니다.
+   - 짧은 능동문을 씁니다. 한 문장에는 하나의 핵심 사실이나 행동을 담습니다. 수행 주체, 작업 대상, 행동을 명확히 씁니다.
+   - 같은 대상에는 같은 명칭을 씁니다. 필요한 전문 용어와 약어는 처음에 뜻을 설명합니다. 불필요한 표현은 줄이되 대상, 조건, 결과를 이해하는 데 필요한 정보는 남깁니다.
+   - 절차는 실행 순서대로 씁니다. 각 단계에는 행동 하나를 적습니다. 필요한 선행 조건은 해당 행동 앞에 적습니다.
+   - 결과와 계획을 구분합니다. 상태 보고는 완료된 일, 미완료된 일과 차단 원인, 다음 행동을 구분해 씁니다. 확인된 사실과 추정을 나누고 근거 없는 확신을 쓰지 않습니다. "승인", "검증", "반영", "배포"만 단독으로 쓰지 말고 누가 무엇을 허가하거나 확인하거나 바꾸었는지 명시합니다.

package/assets/android/zigmini.apk.json

@@ -1,5 +1,5 @@
 {
-  "versionCode": 25,
-  "versionName": "0.8.0-beta.6",
-  "sha256": "4fc49f125efaa2ae1118d4724b7a2370c7d1c80227f9228858266eea64678155"
+  "versionCode": 27,
+  "versionName": "0.9.0-beta.1",
+  "sha256": "9c7e1137669ff0dc05c2bd6bab78056b54e31fc622eab0b3bf5c6815d3c21a61"
 }

package/assets/build.json

@@ -1 +1 @@
-{"commit":"46f57dd257c4451fbc4f2d9f4022501e20798032"}
+{"commit":"0109d29906dd908fce5cd3ba0c02eecbe33283b1"}

package/docs/manual.ko.md

@@ -57,6 +57,16 @@ Shift+Enter는 줄을 바꿉니다. 한글 조합 중에 누른 Enter는 메시
 
 에이전트가 일하는 동안 "중단" 버튼이 보입니다. 이 버튼을 누르면 진행 중인 작업을 멈춥니다.
 
+#### 대화 요약
+
+압축은 같은 세션을 계속 쓰기 위해 오래된 대화 내용을 요약하는 작업입니다. 요약이 작업을 막으면 채팅에 요청별 시작 안내 한 개와 완료·취소·실패 안내 한 개가 나타납니다. 백그라운드 준비만으로는 채팅 안내를 추가하지 않습니다. 세션이 유휴 상태일 때 준비된 요약을 적용하는 경우에도 기다리라고 안내하지 않으므로 채팅 안내를 추가하지 않습니다. 직접 실행한 요약은 시작 안내와 종료 안내를 그대로 표시합니다. 재접속하면 저장된 안내를 다시 표시합니다. 요약을 새로 요청하지는 않습니다.
+
+새 필수 설정은 없습니다. `compaction.model`이 없거나 `"auto"`이면 엔진은 현재 세션의 제공자 안에서 입력을 수용할 수 있는 요약 모델을 고릅니다. 기존 `provider/model` 직접 설정은 유지합니다. 다른 제공자의 모델을 직접 지정하면 요약 대상 대화를 그 제공자로 전송합니다. 직접 지정한 모델이 잘못되었거나 사용할 수 없어도 엔진이 몰래 다른 모델로 바꾸지 않습니다. 기존 전역·신뢰한 프로젝트·실행 중 설정의 우선순위는 유지합니다.
+
+요약에 실패하면 엔진은 이전 작업 문맥을 유지하고 멈춥니다. 비상 축약본을 대신 적용하지 않습니다. 안내에 따라 모델 설정을 확인하거나 요약 제공자에 다시 로그인해 주세요. 사용 한도가 복구되기를 기다리거나 계정·조직 권한을 확인해야 할 수도 있습니다. 다른 실패도 원인을 해결한 뒤 계속할 지시를 보내거나 명시적으로 다시 시도해 주세요. 게이트웨이는 이전 입력을 다시 보내거나 새 세션을 시작하지 않습니다. 취소는 실패와 구분해서 표시합니다. 정상 요약도 모든 세부 정보의 보존을 보증하지 않습니다. 계속할 때 중요한 조건을 확인해 주세요.
+
+게이트웨이는 메인과 작업 세션을 엔진의 기존 앱 모드로 엽니다. 그래서 응답은 터미널이 아니라 채팅 화면에 맞춰집니다. 바꿀 설정은 없습니다. 앱 모드는 모든 모델 응답이 유효한 JSON 같은 요청 형식을 지킨다고 보장하지 않으며, 위의 요약 실패 복구도 바꾸지 않습니다.
+
 새 대화를 만들려면 사이드바의 + 버튼을 누릅니다. 대화 이름을 묻는 창이 뜹니다.
 
 #### 슬래시 명령 메뉴
@@ -82,6 +92,44 @@ README의 '명령' 절에 따르면 채팅에서 `/usage`를 보내면 게이트
 
 ### 2.3 첨부와 참조
 
+#### 흐름도와 구조도
+
+웹과 Android 채팅은 완성된 `zigmini-diagram` 코드 블록을 도식으로 표시합니다.
+좁은 화면에서도 글자를 줄이지 않습니다. 도식 안을 스크롤하면 화면 밖의 노드를 볼 수 있습니다.
+원문 표시를 열면 원래 JSON을 선택하고 복사할 수 있습니다.
+메시지를 참조하면 이미지나 로컬 경로가 아니라 원래 본문을 전달합니다.
+기록 조회와 재연결도 같은 저장 본문을 사용합니다. 업로드나 외부 렌더러는 필요하지 않습니다.
+
+에이전트는 답변 본문에 아래처럼 완성된 블록을 넣습니다.
+
+````markdown
+```zigmini-diagram
+{"version":1,"title":"요청 흐름","nodes":[{"id":"request","label":"요청"},{"id":"gateway","label":"게이트웨이"},{"id":"reply","label":"답변"}],"edges":[{"from":"request","to":"gateway"},{"from":"gateway","to":"reply"}]}
+```
+````
+
+지원 형식은 순환 없는 작은 방향 그래프입니다. Mermaid나 임의 SVG·HTML은 지원하지 않습니다.
+갈라지는 연결로 구조를 표현할 수 있습니다.
+노드는 위에서 아래로 배치합니다. 같은 깊이의 노드는 입력 순서로 배치합니다.
+
+- 최상위 필수 키는 `version: 1`, `nodes`, `edges`입니다. `title`은 선택 항목입니다.
+- 노드에는 `id`와 `label`만 넣습니다. 노드는 1~16개입니다.
+  ID는 서로 달라야 하며 `[A-Za-z][A-Za-z0-9_-]{0,31}` 형식을 사용합니다.
+  이름은 공백만이 아닌 일반 텍스트로 쓰며 유니코드 코드 포인트 48개까지입니다.
+- 연결에는 기존 노드의 ID인 `from`과 `to`만 넣습니다. 연결은 0~24개입니다.
+  중복 연결, 자기 자신으로의 연결, 순환은 지원하지 않습니다.
+- 선택 제목은 공백만이 아닌 일반 텍스트로 쓰며 유니코드 코드 포인트 80개까지입니다.
+  제목과 이름에는 제어 문자 U+0000~U+001F와 U+007F를 넣을 수 없습니다.
+- JSON은 UTF-16 코드 단위 16,384개까지입니다. 다른 키는 지원하지 않습니다.
+  들여쓰기 없는 백틱 세 개와 위 예시의 정확한 언어 이름을 사용합니다.
+
+미완성·잘못된 형식·미지원 블록은 원문으로 표시합니다.
+스트리밍 중 블록이 완성되고 형식이 맞으면 도식으로 표시할 수 있습니다.
+도식 내용은 스크립트 실행, URL 로드, 파일 읽기를 할 수 없습니다.
+이 기능이 없는 이전 클라이언트는 코드 블록으로 표시합니다.
+짧은 매 요청 규칙은 흐름이나 구조 설명에 도움이 될 때만 도식을 사용하도록 안내합니다.
+모든 답변에 도식을 요구하지 않습니다.
+
 #### 이미지
 
 - "이미지" 버튼을 눌러 이미지를 고릅니다.
@@ -163,6 +211,20 @@ README의 '명령' 절에 따르면 채팅에서 `/usage`를 보내면 게이트
 
 이름 입력란에서 Enter는 저장하고 Esc는 취소합니다. 입력란을 벗어나도 저장합니다. 이름은 게이트웨이에 저장됩니다. 저장에 실패하면 이 브라우저에만 바뀐 이름이 보입니다.
 
+#### 보안검사
+
+- "보안검사 켜짐/꺼짐"은 보내는 메시지의 검사를 켜고 끕니다. 기본은 켜짐이고 게이트웨이가 설정을 기억합니다.
+- 메시지나 확인함 답에 허용하지 않은 값이 탐지되면 게이트웨이가 에이전트에 보내기 전에 보류합니다. 확인함과 채팅에는 같은 보안 항목이 보입니다. 항목은 기억할 전체 값과 종류를 보여 줍니다.
+- 보내기를 선택하면 원래 메시지를 전송하고 표시한 정확한 값을 이 게이트웨이에 기억합니다. 다음부터 같은 값은 다시 묻지 않습니다. 다른 값은 계속 확인합니다. 이미 보류한 메시지를 자동으로 보내지는 않습니다.
+- 취소는 이번 전송만 중단합니다. 기존 작업은 중단하지 않습니다. 보류한 내용이 확인함 답이면 원래 질문은 답하지 않은 상태로 남고 답변 입력란도 유지합니다.
+- 웹은 같은 대화의 입력창이 비어 있을 때만 취소한 메시지의 글을 되돌립니다. 새로 작성한 초안은 바꾸지 않습니다. Android는 취소한 메시지를 입력창에 되돌리지 않습니다. 전송 결과가 미확인이면 자동 복구하거나 다시 보내지 않습니다.
+- 요청을 처리하는 동안 선택 버튼을 잠급니다. HTTP 응답, 실시간 이벤트, 재연결 결과로 같은 항목을 갱신합니다. 미확인은 전달을 확인하지 못했다는 뜻입니다. 다시 보내지 말고 상태 확인을 사용합니다.
+- 값을 기억한 뒤 전송합니다. 저장에 실패하면 보내지 않습니다. 저장한 뒤 전송에 실패하거나 결과를 확인하지 못하면 값은 기억된 상태로 남습니다. 결과는 기억 여부와 전송 상태를 따로 알립니다.
+- 허용 목록은 이 설치에만 비공개로 저장하며 게이트웨이를 다시 시작해도 유지합니다. 웹 설정의 보안검사 구역에서 목록을 봅니다. Android는 매뉴얼 버튼이 있는 게이트웨이 설정 화면에서 허용 값 목록을 엽니다.
+- 항목마다 전체 값, 종류, 승인 시각, 승인한 클라이언트를 보여 줍니다. 개별 삭제나 전체 삭제를 하면 다음 전송부터 해당 값을 다시 검사합니다. 삭제는 이미 승인한 전송을 취소하거나 보낸 메시지를 지우지 않습니다.
+- 구형 앱의 보내기는 한 번만 전송하며 값을 기억하지 않습니다. 값을 기억하려면 새 화면의 전송·기억 선택이 필요합니다. 미승인 원문은 일반 질문 기록이나 대화 이력에 저장하지 않습니다. 게이트웨이를 다시 시작하면 보류 원문은 사라집니다.
+- 이 목록은 메시지와 답변의 전송 검사에만 적용합니다. 저장소와 릴리스 보안검사는 바꾸지 않습니다.
+
 #### 업데이트
 
 - "지금 버전"과 "새 버전"이 보입니다.
@@ -312,7 +374,13 @@ Ctrl 단축키는 Cmd, Alt, Shift와 함께 누르면 동작하지 않습니다.
 ### 4.6 알림
 
 - 등록한 게이트웨이마다 알림 연결이 하나씩 있습니다.
-- 알림 채널은 "일정 알림", "확인 요청", "연결 유지"입니다.
+- 웹 설정에서 앱 알림 수준을 고릅니다. 앱에서는 헤더의 상태 태그를 짧게 눌러 기존 설정창을 엽니다. 두 선택기는 매뉴얼 위에 있으며 작업 상태 화면에는 없습니다.
+- "확인함 알림만"이 기본값입니다. 기존 확인 요청 알림을 유지합니다.
+- "모든 답장 알림"은 확인 요청 알림과 main·작업 에이전트의 개별 완성 답장을 알립니다. 사용자 메시지와 스트리밍 조각은 알리지 않습니다.
+- 두 화면은 같은 게이트웨이 저장값을 바꿉니다. 앱은 현재 게이트웨이만 바꿉니다. 설정을 바꿔도 과거 답장을 다시 알리지 않습니다.
+- 저장에 실패하면 마지막으로 확인된 선택을 유지합니다. "다시 시도"는 저장값을 다시 읽습니다. 읽기가 끝나면 원하는 항목을 다시 고릅니다.
+- 일정과 명시적 알림은 이 선택과 별개입니다. 확인 요청 알림의 기존 웹 화면 표시 여부 규칙도 유지합니다.
+- 답장 알림을 누르면 보낸 게이트웨이의 채팅을 엽니다. 같은 답장을 재전송해도 다시 알리지 않습니다.
 - 알림은 소리 없이 진동만 합니다.
 - 알림을 누르면 그 알림을 보낸 게이트웨이로 바꿉니다.
 - 연결 유지 알림에는 게이트웨이마다 연결 상태가 보입니다. "인증 거부, 다시 등록하세요"가 보이면 폰을 다시 등록합니다.