Toolshed

CaveatsPDF output needs an external engine; Typst is fast and light, LaTeX (texlive) is heavy but still the only option for some journal templates.

EscalateNever for the conversion. A model is only useful upstream — writing or restructuring the Markdown before pandoc touches it.

CaveatsWord-native features (comments, tracked changes, floats with anchors) don't round-trip; you get clean structure, not pixel-matched design.

EscalateNever — style mapping is a template problem, not a judgment problem. Rewriting content for a different audience is a separate upstream step.

CaveatsTracked changes and comments are discarded unless you pass --track-changes=all; pseudo-headings faked with bold text stay paragraphs, because they were never structure.

EscalateOnly when there is no structure to recover — a document where every heading was faked with formatting and you want semantic headings inferred.

CaveatsSmaller rule set than pandoc; tables need the GFM plugin and you own the escaping edge cases.

EscalateNever for markup. Use a model only to decide which region of a hostile app UI is "the content" — then hand that node to turndown.

CaveatsRun epubcheck before publishing; store-specific requirements (Apple, Kobo) go beyond mere validity.

EscalateNever.

CaveatsFidelity is high, not perfect: fonts must be installed on the host, and exotic SmartArt or macro-driven content drifts. Concurrent runs need separate profiles via -env:UserInstallation=.

EscalateNever.

CaveatsNo JavaScript execution — render dynamic content to static HTML first. Very modern CSS layout features can differ from a browser's rendering.

EscalateNever.

CaveatsHeavy dependency tree (OCR, ONNX models) and quality varies a lot by document type; validate the extracted structure before trusting anything built on top of it.

EscalateThe model tier is the point here — keep it narrow. Constrain output to the schema, validate every extracted number against the deterministic parse, and log both so a disagreement is visible.

CaveatsDRM-protected files will not convert, and whether to remove DRM is your legal call, not the tool's. Heavily designed fixed-layout books reflow poorly.

EscalateNever.

CaveatsMulti-column and tabular layouts still interleave; -layout helps, and -bbox-layout gives coordinates when you need to reconstruct columns yourself.

EscalateNever for extraction. Escalate only for interpretation — turning extracted text into a schema (see messy-doc-to-schema).

CaveatsOCR quality is bounded by scan quality — deskew and clean help, but phone photos of curved pages stay bad. Slow and CPU-hungry on long documents.

EscalateWhen accuracy matters on hard scans — handwriting, historical type, dense tables — a vision model reads them better. Still run OCR first and keep its output as a cross-check: OCR fails loudly, models fail by writing plausible words.

Caveats300+ dpi over a long document produces very large files quickly; pick the lowest DPI the downstream stage tolerates and record it.

EscalateThis pair is the deterministic half of a model workflow — the model comes after, on the rendered images, never instead of the render.

CaveatsDigital-born PDFs only; borderless tables need tuning, and the parse-accuracy report is worth reading rather than trusting. tabula-java and pdfplumber are reasonable alternatives with different failure shapes.

EscalateScanned tables, or tables whose header semantics are ambiguous, are legitimately model work — render pages with pdftoppm, give the model the image, then validate totals and row counts deterministically.

CaveatsVery large documents need --stream or NDJSON input; the syntax has a genuine learning curve that people repeatedly underestimate.

EscalateUse a model to *write the jq program* when the shape is unfamiliar — then keep the program, drop the model, and put the program in version control.

CaveatsSome subcommands depend on how the binary was built (feature flags); csvkit is slower but pip-installable everywhere and reads more input formats.

EscalateOnly when the fix requires meaning — deciding that "N/A", "-" and "" are the same null, or that two differently-spelled columns are one field. Extract deterministically, let a model propose the mapping, then encode that mapping as a rule you can re-run.

CaveatsFormulas export as their last cached value; merged cells and multi-row headers still need reshaping. Very large workbooks are slow — qsv excel is the fast path.

EscalateWhen the sheet is a human-formatted report rather than a table (title rows, merged headers, stacked sub-tables), identifying the header row is genuine judgment: dump deterministically first, then let a model name the header row and the sub-table boundaries.

Caveats.import types every column as TEXT unless you create the table first — declare the schema when numeric comparison matters. csvkit's csvsql --db infers types at a large speed cost.

EscalateNever.

CaveatsNeeds a reasonably modern SQLite (3.33+) for the -json flag; check BLOB and NULL handling before shipping the output anywhere.

EscalateNever.

CaveatsRequires a libheif-enabled build (check magick -list format | grep -i heic); slower and hungrier than libvips on large batches.

EscalateNever.

CaveatsFewer effects and filters than ImageMagick; heavy compositing or annotation work still belongs in ImageMagick, at its cost.

EscalateNever for the resize. Picking crop focal points across a large library is the one adjacent task where a model (saliency detection) earns its keep.

CaveatsStatic SVG only — no scripting, no remote resource fetching, and web fonts must be installed locally. rsvg-convert (librsvg) is the distro-packaged alternative.

EscalateNever.

CaveatsWants clean, high-contrast, deskewed input; handwriting, stylized type and text over busy imagery are outside its range. When it fails it produces visible garbage, which is a useful property.

EscalateHandwriting, dense multi-column layouts, or text embedded in imagery — a vision model reads those. Also whenever the target is semantic ("what is the total on this receipt") rather than the characters themselves.

CaveatsCRF values are codec-relative — don't reuse an x264 number for x265 or AV1. Hardware encoders are much faster and meaningfully worse per bit.

EscalateNever. Encoding is math; the only judgment is your quality/size target, which is a knob you set once.

CaveatsStream copy needs a container that accepts the codec (AAC to .m4a, not .wav); multi-track sources need an explicit -map.

EscalateNever.

CaveatsSingle-pass loudnorm is approximate; use the two-pass measure-then-apply form when you actually care about hitting a LUFS target.

EscalateNever.

CaveatsNo speaker diarization out of the box; accuracy drops with accents, crosstalk and domain jargon, and it can emit invented text over long silences. Bigger models are considerably better and considerably slower. faster-whisper is the Python/GPU alternative.

EscalateAlready model-tier. Go further only for diarization, or for a cleanup pass on punctuation and domain terminology — and always keep the raw transcript alongside the cleaned one.

CaveatsWriting tags rewrites files — keep the _original backups, or pass -overwrite_original deliberately. Tag namespaces are numerous and vendor-specific.

EscalateNever for reading. A model is only relevant for deriving metadata that isn't there — captions, subjects, scene descriptions — which is a different job with different accuracy expectations.

CaveatsEncoding detection is a guess, not a fact — verify on a sample containing known-odd characters. //TRANSLIT silently degrades anything unmappable.

EscalateNever for the conversion; a model is at most a tie-breaker when detection is ambiguous and you have a sample of known-correct text to compare against.