@taloswork/ose-shared 0.1.15 → 0.1.17

package/skills/document/bin/pdf-render.cjs

@@ -3,7 +3,7 @@
 
 // apps/admin/data/skills.lib/document/bin-src/pdf-render.mjs
 var import_promises = require("node:fs/promises");
-var import_node_path2 = require("node:path");
+var import_node_path3 = require("node:path");
 
 // packages/core/dist/document/pdf-extract.js
 var import_node_path = require("node:path");
@@ -33,9 +33,15 @@ function loadMupdf() {
   }
   return _mupdf;
 }
+function openPdf(mupdf, bytes) {
+  const doc = mupdf.Document.openDocument(bytes, "application/pdf").asPDF();
+  if (!doc)
+    throw new Error("not a PDF document");
+  return doc;
+}
 async function openDoc(bytes) {
   const mupdf = await loadMupdf();
-  const doc = mupdf.Document.openDocument(bytes, "application/pdf");
+  const doc = openPdf(mupdf, bytes);
   if (doc.needsPassword())
     throw new PdfEncryptedError();
   if (doc.countPages() === 0) {
@@ -61,6 +67,17 @@ async function renderPdfPages(bytes, pages, scale = 2, maxEdge) {
   return out;
 }
 
+// apps/admin/data/skills.lib/document/bin-src/lib/derived-path.mjs
+var import_node_path2 = require("node:path");
+var SCRATCH_ENV = "TALOS_SCRATCH_DIR";
+function derivedDir(source, env = process.env) {
+  const scratch = env[SCRATCH_ENV];
+  return scratch ? (0, import_node_path2.join)(scratch, "derived") : (0, import_node_path2.dirname)((0, import_node_path2.resolve)(source));
+}
+function derivedPath(source, name, env = process.env) {
+  return (0, import_node_path2.join)(derivedDir(source, env), name);
+}
+
 // apps/admin/data/skills.lib/document/bin-src/pdf-render.mjs
 function die(msg, code = 1) {
   process.stderr.write(`pdf-render: ${msg}
@@ -104,8 +121,9 @@ async function main() {
   }
   if (!rendered.length) die("no pages rendered (range out of bounds?)", 64);
   const out = [];
+  await (0, import_promises.mkdir)(derivedDir(file), { recursive: true });
   for (const r of rendered) {
-    const dest = (0, import_node_path2.join)((0, import_node_path2.dirname)(file), `${(0, import_node_path2.basename)(file).replace(/\.[^.]+$/, "")}_p${r.page}.png`);
+    const dest = derivedPath(file, `${(0, import_node_path3.basename)(file).replace(/\.[^.]+$/, "")}_p${r.page}.png`);
     await (0, import_promises.writeFile)(dest, Buffer.from(r.png));
     out.push({ page: r.page, path: dest });
   }

package/skills/document/bin/pdf-tables.cjs

@@ -33,9 +33,15 @@ function loadMupdf() {
   }
   return _mupdf;
 }
+function openPdf(mupdf, bytes) {
+  const doc = mupdf.Document.openDocument(bytes, "application/pdf").asPDF();
+  if (!doc)
+    throw new Error("not a PDF document");
+  return doc;
+}
 async function openDoc(bytes) {
   const mupdf = await loadMupdf();
-  const doc = mupdf.Document.openDocument(bytes, "application/pdf");
+  const doc = openPdf(mupdf, bytes);
   if (doc.needsPassword())
     throw new PdfEncryptedError();
   if (doc.countPages() === 0) {

package/skills/document/bin/pptx-clone.cjs

@@ -10000,10 +10000,7 @@ function capacityWarning(slideXml, token, value) {
     return void 0;
   return `${token}: replacement is ~${Math.ceil(width)} width-units, slot fits ~${Math.floor(capacity)} (${Math.round(widthPt)}\xD7${Math.round(heightPt)}pt box @ ${fontPt}pt) \u2014 likely overflow. Shorten the wording; do NOT shrink the font to make it fit.`;
 }
-async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
-  if (!Number.isInteger(slideNumber) || slideNumber < 1) {
-    throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
-  }
+async function openDeckAtSlide(bytes, slideNumber) {
   let zip;
   try {
     zip = await import_jszip.default.loadAsync(Buffer.from(bytes));
@@ -10016,6 +10013,13 @@ async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
   if (!slideNums.includes(slideNumber)) {
     throw new Error(`slide ${slideNumber} does not exist (deck has slides ${Math.min(...slideNums)}\u2013${Math.max(...slideNums)})`);
   }
+  return { zip, slideNums };
+}
+async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
+  if (!Number.isInteger(slideNumber) || slideNumber < 1) {
+    throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
+  }
+  const { zip, slideNums } = await openDeckAtSlide(bytes, slideNumber);
   const newNum = Math.max(...slideNums) + 1;
   const srcXmlPath = `ppt/slides/slide${slideNumber}.xml`;
   const newXmlPath = `ppt/slides/slide${newNum}.xml`;
@@ -10055,18 +10059,7 @@ async function removePptxSlide(bytes, slideNumber) {
   if (!Number.isInteger(slideNumber) || slideNumber < 1) {
     throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
   }
-  let zip;
-  try {
-    zip = await import_jszip.default.loadAsync(Buffer.from(bytes));
-  } catch (e) {
-    throw new Error(`not a readable .pptx: ${e.message}`);
-  }
-  const slideNums = Object.keys(zip.files).map((p) => /^ppt\/slides\/slide(\d+)\.xml$/.exec(p)?.[1]).filter((n) => Boolean(n)).map(Number);
-  if (!slideNums.length)
-    throw new Error("not a PowerPoint file (no slides found)");
-  if (!slideNums.includes(slideNumber)) {
-    throw new Error(`slide ${slideNumber} does not exist (deck has slides ${Math.min(...slideNums)}\u2013${Math.max(...slideNums)})`);
-  }
+  const { zip, slideNums } = await openDeckAtSlide(bytes, slideNumber);
   if (slideNums.length === 1)
     throw new Error("cannot remove the only slide in the deck");
   const xmlPath = `ppt/slides/slide${slideNumber}.xml`;

package/skills/document/bin/pptx-slide.cjs

@@ -10084,10 +10084,7 @@ function capacityWarning(slideXml, token, value) {
     return void 0;
   return `${token}: replacement is ~${Math.ceil(width)} width-units, slot fits ~${Math.floor(capacity)} (${Math.round(widthPt)}\xD7${Math.round(heightPt)}pt box @ ${fontPt}pt) \u2014 likely overflow. Shorten the wording; do NOT shrink the font to make it fit.`;
 }
-async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
-  if (!Number.isInteger(slideNumber) || slideNumber < 1) {
-    throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
-  }
+async function openDeckAtSlide(bytes, slideNumber) {
   let zip;
   try {
     zip = await import_jszip2.default.loadAsync(Buffer.from(bytes));
@@ -10100,6 +10097,13 @@ async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
   if (!slideNums.includes(slideNumber)) {
     throw new Error(`slide ${slideNumber} does not exist (deck has slides ${Math.min(...slideNums)}\u2013${Math.max(...slideNums)})`);
   }
+  return { zip, slideNums };
+}
+async function clonePptxSlide(bytes, slideNumber, replacements = {}) {
+  if (!Number.isInteger(slideNumber) || slideNumber < 1) {
+    throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
+  }
+  const { zip, slideNums } = await openDeckAtSlide(bytes, slideNumber);
   const newNum = Math.max(...slideNums) + 1;
   const srcXmlPath = `ppt/slides/slide${slideNumber}.xml`;
   const newXmlPath = `ppt/slides/slide${newNum}.xml`;
@@ -10139,18 +10143,7 @@ async function removePptxSlide(bytes, slideNumber) {
   if (!Number.isInteger(slideNumber) || slideNumber < 1) {
     throw new Error(`slide number must be a positive integer, got ${slideNumber}`);
   }
-  let zip;
-  try {
-    zip = await import_jszip2.default.loadAsync(Buffer.from(bytes));
-  } catch (e) {
-    throw new Error(`not a readable .pptx: ${e.message}`);
-  }
-  const slideNums = Object.keys(zip.files).map((p) => /^ppt\/slides\/slide(\d+)\.xml$/.exec(p)?.[1]).filter((n) => Boolean(n)).map(Number);
-  if (!slideNums.length)
-    throw new Error("not a PowerPoint file (no slides found)");
-  if (!slideNums.includes(slideNumber)) {
-    throw new Error(`slide ${slideNumber} does not exist (deck has slides ${Math.min(...slideNums)}\u2013${Math.max(...slideNums)})`);
-  }
+  const { zip, slideNums } = await openDeckAtSlide(bytes, slideNumber);
   if (slideNums.length === 1)
     throw new Error("cannot remove the only slide in the deck");
   const xmlPath = `ppt/slides/slide${slideNumber}.xml`;

package/skills/document/bin/template-skin.cjs

@@ -10642,9 +10642,15 @@ function loadMupdf() {
   }
   return _mupdf;
 }
+function openPdf(mupdf, bytes) {
+  const doc = mupdf.Document.openDocument(bytes, "application/pdf").asPDF();
+  if (!doc)
+    throw new Error("not a PDF document");
+  return doc;
+}
 async function openDoc(bytes) {
   const mupdf = await loadMupdf();
-  const doc = mupdf.Document.openDocument(bytes, "application/pdf");
+  const doc = openPdf(mupdf, bytes);
   if (doc.needsPassword())
     throw new PdfEncryptedError();
   if (doc.countPages() === 0) {

package/skills/document/bin/xlsx-recalc.cjs

@@ -111707,6 +111707,13 @@ for (const pluginName of Object.getOwnPropertyNames(plugin_exports)) {
 }
 
 // packages/core/dist/document/xlsx-recalc.js
+var EXCEL_ERROR_CODES = ["#N/A", "#REF!", "#NAME?", "#DIV/0!", "#NULL!", "#VALUE!", "#NUM!"];
+function isExcelErrorCode(code) {
+  return EXCEL_ERROR_CODES.includes(code);
+}
+function excelErrorValue(code) {
+  return { error: isExcelErrorCode(code) ? code : "#VALUE!" };
+}
 function toPrimitive(v) {
   if (v == null)
     return { value: null };
@@ -111720,7 +111727,7 @@ function toPrimitive(v) {
 async function recalcXlsx(bytes) {
   const wb = new import_exceljs.default.Workbook();
   try {
-    await wb.xlsx.load(Buffer.from(bytes));
+    await wb.xlsx.load(new Uint8Array(bytes).buffer);
   } catch (e) {
     throw new Error(`not a readable xlsx: ${e.message}`);
   }
@@ -111755,7 +111762,7 @@ async function recalcXlsx(bytes) {
       const raw = hf.getCellValue({ sheet: sheetId, row: fc.row - 1, col: fc.col - 1 });
       const { value, error } = toPrimitive(raw);
       const cell = wb.getWorksheet(fc.sheet).getCell(fc.row, fc.col);
-      cell.value = { formula: fc.formula, result: error ? { error } : value };
+      cell.value = { formula: fc.formula, result: error ? excelErrorValue(error) : value ?? void 0 };
       if (error)
         errors.push({ sheet: fc.sheet, cell: cell.address, error });
       else if (sample.length < 20)

package/skills/document/bin-reference.md

@@ -15,15 +15,15 @@ unreadable file · `69` a required engine is unavailable · `75` transient, retr
 
 - `bin/doc-scan.cjs <file.pdf>` — per-page signals: `{file, pages:[{page, textChars, imageCoverage, mathHint, tableHint, scanned, …}]}`. PDF only. Every PDF reader here (doc-scan, doc-text, pdf-render, pdf-images, pdf-tables) exits 1 on a password-protected PDF — see pdf.md.
 - `bin/doc-text.cjs <file.pdf>` — the PDF's text layer, `[page N]`-delimited. A .docx/.pptx/.xlsx exits 64 (read the sidecar / use xlsx-query).
-- `bin/pdf-render.cjs <file.pdf> <pages|all> [scale]` — render pages to PNG for vision, written beside the PDF as `<stem>_p<N>.png` (prints `{rendered:[{page, path}]}`); `pages` = `3` | `2-5` | `3,7-8` | `all`. `scale` 0.5–4 (default `2` ≈ 144dpi) trades resolution for vision tokens: `1` (≈72dpi, ¼ the tokens) for layout QA; keep `2` when fine print must stay legible (formulas/tables).
-- `bin/pdf-images.cjs <file.pdf> [pages]` — EMBEDDED images at native resolution, written beside the PDF as `<stem>_p<page>_i<index>.png`, plus a manifest `{images:[{page, index, bbox, width, height, path}], skipped}` (`pages` = `N` | `N-M` | `all`, default all). Use this — not a full-page `pdf-render` — when you need the original figures as their own files (e.g. rebuilding a deck). Vector/text-only pages yield nothing → `pdf-render`.
+- `bin/pdf-render.cjs <file.pdf> <pages|all> [scale]` — render pages to PNG for vision, written as `<stem>_p<N>.png` to the scratch dir (prints `{rendered:[{page, path}]}`); `pages` = `3` | `2-5` | `3,7-8` | `all`. `scale` 0.5–4 (default `2` ≈ 144dpi) trades resolution for vision tokens: `1` (≈72dpi, ¼ the tokens) for layout QA; keep `2` when fine print must stay legible (formulas/tables).
+- `bin/pdf-images.cjs <file.pdf> [pages]` — EMBEDDED images at native resolution, written as `<stem>_p<page>_i<index>.png` to the scratch dir, plus a manifest `{images:[{page, index, bbox, width, height, path}], skipped}` (`pages` = `N` | `N-M` | `all`, default all). Use this — not a full-page `pdf-render` — when you need the original figures as their own files (e.g. rebuilding a deck). Vector/text-only pages yield nothing → `pdf-render`.
 - `bin/pdf-tables.cjs <file.pdf> [page] [minCols]` — text-layer tables as `{tables:[{page, rows}]}` (`minCols` default 2; rows may carry empty spacer cells). Nothing found, or a ruled/scanned table → render + vision.
 - `bin/ocr.cjs <image> [lang]` — text off a png/jpg/webp/bmp image → `{text, confidence}`; for a scanned PDF `pdf-render` the page first. `lang` is a tesseract code, default `eng`; `chi_sim` = simplified Chinese, `chi_tra` traditional, `+` combines (`chi_sim+eng` for mixed text). `eng` and `chi_sim` ship with the skill and work offline; others download once into `$TALOS_TESSDATA` (no network → exit 1 `OCR failed: …`); `$TALOS_TESSDATA_LANGPATH` names a dir holding every `<lang>.traineddata.gz`. **Prefer vision** when a vision model is available; OCR is the text-only fallback.
 - `bin/xlsx-query.cjs <file> [--summary | --agg <sheet> <col> <op> | --sample <sheet> [n]] [--header-row N] [--include-totals]` — exact spreadsheet compute; no mode = `--summary` (sheet names, row/column counts, `headerRow`, headers). `<op>` = `sum` | `avg` | `min` | `max` | `count` | `count-nonempty` (anything else exits 64 listing these); `<col>` is a header label or a 1-based index. The header row is detected (a title row is skipped; `--header-row N` overrides). `--agg` excludes total rows (合计/总计/小计/Total/Subtotal/Sum, or a SUM over the column) and reports them in `excludedRows` (`--include-totals` keeps them), and lists non-numeric cells it skipped in `skippedCells`. `15%` text is 0.15; `¥`/`元` amounts parse. An unknown sheet exits 1 naming the sheets; a column it cannot find returns `value: null, colIdx: -1` — run `--summary` for the exact names. `--sample` prints up to `n` (default 20) rows keyed by header. Caveats: xlsx.md.
 
 ## Generate
 
-- `bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json> [--theme <theme.json|name>] [--topic <subject> | --palette <id>] [--accent <#rrggbb> | --style <id>] [--no-preview]` — generate documents from scratch; spec shapes in rewrite.md "Generate". DOCX/PDF body fields are exactly `paragraphs` and/or `blocks` (never `sections`); in a PDF, any http(s) URL written in body text, list items or table cells becomes a clickable link and wraps inside the page on its own — never split a URL by hand (there is no other link syntax). Unknown fields and empty bodies exit 65 with `DOC_SPEC_INVALID` before any output is written (`allowCoverOnly:true` is the explicit title-only opt-in): correct the reported JSON path and rerun. Prints `wrote <out>` (a PDF adds its engine) then one JSON line — the self-check in SKILL.md "After writing a file"; PDF previews land beside it as `<stem>_p<N>.png` (`--no-preview` skips them). A PDF prints in Chromium — the app's service, else a headless Chromium; with neither it exits 69. `doc-gen pptx` exits 64: decks are built with html2pptx. **Look flags** (docx/pdf): `--theme` = a theme file (built-ins `<skill>/themes/<id>.json`) or the name of one the user saved in `$TALOS_DOC_STYLES_DIR/themes`; `--topic <subject>` picks a topic-adaptive palette, `--palette <id>` forces one (`doc-gen --list-palettes`); `--accent <#rrggbb>` / `--style <id>` keep white paper and near-black text with ONE brand colour on H1/H2 + a faint table-header tint — `--style` takes it from a catalog skin or pack (the deck picker's ids; the deck's full palette is NOT carried onto paper); an accent that is not 6-digit hex falls back to black-on-white with a warning. Precedence: `--theme` > spec `"theme"` > `--accent`/`--style` > `--palette`/`--topic` > default.
+- `bin/doc-gen.cjs <docx|xlsx|pdf> <out> <spec.json> [--theme <theme.json|name>] [--topic <subject> | --palette <id>] [--accent <#rrggbb> | --style <id>] [--no-preview]` — generate documents from scratch; spec shapes in rewrite.md "Generate". DOCX/PDF body fields are exactly `paragraphs` and/or `blocks` (never `sections`); in a PDF, any http(s) URL written in body text, list items or table cells becomes a clickable link and wraps inside the page on its own — never split a URL by hand (there is no other link syntax). Unknown fields and empty bodies exit 65 with `DOC_SPEC_INVALID` before any output is written (`allowCoverOnly:true` is the explicit title-only opt-in): correct the reported JSON path and rerun. Prints `wrote <out>` (a PDF adds its engine) then one JSON line — the self-check in SKILL.md "After writing a file"; PDF previews land in the scratch dir as `<stem>_p<N>.png` (`--no-preview` skips them). A PDF prints in Chromium — the app's service, else a headless Chromium; with neither it exits 69. `doc-gen pptx` exits 64: decks are built with html2pptx. **Look flags** (docx/pdf): `--theme` = a theme file (built-ins `<skill>/themes/<id>.json`) or the name of one the user saved in `$TALOS_DOC_STYLES_DIR/themes`; `--topic <subject>` picks a topic-adaptive palette, `--palette <id>` forces one (`doc-gen --list-palettes`); `--accent <#rrggbb>` / `--style <id>` keep white paper and near-black text with ONE brand colour on H1/H2 + a faint table-header tint — `--style` takes it from a catalog skin or pack (the deck picker's ids; the deck's full palette is NOT carried onto paper); an accent that is not 6-digit hex falls back to black-on-white with a warning. Precedence: `--theme` > spec `"theme"` > `--accent`/`--style` > `--palette`/`--topic` > default.
 - `bin/doc-run.cjs <script.js> [args…]` — run a custom Node script with the engine's libraries bundled in (`require("pptxgenjs"|"docx"|"xlsx"|"exceljs"|"pdf-lib"|"jszip"|"pizzip"|"hyperformula")` guaranteed on any machine; `--list` prints the registry; nothing else is installed, and an unbundled `require` fails naming the bundled alternative). For a **formatted workbook** (fills, font colors, borders, merged cells) use `exceljs` — `xlsx` (SheetJS community) writes no cell styles at all and drops them without an error; `doc-gen xlsx` covers only a bold header, column widths, number formats and formulas. The long-tail escape hatch when no verb fits — see rewrite.md "Custom scripts"; ALWAYS `doc-validate --strict` the output.
 - `bin/xlsx-recalc.cjs <in.xlsx> <out.xlsx>` — re-evaluate every formula (HyperFormula) and cache the results, keeping the formulas (`out` may equal `in`). Prints `{ok, out, recomputed, errors:[{sheet, cell, error}], sample}`; it exits 0 even with formula errors, so `errors` must be read — rewrite.md "Formulas".
 
@@ -47,7 +47,7 @@ unreadable file · `69` a required engine is unavailable · `75` transient, retr
 
 Flags and outputs only; the workflow is deck-design.md.
 
-- `bin/deck-scenario.cjs "<scenario>"` — the ONE matrix row the clarify gate picked: `{ok, scenario:{id, tone, density, pages, narrative, flows, sections:[{label, key, content}], researchFocus}}`. `content` = what that section must contain (elements, evidence; `；宜` a recommended shape) — it is in no md table. Matches the id, else the longest alias in the text; no match exits 1 with the ids (map to the nearest and rerun).
+- `bin/deck-scenario.cjs "<scenario>"` — the ONE matrix row the brief picked: `{ok, scenario:{id, tone, density, pages, narrative, flows, sections:[{label, key, content}], researchFocus}}`. `content` = what that section must contain (elements, evidence; `；宜` a recommended shape) — it is in no md table. Matches the id, else the longest alias in the text; no match exits 1 with the ids (map to the nearest and rerun).
 - `bin/deck-styles.cjs --scenario "<scenario>"` — the style picker's first round: `{scenario, source, options}`; pass `options` to the picker as printed (SKILL.md "STYLE PICKER"). `source` `mixed`/`fallback` = the scenario claimed under six styles and the default group topped it up.
 - `bin/deck-plan.cjs --layouts --style <id>` — before plan.json: the layouts this style renders and the plan fields each takes (`stats×N` = exactly N, `unit?` optional, `slots.<name>` = pass it, `source ✓` = footer).
 - `bin/deck-plan.cjs <plan.json> [spec.json]` — **content-first layout selection, run BEFORE deck-build.** The plan is the deck spec's top-level fields (`style`, `themeVersion`, `layoutPack`, `scenario`, `density` (read · talk; default from scenario), `footer`, `chartRender`, …) plus per slide its CONTENT: `role` (cover · toc · section · content · ending; default content), optional `intent` (layouts/profiles.json) / `shape` / `layout` (pin), and `title` · `subtitle` (口径 line) · `takeaway` (启示 line) · `eyebrow` · `meta` · `index` · `points` (`[{title, body, date?, label?}]` or strings) · `stats` (`[{value, unit, label, note}]`) · `chart` · `quote` (`{text, source}` or a string) · `table` (`{columns, rows}`) · `image: true` · `source` (one short source line, "IDC，2026" → the footer; dropped with a warning on a layout without one) · `notes` (speaker notes) · `narrative` (outline only) · `file` (a bespoke slide: one `<section class="slide">` in that file, taken as is, `pick:"bespoke"`) · `slots` / `rows` (explicit values, override the draft). A `\n` in any text is a line break. `--outline <slide-outline.md>` also writes the readable outline (one block per slide + its pick) — the approval gate's document, rendered from the plan, never hand-written. Prints `{ok, slides:[{slide, pick, warnings, blanks, alternatives, rejected:[{layout, why}]}], next}`. Fit = the layout's item count (a 3-card layout takes exactly 3 points; rows layouts take 1..their measured ceiling, at least the count the README density column names) + every drafted string within the layout's capacity measured under your `style` (`layouts/capacity.json`; an unknown style uses the tightest skin). Picks under P1/P2/P3 (layouts/README.md). With `spec.json` it writes the drafted deck-build spec (chart slides get `chartRender:"svg"`) — only when EVERY slide got a pick; otherwise exit 1, nothing written: fix the content the `why` names and re-plan. `blanks` = slots the content had nothing for (left empty, not demo text) — fill them or accept. A layout rejected for leaving slots empty names where each one is filled from (`kpi1_desc ← each stat's note`).
@@ -60,4 +60,4 @@ Flags and outputs only; the workflow is deck-design.md.
 ## Validate and convert
 
 - `bin/doc-validate.cjs <file.docx|pptx|xlsx|pdf> [--strict] [--design-lint]` — structural validation gate: OOXML zip/parts/rels/Content_Types/XML well-formedness, plus pptx `notes-keynote` (→ `pptx-notes <in> {} <out>`) and docx `docx-default-style` (→ `docx-defaults`); a PDF must parse, open without a password (`pdf-encrypted` error: validate before `pdf-ops encrypt`) and hold at least one page (reports `pages` and a `pdf-parse-only` warning — how it looks is render-and-look's job). Exit 1 = broken, fix before delivering. `--strict` (OOXML only; on a PDF it just adds a `strict-not-applicable` warning) adds full ECMA-376 schema (XSD) validation of every recognised part — REQUIRED after custom-code (doc-run) or raw-XML output; a strict failure means the file is non-standard even if Office opens it. `--design-lint` (pptx only) adds deck-qa's lint as advisory warnings (never changes the exit code; codes under deck-qa in Decks) — real design bugs, fix them.
-- `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf> [--cache-dir <dir>] [--require-office]` — Office → PDF. **PPTX requires Office**: local `soffice`, then `TALOS_OFFICE_URL` sidecar. Missing Office exits 69; failed Office exits 75. Never rebuild a deck as browser HTML. Spreadsheets also require Office. DOCX can fall back to reconstructed HTML via the app's Chromium or headless Chromium (content retained, layout lost); `--require-office` blocks this fallback. Report the `[pdf (engine)]` result and any caveat. `--cache-dir` (or `TALOS_OFFICE_CACHE_DIR`) reuses the local Office result for identical source bytes; after any PPTX edit, convert again. Fonts come from the Office environment, which must have the required faces for faithful typography.
+- `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf> [--cache-dir <dir>] [--require-office]` — Office → PDF. **PPTX requires Office**: local `soffice`, then Keynote (Mac) / PowerPoint (Win) for .pptx, then `TALOS_OFFICE_URL` sidecar. Missing Office exits 69; failed Office exits 75. Never rebuild a deck as browser HTML. Spreadsheets also require Office. DOCX can fall back to reconstructed HTML via the app's Chromium or headless Chromium (content retained, layout lost); `--require-office` blocks this fallback. Report the `[pdf (engine)]` result and any caveat. `--cache-dir` (or `TALOS_OFFICE_CACHE_DIR`) reuses the local Office result for identical source bytes; after any PPTX edit, convert again. Fonts come from the Office environment, which must have the required faces for faithful typography.

package/skills/document/content-pipeline.md

@@ -29,33 +29,29 @@ reorganize THEIR content, never invent facts.
 
 ---
 
-## Phase 0 — Clarify & Brief (MANDATORY gate)
-
-The clarify gate and the style picker are defined once, in SKILL.md: ask only for the
-missing values among content source, scenario and slide count, in ONE AskUserQuestion
-call with at most
-THREE questions; the scenario-ranked image-card style picker is a separate call after
-the scenario is known. Run `bin/deck-styles.cjs` and pass its `options` unchanged;
-the app expands the full-gallery option. The manual fallback is defined in SKILL.md.
-What each answer means here:
-
-1. **Content source** — 提供材料 / 联网调研 / 自由创作 (offline / no web tool → say so;
-   only the first and last). Provided → request the materials now; when you ask for a FILE, set
-   `filePick: "file"` on that question (a native file button; the picked path is the
+## Phase 0 — Brief & style
+
+The brief and the style picker are defined once, in SKILL.md: source, scenario and
+slide count are inferred from the request, never asked on their own; the style picker
+is the one call before the outline. What each value means:
+
+1. **Content source** — 提供材料 / 联网调研 / 自由创作 (no web tool → not 联网调研;
+   say so). 提供材料 without the material in hand → ask for it in the picker call,
+   with `filePick: "file"` on that question (a native file button; the picked path is the
    answer). **Material given as CONTENT is for its TEXT/DATA only** — extract and
    re-author it in the chosen style; never reuse its look. A `.pptx` handed in as
    content → read its text (`.txt` sidecar or `bin/doc-text`); do **NOT**
    `pptx-tokenize`/`pptx-theme` it. Reusing a deck's look happens only when the user
    picks it as their **style** ("复用这份 PPT 的风格"), never because the content
    arrived as a `.pptx`.
-2. **Scenario** — AskUserQuestion caps TEXT options at 4, so offer the 3–4 rows of the
-   matrix below that best fit the topic (the user can type any other); an unlisted
+2. **Scenario** — inferred; when it cannot be, the picker call's second question offers
+   the 3–4 matrix rows that best fit the topic (the user may type another); an unlisted
    answer maps to the nearest row. Record it as a short phrase. It locks **five** things:
    tone · density (feeds Phase 4) · **required roles** (the default checklist for Phase 2) ·
    narrative shape (Phase 2) · page range (the slide-count default). Then run
    `bin/deck-scenario.cjs "<scenario>"` once: it prints that row with each section's
    `content` — what the section must contain (elements, evidence, a recommended shape).
-3. **Slide count** — default = the row's **默认页数**; clamp 3–30, double-check outside.
+3. **Slide count** — as stated, else the row's **默认页数**; clamp 3–30, double-check outside.
 
 **Scenario matrix** — source of truth `scenarios.json`; the tables below are generated
 from it. The required roles (必备章节) are the scenario's **default**: every one appears
@@ -104,9 +100,8 @@ Tone also biases the catalog style ranking: 张力/情绪(pitch·发布会·大
 **Persist `deck-brief.md`**: Topic · Scenario · Source · Style (entry id + 2–3 sentences
 on palette/type/motif) · Template style · Slide Count · Overrides (if any) · (assumptions) —
 ≤10 lines of DECISIONS. Research findings, numbers, chart data and citations do not go
-here: they are written once, in `plan.json`. Persist it and
-continue — do not ask the user to approve what they just supplied. If the brief adds a
-material assumption that changes scope, show only that assumption and pause.
+here: they are written once, in `plan.json`. Persisting it is not an approval round
+(Execution discipline 1).
 
 ---
 
@@ -199,7 +194,8 @@ node <skill>/bin/deck-plan.cjs --layouts --style <style id>
 One line per layout this style renders, with the plan fields it takes
 (bin-reference.md). Write each slide's content to the layout you mean it for.
 
-Write the outline ONCE, as `plan.json` — `deck-plan`'s input and the single source of
+Write the outline ONCE, as `plan.json` in the task's scratch folder with every other
+working file (SKILL.md "Where files go") — `deck-plan`'s input and the single source of
 truth for Phase 4–5 (do not re-decide count or roles later). Per slide: `role` · `title`
 (the takeaway, stated as a CONCLUSION) · `shape` / `intent` · what goes ON the canvas,
 (`subtitle` · `points` · `stats` · `quote` · `table` · `chart` · `image` · `takeaway`) ·
@@ -234,7 +230,8 @@ Count them within the total; mark purpose and image/text mode in `narrative`, re
 Then **GATE**, in this order — never ask before the outline exists:
 1. `plan.json` written and `slide-outline.md` rendered by the command above;
 2. `read` `slide-outline.md` — the outline shows in the timeline;
-3. AskUserQuestion, ONE sentence ("是否按这份 12 页大纲制作？"), `confirmation` with
+3. AskUserQuestion, ONE sentence naming the inferred brief ("是否按这份 12 页大纲制作？
+   （培训 · 自由创作）"), `confirmation` with
    `options: ["按此制作", "调整大纲"]` — never the outline in the question.
 
 Advance only on approval. A revision edits `plan.json` and re-runs the same command — the outline and the

package/skills/document/deck-design.md

@@ -183,7 +183,7 @@ Spend the boldness in ONE place (layer 5).
 ## Motion — presets, entrance animation, transitions
 
 **Every catalog entry ships a motion preset (`motion/<id>.json`); the scenario decides
-whether `deck-build` applies it.** Put the confirmed scenario in the spec as
+whether `deck-build` applies it.** Put the brief's scenario in the spec as
 `"scenario"`: a **presented** deck (pitch / 路演 / 发布会 / keynote / 大会 / 讲座 / 销售)
 gets the preset — `data-anim*` / `data-transition*` injected per slide by role; a
 **read** deck (内审 / 评审 / 报告 / 汇报 / 讲义 / 培训 / 述职) gets none; no or an unknown
@@ -374,7 +374,7 @@ Do not launch LibreOffice after every edit.
    chart, which only Office draws) and `previews` (≈72dpi images of those).
    **Read only `previews`.** For hybrid PPTX QA, other slides already passed the HTML
    preview; their visuals come from that render. PDF delivery needs the final check below.
-   - **Read every slide instead** (`pdf-render.cjs <deck>.office.pdf all 1`) when
+   - **Read every slide instead** (`pdf-render.cjs <deck-qa's office.pdf> all 1`) when
      html2pptx reported a `layout (fallback)` engine, or you changed the PPTX after
      building it (`doc-xml`, `pptx-slide`, a script).
    - `office.unavailable`: PPTX has no Office layout check; disclose this. A running

package/skills/document/rewrite.md

@@ -2,11 +2,11 @@
 
 **Read only the sections your task needs** (Read with the offset/limit of the line range):
 
-- New .docx / .pdf / .xlsx → **Generate** (lines 14–55); a formula in a workbook → also **Formulas** (lines 57–73); a particular look, theme or brand → also **Themes** (lines 75–125)
-- Fill a `{{placeholder}}` .docx / .pptx / .xlsx template → **Fill a template** (lines 127–146)
-- Change an existing .docx — text, structure, comments, tracked changes → **Edit an existing .docx** (lines 148–199)
-- New content in an existing deck's look, or restructure a .pptx → **Template decks** (lines 201–281)
-- Nothing above fits → **Custom scripts** (lines 283–308)
+- New .docx / .pdf / .xlsx → **Generate** (lines 14–59); a formula in a workbook → also **Formulas** (lines 61–79); a particular look, theme or brand → also **Themes** (lines 81–131)
+- Fill a `{{placeholder}}` .docx / .pptx / .xlsx template → **Fill a template** (lines 133–152)
+- Change an existing .docx — text, structure, comments, tracked changes → **Edit an existing .docx** (lines 154–205)
+- New content in an existing deck's look, or restructure a .pptx → **Template decks** (lines 207–287)
+- Nothing above fits → **Custom scripts** (lines 289–313)
 
 A PDF's forms, page ops and stamps are in pdf.md; a deck from scratch is the deck route
 (SKILL.md) — `doc-gen` makes no decks. `<skill>` below is this skill's directory.
@@ -31,9 +31,13 @@ than delivering the previous output.
     (DOCX widths in twips; default: full page width, equal columns)
   - `{ "type": "image", "data": "<base64>", "imageType"?: "png", "width"?, "height"? }` (px, default 300×200)
 - **xlsx**: `{ "sheets": { "Name": [["h1","h2"], ["a", 1]] } }` (row 1 = bold header), or per
-  sheet `{ "rows": [...], "header"?, "columnWidths"?: [n…], "numFmt"?: ["#,##0.00"…] }`. A
-  cell string starting with `=` is a **live formula** — then run **Formulas** below.
-  Fills, font colours, borders or merges need exceljs via doc-run (**Custom scripts**).
+  sheet `{ "rows": [...], "header"?, "columnWidths"?: [n…], "numFmt"?: ["#,##0.00"…],
+  "merges"?: ["A1:D1"], "freeze"?: { "rows": 1 }, "styles"?: [{ "range": "A1:D1", "bold"?,
+  "italic"?, "fontSize"?, "color"?: "#1F4E79", "fill"?: "#DDEBF7", "border"?: "thin"|"medium",
+  "align"?: "left"|"center"|"right", "wrap"?, "numFmt"? }] }` — styles apply in order. A cell
+  string starting with `=` is a **live formula**; `"2026-10-21"` is written as a date and
+  keeps a date format. Each sheet prints one page wide (landscape when wide). A quote,
+  invoice, tracker or report sheet is a spec, not a script.
 - The spec may also carry `"topic"`, `"palette"` or `"theme"` (same as the flags).
 
 **A length limit** (正文 1000 字以内 / under 800 words) is kept in the spec, before
@@ -51,18 +55,20 @@ page size and margin. Inside Talos it uses the app's service (`[pdf (chromium)]`
 elsewhere a headless Chromium (`[pdf (headless chromium)]`); with neither it exits 69 and
 writes nothing — tell the user (a .docx can be offered; never swap formats silently).
 
-Anything past these shapes — an exotic layout, a styled workbook — is a doc-run script
+Anything past these shapes — an exotic layout, a chart or image in a workbook — is a doc-run script
 (**Custom scripts**), not an edit of the bundled bin.
 
 ## Formulas — the xlsx repair loop (mandatory)
 
 Write live formulas (`"=SUM(A2:A9)"`), never precomputed values — the file must
-recalculate when the user edits data. doc-gen and exceljs write formulas without cached
-results, so close the loop:
+recalculate when the user edits data. `doc-gen xlsx` evaluates and caches them as it
+writes: its JSON line reports `recomputed` and `formulaErrors`, and exits 1 when that
+is not empty. A workbook from an exceljs script or an edit has no cached results:
 
 1. `node <skill>/bin/xlsx-recalc.cjs out.xlsx out.xlsx` — evaluates every formula and
    caches the results.
-2. Its `errors` array must be **empty** — it exits 0 either way, so read it. A
+2. Its `errors` array (doc-gen: `formulaErrors`) must be **empty** — xlsx-recalc exits 0
+   either way, so read it. A
    `#DIV/0!`, `#REF!` or `#N/A` → fix the formula (guard divisors with IF, correct the
    range) and recalc again. **Never deliver a spreadsheet with formula errors**, and never
    "fix" one by replacing the formula with a hardcoded value.
@@ -282,8 +288,7 @@ TEXT goes through `doc-fill` (templated) or `doc-xml` (raw).
 
 ## Custom scripts — `bin/doc-run` (the long-tail escape hatch)
 
-When no verb or spec block expresses it (an exotic layout, a bulk transformation, a
-styled workbook), write a CommonJS Node script and run it with `doc-run` — the engine's
+When no verb or spec block expresses it (an exotic layout, a bulk transformation), write a CommonJS Node script and run it with `doc-run` — the engine's
 pure-JS libraries are bundled inside it, so it works on any machine:
 
 ```
@@ -291,8 +296,8 @@ node <skill>/bin/doc-run.cjs myscript.js [args…]
 node <skill>/bin/doc-run.cjs --list          # the guaranteed module registry
 ```
 
-`require()` of these is guaranteed: `docx` (Word) · `exceljs` (formatted workbooks:
-fills, fonts, borders, merges, formulas — then **Formulas**) · `xlsx` (SheetJS: reading
+`require()` of these is guaranteed: `docx` (Word) · `exceljs` (what a doc-gen xlsx spec
+cannot say: charts, images, conditional formats — then **Formulas**) · `xlsx` (SheetJS: reading
 and plain-data workbooks only — it writes no cell styles) · `pdf-lib` (PDF assembly) ·
 `jszip` / `pizzip` (OOXML zip surgery) · `hyperformula` (formula evaluation) ·
 `pptxgenjs` (non-deck pptx only — every deck goes through html2pptx). Nothing else: no

package/skills/document/vision.md

@@ -7,7 +7,7 @@ loses.
 ## Steps
 
 1. `bin/pdf-render.cjs file.pdf <pages> [scale]` — `<pages>` is `4`, `2-6`, `3,7-8`
-   or `all`; PNGs land beside the PDF (`<stem>_p<N>.png`) and their paths are printed.
+   or `all`; PNGs (`<stem>_p<N>.png`) land in the scratch directory and their paths are printed.
    Keep the default scale `2` for formulas and fine print; `1` is enough for layout.
 2. Look at each PNG. For:
    - **Formulas** → transcribe to LaTeX from the image.

package/skills/expert-create/LICENSE.txt

@@ -0,0 +1,7 @@
+© 2026 Nexora AI Limited. All rights reserved.
+
+LICENSE: This Skill (including all prompts, reference documents, and other
+components) is proprietary to Nexora AI Limited and provided solely for use
+within the Talos application under your agreement with Nexora AI Limited.
+Redistribution, extraction, or use outside Talos is not permitted without
+prior written consent.

package/skills/expert-create/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: expert-create
+description: "Use when the user wants to create, edit or delete their own expert (an OSE: a named assistant persona with its own role prompt, shown in the expert switcher). Triggers: create an expert / make a new expert / build an assistant for X / edit my expert / change the expert's role / delete my expert, 新建专家 / 创建一个专家 / 做一个XX专家 / 修改专家 / 改一下专家的角色 / 删除专家. Not for installing skills (install_skill) or for switching experts."
+license: Proprietary. LICENSE.txt has complete terms
+---
+
+# Create, edit and delete local experts
+
+An expert is a persona the user switches to: a name, a one-line description,
+an optional English label, up to four starter prompts, and a role prompt
+(`role.md`) that becomes the opening of every conversation with it. Experts the
+user makes here are **local**: only on this machine, editable and deletable.
+Published experts cannot be changed here.
+
+Everything goes through one command, where `<skill>` is this skill's
+directory. The Talos app validates, writes and refreshes the expert list; never
+create or edit expert files yourself, and never state where they live.
+
+```
+node <skill>/bin/expert-create.cjs list
+node <skill>/bin/expert-create.cjs show <id>
+node <skill>/bin/expert-create.cjs create <draft.json>
+node <skill>/bin/expert-create.cjs update <id> <patch.json>
+node <skill>/bin/expert-create.cjs delete <id>
+```
+
+`create`, `update` and `delete` each wait for the user to confirm in a Talos
+dialog that shows what will change; agreeing in the chat does not replace it.
+The dialog stays open for up to 5 minutes (300 seconds), so run these three
+without a `timeout`, or with one of at least 330 seconds. A shorter timeout
+kills the command while the user is still reading the dialog: the dialog
+closes, nothing is written, and running it again opens a second one.
+
+Exit codes:
+
+- 0 done (JSON on stdout).
+- 1 the app refused or failed (read stderr; if it names a field, fix it and
+  retry).
+- 3 the user said no in the dialog; nothing was written.
+- 4 the dialog went unanswered and closed after 5 minutes; nothing was written.
+- 5 `update` would change nothing: the patch matches the expert as it is. No
+  dialog was shown and nothing was written; tell the user it already reads
+  that way.
+- 64 usage; 66/65 the JSON file could not be read or parsed.
+- 69 the Talos app is not reachable or not ready — not running inside Talos,
+  this is a scheduled task, a sub-agent or a channel session (which cannot
+  change experts), or Talos was starting or switched profile. Nothing was
+  written. Do not retry; tell the user, and do not work around it.
+
+## Draft JSON
+
+```json
+{
+  "name": "Sales Coach",
+  "desc": "Coaches sales calls",
+  "role": "…the full role.md…",
+  "en": { "name": "Sales Coach", "desc": "Coaches sales calls" },
+  "demos": [{ "label": "Review a call", "output": "PDF", "icon": "search", "seed": "…" }]
+}
+```
+
+Limits the app enforces: `name`, `desc`, `en.name`, `en.desc` and each demo
+`label` are one line (no line breaks); `name` ≤ 24 characters; `desc` ≤ 20
+characters when it contains Chinese/Japanese/Korean text or full-width
+punctuation, otherwise ≤ 38; `en.name` ≤ 40, `en.desc` ≤ 38; `role` up to 32 KiB; at most 4 `demos`, each with a
+`label` and a `seed` (≤ 420 characters, a prompt that stands alone), `icon` one
+of search, file, image, clock, code, chart, table, bug. A patch for `update`
+holds only the fields that change.
+
+## Creating
+
+1. Ask, in one message, what the expert is for: who uses it, the work it does,
+   the output it should produce, and anything it must or must not do. Do not
+   ask one question at a time.
+2. Draft every field. Write `role` following `references/role-guide.md`.
+   Write the name, description and demos in the language the user speaks; add
+   `en` when that language is not English.
+3. Show the user the name, description, demos and the full role, and revise
+   until they confirm. Do not create before they confirm.
+4. Write the draft to a JSON file in the working directory and run `create`;
+   Talos asks the user to confirm. Exit 3 means they said no — ask what to
+   change. On success, report the expert's name. Offer to switch to it — switching is the user's
+   action in the expert switcher.
+5. The new expert starts with the shared skills only. If the work needs more,
+   say which skills would help; installing them is a separate step.
+
+## Editing
+
+Run `show <id>` (get the id from `list`), change only what the user asked for,
+show the before and after of each changed field, and after confirmation run
+`update` with a patch of just those fields. Talos shows the user the change in
+its own dialog and keeps the version it replaces; exit 3 means they said no.
+An edit to the expert in use takes effect from the next message.
+
+## Deleting
+
+Say what goes: the expert itself. Its conversations stay on this machine but will no longer appear in Talos. Deleting the expert currently in use
+switches the user back to the default expert once this reply ends. Deleting
+the expert this conversation is with ends the conversation: finish your reply,
+and tell the user to continue with another expert, because Talos refuses any
+further message here.
+Then run `delete <id>`; Talos asks the user to confirm in its own dialog. Exit 3
+means they said no — leave it there.
+
+For any of the three, exit 4 means the dialog went unanswered and closed after
+5 minutes; nothing was written — ask the user before trying again.