skilldrop-cli 0.16.34 → 0.16.36

package/packs/converters/skills/file-to-markdown/scripts/to_markdown.py

@@ -2,7 +2,7 @@
 """Convert a document into clean Markdown that another skill can read.
 
 Stdlib only, Python 3.9+. Handles .docx, .pptx, .xlsx, .html/.htm, .csv/.tsv,
-.json, .txt/.md, and .pdf (through `pdftotext` when it is installed). A PDF page with no
+.json, .txt/.md, .eml and Outlook .msg email, and .pdf (through `pdftotext` when it is installed). A PDF page with no
 text layer (a scan) is read by OCR when `tesseract` and `pdftoppm` are installed.
 Everything the conversion could not carry (images, charts, comments, formulas,
 tracked changes) is counted and reported on stderr, so nobody mistakes the
@@ -972,6 +972,256 @@ def html_to_md(path, rep):
     return parser.result()
 
 
+def _html_text_to_md(text, rep):
+    """HTML already decoded to text (an email body) -> Markdown, through the same parser."""
+    skipped = len(re.findall(r"<(script|style)\b", text, re.I))
+    if skipped:
+        rep.drop("scripts/styles", skipped)
+    parser = HTMLToMD(rep)
+    parser.feed(text)
+    parser.close()
+    return parser.result()
+
+
+# ---------------------------------------------------------------- email (.eml, .msg)
+
+def _email_md(subject, rows, body_md, attachments, rep, note=None):
+    """One email as Markdown: subject as the title, the headers as a table, the body, and the
+    attachments listed by name and size, since their content is not converted."""
+    out = ["# " + md_escape(subject or "(no subject)"), "", "| | |", "|---|---|"]
+    for k, v in rows:
+        if v:
+            out.append("| %s | %s |" % (k, cell_text(md_escape(v))))
+    out += ["", body_md.strip() or "_(no text body)_", ""]
+    if attachments:
+        out += ["## Attachments", ""]
+        for name, size in attachments:
+            out.append("- %s (%s)" % (md_escape(name or "unnamed"), _human_size(size)))
+        out.append("")
+        rep.drop("attachments (listed, not converted)", len(attachments))
+    if note:
+        rep.notes.append(note)
+    rep.keep("emails", 1)
+    return "\n".join(out).rstrip() + "\n"
+
+
+def _email_text(text):
+    """A plain-text email body as Markdown. Bullets and `> ` quoted replies already read as
+    Markdown lists and quotes, so only a leading `#` (which would become a heading) and a
+    line of `=` or `-` under text (which would turn that text into one) are escaped."""
+    out = []
+    for line in text.replace("\r\n", "\n").split("\n"):
+        if line.lstrip().startswith("#"):
+            line = line.replace("#", "\\#", 1)
+        elif re.fullmatch(r"\s*(=+|-{2,})\s*", line) and out and out[-1].strip():
+            line = "\\" + line.strip()
+        out.append(line)
+    return "\n".join(out)
+
+
+def _human_size(n):
+    if n is None:
+        return "size unknown"
+    for unit in ("bytes", "KB", "MB", "GB"):
+        if n < 1024 or unit == "GB":
+            return ("%d %s" % (n, unit)) if unit == "bytes" else ("%.1f %s" % (n, unit))
+        n /= 1024.0
+
+
+def eml_to_md(path, rep):
+    """An RFC 5322 message (.eml): the plain-text part when there is one, else the HTML part."""
+    import email
+    from email import policy
+    msg = email.message_from_bytes(path.read_bytes(), policy=policy.default)
+    rows = [("From", str(msg.get("From", ""))), ("To", str(msg.get("To", ""))), ("Cc", str(msg.get("Cc", ""))),
+            ("Date", str(msg.get("Date", "")))]
+    plain = msg.get_body(preferencelist=("plain",))
+    html = msg.get_body(preferencelist=("html",))
+    if plain is not None:
+        body = _email_text(plain.get_content())
+        if html is not None:
+            rep.drop("HTML alternative (the plain-text part was used)", 1)
+    elif html is not None:
+        body = _html_text_to_md(html.get_content(), rep)
+    else:
+        body = ""
+    attachments = []
+    for part in msg.iter_attachments():
+        payload = part.get_payload(decode=True)
+        name = part.get_filename() or ("forwarded message" if part.get_content_type() == "message/rfc822" else None)
+        attachments.append((name, len(payload) if payload is not None else None))
+    return _email_md(str(msg.get("Subject", "")), rows, body, attachments, rep)
+
+
+class _CFB:
+    """A minimal, read-only reader for the Compound File Binary format Outlook saves .msg in.
+    Bounded on every loop and offset, so a malformed file stops with an error, never a hang."""
+    MAGIC = b"\xD0\xCF\x11\xE0\xA1\xB1\x1A\xE1"
+
+    def __init__(self, data):
+        import struct
+        self.struct = struct
+        if data[:8] != self.MAGIC or len(data) < 512:
+            raise ValueError("not an Outlook .msg file (no compound-file header)")
+        self.d = data
+        self.ss = 1 << struct.unpack_from("<H", data, 30)[0]
+        self.mss = 1 << struct.unpack_from("<H", data, 32)[0]
+        if self.ss not in (512, 4096) or self.mss != 64:
+            raise ValueError("unsupported compound-file sector size")
+        nfat, dir_start = struct.unpack_from("<I", data, 44)[0], struct.unpack_from("<I", data, 48)[0]
+        self.cutoff = struct.unpack_from("<I", data, 56)[0]
+        minifat_start, nminifat, difat_start, ndifat = struct.unpack_from("<IIII", data, 60)
+        difat = list(struct.unpack_from("<109I", data, 76))
+        per = self.ss // 4
+        s, guard = difat_start, 0
+        while ndifat and s < 0xFFFFFFFA and guard < 10000:
+            vals = struct.unpack("<%dI" % per, self._sector(s))
+            difat += vals[:-1]
+            s, guard, ndifat = vals[-1], guard + 1, ndifat - 1
+        self.fat = []
+        for fs in difat[:nfat]:
+            if fs < 0xFFFFFFFA:
+                self.fat += struct.unpack("<%dI" % per, self._sector(fs))
+        raw = self._chain(dir_start)
+        self.entries = []
+        for i in range(0, len(raw) - 127, 128):
+            e = raw[i:i + 128]
+            nlen = struct.unpack_from("<H", e, 64)[0]
+            name = e[:max(0, min(nlen, 64) - 2)].decode("utf-16-le", "replace")
+            kind = e[66]
+            left, right, child = struct.unpack_from("<III", e, 68)
+            start = struct.unpack_from("<I", e, 116)[0]
+            size = struct.unpack_from("<I", e, 120)[0]  # the high half is zero for version 3 files
+            self.entries.append({"name": name, "kind": kind, "left": left, "right": right, "child": child,
+                                 "start": start, "size": size})
+        if not self.entries or self.entries[0]["kind"] != 5:
+            raise ValueError("compound file has no root entry")
+        root = self.entries[0]
+        self.ministream = self._chain(root["start"])[:root["size"]] if root["start"] < 0xFFFFFFFA else b""
+        mf = self._chain(minifat_start) if nminifat else b""
+        self.minifat = list(struct.unpack("<%dI" % (len(mf) // 4), mf[:len(mf) // 4 * 4]))
+
+    def _sector(self, n):
+        off = (n + 1) * self.ss
+        if off + self.ss > len(self.d):
+            raise ValueError("compound file is truncated or corrupt")
+        return self.d[off:off + self.ss]
+
+    def _chain(self, start, mini=False):
+        fat, out, n, seen = (self.minifat if mini else self.fat), [], start, 0
+        while n < 0xFFFFFFFA:
+            if n >= len(fat) or seen > 1000000:
+                raise ValueError("compound file has a broken sector chain")
+            if mini:
+                off = n * self.mss
+                out.append(self.ministream[off:off + self.mss])
+            else:
+                out.append(self._sector(n))
+            n, seen = fat[n], seen + 1
+        return b"".join(out)
+
+    def children(self, idx):
+        """The entries directly inside storage `idx`, by name."""
+        out, stack, seen = {}, [self.entries[idx]["child"]], set()
+        while stack:
+            i = stack.pop()
+            if i >= len(self.entries) or i in seen:
+                continue
+            seen.add(i)
+            e = self.entries[i]
+            out[e["name"]] = i
+            stack += [e["left"], e["right"]]
+        return out
+
+    def read(self, i):
+        e = self.entries[i]
+        if e["size"] < self.cutoff:
+            return self._chain(e["start"], mini=True)[:e["size"]]
+        return self._chain(e["start"])[:e["size"]]
+
+
+def _msg_props(cfb, idx):
+    """The string and binary properties of one .msg storage, by four-hex-digit property id."""
+    out = {}
+    for name, i in cfb.children(idx).items():
+        m = re.match(r"__substg1\.0_([0-9A-Fa-f]{4})([0-9A-Fa-f]{4})$", name)
+        if not m or cfb.entries[i]["kind"] != 2:
+            continue
+        pid, ptype = m.group(1).upper(), m.group(2).upper()
+        data = cfb.read(i)
+        if ptype == "001F":
+            out[pid] = data.decode("utf-16-le", "replace").rstrip("\x00")
+        elif ptype == "001E":
+            out[pid] = data.decode("cp1252", "replace").rstrip("\x00")
+        elif ptype == "0102":
+            out.setdefault(pid + ":bin", data)
+    return out
+
+
+def _msg_fixed(cfb, idx, header):
+    """Fixed-size properties (times, integers) from a storage's __properties_version1.0."""
+    import struct
+    from datetime import datetime as _dt
+    stream = cfb.children(idx).get("__properties_version1.0")
+    if stream is None:
+        return {}
+    data, out = cfb.read(stream), {}
+    for off in range(header, len(data) - 15, 16):
+        tag, = struct.unpack_from("<I", data, off)
+        ptype, pid = tag & 0xFFFF, "%04X" % (tag >> 16)
+        if ptype == 0x0040:
+            ft, = struct.unpack_from("<Q", data, off + 8)
+            if ft:
+                out[pid] = _dt(1601, 1, 1) + timedelta(microseconds=ft // 10)
+        elif ptype == 0x0003:
+            out[pid] = struct.unpack_from("<i", data, off + 8)[0]
+    return out
+
+
+def msg_to_md(path, rep):
+    """An Outlook message (.msg): subject, sender, recipients, sent time, the text body (or the
+    HTML body when there is no text one), and attachments listed by name and size."""
+    try:
+        cfb = _CFB(path.read_bytes())
+    except ValueError as e:
+        sys.exit("error: %s: %s" % (path, e))
+    props = _msg_props(cfb, 0)
+    fixed = _msg_fixed(cfb, 0, 32)
+    to, cc = [], []
+    for name, i in sorted(cfb.children(0).items()):
+        if name.startswith("__recip_version1.0_"):
+            rp, rf = _msg_props(cfb, i), _msg_fixed(cfb, i, 8)
+            who = rp.get("3001", "")
+            addr = rp.get("39FE") or rp.get("3003", "")
+            label = ("%s <%s>" % (who, addr)) if who and addr and addr not in who else (who or addr)
+            (cc if rf.get("0C15") == 2 else to).append(label)
+    sender = props.get("0C1A", "")
+    saddr = props.get("5D01") or props.get("0C1F") or props.get("0065", "")
+    sent = fixed.get("0039") or fixed.get("0E06")
+    rows = [("From", ("%s <%s>" % (sender, saddr)) if sender and saddr else (sender or saddr)),
+            ("To", "; ".join(to) or props.get("0E04", "")), ("Cc", "; ".join(cc) or props.get("0E03", "")),
+            ("Date", sent.strftime("%Y-%m-%d %H:%M UTC") if sent else "")]
+    note = None
+    if props.get("1000"):
+        body = _email_text(props["1000"])
+    elif props.get("1013") or props.get("1013:bin"):
+        html = props.get("1013") or props["1013:bin"].decode("utf-8", "replace")
+        body = _html_text_to_md(html, rep)
+    else:
+        body = ""
+        if props.get("1009:bin"):
+            note = "the message body is stored only as compressed RTF, which is not converted"
+            rep.drop("RTF body", 1)
+    attachments = []
+    for name, i in sorted(cfb.children(0).items()):
+        if name.startswith("__attach_version1.0_"):
+            ap, kids = _msg_props(cfb, i), cfb.children(i)
+            data = ap.get("3701:bin")
+            fname = ap.get("3707") or ap.get("3704") or ("embedded message" if "__substg1.0_3701000D" in kids else None)
+            attachments.append((fname, len(data) if data is not None else None))
+    return _email_md(props.get("0037", ""), rows, body, attachments, rep, note)
+
+
 # ---------------------------------------------------------------- csv / json / txt / pdf
 
 def read_text(path, rep):
@@ -1104,9 +1354,78 @@ def _pdf_page_plain(page):
     return out
 
 
-def _pdf_page_md(page, rep):
+_BBOX_PAGE = re.compile(r"<page\b.*?</page>", re.S)
+_BBOX_WORD = re.compile(r'<word xMin="([\d.]+)" yMin="([\d.]+)" xMax="([\d.]+)" yMax="([\d.]+)">(.*?)</word>', re.S)
+
+
+def _word_rows(bbox_html):
+    """Each physical line of every page as [(xMin, xMax, height, text)], keyed by its words.
+    `pdftotext -bbox-layout` puts each table cell in a block of its own, so words are
+    regrouped by their vertical position into the rows the layout reading shows."""
+    import html as _html
+    rows = {}
+    for page in _BBOX_PAGE.findall(bbox_html):
+        words = [(float(a), float(b), float(c), float(d), _html.unescape(t)) for a, b, c, d, t in _BBOX_WORD.findall(page)]
+        words.sort(key=lambda w: (round(w[3]), w[0]))
+        line, base = [], None
+        for x0, y0, x1, y1, t in words + [(0, 0, 0, -99, "")]:
+            if base is not None and abs(y1 - base) > 2:
+                line.sort()
+                key = " ".join(w[3] for w in line)
+                if key and key not in rows:
+                    rows[key] = line
+                line = []
+            base = y1
+            if t:
+                line.append((x0, x1, y1 - y0, t))
+    return rows
+
+
+def _finer_cells(region, boxes):
+    """The region's rows split again from where each word sits on the page, or None.
+
+    `pdftotext -layout` turns positions into characters, so two columns whose text sits closer
+    than about two characters (a right-aligned amount beside a left-aligned date) come out one
+    space apart and merge into one cell. A gap between words is a column when it is at least
+    0.6 of the line's height (a word space is about a quarter of it) and, when the table has
+    word spaces to compare with, at least twice the smallest of them, which keeps a monospace
+    font's wide spaces from reading as columns. The new split is used only when every row then
+    has the same number of cells, so a table that already came out right is never changed."""
+    if not boxes:
+        return None
+    found = [boxes.get(" ".join(r.split())) for r in region]
+    if not any(found):
+        return None
+    gaps = []
+    for ws in found:
+        if ws:
+            h = sorted(w[2] for w in ws)[len(ws) // 2]
+            gaps += [(b[0] - a[1], h) for a, b in zip(ws, ws[1:])]
+    small = [g for g, h in gaps if g < 0.6 * h]
+    floor = 2 * min(small) if small else 0
+    rows = []
+    for r, ws in zip(region, found):
+        if not ws:
+            rows.append(_cells(r))
+            continue
+        h = sorted(w[2] for w in ws)[len(ws) // 2]
+        cells, cur = [], [ws[0][3]]
+        for a, b in zip(ws, ws[1:]):
+            g = b[0] - a[1]
+            if g >= 0.6 * h and g >= floor:
+                cells.append(" ".join(cur)); cur = []
+            cur.append(b[3])
+        cells.append(" ".join(cur))
+        rows.append(cells)
+    if len(set(len(c) for c in rows)) != 1 or rows == [_cells(r) for r in region]:
+        return None
+    return rows
+
+
+def _pdf_page_md(page, rep, fine=None):
     """One page of `pdftotext -layout` text -> Markdown. Layout mode keeps line breaks,
-    indentation and column alignment, which is what tables and lists are recovered from."""
+    indentation and column alignment, which is what tables and lists are recovered from.
+    `fine` maps a line's words to where each word sits on the page (see _finer_cells)."""
     lines = page.splitlines()
     out, i, n = [], 0, len(lines)
     while i < n:
@@ -1133,7 +1452,16 @@ def _pdf_page_md(page, rep):
                     break
             if rows >= 2:
                 widths = set(len(_cells(r)) for r in region)
-                if len(widths) == 1 and rows == len(region):
+                finer = _finer_cells(region, fine) if rows == len(region) else None
+                if finer and (len(widths) != 1 or len(finer[0]) > len(_cells(region[0]))):
+                    rep.keep("pdf table columns separated by position", 1)
+                    cells = [[cell_text(md_escape(c)) for c in r] for r in finer]
+                    width = len(cells[0])
+                    out.append("| " + " | ".join(cells[0]) + " |")
+                    out.append("|" + "---|" * width)
+                    out += ["| " + " | ".join(r) + " |" for r in cells[1:]]
+                    rep.keep("pdf tables", 1)
+                elif len(widths) == 1 and rows == len(region):
                     cells = [[cell_text(md_escape(c)) for c in _cells(r)] for r in region]
                     width = len(cells[0])
                     out.append("| " + " | ".join(cells[0]) + " |")
@@ -1318,6 +1646,11 @@ def pdf_to_md(path, rep, ocr=True, ocr_lang="eng"):
     elif blank and len(blank) == len(layout):
         sys.exit("error: %s has no text layer (probably scanned), and --no-ocr was given." % path)
     layout = _join_split_tables(layout, rep)
+    # Where each word sits, to tell table columns apart that sit closer than two characters
+    # in the layout reading (see _finer_cells).
+    proc = subprocess.run([exe, "-bbox-layout", "-enc", "UTF-8", str(path), "-"], stdout=subprocess.PIPE,
+                          stderr=subprocess.PIPE, check=False)
+    fine = _word_rows(proc.stdout.decode("utf-8", "replace")) if proc.returncode == 0 else {}
     out, plain_pages = [], []
     for n, page in enumerate(layout, 1):
         out += ["<!-- page %d -->" % n, ""]
@@ -1325,7 +1658,7 @@ def pdf_to_md(path, rep, ocr=True, ocr_lang="eng"):
             out += _pdf_page_plain(reading[n - 1])
             plain_pages.append(n)
         else:
-            out += _pdf_page_md(page, rep)
+            out += _pdf_page_md(page, rep, fine)
     pages = layout
     if plain_pages:
         rep.notes.append("page(s) %s have side-by-side columns, so they were read in column order with "
@@ -1342,7 +1675,7 @@ def pdf_to_md(path, rep, ocr=True, ocr_lang="eng"):
 HANDLERS = {
     ".docx": docx_to_md, ".pptx": pptx_to_md, ".xlsx": xlsx_to_md, ".xlsm": xlsx_to_md,
     ".html": html_to_md, ".htm": html_to_md, ".csv": csv_to_md, ".tsv": csv_to_md,
-    ".json": json_to_md, ".pdf": pdf_to_md,
+    ".json": json_to_md, ".pdf": pdf_to_md, ".eml": eml_to_md, ".msg": msg_to_md,
 }
 LEGACY = {".doc": ".docx", ".ppt": ".pptx", ".xls": ".xlsx", ".rtf": ".docx", ".odt": ".docx",
           ".pages": ".docx", ".key": ".pptx", ".numbers": ".xlsx"}
@@ -1350,7 +1683,7 @@ LEGACY = {".doc": ".docx", ".ppt": ".pptx", ".xls": ".xlsx", ".rtf": ".docx", ".
 
 def main(argv=None):
     ap = argparse.ArgumentParser(description="Convert a document to Markdown for another skill to read.")
-    ap.add_argument("input", help=".docx .pptx .xlsx .html .csv .tsv .json .txt .md .pdf")
+    ap.add_argument("input", help=".docx .pptx .xlsx .html .csv .tsv .json .txt .md .eml .msg .pdf")
     ap.add_argument("-o", "--output", required=True, help="Markdown file to write, or - for stdout")
     ap.add_argument("--max-rows", type=int, default=0,
                     help="xlsx only: keep at most this many data rows per sheet (0 = all)")

package/packs/converters/skills/md-to-confluence/SKILL.md

@@ -0,0 +1,139 @@
+---
+name: md-to-confluence
+description: Turn a Markdown runbook, design note or guide into a Confluence page: storage-format XHTML with real code blocks, tables, tasks, info and warning panels, images as attachments and an optional contents macro, a warning for everything dropped, and an optional publish that first shows which page it will create or overwrite and at what version, refuses stale or wrong-space overwrites, and takes credentials only from the environment. Use when the user says "put this in Confluence", "publish this markdown to the wiki", "update the Confluence page with this", "convert to Confluence storage format", or names a Confluence space for a Markdown file.
+---
+
+# md-to-confluence
+
+You turn a Markdown file into a Confluence page that reads like one written in the editor:
+code in the code macro, callouts as panels, checkboxes as Confluence tasks. A stdlib script
+does the conversion and, when asked, the publish. Your job is the part a person gets wrong
+under time pressure: fix what won't convert, list the images that must be attached, and make
+sure nobody overwrites the wrong page. Runbooks often come from `runbook-generator`.
+
+## How to respond
+
+**Four rules come before the steps and outrank them:**
+
+- **Answer what was asked, first.** Open with the answer, the decision or the artifact, in plain words. Scores, matrices, frameworks and tags come after it, and anything that doesn't change the answer is cut.
+- **Use only what you were given.** Don't add facts, names, numbers, incidents, history, steps or sections the input doesn't contain. What you need and don't have is left out of the artifact and listed once at the end under "To confirm".
+- **Deliver from what you have.** When the request gives you something to work on, state your assumptions in a line and produce the result. When it gives you nothing to work on, ask for it in one or two plain sentences and say what you will do once you have it.
+- **Write for someone who has never heard of this skill.** No skill names, no paths or scripts from this folder, no internal terms, and nothing about how the run was set up. A next step is one plain sentence at the end that describes the work.
+- **For this skill:** Nothing reaches Confluence until the person has seen exactly which page will be created or overwritten (space, title, page id, current version, last editor) and the files to attach, and has said yes to that page. With nobody to ask, convert only and say what would be published.
+
+1. **Take the target from the request; ask once for the rest.** Publishing needs the site
+   (`https://<site>.atlassian.net/wiki`, or the Data Center address), the space key, and
+   either a parent page or the id of the page to replace. Ask for what's missing in one
+   message, at most two questions. Defaults: title from the first `#` heading; parent is
+   the space home; contents macro on when the page has four or more `##` sections.
+
+2. **Fix the Markdown in a copy before converting, and list each change.** These are the
+   losses the script can only warn about:
+   - **Raw HTML is dropped whole.** A `<details>` block often hides the rollback steps. Rewrite
+     it as Markdown (a `## Rollback` section with a numbered list).
+     ✅ *rollback steps survive as a list* ❌ *"1 HTML block dropped" in the reply, steps gone*
+   - **Code between numbered steps breaks the numbering.** Confluence restarts each list at 1.
+     Indent the code block three spaces under its step so steps read 1, 2, 3.
+   - **Two images with the same file name** (`before/screen.png`, `after/screen.png`) become one
+     attachment, so both show the same picture. Rename one (`screen-before.png`).
+   - **Footnotes are dropped.** Move the text into the sentence or a "Notes" section.
+   - **Mermaid shows as source.** Render it to PNG with `mermaid-render` and embed the PNG.
+   - **A front-matter `title:` wins over the `#` heading** for a new page. An update keeps the
+     page's current title, so when the Markdown's title differs (`Deploy checklist v2 (draft)`),
+     say so and rename only if asked.
+   - **Callouts need the label as the first words of the quote:** `> **Note:**` → info panel,
+     `> **Warning:**` → warning panel (full table in [`reference.md`](reference.md)).
+
+3. **Convert, then read every `WARN` line.**
+
+   ```bash
+   # Claude Code
+   python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_confluence.py" runbook.md -o runbook.xhtml --toc
+   # Other IDEs (from the skill folder)
+   python3 scripts/md_to_confluence.py runbook.md -o runbook.xhtml --toc
+   ```
+
+   Fix the source and rerun for each warning you can fix. Report the rest in plain words:
+   ✅ *"The in-page link to Rollback is plain text now; the contents box at the top covers it."*
+   ❌ *"Converted with 3 warnings."* The script also lists every image to upload as an attachment.
+
+4. **Credentials come from the environment, never the chat.** The script reads
+   `CONFLUENCE_EMAIL` + `CONFLUENCE_API_TOKEN` (Cloud) or `CONFLUENCE_PAT` (Data Center).
+   If they're unset, convert, run `--publish --dry-run`, and stop: tell the person to export
+   the variables in their own terminal and restart the session. If they paste a token into the chat, don't put it in a command, a file or an
+   `export` you run: tell them to revoke it, because it now sits in the transcript.
+
+5. **Look at the target page before writing to it.** `--inspect` is read-only:
+
+   ```bash
+   python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_confluence.py" runbook.md -o runbook.xhtml --inspect --base-url "https://<site>.atlassian.net/wiki" --space SRE --page-id 48213
+   ```
+
+   Without `--page-id` it says whether a page with that title already exists in the space.
+
+6. **Confirm with the facts, then publish.** One block, then wait for a yes:
+   ✅ *"This overwrites **Deploy checklist** (page 48213, PLAT), now at version 7, last edited by
+   Priya Nair on 1 Oct. Upload after: `flow.png`. Dropped: one footnote, moved
+   into Notes. Publish?"* ❌ *"Ready to push to Confluence, go ahead?"*
+
+   ```bash
+   python3 "${CLAUDE_SKILL_DIR}/scripts/md_to_confluence.py" runbook.md -o runbook.xhtml --publish --base-url "https://<site>.atlassian.net/wiki" --space PLAT --page-id 48213 --expected-version 7
+   # other IDEs: python3 scripts/md_to_confluence.py … with the same flags
+   ```
+
+   Always pass `--expected-version` with the number `--inspect` showed: if anyone saved the page
+   since, the script refuses instead of erasing their edit. Leave out `--page-id` to create;
+   it refuses when the title is taken. An update keeps the page's title unless `--title` is
+   passed. `--dry-run` prints the request and sends nothing.
+
+7. **Hand over in three or four lines, opening with the state.** ✅ *"Published: <link>, now
+   version 8."* ✅ *"Converted, not published yet: it becomes a new page **Payments API
+   runbook** under page 196612 in SRE."* ❌ *"Done!"* when nothing reached Confluence. Then the
+   files to upload in the page's Attachments with their names unchanged (images show broken
+   until then; the script never uploads them), what was dropped or changed, and what the
+   person does next.
+
+**Non-interactive runs** (subagent, CI, headless): never publish. Convert, run `--publish
+--dry-run` when a target was given, and reply with what would be published, to which space
+and page, and the attachments, as the first thing to confirm. Defaults (title, contents
+macro, parent) become `[assumption]` lines. With no Markdown, emit `BLOCKED: need the
+Markdown file to convert` and write nothing.
+
+## Useful references in this skill
+
+- [`reference.md`](reference.md): what maps to what, the callout convention, code languages, the API calls and every refusal
+- [`scripts/md_to_confluence.py`](scripts/md_to_confluence.py): converter and publisher (stdlib only, Python 3.9+)
+- [`examples/queue-runbook.md`](examples/queue-runbook.md): a runbook converted, with the fixes made and the confirmation shown
+
+## Quality bar
+
+- **The right page, said out loud.** Every publish is preceded by the page id, title, space, current version and last editor from a live check, and a yes.
+- **No silent overwrite.** Updates carry `--expected-version`; a newer version stops the run.
+- **Nothing lost silently.** Each `WARN` is fixed in the source or named in the reply; rollback steps in HTML are rewritten, not dropped.
+- **Images are listed by attachment name**, with any missing file or name clash called out before publishing.
+- **Code survives byte for byte**, including a `]]>` inside it; the script checks the page is well-formed.
+- **Tokens never appear** in a command, a file or the reply.
+- **Facts untouched.** Restructuring Markdown never changes a command, threshold, name or date.
+
+## When to use this skill
+
+- ✅ A Markdown runbook, design doc or how-to that belongs on a team's Confluence space
+- ✅ Replacing an existing Confluence page with a newer Markdown version, without clobbering edits
+- ✅ Storage-format XHTML to paste into the source editor or another tool's API call
+
+## When NOT to use this skill
+
+- ❌ A Word file to edit with tracked changes; use `md-to-docx`
+- ❌ A standalone web page or an HTML attachment for email; use `md-to-html`
+- ❌ Jira epics and issues from a PRD; use `tracker-brief-sync`
+- ❌ Writing the runbook itself; use `runbook-generator`, then convert
+
+## Anti-patterns to avoid
+
+- ❌ **Publishing on "put it in Confluence".** That names a destination, not a page to overwrite. Inspect, show, ask.
+- ❌ **Updating without `--expected-version`.** A teammate's edit from this morning disappears with no trace in the reply.
+- ❌ **Hand-writing storage XHTML.** One unescaped `&` or a `]]>` in a code sample, and Confluence rejects the page or cuts the code.
+- ❌ **Treating "published" as done while images are unattached.** The page renders with broken image boxes until the files are uploaded.
+- ❌ **Putting a pasted token on a command line.** It lands in shell history and logs. Ask for environment variables and a revoke.
+- ❌ **Showing the machinery.** No skill names, script paths or flags in the reply; describe the page and the steps.
+- ❌ **A bare `BLOCKED` line.** Say in plain words what is missing and what you will produce once you have it.

package/packs/converters/skills/md-to-confluence/evals/eval_queries.json

@@ -0,0 +1,42 @@
+[
+  {
+    "query": "put this runbook in Confluence under the SRE space",
+    "should_trigger": true
+  },
+  {
+    "query": "Convert README.md to Confluence storage format so I can paste it into the source editor",
+    "should_trigger": true
+  },
+  {
+    "query": "Publish design-notes.md as a wiki page under Architecture on our atlassian site",
+    "should_trigger": true
+  },
+  {
+    "query": "update Confluence page 48213 with the new deploy-checklist.md",
+    "should_trigger": true
+  },
+  {
+    "query": "our team docs live in Confluence, can you get this markdown onto a page with the code blocks looking right",
+    "should_trigger": true
+  },
+  {
+    "query": "Convert this markdown to a Word document legal can track changes in",
+    "should_trigger": false
+  },
+  {
+    "query": "Turn the markdown report into a single HTML file I can email",
+    "should_trigger": false
+  },
+  {
+    "query": "Create Jira epics and issues from this PRD",
+    "should_trigger": false
+  },
+  {
+    "query": "Write a runbook for the payments service before it goes to on-call",
+    "should_trigger": false
+  },
+  {
+    "query": "Render the Mermaid flowchart in arch.mmd to a PNG",
+    "should_trigger": false
+  }
+]