edgemint

name	edgemint
description	Generate style-faithful DOCX documents from Markdown using the edgemint CLI. Use this skill when the user wants to: create a branded Word document from Markdown or AsciiDoc, extract visual styles from a .docx template, regenerate a document after editing its content, diff two style sheets, audit a template change, or automate a batch document pipeline. Handles all edgemint commands: extract-styles, extract, apply-styles, diff, validate, info, schema.
argument-hint	[template.docx] [action: extract|apply|diff|batch|inspect]
allowed-tools	Bash(edgemint *) Bash(pip install *) Bash(pandoc *) Read Write
effort	high

edgemint — DOCX Style Extraction & Document Generation

You are an expert at producing style-faithful Word documents from Markdown source using the edgemint CLI. You understand DOCX named styles, Pandoc Extended Markdown custom-style annotations, and the three-file architecture (content.md + styles.json + media/).

---

0. Prerequisites Check

Before any operation, verify edgemint is installed:

edgemint --version 2>/dev/null || echo "NOT_INSTALLED"

If NOT_INSTALLED:

pip install "edgemint[pandoc]"

Pandoc is required for extract and apply-styles. Confirm:

pandoc --version 2>/dev/null | head -1 || echo "PANDOC_MISSING"

---

1. Core Concept

edgemint separates what a document looks like from what it says:

  template.docx  ──extract-styles──►  styles.json   (visual identity)
  content.md     ──apply-styles ──►   output.docx   (content + identity = output)

styles.json is the portable visual identity. Check it into version control. content.md is plain Pandoc Extended Markdown. Edit it freely.

---

2. Workflows

Workflow A — Extract styles from a template

When the user has a .docx template and wants to understand or capture its styles:

edgemint extract-styles template.docx -o styles.json --resolved

Then read styles.json and summarise:

• Total style count by type (paragraph / character / table)
• Key custom styles (non-built-in, branded names)
• Theme fonts (headings vs. body)
• Color palette from theme

Present a table: name | type | font | size_pt | color.

---

Workflow B — Generate a styled document

When the user wants to produce a branded .docx from Markdown content:

1. If no styles.json exists yet, run Workflow A first.
2. Read styles.json — note every available name value precisely.
3. Write content.md using Pandoc Extended Markdown and custom-style annotations.
4. Run edgemint apply-styles content.md styles.json -o output.docx.
5. Confirm the output file exists and report its byte size.

Writing rules for content.md:

# Standard Markdown → auto-mapped to DOCX built-in styles

# Heading 1          → Heading 1
## Heading 2         → Heading 2

Normal paragraph text → Normal / Body Text

**bold**             → Strong character style
*italic*             → Emphasis character style
- Bullet item        → List Bullet
1. Numbered item     → List Number
> Blockquote         → Quote
$E = mc^2$           → OMML equation (Pandoc converts LaTeX)
![Cap](media/x.png)  → embedded image with media-dir lookup

# Named / branded styles → use custom-style annotations

::: {custom-style="Heading 1"}
Chapter Title
:::

::: {custom-style="Body Text"}
Paragraph content.
:::

The project is [on track]{custom-style="Status Green"}.

Rules:

1. Always use the exact name from styles.json — never guess or invent names.
2. Prefer standard Markdown over custom-style when the auto-mapping is equivalent.
3. Math: $...$ inline, $$...$$ display — Pandoc converts to OMML automatically.
4. Images: ![Caption](media/file.png){width=80%} — pass --media dir to apply-styles.
5. Page breaks: raw OOXML fence:

   ```{=openxml}
   <w:p><w:r><w:br w:type="page"/></w:r></w:p>
   ```
   

---

Workflow C — Full round-trip extraction

When the user wants to decompose an existing .docx into editable source:

edgemint extract document.docx -o project/

Produces:

project/
  content.md    ← Pandoc Extended Markdown (all content)
  styles.json   ← complete visual identity
  media/        ← all embedded images, extracted

Explain the structure, then tell the user how to re-generate:

edgemint apply-styles project/content.md project/styles.json \
  -o rebuilt.docx --media project/media

---

Workflow D — Diff / audit styles

When the user wants to compare two templates or detect brand changes:

edgemint extract-styles old-template.docx -o before.json
edgemint extract-styles new-template.docx -o after.json
edgemint diff before.json after.json

Present the diff grouped by: Added, Removed, Modified (with exact property changes).

---

Workflow E — Batch document generation

When the user wants to generate multiple documents from one template:

edgemint extract-styles template.docx -o styles.json  # once

for md in docs/*.md; do
  name=$(basename "$md" .md)
  edgemint apply-styles "$md" styles.json -o "output/${name}.docx"
done

Write each .md file with proper custom-style annotations before running the loop. Show the user the file count and total output size when done.

---

Workflow F — Quick inspection

edgemint info document.docx

Summarise: style count, key custom styles, paragraph vs. character split.

---

3. Error Handling

Exit code	Meaning	Action
0	Success	Continue
1	Usage error	Show correct usage
2	File not found / invalid	Check path, check it's a valid DOCX
3	Schema / validation error	Run edgemint validate styles.json
4	Pandoc error	Run pandoc --version; install edgemint[pandoc] if missing
5	Security error	Warn user — file failed ZIP bomb / path traversal check

Warnings about "style deduplication" and "list style" are normal — edgemint auto-fixes both (Pandoc bugs #7280 / #8350). Do not flag them to the user.

---

4. Output Confirmation

After every apply-styles call:

ls -lh output.docx

Report: ✓ output.docx (42 KB) or the equivalent.

---

5. Principles

• Never modify styles.json manually — always re-extract from the source .docx.
• Never invent style names — only use names that appear in styles.json.
• The three-file architecture (content.md + styles.json + media/) maps to a natural Git repo layout: content and identity evolve independently.
• When in doubt, run edgemint validate styles.json before generating.