officecli-word-form

OfficeCLI Word-Form スキル

このスキルは独立しており、docx のシーンレイヤーではありません。 フォームのペイロード（<w:sdt> コントロール、<w:ffData> レガシーフィールド、<w:fldChar> メールマージ、documentProtection）は、docx の段落／見出し／スタイルの基本要素とは異なる要素クラスです。QA も異なります。docx のデリバリーゲートでは視覚的なレイアウトと有効な PAGE フィールドを重視しますが、このスキルではデータの流れ（保護の適用／エイリアス＋タグ／項目の挿入／名前が 20 文字以下／アンダースコアのアンチパターンなし）を重視します。逆方向の引き継ぎ： ユーザーのドキュメントに入力可能なフィールドがない場合（レポート、手紙、メモ、論文、提案書）は、officecli-docx または docx シーンスキルに引き継いでください。このスキルは使用しないでください。

始める前に（重要）

officecli がインストールされていない場合：

macOS / Linux

if ! command -v officecli >/dev/null 2>&1; then
    curl -fsSL https://d.officecli.ai/install.sh | bash
fi

Windows (PowerShell)

if (-not (Get-Command officecli -ErrorAction SilentlyContinue)) {
    irm https://d.officecli.ai/install.ps1 | iex
}

確認：officecli --version

最初のインストール後も officecli が見つからない場合は、新しいターミナルを開いて、もう一度確認コマンドを実行してください。

上記のインストールコマンドが失敗した場合（セキュリティポリシーによるブロック、ネットワークに接続できない、権限が不足している場合など）は、手動でインストールしてください。お使いのプラットフォーム用のバイナリを https://github.com/iOfficeAI/OfficeCLI/releases からダウンロードし、確認コマンドを再実行します。

ヘルプ優先のルール

このスキルでは、すべての CLI フラグではなく、実際のフォームに必要な内容を説明します。プロパティ／エイリアス／列挙値が不確かな場合は、推測する前にヘルプを確認してください：officecli help docx [element] [--json]（例：sdt、formfield、field）。ヘルプはインストール済みの CLI バージョンに対応しており、正式な情報源です。このスキルとヘルプの内容が異なる場合は、ヘルプを優先してください（特に sdt のプロパティセットは時間とともに拡張されています。固定リストではなく、help docx sdt を信頼してください）。

メンタルモデルと継承

Word フォームは .docx に、通常の docx スキルでは扱わない 4 つの OpenXML ペイロードレイヤーを加えたものです。<w:sdt> コンテンツコントロール（種類：テキスト／リッチテキスト／ドロップダウン／コンボボックス／日付／画像／グループ）、<w:ffData> レガシー FormField（実際のチェックボックスを作成する唯一の方法です。SDT の type=checkbox は実装されていません）、<w:fldChar> 複合フィールド（MERGEFIELD、REF、PAGEREF、SEQ、IF。テンプレート作成時に使用し、ユーザー入力には使用しません）、そして documentProtection（Word でフィールド以外のテキストを読み取り専用にするロックです。また CLI では protection=forms により、フィールド以外のコンテンツ編集がロックされます（編集には --force または raw-set が必要です）が、フォーム保護の目的どおり、フォームフィールド（SDT）の編集は引き続き可能です）。

docx v2 からの継承はありません。 docx のデリバリーゲート（表紙の入力率、有効な PAGE の確認）は適用されません。フォームの QA では view forms ＋ query sdt alias+tag ＋ protectionEnforced を確認します。

docx への逆方向の引き継ぎ。 レポート／手紙／メモ／論文／ピッチデッキなど、編集可能なフィールドがないドキュメントは officecli-docx に引き継いでください。データ収集またはテンプレートのマージを目的とするドキュメントには、このスキルを使用してください。

シェルと実行の規律

一度に実行するコマンドは1つだけにしてください。次のコマンドを実行する前に出力を確認してください。 OfficeCLI は逐次的に動作します。add／set／remove を実行するたびに、ファイルが直ちに変更されます。以下のすべてのレシピでは、シェル変数として FILE=form.docx を使用します。

シェルでのエスケープは3層あります：

1. [N] を含むパスは必ずクォートしてください — zsh/bash は角括弧をグロブ展開します。officecli get "$FILE" /body/sdt[1] は no matches found で失敗します。正しくは、officecli get "$FILE" '/body/sdt[1]' です。
2. $ を含む prop はシングルクォートしてください — "Total: $50,000" は、$50 の変数展開後に "Total: ,000" になります。正しくは、'Total: $50,000' です。
3. --after find:<text> は外側をシングルクォートで囲み、内側にダブルクォートを使わないでください — --after find:"Client Signature:" とすると、クォートが検索文字列の一部になり、一致しません。正しくは、--after 'find:Client Signature:' です。

WARNING: UNSUPPORTED（終了コード2）は、誤った状態が通知されずに発生していることを意味します。 CLI は、拒否された prop を除いて要素を作成しています（終了コード2は、注意事項がある状態で実行されたことを意味します。--json が success: false を報告するのは、すべての prop が拒否された場合のみです）。ビルドログに UNSUPPORTED があれば、その要素に対して現在の CLI が受け付けない prop 名を使用しています。そこで作業を止め、正しい prop 名を help docx <element> で確認してください（items／format／lock など、ほとんどの SDT prop は現在受け付けられますが、maxlength は受け付けられません）。コマンドを修正して再実行してください。その状態のまま出荷してはいけません。

protection=forms は最後に実行する構造上のコマンドです。 設定すると、protection=forms はフィールド以外のコンテンツをロックします（こうした編集には --force または raw-set が必要です）が、フォームフィールド（SDT）の編集は引き続き可能です。これがフォーム保護の目的です。フィールド以外のコンテンツ編集（例：set /body/p[N] --prop text=）は拒否され（ERROR: Document is protected … use --force）、フォームフィールドの編集（例：set /body/sdt[N] --prop text=／--prop alias=）は成功します（終了コード0）。入力可能なフィールドを見つけるには Query("editable") を使用してください。そのため、まずフィールド以外の（静的レイアウトの）編集をすべて終えてからロックしてください。後から静的コンテンツを編集する必要がある場合は、--force を指定するか、一時的に保護を解除して編集し、再度ロックしてください。

--after find: の実践ガイド

--after find:<text> は、最初に一致した箇所を検索します。アンカーを誤ると挿入位置を間違え、デバッグに手間がかかります。次の3つのルールに従ってください。

1. アンカーは文書全体で一意でなければなりません。 二言語の契約書で「甲方签字」は両方の当事者に一致します。「甲方签字（Service Provider）」や英語の完全なタイトルなど、一意なフレーズを使用してください。
2. 挿入後は /body/p[last()] があてになりません — 検索による挿入で <w:body> の子要素の順序が変わります。新しい段落に対する操作を続けるには、実際の paraId を読み取ってください：officecli query "$FILE" paragraph --json | jq -r '.data.results[-1].format.paraId'。
3. 中国語と全角かっこ （） は find で文字どおりに一致しますが、確信が持てない場合は、まず officecli view "$FILE" text | grep -n "锚点" を実行して、ファイル内の正確なバイト列を確認してください。

# Trap: first-match hits 甲方 only, 乙方 missed
officecli add "$FILE" /body --type sdt --after 'find:签字'

# Fix: two signatories, two unique anchors
officecli add "$FILE" /body --type sdt --prop alias=Party_A_Name --prop tag=party_a \
  --after 'find:甲方签字（Service Provider）'
PID_A=$(officecli query "$FILE" paragraph --json | jq -r '.data.results[-1].format.paraId')
officecli add "$FILE" "/body/p[@paraId='$PID_A']" --type sdt --prop alias=Party_A_Title --prop tag=party_a_title

--after find: を使用したインライン SDT は、新しい段落ではなく、一致した段落の子要素として追加されます。ラベルと SDT を同じ行に置く必要がある場合に使用してください。

本物のフォームを構成するもの（識別情報）

入力可能な本物のフォームには、構造化フィールドと文書の保護が必要です。

方法	Word ユーザーに表示される内容	CLI で読み取り可能	本物のフォームか
SDT controls + protection=forms	灰色の枠線付きフィールド。その他の部分はロックされます	query sdt / view forms	はい
FormField checkbox + protection=forms	クリック可能な本物のチェックボックス。その他の部分はロックされます	query formfield / view forms	はい（チェックボックスのみ）
MERGEFIELD placeholders	下流のエンジンによって «CustomerName» が差し込まれます	query field	はい（テンプレート時）
アンダースコア ___ / 空白行	見た目だけの表現で、文書全体を編集できます	いいえ — 構造化フィールドがありません	いいえ

アンダースコアでフィールドを模倣しないでください。 姓名：_______________ は構造化データを一切生成せず、すべての検証をすり抜けます。必ず --type sdt または --type formfield を使用してください。

チェックボックスは SDT ではなく、FormField です。 --type sdt --prop type=checkbox は終了コード 1 で終了します（SDT type 'checkbox' is not implemented）。すべてのレシピで、チェックボックスには --type formfield --prop type=checkbox を使用してください。

MERGEFIELD は別の経路です。 view forms には SDT と formfield のみが表示され、query field には複合フィールドのみが表示されます。互いに重複しない 2 つの一覧であり、どちらも 1 つのファイル内で有効です。

出力要件（最低基準）

すべてのフォームは以下の要件を満たす必要があります。Delivery Gate は各項目を実行可能なチェックとして検証します。

1. protection=forms が適用されていること（get $FILE / → protectionEnforced=True）。
2. すべての SDT に alias と tag の両方があること。
3. すべてのドロップダウン／コンボボックスに、view forms で空でない items=... が表示されること。
4. すべての日付 SDT に意図した format=... が表示されること。
5. すべてのロック対象 SDT に、意図した lock=sdtLocked / contentLocked / sdtContentLocked が表示されること。
6. ビルドログに WARNING: UNSUPPORTED が一切ないこと。
7. SDT に type=checkbox が一切ないこと。
8. すべての formfield の name が 20 文字以下であること。
9. アンダースコア行／空白行のプレースホルダーが一切ないこと。
10. フィールドの種類がユーザーの意図と一致していること（短文テキスト／段落／固定リスト／リスト＋カスタム入力／日付／ブール値）。

3 つの方法（基本的な判断）

SDT のプロパティは add で第一級の機能として指定できます。現在の対応項目は officecli help docx sdt で確認してください。現時点では、type, tag, alias, text, items, format, lock, placeholder/placeholderText, date.* と、SDT の種類 text / richtext / dropdown / combobox / date / group / picture が含まれます。そのため、ほとんどのフォームは add だけで作成でき、raw-set も Word テンプレートも不要です。残る 2 つの方法は、API では対応できないケースに限られます。コマンドを 1 つでも書く前に、使用する方法を選んでください。**

方法 A — CLI のみ（ほぼすべてのケースでの既定）

使用するケース：あらゆる text / richtext / dropdown / combobox / date / picture / group SDT。オプション、日付形式、ロックも含みます。プロパティを add に直接渡し、get '/body/sdt[N]' --json でそれぞれが保持されていることを確認してください。

# dropdown WITH its options and a non-default date format, in one add each — no raw-set:
officecli add "$FILE" /body --type sdt \
  --prop type=dropdown --prop alias="Department" --prop tag=dept \
  --prop items="Engineering,Finance,HR"
officecli add "$FILE" /body --type sdt \
  --prop type=date --prop alias="Start Date" --prop tag=start \
  --prop format="yyyy年MM月dd日"
# lock works on add AND set:
officecli add "$FILE" /body --type sdt --prop type=text --prop tag=full_name \
  --prop alias="Full Name" --prop text="Enter full name" --prop lock=sdtLocked
# protection comes last, once all fields exist:
# officecli set "$FILE" / --prop protection=forms

方法 B — CLI + raw-set ブリッジ（help に公開されていない属性のみ）

使用するケース：help docx sdt に記載されていない SDT 属性が必要な場合（例：w:value が表示テキストと異なる <w:listItem>、または --prop で指定できない sdtPr 子要素）。raw-set は OfficeCLI の汎用 OpenXML フォールバックであり、トップレベルコマンドとして officecli --help に記載されています。通常のドロップダウンには --prop items= を使用してください（方法 A）。ここでの raw-set は例外であり、通常の方法ではありません。

# Display text ≠ stored value — not expressible via items=, so inject the listItems directly:
officecli add "$FILE" /body --type sdt --prop type=dropdown --prop alias="Department" --prop tag=dept
officecli raw-set "$FILE" /document \
  --xpath "//w:sdt[w:sdtPr/w:tag/@w:val='dept']/w:sdtPr/w:dropDownList" \
  --action append \
  --xml '<w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Engineering" w:value="ENG"/><w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Finance" w:value="FIN"/>'

方法 C — Word テンプレート（API では対応できない場合のみ）

使用するケース：本物の SDT チェックボックス（type=checkbox は引き続き終了コード 1 で終了します。その場合は、代わりにレガシー FormField を使用してください。「§レガシー FormField」を参照）、placeholderDocPart のプロンプトテキストパーツ、または --prop では対応できないカスタム richtext 表示／パーツ間のネスト。画像およびグループ化された SDT は、すでにこの方法の対象ではありません。方法 A で問題なく追加できます。

# One-time in Word: Developer tab → Insert Content Control → Save as template.docx
cp templates/onboarding_with_signature.docx "$FILE"
officecli open "$FILE"
officecli view "$FILE" forms                 # inspect embedded controls + paths
officecli set "$FILE" '/body/sdt[@sdtId=3]' --prop text="Jane Smith"
officecli set "$FILE" / --prop protection=forms

決定表

ニーズ	パス	備考
デフォルト文字列を持つテキスト／リッチテキスト SDT	A	--prop type/alias/tag/text
ロックが必要なテキスト SDT	A	--prop lock=sdtLocked は add（および set）で使用できます
オプション付きのドロップダウン／コンボボックス	A	--prop items="A,B,C"
デフォルト以外の書式を使う日付 SDT	A	--prop format="yyyy年MM月dd日"
署名画像 SDT、グループ化 SDT	A	--prop type=picture ／ type=group で直接追加できます
保存値と表示テキストが異なるドロップダウン	B	raw-set で <w:listItem w:value=…> を追加します
実際のチェックボックス	FormField	--type formfield --prop type=checkbox（§Legacy FormField を参照）
差し込み印刷のプレースホルダー	MERGEFIELD	--type field --prop fieldType=mergefield（§MERGEFIELD を参照）
実際の SDT チェックボックス／プレースホルダー部分／カスタム外観	C	Word でひな形を作成し、CLI から値を入力します

クイックスタート — パス A + FormField（最小限の受付フォーム）

2 つの SDT テキストフィールド、1 つのチェックボックス、保護機能を備えています。貼り付けて調整してください。これは実用に耐える最小限のフォームです。

FILE=intake.docx
officecli close "$FILE" 2>/dev/null; rm -f "$FILE"   # preflight: clear stale resident / prior file (cold-start after CLI upgrade commonly leaks a resident)
officecli create "$FILE"
officecli open "$FILE"

officecli set "$FILE" / --prop title="Employee Onboarding Intake" \
  --prop docDefaults.font="Calibri" --prop docDefaults.fontSize="12pt"

officecli add "$FILE" /body --type paragraph \
  --prop text="Employee Onboarding Intake" --prop style=Heading1 \
  --prop size=20 --prop bold=true --prop spaceAfter=18pt

officecli add "$FILE" /body --type paragraph \
  --prop text="Full Name:" --prop size=11 --prop bold=true --prop spaceAfter=4pt
officecli add "$FILE" /body --type sdt --prop type=text \
  --prop alias="Full Name" --prop tag=full_name --prop text="Enter full name"

officecli add "$FILE" /body --type paragraph \
  --prop text="Start Date:" --prop size=11 --prop bold=true --prop spaceAfter=4pt
officecli add "$FILE" /body --type sdt --prop type=date \
  --prop alias="Start Date" --prop tag=start_date

officecli add "$FILE" /body --type paragraph \
  --prop text="Read and agree to employee handbook" --prop size=11 --prop spaceAfter=4pt
officecli add "$FILE" /body --type formfield \
  --prop type=checkbox --prop name=agree_handbook --prop checked=false

officecli set "$FILE" '/body/sdt[1]' --prop lock=sdtlocked
officecli set "$FILE" '/body/sdt[2]' --prop lock=sdtlocked
officecli set "$FILE" / --prop protection=forms
officecli close "$FILE"
officecli view "$FILE" forms

パス B — raw-set のレシピ

3 つのレシピで、SDT フォームの複雑な属性に関するニーズのほとんどに対応できます。

B1 — ドロップダウン項目（追加）

# Skeleton (Path A)
officecli add "$FILE" /body --type sdt --prop type=dropdown \
  --prop alias="Department" --prop tag=dept

# Inject items
officecli raw-set "$FILE" /document \
  --xpath "//w:sdt[w:sdtPr/w:tag/@w:val='dept']/w:sdtPr/w:dropDownList" \
  --action append \
  --xml '<w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Engineering" w:value="Engineering"/><w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Finance" w:value="Finance"/><w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="HR" w:value="HR"/>'

# Verify
officecli get "$FILE" '/body/sdt[1]'   # expect: type=dropdown items=Engineering,Finance,HR

テンプレート。 <TAG> ／ <LABEL> ／ <VALUE> のみを置き換えてください。すべてのルート <w:listItem> に xmlns:w=... が必要です。raw-set は名前空間プレフィックスを継承しません。1 回の呼び出しで複数の <w:listItem> を連結できます。オプションの順序は保持されます。

B2 — コンボボックス項目（B1 と同じですが、xpath の末尾が異なります）

officecli add "$FILE" /body --type sdt --prop type=combobox \
  --prop alias="Current Medication" --prop tag=current_med

officecli raw-set "$FILE" /document \
  --xpath "//w:sdt[w:sdtPr/w:tag/@w:val='current_med']/w:sdtPr/w:comboBox" \
  --action append \
  --xml '<w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Antihypertensives" w:value="Antihypertensives"/><w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Insulin" w:value="Insulin"/><w:listItem xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" w:displayText="Other (specify)" w:value="Other"/>'

B1 との唯一の違いは、xpath の末尾が w:dropDownList ではなく w:comboBox であることです。コンボボックスではユーザーが独自の値を入力できますが、ドロップダウンでは入力できません。

B3 — 日付の書式（setattr）

officecli add "$FILE" /body --type sdt --prop type=date \
  --prop alias="Contract Start Date" --prop tag=contract_start

# Chinese: yyyy年MM月dd日
officecli raw-set "$FILE" /document \
  --xpath "//w:sdt[w:sdtPr/w:tag/@w:val='contract_start']/w:sdtPr/w:date/w:dateFormat" \
  --action setattr \
  --xml "w:val=yyyy年MM月dd日"

# US:    w:val=MM/dd/yyyy
# ISO:   w:val=yyyy-MM-dd  (already the default)
# Long:  w:val="MMMM d, yyyy"

officecli get "$FILE" '/body/sdt[N]'   # expect: type=date format=yyyy年MM月dd日

setattr は属性を 1 つ置き換えます。--xml 内では値を引用符で囲まないでください。変更されるのは w:val のみで、<w:dateFormat> ラッパーは保持されます。

raw-set のアクションとエラー

--action	フォームでの用途
append	対象の末尾に新しい子要素を挿入します（B1、B2 — listItem）
setattr	属性を 1 つ変更します。--xml "key=value"（B3 — dateFormat/@val）
replace	対象全体を置き換えます（まれなケース — <w:date> ラッパー全体をリセットする場合）
remove	対象を削除します（オプションを再設定する前にクリアする場合）

症状	対処方法
raw-set: 0 element(s) affected	XPath が一致しませんでした。tag の値と、SDT がブロックかインラインかを確認してください。officecli raw $FILE /document に切り替えて、実際の XML を確認してください。
Error: prefix 'w' is not defined	フラグメントに xmlns:w="http://schemas.openxmlformats.org/wordprocessingml/2006/main" がありません。--xml 内のすべてのルート要素にこれが必要です。
追加後の項目の読み戻し結果が空	<w:dropDownList/> がすでに存在している必要があります（パス A の type=dropdown で確実に作成されます）。存在しない場合、追加先がありません。
成功と同じ行に VALIDATION: N new error(s) introduced と表示される	追加した子要素がスキーマに適合していません。raw-set が終了コード 0 で終了していても、処理を止めて修正してください。

パス C — Word のひな形ワークフロー

CLI では表現できないフィールド（署名の picture SDT、実際の SDT チェックボックス、placeholderDocPart のプロンプトテキスト、グループ化 SDT、カスタムのリッチテキストスタイル）については、Word でひな形を一度作成してから、CLI で値を入力します。

Word での初回設定： ファイル → オプション → リボンのユーザー設定 → 開発。開発タブ → 画像の挿入／チェックボックス／グループ化コンテンツコントロール → 右クリック → プロパティ → タイトル（alias）とタグを設定します。template.docx として保存します。

CLI で値を入力：

cp templates/onboarding_with_signature.docx "$FILE"
officecli open "$FILE"
officecli view "$FILE" forms                                    # see /body/... paths + sdtId values
officecli set "$FILE" '/body/sdt[@sdtId=3]' --prop text="Jane Smith"
officecli set "$FILE" / --prop protection=forms
officecli close "$FILE"

MERGEFIELD（データ駆動型の方法）

help docx field では、mergefield、ref、pageref、seq、if など約 30 種類の値を含む fieldType 列挙型を定義しており、それぞれの型付きプロパティを使ってすべて CLI で指定できます。MERGEFIELD は同じファイル内の SDT と共存しますが、query field でのみ報告されます。MERGEFIELD はユーザーが入力するものではないため、view forms には表示されません。

正規の MERGEFIELD：

officecli add "$FILE" /body --type paragraph --prop text="Dear "
officecli add "$FILE" '/body/p[1]' --type field --prop fieldType=mergefield --prop name=CustomerName
officecli add "$FILE" '/body/p[1]' --type run --prop text=", "
officecli add "$FILE" '/body/p[1]' --type field --prop fieldType=mergefield --prop name=CompanyName
# Readback: "Dear «CustomerName», «CompanyName»"

要素タイプのショートカット（同等）：officecli add "$FILE" '/body/p[1]' --type mergefield --prop name=CustomerName。

よく使われるフィールドパターン

パターン	呼び出し形式
差し込み印刷のプレースホルダー	--type field --prop fieldType=mergefield --prop name=<FieldName>
数値書式（通貨、パーセント）を指定した差し込み印刷	--type field --prop fieldType=mergefield --prop name=Amount --prop instr='MERGEFIELD Amount \# "#,##0.00"'。mergefield では型付きの format プロパティは無視されます（警告が表示されます）。フィールドコード全体を埋め込むには instr（別名 instruction）を使用してください。確認方法：query "$FILE" field --json | jq '.data.results[].format.instruction' に \# と書式指定が含まれている必要があります。
日付書式を指定した差し込み印刷	--type field --prop fieldType=mergefield --prop name=StartDate --prop instr='MERGEFIELD StartDate \@ "yyyy-MM-dd"'
ブックマークテキストへの相互参照	--type field --prop fieldType=ref --prop name=<BookmarkName>
ブックマークのページ番号への相互参照	--type field --prop fieldType=pageref --prop name=<BookmarkName>
自動採番（図 1／2／3）	--type field --prop fieldType=seq --prop identifier=Figure
フッターのページ番号	--type field --prop fieldType=page
「ページ X／Y」	2 つのフィールド：fieldType=page + fieldType=numpages
条件付きテキスト	--type field --prop fieldType=if --prop expression='{ MERGEFIELD Gender } = "Male"' --prop trueText="Mr." --prop falseText="Ms."

IF 条件（CLI で指定可能）

officecli add "$FILE" /body --type paragraph --prop text=""
officecli add "$FILE" '/body/p[last()]' --type field --prop fieldType=if \
  --prop expression='{ MERGEFIELD Gender } = "Male"' \
  --prop trueText="Mr." --prop falseText="Ms."
officecli add "$FILE" '/body/p[last()]' --type run --prop text=" "
officecli add "$FILE" '/body/p[last()]' --type field --prop fieldType=mergefield --prop name=LastName
# Merge-time result: "Mr. «LastName»" or "Ms. «LastName»"

{ IF { MERGEFIELD X } = "Y" { REF bm } "fallback" } のような入れ子のラッパーは、--prop の連結では指定できません。手書きの <w:fldChar>／<w:instrText> フラグメントを raw-set するか、Word テンプレート（パス C）で一度作成してください。

読み取り。 query $FILE field は /field[N] と命令、および fieldType を一覧表示します。view $FILE forms は MERGEFIELD を一覧表示しません（SDT と formfield のみ）。これらはエンドユーザーが入力できる項目ではなく、テンプレート作成時の項目です。get $FILE '/body/p[1]' は、フィールド名を山括弧で囲んで表示します。

レガシー FormField

実際のチェックボックスが必要な場合は FormField を使用してください。テキスト／ドロップダウンには SDT を優先してください。

help docx formfield：type（text/checkbox/check/dropdown）、name（必須、20 文字以下 — OpenXML スキーマの MaxLength。add は 20 文字を超えても通りますが、validate で拒否されます）、text（テキストのみ、別名 value）、checked（チェックボックスのみ）。

# CHECKBOX — the only real checkbox (SDT type=checkbox is not implemented)
officecli add "$FILE" /body --type formfield --prop type=checkbox \
  --prop name=agree_terms --prop checked=false

# TEXT formfield
officecli add "$FILE" /body --type formfield --prop type=text \
  --prop name=emp_name --prop text="Enter name"

# DROPDOWN formfield — items NOT settable via CLI; use Word template or SDT Path B
officecli add "$FILE" /body --type formfield --prop type=dropdown --prop name=dept_select

# Read / modify by name (stable) or 1-based index
officecli get "$FILE" '/formfield[agree_terms]'
officecli set "$FILE" '/formfield[agree_terms]' --prop checked=true
officecli set "$FILE" '/formfield[emp_name]' --prop text="Jane Smith"
officecli set "$FILE" '/formfield[dept_select]' --prop text="Engineering"

FormField のパス（/formfield[N] または /formfield[<name>]）は、SDT のパス（/body/sdt[N]）とは別です。両方を併用でき、protection=forms は両方を対象にします。

規模。 1 つのドキュメントに 50 個以上のチェックボックスを配置してテスト済みです。formfield の数に実用上の上限はありません。作成と validate は問題なく実行できます。ハード制約は name が 20 文字以下であること（K13）のみです。

レンダラーに関する注意 — formfield チェックボックス [RENDERER-BUG]。 LibreOffice の PDF エクスポートでは、formfield のチェックボックスがまれに ☐☐（二重のボックス）として表示されます。Word と WPS では、クリック可能な単一のボックスが表示され（クリックすると ☑ に切り替わります）。これは LibreOffice レンダラーの癖であり、スキルやドキュメント品質の問題ではありません。K19 を参照してください。フォームで回避策を試さないでください。評価者が LibreOffice で生成した PDF のスクリーンショットを確認し、☐☐ が表示されていても、[RENDERER-BUG] に起因するものとして扱ってください。

ドキュメントの保護とロック

フォーム保護の有効化

officecli set "$FILE" / --prop protection=forms
officecli get "$FILE" /                                  # look for: protectionEnforced=True

保護モード

モード	Word ユーザーにできること	CLI の動作
forms	SDT とフォームフィールドの入力のみ	フォームフィールド（SDT）の編集は成功します（終了コード 0）。フィールド以外のコンテンツを編集するには、--force または raw-set が必要です
readOnly	読み取りのみ	フィールド以外の編集には --force が必要です。raw-set は保護を回避します
comments	コメントの追加のみ	フィールド以外の編集には --force が必要です。raw-set は保護を回避します
trackedChanges	変更履歴を記録した編集のみ	フィールド以外の編集には --force が必要です。raw-set は保護を回避します
none	全面的な編集	すべての操作が可能です

重要： ドキュメントの保護は、Word ユーザーと CLI の両方を制限します。protection=forms の場合、フォームフィールド（SDT）の編集 — set /body/sdt[N] --prop text= / --prop alias= — は成功します（終了コード 0）。これがフォーム保護の目的です。拒否されるのは、フィールド以外のコンテンツの編集（例：set /body/p[N] --prop text=）のみです。その際は ERROR: Document is protected (mode: forms). … use --force to override が表示されます。静的コンテンツも編集するには、--force（または保護を完全に回避できる唯一の動詞である raw-set）を指定してください。Word ユーザーが引き続き入力できるフィールドを見つけるには、Query("editable") を使用します。

ロック値（add と set で設定可能）

officecli set "$FILE" '/body/sdt[1]' --prop lock=sdtlocked           # content editable; control cannot be deleted
officecli set "$FILE" '/body/sdt[1]' --prop lock=contentlocked       # content read-only; control can be deleted
officecli set "$FILE" '/body/sdt[1]' --prop lock=sdtcontentlocked    # both locked
# Omit lock entirely → unlocked (default)

--prop lock=... は set だけでなく add でも機能するため、コントロールの作成時にインラインで設定できます。読み戻し時は、入力時の大文字・小文字にかかわらず、キャメルケース（sdtLocked）に正規化されます。どちらの表記も受け付けられます。

ロックと protection=forms の相互作用

ロック値	protection=forms が有効	Word ユーザーは編集できるか	Word ユーザーはコントロールを削除できるか
（なし）	はい	はい	はい
sdtlocked	はい	はい	いいえ
contentlocked	はい	いいえ	はい
sdtcontentlocked	はい	いいえ	いいえ
ブロックレベル SDT のラップ contentlocked	任意	いいえ（ラップされた段落は保護モードにかかわらず読み取り専用）	いいえ
任意	readOnly モード	いいえ	いいえ

ブロックレベルのロック（段落をラップする SDT）

protection=forms はドキュメントレベルの設定です。管理者が保護を解除すると、すべての静的な段落（免責事項、法的証明文、契約条項）が再び編集可能になります。マスターテンプレートでは、多層防御が必要です。重要な段落を lock=contentLocked のブロックレベル <w:sdt> でラップすると、保護が解除された後もコンテンツは読み取り専用のままになります。

officecli add "$FILE" /body --type paragraph \
  --prop text="I authorize the above and acknowledge all clauses." --prop size=11 --prop spaceAfter=12pt
PID=$(officecli query "$FILE" paragraph --json | jq -r '.data.results[-1].format.paraId')

# raw-set actions: append | prepend | insertbefore | insertafter | replace | remove | setattr
# No `wrap` action — two-step instead: (1) insertbefore an empty <w:sdt><w:sdtContent/></w:sdt>,
# (2) move the original <w:p> inside by `replace` on the sdtContent with a copy of the paragraph XML.
# Simpler alternative: read the paragraph XML via `officecli raw`, then `replace` the whole <w:p> with <w:sdt>...<w:sdtContent>[original w:p]</w:sdtContent></w:sdt>:
# NOTE: this needs an XML-aware extraction, NOT awk. `raw /document` emits the whole document on ONE line,
# so an awk range like `/paraId=.../,/<\/w:p>/` grabs the entire <w:document> (schema-invalid). Parse the XML
# and pull the single <w:p> by paraId instead:
PARA_XML=$(officecli raw "$FILE" /document | python3 -c '
import sys, xml.etree.ElementTree as ET
xml = sys.stdin.read(); pid = sys.argv[1]
ns = {"w":"http://schemas.openxmlformats.org/wordprocessingml/2006/main","w14":"http://schemas.microsoft.com/office/word/2010/wordml"}
for p, u in ns.items(): ET.register_namespace(p, u)
root = ET.fromstring(xml); key = "{%s}paraId" % ns["w14"]
for p in root.iter("{%s}p" % ns["w"]):
    if p.attrib.get(key) == pid:
        sys.stdout.write(ET.tostring(p, encoding="unicode")); break
' "$PID")
officecli raw-set "$FILE" /document \
  --xpath "//w:p[@w14:paraId='$PID']" \
  --action replace \
  --xml "<w:sdt xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" xmlns:w14=\"http://schemas.microsoft.com/office/word/2010/wordml\"><w:sdtPr><w:alias w:val=\"Authorization\"/><w:tag w:val=\"auth_para\"/><w:lock w:val=\"contentLocked\"/></w:sdtPr><w:sdtContent>${PARA_XML}</w:sdtContent></w:sdt>"

query sdt --json | jq '.data.results[] | select(.format.lock == "contentLocked" and .format.type == "block")' で確認します。これは法的証明文、コンプライアンスに関する免責事項、機密保持条項にのみ使用してください。通常の受付フィールドには不要です。

役割で制御するフィールド（複数の役割があるフォーム）

1つのフォームに2つの役割（患者と医師、当事者 A と当事者 B）が入力する場合、もう一方の役割が編集できないようにするフィールドには lock=contentLocked を使用します。protection=forms の場合、contentLocked の SDT は Word で読み取り専用として表示されます。対象の役割が保護を解除する（または管理者が役割ごとのコピーを切り替える）ことで、もう一方の部分を入力できます。

# Patient section — editable (no lock, or sdtlocked to prevent accidental deletion only)
officecli set "$FILE" '/body/sdt[1]' --prop lock=sdtlocked      # patient_name
officecli set "$FILE" '/body/sdt[2]' --prop lock=sdtlocked      # patient_dob

# Physician section — locked against patient edits
officecli set "$FILE" '/body/sdt[14]' --prop lock=contentLocked # physician_diagnosis
officecli set "$FILE" '/body/sdt[15]' --prop lock=contentLocked # physician_signature

これは、医療の受付、二者間契約、承認を順番に行うフォームの基本パターンです。

レシピ — MERGEFIELD と署名を含む契約書／SOW テンプレート

3つのサブレシピにおける行の対応関係：SDT[1]=project_name、SDT[2]=contract_start、SDT[3]=payment_schedule、SDT[4]=signatory_name（インライン）。同じ $FILE に対して（sow-a）→（sow-b）→（sow-c）の順に実行します。各サブレシピは20行未満なので、シェルのエスケープミスが1つのブロックを越えて連鎖することはありません。

レシピ（sow-a）定型文＋表紙＋当事者

ファイルを作成し、docDefaults を設定して、タイトル／イントロを記述します。また、後続のメールマージで入力する2つの MERGEFIELD プレースホルダー（CustomerName、ContractNo）を配置します。

FILE=sow.docx
officecli create "$FILE"
officecli open "$FILE"
officecli set "$FILE" / --prop title="Statement of Work" \
  --prop docDefaults.font="Calibri" --prop docDefaults.fontSize="12pt"

officecli add "$FILE" /body --type paragraph --prop text="Statement of Work" \
  --prop style=Heading1 --prop size=20 --prop bold=true --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph \
  --prop text="This Statement of Work ('SOW') is entered into between the parties identified below and governs the delivery of professional services." \
  --prop size=11 --prop spaceAfter=12pt

officecli add "$FILE" /body --type paragraph --prop text="Customer: "
officecli add "$FILE" '/body/p[last()]' --type field \
  --prop fieldType=mergefield --prop name=CustomerName
officecli add "$FILE" /body --type paragraph --prop text="Contract #: "
officecli add "$FILE" '/body/p[last()]' --type field \
  --prop fieldType=mergefield --prop name=ContractNo

レシピ（sow-b）SDT フィールド — すべて Path A を使用

3つのブロックレベル SDT（プロジェクト／日付／ドロップダウン）と、--after 'find:Client Signature:' で位置を指定するインライン署名 SDT を追加します。日付形式とドロップダウンの項目は add に直接指定するため、raw-set は不要です。

officecli add "$FILE" /body --type sdt --prop type=text \
  --prop alias="Project Name" --prop tag=project_name --prop text="Enter project name"
officecli add "$FILE" /body --type sdt --prop type=date \
  --prop alias="Contract Start Date" --prop tag=contract_start --prop format="MM/dd/yyyy"
officecli add "$FILE" /body --type sdt --prop type=dropdown \
  --prop alias="Payment Schedule" --prop tag=payment_schedule \
  --prop items="Full Prepayment,Net 30 Upon Delivery"
officecli add "$FILE" /body --type paragraph --prop text="Client Signature:" \
  --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=4pt
officecli add "$FILE" /body --type sdt --prop type=text \
  --prop alias="Signatory Name" --prop tag=signatory_name --prop text="Authorized Signatory" \
  --after 'find:Client Signature:'
# (Only reach for raw-set if a listItem's stored value must differ from its display text — see Path B.)

レシピ（sow-c）透かし＋ロック＋文書保護

CONFIDENTIAL の透かしを追加します（親要素は / で、/body ではありません）。ブロックレベルの SDT 3 つをロックし、インラインの signatory_name SDT をロックする方法を指示します（パスは view forms を実行した後にのみ判明します）。最後のコマンドとして protection=forms で文書を保護します。

officecli add "$FILE" / --type watermark \
  --prop text="CONFIDENTIAL" --prop color=FF0000 --prop rotation=315

officecli set "$FILE" '/body/sdt[1]' --prop lock=sdtlocked
officecli set "$FILE" '/body/sdt[2]' --prop lock=sdtlocked
officecli set "$FILE" '/body/sdt[3]' --prop lock=sdtlocked
officecli view "$FILE" forms   # copy signatory_name path, then: set '/body/p[@paraId=...]/sdt[1]' --prop lock=sdtlocked

officecli set "$FILE" / --prop protection=forms
officecli close "$FILE"
officecli query "$FILE" field     # expect 2 MERGEFIELDs: CustomerName, ContractNo

設計原則（フォーム）

コントロールタイプの決定木：

Date → type=date | Fixed list → type=dropdown | List + custom → type=combobox
Short text → type=text | Long text → type=richtext | Boolean → formfield checkbox

タイポグラフィのスケール。 間隔の単位に注意してください。spaceBefore／spaceAfter／spaceLine の既定値は twips（1/20 pt）です。必ず spaceBefore=18pt のように指定してください。

要素	サイズ	スタイル	間隔
フォームタイトル（H1）	20pt	太字	spaceBefore=0pt、spaceAfter=12pt
セクション見出し（H2）	14pt	太字	spaceBefore=18pt、spaceAfter=8pt
フィールドラベル	11pt	太字	spaceAfter=4pt
説明／注記	11pt	斜体 color=666666	spaceAfter=18pt

アクセシビリティ向けの調整。 医療／高齢者向け／アクセシビリティ重視のフォームでは、フィールドラベルと説明を 12pt に引き上げます（既定の 11pt は高齢のユーザーには小さすぎます）。セクション見出しは 14pt のままにします。

CJK フォーム： docDefaults.font="Microsoft YaHei" を設定します。Calibri には中国語のグリフがありません。

フィールドの順序。 （1）個人情報／ID、（2）役割／分類、（3）日付、（4）補足の自由記述、（5）確認／署名。

はい／いいえ＋条件付きの追加質問（コンプライアンス／医療の初回問診でよく使われます）：フォームフィールドのチェックボックスに続けて、手がかりを alias に設定した richtext SDT を配置します。例：--type formfield --prop type=checkbox --prop name=has_cond、続けて --type sdt --prop type=richtext --prop alias="If yes, explain" --prop tag=cond_detail --prop text="If yes, explain here"。

署名欄の順序。 ラベルは独立した段落に置き、SDT は次の段落に配置します（ラベルに spaceBefore=18pt、SDT に spaceAfter=4pt を設定します）。Label: SDT のようにインラインに配置しないでください。Word では run が隣接して描画され、視覚的にくっついて見えます。

構築順序。 作成＋開く → メタデータ → 構造（見出し、ラベル段落）→ SDT／フォームフィールドの骨組み（Path A 4 props）→ Path B の挿入 → フィールドごとのロック → 最後に protection=forms → 閉じる。

ヘッダー／フッターに関する注意。 ヘッダー／フッターはセクション作成時に 事前定義 されます（default／first／even がそれぞれ 3 つ）。最初の変更には add ではなく、既存パーツに対する set を使ってください。add $FILE /header ... は already exists を返すか、何もせず終了します。まず officecli query "$FILE" header --json で type の値を確認し、その後 officecli set "$FILE" '/header[@type=default]' --prop text=... を実行します。add は独自のヘッダー／フッターを持つ追加セクションを作成する場合にのみ使ってください。

バッチモード（概要）

コントロールの多いフォームでは、バッチ処理によってオーバーヘッドを削減できます。Path A と Path B は同じバッチ内で併用できます。

cat <<'EOF' | officecli batch "$FILE"
[
  {"command":"add","parent":"/body","type":"sdt","props":{"type":"text","alias":"Full Name","tag":"full_name","text":"Enter name"}},
  {"command":"add","parent":"/body","type":"sdt","props":{"type":"dropdown","alias":"Department","tag":"dept"}},
  {"command":"raw-set","part":"/document","xpath":"//w:sdt[w:sdtPr/w:tag/@w:val='dept']/w:sdtPr/w:dropDownList","action":"append","xml":"<w:listItem xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" w:displayText=\"Engineering\" w:value=\"Engineering\"/><w:listItem xmlns:w=\"http://schemas.openxmlformats.org/wordprocessingml/2006/main\" w:displayText=\"Finance\" w:value=\"Finance\"/>"},
  {"command":"set","path":"/body/sdt[1]","props":{"lock":"sdtlocked"}},
  {"command":"set","path":"/body/sdt[2]","props":{"lock":"sdtlocked"}}
]
EOF
officecli set "$FILE" / --prop protection=forms

• xml 内の " は \" でエスケープします。$var が展開されないよう、シングルクォート付きのヒアドキュメント <<'EOF' を使います。
• P0 バッチの落とし穴： 本当にサポートされていないプロパティは、バッチでは 警告なしで 無視されます（対話形式の add では WARNING: UNSUPPORTED が出力され、終了コード 2 になります）。対策：help docx sdt に記載されているプロパティ（add では type/tag/alias/text/items/format/lock/... は使用できますが、maxlength は使用できません）のみを渡し、バッチ後に読み戻して確認してください。
• batch は add、set、get、query、remove、validate、raw-set をサポートします。

納品ゲート（実行可能）

各フォームの作成後、以下のすべてのゲートを実行してください。各ゲートで OK の行が出力される必要があります。REJECT が 1 つでもあれば、納品しないでください。

# Assumes FILE=<your-form.docx>, document has been closed with officecli close "$FILE"

# Gate 1 — Validate (must be clean; protection=forms no longer produces a schema error)
VAL_OUT=$(officecli validate "$FILE" 2>&1)
VAL_ERRS=$(echo "$VAL_OUT" | grep -c '\[Schema\]')
if [ "$VAL_ERRS" -eq 0 ]; then echo "Gate 1 OK (validate clean)"
else echo "REJECT Gate 1: $VAL_ERRS schema errors"; echo "$VAL_OUT"; exit 1
fi

# Gate 2 — Token / placeholder leak (labels used as visual underscore substitutes)
LEAK=$(officecli view "$FILE" text | grep -niE '_{3,}|TBD|\(fill in\)|\{\{|xxxx|lorem|placeholder')
[ -z "$LEAK" ] && echo "Gate 2 OK (no underscore / placeholder leak)" || { echo "REJECT Gate 2:"; echo "$LEAK"; exit 1; }

# Gate 3 — At least one structured field exists
SDT_N=$(officecli query "$FILE" sdt --json | jq '.data.results | length')
FF_N=$(officecli query "$FILE" formfield --json | jq '.data.results | length')
FLD_N=$(officecli query "$FILE" field --json | jq '.data.results | length')
TOTAL=$((SDT_N + FF_N + FLD_N))
[ "$TOTAL" -gt 0 ] && echo "Gate 3 OK ($SDT_N sdt + $FF_N formfield + $FLD_N field)" || { echo "REJECT Gate 3: 0 structured fields — this is not a form"; exit 1; }

# Gate 4 — Every SDT has alias + tag (skill-imposed H2)
# NOTE: `query`/`get --json` wrap prop fields under `.data.results[N].format.{prop}` — use `.data.results[0].format.alias` / `.format.tag`, never bare `.alias` or `.data.format`.
SDT_MISSING=$(officecli query "$FILE" sdt --json | jq '[.data.results[] | select(.format.alias == null or .format.alias == "" or .format.tag == null or .format.tag == "")] | length')
[ "$SDT_MISSING" -eq 0 ] && echo "Gate 4 OK (every SDT has alias+tag)" || { echo "REJECT Gate 4: $SDT_MISSING SDT(s) missing alias or tag"; exit 1; }

# Gate 5 — Protection enforced + per-field lock inventory
PROT=$(officecli get "$FILE" / --json | jq -r '.data.results[0].format.protection // "none"')
[ "$PROT" = "forms" ] && echo "Gate 5 OK (protection=forms enforced)" || { echo "REJECT Gate 5: protection is '$PROT', expected 'forms'"; exit 1; }
officecli view "$FILE" forms | head -40   # visual spot-check: every dropdown shows items=; every date shows format=; every locked SDT shows lock=

# Gate 6 — No type=checkbox leaked onto any SDT
BAD_CB=$(officecli query "$FILE" sdt --json | jq '[.data.results[] | select(.format.type == "checkbox")] | length')
[ "$BAD_CB" -eq 0 ] && echo "Gate 6 OK (no SDT checkbox — formfield only)" || { echo "REJECT Gate 6: $BAD_CB SDT with type=checkbox"; exit 1; }

view issues がゲートではない理由。 view issues が実行するのは文章スタイルのチェック（first-line-indent、見出しのサイズ）のみで、すべてのフォームラベルに Body paragraph missing first-line indent という誤検出を大量に出します。このスキルでは無視してください。スキーマの整合性には validate を、フィールドの一覧表示には view forms を使います。

既知の問題

#	問題	動作	回避策
K1	SDT の type=checkbox は未実装です	add ... --type sdt --prop type=checkbox → Error: SDT type 'checkbox' is not implemented、終了コード 1（エラーには、group/picture を含むサポート対象の種類が表示されるようになりました）	--type formfield --prop type=checkbox を使用してください
K3	SDT の maxlength は add では未サポートです	WARNING: UNSUPPORTED: maxlength、終了コード 2。要素は作成されます。（items / format / lock / placeholderText は add でサポートされるようになりました。拒否されるのは maxlength のみです。name は受け付けられますが、SDT では何も行いません。alias / tag を使用してください）	長さは後続処理で検証してください。初期コンテンツには text を使用してください
K4	SDT の items / format / type は作成後に設定できません	set --prop items=... → UNSUPPORTED props (use raw-set instead)。（add では設定できます。作成時にインラインで設定してください）	add の時点で設定してください。後から変更するには、Path B の raw-set を使用するか、remove して再度追加してください
K5	FormField の maxlength は未サポートです	WARNING: UNSUPPORTED: maxlength。formfield は作成されます	長さは後続の検証で確認してください
K6	FormField のドロップダウンでは items は未サポートです	ドロップダウン formfield は、選択肢リストが空の状態で作成されます	代わりに --prop items= を指定した SDT ドロップダウンを使用してください
K7	Watermark の width / height は設定できません	Watermark はこれらの値なしで作成されます。opacity は add で設定でき、読み戻しもできます（実際の寸法は計算されます）	正確なサイズにするには、Word を開いて図形を調整してください（Phase 2）
K9	バッチモードでは、本当に未サポートのプロパティが警告なく破棄されます	WARNING 行は表示されません。maxlength などのプロパティが破棄されても、バッチ処理では「N succeeded」と報告されます	バッチ内の SDT エントリには、help docx sdt に記載されているプロパティのみを指定してください。バッチ処理後に読み戻して確認してください
K13	FormField の name が 20 文字を超えています	add は警告なしで終了コード 0 を返します。後で validate を実行すると、/w:ffData/w:name に対して [Schema] ... MaxLength=20 が報告されます	name は 20 文字以下にしてください（OpenXML スキーマの上限）。SDT の alias / tag にはこの制限はありません
K14	段落に対する shd.fill はスキーマに無効な <w:pPr>/<w:shd> を出力します	validate ではインスタンスごとにスキーマエラーが 2 件報告されます（unexpected child element、required attribute 'val' missing）。Word ではそのまま表示されます	代わりに run にハイライトを適用してください（shading=HEX、正規形式）。または、run の <w:rPr> に <w:shd w:val="clear" w:fill="HEX"/> を raw-set してください
K15	view forms は MERGEFIELD を一覧表示しません	出力に含まれるのは SDT と formfield のみです。MERGEFIELD はテンプレート作成時のもので、エンドユーザーが入力できるものではありません	query field と view forms は別々の一覧として扱ってください。各レシピでは両方を検証します
K16	ヘッダー / フッターはセクション作成時にあらかじめ定義されます（default/first/even が各 3 つ）	add $FILE /header ... は最初の呼び出しで already exists を返すか、何もせず終了します	最初の変更では、既存のパーツに対して set を使用します。officecli query $FILE header --json で type を読み取り、set '/header[@type=default]' --prop text=... を実行してください。add は新しいセクションのヘッダー / フッターを追加する場合にのみ使用してください
K17	ヘッダーに挿入された Watermark は、スキーマに無効な子要素 <w:noProof> を出力します	validate は /header[N]/w:sdt/.../w:noProof に追加の [Schema] エラーを報告します。これは無視できるものではなく、修正が必要な実際のスキーマエラーです	add $FILE / --type watermark の後、各ヘッダーパーツに対して一度、officecli raw-set $FILE /word/header1.xml --xpath "//w:noProof" --action remove を実行してください（header2.xml、header3.xml が存在する場合は、それらに対しても繰り返してください）
K18	query/get --json では、プロパティフィールドは .data.results[N].format.{prop} の下にネストされます	.alias / .tag / .protection、または .data.format.* を使った jq の記述では null が返るか、0 件が一致し、Gate 4/5 で誤って「missing=N」と報告されます	.data.results[].format.alias / .format.tag を使用してください。get / では .data.results[0].format.protection を使用してください（.data.format.protection ではありません）。.format.type / .format.paraId も同様です
K19	LibreOffice は PDF エクスポート時に formfield のチェックボックスを ☐☐（二重のボックス）として表示します	見た目だけの問題です。Word / WPS では単一のボックスとして表示され、クリックすると ☑ に切り替わります。LibreOffice レンダラーの問題として [RENDERER-BUG] のフラグが付いています	スキル内で「修正」しようとしないでください。評価者が LibreOffice 生成の PDF のスクリーンショットで ☐☐ を見た場合は、フォーム品質の欠陥ではなく [RENDERER-BUG] に起因するものとして扱ってください

フェーズ 2 — Word で仕上げる

一部の仕上げ作業は CLI の対象外です。これらは人間にファイルを渡して作業してもらってください。有効なフォームを作成するうえで必須ではありません。

必要な作業	Word で開く理由
特定のロック設定を備えた実際の SDT チェックボックス	type=checkbox は終了コード 1 になります。開発 → チェック ボックス コンテンツ コントロールを使用してください（または CLI から従来の FormField チェックボックスを使用してください）。
プロンプトテキスト（「ここをクリックして日付を入力」）	/word/glossary/document.xml に placeholderDocPart が必要です。
カスタム richtext の既定の外観	Word のスタイルペインで、参照先のスタイルを調整してください。
透かしのサイズ変更	width / height は設定できません。図形のハンドルをドラッグしてください。

（picture と group の SDT は --type sdt --prop type=picture / type=group で直接追加できます。フェーズ 2 の対象ではなくなりました。）

最初の 4 項目は、一度ひな形（パス C）を作成し、再利用してください。

ヘルプの参照先

迷った場合は、officecli help docx、officecli help docx <element>、officecli help docx <element> --json を参照してください。ヘルプが正式なスキーマです。このスキルは、そのスキーマを基に実際に入力可能な Word フォームを作成するための判断ガイドです。