switchroom 0.19.9 → 0.19.11

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.19.9", COMMIT_SHA = "9d791e63";
+var VERSION = "0.19.11", COMMIT_SHA = "cd60a0c0";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -23861,8 +23861,7 @@ function getBuiltinDefaultSkillEntries() {
     "switchroom-health",
     "switchroom-runtime",
     "mental-model-curator",
-    "dev-protocol",
-    "telegram-formatting"
+    "dev-protocol"
   ];
   return [
     ...anthropic.map((key) => ({ key, optOutKey: key, source: "anthropic" })),
@@ -24077,6 +24076,38 @@ function reconcileAgentDefaultSkills(agentDir, optOuts = {}, defaults = getBuilt
       result.conflicts.push(entry.key);
     }
   }
+  const defaultKeys = new Set(defaults.map((d) => d.key));
+  const legitimate = new Set(defaultKeys);
+  try {
+    for (const poolName of readdirSync4(poolDir)) {
+      if (!poolName.startsWith("switchroom-"))
+        continue;
+      if (defaultKeys.has(poolName))
+        continue;
+      try {
+        const st = lstatSync2(join6(poolDir, poolName));
+        if (st.isDirectory() && existsSync8(join6(poolDir, poolName, "SKILL.md"))) {
+          legitimate.add(poolName);
+        }
+      } catch {}
+    }
+  } catch {}
+  let dirEntries = [];
+  try {
+    dirEntries = readdirSync4(targetDir);
+  } catch {}
+  for (const linkName of dirEntries) {
+    if (legitimate.has(linkName))
+      continue;
+    const dest = join6(targetDir, linkName);
+    if (!isOwnedBundledLink(dest, poolDir))
+      continue;
+    try {
+      rmSync2(dest, { force: true });
+      result.pruned.push(linkName);
+      result.changed = true;
+    } catch {}
+  }
   return result;
 }
 var warnedMissingPool, warnedMissingDefault;
@@ -29475,31 +29506,45 @@ You're writing for a phone screen in Telegram. Every reply renders as rich Markd
 
 - **Short answers (a line or two): plain prose, no formatting.** "on it, pulling the
   logs now" is already perfect. No bold, no bullets, no headings.
-- **Default: light structure.** Bold ONLY the one key fact or answer, never more. Use
-  a list only for 3+ genuinely parallel items the reader will scan or compare; two
-  items or a flowing thought stay prose. \`code spans\` for identifiers: filenames,
-  commands, config keys, error codes (tap-to-copy).
-- **Long answers may add tables / headings / blockquotes, but only when they genuinely
-  aid scanning**: a table for real 2-D data (rows x columns), headings only in a
-  multi-section answer, \`>\` for quoted text. If the structure doesn't cut the
-  reader's effort, drop it.
-
-The framework normalizes mechanics in code on every outbound message: block spacing
-(one blank line between distinct blocks), em/en dashes, and \`\u2022\` bullet markers are
-rewritten deterministically at send time. Don't fight it or hand-tune spacing; write
-the content, the gateway makes the typography consistent. Over-bolded messages (most
-of the text bold, or whole paragraphs/lists bolded) have their bold stripped at send
-time, so bold sparingly.
-
-Hard cap is 32768 characters. Long before that, ask whether a wall of text is the
-right answer at all. Structure exists for the reader, not the writer: a two-item
-bullet list is worse than a sentence, a heading on a three-line reply is noise. When
-in doubt, shorter and plainer wins.
-
-Full palette when a rich or long message earns it \u2014 expandable blockquotes, spoilers,
-highlight, code-fence language hints, tables, escaping and chunking rules: load the
-\`telegram-formatting\` skill. Reach for it only when you're actually composing that
-message, never for everyday replies.
+- **Default: light structure.** Bold ONLY the one key fact or answer, never more.
+  *Italic* for a light aside or a term of art \u2014 rarer than bold; if everything is
+  emphasised, nothing is. ~~Strikethrough~~ only for a genuine retraction or a
+  "was X, now Y" \u2014 never decoration. A
+  list only for 3+ genuinely parallel items the reader will scan or compare; two items
+  or a flowing thought stay prose. A numbered list ONLY when order carries meaning
+  (steps to follow, a ranking); a nested sub-list only for a real hierarchy, one level
+  deep. \`code spans\` for identifiers: filenames, commands,
+  config keys, error codes (tap-to-copy). Wrap dynamic identifiers in backticks:
+  code-span content is literal, so it never needs escaping. Links as \`[label](url)\`,
+  never bare pasted URLs mid-prose.
+- **Long answers may add the rich constructs, but only when they cut the reader's
+  effort:** a GFM pipe table for real 2-D data (rows x columns); headings only in a
+  multi-section answer; a \`---\` divider only between genuinely separate sections of a
+  long answer (a heading usually does the job alone); \`>\` for quoted text; a spoiler
+  \`||text||\` ONLY when the reader should opt in before seeing it (a punchline, a plot
+  detail, a shock number) \u2014 never for emphasis; \`==highlight==\` to marker-pen the one
+  decisive phrase inside a longer passage \u2014 rarer than bold, never stacked with it;
+  fenced code blocks ALWAYS with a language
+  hint (\`\`\`diff, \`\`\`json, \`\`\`bash \u2014 bare fence only for non-code fixed-width output);
+  and the flagship \u2014 the **expandable blockquote** \`**> first line\` + \`> continuation\`
+  for a long quote, stack trace, or detailed aside the reader can collapse. Use it
+  whenever a bulky supporting block would otherwise dominate the message.
+
+Renders wrong on this path \u2014 never emit: underline (\`__x__\` renders as bold),
+\`^sup^\`/\`~sub~\`, \`$math$\`, \`<details>\`, footnotes \`[^1]\`. Write "squared", not \`x^2^\`.
+
+The framework normalizes mechanics in code on every outbound message: block spacing,
+em/en dashes, and \`\u2022\` bullet markers are
+rewritten deterministically; unsupported tokens (the CARET \`^highlight^\` form \u2014
+\`==highlight==\` renders fine \u2014 plus \`$math$\`, \`<details>\`, footnotes) are repaired;
+long messages are chunked safely at 32768 chars (fences and
+table rows never bisected); over-bolded messages get their bold stripped. Don't
+hand-tune spacing or fight it \u2014 write the content, the gateway makes typography
+consistent. Long before the cap, ask whether a wall of text is the right answer at all.
+
+Structure exists for the reader, not the writer: a two-item bullet list is worse than
+a sentence, a heading on a three-line reply is noise. When in doubt, shorter and
+plainer wins.
 
 Every turn that answers a user message ends with a user-visible \`reply\`
 \u2014 Telegram is all the user sees; your terminal output

package/dist/host-control/main.js

@@ -26664,7 +26664,7 @@ import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:f
 import { dirname as dirname5, join as join7 } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.19.9";
+var VERSION = "0.19.11";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {
@@ -28449,7 +28449,8 @@ class HostdServer {
     return [
       join10(root, "profiles"),
       join10(root, "profiles", "default"),
-      join10(root, "vendor", "hindsight-memory")
+      join10(root, "vendor", "hindsight-memory"),
+      join10(root, "skills")
     ].filter((p) => !existsSync11(p));
   }
   applyAssetPreflight(request_id, started) {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.9",
+  "version": "0.19.11",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -8755,9 +8755,51 @@ var init_inline_pairs_guard = __esm(() => {
   SPOILER_OP = /(?<=\w)\|\|(?=\w)/g;
 });
 
+// render/unsupported-token-guard.ts
+function toExpandableBlockquote(title, body) {
+  const lines = [];
+  const t = title.trim();
+  if (t)
+    lines.push(t);
+  for (const raw of body.split(`
+`)) {
+    const line = raw.trimEnd();
+    if (line.trim() === "" && lines.length === 0)
+      continue;
+    lines.push(line);
+  }
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "")
+    lines.pop();
+  if (lines.length === 0)
+    return "";
+  return lines.map((line, i) => i === 0 ? `**> ${line}` : `> ${line}`).join(`
+`);
+}
+function repairProse(text) {
+  let out = text;
+  out = out.replace(DETAILS_BLOCK, (_m, summary, body) => toExpandableBlockquote(summary ?? "", body ?? ""));
+  out = out.replace(ORPHAN_TAGS, "");
+  out = out.replace(CARET_PAIR, (_m, inner) => inner);
+  out = out.replace(FOOTNOTE_MARKER, "");
+  return out;
+}
+function guardUnsupportedTokens(text) {
+  if (!/[\^]|<details|<\/details|<summary/i.test(text))
+    return text;
+  return splitProtectedSegments(text).map((seg) => seg.code ? seg.text : repairProse(seg.text)).join("");
+}
+var CARET_PAIR, FOOTNOTE_MARKER, DETAILS_BLOCK, ORPHAN_TAGS;
+var init_unsupported_token_guard = __esm(() => {
+  CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
+  FOOTNOTE_MARKER = /\[\^\d+\](?!:)/g;
+  DETAILS_BLOCK = /<details[^>]*>\s*(?:<summary[^>]*>([\s\S]*?)<\/summary>)?([\s\S]*?)<\/details>/gi;
+  ORPHAN_TAGS = /<\/?(?:details|summary)[^>]*>/gi;
+});
+
 // rich-send.ts
 function guardAccidentalFormatting(markdown) {
   let out = markdown;
+  out = guardUnsupportedTokens(out);
   out = guardAccidentalEmphasis(out);
   out = guardAccidentalHeading(out);
   out = guardAccidentalBlockConstructs(out);
@@ -8788,6 +8830,7 @@ var init_rich_send = __esm(() => {
   init_emphasis_guard();
   init_line_start_guard();
   init_inline_pairs_guard();
+  init_unsupported_token_guard();
   import_grammy = __toESM(require_mod2(), 1);
 });
 
@@ -73578,9 +73621,11 @@ init_dollar_math_guard();
 init_emphasis_guard();
 init_line_start_guard();
 init_inline_pairs_guard();
+init_unsupported_token_guard();
 var import_grammy9 = __toESM(require_mod2(), 1);
 function guardAccidentalFormatting2(markdown) {
   let out = markdown;
+  out = guardUnsupportedTokens(out);
   out = guardAccidentalEmphasis(out);
   out = guardAccidentalHeading(out);
   out = guardAccidentalBlockConstructs(out);
@@ -93569,10 +93614,10 @@ function startGatewayHeartbeat(stateDir, intervalMs = GATEWAY_HEARTBEAT_INTERVAL
 }
 
 // ../src/build-info.ts
-var VERSION = "0.19.9";
-var COMMIT_SHA = "9d791e63";
-var COMMIT_DATE = "2026-07-21T06:12:01Z";
-var LATEST_PR = 3492;
+var VERSION = "0.19.11";
+var COMMIT_SHA = "cd60a0c0";
+var COMMIT_DATE = "2026-07-21T21:06:25Z";
+var LATEST_PR = 3497;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

package/telegram-plugin/render/unsupported-token-guard.ts

@@ -0,0 +1,121 @@
+// Outbound repair of markdown tokens Telegram's rich GFM parser (Bot API 10.1)
+// CANNOT render, so the reader would otherwise see literal noise glyphs.
+//
+// ── Root cause ───────────────────────────────────────────────────────────
+// Assistant replies are composed by a model that habitually emits constructs
+// from OTHER surfaces (GitHub / Obsidian / LaTeX): caret highlight/superscript
+// `^…^`, footnote markers `[^1]`, and HTML `<details><summary>` collapsibles.
+// None of these are part of Telegram's rich markdown; they degrade to literal
+// carets, stray `[^1]`, and raw `<details>` tags on the reader's screen — the
+// worst kind of consistency failure (a broken glyph in chat). The resident
+// floor card tells the model not to emit them, but prompt discipline is not a
+// guarantee. This guard makes the repair deterministic at send time.
+//
+// ── What it repairs (deterministic, pure string transform) ─────────────────
+//   • `<details><summary>Title</summary>body</details>` → a Telegram EXPANDABLE
+//     blockquote (`**> Title` first line + `> …` continuation) — the native
+//     equivalent of a collapsible. `<details>` without a `<summary>` folds the
+//     whole body into an expandable blockquote. Any orphan `<details>` /
+//     `</details>` / `<summary>` tags left over are stripped.
+//   • `^highlight^` / `x^2^` caret pairs → the inner text, carets removed
+//     (Telegram has no highlight/superscript; the carets render literally).
+//   • Footnote reference markers `[^id]` → removed (Telegram has no footnotes).
+//     A footnote DEFINITION line `[^id]: …` is left alone (the `]:` lookahead).
+//
+// ── What it deliberately does NOT touch ────────────────────────────────────
+//   • `$…$` math: already neutralised deterministically upstream by
+//     `guardDollarMath` (it backslash-escapes `$` so the pair can never typeset
+//     as math — the reader sees literal `$`). Re-processing `$` here would
+//     double-process and risk corrupting currency prose, so this guard leaves
+//     `$` untouched by design. Math repair is COVERED, just in the sibling guard.
+//   • `~sub~` tilde pairs: the strikethrough/tilde trigger is owned by
+//     `guardAccidentalInlinePairs` (disjoint char set). This guard never
+//     inspects or inserts `~`.
+//   • `__underline__`: renders as BOLD in Telegram — legible, not broken — so it
+//     is left as-is (the floor card asks the model to avoid it, but there is no
+//     glyph-level failure to repair).
+//
+// Code spans / fenced blocks / link destinations / table rows are emitted
+// verbatim (shared `splitProtectedSegments`). A strict no-op for any body
+// without one of these tokens, and idempotent (running twice is a no-op the
+// second time — a repaired blockquote contains no `<details>`, a stripped caret
+// pair contains no `^`). Safe to compose once per send alongside the #3252
+// accidental-formatting guards.
+
+import { splitProtectedSegments } from "./code-segments.js";
+
+/** Paired caret highlight / superscript: `^text^` where the inner run is a
+ *  single ALPHANUMERIC token (no newline, no whitespace, no nested caret, and
+ *  crucially no expression punctuation like `+ = -`). Non-greedy inner run.
+ *  Replaced by the inner text.
+ *
+ *  The alphanumeric-only constraint is deliberate and NARROWER than a plain
+ *  "non-caret non-space" run: it distinguishes a genuine single superscript /
+ *  highlight token (`x^2^`, `^highlighted^`) from a whitespace-free math
+ *  expression whose carets are INDEPENDENT exponents (`a^2+b^2=c^2`). With a
+ *  permissive inner run the first two carets of `a^2+b^2=c^2` pair up (`^2+b^`)
+ *  and get stripped, mangling the math; requiring the inner run to be pure
+ *  alphanumerics means `^2+b^` never matches (the `+` breaks the run), so
+ *  `a^2+b^2=c^2`, `2^8`, and `x^n` all pass through untouched. */
+const CARET_PAIR = /\^([A-Za-z0-9]+)\^/g;
+
+/** Footnote reference marker `[^N]` (digits only) NOT immediately followed by
+ *  `:` (which would make it a footnote DEFINITION line we leave intact). Removed
+ *  entirely. Restricting the id to digits keeps this off in-prose bracket
+ *  literals like `array[^index]` and regex-ish `[^/]`, which are NOT footnotes
+ *  and would otherwise be silently eaten. */
+const FOOTNOTE_MARKER = /\[\^\d+\](?!:)/g;
+
+/** `<details>…</details>` with an optional leading `<summary>…</summary>`.
+ *  Dot-all via `[\s\S]`; non-greedy so adjacent blocks don't merge. */
+const DETAILS_BLOCK =
+  /<details[^>]*>\s*(?:<summary[^>]*>([\s\S]*?)<\/summary>)?([\s\S]*?)<\/details>/gi;
+
+/** Orphan collapsible tags left after DETAILS_BLOCK (malformed / unpaired). */
+const ORPHAN_TAGS = /<\/?(?:details|summary)[^>]*>/gi;
+
+/** Fold `title` + `body` into a Telegram expandable blockquote: the first
+ *  emitted line carries the `**> ` marker (switchroom's expandable-blockquote
+ *  encoding — see parse.ts), every subsequent line a plain `> `. */
+function toExpandableBlockquote(title: string, body: string): string {
+  const lines: string[] = [];
+  const t = title.trim();
+  if (t) lines.push(t);
+  for (const raw of body.split("\n")) {
+    const line = raw.trimEnd();
+    // Collapse leading/trailing blank lines but keep interior structure.
+    if (line.trim() === "" && lines.length === 0) continue;
+    lines.push(line);
+  }
+  // Trim trailing blanks.
+  while (lines.length > 0 && lines[lines.length - 1].trim() === "") lines.pop();
+  if (lines.length === 0) return "";
+  return lines
+    .map((line, i) => (i === 0 ? `**> ${line}` : `> ${line}`))
+    .join("\n");
+}
+
+/** Repair unsupported tokens in a single PROSE segment. */
+function repairProse(text: string): string {
+  let out = text;
+  out = out.replace(DETAILS_BLOCK, (_m, summary: string | undefined, body: string) =>
+    toExpandableBlockquote(summary ?? "", body ?? ""),
+  );
+  out = out.replace(ORPHAN_TAGS, "");
+  out = out.replace(CARET_PAIR, (_m, inner: string) => inner);
+  out = out.replace(FOOTNOTE_MARKER, "");
+  return out;
+}
+
+/**
+ * Neutralise Telegram-unrenderable tokens (`<details>`, `^…^`, `[^1]`) on the
+ * FINAL rendered rich-markdown string. Code / links / tables are verbatim.
+ * Deterministic, idempotent, and a strict no-op absent any target token.
+ */
+export function guardUnsupportedTokens(text: string): string {
+  // Cheap pre-check: nothing to do unless a target trigger char is present.
+  if (!/[\^]|<details|<\/details|<summary/i.test(text)) return text;
+  return splitProtectedSegments(text)
+    .map((seg) => (seg.code ? seg.text : repairProse(seg.text)))
+    .join("");
+}

package/telegram-plugin/rich-send.ts

@@ -22,6 +22,7 @@ import { guardDollarMath } from './render/dollar-math-guard.js'
 import { guardAccidentalEmphasis } from './render/emphasis-guard.js'
 import { guardAccidentalBlockConstructs, guardAccidentalHeading } from './render/line-start-guard.js'
 import { guardAccidentalInlinePairs } from './render/inline-pairs-guard.js'
+import { guardUnsupportedTokens } from './render/unsupported-token-guard.js'
 
 /** The `InputRichMessage` shape grammy 1.44 accepts on send AND edit. */
 export interface InputRichMessageMarkdown {
@@ -56,6 +57,14 @@ export interface InputRichMessageMarkdown {
  */
 export function guardAccidentalFormatting(markdown: string): string {
   let out = markdown
+  // Repair Telegram-unrenderable tokens FIRST: `<details>` folds into a `**> `
+  // expandable blockquote whose `> `-with-space lines are invisible to the
+  // block-construct guard (which only escapes space-LESS `>digit`/`>=`), and
+  // `**> ` is the exact marker switchroom's own render path emits — so the
+  // downstream emphasis/block guards treat it identically to a native
+  // expandable quote. Caret/footnote removal inserts no trigger char for any
+  // sibling guard, so this pass neither creates nor destroys their signals.
+  out = guardUnsupportedTokens(out)
   out = guardAccidentalEmphasis(out)
   out = guardAccidentalHeading(out)
   out = guardAccidentalBlockConstructs(out)

package/telegram-plugin/tests/render/unsupported-token-guard.test.ts

@@ -0,0 +1,125 @@
+import { describe, it, expect } from "vitest";
+import { guardUnsupportedTokens } from "../../render/unsupported-token-guard.js";
+import { richMessage } from "../../rich-send.js";
+
+describe("guardUnsupportedTokens — deterministic send-time repair", () => {
+  it("folds <details><summary> into a Telegram expandable blockquote", () => {
+    const input =
+      "Here is the trace:\n<details><summary>Stack trace</summary>\nline 1\nline 2\n</details>\ndone";
+    const out = guardUnsupportedTokens(input);
+    // Anti-tautology: the raw HTML tags MUST be gone from the wire body.
+    expect(out).not.toContain("<details>");
+    expect(out).not.toContain("</details>");
+    expect(out).not.toContain("<summary>");
+    // Summary becomes the expandable-blockquote first line (`**> ` marker).
+    expect(out).toContain("**> Stack trace");
+    // Body lines become plain `> ` continuation lines.
+    expect(out).toContain("> line 1");
+    expect(out).toContain("> line 2");
+  });
+
+  it("folds a <details> without a <summary> into an expandable blockquote", () => {
+    const out = guardUnsupportedTokens("<details>hidden body text</details>");
+    expect(out).not.toContain("<details");
+    expect(out).toContain("**> hidden body text");
+  });
+
+  it("strips caret highlight / superscript pairs to their inner text", () => {
+    expect(guardUnsupportedTokens("energy is x^2^ joules")).toBe(
+      "energy is x2 joules",
+    );
+    expect(guardUnsupportedTokens("a ^highlighted^ word")).toBe(
+      "a highlighted word",
+    );
+  });
+
+  it("removes footnote reference markers but keeps definition lines", () => {
+    expect(guardUnsupportedTokens("see the note[^1] here")).toBe(
+      "see the note here",
+    );
+    // A `[^1]:` definition line is left intact (the negative lookahead).
+    expect(guardUnsupportedTokens("[^1]: the definition")).toBe(
+      "[^1]: the definition",
+    );
+  });
+
+  it("leaves unpaired carets scattered across prose intact (no interior space)", () => {
+    // Two separate literal carets across words are NOT a highlight pair —
+    // stripping both and joining the words would corrupt the prose.
+    expect(guardUnsupportedTokens("the exponent a^n plus b^m here")).toBe(
+      "the exponent a^n plus b^m here",
+    );
+    expect(guardUnsupportedTokens("score^total and rank^final done")).toBe(
+      "score^total and rank^final done",
+    );
+    // But a genuine adjacent highlight/superscript is still repaired.
+    expect(guardUnsupportedTokens("value ^highlight^ here")).toBe(
+      "value highlight here",
+    );
+  });
+
+  it("leaves whitespace-free multi-caret math expressions intact (no false superscript pairing)", () => {
+    // Review MED-LOW: the caret pair must NOT span two independent exponents.
+    // A permissive inner run would pair `^2+b^` in `a^2+b^2=c^2` and strip the
+    // carets, mangling the math. The alphanumeric-only inner run breaks the run
+    // at `+`/`=`/`-`, so each is left as a literal caret expression.
+    expect(guardUnsupportedTokens("a^2+b^2=c^2")).toBe("a^2+b^2=c^2");
+    expect(guardUnsupportedTokens("2^8")).toBe("2^8");
+    expect(guardUnsupportedTokens("x^n")).toBe("x^n");
+    expect(guardUnsupportedTokens("compute a^2-b^2 now")).toBe("compute a^2-b^2 now");
+    // And a real single superscript token is still repaired.
+    expect(guardUnsupportedTokens("x^2^ metres")).toBe("x2 metres");
+  });
+
+  it("leaves in-prose bracket literals intact, repairs real numeric footnotes", () => {
+    // `array[^index]` is a negated-char-class / index literal, not a footnote.
+    expect(guardUnsupportedTokens("array[^index] lookup")).toBe(
+      "array[^index] lookup",
+    );
+    expect(guardUnsupportedTokens("use [^/] to match")).toBe(
+      "use [^/] to match",
+    );
+    // A real numeric footnote marker is still stripped.
+    expect(guardUnsupportedTokens("see the note[^1] here")).toBe(
+      "see the note here",
+    );
+  });
+
+  it("is a strict no-op for clean markdown (no target tokens)", () => {
+    const clean =
+      "**Answer:** the `config.yaml` file. See [docs](https://example.com/x).";
+    expect(guardUnsupportedTokens(clean)).toBe(clean);
+  });
+
+  it("never touches carets inside code spans / fenced blocks", () => {
+    const code = "run `git rev-parse HEAD^` then\n```bash\necho x^2^\n```";
+    // Carets inside the code span and fence survive verbatim.
+    expect(guardUnsupportedTokens(code)).toBe(code);
+  });
+
+  it("leaves `$` untouched (currency is owned by guardDollarMath)", () => {
+    const money = "it costs $5 and $10";
+    expect(guardUnsupportedTokens(money)).toBe(money);
+  });
+
+  it("is idempotent — a second pass changes nothing", () => {
+    const input = "<details><summary>T</summary>b</details> and x^2^ and n[^3]";
+    const once = guardUnsupportedTokens(input);
+    expect(guardUnsupportedTokens(once)).toBe(once);
+  });
+
+  it("OUTCOME: the composed richMessage wire body has unsupported tokens repaired", () => {
+    // End-to-end through the real send-path composition. This is the
+    // anti-tautology anchor: without guardUnsupportedTokens wired into
+    // guardAccidentalFormatting, the raw `<details>` / `^` / `[^1]` tokens would
+    // reach the wire and this assertion would FAIL.
+    const { markdown } = richMessage(
+      "note[^1]\n<details><summary>More</summary>\ndetail line\n</details>\nx^2^",
+    );
+    expect(markdown).not.toContain("<details>");
+    expect(markdown).not.toContain("[^1]");
+    expect(markdown).toContain("**> More");
+    expect(markdown).toContain("> detail line");
+    expect(markdown).toContain("x2");
+  });
+});

package/skills/telegram-formatting/SKILL.md

@@ -1,147 +0,0 @@
----
-name: telegram-formatting
-description: >
-  Use when composing a rich or long Telegram reply and you want the full
-  formatting palette with exact syntax — expandable blockquotes, spoilers,
-  highlight, code-fence language hints, GFM tables, nested lists — plus the
-  escaping rules and the framework's send-time chunking/normalizer behaviour.
-  Load it when a message genuinely needs structure, NOT for everyday short
-  replies (plain prose already wins there). Teaches judgment first: which
-  construct helps the reader vs when plain text is better. Do NOT use for
-  deciding whether to reply, or for non-Telegram output.
----
-
-# Telegram formatting — the full palette
-
-Every outbound Switchroom message renders as raw GFM markdown over Telegram
-Bot API 10.1 rich messages (`telegram-plugin/rich-send.ts` `richMessage(md)` →
-`{ markdown }` → `sendRichMessage` / `editMessageText({ markdown })`). No HTML,
-no `parse_mode`. This skill is the depth reference behind the boot-injected
-floor card: the full construct vocabulary, correct syntax, escaping, and the
-send-time behaviour you can rely on.
-
-## Judgment first — reach for structure only when it helps the reader
-
-The floor card's stance is the law here too: **structure exists for the reader,
-not the writer.** Loading this skill does not mean "use everything below." Match
-the construct to the message.
-
-- **Short answers (a line or two): plain prose, no formatting.** "on it,
-  pulling the logs now" is already perfect. No bold, no bullets, no headings.
-  Most replies live here — don't dress them up.
-- **Default: light structure.** Bold ONLY the one key fact or answer, never
-  more. A list only for 3+ genuinely parallel items the reader will scan or
-  compare; two items or a flowing thought stay prose. `code spans` for
-  identifiers (filenames, commands, config keys, error codes) — tap-to-copy.
-- **Long / multi-section answers may add the rich constructs below** — tables,
-  headings, blockquotes, expandable blocks, fences — but only when they cut the
-  reader's effort. If the structure doesn't reduce scanning effort, drop it. A
-  two-item bullet list is worse than a sentence; a heading on a three-line reply
-  is noise. When in doubt, shorter and plainer wins.
-
-Over-bolded messages (most of the text bold, whole paragraphs/lists bolded) get
-their bold stripped at send time — so bold sparingly and deliberately.
-
-## Full rich vocabulary
-
-### Inline spans
-
-| Effect | Markdown | When / notes |
-| --- | --- | --- |
-| Bold | `**text**` | The one key fact or answer, not decoration. |
-| Italic | `*text*` or `_text_` | Light emphasis, labels, asides. |
-| Strikethrough | `~~text~~` | Retractions, "was X now Y". |
-| Spoiler | `\|\|text\|\|` | Only for an opt-in surprise or a reveal the reader chose to wait for (a punchline they want suspended) — NEVER to hide an answer someone is asking for or anxious about; when in doubt, show it plainly. Surfaces as a `spoiler` entity on the wire (live-verified 2026-07). |
-| Highlight / marked | `==text==` | Surfaces as a `marked` entity on the wire (live-verified 2026-07). `=` is an `escapeMarkdown` special, so dynamic text won't trigger it by accident. |
-| Inline code | `` `text` `` | Identifiers, tap-to-copy. Content is literal — no escaping inside. |
-| Link | `[label](https://…)` | Standard GFM link. |
-
-**Do NOT rely on these — they don't render as intended:**
-
-- **Underline** — there is NO underline token on this path. `__text__` renders
-  as **bold** (Telegram's rich-message markdown parser reads a `__…__` run
-  identically to `**…**`, live-verified against the Bot API 2026-07). Use `**`
-  for bold and don't reach for underline.
-- **Subscript** `~text~` (single tilde) and **superscript** `^text^` fall back
-  to literal text in rich messages — avoid (write "squared", not `x^2^`).
-- **Custom emoji** (premium custom-emoji entity) renders as a normal emoji for
-  non-premium viewers — don't rely on it to carry meaning.
-
-(Inline math `$…$`, HTML `<details>`/collapsible, and footnotes `[^1]` are NOT
-supported on this path — do not emit them; they degrade to literal or neutralised
-text.)
-
-### Block types
-
-- **Code fence** — ` ```lang ` … ` ``` `. Multi-line literal output (diffs,
-  logs, JSON, command blocks). The language hint (`diff`, `json`, `bash`, …)
-  sharpens syntax rendering — use it. Content inside is verbatim, never escape
-  it; the only hazard is an embedded ` ``` ` closing the block early, which the
-  framework defuses (`preBlock` in `shared/bot-runtime.ts`).
-- **Preformatted block** — a code fence with NO language, for fixed-width
-  non-code (ASCII tables, aligned columns).
-- **Bulleted list** — `- item` (also `*` / `+`). 3+ parallel items only.
-- **Numbered list** — `1. item`. Ordered steps or ranked items.
-- **Nested lists** — indent sub-items; tight (no blank lines) vs loose (blank
-  lines between items) both render. 3-level nesting is live-verified.
-- **Task list** — `- [ ] todo` / `- [x] done`.
-- **Table** — GFM pipe table (`| col | col |` + `| --- | --- |` separator),
-  optional per-column alignment (`:---`, `:---:`, `---:`). 2-D data ONLY (rows ×
-  columns) — not a substitute for prose. Chunk-safe: `splitMarkdownChunks` never
-  bisects a row.
-- **Blockquote** — `> quoted`. Quoted text or an indented continuation; the
-  right way to indent, because Telegram drops leading whitespace.
-- **Expandable blockquote** — `**> …` (Bot API 10.1). A long quote/aside the
-  reader can collapse and expand. The flagship rich construct — use it for a
-  long quotation, a stack trace, or a detailed aside you don't want dominating
-  the message. First line carries the `**> ` marker; continuation lines use `> `.
-- **Section heading** — `#` … `######`. Only in a genuinely long, multi-section
-  answer. Never on a short reply.
-- **Divider** — `---` (thematic break). Heavy horizontal rule between genuinely
-  separate sections. Use sparingly.
-- **Collage / album** — multiple images grouped in one message (media group).
-  Send via the attachment path, not markdown.
-
-## Escaping rules
-
-Dynamic content (filenames, ids, arbitrary user text) interpolated into a
-hand-built markdown card MUST be escaped so it renders LITERALLY instead of
-being parsed as formatting. Use `escapeMarkdown(value)` from
-`telegram-plugin/format.ts`.
-
-`escapeMarkdown` escapes exactly the characters that trigger INLINE formatting:
-backslash, `` ` ``, `*`, `_`, `~`, `=`, `[`, `]`, `|` — the set `` \`*_~=[]| ``.
-The backslash is escaped first so it never double-escapes a following special.
-It deliberately does **not** escape `.` `-` `+` `#` `(` `)` `{` `}` `!` `>`:
-those are only meaningful at line-start or in link/structure context, and
-escaping them mid-word would litter filenames (`foo.ts`), versions (`v1.2-rc`),
-and URLs with visible backslashes.
-
-- **Bold/italic a dynamic value:** `` `**${escapeMarkdown(value)}**` ``.
-- **Code-span a dynamic value:** `` `\`${value}\`` `` — code spans need NO
-  escaping (backtick content is already literal). This is the preferred, safest
-  way to render any identifier.
-
-## Send-time behaviour you can rely on
-
-- **Chunking.** Hard cap is `RICH_MESSAGE_MAX_CHARS = 32768` (32768 accepted,
-  32769 rejected — the single constant, never re-derive it). A longer body is
-  split by `splitMarkdownChunks(text, 32768)` in `format.ts`: it cuts at the
-  largest safe boundary (blank line → newline → space), **never bisects a fenced
-  code block** (`backOffOpenFence`) and **never bisects a table row**
-  (`backOffTableRow`). A single indivisible region larger than the cap is
-  emitted whole and re-split / hard-sliced at send time rather than hanging.
-  Long before 32768, ask whether a wall of text is the right answer at all.
-- **Typography normalizer (deterministic, every message).** Block spacing (one
-  blank line between distinct blocks), em/en dashes, and `•` bullet markers are
-  rewritten at send time. A LONE `\n` between two prose paragraphs is promoted
-  to a real visual break; runs of 3+ newlines collapse to `\n\n`; lists, tables,
-  code, and existing `\n\n` gaps are left exactly as written. Don't hand-tune
-  spacing or fight the normalizer — write the content, the gateway makes the
-  typography consistent.
-
-## The one rule that outranks everything here
-
-You loaded this skill to format a rich message well — but the best formatting is
-still the least that serves the reader. Use the palette to make a genuinely
-complex answer scannable, never to decorate a simple one.