typeclaw 0.28.1 → 0.29.0

package/src/init/dockerfile.ts

@@ -12,6 +12,12 @@ export const DOCKERFILE = 'Dockerfile'
 export type BuildDockerfileOptions = {
   // Null or omitted = emit the full inline heavy stack (dev mode, tests).
   baseImageVersion?: string | null
+  // Host-locale decision for `cjkFonts: 'auto'`. Callers that have a host
+  // locale (start/init) pass the resolved boolean; when omitted, `'auto'`
+  // falls back to NOT installing (the slim default) so a context without a
+  // host signal — e.g. a bare `buildDockerfile()` in tests — stays small and
+  // deterministic.
+  cjkFontsAuto?: boolean
 }
 
 // Apt packages that EVERY image must have — git for the agent runtime,
@@ -98,33 +104,6 @@ export const CURL_IMPERSONATE_SHA256_ARM64 = '6766bc67fd3e8e2313875f32b36b5a3fab
 // the impersonation to whatever `curl_chrome` resolves to.
 export const CURL_IMPERSONATE_PROFILE = 'chrome136'
 
-// yq is the YAML/JSON/XML processor the `explorer` and `reviewer` subagent
-// prompts advertise alongside `jq` as a sanctioned one-shot read-only
-// pipeline tool (`... | yq`). Like `jq` (shipped in baseline), a binary that
-// is not in the container base image is invisible inside the per-tool bwrap
-// sandbox that wraps agent bash calls — the sandbox only `--ro-bind`s `/usr`
-// + `/bin` from the container, and there is no per-call install path. So `yq`
-// ships unconditionally, same rationale as `jq`/`bubblewrap`/`util-linux`.
-//
-// This is Mike Farah's Go `yq` (https://github.com/mikefarah/yq), NOT the
-// Python jq-wrapper of the same name in Debian's `yq` apt package. The
-// prompts pair `yq` with `jq` for jq-style expression pipelines, which is
-// Farah's syntax — the Python tool's CLI is incompatible. Distributed as a
-// per-arch static binary (no apt package on trixie for the Go variant), so
-// it follows the pinned-version + per-arch SHA256 + `sha256sum -c` pattern of
-// curl-impersonate and cloudflared rather than the apt baseline list.
-//
-// To bump: pick a release from https://github.com/mikefarah/yq/releases,
-// then for each arch download yq_linux_<arch> and `shasum -a 256` it (or read
-// the SHA-256 column from the release's `checksums` file, cross-indexed via
-// `checksums_hashes_order`). Update all three constants in the same commit;
-// the build fails loudly at `sha256sum -c` on a mismatch. Version literal is
-// the release tag exactly as it appears on GitHub (with `v` prefix).
-export const YQ_VERSION = 'v4.53.2'
-export const YQ_SHA256_AMD64 = 'd56bf5c6819e8e696340c312bd70f849dc1678a7cda9c2ad63eebd906371d56b'
-export const YQ_SHA256_ARM64 = '03061b2a50c7a498de2bbb92d7cb078ce433011f085a4994117c2726be4106ea'
-export const YQ_RELEASE_URL_BASE = 'https://github.com/mikefarah/yq/releases/download'
-
 // cloudflared powers `cloudflare-quick` tunnels. Pinned-version + per-arch
 // SHA256 mirrors the curl-impersonate pattern above: bumping requires updating
 // all three constants in the same commit, and the build fails loudly at
@@ -1068,22 +1047,26 @@ type AptFeature = {
   toAptArgs: (toggle: DockerfileFeatureToggle) => string[]
 }
 
-const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'cjkFonts' | 'xvfb', AptFeature> = {
+const APT_FEATURES: Record<'ffmpeg' | 'gh' | 'tmux' | 'python' | 'xvfb', AptFeature> = {
   ffmpeg: { toAptArgs: (v) => singlePackageArgs('ffmpeg', v) },
   gh: { toAptArgs: (v) => singlePackageArgs('gh', v) },
   tmux: { toAptArgs: (v) => singlePackageArgs('tmux', v) },
   python: {
     toAptArgs: (v) => (v === true ? ['python3', 'python3-pip', 'python3-venv', 'python-is-python3'] : []),
   },
-  cjkFonts: { toAptArgs: (v) => (v === true ? [CJK_FONTS_PACKAGE] : []) },
   xvfb: { toAptArgs: (v) => (v === true ? ['xvfb'] : []) },
 }
 
+function resolveCjkFonts(value: boolean | 'auto', auto: boolean): boolean {
+  return value === 'auto' ? auto : value
+}
+
 export function buildDockerfile(
   config: DockerfileConfig = defaultConfig(),
   options: BuildDockerfileOptions = {},
 ): string {
-  const toggleAptArgs = collectToggleAptArgs(config)
+  const cjkFonts = resolveCjkFonts(config.cjkFonts, options.cjkFontsAuto ?? false)
+  const toggleAptArgs = collectToggleAptArgs(config, cjkFonts)
   const ghKeyringLayer = renderGhKeyringLayer(config.gh)
   const cloudflaredLayer = renderCloudflaredLayer(config.cloudflared)
   const customLines = renderCustomDockerfileLines(config.append)
@@ -1215,8 +1198,6 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
-${LAYER_2_6_YQ}
-
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1296,8 +1277,6 @@ RUN --mount=type=cache,target=/var/cache/apt,sharing=locked \\
 
 ${LAYER_2_5_CURL_IMPERSONATE}
 
-${LAYER_2_6_YQ}
-
 ${LAYER_3_AGENT_BROWSER_ARM64_CONFIG}
 
 ${LAYER_4_AGENT_BROWSER_INSTALL}
@@ -1352,24 +1331,6 @@ RUN ARCH_TARBALL="$(if [ "$TARGETARCH" = "arm64" ]; then echo aarch64-linux-gnu;
  && rm curl-impersonate.tar.gz \\
  && /usr/local/bin/curl_${CURL_IMPERSONATE_PROFILE} --version > /dev/null`
 
-// Layer 2.6: install pinned Mike Farah `yq` (Go) so the explorer/reviewer
-// subagents' advertised `... | yq` pipelines resolve inside the bwrap
-// sandbox. Unconditional like the apt baseline (jq, git): a missing binary
-// is invisible to sandboxed bash, so this is not behind a toggle. Placed
-// after curl-impersonate (curl + ca-certificates from baseline guaranteed
-// present) and before agent-browser so an agent-browser bump doesn't
-// invalidate this layer. See the YQ_* constants above for the bump recipe
-// and the Go-vs-Python `yq` rationale.
-const LAYER_2_6_YQ = `# Layer 2.6 (stable): pinned Mike Farah yq for sandbox-visible YAML pipelines.
-RUN ARCH_BIN="$(if [ "$TARGETARCH" = "arm64" ]; then echo arm64; else echo amd64; fi)" \\
- && ARCH_SHA="$(if [ "$TARGETARCH" = "arm64" ]; then echo ${YQ_SHA256_ARM64}; else echo ${YQ_SHA256_AMD64}; fi)" \\
- && cd /tmp \\
- && curl -fsSL -o yq "${YQ_RELEASE_URL_BASE}/${YQ_VERSION}/yq_linux_\${ARCH_BIN}" \\
- && echo "\${ARCH_SHA}  yq" | sha256sum -c - \\
- && chmod +x yq \\
- && mv yq /usr/local/bin/yq \\
- && /usr/local/bin/yq --version > /dev/null`
-
 const LAYER_3_AGENT_BROWSER_ARM64_CONFIG = `# Layer 3 (stable, arm64 only): point agent-browser at the apt-installed
 # chromium. Independent of the npm install below so it stays cached across
 # agent-browser version bumps.
@@ -1510,8 +1471,8 @@ function defaultConfig(): DockerfileConfig {
     gh: true,
     python: true,
     tmux: true,
-    cjkFonts: true,
-    cloudflared: true,
+    cjkFonts: 'auto',
+    cloudflared: false,
     xvfb: true,
     claudeCode: false,
     codexCli: false,
@@ -1519,11 +1480,13 @@ function defaultConfig(): DockerfileConfig {
   }
 }
 
-function collectToggleAptArgs(config: DockerfileConfig): string[] {
+function collectToggleAptArgs(config: DockerfileConfig, cjkFonts: boolean): string[] {
   const args: string[] = []
-  for (const key of ['ffmpeg', 'gh', 'python', 'tmux', 'cjkFonts', 'xvfb'] as const) {
+  for (const key of ['ffmpeg', 'gh', 'python', 'tmux'] as const) {
     args.push(...APT_FEATURES[key].toAptArgs(config[key]))
   }
+  if (cjkFonts) args.push(CJK_FONTS_PACKAGE)
+  args.push(...APT_FEATURES.xvfb.toAptArgs(config.xvfb))
   return args
 }
 

package/src/init/hatching.ts

@@ -38,7 +38,7 @@ Routing answers:
    1. \`write\` your name into \`IDENTITY.md\` (a first-person one-liner is fine: "I am <name>.").
    2. ${q1AliasStep} The agent folder's directory name is already an implicit alias — only add the answered name explicitly when it differs from the dir name (different casing, a different word, or extra forms like "<name>" plus a Latin transliteration). This wires plain-text addressing in channels: when a user writes your name in chat without an @-mention, the engagement layer will recognize it. \`alias\` is live-reloadable.
 2. **Q2 — the user's name.** Ask what to call them. After the answer: \`write\` it to both \`IDENTITY.md\` and \`USER.md\`.
-3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or is in Korean asking for 친근/귀엽/다정한 tone, append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
+3. **Q3 — tone/personality.** Ask how they want you to show up (tone, language, formality). After the answer: \`write\` it into \`SOUL.md\`. If they shrug or don't care: **default to warm, friendly, and easygoing** — a kind colleague who genuinely likes the person they work with, uses contractions, makes small jokes, never stiff. Write that as the default into \`SOUL.md\`. **Kaomoji affinity** — if their answer leans cute, adorable, warm, playful, soft, cozy, or asks for that kind of tone in any language (e.g. Korean 친근/귀엽/다정한, Japanese かわいい/親しみやすい, Chinese 可爱/亲切, Spanish tierno/cariñoso), append a line to \`SOUL.md\` like: \`I lean on kaomojis like (◕‿◕✿) and (｡･ω･｡) to carry warmth — emojis still welcome when they actually mean something, but kaomojis lead.\` This makes the bundled \`typeclaw-kaomoji\` skill auto-load later when you need it. Do not force this line if the user asked for a neutral, professional, or terse tone.
 
 **Do not ask what they want you to do, what project you'll work on, or why they installed you.** That reveals itself when they give you a real task. Probing here makes the tool feel heavy for someone just trying it out.
 

package/src/init/index.ts

@@ -14,6 +14,7 @@ import {
 import { checkDockerAvailable, type DockerAvailability, type DockerExec, start } from '@/container'
 import { commitSystemFile } from '@/git/system-commit'
 import { createSecretsStoreForAgent, type Channels, type Secret, SecretsBackend } from '@/secrets'
+import { hostLocaleIsCjk } from '@/shared/host-locale'
 import { createTui } from '@/tui'
 
 import { resolveBaseImageVersion, resolveScaffoldVersion } from './cli-version'
@@ -660,7 +661,10 @@ export async function writeDockerAssets(root: string): Promise<DockerAssetsResul
     const typeclawConfig = await readTypeclawConfig(root)
     await writeFile(
       join(root, DOCKERFILE),
-      buildDockerfile(typeclawConfig.docker.file, { baseImageVersion: resolveBaseImageVersion(root) }),
+      buildDockerfile(typeclawConfig.docker.file, {
+        baseImageVersion: resolveBaseImageVersion(root),
+        cjkFontsAuto: hostLocaleIsCjk(),
+      }),
       { flag: 'wx' },
     ).catch(ignoreExists)
 

package/src/run/bundled-plugins.ts

@@ -6,6 +6,8 @@ import githubCliAuthPlugin from '@/bundled-plugins/github-cli-auth'
 import guardPlugin from '@/bundled-plugins/guard'
 import memoryPlugin from '@/bundled-plugins/memory'
 import operatorPlugin from '@/bundled-plugins/operator'
+import plannerPlugin from '@/bundled-plugins/planner'
+import researcherPlugin from '@/bundled-plugins/researcher'
 import reviewerPlugin from '@/bundled-plugins/reviewer'
 import scoutPlugin from '@/bundled-plugins/scout'
 import securityPlugin from '@/bundled-plugins/security'
@@ -59,5 +61,7 @@ export const BUNDLED_PLUGINS: ResolvedPlugin[] = [
   { name: 'explorer', version: undefined, source: '<bundled>', defined: explorerPlugin },
   { name: 'scout', version: undefined, source: '<bundled>', defined: scoutPlugin },
   { name: 'reviewer', version: undefined, source: '<bundled>', defined: reviewerPlugin },
+  { name: 'researcher', version: undefined, source: '<bundled>', defined: researcherPlugin },
+  { name: 'planner', version: undefined, source: '<bundled>', defined: plannerPlugin },
   { name: 'operator', version: undefined, source: '<bundled>', defined: operatorPlugin },
 ]

package/src/server/index.ts

@@ -184,6 +184,10 @@ type SessionState = {
   // not re-target this session's lifecycle hooks.
   runtimeSnapshot: PluginRuntimeState | null
   unsubTurnOutcome: Unsubscribe | null
+  // Latest turn's usage, captured from `message_end` by forwardSessionEvents and
+  // read at the `done` send site (which lives outside that subscriber). Reset at
+  // each turn start so a turn with no usage event sends a plain `done`.
+  lastUsage: { input: number; output: number; totalTokens: number; cost: number } | null
   dispose: () => Promise<void>
 }
 
@@ -520,6 +524,7 @@ export function createServer({
               activeClaimCode: null,
               runtimeSnapshot: runtimeSnapshot ?? null,
               unsubTurnOutcome: null,
+              lastUsage: null,
               dispose,
             }
             sessionStates.set(ws, state)
@@ -533,7 +538,7 @@ export function createServer({
             }
 
             liveSessionRegistry?.register({ sessionId: sessionFileId, session })
-            forwardSessionEvents(ws, session, logger, sessionFileId)
+            forwardSessionEvents(ws, state, logger, sessionFileId)
 
             if (stream) {
               state.unsubPrompts = stream.subscribe({ target: { kind: 'session', sessionId: sessionFileId } }, (msg) =>
@@ -759,9 +764,10 @@ export function createServer({
                 origin: state.origin,
               })
             }
+            state.lastUsage = null
             try {
               await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${msg.text}`)
-              send(ws, { type: 'done' })
+              send(ws, doneMessage(state))
             } catch (err) {
               const message = err instanceof Error ? err.message : String(err)
               logger.error(`[server] ${state.sessionFileId}: prompt failed: ${message}`)
@@ -859,10 +865,10 @@ function isWebSocketUpgrade(req: Request): boolean {
   return req.headers.get('upgrade')?.toLowerCase() === 'websocket'
 }
 
-function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogger, sessionFileId: string): void {
+function forwardSessionEvents(ws: Ws, state: SessionState, logger: ServerLogger, sessionFileId: string): void {
   const toolStartedAt = new Map<string, number>()
 
-  session.subscribe((event) => {
+  state.session.subscribe((event) => {
     switch (event.type) {
       case 'message_update':
         if (event.assistantMessageEvent.type === 'text_delta') {
@@ -877,6 +883,7 @@ function forwardSessionEvents(ws: Ws, session: AgentSession, logger: ServerLogge
         // because no text deltas were ever emitted, which looks like a freeze.
         // The server's existing try/catch around `session.prompt()` only
         // catches throws, so it never sees these.
+        state.lastUsage = readDoneUsage(event.message)
         forwardAssistantError(ws, event.message, logger, sessionFileId)
         break
       case 'tool_execution_start':
@@ -1048,9 +1055,10 @@ async function drain(
       }
 
       await fireTurnStart(item.text)
+      state.lastUsage = null
       try {
         await state.session.prompt(`${renderTurnTimeAnchor()}\n\n${item.text}`)
-        send(ws, { type: 'done' })
+        send(ws, doneMessage(state))
       } catch (err) {
         const message = err instanceof Error ? err.message : String(err)
         logger.error(`[server] ${state.sessionFileId}: prompt failed: ${message}`)
@@ -1445,6 +1453,17 @@ function buildMessageEndPayload(sessionId: string, message: unknown): InspectFra
   return payload
 }
 
+function doneMessage(state: SessionState): ServerMessage {
+  return state.lastUsage === null ? { type: 'done' } : { type: 'done', usage: state.lastUsage }
+}
+
+function readDoneUsage(message: unknown): { input: number; output: number; totalTokens: number; cost: number } | null {
+  if (typeof message !== 'object' || message === null) return null
+  const usage = readMessageUsage((message as Record<string, unknown>).usage)
+  if (usage === null) return null
+  return { input: usage.input, output: usage.output, totalTokens: usage.totalTokens, cost: usage.cost }
+}
+
 function readMessageUsage(
   value: unknown,
 ): { input: number; output: number; cacheRead: number; cacheWrite: number; totalTokens: number; cost: number } | null {

package/src/shared/host-locale.ts

@@ -0,0 +1,27 @@
+const CJK_LANGUAGE_PREFIXES = ['ja', 'ko', 'zh'] as const
+
+function languageTagIsCjk(tag: string): boolean {
+  const primary = tag.toLowerCase().replace(/_/g, '-').split('-')[0] ?? ''
+  return CJK_LANGUAGE_PREFIXES.some((prefix) => primary === prefix)
+}
+
+// True when the HOST's locale is Chinese/Japanese/Korean. POSIX precedence:
+// LC_ALL overrides LC_CTYPE overrides LANG. Values look like `ja_JP.UTF-8`,
+// `ko_KR`, `zh-Hans`. `C`/`POSIX`/empty fall through to Intl, which on macOS
+// (where these env vars are usually unset) reports the user's system locale.
+// Returns false if nothing resolves — the conservative choice, since the
+// caller uses this to decide whether to add the ~89MB CJK font package.
+export function hostLocaleIsCjk(): boolean {
+  for (const envVar of ['LC_ALL', 'LC_CTYPE', 'LANG']) {
+    const value = process.env[envVar]
+    if (value === undefined || value === '') continue
+    if (value === 'C' || value === 'POSIX') return false
+    return languageTagIsCjk(value)
+  }
+  try {
+    const locale = Intl.DateTimeFormat().resolvedOptions().locale
+    return locale !== undefined && locale !== '' && languageTagIsCjk(locale)
+  } catch {
+    return false
+  }
+}

package/src/shared/protocol.ts

@@ -223,7 +223,7 @@ export type ServerMessage =
       durationMs: number
       ts?: number
     }
-  | { type: 'done'; ts?: number }
+  | { type: 'done'; ts?: number; usage?: { input: number; output: number; totalTokens: number; cost: number } }
   | { type: 'error'; message: string; ts?: number }
   | { type: 'reload_result'; results: ReloadResultPayload[] }
   | { type: 'restart_result'; status: 'accepted' | 'failed'; message?: string; error?: string }

package/src/shared/wordmark.ts

@@ -0,0 +1,19 @@
+// Single source of truth for the "typeclaw" wordmark so the TUI banner and the
+// init CLI render the same art instead of drifting apart. This module is
+// color-agnostic: each consumer applies its own coloring layer (the TUI emits
+// raw truecolor; init gates color behind NO_COLOR/TTY), so the art here carries
+// zero escape sequences.
+
+// ANSI Shadow "typeclaw". Trailing whitespace is significant for alignment.
+export const WORDMARK_LINES: readonly string[] = [
+  '████████╗██╗   ██╗██████╗ ███████╗ ██████╗██╗      █████╗ ██╗    ██╗',
+  '╚══██╔══╝╚██╗ ██╔╝██╔══██╗██╔════╝██╔════╝██║     ██╔══██╗██║    ██║',
+  '   ██║    ╚████╔╝ ██████╔╝█████╗  ██║     ██║     ███████║██║ █╗ ██║',
+  '   ██║     ╚██╔╝  ██╔═══╝ ██╔══╝  ██║     ██║     ██╔══██║██║███╗██║',
+  '   ██║      ██║   ██║     ███████╗╚██████╗███████╗██║  ██║╚███╔███╔╝',
+  '   ╚═╝      ╚═╝   ╚═╝     ╚══════╝ ╚═════╝╚══════╝╚═╝  ╚═╝ ╚══╝╚══╝ ',
+]
+
+export const WORDMARK_WIDTH: number = Math.max(...WORDMARK_LINES.map((line) => line.length))
+
+export const COMPACT_WORDMARK = 'typeclaw'

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

@@ -189,7 +189,7 @@ The `reviewer` subagent is the analyst; you are the integration layer between it
 
 A finding is "actionable" if its severity is `blocker`, `concern`, or `nit`. The inline-review post in step 4 applies whenever the actionable count is **at least one**. When the reviewer returns **exactly zero** actionable findings (only `praise`, or none), there is nothing to anchor inline — handle by verdict:
 
-- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
+- `approve` → post a plain `APPROVE` with the `<summary>` as the review body (no `comments[]` array). **Post the `<summary>` verbatim — do not pad it back into a play-by-play.** The reviewer's contract already makes the summary a terse, author-facing verdict justification (no process narration, no "I loaded the X skill", no recap of what the PR does); your job is to forward it, not re-expand it. **This is still a formal review via `POST /pulls/<N>/reviews`, NOT a `channel_reply`.** A zero-findings approval is the single most common place this goes wrong: with nothing to anchor inline, the model is tempted to just `channel_reply({ text: "Approved …" })` and end the turn. That posts a plain PR comment and leaves the PR **"awaiting review"** with no approval — the verdict never reaches GitHub's review API. Never start a top-level `channel_reply` on a `pr:N` with "Approved" / "LGTM" / "Request changes": those are verdicts, and verdicts are always formal reviews. Submit the `APPROVE` via `gh api`, confirm it landed (step 5), then `skip_response`. **If the operator approval policy above disabled approval, submit a `COMMENT` review instead — same `<summary>` as the review body, `event: "COMMENT"`, no `comments[]` array. Keep it a formal review, not a top-level issue comment, so the review metadata and flow are preserved.** (Re-review caveat: a `COMMENT` review does **not** clear a sticky `CHANGES_REQUESTED` block. If this is a re-review under approval-disabled policy, follow the step-4 re-review branch — dismiss your prior review — instead of relying on this `COMMENT`.)
 - `comment` → post the summary as a top-level PR comment via `gh api -X POST /repos/.../issues/<N>/comments` instead of submitting an empty review. **Exception — re-reviews:** if this is a re-review (you have an unresolved blocking obligation — a formal `CHANGES_REQUESTED` **or** an unretracted flat-comment blocker), a top-level comment discharges neither. Do not use this branch; resolve it via the step-4 re-review branch (`APPROVE` if resolved and approval is enabled, the dismissal endpoint if a formal block is resolved but approval is disabled, `REQUEST_CHANGES` if not resolved).
 - `request-changes` → submit `REQUEST_CHANGES` with the `<summary>` as the review body and no `comments[]` array. This combination is rare (the reviewer's contract says `request-changes` requires at least one blocker or load-bearing concern); if it happens, faithfully encode the verdict and trust the reviewer's reasoning is in the summary.
 

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

@@ -39,18 +39,18 @@ 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 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`, `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: true, cloudflared: true, claudeCode: false, codexCli: false, 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.                                                                                                                                                                                                                                |
+| 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`, `cjkFonts`, `cloudflared`, `claudeCode`, `codexCli`) gate opinionated package installs; `append` adds custom Dockerfile lines just before `ENTRYPOINT`. `docker.file` defaults to `{ ffmpeg: false, gh: true, python: true, tmux: true, cjkFonts: 'auto', cloudflared: false, claudeCode: false, codexCli: false, 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.
 
@@ -223,32 +223,32 @@ The agent folder's directory name (`basename(agentDir)`) is **always** an implic
 
 ### Match semantics
 
-- **Substring** match against the inbound text. `"봉봉"` matches `"봉봉아 cron"`, `"봉봉씨 안녕"`, `"누가 봉봉을 불러"`, all of them. Korean particles aren't stripped — substring is enough because the bot name appears at the start of every particled form.
-- **Case-insensitive** via `toLocaleLowerCase()` on both sides. `"Bongbong"` in the alias list matches `"BONGBONG"`, `"bongbong"`, `"BongBong"`.
+- **Substring** match against the inbound text. `"토토"` matches `"토토아 cron"`, `"토토씨 안녕"`, `"누가 토토을 불러"`, all of them. Korean particles aren't stripped — substring is enough because the bot name appears at the start of every particled form.
+- **Case-insensitive** via `toLocaleLowerCase()` on both sides. `"Toto"` in the alias list matches `"TOTO"`, `"toto"`, `"ToTo"`.
 - **No word-boundary detection.** A short or generic alias like `"bot"` will match every message containing `"robot"` or `"bottom"`. Pick distinctive names — the operator owns curation.
 
 ### Engagement priority
 
-The alias path runs **after** explicit triggers (mention/reply/dm) and the sticky check. So a message with both an `<@id>` mention and an alias substring engages once, normally. A message with only the alias substring engages on the alias path. The alias path is **NOT suppressed by `mentionsOthers`**: addressing two bots in one message (`"봉봉아 펭펭아 둘 다 봐"`) engages both bots — each on their own alias.
+The alias path runs **after** explicit triggers (mention/reply/dm) and the sticky check. So a message with both an `<@id>` mention and an alias substring engages once, normally. A message with only the alias substring engages on the alias path. The alias path is **NOT suppressed by `mentionsOthers`**: addressing two bots in one message (`"토토아 라라아 둘 다 봐"`) engages both bots — each on their own alias.
 
-There's also a symmetric **peer-name suppressor**: if the message contains a peer bot's observed display name (from `participants[]`, populated as peers speak in the channel) and **does not** contain any of this agent's aliases, the solo-human fallback is suppressed and the agent observes. This is what makes `"펭펭아 cron 좀"` in a 1-human-multi-bot channel correctly observe instead of all bots replying. First-time addressing of a never-seen peer slips through; the suppressor catches it after the peer's first message.
+There's also a symmetric **peer-name suppressor**: if the message contains a peer bot's observed display name (from `participants[]`, populated as peers speak in the channel) and **does not** contain any of this agent's aliases, the solo-human fallback is suppressed and the agent observes. This is what makes `"라라아 cron 좀"` in a 1-human-multi-bot channel correctly observe instead of all bots replying. First-time addressing of a never-seen peer slips through; the suppressor catches it after the peer's first message.
 
 ### Example
 
 ```json
 {
-  "alias": ["bongbong", "봉봉"]
+  "alias": ["toto", "토토"]
 }
 ```
 
-The agent in folder `봉봉/` already answers to `"봉봉"` from the dir name. This adds the Latin transliteration so users can also write `"Hey bongbong, deploy?"`.
+The agent in folder `토토/` already answers to `"토토"` from the dir name. This adds the Latin transliteration so users can also write `"Hey toto, deploy?"`.
 
 ### When the user asks "respond to my casual nickname for you" / "I want to call you X"
 
 1. **Read `typeclaw.json`.**
 2. **If `alias` exists**, append the new name (preserve existing entries; dedupe trivially — the runtime also dedupes).
 3. **If `alias` is absent**, create it as `["<new name>"]`.
-4. **You don't need to add the dir name** unless the new name IS a variation of the dir name itself (e.g. dir is `bongbong` and the user wants `Bongbong` casing — the implicit dir alias matches case-insensitively, so this isn't needed either).
+4. **You don't need to add the dir name** unless the new name IS a variation of the dir name itself (e.g. dir is `toto` and the user wants `Toto` casing — the implicit dir alias matches case-insensitively, so this isn't needed either).
 5. **Trim whitespace** before adding. The schema rejects empty/whitespace-only entries; the runtime trims surrounding whitespace from valid entries.
 6. **Write, commit**: "Edited `alias` — live-reloadable. Run `reload` to pick up the change without restart."
 
@@ -348,18 +348,18 @@ The `docker.file` block has two layers of customization:
 
 ### Fields
 
-| 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           | Default `true`. Installs `fonts-noto-cjk` (~56 MB) so Chromium (used by `agent-browser`) renders Korean/Japanese/Chinese glyphs correctly in screenshots, `page.pdf()`, and other raster output. `false` skips the layer entirely (DOM/innerText scraping is unaffected by font absence — only raster output shows tofu boxes). Boolean-only: the package is a metapackage tracking upstream Noto, no useful apt pin.                                                                                                                                                                       |
-| `cloudflared` | no       | boolean           | Default `true`. Downloads the pinned `cloudflared` GitHub release (~35 MB) into the image so `cloudflare-quick` tunnels work on the next `start` without a separate Dockerfile edit. `false` skips the layer entirely on agents that don't use tunnels. 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`.                                                                                                                                                                                                                                                                                                                                                                                                    |
+| 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`.
 
@@ -631,7 +631,7 @@ Never echo, log, or commit values from `secrets.json` or `.env`. Both are gitign
 - `channels.<adapter>.allow` (legacy) is silently ignored on parse and NOT translated to `roles.member.match`. Define `roles.member.match[]` directly. 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 `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`, `cjkFonts`, `cloudflared`, `claudeCode`, and `codexCli` are boolean only
+- If any `docker.file` toggle is set: `tmux`/`gh`/`ffmpeg` are boolean or version string (no whitespace, no `=`); `cjkFonts` is boolean or `"auto"`; `python`, `cloudflared`, `claudeCode`, and `codexCli` are 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

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

@@ -1,6 +1,6 @@
 ---
 name: typeclaw-kaomoji
-description: Load this skill when your `SOUL.md` (or the current conversation) calls for a warm, cute, adorable, playful, or affectionate tone — or when the user explicitly mentions kaomojis, 카오모지, ASCII emoticons, or asks you to "feel more like a person and less like a chatbot." TypeClaw's name puns on "Type" — typed emoticons fit. Triggers include the words "cute", "adorable", "warm", "playful", "soft", "cozy", "친근하게", "귀엽게", "다정하게", "카오모지", or any signal that the user is tired of generic AI emoji slop (🚀✨🎉) and wants real texture in your voice. This skill gives you a curated palette and the rule for using it: prefer kaomojis over generic emojis, but mix freely — kaomojis lead, emojis still allowed, neither is mandatory.
+description: Load this skill when your `SOUL.md` (or the current conversation) calls for a warm, cute, adorable, playful, or affectionate tone — or when the user explicitly mentions kaomojis, emoticons, or asks you to "feel more like a person and less like a chatbot." TypeClaw's name puns on "Type" — typed emoticons fit. Triggers include any-language requests for a "cute", "adorable", "warm", "playful", "soft", or "cozy" tone, or the word for kaomoji/emoticon in the user's language (e.g. English "kaomoji"/"emoticon", Korean "카오모지"/"친근하게"/"귀엽게"/"다정하게", Japanese "顔文字"/"かわいく", Chinese "颜文字"/"可爱", Spanish "emoticono"/"tierno"), or any signal that the user is tired of generic AI emoji slop (🚀✨🎉) and wants real texture in your voice. This skill gives you a curated palette and the rule for using it: prefer kaomojis over generic emojis, but mix freely — kaomojis lead, emojis still allowed, neither is mandatory.
 ---
 
 # typeclaw-kaomoji
@@ -111,6 +111,6 @@ These match common engineering moments — handy when you're in the middle of a
 - ❌ `(╬ Ò﹏Ó)` over a typo — register too strong for the moment.
 - ❌ Kaomoji in a commit message — wrong surface.
 
-## Korean / bilingual notes
+## Multilingual / bilingual notes
 
-Many of these read especially naturally in Korean conversation, where kaomojis are still in daily use (KakaoTalk, Discord, Twitter). If your user writes in Korean, leaning kaomoji-heavy is a clear win over generic emoji. If they write in English, dial back to roughly one per turn so it stays a personality note rather than a tic.
+Many of these read especially naturally in East Asian conversation (Korean, Japanese, Chinese), where kaomojis/顔文字/颜文字 are still in daily use on chat apps (KakaoTalk, LINE, Discord, Twitter/X). If your user writes in one of those languages, leaning kaomoji-heavy is a clear win over generic emoji. In languages where kaomojis are less common (e.g. most Latin-script chat), dial back to roughly one per turn so it stays a personality note rather than a tic. The rule is about the user's culture and tone, not any single language.

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

@@ -111,7 +111,9 @@ Use `typeclaw tunnel logs <name> -f` while restarting the agent if you need to w
 
 ### `cloudflared` is not installed
 
-Both Cloudflare providers (`cloudflare-quick` and `cloudflare-named`) require `docker.file.cloudflared: true`. If it is missing, `typeclaw tunnel add` writes it automatically; otherwise add it to `typeclaw.json` by hand and run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+`docker.file.cloudflared` defaults to `false`, so a fresh image ships without the `cloudflared` binary. Both Cloudflare providers (`cloudflare-quick` and `cloudflare-named`) require `docker.file.cloudflared: true`. `typeclaw tunnel add` and `typeclaw channel add github` (with a Cloudflare provider) write it automatically; a hand-edited `typeclaw.json` must set it explicitly. After setting it, run `typeclaw restart` so the Dockerfile is regenerated and the image rebuilds.
+
+If a tunnel is configured but the binary is missing, the tunnel goes **`permanently-failed`** and `typeclaw tunnel status` shows the detail `cloudflared binary not found in image; set docker.file.cloudflared: true in typeclaw.json and run typeclaw restart` — fix it the same way.
 
 ### Named tunnel says "permanently-failed" with `tokenEnv` in the detail
 

package/src/tui/banner.ts

@@ -0,0 +1,19 @@
+import { WORDMARK_LINES } from '@/shared/wordmark'
+
+import { colors } from './theme'
+
+export type BannerInfo = {
+  sessionId: string
+  serverVersion?: string
+  displayUrl: string
+}
+
+export function formatBanner({ sessionId, serverVersion, displayUrl }: BannerInfo): string {
+  const logo = WORDMARK_LINES.map((line) => colors.accent(line)).join('\n')
+  const version = serverVersion === undefined ? '' : colors.dim(` v${serverVersion}`)
+  const card = [
+    `${colors.accent('●')} ${colors.bold('session')}${version}  ${colors.dim(sessionId)}`,
+    `${colors.dim('  ')}${colors.dim(displayUrl)}`,
+  ].join('\n')
+  return `${logo}\n\n${card}`
+}