diff --git a/README.md b/README.md
index a699a6f..08de960 100644
--- a/README.md
+++ b/README.md
@@ -248,6 +248,50 @@ If a worktree for that reference already exists it is replaced.
 
 ---
 
+### `export`
+
+Export the archive as Markdown files — one `.md` per message — with YAML frontmatter and a human-readable body.
+
+```sh
+backmail export
+backmail export --only-folder INBOX --only-folder Sent
+backmail export --exclude-folder Spam --verbose
+```
+
+| Option | Description |
+|--------|-------------|
+| `--exclude-folder <name>` | Skip a folder (repeatable) |
+| `--only-folder <name>` | Restrict to a folder (repeatable) |
+| `--verbose` | Log one line per folder and per message |
+
+`--exclude-folder` and `--only-folder` are mutually exclusive.
+
+Output is written to `export/` next to `archive/`, mirroring the folder structure. Each file contains:
+
+- YAML frontmatter with `messageId`, `from`, `to`, `subject`, `received`, `folders`, `formats`, and `attachments`
+- The subject as a top-level heading
+- Plain text body (when present)
+- HTML body converted to Markdown, preceded by a labelled separator block (when both parts are present — layout tables are unwrapped to prose, external images stripped, inline attachments preserved)
+
+Running `export` again is idempotent — existing files are overwritten with identical content.
+
+Output:
+
+```
+export: =42 exported
+```
+
+If any message fails the export continues and the summary line is tagged `[partial]`:
+
+```
+export [partial]: =38 exported
+folder INBOX/Archive failed: read error
+```
+
+Exit code is non-zero when any folder fails.
+
+---
+
 ### `restore`
 
 Re-upload messages from a backup to an IMAP server. Useful for migrating to a new provider or recovering deleted mail.
@@ -290,6 +334,9 @@ archive/            # git repository
 worktrees/          # point-in-time checkouts (outside the git repo)
   2024-01-15/
   abc1234/
+export/             # Markdown export (created by `backmail export`)
+  INBOX/
+    2024-01-15_subject_aabbccdd.md
 ```
 
 Messages are content-addressed by Message-ID, so identical emails that appear in multiple IMAP folders (common with Gmail labels) are stored only once.
diff --git a/package-lock.json b/package-lock.json
index 94f8c84..fd35085 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -18,6 +18,8 @@
         "mailparser": "^3.9.8",
         "simple-git": "3.36.0",
         "slugify": "^1.6.9",
+        "turndown": "^7.2.4",
+        "turndown-plugin-gfm": "^1.0.2",
         "zod": "^4.3.6"
       },
       "bin": {
@@ -26,6 +28,7 @@
       "devDependencies": {
         "@types/mailparser": "^3.4.6",
         "@types/node": "25.6.0",
+        "@types/turndown": "^5.0.6",
         "@vitest/coverage-v8": "^4.1.5",
         "tsx": "4.21.0",
         "typescript": "6.0.3",
@@ -938,6 +941,12 @@
       "integrity": "sha512-GaHYm+c0O9MjZRu0ongGBRbinu8gVAMd2UZjji6jVmqKtZluZnptXGWhz1E8j8D2HJ3f/yMxKAUC0b+57wncIw==",
       "license": "MIT"
     },
+    "node_modules/@mixmark-io/domino": {
+      "version": "2.2.0",
+      "resolved": "https://registry.npmjs.org/@mixmark-io/domino/-/domino-2.2.0.tgz",
+      "integrity": "sha512-Y28PR25bHXUg88kCV7nivXrP2Nj2RueZ3/l/jdx6J9f8J4nsEGcgX0Qe6lt7Pa+J79+kPiJU3LguR6O/6zrLOw==",
+      "license": "BSD-2-Clause"
+    },
     "node_modules/@napi-rs/keyring": {
       "version": "1.3.0",
       "resolved": "https://registry.npmjs.org/@napi-rs/keyring/-/keyring-1.3.0.tgz",
@@ -1562,6 +1571,13 @@
         "undici-types": "~7.19.0"
       }
     },
+    "node_modules/@types/turndown": {
+      "version": "5.0.6",
+      "resolved": "https://registry.npmjs.org/@types/turndown/-/turndown-5.0.6.tgz",
+      "integrity": "sha512-ru00MoyeeouE5BX4gRL+6m/BsDfbRayOskWqUvh7CLGW+UXxHQItqALa38kKnOiZPqJrtzJUgAC2+F0rL1S4Pg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@vitest/coverage-v8": {
       "version": "4.1.5",
       "resolved": "https://registry.npmjs.org/@vitest/coverage-v8/-/coverage-v8-4.1.5.tgz",
@@ -3103,6 +3119,25 @@
         "fsevents": "~2.3.3"
       }
     },
+    "node_modules/turndown": {
+      "version": "7.2.4",
+      "resolved": "https://registry.npmjs.org/turndown/-/turndown-7.2.4.tgz",
+      "integrity": "sha512-I8yFsfRzmzK0WV1pNNOA4A7y4RDfFxPRxb3t+e3ui14qSGOxGtiSP6GjeX+Y6CHb7HYaFj7ECUD7VE5kQMZWGQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@mixmark-io/domino": "^2.2.0"
+      },
+      "engines": {
+        "node": ">=18",
+        "npm": ">=9"
+      }
+    },
+    "node_modules/turndown-plugin-gfm": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/turndown-plugin-gfm/-/turndown-plugin-gfm-1.0.2.tgz",
+      "integrity": "sha512-vwz9tfvF7XN/jE0dGoBei3FXWuvll78ohzCZQuOb+ZjWrs3a0XhQVomJEb2Qh4VHTPNRO4GPZh0V7VRbiWwkRg==",
+      "license": "MIT"
+    },
     "node_modules/typescript": {
       "version": "6.0.3",
       "resolved": "https://registry.npmjs.org/typescript/-/typescript-6.0.3.tgz",
diff --git a/package.json b/package.json
index 5c3fe26..300c6f6 100644
--- a/package.json
+++ b/package.json
@@ -48,6 +48,7 @@
   "devDependencies": {
     "@types/mailparser": "^3.4.6",
     "@types/node": "25.6.0",
+    "@types/turndown": "^5.0.6",
     "@vitest/coverage-v8": "^4.1.5",
     "tsx": "4.21.0",
     "typescript": "6.0.3",
@@ -63,6 +64,8 @@
     "mailparser": "^3.9.8",
     "simple-git": "3.36.0",
     "slugify": "^1.6.9",
+    "turndown": "^7.2.4",
+    "turndown-plugin-gfm": "^1.0.2",
     "zod": "^4.3.6"
   }
 }
diff --git a/src/cli/index.ts b/src/cli/index.ts
index 4b063a4..64dab6b 100644
--- a/src/cli/index.ts
+++ b/src/cli/index.ts
@@ -39,7 +39,7 @@ function getRepoRoot(): string {
   return repoRoot
 }
 
-import { syncAccount, getLog, checkoutCommit, listFolders, listMessages, viewMessage, restoreAccount } from '../core/index.js'
+import { syncAccount, getLog, checkoutCommit, listFolders, listMessages, viewMessage, restoreAccount, exportAccount } from '../core/index.js'
 
 function getErrorMessage(err: unknown): string {
   if (err instanceof Error) {
@@ -373,4 +373,48 @@ program
     }
   })
 
+// ── export ───────────────────────────────────────────────────────────────────
+program
+  .command('export')
+  .description('Export archive messages as Markdown files')
+  .option('--exclude-folder <name>', 'skip this folder (repeatable)', collectRepeatable, [])
+  .option('--only-folder <name>', 'restrict to this folder (repeatable)', collectRepeatable, [])
+  .option('--verbose', 'log one line per exported file')
+  .action(async (opts: { excludeFolder: string[]; onlyFolder: string[]; verbose?: boolean }) => {
+    if (opts.excludeFolder.length > 0 && opts.onlyFolder.length > 0) {
+      console.error('Error: --exclude-folder and --only-folder are mutually exclusive')
+      process.exit(1)
+    }
+
+    try {
+      const repoRoot = getRepoRoot()
+      const archivePath = path.join(repoRoot, 'archive')
+      const exportPath = path.join(repoRoot, 'export')
+      const verbose = opts.verbose ?? false
+
+      const result = await exportAccount(archivePath, exportPath, {
+        excludeFolders: opts.excludeFolder,
+        onlyFolders: opts.onlyFolder,
+        verbose,
+        onLog: verbose ? (msg) => console.log(msg) : undefined,
+      })
+
+      const partialTag = result.errors > 0 ? ' [partial]' : ''
+      console.log(`export${partialTag}: =${result.exported} exported`)
+
+      for (const fr of result.folderResults) {
+        if (fr.error) {
+          console.error(`folder ${fr.path} failed: ${fr.error.message}`)
+        }
+      }
+
+      if (result.errors > 0) {
+        process.exit(1)
+      }
+    } catch (err) {
+      console.error(getErrorMessage(err))
+      process.exit(1)
+    }
+  })
+
 program.parse(process.argv)
diff --git a/src/core/export.ts b/src/core/export.ts
new file mode 100644
index 0000000..148f1b1
--- /dev/null
+++ b/src/core/export.ts
@@ -0,0 +1,575 @@
+// src/core/export.ts — no exit calls, no console, no CLI imports.
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import { simpleParser } from 'mailparser'
+import type { ParsedMail } from 'mailparser'
+import TurndownService from 'turndown'
+import { gfm } from 'turndown-plugin-gfm'
+import { parseHeaderBlock, extractRawHeader } from './sync.js'
+import { listFolders } from './browse.js'
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+export interface ExportOptions {
+  excludeFolders?: string[]
+  onlyFolders?: string[]
+  verbose?: boolean
+  onLog?: (msg: string) => void
+}
+
+export interface ExportResult {
+  exported: number
+  errors: number
+  folderResults: FolderExportResult[]
+}
+
+export interface FolderExportResult {
+  path: string
+  exported: number
+  error?: Error
+}
+
+// ── HTML → Markdown ───────────────────────────────────────────────────────────
+
+export function preprocessHtml(html: string): string {
+  // Strip invisible filler characters used as spacers in HTML email
+  // (soft hyphen U+00AD, zero-width space U+200B, zero-width non-joiner U+200C,
+  //  zero-width joiner U+200D, BOM/zero-width no-break space U+FEFF,
+  //  combining grapheme joiner U+034F \u2014 used in preheader padding sequences)
+  let out = html.replace(/[\u034f\u00ad\u200b\u200c\u200d\ufeff]/g, '')
+
+  // Strip <style> and <script> blocks
+  out = out.replace(/<style[\s\S]*?<\/style>/gi, '')
+  out = out.replace(/<script[\s\S]*?<\/script>/gi, '')
+
+  // Strip all <img> tags except inline attachments (src="cid:...").
+  // Logos, layout images, and tracking pixels from external URLs are all removed.
+  out = out.replace(/<img\b[^>]*>/gi, (tag) => {
+    const src = tag.match(/\bsrc\s*=\s*["']([^"']*)["']/i)
+    return src && src[1].toLowerCase().startsWith('cid:') ? tag : ''
+  })
+
+  return out
+}
+
+// ── Smart table rules ─────────────────────────────────────────────────────────
+// Layout tables (no <th> in first row, or role="presentation") are unwrapped to
+// prose. Data tables (first row all <th>) are kept as GFM pipe tables.
+
+// Block-level tags that indicate a <th> is being used for layout rather than
+// as a data column header. A genuine header cell contains short inline text.
+const BLOCK_TAGS = new Set(['table', 'div', 'p', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6',
+  'ul', 'ol', 'blockquote', 'img', 'figure'])
+
+function cellHasBlockContent(cell: any): boolean {
+  function walk(node: any): boolean {
+    if (node.nodeType !== 1) return false
+    if (BLOCK_TAGS.has((node.nodeName as string).toLowerCase())) return true
+    for (const child of Array.from(node.childNodes as Iterable<any>)) {
+      if (walk(child)) return true
+    }
+    return false
+  }
+  for (const child of Array.from(cell.childNodes as Iterable<any>)) {
+    if (walk(child)) return true
+  }
+  return false
+}
+
+function tableHasHeadingRow(table: any): boolean {
+  if (typeof table.getAttribute === 'function' && table.getAttribute('role') === 'presentation') {
+    return false
+  }
+  if (!table.rows || table.rows.length === 0) return false
+  const firstRow = table.rows[0]
+  let cellCount = 0
+  for (const child of Array.from(firstRow.childNodes as Iterable<any>)) {
+    if (child.nodeType !== 1) continue
+    cellCount++
+    if (child.nodeName !== 'TH') return false
+    // A <th> containing block-level elements is a layout cell, not a data header
+    if (cellHasBlockContent(child)) return false
+  }
+  return cellCount > 0
+}
+
+function findAncestorTable(node: any): any {
+  for (let n = node.parentNode; n; n = n.parentNode) {
+    if (n.nodeName === 'TABLE') return n
+  }
+  return null
+}
+
+function gfmPipeCell(content: string, node: any): string {
+  const index = Array.prototype.indexOf.call(node.parentNode.childNodes, node)
+  return (index === 0 ? '| ' : ' ') + content + ' |'
+}
+
+function isFirstTbody(node: any): boolean {
+  const prev = node.previousSibling
+  return (
+    node.nodeName === 'TBODY' &&
+    (!prev || (prev.nodeName === 'THEAD' && /^\s*$/.test(prev.textContent || '')))
+  )
+}
+
+function isGfmHeadingRow(tr: any): boolean {
+  const parent = tr.parentNode
+  const allTh = Array.prototype.every.call(tr.childNodes, (n: any) => n.nodeName === 'TH')
+  return (
+    parent.nodeName === 'THEAD' ||
+    (parent.firstChild === tr &&
+      allTh &&
+      (parent.nodeName === 'TABLE' || isFirstTbody(parent)))
+  )
+}
+
+function configureSmartTableRules(service: TurndownService): void {
+  // These override GFM's rules by reusing the same key names, preserving rule
+  // priority order while replacing the implementation.
+
+  service.addRule('tableCell', {
+    filter: ['th', 'td'],
+    replacement(content: string, node: any): string {
+      const table = findAncestorTable(node)
+      if (!table || !tableHasHeadingRow(table)) {
+        const trimmed = content.trim()
+        return trimmed ? '\n\n' + trimmed + '\n\n' : ''
+      }
+      return gfmPipeCell(content, node)
+    },
+  })
+
+  service.addRule('tableRow', {
+    filter: 'tr',
+    replacement(content: string, node: any): string {
+      const table = findAncestorTable(node)
+      if (!table || !tableHasHeadingRow(table)) return content
+      if (isGfmHeadingRow(node)) {
+        let border = ''
+        for (const n of Array.from(node.childNodes as Iterable<any>)) {
+          if (n.nodeType === 1) border += gfmPipeCell('---', n)
+        }
+        return '\n' + content + '\n' + border
+      }
+      return '\n' + content
+    },
+  })
+
+  service.addRule('table', {
+    filter: 'table',
+    replacement(content: string, node: any): string {
+      if (!tableHasHeadingRow(node)) {
+        const prose = content.replace(/\n{2,}/g, '\n').trim()
+        return prose ? '\n\n' + prose + '\n\n' : ''
+      }
+      return '\n\n' + content + '\n\n'
+    },
+  })
+}
+
+export function htmlToMarkdown(html: string): string {
+  const cleaned = preprocessHtml(html)
+
+  const td = new TurndownService({ headingStyle: 'atx', codeBlockStyle: 'fenced' })
+  td.use(gfm)
+  configureSmartTableRules(td)
+  let md = td.turndown(cleaned)
+
+  // (a) Strip invisible characters that may have been decoded from HTML entities
+  //     by the DOM parser inside Turndown (e.g. &#847; \u2192 U+034F, &shy; \u2192 U+00AD).
+  //     Mirrors the preprocessHtml strip but catches entity-encoded variants.
+  md = md.replace(/[\u00ad\u034f\u200b\u200c\u200d\ufeff]/g, '')
+  // (b) Replace Unicode non-breaking / decorative spaces with plain space.
+  //     U+2007 FIGURE SPACE (&#8199;) is the main culprit in preheader padding divs.
+  md = md.replace(/[\u00a0\u1680\u2002\u2003\u2007\u2008\u2009\u200a\u202f\u205f\u3000]/g, ' ')
+  // (c) Trim trailing whitespace from every line (also collapses space-only lines to empty)
+  md = md.replace(/[ \t]+$/gm, '')
+  // (e) Remove links with empty or whitespace-only text \u2014 these come from <a> tags
+  //     that wrapped images or content we stripped (tracking links, logo anchors).
+  md = md.replace(/\[ *\]\([^)]*\)/g, '')
+  // (d) Convert Turndown-escaped visual bullets (\* / \-) to real list items.
+  //     Also strips leading whitespace so 4+-space indent doesn't trigger code blocks.
+  md = md.replace(/^[ \t]*\\([*-]) /gm, '- ')
+  // (c) Collapse 3+ consecutive newlines to 2
+  md = md.replace(/\n{3,}/g, '\n\n')
+  // (f) Add hard line breaks between consecutive non-block prose lines so that
+  //     content extracted from layout tables (collapsed to single newlines) still
+  //     renders with visible line breaks in markdown.
+  md = addMarkdownHardBreaks(md)
+
+  return md
+}
+
+// ── Markdown hard-break pass ──────────────────────────────────────────────────
+// Detects markdown structural lines that should not receive or trigger a hard-
+// break marker: headings, blockquotes, list items, indented/fenced code,
+// thematic breaks, setext underlines, and GFM table rows.
+const MD_BLOCK_RE =
+  /^(?:[ ]{0,3}#{1,6}[ \t]|>|[ ]{0,3}[-*+][ \t]|[ ]{0,3}\d+\.[ \t]|[ ]{4,}|\t|`{3,}|~{3,}|[=\-*_]{3,}\s*$|\|)/
+
+function addMarkdownHardBreaks(md: string): string {
+  const lines = md.split('\n')
+  const out: string[] = []
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    const next = lines[i + 1]
+    const isEmpty = (s: string | undefined): boolean =>
+      s === undefined || s === '' || /^\s+$/.test(s)
+    const isBlock = (s: string): boolean => MD_BLOCK_RE.test(s)
+
+    const addBreak =
+      !isEmpty(line) &&
+      !isBlock(line) &&
+      !isEmpty(next) &&
+      !isBlock(next)
+
+    out.push(addBreak ? line + '\\' : line)
+  }
+  return out.join('\n')
+}
+
+// ── Plain text → Markdown ─────────────────────────────────────────────────────
+
+// Matches manually typed list lines: optional leading spaces, then "- " or "* " or "N. "
+const MANUAL_LIST_RE = /^[ ]*(?:[-*][ \t]|\d+\.[ \t])/
+
+// Matches ASCII divider lines: 2+ dashes or equals signs (optional trailing spaces).
+// These are Setext heading underlines in CommonMark — when they appear directly under
+// a text line they would turn it into a heading. We normalise them to thematic breaks.
+const DIVIDER_RE = /^[-=]{2,}\s*$/
+
+function escapeHtml(s: string): string {
+  return s.replace(/</g, '&lt;')
+}
+
+interface ConvertedLine {
+  out: string
+  isBlock: boolean
+  isDivider: boolean
+}
+
+// Matches ATX heading lines: up to 3 leading spaces, then 1-6 # chars, then space/tab or EOL
+const ATX_HEADING_RE = /^[ ]{0,3}#{1,6}([ \t]|$)/
+
+function classifyLine(line: string): ConvertedLine {
+  // Whitespace-only lines (tabs, spaces) count as blank lines — they must not
+  // trigger hard-break markers on the line before them.
+  if (line === '' || /^\s+$/.test(line)) return { out: '', isBlock: false, isDivider: false }
+  if (DIVIDER_RE.test(line)) return { out: '---', isBlock: false, isDivider: true }
+  if (MANUAL_LIST_RE.test(line)) return { out: escapeHtml(line).trimEnd(), isBlock: true, isDivider: false }
+  // Blockquote lines (email quote marker >) are treated as block elements so they
+  // neither receive nor trigger hard-break markers on adjacent lines.
+  if (line.startsWith('>')) return { out: escapeHtml(line).trimEnd(), isBlock: true, isDivider: false }
+  // Escape the # to prevent ATX heading interpretation, preserving any leading spaces
+  const escaped = ATX_HEADING_RE.test(line)
+    ? escapeHtml(line).replace(/^([ ]{0,3})(#{1,6})/, '$1\\$2')
+    : escapeHtml(line)
+  return { out: escaped.trimEnd(), isBlock: false, isDivider: false }
+}
+
+export function convertPlainText(text: string): string {
+  if (text === '') return ''
+
+  const lines = text.split('\n').map(classifyLine)
+  const out: string[] = []
+
+  for (let i = 0; i < lines.length; i++) {
+    const curr = lines[i]
+    const next = lines[i + 1]
+
+    if (curr.isDivider) {
+      // Insert a blank line before the divider when the previous output line is
+      // non-empty, so the Markdown parser sees a thematic break rather than a
+      // Setext heading underline.
+      if (out.length > 0 && out[out.length - 1] !== '') out.push('')
+      out.push('---')
+      continue
+    }
+
+    if (curr.out === '') {
+      out.push('')
+      continue
+    }
+
+    // Append \ only between two consecutive non-empty prose lines.
+    // Skip if the next line is a divider (a blank line will be inserted before it).
+    const hardBreak =
+      !curr.isBlock &&
+      next !== undefined &&
+      !next.isDivider &&
+      next.out !== '' &&
+      !next.isBlock
+
+    out.push(hardBreak ? curr.out + '\\' : curr.out)
+  }
+
+  return out.join('\n')
+}
+
+// ── receivedDate extraction ───────────────────────────────────────────────────
+
+export function extractReceivedDate(rawSource: Buffer | string): string {
+  const unfolded = parseHeaderBlock(rawSource)
+
+  const receivedLine = extractRawHeader(unfolded, 'received')
+  if (receivedLine) {
+    const semi = receivedLine.lastIndexOf(';')
+    if (semi !== -1) {
+      const parsed = new Date(receivedLine.slice(semi + 1).trim())
+      if (!isNaN(parsed.getTime())) {
+        return parsed.toISOString().replace('T', ' ').slice(0, 19)
+      }
+    }
+  }
+
+  const dateLine = extractRawHeader(unfolded, 'date')
+  if (dateLine) {
+    const parsed = new Date(dateLine.trim())
+    if (!isNaN(parsed.getTime())) {
+      return parsed.toISOString().replace('T', ' ').slice(0, 19)
+    }
+  }
+
+  return '0000-00-00 00:00:00'
+}
+
+// ── Frontmatter builder ───────────────────────────────────────────────────────
+
+function yamlQuote(s: string): string {
+  // Escape backslashes and double quotes, then wrap in double quotes
+  return '"' + s.replace(/\\/g, '\\\\').replace(/"/g, '\\"') + '"'
+}
+
+function formatAddress(name: string | undefined, email: string | undefined): string {
+  const n = name?.trim() ?? ''
+  const e = email?.trim() ?? ''
+  if (n && e) return `${n} <${e}>`
+  return n || e
+}
+
+export function buildFrontmatter(
+  parsed: ParsedMail,
+  rawSource: Buffer | string,
+  folderPath: string,
+  formats: string[],
+): string {
+  const messageId = parsed.messageId ?? ''
+  const fromAddr = parsed.from?.value[0]
+  const fromStr = formatAddress(fromAddr?.name, fromAddr?.address)
+  const toList = (parsed.to ? (Array.isArray(parsed.to) ? parsed.to : [parsed.to]) : [])
+    .flatMap((a) => a.value)
+  const subject = parsed.subject ?? ''
+  const receivedDate = extractReceivedDate(rawSource)
+  const attachments = parsed.attachments ?? []
+
+  const lines: string[] = []
+  lines.push('---')
+  lines.push(`messageId: ${yamlQuote(messageId)}`)
+  lines.push(`from: ${yamlQuote(fromStr)}`)
+
+  if (toList.length === 0) {
+    lines.push('to: []')
+  } else {
+    lines.push('to:')
+    for (const addr of toList) {
+      lines.push(`  - ${yamlQuote(formatAddress(addr.name, addr.address))}`)
+    }
+  }
+
+  lines.push(`subject: ${yamlQuote(subject)}`)
+  lines.push(`received: ${yamlQuote(receivedDate)}`)
+  lines.push('folders:')
+  lines.push(`  - ${yamlQuote(folderPath)}`)
+
+  if (formats.length === 0) {
+    lines.push('formats: []')
+  } else {
+    lines.push('formats:')
+    for (const fmt of formats) {
+      lines.push(`  - ${yamlQuote(fmt)}`)
+    }
+  }
+
+  if (attachments.length === 0) {
+    lines.push('attachments: []')
+  } else {
+    lines.push('attachments:')
+    for (const att of attachments) {
+      const name = att.filename ?? ''
+      const size = att.size ?? 0
+      lines.push(`  - ${yamlQuote(name ? `${name} (${size} bytes)` : `(${size} bytes)`)}`)
+    }
+  }
+
+  lines.push('---')
+  return lines.join('\n')
+}
+
+// ── Document assembler ────────────────────────────────────────────────────────
+
+// Separator used when both plain text and HTML body parts are present.
+// Three thematic breaks frame a bold label so AI agents and humans can
+// unambiguously identify the boundary and understand what follows.
+const HTML_BODY_SEPARATOR =
+  '\n\n---\n---\n---\n\n' +
+  '**[html-body below - automatically converted from HTML; may contain formatting loss or artifacts]**' +
+  '\n\n---\n---\n---\n\n'
+
+export function assembleDocument(
+  parsed: ParsedMail,
+  rawSource: Buffer | string,
+  folderPath: string,
+): string {
+  // mailparser auto-generates text from html and vice versa — check the raw
+  // content-type to determine which parts were explicitly present
+  const unfolded = parseHeaderBlock(rawSource)
+  const ct = extractRawHeader(unfolded, 'content-type').toLowerCase().trim()
+  const isTopLevelTextOnly = ct.startsWith('text/plain')
+  const isTopLevelHtmlOnly = ct.startsWith('text/html')
+
+  const hasHtml = !isTopLevelTextOnly && typeof parsed.html === 'string' && parsed.html.length > 0
+  const hasText = !isTopLevelHtmlOnly && typeof parsed.text === 'string' && parsed.text.length > 0
+
+  const formats: string[] = []
+  if (hasText) formats.push('plaintext')
+  if (hasHtml) formats.push('html')
+
+  const frontmatter = buildFrontmatter(parsed, rawSource, folderPath, formats)
+
+  const subject = parsed.subject ?? ''
+  const subjectHeading = subject.length > 0
+    ? subject + '\n' + '='.repeat(subject.length)
+    : ''
+
+  const header = subjectHeading ? frontmatter + '\n\n' + subjectHeading : frontmatter
+
+  if (!hasHtml && !hasText) {
+    return header + '\n'
+  }
+
+  if (hasHtml && !hasText) {
+    return header + '\n\n' + htmlToMarkdown(parsed.html as string)
+  }
+
+  if (!hasHtml && hasText) {
+    return header + '\n\n' + convertPlainText(parsed.text as string)
+  }
+
+  // Both present: plain text first (canonical), then HTML conversion
+  return (
+    header +
+    '\n\n' +
+    convertPlainText(parsed.text as string) +
+    HTML_BODY_SEPARATOR +
+    htmlToMarkdown(parsed.html as string)
+  )
+}
+
+// ── Folder/account export ─────────────────────────────────────────────────────
+
+interface FolderMessage {
+  uid: number
+  'message-id': string
+  filename: string
+  flags: string[]
+}
+
+interface FolderState {
+  uidvalidity: string
+  uidnext: number
+  messages: FolderMessage[]
+}
+
+function filterStringFolders(
+  folders: string[],
+  onlyFolders?: string[],
+  excludeFolders?: string[],
+): string[] {
+  if (onlyFolders && onlyFolders.length > 0 && excludeFolders && excludeFolders.length > 0) {
+    throw new Error('onlyFolders and excludeFolders are mutually exclusive')
+  }
+  if (onlyFolders && onlyFolders.length > 0) {
+    return folders.filter((f) => onlyFolders.includes(f))
+  }
+  if (excludeFolders && excludeFolders.length > 0) {
+    return folders.filter((f) => !excludeFolders.includes(f))
+  }
+  return folders
+}
+
+export async function listExportFolders(
+  archivePath: string,
+  opts: { excludeFolders?: string[]; onlyFolders?: string[] },
+): Promise<string[]> {
+  const all = await listFolders(archivePath)
+  return filterStringFolders(all, opts.onlyFolders, opts.excludeFolders)
+}
+
+export async function exportFolder(
+  archivePath: string,
+  exportPath: string,
+  folderPath: string,
+  opts: { verbose?: boolean; onLog?: (m: string) => void },
+): Promise<FolderExportResult> {
+  const result: FolderExportResult = { path: folderPath, exported: 0 }
+
+  const stateFilePath = path.join(archivePath, folderPath, '.backmail_state.json')
+  let state: FolderState
+  try {
+    const content = await fs.readFile(stateFilePath, 'utf-8')
+    state = JSON.parse(content) as FolderState
+  } catch (err) {
+    result.error = err instanceof Error ? err : new Error(String(err))
+    return result
+  }
+
+  const outDir = path.join(exportPath, folderPath)
+  await fs.mkdir(outDir, { recursive: true })
+
+  for (const msg of state.messages) {
+    const emlPath = path.join(archivePath, folderPath, `${msg.filename}.eml`)
+    try {
+      const rawSource = await fs.readFile(emlPath)
+      const parsed = await simpleParser(rawSource)
+      const mdContent = assembleDocument(parsed, rawSource, folderPath)
+      const mdPath = path.join(outDir, `${msg.filename}.md`)
+      await fs.writeFile(mdPath, mdContent, 'utf-8')
+      result.exported++
+      if (opts.verbose) opts.onLog?.(`exported ${folderPath}/${msg.filename}.md`)
+    } catch (err) {
+      const msg2 = err instanceof Error ? err.message : String(err)
+      opts.onLog?.(`error exporting ${folderPath}/${msg.filename}.eml: ${msg2}`)
+      result.exported  // don't increment
+    }
+  }
+
+  return result
+}
+
+export async function exportAccount(
+  archivePath: string,
+  exportPath: string,
+  opts: ExportOptions,
+): Promise<ExportResult> {
+  const folders = await listExportFolders(archivePath, {
+    excludeFolders: opts.excludeFolders,
+    onlyFolders: opts.onlyFolders,
+  })
+
+  const folderResults: FolderExportResult[] = []
+  let totalExported = 0
+  let totalErrors = 0
+
+  for (const folder of folders) {
+    const fr = await exportFolder(archivePath, exportPath, folder, {
+      verbose: opts.verbose,
+      onLog: opts.onLog,
+    })
+    folderResults.push(fr)
+    totalExported += fr.exported
+    if (fr.error) totalErrors++
+  }
+
+  return { exported: totalExported, errors: totalErrors, folderResults }
+}
diff --git a/src/core/index.ts b/src/core/index.ts
index d3ca834..f7bda92 100644
--- a/src/core/index.ts
+++ b/src/core/index.ts
@@ -11,7 +11,7 @@ export { findRepository } from './discovery.js'
 
 // Sync
 export type { SyncResult, SyncOptions, FolderSyncResult } from './sync.js'
-export { syncAccount, reindexLocalFolders, decodeMimeWords } from './sync.js'
+export { syncAccount, reindexLocalFolders, decodeMimeWords, parseHeaderBlock, extractRawHeader } from './sync.js'
 
 // Browse
 export type { MessageSummary } from './browse.js'
@@ -29,3 +29,7 @@ export { restoreAccount } from './restore.js'
 
 // Init
 export { initRepository } from './init.js'
+
+// Export
+export type { ExportOptions, ExportResult, FolderExportResult } from './export.js'
+export { exportAccount } from './export.js'
diff --git a/src/core/sync.ts b/src/core/sync.ts
index 37dad9c..b68b5cf 100644
--- a/src/core/sync.ts
+++ b/src/core/sync.ts
@@ -113,13 +113,13 @@ export function decodeMimeWords(value: string): string {
 }
 
 // Extract the first occurrence of a named header from the raw (unfolded) header block.
-function extractRawHeader(unfolded: string, name: string): string {
+export function extractRawHeader(unfolded: string, name: string): string {
   const re = new RegExp(`^${name}:[ \\t]*(.*)$`, 'im')
   return unfolded.match(re)?.[1]?.trim() ?? ''
 }
 
 // Unfold and extract just the header section from raw email bytes.
-function parseHeaderBlock(rawSource: Buffer | string): string {
+export function parseHeaderBlock(rawSource: Buffer | string): string {
   const text = typeof rawSource === 'string'
     ? rawSource.slice(0, 65536)
     : rawSource.subarray(0, 65536).toString('utf-8')
diff --git a/src/types/turndown-plugin-gfm.d.ts b/src/types/turndown-plugin-gfm.d.ts
new file mode 100644
index 0000000..637bf98
--- /dev/null
+++ b/src/types/turndown-plugin-gfm.d.ts
@@ -0,0 +1,6 @@
+declare module 'turndown-plugin-gfm' {
+  import TurndownService from 'turndown'
+  export function gfm(service: TurndownService): void
+  export function tables(service: TurndownService): void
+  export function strikethrough(service: TurndownService): void
+}
diff --git a/tests/fixtures/export/html-only.eml b/tests/fixtures/export/html-only.eml
new file mode 100644
index 0000000..b8ba57a
--- /dev/null
+++ b/tests/fixtures/export/html-only.eml
@@ -0,0 +1,9 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: HTML Only Email
+Date: Thu, 15 Jan 2026 13:37:42 +0000
+Message-ID: <html-only@example.com>
+Content-Type: text/html; charset=UTF-8
+
+<p><strong>Hello</strong>, this is an HTML-only email.</p>
+<p>No plain text part.</p>
diff --git a/tests/fixtures/export/multi-recipient.eml b/tests/fixtures/export/multi-recipient.eml
new file mode 100644
index 0000000..0683647
--- /dev/null
+++ b/tests/fixtures/export/multi-recipient.eml
@@ -0,0 +1,8 @@
+From: sender@example.com
+To: Alice <alice@example.com>, Bob <bob@example.com>, Carol <carol@example.com>
+Subject: Multi-Recipient Email
+Date: Thu, 15 Jan 2026 17:00:00 +0000
+Message-ID: <multi-recipient@example.com>
+Content-Type: text/plain; charset=UTF-8
+
+Hello everyone, this email has three recipients.
diff --git a/tests/fixtures/export/multipart.eml b/tests/fixtures/export/multipart.eml
new file mode 100644
index 0000000..9456f85
--- /dev/null
+++ b/tests/fixtures/export/multipart.eml
@@ -0,0 +1,18 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: Multipart Email
+Date: Thu, 15 Jan 2026 15:00:00 +0000
+Message-ID: <multipart@example.com>
+Content-Type: multipart/alternative; boundary="mp-boundary-123"
+
+--mp-boundary-123
+Content-Type: text/plain; charset=UTF-8
+
+Hello, this is the plain text part.
+
+--mp-boundary-123
+Content-Type: text/html; charset=UTF-8
+
+<p>Hello, this is the <strong>HTML part</strong>.</p>
+
+--mp-boundary-123--
diff --git a/tests/fixtures/export/plaintext-only.eml b/tests/fixtures/export/plaintext-only.eml
new file mode 100644
index 0000000..9a3302a
--- /dev/null
+++ b/tests/fixtures/export/plaintext-only.eml
@@ -0,0 +1,9 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: Plain Text Only Email
+Date: Thu, 15 Jan 2026 14:00:00 +0000
+Message-ID: <plaintext-only@example.com>
+Content-Type: text/plain; charset=UTF-8
+
+Hello, this is a plain-text-only email.
+No HTML part here.
diff --git a/tests/fixtures/export/pure-attachment.eml b/tests/fixtures/export/pure-attachment.eml
new file mode 100644
index 0000000..c6f6b33
--- /dev/null
+++ b/tests/fixtures/export/pure-attachment.eml
@@ -0,0 +1,15 @@
+From: sender@example.com
+To: recipient@example.com
+Subject: Pure Attachment Email
+Date: Thu, 15 Jan 2026 16:00:00 +0000
+Message-ID: <pure-attachment@example.com>
+Content-Type: multipart/mixed; boundary="att-boundary-456"
+
+--att-boundary-456
+Content-Type: application/pdf
+Content-Disposition: attachment; filename="document.pdf"
+Content-Transfer-Encoding: base64
+
+JVBERi0xLjAK
+
+--att-boundary-456--
diff --git a/tests/integration/export.test.ts b/tests/integration/export.test.ts
new file mode 100644
index 0000000..db451c8
--- /dev/null
+++ b/tests/integration/export.test.ts
@@ -0,0 +1,142 @@
+import { describe, it, expect, beforeAll, afterAll } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { exportAccount } from '../../src/core/export.js'
+
+// ── Fixture EML filenames (stems) ─────────────────────────────────────────────
+
+const FIXTURES_DIR = path.join(import.meta.dirname, '../fixtures/export')
+
+const FOLDER_A_FILES = [
+  '2026-01-15_html-only_aabbccdd',
+  '2026-01-15_plaintext_bbccddee',
+  '2026-01-15_multipart_ccddeeff',
+]
+
+const FOLDER_B_FILES = [
+  '2026-01-15_attachment_ddeeffgg',
+  '2026-01-15_multircpt_eeffgghh',
+]
+
+const FIXTURE_MAP: Record<string, string> = {
+  '2026-01-15_html-only_aabbccdd': 'html-only.eml',
+  '2026-01-15_plaintext_bbccddee': 'plaintext-only.eml',
+  '2026-01-15_multipart_ccddeeff': 'multipart.eml',
+  '2026-01-15_attachment_ddeeffgg': 'pure-attachment.eml',
+  '2026-01-15_multircpt_eeffgghh': 'multi-recipient.eml',
+}
+
+function makeState(filenames: string[]) {
+  return JSON.stringify({
+    uidvalidity: '1',
+    uidnext: filenames.length + 1,
+    messages: filenames.map((f, i) => ({
+      uid: i + 1,
+      'message-id': `<${f}@test>`,
+      filename: f,
+      flags: [],
+    })),
+  })
+}
+
+// ── Setup/teardown ────────────────────────────────────────────────────────────
+
+let tmpDir: string
+let archivePath: string
+let exportPath: string
+
+beforeAll(async () => {
+  tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'backmail-export-integration-'))
+  archivePath = path.join(tmpDir, 'archive')
+  exportPath = path.join(tmpDir, 'export')
+
+  // Create FolderA and FolderB under archive
+  for (const [folder, files] of [['FolderA', FOLDER_A_FILES], ['FolderB', FOLDER_B_FILES]] as const) {
+    const folderDir = path.join(archivePath, folder)
+    await fs.mkdir(folderDir, { recursive: true })
+    await fs.writeFile(path.join(folderDir, '.backmail_state.json'), makeState(files))
+    for (const stem of files) {
+      const fixtureName = FIXTURE_MAP[stem]
+      const src = path.join(FIXTURES_DIR, fixtureName)
+      await fs.copyFile(src, path.join(folderDir, `${stem}.eml`))
+    }
+  }
+})
+
+afterAll(async () => {
+  await fs.rm(tmpDir, { recursive: true, force: true })
+})
+
+// ── Tests ─────────────────────────────────────────────────────────────────────
+
+describe('exportAccount integration', () => {
+  it('exports all folders and mirrors archive directory structure', async () => {
+    const result = await exportAccount(archivePath, exportPath, {})
+    expect(result.errors).toBe(0)
+    expect(result.exported).toBe(FOLDER_A_FILES.length + FOLDER_B_FILES.length)
+
+    // Check directory structure
+    for (const folder of ['FolderA', 'FolderB']) {
+      const stat = await fs.stat(path.join(exportPath, folder))
+      expect(stat.isDirectory()).toBe(true)
+    }
+  })
+
+  it('produces one .md per .eml (file counts match)', async () => {
+    // Count .eml files under archivePath
+    let emlCount = 0
+    for (const folder of ['FolderA', 'FolderB']) {
+      const entries = await fs.readdir(path.join(archivePath, folder))
+      emlCount += entries.filter((e) => e.endsWith('.eml')).length
+    }
+
+    // Count .md files under exportPath
+    let mdCount = 0
+    for (const folder of ['FolderA', 'FolderB']) {
+      const entries = await fs.readdir(path.join(exportPath, folder))
+      mdCount += entries.filter((e) => e.endsWith('.md')).length
+    }
+
+    expect(mdCount).toBe(emlCount)
+  })
+
+  it('is idempotent: running twice produces identical output', async () => {
+    // Read current content
+    const readAll = async () => {
+      const contents: Record<string, string> = {}
+      for (const folder of ['FolderA', 'FolderB']) {
+        const dir = path.join(exportPath, folder)
+        const entries = await fs.readdir(dir)
+        for (const f of entries.filter((e) => e.endsWith('.md'))) {
+          contents[`${folder}/${f}`] = await fs.readFile(path.join(dir, f), 'utf-8')
+        }
+      }
+      return contents
+    }
+
+    const before = await readAll()
+    await exportAccount(archivePath, exportPath, {})
+    const after = await readAll()
+
+    expect(after).toEqual(before)
+  })
+
+  it('--only-folder: only specified folder is in output', async () => {
+    const onlyExportPath = path.join(tmpDir, 'export-only')
+    await exportAccount(archivePath, onlyExportPath, { onlyFolders: ['FolderA'] })
+
+    const entries = await fs.readdir(onlyExportPath)
+    expect(entries).toContain('FolderA')
+    expect(entries).not.toContain('FolderB')
+  })
+
+  it('--exclude-folder: excluded folder is absent from output', async () => {
+    const excExportPath = path.join(tmpDir, 'export-exclude')
+    await exportAccount(archivePath, excExportPath, { excludeFolders: ['FolderA'] })
+
+    const entries = await fs.readdir(excExportPath)
+    expect(entries).not.toContain('FolderA')
+    expect(entries).toContain('FolderB')
+  })
+})
diff --git a/tests/unit/export.test.ts b/tests/unit/export.test.ts
new file mode 100644
index 0000000..35488f9
--- /dev/null
+++ b/tests/unit/export.test.ts
@@ -0,0 +1,733 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import os from 'node:os'
+import path from 'node:path'
+import fs from 'node:fs'
+import fsp from 'node:fs/promises'
+import { simpleParser } from 'mailparser'
+import {
+  preprocessHtml,
+  htmlToMarkdown,
+  extractReceivedDate,
+  buildFrontmatter,
+  assembleDocument,
+  convertPlainText,
+  exportFolder,
+  exportAccount,
+} from '../../src/core/export.js'
+
+// ── preprocessHtml ────────────────────────────────────────────────────────────
+
+describe('preprocessHtml', () => {
+  it('strips <style> blocks', () => {
+    const html = '<style>body { color: red; }</style><p>Hello</p>'
+    expect(preprocessHtml(html)).not.toContain('<style>')
+    expect(preprocessHtml(html)).toContain('<p>Hello</p>')
+  })
+
+  it('strips <script> blocks', () => {
+    const html = '<script>alert(1)</script><p>Text</p>'
+    expect(preprocessHtml(html)).not.toContain('<script>')
+    expect(preprocessHtml(html)).toContain('<p>Text</p>')
+  })
+
+  it('strips external images (logos, layout, tracking pixels)', () => {
+    const html = '<img src="https://example.com/logo.png"><img src="track.gif" width="1" height="1"><p>Text</p>'
+    const result = preprocessHtml(html)
+    expect(result).not.toContain('<img')
+    expect(result).toContain('<p>Text</p>')
+  })
+
+  it('preserves inline attachment images (cid: src)', () => {
+    const html = '<img src="cid:image001@example.com"><p>Text</p>'
+    const result = preprocessHtml(html)
+    expect(result).toContain('<img')
+    expect(result).toContain('cid:image001@example.com')
+  })
+
+  it('strips soft hyphens and zero-width spaces used as email spacers', () => {
+    const html = '<td>­</td><td>Text</td><td>​</td>'
+    const result = preprocessHtml(html)
+    expect(result).not.toContain('­')
+    expect(result).not.toContain('​')
+    expect(result).toContain('Text')
+  })
+
+  it('strips combining grapheme joiner (U+034F) used in preheader padding', () => {
+    const html = '<p>Preview text͏͏͏͏͏</p><p>Body</p>'
+    const result = preprocessHtml(html)
+    expect(result).not.toContain('͏')
+    expect(result).toContain('Preview text')
+  })
+})
+
+// ── htmlToMarkdown ────────────────────────────────────────────────────────────
+
+describe('htmlToMarkdown', () => {
+  it('converts basic HTML to markdown', () => {
+    const result = htmlToMarkdown('<p><strong>Hello</strong> world</p>')
+    expect(result).toContain('**Hello**')
+  })
+
+  it('replaces non-breaking spaces with regular spaces', () => {
+    const result = htmlToMarkdown('<p>Hello World</p>')
+    expect(result).not.toContain(' ')
+    expect(result).toContain('Hello World')
+  })
+
+  it('strips entity-encoded invisible chars and figure spaces that survive preprocessHtml', () => {
+    // &#8199; = U+2007 figure space, &#847; = U+034F CGJ, &shy; = U+00AD soft hyphen
+    const html = '<div>&#8199;&#847; &#8199;&#847; &shy; &shy;</div><p>Body</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toContain('\u2007')
+    expect(result).not.toContain('\u034f')
+    // The padding div should collapse to nothing, leaving only the body
+    expect(result.trim()).toBe('Body')
+  })
+
+  it('trims trailing whitespace from lines', () => {
+    const result = htmlToMarkdown('<p>Hello   </p><p>World</p>')
+    expect(result).not.toMatch(/[ \t]+\n/)
+    expect(result).not.toMatch(/[ \t]+$/)
+  })
+
+  it('collapses 3+ consecutive newlines to 2', () => {
+    const html = '<p>A</p><p></p><p></p><p></p><p>B</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toMatch(/\n{3,}/)
+  })
+
+  it('converts escaped visual bullets with leading spaces to real list items', () => {
+    // &nbsp;&nbsp;&nbsp;* text is a common email pattern for visual lists
+    const html = '<p>&nbsp;&nbsp;&nbsp;&nbsp;* Item one<br>&nbsp;&nbsp;&nbsp;&nbsp;* Item two</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toContain('\\*')
+    expect(result).toContain('- Item one')
+    expect(result).toContain('- Item two')
+  })
+
+  it('does not convert \\* in the middle of a line', () => {
+    // Only line-leading escaped bullets should become list items
+    const html = '<p>Price is 5 \\* 3 = 15</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).toContain('5')
+    expect(result).toContain('3')
+  })
+
+  it('removes links with empty text (remnants of stripped images inside <a>)', () => {
+    const html = '<p>Before</p><a href="https://track.example.com/click"><img src="logo.png"></a><p>After</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toMatch(/\[\s*\]\(/)
+    expect(result).toContain('Before')
+    expect(result).toContain('After')
+  })
+
+  it('collapses 4+ consecutive blank lines to 2', () => {
+    // Force 4+ blank lines by injecting them after conversion
+    // We test by passing content that will produce multiple blank lines
+    const html = '<p>A</p><p></p><p></p><p></p><p>B</p>'
+    const result = htmlToMarkdown(html)
+    expect(result).not.toMatch(/\n{4,}/)
+  })
+
+  describe('table handling', () => {
+    it('unwraps a layout table (no <th>) to prose — no pipe characters', () => {
+      const html = `<table>
+        <tr><td>Hello</td><td>World</td></tr>
+        <tr><td>Foo</td><td>Bar</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Hello')
+      expect(result).toContain('World')
+    })
+
+    it('unwraps a table with role="presentation" even if it has <th>', () => {
+      const html = `<table role="presentation">
+        <tr><th>Name</th><th>Value</th></tr>
+        <tr><td>foo</td><td>bar</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Name')
+      expect(result).toContain('foo')
+    })
+
+    it('preserves a data table (first row all <th>) as a pipe table', () => {
+      const html = `<table>
+        <tr><th>Name</th><th>Value</th></tr>
+        <tr><td>foo</td><td>bar</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).toContain('| Name | Value |')
+      expect(result).toContain('| foo | bar |')
+      expect(result).toContain('---')
+    })
+
+    it('preserves inline formatting inside layout table cells', () => {
+      const html = `<table>
+        <tr><td><strong>Bold</strong> and <a href="/x">link</a></td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).toContain('**Bold**')
+      expect(result).toContain('[link](/x)')
+    })
+
+    it('unwraps nested layout tables', () => {
+      const html = `<table>
+        <tr><td>
+          <table><tr><td>Inner</td></tr></table>
+        </td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Inner')
+    })
+
+    it('unwraps a layout table that uses <th> for layout (cells contain block content)', () => {
+      // Newsletters often use <th> for two-column grids — these are layout tables,
+      // not data tables, and should be unwrapped to prose, not rendered as pipe tables.
+      const html = `<table>
+        <tr>
+          <th><img src="cid:a.jpg" alt="A"><p>Left text</p></th>
+          <th><img src="cid:b.jpg" alt="B"><p>Right text</p></th>
+        </tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('|')
+      expect(result).toContain('Left text')
+      expect(result).toContain('Right text')
+    })
+
+    it('preserves a data table nested inside a layout table', () => {
+      const html = `<table>
+        <tr><td>
+          <table>
+            <tr><th>Col A</th><th>Col B</th></tr>
+            <tr><td>1</td><td>2</td></tr>
+          </table>
+        </td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      expect(result).toContain('| Col A | Col B |')
+    })
+
+    it('adds hard line breaks between layout table cell lines so they render visibly', () => {
+      // Each cell ends up on its own line after table unwrapping; without \
+      // they would render as a single run-on paragraph in markdown.
+      const html = `<table>
+        <tr><td>First cell</td><td>Second cell</td></tr>
+        <tr><td>Third cell</td><td>Fourth cell</td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      // All prose lines except the last in a consecutive run should end with \
+      const lines = result.split('\n').filter((l) => l.trim() !== '')
+      for (let i = 0; i < lines.length - 1; i++) {
+        expect(lines[i]).toMatch(/\\$/)
+      }
+      expect(lines[lines.length - 1]).not.toMatch(/\\$/)
+    })
+
+    it('does not add hard breaks to lines already separated by blank lines', () => {
+      // Regular paragraphs are separated by \n\n and must NOT get \
+      const html = '<p>Paragraph one</p><p>Paragraph two</p>'
+      const result = htmlToMarkdown(html)
+      expect(result).not.toContain('\\')
+    })
+
+    it('does not add hard breaks to heading or list lines from layout tables', () => {
+      // When a layout table cell contains a heading or list, those lines are
+      // block elements and should not receive or trigger hard-break markers.
+      const html = `<table>
+        <tr><td><h2>Section title</h2></td></tr>
+        <tr><td><ul><li>item one</li><li>item two</li></ul></td></tr>
+      </table>`
+      const result = htmlToMarkdown(html)
+      // No line ending with \ should appear
+      expect(result).not.toMatch(/\\\n/)
+      expect(result).not.toMatch(/\\$/)
+    })
+  })
+})
+
+// ── convertPlainText ──────────────────────────────────────────────────────────
+
+describe('convertPlainText', () => {
+  it('returns empty string for empty input', () => {
+    expect(convertPlainText('')).toBe('')
+  })
+
+  it('adds trailing \\ between consecutive prose lines', () => {
+    const result = convertPlainText('Line one\nLine two\nLine three')
+    expect(result).toBe('Line one\\\nLine two\\\nLine three')
+  })
+
+  it('does not add \\ after the last line', () => {
+    const result = convertPlainText('Only line')
+    expect(result).toBe('Only line')
+  })
+
+  it('does not add \\ before a blank line', () => {
+    const result = convertPlainText('Para one\n\nPara two')
+    expect(result).toBe('Para one\n\nPara two')
+  })
+
+  it('does not add \\ to list items (- )', () => {
+    const result = convertPlainText('- item one\n- item two')
+    expect(result).toBe('- item one\n- item two')
+  })
+
+  it('does not add \\ to list items (* )', () => {
+    const result = convertPlainText('* item one\n* item two')
+    expect(result).toBe('* item one\n* item two')
+  })
+
+  it('does not add \\ to numbered list items', () => {
+    const result = convertPlainText('1. first\n2. second')
+    expect(result).toBe('1. first\n2. second')
+  })
+
+  it('does not add \\ to prose line followed by a list item', () => {
+    const result = convertPlainText('Intro text\n- item one')
+    expect(result).toBe('Intro text\n- item one')
+  })
+
+  it('does not add \\ to list item followed by prose', () => {
+    const result = convertPlainText('- item\nTrailing prose')
+    expect(result).toBe('- item\nTrailing prose')
+  })
+
+  it('handles mixed prose and list', () => {
+    const result = convertPlainText('Hello\nWorld\n\n- item\n\nFoo\nBar')
+    expect(result).toBe('Hello\\\nWorld\n\n- item\n\nFoo\\\nBar')
+  })
+
+  it('escapes < in prose (prevents HTML injection)', () => {
+    const result = convertPlainText('See <https://example.com>')
+    expect(result).toBe('See &lt;https://example.com>')
+  })
+
+  it('escapes < in list items', () => {
+    const result = convertPlainText('- See <note>')
+    expect(result).toBe('- See &lt;note>')
+  })
+
+  it('keeps > as-is so quoted lines become Markdown blockquotes', () => {
+    const text = '> Hello\n> World'
+    const result = convertPlainText(text)
+    expect(result).toContain('> Hello')
+    expect(result).toContain('> World')
+    expect(result).not.toContain('&gt;')
+  })
+
+  it('treats whitespace-only lines as blank — does not add \\ to preceding line', () => {
+    // Plain-text emails often use tab-only lines as separators between content blocks.
+    // They should not trigger hard-break markers on the line before them.
+    const text = 'USA / New York\n\t\nLive dabei'
+    const result = convertPlainText(text)
+    expect(result).not.toContain('\\')
+    expect(result).toContain('USA / New York')
+    expect(result).toContain('Live dabei')
+  })
+
+  it('does not emit whitespace-only lines — collapses them to empty', () => {
+    const text = 'Line A\n\t\n\t\nLine B'
+    const result = convertPlainText(text)
+    expect(result).not.toMatch(/^\t/m)
+  })
+
+  it('does not add hard-break \\ to blockquote lines', () => {
+    const text = '> Quoted line one\n> Quoted line two'
+    const result = convertPlainText(text)
+    expect(result).not.toContain('\\')
+  })
+
+  it('does not add hard-break \\ to prose line immediately before a blockquote', () => {
+    const text = 'Someone wrote:\n> Quoted text'
+    const result = convertPlainText(text)
+    expect(result).not.toMatch(/wrote:\\$/)
+    expect(result).toContain('> Quoted text')
+  })
+
+  it('preserves indented list items (spaces)', () => {
+    const result = convertPlainText('  - nested item')
+    expect(result).toBe('  - nested item')
+  })
+
+  it('turns a dash divider directly under text into a thematic break (not a heading)', () => {
+    const result = convertPlainText('Some text\n----------')
+    expect(result).toBe('Some text\n\n---')
+  })
+
+  it('turns an equals divider directly under text into a thematic break', () => {
+    const result = convertPlainText('Some text\n==========')
+    expect(result).toBe('Some text\n\n---')
+  })
+
+  it('turns a standalone dash divider into a thematic break without extra blank line', () => {
+    // Divider not preceded by non-empty line — no extra blank line needed
+    const result = convertPlainText('----------')
+    expect(result).toBe('---')
+  })
+
+  it('handles divider between two prose paragraphs', () => {
+    const result = convertPlainText('Para one\n----------\nPara two')
+    expect(result).toBe('Para one\n\n---\nPara two')
+  })
+
+  it('does not add \\ to prose line immediately before a divider', () => {
+    const result = convertPlainText('Line one\n----------')
+    // "Line one" should NOT get a trailing \ even though it is followed by non-empty content
+    expect(result).not.toContain('\\')
+  })
+
+  it('normalises both 2-char and long dividers to ---', () => {
+    expect(convertPlainText('--')).toBe('---')
+    expect(convertPlainText('==================================================================')).toBe('---')
+  })
+
+  it('escapes # heading (h1)', () => {
+    expect(convertPlainText('# Hello')).toBe('\\# Hello')
+  })
+
+  it('escapes ## heading (h2)', () => {
+    expect(convertPlainText('## Section')).toBe('\\## Section')
+  })
+
+  it('escapes up to h6', () => {
+    expect(convertPlainText('###### tiny')).toBe('\\###### tiny')
+  })
+
+  it('escapes # with no following space (bare hash at EOL counts as heading)', () => {
+    expect(convertPlainText('#')).toBe('\\#')
+  })
+
+  it('does not escape # in the middle of a line', () => {
+    expect(convertPlainText('color: #ff0000')).toBe('color: #ff0000')
+  })
+
+  it('does not escape lines with 7+ # chars (not a heading)', () => {
+    expect(convertPlainText('####### not a heading')).toBe('####### not a heading')
+  })
+
+  it('escapes # with up to 3 leading spaces, backslash right before #', () => {
+    expect(convertPlainText('   # indented')).toBe('   \\# indented')
+  })
+})
+
+// ── extractReceivedDate ───────────────────────────────────────────────────────
+
+describe('extractReceivedDate', () => {
+  it('prefers Received: header timestamp after semicolon', () => {
+    const raw = 'Received: from mail.example.com by server; Thu, 15 Jan 2026 13:37:42 +0000\r\nDate: Mon, 1 Jan 2024 00:00:00 +0000\r\n\r\nBody'
+    expect(extractReceivedDate(raw)).toBe('2026-01-15 13:37:42')
+  })
+
+  it('falls back to Date: header when Received: is absent', () => {
+    const raw = 'Date: Wed, 15 Jan 2025 10:20:30 +0000\r\n\r\nBody'
+    expect(extractReceivedDate(raw)).toBe('2025-01-15 10:20:30')
+  })
+
+  it('falls back to 0000-00-00 00:00:00 when no date headers', () => {
+    const raw = 'From: foo@example.com\r\n\r\nBody'
+    expect(extractReceivedDate(raw)).toBe('0000-00-00 00:00:00')
+  })
+})
+
+// ── buildFrontmatter ──────────────────────────────────────────────────────────
+
+describe('buildFrontmatter', () => {
+  it('produces correct frontmatter for a basic email', async () => {
+    const eml = [
+      'From: Jane Doe <jane@example.com>',
+      'To: John Doe <john@example.com>',
+      'Subject: Hello World',
+      'Message-ID: <abc123@example.com>',
+      'Date: Thu, 15 Jan 2026 13:37:42 +0000',
+      '',
+      'Body text',
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('messageId:')
+    expect(fm).toContain('subject: "Hello World"')
+    expect(fm).toContain('from: "Jane Doe <jane@example.com>"')
+    expect(fm).toContain('- "INBOX"')
+  })
+
+  it('produces to: [] when To header is absent', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('to: []')
+  })
+
+  it('produces YAML list when multiple To recipients', async () => {
+    const eml = [
+      'From: sender@example.com',
+      'To: Alice <alice@example.com>, Bob <bob@example.com>',
+      'Subject: Multi',
+      '',
+      'Body',
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('"Alice <alice@example.com>"')
+    expect(fm).toContain('"Bob <bob@example.com>"')
+  })
+
+  it('sets subject to empty string when missing', async () => {
+    const eml = 'From: foo@example.com\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('subject: ""')
+  })
+
+  it('sets from to bare email when name is absent', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('from: "foo@example.com"')
+  })
+
+  it('lists attachments as "filename (N bytes)" strings', async () => {
+    const boundary = 'abc123boundary'
+    const eml = [
+      'From: foo@example.com',
+      'Subject: With Attachment',
+      `Content-Type: multipart/mixed; boundary="${boundary}"`,
+      '',
+      `--${boundary}`,
+      'Content-Type: text/plain',
+      '',
+      'Body',
+      `--${boundary}`,
+      'Content-Type: application/pdf',
+      'Content-Disposition: attachment; filename="report.pdf"',
+      'Content-Transfer-Encoding: base64',
+      '',
+      'AAAA',
+      `--${boundary}--`,
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toMatch(/- "report\.pdf \(\d+ bytes\)"/)
+    expect(fm).not.toContain('contentType:')
+  })
+
+  it('sets attachments: [] when no attachments', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('attachments: []')
+  })
+
+  it('includes formats list in frontmatter', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', ['plaintext', 'html'])
+    expect(fm).toContain('formats:')
+    expect(fm).toContain('  - "plaintext"')
+    expect(fm).toContain('  - "html"')
+  })
+
+  it('includes formats: [] when no formats given', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Test\r\n\r\nBody'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const fm = buildFrontmatter(parsed, Buffer.from(eml), 'INBOX', [])
+    expect(fm).toContain('formats: []')
+  })
+})
+
+// ── assembleDocument ──────────────────────────────────────────────────────────
+
+describe('assembleDocument', () => {
+  it('HTML-only: body is markdown, no divider', async () => {
+    const eml = [
+      'From: foo@example.com',
+      'Subject: HTML Only',
+      'Content-Type: text/html',
+      '',
+      '<p><strong>Hello</strong></p>',
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('**Hello**')
+    expect(doc).not.toContain('html-body below')
+  })
+
+  it('plain-text-only: body is plain text, no conversion', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Text\r\n\r\nHello plain world'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('Hello plain world')
+  })
+
+  it('HTML + plain text: separator present, plain text before HTML', async () => {
+    const boundary = 'div123'
+    const eml = [
+      'From: foo@example.com',
+      'Subject: Both',
+      `Content-Type: multipart/alternative; boundary="${boundary}"`,
+      '',
+      `--${boundary}`,
+      'Content-Type: text/plain',
+      '',
+      'Plain text here',
+      `--${boundary}`,
+      'Content-Type: text/html',
+      '',
+      '<p>HTML here</p>',
+      `--${boundary}--`,
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('**[html-body below - automatically converted from HTML; may contain formatting loss or artifacts]**')
+    expect(doc).toContain('HTML here')
+    expect(doc).toContain('Plain text here')
+    // Plain text section must come before the HTML section
+    expect(doc.indexOf('Plain text here')).toBeLessThan(doc.indexOf('HTML here'))
+    // Frontmatter must list both formats
+    expect(doc).toContain('formats:')
+    expect(doc).toContain('"plaintext"')
+    expect(doc).toContain('"html"')
+  })
+
+  it('includes setext h1 with subject between frontmatter and body', async () => {
+    const eml = 'From: foo@example.com\r\nSubject: Hello World\r\n\r\nBody text'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    expect(doc).toContain('Hello World\n===========')
+  })
+
+  it('omits heading when subject is empty', async () => {
+    const eml = 'From: foo@example.com\r\n\r\nBody text'
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    // No setext underline in output
+    expect(doc).not.toMatch(/^=+$/m)
+  })
+
+  it('pure-attachment: only frontmatter, no body content', async () => {
+    const boundary = 'att123'
+    const eml = [
+      'From: foo@example.com',
+      'Subject: Attachment Only',
+      `Content-Type: multipart/mixed; boundary="${boundary}"`,
+      '',
+      `--${boundary}`,
+      'Content-Type: application/pdf',
+      'Content-Disposition: attachment; filename="doc.pdf"',
+      'Content-Transfer-Encoding: base64',
+      '',
+      'AAAA',
+      `--${boundary}--`,
+    ].join('\r\n')
+    const parsed = await simpleParser(Buffer.from(eml))
+    const doc = assembleDocument(parsed, Buffer.from(eml), 'INBOX')
+    // Only frontmatter + optional subject heading, no body content
+    expect(doc).not.toContain('AAAA')
+    expect(doc).not.toContain('text/plain')
+    // No prose body after the heading
+    const afterHeading = doc.replace(/^---[\s\S]*?---\n(\n[\s\S]*?={3,}\n)?/, '')
+    expect(afterHeading.trim()).toBe('')
+  })
+})
+
+// ── exportFolder / exportAccount (I/O) ────────────────────────────────────────
+
+const SIMPLE_EML = 'From: foo@example.com\r\nSubject: Test\r\n\r\nHello world'
+
+function makeState(messages: { filename: string }[]) {
+  return JSON.stringify({
+    uidvalidity: '1',
+    uidnext: messages.length + 1,
+    messages: messages.map((m, i) => ({
+      uid: i + 1,
+      'message-id': `<${m.filename}@test>`,
+      filename: m.filename,
+      flags: [],
+    })),
+  })
+}
+
+describe('exportFolder', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backmail-export-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('writes .md at correct path for a single message', async () => {
+    const archivePath = path.join(tmpDir, 'archive')
+    const exportPath = path.join(tmpDir, 'export')
+    const folderDir = path.join(archivePath, 'INBOX')
+    await fsp.mkdir(folderDir, { recursive: true })
+    await fsp.writeFile(path.join(folderDir, '.backmail_state.json'), makeState([{ filename: '2026-01-01_test_abc12345' }]))
+    await fsp.writeFile(path.join(folderDir, '2026-01-01_test_abc12345.eml'), SIMPLE_EML)
+
+    const result = await exportFolder(archivePath, exportPath, 'INBOX', {})
+    expect(result.exported).toBe(1)
+    expect(result.error).toBeUndefined()
+
+    const mdPath = path.join(exportPath, 'INBOX', '2026-01-01_test_abc12345.md')
+    const content = await fsp.readFile(mdPath, 'utf-8')
+    expect(content).toContain('messageId:')
+  })
+
+  it('counts error and continues when .eml is missing', async () => {
+    const archivePath = path.join(tmpDir, 'archive')
+    const exportPath = path.join(tmpDir, 'export')
+    const folderDir = path.join(archivePath, 'INBOX')
+    await fsp.mkdir(folderDir, { recursive: true })
+    await fsp.writeFile(
+      path.join(folderDir, '.backmail_state.json'),
+      makeState([{ filename: 'missing_file' }, { filename: '2026-01-01_ok_abc12345' }]),
+    )
+    // Only write the second eml
+    await fsp.writeFile(path.join(folderDir, '2026-01-01_ok_abc12345.eml'), SIMPLE_EML)
+
+    const logs: string[] = []
+    const result = await exportFolder(archivePath, exportPath, 'INBOX', { onLog: (m) => logs.push(m) })
+    expect(result.exported).toBe(1)
+    expect(logs.some((l) => l.includes('missing_file'))).toBe(true)
+  })
+})
+
+describe('exportAccount', () => {
+  let tmpDir: string
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'backmail-exportacc-'))
+  })
+
+  afterEach(async () => {
+    await fsp.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  it('exports two folders and sums counts correctly', async () => {
+    const archivePath = path.join(tmpDir, 'archive')
+    const exportPath = path.join(tmpDir, 'export')
+
+    for (const folder of ['INBOX', 'Sent']) {
+      const folderDir = path.join(archivePath, folder)
+      await fsp.mkdir(folderDir, { recursive: true })
+      await fsp.writeFile(
+        path.join(folderDir, '.backmail_state.json'),
+        makeState([{ filename: `2026-01-01_msg_${folder.toLowerCase()}` }]),
+      )
+      await fsp.writeFile(
+        path.join(folderDir, `2026-01-01_msg_${folder.toLowerCase()}.eml`),
+        SIMPLE_EML,
+      )
+    }
+
+    const result = await exportAccount(archivePath, exportPath, {})
+    expect(result.exported).toBe(2)
+    expect(result.errors).toBe(0)
+    expect(result.folderResults).toHaveLength(2)
+  })
+})