# Documents Core

> Shared reference for the documents cluster: the editable-source vs rendered-artifact decision every task turns on, the format→tool matrix (DOCX/PDF/PPTX/XLSX/diagram), the ingest (OCR/NotebookLM) and publish (Mintlify/changelog) paths, and the fidelity/round-trip guardrails. USE WHEN choosing how to create, edit, extract from, or render a document — the conventions every documents spoke shares.

- Skill: `sheshiyer/documents-core` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sheshiyer/documents-core`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sheshiyer/documents-core/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Data & Analytics
- Author: Sheshiyer (https://skillmd.com/u/sheshiyer)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sheshiyer/documents-core

---


# Documents Core

Shared model for the `documents` cluster. Every spoke either keeps a file **editable** or turns
it into a **rendered artifact** — get that call right first and the tool choice follows. Keep the
matrix below consistent so no spoke contradicts another.

## 1. The defining decision: editable source vs rendered artifact

A document is processed in one of two modes, and the mode is a one-way door:

```
Editable source  ──(render)──>  Rendered artifact
  (OOXML, openpyxl,                (Playwright PDF, OCR'd text,
   .drawio XML, .md)                flattened PDF, GIF)
  round-trippable, diff-able        pixel/print fidelity, terminal — you can't edit back
```

- **Editable** — work in the native structured format (DOCX OOXML, XLSX cells+formulas, PPTX
  OOXML, `.drawio` XML, Markdown). Structure, tracked changes, and formulas survive; the file
  can be re-opened and re-edited. Default here.
- **Rendered** — produce a fixed output for delivery or print (HTML→PDF via Playwright, a
  flattened/filled PDF, OCR text from a scan, a GIF of a diagram). High fidelity, but the
  source structure is gone — treat it as terminal.

**Rule:** stay editable as long as the user might edit again; only render at the **last** step,
and state it when you do. Keep the original; write the render **alongside**, never over it.

## 2. Format → tool matrix

| Format / task | Spoke | Editable path | Rendered path |
|---|---|---|---|
| Word (DOCX) | `documents` → `docx/` | docx-js create · OOXML edit · tracked changes | export/convert to PDF |
| PDF (office) | `documents` → `pdf/` | reportlab create · pypdf merge/split · pdfplumber extract · forms fill | flatten / fill-and-flatten |
| PDF (quick NL edit) | `nano-pdf` | natural-language page ops | — |
| PowerPoint (PPTX) | `documents` → `pptx/` | html2pptx · OOXML edit · templates | thumbnail grid / images |
| Excel (XLSX) | `documents` → `xlsx/` | openpyxl + **formulas** · recalc.py | — |
| Consulting report | `documents` (ConsultingReport) | structured HTML | **Playwright PDF** (A4, TOC, headers) |
| Scanned PDF → data | `deepread-ocr` | — | OCR text + structured data **with confidence flags** |
| Corpus → notebook/podcast | `notebooklm` | sources/notebook | briefing / audio artifact |
| Docs site | `mintlify` | MDX pages + nav config | published site |
| Release notes | `changelog-generator` | Markdown changelog | — |
| draw.io diagram | `drawio-diagrams-enhanced` | `.drawio` XML | exported image |
| Mermaid → motion | `mermaid-to-gif` | `.mmd` / fenced block | **GIF** |

## 3. Ingest path (document → data)

- **OCR first, never blind.** Scanned or image-only PDFs go through `deepread-ocr`, which scores
  confidence and flags low-quality regions — surface those flags; don't pass OCR text downstream
  as if it were clean.
- **Synthesize after.** Once you have text, `notebooklm` turns a corpus into a notebook,
  briefing, or podcast. Typical chain: `deepread-ocr` → `notebooklm`.

## 4. Publish path (docs about the work)

- **`mintlify`** builds and maintains the documentation **site** (MDX pages, navigation, API refs).
- **`changelog-generator`** turns git history into user-facing release notes.
  These narrate the project; they don't process arbitrary user files — keep them distinct from the
  office-format engine.

## 5. Fidelity & conventions

- **XLSX:** always use Excel **formulas**, never hardcode computed values; run `recalc.py` after
  create/edit; deliver zero formula errors; follow input/formula/link color coding.
- **DOCX:** use the redlining (tracked-changes) workflow for review; mark only what changes,
  preserve RSIDs; verify by converting to Markdown.
- **PPTX:** web-safe fonts only; generate a thumbnail grid to visually verify before delivery.
- **PDF:** pick the library by job — pypdf (structure), pdfplumber (text/tables), reportlab
  (create); `nano-pdf` for quick NL edits; flatten only at the end.
- **Diagrams:** keep the `.drawio`/`.mmd` source in the repo; the image/GIF is the render.

## 6. Shared guardrails

- **Preserve the source**: stay in the editable format; render only at the last step and say so.
- **Render is one-way**: never overwrite the original with its rendered output.
- **No fabricated values**: formulas compute (XLSX); OCR confidence is shown, not hidden.
- **No silent flattening**: don't drop tracked changes, form fields, or layers without stating it.
- **Right tool per format**: follow the matrix above; don't reach for a generic converter when a
  format-native spoke exists.
- **Diagram-as-code**: source diagrams live as text (`.drawio` XML / Mermaid); export is derived.