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

package/docs/manual.md

@@ -19,7 +19,7 @@ zigmini has two surfaces.
 
 The web screen has three parts.
 
-- Left sidebar: the default agent (main) conversation, the agent group with one conversation per agent, the work status area, your profile and the default agent profile. The "엔진" (engine) badge at the top shows the engine connection.
+- Left sidebar: the default agent (main) conversation, the agent group with one conversation per agent, the work status area, your profile and the default agent profile. While an agent conversation is open, the profile shows that agent's name and icon instead. The "Engine" badge at the top shows the engine connection.
 - Center chat: the header, the message list and the input box.
 - Right panels: the inbox, settings and the event panel open here.
 
@@ -34,7 +34,7 @@ model or saved model profiles; an installed gateway needs an update to receive i
 | --- | --- |
 | Zig face button | Shows work status. At phone width it switches to the work status view. |
 | Model picker | Picks the model the agent uses. If the switch can't happen right away, it happens after the conversation is compacted on your next message. |
-| 새 세션 (new session) | Starts a fresh agent session for this conversation. A confirmation comes first. The history on screen stays, and part of the recent conversation is handed to the new session. |
+| New session | Starts a fresh agent session for this conversation. A confirmation comes first. The history on screen stays, and part of the recent conversation is handed to the new session. In an agent conversation whose definition changed, the button is highlighted and reads "Apply with new session". |
 | 음성 켜짐 / 음성 꺼짐 (voice on/off) | Turns the gateway's voice servers on or off. With voice off, the mic, wake word, clap detection and spoken answers are unavailable. |
 | 음성 설치 (install voice) | Shown only on an npm install without voice. It downloads and installs the voice servers. |
 | 박수 감지 (clap detection) | Two claps turn wake word listening on or off. |
@@ -134,8 +134,12 @@ at the same depth follow their input order.
 Unfinished, invalid or unsupported blocks remain visible as source. When a streamed
 block becomes complete and valid, chat can render it. Diagram text cannot run
 scripts, load URLs or read files. An older client displays the code block instead.
-The concise per-request instruction asks for a diagram only when it helps explain
-a flow or structure; it does not require diagrams in every reply.
+The per-request instruction says that people understand faster when they can see it.
+When a reply explains a flow (order, steps, state changes), a structure (components
+and their relations) or a cause and its result, the agent adds a diagram in this
+`zigmini-diagram` format. Other replies do not require a diagram. When a reply
+compares or summarizes several items by the same criteria (for example current
+state, problem, fix direction), the agent uses a table.
 
 #### Images
 
@@ -145,6 +149,44 @@ a flow or structure; it does not require diagrams in every reply.
 
 You can send up to 4 images at once: PNG, JPEG, GIF or WebP. Images upload when you send.
 
+#### Files on this Mac
+
+Type `@` at the start of the input box or after a space, or click **Mac files**. The **Files on this Mac** picker lists files on the Mac that runs the gateway. It never lists files on your browser's computer or on your phone. There's no extra folder or device to set up. An `@` inside a word, such as an email address, stays plain text, and so do `\@` and `@@`.
+
+The picker opens in `~/Downloads` when it can, and **Home** and **Computer** take you elsewhere. Search covers the current folder only. Hidden files stay out of the list until you turn on **Show hidden files**. Links can't be selected.
+
+| Item | Limit |
+| --- | --- |
+| Formats | `.html`, `.htm`, `.md`, `.markdown`, `.txt`, `.pdf` |
+| File size | 10 MiB per file, not empty |
+| PDF length | 300 pages |
+| One message | 4 different documents, counting documents from referenced messages |
+| Selected but not sent | 16 files and 64 MiB per web or phone client |
+
+Images keep using the separate image button.
+
+The gateway saves a private copy of the file the moment you select it. That copy can't change, so editing the source file afterwards has no effect on it. To send a newer version, select the file again. The gateway never moves or changes the source file.
+
+Each file shows its progress on a chip above the input box. Send waits until every file is **Ready**. If one fails, retry it or remove it. A text file that isn't UTF-8 asks you to **Choose encoding**.
+
+Selecting a file gives no agent access. **Send** lets only the receiving conversation's agent read it. Other conversations and agent clones get nothing, and the file isn't copied into an agent's knowledge or memory. Agents read it with a narrow tool, `zgw_attachment_read`, which can open only the files granted to that conversation. It can't take a path, so an agent can't use it to browse the Mac.
+
+How a PDF reaches the model depends on the model in use. The gateway decides this for you and doesn't switch models:
+
+| Model route | What the model receives | Chip label |
+| --- | --- | --- |
+| Public OpenAI or Anthropic API with PDF input | The PDF itself | **PDF input** |
+| ChatGPT or Claude subscription | Page text plus page images | **Page images** |
+| Text-only model | Page text plus OCR on this Mac | **OCR text** |
+
+The gateway keeps your original copy, and a sent file's name in the message downloads it. HTML is only downloaded, never opened as a page.
+
+To revoke a sent file, press **Revoke** on that file in your sent message and confirm. The file then shows **Unavailable**, whether its delivery was still pending, and what revocation does not take back. Revoking a sent file denies future reads and future downloads. It can't erase what a model has already read, files you've already downloaded, or anything made from the file. Cleanup happens only when you ask for it and moves the files to the macOS Trash. Nothing is deleted automatically.
+
+If a row or chip says **Mac access denied**, macOS privacy protection blocked that location. Other locations keep working. See 5.4.
+
+An older gateway shows **This gateway does not support Mac file attachments.** An older app that receives a sent file shows its name as `[Attached: name]` text.
+
 #### Referencing earlier messages
 
 Right-click a message to attach it as a reference tag above the input box. The message's 참조 (reference) button does the same. You can add up to 4 references. Images from referenced messages plus new attachments can't go over 4 in one send. To drop a tag, click its button, or focus it and press Delete or Backspace.
@@ -298,7 +340,7 @@ A QR for the Android app (APK) shows. Scan it with the phone camera, get the APK
 
 #### Cleanup (정리)
 
-The gateway lists things that are safe to delete: DB backups, engine version folders, leftover update files, temp folders and old RPC daemons. Tick the ones to remove and click 선택한 항목 정리 (clean selected). The 전체 선택 (select all) box beside the count ticks every candidate at once, or clears them all.
+The gateway shows two groups. "Work state" lists unfinished works that the gateway closed on evidence or that need a decision; these rows are read only. A row that needs a decision shows the note "Main will ask you to confirm", and a row the gateway closed shows "Closed from evidence". "Reclaim" lists things that are safe to remove: DB backups, engine version folders, leftover update files, temp folders, archived agent folders, merged worktrees and old gateway Docker images. Tick the ones to remove and click "Clean the selected items". Files and folders go to the macOS Trash. Docker images carry the "Cannot be undone" badge. "Select all" ticks every row you can pick, or clears them all; information rows such as the Docker build cache size can't be picked. "View log" shows the last 20 cleanup records. Old RPC daemons and orphaned test processes are stopped automatically. Details: [Housekeeping](operator.md#housekeeping).
 
 #### Voice settings
 
@@ -331,16 +373,47 @@ Terms: the default agent (main, Zig) is the conversation the gateway has from th
 {"version":1,"title":"Default agent, agents and work sessions","nodes":[{"id":"user","label":"You"},{"id":"main","label":"Default agent (main, Zig)"},{"id":"agent","label":"Agent conversation"},{"id":"work","label":"Work"},{"id":"knowledge","label":"Agent knowledge folder"}],"edges":[{"from":"user","to":"main"},{"from":"user","to":"agent"},{"from":"main","to":"work"},{"from":"agent","to":"knowledge"}]}
 ```
 
+The usual flow: create the agent, upload its material, talk with it, then download what it made.
+
+```zigmini-diagram
+{"version":1,"title":"From a new agent to its outputs","nodes":[{"id":"create","label":"Create (+ Agent)"},{"id":"upload","label":"Upload to knowledge/source/"},{"id":"chat","label":"Talk in the agent conversation"},{"id":"outputs","label":"Download from knowledge/outputs/"}],"edges":[{"from":"create","to":"upload"},{"from":"upload","to":"chat"},{"from":"chat","to":"outputs"}]}
+```
+
 - **Sidebar.** Agents appear in their own group. The **⋯** button beside the group name (or **Agents** at the top of the chat) opens the Agents screen with three views: **List**, **Shared defaults** and **Archive**. You create and edit agents only on this screen: **+ Agent** in **List** creates one, and **Edit** on a row opens its editor. The sidebar and the chat header have no add or edit button. Each agent has exactly one conversation.
-- **Editor.** Name and a one-line purpose are required. Optional fields: icon, model (provider and model ID, both filled or both empty; empty means the gateway's current model), thinking level, skill allow list, web research (web_search, webfetch), app notification when a reply ends, gateway and install rules on or off, and the MEMORY.md size limit (0 to 32768 bytes). Shell and code execution are always off. Each field shows where its value comes from: package default, shared default or this agent. The body is the role instruction.
-- **Changes apply from the next session.** After you edit an agent, its header shows **Definition changed · applies from the next session**. The open session keeps the old definition. Click the badge to start a new session with the edited one.
+- **Conversation.** Replies in an agent conversation carry the agent's name and icon. An agent without an icon shows the first letter of its name.
+- **Editor.** **Name** and **One-line purpose** are required. Optional fields: **Icon**, **Model** (**Provider** and **Model ID**, both filled or both empty; empty means the gateway's current model), **Thinking level**, **Allowed skills**, **Web research (web_search, webfetch)**, **App notification when the reply ends**, the two rule switches **Shared rules** and **Override rules**, and **MEMORY.md limit (bytes)** (0 to 32768). There's no schema version field; the gateway writes it for you. **Shell (prohibited)** and **Code execution (prohibited)** show as switches that stay off, with the reason: shell and code execution bypass the knowledge folder path checks. Each field shows where its value comes from: package default, shared default or this agent. The body is the **Role instructions**. Above it, **How to write role instructions** lists four parts: **Scope**, **Tasks**, **Not to do** and **Form of address**. Write "Call the user ○○" there to change how the agent addresses you; otherwise the profile nickname rule applies.
+- **Allowed skills.** Pick skills from a checklist of the skills installed in the engine. A saved skill that isn't installed stays checked with the mark **not installed**; saving keeps it, and unchecking removes it. If the list can't load, **Try again** appears and the saved values are kept.
+- **What this agent can and cannot do.** A box at the top of the editor lists what the agent **Can** and **Cannot** do with the values you're editing. The gateway computes it as a preview, and it changes as you edit (for example, **Web research (web_search, webfetch)** moves between the two columns with its switch).
+- **Drafts while creating.** While you fill in a new agent, the gateway saves a draft as you type and shows **Draft saved · {time}**. **Reopen a draft ({count})** in **List** brings it back, also from another device. A draft keeps picked files' names and sizes, not their contents, so pick the files again. If saving fails while the editor is closed or reopening, reopening on the same page keeps the latest local text and file list instead of loading an older saved copy. The draft status explains the failure. Check the connection and draft size, then edit to retry saving. Keep this page open without refreshing until **Draft saved · {time}** appears; another page or device can read only the last successful save. Creating the agent closes its draft. Old drafts show up later in **Cleanup** in Settings.
+- **Changes apply from the next session.** After you edit an agent, its header shows the status **⚠ The definition changed** with the note "Press New session to apply the changed definition". The open session keeps the old definition. The **New session** button at the top right is highlighted and reads **Apply with new session**; press it and confirm to start a new session with the edited definition. If the gateway cannot tell which definition the open session applied, the status reads **Cannot confirm whether the definition was applied**, and the button is highlighted the same way; a new session applies the current one. Saving a real change also shows **Apply now** in the editor; after you confirm, it opens the new session at once. Saving without a change says **Nothing changed in the definition.**
 - **Skills.** The "/" menu in an agent conversation hides skills outside its allow list.
-- **Knowledge.** The agent's file tools work only inside its knowledge folder. Upload source files in the agent's editor (**Agents** screen, **List**, **Edit**). With web research on, research notes are saved under `knowledge/notes/` with the source URL beside each fact. An agent can search only its own conversation history.
-- **Clone.** Cloning copies the definition, source files and MEMORY.md into a new agent named "<name> 사본". The conversation isn't copied.
-- **Delete and restore.** To delete, type the agent's exact name. The conversation is hidden, and the definition and knowledge move to **Archive** for 30 days. You can't delete during a running turn or an open question. **Restore** in **Archive** brings the conversation back.
-- **Default agent.** Zig can list agents (name, purpose, link) but can't talk to them. Trashed agents aren't listed.
+- **Knowledge files.** The editor groups the files by location: **Uploaded material** in `knowledge/source/`, **Outputs** in `knowledge/outputs/`, and **Notes** in `notes/, MEMORY.md` (read only). Drop files on the upload area or press **Choose files**; you can pick several files at once, and each row shows its progress. Uploads are saved at once and the agent uses them right away. No new session is needed: the agent gets the list of its files at every turn. If a file with the same name exists, the new one is saved as "name (2)". Files picked on the create screen show **Uploads after creation** and are uploaded right after the agent is created, and the editor of the new agent then shows their progress.
+- **What the agent writes.** The agent reads every file in its knowledge folder but writes only to `outputs/`, `notes/` and `MEMORY.md`; it can't change `source/`. Ask it to save results to `outputs/`. Each file in **Outputs** and **Uploaded material** has **Download**. With web research on, research notes go under `notes/` with the source URL beside each fact. An agent can search only its own conversation history.
+- **Daily notes.** The agent writes `notes/daily/<date>.md` on each day it works. If today's note is missing after a turn, the agent gets a reminder at its next turn. **Notes** shows **Last daily note: {date}**.
+- **Deleting files.** **Delete** on a file in `source/` or `outputs/` moves it to **Deleted files ({count})**, where **Restore** brings it back for 30 days. After that, **Cleanup** in Settings lists it as a candidate, and it goes to the macOS Trash only after you confirm there. There's no replace button: delete the old file and upload the new one.
+- **Duplicate.** **Duplicate** copies the definition, source files and MEMORY.md into a new agent named "<name> copy". The conversation isn't copied.
+- **Delete and restore.** To delete, type the agent's exact name. The conversation is hidden, and the definition and knowledge move to **Archive** for 30 days. After that, **Cleanup** in Settings offers them for the macOS Trash. You can't delete during a running turn or an open question. **Restore** in **Archive** brings the conversation back. If an agent with the same ID already exists (the same agent was deleted twice and one copy was restored), the row explains the conflict and offers **Restore under a new ID**, which keeps both. An existing agent is never overwritten.
+- **Tour.** On first use, a short tour walks through the input box, the sidebar, **New session**, the inbox, **Agents**, **+ Agent** and Settings. Most steps move on when you use the highlighted part: type one character in the input box (nothing is sent) or click the highlighted control. The **New session** step uses the **Next** button instead, because a real click would start a new engine session; a step whose control is missing or disabled also shows **Next**, and a step whose target isn't on the screen is skipped. **Skip** or Esc ends the whole tour. The tour starts once per browser. **Show the tour again** under **Guided tour** in Settings replays it.
+- **Default agent.** Zig can list agents (name, purpose, link) and can send them collaboration requests (see 2.13). Trashed agents aren't listed.
 - **Android.** The app stays on the default agent (main) conversation. Agent conversations are web only for now.
 
+#### Tool permissions
+
+A new agent, or a duplicate, starts with no tool access. When it needs a tool, it asks for it, and the request appears in the inbox as a **Tool access request** card. The card shows **Agent**, **Request source** (**Direct request** or a request from a collaborating agent), **Tool**, **Target**, **Operation** and **Duration** (**Until revoked**).
+
+```zigmini-diagram
+{"version":1,"title":"Tool access from request to result","nodes":[{"id":"need","label":"Agent asks for a tool"},{"id":"check","label":"Gateway checks existing permissions"},{"id":"inbox","label":"Tool access request in the inbox"},{"id":"grant","label":"Allow this scope: permission is kept"},{"id":"deny","label":"Do not allow: nothing runs"},{"id":"run","label":"Recheck, then run once"},{"id":"result","label":"Agent gets the result and continues"},{"id":"edit","label":"Edit scope or Revoke access"}],"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"}]}
+```
+
+- **Persistent permission.** **Allow this scope** keeps the permission for that agent, tool, operation and target until you revoke it. The agent won't ask again for the same target and operation. It doesn't spread to another tool, another agent or another tab. After you allow it, the gateway runs the waiting operation once and the agent continues its original task with the result. **Do not allow** runs nothing ("Access was not granted. Nothing was run."), and the agent won't repeat the same request unless you ask for something new.
+- **Editing and revoking.** The agent editor has a **Tool permissions** section. Each row shows the tool, operations, target, state (**Allowed**, **Applying**, **Revoked**, **Target needs confirmation** or **No access**) and the original confirmation. Turning a row's switch off revokes it at once; open sessions stop using it too, and no new session is needed. **Edit scope** narrows a scope at once. Widening one sends a new request to the inbox ("Approve the added scope"), and only the current scope applies until you allow it. **Revoke access** removes one permission. If an operation is running, the gateway asks it to stop and shows "Access revoked. Stopping the running operation." until the stop is confirmed; it can't undo what already happened. **Revoke all tool access** revokes every permission of the agent and blocks new requests. To use tools again, allow a new request in the inbox; old permissions don't come back.
+- **External actions need their own confirmation.** A tool permission lets the agent use a tool. It doesn't approve a specific post, message, purchase, deletion or settings change. Each such action asks separately in the inbox for its exact content and destination, and that confirmation is used once. If the content or recipient changes, it asks again. Reading and writing in the agent's own knowledge folder don't ask twice.
+- **Existing agents.** Agents made before this version keep their current tools for now. Each one gets a single inbox card that lists its existing scope (the web research setting and the knowledge folder access it had). If you confirm, those become permissions. If you decline, the agent switches to no access. Either way the switch happens when the agent is idle, so a running turn finishes with its old scope. Without an answer nothing changes. The **Web research (web_search, webfetch)** switch no longer grants anything by itself.
+- **Aside tabs.** An agent can read a tab you already have open in Aside only after you pick it. On the request card, press **Load open tabs** and choose the tab under **Choose the target tab**. The tab list is shown to you only; the agent receives just the tab you chose. Reading never clicks, types, moves or closes the tab. Clicking or typing needs a separate permission for the same tab, and posting or sending still needs its own confirmation. If the tab closes or moves to another site, the permission waits as **Target needs confirmation**. For its own work, an agent opens background tabs and closes them when it's done.
+- **Code and commands.** Code execution and shell commands run confined. They can't reach the network, browser profiles, the gateway or its settings, and they see only their own work folder. Permission to run code doesn't replace file, web or browser permissions, and every file or web call inside it is checked again.
+- **Where you can answer.** Answer tool requests on the web screen opened directly at the gateway address. The Android app can answer them too (see 4.3). An older app shows "Review this access request on the web".
+- **Requirements.** This needs the gateway release that contains it and the engine it installs (patch manifest revision 6, engine `5.1.51-zgw.6`). An update to an engine without this support is refused before that engine is activated, and the gateway keeps the previous engine.
+
 ### 2.12 Agent rules
 
 The gateway adds the common rules of the package and this installation's `~/.zigmini/rules.md` to every main and work session.
@@ -350,6 +423,29 @@ Replacing a common rule item: each item in the common rules file has a fixed id
 - `zigmini rules`: lists the common items with number, id and first line.
 - `zigmini rules check`: shows each `rules.md` item as "replaces common N", "new rule" or "unknown id" (exit code 1 when an unknown id exists).
 
+### 2.13 Agent collaboration
+
+Zig can hand a request to an agent, and an agent can ask another agent a question. Each request has its own record, and the reply comes back to the conversation that asked.
+
+```zigmini-diagram The collaboration tools themselves need no **Tool access request**; every other tool still needs your grant. A blocked agent gets none of them.
+{"version":1,"title":"A collaboration request","nodes":[{"id":"asker","label":"Asking conversation (Zig or an agent)"},{"id":"gateway","label":"Gateway request record"},{"id":"agent","label":"Receiving agent"},{"id":"inbox","label":"Inbox (your answer)"}],"edges":[{"from":"asker","to":"gateway"},{"from":"gateway","to":"agent"},{"from":"agent","to":"inbox"},{"from":"inbox","to":"agent"},{"from":"agent","to":"asker"}]}
+```
+
+- **Who may ask whom.** In the agent editor, **Collaboration** > **Agents it may ask** lists the agents this agent may send requests to. The permission goes one way, and the list is empty by default. Zig may ask any agent that isn't archived. An agent may only ask questions; it can't hand out tasks.
+- **Cards in the chat.** Both conversations show a card: **Collaboration request sent** in the asking one and **Collaboration request received** in the other. The card shows **From**, **To**, the kind (**Task** or **Question**), the text, the state and, when it ends, the **Result** with its **Files**. An open page updates the card as the state and result change, without a reload.
+- **States.** **Queued**, **Running**, **Waiting for another agent**, **Waiting for your answer**, **Preparing the result**, **Completed**, **Failed**, **Interrupted**, **Cancel requested**, **Cancelled**, **Delivery unconfirmed** and **Definition changed**. A request counts as **Completed** only when the agent submitted an explicit result; an agent that stops without one leaves the request **Interrupted**, and nothing runs it again.
+- **Your turn comes first.** A request never interrupts a turn you started. It waits and runs after your turn ends.
+- **Questions to you.** When an agent asks you a question while working on a request, only that request (and requests it started) waits as **Waiting for your answer**. Other requests keep running. Answer in the inbox; the request continues once with your answer. A **Tool access request** card the agent asks for while working on a request pauses only that request (and requests it started) as **Waiting for your answer** in the same way, and the request continues once after you answer. After the other agent replies to a request you started, a tool call that needs permission in the agent's next run also shows a **Tool access request** card, marked **Request from a collaboration you started**. Allowing it runs that call once, and the agent continues once.
+- **Result files.** The agent saves files to `outputs/` and lists them in its result. The gateway seals a copy, so later edits in `outputs/` don't change the result. A file the agent received this way appears in its knowledge files as **Collaboration copy**; deleting it removes only that copy.
+- **File read review.** When an agent reads a shared file, the gateway runs the security check on the part it asked for. If the check flags something, the read is held. A PDF page with no text layer can't be checked automatically, so it's held too. The inbox then shows a **File read review** card with **Reading agent**, **File**, **Requested part** and **Security check**. That last row lists only the finding kinds and their counts (for example, **Token / API key: 1**). The flagged values themselves never appear. For an unchecked page, the card asks you to look at it yourself first. **Allow this read** sends that part to the agent once. **Do not allow** sends nothing. If the gateway doesn't accept this browser as the owner, or can't be reached, the card says so. Nothing is processed in the first case, and in the second you should check the latest state. If the hold changed meanwhile, the card loads the latest state; check it and answer again.
+- **Cancel and recheck.** **Cancel request** stops a request and the requests it started. A running request shows **Cancel requested** until the agent has stopped, then **Cancelled**. **Delivery unconfirmed** means the gateway can't tell whether the agent received the request (for example after a restart); it is never sent again on its own. **Recheck** reads the states again. Pressing **Stop** in an agent conversation while it works on a collaboration request cancels that request and the requests it started, just like **Cancel request**.
+- **Ending without a result.** When a request ends as **Cancelled**, **Interrupted** (including a missing result) or **Definition changed**, the asking conversation still gets one final reply. That reply carries the state and the reason, but no text and no files. Nothing is delivered, and nothing runs again. If the asking request is itself finished or being cancelled, it gets no reply.
+- **Asking again.** Only Zig can ask again, and only from the conversation that sent the first request. Zig sends a new request with `retryOf` set to the first request's id. That works when the first request ended in any final state except **Completed**: **Failed**, **Cancelled**, **Interrupted** or **Definition changed**. The same request sent again without `retryOf` is refused. Agents can't ask again this way.
+- **Owner sign-in.** **Cancel request** and **Download** work only from the web page on this Mac or from an approved device. The page proves it is yours with the same owner check as agent tool permissions. If the check fails, the card says so, and nothing is cancelled or downloaded.
+- **Deleting an agent.** An agent that still has open collaboration requests can't be deleted; cancel them or let them finish first.
+- **Cost and limits.** Each request runs the receiving agent's model, so it costs like a normal turn. Agents may ask the same thing twice; the gateway doesn't merge similar requests. Results are what the agent submitted, not a checked answer.
+- **Android.** The app doesn't show collaboration cards. Instead, its chat shows one system line for each collaboration message, such as "Sent a collaboration request: …", "Received the collaboration result: …" or "The collaboration request ended without a result: …". These lines don't send phone notifications.
+
 ## 3. Keyboard shortcuts
 
 | Key | Where | What it does |
@@ -413,8 +509,11 @@ Open it from the inbox icon in the header. The top shows counts for "확인 필
 - Pick an answer and send it.
 - 삭제 removes the item after a confirm step. For a question still waiting, the button reads 질문 취소하고 삭제 (cancel question and delete).
 - 원문 보기 jumps to the question card in chat.
+- When a work waits on a required question and main sends it a new instruction, the work handles the new instruction at once. The question stays in the inbox, and the step that depends on it waits for your answer.
 - While disconnected, the list is the last one received. Answers can be sent after reconnecting.
 
+Tool access requests from agents (see Tool permissions in 2.11) appear here as **Tool access request** cards with **Allow this scope** and **Do not allow**. **Manage access** opens that permission, and **Revoke access** removes it. The app has no full agent editor; use the web for editing scopes. An app that doesn't support these cards shows "Review this access request on the web".
+
 ### 4.4 Work status screen
 
 Tap the Zig face to open it. Slot states include running, waiting for input, waiting, waiting for subtasks, unresponsive, broken, completed, failed and cancelled.
@@ -458,6 +557,12 @@ Tap the Zig face to open it. Slot states include running, waiting for input, wai
 
 The 매뉴얼 button on the gateway connection screen opens this document. See 2.10, Viewing the manual.
 
+### 4.10 Mac files
+
+Type `@` in the input field or tap **Mac files** to open **Files on this gateway Mac**. This sheet lists files on the gateway Mac, not on your phone. It's separate from the phone image picker, which works as before. Only a registered phone can open it. The formats, limits and rules are the same as on the web; see "Files on this Mac" in 2.3. **Save original** on a sent file saves the original to the phone.
+
+If you revoke a phone's registration on the Mac, that phone immediately loses listing, selecting, status, download and send. Files already sent stay readable by their conversation until they're revoked.
+
 ## 5. Common
 
 ### 5.1 Giving work to Zig
@@ -489,6 +594,7 @@ The conversation may keep going while a question waits. If you can't tell whethe
 | The gateway won't start and says consent is missing. | Run `zigmini consent` in the Mac terminal. |
 | The app can't connect. | Check 외부 접속 in web settings. Without a choice, the phone can't connect. If the app shows auth refused, register the phone again. |
 | Phone registration is locked. | Click 잠금 해제 on the request line in the web screen. |
+| A Mac file shows **Mac access denied**. | macOS privacy protection is blocking the gateway from that location. Allow it yourself in System Settings > Privacy & Security, under Files and Folders or Full Disk Access. zigmini never changes System Settings. |
 
 ## 6. CLI
 

package/host/document-reader/DocumentRead.swift

@@ -0,0 +1,370 @@
+import Foundation
+import PDFKit
+import CoreGraphics
+import CoreText
+import Vision
+import ImageIO
+import CryptoKit
+import Darwin
+
+// SIZE_OK: T4's frozen ownership allows only this native module and its document-only entrypoint.
+// Parsing never receives a pathname, URL, password, authority or caller-selected sandbox policy.
+enum DocumentReadFailure: Error {
+    case failed(HelperFailureCode)
+    case isolation
+}
+enum DocumentRead {
+    static func digest(_ data: Data) -> String {
+        SHA256.hash(data: data).map { String(format: "%02x", $0) }.joined()
+    }
+    static func event(_ stage: String, page: Int = 0) {
+        let value = "{\"stage\":\"\(stage)\",\"page\":\(page)}\n"
+        FileHandle.standardError.write(Data(value.utf8))
+    }
+    static func recognizer() throws -> VNRecognizeTextRequest {
+        for revision in VNRecognizeTextRequest.supportedRevisions.sorted(by: >) {
+            let request = VNRecognizeTextRequest()
+            request.revision = revision
+            request.recognitionLevel = .accurate
+            let supported = try request.supportedRecognitionLanguages()
+            if supported.contains("ko-KR") && supported.contains("en-US") {
+                request.recognitionLanguages = ["ko-KR", "en-US"]
+                request.usesLanguageCorrection = true
+                return request
+            }
+        }
+        throw DocumentReadFailure.failed(.ocrFailed)
+    }
+    static func bitmap(width: Int, height: Int) throws -> CGContext {
+        guard width > 0, height > 0, width <= 12_000_000 / height,
+              let context = CGContext(data: nil, width: width, height: height, bitsPerComponent: 8,
+                bytesPerRow: width * 4, space: CGColorSpaceCreateDeviceRGB(),
+                bitmapInfo: CGImageAlphaInfo.premultipliedLast.rawValue) else {
+            throw DocumentReadFailure.failed(.processingLimit)
+        }
+        context.setFillColor(CGColor(gray: 1, alpha: 1))
+        context.fill(CGRect(x: 0, y: 0, width: width, height: height))
+        return context
+    }
+    static func recognize(_ image: CGImage, with request: VNRecognizeTextRequest) throws -> String {
+        do {
+            try VNImageRequestHandler(cgImage: image, options: [:]).perform([request])
+            guard let observations = request.results else { throw DocumentReadFailure.failed(.ocrFailed) }
+            return observations.compactMap { $0.topCandidates(1).first?.string }.joined(separator: "\n")
+        } catch {
+            throw DocumentReadFailure.failed(.ocrFailed)
+        }
+    }
+    // Only fixed trusted data is touched here. No stdin access, document-dependent options or output.
+    // This initializes lazily loaded font/recognition resources before narrowing the process.
+    static func bootstrap() throws -> VNRecognizeTextRequest {
+        event("bootstrap-languages")
+        let request = try recognizer()
+        event("bootstrap-font")
+        let context = try bitmap(width: 1200, height: 400)
+        let font = CTFontCreateWithName("AppleSDGothicNeo-Regular" as CFString, 48, nil)
+        let line = CTLineCreateWithAttributedString(NSAttributedString(
+            string: "TRUSTED BOOTSTRAP 파란 하늘", attributes: [
+                NSAttributedString.Key(kCTFontAttributeName as String): font,
+                NSAttributedString.Key(kCTForegroundColorAttributeName as String): CGColor(gray: 0, alpha: 1)
+            ]))
+        context.textPosition = CGPoint(x: 40, y: 180)
+        CTLineDraw(line, context)
+        guard let image = context.makeImage() else { throw DocumentReadFailure.failed(.ocrFailed) }
+        event("bootstrap-recognize")
+        _ = try recognize(image, with: request)
+        event("bootstrap-complete")
+        return request
+    }
+    static func raster(_ page: PDFPage, ocr: Bool) throws -> CGImage {
+        let bounds = page.bounds(for: .mediaBox)
+        guard bounds.width.isFinite, bounds.height.isFinite, bounds.width > 0, bounds.height > 0 else {
+            throw DocumentReadFailure.failed(.invalidPDF)
+        }
+        let rotated = abs(page.rotation % 180) == 90
+        let width = rotated ? bounds.height : bounds.width
+        let height = rotated ? bounds.width : bounds.height
+        let scale = ocr ? 300.0 / 72.0 : min(1, 1568 / max(width, height))
+        let w = ceil(width * scale), h = ceil(height * scale)
+        guard w.isFinite, h.isFinite, w >= 1, h >= 1, w * h <= 12_000_000,
+              w <= 12_000_000, h <= 12_000_000 else { throw DocumentReadFailure.failed(.processingLimit) }
+        let context = try bitmap(width: Int(w), height: Int(h))
+        guard let reference = page.pageRef else { throw DocumentReadFailure.failed(.invalidPDF) }
+        let destination = CGRect(x: 0, y: 0, width: w, height: h)
+        context.concatenate(reference.getDrawingTransform(.mediaBox, rect: destination, rotate: 0, preserveAspectRatio: true))
+        context.drawPDFPage(reference)
+        guard let image = context.makeImage() else { throw DocumentReadFailure.failed(.processingLimit) }
+        return image
+    }
+    static func jpeg(_ image: CGImage) throws -> Data {
+        let result = NSMutableData()
+        guard let destination = CGImageDestinationCreateWithData(result, "public.jpeg" as CFString, 1, nil) else {
+            throw DocumentReadFailure.failed(.processingLimit)
+        }
+        CGImageDestinationAddImage(destination, image,
+            [kCGImageDestinationLossyCompressionQuality: 0.8] as CFDictionary)
+        guard CGImageDestinationFinalize(destination), result.length <= HelperLimits.imageBytes else {
+            throw DocumentReadFailure.failed(.processingLimit)
+        }
+        return result as Data
+    }
+    static func decode(_ bytes: Data, encoding: DocumentEncoding?) throws -> String {
+        let values = [UInt8](bytes.prefix(3))
+        var bom: DocumentEncoding?, skip = 0
+        if values.starts(with: [0xef, 0xbb, 0xbf]) { bom = .utf8; skip = 3 }
+        else if values.starts(with: [0xff, 0xfe]) { bom = .utf16le; skip = 2 }
+        else if values.starts(with: [0xfe, 0xff]) { bom = .utf16be; skip = 2 }
+        if let bom, let encoding, bom != encoding { throw DocumentReadFailure.failed(.unsupportedEncoding) }
+        let selected = encoding ?? bom ?? .utf8
+        let native: String.Encoding
+        switch selected {
+        case .utf8: native = .utf8
+        case .utf16le: native = .utf16LittleEndian
+        case .utf16be: native = .utf16BigEndian
+        case .eucKR:
+            native = String.Encoding(rawValue: CFStringConvertEncodingToNSStringEncoding(
+                CFStringEncoding(CFStringEncodings.EUC_KR.rawValue)))
+        case .cp949:
+            native = String.Encoding(rawValue: CFStringConvertEncodingToNSStringEncoding(
+                CFStringEncoding(CFStringEncodings.dosKorean.rawValue)))
+        }
+        let data = bytes.dropFirst(skip)
+        guard let text = String(data: data, encoding: native),
+              !text.contains("\0"), let roundtrip = text.data(using: native, allowLossyConversion: false),
+              roundtrip == data else {
+            throw DocumentReadFailure.failed(encoding == nil && bom == nil ? .encodingRequired : .unsupportedEncoding)
+        }
+        return text.replacingOccurrences(of: "\r\n", with: "\n").replacingOccurrences(of: "\r", with: "\n")
+    }
+    // Vision also reads a page's selectable text. Only whole lines the native text lacks are new content.
+    static func addedLines(_ recognized: String, beyond native: String) -> String {
+        let squash = { (line: Substring) in line.filter { !$0.isWhitespace }.lowercased() }
+        let known = Set(native.split(separator: "\n").map(squash))
+        return recognized.split(separator: "\n").filter { !known.contains(squash($0)) }.joined(separator: "\n")
+    }
+    static func handle(_ request: DocumentRequest, recognizer: VNRecognizeTextRequest?,
+                       emit: (HelperFrame) throws -> Void) throws {
+        let original = try request.originalBytes()
+        if request.options.format != .pdf {
+            guard request.options.format != .html,
+                  request.operation == .text || request.operation == .inspect else {
+                throw HelperProtocolError.invalidOperation
+            }
+            let text = try decode(original, encoding: request.options.encoding)
+            if request.operation == .inspect {
+                try emit(.documentComplete(DocumentComplete(requestId: request.requestId,
+                    originalSha256: digest(original), representationSha256: digest(Data(text.utf8)),
+                    coverage: DocumentCoverage(totalPages: 1, pages: [PageCoverage(page: 1, representation: .nativeText)]),
+                    content: [])))
+            } else {
+                try emit(PreparedDocumentText(pages: [PreparedTextPage(page: 1, representation: .nativeText, text: text)]).frame(for: request))
+            }
+            return
+        }
+        guard original.starts(with: Data("%PDF-".utf8)), let pdf = PDFDocument(data: original) else {
+            throw DocumentReadFailure.failed(.invalidPDF)
+        }
+        guard !pdf.isLocked else { throw DocumentReadFailure.failed(.passwordRequired) }
+        guard pdf.pageCount > 0 else { throw DocumentReadFailure.failed(.invalidPDF) }
+        guard pdf.pageCount <= 300 else { throw DocumentReadFailure.failed(.processingLimit) }
+        var prepared: [PreparedTextPage] = [], coverage: [PageCoverage] = [], images: [HelperContent] = []
+        var bytes = 0
+        let first = request.options.firstPage ?? 1
+        let end = min(first + (request.options.pageLimit ?? 2), pdf.pageCount + 1)
+        // A text or OCR call without a range reads the whole document. Pages always use a range.
+        let ranged = request.operation == .pages || (request.operation != .inspect
+            && (request.options.firstPage != nil || request.options.pageLimit != nil))
+        if ranged && first >= end { throw HelperProtocolError.invalidBounds }
+        for index in 0..<pdf.pageCount {
+            if ranged && !(first..<end).contains(index + 1) { continue }
+            try autoreleasepool {
+                event("page-start", page: index + 1)
+                defer { event("page-end", page: index + 1) }
+                guard let page = pdf.page(at: index) else { throw DocumentReadFailure.failed(.invalidPDF) }
+                let native = (page.string ?? "").replacingOccurrences(of: "\r\n", with: "\n").replacingOccurrences(of: "\r", with: "\n")
+                guard !native.contains("\0") else { throw DocumentReadFailure.failed(.invalidPDF) }
+                if request.operation == .pages {
+                    let image = try raster(page, ocr: false)
+                    let data = try jpeg(image)
+                    images.append(.image(HelperImage(data: data.base64EncodedString(), mimeType: .jpeg)))
+                    coverage.append(PageCoverage(page: index + 1, representation: .renderedImage))
+                    return
+                }
+                var text = native, representation: PageRepresentation = .nativeText
+                if request.operation == .ocr {
+                    guard let recognizer else { throw DocumentReadFailure.failed(.ocrFailed) }
+                    event("ocr", page: index + 1)
+                    let recognized = try recognize(raster(page, ocr: true), with: recognizer)
+                    text = "[Page \(index + 1) native]\n\(native)\n[Page \(index + 1) OCR]\n\(addedLines(recognized, beyond: native))\n"
+                    representation = .ocrText
+                }
+                // Empty native text is not a verified blank page. It remains native-text.
+                if request.operation != .ocr && !native.isEmpty { text = "[Page \(index + 1) native]\n\(native)\n" }
+                bytes += text.utf8.count
+                guard bytes <= HelperLimits.preparedTextBytes else { throw DocumentReadFailure.failed(.processingLimit) }
+                prepared.append(PreparedTextPage(page: index + 1, representation: representation, text: text))
+                coverage.append(PageCoverage(page: index + 1,
+                    representation: request.operation == .inspect && native.isEmpty ? .renderedImage : representation))
+            }
+        }
+        switch request.operation {
+        case .text, .ocr:
+            try emit(PreparedDocumentText(pages: prepared, totalPages: pdf.pageCount).frame(for: request))
+        case .inspect:
+            let representation = try PreparedDocumentText(pages: prepared)
+            try emit(.documentComplete(DocumentComplete(requestId: request.requestId, originalSha256: digest(original),
+                representationSha256: representation.sha256,
+                coverage: DocumentCoverage(totalPages: pdf.pageCount, pages: coverage), content: [])))
+        case .pages:
+            let imageData = images.compactMap { item -> Data? in
+                if case .image(let image) = item { return Data(base64Encoded: image.data) }
+                return nil
+            }.reduce(into: Data()) { $0.append($1) }
+            try emit(.documentComplete(DocumentComplete(requestId: request.requestId, originalSha256: digest(original),
+                representationSha256: digest(imageData), coverage: DocumentCoverage(totalPages: pdf.pageCount, pages: coverage),
+                content: images)))
+        }
+    }
+}
+
+#if DOCUMENT_READER_MAIN
+// Custom kernel policy is installed after trusted framework bootstrap, strictly before readRequest.
+// No App Sandbox bundle, protected container, external files, networking or native output directory.
+@_silgen_name("sandbox_init")
+private func documentSandboxInit(_ profile: UnsafePointer<CChar>, _ flags: UInt64,
+                                 _ error: UnsafeMutablePointer<UnsafeMutablePointer<CChar>?>) -> Int32
+@_silgen_name("sandbox_free_error")
+private func documentSandboxFreeError(_ error: UnsafeMutablePointer<CChar>?)
+
+@main struct DocumentReaderEntrypoint {
+    // Vision's precompiled runtime reopens its per-executable model cache and the Neural Engine
+    // client after bootstrap when a page size differs. Those two grants exist only for OCR.
+    static func ocrRules() throws -> String {
+        guard let entry = getpwuid(getuid()), let home = entry.pointee.pw_dir else { throw DocumentReadFailure.isolation }
+        let quoted = URL(fileURLWithPath: String(cString: home)).appendingPathComponent("Library/Caches")
+            .appendingPathComponent(ProcessInfo.processInfo.processName)
+            .appendingPathComponent("com.apple.e5rt.e5bundlecache").resolvingSymlinksInPath().path
+            .replacingOccurrences(of: "\\", with: "\\\\").replacingOccurrences(of: "\"", with: "\\\"")
+        return "(allow file-read* (subpath \"\(quoted)\"))\n(allow iokit-open (iokit-user-client-class \"H11ANEInDirectPathClient\"))\n"
+    }
+    static func isolate(ocr: Bool) throws {
+        let profile = """
+        (version 1)
+        (deny default)
+        (allow signal (target self))
+        (allow sysctl-read)
+        (allow file-read-metadata)
+        (allow file-read* (subpath "/System") (subpath "/usr/lib") (subpath "/usr/share")
+          (subpath "/Library/Fonts") (literal "/dev/null") (literal "/dev/random") (literal "/dev/urandom"))
+        (allow file-map-executable (subpath "/System") (subpath "/usr/lib"))
+        (allow mach-lookup (global-name "com.apple.system.logger") (global-name "com.apple.logd")
+          (global-name "com.apple.FontObjectsServer") (global-name "com.apple.fonts")
+          (global-name "com.apple.cfprefsd.agent") (global-name "com.apple.cfprefsd.daemon")
+          (global-name "com.apple.securityd.xpc") (global-name "com.apple.trustd.agent"))
+
+        """ + (ocr ? try ocrRules() : "")
+        var error: UnsafeMutablePointer<CChar>?
+        let result = profile.withCString { documentSandboxInit($0, 0, &error) }
+        defer { documentSandboxFreeError(error) }
+        guard result == 0 else { throw DocumentReadFailure.isolation }
+        DocumentRead.event("isolated")
+    }
+    // Package gate. Fixed synthetic data only: it reads no stdin, user path or document.
+    static func selfTest() -> Never {
+        var korean = false, english = false
+        for revision in VNRecognizeTextRequest.supportedRevisions {
+            let request = VNRecognizeTextRequest()
+            request.revision = revision
+            request.recognitionLevel = .accurate
+            guard let supported = try? request.supportedRecognitionLanguages() else { continue }
+            korean = korean || supported.contains("ko-KR")
+            english = english || supported.contains("en-US")
+        }
+        let recognizer = try? DocumentRead.bootstrap()
+        var sandbox = false
+        if (try? isolate(ocr: recognizer != nil)) != nil {
+            let descriptor = open("/private/etc/hosts", O_RDONLY)
+            sandbox = descriptor < 0 && (errno == EPERM || errno == EACCES)
+            if descriptor >= 0 { close(descriptor) }
+        }
+        let bytes = NSMutableData()
+        var box = CGRect(x: 0, y: 0, width: 72, height: 72)
+        var pdfkit = false
+        if let consumer = CGDataConsumer(data: bytes), let context = CGContext(consumer: consumer, mediaBox: &box, nil) {
+            context.beginPDFPage(nil)
+            context.endPDFPage()
+            context.closePDF()
+            pdfkit = PDFDocument(data: bytes as Data)?.pageCount == 1
+        }
+        var recognized = false
+        if let recognizer, let image = (try? DocumentRead.bitmap(width: 200, height: 80))?.makeImage() {
+            recognized = (try? DocumentRead.recognize(image, with: recognizer)) != nil
+        }
+        let ok = pdfkit && sandbox && recognized && korean && english
+        print("{\"type\":\"self-test\",\"version\":1,\"pdfkit\":\(pdfkit),\"ocr\":{\"revision\":\(recognizer?.revision ?? 0),\"recognized\":\(recognized),\"ko-KR\":\(korean),\"en-US\":\(english)},\"sandbox\":\(sandbox),\"ok\":\(ok)}")
+        exit(ok ? 0 : 1)
+    }
+    static func main() {
+        do {
+            let arguments = Array(CommandLine.arguments.dropFirst())
+            if arguments == ["--self-test"] {
+                alarm(60)
+                selfTest()
+            }
+            guard arguments.isEmpty || arguments == ["--ocr"] || arguments == ["--isolation-probe"]
+                    || arguments == ["--isolation-probe", "--ocr"] else { exit(64) }
+            alarm(60)
+            // The trusted supervisor selects this fixed nonpath mode, not document content.
+            // Vision routes do not recognize even synthetic bootstrap images.
+            let ocr = arguments.contains("--ocr")
+            let recognizer = ocr ? try DocumentRead.bootstrap() : nil
+            try isolate(ocr: ocr)
+            alarm(0)
+            if let recognizer {
+                FileHandle.standardError.write(Data(
+                    "{\"stage\":\"ocr-config\",\"revision\":\(recognizer.revision),\"languages\":[\"ko-KR\",\"en-US\"]}\n".utf8))
+            }
+            #if DOCUMENT_READER_TESTING
+            if CommandLine.arguments.dropFirst().first == "--isolation-probe" {
+                guard let path = ProcessInfo.processInfo.environment["DOCUMENT_OWNED_PROBE"] else { exit(70) }
+                let fd = open(path, O_RDONLY | O_NOFOLLOW)
+                let fileDenied = fd < 0 && (errno == EPERM || errno == EACCES)
+                if fd >= 0 { close(fd) }
+                let descriptor = socket(AF_INET, SOCK_STREAM, 0)
+                var networkDenied = descriptor < 0 && (errno == EPERM || errno == EACCES)
+                if descriptor >= 0 {
+                    var address = sockaddr_in()
+                    address.sin_len = UInt8(MemoryLayout<sockaddr_in>.size)
+                    address.sin_family = sa_family_t(AF_INET); address.sin_port = UInt16(9).bigEndian
+                    address.sin_addr.s_addr = inet_addr("127.0.0.1")
+                    let result = withUnsafePointer(to: &address) {
+                        $0.withMemoryRebound(to: sockaddr.self, capacity: 1) {
+                            connect(descriptor, $0, socklen_t(MemoryLayout<sockaddr_in>.size))
+                        }
+                    }
+                    networkDenied = result < 0 && (errno == EPERM || errno == EACCES)
+                    close(descriptor)
+                }
+                print("{\"fileDenied\":\(fileDenied),\"networkDenied\":\(networkDenied)}")
+                exit(fileDenied && networkDenied ? 0 : 71)
+            }
+            #endif
+            let request = try HelperCodec.readRequest(from: .standardInput, privilege: .document)
+            guard case .document(let document) = request else { throw HelperProtocolError.wrongPrivilege }
+            let writer = try HelperFrameWriter(request: request, output: .standardOutput)
+            do {
+                try DocumentRead.handle(document, recognizer: recognizer, emit: writer.emit)
+                try writer.finish()
+            } catch DocumentReadFailure.failed(let code) {
+                try writer.emit(.error(HelperFailure(requestId: document.requestId, code: code)))
+                try writer.finish()
+                exit(2)
+            }
+        } catch {
+            // Boundary diagnostics contain only typed stage names, never input, paths or OS identity.
+            DocumentRead.event(error is DocumentReadFailure ? "native-initialization-failed" : "invalid-request")
+            exit(70)
+        }
+    }
+}
+#endif