@taloswork/ose-shared 0.0.5 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@taloswork/ose-shared",
-  "version": "0.0.5",
+  "version": "0.1.1",
   "description": "Talos cross-OSE shared library — skills + MCP servers auto-loaded into every OSE (P93 2026-07-27).",
   "type": "module",
   "files": [
@@ -10,6 +10,6 @@
   "publishConfig": {
     "access": "public"
   },
-  "_talosPublishHash": "sha256-lL5368bfc0Q4tq2TUv6gxgTk5TrR6nkjMCuUlj2_yRo",
-  "_talosPublishedAt": "2026-08-26T02:54:29.336Z"
+  "_talosPublishHash": "sha256-qYMkSCYzW7s-GEXLCu9xYsIMRDV_FT9ZUxNJ4Dbkctk",
+  "_talosPublishedAt": "2026-08-28T05:55:50.205Z"
 }

package/skills/document/SKILL.md

@@ -200,7 +200,7 @@ Fidelity-decision self-correct, but pointed at your OWN output:
 - `bin/pdf-tables.cjs <file.pdf> [page] [minCols]` — recover text-layer tables as rows (ruled/scanned tables need render + vision instead).
 - `bin/ocr.cjs <image.png|jpg> [lang]` — read text off a scanned image (tesseract.js). For a scanned PDF, `pdf-render` a page first, then OCR the PNG. Language data downloads on first use / set `$TALOS_TESSDATA` for offline. **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]]` — spreadsheet compute.
-- `bin/doc-gen.cjs <docx|xlsx|pptx|pdf> <out> <spec.json> [--theme <theme.json>] [--topic <subject> | --palette <id>] [--design native|html]` — generate documents from scratch; `--theme` applies a presentation theme (colors/fonts/cover/header/footer/pptx master — see rewrite.md "Themes"; built-ins in `themes/`). **`--topic <subject>` (pptx, when no `--theme`) picks a topic-adaptive palette** so the deck is designed-for-subject instead of template-flat, and turns on richness (motif + gradient wash + depth). `--palette <id>` forces a specific palette (`doc-gen --list-palettes` prints them). **`--accent <#hex>` / `--style <skin>` (docx/pdf)**: white-paper-black-text base with ONE brand color on H1/H2 + a faint table-header tint — the practical doc shape (a document is read/printed/edited, not projected, so body text stays near-black). `--accent` takes a literal hex; `--style <skin>` pulls just the `--accent` from `styles/<skin>/skin.css` (the deck skin's full palette is NOT carried onto paper). Precedence: `--theme` > spec `"theme"` > `--accent`/`--style` > `--palette`/`--topic` > default. `--design html` (pptx only, in-app) renders eligible slides through designed HTML templates for a magazine look — richer but a flat collage (no master structure); auto-falls back to native when headless or a slide has no template. Default `native` (structured, editable, charts, headless-safe).
+- `bin/doc-gen.cjs <docx|xlsx|pptx|pdf> <out> <spec.json> [--theme <theme.json>] [--topic <subject> | --palette <id>] [--design native|html]` — generate documents from scratch. DOCX/PDF body fields are exactly `paragraphs` and/or `blocks` (never `sections`); unknown fields and empty bodies fail 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. `--theme` applies a presentation theme (colors/fonts/cover/header/footer/pptx master — see rewrite.md "Themes"; built-ins in `themes/`). **`--topic <subject>` (pptx, when no `--theme`) picks a topic-adaptive palette** so the deck is designed-for-subject instead of template-flat, and turns on richness (motif + gradient wash + depth). `--palette <id>` forces a specific palette (`doc-gen --list-palettes` prints them). **`--accent <#hex>` / `--style <skin>` (docx/pdf)**: white-paper-black-text base with ONE brand color on H1/H2 + a faint table-header tint — the practical doc shape (a document is read/printed/edited, not projected, so body text stays near-black). `--accent` takes a literal hex; `--style <skin>` pulls just the `--accent` from `styles/<skin>/skin.css` (the deck skin's full palette is NOT carried onto paper). Precedence: `--theme` > spec `"theme"` > `--accent`/`--style` > `--palette`/`--topic` > default. `--design html` (pptx only, in-app) renders eligible slides through designed HTML templates for a magazine look — richer but a flat collage (no master structure); auto-falls back to native when headless or a slide has no template. Default `native` (structured, editable, charts, headless-safe).
 - `bin/doc-convert.cjs <in.docx|pptx|xlsx> <out.pdf>` — faithful docx/pptx/xlsx → PDF conversion. Engine precedence (best fidelity first, each downgrade tagged on stdout `[pdf (…)]` + warned on stderr): (1) **LibreOffice** if a system `soffice` is found — true layout render (page geometry, headers/footers, text-box positions, native charts), offline; (2) **LibreOffice sidecar** if `TALOS_OFFICE_URL` is set — same true-layout fidelity via a remote converter (e.g. Gotenberg), needs network; (3) **Chromium** (in-app) — reconstructed HTML, content/structure/images preserved but in-document layout is not (pptx = one page per slide); (4) **pdf-lib text-only** headless last resort — images/tables flatten. Surface the resulting `[pdf (engine)]` caveat to the user. NOTE: spreadsheets (xlsx/xls/ods) render ONLY via tiers 1–2 (real LibreOffice); tiers 3–4 do not rebuild spreadsheets, so with no LibreOffice available the command errors (never a degraded text-only sheet).
 - `bin/doc-validate.cjs <file.docx|pptx|xlsx> [--strict] [--design-lint]` — structural OOXML validation gate (zip/parts/rels/Content_Types/XML well-formedness); run after every generation or edit; exit 1 = broken, fix before delivering. `--strict` adds full ECMA-376 schema (XSD) validation of every recognised part — REQUIRED after custom-code (doc-run/html2pptx) or raw-XML output; a strict failure means the file is non-standard even if Office opens it. `--design-lint` (pptx only) adds an ADVISORY design pass — flags `text-only-slide` (a wall of text with no visual anchor), `low-contrast-text`, `placeholder-text` (a layout pasted but never filled — 替换为…/占位/Lorem still in the slide), `font-mismatch` (CJK text set in a Latin-only font → 豆腐; expected language defaults to the system locale, override with `TALOS_DECK_LANG`), `off-canvas`, `tiny-font`, `shape-overlap`; findings are warnings (never change the exit code) but are real design bugs — fix them. See deck-design.md "Design principles".
 - `bin/deck-qa.cjs <file.pptx> [--json]` — MECHANICAL design QA (deterministic, token-free): reads slide XML and flags `off-canvas` (content clipped past the edge), `tiny-font` (<10pt), `shape-overlap` (colliding text), plus `text-only-slide` / `low-contrast-text` / `placeholder-text` / `font-mismatch` (CJK text in a Latin-only font → 豆腐). Advisory (exit 0 even with findings). `--json` → `{ok,findings:[{slide,code,message}]}` for the visual-QA loop. It is the CHEAP GATE before spending vision tokens — run it every QA round and fix all findings first; then do the vision critic + per-slide regeneration (deck-design.md "Verify before delivering").

package/skills/document/bin/doc-convert.cjs

@@ -168597,12 +168597,285 @@ function iconSvgDataUri(name, colorHex) {
 function bareHex(c) {
   return c.replace("#", "").toUpperCase();
 }
+var DocumentSpecValidationError = class extends Error {
+  code = "DOC_SPEC_INVALID";
+  issues;
+  constructor(issues) {
+    const detail = issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+    super(`DOC_SPEC_INVALID: ${detail}`);
+    this.name = "DocumentSpecValidationError";
+    this.issues = [...issues];
+  }
+};
+var TEXT_DOCUMENT_KEYS = /* @__PURE__ */ new Set(["title", "paragraphs", "blocks", "allowCoverOnly", "fontPath", "theme", "topic", "palette"]);
+var XLSX_DOCUMENT_KEYS = /* @__PURE__ */ new Set(["sheets", "theme", "topic", "palette"]);
+var PPTX_DOCUMENT_KEYS = /* @__PURE__ */ new Set(["slides", "theme", "topic", "palette"]);
+var PPTX_SLIDE_KEYS = /* @__PURE__ */ new Set([
+  "title",
+  "cover",
+  "toc",
+  "ending",
+  "section",
+  "kpiCards",
+  "cards",
+  "timeline",
+  "steps",
+  "iconList",
+  "splitImage",
+  "comparison",
+  "quadrant",
+  "bigStat",
+  "quote",
+  "bullets",
+  "table",
+  "image",
+  "chart"
+]);
+function isJsonRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function addUnknownPropertyIssues(record, allowed, path, issues) {
+  for (const key of Object.keys(record)) {
+    if (allowed.has(key))
+      continue;
+    const message = allowed === TEXT_DOCUMENT_KEYS && (key === "section" || key === "sections") ? `${key} is unsupported for DOCX/PDF content; use $.blocks with heading/paragraph/list/table/image blocks (section is PPTX-only)` : `unsupported property ${JSON.stringify(key)}; allowed properties: ${[...allowed].join(", ")}`;
+    issues.push({ path: `${path}.${key}`, code: "UNKNOWN_PROPERTY", message });
+  }
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function validateTextBlock(value, path, issues) {
+  if (!isJsonRecord(value)) {
+    issues.push({ path, code: "INVALID_TYPE", message: "block must be an object" });
+    return false;
+  }
+  if (typeof value.type !== "string") {
+    issues.push({ path: `${path}.type`, code: "INVALID_TYPE", message: "block type must be a string" });
+    return false;
+  }
+  const requireText = () => {
+    if (nonBlankString(value.text))
+      return true;
+    issues.push({ path: `${path}.text`, code: "EMPTY_CONTENT", message: "text must be a non-empty string" });
+    return false;
+  };
+  switch (value.type) {
+    case "heading": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "text", "level"]), path, issues);
+      const valid = requireText();
+      if (value.level !== void 0 && ![1, 2, 3, 4].includes(value.level)) {
+        issues.push({ path: `${path}.level`, code: "INVALID_VALUE", message: "level must be one of 1, 2, 3, 4" });
+      }
+      return valid;
+    }
+    case "paragraph": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "text", "bold", "italic"]), path, issues);
+      const valid = requireText();
+      for (const key of ["bold", "italic"]) {
+        if (value[key] !== void 0 && typeof value[key] !== "boolean") {
+          issues.push({ path: `${path}.${key}`, code: "INVALID_TYPE", message: `${key} must be a boolean` });
+        }
+      }
+      return valid;
+    }
+    case "list": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "items", "ordered"]), path, issues);
+      if (!Array.isArray(value.items) || value.items.length === 0) {
+        issues.push({ path: `${path}.items`, code: "EMPTY_CONTENT", message: "items must be a non-empty string array" });
+        return false;
+      }
+      let valid = true;
+      value.items.forEach((item, index) => {
+        if (nonBlankString(item))
+          return;
+        valid = false;
+        issues.push({ path: `${path}.items[${index}]`, code: "EMPTY_CONTENT", message: "list item must be a non-empty string" });
+      });
+      if (value.ordered !== void 0 && typeof value.ordered !== "boolean") {
+        issues.push({ path: `${path}.ordered`, code: "INVALID_TYPE", message: "ordered must be a boolean" });
+      }
+      return valid;
+    }
+    case "table": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "rows", "header", "columnWidths"]), path, issues);
+      if (!Array.isArray(value.rows) || value.rows.length === 0) {
+        issues.push({ path: `${path}.rows`, code: "EMPTY_CONTENT", message: "rows must be a non-empty array" });
+        return false;
+      }
+      let hasCellContent = false;
+      value.rows.forEach((row, rowIndex) => {
+        if (!Array.isArray(row) || row.length === 0) {
+          issues.push({ path: `${path}.rows[${rowIndex}]`, code: "INVALID_TYPE", message: "table row must be a non-empty array" });
+          return;
+        }
+        row.forEach((cell, columnIndex) => {
+          if (typeof cell !== "string" && typeof cell !== "number") {
+            issues.push({ path: `${path}.rows[${rowIndex}][${columnIndex}]`, code: "INVALID_TYPE", message: "table cell must be a string or number" });
+          } else if (String(cell).trim().length > 0) {
+            hasCellContent = true;
+          }
+        });
+      });
+      if (!hasCellContent) {
+        issues.push({ path: `${path}.rows`, code: "EMPTY_CONTENT", message: "table must contain at least one non-empty cell" });
+      }
+      if (value.header !== void 0 && typeof value.header !== "boolean") {
+        issues.push({ path: `${path}.header`, code: "INVALID_TYPE", message: "header must be a boolean" });
+      }
+      if (value.columnWidths !== void 0 && (!Array.isArray(value.columnWidths) || value.columnWidths.some((width) => typeof width !== "number" || !Number.isFinite(width) || width <= 0))) {
+        issues.push({ path: `${path}.columnWidths`, code: "INVALID_VALUE", message: "columnWidths must contain only positive finite numbers" });
+      }
+      return hasCellContent;
+    }
+    case "image": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "data", "imageType", "width", "height"]), path, issues);
+      if (!nonBlankString(value.data)) {
+        issues.push({ path: `${path}.data`, code: "EMPTY_CONTENT", message: "image data must be non-empty base64" });
+        return false;
+      }
+      if (value.imageType !== void 0 && !["png", "jpg", "gif", "bmp"].includes(String(value.imageType))) {
+        issues.push({ path: `${path}.imageType`, code: "INVALID_VALUE", message: "imageType must be png, jpg, gif, or bmp" });
+      }
+      for (const key of ["width", "height"]) {
+        if (value[key] !== void 0 && (typeof value[key] !== "number" || !Number.isFinite(value[key]) || value[key] <= 0)) {
+          issues.push({ path: `${path}.${key}`, code: "INVALID_VALUE", message: `${key} must be a positive finite number` });
+        }
+      }
+      return true;
+    }
+    default:
+      issues.push({ path: `${path}.type`, code: "INVALID_VALUE", message: `unhandled block type: ${value.type}` });
+      return false;
+  }
+}
+function inspectTextDocumentSpec(spec) {
+  const issues = [];
+  if (!isJsonRecord(spec)) {
+    issues.push({ path: "$", code: "INVALID_TYPE", message: "spec must be a JSON object" });
+    return { issues, hasBody: false, hasTitle: false, allowCoverOnly: false };
+  }
+  addUnknownPropertyIssues(spec, TEXT_DOCUMENT_KEYS, "$", issues);
+  const hasTitle = nonBlankString(spec.title);
+  if (spec.title !== void 0 && !hasTitle) {
+    issues.push({ path: "$.title", code: "EMPTY_CONTENT", message: "title must be a non-empty string when provided" });
+  }
+  if (spec.allowCoverOnly !== void 0 && typeof spec.allowCoverOnly !== "boolean") {
+    issues.push({ path: "$.allowCoverOnly", code: "INVALID_TYPE", message: "allowCoverOnly must be a boolean" });
+  }
+  if (spec.fontPath !== void 0 && !nonBlankString(spec.fontPath)) {
+    issues.push({ path: "$.fontPath", code: "INVALID_TYPE", message: "fontPath must be a non-empty string" });
+  }
+  let hasBody = false;
+  if (spec.paragraphs !== void 0) {
+    if (!Array.isArray(spec.paragraphs)) {
+      issues.push({ path: "$.paragraphs", code: "INVALID_TYPE", message: "paragraphs must be a string array" });
+    } else {
+      spec.paragraphs.forEach((paragraph, index) => {
+        if (nonBlankString(paragraph))
+          hasBody = true;
+        else
+          issues.push({ path: `$.paragraphs[${index}]`, code: "EMPTY_CONTENT", message: "paragraph must be a non-empty string" });
+      });
+    }
+  }
+  if (spec.blocks !== void 0) {
+    if (!Array.isArray(spec.blocks)) {
+      issues.push({ path: "$.blocks", code: "INVALID_TYPE", message: "blocks must be an array" });
+    } else {
+      spec.blocks.forEach((block, index) => {
+        if (validateTextBlock(block, `$.blocks[${index}]`, issues))
+          hasBody = true;
+      });
+    }
+  }
+  return { issues, hasBody, hasTitle, allowCoverOnly: spec.allowCoverOnly === true };
+}
 function assertTextDocumentSpec(spec) {
-  if (!spec || typeof spec !== "object")
+  const { issues } = inspectTextDocumentSpec(spec);
+  if (issues.length > 0)
+    throw new DocumentSpecValidationError(issues);
+}
+function validateRows(rows, path, issues) {
+  if (!Array.isArray(rows) || rows.length === 0) {
+    issues.push({ path, code: "EMPTY_CONTENT", message: "rows must be a non-empty array" });
+    return false;
+  }
+  let hasContent = false;
+  rows.forEach((row, rowIndex) => {
+    if (!Array.isArray(row) || row.length === 0) {
+      issues.push({ path: `${path}[${rowIndex}]`, code: "INVALID_TYPE", message: "row must be a non-empty array" });
+      return;
+    }
+    row.forEach((cell, columnIndex) => {
+      if (typeof cell !== "string" && typeof cell !== "number") {
+        issues.push({ path: `${path}[${rowIndex}][${columnIndex}]`, code: "INVALID_TYPE", message: "cell must be a string or number" });
+      } else if (String(cell).trim().length > 0) {
+        hasContent = true;
+      }
+    });
+  });
+  if (!hasContent)
+    issues.push({ path, code: "EMPTY_CONTENT", message: "rows must contain at least one non-empty cell" });
+  return hasContent;
+}
+function assertDocumentSpec(kind, spec) {
+  if (kind === "docx" || kind === "pdf") {
+    const inspection = inspectTextDocumentSpec(spec);
+    if (!inspection.hasBody && !(inspection.allowCoverOnly && inspection.hasTitle)) {
+      inspection.issues.push({
+        path: "$",
+        code: "EMPTY_CONTENT",
+        message: "document body is empty; provide non-empty paragraphs/blocks, or set allowCoverOnly=true with a non-empty title"
+      });
+    }
+    if (inspection.issues.length > 0)
+      throw new DocumentSpecValidationError(inspection.issues);
     return;
-  if (Object.prototype.hasOwnProperty.call(spec, "section")) {
-    throw new Error("unsupported document field: section (use blocks for DOCX/PDF content; section is PPTX-only)");
   }
+  const issues = [];
+  if (!isJsonRecord(spec)) {
+    throw new DocumentSpecValidationError([{ path: "$", code: "INVALID_TYPE", message: "spec must be a JSON object" }]);
+  }
+  if (kind === "xlsx") {
+    addUnknownPropertyIssues(spec, XLSX_DOCUMENT_KEYS, "$", issues);
+    if (!isJsonRecord(spec.sheets) || Object.keys(spec.sheets).length === 0) {
+      issues.push({ path: "$.sheets", code: "EMPTY_CONTENT", message: "sheets must be a non-empty object" });
+    } else {
+      for (const [name, sheet] of Object.entries(spec.sheets)) {
+        const path = `$.sheets[${JSON.stringify(name)}]`;
+        if (Array.isArray(sheet)) {
+          validateRows(sheet, path, issues);
+        } else if (isJsonRecord(sheet)) {
+          addUnknownPropertyIssues(sheet, /* @__PURE__ */ new Set(["rows", "header", "columnWidths", "numFmt"]), path, issues);
+          validateRows(sheet.rows, `${path}.rows`, issues);
+        } else {
+          issues.push({ path, code: "INVALID_TYPE", message: "sheet must be a row array or an object containing rows" });
+        }
+      }
+    }
+  } else if (kind === "pptx") {
+    addUnknownPropertyIssues(spec, PPTX_DOCUMENT_KEYS, "$", issues);
+    if (!Array.isArray(spec.slides) || spec.slides.length === 0) {
+      issues.push({ path: "$.slides", code: "EMPTY_CONTENT", message: "slides must be a non-empty array" });
+    } else {
+      spec.slides.forEach((slide, index) => {
+        const path = `$.slides[${index}]`;
+        if (!isJsonRecord(slide)) {
+          issues.push({ path, code: "INVALID_TYPE", message: "slide must be an object" });
+          return;
+        }
+        addUnknownPropertyIssues(slide, PPTX_SLIDE_KEYS, path, issues);
+        if (Object.keys(slide).length === 0) {
+          issues.push({ path, code: "EMPTY_CONTENT", message: "slide must contain at least one supported field" });
+        }
+      });
+    }
+  } else {
+    throw new Error(`unsupported kind: ${String(kind)}`);
+  }
+  if (issues.length > 0)
+    throw new DocumentSpecValidationError(issues);
 }
 var HEADINGS = [HeadingLevel.HEADING_1, HeadingLevel.HEADING_2, HeadingLevel.HEADING_3, HeadingLevel.HEADING_4];
 var ORDERED_REF = "ol";
@@ -169864,6 +170137,7 @@ async function generatePdf(spec, themeInput) {
   return doc.save();
 }
 async function generateDocument(kind, spec, theme) {
+  assertDocumentSpec(kind, spec);
   switch (kind) {
     case "docx":
       return generateDocx(spec, theme);

package/skills/document/bin/doc-gen.cjs

@@ -36477,7 +36477,7 @@ var require_polyfills = __commonJS({
       }
       if (platform === "win32") {
         fs.rename = typeof fs.rename !== "function" ? fs.rename : (function(fs$rename) {
-          function rename(from, to, cb) {
+          function rename2(from, to, cb) {
             var start = Date.now();
             var backoff = 0;
             fs$rename(from, to, function CB(er) {
@@ -36497,8 +36497,8 @@ var require_polyfills = __commonJS({
               if (cb) cb(er);
             });
           }
-          if (Object.setPrototypeOf) Object.setPrototypeOf(rename, fs$rename);
-          return rename;
+          if (Object.setPrototypeOf) Object.setPrototypeOf(rename2, fs$rename);
+          return rename2;
         })(fs.rename);
       }
       fs.read = typeof fs.read !== "function" ? fs.read : (function(fs$read) {
@@ -72021,8 +72021,8 @@ var require_tmp = __commonJS({
       if (!_isUndefined(options.name)) {
         const name = options.name;
         if (path.isAbsolute(name)) throw new Error(`name option must not contain an absolute path, found "${name}".`);
-        const basename = path.basename(name);
-        if (basename === ".." || basename === "." || basename !== name) {
+        const basename2 = path.basename(name);
+        if (basename2 === ".." || basename2 === "." || basename2 !== name) {
           throw new Error(`name option must not contain a path, found "${name}".`);
         }
       }
@@ -152474,12 +152474,285 @@ function iconSvgDataUri(name, colorHex) {
 function bareHex(c) {
   return c.replace("#", "").toUpperCase();
 }
+var DocumentSpecValidationError = class extends Error {
+  code = "DOC_SPEC_INVALID";
+  issues;
+  constructor(issues) {
+    const detail = issues.map((issue) => `${issue.path}: ${issue.message}`).join("; ");
+    super(`DOC_SPEC_INVALID: ${detail}`);
+    this.name = "DocumentSpecValidationError";
+    this.issues = [...issues];
+  }
+};
+var TEXT_DOCUMENT_KEYS = /* @__PURE__ */ new Set(["title", "paragraphs", "blocks", "allowCoverOnly", "fontPath", "theme", "topic", "palette"]);
+var XLSX_DOCUMENT_KEYS = /* @__PURE__ */ new Set(["sheets", "theme", "topic", "palette"]);
+var PPTX_DOCUMENT_KEYS = /* @__PURE__ */ new Set(["slides", "theme", "topic", "palette"]);
+var PPTX_SLIDE_KEYS = /* @__PURE__ */ new Set([
+  "title",
+  "cover",
+  "toc",
+  "ending",
+  "section",
+  "kpiCards",
+  "cards",
+  "timeline",
+  "steps",
+  "iconList",
+  "splitImage",
+  "comparison",
+  "quadrant",
+  "bigStat",
+  "quote",
+  "bullets",
+  "table",
+  "image",
+  "chart"
+]);
+function isJsonRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+function addUnknownPropertyIssues(record, allowed, path, issues) {
+  for (const key of Object.keys(record)) {
+    if (allowed.has(key))
+      continue;
+    const message = allowed === TEXT_DOCUMENT_KEYS && (key === "section" || key === "sections") ? `${key} is unsupported for DOCX/PDF content; use $.blocks with heading/paragraph/list/table/image blocks (section is PPTX-only)` : `unsupported property ${JSON.stringify(key)}; allowed properties: ${[...allowed].join(", ")}`;
+    issues.push({ path: `${path}.${key}`, code: "UNKNOWN_PROPERTY", message });
+  }
+}
+function nonBlankString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+function validateTextBlock(value, path, issues) {
+  if (!isJsonRecord(value)) {
+    issues.push({ path, code: "INVALID_TYPE", message: "block must be an object" });
+    return false;
+  }
+  if (typeof value.type !== "string") {
+    issues.push({ path: `${path}.type`, code: "INVALID_TYPE", message: "block type must be a string" });
+    return false;
+  }
+  const requireText = () => {
+    if (nonBlankString(value.text))
+      return true;
+    issues.push({ path: `${path}.text`, code: "EMPTY_CONTENT", message: "text must be a non-empty string" });
+    return false;
+  };
+  switch (value.type) {
+    case "heading": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "text", "level"]), path, issues);
+      const valid = requireText();
+      if (value.level !== void 0 && ![1, 2, 3, 4].includes(value.level)) {
+        issues.push({ path: `${path}.level`, code: "INVALID_VALUE", message: "level must be one of 1, 2, 3, 4" });
+      }
+      return valid;
+    }
+    case "paragraph": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "text", "bold", "italic"]), path, issues);
+      const valid = requireText();
+      for (const key of ["bold", "italic"]) {
+        if (value[key] !== void 0 && typeof value[key] !== "boolean") {
+          issues.push({ path: `${path}.${key}`, code: "INVALID_TYPE", message: `${key} must be a boolean` });
+        }
+      }
+      return valid;
+    }
+    case "list": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "items", "ordered"]), path, issues);
+      if (!Array.isArray(value.items) || value.items.length === 0) {
+        issues.push({ path: `${path}.items`, code: "EMPTY_CONTENT", message: "items must be a non-empty string array" });
+        return false;
+      }
+      let valid = true;
+      value.items.forEach((item, index) => {
+        if (nonBlankString(item))
+          return;
+        valid = false;
+        issues.push({ path: `${path}.items[${index}]`, code: "EMPTY_CONTENT", message: "list item must be a non-empty string" });
+      });
+      if (value.ordered !== void 0 && typeof value.ordered !== "boolean") {
+        issues.push({ path: `${path}.ordered`, code: "INVALID_TYPE", message: "ordered must be a boolean" });
+      }
+      return valid;
+    }
+    case "table": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "rows", "header", "columnWidths"]), path, issues);
+      if (!Array.isArray(value.rows) || value.rows.length === 0) {
+        issues.push({ path: `${path}.rows`, code: "EMPTY_CONTENT", message: "rows must be a non-empty array" });
+        return false;
+      }
+      let hasCellContent = false;
+      value.rows.forEach((row, rowIndex) => {
+        if (!Array.isArray(row) || row.length === 0) {
+          issues.push({ path: `${path}.rows[${rowIndex}]`, code: "INVALID_TYPE", message: "table row must be a non-empty array" });
+          return;
+        }
+        row.forEach((cell, columnIndex) => {
+          if (typeof cell !== "string" && typeof cell !== "number") {
+            issues.push({ path: `${path}.rows[${rowIndex}][${columnIndex}]`, code: "INVALID_TYPE", message: "table cell must be a string or number" });
+          } else if (String(cell).trim().length > 0) {
+            hasCellContent = true;
+          }
+        });
+      });
+      if (!hasCellContent) {
+        issues.push({ path: `${path}.rows`, code: "EMPTY_CONTENT", message: "table must contain at least one non-empty cell" });
+      }
+      if (value.header !== void 0 && typeof value.header !== "boolean") {
+        issues.push({ path: `${path}.header`, code: "INVALID_TYPE", message: "header must be a boolean" });
+      }
+      if (value.columnWidths !== void 0 && (!Array.isArray(value.columnWidths) || value.columnWidths.some((width) => typeof width !== "number" || !Number.isFinite(width) || width <= 0))) {
+        issues.push({ path: `${path}.columnWidths`, code: "INVALID_VALUE", message: "columnWidths must contain only positive finite numbers" });
+      }
+      return hasCellContent;
+    }
+    case "image": {
+      addUnknownPropertyIssues(value, /* @__PURE__ */ new Set(["type", "data", "imageType", "width", "height"]), path, issues);
+      if (!nonBlankString(value.data)) {
+        issues.push({ path: `${path}.data`, code: "EMPTY_CONTENT", message: "image data must be non-empty base64" });
+        return false;
+      }
+      if (value.imageType !== void 0 && !["png", "jpg", "gif", "bmp"].includes(String(value.imageType))) {
+        issues.push({ path: `${path}.imageType`, code: "INVALID_VALUE", message: "imageType must be png, jpg, gif, or bmp" });
+      }
+      for (const key of ["width", "height"]) {
+        if (value[key] !== void 0 && (typeof value[key] !== "number" || !Number.isFinite(value[key]) || value[key] <= 0)) {
+          issues.push({ path: `${path}.${key}`, code: "INVALID_VALUE", message: `${key} must be a positive finite number` });
+        }
+      }
+      return true;
+    }
+    default:
+      issues.push({ path: `${path}.type`, code: "INVALID_VALUE", message: `unhandled block type: ${value.type}` });
+      return false;
+  }
+}
+function inspectTextDocumentSpec(spec) {
+  const issues = [];
+  if (!isJsonRecord(spec)) {
+    issues.push({ path: "$", code: "INVALID_TYPE", message: "spec must be a JSON object" });
+    return { issues, hasBody: false, hasTitle: false, allowCoverOnly: false };
+  }
+  addUnknownPropertyIssues(spec, TEXT_DOCUMENT_KEYS, "$", issues);
+  const hasTitle = nonBlankString(spec.title);
+  if (spec.title !== void 0 && !hasTitle) {
+    issues.push({ path: "$.title", code: "EMPTY_CONTENT", message: "title must be a non-empty string when provided" });
+  }
+  if (spec.allowCoverOnly !== void 0 && typeof spec.allowCoverOnly !== "boolean") {
+    issues.push({ path: "$.allowCoverOnly", code: "INVALID_TYPE", message: "allowCoverOnly must be a boolean" });
+  }
+  if (spec.fontPath !== void 0 && !nonBlankString(spec.fontPath)) {
+    issues.push({ path: "$.fontPath", code: "INVALID_TYPE", message: "fontPath must be a non-empty string" });
+  }
+  let hasBody = false;
+  if (spec.paragraphs !== void 0) {
+    if (!Array.isArray(spec.paragraphs)) {
+      issues.push({ path: "$.paragraphs", code: "INVALID_TYPE", message: "paragraphs must be a string array" });
+    } else {
+      spec.paragraphs.forEach((paragraph, index) => {
+        if (nonBlankString(paragraph))
+          hasBody = true;
+        else
+          issues.push({ path: `$.paragraphs[${index}]`, code: "EMPTY_CONTENT", message: "paragraph must be a non-empty string" });
+      });
+    }
+  }
+  if (spec.blocks !== void 0) {
+    if (!Array.isArray(spec.blocks)) {
+      issues.push({ path: "$.blocks", code: "INVALID_TYPE", message: "blocks must be an array" });
+    } else {
+      spec.blocks.forEach((block, index) => {
+        if (validateTextBlock(block, `$.blocks[${index}]`, issues))
+          hasBody = true;
+      });
+    }
+  }
+  return { issues, hasBody, hasTitle, allowCoverOnly: spec.allowCoverOnly === true };
+}
 function assertTextDocumentSpec(spec) {
-  if (!spec || typeof spec !== "object")
+  const { issues } = inspectTextDocumentSpec(spec);
+  if (issues.length > 0)
+    throw new DocumentSpecValidationError(issues);
+}
+function validateRows(rows, path, issues) {
+  if (!Array.isArray(rows) || rows.length === 0) {
+    issues.push({ path, code: "EMPTY_CONTENT", message: "rows must be a non-empty array" });
+    return false;
+  }
+  let hasContent = false;
+  rows.forEach((row, rowIndex) => {
+    if (!Array.isArray(row) || row.length === 0) {
+      issues.push({ path: `${path}[${rowIndex}]`, code: "INVALID_TYPE", message: "row must be a non-empty array" });
+      return;
+    }
+    row.forEach((cell, columnIndex) => {
+      if (typeof cell !== "string" && typeof cell !== "number") {
+        issues.push({ path: `${path}[${rowIndex}][${columnIndex}]`, code: "INVALID_TYPE", message: "cell must be a string or number" });
+      } else if (String(cell).trim().length > 0) {
+        hasContent = true;
+      }
+    });
+  });
+  if (!hasContent)
+    issues.push({ path, code: "EMPTY_CONTENT", message: "rows must contain at least one non-empty cell" });
+  return hasContent;
+}
+function assertDocumentSpec(kind, spec) {
+  if (kind === "docx" || kind === "pdf") {
+    const inspection = inspectTextDocumentSpec(spec);
+    if (!inspection.hasBody && !(inspection.allowCoverOnly && inspection.hasTitle)) {
+      inspection.issues.push({
+        path: "$",
+        code: "EMPTY_CONTENT",
+        message: "document body is empty; provide non-empty paragraphs/blocks, or set allowCoverOnly=true with a non-empty title"
+      });
+    }
+    if (inspection.issues.length > 0)
+      throw new DocumentSpecValidationError(inspection.issues);
     return;
-  if (Object.prototype.hasOwnProperty.call(spec, "section")) {
-    throw new Error("unsupported document field: section (use blocks for DOCX/PDF content; section is PPTX-only)");
   }
+  const issues = [];
+  if (!isJsonRecord(spec)) {
+    throw new DocumentSpecValidationError([{ path: "$", code: "INVALID_TYPE", message: "spec must be a JSON object" }]);
+  }
+  if (kind === "xlsx") {
+    addUnknownPropertyIssues(spec, XLSX_DOCUMENT_KEYS, "$", issues);
+    if (!isJsonRecord(spec.sheets) || Object.keys(spec.sheets).length === 0) {
+      issues.push({ path: "$.sheets", code: "EMPTY_CONTENT", message: "sheets must be a non-empty object" });
+    } else {
+      for (const [name, sheet] of Object.entries(spec.sheets)) {
+        const path = `$.sheets[${JSON.stringify(name)}]`;
+        if (Array.isArray(sheet)) {
+          validateRows(sheet, path, issues);
+        } else if (isJsonRecord(sheet)) {
+          addUnknownPropertyIssues(sheet, /* @__PURE__ */ new Set(["rows", "header", "columnWidths", "numFmt"]), path, issues);
+          validateRows(sheet.rows, `${path}.rows`, issues);
+        } else {
+          issues.push({ path, code: "INVALID_TYPE", message: "sheet must be a row array or an object containing rows" });
+        }
+      }
+    }
+  } else if (kind === "pptx") {
+    addUnknownPropertyIssues(spec, PPTX_DOCUMENT_KEYS, "$", issues);
+    if (!Array.isArray(spec.slides) || spec.slides.length === 0) {
+      issues.push({ path: "$.slides", code: "EMPTY_CONTENT", message: "slides must be a non-empty array" });
+    } else {
+      spec.slides.forEach((slide, index) => {
+        const path = `$.slides[${index}]`;
+        if (!isJsonRecord(slide)) {
+          issues.push({ path, code: "INVALID_TYPE", message: "slide must be an object" });
+          return;
+        }
+        addUnknownPropertyIssues(slide, PPTX_SLIDE_KEYS, path, issues);
+        if (Object.keys(slide).length === 0) {
+          issues.push({ path, code: "EMPTY_CONTENT", message: "slide must contain at least one supported field" });
+        }
+      });
+    }
+  } else {
+    throw new Error(`unsupported kind: ${String(kind)}`);
+  }
+  if (issues.length > 0)
+    throw new DocumentSpecValidationError(issues);
 }
 var HEADINGS = [HeadingLevel.HEADING_1, HeadingLevel.HEADING_2, HeadingLevel.HEADING_3, HeadingLevel.HEADING_4];
 var ORDERED_REF = "ol";
@@ -153741,6 +154014,7 @@ async function generatePdf(spec, themeInput) {
   return doc.save();
 }
 async function generateDocument(kind, spec, theme) {
+  assertDocumentSpec(kind, spec);
   switch (kind) {
     case "docx":
       return generateDocx(spec, theme);
@@ -153856,6 +154130,7 @@ function themePrintOptions(themeInput, title) {
 // apps/admin/data/skills.lib/document/bin-src/doc-gen.mjs
 var import_node_path = require("node:path");
 var import_node_fs2 = require("node:fs");
+var import_node_crypto = require("node:crypto");
 
 // packages/core/dist/fs/tpl-interp.js
 var TAG = /\{\{\{?\s*([#/]?)\s*([^}]*?)\s*\}?\}\}/g;
@@ -154596,6 +154871,21 @@ function die(msg, code = 1) {
 `);
   process.exit(code);
 }
+async function writeArtifactAtomically(out, bytes) {
+  const temp = (0, import_node_path.join)((0, import_node_path.dirname)(out), `.${(0, import_node_path.basename)(out)}.${process.pid}.${(0, import_node_crypto.randomUUID)()}.tmp`);
+  try {
+    await (0, import_promises.writeFile)(temp, Buffer.from(bytes), { flag: "wx" });
+    await (0, import_promises.rename)(temp, out);
+  } catch (error) {
+    try {
+      await (0, import_promises.rm)(temp, { force: true });
+    } catch (cleanupError) {
+      process.stderr.write(`doc-gen: cleanup failed for ${temp}: ${cleanupError instanceof Error ? cleanupError.message : String(cleanupError)}
+`);
+    }
+    throw error;
+  }
+}
 async function renderDesignHtml(spec, theme) {
   const { html, unsupported } = buildDeckHtml(spec, theme);
   if (unsupported.length) {
@@ -154698,6 +154988,11 @@ async function main() {
   } catch (e) {
     die(`bad spec: ${e.message}`, 64);
   }
+  try {
+    assertDocumentSpec(kind, spec);
+  } catch (e) {
+    die(e instanceof Error ? e.message : String(e), e?.code === "DOC_SPEC_INVALID" ? 65 : 64);
+  }
   if (paletteFlag) spec.palette = paletteFlag;
   if (topicFlag) spec.topic = topicFlag;
   let rawTheme = spec.theme;
@@ -154751,8 +155046,10 @@ async function main() {
     if (kind === "pdf") engine = "pdf (pdf-lib)";
     else if (kind === "pptx" && design === "html") engine = "pptx (native fallback)";
   }
-  await (0, import_promises.writeFile)(out, Buffer.from(bytes));
+  await writeArtifactAtomically(out, bytes);
   process.stdout.write(`wrote ${out}${kind === "pdf" || kind === "pptx" && design === "html" ? ` [${engine}]` : ""}
 `);
 }
-main();
+main().catch((error) => {
+  die(error instanceof Error ? error.message : String(error), 1);
+});

package/skills/document/rewrite.md

@@ -205,6 +205,12 @@ Simple spec shapes:
 - **xlsx**: `{ "sheets": { "SheetName": [["h1","h2"], ["a", 1], ...] } }` (row 1 = bold header)
 - **pptx**: `{ "slides": [{ "title"?: "...", "bullets"?: ["...", ...] }] }`
 
+`doc-gen` validates these shapes **strictly before rendering**: unknown fields are
+errors, not ignored. For DOCX/PDF use `paragraphs` and/or `blocks`—never
+`sections`. A title-only artifact also fails unless it is intentional and the
+spec explicitly sets `"allowCoverOnly": true`; on `DOC_SPEC_INVALID`, correct
+the reported JSON path and rerun rather than delivering the previous output.
+
 Rich spec shapes (use these for real documents, not just prose):
 - **docx** `blocks`: ordered list of
   - `{ "type": "heading", "text": "...", "level": 1..4 }`

package/mcp/.gitkeep

@@ -1,8 +0,0 @@
-# Placeholder for shared MCP servers.
-#
-# Each shared MCP package lives at `mcp/<pkg>/mcp.json` — the client extracts
-# this directory tree into `~/.talos/bundled/shared/mcp/` and every OSE
-# auto-merges the servers in without opt-in (P12b / docs/02-ose-and-prompt.md). The mcp.json
-# shape matches per-OSE `bundled/<id>/mcp.json`: `{ version, servers: { ... } }`.
-#
-# Delete this file once at least one real shared MCP package lands here.

package/skills/.gitkeep

@@ -1,7 +0,0 @@
-# Placeholder for shared skills.
-#
-# Each shared skill lives at `skills/<name>/SKILL.md` — the client extracts
-# this directory tree into `~/.talos/bundled/shared/skills/` and every OSE
-# auto-loads the skills without opt-in (P12b / docs/02-ose-and-prompt.md).
-#
-# Delete this file once at least one real shared skill lands here.