OfficeCLI Academic Paper Skill

This skill is a scene layer on top of officecli-docx. Every docx hard rule — style architecture, heading hierarchy, shell quoting, page-break rules, live PAGE field, Delivery Gate, renderer quirks — is inherited, not re-taught. This file adds only what academic papers need on top: citation styles, equations, SEQ / PAGEREF cross-refs, multi-column journal layout, bibliography hanging indent, abstract/keywords/affiliation block.

When the docx base rules cover it, the text here says → see docx v2 §X. Read docx v2 first if you have not.

Setup

If officecli is missing:

• macOS / Linux: curl -fsSL https://d.officecli.ai/install.sh | bash
• Windows (PowerShell): irm https://d.officecli.ai/install.ps1 | iex

Verify with officecli --version (open a new terminal if PATH hasn't picked up). If install fails, download a binary from https://github.com/iOfficeAI/OfficeCLI/releases.

⚠️ Help-First Rule

This skill teaches what an academic paper requires, not every command flag. When a prop name, enum value, or field instruction is uncertain, consult help BEFORE guessing.

officecli help docx                          # All docx elements
officecli help docx <element>                # Full schema (e.g. section, equation, field, footnote)
officecli help docx <element> --json         # Machine-readable

Help is pinned to the installed CLI version. When this skill and help disagree, help wins. Every --prop X= in this file has been grep-verified against officecli help docx <element> — if help adds / renames a prop in a later version, trust help.

Mental Model & Inheritance

Inherits docx v2. You should have read skills/officecli-docx/SKILL.md first. This skill assumes you know how to add paragraphs, set styles, build tables, insert images, manage TOC/footer/headers, force page breaks, and run the Delivery Gate. If any of those are unfamiliar, open a second session on docx v2 before continuing.

Shell & Execution Discipline

Shell quoting, incremental execution, $FILE convention → see docx v2 §Shell & Execution Discipline. The same rules apply here verbatim — quote [N] paths, single-quote any value containing $ (including $2.8B in a body paragraph or @ DOIs), never hand-write \$ \t \n in executable examples, one command at a time. Academic-paper examples below use $FILE as a shell variable (FILE="thesis.docx").

What "academic" means here (identity)

An academic paper is a docx with a scholarly layer on top: verifiable citations, precise equations, cross-refs that stay in sync, a formatted reference list. The base docx rules still apply; academic adds six deltas:

1. Citation style is a contract. APA / Chicago / IEEE / MLA each dictate author format, date placement, reference-list order, in-text marker shape. Pick one at the start; every later decision (hanging indent, footnote vs parenthetical, [1] vs (Smith, 2024)) follows.
2. Equations are first-class content — inline oMath inside prose, display oMathPara as standalone blocks, optionally numbered.
3. Figures and tables auto-number. SEQ Figure / SEQ Table fields count them; PAGEREF links "see Fig. 2" to its live page number.
4. Bibliography uses hanging indent (first line flush left, continuation lines indented). Not first-line indent. Not left indent alone. Hanging.
5. Abstract / keywords / affiliation block is a first-page three-piece, not a cover in the marketing sense. Block-style abstract, no first-line indent, no decoration.
6. Multi-column layout appears in IEEE / ACM / Nature / many journals: single-column abstract + two-column body.

Reverse handoff — when to go BACK to docx

Stay in docx v2 for white papers, policy briefs, technical reports, HR templates — anything without a venue / citation style. Use this skill only when the document will carry at least TWO of: citation-style biblio, equations, SEQ/PAGEREF cross-refs, multi-column, abstract + keywords block.

Workflow — 5 verbs

1. Read the venue spec. APA 7 / Chicago 17 / IEEE / MLA 9 / journal-specific. Line spacing, font, citation shape, biblio sort order — everything downstream follows from this one decision.
2. Plan the sections. Abstract → keywords → introduction → methods → results → discussion → conclusion → references. Estimate heading count for TOC decision (3+ headings = add a TOC, see docx v2 §Table of Contents).
3. Set styles up front. Heading1 / Heading2 / Heading3 / Caption / AbstractTitle / Bibliography. Define all styles BEFORE any content (→ see docx v2 §Paragraphs and styles — same rule here, same failure mode if skipped).
4. Build body in order. Cover / title block → abstract → keywords → TOC (if needed) → body sections in reading order → figures / tables with SEQ captions → bibliography → footnotes are added last by paragraph path.
5. QA — Delivery Gate. Inherit docx v2 Gates 1-3, then add academic Gates 4-5 below.

Requirements (academic floor on top of docx v2)

Everything in docx v2 §Requirements for Outputs applies. On top of that, academic papers MUST meet these additional rules:

Typography and spacing (venue-aware)

• Font. Times New Roman 11-12pt body (default) or venue-specified (IEEE uses Times 10pt 2-col; APA allows Calibri 11pt). Same body font throughout; no decorative heading fonts.
• Heading hierarchy. H1 = 20pt bold, H2 = 14pt bold, H3 = 12pt bold italic, body = 11-12pt. (Same numbers as docx v2 — restated because academic papers never rely on Word defaults.)
• Line spacing. APA 7 = 2x (double). Chicago / IEEE / most journals = 1.5x. Never below 1.15x. Set on body paragraphs and on References.
• Margins. 1 inch (1440 twips) all sides unless the venue says otherwise (some journals require 1.25in left for binding — check the spec).

Abstract, bibliography, caption placement

• Abstract is block-style. NO firstLineIndent. Use spaceAfter=12pt for paragraph separation. If view issues reports "body paragraph missing first-line indent" on an Abstract paragraph, it's a false positive — ignore.
• Bibliography uses hanging indent. Each entry is one paragraph with indent=720 hangingIndent=720 (left indent 0.5", first-line reversed by same amount). First line flush left; wraps indent under author name.
• Figure captions go BELOW the figure. Table captions go ABOVE the table. This is the single rule most non-academics get wrong — APA, Chicago, IEEE, MLA all agree on it.
• Citation round-trip. Every in-text citation key must resolve to an entry in the reference list. Delivery Gate 4 verifies.
• SEQ presence. Any paper with numbered figures or tables must carry live SEQ Figure / SEQ Table fields (not hardcoded "Figure 1" text that drifts when you insert a new figure mid-document). Delivery Gate 5 verifies.

Cover / first-page block

Academic covers differ from professional covers. Minimum elements: title (centered, 20-22pt bold), author(s), affiliation, submission target or journal, date, abstract, keywords. The "60% fill" rule from docx v2 §Visual delivery floor still applies — a three-line cover with half a page of whitespace is a fail. See §Abstract / keywords / affiliation block below for the first-page recipe.

Section numbering convention (STYLE-DEPENDENT — do not apply blindly)

Academic section numbers are part of the heading text, not computed via list numbering. officecli's numId/listStyle mechanism is fragile across Heading1 re-use, so hand-write the prefix. BUT the prefix shape varies by style — DO NOT use the same form for all four:

APA 7 L1 headings are centered, bold, unnumbered; L2 are flush-left bold; L3 flush-left bold italic; L4/L5 run-in. Do NOT prefix APA headings with 1. / 2. — that is Chicago/IEEE convention. IEEE wants ALL CAPS with Roman numerals (I. INTRODUCTION); inside each section, use A./B./C. sub-headings (title case). Arabic-numbered body sections are Chicago-style only.

Exception for all four: References / Bibliography / Works Cited / Acknowledgments are unnumbered regardless of style — omit the N. prefix.

Quick Start — minimal APA paper

FILE="paper.docx"
officecli create "$FILE"
officecli open "$FILE"
officecli set "$FILE" / --prop defaultFont="Times New Roman"
officecli add "$FILE" /body --type paragraph --prop text="Remote Work and Team Cohesion" --prop align=center --prop size=20pt --prop bold=true --prop spaceAfter=24pt
officecli add "$FILE" /body --type paragraph --prop text="Alice Chen" --prop align=center --prop size=12pt
officecli add "$FILE" /body --type paragraph --prop text="Department of Psychology, Stanford University" --prop align=center --prop size=11pt --prop spaceAfter=24pt
officecli add "$FILE" /body --type paragraph --prop text="Abstract" --prop align=center --prop size=14pt --prop bold=true --prop spaceBefore=12pt --prop spaceAfter=6pt
officecli add "$FILE" /body --type paragraph --prop text="This study examines remote-work adoption on team cohesion across 18 months..." --prop size=12pt --prop lineSpacing=2x --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Keywords: remote work, team cohesion, psychological safety" --prop italic=true --prop size=11pt --prop spaceAfter=18pt
officecli add "$FILE" /body --type paragraph --prop text="1. Introduction" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Remote-work research (Smith, 2024) has expanded since 2020..." --prop size=12pt --prop lineSpacing=2x --prop firstLineIndent=720
officecli add "$FILE" /body --type paragraph --prop text="References" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt --prop spaceAfter=12pt
officecli add "$FILE" /body --type paragraph --prop text="Smith, J. (2024). Remote work and cohesion. Journal of Applied Psychology, 109(3), 412-430." --prop size=12pt --prop lineSpacing=2x --prop indent=720 --prop hangingIndent=720
officecli add "$FILE" / --type footer --prop type=default --prop align=center --prop size=10pt --prop field=page
officecli close "$FILE"
officecli validate "$FILE"

Ten-line skeleton. Real papers grow by adding more body paragraphs, more bibliography entries (each with the same indent=720 hangingIndent=720 pair), figures / tables with captions, and a TOC if there are 3+ Heading1s. The Quick Start validates clean; the sections below elaborate each dimension.

Citation style recipes

Four mainstream families. Pick one at project start; every downstream decision follows. Per-style decision table:

Shared defaults across all four: reference-list paragraphs use indent=720 hangingIndent=720 (hanging indent 0.5"); add a live TOC if 3+ Heading1s (→ see docx v2 §Table of Contents); set updateFields=true and report TOC page numbers as uncomputed until a Word-compatible field engine updates them.

APA 7 (social sciences — psychology, education, management)

• In-text: (Author, Year) or Author (Year) for narrative. Page number required on direct quotes: (Smith, 2024, p. 15). Three+ authors: (Smith et al., 2024) after first citation.
• Reference list order: alphabetical by first author's surname. Title caps: sentence case for article titles, title case for journal names (italic).
• Reference shape: Author, A. A., & Co-Author, B. B. (Year). Title of article. Journal Name, Volume(Issue), pages. DOI preferred over URL; present as https URL, not doi: prefix.
• Double-space everything (lineSpacing=2x) including abstract and references. Body first-line indent = 0.5" (firstLineIndent=720).

# Body paragraph with parenthetical citation
officecli add "$FILE" /body --type paragraph --prop text="Remote work adoption accelerated during the pandemic (Kramer & Kramer, 2020)." --prop size=12pt --prop lineSpacing=2x --prop firstLineIndent=720
# Reference entry with hanging indent
officecli add "$FILE" /body --type paragraph --prop text="Kramer, A., & Kramer, K. Z. (2020). The potential impact of the Covid-19 pandemic on occupational status. Journal of Vocational Behavior, 119, 103442." --prop size=12pt --prop lineSpacing=2x --prop indent=720 --prop hangingIndent=720
# DOI hyperlink appended to the reference paragraph
officecli add "$FILE" "/body/p[last()]" --type hyperlink --prop url="https://doi.org/10.1016/j.jvb.2020.103442" --prop text="https://doi.org/10.1016/j.jvb.2020.103442"

QA: officecli query "$FILE" 'paragraph[hangingIndent]' returns every reference entry; zero references with first-line indent instead of hanging.

Chicago 17 — Notes-Bibliography (humanities — history, philosophy, religion)

• In-text: superscript footnote number; full citation in the first footnote (Timothy Brook, The Troubled Empire (Cambridge, MA: Harvard UP, 2010), 142.); shortened form thereafter (Brook, Troubled Empire, 150.).
• Repeat-citation rule (Chicago 17, op. cit. deprecated):
• Immediately-consecutive citation of the same source, same page → Ibid.
• Immediately-consecutive, different page of same source → Ibid., 22.
• Non-consecutive repeat → shortened form (Brook, Troubled Empire, 150.), NOT op. cit.. Chicago 17 drops op. cit. — use shortened form every time except for immediate repeats.
• Bibliography at end, alphabetical by first author's surname ("Brook, Timothy."), hanging indent. Footnote body renders at the viewer's footnote default (typically 10pt); bibliography entries 12pt. (The footnote element exposes only text — size is not settable per-footnote; trust renderer defaults.)
• Typical split for primary-source-heavy papers: Primary Sources and Secondary Sources as two Heading2s under a single Bibliography Heading1. Book titles italic in both footnotes and bibliography.
• Chicago also has an Author-Date variant used in the sciences — if the venue specifies Chicago Author-Date, fall back to the APA recipe and change only the punctuation (no comma between author and year: (Smith 2024)).

# Body paragraph that will anchor a footnote, then the footnote itself
officecli add "$FILE" /body --type paragraph --prop text="The Ming dynasty's 海禁 policy shaped coastal trade for two centuries." --prop size=12pt --prop lineSpacing=1.5x --prop firstLineIndent=720
officecli add "$FILE" "/body/p[last()]" --type footnote --prop text="Timothy Brook, The Troubled Empire: China in the Yuan and Ming Dynasties (Cambridge, MA: Harvard University Press, 2010), 142."
# Next footnote — shortened form
officecli add "$FILE" "/body/p[last()]" --type footnote --prop text="Brook, Troubled Empire, 150."
# Bibliography section split — primary sources first
officecli add "$FILE" /body --type paragraph --prop text="Bibliography" --prop style=Heading1 --prop size=20pt --prop bold=true --prop spaceBefore=18pt
officecli add "$FILE" /body --type paragraph --prop text="Primary Sources" --prop style=Heading2 --prop size=14pt --prop bold=true --prop spaceBefore=12pt
officecli add "$FILE" /body --type paragraph --prop text="Ming Shilu 明實錄. Taipei: Academia Sinica, 1966." --prop size=12pt --prop indent=720 --prop hangingIndent=720
officecli add "$FILE" /body --type paragraph --prop text="Secondary Sources" --prop style=Heading2 --prop size=14pt --prop bold=true --prop spaceBefore=12pt
officecli add "$FILE" /body --type paragraph --prop text="Brook, Timothy. The Troubled Empire: China in the Yuan and Ming Dynasties. Cambridge, MA: Harvard University Press, 2010." --prop size=12pt --prop indent=720 --prop hangingIndent=720

QA: officecli query "$FILE" 'footnote' count ≥ body-paragraph citation count.

IEEE (engineering — transactions, conference proceedings)

• In-text: [1], [2]. Numbered in order of first appearance, not alphabetical. Reuse the same number for repeat citations. [1, p. 15] for page refs, [1]-[3] for a range.
• Reference entry starts with the bracketed number: [1] A. Smith and B. Jones, "Title," IEEE Trans. X, vol. 5, no. 3, pp. 1-10, 2024, doi: .... Authors are initial-first; journal names abbreviated per IEEE list (IEEE Trans. Neural Netw., not full name).
• Body is two-column (see §Multi-column below). Abstract is single-column above the fold, 10pt, 1.15x line spacing, typically 200-250 words.
• First-line indent on body paragraphs = 0.2" (firstLineIndent=288 twips ≈ 14pt). Smaller than APA's 0.5" because the 2-col width is narrower.
• Section headings: ALL CAPS with Roman numerals — I. INTRODUCTION, II. RELATED WORK, III. METHOD. Sub-sections A. Datasets, B. Baselines in title case. Do NOT use 1. Introduction (Arabic) for IEEE — that is Chicago style.
• Tables are numbered Roman: Table I, Table II, Table III. Figures remain Arabic (Fig. 1, Fig. 2). recalcFields=seq writes Arabic cached values for both — for IEEE Roman tables, either patch the cached <w:t> to Roman manually after recalc, or accept Arabic and note it in the cover letter.

# Body citing reference 1
officecli add "$FILE" /body --type paragraph --prop text="Attention-based anomaly detection has been applied to industrial sensor data [1], [2]." --prop size=10pt --prop lineSpacing=1.15x
# Reference list entry — number in the text
officecli add "$FILE" /body --type paragraph --prop text="[1] A. Smith and B. Jones, \"Attention for anomaly detection,\" IEEE Trans. Neural Netw., vol. 35, no. 2, pp. 412-430, 2024." --prop size=10pt --prop indent=720 --prop hangingIndent=720
officecli add "$FILE" /body --type paragraph --prop text="[2] C. Lee, \"Time-series anomaly survey,\" in Proc. ICML, 2023, pp. 1200-1215." --prop size=10pt --prop indent=720 --prop hangingIndent=720

QA: the highest [N] in body must equal the number of reference-list entries. Grep: officecli view "$FILE" text | grep -oE '\[[0-9]+\]' | sort -u | tail -5.

MLA 9 (literature, languages, cultural studies)

Diff vs APA: in-text is (Author Page) no comma (e.g. (Smith 412)); direct quotes always carry the page number. Reference section titled Works Cited (not References / Bibliography). Entries alphabetical by surname, hanging indent, 2x spacing, nine "core elements" separated by periods: Author. Title. Container, Other Contributors, Version, Number, Publisher, Date, Location. — skip any that don't apply. Book titles italic; article titles in quotes. Otherwise identical to APA paragraph setup.

Equations (OMML — inline vs display)

--type equation parses a LaTeX-ish formula into OMML. Two modes, selected by --prop mode=:

# Display equation (own paragraph, centered) — explicitly set mode=display for clarity
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="x^2 + y^2 = z^2"
# Display equation with Greek / subscript / integral — verify rendering below
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="\\lambda_1 + \\alpha"
officecli add "$FILE" /body --type equation --prop mode=display --prop formula="\\frac{1}{2\\pi} \\int_0^{\\infty} e^{-x^2} dx"
# Inline equation INSIDE prose — required whenever variables like x_{t+1}, \lambda, etc. appear in a body paragraph:
officecli add "$FILE" /body --type paragraph --prop text="Given the weight " --prop size=11pt
officecli add "$FILE" "/body/p[last()]" --type equation --prop mode=inline --prop formula="W_t"
officecli add "$FILE" "/body/p[last()]" --type run --prop text=" we define the loss..."

Verify equations render as OMML math, not plain-text LaTeX tokens. After close, run:

officecli view "$FILE" text | head -20       # λ₁ + α, ∫₀∞, x² must appear as unicode math (verified renders)
officecli raw "$FILE" /document | grep -c '<m:oMathPara'   # ≥ 1 per display equation

If the body prose contains raw lambda_1, x_{t+1}, \alpha or similar plain-text tokens (i.e., you typed them into a paragraph --prop text= instead of wrapping with --type equation --prop mode=inline), downstream viewers will render them as literal ASCII. Rule: every mathematical variable / Greek letter / subscript in prose goes through --type equation mode=inline, never through paragraph --prop text=.

LaTeX subset pitfalls (non-negotiable):

1. \left(...\right) / \left[...\right] with a sub/superscript inside the delimiters → parse error (Error: cast object … Subscript). An OUTER script (\left(x+y\right)^2) is fine; plain (, ), [, ] always work and OMML auto-sizes them in display mode.
2. move on /body/oMathPara[N] reorders the display equation (it repositions the wrapping paragraph). --before <path> may leave a stray empty paragraph; prefer --index or --after for a clean reorder.

Equation numbering — no native \eqno. The journal-standard layout is one line: equation centered, number flush-right at the column edge (Y = A(X) ⊗ X (1)). Build it with two paragraph tab stops — a center tab at the column mid-point and a right tab at the column right edge — then lay out [tab] equation(inline) [tab] (1) in a single paragraph. Do NOT use a centered display equation followed by a separate right-aligned (1) line — that splits the number onto its own line and is the most common reason agents fail to reproduce the expected look.

# Tab positions depend on the COLUMN width (twips). Default blank doc = A4, 3.18cm margins
#   → text width = 8300 twips.
#   single column: center tab = 4150, right tab = 8300
#   two columns (default 720-twip gutter): col = (8300-720)/2 = 3790 → center 1895, right 3790
# (other page size / margins: text width = pageWidth - marginLeft - marginRight; recompute.)
officecli add "$FILE" /body --type paragraph                                   # the equation paragraph (say it lands at p[N])
officecli add "$FILE" "/body/p[N]" --type tab --prop pos=4150 --prop val=center
officecli add "$FILE" "/body/p[N]" --type tab --prop pos=8300 --prop val=right
officecli add "$FILE" "/body/p[N]" --type run --prop text=$'\t'                 # tab → jump to center
officecli add "$FILE" "/body/p[N]" --type equation --prop mode=inline --prop formula='Y = A(X) \otimes X'
officecli add "$FILE" "/body/p[N]" --type run --prop text=$'\t(1)'             # tab → jump to right edge, then the number

For a two-column section just use the two-column tab positions (1895 / 3790); the same paragraph then centers the equation within its column with (1) at the column's right edge. Schema: officecli help docx tab.

**Do NOT place --type equation directly o