dsh-deeptutor 0.3.0 → 0.3.2

package/.agents/skills/deeptutor/SKILL.md

@@ -120,16 +120,32 @@ acceptance criteria; references.
 
 Pass `html` to `deeptutor_run` and the answer is rendered to a self-contained
 page (dark/light toggle, TOC, collapsible quiz answers, print-friendly) with
-the bundled **html-doc** converter, plus the `.md` source next to it:
+the **html-doc** converter, plus the `.md` source next to it:
 
 ```
 deeptutor_run capability=deep_solve prompt=<topic> kbs=[...] tools=[rag, web_search]
-  html="data/study/<topic>/knowledge.html" html_title="<主题> · 知识点" language=zh
+  html="<absolute path, e.g. /home/me/study/<topic>/knowledge.html>" html_title="<主题> · 知识点" language=zh
 ```
 
-Relative paths resolve against your working directory. To render other
-Markdown, use the html-doc skill's converter
-(`node <html-doc skill dir>/scripts/md-to-html.js <in.md> --out <out.html> --title "<t>" --toc`).
+`html` must be an **absolute** path. A tool has no workspace root (dsh hands it
+only the agent identity, and the MCP server has no session), so a relative path
+cannot be resolved against your working directory — it is rejected instead of
+silently landing under the host process cwd. Prefix it with your working
+directory explicitly.
+
+The converter and its template are resolved in this order, and the tool result
+prints which layer won (`converter:` / `template:` lines):
+
+1. `HTML_DOC_SCRIPT` / `HTML_DOC_TEMPLATE` env vars (explicit override; a
+   set-but-missing path is an error),
+2. the installed skill at `<DSH_HOME>/skills/html-doc/` (`DSH_HOME` defaults to
+   `~/.dsh`) — edit the template there to customise the page, no plugin edit
+   needed,
+3. the copy bundled with the plugin.
+
+To render other Markdown, use the html-doc skill's converter
+(`node <html-doc skill dir>/scripts/md-to-html.js <in.md> --out <out.html> --title "<t>" --toc`,
+plus `--template <file>` to pick a specific template).
 Tell the user the file paths.
 
 ### 6. Archive (only on request)

package/.agents/skills/html-doc/SKILL.md

@@ -39,6 +39,8 @@ cat notes.md | node scripts/md-to-html.js --title "Quiz" --theme dark --out quiz
 #   --toc            generate a table of contents from headings (h2/h3)
 #   --lang <code>    html lang attribute (default: zh-CN)
 #   --no-collapse    disable <details> wrapping for quiz answers (default: collapse enabled)
+#   --template <file> HTML template to use (default: the assets/ copy next to the
+#                    script, or $HTML_DOC_TEMPLATE when that is set)
 ```
 
 ## Supported Markdown
@@ -84,6 +86,29 @@ Edit `assets/template.html` — it uses `{{TITLE}}`, `{{BODY}}`, `{{THEME}}`, `{
 - Table styling, blockquote styling, task-list checkboxes
 - Responsive layout (comfortable reading column)
 
+### Which template wins
+
+The converter resolves the template in this order (first hit wins); the `--out`
+log line names the file it used, and `deeptutor_run`'s `html` note prints it too:
+
+1. `--template <file>` on the command line,
+2. `$HTML_DOC_TEMPLATE`,
+3. `assets/template.html` next to the script (the copy shipped in this skill),
+4. `../.agents/skills/html-doc/assets/template.html` from a package-root duplicate.
+
+An explicitly requested template (1 or 2) that does not exist is an error
+instead of a silent fallback, so a typo cannot produce pages from the default
+template.
+
+`deeptutor_run`'s `html` path resolves this in the **host**, not inside this
+script: it prefers the **installed** skill at `<DSH_HOME>/skills/html-doc/` over
+the copy bundled in the plugin package (with `$HTML_DOC_SCRIPT`/`$HTML_DOC_TEMPLATE`
+as explicit overrides), then hands the winning template to the converter as
+`--template`. Editing the installed template therefore changes the next render —
+no plugin edit needed. (Re-running the installer copies the bundled skill files
+back over the installed ones, so keep a copy of a heavily customised template
+outside `<DSH_HOME>/skills/` and point `$HTML_DOC_TEMPLATE` at it.)
+
 ## Notes
 
 - Zero dependencies — only `node` (≥ 20.11, uses `import.meta.dirname`) is required; no npm install needed

package/.agents/skills/html-doc/scripts/md-to-html.js

@@ -4,9 +4,12 @@
  *
  * Usage:
  *   node md-to-html.js <input.md> [--out out.html] [--title "T"] [--theme dark|light]
- *                      [--toc] [--lang zh-CN] [--no-collapse]
+ *                      [--toc] [--lang zh-CN] [--no-collapse] [--template template.html]
  *   cat file.md | node md-to-html.js --title "T" --out out.html
  *
+ * Template resolution order: --template, $HTML_DOC_TEMPLATE, the assets/ copy
+ * next to this script, then the package-root duplicate's skill copy.
+ *
  * Features: headings, fenced code blocks, inline code/bold/italic/links, lists,
  * task lists, blockquotes, pipe tables, hr, quiz answer collapsing (<details>),
  * raw HTML passthrough, HTML escaping. Zero npm dependencies (Node >= 20.11 — uses import.meta.dirname).
@@ -27,9 +30,10 @@ function parseArgs(argv) {
     toc: false,
     lang: "zh-CN",
     collapse: true,
+    template: null,
   };
   const positional = [];
-  const valueFlags = new Set(["--out", "--title", "--theme", "--lang"]);
+  const valueFlags = new Set(["--out", "--title", "--theme", "--lang", "--template"]);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--toc") opts.toc = true;
@@ -50,7 +54,11 @@ function parseArgs(argv) {
           fail(`Invalid --theme value "${value}": expected dark or light`);
         }
         opts.theme = value;
-      } else if (a === "--lang") opts.lang = value;
+      } else if (a === "--lang") {
+        opts.lang = value;
+      } else if (a === "--template") {
+        opts.template = value;
+      }
     } else if (a.startsWith("--")) {
       fail(`Unknown option: ${a} (run with --help for usage)`);
     } else positional.push(a);
@@ -77,6 +85,8 @@ Options:
   --theme <mode>   dark | light (default: light; toggle also available in page)
   --toc            generate a table of contents from h2/h3 headings
   --lang <code>    html lang attribute (default: zh-CN)
+  --template <file> HTML template to use (default: the assets/ copy next to this
+                   script, or $HTML_DOC_TEMPLATE when set)
   --no-collapse    disable quiz-answer collapsing
   --help           show this help`);
 }
@@ -351,11 +361,25 @@ function main() {
   const generated = new Date().toISOString().slice(0, 10);
   // The same converter ships in two locations (.agents/skills/html-doc/scripts/
   // and a package-root scripts/ copy); resolve the template wherever we are.
+  // Order: --template, $HTML_DOC_TEMPLATE, then the copies next to this script.
+  // An explicit override that does not exist is an error: a typo must not
+  // silently fall through to a different template.
+  const explicitTemplate = opts.template || process.env.HTML_DOC_TEMPLATE || null;
   const templateCandidates = [
     path.join(import.meta.dirname, "..", "assets", "template.html"),
     path.join(import.meta.dirname, "..", ".agents", "skills", "html-doc", "assets", "template.html"),
   ];
-  const templatePath = templateCandidates.find((p) => fs.existsSync(p));
+  let templatePath;
+  if (explicitTemplate) {
+    if (!fs.existsSync(explicitTemplate)) {
+      fail(
+        `template not found: ${explicitTemplate} (from ${opts.template ? "--template" : "HTML_DOC_TEMPLATE"})`,
+      );
+    }
+    templatePath = explicitTemplate;
+  } else {
+    templatePath = templateCandidates.find((p) => fs.existsSync(p));
+  }
   if (!templatePath) {
     fail(`template.html not found (looked in: ${templateCandidates.join(", ")})`);
   }
@@ -380,7 +404,7 @@ function main() {
   if (opts.out) {
     fs.writeFileSync(opts.out, template, "utf8");
     console.log(
-      `[html-doc] wrote ${path.resolve(opts.out)} (${Buffer.byteLength(template)} bytes)`,
+      `[html-doc] wrote ${path.resolve(opts.out)} (${Buffer.byteLength(template)} bytes, template: ${templatePath})`,
     );
   } else {
     process.stdout.write(template);

package/README.md

@@ -58,7 +58,7 @@ A typical flow when you ask your agent for learning help:
 
 1. **Ask** — *"Explain C# generics covariance using my dotnet knowledge base, and generate a study page."*
 2. The agent grounds the answer in your own material: `deeptutor_kb` (`action=search`, `kb=dotnet`).
-3. It runs a deep-solve: `deeptutor_run` (`capability=deep_solve`, `kbs=[dotnet]`, `html=data/study/csharp-covariance.html`) — the answer comes back and a self-contained HTML page (plus the `.md` source) is written to disk.
+3. It runs a deep-solve: `deeptutor_run` (`capability=deep_solve`, `kbs=[dotnet]`, `html=/home/me/study/csharp-covariance.html`) — the answer comes back and a self-contained HTML page (plus the `.md` source) is written to disk. The `html` path must be absolute; relative paths are rejected.
 4. It files a summary: `deeptutor_note` (`notebook=dotnet-learning`, `type=solve`).
 
 Nothing here is a fixed script — the agent picks the tools and parameters based
@@ -182,7 +182,7 @@ install`:
 
 ```json
 {
-  "dependencies": { "dsh-deeptutor": "^0.3.0" },
+  "dependencies": { "dsh-deeptutor": "^0.3.1" },
   "dsh": {
     "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
   }
@@ -215,8 +215,12 @@ Two skills ship inside this package (`.agents/skills/deeptutor` and
 
 - `deeptutor` — the agent-facing learning workflow (`~/.dsh/skills/deeptutor/SKILL.md`)
 - `html-doc` — renders study answers to self-contained HTML pages
-  (`~/.dsh/skills/html-doc/`); the bundle uses the same converter
-  (`scripts/md-to-html.js`) when `deeptutor_run` gets an `html` path
+  (`~/.dsh/skills/html-doc/`); when `deeptutor_run` gets an `html` path, the
+  converter and template are resolved as `$HTML_DOC_SCRIPT` /
+  `$HTML_DOC_TEMPLATE` → the installed skill above → the copy bundled in this
+  package. Editing the installed template (say, wiring KaTeX in) changes the
+  next render without patching the plugin, and the tool result prints which
+  layer supplied each file. The `html` path itself must be absolute.
 
 Installing a newer package version overwrites skill files in place; files not
 shipped by the package are never deleted.
@@ -290,8 +294,7 @@ scripts/install-profile.mjs  # one-shot profile installer (exposed as the `dsh-d
 scripts/mcp-launch.mjs # starts the MCP server for the Claude Code plugin
 scripts/check-cli.ts   # drift check against a live DeepTutor (`npm run check:cli`)
 .agents/skills/       # bundled skills: deeptutor/ + html-doc/ (installed to <DSH_HOME>/skills/)
-.claude-plugin/       # Claude Code plugin.json + marketplace.json
-.mcp.json            # the plugin's MCP server (runs scripts/mcp-launch.mjs)
+.claude-plugin/       # Claude Code plugin.json (skills + MCP server) + marketplace.json
 cordis.yml           # dev overlay: insert src/index.ts by absolute path
 cordis.patch.yml     # bundle patch: insert the package by name
 ```

package/README.zh.md

@@ -38,7 +38,7 @@
 
 1. **提问** —— *"用我的 dotnet 知识库讲讲 C# 泛型协变,并生成学习页。"*
 2. agent 先检索你的自有资料:`deeptutor_kb`(`action=search`,`kb=dotnet`)。
-3. 再执行深度讲解:`deeptutor_run`(`capability=deep_solve`,`kbs=[dotnet]`,`html=data/study/csharp-covariance.html`)—— 答案返回的同时,自包含 HTML 学习页(及配套 `.md` 源文件)写入磁盘。
+3. 再执行深度讲解:`deeptutor_run`(`capability=deep_solve`,`kbs=[dotnet]`,`html=/home/me/study/csharp-covariance.html`)—— 答案返回的同时,自包含 HTML 学习页(及配套 `.md` 源文件)写入磁盘。`html` 必须是绝对路径,相对路径会被拒绝。
 4. 最后归档摘要:`deeptutor_note`(`notebook=dotnet-learning`,`type=solve`)。
 
 以上不是固定脚本 —— agent 会根据你的提问自由选择工具与参数。
@@ -119,7 +119,7 @@ dsh --profile web --dump-config | grep dsh-deeptutor
 
 ```json
 {
-  "dependencies": { "dsh-deeptutor": "^0.3.0" },
+  "dependencies": { "dsh-deeptutor": "^0.3.1" },
   "dsh": {
     "profile": { "bundles": ["@deepseek-ai/dsh-base", "@deepseek-ai/dsh-web-app", "dsh-deeptutor"] }
   }
@@ -146,7 +146,7 @@ bundle 清单(`dsh.bundle.patch → cordis.patch.yml`)负责插入插件行;上
 本包携带两个 skill(`.agents/skills/deeptutor` 与 `.agents/skills/html-doc`),随包安装器每次运行时都会把它们复制到 `<DSH_HOME>/skills/<name>/`(dsh 自动发现)—— 所以 `pnpm dlx dsh-deeptutor` 一次装齐插件 **和** skill:
 
 - `deeptutor` — 面向 agent 的学习工作流(`~/.dsh/skills/deeptutor/SKILL.md`)
-- `html-doc` — 将学习内容渲染为自包含 HTML 页面(`~/.dsh/skills/html-doc/`);`deeptutor_run` 传入 `html` 路径时,插件内部使用同一转换器(`scripts/md-to-html.js`)
+- `html-doc` — 将学习内容渲染为自包含 HTML 页面(`~/.dsh/skills/html-doc/`);`deeptutor_run` 传入 `html` 时,转换器与模板按 `$HTML_DOC_SCRIPT` / `$HTML_DOC_TEMPLATE` → 上面这个已安装 skill → 包内副本的顺序解析。改已安装模板(例如真正接上 KaTeX)下次渲染即生效,不用改插件包;工具结果会打印每层实际用的文件。`html` 路径必须是绝对路径。
 
 升级包版本时会就地覆盖 skill 文件;包未携带的文件不会被删除。
 
@@ -205,8 +205,7 @@ scripts/install-profile.mjs  # 一键 profile 安装器(以 `dsh-deeptutor` 二
 scripts/mcp-launch.mjs # 为 Claude Code 插件启动 MCP server
 scripts/check-cli.ts   # 对真实 DeepTutor 的漂移检查(`npm run check:cli`)
 .agents/skills/       # 随包 skill:deeptutor/ + html-doc/(安装到 <DSH_HOME>/skills/)
-.claude-plugin/       # Claude Code 的 plugin.json 和 marketplace.json
-.mcp.json            # 插件的 MCP server(运行 scripts/mcp-launch.mjs)
+.claude-plugin/       # Claude Code 的 plugin.json(skill 和 MCP server)和 marketplace.json
 cordis.yml           # 开发 overlay:按绝对路径插入 src/index.ts
 cordis.patch.yml     # bundle patch:按包名插入插件
 ```

package/lib/cli-exec.d.ts

@@ -1,9 +1,33 @@
+/**
+ * Upper bound for one CLI run's captured stdout/stderr.
+ *
+ * `deeptutor run --format json` writes one JSON line per streamed chunk, and a
+ * chunk is roughly one character of the answer once event metadata is included
+ * (~1.5 KB of JSON per output character measured on 1.7.1). A 1500-character
+ * answer is therefore ~2 MB, already past Node's 1 MB `execFile` default: the
+ * child is killed mid-turn and the only trace is a string `err.code`
+ * (`ERR_CHILD_PROCESS_STDIO_MAXBUFFER`) with empty stderr. 64 MB covers a
+ * ~40k-character answer, well beyond the CLI's own per-turn token ceiling.
+ */
+export declare const MAX_CLI_OUTPUT_BYTES: number;
 export interface CliResult {
     stdout: string;
     stderr: string;
     code: number;
     killed: boolean;
+    /** Node-level failure code, kept when stderr is empty so callers can report it. */
+    error?: string;
 }
+/** Model-facing detail for a failed CLI run: stderr first, else the Node error code. */
+export declare function describeCliFailure(res: Pick<CliResult, "stderr" | "error">): string;
+/** Exec one command with optional abort + timeout, resolving instead of throwing.
+ *  Exported for tests: the captured-output ceiling is part of the contract. */
+export declare function execFileResolved(file: string, args: string[], opts?: {
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    env?: Record<string, string>;
+    windowsVerbatimArguments?: boolean;
+}): Promise<CliResult>;
 /** Options shared by every CLI invocation. */
 export interface CliOptions {
     signal?: AbortSignal;

package/lib/cli-exec.js

@@ -8,6 +8,27 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { DEEPTUTOR_BIN, DEEPTUTOR_HOME, LOCAL_BIN, SSH_HOST } from "./config.js";
 import { resolveLocalCommand } from "./win-cmd.js";
+/**
+ * Upper bound for one CLI run's captured stdout/stderr.
+ *
+ * `deeptutor run --format json` writes one JSON line per streamed chunk, and a
+ * chunk is roughly one character of the answer once event metadata is included
+ * (~1.5 KB of JSON per output character measured on 1.7.1). A 1500-character
+ * answer is therefore ~2 MB, already past Node's 1 MB `execFile` default: the
+ * child is killed mid-turn and the only trace is a string `err.code`
+ * (`ERR_CHILD_PROCESS_STDIO_MAXBUFFER`) with empty stderr. 64 MB covers a
+ * ~40k-character answer, well beyond the CLI's own per-turn token ceiling.
+ */
+export const MAX_CLI_OUTPUT_BYTES = 64 * 1024 * 1024;
+/** Model-facing detail for a failed CLI run: stderr first, else the Node error code. */
+export function describeCliFailure(res) {
+    const stderr = (res.stderr ?? "").trim();
+    if (stderr)
+        return stderr;
+    if (res.error === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER")
+        return `output exceeded ${MAX_CLI_OUTPUT_BYTES} bytes (see MAX_CLI_OUTPUT_BYTES)`;
+    return res.error || "(no stderr)";
+}
 // Remote runner: reads argv from a JSON file and executes without a shell (avoids all quoting/escaping).
 const PY_RUNNER = [
     "import json, subprocess, sys",
@@ -48,14 +69,16 @@ const PY_NOTE = [
 const b64 = (s) => Buffer.from(s, "utf8").toString("base64");
 /** Timeout for each notebook-archiver CLI step (list / create / add-md). */
 const NOTE_STEP_TIMEOUT_MS = 30_000;
-/** Exec one command with optional abort + timeout, resolving instead of throwing. */
-function execFileResolved(file, args, opts = {}) {
+/** Exec one command with optional abort + timeout, resolving instead of throwing.
+ *  Exported for tests: the captured-output ceiling is part of the contract. */
+export function execFileResolved(file, args, opts = {}) {
     return new Promise((resolve) => {
         const child = execFile(file, args, {
             env: opts.env ? { ...process.env, ...opts.env } : process.env,
             windowsHide: true,
             windowsVerbatimArguments: opts.windowsVerbatimArguments,
             timeout: opts.timeoutMs,
+            maxBuffer: MAX_CLI_OUTPUT_BYTES,
         }, (err, stdout, stderr) => {
             const e = err;
             resolve({
@@ -63,6 +86,7 @@ function execFileResolved(file, args, opts = {}) {
                 stderr: stderr ?? "",
                 code: e ? (typeof e.code === "number" ? e.code : e.code === "ENOENT" ? 127 : 1) : 0,
                 killed: e?.killed ?? false,
+                error: e && typeof e.code === "string" ? String(e.code) : undefined,
             });
         });
         opts.signal?.addEventListener("abort", () => {
@@ -107,6 +131,7 @@ async function sshExec(argv, opts = {}) {
         stderr: (stderr ?? "").trim(),
         code: res.code ?? -1,
         killed: res.killed,
+        error: res.error,
     };
 }
 /**
@@ -131,12 +156,19 @@ export async function runCli(args, opts = {}) {
         windowsVerbatimArguments: cmd.windowsVerbatimArguments,
     });
     const out = res.stdout ?? "";
-    const [stdout, stderr] = out.split("__DT_STDERR__");
+    // Local mode is a direct execFile: the child's real stderr lands in res.stderr, and
+    // the __DT_STDERR__ marker only exists on the ssh path (the remote Python runner
+    // folds stderr into stdout). Splitting stdout still strips the marker if some wrapper
+    // emits one, but res.stderr must win — reading only the split tail threw away every
+    // Python traceback and reported "(no stderr)" for local runs (issue #20).
+    const [stdout, wrapped] = out.split("__DT_STDERR__");
+    const captured = (res.stderr ?? "").trim();
     return {
         stdout: stdout ?? "",
-        stderr: (stderr ?? "").trim(),
+        stderr: captured || (wrapped ?? "").trim(),
         code: res.code,
         killed: res.killed,
+        error: res.error,
     };
 }
 /** Local-deployment notebook archiver: list → parse ID → create → add-md */

package/lib/html-render.d.ts

@@ -1,5 +1,36 @@
-/** Absolute path to the bundled md-to-html converter script. */
+/** Absolute path to the bundled md-to-html converter (the last-resort fallback). */
 export declare const HTML_DOC_SCRIPT: string;
+/** dsh home: `$DSH_HOME`, else `~/.dsh` (mirrors scripts/install-profile.mjs). */
+export declare function dshHome(): string;
+export type Resolution = {
+    ok: true;
+    path: string;
+    source: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Resolve the converter: explicit `$HTML_DOC_SCRIPT`, the installed html-doc
+ * skill, then the package copy. A set-but-missing override is an error — a typo
+ * must not silently fall through to a different converter.
+ */
+export declare function resolveHtmlDocScript(): Resolution;
+/**
+ * Resolve the HTML template: explicit `$HTML_DOC_TEMPLATE`, the installed
+ * html-doc skill, then the package copy. A set-but-missing override is an error.
+ */
+export declare function resolveHtmlDocTemplate(): Resolution;
+/**
+ * Why `html` cannot be a relative path (null when it is acceptable).
+ *
+ * A tool has no workspace root: dsh hands `execute` only the agent identity
+ * (`exec.agent.id`) plus the call's signal, and the MCP server has no session at
+ * all, so a relative path could only resolve against the host process cwd — the
+ * dsh config directory, not the caller's project. Requiring an absolute path is
+ * the one contract that can never write somewhere unexpected.
+ */
+export declare function htmlTargetProblem(out: string): string | null;
 /**
  * Render a learning answer to a self-contained local HTML file (dark/light toggle,
  * TOC, collapsible quiz answers, print-friendly). Also writes the companion .md

package/lib/html-render.js

@@ -1,14 +1,113 @@
 /**
  * DeepTutor bridge: render a learning answer to a self-contained local HTML file
- * via the bundled zero-dependency Node converter (scripts/md-to-html.js, from
- * the html-doc skill). Kept as a standalone module (node built-ins only).
+ * via the zero-dependency Node converter (scripts/md-to-html.js, from the
+ * html-doc skill). Kept as a standalone module (node built-ins only).
+ *
+ * Two things are resolved at call time, first hit wins, and both are reported in
+ * the tool note so the order is visible without reading this file:
+ *
+ *   converter  $HTML_DOC_SCRIPT
+ *              → <DSH_HOME>/skills/html-doc/scripts/md-to-html.js (installed skill)
+ *              → the bundled package copy
+ *   template   $HTML_DOC_TEMPLATE
+ *              → <DSH_HOME>/skills/html-doc/assets/template.html (installed skill)
+ *              → the bundled package template
+ *
+ * <DSH_HOME> is `$DSH_HOME` or `~/.dsh` (same rule as scripts/install-profile.mjs),
+ * and `<DSH_HOME>/skills/<name>/` is where that installer copies the bundled
+ * skills for dsh auto-discovery. Preferring the installed copy means editing the
+ * installed html-doc template (say, wiring KaTeX in) changes `deeptutor_run`'s
+ * HTML immediately, instead of requiring edits to two files inside the plugin
+ * package that the next upgrade overwrites.
  */
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
-/** Absolute path to the bundled md-to-html converter script. */
-export const HTML_DOC_SCRIPT = join(fileURLToPath(new URL("..", import.meta.url)), "scripts", "md-to-html.js");
+const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
+/** Absolute path to the bundled md-to-html converter (the last-resort fallback). */
+export const HTML_DOC_SCRIPT = join(PKG_ROOT, "scripts", "md-to-html.js");
+/** Bundled html-doc template, shipped inside the package's copy of the skill. */
+const BUNDLED_TEMPLATE = join(PKG_ROOT, ".agents", "skills", "html-doc", "assets", "template.html");
+/** dsh home: `$DSH_HOME`, else `~/.dsh` (mirrors scripts/install-profile.mjs). */
+export function dshHome() {
+    return process.env.DSH_HOME?.trim() || join(homedir(), ".dsh");
+}
+/** `<DSH_HOME>/skills/html-doc/<segments…>` — the installer's auto-discovered skill. */
+function installedSkill(...segments) {
+    return join(dshHome(), "skills", "html-doc", ...segments);
+}
+/**
+ * Resolve the converter: explicit `$HTML_DOC_SCRIPT`, the installed html-doc
+ * skill, then the package copy. A set-but-missing override is an error — a typo
+ * must not silently fall through to a different converter.
+ */
+export function resolveHtmlDocScript() {
+    const explicit = process.env.HTML_DOC_SCRIPT?.trim();
+    if (explicit) {
+        return existsSync(explicit)
+            ? { ok: true, path: explicit, source: "HTML_DOC_SCRIPT" }
+            : { ok: false, error: `HTML_DOC_SCRIPT points at a missing file: ${explicit}` };
+    }
+    const installed = installedSkill("scripts", "md-to-html.js");
+    if (existsSync(installed))
+        return { ok: true, path: installed, source: "installed skill" };
+    if (existsSync(HTML_DOC_SCRIPT))
+        return { ok: true, path: HTML_DOC_SCRIPT, source: "bundled package" };
+    return {
+        ok: false,
+        error: `html-doc converter not found (looked in: HTML_DOC_SCRIPT, ${installed}, ${HTML_DOC_SCRIPT})`,
+    };
+}
+/**
+ * Resolve the HTML template: explicit `$HTML_DOC_TEMPLATE`, the installed
+ * html-doc skill, then the package copy. A set-but-missing override is an error.
+ */
+export function resolveHtmlDocTemplate() {
+    const explicit = process.env.HTML_DOC_TEMPLATE?.trim();
+    if (explicit) {
+        return existsSync(explicit)
+            ? { ok: true, path: explicit, source: "HTML_DOC_TEMPLATE" }
+            : { ok: false, error: `HTML_DOC_TEMPLATE points at a missing file: ${explicit}` };
+    }
+    const installed = installedSkill("assets", "template.html");
+    if (existsSync(installed))
+        return { ok: true, path: installed, source: "installed skill" };
+    if (existsSync(BUNDLED_TEMPLATE))
+        return { ok: true, path: BUNDLED_TEMPLATE, source: "bundled package" };
+    return {
+        ok: false,
+        error: `html-doc template not found (looked in: HTML_DOC_TEMPLATE, ${installed}, ${BUNDLED_TEMPLATE})`,
+    };
+}
+/**
+ * Why `html` cannot be a relative path (null when it is acceptable).
+ *
+ * A tool has no workspace root: dsh hands `execute` only the agent identity
+ * (`exec.agent.id`) plus the call's signal, and the MCP server has no session at
+ * all, so a relative path could only resolve against the host process cwd — the
+ * dsh config directory, not the caller's project. Requiring an absolute path is
+ * the one contract that can never write somewhere unexpected.
+ */
+export function htmlTargetProblem(out) {
+    if (isAbsolute(out.trim()))
+        return null;
+    return (`html must be an absolute path, got "${out}". Nothing was rendered: this tool cannot ` +
+        `resolve a relative path against your working directory (it has no workspace root, so a ` +
+        `relative path would land under the host process cwd instead). Prefix it with your working ` +
+        `directory, e.g. "<workspace>/data/study/topic/knowledge.html".`);
+}
+/**
+ * Extra CLI flag for the converter. The converter already picks up the template
+ * sitting next to it, so only pass `--template` when the resolved template is
+ * not that sibling — a plain bundled or installed run stays flag-free, and older
+ * converter copies that predate `--template` keep working on their own layout.
+ */
+function templateArgs(scriptPath, templatePath) {
+    const native = resolve(join(dirname(scriptPath), "..", "assets", "template.html"));
+    return native === resolve(templatePath) ? [] : ["--template", templatePath];
+}
 /**
  * Render a learning answer to a self-contained local HTML file (dark/light toggle,
  * TOC, collapsible quiz answers, print-friendly). Also writes the companion .md
@@ -21,19 +120,31 @@ export async function renderHtml(params, answer) {
     const out = params.html;
     if (!out)
         return "";
-    const htmlPath = extname(out).toLowerCase() === ".html" ? resolve(out) : resolve(out + ".html");
+    const problem = htmlTargetProblem(out);
+    if (problem)
+        return `\n[html] ✗ ${problem}`;
+    const target = out.trim();
+    const htmlPath = extname(target).toLowerCase() === ".html" ? resolve(target) : resolve(target + ".html");
     const mdPath = htmlPath.slice(0, -extname(htmlPath).length) + ".md";
     const title = params.html_title || basename(htmlPath, extname(htmlPath));
+    const script = resolveHtmlDocScript();
+    if (!script.ok)
+        return `\n[html] ✗ ${script.error}`;
+    const template = resolveHtmlDocTemplate();
+    if (!template.ok)
+        return `\n[html] ✗ ${template.error}`;
     try {
-        if (!existsSync(HTML_DOC_SCRIPT)) {
-            return `\n[html] ✗ html-doc converter not found: ${HTML_DOC_SCRIPT}`;
-        }
         mkdirSync(dirname(htmlPath), { recursive: true });
         writeFileSync(mdPath, answer || "(no answer)", "utf8");
+        const argv = [script.path, mdPath, "--out", htmlPath, "--title", title, "--toc"];
         await new Promise((res, rej) => {
-            execFile(process.execPath, [HTML_DOC_SCRIPT, mdPath, "--out", htmlPath, "--title", title, "--toc"], { windowsHide: true, timeout: 60_000 }, (err, _stdout, stderr) => (err ? rej(new Error(stderr || err.message)) : res()));
+            execFile(process.execPath, [...argv, ...templateArgs(script.path, template.path)], { windowsHide: true, timeout: 60_000 }, (err, _stdout, stderr) => (err ? rej(new Error(stderr || err.message)) : res()));
         });
-        return `\n[html] ✓ rendered (html-doc skill)\n[html]   page: ${htmlPath}\n[html]   source: ${mdPath}`;
+        return (`\n[html] ✓ rendered (html-doc skill)` +
+            `\n[html]   page: ${htmlPath}` +
+            `\n[html]   source: ${mdPath}` +
+            `\n[html]   converter: ${script.path} (${script.source})` +
+            `\n[html]   template: ${template.path} (${template.source})`);
     }
     catch (err) {
         return `\n[html] ✗ rendering failed: ${err?.message ?? String(err)}`;

package/lib/index.js

@@ -1,5 +1,5 @@
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { HTML_DOC_SCRIPT } from "./html-render.js";
+import { resolveHtmlDocScript } from "./html-render.js";
 import { TOOLS } from "./tools.js";
 export const name = "dsh-deeptutor";
 export const inject = ["tools"];
@@ -20,7 +20,8 @@ const OUTPUT = {
     render: (_args, value) => [{ type: "text", text: value.text ?? "" }],
 };
 export function apply(ctx) {
-    console.log(`[dsh-deeptutor] plugin loaded (html script: ${HTML_DOC_SCRIPT})`);
+    const converter = resolveHtmlDocScript();
+    console.log(`[dsh-deeptutor] plugin loaded (html-doc converter: ${converter.ok ? `${converter.path} (${converter.source})` : converter.error})`);
     for (const tool of TOOLS) {
         ctx.tools.register(defineTool({
             name: tool.name,

package/lib/tools.js

@@ -20,7 +20,7 @@ import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.js";
 import { classifyCliArgs } from "./cli-policy.js";
 import { configGuide, configHint, SSH_HOST, truncate } from "./config.js";
 import { describeCapabilities, discoverCapabilities } from "./discovery.js";
-import { renderHtml } from "./html-render.js";
+import { renderHtml, htmlTargetProblem } from "./html-render.js";
 import { cliRunTurn, fmtTurnResult } from "./turn.js";
 /** Plain JSON Schema (object) for one tool's parameters. Pure. */
 export function toJsonSchema(params) {
@@ -95,11 +95,16 @@ const runTool = {
         max_chars: { type: "number", description: "Max characters of the answer returned, default 30000" },
         html: {
             type: "string",
-            description: "Optional output path for a self-contained local HTML render of the answer (also writes the companion .md next to it), e.g. data/study/abstract-class/knowledge.html. Relative paths resolve against the agent's working directory. Set it when the user wants browsable/printable study material.",
+            description: "Optional absolute output path for a self-contained local HTML render of the answer (also writes the companion .md next to it), e.g. /home/me/study/abstract-class/knowledge.html. Must be absolute: this tool has no workspace root, so relative paths are rejected instead of silently landing under the host process cwd. The template comes from the installed html-doc skill when present ($HTML_DOC_TEMPLATE overrides it); see SKILL.md. Set it when the user wants browsable/printable study material.",
         },
         html_title: { type: "string", description: "HTML page title (default: derived from the html file name)" },
     },
     async execute(args, signal) {
+        // Fail before the (possibly minutes-long) DeepTutor turn: a relative html
+        // path cannot be resolved against the caller's workspace, so reject it here.
+        const htmlProblem = args.html ? htmlTargetProblem(String(args.html)) : null;
+        if (htmlProblem)
+            throw new Error(`[deeptutor_run] ${htmlProblem}`);
         const timeoutMs = (args.timeout ?? 600) * 1000;
         const maxChars = args.max_chars ?? 30000;
         const capability = String(args.capability).trim();

package/lib/turn.js

@@ -3,7 +3,7 @@
  * (local or over SSH), JSONL event parsing and result formatting.
  */
 import { truncate } from "./config.js";
-import { runCli } from "./cli-exec.js";
+import { describeCliFailure, runCli } from "./cli-exec.js";
 /** Fold one CLI JSONL event into the running turn state. Exported for unit tests. */
 export function collectEvent(state, e) {
     if (e.type === "content" && typeof e.content === "string")
@@ -49,14 +49,17 @@ export function buildRunArgs(params) {
 }
 /** Execute one turn via the CLI (local or SSH). `run` is injectable for tests. */
 export async function cliRunTurn(params, timeoutMs, signal, run = runCli) {
-    const { stdout, stderr, code, killed } = await run(buildRunArgs(params), { signal, timeoutMs });
+    const { stdout, stderr, code, killed, error } = await run(buildRunArgs(params), {
+        signal,
+        timeoutMs,
+    });
     if (killed) {
         // A kill can come from the user cancelling (signal) or from the timeout;
         // report the real reason instead of always blaming the timeout.
         throw new Error(signal?.aborted ? "Aborted" : `CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`);
     }
     if (code !== 0)
-        throw new Error(`CLI exit=${code}: ${stderr || "(no stderr)"}`);
+        throw new Error(`CLI exit=${code}: ${describeCliFailure({ stderr, error })}`);
     const state = { answer: "", errors: [], toolCalls: [] };
     for (const line of stdout.split("\n")) {
         if (!line.trim())

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-deeptutor",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "description": "Learning assistant extension for DeepSeek Harness (dsh) and Claude Code (MCP): DeepTutor tutoring for your agent: deep explanations, self-test questions, learning paths, personal knowledge-base search (RAG), note archiving, and any other DeepTutor CLI command (drives the DeepTutor CLI locally or over SSH).",
   "keywords": [
     "dsh",

package/scripts/mcp-launch.mjs

@@ -1,7 +1,10 @@
 #!/usr/bin/env node
 /**
  * Launcher for the DeepTutor MCP server, used by the Claude Code plugin
- * (.mcp.json → `node ${CLAUDE_PLUGIN_ROOT}/scripts/mcp-launch.mjs`).
+ * (`mcpServers` in .claude-plugin/plugin.json → `node ${CLAUDE_PLUGIN_ROOT}/scripts/mcp-launch.mjs`).
+ * The config lives in plugin.json, not a root .mcp.json: Claude Code also reads
+ * a root .mcp.json as project-scope config whenever this repo is the working
+ * directory, where ${CLAUDE_PLUGIN_ROOT} is undefined.
  *
  * A plugin installed from the marketplace is a plain git checkout: it has the
  * TypeScript sources but no compiled lib/ and no node_modules. The server has no

package/scripts/md-to-html.js

@@ -4,9 +4,12 @@
  *
  * Usage:
  *   node md-to-html.js <input.md> [--out out.html] [--title "T"] [--theme dark|light]
- *                      [--toc] [--lang zh-CN] [--no-collapse]
+ *                      [--toc] [--lang zh-CN] [--no-collapse] [--template template.html]
  *   cat file.md | node md-to-html.js --title "T" --out out.html
  *
+ * Template resolution order: --template, $HTML_DOC_TEMPLATE, the assets/ copy
+ * next to this script, then the package-root duplicate's skill copy.
+ *
  * Features: headings, fenced code blocks, inline code/bold/italic/links, lists,
  * task lists, blockquotes, pipe tables, hr, quiz answer collapsing (<details>),
  * raw HTML passthrough, HTML escaping. Zero npm dependencies (Node >= 20.11 — uses import.meta.dirname).
@@ -27,9 +30,10 @@ function parseArgs(argv) {
     toc: false,
     lang: "zh-CN",
     collapse: true,
+    template: null,
   };
   const positional = [];
-  const valueFlags = new Set(["--out", "--title", "--theme", "--lang"]);
+  const valueFlags = new Set(["--out", "--title", "--theme", "--lang", "--template"]);
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === "--toc") opts.toc = true;
@@ -50,7 +54,11 @@ function parseArgs(argv) {
           fail(`Invalid --theme value "${value}": expected dark or light`);
         }
         opts.theme = value;
-      } else if (a === "--lang") opts.lang = value;
+      } else if (a === "--lang") {
+        opts.lang = value;
+      } else if (a === "--template") {
+        opts.template = value;
+      }
     } else if (a.startsWith("--")) {
       fail(`Unknown option: ${a} (run with --help for usage)`);
     } else positional.push(a);
@@ -77,6 +85,8 @@ Options:
   --theme <mode>   dark | light (default: light; toggle also available in page)
   --toc            generate a table of contents from h2/h3 headings
   --lang <code>    html lang attribute (default: zh-CN)
+  --template <file> HTML template to use (default: the assets/ copy next to this
+                   script, or $HTML_DOC_TEMPLATE when set)
   --no-collapse    disable quiz-answer collapsing
   --help           show this help`);
 }
@@ -351,11 +361,25 @@ function main() {
   const generated = new Date().toISOString().slice(0, 10);
   // The same converter ships in two locations (.agents/skills/html-doc/scripts/
   // and a package-root scripts/ copy); resolve the template wherever we are.
+  // Order: --template, $HTML_DOC_TEMPLATE, then the copies next to this script.
+  // An explicit override that does not exist is an error: a typo must not
+  // silently fall through to a different template.
+  const explicitTemplate = opts.template || process.env.HTML_DOC_TEMPLATE || null;
   const templateCandidates = [
     path.join(import.meta.dirname, "..", "assets", "template.html"),
     path.join(import.meta.dirname, "..", ".agents", "skills", "html-doc", "assets", "template.html"),
   ];
-  const templatePath = templateCandidates.find((p) => fs.existsSync(p));
+  let templatePath;
+  if (explicitTemplate) {
+    if (!fs.existsSync(explicitTemplate)) {
+      fail(
+        `template not found: ${explicitTemplate} (from ${opts.template ? "--template" : "HTML_DOC_TEMPLATE"})`,
+      );
+    }
+    templatePath = explicitTemplate;
+  } else {
+    templatePath = templateCandidates.find((p) => fs.existsSync(p));
+  }
   if (!templatePath) {
     fail(`template.html not found (looked in: ${templateCandidates.join(", ")})`);
   }
@@ -380,7 +404,7 @@ function main() {
   if (opts.out) {
     fs.writeFileSync(opts.out, template, "utf8");
     console.log(
-      `[html-doc] wrote ${path.resolve(opts.out)} (${Buffer.byteLength(template)} bytes)`,
+      `[html-doc] wrote ${path.resolve(opts.out)} (${Buffer.byteLength(template)} bytes, template: ${templatePath})`,
     );
   } else {
     process.stdout.write(template);

package/src/cli-exec.ts

@@ -9,11 +9,35 @@ import { join } from "node:path";
 import { DEEPTUTOR_BIN, DEEPTUTOR_HOME, LOCAL_BIN, SSH_HOST } from "./config.ts";
 import { resolveLocalCommand } from "./win-cmd.ts";
 
+/**
+ * Upper bound for one CLI run's captured stdout/stderr.
+ *
+ * `deeptutor run --format json` writes one JSON line per streamed chunk, and a
+ * chunk is roughly one character of the answer once event metadata is included
+ * (~1.5 KB of JSON per output character measured on 1.7.1). A 1500-character
+ * answer is therefore ~2 MB, already past Node's 1 MB `execFile` default: the
+ * child is killed mid-turn and the only trace is a string `err.code`
+ * (`ERR_CHILD_PROCESS_STDIO_MAXBUFFER`) with empty stderr. 64 MB covers a
+ * ~40k-character answer, well beyond the CLI's own per-turn token ceiling.
+ */
+export const MAX_CLI_OUTPUT_BYTES = 64 * 1024 * 1024;
+
 export interface CliResult {
   stdout: string;
   stderr: string;
   code: number;
   killed: boolean;
+  /** Node-level failure code, kept when stderr is empty so callers can report it. */
+  error?: string;
+}
+
+/** Model-facing detail for a failed CLI run: stderr first, else the Node error code. */
+export function describeCliFailure(res: Pick<CliResult, "stderr" | "error">): string {
+  const stderr = (res.stderr ?? "").trim();
+  if (stderr) return stderr;
+  if (res.error === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER")
+    return `output exceeded ${MAX_CLI_OUTPUT_BYTES} bytes (see MAX_CLI_OUTPUT_BYTES)`;
+  return res.error || "(no stderr)";
 }
 
 // Remote runner: reads argv from a JSON file and executes without a shell (avoids all quoting/escaping).
@@ -60,8 +84,9 @@ const b64 = (s: string) => Buffer.from(s, "utf8").toString("base64");
 /** Timeout for each notebook-archiver CLI step (list / create / add-md). */
 const NOTE_STEP_TIMEOUT_MS = 30_000;
 
-/** Exec one command with optional abort + timeout, resolving instead of throwing. */
-function execFileResolved(
+/** Exec one command with optional abort + timeout, resolving instead of throwing.
+ *  Exported for tests: the captured-output ceiling is part of the contract. */
+export function execFileResolved(
   file: string,
   args: string[],
   opts: {
@@ -80,6 +105,7 @@ function execFileResolved(
         windowsHide: true,
         windowsVerbatimArguments: opts.windowsVerbatimArguments,
         timeout: opts.timeoutMs,
+        maxBuffer: MAX_CLI_OUTPUT_BYTES,
       },
       (err, stdout, stderr) => {
         const e: any = err;
@@ -88,6 +114,7 @@ function execFileResolved(
           stderr: stderr ?? "",
           code: e ? (typeof e.code === "number" ? e.code : e.code === "ENOENT" ? 127 : 1) : 0,
           killed: e?.killed ?? false,
+          error: e && typeof e.code === "string" ? String(e.code) : undefined,
         });
       },
     );
@@ -151,6 +178,7 @@ async function sshExec(argv: string[], opts: CliOptions = {}): Promise<CliResult
     stderr: (stderr ?? "").trim(),
     code: res.code ?? -1,
     killed: res.killed,
+    error: res.error,
   };
 }
 
@@ -175,12 +203,19 @@ export async function runCli(args: string[], opts: CliOptions = {}): Promise<Cli
     windowsVerbatimArguments: cmd.windowsVerbatimArguments,
   });
   const out = res.stdout ?? "";
-  const [stdout, stderr] = out.split("__DT_STDERR__");
+  // Local mode is a direct execFile: the child's real stderr lands in res.stderr, and
+  // the __DT_STDERR__ marker only exists on the ssh path (the remote Python runner
+  // folds stderr into stdout). Splitting stdout still strips the marker if some wrapper
+  // emits one, but res.stderr must win — reading only the split tail threw away every
+  // Python traceback and reported "(no stderr)" for local runs (issue #20).
+  const [stdout, wrapped] = out.split("__DT_STDERR__");
+  const captured = (res.stderr ?? "").trim();
   return {
     stdout: stdout ?? "",
-    stderr: (stderr ?? "").trim(),
+    stderr: captured || (wrapped ?? "").trim(),
     code: res.code,
     killed: res.killed,
+    error: res.error,
   };
 }
 

package/src/html-render.ts

@@ -1,19 +1,123 @@
 /**
  * DeepTutor bridge: render a learning answer to a self-contained local HTML file
- * via the bundled zero-dependency Node converter (scripts/md-to-html.js, from
- * the html-doc skill). Kept as a standalone module (node built-ins only).
+ * via the zero-dependency Node converter (scripts/md-to-html.js, from the
+ * html-doc skill). Kept as a standalone module (node built-ins only).
+ *
+ * Two things are resolved at call time, first hit wins, and both are reported in
+ * the tool note so the order is visible without reading this file:
+ *
+ *   converter  $HTML_DOC_SCRIPT
+ *              → <DSH_HOME>/skills/html-doc/scripts/md-to-html.js (installed skill)
+ *              → the bundled package copy
+ *   template   $HTML_DOC_TEMPLATE
+ *              → <DSH_HOME>/skills/html-doc/assets/template.html (installed skill)
+ *              → the bundled package template
+ *
+ * <DSH_HOME> is `$DSH_HOME` or `~/.dsh` (same rule as scripts/install-profile.mjs),
+ * and `<DSH_HOME>/skills/<name>/` is where that installer copies the bundled
+ * skills for dsh auto-discovery. Preferring the installed copy means editing the
+ * installed html-doc template (say, wiring KaTeX in) changes `deeptutor_run`'s
+ * HTML immediately, instead of requiring edits to two files inside the plugin
+ * package that the next upgrade overwrites.
  */
 import { execFile } from "node:child_process";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { basename, dirname, extname, isAbsolute, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Absolute path to the bundled md-to-html converter script. */
-export const HTML_DOC_SCRIPT = join(
-  fileURLToPath(new URL("..", import.meta.url)),
-  "scripts",
-  "md-to-html.js",
-);
+const PKG_ROOT = fileURLToPath(new URL("..", import.meta.url));
+
+/** Absolute path to the bundled md-to-html converter (the last-resort fallback). */
+export const HTML_DOC_SCRIPT = join(PKG_ROOT, "scripts", "md-to-html.js");
+
+/** Bundled html-doc template, shipped inside the package's copy of the skill. */
+const BUNDLED_TEMPLATE = join(PKG_ROOT, ".agents", "skills", "html-doc", "assets", "template.html");
+
+/** dsh home: `$DSH_HOME`, else `~/.dsh` (mirrors scripts/install-profile.mjs). */
+export function dshHome(): string {
+  return process.env.DSH_HOME?.trim() || join(homedir(), ".dsh");
+}
+
+/** `<DSH_HOME>/skills/html-doc/<segments…>` — the installer's auto-discovered skill. */
+function installedSkill(...segments: string[]): string {
+  return join(dshHome(), "skills", "html-doc", ...segments);
+}
+
+export type Resolution =
+  | { ok: true; path: string; source: string }
+  | { ok: false; error: string };
+
+/**
+ * Resolve the converter: explicit `$HTML_DOC_SCRIPT`, the installed html-doc
+ * skill, then the package copy. A set-but-missing override is an error — a typo
+ * must not silently fall through to a different converter.
+ */
+export function resolveHtmlDocScript(): Resolution {
+  const explicit = process.env.HTML_DOC_SCRIPT?.trim();
+  if (explicit) {
+    return existsSync(explicit)
+      ? { ok: true, path: explicit, source: "HTML_DOC_SCRIPT" }
+      : { ok: false, error: `HTML_DOC_SCRIPT points at a missing file: ${explicit}` };
+  }
+  const installed = installedSkill("scripts", "md-to-html.js");
+  if (existsSync(installed)) return { ok: true, path: installed, source: "installed skill" };
+  if (existsSync(HTML_DOC_SCRIPT)) return { ok: true, path: HTML_DOC_SCRIPT, source: "bundled package" };
+  return {
+    ok: false,
+    error: `html-doc converter not found (looked in: HTML_DOC_SCRIPT, ${installed}, ${HTML_DOC_SCRIPT})`,
+  };
+}
+
+/**
+ * Resolve the HTML template: explicit `$HTML_DOC_TEMPLATE`, the installed
+ * html-doc skill, then the package copy. A set-but-missing override is an error.
+ */
+export function resolveHtmlDocTemplate(): Resolution {
+  const explicit = process.env.HTML_DOC_TEMPLATE?.trim();
+  if (explicit) {
+    return existsSync(explicit)
+      ? { ok: true, path: explicit, source: "HTML_DOC_TEMPLATE" }
+      : { ok: false, error: `HTML_DOC_TEMPLATE points at a missing file: ${explicit}` };
+  }
+  const installed = installedSkill("assets", "template.html");
+  if (existsSync(installed)) return { ok: true, path: installed, source: "installed skill" };
+  if (existsSync(BUNDLED_TEMPLATE)) return { ok: true, path: BUNDLED_TEMPLATE, source: "bundled package" };
+  return {
+    ok: false,
+    error: `html-doc template not found (looked in: HTML_DOC_TEMPLATE, ${installed}, ${BUNDLED_TEMPLATE})`,
+  };
+}
+
+/**
+ * Why `html` cannot be a relative path (null when it is acceptable).
+ *
+ * A tool has no workspace root: dsh hands `execute` only the agent identity
+ * (`exec.agent.id`) plus the call's signal, and the MCP server has no session at
+ * all, so a relative path could only resolve against the host process cwd — the
+ * dsh config directory, not the caller's project. Requiring an absolute path is
+ * the one contract that can never write somewhere unexpected.
+ */
+export function htmlTargetProblem(out: string): string | null {
+  if (isAbsolute(out.trim())) return null;
+  return (
+    `html must be an absolute path, got "${out}". Nothing was rendered: this tool cannot ` +
+    `resolve a relative path against your working directory (it has no workspace root, so a ` +
+    `relative path would land under the host process cwd instead). Prefix it with your working ` +
+    `directory, e.g. "<workspace>/data/study/topic/knowledge.html".`
+  );
+}
+
+/**
+ * Extra CLI flag for the converter. The converter already picks up the template
+ * sitting next to it, so only pass `--template` when the resolved template is
+ * not that sibling — a plain bundled or installed run stays flag-free, and older
+ * converter copies that predate `--template` keep working on their own layout.
+ */
+function templateArgs(scriptPath: string, templatePath: string): string[] {
+  const native = resolve(join(dirname(scriptPath), "..", "assets", "template.html"));
+  return native === resolve(templatePath) ? [] : ["--template", templatePath];
+}
 
 /**
  * Render a learning answer to a self-contained local HTML file (dark/light toggle,
@@ -29,24 +133,36 @@ export async function renderHtml(
 ): Promise<string> {
   const out = params.html;
   if (!out) return "";
-  const htmlPath = extname(out).toLowerCase() === ".html" ? resolve(out) : resolve(out + ".html");
+  const problem = htmlTargetProblem(out);
+  if (problem) return `\n[html] ✗ ${problem}`;
+  const target = out.trim();
+  const htmlPath =
+    extname(target).toLowerCase() === ".html" ? resolve(target) : resolve(target + ".html");
   const mdPath = htmlPath.slice(0, -extname(htmlPath).length) + ".md";
   const title = params.html_title || basename(htmlPath, extname(htmlPath));
+  const script = resolveHtmlDocScript();
+  if (!script.ok) return `\n[html] ✗ ${script.error}`;
+  const template = resolveHtmlDocTemplate();
+  if (!template.ok) return `\n[html] ✗ ${template.error}`;
   try {
-    if (!existsSync(HTML_DOC_SCRIPT)) {
-      return `\n[html] ✗ html-doc converter not found: ${HTML_DOC_SCRIPT}`;
-    }
     mkdirSync(dirname(htmlPath), { recursive: true });
     writeFileSync(mdPath, answer || "(no answer)", "utf8");
+    const argv = [script.path, mdPath, "--out", htmlPath, "--title", title, "--toc"];
     await new Promise<void>((res, rej) => {
       execFile(
         process.execPath,
-        [HTML_DOC_SCRIPT, mdPath, "--out", htmlPath, "--title", title, "--toc"],
+        [...argv, ...templateArgs(script.path, template.path)],
         { windowsHide: true, timeout: 60_000 },
         (err, _stdout, stderr) => (err ? rej(new Error(stderr || err.message)) : res()),
       );
     });
-    return `\n[html] ✓ rendered (html-doc skill)\n[html]   page: ${htmlPath}\n[html]   source: ${mdPath}`;
+    return (
+      `\n[html] ✓ rendered (html-doc skill)` +
+      `\n[html]   page: ${htmlPath}` +
+      `\n[html]   source: ${mdPath}` +
+      `\n[html]   converter: ${script.path} (${script.source})` +
+      `\n[html]   template: ${template.path} (${template.source})`
+    );
   } catch (err: any) {
     return `\n[html] ✗ rendering failed: ${err?.message ?? String(err)}`;
   }

package/src/index.ts

@@ -19,7 +19,7 @@
  */
 import type { Context } from "@deepseek-ai/cordis";
 import { defineTool } from "@deepseek-ai/dsh-tools";
-import { HTML_DOC_SCRIPT } from "./html-render.ts";
+import { resolveHtmlDocScript } from "./html-render.ts";
 import { TOOLS } from "./tools.ts";
 
 export const name = "dsh-deeptutor";
@@ -42,7 +42,10 @@ const OUTPUT = {
 } as const;
 
 export function apply(ctx: Context) {
-  console.log(`[dsh-deeptutor] plugin loaded (html script: ${HTML_DOC_SCRIPT})`);
+  const converter = resolveHtmlDocScript();
+  console.log(
+    `[dsh-deeptutor] plugin loaded (html-doc converter: ${converter.ok ? `${converter.path} (${converter.source})` : converter.error})`,
+  );
   for (const tool of TOOLS) {
     ctx.tools.register(
       defineTool({

package/src/tools.ts

@@ -20,7 +20,7 @@ import { cliNoteLocal, cliNoteRemote, runCli } from "./cli-exec.ts";
 import { classifyCliArgs } from "./cli-policy.ts";
 import { configGuide, configHint, SSH_HOST, truncate } from "./config.ts";
 import { describeCapabilities, discoverCapabilities } from "./discovery.ts";
-import { renderHtml } from "./html-render.ts";
+import { renderHtml, htmlTargetProblem } from "./html-render.ts";
 import { cliRunTurn, fmtTurnResult } from "./turn.ts";
 
 interface Base {
@@ -134,11 +134,15 @@ const runTool: ToolSpec = {
     html: {
       type: "string",
       description:
-        "Optional output path for a self-contained local HTML render of the answer (also writes the companion .md next to it), e.g. data/study/abstract-class/knowledge.html. Relative paths resolve against the agent's working directory. Set it when the user wants browsable/printable study material.",
+        "Optional absolute output path for a self-contained local HTML render of the answer (also writes the companion .md next to it), e.g. /home/me/study/abstract-class/knowledge.html. Must be absolute: this tool has no workspace root, so relative paths are rejected instead of silently landing under the host process cwd. The template comes from the installed html-doc skill when present ($HTML_DOC_TEMPLATE overrides it); see SKILL.md. Set it when the user wants browsable/printable study material.",
     },
     html_title: { type: "string", description: "HTML page title (default: derived from the html file name)" },
   },
   async execute(args, signal) {
+    // Fail before the (possibly minutes-long) DeepTutor turn: a relative html
+    // path cannot be resolved against the caller's workspace, so reject it here.
+    const htmlProblem = args.html ? htmlTargetProblem(String(args.html)) : null;
+    if (htmlProblem) throw new Error(`[deeptutor_run] ${htmlProblem}`);
     const timeoutMs = (args.timeout ?? 600) * 1000;
     const maxChars = args.max_chars ?? 30000;
     const capability = String(args.capability).trim();

package/src/turn.ts

@@ -3,7 +3,7 @@
  * (local or over SSH), JSONL event parsing and result formatting.
  */
 import { truncate } from "./config.ts";
-import { runCli } from "./cli-exec.ts";
+import { describeCliFailure, runCli } from "./cli-exec.ts";
 
 export interface TurnResult {
   answer: string;
@@ -69,7 +69,10 @@ export async function cliRunTurn(
   signal?: AbortSignal,
   run: typeof runCli = runCli,
 ): Promise<TurnResult> {
-  const { stdout, stderr, code, killed } = await run(buildRunArgs(params), { signal, timeoutMs });
+  const { stdout, stderr, code, killed, error } = await run(buildRunArgs(params), {
+    signal,
+    timeoutMs,
+  });
   if (killed) {
     // A kill can come from the user cancelling (signal) or from the timeout;
     // report the real reason instead of always blaming the timeout.
@@ -77,7 +80,7 @@ export async function cliRunTurn(
       signal?.aborted ? "Aborted" : `CLI execution timed out (${Math.round(timeoutMs / 1000)}s)`,
     );
   }
-  if (code !== 0) throw new Error(`CLI exit=${code}: ${stderr || "(no stderr)"}`);
+  if (code !== 0) throw new Error(`CLI exit=${code}: ${describeCliFailure({ stderr, error })}`);
   const state: TurnResult = { answer: "", errors: [], toolCalls: [] };
   for (const line of stdout.split("\n")) {
     if (!line.trim()) continue;