@fectivnfy112358/minimax-code-web 0.1.0-preview.0 → 0.1.0-preview.3

package/server/assets/skills/pdf/scripts/lib/acroform_io.py

@@ -0,0 +1,170 @@
+"""AcroForm metadata enumeration for the MiniMax PDF skill.
+
+The functions here produce the JSON-shaped records that the
+``inspect`` and ``fill`` script groups consume. The schema is:
+
+    [
+      {
+        "qname": str,           # fully qualified field name
+        "page_no": int,         # 1-based page number
+        "box": [l, b, r, t],    # rectangle in PDF user space
+        "type": "text" | "checkbox" | "radio_group" | "choice" | "unknown (...)",
+        # type-specific extras:
+        "on_value": str,        # checkbox: the value that ticks the box
+        "off_value": str,       # checkbox: the value that unticks it
+        "radio_choices": [...], # radio: [{"set_to": str, "box": [...]}]
+        "choice_options": [...] # choice: [{"set_to": str, "label": str}]
+      }
+    ]
+
+The qname is the dotted path of every ``/T`` from the leaf annotation
+up to the root, joined with "." (so "address.line2" stays distinct
+from "shipping.line2"). When pypdf cannot resolve the parent chain we
+return ``None``.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+
+def resolve_full_qualified_name(annot: Any) -> str | None:
+    """Walk the ``/Parent`` chain of an annotation/field and join names."""
+    parts: list[str] = []
+    cursor = annot
+    while cursor is not None:
+        leaf = cursor.get("/T")
+        if leaf:
+            parts.append(leaf)
+        cursor = cursor.get("/Parent")
+    if not parts:
+        return None
+    return ".".join(reversed(parts))
+
+
+def build_field_record(raw_field: Any, qname: str) -> dict:
+    """Turn a pypdf field object into our JSON record (without box/page)."""
+    record: dict = {"qname": qname}
+    ft = raw_field.get("/FT")
+    if ft == "/Tx":
+        record["type"] = "text"
+    elif ft == "/Btn":
+        record["type"] = "checkbox"
+        states = raw_field.get("/_States_", [])
+        if len(states) == 2:
+            if "/Off" in states:
+                on = states[0] if states[0] != "/Off" else states[1]
+                record["on_value"] = on
+                record["off_value"] = "/Off"
+            else:
+                # Unusual two-state checkbox without an explicit /Off.
+                # Fall back to positional guess and warn the caller.
+                print(
+                    f"WARN: checkbox `{qname}` has non-standard states "
+                    f"{states}; verify the rendered PDF before relying on it."
+                )
+                record["on_value"] = states[0]
+                record["off_value"] = states[1]
+    elif ft == "/Ch":
+        record["type"] = "choice"
+        states = raw_field.get("/_States_", [])
+        record["choice_options"] = [
+            {"set_to": pair[0], "label": pair[1]} for pair in states
+        ]
+    else:
+        record["type"] = f"unknown ({ft})"
+    return record
+
+
+def enumerate_acroform_fields(pdf_doc) -> list[dict]:
+    """Return every fillable field in reading order, with location info.
+
+    ``pdf_doc`` is a ``pypdf.PdfReader``. Fields without a resolvable
+    page/box are skipped with a printed warning so a caller scanning the
+    JSON output never sees half-populated records.
+    """
+    raw_fields = pdf_doc.get_fields() or {}
+
+    record_by_qname: dict[str, dict] = {}
+    candidate_radio_qnames: set[str] = set()
+
+    for qname, field in raw_fields.items():
+        if field.get("/Kids"):
+            if field.get("/FT") == "/Btn":
+                candidate_radio_qnames.add(qname)
+            continue
+        record_by_qname[qname] = build_field_record(field, qname)
+
+    radio_groups_by_qname: dict[str, dict] = {}
+
+    for page_index, pg in enumerate(pdf_doc.pages):
+        for ann in pg.get("/Annots", []):
+            qname = resolve_full_qualified_name(ann)
+            if qname in record_by_qname:
+                record_by_qname[qname]["page_no"] = page_index + 1
+                record_by_qname[qname]["box"] = ann.get("/Rect")
+            elif qname in candidate_radio_qnames:
+                try:
+                    on_states = [v for v in ann["/AP"]["/N"] if v != "/Off"]
+                except KeyError:
+                    continue
+                if len(on_states) != 1:
+                    continue
+                box = ann.get("/Rect")
+                if qname not in radio_groups_by_qname:
+                    radio_groups_by_qname[qname] = {
+                        "qname": qname,
+                        "type": "radio_group",
+                        "page_no": page_index + 1,
+                        "radio_choices": [],
+                    }
+                radio_groups_by_qname[qname]["radio_choices"].append(
+                    {"set_to": on_states[0], "box": box}
+                )
+
+    placed_records: list[dict] = []
+    for record in record_by_qname.values():
+        if "page_no" in record:
+            placed_records.append(record)
+        else:
+            print(
+                f"WARN: cannot place field `{record.get('qname')}`, "
+                "skipping it in the output."
+            )
+
+    def reading_order_key(rec: dict):
+        if "radio_choices" in rec:
+            box = rec["radio_choices"][0]["box"] or [0, 0, 0, 0]
+        else:
+            box = rec.get("box") or [0, 0, 0, 0]
+        # sort top-to-bottom (negative y so larger y first), then left-to-right
+        return [rec.get("page_no"), [-box[1], box[0]]]
+
+    ordered_records = placed_records + list(radio_groups_by_qname.values())
+    ordered_records.sort(key=reading_order_key)
+    return ordered_records
+
+
+def patch_pypdf_inheritance() -> None:
+    """Smooth over a pypdf quirk for choice fields.
+
+    pypdf's ``DictionaryObject.get_inherited`` returns the raw ``/Opt``
+    list which, for choice widgets that store ``[value, display]`` pairs,
+    breaks downstream value validation. We unwrap the pair so callers see
+    a flat list of valid values.
+    """
+    from pypdf.generic import DictionaryObject
+    from pypdf.constants import FieldDictionaryAttributes
+
+    original = DictionaryObject.get_inherited
+
+    def patched(self, key: str, default=None):
+        result = original(self, key, default)
+        if key == FieldDictionaryAttributes.Opt:
+            if isinstance(result, list) and all(
+                isinstance(v, list) and len(v) == 2 for v in result
+            ):
+                result = [r[0] for r in result]
+        return result
+
+    DictionaryObject.get_inherited = patched

package/server/assets/skills/pdf/scripts/lib/cli_utils.py

@@ -0,0 +1,41 @@
+"""Tiny CLI helpers shared across the MiniMax PDF skill scripts.
+
+Each entry-point script in ``scripts/`` builds its argparse parser
+through :func:`make_parser` so the help output, default ``--quiet`` /
+``--verbose`` flags, and exit-code conventions stay uniform. The
+``emit`` / ``warn`` / ``fail`` helpers funnel all chatter through a
+single place so we can later switch to ``logging`` if needed.
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+
+def make_parser(prog: str, description: str) -> argparse.ArgumentParser:
+    """Build a parser pre-loaded with the project-wide flags."""
+    parser = argparse.ArgumentParser(prog=prog, description=description)
+    parser.add_argument(
+        "--quiet",
+        action="store_true",
+        help="Suppress informational output (warnings and errors still print).",
+    )
+    return parser
+
+
+def emit(msg: str, *, quiet: bool = False) -> None:
+    """Print an informational message unless ``--quiet`` is in effect."""
+    if not quiet:
+        print(msg)
+
+
+def warn(msg: str) -> None:
+    """Print a warning to stderr; never silenced by ``--quiet``."""
+    print(f"WARN: {msg}", file=sys.stderr)
+
+
+def fail(msg: str, code: int = 1) -> None:
+    """Print an error to stderr and exit with a non-zero status."""
+    print(f"ERROR: {msg}", file=sys.stderr)
+    sys.exit(code)

package/server/assets/skills/pdf/scripts/lib/geometry.py

@@ -0,0 +1,79 @@
+"""Geometry helpers for the MiniMax PDF skill.
+
+This module concentrates the coordinate-system bridges that the
+form-fill scripts share:
+
+- ``image_box_to_pdf_rect``: rasterised page pixel coords -> pypdf rect
+  (origin at the bottom-left of the page).
+- ``pdf_box_to_pypdf_rect``: pdfplumber-style PDF coords (origin at
+  the top-left) -> pypdf rect (origin at the bottom-left).
+- ``boxes_overlap``: boolean intersection check used by the geometry
+  linter.
+
+All functions are intentionally side-effect free so the module can be
+imported at unit-test time without touching disk or pulling in heavy
+PDF dependencies.
+"""
+
+from __future__ import annotations
+
+from typing import Sequence
+
+# Type aliases (Python 3.9+ accepts these in annotations because
+# ``from __future__ import annotations`` defers evaluation).
+Box = Sequence[float]
+
+
+def image_box_to_pdf_rect(
+    bbox: Box,
+    img_w: float,
+    img_h: float,
+    pdf_w: float,
+    pdf_h: float,
+) -> tuple[float, float, float, float]:
+    """Convert a pixel-space bbox into a pypdf rectangle.
+
+    ``bbox`` is ``[left, top, right, bottom]`` in raster pixels. The
+    output is ``(left, bottom, right, top)`` in PDF user-space points,
+    with the origin at the bottom-left of the page (which is what
+    ``pypdf.annotations.FreeText`` expects).
+    """
+    sx = pdf_w / img_w
+    sy = pdf_h / img_h
+
+    left = bbox[0] * sx
+    right = bbox[2] * sx
+
+    top = pdf_h - (bbox[1] * sy)
+    bottom = pdf_h - (bbox[3] * sy)
+
+    return left, bottom, right, top
+
+
+def pdf_box_to_pypdf_rect(
+    bbox: Box,
+    pdf_h: float,
+) -> tuple[float, float, float, float]:
+    """Flip a pdfplumber-style bbox to pypdf orientation.
+
+    pdfplumber reports ``[x0, top, x1, bottom]`` with the origin at the
+    top-left; pypdf expects the origin at the bottom-left.
+    """
+    left = bbox[0]
+    right = bbox[2]
+    pypdf_top = pdf_h - bbox[1]
+    pypdf_bottom = pdf_h - bbox[3]
+    return left, pypdf_bottom, right, pypdf_top
+
+
+def boxes_overlap(box_a: Box, box_b: Box) -> bool:
+    """True iff two axis-aligned boxes have a non-empty intersection.
+
+    Both inputs are ``[left, top, right, bottom]`` (the convention used
+    in the ``fields.json`` schema). Edge contact is treated as
+    *non-overlapping* so the linter does not complain about boxes that
+    happen to share a border.
+    """
+    apart_x = box_a[0] >= box_b[2] or box_a[2] <= box_b[0]
+    apart_y = box_a[1] >= box_b[3] or box_a[3] <= box_b[1]
+    return not (apart_x or apart_y)

package/server/assets/skills/pdf/scripts/make.sh

@@ -0,0 +1,388 @@
+#!/usr/bin/env bash
+# make.sh — pdf unified CLI (HTML → PDF)
+# Usage: bash make.sh <command> [options]
+#
+# Commands:
+#   check                          Verify all dependencies
+#   fix                            Auto-install missing dependencies
+#   render --in page.html --out report.pdf [--wait 15000] [--format A4] ...
+#                                  CREATE: render any HTML file/URL → PDF
+#   reformat --input doc.md --out report.pdf [--title T] [--accent #HEX] ...
+#                                  REFORMAT: parse markdown/text/pdf → HTML → PDF
+#   fill   <subcommand> [args...]  FILL: probe / inspect / apply (AcroForm)
+#                                        scan / rasterize / preview / overlay / lint (visual)
+#
+# For READ / extract existing PDFs, see docs/read-guide.md (pdfplumber default,
+#   scripts/read_pdf_vision.py for vision escalation).
+# For PDF mutation (merge / split / rotate / watermark / annotate), see
+# docs/advanced-reference.md (qpdf / pypdf / reportlab cookbook).
+#
+# Exit codes: 0 success, 1 usage error, 2 dep missing, 3 runtime error
+
+set -euo pipefail
+SCRIPTS="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILL_ROOT="$(cd "$SCRIPTS/.." && pwd)"
+PY="${PYTHON:-$(command -v python3 2>/dev/null || command -v python 2>/dev/null || echo python3)}"
+
+# ── Colour helpers ─────────────────────────────────────────────────────────────
+red()    { printf '\033[0;31m%s\033[0m\n' "$*"; }
+green()  { printf '\033[0;32m%s\033[0m\n' "$*"; }
+yellow() { printf '\033[0;33m%s\033[0m\n' "$*"; }
+bold()   { printf '\033[1m%s\033[0m\n' "$*"; }
+
+# ── Minimum versions (single source of truth for `check` and `fix`) ───────────
+PY_MIN="3.9"
+NODE_MIN_MAJOR=18
+PYPDF_MIN="3.0"
+MARKDOWN_IT_MIN="3.0"
+
+# Compare two dotted versions A and B; succeed iff A >= B.
+ver_ge() {
+  $PY - "$1" "$2" <<'PYEOF'
+import sys
+def parts(v):
+    out = []
+    for chunk in v.split("."):
+        digits = "".join(c for c in chunk if c.isdigit())
+        out.append(int(digits) if digits else 0)
+    return out
+a, b = parts(sys.argv[1]), parts(sys.argv[2])
+n = max(len(a), len(b))
+a += [0] * (n - len(a))
+b += [0] * (n - len(b))
+sys.exit(0 if a >= b else 1)
+PYEOF
+}
+
+# Print "OK <label> <version> (>= <min>)" or set ok=false and warn.
+# Args: <import-name> <pretty-label> <min-version> [optional]
+py_pkg_check() {
+  local import_name="$1" label="$2" min="$3" optional="${4:-}"
+  if ! $PY -c "import importlib, sys; m=importlib.import_module('$import_name'); v=getattr(m,'__version__','0'); print(v)" 2>/dev/null >/tmp/.pdfgen_ver; then
+    if [[ "$optional" == "true" ]]; then
+      yellow "  WARN $label not installed (optional)"
+    else
+      yellow "  MISSING $label (run: bash make.sh fix)"
+      ok=false
+    fi
+    return
+  fi
+  local ver
+  ver="$(cat /tmp/.pdfgen_ver)"
+  if ver_ge "$ver" "$min"; then
+    green "  OK $label $ver (>= $min)"
+  else
+    red "  FAIL $label $ver is below required $min"
+    ok=false
+  fi
+}
+
+# ── check ──────────────────────────────────────────────────────────────────────
+cmd_check() {
+  local ok=true
+  bold "Checking dependencies..."
+
+  # Python interpreter + version gate
+  if ! command -v $PY &>/dev/null; then
+    red "  MISSING python3 not found"
+    ok=false
+  else
+    local py_ver
+    py_ver=$($PY -c 'import sys;print(f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}")' 2>/dev/null || echo "?")
+    if ver_ge "$py_ver" "$PY_MIN"; then
+      green "  OK python3 $py_ver (>= $PY_MIN) at $(command -v $PY)"
+    else
+      red "  FAIL python3 $py_ver is below required $PY_MIN"
+      ok=false
+    fi
+    # pip must be importable so 'fix' can do its job
+    if $PY -m pip --version &>/dev/null; then
+      local pip_ver
+      pip_ver=$($PY -m pip --version 2>/dev/null | awk '{print $2}')
+      green "  OK pip $pip_ver"
+    else
+      yellow "  WARN pip not importable from $PY (try: $PY -m ensurepip)"
+      ok=false
+    fi
+  fi
+
+  # Python packages — pypdf is needed by fill/, markdown-it-py by reformat
+  py_pkg_check pypdf       "pypdf"          "$PYPDF_MIN"
+  py_pkg_check markdown_it "markdown-it-py" "$MARKDOWN_IT_MIN"
+
+  # Node.js + version gate
+  if command -v node &>/dev/null; then
+    local node_ver node_major
+    node_ver=$(node --version 2>&1 | sed 's/^v//')
+    node_major=${node_ver%%.*}
+    if [[ "$node_major" -ge "$NODE_MIN_MAJOR" ]]; then
+      green "  OK node v$node_ver (>= v$NODE_MIN_MAJOR)"
+    else
+      red "  FAIL node v$node_ver is below required v$NODE_MIN_MAJOR"
+      ok=false
+    fi
+  else
+    red "  MISSING node not found - HTML rendering unavailable"
+    ok=false
+  fi
+
+  # Playwright (resolved either locally or globally)
+  if node -e "require('playwright')" 2>/dev/null || \
+     node -e "require(require('child_process').execSync('npm root -g').toString().trim()+'/playwright')" 2>/dev/null; then
+    green "  OK playwright"
+  else
+    yellow "  WARN playwright not found  (run: bash make.sh fix)"
+    ok=false
+  fi
+
+  # pdfinfo / qpdf are nice-to-have for verification & mutation
+  if command -v pdfinfo &>/dev/null; then green "  OK pdfinfo $(pdfinfo -v 2>&1 | head -1 | awk '{print $NF}')"
+  else yellow "  WARN pdfinfo not found (brew install poppler) — only used for verification"; fi
+  if command -v qpdf &>/dev/null; then green "  OK qpdf $(qpdf --version | head -1 | awk '{print $NF}')"
+  else yellow "  WARN qpdf not found (brew install qpdf) — only used for advanced PDF mutation"; fi
+
+  if $ok; then
+    green ""
+    green "All required dependencies satisfied."
+    exit 0
+  else
+    yellow ""
+    yellow "Some dependencies are missing or below the supported minimum."
+    yellow "Run: bash make.sh fix"
+    exit 2
+  fi
+}
+
+# ── fix ────────────────────────────────────────────────────────────────────────
+cmd_fix() {
+  bold "Installing missing dependencies..."
+  local rc=0
+
+  if ! command -v $PY &>/dev/null; then
+    red "  python3 not found - install Python $PY_MIN+ first"
+    exit 2
+  fi
+  if ! $PY -m pip --version &>/dev/null; then
+    red "  pip is not importable from $(command -v $PY)"
+    yellow "  Try: $PY -m ensurepip --upgrade"
+    exit 2
+  fi
+
+  # Python packages
+  local pip_log
+  pip_log=$(mktemp -t pdfgen-pip.XXXXXX)
+  local pip_specs=("pypdf>=$PYPDF_MIN" "markdown-it-py>=$MARKDOWN_IT_MIN")
+  bold "  Running: $PY -m pip install ${pip_specs[*]}"
+  if $PY -m pip install --break-system-packages -q "${pip_specs[@]}" >"$pip_log" 2>&1 \
+     || $PY -m pip install -q "${pip_specs[@]}" >"$pip_log" 2>&1; then
+    green "  OK Python packages installed (pypdf, markdown-it-py)"
+  else
+    yellow "  pip install failed -- last 20 lines of output:"
+    tail -20 "$pip_log" | sed 's/^/    /'
+    rc=3
+  fi
+  rm -f "$pip_log"
+
+  # Playwright -- skip when already resolvable
+  if node -e "require('playwright')" 2>/dev/null || \
+     node -e "require(require('child_process').execSync('npm root -g').toString().trim()+'/playwright')" 2>/dev/null; then
+    green "  OK playwright already installed -- skipping"
+  elif command -v npm &>/dev/null; then
+    if npm install -g playwright --silent 2>/dev/null && \
+       npx playwright install chromium --silent 2>/dev/null; then
+      green "  OK Playwright + Chromium installed"
+    else
+      yellow "  playwright install failed -- try: npm install -g playwright && npx playwright install chromium"
+      rc=3
+    fi
+  else
+    yellow "  npm not found - cannot install Playwright (HTML rendering will fail)"
+    rc=2
+  fi
+
+  if [[ $rc -eq 0 ]]; then
+    green ""
+    green "All dependencies installed. Run: bash make.sh check"
+  else
+    yellow ""
+    yellow "Some installs failed -- run 'bash make.sh check' for the current state."
+  fi
+  exit $rc
+}
+
+# ── render ────────────────────────────────────────────────────────────────────
+# Thin wrapper around scripts/render_html.cjs. Forwards every flag through.
+# Usage:
+#   bash make.sh render --in page.html --out report.pdf [--wait 15000] ...
+cmd_render() {
+  if [[ $# -eq 0 ]]; then
+    cat <<'USAGE'
+Usage: bash make.sh render --in <file.html|url> --out <file.pdf>
+                          [--wait <ms>]              extra settle time (Chart.js: 15000)
+                          [--format A4|Letter]      page format (default A4)
+                          [--margin "14mm 12mm"]    CSS margin shorthand
+                          [--landscape]             landscape orientation
+                          [--scale 1]               print scale 0.1–2
+                          [--no-print-background]   disable color-exact print
+                          [--header <html>]         header template
+                          [--footer <html>]         footer template
+
+Examples:
+  bash make.sh render --in templates/data-viz-report/skeleton.html \
+                      --out demo.pdf --wait 15000
+  bash make.sh render --in https://example.com --out site.pdf --landscape
+USAGE
+    exit 1
+  fi
+  exec node "$SCRIPTS/render_html.cjs" "$@"
+}
+
+# ── reformat ───────────────────────────────────────────────────────────────────
+# Parse a markdown / text / pdf source into HTML using the reformat-default
+# template, then render to PDF.
+cmd_reformat() {
+  local input="" out="output.pdf"
+  local title="" subtitle="" author="" date="" accent=""
+  local template="default" wait_ms="800"
+  local keep_html=false
+
+  while [[ $# -gt 0 ]]; do
+    case "$1" in
+      --input)    input="$2";    shift 2 ;;
+      --out)      out="$2";      shift 2 ;;
+      --title)    title="$2";    shift 2 ;;
+      --subtitle) subtitle="$2"; shift 2 ;;
+      --author)   author="$2";   shift 2 ;;
+      --date)     date="$2";     shift 2 ;;
+      --accent)   accent="$2";   shift 2 ;;
+      --template) template="$2"; shift 2 ;;
+      --wait)     wait_ms="$2";  shift 2 ;;
+      --keep-html) keep_html=true; shift ;;
+      -h|--help)
+        cat <<'USAGE'
+Usage: bash make.sh reformat --input <file.md|.txt|.pdf|.html> --out <file.pdf>
+                            [--title T] [--subtitle S] [--author A] [--date D]
+                            [--accent "#007AFF"] [--template default]
+                            [--wait <ms>] [--keep-html]
+
+Pipeline: source → markdown → reformat-default skeleton → PDF
+USAGE
+        exit 0 ;;
+      *) red "Unknown option: $1"; exit 1 ;;
+    esac
+  done
+
+  if [[ -z "$input" ]]; then
+    red "error: --input is required"
+    bash "$0" reformat --help
+    exit 1
+  fi
+  if [[ ! -f "$input" ]]; then
+    red "error: input not found: $input"
+    exit 1
+  fi
+
+  local tmpdir
+  tmpdir="$(mktemp -d -t pdfgen-reformat.XXXXXX)"
+  local html="$tmpdir/page.html"
+
+  bold "Parsing → HTML: $input"
+  local parse_args=(--input "$input" --out "$html" --template "$template")
+  [[ -n "$title"    ]] && parse_args+=(--title    "$title")
+  [[ -n "$subtitle" ]] && parse_args+=(--subtitle "$subtitle")
+  [[ -n "$author"   ]] && parse_args+=(--author   "$author")
+  [[ -n "$date"     ]] && parse_args+=(--date     "$date")
+  [[ -n "$accent"   ]] && parse_args+=(--accent   "$accent")
+  $PY "$SCRIPTS/reformat_parse.py" "${parse_args[@]}"
+
+  bold "Rendering → PDF: $out"
+  node "$SCRIPTS/render_html.cjs" --in "$html" --out "$out" --wait "$wait_ms"
+
+  if $keep_html; then
+    yellow "  (--keep-html) intermediate HTML kept at: $html"
+  else
+    rm -rf "$tmpdir"
+  fi
+  green "OK reformat complete: $out"
+}
+
+# ── fill ──────────────────────────────────────────────────────────────────────
+# FILL is dispatched via subverbs that map to subpackages under scripts/.
+# All scripts run as `python -m scripts.<group>.<name>` from the skill root.
+cmd_fill() {
+  if [[ $# -lt 1 ]]; then
+    cat <<'USAGE'
+Usage: make.sh fill <subcommand> [args...]
+
+Subcommands:
+  probe     <input.pdf>                                 Detect AcroForm: prints acroform=true|false
+  inspect   <input.pdf> <meta.json>                     Dump AcroForm field metadata
+  apply     <input.pdf> <values.json> <output.pdf>      Apply values to AcroForm fields
+  scan      <input.pdf> <layout.json>                   Scan visual layout (non-fillable PDFs)
+  rasterize <input.pdf> <out_dir/> [--max-edge N] [--dpi N]
+                                                        Render pages to PNG
+  preview   <page> <fields.json> <page.png> <out.png>   Overlay bbox preview on a page image
+  overlay   <input.pdf> <fields.json> <output.pdf>      Lay text via FreeText annotations
+  lint      <fields.json> [--max-findings N]            Lint bounding-box geometry in fields.json
+
+Decision tree: run 'fill probe' first.
+  acroform=true  → inspect → apply
+  acroform=false → scan → rasterize → preview → overlay → lint
+USAGE
+    exit 1
+  fi
+
+  local sub="$1"; shift
+  cd "$SKILL_ROOT"
+  # Prepend the skill root to PYTHONPATH so `python -m scripts.X` works even
+  # when PYTHONSAFEPATH=1 is set in the user environment.
+  export PYTHONPATH="$SKILL_ROOT${PYTHONPATH:+:$PYTHONPATH}"
+
+  case "$sub" in
+    probe)     bold "Probing AcroForm: $1";              $PY -m scripts.pdf_inspect.acroform_probe   "$@" ;;
+    inspect)   bold "Inspecting AcroForm: $1 → $2";      $PY -m scripts.pdf_inspect.acroform_inspect "$@" ;;
+    apply)     bold "Applying values: $1 + $2 → $3";     $PY -m scripts.fill.acroform_apply          "$@" ;;
+    scan)      bold "Scanning layout: $1 → $2";          $PY -m scripts.pdf_inspect.layout_scan      "$@" ;;
+    rasterize) bold "Rasterising pages: $1 → $2";        $PY -m scripts.render.page_rasterize        "$@" ;;
+    preview)   bold "Overlay preview: page $1 → $4";     $PY -m scripts.render.overlay_preview       "$@" ;;
+    overlay)   bold "Filling via overlay: $1 + $2 → $3"; $PY -m scripts.fill.overlay_apply           "$@" ;;
+    lint)      bold "Linting fields: $1";                $PY -m scripts.validate.geometry_lint       "$@" ;;
+    *)         red "Unknown fill subcommand: $sub";      exit 1 ;;
+  esac
+}
+
+# ── dispatch ───────────────────────────────────────────────────────────────────
+main() {
+  if [[ $# -lt 1 ]]; then
+    bold "pdf — make.sh (HTML → PDF)"
+    cat <<'USAGE'
+
+Usage: bash make.sh <command> [options]
+
+Commands:
+  check                              Verify all dependencies
+  fix                                Auto-install missing dependencies
+  render --in HTML --out PDF [opts]  CREATE: render HTML file or URL → PDF
+                                     (see: bash make.sh render with no args)
+  reformat --input SRC --out PDF     REFORMAT: markdown/text/pdf → HTML → PDF
+                                     (see: bash make.sh reformat --help)
+  fill <subcommand> [args...]        FILL: AcroForm probe/apply, visual overlay
+                                     (see: bash make.sh fill with no args)
+
+For READ / extract existing PDFs, see docs/read-guide.md.
+For PDF mutation (merge / split / rotate / watermark), see docs/advanced-reference.md.
+USAGE
+    exit 0
+  fi
+
+  case "$1" in
+    check)        cmd_check ;;
+    fix)          cmd_fix   ;;
+    render)       shift; cmd_render     "$@" ;;
+    reformat)     shift; cmd_reformat   "$@" ;;
+    fill)         shift; cmd_fill       "$@" ;;
+    *)            red "Unknown command: $1"; exit 1 ;;
+  esac
+}
+
+main "$@"