iOfficeAI · lidge-jun · May 2, 2026 · May 2, 2026 · May 2, 2026 · May 3, 2026
diff --git a/.github/workflows/notify-skills-update.yml b/.github/workflows/notify-skills-update.yml
@@ -0,0 +1,33 @@
+# Notify cli-jaw-skills repo when OfficeCLI skills change
+#
+# Trigger: push to skills/** on main/agent branches
+# What it does: sends repository_dispatch to cli-jaw-skills repo
+#
+# Required secret: SKILLS_SYNC_TOKEN
+#   - GitHub PAT with repo scope for lidge-jun/cli-jaw-skills
+#   - Set in OfficeCLI repo Settings → Secrets → Actions
+
+name: Notify Skills Update
+
+on:
+  push:
+    branches: [main, agent]
+    paths:
+      - 'skills/**'
+
+jobs:
+  notify:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Trigger cli-jaw-skills sync
+        uses: peter-evans/repository-dispatch@v3
+        with:
+          token: ${{ secrets.SKILLS_SYNC_TOKEN }}
+          repository: lidge-jun/cli-jaw-skills
+          event-type: officecli-skills-updated
+          client-payload: |
+            {
+              "ref": "${{ github.ref }}",
+              "sha": "${{ github.sha }}",
+              "message": "${{ github.event.head_commit.message }}"
+            }
diff --git a/.gitignore b/.gitignore
@@ -0,0 +1,22 @@
+# Build output
+build-local/
+bin/
+obj/
+target/
+src/rhwp-field-bridge/target/
+*.user
+*.suo
+*.pdb
+
+# IDE
+.vs/
+.vscode/
+.idea/
+
+# Python
+__pycache__/
+*.pyc
+
+# OS
+.DS_Store
+Thumbs.db
diff --git a/99.9_test/README.md b/99.9_test/README.md
@@ -0,0 +1,171 @@
+# 99.9 Phase A-H Manual Test Guide
+
+> Run from: `cd /Users/jun/Developer/new/700_projects/cli-jaw/officecli`
+> CLI: `dotnet run --project src/officecli -- <command>`
+> Python: `python3 scripts/hwpx_form_edit.py <command>`
+
+---
+
+## Phase E — Security
+
+### E1: Path Traversal
+```bash
+# Validate catches no errors on clean file
+dotnet run --project src/officecli -- validate 99.9_test/test_phase_e.hwpx
+```
+**Pass**: No `path_traversal` errors
+
+### E2: ZIP Bomb
+**Pass**: Opening any test file completes without timeout or OOM
+
+### E5: XXE Defense
+**Pass**: `validate` does not throw on any test file (XXE would cause exception)
+
+---
+
+## Phase A — Quick Wins
+
+### A1: Extended Keywords
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_a.hwpx forms
+```
+**Pass**: All 8 keywords (성명, 주소, 생년월일, 전화번호, 이메일, 직업, 학력, 자격증) appear in form field recognition
+
+### A3: False Positive Filter
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_a.hwpx text
+```
+**Pass**: "접수시간: 10:30" — the time value "10:30" is NOT stripped (time-related labels preserve values)
+
+### A4: Shape Alt Text
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_a.hwpx text
+```
+**Pass**: "면적: 100m²" renders with superscript stripped cleanly
+
+---
+
+## Phase B — Form Enhancement
+
+### B1-B2: In-Cell & KV Table
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_b.hwpx forms
+```
+**Pass**: Table recognized as form with fields: 성명, 생년월일, 주소, 전화번호, 이메일, 비고
+
+### B5: Checkbox Recognition
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_b.hwpx text
+```
+**Pass**: "□남 □여" and "□동의 □미동의" detected as checkbox fields
+
+### B6: Fill Test (Optional)
+```bash
+dotnet run --project src/officecli -- set 99.9_test/test_phase_b.hwpx fill --props '성명=홍길동'
+dotnet run --project src/officecli -- view 99.9_test/test_phase_b.hwpx forms
+```
+**Pass**: 성명 field now shows "홍길동"
+
+---
+
+## Phase F — Text Quality
+
+### F1: PUA Strip
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_f.hwpx text
+```
+**Pass**: No PUA characters (U+E000-U+F8FF range) in output
+
+### F3: Legal Heading Detection
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_f.hwpx outline
+```
+**Pass**: "별표 1" appears as heading in outline
+**Pass**: "별첨 서류는 반환하지 않습니다" does NOT appear as heading (it's body text)
+
+### F5: 1x1 Cell
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_f.hwpx markdown
+```
+**Pass**: Single-cell table rendered as structured text, not markdown table syntax
+
+### F7: Phone Spacing (Python)
+```bash
+python3 scripts/hwpx_form_edit.py extract 99.9_test/test_phase_f.hwpx
+```
+**Pass**: "0 1 0 - 1 2 3 4 - 5 6 7 8" collapsed to "010-1234-5678"
+
+---
+
+## Phase G — Parser
+
+### G1: Section File Regex
+**Pass**: All test files open successfully (section discovery works)
+
+### G3: Legal Heading Detection
+```bash
+dotnet run --project src/officecli -- view 99.9_test/test_phase_g.hwpx outline
+```
+**Pass**: "제1장 총칙" appears as h1 heading
+**Pass**: "제2절 적용범위" appears as h2 heading
+**Pass**: "제1장에서 언급한 바와 같이" does NOT appear as heading
+
+### G4: Dublin Core Metadata
+```bash
+dotnet run --project src/officecli -- get 99.9_test/test_phase_g.hwpx /metadata
+```
+**Pass**: Returns metadata dict (may include dc:title, dc:creator if present in file)
+
+### G5: MIME Validation
+```bash
+dotnet run --project src/officecli -- validate 99.9_test/test_phase_g.hwpx
+```
+**Pass**: No `package_mimetype_invalid` error
+
+### G7: Markdown Import
+```bash
+# Create a test file and import markdown
+dotnet run --project src/officecli -- create 99.9_test/test_import.hwpx --type hwpx
+dotnet run --project src/officecli -- import 99.9_test/test_import.hwpx --markdown "# Heading\n\n> Quote text\n\n- List item 1\n- List item 2\n\n1. Ordered 1\n2. Ordered 2"
+dotnet run --project src/officecli -- view 99.9_test/test_import.hwpx text
+```
+**Pass**: Heading, quote (with > prefix), list items all present in output
+
+---
+
+## Phase H — Diff/Compare
+
+### H1: Text Compare
+```bash
+dotnet run --project src/officecli -- compare 99.9_test/test_phase_h_a.hwpx 99.9_test/test_phase_h_b.hwpx text
+```
+**Pass**: Output shows:
+- "첫 번째 문장입니다" — `unchanged`
+- "두 번째 문장입니다" → "두 번째 문장이 수정되었습니다" — `modified`
+- "세 번째 문장입니다" — `unchanged`
+- "네 번째 문장이 추가되었습니다" — `added`
+
+### H5: Page Range Compare
+```bash
+dotnet run --project src/officecli -- compare 99.9_test/test_phase_h_a.hwpx 99.9_test/test_phase_h_b.hwpx text --pages "1"
+```
+**Pass**: Returns diff filtered to section 1 only
+
+---
+
+## Summary Checklist
+
+| Phase | Items | Test File | Key Check |
+|-------|-------|-----------|-----------|
+| E | E1-E6 | test_phase_e.hwpx | `validate` clean |
+| A | A1-A4 | test_phase_a.hwpx | `view forms` shows 8 keywords |
+| B | B1-B7 | test_phase_b.hwpx | `view forms` shows table fields |
+| F | F1-F8 | test_phase_f.hwpx | heading detection, 1x1 cell, phone spacing |
+| G | G1-G7 | test_phase_g.hwpx | heading h1/h2, MIME check, import |
+| H | H1-H5 | test_phase_h_{a,b}.hwpx | compare shows unchanged/modified/added |
+
+### Build Status
+```bash
+cd officecli && dotnet build && dotnet test
+```
+**Expected**: 0 errors, 189 tests pass, 2 pre-existing failures (Plan703 tests)
diff --git a/99.9_test/comprehensive_form.hwpx b/99.9_test/comprehensive_form.hwpx
diff --git a/99.9_test/cu_blank_01.hwpx b/99.9_test/cu_blank_01.hwpx
diff --git a/99.9_test/cu_blank_02.hwpx b/99.9_test/cu_blank_02.hwpx
diff --git a/99.9_test/cu_blank_03.hwpx b/99.9_test/cu_blank_03.hwpx
diff --git a/99.9_test/cu_blank_04.hwpx b/99.9_test/cu_blank_04.hwpx
diff --git a/99.9_test/cu_template_01.hwpx b/99.9_test/cu_template_01.hwpx
diff --git a/99.9_test/cu_template_01_visual_pass_01.hwpx b/99.9_test/cu_template_01_visual_pass_01.hwpx
diff --git a/99.9_test/cu_template_02.hwpx b/99.9_test/cu_template_02.hwpx
diff --git a/99.9_test/cu_template_02_visual_pass_01.hwpx b/99.9_test/cu_template_02_visual_pass_01.hwpx
diff --git a/99.9_test/cu_template_03.hwpx b/99.9_test/cu_template_03.hwpx
diff --git a/99.9_test/cu_template_03_visual_pass_01.hwpx b/99.9_test/cu_template_03_visual_pass_01.hwpx
diff --git a/99.9_test/cu_template_04.hwpx b/99.9_test/cu_template_04.hwpx
diff --git a/99.9_test/cu_template_04_visual_pass_01.hwpx b/99.9_test/cu_template_04_visual_pass_01.hwpx
diff --git a/99.9_test/cu_template_05.hwpx b/99.9_test/cu_template_05.hwpx
diff --git a/99.9_test/cu_template_06.hwpx b/99.9_test/cu_template_06.hwpx
diff --git a/99.9_test/cu_template_07.hwpx b/99.9_test/cu_template_07.hwpx
diff --git a/99.9_test/cu_template_07_visual_pass_01.hwpx b/99.9_test/cu_template_07_visual_pass_01.hwpx
diff --git a/99.9_test/cu_template_08.hwpx b/99.9_test/cu_template_08.hwpx
diff --git a/99.9_test/cu_template_09.hwpx b/99.9_test/cu_template_09.hwpx
diff --git a/99.9_test/cu_template_09_visual_pass_01.hwpx b/99.9_test/cu_template_09_visual_pass_01.hwpx
diff --git a/99.9_test/kice_edited.hwpx b/99.9_test/kice_edited.hwpx
diff --git a/99.9_test/kice_korean.hwpx b/99.9_test/kice_korean.hwpx
diff --git a/99.9_test/kice_sample.hwpx b/99.9_test/kice_sample.hwpx
diff --git a/99.9_test/test_phase_a.hwpx b/99.9_test/test_phase_a.hwpx
diff --git a/99.9_test/test_phase_b.hwpx b/99.9_test/test_phase_b.hwpx
diff --git a/99.9_test/test_phase_e.hwpx b/99.9_test/test_phase_e.hwpx
diff --git a/99.9_test/test_phase_f.hwpx b/99.9_test/test_phase_f.hwpx
diff --git a/99.9_test/test_phase_g.hwpx b/99.9_test/test_phase_g.hwpx
diff --git a/99.9_test/test_phase_h_a.hwpx b/99.9_test/test_phase_h_a.hwpx
diff --git a/99.9_test/test_phase_h_b.hwpx b/99.9_test/test_phase_h_b.hwpx
diff --git a/99.9_test/공문_샘플.hwpx b/99.9_test/공문_샘플.hwpx
diff --git a/BRANCH_STRATEGY.md b/BRANCH_STRATEGY.md
@@ -0,0 +1,56 @@
+# Branch Strategy
+
+## Current State (2026-05-06)
+- **upstream/main**: tracks `iOfficeAI/OfficeCLI` main. Pull-only, never push.
+- **main**: local mirror of `upstream/main` plus compliance docs.
+- **feat/hwpx**: active working branch on `origin`. Phase 36 HWP/HWPX evidence work (compatibility corpus, round-trip catalog, visual thresholds, provider matrix, release gate, safe-save) lives here.
+- **docs/structure-init-2026-05-06**: short-lived doc branch that introduced `structure/`, fast-forwarded into `feat/hwpx`.
+
+## Branch Roles
+- **upstream/main**: read-only upstream reference.
+- **main**: clean mirror; rebased from `upstream/main`.
+- **feat/hwpx**: primary working branch. All cli-jaw HWP/HWPX changes land here.
+- **feature/\*** / **docs/\***: optional short-lived branches. Merge back into `feat/hwpx` (typically `--ff-only`) and delete.
+
+## Sync Procedure
+```bash
+git fetch upstream
+git checkout main
+git merge --ff-only upstream/main
+git checkout feat/hwpx
+git rebase main          # or: git merge main --no-ff, depending on history needs
+```
+
+## Rebase Conflict Notes
+
+### 2026-05-14: upstream/main 1.0.91 rebase
+
+`upstream/main` moved from the 1.0.68-era base to 1.0.91 and introduced core plugin/exporter work while `feat/hwpx` carried native HWPX and experimental HWP bridge work. Resolve these conflicts by preserving both sides:
+
+- `BlankDocCreator.cs`: keep upstream `--minimal`/plugin-create support and keep native `.hwpx` creation before the plugin fallback. Unsupported-type text should list `.hwpx` plus plugin-served formats.
+- `CommandBuilder.Import.cs`: keep upstream `--minimal` for DOCX and keep HWPX `--from-markdown`/`--align`; call `BlankDocCreator.Create(file, locale, minimal)` before optional HWPX markdown import.
+- `CommandBuilder.cs`: register both upstream `BuildPluginsCommand` and fork `BuildCompareCommand`.
+- `DocumentHandlerFactory.cs`: route `.hwpx` to `HwpxHandler`, keep `.hwp` bridge guidance, and fall back to upstream plugin handlers for unknown extensions.
+- `CommandBuilder.View.cs` / `ResidentServer.cs`: keep upstream `pdf`/plugin forms support and HWP/HWPX modes (`forms`, `tables`, `markdown`, `objects`, `styles`, `fields`, `field`). Keep `BuildViewDescription()` when HWP bridge help is present.
+- `WordHandler.Add.Text.cs`: keep upstream `sym=font:hex` handling so dump/batch round-trips do not duplicate symbol glyph text.
+
+After resolving, continue the rebase and verify:
+
+```bash
+git ls-files 'src/rhwp-field-bridge/target/*' | wc -l  # must be 0
+dotnet build officecli.slnx
+cargo build --manifest-path src/rhwp-field-bridge/Cargo.toml
+dotnet test tests/OfficeCli.Tests/OfficeCli.Tests.csproj --filter FullyQualifiedName~HwpBridge --no-build
+dotnet test tests/OfficeCli.Tests/OfficeCli.Tests.csproj --no-build
+```
+
+## Working with `structure/`
+- See [`structure/INDEX.md`](structure/INDEX.md) for the doc map.
+- Update `structure/*.md` whenever the corresponding source/schema/test surface changes (sync checklist in `structure/INDEX.md`).
+- Doc-only changes should not modify `.cs`, `.ts`, `.js`, `.py`, or other source files.
+
+## Rules
+- Never push to `upstream`.
+- All cli-jaw changes go on `feat/hwpx` (or short-lived branches that merge into it).
+- HWP/HWPX claims must be evidence-gated per `docs/qa/phase-36-release-gate.md` — no DOCX parity language.
+- Tag releases as `cjk-v{version}` on `feat/hwpx`.
diff --git a/COMPLIANCE_NOTES.md b/COMPLIANCE_NOTES.md
@@ -0,0 +1,39 @@
+# OfficeCLI Fork — Apache 2.0 Compliance Notes
+
+## License Status
+- Upstream: Apache License 2.0 (LICENSE file intact)
+- Upstream NOTICE file: **none shipped** (checked v1.0.28)
+- Apache 2.0 §4(b): modified files must carry prominent change notices
+
+## Our Fork
+- Fork owner: lidge-jun
+- Fork URL: https://github.com/lidge-jun/OfficeCLI
+- Upstream: https://github.com/iOfficeAI/OfficeCLI
+
+## Planned Modifications
+- CJK font handling (CjkHelper.cs) — Korean/Japanese/Chinese font metadata
+- CJK language tag injection (w:lang, a:lang attributes)
+- Kinsoku line-break processing
+- East Asian character spacing
+
+## Attribution (for distribution)
+If we ship a bundled binary, include this NOTICE:
+
+```
+OfficeCLI
+Copyright (c) iOfficeAI contributors
+
+This product includes software developed at
+iOfficeAI (https://github.com/iOfficeAI/OfficeCLI).
+
+Licensed under the Apache License, Version 2.0.
+
+Modifications by cli-jaw contributors:
+- CJK (Korean/Japanese/Chinese) font handling and language tags
+- CJK line-break (kinsoku) processing
+- East Asian character spacing support
+```
+
+## Build Environment
+- .NET 10.0.201 SDK installed at ~/.dotnet/
+- `dotnet build src/officecli/officecli.csproj -c Release` — Build succeeded (0 warnings, 0 errors)
diff --git a/README.md b/README.md
@@ -13,6 +13,8 @@ Open-source. Single binary. No Office installation. No dependencies. Works every
 
 **English** | [中文](README_zh.md) | [日本語](README_ja.md) | [한국어](README_ko.md)
 
+> 📂 **Working in this repo as an agent or contributor?** Start at [`structure/INDEX.md`](structure/INDEX.md) — the agent-facing source-of-truth map covering file layout, command surface, format support, providers, and Phase 36 HWP/HWPX evidence gates.
+
 <p align="center">
   <strong>💬 Community:</strong> <a href="https://discord.gg/2QAwJn7Egx" target="_blank">Discord</a>
 </p>
@@ -172,6 +174,10 @@ officecli add deck.pptx / --type slide --prop title="Q4 Report"
 | Word (.docx) | ✅ | ✅ | ✅ |
 | Excel (.xlsx) | ✅ | ✅ | ✅ |
 | PowerPoint (.pptx) | ✅ | ✅ | ✅ |
+| HWPX (.hwpx) | 🧪 | 🧪 | 🧪 (`Resources/base.hwpx`) |
+| HWP (.hwp, binary) | 🧪 (rhwp bridge) | 🧪 (output-first + safe in-place text) | 🧪 (rhwp sidecar) |
+
+> 🧪 = experimental, evidence-gated. HWP/HWPX support is active on `feat/hwpx` and is **not** at DOCX parity. Operation truth lives in `officecli capabilities --json`, the corpus manifests under `tests/fixtures/{hwp,hwpx,common}`, and Phase 36 docs in `docs/qa/`. See [`structure/03-format-support.md`](structure/03-format-support.md) and [`structure/04-providers.md`](structure/04-providers.md) before making any HWP/HWPX claim.
 
 **Word** — full [i18n & RTL support](https://github.com/iOfficeAI/OfficeCLI/wiki/i18n) (per-script font slots, per-script BCP-47 lang tags `lang.latin/ea/cs`, complex-script bold/italic/size, `direction=rtl` cascading through paragraph/run/section/table/style/header/footer/docDefaults, `rtlGutter` + `pgBorders` shorthand, locale-aware page numbering for Hindi/Arabic/Thai/CJK), [paragraphs](https://github.com/iOfficeAI/OfficeCLI/wiki/word-paragraph), [runs](https://github.com/iOfficeAI/OfficeCLI/wiki/word-run), [tables](https://github.com/iOfficeAI/OfficeCLI/wiki/word-table), [styles](https://github.com/iOfficeAI/OfficeCLI/wiki/word-style), [headers/footers](https://github.com/iOfficeAI/OfficeCLI/wiki/word-header-footer), [images](https://github.com/iOfficeAI/OfficeCLI/wiki/word-picture) (PNG/JPG/GIF/SVG), [equations](https://github.com/iOfficeAI/OfficeCLI/wiki/word-equation), [comments](https://github.com/iOfficeAI/OfficeCLI/wiki/word-comment), [footnotes](https://github.com/iOfficeAI/OfficeCLI/wiki/word-footnote), [watermarks](https://github.com/iOfficeAI/OfficeCLI/wiki/word-watermark), [bookmarks](https://github.com/iOfficeAI/OfficeCLI/wiki/word-bookmark), [TOC](https://github.com/iOfficeAI/OfficeCLI/wiki/word-toc), [charts](https://github.com/iOfficeAI/OfficeCLI/wiki/word-chart), [hyperlinks](https://github.com/iOfficeAI/OfficeCLI/wiki/word-hyperlink), [sections](https://github.com/iOfficeAI/OfficeCLI/wiki/word-section), [form fields](https://github.com/iOfficeAI/OfficeCLI/wiki/word-formfield), [content controls (SDT)](https://github.com/iOfficeAI/OfficeCLI/wiki/word-sdt), [fields](https://github.com/iOfficeAI/OfficeCLI/wiki/word-field) (22 zero-param types + MERGEFIELD / REF / PAGEREF / SEQ / STYLEREF / DOCPROPERTY / IF), [OLE objects](https://github.com/iOfficeAI/OfficeCLI/wiki/word-ole), [document properties](https://github.com/iOfficeAI/OfficeCLI/wiki/word-document)
 
@@ -198,7 +204,10 @@ officecli add deck.pptx / --type slide --prop title="Q4 Report"
 
 ## Installation
 
-Ships as a single self-contained binary. The .NET runtime is embedded -- nothing to install, no runtime to manage.
+Ships as a self-contained OfficeCLI binary. Experimental binary HWP support
+also installs `rhwp-officecli-bridge` and `rhwp-field-bridge` sidecars beside
+the binary so `.hwp` create/read/render/mutation paths can run without manual
+environment variables.
 
 **One-line install:**
 

diff --git a/README_ko.md b/README_ko.md
@@ -4,7 +4,7 @@
 
 **모든 AI 에이전트에게 Word, Excel, PowerPoint의 완전한 제어권을 — 단 한 줄의 코드로.**
 
-오픈소스. 단일 바이너리. Office 설치 불필요. 의존성 제로. 모든 플랫폼 지원.
+오픈소스. 자체 완결형 바이너리. Office 설치 불필요. 모든 플랫폼 지원.
 
 **에이전트 친화적 렌더링 엔진 내장** — 에이전트가 자신이 만든 것을 "볼" 수 있고, Office 불필요. `.docx` / `.xlsx` / `.pptx`를 HTML 또는 PNG로 렌더링하며, *렌더링 → 보기 → 수정* 루프는 바이너리가 실행되는 어디서나 닫힙니다.
 
@@ -198,7 +198,9 @@ officecli add deck.pptx / --type slide --prop title="Q4 Report"
 
 ## 설치
 
-단일 자체 완결형 바이너리로 제공. .NET 런타임 내장 -- 설치할 것도, 관리할 런타임도 없습니다.
+자체 완결형 OfficeCLI 바이너리로 제공됩니다. 실험적 binary HWP 지원은
+`rhwp-officecli-bridge`와 `rhwp-field-bridge` sidecar를 바이너리 옆에 함께
+설치해 `.hwp` 생성/읽기/렌더링/수정 경로가 수동 환경변수 없이 동작하게 합니다.
 
 **원라인 설치:**
 

diff --git a/SKILL.md b/SKILL.md
@@ -398,7 +398,13 @@ officecli add-part <file> <parent>                   # create new document part
 | `financial-model` | Financial models, scenarios, projections. NOT for general data analysis (route those to `excel`) |
 | `data-dashboard` | CSV/tabular data → KPI / analytics / executive dashboards with charts and sparklines. NOT for raw data tracking (route those to `excel`) |
 
-Example: a fundraising deck task → `officecli load_skill pitch-deck` → use the printed rules.
+### HWPX (.hwpx, Hancom)
+
+| Name | When to use | Layer |
+|------|-------------|-------|
+| `officecli-hwpx` | Korean government / OWPML documents (한글 / 공문서) | **base** |
+
+Example: a fundraising deck task → `officecli skill pitch-deck` → use the printed rules.
 
 ---