@deckflow/deckuse 1.2.1 → 1.3.1

package/README.ko.md

@@ -0,0 +1,342 @@
+<div align="center">
+
+# Deckuse
+
+[![Node.js 18+](https://img.shields.io/badge/Node.js-18%2B-339933?logo=node.js&logoColor=white)](https://nodejs.org/)
+[![pnpm 10](https://img.shields.io/badge/pnpm-10-F69220?logo=pnpm&logoColor=white)](https://pnpm.io/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-3178C6?logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
+[![PPTX](https://img.shields.io/badge/Format-PPTX-B7472A?logo=microsoftpowerpoint&logoColor=white)](#pptx-capabilities)
+
+[English](README.md) · [简体中文](README.zh-CN.md) · [Français](README.fr.md) · [日本語](README.ja.md) · [한국어](README.ko.md) · [Русский](README.ru.md) · [Español](README.es.md) · [Português](README.pt-BR.md)
+
+</div>
+
+Deckuse는 코딩 에이전트를 위한 로컬 우선, 스키마 기반 Office 문서 자동화 엔진입니다. 문서를 버전 관리되는 작업 공간으로 열고, 에이전트가 구조를 검사하고 대상 요소를 지정하여 명시적인 JSON 명령을 적용·검증한 뒤 새 문서로 내보낼 수 있게 합니다.
+
+현재 구현된 형식은 PPTX와 DOCX입니다. XLSX, Keynote 및 Numbers 어댑터는 의도적으로 `FORMAT_NOT_IMPLEMENTED`를 반환하며, 아직 지원되는 편집 대상이 아닙니다.
+
+이 저장소는 **커뮤니티 에디션**(`edition=community`)입니다. 자세한 내용은 [docs/edition.md](docs/edition.md)를 참고하세요. 상용 에디션은 별도 저장소 `deckuse-commercial`에 있습니다.
+
+## Agent Skill (먼저 설치)
+
+Deckuse는 에이전트 우선입니다. **CLI를 쓰기 전에 Deckuse skill을 설치하세요.** workspace 우선 루프, 배치 `apply`, 시맨틱 주소, 단위계, 자주 쓰는 레시피가 담겨 있어 README만으로는 틀리기 쉽습니다.
+
+- Skill: [`skills/deckuse/SKILL.md`](skills/deckuse/SKILL.md)
+- Cursor (프로젝트): `.cursor/skills/deckuse/`로 복사 또는 심볼릭 링크
+- Cursor (개인): `~/.cursor/skills/deckuse/`로 복사 또는 심볼릭 링크
+
+**CLI `deckuse >= 1.2.0`** 필요. 빠른 참고: [docs/agent-cookbook.md](docs/agent-cookbook.md).
+
+## Deckuse를 선택하는 이유
+
+Deckuse는 프레젠테이션을 처음부터 다시 만들지 않고 기존 파일을 수정합니다. 소스 파일이 없으면 `deckuse new`로 번들된 빈 템플릿에서 작업 공간을 만들 수 있습니다. 이 워크플로는 시각적 판단보다 구조를 우선하도록 설계되었습니다.
+
+```text
+existing.pptx → init ─┐
+                      ├→ list / get → set / add → validate → export
+blank template → new ─┘
+```
+
+Every successful write automatically commits a Git revision, updates `operations.jsonl`, and rebuilds `package.pptx`. Use `undo` to revert writes and `history` to inspect the operation log.
+
+가능한 경우 변경하지 않은 XML과 알려지지 않은 패키지 파트를 보존합니다. 완전한 PowerPoint 렌더링/레이아웃 엔진은 아닙니다. `monitor`로 라이브 HTML 미리보기, `render`로 한 장을 PNG로 캡처할 수 있습니다. 의미적 `diff` / `branch`는 이후 제공됩니다.
+
+## 설치
+
+요구 사항: Node.js 18 이상.
+
+```sh
+npm install -g @deckflow/deckuse
+```
+
+이 명령은 `deckuse` CLI를 전역으로 설치합니다.
+
+```sh
+# 프레젠테이션에서 영구 작업 공간을 만듭니다.
+deckuse init input.pptx ./workspace --json
+
+# 또는 번들된 빈 16:9 템플릿으로 시작 (input.pptx 불필요).
+deckuse new ./workspace --json
+
+# 인덱싱된 문서를 검사하고 대상 요소를 조회합니다.
+deckuse inspect ./workspace --json
+deckuse query ./workspace 'kind=textbox text=Quarter' --json
+deckuse query ./workspace '*' --limit 500 --json
+
+# JSON 명령 하나, JSON 배열 또는 JSONL을 적용합니다.
+deckuse apply ./workspace --input operations.jsonl --json
+
+# 패키지를 검증하고 내보냅니다.
+deckuse validate ./workspace --json
+deckuse history ./workspace --json
+deckuse undo ./workspace --steps 1 --json
+```
+
+## CLI 워크플로
+
+`apply` accepts a transaction file (`{ "operations": [...] }`), a single JSON mutation, a JSON array, or JSON Lines. One invocation can apply many write commands; multiple commands run as one atomic batch. Use `--input -` (the default) to read from standard input. Legacy ElementRef mutations remain supported. Commands passed to `apply` do not need `version`, `workspaceId`, or `transactionId`: the CLI supplies them.
+
+명령 결과는 JSON으로 표준 출력에 기록됩니다. 잘못된 인수 또는 입력 오류는 표준 오류로 기록됩니다. 종료 상태 `0`은 성공, `1`은 명령 실패, `2`는 CLI 사용법 또는 파싱 실패를 뜻합니다.
+
+### 선택자
+
+Prefer `search text` / `search shape` and `list` for Phase 1a inventory. `query` remains available for back-compat and accepts either a selector string or a structured selector in a command. Space-separated terms are combined with AND.
+
+| Syntax                                 | Meaning                                              |
+| -------------------------------------- | ---------------------------------------------------- |
+| `*` or `all`                           | Match every indexed element.                         |
+| `kind=textbox`                         | Match an element kind by case-insensitive substring. |
+| `text=Quarter`                         | Match text that contains the literal value.          |
+| `text~=pattern`                        | Match text with a Unicode regular expression.        |
+| `hasText=true`                         | Match elements that contain text.                    |
+| `slide=256`, `id=256:10`, `name=Title` | Filter by slide ID, element ID, or name.             |
+
+Query results provide stable element references. A reference includes a document ID and an element ID or structural path; array positions are not stable identifiers.
+
+## 일반적인 에이전트 워크플로
+
+이 예시는 현재 PPTX 기능만 사용합니다. Deckuse가 추론, 카피라이팅 또는 시각적 검토를 독립적으로 수행한다고 주장하는 것이 아니라, 에이전트가 Deckuse 프리미티브를 조합하여 구성할 수 있는 워크플로를 설명합니다.
+
+### 1. 프레젠테이션 전체에서 오래된 연도 업데이트
+
+**요청:** “모든 `FY2025` 참조를 `FY2026`으로 바꾸고, 그 외에는 아무것도 변경하지 마세요.”
+
+먼저 `query`로 영향을 받는 요소를 검토한 다음, 리터럴 `replaceText`를 수행하고 내보내기 전에 검증합니다.
+
+```sh
+deckuse init master.pptx ./year-update --json
+deckuse query ./year-update 'text=FY2025' --limit 1000 --json
+cat > year-update.json <<'EOF'
+{
+  "type": "replaceText",
+  "find": "FY2025",
+  "replace": "FY2026"
+}
+EOF
+deckuse apply ./year-update --input year-update.json --json
+deckuse validate ./year-update --json
+```
+
+After the write completes, `./year-update/package.pptx` is rebuilt automatically as the latest snapshot.
+
+검토 쿼리는 변경 범위를 확인된 항목으로 제한합니다. `replaceText`는 승인된 일괄 변경을 수행하면서 관련 없는 객체는 그대로 유지합니다. selector가 없으면 하위 텍스트를 집계하는 조상 컨테이너 대신 가장 구체적인 인덱스된 텍스트 노드를 업데이트합니다.
+
+### 2. 회사 또는 제품 이름 변경
+
+**요청:** “기존 제품 이름을 새 제품 이름으로 모든 곳에서 바꾸세요.”
+
+이는 동일한 안전한 검토 후 교체 패턴입니다. 먼저 정확한 기존 이름을 검색한 뒤, 리터럴 값으로 `replaceText`를 사용합니다. 구두점이나 공백처럼 변형이 있는 경우에는 쿼리 출력을 확인한 후에만 정규식 교체를 사용하세요.
+
+```json
+{
+  "type": "replaceText",
+  "find": "Legacy Platform",
+  "replace": "Unified Platform"
+}
+```
+
+더 제한적인 변경을 위해서는 명령에 예를 들어 `"selector": "slide=256"` 같은 선택자를 포함하여 하나의 슬라이드만 대상이 되게 하세요.
+
+### 3. 에이전트용 프레젠테이션 개요 추출
+
+**요청:** “슬라이드 제목을 나열하고 이 덱이 다루는 내용을 요약하세요.”
+
+`inspect`를 실행하여 인덱싱된 프레젠테이션 구조를 가져온 다음 텍스트가 있는 객체를 쿼리합니다. 호출하는 에이전트는 반환된 객체를 슬라이드 ID별로 그룹화하고, 이름·위치·텍스트를 기준으로 제목처럼 보이는 객체를 식별하며, 추출된 텍스트에서 요약을 생성할 수 있습니다.
+
+```sh
+deckuse init briefing.pptx ./outline --json
+deckuse inspect ./outline --depth 2 --json
+deckuse query ./outline 'hasText=true' --limit 10000 --json
+```
+
+Deckuse는 구조화된 원본 데이터를 제공합니다. 어떤 텍스트가 제목인지 결정하고 요약을 작성하는 일은 Deckuse가 아니라 에이전트의 책임입니다.
+
+### 4. 발송 전 콘텐츠 QA 실행
+
+**요청:** “이 덱을 보내기 전에 이전 고객명, 날짜, 제품명, URL 및 필수 면책 문구를 찾으세요.”
+
+알려진 각 위험 항목을 쿼리하고 반환된 참조를 검사합니다. 부재 확인도 같은 방식으로 동작합니다. 필수 텍스트를 쿼리하고 결과가 비어 있으면 표시합니다. 에이전트는 프레젠테이션을 수정하지 않고 QA 보고서를 만들거나, 승인된 수정 사항에 대해 범위를 좁힌 `setText` / `replaceText` 명령을 준비할 수 있습니다.
+
+```sh
+deckuse query ./workspace 'text=Customer A' --limit 1000 --json
+deckuse query ./workspace 'text~=https?://' --limit 1000 --json
+deckuse query ./workspace 'text=Required disclaimer' --limit 1000 --json
+```
+
+이는 콘텐츠 및 구조 QA이지 시각 QA가 아닙니다. `render` / `monitor`는 검토 보조로만 사용하세요. Deckuse는 겹침을 감지하거나 레이아웃 품질을 판단하지 않습니다.
+
+### 5. 한 슬라이드에서 정확히 하나의 항목 변경
+
+**요청:** “슬라이드 7에서 제목을 `Enterprise Strategy`로 바꾸고, 그 외에는 아무것도 변경하지 마세요.”
+
+먼저 해당 슬라이드와 제목 텍스트를 쿼리한 뒤, 반환된 `ref`를 가져와 `setText` 명령을 보냅니다. `ref`는 모호한 전역 교체를 방지합니다.
+
+```json
+{
+  "type": "setText",
+  "ref": {
+    "documentId": "./workspace",
+    "elementId": "256:10"
+  },
+  "text": "Enterprise Strategy"
+}
+```
+
+요소 ID는 프레젠테이션별 예시입니다. 이 값을 복사하지 말고 항상 현재 작업 공간에서 반환된 ID를 사용하세요.
+
+### 6. 제목 타이포그래피 표준화
+
+**요청:** “승인된 모든 제목을 28 pt로 만들고 승인된 서체를 사용하세요.”
+
+쿼리로 제목 객체를 식별하고, 에이전트가 반환된 참조를 검토하거나 필터링한 다음 승인된 각 참조에 대해 `setProperties`를 한 번씩 적용합니다. `setProperties`는 한 번에 하나의 참조만 대상으로 하며, 자체적으로 선택자를 받지 않습니다.
+
+```json
+{
+  "type": "setProperties",
+  "ref": {
+    "documentId": "./workspace",
+    "elementId": "256:8"
+  },
+  "properties": {
+    "fontSize": 28,
+    "fontFamily": "Approved Sans",
+    "bold": true
+  }
+}
+```
+
+같은 명령으로 `fill`, `stroke`(`border`, `outline`, `line`도 가능), `textColor`, `italic`, `underline`, `name`, `hidden`을 설정할 수 있습니다. 알 수 없는 속성 키는 `INVALID_COMMAND`로 실패합니다.
+
+### 7. 객체의 기하를 정밀하게 조정
+
+**요청:** “승인된 모든 제목을 약간 아래로 이동하세요.”
+
+의도한 제목 참조를 쿼리하고 선택한 다음 현재 기하 정보를 검사하고, 명시적 좌표를 포함하여 객체마다 하나의 `setTransform` 명령을 실행합니다. 이는 구조적 기하 작업이므로, 시각적 검증 없이 자동 레이아웃 보정으로 홍보해서는 안 됩니다.
+
+```json
+{
+  "type": "setTransform",
+  "ref": {
+    "documentId": "./workspace",
+    "elementId": "256:8"
+  },
+  "transform": {
+    "x": 914400,
+    "y": 731520,
+    "width": 8229600,
+    "height": 685800
+  }
+}
+```
+
+변환 좌표는 OOXML EMU입니다. 세로 위치만 변경할 때는 검사한 객체의 `x`, `width`, `height`를 유지하세요.
+
+### 8. 승인된 영업 덱 개인화
+
+**요청:** “잠재 고객용 버전을 만드세요. 고객 이름과 승인된 계정별 문구는 업데이트하되 디자인은 유지하세요.”
+
+승인된 마스터에서 각 출력물마다 별도의 작업 공간을 만듭니다. 플레이스홀더 또는 기존 고객 텍스트를 쿼리하고, 검토된 교체만 적용한 뒤 검증하고 자동으로 갱신되는 `package.pptx`를 사용합니다.
+
+```sh
+deckuse init approved-master.pptx ./customer-a --json
+deckuse query ./customer-a 'text=Customer Name' --json
+# Apply reviewed replacements for this customer only.
+deckuse apply ./customer-a --input customer-a.jsonl --json
+deckuse validate ./customer-a --json
+```
+
+별도 작업 공간은 한 고객의 편집 내용이 다른 출력물로 새어 나가는 것을 방지합니다. 승인 절차가 에이전트의 수정을 허용한 객체만 교체하세요.
+
+### 9. 하나의 마스터에서 지역 또는 대상별 변형 생성
+
+**요청:** “승인된 프레젠테이션에서 지역별 및 엔터프라이즈 변형을 생성하세요.”
+
+각 변형마다 동일한 마스터에서 새 작업 공간을 초기화합니다. 각 변형은 고유한 명령 파일과 출력 경로를 가집니다.
+
+Prefer `apply` with a JSON array, JSONL, or `{ "operations": [...] }`: multiple write commands in one invocation run as one atomic batch (if one fails, none persist). The protocol `batch` command form remains supported.
+
+```json
+[
+  {
+    "type": "replaceText",
+    "find": "Default Message",
+    "replace": "Regional Message"
+  },
+  {
+    "type": "replaceText",
+    "find": "Default Offer",
+    "replace": "Enterprise Offer"
+  }
+]
+```
+
+```sh
+deckuse apply ./regional --input regional.json --json
+```
+
+이 방식은 하나의 승인된 원본 덱을 보존하면서, 명시적인 변경 집합으로 모든 변형을 재현할 수 있게 합니다.
+
+### 10. 코딩 에이전트가 기존 프레젠테이션을 조작하도록 하기
+
+**요청:** “이 덱을 검사하고, 요청된 편집을 식별하여 적용한 뒤 수정된 PPTX를 내보내세요.”
+
+에이전트에 다음 루프를 제공합니다. 작업 공간을 초기화하고, 대상 변경 전마다 inspect 또는 query를 실행하며, 명시적인 JSON 명령을 생성하고 적용한 뒤 패키지를 검증하고 재구성된 `package.pptx`를 내보내기로 사용합니다. 감사 가능성이 중요한 경우 명령 파일과 명령 결과를 작업과 함께 저장하세요.
+
+Deckuse는 에이전트에 안정적인 참조, 선택자, 트랜잭션, 검증 및 결정론적인 내보내기 경로를 제공합니다. 작업을 해석하고 어떤 작업이 적절한지 결정하는 것은 에이전트입니다.
+
+### `setProperties` 예시
+
+```json
+{
+  "type": "setProperties",
+  "ref": { "documentId": "./workspace", "elementId": "256:8" },
+  "properties": {
+    "stroke": { "color": "0000FF", "width": 1.5 },
+    "fill": "none",
+    "textColor": "111111",
+    "fontSize": 18,
+    "fontFamily": "Approved Sans",
+    "bold": true
+  }
+}
+```
+
+`stroke` and `fill` accept a hexadecimal color string. Use `none`, `false`, or `null` for no stroke or fill. `stroke.width` is in points and defaults to `1`.
+
+## PPTX 기능
+
+- Persistent workspaces, revision-conflict detection, dry runs, atomic batches, and an operation log.
+- `inspect`, `list`, `get`, `search`, and back-compat `query` / `getText`; stable references include slide ID, part URI, cNvPr ID, and ancestor path when available.
+- `setText` and `replaceText`, including literal or regular-expression replacement in an optional selector scope. Without a selector, `replaceText` prefers leaf text nodes over ancestor containers that aggregate descendant text. Newlines in `setText` become separate paragraphs.
+- `setTransform` for explicit object position, size, rotation, and flip changes.
+- `setProperties` for common shape and text properties, including `paragraph.align`, `paragraph.level`, `bullet`, `fill` transparency, and `hyperlink`.
+- Add, duplicate, remove, and rebind slides to another layout (`setSlideLayout` / `deckuse set slide-layout`); layout refs accept index, `layout:N`, `slide:N`, display name, or basename. Rebind updates the relationship only (does not edit layout parts). Duplicated slides clone mutable notes and chart parts while layouts and media can be shared safely.
+- Add shapes/text boxes (optional `role` writes a `p:ph` placeholder), connectors, groups, pictures (from a file path or base64), tables, charts (cache-only), and embedded video/audio; duplicate or remove elements.
+- `role` must be an OOXML placeholder type (`title`, `body`, `subTitle`, `ctrTitle`, …). Common aliases like `subtitle`→`subTitle` are normalized; non-OOXML labels (for example `card`) are rejected so PowerPoint does not prompt to repair.
+- Address placeholders with `slide:N/placeholder:<type>` (for example `title`, `body`, `subTitle`, `ctrTitle`).
+- `replacePicture` replaces a picture’s embedded media in place while retaining its element reference and layer order.
+- Table-cell addressing by table ID, row, and column; table row/column insert and delete via `setProperties`; cell `fill`; speaker-note reading and text editing (notes parts are created automatically when writing `slide:N/notes` if missing).
+- Create charts (`bar` / `column` / `line` / `pie`) and edit chart title, series-name, and cached values. When an embedded workbook exists, Deckuse emits `EMBEDDED_WORKBOOK_NOT_SYNCHRONIZED` rather than claiming that workbook data was updated. Advanced charts (other families, combo, ChartEx) are preserve-only in the community edition.
+- List and resolve master, layout, and theme parts; community edition rejects writes to those parts (`UNSUPPORTED_CAPABILITY`). Master/layout editing is available in the commercial edition repository.
+- `monitor` for live HTML preview and `render` for single-slide PNG screenshots (office2html + Playwright).
+- Preservation of unknown parts and untouched nodes. ZIP files are recompressed, so fidelity is defined by uncompressed data for untouched entries rather than ZIP byte identity.
+
+## 제한 사항
+
+- Deckuse does not implement the full PowerPoint DrawingML surface, animation editing, SmartArt editing, OLE editing, or macro editing.
+- It is not a full PowerPoint rendering or layout engine. `monitor` and `render` provide HTML/PNG review aids only; do not rely on them to assess visual quality, detect overlap, or automatically improve slide design.
+- Chart edits update OOXML chart caches only; embedded Excel workbooks are not rewritten.
+- Duplicated slides clone notes and chart parts and reuse layouts, themes, and media. Complex custom XML extensions are retained but not edited semantically.
+- `setText` and `replaceText` collapse multi-run text in the targeted node into one run while retaining the first run’s style.
+
+## 개발 검사
+
+```sh
+pnpm format:check
+pnpm lint
+pnpm typecheck
+pnpm test
+pnpm build
+```
+
+For the complete canonical English documentation and command wording, see [README.md](README.md).

package/README.md

@@ -11,11 +11,14 @@
 
 </div>
 
+Deckuse is a local-first, schema-driven Office document automation engine for coding agents. It turns document editing into an explicit, reviewable workflow: open a versioned workspace, inspect and target its structure, apply JSON commands, validate the result, and export a new document.
+
+The engine is built around format adapters. PPTX and DOCX are implemented. XLSX, Keynote, and Numbers adapters return `FORMAT_NOT_IMPLEMENTED` today, so agents fail clearly instead of silently producing unsafe edits.
 Deckuse is a local-first, schema-driven Office document automation engine for coding agents. It opens a document into a versioned workspace, lets an agent inspect and target its structure with semantic addresses (`slide:1/shape:2`), applies explicit mutations, validates the result, and exports a new document.
 
-This repository is the **community edition** (`edition=community`). See [docs/edition.md](https://github.com/deckflow/deckuse/blob/main/docs/edition.md). Shared packages here are the source of truth; the commercial edition is a private thin overlay (`deckuse-commercial`) that swaps `@deckflow/deckuse-edition-config`, registers a `PptxEditionExtension` for gated writes, and may add proprietary packages.
+This repository is the **community edition** (`edition=community`). See [docs/edition.md](https://github.com/deckflow/deckuse/blob/main/docs/edition.md). Shared source here is the source of truth, published as `@deckflow/deckuse`; the commercial edition is a private thin overlay (`deckuse-commercial`) that registers a `PptxEditionExtension` for gated writes and may add proprietary packages.
 
-PPTX is the currently implemented format (**protocol 2.0 / Phase 1a**). DOCX, XLSX, Keynote, and Numbers adapters deliberately return `FORMAT_NOT_IMPLEMENTED`; they are not supported editing targets yet.
+PPTX and DOCX are implemented (**protocol 2.0**). XLSX, Keynote, and Numbers adapters deliberately return `FORMAT_NOT_IMPLEMENTED`; they are not supported editing targets yet.
 
 ## Agent Skill (install first)
 
@@ -29,16 +32,32 @@ Requires **CLI `deckuse >= 1.2.0`**. Quick reference: [docs/agent-cookbook.md](h
 
 ## Why Deckuse
 
-Deckuse lets an agent modify an existing presentation without recreating it from scratch. Its workflow is deliberately structural rather than visual:
+Deckuse lets an agent modify an existing presentation without recreating it from scratch. When you have no source file, `deckuse new` bootstraps a workspace from the bundled blank template. Its workflow is deliberately structural rather than visual:
 
 ```text
-existing.pptx → init → list / get → set / add → validate → export
+existing.pptx → init ─┐
+                      ├→ list / get → set / add → validate → export
+blank template → new ─┘
 ```
 
 Every successful write automatically commits a Git revision, updates `operations.jsonl`, rebuilds `package.pptx`, and refreshes `.deckuse/index.json`. Use `undo` to revert writes and `history` to inspect the operation log.
 
 It preserves untouched XML and unknown package parts where possible. It is not a full PowerPoint rendering or layout engine and cannot reliably judge whether a slide is visually attractive or whether a layout is visually correct. Use `monitor` for live HTML preview and `render` to screenshot one slide to PNG for agent visual review. Semantic `diff` / `branch` remain deferred past Phase 1a.
 
+## Where it creates value
+
+Deckuse is designed for document changes that need to be precise, repeatable,
+and auditable:
+
+- **Recurring content updates** — refresh dates, metrics, names, pricing, and
+  disclaimers without rebuilding a presentation.
+- **Customer and market variants** — create controlled versions with explicit
+  selectors and reviewable operations.
+- **Content governance** — query sensitive or outdated content, inspect every
+  match, and validate before export.
+- **Agent-driven automation** — use structured JSON, revision checks, dry runs,
+  atomic batches, and operation logs in larger workflows.
+
 ## Installation
 
 Requirements: Node.js 18 or later.
@@ -52,9 +71,12 @@ This installs the `deckuse` CLI globally.
 ## CLI workflow
 
 ```sh
-# Create a persistent workspace from a presentation (revision starts at 1).
+# Create a workspace from an existing presentation (revision starts at 1).
 deckuse init input.pptx ./workspace --json
 
+# Or start from the bundled blank 16:9 template (no input.pptx needed).
+deckuse new ./workspace --json
+
 # Inventory and read live properties with provenance.
 deckuse status --workspace ./workspace --json
 deckuse list slides --workspace ./workspace --json
@@ -75,6 +97,10 @@ deckuse export ./out.pptx --workspace ./workspace --json
 
 # Live HTML preview; conversion starts when a browser subscribes.
 deckuse monitor --workspace ./workspace --port 4173
+# Background daemon: start / status (lists all when --workspace omitted) / stop [--all]
+deckuse monitor start --workspace ./workspace --port 0
+deckuse monitor status --json
+deckuse monitor stop --workspace ./workspace
 
 # Screenshot one slide to PNG for visual review (requires Chrome / Chromium / Edge).
 deckuse render --page 1 --workspace ./workspace --json
@@ -309,7 +335,7 @@ Deckuse gives the agent stable references, selectors, transactions, validation,
 - Geometry accepts **EMU numbers or unit strings** (`px` @ 96 DPI, `pt`, `cm`, `mm`, `in`, `%` of slide). `alignElements` / `deckuse align` distributes or aligns targets into absolute EMU writes. Same-batch forward refs by shape `name` work after `addShape` inside one `apply`.
 - `setTransform` for explicit object position, size, rotation, and flip changes.
 - `setProperties` for common shape and text properties, including `paragraph.align` (aliases `center`/`left`/…), `paragraph.level`, `bullet`, `fill` transparency, `hyperlink`, `wrap`, `anchor`/`valign`, and `cornerRadius`.
-- Add, duplicate, and remove slides; duplicated slides clone mutable notes and chart parts while layouts and media can be shared safely.
+- Add, duplicate, remove, and rebind slides to another layout (`setSlideLayout` / `deckuse set slide-layout`); layout refs accept index, `layout:N`, `slide:N`, display name, or basename. Rebind updates the relationship only (does not edit layout parts). Duplicated slides clone mutable notes and chart parts while layouts and media can be shared safely.
 - Add shapes/text boxes (optional `role` writes a `p:ph` placeholder), straight connectors (`line`/`connector`), elbow/curved connectors, arrow presets, groups, pictures (from a file path or base64), tables, charts (cache-only), and embedded video/audio; duplicate or remove elements.
 - `role` must be an OOXML placeholder type (`title`, `body`, `subTitle`, `ctrTitle`, …). Common aliases like `subtitle`→`subTitle` are normalized; non-OOXML labels (for example `card`) are rejected so PowerPoint does not prompt to repair.
 - Address placeholders with `slide:N/placeholder:<type>` (for example `title`, `body`, `subTitle`, `ctrTitle`). Target `slide:N/shape:X/run:K` to style a single run.
@@ -322,7 +348,19 @@ Deckuse gives the agent stable references, selectors, transactions, validation,
 
 Agent quick reference: [docs/agent-cookbook.md](https://github.com/deckflow/deckuse/blob/main/docs/agent-cookbook.md). Requires **CLI >= 1.2.0**.
 
-### `setProperties` example
+## DOCX capabilities
+
+Word uses the same workspace loop as PPTX (`new` / `init`, `list`, `apply`, `validate`, `export`, `undo`) but not the slide canvas. `deckuse new ./workspace --format docx` starts from a blank document. `init report.docx` unpacks an existing file. Snapshot file is `package.docx`.
+
+- Addresses: `body/p:3` (1-based; tables are not paragraphs), `body/p:3/run:0` (0-based run), `para:<w14:paraId>`, `bookmark:<name>`, `body/table:1/row:2/cell:1/p:1`. `style:Heading1` is readable; applying a style uses `paragraph.style` and does not edit `styles.xml`.
+- `setText`, `replaceText` (matches across runs inside one paragraph, including text split by `w:proofErr`), `setProperties` (`fontSize`, `bold`, `italic`, `underline`, `textColor`, `fontFamily`, `paragraph.align`, `paragraph.style`).
+- `addParagraph` (`name` writes a bookmark for same-batch `bookmark:` refs), `addTable`, `insertBreak` (`page`). CLI: `deckuse add paragraph|table|break`.
+- Slide commands (`addShape`, `xfrmSet`, `alignElements`, …) return `UNSUPPORTED_CAPABILITY`.
+- Tracked changes, fields, comments, content controls, and equations are preserved. A command that would have to rewrite them fails instead of stripping them.
+- Community edition does not write style definitions, numbering definitions, theme, or settings parts.
+- `render --page` is PPTX-only. `@deckflow/office2html` does not paginate Word; export and open the `.docx` to check layout.
+
+## PPTX `setProperties` example
 
 ```json
 {
@@ -341,7 +379,7 @@ Agent quick reference: [docs/agent-cookbook.md](https://github.com/deckflow/deck
 
 `stroke` and `fill` accept a hexadecimal color string. Use `none`, `false`, or `null` for no stroke or fill. `stroke.width` is in points and defaults to `1`.
 
-The complete command schema is at [`packages/core/schema/command.schema.json`](https://github.com/deckflow/deckuse/blob/main/packages/core/schema/command.schema.json). The TypeScript package entry points are `@deckflow/deckuse-core`, `@deckflow/deckuse-opc`, and `@deckflow/deckuse-pptx`.
+The complete command schema is at [`schema/command.schema.json`](https://github.com/deckflow/deckuse/blob/main/schema/command.schema.json). The TypeScript package entry point is `@deckflow/deckuse`.
 
 ## Limitations
 
@@ -361,3 +399,17 @@ pnpm typecheck
 pnpm test
 pnpm build
 ```
+
+Integration write smoke (curated fixtures, default `--batch`, semantic gate):
+
+```sh
+pnpm build
+pnpm test:integration-writes:smoke
+```
+
+Large corpus scans (optional / nightly):
+
+```sh
+pnpm test:integration-writes:corpus -- /path/to/pptx-docx-dir
+pnpm test:openability -- ./path/to/package.pptx   # LibreOffice; or --osascript on macOS
+```