typeclaw 0.32.1 → 0.34.0

package/src/skills/typeclaw-config/references/dockerfile.md

@@ -0,0 +1,66 @@
+# `docker.file` reference — toggle catalog and build internals
+
+Companion to the **Dockerfile** section of the `typeclaw-config` SKILL.md. The SKILL.md owns the entry point and the per-question playbooks; this file is the lookup table for the individual `docker.file` toggles and the build-layer internals. Consult it when the user wants a specific package toggled/pinned, or asks how the toggles land in the image.
+
+## Toggle fields
+
+`docker.file` has two layers of customization:
+
+1. **Toggles** for opinionated package installs typeclaw knows how to layer correctly (`tmux`, `gh`, `python`, `ffmpeg`, `cjkFonts`, `cloudflared`, `xvfb`, `claudeCode`, `codexCli`). Most are apt packages — boolean for on/off, version string for an apt pin (e.g. `"gh": "2.40.0"` → `gh=2.40.0`) — and benefit from BuildKit cache mounts. `cloudflared`, `claudeCode`, and `codexCli` are the exceptions: `cloudflared` downloads the pinned GitHub release, `claudeCode` runs Anthropic's `curl | bash` installer, `codexCli` `bun install`s the `@openai/codex` npm package; all three are boolean-only. Use a toggle whenever it covers what the user wants over a hand-rolled `append` entry.
+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.
+
+| Field         | Required | Type                | Notes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
+| ------------- | -------- | ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `tmux`        | no       | boolean \| string   | Default `true`. `false` omits tmux from the apt install. String pins the Debian package version (e.g. `"3.3a-3"` → `tmux=3.3a-3`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `gh`          | no       | boolean \| string   | Default `true`. `false` omits **both** the `gh` package and the GitHub CLI keyring bootstrap layer (skipping the network roundtrip on cold builds). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `python`      | no       | boolean             | Default `true`. Fans out to `python3 python3-pip python3-venv python-is-python3` (the bundle that makes `python` and `pip` resolve correctly inside the container). Boolean-only — no version pin, because Debian's `python3` is a meta-package that doesn't accept a useful pin.                                                                                                                                                                                                                                                                                                                   |
+| `ffmpeg`      | no       | boolean \| string   | Default `false`. `true` apt-installs ffmpeg (~80 MB of codecs). String pins the version.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
+| `cjkFonts`    | no       | boolean or `"auto"` | Default `"auto"`. Installs `fonts-noto-cjk` (~89 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `"auto"` resolves at `typeclaw start` from the host locale (`LANG`/`LC_ALL`/`Intl`): a CJK host (ja/ko/zh) installs the fonts, any other host skips them. An explicit `true`/`false` forces the decision. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes).                                                         |
+| `cloudflared` | no       | boolean             | Default `false`. Downloads the pinned `cloudflared` GitHub release (~38 MB) into the image so `cloudflare-quick` tunnels work. Default `false` skips the layer on agents that don't use tunnels; `typeclaw tunnel add` / `channel add github` with a Cloudflare provider flip it to `true` automatically and prompt for a restart, so the happy path needs no manual edit. If the binary is absent when a tunnel starts, the tunnel goes `permanently-failed` with a "set docker.file.cloudflared: true and run typeclaw restart" message. Boolean-only — pinning is owned by the typeclaw release. |
+| `xvfb`        | no       | boolean             | Default `true`. Installs `xvfb` (~5 MB) so the entrypoint shim can spawn a virtual X server and export `DISPLAY=:99`, giving headed Chrome (agent-browser `--headed`, headful Playwright) a real X11 display to defeat headless-mode WAF fingerprinting. `false` skips the layer; the shim self-heals (no `Xvfb` on PATH → execs the agent without `DISPLAY`). Boolean-only — xvfb tracks the upstream X server release with no useful apt pin.                                                                                                                                                     |
+| `claudeCode`  | no       | boolean             | Default `false`. `true` runs Anthropic's official `curl -fsSL https://claude.ai/install.sh \| bash` in a dedicated layer (between agent-browser and the entrypoint shim) and pre-seeds `~/.claude.json` to skip the TTY-only theme picker on first launch (without it the agent's `tmux send-keys` would be eaten by the picker). Not apt: no version-pin variant; the upstream installer manages channels via env vars. Pairs with the `typeclaw-claude-code` skill, which documents the auth + tmux-driven usage flow including how to clear the post-seed API-key/trust dialogs.                 |
+| `codexCli`    | no       | boolean             | Default `false`. `true` runs `bun install -g @openai/codex` in a dedicated layer (after `claudeCode`, before the entrypoint shim) and pre-writes `~/.codex/hooks.json` registering `SessionStart` + `Stop` hooks so the operator can detect turn boundaries the same way as Claude Code (sentinel files, `.session-id` discovery). Not apt: no version-pin variant. Codex CLI has NO theme picker so no onboarding seed is needed, but auth (`codex login` or `OPENAI_API_KEY`) and the per-project trust dialog are still required at runtime — handled by the `typeclaw-codex-cli` skill.         |
+| `append`      | no       | array of strings    | Each entry is a single Dockerfile line — schema **rejects** entries containing `\n` or `\r`. Defaults to `[]`. Splice happens just before `ENTRYPOINT`, after `ENV NODE_ENV=production`.                                                                                                                                                                                                                                                                                                                                                                                                            |
+
+Toggle version strings reject whitespace and `=` (apt-injection guard) — pass just the version, not `pkg=ver`.
+
+## The single-line constraint (`append` only)
+
+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
+"docker": {
+  "file": {
+    "append": [
+      "RUN apt-get update && apt-get install -y --no-install-recommends ripgrep fd-find",
+      "ENV CUSTOM_TOOL=1"
+    ]
+  }
+}
+```
+
+A single `RUN` with `&&`-chained shell commands is fine and idiomatic — that's still a single Dockerfile line. What's rejected is a literal newline inside the JSON string.
+
+## Where things land in the build
+
+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#docker.file.append.   ← only emitted when append is non-empty
+<your appended lines>
+ENTRYPOINT ["/usr/local/bin/typeclaw-entrypoint"]
+CMD ["run"]
+```
+
+The toggle-driven apt install benefits from BuildKit `--mount=type=cache` on `/var/cache/apt` and `/var/lib/apt/lists`, so toggling `ffmpeg: true` (or pinning `gh: "2.40.0"`) only re-fetches what changed. The `gh` keyring bootstrap is in its own earlier layer that's gated on `gh` being enabled — turning `gh: false` saves the network roundtrip even on cold builds.
+
+`append` runs after every cache-friendly base layer (apt setup, the toggle-driven apt install, `agent-browser`, Chrome for Testing on amd64), so changing `append` invalidates only the final layer. Conversely, putting `apt-get install` in `append` is **slower than using a toggle** (no BuildKit cache mount) — and if the package you want is `tmux/gh/python/ffmpeg/cjkFonts`, just use the toggle.
+
+## Restart and rebuild semantics
+
+- **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.

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-cron
-description: Use this skill whenever the user asks you to schedule recurring work, run something on a cron, do something every day/hour/week, set up a periodic task, list or inspect scheduled jobs, or read or edit your cron schedule. Triggers include "every morning", "every Monday", "schedule a", "remind me every", "set up a cron", "run X periodically", "list cron jobs", "list scheduled jobs", "show me the cron", "what cron jobs do you have", "what's on my cron", "when does X run", or any mention of `cron.json`. Read it before touching `cron.json` — the file has a strict schema, restart semantics, and a best-effort execution model that you must not misrepresent to the user.
+description: Use this skill whenever the user asks you to schedule recurring work OR a one-off future task/reminder, run something on a cron, do something every day/hour/week, do something once at a future time, set up a periodic task, list or inspect scheduled jobs, or read or edit your cron schedule. Triggers include "every morning", "every Monday", "schedule a", "remind me every", "set up a cron", "run X periodically", "remind me in 3 days", "remind me tomorrow", "remind me at 9am", "remind me next Monday", "in N hours/days do X", "do X once at hh:mm", "stop after N times", "until <date>", "list cron jobs", "list scheduled jobs", "show me the cron", "what cron jobs do you have", "what's on my cron", "when does X run", or any mention of `cron.json`. Read it before touching `cron.json` — the file has a strict schema, restart semantics, and a best-effort execution model that you must not misrepresent to the user.
 ---
 
 # typeclaw-cron
@@ -25,12 +25,17 @@ Tell the user this if they ask about reliability. Do not invent guarantees the r
 
 ### Shared fields (all jobs)
 
-| Field      | Required | Notes                                                                                                         |
-| ---------- | -------- | ------------------------------------------------------------------------------------------------------------- |
-| `id`       | yes      | Unique. Letters, digits, hyphens, underscores. Used in logs and to coalesce.                                  |
-| `schedule` | yes      | Standard 5-field cron expression (`min hr dom mon dow`) or 6-field with seconds. See "Schedule syntax" below. |
-| `enabled`  | no       | Defaults to `true`. Set to `false` to keep a job in the file but skip it.                                     |
-| `timezone` | no       | IANA name like `Asia/Seoul`. Defaults to UTC (the container's timezone).                                      |
+| Field      | Required     | Notes                                                                                                                                           |
+| ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `id`       | yes          | Unique. Letters, digits, hyphens, underscores. Used in logs and to coalesce.                                                                    |
+| `schedule` | one of these | Standard 5-field cron expression (`min hr dom mon dow`) or 6-field with seconds. Recurring. See "Schedule syntax" below.                        |
+| `at`       | one of these | One-shot ISO instant — fires **once** then retires. Mutually exclusive with `schedule`; set exactly one. See "One-shot reminders (`at`)" below. |
+| `until`    | no           | Recurring only. Absolute ISO instant; last allowed fire (inclusive). The job retires after this.                                                |
+| `count`    | no           | Recurring only. Stop after N accepted fires. Coexists with `until` — whichever boundary is reached first wins.                                  |
+| `enabled`  | no           | Defaults to `true`. Set to `false` to keep a job in the file but skip it.                                                                       |
+| `timezone` | no           | IANA name like `Asia/Seoul`. Recurring (`schedule`) only — NOT valid with `at`. Defaults to UTC (the container's timezone).                     |
+
+**`schedule` XOR `at`:** every job has exactly one of `schedule` (recurring) or `at` (one-shot). Setting both, or neither, is rejected. `at` jobs may not set `until`, `timezone`, or `count` > 1 (the instant already pins the single fire).
 
 ### `kind: "prompt"` — fire a prompt into a fresh session
 
@@ -69,6 +74,49 @@ Use `exec` only for jobs that are pure mechanics — no judgement required. Exam
 
 `command` is an array. Index 0 is the executable, the rest are argv. Do **not** put a single shell pipeline in `command[0]` — that won't be parsed by a shell. If you need shell features (`|`, `>`, `&&`), wrap explicitly: `["sh", "-c", "your | pipeline | here"]`.
 
+## One-shot reminders and future tasks (`at`)
+
+When the user wants something to happen **once at a future time** — "remind me in 3 days to cancel the subscription", "ping me tomorrow at 9", "in 2 hours, check if the build finished" — use `at` instead of `schedule`. The job fires exactly once at that instant, then retires (the scheduler stops arming it; it never fires again).
+
+```json
+{
+  "id": "cancel-sub",
+  "at": "2026-06-11T09:00:00+09:00",
+  "kind": "prompt",
+  "prompt": "Remind the user to cancel the subscription they mentioned on 2026-06-08. If they already handled it, say so and move on.",
+  "scheduledByRole": "owner"
+}
+```
+
+`at` works with any `kind` (`prompt` for "remind me / do this judgement task", `exec` for a one-off mechanical command). The same best-effort rules apply: if the container is down at the `at` instant, the fire is **lost, not replayed**. Say so if the user is relying on it for something important.
+
+### The `at` value MUST carry an explicit zone or offset
+
+`at` is parsed as an **absolute instant**, so it requires a trailing `Z` or a numeric offset. A bare local-time string is rejected (it would silently resolve to UTC and surprise the user).
+
+- ✅ `2026-06-11T09:00:00+09:00` (Seoul morning) or `2026-06-11T00:00:00Z`
+- ❌ `2026-06-11T09:00:00` (no zone — rejected by `parseCronFile`)
+
+**The `at` instant must be in the future.** Writing an enabled `at` in the past is **rejected at write time** (the `reload`/guard validation returns `"at" is in the past`), because a past reminder would be retired immediately and never fire — a silent no-op the user would mistake for a scheduled reminder. If you get this error, recompute the instant (you probably botched the timezone offset) and write again. (An already-_fired_ one-shot left on disk is the one exception — it stays valid so it can't brick reload — but you never author one of those by hand.)
+
+**Resolving "9am" / "tomorrow" / "in 3 days" to an instant:**
+
+1. Get the user's timezone. Check `USER.md` for a recorded zone; if it's not there and the wall-clock matters, ask once.
+2. Compute the absolute instant in that zone. "Remind me in 3 days" → take now, add 3×24h (or the next 09:00 in their zone if they said a time), and emit it with the zone's offset, e.g. `+09:00`.
+3. Use `bash` (`date`) if you need to compute the offset precisely rather than guessing — e.g. `date -u -d '+3 days' +%Y-%m-%dT%H:%M:%SZ`. Don't hand-roll DST math.
+
+Do not invent `until`, `timezone`, or `count` > 1 on an `at` job — they're rejected. The single instant is the whole schedule.
+
+### Clean up after a one-shot fires (self-prune)
+
+A fired `at` job does **not** delete itself from `cron.json` — it stays on disk as an inert, already-retired entry (the runtime never writes back to `cron.json`; that's by design). On its own this is harmless: the scheduler sees the past instant and retires it without firing, so it will not run again and will not break reload.
+
+But to keep `cron.json` clean, **a one-shot `prompt` job should remove its own entry as the last step of its fire.** Because the fire runs in a full agent session with all your tools, end the reminder prompt with a self-cleanup instruction. Write your `prompt` so your future self does this:
+
+> "... After delivering the reminder, remove the cron job with id `cancel-sub` from `cron.json` and call the `reload` tool so the dead one-shot doesn't linger."
+
+Removing a job needs **no** `cronPromotion` ack — deletions pass the guard freely (only _adding_ a job or elevating its role requires `acknowledgeGuards`). If the cleanup is ever skipped (model error, crash mid-session), the worst case is a harmless leftover entry you can prune on any later edit — never a broken schedule. This self-prune only applies to `prompt` jobs; an `at` `exec` job has no LLM to clean up after itself, so its entry just lingers until a human or a later prompt removes it.
+
 ## `exec → LLM`: write a plugin cron handler (best practice)
 
 If a scheduled job needs imperative control flow that mixes shell calls and LLM calls (probe → maybe prompt → write file), the best practice is a **plugin cron handler**: a TypeScript function the plugin registers under its own `cronJobs` with `kind: 'handler'`. The cron consumer invokes it directly — no shell-out, no WS round-trip, no `Bun.spawn`. Prefer this whenever the cadence and the logic both belong to the same plugin (which is almost always — see "When to reach for the exec bridge instead" below for the two narrow exceptions).
@@ -322,11 +370,13 @@ For every job you add:
 
 - `id` is unique within the file
 - `id` matches `[a-zA-Z0-9_-]+` (no spaces, no slashes, no dots)
-- `schedule` parses as cron
+- Exactly one of `schedule` or `at` is set (never both, never neither)
+- If recurring: `schedule` parses as cron
+- If one-shot: `at` is a future ISO instant **with an explicit `Z` or numeric offset**, and `until`/`timezone`/`count` > 1 are absent
 - `kind` is exactly `"prompt"` or `"exec"`
 - If `prompt`: `prompt` is non-empty
 - If `exec`: `command` is a non-empty array of non-empty strings
-- If a wall-clock schedule was requested: `timezone` is set
+- If a wall-clock `schedule` was requested: `timezone` is set
 
 ### Applying changes — the `reload` tool
 
@@ -345,19 +395,23 @@ If you finished an edit and the user only sees an in-flight job from the previou
 - **Do not promise sub-second precision or guaranteed execution.** This is best-effort — see "What cron actually does" above.
 - **Do not invent fields the schema doesn't support** (no `retry`, `timeout`, `onFailure`, `concurrency`, etc.). They will be silently ignored at best, or rejected at worst.
 
-## When the user says "every X"
+## When the user says "every X" or "do X once"
+
+0. **Recurring or one-shot?** This is the first fork.
+   - **Recurring** ("every morning", "every Monday", "hourly") → use `schedule`. Continue with step 1 below.
+   - **One-shot / future task** ("remind me in 3 days", "tomorrow at 9", "in 2 hours", "do X once at hh:mm") → use `at` with an absolute instant (explicit zone/offset). See "One-shot reminders and future tasks (`at`)" above for resolving the instant and self-prune. Then pick the kind (almost always `prompt` for a reminder) and skip straight to step 4. Don't set `schedule`, `timezone`, `until`, or `count` on it.
 
-Pick `kind` first, then schedule, then timezone:
+For a **recurring** job:
 
 1. **Pick the kind.**
    - **Pure mechanics, no judgement** (git snapshots, log rotation, calling an existing script) → `kind: 'exec'` in `cron.json`. Done.
-   - **One-shot natural-language instruction, no shell pre-work, no conditional logic** → `kind: 'prompt'` in `cron.json`. Done.
+   - **One natural-language instruction, no shell pre-work, no conditional logic** → `kind: 'prompt'` in `cron.json`. Done.
    - **Imperative control flow mixing shell calls and LLM calls** (probe → maybe prompt → write file, "if there are new emails then triage", etc.) → **write a `kind: 'handler'` plugin cron job** (see "`exec → LLM`: write a plugin cron handler" above). This is the default for scheduled `exec → LLM` work.
    - **Reuse a CLI command on a custom cadence** — the same logic must ALSO be invocable from the TUI / manual shell / `compose` orchestration, or the schedule is owned by the user (`cron.json`) rather than the plugin author, or the work must run as a `surface: 'host'` command → `kind: 'exec'` in `cron.json` with `command: ["typeclaw", "<plugin-command>", ...]`. Reach for this ONLY when reusability is the actual requirement, not just because the work is scheduled. See "When to reach for the exec bridge instead" above.
-2. **Translate the cadence to cron.** "Every morning at 7" → `0 7 * * *`. "Every weekday at 9:30" → `30 9 * * 1-5`. "Every five minutes" → `*/5 * * * *`. If you are not sure, ask once. Don't guess on tricky cases like "every other Friday".
+2. **Translate the cadence to cron.** "Every morning at 7" → `0 7 * * *`. "Every weekday at 9:30" → `30 9 * * 1-5`. "Every five minutes" → `*/5 * * * *`. If you are not sure, ask once. Don't guess on tricky cases like "every other Friday". If the user wants the recurrence to stop ("until end of quarter", "only 5 times"), add `until` (absolute ISO instant) and/or `count` (N fires).
 3. **Timezone.** If the user mentioned a wall-clock time, set `timezone` to their zone. If unknown, ask once or default to the timezone in `USER.md` if it's recorded there.
 4. **Pick a stable `id`.** Use kebab-case that describes the job, not the schedule. `daily-summary` not `0-23-30`.
-5. **Write it. Call `reload`. If reload succeeded, commit it.** If reload failed, fix `cron.json` based on the error and retry — do not commit a broken file.
+5. **Write it. Call `reload`. If reload succeeded, commit it.** If reload failed, fix `cron.json` based on the error and retry — do not commit a broken file. **Adding any new job (recurring or one-shot) requires `acknowledgeGuards: { cronPromotion: true }` in the write** — but never ack a job scheduled on behalf of a channel speaker asking to elevate themselves (see step 3 of "Editing `cron.json` safely").
 
 ## Listing what is currently scheduled
 

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

@@ -141,7 +141,7 @@ Probable causes, in descending order of frequency:
 
 1. **No match rule covers the speaking author's coordinates.** Read `typeclaw.json` `roles`, compare every `match[]` entry to the channel ID and author ID the user is reporting. If nothing matches, the author resolves to `guest`, which has no `channel.respond`, so every inbound is dropped at the router. The fix is to append a match rule to `roles.<role>.match[]` for that channel (or DM bucket).
 2. **The match rule exists but the role has `permissions: []`** (or otherwise lacks `channel.respond`). A user-declared role replaces the built-in's permissions wholesale. Re-add `channel.respond` or use a built-in role name (`member`, `trusted`, `owner`) that carries it by default.
-3. **Engagement triggers are filtering admitted messages.** This is a different problem — the inbound was admitted by permissions but engagement (`channels.<adapter>.engagement.trigger`) decided not to wake you. See the `typeclaw-config` skill for the engagement model.
+3. **Engagement triggers are filtering admitted messages.** This is a different problem — the inbound was admitted by permissions but engagement (`channels.<adapter>.engagement.trigger`) decided not to wake you. See the `typeclaw-channels` skill for the engagement model.
 
 To distinguish cause 1/2 from cause 3: if `typeclaw logs <container> -f` (host stage) shows `[channels] ... denied by permissions (channel.respond)`, it's a permissions problem. If it shows the message being admitted but no LLM call follows, it's engagement.
 
@@ -160,7 +160,7 @@ This is a `roles` edit. The full procedure:
 Two interpretations — clarify if ambiguous:
 
 - **"Stop everything"** — remove the match rule from `roles.<role>.match[]`. The author resolves to `guest`, and the channel router silently drops every inbound. You lose all visibility into their messages. Restart-required.
-- **"Just stop auto-replying"** — keep the match rule, but narrow `channels.<adapter>.engagement.trigger` and/or `stickiness`. See `typeclaw-config`. The agent still receives the messages and can still post if you tell it to. The solo-human fallback (single human in a channel) overrides `trigger: []`, so this approach can't fully silence you in a 1:1; only removing the match rule does.
+- **"Just stop auto-replying"** — keep the match rule, but narrow `channels.<adapter>.engagement.trigger` and/or `stickiness`. See `typeclaw-channels`. The agent still receives the messages and can still post if you tell it to. The solo-human fallback (single human in a channel) overrides `trigger: []`, so this approach can't fully silence you in a 1:1; only removing the match rule does.
 
 ## When the user asks "what role am I in this session?"
 
@@ -192,7 +192,7 @@ If you see a cron job mysteriously failing every fire with `denied by permission
 
 ## What this skill does not cover
 
-- **The `channels.<adapter>` block** — engagement, history, stickiness, alias. See `typeclaw-config`. Engagement decides whether an _admitted_ inbound wakes the loop; this skill is only about admission.
+- **The `channels.<adapter>` block behavior** — engagement, history, stickiness, alias matching. See `typeclaw-channels`. Engagement decides whether an _admitted_ inbound wakes the loop; this skill is only about admission. The `channels`/`alias` schema and edit mechanics live in `typeclaw-config`.
 - **The full `typeclaw.json` schema** — model, mounts, plugins, docker, git.ignore. See `typeclaw-config`.
 - **Cron job authoring** — schedule syntax, `prompt` vs `exec`, the `reload` tool. See `typeclaw-cron`. This skill only covers the `scheduledByRole` field and its provenance semantics.
 - **Plugin authoring** — `definePlugin`, contributing permissions, custom `tool.before` hooks. See `typeclaw-plugins`. The bundled security plugin is an example of a plugin that contributes `security.bypass.*` strings and uses `permissions.has()` to gate its own guards.

package/typeclaw.schema.json

@@ -41,7 +41,18 @@
               "zai-coding/glm-4.7",
               "zai-coding/glm-5",
               "zai-coding/glm-5-turbo",
-              "zai-coding/glm-5.1"
+              "zai-coding/glm-5.1",
+              "xai/grok-4.3",
+              "xai/grok-4.20-0309-reasoning",
+              "xai/grok-4.20-0309-non-reasoning",
+              "xai/grok-build-0.1",
+              "minimax/MiniMax-M3",
+              "minimax/MiniMax-M2.7",
+              "minimax/MiniMax-M2.5",
+              "minimax/MiniMax-M2.1",
+              "minimax/MiniMax-M2",
+              "deepseek/deepseek-v4-flash",
+              "deepseek/deepseek-v4-pro"
             ]
           },
           {
@@ -69,7 +80,18 @@
                 "zai-coding/glm-4.7",
                 "zai-coding/glm-5",
                 "zai-coding/glm-5-turbo",
-                "zai-coding/glm-5.1"
+                "zai-coding/glm-5.1",
+                "xai/grok-4.3",
+                "xai/grok-4.20-0309-reasoning",
+                "xai/grok-4.20-0309-non-reasoning",
+                "xai/grok-build-0.1",
+                "minimax/MiniMax-M3",
+                "minimax/MiniMax-M2.7",
+                "minimax/MiniMax-M2.5",
+                "minimax/MiniMax-M2.1",
+                "minimax/MiniMax-M2",
+                "deepseek/deepseek-v4-flash",
+                "deepseek/deepseek-v4-pro"
               ]
             }
           }
@@ -584,6 +606,166 @@
             }
           }
         },
+        "line": {
+          "type": "object",
+          "properties": {
+            "engagement": {
+              "default": {
+                "trigger": [
+                  "mention",
+                  "reply",
+                  "dm"
+                ],
+                "stickiness": {
+                  "perReply": {
+                    "window": 900000
+                  }
+                }
+              },
+              "type": "object",
+              "properties": {
+                "trigger": {
+                  "default": [
+                    "mention",
+                    "reply",
+                    "dm"
+                  ],
+                  "type": "array",
+                  "items": {
+                    "type": "string",
+                    "enum": [
+                      "mention",
+                      "reply",
+                      "dm"
+                    ]
+                  }
+                },
+                "stickiness": {
+                  "default": {
+                    "perReply": {
+                      "window": 900000
+                    }
+                  },
+                  "anyOf": [
+                    {
+                      "type": "string",
+                      "const": "off"
+                    },
+                    {
+                      "type": "object",
+                      "properties": {
+                        "perReply": {
+                          "type": "object",
+                          "properties": {
+                            "window": {
+                              "type": "integer",
+                              "minimum": 1,
+                              "maximum": 86400000
+                            }
+                          },
+                          "required": [
+                            "window"
+                          ]
+                        }
+                      },
+                      "required": [
+                        "perReply"
+                      ]
+                    }
+                  ]
+                }
+              }
+            },
+            "history": {
+              "default": {
+                "prefetch": {
+                  "thread": {
+                    "head": 3,
+                    "tail": 10
+                  },
+                  "channel": {
+                    "tail": 10
+                  }
+                }
+              },
+              "type": "object",
+              "properties": {
+                "prefetch": {
+                  "default": {
+                    "thread": {
+                      "head": 3,
+                      "tail": 10
+                    },
+                    "channel": {
+                      "tail": 10
+                    }
+                  },
+                  "type": "object",
+                  "properties": {
+                    "thread": {
+                      "default": {
+                        "head": 3,
+                        "tail": 10
+                      },
+                      "type": "object",
+                      "properties": {
+                        "head": {
+                          "default": 3,
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 200
+                        },
+                        "tail": {
+                          "default": 10,
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 200
+                        }
+                      }
+                    },
+                    "channel": {
+                      "default": {
+                        "tail": 10
+                      },
+                      "type": "object",
+                      "properties": {
+                        "tail": {
+                          "default": 10,
+                          "type": "integer",
+                          "minimum": 0,
+                          "maximum": 200
+                        }
+                      }
+                    }
+                  }
+                }
+              }
+            },
+            "enabled": {
+              "default": true,
+              "type": "boolean"
+            },
+            "quotedReply": {
+              "default": {
+                "enabled": true,
+                "queueDelayMs": 10000
+              },
+              "type": "object",
+              "properties": {
+                "enabled": {
+                  "default": true,
+                  "type": "boolean"
+                },
+                "queueDelayMs": {
+                  "default": 10000,
+                  "type": "integer",
+                  "minimum": 0,
+                  "maximum": 9007199254740991
+                }
+              }
+            }
+          }
+        },
         "kakaotalk": {
           "type": "object",
           "properties": {
@@ -1286,7 +1468,7 @@
             "type": "array",
             "items": {
               "type": "string",
-              "pattern": "^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$"
+              "pattern": "^(tui|cron|subagent(:[a-z][a-z0-9-]*)?|\\*|(slack|discord|telegram|line|kakao|github):[^\\s]+)(\\s+[a-zA-Z][a-zA-Z0-9_]*:[^\\s]+)*$"
             }
           },
           "permissions": {