/brand-docx

name: brand-docx
description: >-
  Brand-aware Word engine. Use to (1) EXTRACT a company's brand from a Word template into a
  reusable "Brand Profile", (2) COMPREHEND the template with the model (optional), (3) VERIFY it,
  (4) GENERATE new on-brand .docx documents FROM a saved profile. Trigger on "extract our brand",
  "learn/match this template", "use our brand kit", "generate a branded report from our profile",
  or when a ./brand-kit exists. For one-off Word edits with NO saved brand profile, use the docx
  skill instead. NOT for .pptx (brand-pptx), .xlsx (brand-xlsx), or PDFs.

brand-docx

Use this skill when the user wants a reusable Word brand kit or wants to create a new on-brand `.docx` from a company template and variable content.

This is an AI-agent skill for Codex and Claude Code. The user should not need to write JSON or run shell commands. The agent converts the user's content into an IntermediateDocument, invokes the internal engine, verifies the output, and returns the generated `.docx`.

The seven verbs: three deterministic + four model-assisted

Every brand skill (`brand-docx`, `brand-pptx`, `brand-xlsx`) implements the same contract. The deterministic core is **extract / verify / generate**; on top of it sit the optional learning verbs **comprehend / learn / propose-overrides / refine**, each fail-closed (the engine validates every proposal and authors every value).

| Verb | Input | Output | |---|---|---| | **extract** | a company `.docx` template | a reusable Brand Profile | | **comprehend** *(optional, model-driven)* | a saved profile + a model-authored `comprehension.json` | the profile with a validated, cached `comprehension` block | | **verify** | a saved Brand Profile | QA findings + a verdict | | **generate** | content (an IntermediateDocument) + a profile | a new on-brand `.docx` | | **learn** *(deterministic distillation)* | the profile's cross-run generation history | recurring QA findings distilled into shell-frozen overrides, advisory until `--accept` | | **propose-overrides** *(model-driven)* | the recurring remainder `learn` could not bind + a model-authored proposal | shell-backed corrections through the same fail-closed sink, advisory until `--accept` | | **refine** | end-of-generation user feedback (text or a screenshot) as a `refinement.json` delta | the existing comprehension overlaid for FUTURE generations, advisory until `--accept` |

`comprehend` is **optional**: `generate` works on the deterministic profile alone. When a current comprehension is present, `generate` additionally reconciles the template's preserved cover/index structures with the new content. See [reference/comprehension.md](reference/comprehension.md) for the full step.

Hard Rules

• Treat `python scripts/cli.py ...` as an internal engine command, not the user-facing workflow.
• `scripts/cli.py` is a LAUNCHER that locates the engine root by itself: it works from this skill folder AND from the repo/plugin root (set `BRAND_DOCS_ROOT` to override). Never guess deeper paths like `scripts/brandkit/...`.
• Run the dependency preflight before starting extract / comprehend / verify / generate, and report missing or unusable dependencies before proceeding.
• Extract opens the source template read-only and saves `brand-kit/<name>/template/shell.docx` byte-for-byte.
• Generate opens the saved shell and resolves every semantic block through `profile.json`.
• Do not put style names, colors, fonts, or brand identifiers in an IntermediateDocument.
• If the user did not provide a template or enough content, ask for the missing input.
• Return the generated file path plus a QA summary.
• Consult `profile.json.artifact_catalog` before generation when the user asks to mimic a specific piece of the template.

Preflight (always first)

Before doing any work, run:

python scripts/cli.py doctor

Use its output to decide the run mode:

• If a required Python dependency is missing, install/repair it before extraction

or generation; the core engine is not ready.

• If only visual renderers are missing or unusable (`soffice` plus `pdftoppm` or

optional PyMuPDF/`fitz`), the core L0 workflow can still run, but a full visual audit cannot be claimed. Tell the user what is missing, include the install/repair hint printed by `doctor`, and either proceed with degraded QA or install the renderer first.

• If optional OCR (`tesseract`) is missing, the visual audit can still run, but

rendered residual-text proof is incomplete. Report that limitation when judging stale placeholders or field caches.

• For `--qa deep` or `--qa strict`, prefer repairing/installing renderers before

generation. If the environment cannot run them, `deep` generates a degraded manifest and `strict` fails with a visual proof blocker.

Agent Workflow

1. Run the dependency preflight above and report any degraded capability. 2. Determine the brand name and locate the user-provided `.docx` template. 3. If no matching `brand-kit/<name>` exists, **extract** one. 4. **Comprehend** the template (optional, model-driven; see below). Skip when a current comprehension is already cached or no model is available. 5. Convert the user's requested content into `IntermediateDocument` JSON. 6. **Generate** the `.docx` with the internal engine. 7. Run **QA** and report any warnings honestly. 8. **Feedback** (only after returning the file): invite a refinement of the understanding for future documents (see below).

Before generation, inspect `profile.json.artifact_catalog` when the user asks to mimic a specific template piece. It records OOXML parts, media parts, paragraph/table styles, style details, sections/margins, paragraph samples, and table counts.

Authoring the IntermediateDocument

The IDoc is where "correct document" becomes "great document". Author it role-first, against the profile, never style-first:

1. **Read `brand-kit/<name>/PROFILE.md` before writing a block.** It lists the role