diff --git a/README.md b/README.md
index 2383d04..0351395 100644
--- a/README.md
+++ b/README.md
@@ -57,14 +57,22 @@ The full `secrets.json` stays on the host. `agent-secrets.json` goes into the co
 
 ```bash
 ccc-server --secrets secrets.json
+ccc-server --secrets secrets.json --mail-perms mail-perms.json
 ```
 
+Server flags:
+| Flag | Env variable | Description |
+|------|-------------|-------------|
+| `--secrets <path>` | — | Path to secrets file (required) |
+| `--bind <addr>` | `CONDUIT_BIND` | Address to bind to (default `127.0.0.1`) |
+| `--mail-perms <path>` | `CONDUIT_MAIL_PERMS` | File to persist mail permissions (optional; in-memory only if omitted) |
+
 Server environment variables:
 | Variable | Default | Description |
 |----------|---------|-------------|
 | `CONDUIT_PORT` | `3015` | Port to listen on |
 | `CONDUIT_BIND` | `127.0.0.1` | Address to bind to |
-| `CONDUIT_ROOT` | `/workspace` | Workspace root for path resolution |
+| `CONDUIT_ROOT` | `/workspace` | Label printed at startup (informational only — path resolution uses `VOLUME_MAPPING` in `server/helpers.mjs`) |
 
 ### Client (container / agent)
 
@@ -134,7 +142,12 @@ Built-in actions:
 | `list-actions` | auto-accept | — |
 | `edit-file` | auto-accept | `filename` (path) |
 | `open-browser` | queue | `url` (http/https only) |
-| `open-terminal` | queue | `path` (optional) |
+| `open-terminal` | queue | `path` (optional, defaults to workspace) |
+| `send-email` | auto-accept | `to`, `subject`, `body`, `topic` |
+| `set-mail-permission` | auto-accept | `target_user`, `to`, `topic`, `allow` (bool) |
+| `get-mail-permissions` | auto-accept | `target_user` (optional) |
+
+`send-email` checks that the caller has a mail permission entry matching `(caller, to, topic)` before sending. Permissions are managed via `set-mail-permission`, which requires the caller to have `canApprove` over the target user — so only humans can grant/revoke permissions for agents.
 
 ### Adding actions
 
@@ -145,8 +158,9 @@ Edit `server/actions.mjs`. Each entry needs:
     description: 'What this does',
     params: [{ name: 'foo', required: true, type: 'string' }],
     policy: 'auto-accept',   // or 'auto-deny' | 'queue'
-    handler: ({ foo }) => {
-        // do something
+    handler: ({ foo }, ctx) => {
+        // ctx = { caller, users, mail_perm_store, mailer_send }
+        // ctx is optional — omit the second argument if you don't need it
         return { result: foo };
     },
 },