metedata/pdf-proof/pdf-proof

PDF Proof Page Generator

What This Skill Does

When a user needs to verify that specific values match their source PDF documents, this skill:

1. Searches the PDF(s) for the exact text of each value
2. Crops a tight, readable section around each match
3. Draws a translucent orange highlight over the found value (using exact text coordinates, not guesswork)
4. Cross-checks by reading text back from the highlighted region to confirm correctness
5. Generates a clean HTML proof page with a summary table, confidence indicators, and per-value proof cards showing the actual screenshots

The output is a standalone HTML file that references cropped PNG screenshots — a visual audit trail the user can keep, share, or refer back to.

Important: Always generate the HTML proof page in your first response. Do not just show screenshots inline or summarize values in chat — the shareable proof document is the whole point. Find, extract, and assemble the proof page in one pass.

How It Works

The key insight is using PyMuPDF's page.search_for(text) to get exact PDF-coordinate rectangles for each value, then using those coordinates to draw highlights at mathematically precise positions. This avoids the problem of CSS-percentage-based overlays that never quite land in the right spot.

Step-by-Step Process

1. Identify what needs to be proven

From the user's request, extract:

• Values to verify: The specific numbers, amounts, or text the user wants confirmed
• Source PDFs: Which PDF documents contain the source data
• Context for each value: What form/line/field the value comes from (e.g., "Form 1040, line 15", "Invoice #4521, total amount", "Section 3.2, indemnification cap")

2. Search and locate values in the PDFs

Use the bundled scripts/extract_proof.py script. It handles the PyMuPDF text search, cropping, and highlight drawing.

Step A — Find first. PDFs often contain the same value in multiple places — a form field and its instructions, a header and a total row, or a cross-reference on another page. Jumping straight to extract risks highlighting the wrong occurrence and producing a misleading proof. Run a find first to see all matches:

python3 /path/to/skill/scripts/extract_proof.py \
  --pdf "/path/to/source.pdf" \
  --search "3,000" \
  --page 39 \
  --mode find

Review the output — if there are multiple matches, note which index corresponds to the actual value vs. mentions in labels, headers, or instructions.

Step B — Extract with verification:

# Single highlight (typical for numbers):
python3 /path/to/skill/scripts/extract_proof.py \
  --pdf "/path/to/source.pdf" \
  --search "1,250.00" \
  --page 5 \
  --output "/path/to/output/proof_total.png" \
  --highlight value \
  --mode verify \
  --json
 
# Multiple highlights (for policy/text questions):
python3 /path/to/skill/scripts/extract_proof.py \
  --pdf "/path/to/source.pdf" \
  --search "Pets are allowed" "$25 per month" "written permission" \
  --page 3 \
  --output "/path/to/output/proof_pet_policy.png" \
  --highlight value \
  --mode verify \
  --json --context 120

Parameters:

• --pdf: Path to the source PDF
• --search: One or more text strings to find and highlight (multiple terms = multiple highlights on the same screenshot)
• --page: 1-indexed page number to search on (if known; omit to search all pages)
• --context: How many PDF points of vertical context to include above and below the found text (default: 80). Increase for more surrounding context.
• --output: Where to save the cropped PNG
• --highlight: Highlight mode — value (tight box around the text), row (full-width band at the text's vertical position), or none
• --scale: Render scale factor (default: 3 for high-res)
• --mode: find (locate text), extract (crop+highlight), or verify (extract + read text back to cross-check)
• --prefer: When multiple matches exist — right (rightmost, best for forms), first, or last (default: right)
• --match-index: Use the Nth match (0-indexed), overrides --prefer
• --json: Output structured JSON with confidence and verification results

If you don't know the exact page number, run a search pass first:

python3 /path/to/skill/scripts/extract_proof.py \
  --pdf "/path/to/source.pdf" \
  --search "1,250.00" \
  --mode find

This prints every page and coordinate where the text appears, so you can pick the right one.

3. Interpret confidence and verification results

When using --mode verify --json, the output includes:

{
  "confidence": "high",
  "confidence_note": "Single match on page",
  "verification": {
    "readback_text": "1,250.00",
    "text_match": true,
    "status": "pass"
  }
}

Confidence levels (based on verification status, not match method):

• high / Verified: Readback verification passed — the highlighted region contains the expected text. Always use this when verification passes, regardless of OCR, multiple matches, or formatting variations.
• medium / Unverified: Verification was not run (--mode extract instead of --mode verify). The highlight is likely correct but not confirmed.
• low / Check: Verification failed — the readback text doesn't match the search text. Flag this to the user.

OCR, multiple-match auto-selection, and formatting variations are metadata — note them in the extraction details box or screenshot caption, not in the confidence badge.

If verification fails, the highlighted region may contain the wrong text. Re-run with --mode find to inspect all matches and use --match-index to select the correct one.

4. Generate the HTML proof page

The HTML proof page is the primary deliverable of this skill — always generate it. Do not stop at showing inline screenshots or summarizing values in chat. The whole point is a standalone, shareable proof document. Generate the HTML proof page in your first response, not as an afterthought.

After creating all the cropped screenshots, generate an HTML file. Read the template from assets/proof_template.html and populate it. The template expects a JSON data structure — see the template comments for the schema.

Include confidence indicators in the proof page based on verification status:

• Verification passed → green badge "Verified" (confidence-high)
• Verification skipped → yellow badge "Unverified" (confidence-medium)
• Verification failed → red badge "Check" (confidence-low)

OCR, multiple matches, and formatting variations are metadata — note them in the extraction details or screenshot caption, NOT in the confidence badge. If readback verification passed, the badge is always "Verified" regardless of how the match was found.

Read assets/proof_template.html for the exact CSS classes and schema. The template comments document the JSON data structure. Here are the key structural rules:

One proof card per question, not per value. Structure cards around what the user asked, not around what was searched. A numeric question ("what's the rent?") → one card, one highlight. A policy question ("what does it say about pets?") → one card with a synthesized answer and multiple highlights.

Header highlights are mandatory. Every proof card header must surface the answer: <h3>Field: <span class="highlight">Answer</span></h3>. For numbers, show the number. For text, show a short answer ("Allowed with permission, +$25/mo"). The user should get every answer from the headers alone without reading screenshots.

Multiple highlights per screenshot. The script accepts multiple search terms (--search "term1" "term2") and draws all of them on one screenshot. Use this when a question's answer spans multiple phrases.

Page metadata is plain text, not a badge. The page number uses <span class="badge"> which renders as subtle metadata text, not a label.

Verification is collapsible. Use <details class="verification"> with <summary>Extraction details</summary>. This is debug info, not primary content.

Screenshot captions are omitted by default — the proof header and description provide sufficient context.

5. Save outputs

Always create a dedicated subfolder for proof outputs — never drop PNGs into the user's main workspace. This keeps the workspace clean and groups related proof files together.

• Create a subfolder named after what's being verified, e.g., proof-capital-loss-carryover/, proof-invoice-4521/, proof-contract-terms/
• Save the HTML file and all PNG screenshots inside this subfolder
• Use relative paths in the HTML <img src=""> tags (just the filename, no path prefix) so the page works when opened locally
• Share the link to the HTML file inside the subfolder

workspace/
  proof-capital-loss-carryover/
    proof.html
    proof_1040_line15.png
    proof_schedD_line7.png
    proof_schedD_line15.png
    proof_schedD_line21.png

Important Technical Notes

PyMuPDF installation

pip install pymupdf --break-system-packages -q

Text search precision

page.search_for() returns fitz.Rect objects with exact (x0, y0, x1, y1) coordinates in PDF points. These are the source of truth for highlight positioning. CSS-percentage overlays and manual pixel guesses produce highlights that land in the wrong spot because PDF coordinate systems don't map cleanly to rendered pixel grids — this was the original failure mode that led to building the script.

Multiple matches on the same page

A value like "3,000" might appear multiple times on a page — once as the actual form field value, and again in nearby instruction text or labels. When the script finds multiple matches, it prints a warning showing all matches with their coordinates and index numbers.

Run --mode find first whenever you're unsure a value is unique on the page. This avoids the most common failure: highlighting a mention of the value in nearby instruction text (e.g., "enter the amount from line 21, up to $3,000") instead of the actual form field. Review the match coordinates, identify which one is the real value, and use --match-index N to select it explicitly.

The script defaults to --prefer right which picks the rightmost match. This heuristic exists because structured forms (tax returns, invoices, applications) place values in right-hand columns while labels and instructions sit on the left. For non-form documents like contracts or reports where values appear inline in paragraphs, switch to --prefer first or pick manually with --match-index.

Use verify mode for final extractions

The whole point of a proof page is trust — the user needs to know the highlighted value is actually the right one. --mode verify reads the text back from the highlighted region and confirms it matches what was searched for. Without this step, a wrong-match highlight looks correct in the screenshot but proves the wrong thing. If verification fails, the highlighted region contains different text than expected — re-run with --mode find and pick the right match.

Handling text not found

If a value isn't found via search_for():

• Try variations: with/without commas, with/without decimal points, with/without dollar signs, with/without parentheses for negative values
• Try nearby pages (off-by-one is common with PDF page indexing)
• As a fallback, search the full page text with page.get_text() and use regex to confirm the value exists, then use a broader crop without a precise highlight

Negative values in financial documents

Financial PDFs often format negatives as (3,000.) or -3,000 or 3,000-. Try multiple format variations when searching. The script automatically tries several common variations.