zigmini 0.8.0-beta.3 → 0.8.0-beta.4

package/docs/manual.ko.md

@@ -0,0 +1,382 @@
+[English](manual.md) | 한국어
+
+# zigmini 사용 설명서
+
+## 1. 소개
+
+zigmini는 맥에서 도는 개인 AI 에이전트 게이트웨이입니다. 사용자는 에이전트와 대화하고, 작업을 맡기고, 알림을 받습니다. 기본 에이전트의 이름은 "지그"입니다. 이 이름은 프로필에서 바꿀 수 있습니다.
+
+zigmini는 화면 두 개를 제공합니다.
+
+| 화면 | 설명 |
+| --- | --- |
+| 웹 화면 | 맥의 브라우저에서 엽니다. 대화, 확인함, 작업 상태, 설정을 모두 씁니다. |
+| Android 앱 | 폰에서 씁니다. 대화, 확인함, 작업 상태, 알림을 씁니다. 먼저 폰을 게이트웨이에 등록해야 합니다. |
+
+## 2. 웹 화면
+
+### 2.1 화면 구성
+
+웹 화면은 세 부분으로 나뉩니다.
+
+- 왼쪽 사이드바: 대화 목록, 새 대화 버튼(+), 작업 상태 영역, 내 프로필, 에이전트 프로필이 있습니다. 사이드바 맨 위의 "omo" 배지는 에이전트 엔진 연결 상태를 보여 줍니다.
+- 가운데 채팅: 헤더, 메시지 목록, 입력창이 있습니다.
+- 오른쪽 패널: 확인함, 설정, 이벤트 패널이 열립니다.
+
+헤더에는 아래 항목이 있습니다.
+
+| 항목 | 동작 |
+| --- | --- |
+| 지그 얼굴 버튼 | 작업 상태를 봅니다. 폰 너비에서는 작업 상태 화면으로 바꿉니다. |
+| 모델 선택 | 에이전트가 쓸 모델을 고릅니다. 바로 바꿀 수 없으면 다음 메시지를 보낼 때 대화를 압축한 뒤 바꿉니다. |
+| 새 세션 | 이 대화의 에이전트 세션을 새로 시작합니다. 확인 창이 먼저 뜹니다. 화면의 기록은 그대로 남고, 최근 대화 일부를 새 세션에 넘깁니다. |
+| 음성 켜짐 / 음성 꺼짐 | 게이트웨이의 음성 서버를 켜고 끕니다. 끄면 마이크, 호출어, 박수 감지, 음성 답변을 쓸 수 없습니다. |
+| 음성 설치 | 음성 서버가 설치되지 않은 npm 설치에서만 보입니다. 누르면 음성 서버를 내려받아 설치합니다. |
+| 박수 감지 | 박수를 두 번 치면 호출어 대기를 켜고 끕니다. |
+| 호출어 | "헤이 지그"를 들으면 받아 적어 입력창에 채웁니다. |
+| 음성 답변 | 답변을 음성으로 읽습니다. |
+| 확인함 | 답을 기다리는 질문과 승인 요청을 엽니다. 배지에 확인이 필요한 개수가 보입니다. |
+| 이벤트 | 이벤트 패널을 엽니다. 패널의 "지우기"는 표시된 이벤트를 지웁니다. |
+| 설정 | 설정 창을 엽니다. |
+
+헤더에는 상황에 따라 안내 줄도 나타납니다.
+
+- "모델 계정에 로그인하세요": 모델 계정에 로그인하지 않은 상태입니다.
+- 스키마 안내: 에이전트 엔진의 데이터 형식이 게이트웨이보다 새로울 때 나타납니다.
+- 새 버전 안내: 누르면 설정의 업데이트 영역이 열립니다.
+- "세션 교체 중": 세션을 바꾸는 동안 보입니다. 이때는 메시지를 보낼 수 없습니다.
+
+메시지 목록 오른쪽의 ▲ 버튼은 이전 내 메시지로 이동합니다. ▼ 버튼은 다음 내 메시지로 이동합니다. ▼ 버튼을 두 번 누르면 맨 아래로 이동합니다.
+
+### 2.2 대화
+
+1. 입력창에 메시지를 씁니다.
+2. Enter를 누르거나 "전송" 버튼을 누릅니다.
+
+Shift+Enter는 줄을 바꿉니다. 한글 조합 중에 누른 Enter는 메시지를 보내지 않습니다.
+
+에이전트가 일하는 동안 "중단" 버튼이 보입니다. 이 버튼을 누르면 진행 중인 작업을 멈춥니다.
+
+새 대화를 만들려면 사이드바의 + 버튼을 누릅니다. 대화 이름을 묻는 창이 뜹니다.
+
+#### 슬래시 명령 메뉴
+
+입력창에 `/`를 쓰면 명령과 스킬 메뉴가 열립니다. 이어서 쓴 글자로 목록을 좁힙니다. 메뉴에는 스킬, 명령, 템플릿, 웹 지그 명령이 있습니다.
+
+웹 지그 명령은 아래와 같습니다.
+
+| 명령 | 동작 |
+| --- | --- |
+| `/tts on`, `/tts off` | 음성 답변을 켜고 끕니다. |
+| `/wake on`, `/wake off` | 호출어 대기를 켜고 끕니다. |
+| `/clap on`, `/clap off` | 박수 감지를 켜고 끕니다. |
+| `/voice on`, `/voice off` | 음성 기능(음성 서버)을 켜고 끕니다. |
+| `/옵션` | 음성 기능, 음성 답변, 호출어, 박수 감지 상태를 보여 줍니다. |
+| `/read` | 마지막 답변 전체를 음성으로 읽습니다. |
+| `/기기` | 등록된 기기 목록을 보여 줍니다. 맥에서만 됩니다. |
+| `/기기 삭제 <번호>` | 그 번호의 등록된 기기를 삭제합니다. 맥에서만 됩니다. |
+
+음성 기능이 꺼져 있으면 음성 명령은 메뉴에 보이지 않습니다. 직접 입력해도 "음성 기능이 꺼져 있습니다"라고 답합니다.
+
+README의 '명령' 절에 따르면 채팅에서 `/usage`를 보내면 게이트웨이가 모델 계정의 사용량을 답합니다.
+
+### 2.3 첨부와 참조
+
+#### 이미지
+
+- "이미지" 버튼을 눌러 이미지를 고릅니다.
+- 입력창에 이미지를 붙여 넣을 수 있습니다.
+- 메시지 목록이나 입력 영역에 이미지 파일을 끌어 놓을 수 있습니다.
+
+한 번에 4장까지 보낼 수 있습니다. PNG, JPEG, GIF, WebP를 씁니다. 이미지는 전송할 때 올라갑니다.
+
+#### 이전 메시지 참조
+
+메시지를 마우스 오른쪽 버튼으로 누르면 그 메시지가 참조 태그로 입력창 위에 붙습니다. 메시지의 "참조" 버튼도 같은 일을 합니다. 참조는 한 번에 4개까지 넣을 수 있습니다. 참조한 메시지의 이미지와 새 첨부 이미지를 합쳐 4장까지만 보낼 수 있습니다. 참조 태그를 빼려면 태그의 버튼을 누르거나, 태그에 초점을 두고 Delete 또는 Backspace를 누릅니다.
+
+#### 쪽지
+
+"쪽지" 버튼은 쪽지 창을 열고 닫습니다. 쪽지에는 자주 쓰는 프롬프트나 메모를 적습니다. 쪽지는 자동 저장됩니다. "이미지 보관"으로 이미지를 2장까지 보관할 수 있습니다.
+
+#### 자동 복사
+
+메시지 목록에서 마우스로 글을 고르면 고른 글이 바로 복사됩니다. "복사했습니다" 안내가 잠깐 보입니다. 입력창 안에서 고른 글은 자동으로 복사하지 않습니다.
+
+### 2.4 마지막으로 보낸 메시지 줄
+
+헤더 아래 한 줄에 이 대화에서 마지막으로 보낸 메시지가 보입니다. 이미지나 참조가 있으면 개수도 보입니다. 이 줄을 누르면 전체 내용을 펼칩니다. 다시 누르면 접습니다.
+
+### 2.5 보낸 메시지 다시 불러오기
+
+입력창에서 위쪽 화살표를 누르면 이전에 보낸 메시지를 불러옵니다. 아래쪽 화살표는 더 최근 메시지로 돌아갑니다. 맨 끝까지 내려가면 쓰고 있던 글이 돌아옵니다.
+
+아래 조건에서만 동작합니다.
+
+- 위쪽 화살표는 커서가 첫 줄에 있을 때만 동작합니다.
+- 아래쪽 화살표는 불러오기 중이고 커서가 마지막 줄에 있을 때만 동작합니다.
+- Ctrl, Cmd, Alt, Shift를 함께 누르면 동작하지 않습니다.
+- 글을 선택한 상태나 한글 조합 중에는 동작하지 않습니다.
+- 슬래시 메뉴가 열려 있으면 화살표는 메뉴를 움직입니다.
+
+### 2.6 확인함
+
+확인함은 에이전트가 사용자에게 묻는 질문과 승인 요청을 모읍니다. 헤더의 "확인함" 버튼이나 Ctrl+C로 엽니다. 배지 숫자는 확인이 필요한 항목 수입니다.
+
+항목마다 아래 버튼이 상황에 따라 보입니다.
+
+| 버튼 | 동작 |
+| --- | --- |
+| 답변 보내기 등 기본 버튼 | 고른 답을 보냅니다. |
+| 다시 보내기 | 전달 여부가 불확실한 답을 같은 내용으로 다시 보냅니다. |
+| 현재 상황 확인 | 질문을 낸 작업의 지금 상황을 다시 확인합니다. |
+| 최신 내용 확인 | 질문이 바뀌었을 때 최신 내용을 확인하고 다시 답할 수 있게 합니다. |
+| 삭제 | 확인함에서 항목을 지웁니다. 확인 단계가 한 번 더 나옵니다. "그대로 두기"는 지우지 않습니다. |
+| 원문 보기 | 채팅의 원래 질문 카드로 이동합니다. |
+
+"대화 맥락"을 펼치면 질문과 관련된 대화가 보입니다. 아직 답을 기다리는 질문을 지우면, 질문을 낸 작업에 취소가 전달됩니다. 목록이 길면 "더 보기"를 누릅니다.
+
+채팅 안의 질문 카드에서도 같은 질문에 답할 수 있습니다. 두 곳은 같은 상태를 보여 줍니다.
+
+### 2.7 작업 상태 화면
+
+작업 상태 영역은 사이드바에 있습니다. 가운데에 지그가 있고, 맡긴 작업이 칸으로 보입니다. 칸마다 작업 제목, 상태, 시간이 보입니다. 비어 있는 칸에는 "빈 칸"이 보입니다.
+
+- 끝난 작업의 칸을 누르면 그 칸을 비웁니다. 키보드로는 칸에 초점을 두고 Enter나 Space를 누릅니다.
+- 접기 버튼은 작업 상태 영역을 숨기고 다시 보입니다.
+- 게이트웨이가 칸을 관리하므로, 웹과 앱은 같은 작업 상태를 보여 줍니다.
+
+폰 너비 화면에서는 사이드바가 숨겨집니다. 이때 헤더의 지그 얼굴 버튼을 누르면 작업 상태만 보이는 화면으로 바뀝니다. 왼쪽 위 버튼, 브라우저의 뒤로 가기, Esc는 채팅으로 돌아갑니다.
+
+### 2.8 설정
+
+헤더의 "설정" 버튼으로 엽니다. Esc, 닫기 버튼(×), 창 바깥 누르기로 닫습니다.
+
+#### 프로필
+
+프로필은 사이드바 아래에 있습니다.
+
+| 대상 | 방법 | 규칙 |
+| --- | --- | --- |
+| 내 닉네임 | 내 프로필을 두 번 누릅니다. | 20자까지입니다. 비우면 "나"가 됩니다. |
+| 에이전트 이름 | 에이전트 프로필을 두 번 누릅니다. | 한글 10자, 영문 20자까지입니다. 너무 길면 바꾸지 않습니다. 비우면 "지그"가 됩니다. |
+| 에이전트 아이콘 | 에이전트 아이콘을 두 번 누릅니다. | PNG, JPEG, WebP, 1MB 이하입니다. 가운데를 정사각형으로 자릅니다. 기본 아이콘으로 되돌릴 수 있습니다. |
+
+이름 입력란에서 Enter는 저장하고 Esc는 취소합니다. 입력란을 벗어나도 저장합니다. 이름은 게이트웨이에 저장됩니다. 저장에 실패하면 이 브라우저에만 바뀐 이름이 보입니다.
+
+#### 업데이트
+
+- "지금 버전"과 "새 버전"이 보입니다.
+- "지금 확인"은 새 버전을 바로 찾습니다. 실패하면 이유와 함께 다시 시도하라는 안내가 보입니다.
+- "변경 내용 보기"는 새 버전이 있을 때 보입니다.
+- "업데이트" 버튼은 새 버전이 있고 npm으로 설치한 경우에만 보입니다. 저장소에서 배포한 설치에는 보이지 않습니다.
+
+"업데이트" 버튼은 아래 경우에 막히거나 추가 확인을 묻습니다.
+
+| 조건 | 화면 |
+| --- | --- |
+| 확인함에 답을 기다리는 질문이 있음 | 버튼이 꺼집니다. "답을 기다리는 질문이 N개 있습니다" 안내와 "확인함 열기" 버튼이 보입니다. 질문에 답한 뒤 업데이트할 수 있습니다. |
+| 권한 안내가 바뀜 | 새 안내문이 보입니다. 입력란에 동의를 입력해야 진행합니다. |
+| 공유 데이터 형식 변경 | 변경 내용을 보여 주고 확인을 받습니다. |
+| 진행 중인 작업이 있음 | 게이트웨이가 바쁘다는 안내가 보입니다. |
+
+업데이트하면 게이트웨이와 브리지가 다시 시작됩니다. 그동안 연결과 진행 중인 대화가 잠시 끊길 수 있습니다. 진행 상황이 영역 아래에 보입니다. 끝나면 페이지를 새로 고칩니다.
+
+#### 기기 등록
+
+- 폰 등록 QR이 보입니다. QR 하나는 10분 동안 한 번만 쓸 수 있습니다.
+- QR이 만료되면 "새로 만들기"를 누릅니다.
+- "등록된 기기" 목록에 기기 이름, 모델, 마지막 접속 시간이 보입니다.
+- 기기를 지우려면 "등록 취소"를 누르고, "다시 누르면 취소"가 보일 때 한 번 더 누릅니다.
+
+폰이 등록을 요청하면 채팅 위에 요청 줄이 나타납니다. 줄에는 기기 이름과 확인 번호가 있습니다. 폰에 보이는 번호와 같은지 확인한 뒤 "승인"을 누릅니다. 30초 안에 승인하지 않으면 자동으로 거절됩니다. 거절이나 만료가 반복되면 등록이 잠깁니다. 이때는 "잠금 해제"를 누릅니다.
+
+#### 외부 접속
+
+폰이 게이트웨이에 접속하는 방식을 고릅니다.
+
+| 선택 | 의미 |
+| --- | --- |
+| 집 Wi-Fi만 | 같은 Wi-Fi에서만 접속합니다. |
+| Tailscale | 맥과 폰에 Tailscale을 설치하고 같은 계정으로 로그인합니다. |
+| 자기 도메인(https) | 사용자의 https 주소를 입력합니다. |
+
+고른 뒤 "바꾸기"를 누릅니다.
+
+#### 앱 내려받기
+
+Android 앱(APK)을 받는 QR이 보입니다. 폰 카메라로 QR을 찍어 APK를 받고 설치합니다. 출처를 알 수 없는 앱 설치 허가가 필요합니다. QR이 만료되면 "새로 만들기"를 누릅니다.
+
+#### 정리
+
+게이트웨이가 지워도 되는 후보를 보여 줍니다. 후보는 DB 백업, OMO 버전 폴더, 업데이트 남은 파일, 임시 폴더, 이전 RPC 데몬입니다. 지울 항목을 고르고 "선택한 항목 정리"를 누릅니다.
+
+#### 음성 설정
+
+음성 설정은 설정 창이 아니라 헤더 버튼에 있습니다. 2.1의 표와 2.9를 보세요.
+
+### 2.9 웹의 음성 기능
+
+음성 기능은 "음성 켜짐"일 때만 씁니다.
+
+- 마이크: "마이크" 버튼을 누르고 말합니다. 다시 누르면 보냅니다.
+- 음성 답변: 켜면 답변을 음성으로 읽습니다.
+- 호출어: 켜면 "헤이 지그"를 기다립니다. 뒤에 한 말을 입력창에 채우고, 몇 초 뒤 자동으로 보냅니다. 전송 버튼에 남은 초가 보입니다. Esc를 누르거나 입력창을 고치면 자동 전송을 취소합니다.
+- "헤이 헤이 헤이": 하던 작업을 멈추고 다음 말을 기다립니다.
+- "귀 닫아": 호출어 대기를 끕니다.
+- 박수 감지: 켜면 박수 두 번으로 호출어 대기를 켜고 끕니다.
+
+### 2.10 매뉴얼 보기
+
+- 웹: 설정 창 위쪽의 "매뉴얼" 버튼을 누릅니다. 한국어 판이 먼저 보입니다. "English" 버튼이나 문서 첫 줄의 링크는 영어 판으로 바꿉니다. Esc, 닫기 버튼(×), 창 바깥 누르기로 닫습니다.
+- 앱: 헤더의 상태 태그(예: "작업 상태 확인 중")를 짧게 눌러 게이트웨이 연결 화면을 엽니다. 그 화면의 "매뉴얼" 버튼을 누릅니다. "English" 버튼은 영어 판으로 바꿉니다. "닫기"나 뒤로 가기는 연결 화면으로 돌아갑니다.
+- 게이트웨이가 매뉴얼을 주지 않으면 "이 게이트웨이 버전에는 매뉴얼이 없습니다" 안내가 보입니다. 게이트웨이를 업데이트하면 볼 수 있습니다.
+
+## 3. 키보드 단축키
+
+| 키 | 위치(어디서) | 동작 |
+| --- | --- | --- |
+| Ctrl+E | 화면 어디서나 | 이벤트 패널을 열고 닫습니다. |
+| Ctrl+C | 화면 어디서나, 선택한 글이 없을 때 | 확인함을 열고 닫습니다. 글을 선택했으면 평소처럼 복사합니다. |
+| Enter | 입력창 | 메시지를 보냅니다. 한글 조합 중에는 보내지 않습니다. |
+| Shift+Enter | 입력창 | 줄을 바꿉니다. |
+| Esc | 입력창 | 호출어 자동 전송을 취소합니다. |
+| 위쪽 화살표 | 입력창 첫 줄 | 이전에 보낸 메시지를 불러옵니다. |
+| 아래쪽 화살표 | 입력창 마지막 줄, 불러오기 중 | 더 최근 메시지나 쓰던 글로 돌아갑니다. |
+| 위쪽/아래쪽 화살표 | 슬래시 메뉴 | 항목을 옮깁니다. |
+| Tab, Enter | 슬래시 메뉴 | 고른 항목을 입력창에 넣습니다. |
+| Esc | 슬래시 메뉴 | 메뉴를 닫습니다. |
+| Enter, Space | 마지막으로 보낸 메시지 줄 | 줄을 펼치고 접습니다. |
+| Delete, Backspace | 참조 태그 | 참조를 뺍니다. |
+| Enter, Space | 작업 상태의 끝난 작업 칸 | 칸을 비웁니다. |
+| Esc | 작업 상태 화면(폰 너비) | 채팅으로 돌아갑니다. |
+| Esc | 확인함 | 확인함을 닫습니다. |
+| Tab, Shift+Tab | 확인함 | 초점이 확인함 안에서만 돕니다. |
+| Esc | 설정 | 설정을 닫습니다. |
+| Tab, Shift+Tab | 설정 | 초점이 설정 안에서만 돕니다. |
+| Esc | 매뉴얼 | 매뉴얼을 닫고 설정으로 돌아갑니다. |
+| Tab, Shift+Tab | 매뉴얼 | 초점이 매뉴얼 안에서만 돕니다. |
+| Enter | 닉네임, 에이전트 이름 입력란 | 저장합니다. |
+| Esc | 닉네임, 에이전트 이름 입력란 | 바꾸지 않고 닫습니다. |
+| Esc | 에이전트 아이콘 편집 창 | 바꾸지 않고 닫습니다. |
+
+Ctrl 단축키는 Cmd, Alt, Shift와 함께 누르면 동작하지 않습니다. 한글 자판에서도 같은 키 위치로 동작합니다.
+
+## 4. Android 앱
+
+### 4.1 연결
+
+앱 헤더 왼쪽에 지그 얼굴과 상태 태그가 있습니다. 상태 태그에는 "게이트웨이 재연결 중", "omo 끊김", "omo 연결됨", "작업 상태 확인 중" 중 하나가 보입니다.
+
+| 조작 | 동작 |
+| --- | --- |
+| 지그 얼굴 누르기 | 채팅과 작업 상태 화면을 오갑니다. |
+| 상태 태그 짧게 누르기 | 게이트웨이 연결 화면을 엽니다. 이 화면에 앱 버전, 게이트웨이 버전, "매뉴얼" 버튼이 있습니다. |
+| 상태 태그 길게 누르기 | 앱 버전 창을 엽니다. |
+
+게이트웨이 연결 화면에서는 등록된 게이트웨이를 관리합니다.
+
+- "선택"은 그 게이트웨이로 바꿉니다. 지금 쓰는 게이트웨이에는 "사용 중"이 보입니다.
+- "삭제"를 누른 뒤 "삭제 확인"을 누르면 폰에서 그 게이트웨이를 지웁니다.
+
+### 4.2 기기 등록
+
+등록 방법은 두 가지입니다.
+
+1. "QR로 등록"을 누르고 웹 설정의 기기 등록 QR을 찍습니다.
+2. 또는 게이트웨이 주소와 등록 토큰을 붙여 넣고 "등록"을 누릅니다.
+
+그 다음 맥의 웹 화면에 뜬 요청을 30초 안에 승인합니다. 폰과 맥의 번호가 같은지 확인합니다.
+
+### 4.3 확인함
+
+헤더의 확인함 아이콘으로 엽니다. 위에 "확인 필요"와 "전달 중" 개수가 보입니다. 필수 질문에는 "필수" 태그가 붙습니다. 필수 질문에 모두 답해야 보낼 수 있습니다.
+
+- 답을 고르고 보냅니다.
+- "삭제"는 확인 단계를 거쳐 항목을 지웁니다. 답을 기다리는 질문이면 버튼이 "질문 취소하고 삭제"로 바뀝니다.
+- "원문 보기"는 채팅의 질문 카드로 이동합니다.
+- 연결이 끊기면 목록은 마지막으로 받은 내용입니다. 답변은 다시 연결된 뒤에 보낼 수 있습니다.
+
+### 4.4 작업 상태 화면
+
+지그 얼굴을 누르면 열립니다. 작업 칸의 상태는 진행 중, 입력 대기, 대기 중, 하위 작업 대기, 응답 없음, 고장, 완료, 실패, 취소됨 등으로 보입니다.
+
+- 끝난 작업 칸을 누르면 칸을 비웁니다.
+- 칸을 길게 누르면 작업 이름을 보입니다.
+- "ID 복사"는 작업 ID를 복사합니다.
+
+### 4.5 업데이트와 내려받기
+
+- 게이트웨이 새 버전: 알림 줄이 보입니다. npm 설치면 "업데이트" 버튼이 있고, 누르면 확인 창이 뜹니다. 확인함에 답을 기다리는 질문이 있으면 버튼이 꺼지고 "확인함 열기"가 보입니다. ✕는 다음 연결 때까지 알림 줄을 숨깁니다.
+- 새 앱 버전: "새 앱 버전" 줄의 "내려받기"를 누르면 브라우저에서 APK를 받습니다. 출처를 알 수 없는 앱 설치 허가가 필요합니다.
+
+### 4.6 알림
+
+- 등록한 게이트웨이마다 알림 연결이 하나씩 있습니다.
+- 알림 채널은 "일정 알림", "확인 요청", "연결 유지"입니다.
+- 알림은 소리 없이 진동만 합니다.
+- 알림을 누르면 그 알림을 보낸 게이트웨이로 바꿉니다.
+- 연결 유지 알림에는 게이트웨이마다 연결 상태가 보입니다. "인증 거부, 다시 등록하세요"가 보이면 폰을 다시 등록합니다.
+
+### 4.7 메시지 복사와 참조
+
+- 메시지의 글을 길게 눌러 고르면 고른 글이 바로 복사됩니다. Android 13보다 낮은 버전에서는 "복사했습니다" 안내가 보입니다.
+- 메시지를 왼쪽으로 밀면 그 메시지를 참조로 붙입니다. 참조는 4개까지입니다.
+- 쪽지의 "복사" 버튼은 쪽지 글을 복사합니다.
+
+### 4.8 음성
+
+- 마이크 버튼을 누르고 말합니다. 다시 누르면 보냅니다. "취소"는 녹음을 버립니다.
+- 헤더의 스피커 아이콘은 음성 답변을 켜고 끕니다. 게이트웨이의 음성 기능이 꺼져 있으면 보이지 않습니다.
+- 음성 설치와 켜기, 끄기는 맥의 웹 화면에서 합니다.
+
+### 4.9 매뉴얼 버튼
+
+게이트웨이 연결 화면의 "매뉴얼" 버튼은 이 문서를 엽니다. 2.10의 '매뉴얼 보기'를 보세요.
+
+## 5. 공통
+
+### 5.1 지그에게 일 맡기기
+
+채팅으로 지그에게 일을 말합니다. 지그가 일을 따로 맡기면 작업 상태 화면에 칸이 생깁니다. 작업이 끝나면 칸을 눌러 비웁니다.
+
+### 5.2 질문과 승인
+
+1. 지그나 작업이 사용자에게 묻거나 승인을 요청합니다.
+2. 질문은 채팅의 카드와 확인함에 함께 나타납니다. 앱은 "확인 요청" 알림을 보냅니다.
+3. 사용자가 둘 중 한 곳에서 답합니다.
+4. 게이트웨이가 답을 질문을 낸 곳에 전달합니다.
+
+질문을 기다리는 동안에도 대화는 멈추지 않을 수 있습니다. 답이 전달됐는지 알 수 없으면 같은 답을 다시 보낼 수 있고, 한 번만 처리됩니다. 질문이 바뀌었으면 "최신 내용 확인" 뒤에 다시 답합니다.
+
+### 5.3 업데이트하는 방법
+
+- 웹: 설정의 "업데이트"를 누릅니다(2.8).
+- 맥 터미널: `zigmini update`를 실행합니다. 버전을 정하려면 `zigmini update <버전>`을 씁니다.
+
+### 5.4 자주 묻는 문제와 해결
+
+| 문제 | 해결 |
+| --- | --- |
+| 헤더에 "모델 계정에 로그인하세요"가 보입니다. | README의 설치 절에 나온 로그인 명령을 실행한 뒤 `/login`을 입력합니다. |
+| 헤더에 스키마 안내가 보입니다. | 에이전트 엔진이 게이트웨이보다 새 데이터 형식을 씁니다. 안내 줄의 내용을 따릅니다. |
+| 연결이 끊겼습니다. | 맥에서 `zigmini status`로 상태를 봅니다. `zigmini doctor`로 점검하고, `zigmini doctor --fix`로 이상 있는 항목만 다시 띄웁니다. |
+| "업데이트" 버튼이 꺼져 있습니다. | 확인함에 답을 기다리는 질문이 있습니다. "확인함 열기"를 눌러 먼저 답합니다. |
+| 게이트웨이가 시작하지 않고 권한 동의가 없다고 나옵니다. | 맥 터미널에서 `zigmini consent`를 실행합니다. |
+| 앱이 접속하지 못합니다. | 웹 설정의 "외부 접속"을 확인합니다. 방식을 고르지 않으면 폰은 접속할 수 없습니다. 앱에 "인증 거부"가 보이면 폰을 다시 등록합니다. |
+| 폰 등록이 잠겼습니다. | 웹 화면의 요청 줄에서 "잠금 해제"를 누릅니다. |
+
+## 6. CLI
+
+맥 터미널에서 쓰는 주요 명령입니다.
+
+- `zigmini setup`: 설치합니다.
+- `zigmini start`: 게이트웨이와 브리지를 시작합니다.
+- `zigmini stop`: 게이트웨이와 브리지를 멈춥니다. 진행 중인 작업도 멈춥니다.
+- `zigmini restart [gateway|bridge]`: 다시 시작합니다.
+- `zigmini status`: 상태를 보여 줍니다.
+- `zigmini doctor [--fix]`: 전체 상태를 점검합니다.
+- `zigmini pair [--apk]`: 폰 등록 QR이나 앱 내려받기 QR을 보여 줍니다.
+- `zigmini consent`: 권한 안내를 보이고 동의를 기록합니다.
+- `zigmini update [버전]`: 업데이트합니다.
+
+전체 목록은 README의 '명령' 절을 보세요.