typeclaw 0.9.2 → 0.11.0

package/src/skills/typeclaw-channel-github/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-channel-github
-description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`. GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
+description: Use this skill BEFORE every `channel_reply` or `channel_send` call whose adapter is `github`, AND before composing replies to GitHub-originated inbounds, AND before opening new issues or PRs with `gh`, AND ALWAYS when an inbound says "requested your review on PR #N" or "requested a review from team @… on PR #N" (the agent has been assigned as a reviewer and must do a real code review with line-by-line comments via `gh api`). GitHub renders **real markdown** — `**bold**`, `## headings`, `| tables |`, fenced code blocks, and `inline code` all render natively. Use rich markdown freely. GitHub cannot send file attachments via API — do not call `channel_send` with attachments on github chats. GitHub has no typing indicator. PR review threads use `thread` keyed on the root comment id; reply to a thread to stay in it, or omit `thread` to post a top-level issue/PR comment. To open new issues or PRs use the `gh` CLI — `GH_TOKEN` is pre-set by the adapter. Read this skill before composing anything on GitHub.
 ---
 
 GitHub renders normal Markdown in issues, PRs, discussions, and review comments. Use headings, lists, tables, fenced code blocks, links, and inline code when they improve clarity.
@@ -22,3 +22,47 @@ gh pr create --repo owner/repo --title "Fix: ..." --head my-branch --base main -
 ```
 
 For App auth, `GH_TOKEN` is an installation access token that refreshes automatically — it stays current as long as the adapter is running.
+
+## Reviewing pull requests
+
+When an incoming message says **"requested your review on PR #N"** (or "requested a review from team @… on PR #N"), you have been assigned as a reviewer. Do a real code review and post line-by-line comments via `gh api`. Do **not** just reply in the channel — the user wants feedback on the diff.
+
+### Workflow
+
+1. **Read the diff and context**:
+
+   ```sh
+   gh pr diff <N> --repo owner/repo
+   gh pr view <N> --repo owner/repo --json title,body,baseRefName,headRefOid,files
+   ```
+
+2. **Submit a multi-comment review** in one API call. `comments[]` accepts line-level entries; each one lands on the diff exactly like a human reviewer's inline comment:
+
+   ```sh
+   gh api -X POST /repos/owner/repo/pulls/<N>/reviews \
+     -F event=COMMENT \
+     -f body="Overall: looks good with a few nits." \
+     -F 'comments[][path]=src/foo.ts' \
+     -F 'comments[][line]=42' \
+     -F 'comments[][side]=RIGHT' \
+     -F 'comments[][body]=nit: prefer `const` here.' \
+     -F 'comments[][path]=src/bar.ts' \
+     -F 'comments[][line]=10' \
+     -F 'comments[][side]=RIGHT' \
+     -F 'comments[][body]=Consider extracting this branch into a helper.'
+   ```
+
+3. **Then** post a one-line summary with `channel_reply` so the conversation has a human-readable trace pointing at the review.
+
+### Rules
+
+- Use `event=COMMENT` by default. Use `APPROVE` only when you have high confidence the PR is ready to merge. Use `REQUEST_CHANGES` only when the PR has clear blockers — not for nits.
+- `line` is a line number **in the file**, not a position in the diff. `side: RIGHT` is the new revision (default for additions); `side: LEFT` is the old revision (use for comments on removed lines).
+- For multi-line comments, also set `start_line` and `start_side` (same semantics).
+- If you need to read whole files at the PR's head SHA, use `gh api /repos/owner/repo/contents/<path>?ref=<headRefOid>`.
+- The bundled `agent-browser` is **not** for PR reviews — `gh api` is faster and more reliable. Only use the browser when the API genuinely can't reach what you need.
+- A `review_request_removed` event means the requester un-assigned you. Stop any in-progress review work; do not post a partial review.
+
+### Self-loop safety
+
+The adapter will **not** wake you when you assign yourself as a reviewer (e.g., via `gh pr edit --add-reviewer`). It will only wake you when someone else requests your review.

package/src/skills/typeclaw-codex-cli/SKILL.md

@@ -65,7 +65,7 @@ Why this works: `~/.codex/auth.json` is the canonical credential location for th
 1. Confirm with the user: "Do you have the `codex` CLI installed on your local machine and are you signed in to it with your ChatGPT subscription? If not, install with `npm install -g @openai/codex`, then `codex login` and complete the browser authorization."
 2. Once they confirm, instruct them: "On your machine, the file at `~/.codex/auth.json` now contains your credential. Paste its contents back to me — it's a small JSON object with an `OPENAI_API_KEY` field, OR a `tokens` object with `access_token` / `refresh_token` / `id_token`. Either shape is valid. Treat it like a password (the `access_token` if present is short-lived but the `refresh_token` is long-lived)."
 3. When they paste, **validate** before writing: it must `JSON.parse` cleanly into an object with at least one of `{ OPENAI_API_KEY, tokens }`. If neither field is present, refuse and ask again — the user may have pasted only a fragment.
-4. **Write to `~/.codex/auth.json` inside the container**, not `.env`. Create `~/.codex/` first if missing. Use `acknowledgeGuards: { nonWorkspaceWrite: true }` (the `~/.codex/` dir is outside `workspace/`).
+4. **Write to `~/.codex/auth.json` inside the container**, not `.env`. Create `~/.codex/` first if missing. Use `acknowledgeGuards: { nonWorkspaceWrite: true }` (the `~/.codex/` dir is outside `workspace/`). `~/.codex/auth.json` is symlinked by typeclaw's entrypoint shim to a host-side persistent path, so this write survives container restarts and codex's in-place token refreshes "just work" — see `references/auth-flow.md` "Persistence across container restarts" for the full mechanism.
 5. **Verify** by re-reading the file and re-parsing.
 6. **Ask before restart** (same prompt as the API key path).
 7. On yes → call the `restart` tool. On no → `typeclaw restart` themselves when ready.

package/src/skills/typeclaw-codex-cli/references/auth-flow.md

@@ -99,6 +99,17 @@ There's also a `codex login --device-auth` flag for headless / cross-machine cas
 
 11. **Done.** There is no auth scratch directory, no tmux session to tear down, no worktree. The OAuth path has the same on-disk footprint as the API-key path: one credential file under `$HOME`.
 
+### Persistence across container restarts
+
+`~/.codex/auth.json` inside the container is a symlink — installed by `typeclaw`'s entrypoint shim on every boot — pointing at `/agent/.typeclaw/home/.codex/auth.json`, which lives in the bind-mounted agent folder on the host. Two consequences:
+
+1. **You only paste auth.json once.** After the first successful write, `typeclaw restart` (or `typeclaw stop && typeclaw start`) preserves the credential without any further user action. Re-pasting is only needed when the refresh token itself is revoked (the user `/logout`s from their ChatGPT account, or the token expires after ~one year of inactivity).
+2. **Codex's in-place refresh "just works."** When codex rotates tokens (it rewrites `auth.json` with a refreshed access token plus the updated refresh-token state), the write goes through the symlink and lands on the persistent host-side path. On the next container start the symlink resolves back to the same file, so refreshes compound across runs the same way they do on a persistent CI runner — this is the pattern OpenAI's own [Codex CI/CD auth guide](https://developers.openai.com/codex/auth/ci-cd-auth) prescribes.
+
+You do not need to do anything to enable this — the symlink is unconditional and idempotent, installed before the agent process ever starts. The persistent directory is gitignored (`.typeclaw/home/` in the generated `.gitignore`) so the credential never enters version control even though it sits inside the agent folder.
+
+If the user asks "won't I lose auth.json on restart?" the answer is "no — it's symlinked to a host-side path; only `workspace/` and the container's regular `$HOME` are ephemeral."
+
 ## Failure modes on the user's side
 
 These all surface as the user's reply being an error message instead of a JSON object. Recognize them, do not validate them as credentials, and respond with the matching guidance.
@@ -126,6 +137,8 @@ These all surface as the user's reply being an error message instead of a JSON o
 - **Do not advise the user to `typeclaw shell` and run `codex login` inside the container as a "fallback".** It does not work — the container has no browser. Use the user-machine flow.
 - **Do not assume the `auth.json` schema.** OpenAI may change the shape — today's keys are `OPENAI_API_KEY` and `tokens.{access_token, refresh_token, id_token}`, but future versions may add or rename fields. Validate by presence of at least ONE known key, not by exhaustive shape match.
 - **Do not write to `~/.codex/auth.json` without `acknowledgeGuards: { nonWorkspaceWrite: true }`.** Same guard contract as `.env` writes.
-- **Do not patch-edit `~/.codex/auth.json`.** Read-modify-write the whole file (or just write the new contents wholesale — there's nothing to preserve from a stale `auth.json` on a fresh delegation).
+- **Do not patch-edit `~/.codex/auth.json`.** Read-modify-write the whole file (or just write the new contents wholesale — there's nothing to preserve from a stale `auth.json` on a fresh delegation). Note that `~/.codex/auth.json` is a symlink into `/agent/.typeclaw/home/.codex/auth.json` — your write follows the link automatically and lands at the persistent host-side path, which is exactly what you want.
+- **Do not move, delete, or replace the `~/.codex/auth.json` symlink with a real file.** The entrypoint shim re-establishes it on every container start, so any in-container `mv`/`cp`/`rm -f && touch` against the link is at best wasted work and at worst loses the credential on the next restart. Write THROUGH the symlink instead.
+- **Do not write directly to `/agent/.typeclaw/home/`.** That path is a system-owned directory managed by the entrypoint shim. Use the `$HOME`-side path (`~/.codex/auth.json`) and let the symlink do its job. The persistent root may move or be renamed across typeclaw versions; the `$HOME` path is the stable contract.
 - **Do not store `OPENAI_API_KEY` in `~/.codex/auth.json`'s `OPENAI_API_KEY` field as a workaround for env-var precedence.** If the user wants the API-key path, the canonical location is `.env`. Mixing the two creates ambiguity for the next person debugging an auth failure.
 - **Do not branch on local-vs-remote container topology.** The user-machine flow is the same whether the container is on the user's laptop or on a remote host — the user runs `codex login` on whatever local machine they're at, the credential works in either container.

package/src/skills/typeclaw-config/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-config
-description: "Read or edit typeclaw.json: model, port, mounts, plugins, channels (per-adapter engagement and history; access control lives in roles — see typeclaw-permissions), portForward (auto port forwarding policy), docker.file (tmux/gh/python/ffmpeg toggles + append), git.ignore.append. Also: any question about a default value or whether a behavior is already on by default — port forwarding, channel visibility, model choice, container packages (tmux/gh/python on by default; ffmpeg off), anything ending in 'by default', 'automatically', 'out of the box', 'do I need to configure', 'is X on', 'what does X default to', '기본값', '기본적으로', '자동으로', '디폴트'. MUST load before saying you do not know what X defaults to, or proposing to add a field whose default the user is asking about — most fields already default to the behavior the user expects (portForward defaults to forwarding every container LISTEN; tmux/gh/python are pre-installed in the container; no edit needed). Read it before touching typeclaw.json — strict schema, mix of live-reloadable and restart-required fields."
+description: "Read or edit typeclaw.json: model, port, mounts, plugins, channels (per-adapter engagement and history; access control lives in roles — see typeclaw-permissions), portForward (auto port forwarding policy), docker.file (tmux/gh/python/ffmpeg toggles + append), git.ignore.append. Also: any question about a default value or whether a behavior is already on by default — port forwarding, channel visibility, model choice, container packages (tmux/gh/python on by default; ffmpeg off), anything ending in 'by default', 'automatically', 'out of the box', 'do I need to configure', 'is X on', 'what does X default to', '기본값', '기본적으로', '자동으로', '디폴트'. MUST load before saying you do not know what X defaults to, or proposing to add a field whose default the user is asking about — most fields already default to the behavior the user expects (portForward defaults to forwarding every container LISTEN; tmux/gh/python are pre-installed in the container; no edit needed). Also covers recommended host paths to mount for common use cases (voice memos for STT, screenshots, mail, iMessage, notes vaults, downloads) with macOS/Linux/WSL paths and TCC/Full-Disk-Access gotchas — load when user describes a use case like 'transcribe my voice memos', 'triage my mail', 'mount my notes', 'let you see my screenshots', or asks 'what should I mount?'. Read it before touching typeclaw.json — strict schema, mix of live-reloadable and restart-required fields."
 ---
 
 # typeclaw-config
@@ -126,6 +126,12 @@ The `mounts/` directory itself is **gitignored** in your agent folder. The mount
 1. **Read `typeclaw.json`**, list each mount: `name`, `path`, `readOnly`, `description`.
 2. Optionally `ls mounts/` to confirm what is actually present right now (a mount won't appear until the next `typeclaw start` after it was added).
 
+### Common host paths to recommend
+
+When the user describes a use case rather than naming a path — "transcribe my voice memos", "triage my mail", "look at my screenshots", "search my notes" — consult `references/recommended-mounts.md` for the canonical path per macOS/Linux/WSL, the `readOnly` default, and the macOS TCC / Full-Disk-Access gotchas (Mail, Messages, Calendars, Contacts, Safari all need FDA granted to Docker Desktop / OrbStack on the host). The reference also covers anti-patterns specific to host paths (don't mount `~` or `~/.ssh/` wholesale, `/Volumes/` is fragile under ejection, iCloud Drive paths lazy-load and may surface as 0-byte stubs). These complement the schema/correctness anti-patterns in `## Things you must not do` below.
+
+The reference is **a lookup table, not a wishlist** — recommending a path there is not a license to add the mount silently. The user still has to ask, you still follow the standard procedure (read file, check collisions, pick name, append, write, commit, restart-required), and you still surface the TCC/FDA requirement before promising the agent can read FDA-gated data.
+
 ## Channels
 
 `channels` configures which external messenger adapters are enabled and how the engagement layer should behave on each. **Access control lives in `roles`, not here** — to admit a chat, declare a role match-rule that covers it (see `typeclaw-permissions`). The shape is `channels: { "<adapter-id>": { engagement, history, enabled } }`. Today the adapters are `discord-bot`, `slack-bot`, `telegram-bot`, and `kakaotalk`.

package/src/skills/typeclaw-config/references/recommended-mounts.md

@@ -0,0 +1,233 @@
+# Recommended mounts — common host paths
+
+Deep dive on what host paths are worth recommending when the user asks "what should I mount?" or, more often, when the user describes a use case ("I want you to transcribe my voice memos", "help me triage my mail", "look at my screenshots") and you need to know the canonical path, the `readOnly` default, and the platform-specific gotchas before editing `typeclaw.json`.
+
+Read it when `SKILL.md`'s **Mounts** section sends you here. It is **not** a list of mounts to add silently — every recommendation here still requires the user to ask for it. Adding mounts the user did not request is a security surprise (see `SKILL.md` "Things you must not do").
+
+## How to use this file
+
+When the user describes a use case:
+
+1. **Find the matching row below.** If the use case isn't here, fall through to the general procedure in `SKILL.md` (pick a kebab-case name, pick `readOnly`, append the entry, restart-required).
+2. **Read the row's platform-specific path.** Apple has moved several of these paths across macOS versions; pick the right one for the user's `sw_vers` (you can ask, or have them run it on the host).
+3. **Honor the `readOnly` default.** Most recommendations here lean `readOnly: true` because the use case is "give the agent eyes on this data" not "let the agent rewrite it." If the user explicitly wants read-write, flip it — but say so.
+4. **Surface the gotchas before writing.** TCC/Full Disk Access for protected paths, iCloud lazy-download for `Mobile Documents/`, ejection-fragility for `/Volumes/`. Saying "I'll add the mount — note that this path needs Full Disk Access granted to Docker Desktop, otherwise the bind mount succeeds but reads will fail with EPERM" is the whole point of this file.
+5. **Then follow the standard Mounts procedure** in `SKILL.md` (read file, check collisions, pick name, append, write, commit, restart-required).
+
+## macOS: Transparency, Consent, Control (TCC) and Full Disk Access
+
+Several juicy macOS paths — Mail, Messages, Calendars (macOS 14+), Contacts, Safari, Reminders, Photos — are gated by macOS's **TCC** subsystem. Apple's rule: the application that opens the file needs to be in System Settings → Privacy & Security → **Full Disk Access** (FDA). For typeclaw, that application is **Docker Desktop** (or **OrbStack** if the user is on OrbStack), because Docker is what mounts the path into the container.
+
+What this means operationally:
+
+- **The mount itself always succeeds.** Docker's bind mount is a kernel-level bind, not a file-open. The agent will see the path appear at `mounts/<name>/` after `typeclaw restart`.
+- **`ls` may show files, but `read` returns EPERM.** When FDA is not granted, the container process can stat the directory but fails on actual file `open(2)`. The agent's `read` tool surfaces this as "Permission denied" and the agent looks like it's lying about being able to read the mount.
+- **There is no in-container fix.** FDA is a per-application macOS preference set on the host. The user has to open System Settings, find Docker Desktop / OrbStack in Full Disk Access, toggle it on, and **restart Docker** (toggling FDA does not retroactively re-permission a running Docker daemon).
+
+When recommending an FDA-gated path, say so up front: "This requires you to grant Docker Desktop Full Disk Access in System Settings → Privacy & Security, then restart Docker. Without that, I'll see the directory but get EPERM on every file."
+
+OrbStack users: same rule, OrbStack appears in the FDA list as "OrbStack Helper" or "OrbStack" depending on version.
+
+The rows below mark FDA-gated paths with **"FDA"** in the TCC column.
+
+## Tier 1 — high signal, low friction
+
+Use cases the user will ask about often, with paths that don't need TCC grants (or only need the standard Documents/Desktop prompts macOS already pops on first access).
+
+### Voice memos — pairs with the `stt` skill
+
+| Platform      | Path                                                                      | `readOnly` | TCC | Notes                                                                                                                                                                            |
+| ------------- | ------------------------------------------------------------------------- | ---------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS (12+)   | `~/Library/Group Containers/group.com.apple.VoiceMemos.shared/Recordings` | `true`     | —   | The group container path. **Not** the old `~/Library/Application Support/com.apple.voicememos` (removed in macOS 12). Includes iCloud-synced recordings from iPhone Voice Memos. |
+| macOS (older) | `~/Library/Application Support/com.apple.voicememos/Recordings`           | `true`     | —   | Only on macOS 11 and earlier. If both paths exist on a newer machine, prefer the group container — the old one is a stale copy.                                                  |
+| Linux         | (no native equivalent)                                                    | —          | —   | If the user records via `pw-record` / `pactl`, point them at their chosen output dir.                                                                                            |
+| WSL           | `/mnt/c/Users/<name>/Documents/Sound recordings/` (Voice Recorder app)    | `true`     | —   | Windows Voice Recorder's default.                                                                                                                                                |
+
+Pair with the `stt` skill — once mounted, the agent can transcribe meetings/notes via Soniox.
+
+### Screenshots — quick visual context
+
+| Platform                | Path                                                              | `readOnly` | TCC | Notes                                                                                                                              |
+| ----------------------- | ----------------------------------------------------------------- | ---------- | --- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| macOS                   | `~/Desktop` (default)                                             | `true`     | —   | macOS Screenshots default to Desktop. Mount the whole Desktop or filter narrower if the user has a lot of unrelated stuff there.   |
+| macOS (custom location) | Run `defaults read com.apple.screencapture location` on the host. | `true`     | —   | Common moved locations: `~/Pictures/Screenshots`, `~/Documents/Screenshots`. Ask the user to run the `defaults` command if unsure. |
+| Linux (GNOME)           | `~/Pictures/Screenshots`                                          | `true`     | —   | Default for GNOME Screenshot, KDE Spectacle.                                                                                       |
+| WSL                     | `/mnt/c/Users/<name>/Pictures/Screenshots/`                       | `true`     | —   | Windows Win+Shift+S → Snipping Tool save location.                                                                                 |
+
+Useful with multimodal models: "look at this screenshot and explain the error."
+
+### Downloads — ad-hoc file ingestion
+
+| Platform | Path                             | `readOnly`       | TCC | Notes                                                                                                                                                                                                                                                 |
+| -------- | -------------------------------- | ---------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS    | `~/Downloads`                    | `true` (usually) | —   | "Process the file I just downloaded." Read-only by default — the agent doesn't normally need to write here. macOS may prompt the user once on first container access (TCC prompt for Downloads), but it's a normal user-acknowledged prompt, not FDA. |
+| Linux    | `~/Downloads`                    | `true` (usually) | —   | XDG-spec location.                                                                                                                                                                                                                                    |
+| WSL      | `/mnt/c/Users/<name>/Downloads/` | `true` (usually) | —   | Windows default Downloads folder.                                                                                                                                                                                                                     |
+
+### Obsidian vault — second-brain workflows
+
+**Highly recommended** for users on Obsidian. The storage is plain markdown files in a folder, which is exactly what mounts are good at (no opaque formats, no proprietary databases, no encryption layer). Triggers: "my Obsidian vault", "my second brain", "search my notes", "summarize my daily note", "my vault is on iCloud".
+
+| Platform              | Path                                                                                     | `readOnly`                                           | TCC | Notes                                                                                                                                                                                                                                                                                                                                                |
+| --------------------- | ---------------------------------------------------------------------------------------- | ---------------------------------------------------- | --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS — iCloud-synced | `~/Library/Mobile Documents/iCloud~md~obsidian/Documents/<VaultName>`                    | `false` (RW for editing) or `true` (RO for research) | —   | The canonical Obsidian-on-Apple-devices path. The literal example to use when the user says "my Obsidian vault" without further qualifier — this is where Obsidian Sync and iCloud both land. **iCloud lazy-loads.** Files the user hasn't opened recently may appear as 0-byte stubs until iCloud materializes them; see the anti-patterns section. |
+| macOS — local vault   | `~/Documents/<VaultName>` or `~/Obsidian/<VaultName>`                                    | as above                                             | —   | For users who keep their vault out of iCloud. No lazy-load gotcha.                                                                                                                                                                                                                                                                                   |
+| macOS — Obsidian Sync | (same as the local vault path the user chose)                                            | as above                                             | —   | Obsidian Sync syncs in place — the path is wherever the user pointed Obsidian at, NOT a separate sync directory. Ask if unsure.                                                                                                                                                                                                                      |
+| Linux                 | `~/Documents/<VaultName>` or `~/Obsidian/<VaultName>`                                    | as above                                             | —   | Linux Obsidian is the same Electron app; vault is wherever the user pointed it.                                                                                                                                                                                                                                                                      |
+| WSL                   | `/mnt/c/Users/<name>/Documents/<VaultName>` or `~/Documents/<VaultName>` on the WSL side | as above                                             | —   | If the vault lives on the Windows side, beware 9p slowness — large vaults (thousands of notes) are noticeably laggy on directory traversal. Also CRLF line endings if Windows-side editors touched the files.                                                                                                                                        |
+
+If the user wants the agent to actively edit notes (write daily logs, refile, link), use `readOnly: false`. If they want pure read access for question-answering or research synthesis, use `readOnly: true`. **Always ask which** — the difference is large in practice (a misconfigured RW mount can silently rewrite the user's notes; a misconfigured RO mount can't help them refile).
+
+**Special files in an Obsidian vault** to be aware of: `.obsidian/` (per-vault config, plugins, themes — leave it alone unless the user is debugging an Obsidian setting), `.obsidian/workspace.json` (active panes, mutated constantly while Obsidian is open — don't write to it from the agent or you'll race Obsidian itself), `.trash/` (Obsidian's local trash, gitignored by most users).
+
+### Other personal notes vaults (plaintext, Logseq, etc.)
+
+For users on plain markdown without Obsidian, on Logseq, or on a custom vault structure:
+
+| Platform | Path                                                    | `readOnly`                                           | TCC | Notes                                                                                                                      |
+| -------- | ------------------------------------------------------- | ---------------------------------------------------- | --- | -------------------------------------------------------------------------------------------------------------------------- |
+| macOS    | `~/Documents/<VaultName>` or wherever the user keeps it | `false` (RW for editing) or `true` (RO for research) | —   | If the user wants the agent to edit notes, `false`. If they only want the agent to read/search, `true`. Default to asking. |
+| Linux    | `~/Documents/<VaultName>` or wherever the user keeps it | as above                                             | —   | No iCloud quirks.                                                                                                          |
+| WSL      | `/mnt/c/Users/<name>/Documents/<VaultName>`             | as above                                             | —   | Be aware of CRLF line endings on files originating from Windows-side editors.                                              |
+
+For **Logseq**, the vault is plain markdown (or org-mode) — same shape as the table above, just point at the Logseq graph directory.
+
+### Code repo — already the canonical example
+
+| Platform | Path                                               | `readOnly`        | TCC | Notes                                                                                                                                                                                                        |
+| -------- | -------------------------------------------------- | ----------------- | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| any      | `~/workspace/<repo>` or wherever the user keeps it | `false` typically | —   | The standard "let me code on X" use case. Already covered in the example in `SKILL.md`. The mount is the host repo, so commits inside `mounts/<repo>/` go to the host repo's history (not the agent folder). |
+
+## Tier 2 — privacy-sensitive, FDA-gated
+
+These are powerful but cross a real privacy boundary. **Always recommend `readOnly: true`** unless the user has a specific reason to write. **Always surface the FDA requirement** before editing `typeclaw.json` — the user needs to grant Docker Desktop / OrbStack Full Disk Access on the host, or the mount will read EPERM on every file.
+
+Treat the act of suggesting these as a moment to pause and confirm. They are answers to "I want the agent to triage my mail / search my iMessages / scan my contacts", not defaults.
+
+### macOS Mail — local mailboxes
+
+| Platform                           | Path                                                        | `readOnly` | TCC     | Notes                                                                                                                                                                                |
+| ---------------------------------- | ----------------------------------------------------------- | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| macOS 14+ (Sonoma, Sequoia, Tahoe) | `~/Library/Mail/V10`                                        | `true`     | **FDA** | The `V10` directory holds per-account `.mbox`-like dirs containing `.emlx` files (one per message). The format is parseable as RFC822 + a small Apple-specific binary plist trailer. |
+| macOS 13 (Ventura)                 | `~/Library/Mail/V9`                                         | `true`     | **FDA** | Same shape, older version dir.                                                                                                                                                       |
+| macOS ≤12                          | `~/Library/Mail/V8` or earlier                              | `true`     | **FDA** | Same shape.                                                                                                                                                                          |
+| Linux — Thunderbird                | `~/.thunderbird/<profile>.default-release/Mail/`            | `true`     | —       | `.msf` index + `mbox` files. No TCC.                                                                                                                                                 |
+| Linux — Evolution                  | `~/.local/share/evolution/mail/`                            | `true`     | —       | Maildir layout. No TCC.                                                                                                                                                              |
+| WSL — Outlook (Win32)              | `/mnt/c/Users/<name>/AppData/Local/Microsoft/Outlook/*.pst` | `true`     | —       | PST is a proprietary binary format; the agent needs `libpff` or similar to read it. Not as plug-and-play as `.emlx`. Warn the user.                                                  |
+
+If unsure which `V<n>` the user has, ask them to run `ls ~/Library/Mail/` on the host — there's usually only one.
+
+### macOS Mail downloads — saved attachments
+
+Mail.app stores attachments the user explicitly opened or saved in a separate location from the `V<n>` tree. Useful when the user says "the attachment from that email" — `V10/`'s per-message `Attachments/` subdirs are lazy and may not have the file, but Mail Downloads is a flat dir of explicitly-saved files.
+
+| Platform | Path                                                               | `readOnly` | TCC | Notes                                                                                                                                                                                  |
+| -------- | ------------------------------------------------------------------ | ---------- | --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS    | `~/Library/Containers/com.apple.mail/Data/Library/Mail Downloads/` | `true`     | —   | Sandboxed app container path. **No FDA needed** — the app container is owned by the user and accessible without TCC grant. Complements the `V10/` mount for users who triage by email. |
+
+This is the path Mail.app uses when the user clicks "Save All Attachments" or drags an attachment to Finder. Files here are flat (PDF, docx, images, etc.) — no envelope/header parsing required, unlike `V10/`'s `.emlx` format.
+
+### macOS Reminders
+
+Parallel to Calendar — the raw Reminders store on disk. **Prefer the Reminders API via AppleScript or `gws-` skills** when those work; this is the fallback for direct introspection.
+
+| Platform    | Path                   | `readOnly` | TCC                   | Notes                                                                                                                                   |
+| ----------- | ---------------------- | ---------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS 14+   | `~/Library/Reminders/` | `true`     | **FDA**               | TCC began gating Reminders alongside Calendar in macOS 14. SQLite-backed; mount the parent dir for WAL sidecars (`.db-wal`, `.db-shm`). |
+| macOS ≤13   | `~/Library/Reminders/` | `true`     | — (no FDA prompt yet) | Same path, no FDA needed.                                                                                                               |
+| Linux / WSL | —                      | —          | —                     | No native equivalent.                                                                                                                   |
+
+If the user is on a Google or Microsoft to-do system instead of native Reminders, those flow through their own APIs — this mount is specifically for native macOS Reminders.
+
+### iMessage history
+
+| Platform    | Path                                                               | `readOnly` | TCC     | Notes                                                                                                                                                                                                                                                                                                              |
+| ----------- | ------------------------------------------------------------------ | ---------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| macOS       | `~/Library/Messages` (the **whole directory**, not just `chat.db`) | `true`     | **FDA** | The history is SQLite at `chat.db`. **Mount the parent dir, not just the db file** — SQLite uses `chat.db-wal` and `chat.db-shm` sidecar files for write-ahead logging, and mounting just `chat.db` will give you a frozen or corrupt-looking snapshot. Attachments live under `Attachments/` inside the same dir. |
+| Linux / WSL | —                                                                  | —          | —       | No equivalent (iMessage is Apple-only).                                                                                                                                                                                                                                                                            |
+
+Tell the user: this exposes every iMessage thread on the device. Highly sensitive. Make sure they're sure.
+
+### macOS Calendar (raw CalDAV store)
+
+| Platform    | Path                  | `readOnly` | TCC                   | Notes                                                                  |
+| ----------- | --------------------- | ---------- | --------------------- | ---------------------------------------------------------------------- |
+| macOS 14+   | `~/Library/Calendars` | `true`     | **FDA**               | TCC began gating Calendars at macOS 14. ICS-format files per calendar. |
+| macOS ≤13   | `~/Library/Calendars` | `true`     | — (no FDA prompt yet) | Same path, no FDA needed.                                              |
+| Linux / WSL | —                     | —          | —                     | No native equivalent on these platforms.                               |
+
+**Prefer the `gws-calendar` skill** if the user is on Google Workspace — it's API-backed, no FDA, and writes are first-class. This raw mount is for users on iCloud-only or CalDAV (e.g. Fastmail) calendars where Google's API doesn't reach.
+
+### macOS Contacts
+
+| Platform    | Path                                        | `readOnly` | TCC     | Notes                                                                                                     |
+| ----------- | ------------------------------------------- | ---------- | ------- | --------------------------------------------------------------------------------------------------------- |
+| macOS       | `~/Library/Application Support/AddressBook` | `true`     | **FDA** | SQLite + per-source dirs. Same warning as iMessage on `.db-wal`/`.db-shm` sidecars — mount the whole dir. |
+| Linux / WSL | —                                           | —          | —       | No native equivalent.                                                                                     |
+
+Pairs awkwardly with `gws` Google Contacts if the user syncs both — there will be two sources of truth. Ask what they actually want before mounting.
+
+### Safari bookmarks / reading list
+
+| Platform    | Path               | `readOnly` | TCC     | Notes                                                                                                                                                                                                                      |
+| ----------- | ------------------ | ---------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| macOS       | `~/Library/Safari` | `true`     | **FDA** | `Bookmarks.plist` (binary plist, parseable with `plutil -convert json` if `plutil` is available, or with a Node plist parser inside the container). Reading list is in the same file. History is in `History.db` (SQLite). |
+| Linux / WSL | —                  | —          | —       | No Safari on these platforms. For Chrome/Firefox bookmarks see below.                                                                                                                                                      |
+
+### Browser bookmarks (cross-platform)
+
+| Platform        | Path                                                                          | `readOnly` | TCC | Notes                                                                   |
+| --------------- | ----------------------------------------------------------------------------- | ---------- | --- | ----------------------------------------------------------------------- |
+| macOS — Chrome  | `~/Library/Application Support/Google/Chrome/Default/Bookmarks`               | `true`     | —   | JSON file. No FDA.                                                      |
+| Linux — Chrome  | `~/.config/google-chrome/Default/Bookmarks`                                   | `true`     | —   | Same JSON format.                                                       |
+| WSL — Chrome    | `/mnt/c/Users/<name>/AppData/Local/Google/Chrome/User Data/Default/Bookmarks` | `true`     | —   | Same JSON.                                                              |
+| macOS — Firefox | `~/Library/Application Support/Firefox/Profiles/<profile>/places.sqlite`      | `true`     | —   | SQLite. Mount the parent profile dir, not just the file (WAL sidecars). |
+
+## Things that look mountable but aren't (recommend export)
+
+Apps whose storage is opaque, proprietary, or actively-mutated-by-the-app-while-running. For all of these, the **clean recommendation is "export from the app and mount the export"**, not "mount the raw store." A few are technically parseable raw, but the schema can shift between app versions and the read-side complexity rarely earns its keep.
+
+- **Apple Notes** (`~/Library/Group Containers/group.com.apple.notes/`) — stored as encrypted SQLite (`NoteStore.sqlite`) with content in protobuf blobs. Even with FDA, the format is not usefully readable without Apple's notes-decryption logic. The clean path is **export from Apple Notes app** (File → Export → PDF/HTML) into a regular directory, then mount that. Alternative: AppleScript / `osascript` driven from the host. Don't recommend mounting the raw container.
+- **Photos library** (`~/Pictures/Photos Library.photoslibrary`) — a `.photoslibrary` package containing SQLite metadata and a content-addressed blob store. Mountable, but reading photos by user-visible name requires querying `Photos.sqlite` and joining against the blob store. Recommend the user **export albums** to a flat dir, or use `osxphotos` on the host to dump metadata. Like Notes, the raw package isn't agent-friendly.
+- **Ulysses** (`~/Library/Containers/com.ulyssesapp.mac/Data/Library/Application Support/Ulysses/`) — sheets stored in a custom binary-plus-text format keyed by UUIDs, not human-readable filenames. The format isn't documented. Recommend the user **export sheets** from Ulysses (File → Export → Markdown or Text) to a flat directory, then mount that.
+- **Bear** (`~/Library/Group Containers/9K33E3U3T4.net.shinyfrog.bear/`) — SQLite at `Application Data/database.sqlite`. **Technically parseable**: the schema is documented enough that a determined agent can read notes directly (one row per note, plaintext markdown in a column). But the schema has changed across Bear major versions, the database is locked while Bear is running, and tag/attachment relationships are spread across multiple tables. Recommend **Bear's built-in export** (File → Export Notes → Markdown) for stability; reach for the raw SQLite only if the user specifically asks for live, in-place access and accepts the fragility.
+- **Things 3** (`~/Library/Group Containers/JLMPQHK86H.com.culturedcode.ThingsMac/`) — SQLite at `Things Database.thingsdatabase/main.sqlite`. **Technically parseable**: third-party tools like `things.py` exist and the schema is community-documented. Same caveats as Bear: locked-while-running, schema-shifts-between-versions, multi-table joins required for projects/areas/tags. Recommend Things 3's URL scheme or AppleScript bridge for writes; raw SQLite only for read-only introspection where the user accepts the fragility.
+- **macOS Mail attachments inside `V10/`** — these live inside the `V10/` tree but are split across per-message `.mbox` directories under `Attachments/`. They're materialized lazily when Mail downloads them; messages opened only briefly may have no local attachment. Telling the user "I'll grab the attachment from that email" only works for emails Mail.app has fully cached. **For explicitly-saved attachments, use the Mail Downloads mount above instead** — that path is flat and reliable.
+- **Keychain** (`~/Library/Keychains/`) — encrypted blobs, useless to read directly, very sensitive. Never recommend.
+
+## Dev / workflow staples — minor but worth mentioning
+
+Quick wins that solve common questions without being privacy-loaded. **The recurring pattern**: for dotfiles that pair a `config` file with a `credentials` file, mount the **config**, never the credentials — credentials belong in `.env` or the typeclaw secrets store, not in a bind mount.
+
+| Use case                                 | Path                                                                     | `readOnly` | Notes                                                                                                                                                                                                                                                                                                                              |
+| ---------------------------------------- | ------------------------------------------------------------------------ | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Shell history                            | `~/.zsh_history` or `~/.bash_history` (mount the file or its parent dir) | `true`     | "What command did I run yesterday?" Mounting the parent (`~`) is **not** the answer — mount the specific file.                                                                                                                                                                                                                     |
+| SSH **config** (NOT keys)                | `~/.ssh/config`                                                          | `true`     | Single file. Useful for "ssh me into the staging box you set up." **Never mount `~/.ssh/` wholesale** — private keys live there.                                                                                                                                                                                                   |
+| Git config                               | `~/.gitconfig`                                                           | `true`     | Lets the agent see the user's identity, aliases, signing config.                                                                                                                                                                                                                                                                   |
+| AWS **config** (NOT credentials)         | `~/.aws/config`                                                          | `true`     | Profile names, region defaults, SSO start URLs. Useful for "what AWS profiles do I have?". **Never mount `~/.aws/` wholesale** — `credentials` lives next to `config` in the same dir and carries access keys. For actual AWS work, plumb credentials through `.env` (`AWS_ACCESS_KEY_ID`, `AWS_PROFILE`, etc.), not a bind mount. |
+| Kubernetes config                        | `~/.kube/config`                                                         | `true`     | "What clusters do I have access to?" **Caveat**: depending on the auth method, `~/.kube/config` itself can contain bearer tokens or certificate data inline (older OIDC flows, EKS pre-IAM-auth, direct service-account tokens). Read the file before recommending — if it has inline tokens, treat it like a credential.          |
+| Editor configs (nvim, fish, helix, etc.) | `~/.config/nvim/`, `~/.config/fish/`, `~/.config/helix/`                 | `true`     | "Why is my prompt broken?" / "What plugins do I have?" Generally safe (these dirs don't carry secrets), but check before recommending — some users put API keys in nvim plugin configs.                                                                                                                                            |
+| `/etc/hosts`                             | `/etc/hosts`                                                             | `true`     | "What's in my hosts file?" Single-file mount. **Linux/macOS only.** WSL has a Windows-side hosts file at `/mnt/c/Windows/System32/drivers/etc/hosts` that takes precedence over the WSL-internal one — mount whichever the user actually edits.                                                                                    |
+| macOS LaunchAgents (user-level)          | `~/Library/LaunchAgents/`                                                | `true`     | "What auto-starts on my Mac?" Plist files declaring user-scope launchd jobs. System-level `/Library/LaunchAgents/` and `/Library/LaunchDaemons/` exist too but are SIP-adjacent and rarely useful.                                                                                                                                 |
+| Time Machine-excluded scratch            | `~/scratch` (user creates with `tmutil addexclusion ~/scratch`)          | `false`    | Ephemeral agent output the user doesn't want backed up.                                                                                                                                                                                                                                                                            |
+| iCloud Drive top-level                   | `~/Library/Mobile Documents/com~apple~CloudDocs`                         | mixed      | iCloud lazy-loads — same warning as the Obsidian iCloud row above.                                                                                                                                                                                                                                                                 |
+
+## Anti-patterns
+
+Append-only list, no overlap with `SKILL.md`'s existing anti-patterns (which cover schema/correctness, not host-path safety):
+
+- **Never recommend mounting `~` (the entire home directory).** It's tempting and it's a security disaster: SSH keys, browser cookies, app credentials, `.env` files from every project, shell history with leaked tokens, Keychain blobs. If the user asks for "everything", push back and ask what they actually need.
+- **Never mount `~/.ssh/` wholesale.** Private keys (`id_*`, `id_*.pub` ok but the bare files without `.pub` are private) should not enter the container. Mount the specific file `~/.ssh/config` read-only if the user wants SSH host visibility.
+- **Never mount `~/Library/Keychains/`.** Even read-only, even with FDA. The keychain is encrypted blobs the agent can't use, and the act of bind-mounting it expands the attack surface for no benefit.
+- **Never mount `~/.aws/`, `~/.gcp/`, `~/.azure/`, or any cloud-CLI credential dir.** Same reasoning as keychains — credentials, not data. If the user wants the agent to do cloud work, plumb credentials through `.env` (env vars the cloud SDK reads), not through a bind mount of the secret store. **The `config` file inside `~/.aws/` is fine to mount individually** (see the staples table) — it's the `credentials` file you have to keep out.
+- **Never mount these credential-bearing dotfiles**, even though they look innocuous: `~/.aws/credentials`, `~/.npmrc` (often carries `//registry.npmjs.org/:_authToken=...` for private packages), `~/.pip/pip.conf` and `~/.pypirc` (PyPI upload tokens), `~/.docker/config.json` (Docker registry auth tokens, sometimes inline), `~/.cargo/credentials` (crates.io token), `~/.gradle/gradle.properties` (often carries signing keys and repo creds), `~/.m2/settings.xml` (Maven repo passwords). These pair with safe config files in similar paths — mount the config file individually if the user needs it, never the credentials file, never the parent directory.
+- **`/Volumes/<external-drive>` is fragile.** Bind mounts to removable drives don't recover when the drive is ejected — the container sees the path become an empty stub, and the only fix is `typeclaw restart` after the drive is reattached. Tell the user before mounting, and consider whether copying the data to an internal path is wiser.
+- **iCloud Drive paths lazy-load.** `~/Library/Mobile Documents/com~apple~CloudDocs/` and the per-app `iCloud~<bundle>` dirs only materialize files when the host system opens them. Inside the container, an unmaterialized file appears as a 0-byte stub or a `.icloud` placeholder. The fix is host-side: have the user open the file (or `brctl download` it) before the agent tries to read it. The agent cannot trigger iCloud materialization from inside the container.
+- **`/private/var/db/` and other system stores are not yours.** TCC database, Spotlight metadata, system logs — all gated by SIP (System Integrity Protection) on top of FDA, and none of them are useful to the agent. If the user asks for Spotlight-style search, the answer is `mdfind` from the host (out of scope for the container), not a mount.
+- **Don't mount the same host path twice under different mount names.** Docker allows it, but the agent now has two views of the same data and writes through one are immediately visible through the other. It looks like a bug from the agent's side ("why did `mounts/notes-ro/foo.md` change when I wrote `mounts/notes-rw/foo.md`?"). Pick one mount per host path.
+- **`readOnly: true` is not encryption-at-rest.** A read-only mount prevents the agent from writing back, but reads still happen through the kernel's normal file path — no obfuscation, no privacy gain beyond write-prevention. If the data is so sensitive that read-access itself is a problem, the answer is **don't mount it**, not "mount it read-only".
+- **macOS path versioning will drift.** Apple has moved `~/Library/Mail/V<n>`, Voice Memos, and other paths across macOS versions. The paths in this file are good for macOS 12–26 as of this writing; if a future macOS reorganization breaks one, the symptom is `ls mounts/<name>` returning empty after a successful mount. Update this file, don't paper over it.
+
+## When the path you need isn't here
+
+Fall through to the general procedure in `SKILL.md`. If it's a use case you've handled successfully and it generalizes (other users would benefit), update this file in the same edit — the recommended-mounts list is meant to grow over time as the agent learns common asks.

package/src/skills/typeclaw-permissions/SKILL.md

@@ -11,7 +11,7 @@ You run under an access-control system that gates which sessions wake you, which
 
 Every session you run in has a `SessionOrigin` (TUI / channel / cron / subagent). How the runtime resolves it to a **role** depends on the origin kind:
 
-- **TUI and channel** sessions resolve by walking the `roles` block in `typeclaw.json` in declaration order and picking the first role whose `match` rules cover the origin. This is the only origin shape that match rules actually grant roles to at runtime.
+- **TUI and channel** sessions resolve by walking the role table in **severity-then-declaration order** and picking the first role whose `match` rules cover the origin. The walk order is: `owner` → `trusted` → custom roles (in **reverse** declaration order; later declarations override earlier ones) → `member` → `guest`. Built-in privileged roles always get the first shot regardless of how the operator ordered `typeclaw.json#roles`, so a broad rule on `member` cannot shadow a narrower rule on `owner` or `trusted`. Among custom roles, the later-declared entry wins so operators can append overrides without rewriting earlier blocks. This is the only origin shape that match rules actually grant roles to at runtime.
 - **Cron** sessions resolve from `scheduledByRole`, a string stamped on the cron job record itself (in `cron.json` for hand-authored entries, or by the runtime for plugin-contributed cron). Match rules of the form `cron` parse but never grant a role to a running cron session — provenance wins.
 - **Subagent** sessions resolve from `spawnedByRole`, snapshotted from the spawning session's resolved role at spawn time. Same story: `subagent` / `subagent:<name>` rules parse but don't grant roles at runtime; the spawn provenance is the source of truth.
 
@@ -21,12 +21,14 @@ Each role carries a set of **permissions** — opaque dotted strings like `chann
 
 You always have these four, even if `typeclaw.json` declares zero `roles`. User-declared roles **append** match rules to the built-ins but **replace** the permission list entirely (so `"permissions": []` on a built-in role means "no permissions" — be careful).
 
-| Role      | Built-in `match[]`                                                | Default `permissions[]`                                                                                                                                                                                                                                                                                                                                                                  |
-| --------- | ----------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `owner`   | `["tui"]` (always prepended)                                      | `channel.respond`, `cron.schedule`, `cron.modify`, `security.bypass.low`, `security.bypass.medium`, **plugin-contributed `security.bypass.*` MINUS high-tier strings** (the wildcard sentinel expands to plugin bypasses but excludes the security plugin's `ownerWildcardExclusions` — today: `gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`, plus `bypass.high`) |
-| `trusted` | none                                                              | `channel.respond`, `cron.schedule`, `security.bypass.low`                                                                                                                                                                                                                                                                                                                                |
-| `member`  | none                                                              | `channel.respond`                                                                                                                                                                                                                                                                                                                                                                        |
-| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | none                                                                                                                                                                                                                                                                                                                                                                                     |
+Roles form a strict tower: each role bypasses every guard at its tier and below.
+
+| Role      | Built-in `match[]`                                                | Tier bypass cap | Default `permissions[]`                                                                                                                                                                                                |
+| --------- | ----------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `owner`   | `["tui"]` (always prepended)                                      | `high`          | `channel.respond`, `cron.schedule`, `cron.modify`, `subagent.*`, `security.bypass.low`, `security.bypass.medium`, `security.bypass.high`, plus every plugin-contributed `security.bypass.<guard>` (wildcard expansion) |
+| `trusted` | none                                                              | `medium`        | `channel.respond`, `cron.schedule`, `subagent.*`, `security.bypass.low`, `security.bypass.medium`                                                                                                                      |
+| `member`  | none                                                              | `low`           | `channel.respond`, `subagent.spawn`, `subagent.cancel`, `subagent.output`, `security.bypass.low`                                                                                                                       |
+| `guest`   | none (fallback when nothing else matches, or stamped role is bad) | (none)          | none                                                                                                                                                                                                                   |
 
 A session that doesn't match anything resolves to `guest`. `guest` has no `channel.respond`, so the router silently drops inbound messages whose author resolves to `guest`. **This is the most common cause of "the agent stopped responding"**: the user added a channel but did not add a match rule, so every speaker in that channel is `guest` and every inbound is dropped before you ever see it. There is no message in your session log when this happens — only a host-side line `[channels] <key>: denied by permissions (channel.respond) author=<id>`.
 
@@ -40,7 +42,7 @@ When the runtime knows your permissions, it prepends a block under your `## Sess
 Role: `member`. Permissions: `channel.respond`.
 ```
 
-The block renders for cron / channel / subagent sessions. For TUI sessions, the block is omitted **when** the resolved role is the built-in `owner` (the common case, so we save tokens on every interactive session) and rendered when a user-declared role matched TUI first (because the resolver is first-match-wins in declaration order, a custom role with `match: ["tui"]` placed before `owner` will demote TUI). If you don't see the block in a TUI session, treat yourself as `owner`.
+The block renders for cron / channel / subagent sessions. For TUI sessions, the block is omitted because TUI always resolves to `owner` under severity-then-declaration ordering (built-in `owner.match` includes `tui` and is appended-to, never replaced, by user config — and `owner` is walked first). If you don't see the block in a TUI session, treat yourself as `owner`.
 
 **The role line reflects the session at creation time.** For channel sessions, the speaker on subsequent turns may resolve to a different role; the runtime updates that internally for tool gating (the channel router and the security plugin re-resolve on each turn), but the system prompt is not regenerated mid-session. If the user asks "what role am I right now in this channel", read `typeclaw.json` `roles` and match their author id against `match[]` yourself — do not parrot the system-prompt line as if it always applied.
 
@@ -84,17 +86,21 @@ Three sources contribute permission strings:
 
 The security plugin classifies each guard on a two-axis policy:
 
-- **high — audience-leak.** Bypass sends data to a third-party audience outside the operator's control loop (channel readers, remote git hosts, or the agent's own future access-control state). Inhabitants: `outboundSecret`, `systemPromptLeak`, `gitExfil`, `gitRemoteTainted`, `rolePromotion`, `cronPromotion`. **No role auto-bypasses high.** Per-call ack required from every role, including `owner`. The canonical case is **owner-in-public-channel**: even an owner asking "post deploy status to #general" must not silently include a `Bearer ghp_…` line; even `git push` from TUI must be ack'd; even an owner adding a new entry to `roles.<role>.match[]` or scheduling a privileged cron job must ack the privilege grant. Operators who knowingly want one role to skip a high-tier guard add the per-guard string explicitly to `roles.<role>.permissions[]`.
-- **medium — silent-attack.** Bypass returns secrets / IAM creds into model context with no immediate operator visibility. Inhabitants: `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`. `owner` bypasses (operator already has host access); `trusted` does NOT.
-- **low — noisy, immediately recoverable.** No inhabitants today. Forward-compat for future guards. `trusted` carries `bypass.low` so a future low-tier guard auto-bypasses for trusted without a config edit.
+- **high — direct audience-leak.** Bypass sends data to a third-party audience outside the operator's control loop with NO operator-visible intermediate step. Inhabitants: `outboundSecret`, `systemPromptLeak`, `gitRemoteTainted`. **`owner` bypasses by default; `trusted`, `member`, `guest` do not.** The canonical case is **owner-in-public-channel**: an owner-permissioned operator asking the agent to "post deploy status to #general" can silently leak a `Bearer ghp_…` line. The defense lives in `roles.owner.match[]` discipline — the default is TUI-only, where a human is present. Configs that widen owner to a channel author should narrow the match or strip `security.bypass.high` (and the wildcard sentinel) from `roles.owner.permissions[]` for those origins.
+- **medium — silent-attack OR operator-reviewable state.** Two sub-shapes share this tier because they share a defense story (operator review catches it before the privileged effect escapes). (a) _silent-attack_: bypass returns secrets / IAM creds into model context with no immediate operator visibility — `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`. (b) _operator-reviewable state_: bypass writes to a file the operator force-commits and reviews before the privileged effect takes hold — `gitExfil` (push to a clean operator-configured remote; the retarget-and-push path stays blocked by `gitRemoteTainted` at high), `rolePromotion` (`roles` is restart-required so the operator has wall-clock time), `cronPromotion` (deferred execution gives wall-clock time to revert). **`owner` and `trusted` bypass; `member`, `guest` do not.**
+- **low — noisy, immediately recoverable.** No inhabitants today. Forward-compat for future guards. **`owner`, `trusted`, `member` all carry `bypass.low`; `guest` does not.**
 
 At `tool.before` time, an actor bypasses a guard if they hold **either** the tier permission **or** the per-guard permission (OR-check, both axes work forever).
 
-`owner` carries `security.bypass.low + security.bypass.medium` AND the wildcard sentinel; the sentinel expands to plugin-contributed `security.bypass.*` strings minus the security plugin's `ownerWildcardExclusions` (today: the four high-tier per-guard strings plus `bypass.high`). Net: `owner` auto-bypasses every low- and medium-tier guard; high-tier guards require ack from owner too. `trusted` carries only `bypass.low` — no per-guard medium/high grants by default. `member` and `guest` carry no `security.bypass.*` strings.
+`owner` carries `security.bypass.low + security.bypass.medium + security.bypass.high` AND the wildcard sentinel. The bundled security plugin sets `ownerWildcardExclusions: []`, so the sentinel expands to every plugin-contributed `security.bypass.*` string. Net: `owner` auto-bypasses every tier and every per-guard string by default. `trusted` carries `bypass.low + bypass.medium` — no high-tier grants by default. `member` carries `bypass.low` — no medium/high. `guest` carries no `security.bypass.*` strings.
+
+**Trusted is operator-class for the agent's own state.** Because `gitExfil`, `rolePromotion`, and `cronPromotion` are medium-tier, trusted users can push to operator-configured remotes, edit `typeclaw.json#roles`, and add cron jobs without per-call acks. The two-step taint defense (`gitRemoteTainted`, still high) still blocks the retarget-and-push attack. The privilege-escalation defense for `roles`/`cron` edits now leans on operator review of auto-backup commits — `typeclaw.json` and `cron.json` are force-committed on idle, and the operator sees diffs before reload/restart. Deployments that don't review backup commits should keep `roles.trusted.match[]` narrow, OR subtract by replacing `roles.trusted.permissions[]` with an explicit list that omits `security.bypass.medium`.
+
+**Narrowing owner.** If a deployment matches `owner` to a channel author (not just TUI), the audience-leak defense (owner-in-public-channel) is at risk. Two ways to narrow: (a) tighten `roles.owner.match[]` back to TUI-only and use a separate role for channel access; (b) replace `roles.owner.permissions[]` with an explicit list that omits `security.bypass.high` (and the wildcard sentinel) for the deployment. Either path is supported.
 
-**Trusted lost two per-guard grants in PR #255 compared to pre-PR behavior.** Before: trusted carried `bypassSecretExfilBash` and `bypassGitExfil` so they could `bash env` and `git push` without acks. After: those guards (medium and high respectively) need acks for trusted too. Operators who relied on the old ergonomics can restore them by adding the per-guard strings explicitly to `roles.trusted.permissions[]` in `typeclaw.json` — the per-guard path is supported forever via the OR-check. When the user complains "trusted can't push anymore," this is the explanation and the workaround.
+**Widening lower roles.** Operators who want member to push without acks (or to bypass any other guard) add the per-guard string explicitly via the OR-check: `roles.member.permissions: [..., "security.bypass.gitExfil"]`. This is narrower than granting a whole tier.
 
-Note on the two-step `gitRemoteTainted` defense: even when an operator explicitly grants `security.bypass.gitExfil` to a role (re-opening the high-tier bypass for `git push`), the second-step `gitRemoteTainted` check still fires on the eventual push if origin was re-pointed mid-session. The recorder runs on the first step (the `set-url`) gated by "would the command actually run" — so the second-step checker has taint state to consult. Granting `bypassGitExfil` does NOT silently grant `bypassGitRemoteTainted`; those are independent per-guard strings AND independent high-tier guards.
+Note on the two-step `gitRemoteTainted` defense: trusted bypasses `gitExfil` via `bypass.medium`, so trusted's first-step `git remote set-url` succeeds AND the recorder fires; the second-step push is then blocked by `gitRemoteTainted` (high tier, trusted lacks bypass). The same shape holds for any actor who bypasses `gitExfil` (per-guard OR via tier) but not `gitRemoteTainted` — the recorder runs on the first step gated by "would the command actually run", so the second-step checker has taint state to consult. The two are independent per-guard strings AND independent tier classifications.
 
 **Two-layer defense for channel-side git operations**: the runtime `tool.before` guards are not the only layer that gates `git push` from channel messages. The security plugin's `session.prompt` hook also pattern-matches inbound text for `git push` / `git remote add` / `gh repo create --push` and injects a refusal rule into the system prompt. **The prompt-side `git_exfil` defense is gated to non-subagent origins** — it fires for `channel` and `tui` prompts but skips `subagent` prompts. The reason: bundled subagents like `backup-diagnose` legitimately embed git stderr in their payloads (which contains literal "git push --help" hint strings on failures), and triggering the defense there would inject a "do NOT run git push" rule that contradicts the subagent's own system-prompt instructions to retry with an ack. The runtime `tool.before` is the universal backstop for subagents (under the audience-leak policy, even owner-spawned subagents need an ack for `git push`), so the prompt-side check is redundant for them and harmful to bundled-plugin recovery flows. For channel and TUI prompts the two layers agree: nobody auto-bypasses gitExfil at the runtime layer, so the prompt-injection layer's text-match refusal is the same answer the runtime would give. The only case where the two layers disagree is when an operator has explicitly granted `security.bypass.gitExfil` to a channel speaker's role in `typeclaw.json` — then the runtime would allow the push but the prompt-injection text-match would still refuse. That's a known narrow-scope gap (operator opted into the bypass already); if the user is confused why the agent refused a channel-side push despite the per-guard grant they added, this is why.
 
@@ -136,7 +142,7 @@ To distinguish cause 1/2 from cause 3: if `typeclaw logs <container> -f` (host s
 This is a `roles` edit. The full procedure:
 
 1. **Resolve the coordinates.** Get the platform name (`slack | discord | telegram | kakao`), the workspace ID, the chat ID. If the user gave you names, ask them or look them up in the participants list of a previous inbound from that channel.
-2. **Pick a role.** Default to `member` for "give them normal channel access". Use `trusted` if they should also be able to schedule cron — by default trusted gets ONLY `bypass.low` (no inhabitants today), so trusted on its own does NOT skip any security guard. If the user wants the old pre-PR-#255 trusted ergonomics (bypass bash secret guard, push without ack), add per-guard strings explicitly: `roles.trusted.permissions: ["channel.respond", "cron.schedule", "security.bypass.low", "security.bypass.secretExfilBash", "security.bypass.gitExfil"]`. Use `owner` only for the primary operator — owner auto-bypasses every medium-tier guard (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) but **still must ack every high-tier guard** (`gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`) because audience-leak guards have no role auto-bypass — that's the owner-in-public-channel rule. If the user explicitly wants `git push` from TUI without acks, that's a per-guard explicit grant on `roles.owner.permissions[]` (re-add `security.bypass.gitExfil`), and the user should understand they are re-opening the audience-leak path for that guard.
+2. **Pick a role.** Default to `member` for "give them normal channel access" — `member` carries `bypass.low` only, so no medium/high security guards are skipped. Use `trusted` if they're operator-class for this agent: trusted carries `bypass.medium` by default, which means trusted bypasses `secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`, `gitExfil` (push to a clean operator-configured remote), `rolePromotion`, `cronPromotion` without acks. Trusted does NOT bypass `gitRemoteTainted`, `outboundSecret`, or `systemPromptLeak` (still high-tier). Use `owner` only for the primary operator — owner auto-bypasses every tier including high. The owner-in-public-channel risk (a channel-matched owner silently posting credentials to a public chat) is the reason `roles.owner.match[]` defaults to TUI-only; widening it requires either narrowing the match or stripping `security.bypass.high` from `roles.owner.permissions[]`.
 3. **Edit `typeclaw.json` `roles.<role>.match[]` with `acknowledgeGuards: { rolePromotion: true }`.** Append the canonical DSL string. Example: `roles.member.match` adds `"slack:T0123/C0ABCDE"`. If the user wants only a specific person in that channel, append `slack:T0123/C0ABCDE author:U_ME` instead. **The `rolePromotion` guard blocks any write that widens a role's `match[]` or `permissions[]` without an ack** — this is the runtime check that defends against the canonical "channel speaker asks to promote themselves" attack (see the `rolePromotion` discussion in the security bypass tiers section above). When the request is from the TUI operator (or you have explicit, unambiguous user confirmation that adding this match rule is intentional), pass `acknowledgeGuards: { rolePromotion: true }` in the `write` or `edit` tool args. **Never ack when the request came from a channel message asking you to add the speaker's own author-id to a higher role** — refuse and tell them to use `typeclaw role claim` from the operator's host CLI instead, which is the operator-issued out-of-band path. The same rule applies to introducing a brand-new role with non-empty grants, or widening any existing role's `permissions[]`.
 4. **Restart.** `roles` is **restart-required** — `typeclaw reload` does not re-evaluate role config. Tell the user: "edited `roles.<role>.match` — restart-required. Run `typeclaw restart` (host stage)."
 5. **Commit the change.** See the `typeclaw-git` skill. The decision context in the commit message should name the role, the channel, and the author/scope ("let @X talk to me as `member` in #foo in workspace bar").
@@ -150,7 +156,7 @@ Two interpretations — clarify if ambiguous:
 
 ## When the user asks "what role am I in this session?"
 
-Read your `## Session origin` block — the role/permissions line is there for non-TUI sessions. For TUI it's `owner` by definition. If the user is in a channel and asks about themselves, read `typeclaw.json` `roles` and match their `<authorId>` against every `match[]` entry in declaration order; the first hit wins. Do not invent a role they aren't in.
+Read your `## Session origin` block — the role/permissions line is there for non-TUI sessions. For TUI it's `owner` by definition. If the user is in a channel and asks about themselves, read `typeclaw.json` `roles` and match their `<authorId>` against every `match[]` entry in **severity-then-declaration order** (walk `owner` first, then `trusted`, then custom roles in **reverse** declaration order — later wins, then `member`, then `guest`); the first hit wins. Do not invent a role they aren't in.
 
 ## When the user asks about cron / subagent provenance
 
@@ -168,8 +174,8 @@ If you see a cron job mysteriously failing every fire with `denied by permission
 - **Do not write `*` in user-declared `permissions[]`.** The owner wildcard is a runtime sentinel, not part of the user-facing string format. The schema rejects `*` (it's not a valid dotted permission string anyway).
 - **Do not invent permission strings.** Only the three sources above (core, security plugin including the eight per-guard + three tier strings, declared plugins) contribute valid strings. A string like `bash.execute` looks plausible but is not gated by anything and will only earn a boot warning. If the user asks for a permission the model doesn't have, tell them — don't invent one.
 
-- **Do not grant `security.bypass.high` casually.** High-tier guards (`gitExfil`, `gitRemoteTainted`, `outboundSecret`, `systemPromptLeak`) all defend the audience-leak axis — bypassing them means data leaves the operator's perimeter without per-call confirmation. Even `owner` doesn't have `bypass.high` by default for this exact reason. Granting `security.bypass.high` to any role opens audience-leak bypass on every current high-tier guard PLUS every future high-tier guard added by a security plugin update. If the user wants one specific high-tier bypass (e.g. "let me push from TUI without acks"), grant the **per-guard** string explicitly (`security.bypass.gitExfil`) on the specific role, not the tier — that's narrower and won't widen on plugin updates.
-- **Do not grant `security.bypass.medium` to roles wider than the operator.** Medium-tier bypasses (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) silently dump secrets into model context. Granting `bypass.medium` to a `trusted` role that matches a broad Slack workspace means any trusted speaker can ask the agent to dump environment variables and the bypass succeeds — the operator only sees on session review. If the user wants this anyway, name the specific guard with a per-guard grant rather than the whole tier.
+- **Do not grant `security.bypass.high` to non-owner roles casually.** High-tier guards (`outboundSecret`, `systemPromptLeak`, `gitRemoteTainted`) defend the direct audience-leak axis — bypassing them means data leaves the operator's perimeter with NO operator-visible intermediate step. `owner` carries `bypass.high` by default under the role-tower model, so the default asymmetry is: a TUI operator can do these things silently, a channel speaker matched to `owner` can too (which is the defense rationale for keeping owner's match narrow). Granting `security.bypass.high` to `trusted` or a custom role opens audience-leak bypass on every current high-tier guard PLUS every future high-tier guard added by a security plugin update. If the user wants one specific high-tier bypass for a lower role, grant the **per-guard** string explicitly (`security.bypass.outboundSecret`) on the specific role, not the tier — that's narrower and won't widen on plugin updates.
+- **Be careful with `roles.trusted.match[]` for broad audiences.** Trusted carries `bypass.medium` by default, which is now operator-class for the agent's own state: trusted bypasses not just the silent-attack guards (`secretExfilBash`, `secretExfilRead`, `ssrf`, `sessionSearchSecrets`) but ALSO the operator-reviewable-state guards (`gitExfil` to clean remotes, `rolePromotion`, `cronPromotion`). A trusted role matched to a broad Slack workspace means any trusted speaker can ask the agent to dump env vars, push to operator-configured remotes, OR write a privileged change to `typeclaw.json`/`cron.json` without acks — the operator only catches the latter two on backup-commit review BEFORE the next restart/schedule tick. If the user wants a wider trusted audience without the operator-class authority, replace `roles.trusted.permissions[]` with an explicit list that omits `security.bypass.medium` (and add only narrower per-guard strings as needed).
 - **Do not promise that `typeclaw reload` applied a `roles` edit.** `roles` is restart-required. The reload tool will return success on the config file change, but the live `PermissionService` was built at boot and is not swapped on reload.
 - **Do not silently change a built-in role's permission list.** Setting `"permissions": []` on `member` is a wholesale replace, not a merge — you just took `channel.respond` away from every speaker who resolves to `member`. If the user said "give member just `channel.respond` and nothing else", that's fine (it's the same as the default), but say so explicitly: "this matches the default for `member`, no behavior change". If the user said "remove cron from `trusted`", make the change but warn that `trusted` no longer carries `cron.schedule` either.
 - **Do not write match rules using display names** (`#general`, `@user`, channel/user names). Match rules are platform IDs. Display names change; IDs don't. Always look up the ID before writing the rule.