@cteno/sdk-linux-x64 0.0.0-stage → 2.10.13

package/skills/pdf/references/design-tokens.md

@@ -0,0 +1,381 @@
+# Design System
+
+Design guidance for PDFs you create (HTML/CSS or reportlab). It answers "what should it look like and why".
+
+> Adapted from MiniMax's minimax-pdf design system (MIT). Mentions of `tokens`, cover patterns and block types describe design decisions; implement them in your HTML/CSS or reportlab code — the original generator scripts are not shipped.
+
+---
+
+## The one rule
+
+Every design decision must be **rooted in the document's content and purpose**.
+Dark teal + cream is not "professional". Serif + beige is not "elegant".
+A color chosen because it fits the content will always outperform a color chosen
+because it seems safe.
+
+---
+
+## Palette logic
+
+Derive the palette from a short description of the content:
+
+### Mood → base palette
+
+| Content signal | Mood | Background | Accent | Text |
+|---|---|---|---|---|
+| Research, science, analysis | Authoritative | `#0F1F2E` deep ink | `#00B4A6` teal | `#F0EDE6` warm white |
+| Business, strategy, finance | Confident | `#1C1C2B` near-black | `#E8A020` amber | `#F5F2EC` cream |
+| Creative, portfolio, design | Expressive | `#1A0A2E` deep violet | `#FF6B6B` coral | `#FAF5FF` lavender white |
+| Education, academic paper | Scholarly | `#FAFAF7` warm white | `#2C4A7C` navy | `#1A1A2E` dark |
+| Healthcare, wellness | Calm | `#F5F9F8` pale mint | `#2D8B72` forest | `#1E3830` deep green |
+| Resume / personal | Clean | `#FFFFFF` white | pick from content | `#111111` near-black |
+| General / unknown | Neutral | `#F8F6F1` warm off-white | `#3D3D3D` dark gray | `#1A1A1A` black |
+| Formal publications, annual reports | Magazine | `#F2F0EC` warm linen | `#1C3557` deep navy | `#0D1A2B` near-black |
+| Premium/dark reports, tech reviews | Darkroom | `#151C27` deep navy | `#4A6FA5` steel blue | `#F0EDE6` warm white |
+| Technical docs, developer reports | Terminal | `#0D1117` near-black | `#39D353` neon green | `#E6EDF3` cool white |
+| Portfolios, creative, photography | Poster | `#FFFFFF` white | `#0A0A0A` near-black | `#0A0A0A` near-black |
+
+### Accent selection rules
+
+- **One accent color only.** Using two accents splits visual energy.
+- Accent appears on: cover geometric elements, section rules, callout left borders,
+  table header background, page header rule. Nowhere else.
+- Accent must contrast with the cover background by at least 4.5:1 (WCAG AA).
+- Do not default to blue. Blue is the most overused accent in AI-generated documents.
+
+### Color pairing anti-patterns (never use these)
+
+| ❌ Avoid | Why |
+|---|---|
+| Purple gradient on white | The default AI aesthetic — immediately signals "generated" |
+| Navy + gold | Overused corporate cliché |
+| All-black background | Prints badly, feels aggressive |
+| More than 3 colors in the system | Visual noise |
+| Accent on body text | Destroys readability |
+
+---
+
+## Typography system
+
+### Font pairing logic
+
+Two typefaces maximum. Always.
+
+| Role | Criteria | Good choices (system-safe) |
+|---|---|---|
+| Display (cover title, H1) | Distinctive, strong contrast, high weight | Times New Roman, Georgia (serif) |
+| Text (body, captions, UI) | Highly readable at 10–11pt | Helvetica, Arial (sans) |
+
+Cover fonts are loaded live via `@import url(...)` in the cover HTML — Playwright
+fetches them at render time, no local caching. Body pages always use system fonts
+(Times-Bold / Helvetica) via ReportLab — consistent and offline-safe.
+
+Pairs by mood (cover HTML only — body always uses system fonts):
+- Authoritative: `Playfair Display` / `IBM Plex Sans`
+- Confident: `Syne` / `Nunito Sans`
+- Expressive: `Fraunces` / `Inter`
+- Scholarly: `EB Garamond` / `Source Sans 3`
+- Clean: `DM Serif Display` / `DM Sans`
+- Restrained: `Cormorant Garamond` / `Jost`
+- Bold: `Barlow Condensed` / `Barlow`
+- Dynamic: `Montserrat` / `Montserrat`
+- Classical: `Cormorant` / `Crimson Pro`
+- Editorial: `Bebas Neue` / `Libre Franklin`
+- Body fallback (always): `Times-Bold` / `Helvetica` (ReportLab system fonts)
+
+### Type scale
+
+All sizes in points. Use this scale for headings and body.
+
+| Token | Size | Leading | Usage |
+|---|---|---|---|
+| `display` | 54pt | 1.0 | Cover title |
+| `h1` | 22pt | 1.3 | Section headings |
+| `h2` | 15pt | 1.4 | Subsection headings |
+| `h3` | 11.5pt | 1.5 | Sub-subsection |
+| `body` | 10.5pt | 1.6 | Main prose |
+| `caption` | 8.5pt | 1.4 | Figure/table captions |
+| `meta` | 8pt | 1.3 | Header/footer text |
+
+### Spacing system
+
+Margins and rhythm are what separate "looks designed" from "looks printed".
+
+| Token | Value | Notes |
+|---|---|---|
+| `margin_outer` | 2.8cm | Left/right page margin |
+| `margin_top` | 2.8cm | Top page margin |
+| `margin_bottom` | 2.5cm | Bottom page margin |
+| `section_gap` | 26pt | Space before H1 |
+| `para_gap` | 8pt | Space after paragraph |
+| `line_gap` | 17pt | Leading for body text |
+
+Never use ReportLab's default margins (too tight). Always set explicitly.
+
+---
+
+## Cover design
+
+The cover is the most important page. It determines whether a reader trusts the document.
+
+### Thirteen cover patterns
+
+Pick one cover pattern that fits the content.
+
+**1. `fullbleed`** — used for: `report`, `general`
+- Deep background fills 100% of page
+- Title: large, left-aligned, upper 60% of page
+- Accent: thin horizontal rule + top-right corner strip
+- Dot-grid background texture (subtle, 8–10% opacity)
+- Footer band: author + date metadata
+- Fonts: Playfair Display / IBM Plex Sans
+
+**2. `split`** — used for: `proposal`
+- Left 42% panel: solid cover color, title + author
+- Right 58%: off-white, dot-grid decoration
+- Hard vertical dividing line in accent color
+- No gradients — pure flat geometry
+- Fonts: Syne / Nunito Sans
+
+**3. `typographic`** — used for: `resume`, `academic`
+- White/off-white background
+- Name or title as oversized display type (60–80pt), left-aligned
+- First word in accent color, remainder in dark
+- Thin rule below title block
+- Fonts: DM Serif Display / DM Sans (resume) · EB Garamond / Source Sans 3 (academic)
+
+**4. `atmospheric`** — used for: `portfolio`
+- Near-black background
+- Soft radial glow in accent color (upper-right quadrant)
+- Title centered-left, 2 lines max
+- Short rule in accent below title
+- Dot-grid texture at low opacity
+- Fonts: Fraunces / Inter
+
+**5. `minimal`** — used for: `minimal`
+- Near-white background, 8px left accent bar is the only color
+- Title in very large, light-weight display type (300 weight)
+- Hairline rule, author + date as single muted line
+- Nothing else — the bar does all the visual work
+- Fonts: Cormorant Garamond / Jost
+
+**6. `stripe`** — used for: `stripe`
+- Page cut into three horizontal bands: accent / dark / light
+- Top band: category label; middle: oversized title in white; bottom: metadata
+- Hard edges, no gradients, no textures — newspaper / brand poster aesthetic
+- Fonts: Barlow Condensed / Barlow
+
+**7. `diagonal`** — used for: `diagonal`
+- SVG polygon cuts page diagonally: dark upper-left, light lower-right
+- Accent-colored edge line traces the diagonal cut
+- Title on dark area, metadata on light area
+- Fonts: Montserrat / Montserrat
+
+**8. `frame`** — used for: `frame`
+- White/cream background with an inset rectangular border (1.2px, 28px from edges)
+- Accent strips inside top + bottom of frame; small accent corner squares
+- Title centered in the frame space, centered alignment, classical weight
+- Formal, timeless — annual reports, legal documents, academic papers
+- Fonts: Cormorant / Crimson Pro
+
+**9. `editorial`** — used for: `editorial`
+- Ghost first-letter of title fills upper-right at 5% opacity — visual texture
+- 5px accent top bar; full-width uppercase title in condensed weight
+- Title all-caps, very large (80px), flush-left
+- Footer rule + author/date metadata
+- Fonts: Bebas Neue / Libre Franklin
+
+**10. `magazine`** — used for: `magazine`
+- Warm cream/linen background; fully centered, vertical stack layout
+- Org/company name in small spaced caps + 2px accent rule beneath (top anchor)
+- Large bold serif title (52px) centered; short accent rule under title
+- Italic subtitle; optional `cover_image` URL renders as centered hero thumbnail
+- Optional `abstract` field: justified text block with bold "Abstract:" label
+- Author name in accent color (large, bold); date beneath
+- Fonts: Playfair Display / EB Garamond
+
+**11. `darkroom`** — used for: `darkroom`
+- Same centered stack layout as `magazine` but deep navy background, white text
+- Org name + rules in semi-transparent white; accent rules desaturated
+- Hero image (if provided) gets `grayscale(20%) brightness(0.9)` filter
+- Fonts: Playfair Display / EB Garamond
+
+**12. `terminal`** — used for: `terminal`
+- Near-black background; neon green accent; Space Mono monospace throughout
+- Grid overlay: faint horizontal + vertical lines at 48px intervals (7% opacity)
+- Status label top-left: green dot + `SYSTEM_REPORT // <date>`
+- Title inside a bracket frame (border-left + border-top + pseudo-element corner)
+- Subtitle prefixed with `>` in accent color
+- Abstract text left; author block right; status bar at bottom (UTF-8 / Ln 1)
+- Fonts: Space Mono / Space Mono
+
+**13. `poster`** — used for: `poster`
+- White background; thick 52px left sidebar in accent (typically near-black)
+- Title: 96px, 900-weight, all-caps, condensed — the dominant visual element
+- Subtitle in typewriter font below title; thin 2px rule as separator
+- Author + meta in Courier Prime monospace beneath rule
+- Optional `cover_image` rendered as 260×340 grayscale thumbnail, right-aligned
+- Accent square icon block (lower-right) with white horizontal lines
+- Fonts: Barlow Condensed / Courier Prime
+
+### Optional token: `cover_image`
+
+Patterns `magazine`, `darkroom`, and `poster` accept an optional `cover_image`
+token containing an absolute URL or `file://` path to an image.
+The image renders via `<img src="...">` — Playwright fetches it at render time.
+If omitted, the image area is simply skipped (layout adjusts gracefully).
+
+### Cover CSS requirements (critical for Playwright rendering)
+
+These three rules must appear in every cover HTML file or the output will have
+white borders / incorrect dimensions:
+
+```css
+body { margin: 0; padding: 0; }
+html, body { width: 794px; height: 1123px; overflow: hidden; }
+```
+
+No `@page` rules needed — Playwright handles page size via the `pdf()` call.
+Do NOT use CSS `background-image` for textures — use inline SVG or `<canvas>`.
+Always use `position: absolute` + `z-index` for layered elements.
+
+### What always kills a cover
+
+- Centered title on white background with a thin horizontal line underneath
+- Gradient from one color to another (reads as PowerPoint, not print design)
+- Drop shadows on text
+- More than one accent color
+- Emoji or icon fonts (fail silently on headless Chromium)
+
+---
+
+## Inner page rules
+
+### What "restraint" means in practice
+
+Every design decision should remove something, not add something.
+The page is done when there is nothing left to remove.
+
+- Accent color appears on section rules only — not on headings, not on bullets
+- No card components (bordered boxes with colored headers)
+- No rounded corners on anything except callout boxes (4px max)
+- No shadows anywhere
+- Tables: header row in accent, alternating row tint, no grid lines except outer box
+- Callout boxes: left border in accent (4px), very light tint background, no icon
+
+### Page header / footer
+
+Header: document title (left, 7.5pt, muted) + accent rule (1.5pt, full width below)
+Footer: author name (left, 7.5pt, muted) + page number (right, 7.5pt, muted) + light rule above
+
+---
+
+## Quality bar
+
+A PDF passes if a designer would not be embarrassed to hand it to a client.
+Concretely:
+
+- Cover has a clear visual identity that is not "generic AI output"
+- Body text is readable at arm's length without squinting
+- Every page looks like it belongs to the same document
+- No element bleeds off the edge or overlaps another
+- Page numbers are present and correct
+- The accent color appears fewer than 8 times per page on average
+
+---
+
+## Block type reference
+
+All body blocks use the same token system — colors and fonts come from the chosen palette, never ad-hoc.
+
+| Block | Rendering | Design notes |
+|---|---|---|
+| `h1` | 22pt heading + full-width accent rule below | KeepTogether with rule — heading never orphaned |
+| `h2` | 15pt heading, dark text | No rule, no accent — visual hierarchy through size only |
+| `h3` | 11.5pt bold, dark text | **No accent color** — accent on body headings violates the one-accent-location rule |
+| `body` | 10.5pt justified, 17pt leading | Supports `<b>` `<i>` `<font>` markup |
+| `bullet` | Body size with `•` prefix, 14pt indent | Use for unordered lists |
+| `numbered` | Body size with `N.` prefix, hanging indent | Counter auto-resets on any non-numbered block — no manual numbering needed |
+| `callout` | Accent left-border (4px) + light tint background | Max one callout per section — overuse kills impact |
+| `table` | Accent header row, alternating row tint, outer box only | Supports `col_widths` (fractions, e.g. `[0.3, 0.5, 0.2]`) for custom column widths |
+| `image` | Scaled to column width, preserving aspect ratio | Use `path` or `src`; always provide a `caption` |
+| `figure` | Same as image, but caption auto-prefixed "Figure N:" | Figure counter increments across all `figure`, `chart`, `flowchart` blocks |
+| `code` | Courier 8.5pt, accent left-border, light tint background | Supports optional `language` label (rendered above block) |
+| `math` | Formula centered, optional right-aligned equation label | LaTeX syntax; matplotlib mathtext renderer |
+| `chart` | Bar / line / pie chart rendered via matplotlib | Color palette derived from document accent; figure auto-numbered |
+| `flowchart` | Process diagram with labeled arrows | Supports 4 node shapes; back-edges drawn as curved arcs |
+| `bibliography` | Numbered reference list with hanging indent | Heading rendered as h2 + accent rule; items as `[N] text` |
+| `divider` | Accent-colored 1.2pt rule with padding | Use sparingly — only for major thematic breaks |
+| `caption` | 8.5pt muted text, centered | Appears below images/tables via field or explicit block |
+| `pagebreak` | Force page break | — |
+| `spacer` | Vertical whitespace | `pt` field (default 12) |
+
+### Math formula guidance
+
+**Input syntax:** standard LaTeX math notation — `\frac{}{}`, `\int`, `\sum`, `\alpha`, `^`, `_`, etc.
+**Rendering engine:** matplotlib mathtext — pure Python, no LaTeX compiler, no browser required.
+
+| Syntax example | Rendered as |
+|---|---|
+| `E = mc^2` | Inline expression |
+| `\frac{\sqrt{\pi}}{2}` | Fraction |
+| `\int_0^\infty e^{-x^2} dx` | Integral |
+| `\sum_{i=1}^{n} x_i` | Summation |
+| `\alpha + \beta = \gamma` | Greek letters |
+
+**Limitations:** matplotlib mathtext covers most common expressions but not advanced LaTeX environments (`align`, `cases`, `matrix`). Split complex multi-line proofs into multiple `math` blocks.
+
+**Fallback:** if matplotlib is not installed, renders as `expression` in code style.
+
+**Equation labels:** `"label": "(1)"` — rendered right-aligned beside the formula.
+
+### Chart guidance
+
+**Rendered entirely in Python** — no external chart services, image files, or internet required.
+
+| chart_type | Use case | Required fields |
+|---|---|---|
+| `bar` | Comparing discrete categories | `labels`, `datasets` |
+| `line` | Trends over time or ordered categories | `labels`, `datasets` |
+| `pie` | Part-to-whole composition | `labels`, `datasets[0].values` |
+
+- Colors are derived from the document accent for visual consistency — do not set custom colors.
+- Multi-series: add multiple objects to `datasets`, each with a `label` and `values` array.
+- Figure auto-numbering: set `"figure": true` (default) or `"figure": false` to suppress.
+
+### Flowchart guidance
+
+**Node shapes:**
+
+| shape | Use for |
+|---|---|
+| `rect` (default) | Process step |
+| `diamond` | Decision / condition |
+| `oval` or `terminal` | Start / End |
+| `parallelogram` | Input / Output |
+
+- Nodes are placed in input order (top to bottom). This controls the layout.
+- Forward edges draw straight arrows; back-edges (to earlier nodes) draw curved arcs.
+- Keep labels short (3–5 words max) — the diagram is A4-column-width at 78% scale.
+- Figure auto-numbering applies same as chart.
+
+### Bibliography guidance
+
+- `id` field is the reference label — use numbers ("1", "2") or alphanumeric ("Smith23").
+- Text should be in a consistent citation style (APA, Chicago, etc.) — the renderer does not enforce style.
+- The `title` field defaults to "References". Set `"title": ""` to suppress the heading.
+- A `bibliography` block always starts with a new section heading + accent rule.
+
+### Image / figure guidance
+
+- Preferred formats: PNG, JPEG
+- Scaled down if wider than the text column; never scaled up
+- `figure` blocks auto-number; `image` blocks do not — use `figure` for numbered figures
+- If the file does not exist at render time, a `[Image not found]` placeholder is substituted
+
+### Code block guidance
+
+- Preserves whitespace exactly — do not indent code in the JSON value
+- Optional `language` field renders a small language label above the block (e.g., `"language": "python"`)
+- No syntax highlighting (by design) — consistent with restraint principle
+- Keep lines under ~90 characters for A4 column width

package/skills/pdf/references/forms.md

@@ -0,0 +1,99 @@
+# Building Fillable Forms: spec format and workflow
+
+The same JSON spec drives both `pdf_form_layout.py` (design lint) and
+`pdf_make_form.py` (AcroForm build). Coordinates are PDF points, origin
+at the bottom-left of the page (1 pt = 1/72 inch; A4 is 595.27 x 841.89,
+letter is 612 x 792).
+
+## Spec shape
+
+```json
+{
+  "title": "Example Intake Form",
+  "author": "example-author",
+  "page_size": "A4",
+  "page_count": 1,
+  "fields": [
+    {"name": "surname", "type": "text", "page": 1,
+     "label": "Surname", "label_box": [72, 700, 150, 714],
+     "entry_box": [160, 696, 400, 716],
+     "value": "", "tooltip": "Family name"},
+
+    {"name": "agree", "type": "checkbox", "page": 1,
+     "label": "I agree", "label_box": [72, 660, 150, 674],
+     "entry_box": [160, 658, 176, 674], "checked": false},
+
+    {"name": "color", "type": "radio", "page": 1,
+     "label": "Color", "label_box": [72, 620, 150, 634],
+     "entry_box": [160, 616, 400, 636],
+     "options": ["red", "blue"], "value": "blue"},
+
+    {"name": "size", "type": "dropdown", "page": 1,
+     "label": "Size", "label_box": [72, 580, 150, 594],
+     "entry_box": [160, 576, 300, 596],
+     "options": ["small", "large"], "value": "small"}
+  ]
+}
+```
+
+- `page_size`: `"A4"`, `"letter"`, or `[width, height]` in points.
+- `page_count`: optional; extended automatically to the highest field page.
+- Boxes are `[x0, y0, x1, y1]` with `x0 < x1`, `y0 < y1`.
+- `label` is drawn as static text near `label_box`; omit it (and
+  `label_box`) for unlabeled fields.
+- `radio`: the buttons are laid out left-to-right inside `entry_box`,
+  one slot per option, each with a small static caption. `value`
+  pre-selects an option by its export name.
+- `dropdown` maps to an AcroForm choice (combo) field.
+
+## Field types → what pdf_read.py --fields reports
+
+| Spec type | /FT | value format after fill |
+|---|---|---|
+| text | /Tx (`text`) | the string |
+| checkbox | /Btn (`button`) | `/Yes` or `/Off` |
+| radio | /Btn (`button`) | `/<export>`, e.g. `/red` |
+| dropdown | /Ch (`choice`) | the option string |
+
+When filling with `pdf_fill_form.py`, checkboxes accept `true`/`false`;
+radio values need the leading slash (`"/red"`); dropdown values are the
+plain option string.
+
+## Layout lint rules (pdf_form_layout.py)
+
+Per field, on its declared page:
+
+- boxes must be well-formed and inside the page bounds;
+- entry boxes must be at least 8x8 pt (12 pt tall for text/dropdown);
+- no two entry boxes on the same page may overlap (the second and later
+  fields of an overlapping cluster are flagged);
+- a label must sit within 150 pt of its entry box and must not overlap it.
+
+Exit code 0 = clean, 1 = at least one problem; the JSON report lists
+per-field `problems`. Lint the spec BEFORE building — fixing numbers in
+JSON is cheaper than debugging a rendered PDF.
+
+## Visual review loop
+
+```bash
+python3 scripts/pdf_form_layout.py spec.json --render-overlay overlay.png [--pdf built.pdf]
+```
+
+Red rectangles = entry boxes (with field names), blue = label boxes.
+Without `--pdf` the overlay is drawn on a blank page (PIL-only, always
+works); with `--pdf` the real page is rasterized underneath
+(needs pypdfium2 or pdftoppm — otherwise the report says
+`"rendered": false` with install hints). Feed the PNG to `vision_analyze`
+and ask specifically about collisions, alignment, and stray labels.
+
+## Radio-group quirks (reportlab + pypdf)
+
+- reportlab requires at least two `radio()` calls per group; a
+  single-option radio group produces a broken field.
+- Pre-selecting is done at build time via `"value"`; changing selection
+  later via `pdf_fill_form.py` needs the slashed export name (`"/red"`).
+- Some viewers render reportlab radio appearances inconsistently after a
+  pypdf fill; verify with `--fields` (data truth) plus a rendered page
+  image (visual truth) rather than either alone.
+- Flattening radio groups is the least reliable flatten case — check the
+  output image before shipping.

package/skills/pdf/references/nano-pdf-editing.md

@@ -0,0 +1,40 @@
+# Natural-language PDF text editing with nano-pdf (merged from the nano-pdf skill)
+# nano-pdf
+
+Edit PDFs using natural-language instructions. Point it at a page and describe what to change. For structural PDF work (merge, split, forms, watermarks, creation), see the `pdf` skill; for text extraction from scans, see `ocr-and-documents`.
+
+## Prerequisites
+
+```bash
+# Install with uv (recommended — already available in Hermes)
+uv pip install nano-pdf
+
+# Or with pip
+pip install nano-pdf
+```
+
+## Usage
+
+```bash
+nano-pdf edit <file.pdf> <page_number> "<instruction>"
+```
+
+## Examples
+
+```bash
+# Change a title on page 1
+nano-pdf edit deck.pdf 1 "Change the title to 'Q3 Results' and fix the typo in the subtitle"
+
+# Update a date on a specific page
+nano-pdf edit report.pdf 3 "Update the date from January to February 2026"
+
+# Fix content
+nano-pdf edit contract.pdf 2 "Change the client name from 'Acme Corp' to 'Acme Industries'"
+```
+
+## Notes
+
+- Page numbers may be 0-based or 1-based depending on version — if the edit hits the wrong page, retry with ±1
+- Always verify the output PDF after editing (use `read_file` to check file size, or open it)
+- The tool uses an LLM under the hood — requires an API key (check `nano-pdf --help` for config)
+- Works well for text changes; complex layout modifications may need a different approach

package/skills/pdf/references/ocr-extraction.md

@@ -0,0 +1,165 @@
+# OCR & Document Text Extraction (merged from the ocr-and-documents skill)
+
+Scripts referenced below live in this skill's scripts/ directory.
+# PDF & Document Extraction
+
+For DOCX: see the `docx` skill (create/edit) or use `python-docx` for structured reads.
+For PPTX: see the `powerpoint` skill (full create/read/edit support).
+For PDF manipulation (merge, split, forms, watermarks, creation): see the `pdf` skill.
+This skill covers **text extraction from PDFs and scanned documents**.
+
+> **Coming from a `read_file` EXTRACTION COVERAGE WARNING?** `read_file` auto-converts local PDFs but reads the text layer only; the warning footer lists the pages that yielded no text (scanned images). For a handful of pages, render + vision is fastest: `pdftoppm -jpeg -r 150 -f N -l N file.pdf $TMPDIR/page` then `vision_analyze` each image. For bulk OCR of many pages, use marker-pdf below (Step 2).
+
+## Step 1: Remote URL Available?
+
+If the document has a URL, **always try `web_extract` first**:
+
+```
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+web_extract(urls=["https://example.com/report.pdf"])
+```
+
+This handles PDF-to-markdown conversion via Firecrawl with no local dependencies.
+
+Only use local extraction when: the file is local, web_extract fails, or you need batch processing.
+
+## Step 2: Choose Local Extractor
+
+| Feature | pymupdf (~25MB) | marker-pdf (~3-5GB) |
+|---------|-----------------|---------------------|
+| **Text-based PDF** | ✅ | ✅ |
+| **Scanned PDF (OCR)** | ❌ | ✅ (90+ languages) |
+| **Tables** | ✅ (basic) | ✅ (high accuracy) |
+| **Equations / LaTeX** | ❌ | ✅ |
+| **Code blocks** | ❌ | ✅ |
+| **Forms** | ❌ | ✅ |
+| **Headers/footers removal** | ❌ | ✅ |
+| **Reading order detection** | ❌ | ✅ |
+| **Images extraction** | ✅ (embedded) | ✅ (with context) |
+| **Images → text (OCR)** | ❌ | ✅ |
+| **EPUB** | ✅ | ✅ |
+| **Markdown output** | ✅ (via pymupdf4llm) | ✅ (native, higher quality) |
+| **Install size** | ~25MB | ~3-5GB (PyTorch + models) |
+| **Speed** | Instant | ~1-14s/page (CPU), ~0.2s/page (GPU) |
+
+**Decision**: Use pymupdf unless you need OCR, equations, forms, or complex layout analysis.
+
+If the user needs marker capabilities but the system lacks ~5GB free disk:
+> "This document needs OCR/advanced extraction (marker-pdf), which requires ~5GB for PyTorch and models. Your system has [X]GB free. Options: free up space, provide a URL so I can use web_extract, or I can try pymupdf which works for text-based PDFs but not scanned documents or equations."
+
+---
+
+## pymupdf (lightweight)
+
+```bash
+pip install pymupdf pymupdf4llm
+```
+
+**Via helper script**:
+```bash
+python scripts/extract_pymupdf.py document.pdf              # Plain text
+python scripts/extract_pymupdf.py document.pdf --markdown    # Markdown
+python scripts/extract_pymupdf.py document.pdf --tables      # Tables
+python scripts/extract_pymupdf.py document.pdf --images out/ # Extract images
+python scripts/extract_pymupdf.py document.pdf --metadata    # Title, author, pages
+python scripts/extract_pymupdf.py document.pdf --pages 0-4   # Specific pages
+```
+
+**Inline**:
+```bash
+python -c "
+import pymupdf
+doc = pymupdf.open('document.pdf')
+for page in doc:
+    print(page.get_text())
+"
+```
+
+---
+
+## marker-pdf (high-quality OCR)
+
+```bash
+# Check disk space first
+python scripts/extract_marker.py --check
+
+pip install marker-pdf
+```
+
+**Via helper script**:
+```bash
+python scripts/extract_marker.py document.pdf                # Markdown
+python scripts/extract_marker.py document.pdf --json         # JSON with metadata
+python scripts/extract_marker.py document.pdf --output_dir out/  # Save images
+python scripts/extract_marker.py scanned.pdf                 # Scanned PDF (OCR)
+python scripts/extract_marker.py document.pdf --use_llm      # LLM-boosted accuracy
+```
+
+**CLI** (installed with marker-pdf):
+```bash
+marker_single document.pdf --output_dir ./output
+marker /path/to/folder --workers 4    # Batch
+```
+
+---
+
+## Arxiv Papers
+
+```
+# Abstract only (fast)
+web_extract(urls=["https://arxiv.org/abs/2402.03300"])
+
+# Full paper
+web_extract(urls=["https://arxiv.org/pdf/2402.03300"])
+
+# Search
+web_search(query="arxiv GRPO reinforcement learning 2026")
+```
+
+## Split, Merge & Search
+
+pymupdf handles these natively — use `execute_code` or inline Python:
+
+```python
+# Split: extract pages 1-5 to a new PDF
+import pymupdf
+doc = pymupdf.open("report.pdf")
+new = pymupdf.open()
+for i in range(5):
+    new.insert_pdf(doc, from_page=i, to_page=i)
+new.save("pages_1-5.pdf")
+```
+
+```python
+# Merge multiple PDFs
+import pymupdf
+result = pymupdf.open()
+for path in ["a.pdf", "b.pdf", "c.pdf"]:
+    result.insert_pdf(pymupdf.open(path))
+result.save("merged.pdf")
+```
+
+```python
+# Search for text across all pages
+import pymupdf
+doc = pymupdf.open("report.pdf")
+for i, page in enumerate(doc):
+    results = page.search_for("revenue")
+    if results:
+        print(f"Page {i+1}: {len(results)} match(es)")
+        print(page.get_text("text"))
+```
+
+No extra dependencies needed — pymupdf covers split, merge, search, and text extraction in one package.
+
+---
+
+## Notes
+
+- `web_extract` is always first choice for URLs
+- pymupdf is the safe default — instant, no models, works everywhere
+- marker-pdf is for OCR, scanned docs, equations, complex layouts — install only when needed
+- Both helper scripts accept `--help` for full usage
+- marker-pdf downloads ~2.5GB of models to `~/.cache/huggingface/` on first use
+- For Word docs: `pip install python-docx` (better than OCR — parses actual structure)
+- For PowerPoint: see the `powerpoint` skill (uses python-pptx)