dsh-office-kit 0.0.0-stage → 0.2.0

package/CAPABILITY.md

@@ -0,0 +1,75 @@
+# Capability report
+
+This file records what the plugin actually does, how each capability maps from the original skills, what was verified, and what remains unsupported. It is intentionally conservative: a feature is listed as supported only after a working command path and a check exist.
+
+## Capability trace
+
+| User capability | Original mechanism | DSH execution chain | Acceptance | State |
+| --- | --- | --- | --- | --- |
+| Create a DOCX report | `documents` skill; Python OOXML scripts; `mark_artifact_operation_started.mjs` | `/documents` chip → `office-documents` skill → `office_status` → `office_cli.py docx create/edit` (python-docx, OMML) → Word/LibreOffice render → PNG inspection | Create with headings, lists, table, image, equation, header/footer; read back counts; edit text and append section; equation survives; rendered page inspected | Supported |
+| Read a DOCX | Same skill | `docx read` → JSON counts/text/tables/images | Counts and text match the created document | Supported |
+| Create a PDF | `pdf` skill; reportlab/pdfplumber/pypdf | `/pdf` chip → `office-pdf` skill → `office_cli.py pdf create/read/edit/render` | Chinese text embeds with registered CJK font; read extracts text; metadata edit; PyMuPDF render inspected | Supported |
+| Inspect a PDF | Same | `pdf read` → page count, text, metadata, form fields | Page count and Chinese/English text extracted | Supported |
+| Edit a PDF | Same | `pdf edit` → metadata, rotate, merge, remove pages | Metadata edit and read-back verified | Supported |
+| Create/edit a PPTX | `presentations` skill; `@oai/artifact-tool` | `/presentations` chip → `office-presentations` skill → `office_cli.py pptx create/edit` (python-pptx) → PowerPoint/LibreOffice render | Three slides with bullets, table, chart, image; edit text and append a slide; four rendered pages inspected; layout overlap fixed with explicit coordinates | Supported, with a different authoring engine than the original |
+| Create/edit an XLSX | `spreadsheets` skill; `@oai/artifact-tool` | `/spreadsheets` chip → `office-spreadsheets` skill → `office_cli.py xlsx create/edit/recalc` (openpyxl + Excel COM) | Formulas, styles, widths, frozen panes, chart; edit cells/append rows; Excel recalculation persists cached values (`40`, `58`, `228`); data-only read confirms | Supported, with a different authoring engine than the original |
+| Render for visual QA | Original render helpers / artifact tool | `render` → Microsoft Office COM (Word/PowerPoint/Excel) or LibreOffice headless; PyMuPDF for PDF | DOCX page, PPTX pages, PDF page rendered and inspected | Supported when a renderer exists; explicit error otherwise |
+| `/` menu with names and icons | Original skill menu (not `InputTrigger`) | Public `ctx.inputTriggers` source named `office`; four candidates with Gravity UI Icons SVGs and locale labels | Typecheck/build; not yet exercised in a running DSH window | Implemented, GUI interaction unverified |
+| Enter → reference chip | Original artifact reference | `onPick` returns `ReferenceInsert`; host `codec` persists `/documents` and serializes a skill instruction | Build/typecheck; chip persistence is the documented public contract, not live-tested | Implemented, GUI interaction unverified |
+| Chip preview | Original skill preview | `openReference` maps feature id → skill name → `SKILL.md` path → `sidebarRight.openResource` | Code path implemented; GUI unverified | Implemented, GUI unverified |
+| Python setup | Original bundled runtime | `postinstall.mjs` detect/download/verify/install/venv/pip/import check/config/PATH | Auto-install path not run (a working Python already existed); venv creation, dependency install, import verification, config write, idempotent rerun all verified | Supported; installer download path unverified in this environment |
+
+## Dependency mapping
+
+| Original dependency | DSH replacement | Notes |
+| --- | --- | --- |
+| `load_workspace_dependencies` | `office_status` + absolute paths embedded in each skill body | No hidden workspace loader; the host verifies the interpreter and packages. |
+| `mark_artifact_operation_started.mjs` | None | It only marked artifact sessions in the original runtime; DSH has no equivalent and the CLI does not pretend to. |
+| `@oai/artifact-tool` (PPTX/XLSX) | `python-pptx`, `openpyxl` | Different API and some different capabilities; see limits. |
+| Google Drive/Slides/Sheets plugins | None | Remote editing is explicitly unsupported, not silently replaced by local files. |
+| Original render helpers | Microsoft Office COM or LibreOffice headless; PyMuPDF | Renderer availability is reported by `office_status`. |
+| Original `agents/openai.yaml` manifests | DSH skill frontmatter + `ctx.skills.registerProvider` | The four DSH skills live in `assets/skills`. |
+
+## Python and renderer environment
+
+- Python: 3.12.12 in `%LOCALAPPDATA%\dsh-office-kit\venv`, created by `postinstall.mjs` from an existing CPython 3.12.12.
+- Installed and import-verified: python-docx 1.2.0, openpyxl 3.1.5, python-pptx 1.0.2, pypdf 6.21.1, reportlab 4.5.1, pdfplumber 0.11.9, PyMuPDF 1.28.2, Pillow 11.3.0, latex2mathml 3.81.1, mathml2omml 0.0.2.
+- Renderers: Microsoft Word/PowerPoint/Excel 16 installed. LibreOffice is not installed on this machine. OCR (`tesseract`) and Poppler `pdftoppm` are not installed; PDF rendering uses PyMuPDF instead.
+
+## Verification evidence
+
+Run on Windows, 2026-10-20, in paths containing Chinese characters and spaces.
+
+| Check | Result |
+| --- | --- |
+| `pnpm run typecheck` | Passed |
+| `pnpm run build` | Passed; `dist/index.js`, `dist/index.d.ts`, `dist/client.js` generated |
+| `pnpm run test -- --run` | 14 passed across 2 files (10 in `test/office-cli.test.ts`) |
+| DOCX create/read/edit/render | Passed; rendered page inspected: Chinese header/title/body/table/equation/image/footer |
+| PDF create/read/edit/render | Passed; Chinese text extracted, metadata edit, page rendered |
+| PPTX create/read/edit/render | Passed; four slides rendered; table/chart/image layout fixed and inspected |
+| XLSX create/read/edit/recalc | Passed; formulas preserved; Excel recalculation produced cached values; data-only read confirmed |
+| `postinstall.mjs` first run | Passed; venv created, 10 packages installed, imports verified, config written |
+| `postinstall.mjs` second run | Passed in 2.7 s; idempotent |
+| `PATH` update | Registry write blocked by this Windows sandbox; plugin now warns instead of claiming success; absolute-path resolution works |
+| Chinese + spaces path | Used for every integration test |
+| Missing/incompatible Python | `resolvePython` reports `found: false` or `compatible: false`; skill bodies tell the agent to stop and ask for repair instead of running |
+| Interrupted installer | Download uses a unique temp filename per process; stale locked installers no longer block a retry |
+| `pnpm run lint --fix` | Passed |
+
+## Unsupported (explicit)
+
+- Google Docs, Google Slides, Google Sheets, Google Drive import/export, or any online document editing.
+- `@oai/artifact-tool`-only behavior and its artifact-session lifecycle.
+- DOCX comments, tracked changes, TOC fields, watermarks, redaction, content controls, template-style transfer, and accessibility audit.
+- PDF OCR, AcroForm filling, signing, redaction, and page-level text editing.
+- PPTX animations, speaker notes, template slide masters, and morph transitions.
+- XLSX pivot tables, macros, data validation, conditional formatting, and shared-workbook features.
+- Installing LibreOffice or Python on macOS/Linux; the plugin detects and reports, but only Windows auto-installs Python.
+- Live GUI interaction (menu open, chip insertion, chip persistence, right-sidebar preview) was not exercised in a running DSH window. It compiles against the public `0.2.1-rc.2` types, but installation into the user's profile was intentionally not performed.
+
+## UI API constraints recorded during implementation
+
+- The public composer `ReferenceChip` shows a custom icon only for `session`, `file`, and `folder`. This plugin uses `appearance: 'file'` in the composer, so the chip shows the built-in file glyph plus the friendly format label. The `/` menu candidates and transcript chips use four Gravity UI Icons SVGs (`file-text`, `file-letter-p`, `display`, `layout-cells`), vendored in `assets/icons` under MIT.
+- `matchEnter` cannot create a reference chip; Enter on a highlighted `/` candidate goes through the source's `onPick`, which is the implemented path.
+- The chip's stable internal ref is the feature id; clipboard/persistence text is `/documents` etc.; model serialization names the skill explicitly so the agent loads it before file work.

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025-PRESENT dsh-tauri-desk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,106 @@
-# Temporary Holding Version
+<div align="center"><a name="readme-top"></a>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<img src="./public/hero.png" alt="安装插件" />
+
+# DSH Office Kit
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![bundle][bundle-src]][bundle-href]
+[![JSDocs][jsdocs-src]][jsdocs-href]
+[![License][license-src]][license-href]
+
+为 DeepSeek Harness (DSH) 提供本地 Word、PDF、演示文稿与电子表格能力，支持 `/` 菜单、引用 Chip，以及侧边栏预览中的选区标注与修改请求。
+</div>
+
+## 📦 安装
+
+在官方插件中安装 `dsh-office-kit`
+
+<img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/install.png" alt="安装插件" />
+
+或使用命令行安装
+
+```sh
+dsh plugin add dsh-office-kit
+```
+
+- 在 **设置 → 插件** 中启用。
+- 需要 DSH ≥ `0.2.1-rc.2`、Python(无需，没有将自动安装) `3.10`–`3.13`。
+- Windows 缺少兼容 Python 时自动安装；macOS / Linux 使用现有 Python。
+
+## 特性
+
+- 📝 **Word**：`/documents` 创建、读取和编辑 DOCX，支持表格、图片、公式与页眉页脚。
+- 📄 **PDF**：`/pdf` 创建、读取和编辑 PDF，支持合并、旋转、删页与元数据。
+- 📽️ **演示文稿**：`/presentations` 创建、读取和编辑 PPTX，支持项目符号、表格、图表与图片。
+- 📊 **电子表格**：`/spreadsheets` 创建、读取和编辑 XLSX，支持公式、样式、图表、冻结窗格与重算。
+- 🖍️ **侧边栏标注**：在 PDF、DOC/DOCX 预览中吸附段落或框选区域，批量提交修改要求。
+- 🔗 **会话引用**：通过 Chip 调用文档技能；注释链接可悬停查看文件名与要求，PDF 标注附选区截图。
+
+## 🚀 快速开始
+
+### 通过菜单处理文档
+
+<img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/image.png" alt="Office 菜单与文档预览" />
+
+1. 在输入框键入 `/`，选择 **文档**、**PDF 文档**、**演示文稿** 或 **电子表格**。
+2. 回车插入 Chip，描述创建、读取或修改任务。
+3. 打开生成的文件，在侧边栏预览结果。
+
+
+### 在预览中请求修改
+
+| <img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/annotation-selection.png" alt="段落吸附与修改要求输入" /> | <img src="https://raw.githubusercontent.com/hairyf/dsh-office-kit/refs/heads/main/public/annotation-conversation.png" alt="注释列表与会话引用" /> |
+| ------------- | ------------- |
+
+1. 打开 PDF 或 DOC/DOCX，点击工具栏的 **请求修改**。
+2. 悬停吸附段落，点击或拖动框选，输入要求并添加注释。
+3. 悬停底部 **注释数量** 查看列表，点击 **发送**；**取消** 清空本批。
+
+- **Esc**：先取消当前选区，再按一次退出标注模式。
+- **附件**：PDF 附选区截图；DOC/DOCX 仅发送文字与定位信息。
+- **草稿**：已有输入时先合入草稿，由你确认发送；暂存注释刷新后不保留。
+
+## 💡 示例文档
+
+- [Word](<public/samples/sample.docx>)
+- [PDF](<public/samples/sample.pdf>)
+- [演示文稿](<public/samples/sample.pptx>)
+- [电子表格](<public/samples/sample.xlsx>)
+- [来源与许可](<public/samples/README.md>)
+
+## 📚 配置与限制
+
+- **Python**：`DSH_OFFICE_PYTHON` 可指定解释器。
+- **标注范围**：仅 PDF、DOC/DOCX；扫描 PDF 可框选截图，不提供 OCR。
+- **本地文件**：不支持 Google Docs / Slides / Sheets 或远程编辑。
+- **完整清单**：[能力与未支持项](<CAPABILITY.md>)。
+
+## 🛠️ 开发与贡献
+
+```sh
+pnpm install
+pnpm run lint --fix
+pnpm run typecheck
+pnpm run test -- --run
+pnpm run build
+```
+
+## 📜️ 许可证
+
+- [MIT](<LICENSE.md>)
+- 示例文档保留 [Apache Tika 的许可与声明](<public/samples/README.md>)。
+
+<!-- Badges -->
+
+[npm-version-src]: https://img.shields.io/npm/v/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669
+[npm-version-href]: https://npmjs.com/package/dsh-office-kit
+[npm-downloads-src]: https://img.shields.io/npm/dm/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669
+[npm-downloads-href]: https://npmjs.com/package/dsh-office-kit
+[bundle-src]: https://img.shields.io/bundlephobia/minzip/dsh-office-kit?style=flat&colorA=080f12&colorB=1fa669&label=minzip
+[bundle-href]: https://bundlephobia.com/result?p=dsh-office-kit
+[license-src]: https://img.shields.io/github/license/hairyf/dsh-office-kit.svg?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: https://github.com/hairyf/dsh-office-kit/blob/main/LICENSE
+[jsdocs-src]: https://img.shields.io/badge/jsdocs-reference-080f12?style=flat&colorA=080f12&colorB=1fa669
+[jsdocs-href]: https://www.jsdocs.io/package/dsh-office-kit

package/assets/icons/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2022 YANDEX LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/assets/icons/README.md

@@ -0,0 +1,9 @@
+Gravity UI Icons
+https://github.com/gravity-ui/icons
+
+The SVG files in this directory are copied from Gravity UI Icons at:
+https://github.com/gravity-ui/icons/tree/main/svgs
+
+comment-fill.svg is the CommentFill icon from @gravity-ui/icons 2.21.0; its shape is also used by the annotation cursor.
+
+License: MIT (see LICENSE in this directory).

package/assets/icons/comment-fill.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M8 13c3.866 0 7-2 7-6s-3.134-6-7-6-7 2-7 6c0 2.16.914 3.737 2.364 4.73l.09 2.161a1.157 1.157 0 0 0 1.857.872l2.322-1.77Q7.816 13 8 13" clip-rule="evenodd"/></svg>

package/assets/icons/display.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M12 3H4a1.5 1.5 0 0 0-1.5 1.5v4A1.5 1.5 0 0 0 4 10h8a1.5 1.5 0 0 0 1.5-1.5v-4A1.5 1.5 0 0 0 12 3M4 1.5a3 3 0 0 0-3 3v4a3 3 0 0 0 3 3h3.25V13h-2.5a.75.75 0 0 0 0 1.5h6.5a.75.75 0 0 0 0-1.5h-2.5v-1.5H12a3 3 0 0 0 3-3v-4a3 3 0 0 0-3-3z" clip-rule="evenodd"/></svg>

package/assets/icons/file-letter-p.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M11 13.5H5A1.5 1.5 0 0 1 3.5 12V4A1.5 1.5 0 0 1 5 2.5h2.757a1.5 1.5 0 0 1 1.061.44l3.243 3.242a1.5 1.5 0 0 1 .439 1.06V12a1.5 1.5 0 0 1-1.5 1.5m2.121-8.379A3 3 0 0 1 14 7.243V12a3 3 0 0 1-3 3H5a3 3 0 0 1-3-3V4a3 3 0 0 1 3-3h2.757a3 3 0 0 1 2.122.879zM6.5 6.5a.75.75 0 0 0-.75.75v4a.75.75 0 0 0 1.5 0v-.75H8.5a2 2 0 1 0 0-4zm2 2.5H7.25V8H8.5a.5.5 0 0 1 0 1" clip-rule="evenodd"/></svg>

package/assets/icons/file-text.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M5 13.5h6a1.5 1.5 0 0 0 1.5-1.5V7.243a1.5 1.5 0 0 0-.44-1.061L8.819 2.939a1.5 1.5 0 0 0-1.06-.439H5A1.5 1.5 0 0 0 3.5 4v8A1.5 1.5 0 0 0 5 13.5m9-6.257a3 3 0 0 0-.879-2.122L9.88 1.88A3 3 0 0 0 7.757 1H5a3 3 0 0 0-3 3v8a3 3 0 0 0 3 3h6a3 3 0 0 0 3-3zM5 8.25a.75.75 0 0 1 .75-.75h4.5a.75.75 0 0 1 0 1.5h-4.5A.75.75 0 0 1 5 8.25m.75 2.25a.75.75 0 0 0 0 1.5h2.5a.75.75 0 0 0 0-1.5z" clip-rule="evenodd"/></svg>

package/assets/icons/layout-cells.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" fill="none" viewBox="0 0 16 16"><path fill="currentColor" fill-rule="evenodd" d="M9.25 3.5h-2.5v2h2.5zM4 3.5h1.25v2H2.5V5A1.5 1.5 0 0 1 4 3.5M2.5 7h2.75v2H2.5zm0 3.5v.5A1.5 1.5 0 0 0 4 12.5h1.25v-2zm4.25 0v2h2.5v-2zm4 0v2H12a1.5 1.5 0 0 0 1.5-1.5v-.5zM13.5 9h-2.75V7h2.75zM9.25 9h-2.5V7h2.5zm1.5-5.5v2h2.75V5A1.5 1.5 0 0 0 12 3.5zM4 2a3 3 0 0 0-3 3v6a3 3 0 0 0 3 3h8a3 3 0 0 0 3-3V5a3 3 0 0 0-3-3z" clip-rule="evenodd"/></svg>

package/assets/skills/office-documents/SKILL.md

@@ -0,0 +1,101 @@
+---
+description: Create, inspect, edit, and render Word .docx documents with the bundled Office helper CLI.
+---
+
+# Documents (.docx)
+
+Create, read, edit, and render local Word documents. This skill produces Office Open XML files; it does not edit Google Docs and does not use the artifact-tool runtime.
+
+## Before any file work
+
+1. Call the `office_status` tool.
+2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file. These are verified absolute paths; do not assume `python` or `soffice` is on `PATH`.
+3. If the runtime block says no compatible Python was found, stop and tell the user to run the package install/rebuild step. Do not fabricate a document or claim success.
+
+Quote every path. Windows paths and paths containing spaces, Chinese characters, or `&` are supported.
+
+## Create
+
+Write a JSON spec in the user's workspace, then run:
+
+```bash
+"<python>" "<cli>" docx create --spec "<spec.json>" --out "<output.docx>"
+```
+
+Minimal spec:
+
+```json
+{
+  "title": "Quarterly Report",
+  "subtitle": "Internal review",
+  "author": "Prepared by DSH Office Suite",
+  "header": "Confidential",
+  "footer": "Page 1",
+  "page_size": "A4",
+  "orientation": "portrait",
+  "blocks": [
+    { "type": "heading", "level": 1, "text": "Executive summary" },
+    { "type": "paragraph", "text": "Revenue grew 18.4% year over year." },
+    { "type": "bullets", "items": ["Renewal rate 92%", "42 new customers"] },
+    { "type": "table", "headers": ["Metric", "Q3"], "rows": [["Revenue", "12,480,000"], ["Gross margin", "71.2%"]] },
+    { "type": "equation", "latex": "\\frac{a^2+b^2}{c^2}" },
+    { "type": "page_break" }
+  ]
+}
+```
+
+Supported block types: `heading` (`level` 0–9), `paragraph` (`bold`, `italic`, `size`, `color`, `align`, `style`), `bullets`, `numbered`, `table` (`headers`, `rows`, optional `style`, default `Table Grid`), `image` (`path`, optional `width` in inches), `equation` (`latex`), `quote`, `page_break`, `spacer`. Page fields: `page_size` (`Letter` or `A4`), `orientation`, margins in inches (`top_margin`, `bottom_margin`, `left_margin`, `right_margin`).
+
+LaTeX equations are converted to native OMML. Simple fractions, superscripts, subscripts, roots, and Greek symbols work; unsupported LaTeX silently falls back to italic text and increments `equation_fallbacks`. Check that counter when the equation matters.
+
+## Read
+
+```bash
+"<python>" "<cli>" docx read --input "<file.docx>"
+```
+
+Returns title, author, paragraphs with styles, headings, tables, image count, equation count, and page dimensions. Use it to verify a file you did not create.
+
+## Edit
+
+Copy-then-edit: the CLI never modifies the input in place.
+
+```bash
+"<python>" "<cli>" docx edit --input "<file.docx>" --spec "<edit.json>" --out "<file-edited.docx>"
+```
+
+```json
+{
+  "replace": [{ "find": "37 customers", "replace": "42 customers" }],
+  "blocks": [{ "type": "heading", "level": 1, "text": "Appendix" }],
+  "core": { "title": "Quarterly Report (final)", "author": "Finance" }
+}
+```
+
+`replace` works on runs and falls back to rebuilding a paragraph when the text spans runs. It cannot reliably edit headers/footers, comments, tracked changes, content controls, or fields; those are unsupported (see below). Adding blocks appends them at the end of the body.
+
+## Render and verify
+
+```bash
+"<python>" "<cli>" docx render --input "<file.docx>" --out-dir "<render-dir>"
+```
+
+The renderer prefers Microsoft Word COM on Windows and LibreOffice otherwise. It writes a PDF and one PNG per page. Open the PNGs with your image-viewing tool and inspect: title/heading hierarchy, table geometry, page breaks, missing glyphs, overflowing text, header/footer, and equation rendering.
+
+If no renderer is available, report "not visually verified" and offer the file. Do not claim layout quality you did not see.
+
+## Quality rules
+
+- Write real content from the user's request; never invent metrics, citations, or names.
+- Use one consistent heading hierarchy. Do not skip levels.
+- Keep tables narrow enough for the page; abbreviate long headers.
+- Verify a non-Latin script renders in the chosen fonts before delivering.
+- Prefer native Word structures (headings, tables, lists) over hand-positioned text.
+
+## Not supported
+
+- Google Docs / Google Drive import or native online editing.
+- Comments, tracked changes, redlining, accept/reject workflows.
+- Existing headers/footers, footnotes, TOC fields, cross-references, content controls, protection, watermarks, redaction.
+- In-place editing, macros, encrypted documents, `.doc` input.
+- Word-perfect pagination or template cloning. `render` is a fidelity check, not a guarantee that Word and LibreOffice paginate identically.

package/assets/skills/office-pdf/SKILL.md

@@ -0,0 +1,86 @@
+---
+description: Create, read, edit, merge, rotate, and render PDF files with the bundled Office helper CLI.
+---
+
+# PDF
+
+Create PDFs, extract their content, edit metadata/pages, and rasterize them for visual verification. This skill handles local files only; OCR and cloud PDF services are out of scope.
+
+## Before any file work
+
+1. Call the `office_status` tool.
+2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file. They are verified absolute paths.
+3. If no compatible Python is reported, stop and tell the user how to install it. Never claim a PDF was produced when the CLI was unavailable.
+
+## Create
+
+```bash
+"<python>" "<cli>" pdf create --spec "<spec.json>" --out "<output.pdf>"
+```
+
+```json
+{
+  "title": "Product Brief",
+  "author": "DSH Office Suite",
+  "page_size": "A4",
+  "blocks": [
+    { "type": "heading", "level": 1, "text": "Product Brief" },
+    { "type": "paragraph", "text": "This PDF contains Chinese, English, numbers, and punctuation." },
+    { "type": "bullets", "items": ["Fast", "Local", "Verifiable"] },
+    { "type": "table", "headers": ["Item", "Value"], "rows": [["Version", "1.0"], ["Status", "Draft"]] },
+    { "type": "image", "path": "<absolute image path>", "width": 4.5 },
+    { "type": "page_break" }
+  ]
+}
+```
+
+Supported blocks: `title`, `heading` (`level` 1–2), `paragraph`, `quote`, `bullets`, `numbered`, `table`, `image` (`path`, `width` inches; height is derived at 0.66 aspect), `page_break`, `spacer` (`height` inches). Use `pages: [{ "blocks": [...], "break": true }]` for explicit page grouping.
+
+CJK text uses the first available system font (`msyh`, `simsun`, PingFang, Noto Sans CJK, DejaVu). If no CJK font exists, Chinese characters may render as blanks; verify before delivery.
+
+## Read
+
+```bash
+"<python>" "<cli>" pdf read --input "<file.pdf>"
+```
+
+Returns `page_count`, `word_count`, metadata, per-page text and character counts, AcroForm field identifiers, and `ocr: { available: false }`. Extraction quality depends on the source PDF (scanned pages have no text layer).
+
+## Edit
+
+```bash
+"<python>" "<cli>" pdf edit --input "<file.pdf>" --spec "<edit.json>" --out "<file-edited.pdf>"
+```
+
+```json
+{
+  "metadata": { "Title": "Product Brief (final)", "Author": "DSH Office Suite" },
+  "merge": ["<other.pdf>"],
+  "rotate": 90,
+  "pages": [0],
+  "remove_pages": [2]
+}
+```
+
+- `merge` appends pages from other PDFs.
+- `rotate` is degrees clockwise; `pages` limits it to zero-based page indexes.
+- `remove_pages` is zero-based and applied to the original pages; merged pages are appended after.
+- Metadata keys may be plain (`Title`) or PDF names (`/Title`); the CLI normalizes them.
+
+The input file is never modified.
+
+## Render and verify
+
+```bash
+"<python>" "<cli>" pdf render --input "<file.pdf>" --out-dir "<render-dir>" --dpi 110
+```
+
+Renders every page to PNG with PyMuPDF. Open the images and check page count, clipping, overlap, missing glyphs, and scanned-page readability. If `read` returns little text and the render shows an image of text, OCR is required; say so instead of pretending the text was extracted.
+
+## Not supported
+
+- OCR / scanned-document text recognition.
+- Filling, creating, or flattening AcroForms (field identifiers are reported for inspection only).
+- Digital signatures, encryption/password handling, redaction, annotations, bookmarks editing.
+- PDF/A, tagged-PDF accessibility repair, or exact reflow of an existing document.
+- Google Drive or other online PDF services.

package/assets/skills/office-presentations/SKILL.md

@@ -0,0 +1,110 @@
+---
+description: Create, inspect, edit, and render PowerPoint .pptx slide decks with the bundled Office helper CLI.
+---
+
+# Presentations (.pptx)
+
+Build local PowerPoint decks with native text, tables, charts, and images, then render them to verify layout. This skill uses `python-pptx`; it does not use the `@oai/artifact-tool` runtime and does not edit Google Slides.
+
+## Before any file work
+
+1. Call the `office_status` tool.
+2. Use the `python` and `cli` values from the `## Office runtime` JSON block at the end of this file.
+3. If no compatible Python is reported, stop and tell the user. Do not deliver a deck you could not create or verify.
+
+## Create
+
+```bash
+"<python>" "<cli>" pptx create --spec "<spec.json>" --out "<output.pptx>"
+```
+
+```json
+{
+  "title": "Annual Review",
+  "author": "DSH Office Suite",
+  "slides": [
+    { "layout": "title", "title": "Annual Review", "subtitle": "FY2026 · Internal" },
+    { "layout": "bullets", "title": "Highlights", "bullets": ["Revenue up 18.4%", { "text": "New markets", "level": 1 }] },
+    {
+      "layout": "blank",
+      "title": "Revenue by quarter",
+      "table": { "headers": ["Quarter", "Revenue"], "rows": [["Q1", 100], ["Q2", 128]] },
+      "chart": {
+        "type": "column",
+        "title": "Quarterly revenue",
+        "left": 3.6,
+        "top": 3.5,
+        "width": 8.8,
+        "height": 3.0,
+        "categories": ["Q1", "Q2"],
+        "series": [{ "name": "Revenue", "values": [100, 128] }]
+      },
+      "image": { "path": "<absolute image path>", "left": 0.8, "top": 3.9, "width": 2.2 }
+    }
+  ]
+}
+```
+
+Layouts: `title`, `bullets`, `section`, `title_only`, `blank`. The deck is 16:9 (13.333 × 7.5 in).
+
+- `bullets` uses the body placeholder; items may be strings or `{ "text", "level" }`.
+- `blank` / `title_only` place content with a vertical cursor starting at 1.5 in. A table advances the cursor; a chart without `top` starts at the cursor and gets a fitted height; an image without `top` starts at the cursor. Explicit `left`/`top`/`width`/`height` in inches are honored, so use them when combining elements side by side.
+- A blank slide with a `title` gets a generated title textbox (32 pt bold).
+- Chart types: `column`, `line`, `pie` (`bar` is accepted as a column alias). Each series needs a `name` and numeric `values`.
+
+## Read
+
+```bash
+"<python>" "<cli>" pptx read --input "<file.pptx>"
+```
+
+Returns slide count, per-slide title, all text, tables, chart categories/series, and image counts. Use it to confirm edits and to inventory a deck you did not create.
+
+## Edit
+
+```bash
+"<python>" "<cli>" pptx edit --input "<file.pptx>" --spec "<edit.json>" --out "<file-edited.pptx>"
+```
+
+```json
+{
+  "replace": [{ "find": "18.4%", "replace": "21.0%" }],
+  "slides": [{ "layout": "bullets", "title": "Next steps", "bullets": ["Finalize acceptance", "Publish docs"] }],
+  "core": { "title": "Annual Review (final)" }
+}
+```
+
+`replace` edits text runs. It cannot edit text split across runs, chart data labels, notes, or tables; use table replacement only by recreating the table on a new slide. New slides are appended.
+
+## Render and verify
+
+```bash
+"<python>" "<cli>" pptx render --input "<file.pptx>" --out-dir "<render-dir>"
+```
+
+The renderer prefers Microsoft PowerPoint COM on Windows and LibreOffice otherwise, producing a PDF and one PNG per slide. Inspect every slide for:
+
+- title and body within margins;
+- tables and charts not overlapping each other or images;
+- legible font sizes (body ≥ 18 pt, title ≥ 28 pt);
+- no clipped text or empty placeholders;
+- chart labels/categories correct.
+
+If the render shows overlap, fix coordinates and re-render. Do not claim a deck is presentation-ready if it was never rendered.
+
+## Design rules
+
+- One idea per slide. Prefer 3–6 bullets; split dense content.
+- Use sentence case, parallel phrasing, and real figures only.
+- Use native tables/charts, not screenshots of spreadsheets where a native chart fits.
+- Keep a consistent palette and alignment grid; do not decorate with random shapes.
+- Choose `blank` for composed layouts and `bullets`/`title` for simple text slides.
+
+## Not supported
+
+- Google Slides / Google Drive editing.
+- Slide master, theme, template, or layout editing.
+- Animations, transitions, speaker notes, hyperlinks, audio/video, SmartArt.
+- Editing existing chart data in place, or replacing table cells in place.
+- `@oai/artifact-tool` helpers, montage/integrity gates, or template-fidelity workflows.
+- PowerPoint-perfect pagination; rendering is a fidelity check.