normalize-id-scan-pdf

Normalize ID Scan PDF

Overview

Turn a bad ID scan PDF into a readable, portable output PDF. Prefer a deterministic transform plus autonomous validation over ad hoc manual tweaking.

Work from the bronze source file. Do not overwrite it.
If pypdf is unavailable, create a local virtualenv and install pypdf there instead of touching the system interpreter.
Run python "${CODEX_HOME:-$HOME/.codex}/skills/normalize-id-scan-pdf/scripts/fix_id_scan_pdf.py" ... against the source PDF.
Review the script output paths and geometry summary.
If the output still clips or uses the page poorly, iterate from the bronze file again. Do not keep transforming the silver or gold output.
After the PDF passes self-check, open the gold PDF locally for final human review if local browser or desktop open access is available. Prefer Chrome when it is installed and reachable.

Use:

python fix_id_scan_pdf.py "/path/to/source.pdf" --output-dir "/path/to/output"

Common options:

--page-mode portrait: keep a portrait page and rotate the content within it. This is the default and the safe choice for ID scans like the one that motivated this skill.
--margin-pt 24: reserve a fixed visual margin so the output does not ride the page edge.
--doc-type personal_id: force the gold filename document type slug.
--gold-name arthur_zakirov__personal_id.pdf: override the inferred gold filename when you already know the canonical delivery name.

The script must be treated as a first-pass fixer plus a geometry validator.

Measure the visible content box from embedded images and text origins.
Choose the rotation and scale that maximize page usage inside the requested orientation.
Re-measure the output page after writing the transform.
If the output crosses the requested margins, reduce the scale and retry automatically until it fits.
Prefer re-running from bronze with adjusted options over stacking transforms on a previously fixed PDF.

If you need a filename decision, read references/naming-convention.md.

After producing the gold file, try to open it for review.

Prefer Chrome when available. Otherwise use the local browser or desktop open mechanism that matches the machine: xdg-open, open, powershell.exe, or an installed browser automation skill.
Ask for approval if the environment requires elevated GUI access.
If local open is unavailable, report the final path clearly instead of pretending the review happened.