typeclaw 0.35.1 → 0.36.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "typeclaw",
-  "version": "0.35.1",
+  "version": "0.36.0",
   "homepage": "https://github.com/typeclaw/typeclaw#readme",
   "bugs": {
     "url": "https://github.com/typeclaw/typeclaw/issues"
@@ -42,6 +42,7 @@
     "postinstall": "bun run scripts/generate-schema.ts"
   },
   "dependencies": {
+    "@clack/core": "^1.2.0",
     "@clack/prompts": "^1.2.0",
     "@mariozechner/pi-coding-agent": "^0.67.3",
     "@mariozechner/pi-tui": "^0.67.3",

package/src/agent/session-origin.ts

@@ -574,14 +574,15 @@ function renderResearchReportDeliveryGuidance(platformInfo: PlatformInfo): strin
     `**Ship reports as a PDF by default.** ${platformInfo.displayName} accepts file`,
     'attachments. When the user asks for a report, document, brief, or "the report"',
     '— or a `researcher` subagent hands you a `research-<slug>.md` file path in its',
-    '`<report>` block — convert that markdown to a PDF with the `typeclaw-markdown-pdf`',
+    '`<report>` block — convert that markdown to a PDF with the `typeclaw-render-pdf`',
     'skill and deliver it with `channel_send({ ..., attachments: [{ path, filename }] })`,',
     'with a one- or two-line summary as the message text. A `researcher` `<summary>`',
     'is a teaser, NOT the deliverable: the deliverable is the report file rendered to',
     'PDF. Never build the PDF with an ad-hoc library (jsPDF, pdfkit, a raw-text dump) —',
     'that yields unrendered markdown and mojibake; the skill is the only correct path.',
-    "For CJK (Korean/Japanese/Chinese) reports, follow that skill's CJK font gate —",
-    'never ship a tofu-rendered PDF; ask before enabling the opt-in `cjkFonts`.',
+    "For CJK (Korean/Japanese/Chinese) reports, follow that skill's CJK guidance —",
+    'never ship a tofu-rendered PDF; if the output has tofu boxes, ask before',
+    'enabling the opt-in `cjkFonts` and restarting.',
     'A downloadable file is what a human wants for a multi-page report; do not paste',
     'the full markdown into chat, and do not attach the raw `.md` when asked for a',
     'report or PDF. Send inline plain text only if the caller explicitly asked for it,',

package/src/agent/system-prompt.ts

@@ -63,7 +63,7 @@ Do not narrate routine, low-risk tool calls. Just call the tool. Narrate only wh
 
 When the user asks for a *report*, *document*, *brief*, *PDF*, or asks you to *send/show/attach/export* a generated result — anything where the deliverable is a file a human would download, print, or forward — produce a polished file, not a wall of text pasted into chat and not a one-line summary that drops the substance. A summary (yours or a subagent's) is a pointer to the deliverable, never the deliverable itself; when the user asked for the report, ship the report.
 
-To turn Markdown into a PDF, use the bundled \`typeclaw-markdown-pdf\` skill — it is the only supported path and it renders Markdown properly (headings, lists, tables). **Never** hand-roll a PDF with an ad-hoc library (jsPDF, pdfkit, a canvas text dump, a headless-browser raw-text print): those produce unrendered raw \`##\`/\`**\` markup and mojibake for non-Latin text. CJK fonts are opt-in, so for Korean/Japanese/Chinese reports follow that skill's CJK gate — never ship a tofu-rendered PDF; ask before enabling opt-in CJK fonts. If a request is plainly satisfied by inline chat — a short answer, a snippet, a quick explanation — stay inline; this rule is for explicit document deliverables, not for every long reply.
+To turn Markdown into a PDF, use the bundled \`typeclaw-render-pdf\` skill — it is the only supported path and it renders Markdown properly (headings, lists, tables). **Never** hand-roll a PDF with an ad-hoc library (jsPDF, pdfkit, a canvas text dump, a headless-browser raw-text print, Python ReportLab): those produce unrendered raw \`##\`/\`**\` markup and mojibake for non-Latin text. CJK fonts are opt-in, so for Korean/Japanese/Chinese reports follow that skill's CJK guidance — never ship a tofu-rendered PDF; if the output has tofu boxes, ask before enabling opt-in CJK fonts and restarting. If a request is plainly satisfied by inline chat — a short answer, a snippet, a quick explanation — stay inline; this rule is for explicit document deliverables, not for every long reply.
 
 ## Long-running and interactive shell work
 

package/src/bundled-plugins/doc-render/index.ts

@@ -0,0 +1,20 @@
+import { join } from 'node:path'
+
+import { definePlugin } from '@/plugin'
+
+// In-container path of the bundled render script, relative to the agent root
+// (the bwrap jail ro-binds /agent, so a low-trust sandboxed `bun run` can read
+// it here). typeclaw always installs at node_modules/typeclaw and ships src/ to
+// npm, so this path is stable across dev and prod. The skill references the same
+// path — keep them in lockstep.
+export const RENDER_SCRIPT_AGENT_RELATIVE_PATH = 'node_modules/typeclaw/src/bundled-plugins/doc-render/render.ts'
+
+export function renderScriptPath(): string {
+  return join(import.meta.dir, 'render.ts')
+}
+
+export default definePlugin({
+  plugin: async () => ({
+    skillsDirs: [join(import.meta.dir, 'skills')],
+  }),
+})

package/src/bundled-plugins/doc-render/render.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env bun
+// Bundled `bun run`-able render script for the doc-render plugin: the agent runs
+// `bun run <this> <main.typ> <out.pdf>`. Lives as a script (not a registered
+// tool) so it costs zero always-on system-prompt context, and the agent
+// dynamic-imports the Typst compiler from its own /agent/node_modules — installed
+// on first use, never baked into the image. Its on-disk path is published to a
+// /tmp hint at boot (see index.ts) so the skill can resolve it.
+//
+// TODO(doc-render): PDF via Typst only. docx/xlsx/pptx are tracked separately —
+// each an npm renderer installed via the same dynamic `bun add` + dynamic-import
+// pattern. Office *conversion* (md->docx, docx->pdf) needs a system binary
+// (LibreOffice/Pandoc), not an npm package, so it is out of scope here. See
+// typeclaw/typeclaw#761.
+
+// Keep in sync with the `bun add` line in skills/typeclaw-render-pdf/SKILL.md.
+// 0.7.0 embeds Typst 0.14.2; bumping is a deliberate, re-validated edit.
+export const COMPILER_PACKAGE = '@myriaddreamin/typst-ts-node-compiler'
+export const COMPILER_VERSION = '0.7.0'
+
+// NodeCompiler does not auto-discover system font dirs the way the Typst CLI
+// does; without these, CJK glyphs render as .notdef tofu. Filtered by existence
+// so a missing dir on a dev/host run is skipped, not fatal.
+export const FONT_PATHS = ['/usr/share/fonts', '/usr/local/share/fonts', '/Library/Fonts', '/System/Library/Fonts']
+
+export function missingCompilerGuidance(): string {
+  return [
+    `doc-render: ${COMPILER_PACKAGE} is not installed.`,
+    '',
+    'One-time PDF toolchain install. Run from the agent root (writes node_modules',
+    '+ package.json + bun.lock, which survive restarts), then re-run this render:',
+    '',
+    `  bun add ${COMPILER_PACKAGE}@${COMPILER_VERSION}`,
+    '',
+    'Do NOT fall back to jsPDF, pdfkit, a canvas text dump, a headless-browser',
+    'raw-text print, or Python ReportLab — those skip Markdown rendering and ship',
+    'no CJK font. This Typst path is the only supported one.',
+  ].join('\n')
+}
+
+// The per-tool sandbox falls back to a degraded `--tmpfs /proc` on a host with
+// no usable user namespaces, where Bun's loader can't read /proc/self/{fd,maps}
+// and aborts with ENOTDIR. Rare since the proc-bind retry fix (typeclaw 0.35.1),
+// but still possible on exotic runtimes — and unfixable by switching libraries.
+function isNotDirError(error: unknown): boolean {
+  return (
+    typeof error === 'object' && error !== null && 'code' in error && (error as { code?: unknown }).code === 'ENOTDIR'
+  )
+}
+
+function notDirGuidance(): string {
+  return [
+    'doc-render: the renderer aborted with a Bun "NotDir" / ENOTDIR error.',
+    '',
+    'This is the sandbox /proc degraded mode, not your markup and not a missing',
+    'font: on a host with no usable user namespaces the per-tool sandbox falls',
+    "back to a tmpfs /proc where bun can't run packages. Retry once; if it",
+    'persists, report it as a sandbox/environment issue. A different PDF library',
+    'will not fix a /proc problem.',
+  ].join('\n')
+}
+
+type NodeCompilerModule = {
+  NodeCompiler: {
+    create(options: { workspace: string; fontArgs?: { fontPaths: string[] }[] }): {
+      pdf(options: { mainFilePath: string }): Uint8Array
+    }
+  }
+}
+
+// Resolve from the CALLER's cwd, not this script's location: the agent installs
+// the compiler into its own /agent/node_modules and runs `bun run <this>` from
+// the agent root, but bare `import(pkg)` resolves relative to this file (under
+// node_modules/typeclaw/...), which need not see the agent's deps. Resolving
+// against cwd, then importing the absolute path, makes the lookup independent of
+// where the bundled script physically lives.
+export async function loadCompilerModule(cwd: string = process.cwd()): Promise<NodeCompilerModule> {
+  const resolved = Bun.resolveSync(COMPILER_PACKAGE, cwd)
+  return (await import(resolved)) as NodeCompilerModule
+}
+
+export async function renderPdf(mainFile: string, outFile: string): Promise<number> {
+  const { existsSync, writeFileSync } = await import('node:fs')
+
+  const fontPaths = FONT_PATHS.filter((p) => existsSync(p))
+  const mod = await loadCompilerModule()
+  const compiler = mod.NodeCompiler.create({
+    workspace: '.',
+    ...(fontPaths.length > 0 ? { fontArgs: [{ fontPaths }] } : {}),
+  })
+  const pdf = compiler.pdf({ mainFilePath: mainFile })
+  writeFileSync(outFile, Buffer.from(pdf))
+  return pdf.length
+}
+
+// Bun phrasings for an unresolved import. Broad on purpose: a false positive only
+// shows the install hint on an unrelated error, and the package name in the
+// message keeps it specific in practice.
+export function isModuleNotFound(message: string): boolean {
+  return (
+    message.includes('Cannot find package') ||
+    message.includes('Cannot find module') ||
+    message.includes('Module not found') ||
+    message.includes(COMPILER_PACKAGE)
+  )
+}
+
+const EXIT_RENDER_FAILED = 1
+const EXIT_BAD_USAGE = 2
+const EXIT_COMPILER_MISSING = 3
+
+async function main(): Promise<void> {
+  const [, , mainFile, outFile] = process.argv
+  if (!mainFile || !outFile) {
+    process.stderr.write('usage: bun run render.ts <main.typ> <out.pdf>\n')
+    process.exit(EXIT_BAD_USAGE)
+  }
+
+  let bytes: number
+  try {
+    bytes = await renderPdf(mainFile, outFile)
+  } catch (error) {
+    if (isNotDirError(error)) {
+      process.stderr.write(`${notDirGuidance()}\n`)
+      process.exit(EXIT_RENDER_FAILED)
+    }
+    const message = error instanceof Error ? error.message : String(error)
+    if (isModuleNotFound(message)) {
+      process.stderr.write(`${missingCompilerGuidance()}\n`)
+      process.exit(EXIT_COMPILER_MISSING)
+    }
+    process.stderr.write(`doc-render: render failed: ${message}\n`)
+    process.exit(EXIT_RENDER_FAILED)
+  }
+
+  process.stdout.write(`wrote ${outFile} (${bytes} bytes)\n`)
+}
+
+if (import.meta.main) {
+  await main()
+}

package/src/bundled-plugins/doc-render/skills/typeclaw-render-pdf/SKILL.md

@@ -0,0 +1,314 @@
+---
+name: typeclaw-render-pdf
+description: "The ONLY supported way to render 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, render report, export document, anything a human would want to download, print, or forward, including a researcher's report file shipped as a Slack/Discord attachment. Triggers: 'make a PDF', 'export to PDF', 'markdown to PDF', 'PDF report', 'render report', 'export document', 'the 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 첨부', '리포트', '보고서'. Provided by the bundled `doc-render` plugin: a small Typst toolchain is installed on first use via `bun add` (no PDF library is baked into the image), and a bundled render script does the compile. Handles CJK/Korean/Japanese/Chinese: CJK fonts are opt-in, so if the output has tofu (□□□) boxes it tells you to enable `docker.file.cjkFonts` and restart, then regenerates — it never auto-downloads a font. Also load before saying you cannot produce PDFs — you can. NEVER build a PDF with jsPDF, pdfkit, a canvas text dump, a headless-browser raw-text print, or Python ReportLab — those produce unrendered markdown and broken CJK; this skill is the only correct path. Covers the one-time install, 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; doc-render produces documents, it does not read them."
+---
+
+# typeclaw-render-pdf
+
+You can produce professional PDFs from Markdown. The bundled `doc-render` plugin
+ships the render script; the only thing installed on demand is the
+[Typst](https://typst.app) compiler — a single npm package the agent `bun add`s
+into its own `node_modules` the **first time** you need a PDF, then reuses. No
+Pandoc, no LaTeX, no headless browser, and no PDF toolchain baked into the image.
+
+The flow is: **(1)** install the compiler once (`bun add` — it lands in the
+agent's `node_modules`, surviving restarts), **(2)** write a styled `.typ`
+wrapper that reads your Markdown, **(3)** run the bundled render script. If a
+channel asked for the PDF, attach the result with `channel_send`.
+
+You do **not** need to learn Typst markup. The
+[`cmarker`](https://typst.app/universe/package/cmarker/) package 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.
+
+> **This is the only supported way to make a PDF from Markdown in TypeClaw.**
+> Do **not** reach for `jsPDF`, `pdfkit`, a `<canvas>` text dump, a
+> headless-browser "print raw text" path, or Python `ReportLab`. Those skip
+> Markdown rendering (you get literal `##` and `**` in the output) and ship no
+> CJK font, so Korean/Japanese/Chinese come out as mojibake. The Typst path below
+> renders the Markdown properly. If you catch yourself about to `bun add` a PDF
+> library other than the Typst compiler named here, stop.
+
+## 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 — install the Typst compiler (once per container)
+
+The PDF compiler is not baked into the image — install it on first use. It is a
+single version-pinned npm package (npm pulls only this platform's prebuilt
+binary — Linux x64/arm64, glibc or musl). It writes to the agent's
+`node_modules` + `package.json` + `bun.lock`, all of which survive restarts, so
+this only runs once per container life:
+
+```sh
+# Idempotent: bun add is a no-op if it's already the installed version.
+bun add @myriaddreamin/typst-ts-node-compiler@0.7.0
+```
+
+The `@0.7.0` pin embeds Typst 0.14.2 and keeps the toolchain reproducible — a
+future npm release can't silently change the embedded Typst version or the API
+the render script depends on. If you forget this step, the render script in
+Step 3 stops with the exact `bun add` line to run, so you can also just try the
+render and follow its guidance.
+
+> **Where it goes:** the agent's own `node_modules` — the canonical home for
+> executable dependencies, gitignored, not user-facing. Do **not** create a
+> `package.json` or `node_modules` under `workspace/` for this; let `bun add`
+> manage it at the agent root like any other dependency.
+
+## Step 1 — have the markdown ready
+
+Use an existing markdown file (yours or a subagent's), or `write` your content to
+a markdown file. Standard CommonMark plus tables and footnotes all work. Put the
+`.md` and the `.typ` (Step 2) in the same directory so the wrapper's relative
+`read("...")` resolves — any agent-writable directory works (`workspace/`,
+`public/`, `mounts/`, or wherever the source `.md` already lives, e.g. a
+researcher's report under `public/`). There is no required directory; keep the
+two files together and run the render from there.
+
+## Step 2 — write the styled wrapper
+
+`write` a `.typ` next to your markdown, pointing `read("...")` at the markdown
+filename. The wrapper below is a clean, professional **starting point** — not a
+fixed template. Design the document to fit its content and audience: a dense
+technical brief wants tighter margins than an airy exec summary; a launch report
+might open with a cover banner. Adjust fonts, spacing, and structure freely, and
+reach for the **Rich elements** palette below when plain prose isn't enough.
+
+```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", "Noto Serif CJK KR"), 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 render's working directory**, so Step 3
+  `cd`s into the directory holding the `.typ` and `.md` before running. Keep them
+  together.
+- Fonts `Libertinus Serif` / `New Computer Modern` are bundled with Typst (no font
+  install) and carry the Latin text. `"Noto Serif CJK KR"` is appended as the
+  fallback so Korean/CJK glyphs resolve per-glyph wherever the Latin fonts have no
+  glyph, leaving Latin runs untouched. It is only present when the container's
+  `cjkFonts` toggle is on — see "## Handling CJK content".
+- `cmarker` fetches from the Typst package registry on first compile (the same
+  network the `bun add` step needs). It caches under the render's `$HOME`, which
+  in a sandboxed (channel/guest) session is per-session scratch — so a later
+  session may re-fetch it. That's a one-time network hit, not an error.
+
+## Step 3 — render
+
+The render script is **bundled with the plugin** — you do not write it. It lives
+at `/agent/node_modules/typeclaw/src/bundled-plugins/doc-render/render.ts`.
+
+**`cd` into the directory holding your `.typ` and `.md` first** — your shell
+starts at the agent root, and the wrapper's `read("report.md")` resolves relative
+to the render's working directory, so you must run it from there:
+
+```sh
+cd /agent/workspace            # or wherever your .typ + .md live (public/, mounts/, …)
+bun run /agent/node_modules/typeclaw/src/bundled-plugins/doc-render/render.ts report.typ report.pdf
+```
+
+On success it prints `wrote report.pdf (<N> bytes)` and `report.pdf` exists in
+that directory.
+
+If it stops with **`@myriaddreamin/typst-ts-node-compiler is not installed`**
+(exit 3), run the Step 0 `bun add` and re-run. If it stops with a **`NotDir` /
+ENOTDIR** error, that is the sandbox `/proc` degraded mode, not your markup and
+not a font — retry once; if it persists, report it as a sandbox/environment
+issue and do **not** switch to another PDF library (it won't help). Any other
+error is a real Typst compile error (usually raw HTML or an unsupported markdown
+extension) and names the offending line — simplify that part and re-run.
+
+## Handling CJK content
+
+CJK fonts are **opt-in** (the `docker.file.cjkFonts` toggle). When they are off,
+Typst still renders — it just substitutes `.notdef` tofu (□) boxes for every
+Korean/Japanese/Chinese glyph. **Do not** download, vendor, or `curl` a font to
+work around this, and **do not** silently deliver a tofu PDF.
+
+You don't need a pre-render gate: render first, then verify. If the source
+markdown contains CJK and the resulting PDF shows tofu boxes (or you know CJK
+fonts aren't enabled on this container), tell the user honestly and offer the
+fix:
+
+> This report has Korean/Japanese/Chinese text but the container has no CJK font
+> — they're opt-in, so the PDF comes out as tofu boxes. Want me to set
+> `docker.file.cjkFonts: true` in `typeclaw.json`? It's a boot setting, so after
+> I edit it you'll run `typeclaw restart` from the host project directory, and
+> then I'll regenerate the PDF.
+
+Only after the user agrees: edit `typeclaw.json` to set `docker.file.cjkFonts:
+true` (use the `typeclaw-config` skill), ask them to `typeclaw restart`, and
+regenerate the PDF after the restarted container comes back. If the markdown has
+no CJK, this section doesn't apply.
+
+## Rich elements (optional)
+
+When plain markdown isn't enough — 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 the
+default). 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 next to the markdown):
+
+```markdown
+<!--raw-typst
+#figure(
+  rect(width: 60%, height: 48pt, fill: luma(245), stroke: 0.5pt + luma(180)),
+  caption: [Revenue trend, Q1–Q2 2026.],
+)
+-->
+```
+
+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**. 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`. Its output is fixed US-Letter with default margins, 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 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: `report.pdf`.
+
+## If you got the markdown from a subagent
+
+The `researcher` subagent writes its report to `research-<slug>.md` and returns a
+`<report>` block naming the file. Point the wrapper's `read(...)` at that file,
+render in that file's directory, 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 cover page with a
+logo, or a different converter? Copy this file to
+`.agents/skills/<your-name>/SKILL.md` (use a **different** `name`; bundled skills
+win name collisions) and edit it there.
+
+## 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 (and the optional
+  raw-typst rich elements).
+- **Don't** build a `package.json` / `node_modules` / a render script under
+  `workspace/`. The compiler installs at the agent root via `bun add`; the render
+  script is bundled with the plugin (at
+  `/agent/node_modules/typeclaw/src/bundled-plugins/doc-render/render.ts`).
+- **Don't** attach a PDF to a GitHub channel — that adapter rejects attachments.
+  Link or inline instead.

package/src/bundled-plugins/security/index.ts

@@ -12,6 +12,7 @@ import {
   recordGitRemoteTaintIfAny,
 } from './policies/git-exfil'
 import { GUARD_OUTBOUND_SECRET_SEVERITY, checkOutboundSecretGuard } from './policies/outbound-secret-scan'
+import { GUARD_PLUGIN_ADDITION_SEVERITY, checkPluginAdditionGuard } from './policies/plugin-addition'
 import { checkPrivateSurfaceReadGuard } from './policies/private-surface-read'
 import { applyPromptInjectionDefense } from './policies/prompt-injection'
 import { clearSessionTaints } from './policies/remote-taint-state'
@@ -68,6 +69,8 @@ const BYPASS_ROLE_HINT = {
     'owner and trusted have it by default (medium tier); member and guest do not. The privilege-escalation defense for trusted now depends on operator review of `typeclaw.json` backup commits — `roles` is restart-required, so the operator has wall-clock time to revert before the new role table takes effect. Operators who do not review can re-tighten by replacing `roles.trusted.permissions[]` with an explicit list that omits `security.bypass.medium`.',
   [SECURITY_PERMISSIONS.bypassCronPromotion]:
     'owner and trusted have it by default (medium tier); member and guest do not. Same shape as rolePromotion but deferred: a new cron job (or a changed scheduledByRole) fires at schedule-time as the stamped role. The operator-review window between write and execution is the trusted-tier defense.',
+  [SECURITY_PERMISSIONS.bypassPluginAddition]:
+    'owner and trusted have it by default (medium tier); member and guest do not. Same shape as cronPromotion but for host-side install: a new (or version-bumped) plugins[] entry is materialized into package.json and installed by the next host `typeclaw start`, running npm lifecycle scripts as the operator. The operator-review window between the typeclaw.json write and the next start is the trusted-tier defense.',
 } as const satisfies Record<PerGuardSecurityPermission, string>
 
 function withPermissionHint(
@@ -121,6 +124,18 @@ export default definePlugin({
             )
         if (cronPromotionResult) return cronPromotionResult
 
+        const pluginAdditionResult = canBypass(
+          GUARD_PLUGIN_ADDITION_SEVERITY,
+          SECURITY_PERMISSIONS.bypassPluginAddition,
+        )
+          ? undefined
+          : withPermissionHint(
+              await checkPluginAdditionGuard({ tool: event.tool, args: event.args, agentDir: ctx.agentDir }),
+              SECURITY_PERMISSIONS.bypassPluginAddition,
+              GUARD_PLUGIN_ADDITION_SEVERITY,
+            )
+        if (pluginAdditionResult) return pluginAdditionResult
+
         // Taint-recording runs FIRST, independently of the gitExfil guard.
         // The gitRemoteTainted defense depends on it. We pass through
         // `permittedBypass` for actors who can skip gitExfil (via either the

package/src/bundled-plugins/security/permissions.ts

@@ -11,6 +11,7 @@ export const SECURITY_PERMISSIONS = {
   bypassGitRemoteTainted: 'security.bypass.gitRemoteTainted',
   bypassRolePromotion: 'security.bypass.rolePromotion',
   bypassCronPromotion: 'security.bypass.cronPromotion',
+  bypassPluginAddition: 'security.bypass.pluginAddition',
   // Severity-tier bypasses. Tiers classify guards on a two-axis policy:
   //   high   — bypass sends data to a third-party audience outside the
   //            operator's control loop (channel readers, remote git host).