Officecli Word Form

OfficeCLI Word-Form Skill

This skill is INDEPENDENT, not a scene layer on docx. A form's payload - <w:sdt> controls, <w:ffData> legacy fields, <w:fldChar> mail-merge, documentProtection - is a distinct element class from docx's paragraph/heading/style primitives. Its QA is different too: docx's Delivery Gate cares about visual layout and live PAGE fields, this skill's cares about data plumbing (protection enforced / alias+tag / items injected / name ≤ 20 / no underscore anti-pattern). Reverse handoff: if the user's document has no fillable fields (report, letter, memo, thesis, proposal), route to officecli-docx or a docx scene skill - don't use this one.

Runtime contract (critical)

Wayland Desktop supplies a checksum-pinned native officecli runtime. Do not install, update, download, or replace it from this skill. Run officecli --version; native authoring requires the exact verified 1.0.136 version. Verify the required form elements with officecli help docx. If either check fails, stop and use Wayland's reinstall/update recovery path. Never bootstrap mutable code or silently switch to hosted-credit generation.

Help-First Rule

This skill teaches what a real form needs, not every CLI flag. When a prop / alias / enum is uncertain, consult help BEFORE guessing: officecli help docx [element] [--json] (e.g. sdt, formfield, field). Help is pinned to installed version - when this skill and help disagree, help wins. Every --prop X= below was verified against officecli help docx <element> on v1.0.63.

Mental Model & Inheritance

A Word form is a .docx plus four OpenXML payload layers plain-docx skills do not touch: <w:sdt> content controls (5 types: text / richtext / dropdown / combobox / date), <w:ffData> legacy FormField (ONLY way to get a real checkbox on v1.0.63), <w:fldChar> complex fields (MERGEFIELD, REF, PAGEREF, SEQ, IF - template-time, not user-fill), and documentProtection (the lock that makes non-field text read-only in Word).

No inheritance from docx v2. docx's Delivery Gate (cover-fill %, live-PAGE check) does NOT apply - form QA is view forms + query sdt alias+tag + protectionEnforced.

Reverse handoff to docx. Route back to officecli-docx for reports / letters / memos / thesis / pitch decks / any document with no editable fields. Use this skill when the document's purpose is data capture or template merge.

Shell & Execution Discipline

One command at a time. Read output before the next. OfficeCLI is incremental - every add / set / remove immediately mutates the file. All recipes below use FILE=form.docx as a shell variable.

Three shell-escape layers:

1. Quote every path with [N] - zsh/bash glob-expand brackets. officecli get "$FILE" /body/sdt[1] fails with no matches found. Correct: officecli get "$FILE" '/body/sdt[1]'.
2. Single-quote any prop containing $ - "Total: $50,000" becomes "Total: ,000" after $50 variable expansion. Correct: 'Total: $50,000'.
3. --after find:<text> uses outer single quotes, never inner double quotes - --after find:"Client Signature:" makes the quotes part of the search string; match fails. Correct: --after 'find:Client Signature:'.

WARNING: UNSUPPORTED (exit 2) is a silently-wrong element. The CLI created the element without the rejected prop - dropdown with no items, date with default format, SDT with no lock. Any UNSUPPORTED in your build log means your command was wrong: stop, rewrite to Path B (raw-set) or a separate set. Do not ship on top.

protection=forms is the LAST command. Not CLI-enforced - add / set / raw-set still run under any protection mode - but finishing with protection gives Word users a consistent locked experience on first open.

--after find: micro-playbook

--after find:<text> matches the first occurrence. Bad anchor = wrong insertion location, expensive to debug. Three rules:

1. Anchor must be globally unique. In a two-party contract a label like "Signature" matches both parties - use a unique phrase like "Signature (Service Provider)" or a full role-qualified title.
2. After insert, /body/p[last()] is unreliable - the find insertion changes <w:body> child order. To continue operating on the new paragraph, read its real paraId: officecli query "$FILE" paragraph --json | jq -r '.data.results[-1].format.paraId'.
3. Non-ASCII characters and full-width parens （） match literally in find, but when unsure, officecli view "$FILE" text | grep -n "anchor" first to confirm the exact bytes in the file.

# Trap: first-match hits Party A only, Party B missed
officecli add "$FILE" /body --type sdt --after 'find:Signature'

# Fix: two signatories, two unique anchors
officecli add "$FILE" /body --type sdt --prop alias=Party_A_Name --prop tag=party_a \
  --after 'find:Signature (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

Inline SDT via --after find: is added as a child of the matched paragraph, not as a new paragraph - use this when label + SDT must share a line.

What makes a real form (identity)

A real fillable form requires structured fields + document protection.

Do not simulate fields with underscores. Name: _______________ produces zero structured data and leaks past every verification. Always use --type sdt or --type formfield.

Checkbox is formfield, NOT SDT. --type sdt --prop type=checkbox exits 1 (SDT type 'checkbox' is not implemented). Every checkbox in every recipe uses --type formfield --prop type=checkbox.

MERGEFIELD is a separate track. view forms lists SDT + formfield only; query field lists complex fields only. Two disjoint inventories; both valid in one file.

Requirements for Outputs (hard floor)

Every form must satisfy these - Delivery Gate enforces each as an executable check.

1. protection=forms enforced (get $FILE / → protectionEnforced=True).
2. Every SDT has both alias + tag.
3. Every dropdown/combobox has non-empty items=... in view forms.
4. Every date SDT shows the intended format=....
5. Every locked SDT shows lock=sdtLocked / contentLocked / sdtContentLocked as intended.
6. Zero WARNING: UNSUPPORTED in build log.
7. Zero type=checkbox on any SDT.
8. Every formfield name ≤ 20 characters.
9. Zero underscore-line / blank-line placeholders.
10. Field types match user intent (short text / paragraph / fixed list / list+custom / date / boolean).

Three Paths (core decision)

CLI v1.0.63 exposes exactly four canonical props on SDT: {type, tag, alias, text}. Everything else - items, format, lock, placeholder, name, maxlength - is UNSUPPORTED at add-time and silently discarded. The skill therefore splits every SDT need into three paths. Pick the path before writing a single command.

Path A - Pure CLI (simple forms)

Use when: the field only needs a label, an initial text, and a type. Acceptable if dropdown/combobox items can be empty at first and dates can default to yyyy-MM-dd.

officecli add "$FILE" /body --type sdt \
  --prop type=text \
  --prop alias="Full Name" --prop tag=full_name \
  --prop text="Enter full name"
# Canonical follow-ups (not on add):
# officecli set "$FILE" '/body/sdt[N]' --prop lock=sdtlocked
# officecli set "$FILE" / --prop protection=forms

Path B - CLI + raw-set bridge (complex attrs)

Use when: dropdown/combobox needs options, or date needs a non-default format. raw-set is OfficeCLI's universal OpenXML fallback - officecli --help lists it as a top-level command.

# Step 1 - Path A skeleton (generates <w:dropDownList/> automatically)
officecli add "$FILE" /body --type sdt \
  --prop type=dropdown --prop alias="Department" --prop tag=dept

# Step 2 - raw-set injects <w:listItem>s
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"/>'

Path C - Word template (beyond raw-set)

Use when: picture SDT (signature image), real SDT checkbox (type=checkbox exits 1), placeholderDocPart prompt text, grouped SDTs wrapping multiple paragraphs, or custom richtext appearance. These involve cross-part relationships or nesting beyond --prop reach.

# 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

Decision table

Quick Start - Path A + FormField (minimal intake form)

Two SDT text fields, one checkbox, protection. Paste and adapt; this is the smallest form worth shipping.

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

Path B - raw-set recipes

Three recipes cover almost every complex-attr need on SDT forms.

B1 - Dropdown items (append)

# 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

Template. Swap <TAG> / <LABEL> / <VALUE> only. xmlns:w=... is required on every root <w:listItem> - raw-set does not inherit namespace prefixes. Chain multiple <w:listItem>s in one call; option order is preserved.

B2 - Combobox items (same as B1, different xpath tail)

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"/>'

Only difference from B1: w:comboBox vs w:dropDownList in the xpath tail. Combobox lets the user type custom input; dropdown does not.

B3 - Date format (setattr)

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

# US:    w:val=MM/dd/yyyy
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=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=MM/dd/yyyy

setattr replaces one attribute - do not quote the value inside --xml. Only w:val is touched; the <w:dateFormat> wrapper is preserved.

raw-set actions & errors

Path C - Word template workflow

For fields CLI cannot express (signature picture SDT, real SDT checkbox, placeholderDocPart prompt text, grouped SDTs, custom richtext styling), build the skeleton once in Word, then fill via CLI.

One-time in Word: File → Options → Customise Ribbon → Developer. Developer tab → Insert Picture / Check Box / Grouping Content Control → right-click → Properties → set Title (alias) + Tag. Save as template.docx.

Fill via 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 (data-driven track)

help docx field on v1.0.63 declares a fieldType enum of ~30 values including mergefield, ref, pageref, seq, if - all CLI-expressible with their typed props. MERGEFIELD coexists with SDT in the same file but is reported by query field only; view forms does NOT list MERGEFIELDs (they are not user-fillable).

Canonical 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»"

Element-type shortcut (equivalent): officecli add "$FILE" '/body/p[1]' --type mergefield --prop name=CustomerName.

Common field patterns

IF conditional (CLI-expressible on v1.0.63)

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»"

Nested wrappers like { IF { MERGEFIELD X } = "Y" { REF bm } "fallback" } are not expressible via --prop chaining - drop to raw-set a hand-crafted <w:fldChar> / <w:instrText> fragment, or build once in a Word template (Path C).

Readback. query $FILE field lists /field[N] + instruction + fieldType. view $FILE forms does NOT list MERGEFIELDs (only SDT + formfield) - they are template-time, not end-user fillable. get $FILE '/body/p[1]' renders the guillemet-wrapped field name.

Legacy FormField

Use FormField when you need a real checkbox. For text/dropdown, prefer SDT.

help docx formfield: type (text/checkbox/check/dropdown), name (required, ≤ 20 chars - OpenXML schema MaxLength; add passes longer but validate rejects), text (text only, alias value), checked (checkbox only).

# CHECKBOX - the only real checkbox available in v1.0.63
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 paths (/formfield[N] or /formfield[<name>]) are separate from SDT paths (/body/sdt[N]). Both coexist; protection=forms covers both.

Scale. Tested with 50+ checkboxes in a single document - no practical cap on formfield count; build and validate remain clean. name ≤ 20 chars (K13) is the only hard constraint.

Renderer note - formfield checkbox [RENDERER-BUG]. LibreOffice's PDF export occasionally renders the formfield checkbox as ☐☐ (doubled box). Word and WPS render a single clickable box (toggles ☑). This is a LibreOffice renderer quirk, not a skill or document quality issue - see K19. Do not attempt workarounds in the form; if an evaluator screenshots a LibreOffice-generated PDF and sees ☐☐, attribute to [RENDERER-BUG].

Document protection & lock

Enabling form protection

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

Protection modes

KEY: Document protection restricts Word users, not the CLI. You can fill / modify / lock a protected form via CLI freely. The CLI does NOT require --force on v1.0.63.

Lock values (applied via set, never add)

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=... on add is UNSUPPORTED (silently discarded). Apply lock via a separate set. Readback normalises to camelCase (sdtLocked) regardless of input case - both accepted.

lock × protection=forms interaction