typeclaw 0.30.1 → 0.31.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.30.1",
+  "version": "0.31.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"

package/src/channels/router.ts

@@ -183,6 +183,18 @@ export const MAX_POLICY_DENIED_CHANNEL_SENDS_PER_TURN = 3
 // including reasoning). Deliberately NOT lowered in `providers.ts`, where
 // `maxTokens` is the model's true capability that compaction math reads.
 export const CHANNEL_MAX_OUTPUT_TOKENS = 4096
+// Raised output-token budget threaded into the ONE re-prompt that follows a
+// `stopReason:'length'` empty turn. The default 4096 backstop bounds kimi's
+// degenerate repetition loop, but it is the same ceiling a *legitimate*
+// reasoning-heavy turn hits when it spends the whole pool thinking and emits no
+// prose — re-prompting under the identical cap reproduces the truncation. A
+// `length` truncation that the byte-identical loop guard did NOT catch is
+// evidence of genuine reasoning starved for room, not a repetition loop, so the
+// retry grants 4x headroom for thinking + a reply. Bounded (not 32000) so a
+// turn that IS looping still can't burn the full pi-ai default. Consumed
+// one-shot via `LiveSession.nextPromptMaxTokens`, then reset at the next real
+// user turn so the raised budget never leaks past the turn that needed it.
+export const CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS = 16384
 // Ceiling on automatic re-prompts for a turn that ended with NO user-facing
 // reply AND no attempted send — the pure "the model burned its budget thinking
 // and produced nothing" failure. The canonical trigger is Fireworks'
@@ -200,18 +212,24 @@ export const CHANNEL_MAX_OUTPUT_TOKENS = 4096
 export const MAX_EMPTY_TURN_RETRIES = 2
 // Reminder-only nudge injected before an empty-turn retry. Uses the repo's
 // SYSTEM MESSAGE framing (see composeTurnPrompt) so persona-rich models do not
-// reply to the notice itself. Neutral by design: it asks for a direct reply
-// without prescribing length or tone, matching the chosen "just retry" posture.
+// reply to the notice itself. Names the actual failure (the prior turn ran out
+// of its output budget mid-reasoning and produced no reply) and asks the model
+// to keep its thinking short and answer directly — the empty turn was budget
+// exhaustion, not a forgotten tool call, so a "reply directly" nudge alone
+// would re-loop. The matching retry re-prompt also runs with a raised budget
+// (CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS) so the room actually exists.
 export const EMPTY_TURN_RETRY_NUDGE = [
   '---',
   '**[SYSTEM MESSAGE — not from a human]**',
   '',
-  'Your previous turn ended without sending any reply to the channel. This is',
+  'Your previous turn ran out of its output budget before sending a reply — it',
+  'spent the whole turn thinking and produced nothing for the channel. This is',
   'an automated signal from the channel router, not a message from anyone in',
   'the chat. **Do not acknowledge or reply to this notice itself.**',
   '',
-  'Respond to the last user message now with a direct answer via your channel',
-  'reply tool. If you genuinely have nothing to say, reply with `NO_REPLY`.',
+  'Answer the last user message now: keep any reasoning brief and send a direct',
+  'reply via your channel reply tool. If you genuinely have nothing to say,',
+  'reply with `NO_REPLY`.',
   '',
   '---',
 ].join('\n')
@@ -532,6 +550,13 @@ type LiveSession = {
   // increments it before injecting EMPTY_TURN_RETRY_NUDGE and reads it to decide
   // retry-vs-fallback. See the candidate===null branch.
   emptyTurnRetries: number
+  // One-shot output-token budget for the NEXT `session.prompt()` only.
+  // `installChannelOutputCap` reads and clears it per stream call, so it
+  // overrides the default backstop for exactly one re-prompt. Set by the
+  // empty-turn length-retry branch to CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS
+  // and reset to undefined at each fresh user turn so the raised budget cannot
+  // leak past the turn that needed it.
+  nextPromptMaxTokens: number | undefined
   // Stamped by `markTurnSkipped` (called from the `skip_response` tool)
   // with the current `turnSeq`. Read at the top of `validateChannelTurn`:
   // if it matches the just-completed turn, recovery is skipped entirely
@@ -1417,6 +1442,7 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
         inFlightToolSends: new Map(),
         policyDeniedToolSendsThisTurn: new Map(),
         emptyTurnRetries: 0,
+        nextPromptMaxTokens: undefined,
         skippedTurn: null,
         skipLockedSendTurn: null,
         pendingQuoteCandidate: null,
@@ -1704,14 +1730,22 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
   // Override pi-ai's hidden `Math.min(model.maxTokens, 32000)` output cap for
   // channel sessions by threading an explicit `maxTokens` into every stream
   // call. See CHANNEL_MAX_OUTPUT_TOKENS for why. Composes the existing streamFn
-  // (pi's default `streamSimple` unless a proxy was installed) and only fills
-  // `maxTokens` when the caller left it unset, so an explicit per-call value
-  // still wins.
+  // (pi's default `streamSimple` unless a proxy was installed). Precedence:
+  // an explicit per-call `maxTokens` always wins; otherwise a one-shot
+  // `live.nextPromptMaxTokens` (set by the empty-turn length-retry) is consumed
+  // and cleared so the raised budget applies to exactly one stream call;
+  // otherwise the default backstop.
   const installChannelOutputCap = (live: LiveSession): void => {
     const { agent } = live.session
     const inner = agent.streamFn
-    agent.streamFn = (model, context, options) =>
-      inner(model, context, { ...options, maxTokens: options?.maxTokens ?? CHANNEL_MAX_OUTPUT_TOKENS })
+    agent.streamFn = (model, context, options) => {
+      let maxTokens = options?.maxTokens
+      if (maxTokens === undefined && live.nextPromptMaxTokens !== undefined) {
+        maxTokens = live.nextPromptMaxTokens
+        live.nextPromptMaxTokens = undefined
+      }
+      return inner(model, context, { ...options, maxTokens: maxTokens ?? CHANNEL_MAX_OUTPUT_TOKENS })
+    }
   }
 
   const startTypingHeartbeat = (live: LiveSession): void => {
@@ -1904,10 +1938,13 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
           live.lastSentText.clear()
           live.pendingQuoteCandidate = captureQuoteCandidate(live.key.adapter, batch, observed)
           // A real user batch starts a fresh logical turn → restore the full
-          // empty-turn retry budget. Reset here (batch.length > 0) and NOT in
-          // the per-prompt block below, so the reminder-only iterations the
-          // retry itself queues do not refill the budget and loop forever.
+          // empty-turn retry budget and drop any raised output-token budget left
+          // over from a prior turn's length-retry. Reset here (batch.length > 0)
+          // and NOT in the per-prompt block below, so the reminder-only
+          // iterations the retry itself queues do not refill the budget and loop
+          // forever (and the raised cap stays scoped to the turn that set it).
           live.emptyTurnRetries = 0
+          live.nextPromptMaxTokens = undefined
         } else if (live.lastTurnAuthorId !== null) {
           live.currentTurnEngageReactions = []
           // Reminder-only turn (batch.length === 0, reminders.length > 0):
@@ -3037,8 +3074,18 @@ export function createChannelRouter(options: CreateChannelRouterOptions): Channe
       }
       if (!attemptedSendThisTurn && live.emptyTurnRetries < MAX_EMPTY_TURN_RETRIES) {
         live.emptyTurnRetries++
+        // Raise the re-prompt's budget ONLY for a `length` truncation: that is
+        // the budget-exhaustion case (reasoning ate the whole pool before any
+        // prose), so the retry needs room to finish thinking AND reply. `error`
+        // and `aborted` are not budget exhaustion — an upstream failure or the
+        // terminal-reply abort — so they retry under the default backstop.
+        // Consumed one-shot by installChannelOutputCap on the next prompt().
+        if (assistantLeafStopReason(live.session) === 'length') {
+          live.nextPromptMaxTokens = CHANNEL_EMPTY_TURN_RETRY_MAX_OUTPUT_TOKENS
+        }
         logger.warn(
-          `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES}`,
+          `[channels] ${live.keyId} empty_turn_retry attempt=${live.emptyTurnRetries}/${MAX_EMPTY_TURN_RETRIES} ` +
+            `max_tokens=${live.nextPromptMaxTokens ?? CHANNEL_MAX_OUTPUT_TOKENS}`,
         )
         live.pendingSystemReminders.push(EMPTY_TURN_RETRY_NUDGE)
         return
@@ -4355,18 +4402,25 @@ function recoverableAssistantText(
   return null
 }
 
-// True only when the leaf is an assistant message that was CUT OFF mid-output:
-// `length` (hit the token cap — the canonical kimi reasoning-loop), `error`, or
-// `aborted`. This is the precise signature of "the model was producing but got
-// truncated", as distinct from a turn that produced no assistant message at all
-// (leaf undefined / a non-assistant entry), which is a benign empty/cold turn —
-// NOT something to re-prompt. The empty-turn retry guard keys off this so it
-// fires for real degenerations and stays silent for cold sessions.
-function assistantLeafTruncated(session: AgentSession): boolean {
+// The truncation stop reason when the leaf is an assistant message that was CUT
+// OFF mid-output — `length` (hit the token cap, the canonical kimi reasoning-
+// loop), `error`, or `aborted` — else undefined. This is the precise signature
+// of "the model was producing but got truncated", as distinct from a turn that
+// produced no assistant message at all (leaf undefined / a non-assistant
+// entry), which is a benign empty/cold turn. Callers that only need the boolean
+// use `assistantLeafTruncated`; the retry guard reads the reason itself because
+// the raised reasoning budget is justified ONLY for `length` (budget
+// exhaustion), not for `error`/`aborted`.
+function assistantLeafStopReason(session: AgentSession): 'length' | 'error' | 'aborted' | undefined {
   const leaf = session.sessionManager.getLeafEntry()
-  if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return false
+  if (!leaf || leaf.type !== 'message' || leaf.message.role !== 'assistant') return undefined
   const stop = leaf.message.stopReason
-  return stop === 'length' || stop === 'error' || stop === 'aborted'
+  if (stop === 'length' || stop === 'error' || stop === 'aborted') return stop
+  return undefined
+}
+
+function assistantLeafTruncated(session: AgentSession): boolean {
+  return assistantLeafStopReason(session) !== undefined
 }
 
 function visibleAssistantText(message: AssistantMessage): string {

package/src/skills/typeclaw-markdown-pdf/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: typeclaw-markdown-pdf
+description: "Turn any Markdown into a polished, professional PDF and (optionally) attach it to a channel. Load this whenever you need to deliver a document as a PDF rather than raw markdown — reports, summaries, briefs, meeting notes, docs, anything a human would want to download, print, or forward. Triggers: 'make a PDF', 'export to PDF', 'markdown to PDF', 'PDF report', 'attach the report', 'send me a PDF', 'as a PDF', 'turn this into a document', a researcher/subagent result you want to ship as a file, 'PDF로', 'PDF로 만들어', 'PDF로 변환', 'PDF 첨부'. Also load before saying you cannot produce PDFs — you can: this skill installs a tiny Typst toolchain into workspace/ on first use, then renders. Covers the one-time setup, the styled wrapper, the render command, and how to attach the PDF to Slack/Discord/Telegram/KakaoTalk. For operating on EXISTING PDFs (merge, split, extract text, fill forms), this is not the skill — use pypdf/qpdf instead."
+---
+
+# typeclaw-markdown-pdf
+
+You can produce professional PDFs from Markdown. This skill installs a small,
+self-contained [Typst](https://typst.app) toolchain into your `workspace/` the
+**first time** you need a PDF, then reuses it. No Pandoc, no LaTeX, no headless
+browser — just an npm-installed Typst compiler plus the
+[`cmarker`](https://typst.app/universe/package/cmarker/) package that reads your
+Markdown.
+
+The flow is: **(1)** run the one-time setup (`bun add` the Typst compiler +
+vendor `cmarker` into `workspace/.tools/`), **(2)** write a styled `.typ` wrapper
+that reads your Markdown, **(3)** run the render script. If a channel asked for
+the PDF, attach the result with `channel_send`.
+
+You do **not** need to learn Typst markup. `cmarker` renders your CommonMark
+(headings, lists, tables, code, blockquotes, footnotes, links, images). The
+wrapper only sets _styling_ — fonts, margins, headings, page numbers — so the
+output looks deliberate, not like a default-template export.
+
+## When to use this
+
+- A research report, brief, or summary the user wants as a downloadable file.
+- A subagent (e.g. the `researcher`) handed you a `research-<slug>.md` to ship as a PDF.
+- Any channel message asking for "a PDF" / "the report attached" / "PDF로 보내줘".
+
+When plain markdown in chat is fine, **don't** make a PDF. This is for when a
+_file_ is the deliverable.
+
+## Step 0 — one-time setup (install the toolchain)
+
+Run this `bash` block once per container life. It is **idempotent** — if the
+tools are already present it does nothing and exits fast. It `bun add`s the
+version-pinned Typst compiler (npm pulls only this platform's prebuilt binary —
+Linux x64/arm64, glibc or musl) and vendors the SHA256-verified `cmarker` package
+into `workspace/.tools/` so `@preview/cmarker` resolves offline.
+
+```sh
+set -eu
+cd workspace
+mkdir -p .tools
+cd .tools
+
+# Pinned to the exact versions validated for this skill. COMPILER_VERSION is the
+# npm package version of the Typst compiler; it embeds Typst 0.14.2. Bumping
+# either is a deliberate edit — keep the embedded-Typst note below in sync.
+COMPILER_VERSION="0.7.0"   # @myriaddreamin/typst-ts-node-compiler (embeds Typst 0.14.2)
+CMARKER_VERSION="0.1.8"
+PKGDIR="typst-packages/preview/cmarker/$CMARKER_VERSION"
+
+if [ -f "node_modules/@myriaddreamin/typst-ts-node-compiler/package.json" ] && [ -f "$PKGDIR/lib.typ" ]; then
+  echo "markdown-pdf toolchain already installed"
+else
+  # The Typst compiler, version-pinned. `bun add` resolves the right prebuilt
+  # NAPI binary for this platform via optionalDependencies — no Rust toolchain,
+  # no manual download. The exact pin keeps the toolchain reproducible: a future
+  # npm release can't silently change the embedded Typst version or the API that
+  # Step 3 depends on.
+  [ -f package.json ] || echo '{"name":"typeclaw-markdown-pdf-tools","private":true}' > package.json
+  bun add "@myriaddreamin/typst-ts-node-compiler@$COMPILER_VERSION"
+
+  # cmarker (Markdown -> Typst), vendored so compilation needs no network.
+  mkdir -p "$PKGDIR"
+  curl -fsSL -o cmarker.tar.gz \
+    "https://packages.typst.org/preview/cmarker-$CMARKER_VERSION.tar.gz"
+  echo "157cc40db2716f12c7eabb95df1f60714a4d95ebfb1c6087cf4aec224e49392a  cmarker.tar.gz" | sha256sum -c -
+  tar -xzf cmarker.tar.gz -C "$PKGDIR"
+  rm cmarker.tar.gz
+  echo "markdown-pdf toolchain installed"
+fi
+```
+
+Notes:
+
+- It writes only under `workspace/`, the directory your `bash`/`write` tools can
+  write to. `workspace/.tools/` is gitignored scratch — it does not get committed.
+- It needs network the first time (to `bun add` the compiler + fetch the package).
+  After that the tools persist for the life of the container.
+- **Everything is version-pinned and reproducible.** The validated toolchain is
+  `@myriaddreamin/typst-ts-node-compiler@0.7.0` (which embeds Typst **0.14.2**) and
+  `cmarker@0.1.8` (SHA256-verified). The `bun add` uses the exact `@0.7.0` pin, so
+  a future npm release can't change the embedded Typst version or the API Step 3
+  uses. To upgrade, bump both `COMPILER_VERSION` and the embedded-Typst note
+  together after re-validating.
+
+## Step 1 — have the markdown ready
+
+Use an existing markdown file (yours or a subagent's), or `write` your content to
+`workspace/<slug>.md`. Standard CommonMark plus tables and footnotes all work.
+
+## Step 2 — write the styled wrapper
+
+`write` this to `workspace/<slug>.typ`, changing only the `read("...")` filename
+to match your markdown. The defaults are a clean, professional house style; adjust
+fonts/margins only if the user asks.
+
+```typst
+#set document(title: "Report")
+#set page(
+  paper: "a4",
+  margin: (x: 2.5cm, y: 2.75cm),
+  numbering: "1",
+  footer: context align(center, text(size: 9pt, fill: luma(120))[
+    #counter(page).display("1 / 1", both: true)
+  ]),
+)
+#set text(font: ("Libertinus Serif", "New Computer Modern"), size: 11pt, lang: "en")
+#set par(justify: true, leading: 0.68em, spacing: 1.1em)
+
+#show heading: set text(weight: "semibold")
+#show heading.where(level: 1): it => block(width: 100%, above: 1.4em, below: 0.9em)[
+  #text(size: 1.5em, it.body)
+  #v(-0.4em)
+  #line(length: 100%, stroke: 0.5pt + luma(200))
+]
+#show link: it => text(fill: rgb("#1a56db"), underline(it))
+#show quote.where(block: true): it => block(
+  inset: (left: 1em), stroke: (left: 2pt + luma(200)),
+  text(style: "italic", fill: luma(80), it.body),
+)
+#show raw.where(block: true): it => block(
+  fill: luma(245), inset: 8pt, radius: 4pt, width: 100%, text(size: 9pt, it),
+)
+#show table: set table(stroke: 0.5pt + luma(200))
+
+#import "@preview/cmarker:0.1.8"
+#cmarker.render(read("report.md"), h1-level: 1, blockquote: quote.with(block: true))
+```
+
+Notes:
+
+- `read("report.md")` is **relative to the workspace** (the compiler's `workspace`
+  is set to `workspace/` — see Step 3). Keep the `.typ` and `.md` in `workspace/`.
+- Fonts `Libertinus Serif` / `New Computer Modern` are bundled with Typst (no font
+  install). For Korean/CJK body text, add `"Noto Serif CJK KR"` to the `font:` list
+  and pass that font dir to `fontPaths` in Step 3 (the container's `cjkFonts` toggle
+  installs `fonts-noto-cjk` under `/usr/share/fonts`).
+
+## Step 3 — render
+
+`write` this tiny renderer to `workspace/.tools/render.ts`, then run it. It loads
+the npm-installed compiler, points the package cache at the vendored `cmarker`, and
+writes the PDF. Pass the wrapper and output paths as arguments.
+
+```ts
+// workspace/.tools/render.ts
+import { NodeCompiler } from '@myriaddreamin/typst-ts-node-compiler'
+import { writeFileSync } from 'node:fs'
+
+const [, , mainFile, outFile] = process.argv
+if (!mainFile || !outFile) throw new Error('usage: render.ts <main.typ> <out.pdf>')
+
+const compiler = NodeCompiler.create({
+  workspace: '.', // run from workspace/, so read("report.md") resolves
+  // Add CJK / extra font dirs here if needed:
+  // fontArgs: [{ fontPaths: ["/usr/share/fonts"] }],
+})
+const pdf = compiler.pdf({ mainFilePath: mainFile })
+writeFileSync(outFile, Buffer.from(pdf))
+console.log(`wrote ${outFile} (${pdf.length} bytes)`)
+```
+
+Run it from `workspace/`, with the package cache pointed at the vendored packages:
+
+```sh
+cd workspace
+TYPST_PACKAGE_CACHE_PATH="$PWD/.tools/typst-packages" \
+TYPST_PACKAGE_PATH="$PWD/.tools/typst-packages" \
+  bun .tools/render.ts report.typ report.pdf
+```
+
+Verify: the command prints `wrote report.pdf (...)` and `workspace/report.pdf`
+exists. On a compile error the compiler throws with the offending Typst line —
+usually raw HTML or a markdown extension `cmarker` doesn't support; simplify that
+part and re-run.
+
+## Rich elements (optional)
+
+When plain markdown isn't enough — you want a cover banner, callout boxes,
+multi-column sections, captioned figures — you don't switch to HTML (Typst
+doesn't render HTML). Instead, drop **raw Typst** into the markdown via
+`<!--raw-typst ... -->` comments. `cmarker` evaluates them as Typst (the
+`raw-typst: true` option is already the default and is set in the wrapper above).
+The rest of the document stays plain markdown.
+
+Each snippet below is self-contained — paste it into your `.md` where you want the
+element. They use Typst built-ins only (no extra packages).
+
+**Cover banner** (top of a report):
+
+```markdown
+<!--raw-typst
+#block(width: 100%, fill: rgb("#0f172a"), inset: 18pt, radius: 6pt)[
+  #text(fill: white, size: 1.6em, weight: "bold")[Quarterly Business Review]
+  #v(2pt)
+  #text(fill: rgb("#94a3b8"), size: 0.95em)[Acme Robotics · Q2 2026 · Confidential]
+]
+#v(1em)
+-->
+```
+
+**Callout boxes** (info / warning — change the two colors for other variants):
+
+```markdown
+<!--raw-typst
+#block(fill: rgb("#eff6ff"), stroke: (left: 3pt + rgb("#3b82f6")), inset: 12pt, radius: 4pt, width: 100%)[
+  #text(weight: "bold")[Note.] Revenue grew 31% YoY.
+]
+#v(0.6em)
+#block(fill: rgb("#fef2f2"), stroke: (left: 3pt + rgb("#ef4444")), inset: 12pt, radius: 4pt, width: 100%)[
+  #text(weight: "bold")[Risk.] A single supplier covers 40% of NPUs.
+]
+-->
+```
+
+**Two-column section** (use `#colbreak()` to split):
+
+```markdown
+<!--raw-typst
+#columns(2, gutter: 1.4em)[
+  #text(weight: "bold")[Strengths]
+  - Net retention 124%
+  - Margin +240bps
+  #colbreak()
+  #text(weight: "bold")[Risks]
+  - Supplier concentration
+  - Partial FX hedging
+]
+-->
+```
+
+**Figure with caption** (swap the `rect(...)` for `image("chart.png")` to embed an
+image written to `workspace/`):
+
+```markdown
+<!--raw-typst
+#figure(
+  rect(width: 60%, height: 48pt, fill: luma(245), stroke: 0.5pt + luma(180)),
+  caption: [Revenue trend, Q1–Q2 2026.],
+)
+-->
+```
+
+**Definition grid** (label column + description column):
+
+```markdown
+<!--raw-typst
+#grid(columns: (auto, 1fr), row-gutter: 6pt, column-gutter: 12pt,
+  text(weight: "bold")[NPU], [Neural processing unit — on-device inference accelerator.],
+  text(weight: "bold")[Net retention], [Revenue from existing customers vs. a year ago.],
+)
+-->
+```
+
+Keep it tasteful — a banner, a couple of callouts, and one good figure read as
+deliberate; a wall of colored boxes reads as noise.
+
+## Rendering an _existing_ web page or HTML to PDF
+
+This skill renders **markdown you author**. If instead you need to capture an
+**existing web page or a live URL** as a PDF — something Typst cannot do — use the
+already-installed `agent-browser` (Chrome): `agent-browser --allow-file-access open
+file:///agent/workspace/page.html` (or a URL), then `agent-browser pdf
+/agent/workspace/out.pdf`. Note its output is fixed US-Letter with default margins
+(no page-size flags), and launching the browser needs a trusted/owner session — so
+it's the right tool for _archiving web content_, not for authoring styled reports.
+For authored documents, stay on the Typst path above.
+
+## Step 4 — deliver
+
+- **Channel asked for the PDF** — attach it:
+
+  ```
+  channel_send(text: "Here's the report.", attachments: [{ path: "/agent/workspace/report.pdf", filename: "Edge-AI-Brief.pdf" }])
+  ```
+
+  Use a human-friendly `filename` and an absolute `/agent/workspace/...` path. Slack,
+  Discord, Telegram, and KakaoTalk upload the file; the GitHub adapter has no
+  attachment support, so there post a link or paste the markdown.
+
+- **Replying in a thread** — use `channel_reply` with the same `attachments` shape.
+
+- **No channel** (TUI session) — just report the path: `workspace/report.pdf`.
+
+## If you got the markdown from a subagent
+
+The `researcher` subagent writes its report to `workspace/research-<slug>.md` and
+returns a `<report>` block naming the file. Point the wrapper's `read(...)` at that
+file, render, and attach. You do the PDF step — the researcher's `bash` is
+read-only and it only emits markdown by design.
+
+## Customizing this skill
+
+This is a bundled default. Want a different house style, a different converter, or
+a cover page with a logo? Copy this file to `.agents/skills/<your-name>/SKILL.md`
+(use a **different** `name`; bundled skills win name collisions) and edit the setup
+or the wrapper there. Because the whole pipeline — install + render — lives in the
+skill, you can change either half without touching the container image.
+
+## Known limitations
+
+`cmarker` covers CommonMark well, but a few markdown features don't render as you
+might expect:
+
+- **Task-list checkboxes** (`- [ ]` / `- [x]`) render as literal `[ ]` text, not
+  checkboxes. Use a plain bullet list or a status column in a table instead.
+- **Bold/italic directly adjacent to CJK + parenthetical Latin** (e.g.
+  `**로컬 우선(local-first)**`) may not be recognized as emphasis — CommonMark's
+  flanking rules treat that boundary as non-emphasis. Put a space inside, or bold a
+  pure run of text.
+- **Raw HTML** in the markdown is mostly ignored. Express structure in markdown
+  (tables, lists) rather than HTML.
+
+## Don'ts
+
+- **Don't** hand-write Typst markup for the body. Let `cmarker` render the
+  markdown; only style via `#set` / `#show` rules in the wrapper.
+- **Don't** write the `.typ`, `.md`, `.pdf`, or `.tools/` outside `workspace/` —
+  the sandbox blocks it.
+- **Don't** re-run Step 0's install if the tools already exist — the guard at the
+  top skips it. Re-installing every time is wasteful.
+- **Don't** attach a PDF to a GitHub channel — that adapter rejects attachments.
+  Link or inline instead.