zigmini 1.0.0-beta.3 → 1.1.0-beta.2

package/README.ko.md

@@ -19,6 +19,8 @@ zigmini는 에이전트를 권한 프리셋 `full-access`로 실행합니다.
 
 `zigmini setup`은 설치 전에 권한 안내문 전체를 보여 줍니다. `동의`를 정확히 입력해야만 설치합니다. 다른 입력이나 Enter는 동의 안 함이고, 그러면 아무것도 설치하지 않습니다. 동의를 건너뛰는 옵션은 없습니다. 안내문이 바뀌면 다시 동의할 때까지 게이트웨이가 시작하지 않습니다. 이때는 맥 터미널에서 `zigmini consent`를 실행합니다.
 
+등록 에이전트(웹에서 만드는 역할 대화)는 예외입니다. 등록 에이전트는 도구 권한 없이 시작하고, 확인함에서 허용한 뒤에만 도구를 씁니다. 권한은 에이전트 편집 화면의 **도구 권한**에서 회수할 때까지 유지됩니다. 게시, 전송, 구매, 삭제는 행위마다 다시 묻습니다. 코드와 셸 명령은 제한된 환경에서 실행하고, Aside 탭은 사용자가 고른 뒤에만 읽습니다. 이 기능에는 릴리스가 설치하는 엔진(`5.1.51-zgw.6`)이 필요하며, 지원하지 않는 엔진은 활성화 전에 거절됩니다. [사용 설명서](docs/manual.ko.md#도구-권한)의 도구 권한을 참고하세요.
+
 ## 설치
 
 1. Bun 버전을 확인합니다. zigmini에는 Bun `1.4.0` 이상이 필요합니다.
@@ -195,6 +197,31 @@ 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))은 웹 설정 창 위쪽의 "매뉴얼" 버튼과, 앱 헤더의 상태 태그를 짧게 눌러 여는 연결 화면의 "매뉴얼" 버튼으로 봅니다.
 
+## 게이트웨이 Mac의 파일 첨부
+
+웹이나 등록한 Android의 입력창에 `@`를 입력하거나 "Mac 파일"을 누르면 게이트웨이가 실행되는 Mac의 파일을 첨부할 수 있습니다. 브라우저를 켠 컴퓨터나 폰의 파일은 목록에 나오지 않습니다. 폴더나 기기를 따로 설정할 필요는 없습니다.
+
+- **형식과 한도:** HTML, Markdown, TXT, PDF를 지원합니다. 파일당 10 MiB, 메시지당 문서 4개까지입니다. 웹·폰 클라이언트별로 보내지 않은 파일을 16개, 64 MiB까지 둘 수 있습니다.
+- **사본:** 파일을 선택하면 바뀌지 않는 비공개 사본을 저장합니다. 선택한 뒤 원래 파일을 고쳐도 영향이 없습니다.
+- **권한:** 보내기를 해야 받는 대화의 에이전트만 전용 도구 `zgw_attachment_read`로 읽을 수 있습니다.
+- **PDF 전달 경로:** PDF 입력을 지원하는 공개 API 경로는 PDF를 받습니다. 구독 경로는 페이지 텍스트와 페이지 이미지를 받습니다. 텍스트 전용 모델은 페이지 텍스트와 Mac에서 수행한 OCR 결과를 받습니다.
+- **보존과 정리:** 원본은 내려받을 수 있게 보존합니다. 보낸 메시지에서 파일의 **회수**를 누르고 확인하면 이후의 읽기를 거절합니다. 모델이 이미 읽은 내용, 내려받은 파일, 그 파일로 만든 결과물은 지울 수 없습니다. 정리는 직접 요청할 때만 진행하며 파일을 macOS 휴지통으로 옮깁니다. 자동으로 삭제하는 일은 없습니다.
+- **Mac 접근 권한이 없다는 표시:** macOS 개인정보 보호 때문입니다(`host_access_denied`). 시스템 설정 > 개인정보 보호 및 보안에서 해당 위치를 직접 허용합니다. 게이트웨이는 시스템 설정을 바꾸지 않습니다.
+- **구버전:** 구형 게이트웨이는 Mac 파일 첨부를 지원하지 않는다고 표시합니다. 구형 앱은 보낸 파일을 `[Attached: 이름]` 글자로 표시합니다.
+
+자세한 내용은 [사용자 매뉴얼](docs/manual.ko.md)의 '이 Mac의 파일'을 보세요.
+
+## 1.1.0-beta.1의 새 기능
+
+1.1.0-beta.1(2026-11-12 KST, Android `versionCode` 33)은 엔진 빌드 `5.1.51-zgw.6`를 선택합니다. 전체 노트: [docs/releases/1.1.0-beta.1.ko.md](docs/releases/1.1.0-beta.1.ko.md).
+
+1.1.0-beta.2(2026-11-12 KST, Android `versionCode` 34)는 공통 에이전트 규칙만 바꾸는 핫픽스입니다. 노트: [docs/releases/1.1.0-beta.2.ko.md](docs/releases/1.1.0-beta.2.ko.md).
+
+- **이 Mac의 파일:** 게이트웨이 Mac의 파일을 대화에 첨부합니다(개선 293).
+- **도구 권한:** 등록 에이전트는 도구 권한 없이 시작하고, 확인함에서 허가합니다(개선 294).
+- **에이전트 협업:** main과 에이전트가 허용된 에이전트에게 요청하고 결과 파일을 받습니다.
+- **에이전트와 정리:** 지식 파일 영역, 초안, 첫 사용 안내, 설정의 "정리"가 바뀌었습니다.
+
 ## 1.0.0-beta.3의 새 기능
 
 1.0.0-beta.3(2026-11-04 KST, Android `versionCode` 32)은 엔진 빌드 `5.1.51-zgw.4`를 선택합니다. 전체 노트: [docs/releases/1.0.0-beta.3.ko.md](docs/releases/1.0.0-beta.3.ko.md).
@@ -214,7 +241,7 @@ 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
 
 1.0.0-beta.1(2026-11-02 KST, Android `versionCode` 30)은 1.0.0의 첫 후보입니다. 엔진 `5.1.51-zgw` 개정 3(OMO 5.1.51, 불변 빌드 `5.1.51-zgw.3`, senpi 2026.10.27-1, 대화 스키마 10)을 선택합니다. 전체 노트는 [docs/releases/1.0.0-beta.1.ko.md](docs/releases/1.0.0-beta.1.ko.md)에 있습니다.
 
-- **에이전트:** 웹에서 특화 대화를 만듭니다. 대화마다 세션, 모델, 지식 폴더가 따로 있습니다.
+- **에이전트:** 웹에서 특화 대화를 만듭니다. 대화마다 세션, 모델, 지식 폴더가 따로 있습니다. 만드는 동안 게이트웨이에 임시 저장됩니다. 여러 파일을 한 번에 올리면 새 세션 없이 바로 쓰고, 에이전트가 `outputs/`에 쓴 결과물을 내려받고, 삭제한 파일은 30일 동안 되살릴 수 있습니다. 처음 쓸 때 안내 투어가 앱의 주요 부분을 보여 줍니다.
 - **보안 기준:** 설정 > 보안검사에 기준 하나를 두고, `zigmini scan`으로 어느 저장소든 검사합니다.
 - **설정:** 검사와 형식 검증 스위치, 도구별 설치 버튼, 화면 언어(영어 또는 한국어) 하나.
 - **채팅:** `/compact`가 생기고, 모든 세션이 프로필 닉네임을 압니다.
@@ -372,7 +399,7 @@ zigmini update <버전>     # 지정한 버전으로 업데이트
   zigmini setup --access lan   # 또는 tailscale, domain --domain https://<도메인>
   ```
 - **설치 뒤 에이전트가 답하지 않습니다.** 모델 계정에 로그인하지 않았습니다(예: 로그인 단계에서 `s`를 입력함). 설치 15~18번(`bun add -g omo-ai@5.1.51`, `omo`, `/login`)을 합니다. 그 뒤 `zigmini setup`을 다시 실행합니다. "모델 계정: 로그인됨"이 나오고, 이미 끝난 단계는 유지됩니다. `--agent-dir`을 쓰면 `OMO_CODING_AGENT_DIR=<경로> omo`로 실행해야 그 폴더에 로그인됩니다.
-- 오래된 DB 백업, 쓰지 않는 엔진 버전, 업데이트에서 남은 파일은 웹 화면 설정의 "정리"에서 확인하고, 고른 항목만 지웁니다.
+- 오래된 DB 백업, 쓰지 않는 엔진 버전, 업데이트에서 남은 파일, 병합된 worktree, 이전 게이트웨이 Docker 이미지는 웹 화면 설정의 "정리"에서 확인합니다. 고른 항목만 지우고, 파일은 macOS 휴지통으로 옮깁니다. [정리](docs/operator.ko.md#정리)를 보세요.
 
 ## 제거
 

package/README.md

@@ -19,6 +19,8 @@ The gateway runs the agent with the permission preset `full-access`. The agent d
 
 `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.
 
+Registered agents (the role conversations you create on the web) are the exception. They start with no tool access and use a tool only after you allow it in the inbox. A permission lasts until you revoke it in the agent editor's **Tool permissions** section. Posting, sending, buying or deleting asks again for each action. Their code and shell commands run confined, and they read an Aside tab only after you pick it. This needs the engine the release installs (`5.1.51-zgw.6`); an engine without the support is refused before activation. See Tool permissions in the [user manual](docs/manual.md#tool-permissions).
+
 ## Install
 
 1. Check the Bun version. The package needs Bun `1.4.0` or later.
@@ -195,6 +197,31 @@ 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.
 
+## Attaching files from the gateway Mac
+
+Type `@` in the web or registered Android input box, or use **Mac files**, to attach a file from the Mac that runs the gateway. Files on the browser's computer or on the phone aren't listed. There's no extra folder or device setup.
+
+- **Formats and limits:** HTML, Markdown, TXT and PDF, up to 10 MiB per file and 4 documents per message. Each web or phone client can hold 16 unsent files and 64 MiB.
+- **Snapshot:** selecting a file saves a private copy that can't change. Editing the source afterwards has no effect.
+- **Access:** Send lets only the receiving conversation's agent read the file, through the narrow `zgw_attachment_read` tool.
+- **PDF routes:** public API routes with PDF input get the PDF, subscription routes get page text and page images, and text-only models get page text with OCR done on the Mac.
+- **Keeping and removing:** the original stays available for download. **Revoke** on a sent file (in the message, after confirming) denies future reads, but can't erase what a model already read, downloads, or anything made from the file. Cleanup is explicit and moves files to the macOS Trash. Nothing is deleted automatically.
+- **Mac access denied:** that's macOS privacy protection (`host_access_denied`). Allow the location in System Settings > Privacy & Security yourself; the gateway doesn't change System Settings.
+- **Older versions:** an older gateway shows that Mac file attachments aren't supported. An older app shows a sent file as `[Attached: name]` text.
+
+Details are in "Files on this Mac" in the [user manual](docs/manual.md).
+
+## What's new in 1.1.0-beta.1
+
+Release 1.1.0-beta.1 (2026-11-12 KST, Android `versionCode` 33) selects engine build `5.1.51-zgw.6`. Full notes: [docs/releases/1.1.0-beta.1.md](docs/releases/1.1.0-beta.1.md).
+
+Release 1.1.0-beta.2 (2026-11-12 KST, Android `versionCode` 34) is a hotfix that changes only the common agent rules. Notes: [docs/releases/1.1.0-beta.2.md](docs/releases/1.1.0-beta.2.md).
+
+- **Files on this Mac:** attach files from the gateway Mac to a conversation (improvement 293).
+- **Tool permissions:** registered agents start with no tool access; the owner allows it in the inbox (improvement 294).
+- **Agent collaboration:** main and agents can ask permitted agents for work and receive result files.
+- **Agents and cleanup:** knowledge file areas, drafts, a first-use tour and a new Settings > Cleanup.
+
 ## What's new in 1.0.0-beta.3
 
 Release 1.0.0-beta.3 (2026-11-04 KST, Android `versionCode` 32) selects engine build `5.1.51-zgw.4`. Full notes: [docs/releases/1.0.0-beta.3.md](docs/releases/1.0.0-beta.3.md).
@@ -214,7 +241,7 @@ Release 1.0.0-beta.2 (2026-11-03 KST, Android `versionCode` 31) is a hotfix. The
 
 Release 1.0.0-beta.1 (2026-11-02 KST, Android `versionCode` 30) is the first candidate for 1.0.0. It selects engine `5.1.51-zgw` revision 3 (OMO 5.1.51, immutable build `5.1.51-zgw.3`, senpi 2026.10.27-1, thread schema 10). Full notes: [docs/releases/1.0.0-beta.1.md](docs/releases/1.0.0-beta.1.md).
 
-- **Agents:** make your own specialist chats on the web, each with its own session, model and knowledge folder.
+- **Agents:** make your own specialist chats on the web, each with its own session, model and knowledge folder. Drafts are saved on the gateway while you create one. Upload several files at once (they apply without a new session), download what the agent writes to `outputs/`, and restore deleted files for 30 days. A first-use tour shows the main parts of the app.
 - **Security baseline:** one baseline in Settings > Security check, and `zigmini scan` for any repository.
 - **Settings:** switches for checks and formal verification, per-tool Install buttons, and one UI language (English or Korean).
 - **Chat:** `/compact`, and every session knows your profile nickname.
@@ -373,7 +400,7 @@ Use these workarounds.
   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.51`, `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.
+- Old DB backups, unused engine versions, files left by updates, merged worktrees and old gateway Docker images appear in "Cleanup" in the web screen settings. Only the items you select are removed, and files go to the macOS Trash. See [Housekeeping](docs/operator.md#housekeeping).
 
 ## Uninstall
 

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

@@ -1,3 +1,10 @@
-사용자에게 보여 주는 모든 답변과 설명은 ASD-STE100의 명확한 기술문서 작성 원칙을 따른다. 짧은 능동문을 쓰고, 한 문장에는 한 가지 내용만 담는다. 주체·대상·행동을 명확히 밝히고, 같은 대상에는 같은 용어를 쓴다.
+사용자에게 보여 주는 모든 글은 ASD-STE100(Simplified Technical English) 글쓰기 규칙을 사용자 언어에 맞게 따른다.
+1. 단어: 쉬운 단어를 쓴다. 한 단어는 한 뜻, 한 품사로만 쓴다. 같은 대상은 늘 같은 이름으로 부른다.
+2. 명사 묶음: 명사를 길게 이어 붙이지 않는다(최대 3단어).
+3. 동사: 단순한 시제를 쓴다. 능동태를 쓴다. 절차에는 수동태를 쓰지 않는다.
+4. 문장: 문장은 짧게 쓴다(영어 기준 절차 20단어, 설명 25단어 이하). 한 문장에는 한 주제만 쓴다. 문장을 줄이려고 꼭 필요한 말을 빼지 않는다. 복잡한 내용은 세로 목록으로 쓴다.
+5. 절차: 한 문장에 지시 하나만 쓴다. 명령형으로 쓴다. 조건은 지시 앞에 쓴다.
+6. 설명: 한 문단에는 한 주제만 쓴다. 문단은 짧게 쓴다.
+7. 경고·주의: 분명한 지시로 시작하고, 위험과 결과를 쓴다.
 
-흐름이나 구조를 설명할 때 도식이 도움이 되면 `docs/manual.md`의 `zigmini-diagram` 형식으로 함께 표시한다.
+사람은 눈으로 봐야 빨리 이해한다. 흐름(순서, 단계, 상태 변화), 구조(구성 요소와 관계), 원인과 결과를 설명할 때는 `docs/manual.md`의 `zigmini-diagram` 형식으로 도식을 함께 넣는다. 여러 항목을 같은 기준(예: 현재 상태, 문제, 해결 방향)으로 비교하거나 정리할 때는 표를 쓴다.

package/assets/agent/gateway-rules.md

@@ -21,6 +21,7 @@ zigmini 패키지 공통 에이전트 규칙입니다. 게이트웨이 브리지
    - 2순위: BrowserSkill 확장 프로그램(`bsk`, browser 스킬의 attached 엔진). 1순위로 해결되지 않을 때만 씁니다.
    - 3순위: 작업이 띄운 headless Chrome. 마이크·카메라 가짜 장치 옵션으로 띄우고, 끝나면 종료합니다.
    - 웹 화면 확인에는 Bun.WebView와 WebKit을 쓰지 않습니다.
+   - 등록 에이전트는 이 순서 대신 게이트웨이의 `zgw_aside` 도구만 씁니다. 사용자가 확인함에서 직접 고르고 허용한 탭은 허용한 동작으로만 다룰 수 있습니다. 이 예외는 그 탭에만 적용하며, main과 작업 세션에는 적용하지 않습니다.
    - 어느 방식이든 작업이 연 백그라운드 탭만 쓰고, 끝나면 닫습니다. 사용자 탭, 쿠키, 설정, 화면 포커스는 건드리지 않습니다. 화면 흉내, 뷰포트 같은 설정은 작업 탭에만 걸고 탭을 닫기 전에 지웁니다.
 10. <!--id:d34b70--> 게이트웨이가 떠 있는 동안 운영 DB를 다른 프로세스로 열지 않습니다. 조회는 게이트웨이 API와 로그로 합니다. <!--repo-security-check-->저장소 보안검사는 `zigmini scan <저장소>`로 하고 종료 코드를 그대로 보고합니다(0 깨끗함, 1 발견, 2 오류, 3 기준 사용 불가, 4 설정에서 결과물 검사 꺼짐). 이 명령이 보내는 읽기 전용 `GET /api/settings/security-check/baseline/revision`은 허용됩니다. 종료 코드 3이나 4이면 기준 파일을 직접 만들거나 고치지 않고 사용자에게 알립니다. 보고에는 규칙·위치·건수만 쓰고 값은 쓰지 않습니다.<!--/repo-security-check-->
 11. <!--id:57e2a8--> 보고에는 증거가 있는 것만 씁니다. 확인된 것과 추정을 나눕니다. 코드 검토, 테스트 통과, dev 머지, 운영 배포, OMO 교체, 앱 설치를 구분하고 각각의 주체와 대상을 적습니다. 다시 시작한 뒤에는 짧은 "재시작 완료" 알림을 먼저 보냅니다.
@@ -29,9 +30,15 @@ zigmini 패키지 공통 에이전트 규칙입니다. 게이트웨이 브리지
 14. <!--id:f2468e--> 사용자는 게이트웨이 프로필의 닉네임으로 부릅니다.
 15. <!--id:7d903c--> main은 오래 기다리거나 오래 실행하는 작업(배포, 전체 테스트, 뮤테이션 테스트, 다른 작업 기다리기)을 맡기면, 그 작업의 세션 기록이 30분 넘게 바뀌지 않을 때 main을 깨우는 감시를 직접 겁니다. 작업이 끝나면 감시를 끕니다. 작업의 "기다리는 중"·"진행 중" 보고만 믿지 않습니다. 사용자에게 그렇게 말하기 전에 그 작업의 마지막 기록 시각과 실행 중인 프로세스(살아 있는지, CPU를 계속 100% 쓰는지)를 확인합니다. 작업이 멈췄으면 바로 그 작업에 조치를 보내고 사용자에게 알립니다. 작업은 긴 명령을 세션과 분리해(nohup, setsid 등) 실행하고, 결과 파일을 직접 확인하며, 시간 상한을 겁니다.
 16. <!--id:0e5fa9--> 작업 하나에 나눌 수 있는 항목이 여럿이거나(예: 버그 여러 개, 구현·검증·문서 단계) 앞 단계를 기다려야 하는 단계가 있으면, 작업 세션은 mass-ulw 스킬을 씁니다. 작업 세션은 처음에 단계와 하위 작업을 정합니다. 서로 기다릴 필요가 없는 하위 작업은 최대한 병렬로 돌립니다. main은 이런 작업을 맡길 때 작업 지시문에 mass-ulw를 쓰라고 적습니다. 파일 하나 고침, 문서 한 줄 같은 작은 작업에는 mass-ulw를 쓰지 않습니다. 같은 파일을 고치는 하위 작업은 같은 단계에서 함께 돌리지 않습니다. 이런 하위 작업은 각자 worktree를 쓰거나 순서대로 돌립니다. 하위 작업을 병렬로 돌려도 무거운 명령(전체 테스트, 뮤테이션 테스트, 빌드 등)은 그 프로젝트나 설치 규칙이 정한 동시 실행 상한을 지킵니다. 규칙 8의 정리와 규칙 15의 감시는 하위 작업에도 적용합니다. 사용자가 질문만 하면 진행 중인 작업을 mass-ulw로 바꾸지 않습니다(규칙 4).
-17. <!--id:b8c1e4--> 모든 사용자용 글(main 답변, 작업 보고, 프리코멘트, 확인함 질문)에 ASD-STE100의 명확한 기술 글쓰기 원칙을 적용합니다.
-   - 사용자가 요청하거나 설정한 언어로 씁니다. 특정 언어를 강제하거나 영어 통제 어휘를 다른 언어에 그대로 적용하지 않습니다.
-   - 짧은 능동문을 씁니다. 한 문장에는 하나의 핵심 사실이나 행동을 담습니다. 수행 주체, 작업 대상, 행동을 명확히 씁니다.
-   - 같은 대상에는 같은 명칭을 씁니다. 불필요한 동의어, 전문 용어, 약어와 대상이 불명확한 대명사를 피합니다. 필요한 전문 용어와 약어는 처음에 뜻을 설명합니다. 불필요한 표현은 줄이되 대상, 조건, 결과를 이해하는 데 필요한 정보는 남깁니다.
-   - 절차는 실행 순서대로 씁니다. 각 단계에는 행동 하나를 적습니다. 필요한 선행 조건은 해당 행동 앞에 적습니다.
-   - 결과와 계획을 구분합니다. 상태 보고는 완료된 일, 미완료된 일과 차단 원인, 다음 행동을 구분해 씁니다. 확인된 사실과 추정을 나누고 근거 없는 확신을 쓰지 않습니다. "승인", "검증", "반영", "배포", "진행"만 단독으로 쓰지 말고 누가 무엇을 허가하거나 확인하거나 바꾸었는지 명시합니다. 예: 사용자 실행 허가, 코드 검토 통과, 대상 테스트 통과, dev 머지 완료, 게이트웨이 운영 배포, OMO 프로그램 교체.
+17. <!--id:b8c1e4--> 사용자에게 보여 주는 모든 글은 ASD-STE100(Simplified Technical English) 글쓰기 규칙을 사용자 언어에 맞게 따른다.
+   1. 단어: 쉬운 단어를 쓴다. 한 단어는 한 뜻, 한 품사로만 쓴다. 같은 대상은 늘 같은 이름으로 부른다.
+   2. 명사 묶음: 명사를 길게 이어 붙이지 않는다(최대 3단어).
+   3. 동사: 단순한 시제를 쓴다. 능동태를 쓴다. 절차에는 수동태를 쓰지 않는다.
+   4. 문장: 문장은 짧게 쓴다(영어 기준 절차 20단어, 설명 25단어 이하). 한 문장에는 한 주제만 쓴다. 문장을 줄이려고 꼭 필요한 말을 빼지 않는다. 복잡한 내용은 세로 목록으로 쓴다.
+   5. 절차: 한 문장에 지시 하나만 쓴다. 명령형으로 쓴다. 조건은 지시 앞에 쓴다.
+   6. 설명: 한 문단에는 한 주제만 쓴다. 문단은 짧게 쓴다.
+   7. 경고·주의: 분명한 지시로 시작하고, 위험과 결과를 쓴다.
+18. <!--id:c47e19--> 사용자에게 보여 줄 문서(보고서, 표, HTML, PDF 등)는 다음 위치에 만듭니다. 이 위치 밖의 임의 위치에는 문서를 만들지 않습니다. 폴더가 없으면 만듭니다. 도구가 다른 기본 위치에 파일을 저장하면 그 파일을 아래 위치로 옮깁니다.
+   - 특정 프로젝트 작업의 문서: 그 프로젝트 안에 만듭니다. 프로젝트에 정해진 문서 위치가 있으면 그 위치를 따릅니다. 저장소에 올리면 안 되는 내용은 커밋하지 않습니다.
+   - 일상 작업이나 대상 프로젝트가 없는 작업의 문서: `~/Documents/zigmini-output`에 만듭니다.
+   - 일회성 문서와 에이전트가 임시로 만드는 자료: `~/Documents/zigmini-output/tmp`에 만듭니다. 이 폴더에는 언제든 삭제해도 문제가 없는 자료만 둡니다. 계속 필요한 문서, 검증 증거, 유일한 원본은 이 폴더에 두지 않습니다.

package/assets/android/zigmini.apk.json

@@ -1,5 +1,5 @@
 {
-  "versionCode": 32,
-  "versionName": "1.0.0-beta.3",
-  "sha256": "b383065911a658e63f3a4738ea6e939cf43db9056b050633a2515d91c2643b69"
+  "versionCode": 34,
+  "versionName": "1.1.0-beta.2",
+  "sha256": "d925ff54307187aba89bdf47585fa64ba94092c1654318065a16066da801ab0f"
 }

package/assets/build.json

@@ -1 +1 @@
-{"commit":"b3f730269e14f70a864efc9c2e4a3b14328fbb12"}
+{"commit":"5eb1ac07c6a8aa214e2241017cd7c3cb9d2afb36"}

package/assets/document-reader/manifest.json

@@ -0,0 +1,27 @@
+{
+  "schema": 1,
+  "target": "arm64-apple-macosx13.0",
+  "compiler": "Apple Swift version 6.4 (swiftlang-6.4.0.34.1 clang-2100.3.34.1)",
+  "sdk": "macosx 27.0 (26A425)",
+  "sourceSha256": "4985f9079724f5922709936bc60d0d246a92d4cc9d887660d0339b16196a78f7",
+  "buildSha256": "39aff6bd0c804b5682ea72688c3c9424d3a0858211625d8fe1898ed6c1ddb1ee",
+  "executables": {
+    "document-reader": {
+      "sourceSha256": "4985f9079724f5922709936bc60d0d246a92d4cc9d887660d0339b16196a78f7",
+      "buildSha256": "39aff6bd0c804b5682ea72688c3c9424d3a0858211625d8fe1898ed6c1ddb1ee",
+      "sources": [
+        "Protocol.swift",
+        "DocumentRead.swift"
+      ]
+    },
+    "host-selector": {
+      "sourceSha256": "8f62efc88a9619172305bfc60eb11300fdb8d1be92ccb4708ae2084cc5093537",
+      "buildSha256": "e8f2e83153c0aa64500444b3220e86986b7239ba78e09b52c77bc0b3544b64e7",
+      "sources": [
+        "Protocol.swift",
+        "HostSelector.swift",
+        "main.swift"
+      ]
+    }
+  }
+}

package/docs/manual.ko.md

@@ -19,7 +19,7 @@ zigmini는 화면 두 개를 제공합니다.
 
 웹 화면은 세 부분으로 나뉩니다.
 
-- 왼쪽 사이드바: 기본 에이전트(main) 대화, 에이전트마다 대화 하나씩인 에이전트 묶음, 작업 상태 영역, 내 프로필, 기본 에이전트 프로필이 있습니다. 사이드바 맨 위의 "엔진" 배지는 엔진 연결 상태를 보여 줍니다.
+- 왼쪽 사이드바: 기본 에이전트(main) 대화, 에이전트마다 대화 하나씩인 에이전트 묶음, 작업 상태 영역, 내 프로필, 기본 에이전트 프로필이 있습니다. 에이전트 대화를 열면 프로필에 그 에이전트의 이름과 아이콘이 보입니다. 사이드바 맨 위의 "엔진" 배지는 엔진 연결 상태를 보여 줍니다.
 - 가운데 채팅: 헤더, 메시지 목록, 입력창이 있습니다.
 - 오른쪽 패널: 확인함, 설정, 이벤트 패널이 열립니다.
 
@@ -34,7 +34,7 @@ Terra Fast는 해당 구독에서 지원하지 않습니다. 현재 선택한
 | --- | --- |
 | 지그 얼굴 버튼 | 작업 상태를 봅니다. 폰 너비에서는 작업 상태 화면으로 바꿉니다. |
 | 모델 선택 | 에이전트가 쓸 모델을 고릅니다. 바로 바꿀 수 없으면 다음 메시지를 보낼 때 대화를 압축한 뒤 바꿉니다. |
-| 새 세션 | 이 대화의 에이전트 세션을 새로 시작합니다. 확인 창이 먼저 뜹니다. 화면의 기록은 그대로 남고, 최근 대화 일부를 새 세션에 넘깁니다. |
+| 새 세션 | 이 대화의 에이전트 세션을 새로 시작합니다. 확인 창이 먼저 뜹니다. 화면의 기록은 그대로 남고, 최근 대화 일부를 새 세션에 넘깁니다. 정의가 바뀐 에이전트 대화에서는 버튼이 강조되고 "새 세션으로 적용"으로 바뀝니다. |
 | 음성 켜짐 / 음성 꺼짐 | 게이트웨이의 음성 서버를 켜고 끕니다. 끄면 마이크, 호출어, 박수 감지, 음성 답변을 쓸 수 없습니다. |
 | 음성 설치 | 음성 서버가 설치되지 않은 npm 설치에서만 보입니다. 누르면 음성 서버를 내려받아 설치합니다. |
 | 박수 감지 | 박수를 두 번 치면 호출어 대기를 켜고 끕니다. |
@@ -136,8 +136,10 @@ README의 '명령' 절에 따르면 채팅에서 `/usage`를 보내면 게이트
 스트리밍 중 블록이 완성되고 형식이 맞으면 도식으로 표시할 수 있습니다.
 도식 내용은 스크립트 실행, URL 로드, 파일 읽기를 할 수 없습니다.
 이 기능이 없는 이전 클라이언트는 코드 블록으로 표시합니다.
-짧은 매 요청 규칙은 흐름이나 구조 설명에 도움이 될 때만 도식을 사용하도록 안내합니다.
-모든 답변에 도식을 요구하지 않습니다.
+매 요청 규칙은 사람이 눈으로 봐야 빨리 이해한다고 안내합니다.
+흐름(순서, 단계, 상태 변화), 구조(구성 요소와 관계), 원인과 결과를 설명할 때는 이 `zigmini-diagram` 형식으로 도식을 함께 넣게 합니다.
+그 밖의 답변에는 도식을 요구하지 않습니다.
+여러 항목을 같은 기준(예: 현재 상태, 문제, 해결 방향)으로 비교하거나 정리할 때는 표를 쓰게 합니다.
 
 #### 이미지
 
@@ -147,6 +149,44 @@ README의 '명령' 절에 따르면 채팅에서 `/usage`를 보내면 게이트
 
 한 번에 4장까지 보낼 수 있습니다. PNG, JPEG, GIF, WebP를 씁니다. 이미지는 전송할 때 올라갑니다.
 
+#### 이 Mac의 파일
+
+입력창 맨 앞이나 공백 뒤에 `@`를 입력하거나 "Mac 파일" 버튼을 누릅니다. "이 Mac의 파일" 창은 게이트웨이가 실행되는 Mac의 파일을 보여 줍니다. 브라우저를 켠 컴퓨터나 폰의 파일은 보여 주지 않습니다. 폴더나 기기를 따로 설정할 필요는 없습니다. 이메일 주소처럼 단어 안에 있는 `@`와 `\@`, `@@`는 그대로 글자로 남습니다.
+
+창은 가능하면 `~/Downloads`에서 열립니다. "홈"과 "컴퓨터"로 다른 위치로 이동합니다. 검색은 현재 폴더만 찾습니다. 숨김 파일은 "숨김 파일 표시"를 켜야 보입니다. 링크는 선택할 수 없습니다.
+
+| 항목 | 한도 |
+| --- | --- |
+| 형식 | `.html`, `.htm`, `.md`, `.markdown`, `.txt`, `.pdf` |
+| 파일 크기 | 파일당 10 MiB, 빈 파일 제외 |
+| PDF 길이 | 300쪽 |
+| 메시지 하나 | 서로 다른 문서 4개(참조한 메시지의 문서 포함) |
+| 선택했지만 보내지 않은 파일 | 웹·폰 클라이언트별 16개, 64 MiB |
+
+이미지는 기존 이미지 버튼을 그대로 씁니다.
+
+게이트웨이는 파일을 선택한 순간 비공개 사본을 저장합니다. 이 사본은 바뀌지 않습니다. 선택한 뒤 원래 파일을 고쳐도 사본에는 영향이 없습니다. 고친 내용을 보내려면 파일을 다시 선택합니다. 게이트웨이는 원래 파일을 옮기거나 고치지 않습니다.
+
+입력창 위의 칩에 파일별 진행 상태가 보입니다. 모든 파일이 "준비됨"이 되어야 보낼 수 있습니다. 실패한 파일은 다시 시도하거나 뺍니다. UTF-8이 아닌 텍스트 파일은 "인코딩 선택"에서 문자 인코딩을 고릅니다.
+
+파일을 선택해도 에이전트는 아직 읽지 못합니다. 보내기를 해야 받는 대화의 에이전트만 읽을 수 있습니다. 다른 대화와 복제한 에이전트는 권한을 받지 않습니다. 파일을 에이전트의 지식이나 메모리에 복사하지도 않습니다. 에이전트는 좁은 전용 도구 `zgw_attachment_read`로 읽습니다. 이 도구는 해당 대화에 허용된 파일만 열고 경로를 받지 않습니다. 따라서 에이전트가 이 도구로 Mac을 둘러볼 수 없습니다.
+
+PDF를 모델에 전달하는 방식은 사용 중인 모델에 따라 다릅니다. 게이트웨이가 자동으로 정하며 모델을 바꾸지는 않습니다.
+
+| 모델 경로 | 모델이 받는 내용 | 칩 표시 |
+| --- | --- | --- |
+| PDF 입력을 지원하는 공개 OpenAI·Anthropic API | PDF 원본 | "PDF 입력" |
+| ChatGPT·Claude 구독 | 페이지 텍스트와 페이지 이미지 | "페이지 이미지" |
+| 텍스트 전용 모델 | 페이지 텍스트와 이 Mac에서 수행한 OCR 결과 | "OCR 텍스트" |
+
+게이트웨이는 원본 사본을 보존합니다. 메시지에 보이는 파일 이름을 누르면 내려받습니다. HTML은 내려받기만 되고 페이지로 열리지 않습니다.
+
+보낸 파일의 권한을 회수하려면 보낸 메시지에서 그 파일의 **회수**를 누르고 확인합니다. 그 파일은 **사용 불가**로 바뀌고, 전달이 아직 대기 중이었는지와 회수가 되돌리지 못하는 것을 함께 보여 줍니다. 보낸 파일의 권한을 회수하면 이후의 읽기와 내려받기를 거절합니다. 모델이 이미 읽은 내용, 이미 내려받은 파일, 그 파일로 만든 결과물은 지울 수 없습니다. 정리는 직접 요청할 때만 진행하며 파일을 macOS 휴지통으로 옮깁니다. 자동으로 삭제하는 일은 없습니다.
+
+"Mac 접근 권한이 없습니다."가 보이면 macOS 개인정보 보호가 그 위치를 막은 것입니다. 다른 위치는 그대로 쓸 수 있습니다. 해결 방법은 5.4를 보세요.
+
+구형 게이트웨이에서는 "이 게이트웨이는 Mac 파일 첨부를 지원하지 않습니다."가 보입니다. 구형 앱은 받은 파일의 이름을 `[Attached: 이름]` 글자로 표시합니다.
+
 #### 이전 메시지 참조
 
 메시지를 마우스 오른쪽 버튼으로 누르면 그 메시지가 참조 태그로 입력창 위에 붙습니다. 메시지의 "참조" 버튼도 같은 일을 합니다. 참조는 한 번에 4개까지 넣을 수 있습니다. 참조한 메시지의 이미지와 새 첨부 이미지를 합쳐 4장까지만 보낼 수 있습니다. 참조 태그를 빼려면 태그의 버튼을 누르거나, 태그에 초점을 두고 Delete 또는 Backspace를 누릅니다.
@@ -300,7 +340,7 @@ Android 앱(APK)을 받는 QR이 보입니다. 폰 카메라로 QR을 찍어 APK
 
 #### 정리
 
-게이트웨이가 지워도 되는 후보를 보여 줍니다. 후보는 DB 백업, 엔진 버전 폴더, 업데이트 남은 파일, 임시 폴더, 이전 RPC 데몬입니다. 지울 항목을 고르고 "선택한 항목 정리"를 누릅니다. 후보 수 옆의 "전체 선택"을 누르면 모든 후보를 한 번에 고르거나 모두 풉니다.
+게이트웨이가 두 묶음을 보여 줍니다. "상태 정리"는 게이트웨이가 근거로 닫았거나 결정이 필요한 미완료 작업입니다. 이 줄은 고를 수 없습니다. 결정이 필요한 줄에는 "main이 확인을 요청합니다", 게이트웨이가 닫은 줄에는 "근거를 확인하고 정리했습니다"가 붙습니다. "회수"는 지워도 되는 후보입니다. 후보는 DB 백업, 엔진 버전 폴더, 업데이트 남은 파일, 임시 폴더, 에이전트 보관 폴더, 병합된 worktree, 이전 게이트웨이 Docker 이미지입니다. 지울 항목을 고르고 "선택한 항목 정리"를 누릅니다. 파일과 폴더는 macOS 휴지통으로 갑니다. Docker 이미지에는 "되돌릴 수 없음" 표시가 붙습니다. "전체 선택"을 누르면 고를 수 있는 줄을 모두 고르거나 모두 풉니다. Docker 빌드 캐시 크기 같은 안내 줄은 고를 수 없습니다. "기록 보기"는 마지막 정리 기록 20줄을 보여 줍니다. 이전 RPC 데몬과 부모 없는 시험 프로세스는 자동으로 멈춥니다. 자세한 내용은 [정리](operator.ko.md#정리)를 보세요.
 
 #### 음성 설정
 
@@ -333,16 +373,47 @@ Android 앱(APK)을 받는 QR이 보입니다. 폰 카메라로 QR을 찍어 APK
 {"version":1,"title":"기본 에이전트, 에이전트, 작업 세션","nodes":[{"id":"user","label":"사용자"},{"id":"main","label":"기본 에이전트 (main, 지그)"},{"id":"agent","label":"에이전트 대화"},{"id":"work","label":"작업"},{"id":"knowledge","label":"에이전트 지식 폴더"}],"edges":[{"from":"user","to":"main"},{"from":"user","to":"agent"},{"from":"main","to":"work"},{"from":"agent","to":"knowledge"}]}
 ```
 
+보통 순서는 에이전트 만들기, 자료 올리기, 대화하기, 결과물 내려받기입니다.
+
+```zigmini-diagram
+{"version":1,"title":"새 에이전트에서 결과물까지","nodes":[{"id":"create","label":"만들기 (+ 에이전트)"},{"id":"upload","label":"knowledge/source/에 올리기"},{"id":"chat","label":"에이전트 대화"},{"id":"outputs","label":"knowledge/outputs/에서 내려받기"}],"edges":[{"from":"create","to":"upload"},{"from":"upload","to":"chat"},{"from":"chat","to":"outputs"}]}
+```
+
 - **사이드바.** 에이전트는 별도 묶음에 보입니다. 묶음 이름 옆 **⋯** 버튼(또는 대화창 위쪽 **에이전트** 버튼)은 에이전트 화면을 엽니다. 이 화면에는 목록, 공통 기본값, 보관함이 있습니다. 에이전트 추가와 편집은 이 화면에서만 합니다. 목록의 **+ 에이전트**는 새 에이전트를 만듭니다. 줄마다 있는 **편집**은 그 에이전트의 편집 화면을 엽니다. 사이드바와 대화창 머리에는 추가·편집 버튼이 없습니다. 에이전트마다 대화는 정확히 하나입니다.
-- **편집 화면.** 이름과 목적 한 줄은 꼭 채웁니다. 선택 항목은 아이콘, 모델(제공자와 모델 ID를 둘 다 채우거나 둘 다 비움, 비우면 게이트웨이의 현재 모델), 사고 수준, 스킬 허용 목록, 웹 리서치(web_search, webfetch), 답이 끝나면 앱 알림, 게이트웨이 규칙·설치 규칙 붙이기, MEMORY.md 상한(0부터 32768바이트)입니다. 셸과 코드 실행은 늘 꺼져 있습니다. 항목마다 값의 출처(패키지 기본값, 공통 기본값, 이 에이전트)가 보입니다. 본문은 역할 지시문입니다.
-- **바꾼 정의는 새 세션부터 적용합니다.** 정의를 고치면 대화 머리줄에 "정의 바뀜 · 새 세션부터 적용"이 보입니다. 열린 세션은 이전 정의를 씁니다. 이 표시를 누르면 새 세션을 시작해 바뀐 정의를 적용합니다.
+- **대화.** 에이전트 대화의 답에는 그 에이전트의 이름과 아이콘이 붙습니다. 아이콘이 없으면 이름의 첫 글자가 보입니다.
+- **편집 화면.** **이름**과 **목적 한 줄**은 꼭 채웁니다. 선택 항목은 **아이콘**, **모델**(**제공자**와 **모델 ID**를 둘 다 채우거나 둘 다 비움, 비우면 게이트웨이의 현재 모델), **사고 수준**, **허용할 스킬**, **웹 리서치 (web_search, webfetch)**, **답변이 끝나면 앱 알림**, 규칙 스위치 **공통 규칙**과 **오버라이드 규칙**, **MEMORY.md 상한 (바이트)**(0부터 32768까지)입니다. 스키마 버전 칸은 없습니다. 게이트웨이가 알아서 적습니다. **셸 (금지)**와 **코드 실행 (금지)**는 켤 수 없는 꺼진 스위치로 보이고, 셸과 코드 실행이 지식 폴더 경로 검사를 우회한다는 금지 이유가 함께 보입니다. 항목마다 값의 출처(패키지 기본값, 공통 기본값, 이 에이전트)가 보입니다. 본문은 **역할 지시문**입니다. 그 위의 **역할 지시문 쓰는 법**은 **담당 범위**, **할 일**, **하지 않을 일**, **호칭** 네 가지를 안내합니다. 호칭을 바꾸려면 "사용자를 ○○라고 부르세요"처럼 적습니다. 적지 않으면 프로필 닉네임 규칙을 따릅니다.
+- **허용할 스킬.** 엔진에 설치된 스킬 목록에서 체크해 고릅니다. 저장된 값 중 설치되지 않은 스킬은 체크된 채 **설치되지 않음** 표시가 붙습니다. 저장하면 그대로 남고, 체크를 풀면 빠집니다. 목록을 불러오지 못하면 **다시 시도** 버튼이 보이고 저장된 값은 유지됩니다.
+- **할 수 있는 일과 없는 일.** 편집 화면 위쪽 상자에 지금 고치는 값으로 **할 수 있는 일**과 **할 수 없는 일**이 보입니다. 게이트웨이가 미리 계산해 보여 주고, 값을 바꾸면 바로 바뀝니다(예: **웹 리서치 (web_search, webfetch)** 스위치에 따라 **웹 조사 (web_search, webfetch)**가 두 열 사이를 옮겨 갑니다).
+- **만드는 동안 임시 저장.** 새 에이전트를 쓰는 동안 게이트웨이가 임시 저장하고 **임시 저장됨 · {time}**을 보여 줍니다. 목록의 **만들던 내용 불러오기 ({count})**로 다시 불러올 수 있고, 다른 기기에서도 됩니다. 임시 저장에는 고른 파일의 이름과 크기만 남고 내용은 남지 않으니 파일을 다시 골라야 합니다. 편집 창을 닫거나 다시 여는 중에 저장이 실패하면, 같은 페이지에서 다시 열 때 예전 저장본 대신 최신 본문과 파일 목록을 유지합니다. 임시 저장 상태 줄에 실패 안내가 보입니다. 연결 상태와 초안 크기를 확인한 뒤 내용을 편집하면 다시 저장합니다. **임시 저장됨 · {time}**이 보일 때까지 페이지를 닫거나 새로고침하지 마세요. 다른 페이지나 기기에서는 마지막으로 저장에 성공한 내용만 읽을 수 있습니다. 에이전트를 만들면 그 임시 저장은 닫힙니다. 오래된 임시 저장은 나중에 설정의 **정리**에 보입니다.
+- **바꾼 정의는 새 세션부터 적용합니다.** 정의를 고치면 대화 머리줄에 상태 표시 **⚠ 정의가 바뀌었습니다**와 안내 "새 세션 버튼을 누르면 바뀐 정의가 적용됩니다"가 보입니다. 열린 세션은 이전 정의를 씁니다. 오른쪽 위 **새 세션** 버튼은 강조되고 **새 세션으로 적용**으로 바뀝니다. 이 버튼을 누르고 확인하면 새 세션을 시작해 바뀐 정의를 적용합니다. 열린 세션이 어떤 정의를 썼는지 게이트웨이가 확인할 수 없으면 상태 표시는 **정의 적용 여부를 확인할 수 없습니다**이고, 버튼도 같은 방식으로 강조됩니다. 새 세션은 지금 정의를 적용합니다. 정의를 바꿔 저장하면 편집 화면에 **지금 적용** 버튼도 보이고, 확인하면 새 세션을 바로 엽니다. 바뀐 것 없이 저장하면 **바뀐 정의가 없습니다.**가 보입니다.
 - **스킬.** 에이전트 대화의 "/" 메뉴에는 허용 목록 밖의 스킬이 보이지 않습니다.
-- **지식.** 에이전트의 파일 도구는 자기 지식 폴더 안에서만 동작합니다. 자료 파일은 에이전트 화면의 목록에서 **편집**을 눌러 연 편집 화면에서 올립니다. 웹 리서치를 켜면 조사 결과를 `knowledge/notes/` 아래에 쓰고, 사실마다 출처 URL을 같은 줄에 적습니다. 에이전트는 자기 대화 기록만 검색합니다.
+- **지식 파일.** 편집 화면은 파일을 위치별로 나눠 보여 줍니다. **올린 자료**는 `knowledge/source/`, **결과물**은 `knowledge/outputs/`, **기록**은 `notes/, MEMORY.md`(보기만 함)입니다. 올리기 영역에 파일을 끌어다 놓거나 **파일 고르기**를 누릅니다. 여러 파일을 한 번에 고를 수 있고, 줄마다 진행 상황이 보입니다. 올리면 바로 저장되고 에이전트가 바로 씁니다. 새 세션은 필요 없습니다. 에이전트는 매 턴 자기 파일 목록을 받습니다. 같은 이름의 파일이 있으면 새 파일은 "이름 (2)"로 저장됩니다. 만들기 화면에서 고른 파일은 **만들기 뒤 올립니다**로 보이고, 에이전트를 만든 직후 올라갑니다. 그 진행은 새 에이전트의 편집 화면에서 보입니다.
+- **에이전트가 쓰는 곳.** 에이전트는 지식 폴더의 모든 파일을 읽지만 쓰기는 `outputs/`, `notes/`, `MEMORY.md`에만 합니다. `source/`는 바꿀 수 없습니다. 결과를 `outputs/`에 저장해 달라고 말하세요. **결과물**과 **올린 자료**의 파일마다 **내려받기**가 있습니다. 웹 리서치를 켜면 조사 결과를 `notes/` 아래에 쓰고, 사실마다 출처 URL을 같은 줄에 적습니다. 에이전트는 자기 대화 기록만 검색합니다.
+- **일일 기록.** 에이전트는 일한 날마다 `notes/daily/<날짜>.md`를 씁니다. 턴이 끝났는데 오늘 기록이 없으면 다음 턴에 알림을 받습니다. **기록**에 **마지막 일일 기록: {date}**가 보입니다.
+- **파일 삭제.** `source/`나 `outputs/` 파일의 **삭제**를 누르면 파일이 **삭제한 파일 ({count})**로 옮겨 가고, 30일 동안 **되살리기**로 되돌릴 수 있습니다. 그 뒤에는 설정의 **정리**에 후보로 보이고, 거기서 확인해야 macOS 휴지통으로 옮겨집니다. 교체 버튼은 없습니다. 옛 파일을 지우고 새 파일을 올립니다.
 - **복제.** 복제하면 정의, 자료 파일, MEMORY.md를 "<이름> 사본"이라는 새 에이전트로 복사합니다. 대화는 복사하지 않습니다.
-- **삭제와 되살리기.** 삭제하려면 에이전트 이름을 똑같이 입력합니다. 대화는 숨기고, 정의와 지식은 보관함에 30일 둡니다. 진행 중인 턴이나 열린 질문이 있으면 삭제할 수 없습니다. 보관함에서 되살리면 대화가 다시 보입니다.
-- **기본 에이전트.** 지그는 에이전트 목록(이름, 목적, 링크)을 볼 수 있지만 에이전트와 대화하지 않습니다. 보관함의 에이전트는 목록에 나오지 않습니다.
+- **삭제와 되살리기.** 삭제하려면 에이전트 이름을 똑같이 입력합니다. 대화는 숨기고, 정의와 지식은 보관함에 30일 둡니다. 그 뒤에는 설정의 **정리**에서 macOS 휴지통으로 옮길 수 있습니다. 진행 중인 턴이나 열린 질문이 있으면 삭제할 수 없습니다. 보관함에서 되살리면 대화가 다시 보입니다. 같은 ID의 에이전트가 이미 있으면(같은 에이전트를 두 번 지운 뒤 하나를 되살린 경우) 그 줄에 충돌 안내와 **새 ID로 되살리기**가 보입니다. 이 버튼은 둘 다 남깁니다. 기존 에이전트를 덮어쓰지 않습니다.
+- **기본 에이전트.** 지그는 에이전트 목록(이름, 목적, 링크)을 볼 수 있고, 에이전트에 협업 요청을 보낼 수 있습니다(2.13 참조). 보관함의 에이전트는 목록에 나오지 않습니다.
+- **투어.** 처음 쓸 때 짧은 투어가 입력창, 사이드바, **새 세션**, 확인함, **에이전트**, **+ 에이전트**, 설정을 차례로 안내합니다. 대부분의 단계는 강조된 곳을 쓰면 넘어갑니다. 입력창에 글자를 하나 쓰거나(보내지는 않습니다) 강조된 버튼을 누릅니다. **새 세션** 단계는 실제로 누르면 새 엔진 세션이 시작되므로 대신 **다음** 버튼을 누릅니다. 대상이 없거나 쓸 수 없는 단계에도 **다음**이 보이고, 화면에 없는 대상의 단계는 건너뜁니다. **건너뛰기**나 Esc는 투어 전체를 끝냅니다. 투어는 브라우저마다 한 번 시작합니다. 설정의 **안내 투어**에서 **안내 투어 다시 보기**를 누르면 다시 봅니다.
 - **Android.** 앱은 기본 에이전트(main) 대화만 씁니다. 에이전트 대화는 지금은 웹에서만 씁니다.
 
+#### 도구 권한
+
+새로 만든 에이전트와 복제한 에이전트는 도구 권한 없이 시작합니다. 에이전트가 도구가 필요하면 요청하고, 그 요청은 확인함에 **도구 사용 허가** 카드로 나타납니다. 카드에는 **에이전트**, **요청 경로**(**직접 요청** 또는 협업 에이전트의 의뢰), **도구**, **대상**, **동작**, **유지 기간**(**권한을 회수할 때까지**)이 보입니다.
+
+```zigmini-diagram
+{"version":1,"title":"도구 권한 요청부터 결과까지","nodes":[{"id":"need","label":"에이전트가 도구를 요청"},{"id":"check","label":"게이트웨이가 기존 권한 확인"},{"id":"inbox","label":"확인함의 도구 사용 허가"},{"id":"grant","label":"이 범위 허용: 권한 유지"},{"id":"deny","label":"허용하지 않음: 실행 안 함"},{"id":"run","label":"다시 확인한 뒤 한 번 실행"},{"id":"result","label":"결과를 받아 원래 일 계속"},{"id":"edit","label":"범위 편집 또는 권한 회수"}],"edges":[{"from":"need","to":"check"},{"from":"check","to":"inbox"},{"from":"check","to":"run"},{"from":"inbox","to":"grant"},{"from":"inbox","to":"deny"},{"from":"grant","to":"run"},{"from":"run","to":"result"},{"from":"grant","to":"edit"}]}
+```
+
+- **계속 유지되는 권한.** **이 범위 허용**을 누르면 그 에이전트·도구·동작·대상에 대한 권한이 회수할 때까지 유지됩니다. 같은 대상과 동작에서는 다시 묻지 않습니다. 다른 도구, 다른 에이전트, 다른 탭으로는 넓어지지 않습니다. 허용하면 게이트웨이가 기다리던 동작을 한 번 실행하고, 에이전트는 그 결과로 원래 일을 이어 갑니다. **허용하지 않음**을 누르면 아무것도 실행하지 않습니다("권한을 허용하지 않았습니다. 도구는 실행하지 않았습니다."). 새로 요청하지 않으면 에이전트는 같은 요청을 반복하지 않습니다.
+- **편집과 회수.** 에이전트 편집 화면에 **도구 권한** 칸이 있습니다. 행마다 도구, 동작, 대상, 상태(**허가됨**, **반영 중**, **회수됨**, **대상 확인 필요**, **권한 없음**)와 원래 확인을 보여 줍니다. 행의 스위치를 끄면 바로 회수합니다. 열려 있는 세션에도 바로 적용되고 새 세션은 필요 없습니다. **범위 편집**에서 범위를 줄이면 바로 적용됩니다. 범위를 넓히면 확인함에 새 확인 요청이 가고("추가 범위를 확인합니다"), 허용하기 전까지는 기존 범위만 유효합니다. **권한 회수**는 권한 하나를 없앱니다. 실행 중인 작업이 있으면 게이트웨이가 중단을 요청하고, 중단이 확인될 때까지 "권한을 회수했습니다. 실행 중인 작업의 중단을 확인하고 있습니다."를 보여 줍니다. 이미 일어난 일을 되돌리지는 못합니다. **전체 도구 접근 회수**는 그 에이전트의 모든 권한을 회수하고 새 요청도 막습니다. 다시 쓰려면 확인함에서 새 요청을 허용해야 하며, 예전 권한은 되살아나지 않습니다.
+- **외부 행위는 따로 확인합니다.** 도구 권한은 도구를 쓸 수 있다는 허가입니다. 특정 게시, 메시지 전송, 구매, 삭제, 설정 변경을 허가한 것은 아닙니다. 이런 행위는 정확한 내용과 대상을 확인함에서 따로 묻고, 그 확인은 한 번만 쓰입니다. 내용이나 받는 사람이 바뀌면 다시 묻습니다. 자기 지식 폴더의 읽기와 쓰기는 두 번 묻지 않습니다.
+- **기존 에이전트.** 이 버전 전에 만든 에이전트는 당분간 지금 쓰던 도구를 그대로 씁니다. 에이전트마다 기존 범위(웹 조사 설정과 지식 폴더 접근)를 적은 확인함 카드가 한 장 생깁니다. 확인하면 그 범위가 권한으로 기록됩니다. 거절하면 그 에이전트는 권한 없음으로 바뀝니다. 어느 쪽이든 에이전트가 쉬는 때에 바뀌므로, 진행 중인 차례는 기존 범위로 끝납니다. 답하지 않으면 아무것도 바뀌지 않습니다. **웹 리서치 (web_search, webfetch)** 스위치만으로는 더 이상 권한이 생기지 않습니다.
+- **Aside 탭.** 에이전트는 사용자가 Aside에 이미 열어 둔 탭을 사용자가 고른 뒤에만 읽을 수 있습니다. 요청 카드에서 **열린 탭 불러오기**를 누르고 **대상 탭 선택**에서 탭을 고릅니다. 탭 목록은 사용자 화면에만 보이고, 에이전트는 고른 탭 하나만 받습니다. 읽기는 탭을 클릭하거나, 입력하거나, 이동하거나, 닫지 않습니다. 클릭이나 입력은 같은 탭에 대한 별도 권한이 필요하고, 게시나 전송은 여기에 더해 따로 확인합니다. 탭이 닫히거나 다른 사이트로 이동하면 권한은 **대상 확인 필요** 상태로 기다립니다. 자기 작업에는 에이전트가 백그라운드 탭을 열고, 끝나면 닫습니다.
+- **코드와 명령 실행.** 코드 실행과 셸 명령은 제한된 환경에서 실행합니다. 네트워크, 브라우저 프로필, 게이트웨이와 그 설정에 닿을 수 없고, 자기 작업 폴더만 봅니다. 코드 실행 권한이 파일·웹·브라우저 권한을 대신하지 않으며, 그 안의 파일·웹 호출도 다시 검사합니다.
+- **답하는 곳.** 도구 요청은 게이트웨이 주소로 직접 연 웹 화면에서 답합니다. Android 앱에서도 답할 수 있습니다(4.3 참고). 이전 앱은 "이 권한은 웹에서 확인해 주세요"를 보여 줍니다.
+- **필요 조건.** 이 기능이 든 게이트웨이 릴리스와 그 릴리스가 설치하는 엔진(패치 매니페스트 개정 6, 엔진 `5.1.51-zgw.6`)이 필요합니다. 이 기능을 지원하지 않는 엔진으로 가는 업데이트는 그 엔진을 활성화하기 전에 거절되고, 게이트웨이는 이전 엔진을 그대로 씁니다.
+
 ### 2.12 에이전트 규칙
 
 게이트웨이는 패키지의 공통 규칙과 이 설치의 `~/.zigmini/rules.md`를 main과 작업 세션마다 붙입니다.
@@ -352,6 +423,29 @@ Android 앱(APK)을 받는 QR이 보입니다. 폰 카메라로 QR을 찍어 APK
 - `zigmini rules`: 공통 항목의 번호, ID, 첫 줄을 보여 줍니다.
 - `zigmini rules check`: `rules.md`의 각 항목이 "공통 N번을 대체", "신규 규칙", "없는 ID" 중 무엇인지 보여 줍니다(없는 ID가 있으면 종료 코드 1).
 
+### 2.13 에이전트 협업
+
+지그는 에이전트에 요청을 맡길 수 있고, 에이전트는 다른 에이전트에 질문할 수 있습니다. 요청마다 기록이 따로 남고, 답은 요청한 대화로 돌아옵니다.
+
+```zigmini-diagram 협업 도구 자체에는 **도구 사용 허가**가 필요 없습니다. 다른 도구는 여전히 허가가 필요합니다. 차단된 에이전트는 협업 도구를 받지 않습니다.
+{"version":1,"title":"협업 요청 한 건","nodes":[{"id":"asker","label":"요청한 대화(지그 또는 에이전트)"},{"id":"gateway","label":"게이트웨이 요청 기록"},{"id":"agent","label":"요청을 받은 에이전트"},{"id":"inbox","label":"확인함(내 답)"}],"edges":[{"from":"asker","to":"gateway"},{"from":"gateway","to":"agent"},{"from":"agent","to":"inbox"},{"from":"inbox","to":"agent"},{"from":"agent","to":"asker"}]}
+```
+
+- **누가 누구에게 물을 수 있나요.** 에이전트 편집 화면의 **협업** > **요청을 보낼 수 있는 에이전트**에서 이 에이전트가 요청을 보낼 수 있는 에이전트를 고릅니다. 허용은 한 방향이고, 처음에는 비어 있습니다. 지그는 보관하지 않은 모든 에이전트에 요청할 수 있습니다. 에이전트는 질문만 보낼 수 있고 작업을 맡길 수는 없습니다.
+- **대화 속 카드.** 두 대화에 모두 카드가 나옵니다. 요청한 쪽에는 **보낸 협업 요청**, 받은 쪽에는 **받은 협업 요청**입니다. 카드에는 **보낸 쪽**, **받는 쪽**, 종류(**작업** 또는 **질문**), 요청 내용, 상태가 나오고, 끝나면 **결과**와 **파일**이 나옵니다. 열린 화면에서는 상태와 결과가 바뀌는 대로 카드가 새로 고침 없이 바뀝니다.
+- **상태.** **대기 중**, **진행 중**, **다른 에이전트의 답 대기**, **내 답 대기**, **결과 준비 중**, **완료**, **실패**, **중단됨**, **취소 요청됨**, **취소됨**, **전달 미확인**, **정의 변경으로 미실행**이 있습니다. 에이전트가 결과를 직접 제출해야 **완료**입니다. 결과 없이 멈추면 요청은 **중단됨**으로 남고, 저절로 다시 실행하지 않습니다.
+- **내 차례가 먼저입니다.** 요청은 내가 시작한 차례를 끊지 않습니다. 내 차례가 끝난 뒤에 실행됩니다.
+- **나에게 온 질문.** 에이전트가 요청을 처리하다가 나에게 질문하면, 그 요청(과 그 요청이 시작한 요청)만 **내 답 대기**로 멈춥니다. 다른 요청은 계속 실행됩니다. 확인함에서 답하면 그 답으로 요청이 한 번 이어집니다. 에이전트가 요청을 처리하다가 요청한 **도구 사용 허가** 카드도 마찬가지로 그 요청(과 그 요청이 시작한 요청)만 **내 답 대기**로 멈추고, 답하면 요청이 한 번 이어집니다. 내가 보낸 요청에 상대 에이전트가 답한 뒤 이어지는 실행에서 허가가 필요한 도구 호출도 **도구 사용 허가** 카드를 만들고, 카드에는 **내가 보낸 협업 요청의 의뢰**라고 나옵니다. 허용하면 그 호출을 한 번 실행하고 에이전트가 한 번 이어집니다.
+- **결과 파일.** 에이전트는 파일을 `outputs/`에 저장하고 결과에 그 파일을 적습니다. 게이트웨이가 사본을 봉인하므로, 나중에 `outputs/`를 고쳐도 결과는 바뀌지 않습니다. 이렇게 받은 파일은 받은 에이전트의 지식 파일에 **협업 사본**으로 나옵니다. 지우면 그 사본만 지워집니다.
+- **파일 읽기 검토.** 에이전트가 공유 파일을 읽으면 게이트웨이가 요청한 부분에 보안검사를 합니다. 검사에서 값이 검출되면 읽기를 보류합니다. 글자 층이 없는 PDF 쪽은 자동으로 검사할 수 없어서 역시 보류합니다. 그러면 확인함에 **파일 읽기 검토** 카드가 나옵니다. 카드에는 **읽는 에이전트**, **파일**, **요청한 부분**, **보안검사**가 나옵니다. **보안검사** 줄에는 검출 종류와 건수만 나오고(예: **토큰·API 키 1건**), 검출된 값 자체는 보이지 않습니다. 검사하지 못한 쪽이 있으면 허용하기 전에 직접 확인하라고 알려 줍니다. **이 읽기 허용**을 누르면 그 부분을 에이전트에게 한 번 전달합니다. **허용하지 않음**을 누르면 아무것도 전달하지 않습니다. 게이트웨이가 이 브라우저를 소유자로 인정하지 않으면 처리하지 않았다고 알려 줍니다. 게이트웨이에 연결하지 못하면 처리 여부를 알 수 없으니 최신 상태를 확인해 주세요. 그사이 보류 상태가 바뀌었으면 카드가 최신 상태를 다시 불러옵니다. 확인한 뒤 다시 답해 주세요.
+- **취소와 다시 확인.** **요청 취소**는 그 요청과 그 요청이 시작한 요청을 멈춥니다. 진행 중인 요청은 에이전트가 멈출 때까지 **취소 요청됨**이고, 그다음 **취소됨**이 됩니다. **전달 미확인**은 에이전트가 요청을 받았는지 게이트웨이가 확인하지 못했다는 뜻입니다(예: 재시작 뒤). 저절로 다시 보내지 않습니다. **다시 확인**은 상태를 다시 읽습니다. 협업 요청을 처리 중인 에이전트 대화에서 **중단**을 누르면 **요청 취소**와 같이 그 요청과 그 요청이 시작한 요청이 취소됩니다.
+- **결과 없이 끝난 요청.** 요청이 **취소됨**, **중단됨**(결과가 없는 경우 포함), **정의 변경으로 미실행**으로 끝나도 요청한 대화에는 마지막 답이 한 번 갑니다. 이 답에는 상태와 이유만 있고, 내용과 파일은 없습니다. 아무것도 전달하지 않고, 다시 실행하지도 않습니다. 요청한 쪽의 요청이 이미 끝났거나 취소 중이면 답이 가지 않습니다.
+- **다시 요청하기.** 다시 요청은 지그만, 처음 요청을 보낸 대화에서만 할 수 있습니다. 지그는 `retryOf`에 처음 요청의 id를 넣어 새 요청을 보냅니다. 처음 요청이 **완료**가 아닌 다른 마지막 상태, 곧 **실패**, **취소됨**, **중단됨**, **정의 변경으로 미실행**으로 끝났을 때 쓸 수 있습니다. `retryOf` 없이 같은 요청을 다시 보내면 거절합니다. 에이전트는 이 방법으로 다시 요청할 수 없습니다.
+- **owner 확인.** **요청 취소**와 **내려받기**는 이 맥의 웹 화면이나 승인된 기기에서만 동작합니다. 웹 화면은 에이전트 도구 권한과 같은 owner 확인으로 본인임을 증명합니다. 확인에 실패하면 카드가 그렇게 알려 주고, 취소나 내려받기를 하지 않습니다.
+- **에이전트 삭제.** 진행 중인 협업 요청이 있는 에이전트는 지울 수 없습니다. 먼저 취소하거나 끝날 때까지 기다리세요.
+- **비용과 한계.** 요청마다 받은 에이전트의 모델이 실행되므로 일반 차례와 같은 비용이 듭니다. 에이전트가 같은 것을 두 번 물을 수 있고, 게이트웨이는 비슷한 요청을 합치지 않습니다. 결과는 에이전트가 제출한 내용이며 검증된 답이 아닙니다.
+- **Android.** 앱에는 협업 카드가 나오지 않습니다. 대신 채팅에 협업 메시지마다 "협업 요청을 보냈습니다: …", "협업 결과를 받았습니다: …", "협업 요청이 결과 없이 끝났습니다: …" 같은 시스템 줄이 한 줄씩 나옵니다. 이 줄은 폰 알림을 보내지 않습니다.
+
 ## 3. 키보드 단축키
 
 | 키 | 위치(어디서) | 동작 |
@@ -415,8 +509,11 @@ Ctrl 단축키는 Cmd, Alt, Shift와 함께 누르면 동작하지 않습니다.
 - 답을 고르고 보냅니다.
 - "삭제"는 확인 단계를 거쳐 항목을 지웁니다. 답을 기다리는 질문이면 버튼이 "질문 취소하고 삭제"로 바뀝니다.
 - "원문 보기"는 채팅의 질문 카드로 이동합니다.
+- 작업이 필수 질문의 답을 기다리는 동안 main이 그 작업에 새 지시를 보내면, 작업은 새 지시를 바로 처리합니다. 질문은 확인함에 남고, 그 답이 필요한 단계는 답이 올 때까지 기다립니다.
 - 연결이 끊기면 목록은 마지막으로 받은 내용입니다. 답변은 다시 연결된 뒤에 보낼 수 있습니다.
 
+에이전트의 도구 요청(2.11의 도구 권한 참고)은 여기에 **도구 사용 허가** 카드로 나타나며 **이 범위 허용**과 **허용하지 않음** 버튼이 있습니다. **권한 관리**는 그 권한을 열고, **권한 회수**는 권한을 없앱니다. 앱에는 에이전트 전체 편집 화면이 없으므로 범위 편집은 웹에서 합니다. 이 카드를 지원하지 않는 앱은 "이 권한은 웹에서 확인해 주세요"를 보여 줍니다.
+
 ### 4.4 작업 상태 화면
 
 지그 얼굴을 누르면 열립니다. 작업 칸의 상태는 진행 중, 입력 대기, 대기 중, 하위 작업 대기, 응답 없음, 고장, 완료, 실패, 취소됨 등으로 보입니다.
@@ -460,6 +557,12 @@ Ctrl 단축키는 Cmd, Alt, Shift와 함께 누르면 동작하지 않습니다.
 
 게이트웨이 연결 화면의 "매뉴얼" 버튼은 이 문서를 엽니다. 2.10의 '매뉴얼 보기'를 보세요.
 
+### 4.10 Mac 파일
+
+입력창에 `@`를 입력하거나 "Mac 파일"을 누르면 "현재 게이트웨이 Mac 파일" 시트가 열립니다. 이 시트는 폰이 아니라 게이트웨이 Mac의 파일을 보여 줍니다. 폰 이미지 선택과는 별개이며 폰 이미지 선택은 그대로 동작합니다. 등록한 폰에서만 열립니다. 형식, 한도, 규칙은 웹과 같습니다. 2.3의 '이 Mac의 파일'을 보세요. 보낸 파일의 "원본 저장"을 누르면 원본을 폰에 저장합니다.
+
+Mac에서 폰 등록을 취소하면 그 폰은 목록, 선택, 상태 확인, 내려받기, 보내기를 바로 쓸 수 없습니다. 이미 보낸 파일은 권한을 회수하기 전까지 해당 대화에서 계속 읽을 수 있습니다.
+
 ## 5. 공통
 
 ### 5.1 지그에게 일 맡기기
@@ -490,6 +593,7 @@ Ctrl 단축키는 Cmd, Alt, Shift와 함께 누르면 동작하지 않습니다.
 | "업데이트" 버튼이 꺼져 있습니다. | 확인함에 답을 기다리는 질문이 있습니다. "확인함 열기"를 눌러 먼저 답합니다. |
 | 게이트웨이가 시작하지 않고 권한 동의가 없다고 나옵니다. | 맥 터미널에서 `zigmini consent`를 실행합니다. |
 | 앱이 접속하지 못합니다. | 웹 설정의 "외부 접속"을 확인합니다. 방식을 고르지 않으면 폰은 접속할 수 없습니다. 앱에 "인증 거부"가 보이면 폰을 다시 등록합니다. |
+| Mac 파일에 "Mac 접근 권한이 없습니다."가 보입니다. | macOS 개인정보 보호가 게이트웨이의 접근을 막고 있습니다. 시스템 설정 > 개인정보 보호 및 보안의 "파일 및 폴더"나 "전체 디스크 접근 권한"에서 직접 허용합니다. zigmini는 시스템 설정을 바꾸지 않습니다. |
 | 폰 등록이 잠겼습니다. | 웹 화면의 요청 줄에서 "잠금 해제"를 누릅니다. |
 
 ## 6. CLI