Photo → Scanned PDF

Two related pipelines, same destination look, different starting point: phone photos of paper documents, or a digital document that needs a synthetic signature before it looks signed. The pipelines that work, and the failure modes that ship wrong PDFs if skipped.

Which one do you need?

photos ──► rectify (photo_to_scan.py --raw)
       ──► ORDER BY CONTENT, detect colored paper   ← agent eyes, not filenames
       ──► enhance: noteshrink (white batch with -g │ colored pages separately,
                                after white-balance pre-pass)
       ──► assemble_pdf.py → A4 PDF
       ──► make_contact_sheet.py → READ IT, verify EVERY page   ← mandatory

Division of labor: scripts carry execution; you (the agent) carry the two judgment steps — content-based page ordering, and whole-document verification. Neither can be automated away: filenames lie about order, and per-page spot checks miss wrong-slot bugs. The digital-signature branch shares this same philosophy with its own two judgment calls — see the reference file.

Step 0 — Dependencies

which pdftoppm || brew install poppler   # contact sheet + any PDF rendering
uvx noteshrink --help | head -3          # first run builds it (~30 s)

Scripts are uv run single-file scripts (PEP 723); OpenCV/PIL/img2pdf resolve automatically on first run.

Step 1 — Rectify

uv run <skill>/scripts/photo_to_scan.py --raw --out-dir work --prefix page \
    photo1.jpg photo2.jpg ...

Expected: one page_NN.jpg per photo, each tagged [quad]. A [FULLFRAME-fallback] tag means the paper outline wasn't found (busy background, page cut off) — view that photo and decide: retake, or accept the uncropped frame.

The script handles EXIF rotation internally (cv2.imread ignores EXIF; phone photos come rotated — this silently produces sideways pages if you rectify with raw OpenCV).

Step 2 — Order by content, detect colored paper (agent judgment)

Read every rectified image (batch of ~6 per message) and record two things:

1. Its identity — date, title, page number, whatever distinguishes pages. Batch-exported photos (WeChat, AirDrop) get timestamps of the export moment, often all within one second — filename order is meaningless. Real case: 17 photos turned out to be in exact reverse document order; only content reading caught it.
2. Its paper color — white, or colored (blue/yellow/pink stock)? Colored pages take a different path in Step 3. If unsure, sample programmatically: mean RGB of a blank region; B > R + 25 ⇒ blue-ish paper.

Build the final page order as an explicit list before proceeding. If pages are supposed to match an external register (an invoice list, a session table), cross-check identity against it now — missing/duplicate pages found here cost seconds; found after delivery they cost a redo.

Step 3 — Enhance (noteshrink, split by paper color)

White-paper pages — one batch, global palette:

uvx noteshrink -w -g -K -q -b ns -c "true" page_03.jpg page_01.jpg page_07.jpg ...
# inputs IN FINAL PAGE ORDER → outputs ns0000.png, ns0001.png, ... in that order

• -w white background, -g one global palette (uniform ink/stamp color across pages), -K keep given order, -c "true" skips its internal PDF step (we assemble ourselves).
• Pass filenames explicitly. zsh does not word-split $VAR — a file list in a variable arrives as one giant "filename", noteshrink exits without output, and -q keeps it silent. Verify outputs exist (ls ns0*.png) rather than trusting stdout.

Colored-paper pages — separate, with white-balance pre-pass:

uv run <skill>/scripts/photo_to_scan.py --out-dir work --prefix wb colored_photo.jpg   # no --raw
uvx noteshrink -w -g -K -q -b nc -c "true" work/wb_01.jpg

Two distinct failure modes force this split (both shipped as bugs before the rule existed):

1. Colored pages inside the -g batch poison the whole document — the paper color enters the global palette and white pages come out with tinted shadows/artifacts.
2. noteshrink alone on colored paper whitens the background but not the foreground cast — black ink photographed on blue stock reads blue-purple, a red stamp reads maroon. The default (non---raw) mode of photo_to_scan.py divides out the paper color first, so ink returns to black and stamps to red.

Step 4 — Assemble

uv run <skill>/scripts/assemble_pdf.py --out scanned.pdf \
    ns0000.png ns0001.png nc0000.png ns0002.png ...   # FINAL page order

Expected: OK scanned.pdf (N pages, ~0.05 MB/page). Edge crop (default 24px top / 12px sides at 200 dpi) removes the sliver of desk surface that rectification drags in along page borders; document margins dwarf it.

Step 5 — Verify the WHOLE document (mandatory, not optional)

uv run <skill>/scripts/make_contact_sheet.py scanned.pdf --out contact.png

Read contact.png and check every page: identity sequence complete and correct (each date/title where it should be, no duplicates, none missing), no off-color page, stamps/signatures present. Then spot-read 1–2 pages at full resolution for text sharpness.

Why whole-document, every time: two shipped-bug stories from the session this skill was distilled from —

• A page-replacement task wrote the new page into the wrong slot (an off-by-one in a copy command), silently overwriting a neighboring page. The per-page check of the replaced slots passed; the clobbered neighbor was only caught by the user.
• A palette-poisoning bug (Step 3 #1) tinted pages that were not being edited. Checking only the edited pages missed it.

The cost asymmetry is absolute: contact sheet = one Read; a wrong page in a delivered PDF = redo + lost trust. "I verified the pages I changed" is not verification.

Replacing pages in an existing scanned PDF

Keep the per-page enhanced PNGs (ns*/nc*) as the working set. To replace page k: process the new photo through Steps 1–3, overwrite that page's PNG, re-run Steps 4–5. When copying into numbered slots, mind the mapping — slot numbers shift when photo order was reversed; derive the slot from the page's content identity, never from its position in the photo batch. Then the Step 5 full check is what actually protects you.

Troubleshooting