typeclaw 0.1.4 → 0.1.6

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 (Discord allow rules + engagement), portForward (auto port forwarding policy), dockerfile (tmux/gh/python/ffmpeg toggles + append), gitignore.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). Read it before touching typeclaw.json — strict schema, mix of live-reloadable and restart-required fields."
 ---
 
 # typeclaw-config
@@ -18,9 +18,9 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
 - `mounts` — additional host directories the user has chosen to expose to you. Each entry produces a `docker run -v <hostPath>:/agent/mounts/<name>` flag at `typeclaw start` time, so the directory shows up at `mounts/<name>` inside your agent folder. **The launcher reads this; the running container does not.** Editing `mounts` only takes effect on the next `typeclaw start`. **Restart-required.**
 - `plugins` — array of plugin package names loaded at server boot. **Restart-required.**
 - `alias` — additional names the agent answers to when a channel message contains its name in plain text (no `<@id>` mention). The agent folder's directory name (`basename(agentDir)`) is always implicit; `alias` adds further forms (Latin transliteration, nicknames, Korean particles, etc.). Used by the channel engagement layer alongside the structural mention/reply/dm triggers. **Live-reloadable.**
-- `channels` — per-adapter allow rules and engagement triggers that gate which external messenger channels (today: Discord) you can read from and post to. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
-- `dockerfile` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated apt packages (`tmux`, `gh`, `python` default `true`; `ffmpeg` defaults `false`) — set the toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python` is boolean-only). (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. **Restart-required** (next `typeclaw start` rebuilds the image).
-- `gitignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
+- `channels` — per-adapter engagement triggers and history-prefetch knobs for external messengers (Discord, Slack, Telegram, KakaoTalk). Access control lives in `roles`, not here. **Live-reloadable** — edits take effect on the next `reload` without a container restart.
+- `docker.file` — controls what ships in the autogenerated container image. Two layers: (1) **toggles** for opinionated apt packages (`tmux`, `gh`, `python` default `true`; `ffmpeg` defaults `false`) — set the toggle to `false` to omit, or to a version string like `"2.40.0"` to apt-pin (`python` is boolean-only). (2) **`append`** — extra Dockerfile lines spliced in right before `ENTRYPOINT` for anything the toggles don't cover. The whole Dockerfile is rewritten on every `start` from the typeclaw template. Lives under the `docker` namespace alongside future Docker-related blocks (e.g. `docker.compose`). **Restart-required** (next `typeclaw start` rebuilds the image).
+- `git.ignore.append` — extra `.gitignore` patterns `typeclaw start` splices into the TypeClaw-owned `.gitignore` before the protected TypeClaw rules. The whole `.gitignore` is rewritten and auto-committed on every `start` when it changes; `append` is the supported escape hatch for local ignore patterns without editing the managed file by hand. Lives under the `git` namespace. **Restart-required** (next `typeclaw start` refreshes and commits `.gitignore`).
 - `portForward` — allow/deny policy for the auto port-forwarder (the host-stage `_hostd` daemon's portbroker). When the agent runs a server inside the container that LISTENs on a TCP port, the broker proxies it to the same port number on `127.0.0.1` of the host so the user can hit it directly. `portForward` decides which ports are allowed through. **Restart-required** — the broker captures the policy at register time on `typeclaw start`.
 
 ### Reload vs. restart
@@ -28,7 +28,7 @@ The runtime reads `typeclaw.json` at container startup. Some fields are picked u
 There is no file watcher, but there is a `reload` mechanism. When `typeclaw.json` changes:
 
 - **Live-reloadable fields** (`model`, `alias`, `channels`) take effect on the next `reload` — no container restart.
-- **Restart-required fields** (`port`, `mounts`, `plugins`, `portForward`, `dockerfile`, `gitignore`) are reported as "reload landed but change won't apply until restart". The diff returns success; the runtime still has the old value in memory. Tell the user explicitly which one they're hitting. `dockerfile` additionally requires an image rebuild — that happens automatically on the next `typeclaw start`, no extra flag needed. `gitignore` refreshes the managed `.gitignore` and auto-commits it on the next `typeclaw start` if content changed.
+- **Restart-required fields** (`port`, `mounts`, `plugins`, `portForward`, `docker.file`, `git.ignore`) are reported as "reload landed but change won't apply until restart". The diff returns success; the runtime still has the old value in memory. Tell the user explicitly which one they're hitting. `docker.file` additionally requires an image rebuild — that happens automatically on the next `typeclaw start`, no extra flag needed. `git.ignore` refreshes the managed `.gitignore` and auto-commits it on the next `typeclaw start` if content changed.
 - **`$schema`** changes are ignored.
 
 When you edit `typeclaw.json`, name the effect: "Edited `channels` — live-reloadable, takes effect on the next `reload`." vs. "Edited `port` — restart-required, run `typeclaw restart` (host stage) to pick up the change." Conflating the two misleads the user into restarting unnecessarily, or worse, into believing a restart-required edit took effect when it did not.
@@ -39,22 +39,22 @@ You yourself cannot run `typeclaw restart` — that is a host-stage command and
 
 `typeclaw.json` is a single JSON object with these fields:
 
-| Field         | Required | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                              |
-| ------------- | -------- | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `$schema`     | no       | string           | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.                                                                                                                                                                                                                                                                   |
-| `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                  |
-| `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                  |
-| `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                     |
-| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                          |
-| `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                        |
-| `channels`    | no       | object           | Per-adapter allow rules and engagement triggers for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds a `discord-bot` block only if the user said yes to "Wire a Discord bot?" during the wizard and supplied a token. **Live-reloadable.** See **Channels** section below.                                                                                                                |
-| `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                       |
-| `dockerfile`  | no       | object           | Customizations for the autogenerated container image build. Toggles (`tmux`, `gh`, `python`, `ffmpeg`) gate opinionated apt packages; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. Defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
-| `gitignore`   | no       | object           | Customizations for the autogenerated `.gitignore`. Today the only field is `append` — extra patterns spliced in before TypeClaw's protected ignore rules. Defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                           |
+| Field         | Required | Type             | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| ------------- | -------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `$schema`     | no       | string           | Path to `typeclaw.schema.json` for editor autocompletion. Scaffolded as `./node_modules/typeclaw/typeclaw.schema.json`. Leave it alone unless the user moves it.                                                                                                                                                                                                                                                                                                  |
+| `port`        | no       | integer          | 1–65535. Defaults to `8973` (T9 spelling of "TYPE"). Change only if the default collides with something on the user's host. **Restart-required.**                                                                                                                                                                                                                                                                                                                 |
+| `model`       | no       | string           | Must be one of the values listed in the **Allowed models** section below. Defaults to `openai/gpt-5.4-nano`. **Live-reloadable.**                                                                                                                                                                                                                                                                                                                                 |
+| `mounts`      | no       | array of objects | Host directories bind-mounted into your container. Defaults to `[]` (no host paths exposed). Omitted from scaffolded `typeclaw.json` — add it only when the user wants host paths exposed. See **Mounts** section below. **Restart-required.**                                                                                                                                                                                                                    |
+| `plugins`     | no       | array of strings | Plugin package names loaded at server boot. Defaults to `[]`. **Restart-required.** Plugin-owned config blocks live alongside as additional top-level keys; see **Plugin config blocks**.                                                                                                                                                                                                                                                                         |
+| `alias`       | no       | array of strings | Additional names the agent answers to in channel engagement, on top of the implicit `basename(agentDir)`. Each entry is a non-empty trimmed string matched case-insensitively as a substring of the inbound text. Defaults to `[]`. Hatching populates this with the agent's chosen name. See **Alias** section below. **Live-reloadable.**                                                                                                                       |
+| `channels`    | no       | object           | Per-adapter engagement triggers and history-prefetch knobs for external messengers. Defaults to `{}` (no adapters configured). `typeclaw init` scaffolds an empty block per requested adapter (e.g. `"discord-bot": {}`) and the schema fills in defaults. Channel access control lives in `roles` — see the `typeclaw-permissions` skill. **Live-reloadable.** See **Channels** section below.                                                                   |
+| `portForward` | no       | object           | Allow/deny policy for the host-stage portbroker that auto-forwards container LISTEN ports to `127.0.0.1` on the host. Defaults to `{ "allow": "*" }` (forward everything). Omitted from scaffolded `typeclaw.json`. **Restart-required.** See **portForward** section below.                                                                                                                                                                                      |
+| `docker`      | no       | object           | Namespace for Docker-related blocks. Today the only child is `docker.file` — toggles (`tmux`, `gh`, `python`, `ffmpeg`) gate opinionated apt packages; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, append: [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` rebuilds the image). See **Dockerfile** section below. |
+| `git`         | no       | object           | Namespace for git-related blocks. Today the only child is `git.ignore` — extra patterns spliced into the autogenerated `.gitignore` before TypeClaw's protected rules. `git.ignore` defaults to `{ "append": [] }`. Omitted from scaffolded `typeclaw.json`. **Restart-required** (next `typeclaw start` refreshes `.gitignore`). See **Gitignore** section below.                                                                                                |
 
 > **Top-level keys not in this table are not "ignored unknowns" anymore** — they are reserved for **plugin config blocks**. The schema's `catchall(z.unknown())` preserves them, and the plugin loader hands each block to its owning plugin's `configSchema` for validation. The bundled memory plugin owns `memory` at the top level — see the `typeclaw-memory` skill for that block's semantics. Do not write a top-level key unless you know which plugin owns it.
 
-Within the well-known ten (`$schema`, `port`, `model`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `dockerfile`, `gitignore`), **fields the schema doesn't predeclare are silently dropped**. Do not invent runtime fields like `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, etc. — those are not plugin blocks, they are imaginary. If the user asks for one, say it is not yet supported and (if it makes sense) suggest they file a request.
+Within the well-known ten (`$schema`, `port`, `models`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`), **fields the schema doesn't predeclare are silently dropped**. Legacy top-level `dockerfile` and `gitignore` keys are migrated to `docker.file` / `git.ignore` automatically the first time the CLI loads the file — see **Legacy migration** below. Do not invent runtime fields like `provider`, `apiKey`, `temperature`, `maxTokens`, `systemPrompt`, `tools`, `timeout`, etc. — those are not plugin blocks, they are imaginary. If the user asks for one, say it is not yet supported and (if it makes sense) suggest they file a request.
 
 A scaffolded `typeclaw.json` looks like:
 
@@ -65,17 +65,17 @@ A scaffolded `typeclaw.json` looks like:
 }
 ```
 
-The runtime fills in defaults for any omitted field: `port` → `8973`, `mounts` → `[]` (no host paths exposed), `plugins` → `[]`, `channels` → `{}` (no adapters configured), `portForward` → `{ "allow": "*" }` (forward every container LISTEN port), `dockerfile` → `{ "ffmpeg": false, "gh": true, "python": true, "tmux": true, "append": [] }` (tmux/gh/python pre-installed, ffmpeg off, no custom build steps), `gitignore` → `{ "append": [] }` (no custom ignore patterns). `typeclaw init` deliberately omits any field whose default is owned elsewhere — `mounts`, `portForward`, `dockerfile`, and `gitignore` default via `configSchema`, and the bundled memory plugin owns its own `memory` defaults — so the scaffolded file stays minimal and the user sees only fields they actually need to think about. Add a `memory` block (a **plugin config block** owned by the bundled memory plugin) only when overriding its defaults; see the `typeclaw-memory` skill for the schema.
+The runtime fills in defaults for any omitted field: `port` → `8973`, `mounts` → `[]` (no host paths exposed), `plugins` → `[]`, `channels` → `{}` (no adapters configured), `portForward` → `{ "allow": "*" }` (forward every container LISTEN port), `docker` → `{ "file": { "ffmpeg": false, "gh": true, "python": true, "tmux": true, "append": [] } }` (tmux/gh/python pre-installed, ffmpeg off, no custom build steps), `git` → `{ "ignore": { "append": [] } }` (no custom ignore patterns). `typeclaw init` deliberately omits any field whose default is owned elsewhere — `mounts`, `portForward`, `docker`, and `git` default via `configSchema`, and the bundled memory plugin owns its own `memory` defaults — so the scaffolded file stays minimal and the user sees only fields they actually need to think about. Add a `memory` block (a **plugin config block** owned by the bundled memory plugin) only when overriding its defaults; see the `typeclaw-memory` skill for the schema.
 
 If the user said yes to "Wire a Discord bot?" during `typeclaw init`, the scaffold also includes:
 
 ```json
 "channels": {
-  "discord-bot": { "allow": ["*"] }
+  "discord-bot": {}
 }
 ```
 
-`allow: ["*"]` means "every guild channel and every DM" — appropriate for a single-user dev setup. The wizard asks the user to confirm `["*"]` and warns them when they decline, but the current scaffold writes `["*"]` either way and expects the user to narrow it by hand afterwards. **If the user said they wanted a narrower allow list during init, do not assume the scaffold honored that — read `typeclaw.json` first.** For shared servers, narrow the allow list before joining (see **Channels** below).
+The empty block declares the adapter to the runtime — the schema fills in `enabled: true`, default engagement triggers, and history prefetch. **Access control is separate**: by default an adapter with no `roles` block matching the speaker resolves to `guest` and the router drops every inbound. To let conversations through, declare a `roles` block (see the `typeclaw-permissions` skill). For example, `"roles": { "member": { "match": ["discord:<guild>"] } }` lets every member of that guild reach the agent on the `channel.respond` permission.
 
 ## Mounts
 
@@ -128,39 +128,21 @@ The `mounts/` directory itself is **gitignored** in your agent folder. The mount
 
 ## Channels
 
-`channels` configures which external messenger channels you can read from and post to. **Today the only adapter is `discord-bot`.** The shape is `channels: { "<adapter-id>": { allow, engagement, enabled } }`.
+`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`.
 
-The channels block is **live-reloadable** — edits take effect on the next `reload`, no container restart. This is intentional: allow-rule changes need to feel immediate, otherwise the user has to restart you every time they want to add a channel.
+The channels block is **live-reloadable** — edits take effect on the next `reload`, no container restart.
 
 ### Adapter block
 
 Each entry in `channels` is keyed by adapter id and has this shape:
 
-| Field        | Required | Type             | Notes                                                                                                                                                        |
-| ------------ | -------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| `allow`      | no       | array of strings | List of allow rules. Defaults to `[]`, which means **the agent cannot post anywhere and the inbound bridge gates every message**. See **Allow rules** below. |
-| `engagement` | no       | object           | When the agent should auto-reply vs. stay silent. Defaults to mention/reply/dm with 5-minute reply stickiness. See **Engagement** below.                     |
-| `enabled`    | no       | boolean          | Defaults to `true`. Set `false` to disable the adapter entirely without removing its config.                                                                 |
+| Field        | Required | Type    | Notes                                                                                                                                                                                    |
+| ------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `engagement` | no       | object  | When the agent should auto-reply vs. stay silent. Defaults to mention/reply/dm with 5-minute reply stickiness. See **Engagement** below.                                                 |
+| `history`    | no       | object  | Cold-start prefetch windows for `(thread.head, thread.tail, channel.tail)`. Set any to `0` to disable that side. Defaults to `{ thread: { head: 3, tail: 10 }, channel: { tail: 10 } }`. |
+| `enabled`    | no       | boolean | Defaults to `true`. Set `false` to disable the adapter entirely without removing its config.                                                                                             |
 
-`allow: []` is **not** the same as "deny everything from being delivered to the agent" — the inbound side may still hand you events for processing depending on engagement, but the `channel_send` tool will refuse to post anywhere. Conversely, `allow: ["*"]` does not turn engagement off; engagement and allow are independent gates.
-
-### Allow rules
-
-Each entry in `allow` is a string matching one of the patterns below. Workspace `@dm` is the literal placeholder for direct messages (Discord doesn't expose a guild id for DMs).
-
-| Rule                   | Matches                                                                |
-| ---------------------- | ---------------------------------------------------------------------- |
-| `*`                    | Every guild channel **and** every DM (full firehose).                  |
-| `guild:*`              | Every channel in every guild. Does **not** include DMs.                |
-| `guild:<id>`           | Every channel in guild `<id>`.                                         |
-| `guild:<id>/<channel>` | Channel `<channel>` in guild `<id>` only.                              |
-| `channel:<id>`         | Channel `<id>` in any guild (Discord channel IDs are globally unique). |
-| `dm:*`                 | Every DM channel. Does **not** include guild channels.                 |
-| `dm:<id>`              | DM channel `<id>` only.                                                |
-
-The schema validates each rule string at load. **Bad rule = config load fails**, the runtime refuses to boot or refuses the reload. Don't fudge this; the regex is strict (numeric IDs only).
-
-`channel:<id>` is the most surgical option and the right default when the user says "let me talk to you in #the-channel-i'm-pointing-at" — channel IDs are globally unique so you don't need the guild id. `guild:<id>` is convenient on a server you fully trust. `*` and `guild:*` are firehose patterns; only set them in single-user setups.
+To stop the agent answering in a specific channel, narrow the `roles` block so the speaking author's role no longer carries `channel.respond` — engagement triggers gate wake-up _given_ the message is admitted; `channel.respond` gates whether the message is admitted at all.
 
 ### Engagement
 
@@ -181,59 +163,51 @@ The schema validates each rule string at load. **Bad rule = config load fails**,
   - `perReply` means: after the agent replies to a user, follow-up messages from that same user in that same channel within the window also wake the loop, even without a mention. The window is bounded server-side (`1` to `86_400_000` ms — 1 ms to 24 hours).
   - `"off"` disables stickiness — the agent only wakes on explicit triggers.
 
-There is also a **solo-human fallback** built into the runtime that is **not configurable** through `engagement`: in any allow-listed channel where the participants cache currently holds at most one distinct human author, every admitted inbound wakes the loop, regardless of `trigger` or `stickiness`. The fallback turns off the moment a second distinct human posts in that channel. This makes "private dev channel with one human and the bot" work without forcing an `@mention` on every message; clearing `trigger` to `[]` does **not** override it. If a user wants strict mention-only behavior in a one-human channel today, the answer is "wait for the post-v0.3 engagement-config work" — not a config edit.
+There is also a **solo-human fallback** built into the runtime that is **not configurable** through `engagement`: in any channel where the participants cache currently holds at most one distinct human author, every admitted inbound wakes the loop, regardless of `trigger` or `stickiness`. The fallback turns off the moment a second distinct human posts in that channel. This makes "private dev channel with one human and the bot" work without forcing an `@mention` on every message; clearing `trigger` to `[]` does **not** override it.
 
-**Engagement does not gate posting.** It gates whether you wake up. If you decide to call `channel_send` to a channel that isn't in `allow`, the tool returns `{ ok: false, error }` regardless of engagement.
-
-To make the agent silent in a channel without removing it from `allow`, the right move is usually `engagement: { trigger: [], stickiness: "off" }`, **not** removing the allow rule — removing the allow rule cuts off both inbound visibility and outbound posting, which is rarely what the user means by "stop replying". Caveat: in a one-human channel the solo-human fallback overrides `trigger: []` and the agent will still wake; the only way to silence the bot in that case is to remove the allow rule (or add a second human to the channel).
+**Engagement does not gate access.** Access is gated by `permissions.has(origin, 'channel.respond')` — see the `typeclaw-permissions` skill. Engagement decides whether an _admitted_ inbound wakes the loop or sits in the context buffer.
 
 ### Example
 
 ```json
 "channels": {
   "discord-bot": {
-    "allow": [
-      "guild:123456789012345678/987654321098765432",
-      "dm:*"
-    ],
     "engagement": {
       "trigger": ["mention", "reply", "dm"],
       "stickiness": { "perReply": { "window": 300000 } }
     },
     "enabled": true
   }
+},
+"roles": {
+  "member": { "match": ["discord:123456789012345678/987654321098765432", "discord:dm/*"] }
 }
 ```
 
-This says: only one specific channel in one specific guild plus all DMs are visible/postable; auto-reply on mentions, replies, or DMs; sticky for 5 minutes after replying to a user.
+This says: the `discord-bot` adapter is enabled with default engagement; one specific channel in one specific guild plus all DMs admit speakers as `member` (which carries `channel.respond` by default).
 
 ### When the user asks "let me talk to you in this channel"
 
-1. **Read `typeclaw.json`.**
-2. **Identify the adapter.** Today this is always `discord-bot`. If `channels["discord-bot"]` is missing, create it: `{ "allow": [], "engagement": { ... defaults ... }, "enabled": true }`.
-3. **Get the channel ID from the user.** Discord channel IDs are 17–20 digit numbers. If they only gave a `#channel-name`, ask for the ID — names aren't unique and the schema needs IDs.
-4. **Pick the rule shape:**
-   - DM: `dm:<channelId>` (or `dm:*` if they want all DMs).
-   - Guild channel they fully trust: `guild:<guildId>/<channelId>` is most explicit; `channel:<channelId>` is shorter and equivalent.
-   - Whole guild: `guild:<guildId>` — confirm explicitly that they want every channel.
-5. **Append to `allow`.** Preserve existing entries.
-6. **Write the file back** (pretty-printed, 2-space indent, trailing newline).
-7. **Commit** with a message naming the rule and why (`typeclaw-git` skill).
-8. **Tell the user the effect:** "Added `<rule>` to `channels.discord-bot.allow`. This is live-reloadable — it takes effect on the next `reload`, no restart needed."
+This is a **`roles`** edit, not a `channels` edit. See the `typeclaw-permissions` skill for the full procedure. Short version:
+
+1. Get the platform ID (Discord channel ID, Slack channel ID, Telegram chat ID, KakaoTalk chat ID).
+2. Append a match-rule to `roles.member.match` using the canonical DSL (`discord:<guild>/<channel>`, `slack:<team>/<channel>`, `telegram:<chat>`, `kakao:<chat>`).
+3. **`roles` is restart-required** — `typeclaw reload` won't apply it; the user needs `typeclaw restart`.
 
 ### When the user asks "stop replying in this channel"
 
 Two interpretations — ask if unclear:
 
-- **"Stop everything"** — remove the matching allow rule. The agent loses both inbound visibility and outbound `channel_send` permission for that channel.
-- **"Just stop auto-replying"** — leave the allow rule, but adjust `engagement` (set `trigger: []` and/or `stickiness: "off"`). The agent can still see the channel and can still post if you tell it to. Caveat: this approach does NOT silence the agent in a channel that currently has only one human posting — the solo-human fallback (see Engagement) overrides `trigger: []`. In that case the only way to go silent today is to remove the allow rule.
+- **"Stop everything"** — remove the match-rule from `roles.<role>.match`. The agent loses both inbound visibility and outbound posting on that channel.
+- **"Just stop auto-replying"** — leave the match-rule, but adjust `engagement` on the adapter (set `trigger: []` and/or `stickiness: "off"`). The agent can still receive the channel and can still post if you tell it to. Caveat: this approach does NOT silence the agent in a channel that currently has only one human posting — the solo-human fallback (see Engagement) overrides `trigger: []`. In that case the only way to go silent today is to remove the match-rule.
 
 The second is usually what people mean by "be quieter".
 
 ### When the user asks "what channels can you see / are you in"
 
-1. **Read `typeclaw.json`**, list each adapter under `channels`: which is enabled, the full `allow` list, the engagement triggers and stickiness window.
-2. Note that the live runtime may have a different view if `typeclaw.json` was edited but `reload` hasn't run yet — say so when relevant.
+1. **Read `typeclaw.json`**, list each adapter under `channels`: which is enabled, the engagement triggers and stickiness window.
+2. Also read `roles.<role>.match` for every role — those are the actual admit lists.
+3. Note that the live runtime may have a different view if `typeclaw.json` was edited but `reload` hasn't run yet — say so when relevant.
 
 ## Alias
 
@@ -361,10 +335,10 @@ Off switch — the broker is constructed but never opens a WS, no LISTEN gets fo
 
 `typeclaw start` rewrites the agent folder's `Dockerfile` from a template baked into the typeclaw CLI on **every** invocation — not just on `init`. The Dockerfile is in the truly-ignored `.gitignore` category specifically because it's regenerated; the source of truth for the template is `src/init/dockerfile.ts` in the typeclaw repo, not the agent folder. This means: editing the Dockerfile by hand inside the agent folder is pointless (the next `typeclaw start` overwrites it), and a clean clone of an agent folder onto a fresh machine works only because `start` materializes the Dockerfile before `docker build` reads it.
 
-The `dockerfile` block has two layers of customization:
+The `docker.file` block has two layers of customization:
 
 1. **Toggles** for opinionated apt packages typeclaw knows how to install with proper layer caching (`tmux`, `gh`, `python`, `ffmpeg`). Boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`). Use these whenever they cover what the user wants — they get BuildKit cache-mount benefits and, for `gh`, automatic keyring layer gating.
-2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#dockerfile.append.` comment.
+2. **`append`** is the escape hatch for everything the toggles don't cover. An array of single-line Dockerfile instructions spliced in right before `ENTRYPOINT`, prefixed with a `# Custom lines from typeclaw.json#docker.file.append.` comment.
 
 ### Fields
 
@@ -383,11 +357,13 @@ Toggle version strings reject whitespace and `=` (apt-injection guard) — pass
 Each entry of `append` must be one Dockerfile instruction's worth of source — a `RUN`, `ENV`, `COPY`, `ARG`, etc. The schema enforces "no embedded newlines" because a multiline string in the JSON would silently break Dockerfile syntax (Dockerfile line continuations require backslashes at end-of-line, and a JSON multiline doesn't carry those). If the user wants a logically multi-step instruction, give them two entries:
 
 ```json
-"dockerfile": {
-  "append": [
-    "RUN apt-get update && apt-get install -y --no-install-recommends ripgrep fd-find",
-    "ENV CUSTOM_TOOL=1"
-  ]
+"docker": {
+  "file": {
+    "append": [
+      "RUN apt-get update && apt-get install -y --no-install-recommends ripgrep fd-find",
+      "ENV CUSTOM_TOOL=1"
+    ]
+  }
 }
 ```
 
@@ -401,7 +377,7 @@ The template's last layers are roughly:
 RUN apt-get install ... <baseline + enabled toggle packages>   ← toggles fan out into this line
 ...
 ENV NODE_ENV=production
-# Custom lines from typeclaw.json#dockerfile.append.   ← only emitted when append is non-empty
+# Custom lines from typeclaw.json#docker.file.append.   ← only emitted when append is non-empty
 <your appended lines>
 ENTRYPOINT ["/usr/local/bin/typeclaw-entrypoint"]
 CMD ["run"]
@@ -413,23 +389,23 @@ The toggle-driven apt install benefits from BuildKit `--mount=type=cache` on `/v
 
 ### Restart and rebuild semantics
 
-- **Restart-required.** `dockerfile` is in `FIELD_EFFECTS` as restart-required. `reload` reports the change as `restartRequired` and the live container keeps running on the old image.
-- **The next `typeclaw start` rebuilds the image automatically.** No `--build` flag is needed; the CLI re-runs `docker build` whenever the Dockerfile content has changed (it rewrites the file from the current template + current `dockerfile` block every start). Tell the user: "Edited `dockerfile` — restart-required. The next `typeclaw start` will rewrite the Dockerfile and rebuild the image."
+- **Restart-required.** `docker.file` is in `FIELD_EFFECTS` as restart-required. `reload` reports the change as `restartRequired` and the live container keeps running on the old image.
+- **The next `typeclaw start` rebuilds the image automatically.** No `--build` flag is needed; the CLI re-runs `docker build` whenever the Dockerfile content has changed (it rewrites the file from the current template + current `docker.file` block every start). Tell the user: "Edited `docker.file` — restart-required. The next `typeclaw start` will rewrite the Dockerfile and rebuild the image."
 - **Pre-existing host-side edits to the Dockerfile are clobbered.** If the user manually edited the Dockerfile before, the next `start` overwrites it and (if the working tree was dirty) auto-commits the cleanup. This is by design; don't try to preserve manual edits.
 
 ### When the user asks "install <package> in the container" / "add a Dockerfile line"
 
 1. **Read `typeclaw.json`.**
-2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, or `ffmpeg`, prefer the toggle: `"dockerfile": { "ffmpeg": true }`. For a pinned version, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`.
+2. **Check if a toggle covers it.** If the package is `tmux`, `gh`, `python`, or `ffmpeg`, prefer the toggle: `"docker": { "file": { "ffmpeg": true } }`. For a pinned version, pass the version string: `"gh": "2.40.0"`. This is faster (BuildKit cache mount) and clearer than `append`.
 3. **Otherwise, use `append`.** Decide on a single-line entry — for apt installs, prefer one `RUN apt-get update && apt-get install -y --no-install-recommends <pkg> && rm -rf /var/lib/apt/lists/*` line. For env vars, one `ENV` line per variable.
 4. **Validate no embedded newlines** (`append` only). Multi-step logic must be `&&`-chained on one line, not split across array entries unless those entries are independent Dockerfile instructions.
-5. **Append to `dockerfile.append`** (creating the field if it doesn't exist). Preserve existing entries.
-6. **Write, commit, restart-required**: "Edited `dockerfile` — restart-required. The next `typeclaw start` will rewrite the Dockerfile and rebuild the image. The new layer will be at the end of the build, so unrelated cache layers stay valid."
+5. **Append to `docker.file.append`** (creating the field if it doesn't exist). Preserve existing entries.
+6. **Write, commit, restart-required**: "Edited `docker.file` — restart-required. The next `typeclaw start` will rewrite the Dockerfile and rebuild the image. The new layer will be at the end of the build, so unrelated cache layers stay valid."
 
 ### When the user asks "uninstall <package>" / "make the image smaller"
 
 1. **Read `typeclaw.json`.**
-2. **If the package is one of the toggles**, set it to `false`: `"dockerfile": { "tmux": false }`. Don't try to remove it via `append` — the toggle is the only way to omit a baseline package from the apt install line.
+2. **If the package is one of the toggles**, set it to `false`: `"docker": { "file": { "tmux": false } }`. Don't try to remove it via `append` — the toggle is the only way to omit a baseline package from the apt install line.
 3. **If it's an `append` entry**, remove that entry from the array.
 4. **Write, commit, restart-required.** Same rebuild story.
 
@@ -442,14 +418,14 @@ The toggle-driven apt install benefits from BuildKit `--mount=type=cache` on `/v
 ### When the user asks "remove that custom Dockerfile line"
 
 1. **Read `typeclaw.json`.**
-2. **Remove the entry from `dockerfile.append`.** If the resulting array is empty AND no toggles are overridden, you may either leave it as `"append": []` or drop the whole `dockerfile` block — both are equivalent. Dropping it keeps the file minimal and matches the scaffold convention.
+2. **Remove the entry from `docker.file.append`.** If the resulting array is empty AND no toggles are overridden, you may either leave it as `"append": []` or drop the whole `docker` block — both are equivalent. Dropping it keeps the file minimal and matches the scaffold convention.
 3. **Write, commit, restart-required.** Same restart story as adding: next `typeclaw start` rebuilds.
 
 ## Gitignore
 
 `typeclaw start` rewrites the agent folder's `.gitignore` from a template baked into the typeclaw CLI on **every** invocation, then auto-commits it when the agent folder is a git repo and the file changed. The template protects two categories: truly-ignored paths (`.env`, `node_modules/`, `workspace/`, `mounts/`, `Dockerfile`, `.DS_Store`) and system-managed runtime state (`sessions/`, `memory/`, `channels/`) that TypeClaw, not the agent, commits on its own schedule. Editing `.gitignore` by hand is temporary; the next `typeclaw start` overwrites it.
 
-The `gitignore.append` field is the supported escape hatch for additional local ignore patterns. It is an array of strings, each treated as a single `.gitignore` line. The CLI splices them into the autogenerated `.gitignore` before TypeClaw's protected rules, prefixed with a `# Custom entries from typeclaw.json#gitignore.append.` comment.
+The `git.ignore.append` field (introduced when the legacy top-level `gitignore` key was nested under the `git` namespace for future extensibility — see **Legacy migration**) is the supported escape hatch for additional local ignore patterns. It is an array of strings, each treated as a single `.gitignore` line. The CLI splices them into the autogenerated `.gitignore` before TypeClaw's protected rules, prefixed with a `# Custom entries from typeclaw.json#git.ignore.append.` comment.
 
 ### Field
 
@@ -459,12 +435,12 @@ The `gitignore.append` field is the supported escape hatch for additional local
 
 ### Ordering and protected paths
 
-`.gitignore` is order-sensitive: later `!` negation rules can unignore earlier ignore rules. TypeClaw therefore renders `gitignore.append` **before** its own truly-ignored and system-managed entries, so even a custom `!sessions/` or `!.env` cannot override TypeClaw's protections. Custom ordinary ignore patterns still work because they add additional ignores; they just do not get the final word over TypeClaw-owned paths.
+`.gitignore` is order-sensitive: later `!` negation rules can unignore earlier ignore rules. TypeClaw therefore renders `git.ignore.append` **before** its own truly-ignored and system-managed entries, so even a custom `!sessions/` or `!.env` cannot override TypeClaw's protections. Custom ordinary ignore patterns still work because they add additional ignores; they just do not get the final word over TypeClaw-owned paths.
 
 Materialized shape when `append` is non-empty:
 
 ```gitignore
-# Custom entries from typeclaw.json#gitignore.append.
+# Custom entries from typeclaw.json#git.ignore.append.
 scratch/
 *.local.log
 
@@ -480,26 +456,42 @@ channels/
 
 ### Restart semantics
 
-- **Restart-required.** `gitignore` is in `FIELD_EFFECTS` as restart-required. `reload` reports the change as `restartRequired`; the already-materialized `.gitignore` on disk remains unchanged until the next host-stage start.
-- **The next `typeclaw start` refreshes and auto-commits `.gitignore`.** Tell the user: "Edited `gitignore.append` — restart-required. The next `typeclaw start` will rewrite `.gitignore` and TypeClaw will auto-commit it if the file changes."
+- **Restart-required.** `git.ignore` is in `FIELD_EFFECTS` as restart-required. `reload` reports the change as `restartRequired`; the already-materialized `.gitignore` on disk remains unchanged until the next host-stage start.
+- **The next `typeclaw start` refreshes and auto-commits `.gitignore`.** Tell the user: "Edited `git.ignore.append` — restart-required. The next `typeclaw start` will rewrite `.gitignore` and TypeClaw will auto-commit it if the file changes."
 
 ### When the user asks "ignore this path" / "add a gitignore entry"
 
 1. **Read `typeclaw.json`.**
 2. **Decide on single-line patterns.** Use one array entry per `.gitignore` pattern. Do not embed newlines.
-3. **Append to `gitignore.append`** (creating the field if it doesn't exist). Preserve existing entries.
+3. **Append to `git.ignore.append`** (creating the field if it doesn't exist). Preserve existing entries.
 4. **Do not edit `.gitignore` directly.** It is managed and will be overwritten on `typeclaw start`.
-5. **Write, commit, restart-required**: "Edited `gitignore.append` — restart-required. The next `typeclaw start` will rewrite and auto-commit `.gitignore`."
+5. **Write, commit, restart-required**: "Edited `git.ignore.append` — restart-required. The next `typeclaw start` will rewrite and auto-commit `.gitignore`."
 
 ### When the user asks "remove that custom ignore entry"
 
 1. **Read `typeclaw.json`.**
-2. **Remove the entry from `gitignore.append`.** If the resulting array is empty, you may either leave it as `"append": []` or drop the whole `gitignore` block — both are equivalent. Dropping it keeps the file minimal and matches the scaffold convention.
+2. **Remove the entry from `git.ignore.append`.** If the resulting array is empty, you may either leave it as `"append": []` or drop the whole `git` block — both are equivalent. Dropping it keeps the file minimal and matches the scaffold convention.
 3. **Write, commit, restart-required.** Same refresh story as adding: next `typeclaw start` rewrites and auto-commits `.gitignore` if content changed.
 
+## Legacy migration
+
+Pre-namespace `typeclaw.json` files carried `dockerfile` and `gitignore` as top-level keys. The current schema nests them under `docker.file` and `git.ignore` so the `docker` and `git` namespaces stay free for future siblings (`docker.compose`, `git.attributes`, etc.) without a second rename.
+
+The first time `validateConfig` or `loadConfigSync` reads a legacy file:
+
+1. The in-memory JSON is rewritten: top-level `dockerfile` → `docker.file`, top-level `gitignore` → `git.ignore`.
+2. The same rewrite is persisted back to `typeclaw.json` on disk (pretty-printed, trailing newline). Best-effort: a read-only filesystem just retries next start.
+3. If the file already has a `docker` or `git` block AND the legacy key, the new shape wins — the legacy duplicate is dropped silently. The new shape would have shadowed the legacy at parse time anyway.
+
+What this means for you:
+
+- **Do not write top-level `dockerfile` or `gitignore` keys** when editing `typeclaw.json`. They'll be migrated away on the next CLI invocation; meanwhile the file is briefly in an inconsistent shape.
+- **Old documentation or examples that still mention `typeclaw.json#dockerfile.append` are stale.** The current path is `typeclaw.json#docker.file.append`. Same for `git.ignore.append`.
+- **An auto-commit may appear** the next time `typeclaw start` runs against a freshly-migrated agent folder. The diff is mechanical (top-level rename → nested) — surface it to the user as a one-time migration, not a behavior change.
+
 ## Plugin config blocks
 
-Top-level keys in `typeclaw.json` that are **not** in the well-known ten (`$schema`, `port`, `model`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `dockerfile`, `gitignore`) are treated as plugin config blocks. The schema preserves them via `catchall(z.unknown())`, and `extractPluginConfigs` hands each block to the owning plugin's `configSchema` for validation at boot.
+Top-level keys in `typeclaw.json` that are **not** in the well-known ten (`$schema`, `port`, `models`, `mounts`, `plugins`, `alias`, `channels`, `portForward`, `docker`, `git`) are treated as plugin config blocks. The schema preserves them via `catchall(z.unknown())`, and `extractPluginConfigs` hands each block to the owning plugin's `configSchema` for validation at boot.
 
 This skill does **not** document individual plugin blocks. For schema, defaults, and reload semantics of a specific plugin's config, defer to that plugin's own skill:
 
@@ -598,14 +590,14 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 
 1. **Read the whole file first** with the `read` tool. Don't assume what's in it — the user may have customized it.
 2. **Modify in memory.** Change only the field(s) the user asked about. Leave `$schema` alone.
-3. **Write the whole file back** with the `write` tool. Always pretty-printed (2-space indent), trailing newline, fields in stable order: `$schema` first, then alphabetical for the rest (`alias`, `channels`, `dockerfile`, `gitignore`, `model`, `mounts`, `plugins`, `port`, `portForward`, then any plugin config blocks like `memory`).
+3. **Write the whole file back** with the `write` tool. Always pretty-printed (2-space indent), trailing newline, fields in stable order: `$schema` first, then alphabetical for the rest (`alias`, `channels`, `docker`, `git`, `model`, `mounts`, `plugins`, `port`, `portForward`, then any plugin config blocks like `memory`).
 4. **Validate before declaring done.** A malformed `typeclaw.json` will refuse to boot the agent on next restart, and a malformed reload-time edit will be rejected by `reload`. Sanity-check your JSON manually or with `bash` (`cat typeclaw.json | jq .`) before considering the edit done.
 5. **Commit the change.** See the `typeclaw-git` skill for the commit-message rule (decision context required). `typeclaw.json` is not gitignored, so an uncommitted edit will pollute your next commit.
 6. **Tell the user the right next step.** Match the field's effect class:
    - `model`, `alias`, `channels` → "Live-reloadable, takes effect on the next `reload`."
    - `port`, `mounts`, `plugins`, `portForward` → "Restart-required. Run `typeclaw restart` (host stage) to pick up the change."
-   - `dockerfile` → "Restart-required, and the next `typeclaw start` will rebuild the image automatically (no `--build` flag needed)."
-   - `gitignore` → "Restart-required, and the next `typeclaw start` will rewrite and auto-commit `.gitignore` if content changed."
+   - `docker.file` → "Restart-required, and the next `typeclaw start` will rebuild the image automatically (no `--build` flag needed)."
+   - `git.ignore` → "Restart-required, and the next `typeclaw start` will rewrite and auto-commit `.gitignore` if content changed."
    - Plugin config blocks (e.g. `memory`) → restart-required by convention because plugins read their config once at boot. Defer to the plugin's own skill for the exact semantics.
    - Mixed edits in one go → spell out which is which; do not collapse to "restart" if part of the change is live.
 
@@ -620,12 +612,12 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 - If `model` is set: exactly one of the values in **Allowed models** above
 - If `plugins` is set: array of non-empty strings
 - If `alias` is set: array of strings, each non-empty after trimming surrounding whitespace
-- If `channels.discord-bot.allow` is set: every entry matches one of the **Allow rules** patterns above (numeric IDs only)
-- If `channels.discord-bot.engagement.trigger` is set: array of `"mention"`, `"reply"`, `"dm"` (any subset, including empty)
-- If `channels.discord-bot.engagement.stickiness` is set: either the literal `"off"` or `{ "perReply": { "window": <int 1..86400000> } }`
+- If `channels.<adapter>.engagement.trigger` is set: array of `"mention"`, `"reply"`, `"dm"` (any subset, including empty)
+- If `channels.<adapter>.engagement.stickiness` is set: either the literal `"off"` or `{ "perReply": { "window": <int 1..86400000> } }`
+- `channels.<adapter>.allow` (legacy) is silently dropped on parse; `migrateLegacyConfigShape` lifts it into `roles.member.match` on load. See the `typeclaw-permissions` skill.
 - If `portForward` is set: `allow` is either `"*"` or an array of integers (1–65535); `deny`, if present, is an array of integers and **only valid when `allow` is `"*"`** (the schema rejects `deny` paired with a number-array `allow`)
-- If `dockerfile.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
-- If any `dockerfile` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `python` is boolean only
+- If `docker.file.append` is set: array of strings, each with no embedded `\n` or `\r` (multi-step shell logic goes in a single `&&`-chained `RUN` entry)
+- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `python` is boolean only
 - No unknown top-level keys you invented — keys outside the well-known ten are interpreted as **plugin config blocks** and only do something if a plugin owns them. Inventing one means the user thinks it took effect and it did not.
 
 ## Things you must not do
@@ -639,14 +631,14 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 - **Do not re-add `"mounts": []` "for clarity" if the user has none.** The scaffold deliberately omits it; defaults live in `configSchema`. Re-emitting it adds maintenance noise (the user has to keep two sources of truth in sync) without changing behavior.
 - **Do not promise to write to a `readOnly: true` mount.** Docker enforces it via `:ro`; writes will fail with EROFS. If the user wants you to edit a read-only mount, the fix is to flip `readOnly` to `false` in `typeclaw.json` and restart, not to retry the write.
 - **Do not invent mount entries the user did not request.** Mounts expose host paths to your container; adding them silently is a security surprise.
-- **Do not add channel allow rules the user did not request, especially `*` or `guild:*`.** Allow rules grant the agent visibility (and, for outbound, posting permission) on real Discord channels with real people in them. Widening the allow list silently is the same class of security surprise as adding a mount.
-- **Do not promise the user that an allow-rule edit took effect immediately just because you wrote the file.** Live-reloadable means "applied on the next `reload`", not "applied the instant the file changes". Until `reload` runs (or the container restarts), the runtime is still using the old `channels` config.
-- **Do not promise to post to a channel that isn't in `allow`.** `channel_send` will refuse with `{ ok: false, error }` regardless of what you tell the user. If they want you to post somewhere new, the prerequisite is an allow-rule edit, not a retry.
-- **Do not conflate "stop replying" with "remove allow rule".** Removing the allow rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
-- **Do not edit the `Dockerfile` directly.** It is autogenerated and rewritten on every `typeclaw start` from `src/init/dockerfile.ts` in the typeclaw repo. Manual edits will be silently overwritten (and auto-committed away if the working tree is dirty). Customizations belong in the `dockerfile` block (toggles or `append`).
-- **Do not reach for `dockerfile.append` when a toggle covers it.** If the user wants tmux, gh, python, or ffmpeg installed (or removed, or pinned), use the toggle — it's the cache-mounted path. `append` for these is slower and harder to read.
-- **Do not use `dockerfile.append` for things that belong in the template.** If the user wants a system package _every_ typeclaw user should have, that's a typeclaw release, not a per-agent `append`. Suggest filing an issue.
-- **Do not put multiline strings in `dockerfile.append`.** The schema rejects entries with embedded `\n`/`\r`. Use one entry per Dockerfile instruction; chain shell logic with `&&` on one line.
+- **Do not add `roles.<role>.match` entries the user did not request, especially `*` or platform-wildcards (`discord:*`, `slack:*`).** Match-rules grant the agent visibility (and, for outbound, posting permission) on real channels with real people in them. Widening them silently is the same class of security surprise as adding a mount. See the `typeclaw-permissions` skill.
+- **Do not promise the user that a `roles` edit took effect immediately just because you wrote the file.** `roles` is **restart-required** — `typeclaw reload` returns it under `restartRequired`; the live runtime keeps the old role table until `typeclaw restart`.
+- **Do not promise to post to a channel the speaker's role does not cover.** The router drops every inbound where the speaking author resolves to a role without `channel.respond`. If the user wants you to post somewhere new, the prerequisite is a `roles` edit + restart, not a retry.
+- **Do not conflate "stop replying" with "remove the role's match-rule".** Removing the match-rule cuts off both inbound visibility and outbound posting. If the user just wants quieter behavior, edit `engagement` instead.
+- **Do not edit the `Dockerfile` directly.** It is autogenerated and rewritten on every `typeclaw start` from `src/init/dockerfile.ts` in the typeclaw repo. Manual edits will be silently overwritten (and auto-committed away if the working tree is dirty). Customizations belong in the `docker.file` block (toggles or `append`).
+- **Do not reach for `docker.file.append` when a toggle covers it.** If the user wants tmux, gh, python, or ffmpeg installed (or removed, or pinned), use the toggle — it's the cache-mounted path. `append` for these is slower and harder to read.
+- **Do not use `docker.file.append` for things that belong in the template.** If the user wants a system package _every_ typeclaw user should have, that's a typeclaw release, not a per-agent `append`. Suggest filing an issue.
+- **Do not put multiline strings in `docker.file.append`.** The schema rejects entries with embedded `\n`/`\r`. Use one entry per Dockerfile instruction; chain shell logic with `&&` on one line.
 - **Do not pass `pkg=ver` as a toggle version string.** The schema rejects `=` in version strings. Pass just the version (`"gh": "2.40.0"`); the renderer prepends `pkg=` itself. Same for whitespace — version strings cannot contain spaces.
 - **Do not list `8973` (or whatever `port` is set to) in `portForward.allow`/`deny`.** That port is owned by `docker run -p`; the broker quietly excludes it regardless. Listing it is misleading.
 - **Do not combine `portForward.deny` with a number-array `allow`.** The schema rejects this; the deny rule would have no effect even if the schema allowed it. `deny` is only meaningful with `allow: "*"`.
@@ -678,5 +670,5 @@ Never echo, log, or commit values from `.env` or `secrets.json`. Both are gitign
 - **Identity files** (`IDENTITY.md`, `SOUL.md`, `USER.md`, `AGENTS.md`) — these are not runtime config; they are _you_. Edit them directly when relevant; no skill needed.
 - **`MEMORY.md` and `memory/`** — explicit exception to the line above. `MEMORY.md` is **dreaming-owned** and you must not write to it directly; the `memory/` directory holds runtime-managed daily streams and muscle-memory skills. See the `typeclaw-memory` skill before touching anything memory-shaped.
 - **Skills directories** (`.agents/skills/`, `memory/skills/`, the bundled `src/skills/`) — these are loaded from disk by the runtime; they are not driven by `typeclaw.json`. See the `typeclaw-skills` skill for the three layers, the `bunx skills` CLI, and the lockfile-based "downloaded vs hand-authored" rule.
-- **The Dockerfile template itself** (the autogenerated layers in `Dockerfile`: bun base image, apt setup, GitHub CLI, `agent-browser`, Chrome for Testing) — that is host-stage, controlled by `src/init/dockerfile.ts` in the typeclaw repo, not by `typeclaw.json`. `typeclaw.json#dockerfile.append` (covered above) is the only piece of the build customizable per-agent; everything else requires a typeclaw release.
+- **The Dockerfile template itself** (the autogenerated layers in `Dockerfile`: bun base image, apt setup, GitHub CLI, `agent-browser`, Chrome for Testing) — that is host-stage, controlled by `src/init/dockerfile.ts` in the typeclaw repo, not by `typeclaw.json`. `typeclaw.json#docker.file.append` (covered above) is the only piece of the build customizable per-agent; everything else requires a typeclaw release.
 - **The host-stage launcher's invocation flags** (`docker run` arguments synthesized by `typeclaw start`, the `_hostd` daemon's lifecycle, the host port allocation that maps to `port` inside the container) — those are host-stage code, not config. The pieces of that flow that **are** user-configurable through `typeclaw.json` (`port`, `mounts`, `portForward`) are documented above; the rest is not.

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

@@ -45,7 +45,7 @@ When dreaming fires, it reads:
 1. `MEMORY.md`
 2. The **undreamed tail** of every `memory/yyyy-MM-dd.md` (the runtime tells it the exact line range — earlier lines are already consolidated into `MEMORY.md` and must NOT be re-read)
 
-It rewrites `MEMORY.md` with the merged result, advances the per-day watermark in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, then `git commit -m "Dream"` the snapshot. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
+It rewrites `MEMORY.md` with the merged result, advances the per-day watermark in `memory/.dreaming-state.json`, optionally writes muscle-memory skills under `memory/skills/<name>/SKILL.md`, then commits the snapshot with a message shaped like `dream: <summary> <emoji>` — e.g. `dream: 3 fragments + new skill 'pr-review' 🔮`. The summary is derived from the staged diff (line additions in daily streams, newly-added skills, etc.), and the emoji is a random pick from a small thematic pool. After the commit, the runtime sets the `skip-worktree` index flag on the tracked memory artifacts so the user's `git status` and `git diff` stay clean. The flag is cleared and re-applied around every commit.
 
 The dreaming subagent has only three tools: `read`, `write`, `ls`. No `bash`. No `edit`. It cannot run shell commands.
 
@@ -74,7 +74,7 @@ If the undreamed tails contain only watermarks, or every new fragment is already
 
 ### What gets injected into your prompt every turn
 
-The plugin's `session.prompt` hook appends a `# Memory` section to your system prompt with:
+Core's `createResourceLoader` appends a `# Memory` section as the LAST block of your system prompt (after `gitNudge`) by calling `loadMemory`. It is pinned to the cache-suffix end so growth in the daily stream invalidates only the memory section itself, not the skills/tools/history above. The section contains:
 
 - `MEMORY.md` (truncated to 12 KB; if larger, the rest is dropped with a `[truncated]` marker)
 - The **undreamed tails** of each `memory/yyyy-MM-dd.md`, with bare watermark lines stripped (they are bookkeeping for the memory-logger, no signal for you)
@@ -115,19 +115,19 @@ You cannot remove a fragment cleanly. The right response depends on what X is:
 
 ## When the user asks "what did you dream?" / "when do you dream next?"
 
-1. **What you dreamed**: read the most recent `Dream` git commit on your agent folder (`git log --grep='^Dream' -1`) and show the diff against `MEMORY.md` if useful. The commit timestamp tells you when dreaming last ran. If the answer is "no `Dream` commits yet", say that — `MEMORY.md` may exist but be the auto-created empty file from the first dreaming attempt.
+1. **What you dreamed**: read the most recent `dream:` git commit on your agent folder (`git log --grep='^dream:' -1`) and show the diff against `MEMORY.md` if useful. The commit timestamp tells you when dreaming last ran. If the answer is "no `dream:` commits yet", say that — `MEMORY.md` may exist but be the auto-created empty file from the first dreaming attempt.
 2. **When you dream next**: read `memory.dreaming.schedule` from `typeclaw.json` (default `"*/30 * * * *"` — every 30 minutes). Translate the cron expression to a wall-clock time in the agent's `TZ`. The dreaming cron job is **always registered** even when `memory.dreaming` is omitted; the default schedule applies. Tell the user honestly when the next fire is in the agent's local time.
 
 ## When the user asks "what's a daily stream?" / "where is your memory stored?"
 
 Stay concrete. Use this map:
 
-| File / dir                      | What it is                                                                    | Who writes it                                                  | Tracked in git                                              |
-| ------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ----------------------------------------------------------- |
-| `MEMORY.md`                     | Long-term memory, consolidated topics with fragment citations.                | Dreaming subagent (rewrites in full on each run).              | Yes (force-committed under `Dream` commits, skip-worktree). |
-| `memory/yyyy-MM-dd.md`          | Daily fragment streams. Append-only during the day.                           | Memory-logger subagent (one fragment ≈ one prompt completion). | Gitignored, but force-committed in the dreaming snapshot.   |
-| `memory/skills/<name>/SKILL.md` | Muscle-memory skills distilled from recurring procedures.                     | Dreaming subagent only.                                        | Gitignored, force-committed in the dreaming snapshot.       |
-| `memory/.dreaming-state.json`   | Per-day watermarks (line counts already consolidated). Plain JSON, fail-open. | Dreaming subagent.                                             | Gitignored, force-committed in the dreaming snapshot.       |
+| File / dir                      | What it is                                                                    | Who writes it                                                  | Tracked in git                                               |
+| ------------------------------- | ----------------------------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------ |
+| `MEMORY.md`                     | Long-term memory, consolidated topics with fragment citations.                | Dreaming subagent (rewrites in full on each run).              | Yes (force-committed under `dream:` commits, skip-worktree). |
+| `memory/yyyy-MM-dd.md`          | Daily fragment streams. Append-only during the day.                           | Memory-logger subagent (one fragment ≈ one prompt completion). | Gitignored, but force-committed in the dreaming snapshot.    |
+| `memory/skills/<name>/SKILL.md` | Muscle-memory skills distilled from recurring procedures.                     | Dreaming subagent only.                                        | Gitignored, force-committed in the dreaming snapshot.        |
+| `memory/.dreaming-state.json`   | Per-day watermarks (line counts already consolidated). Plain JSON, fail-open. | Dreaming subagent.                                             | Gitignored, force-committed in the dreaming snapshot.        |
 
 `typeclaw init` does **not** scaffold any of these. They appear when needed — `MEMORY.md` and `memory/` are created by the first dreaming run; daily streams appear when the first memory-logger fires.