dsh-office-kit 0.1.0 → 0.3.0

package/assets/skills/office-pdf/scripts/split_pages.py

@@ -0,0 +1,155 @@
+#!/usr/bin/env python3
+"""Split a PDF into one file per page, per page range, or in fixed-size chunks.
+
+Ranges are 1-based and inclusive; "6-" runs to the last page, "-4" starts at
+page 1. Without --ranges or --every every page becomes its own file. Each part
+copies the source metadata and reports its page count so the caller can check
+the split before delivering it.
+
+Exit codes: 0 success, 1 bad arguments, 2 unreadable input or write failure,
+3 refused (range outside the document, or output path collision).
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+try:
+    import pymupdf
+except ImportError:  # pragma: no cover - PyMuPDF is a required dependency
+    import fitz as pymupdf  # type: ignore[no-redef]
+
+
+def emit(value, out=None):
+    text = json.dumps(value, ensure_ascii=False, indent=2, default=str)
+    if out:
+        target = Path(out).expanduser()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text + "\n", encoding="utf-8")
+    print(text)
+
+
+def fail(message, code=1):
+    print(json.dumps({"ok": False, "error": message}, ensure_ascii=False, indent=2), file=sys.stderr)
+    raise SystemExit(code)
+
+
+def parse_ranges(spec, page_count):
+    spans = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" not in part:
+            start = end = int(part)
+        else:
+            first, last = part.split("-", 1)
+            start = int(first) if first.strip() else 1
+            end = int(last) if last.strip() else page_count
+        if start < 1 or end > page_count or start > end:
+            fail(f"range {part!r} is outside pages 1-{page_count}", code=3)
+        spans.append((start, end))
+    if not spans:
+        fail("--ranges listed no usable range")
+    spans.sort()
+    for previous, current in zip(spans, spans[1:]):
+        if current[0] <= previous[1]:
+            fail(f"ranges overlap: {previous[0]}-{previous[1]} and {current[0]}-{current[1]}", code=3)
+    return spans
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Split a PDF into page ranges, single pages, or fixed-size chunks.",
+        epilog='Example: split_pages.py --input report.pdf --out-dir parts --ranges "1-2,3,4-"',
+    )
+    parser.add_argument("--input", required=True, help="Source PDF")
+    parser.add_argument("--out-dir", required=True, help="Directory for the parts")
+    parser.add_argument("--ranges", help='1-based inclusive ranges, e.g. "1-2,5,8-"')
+    parser.add_argument("--every", type=int, metavar="N", help="Fixed chunk size in pages")
+    parser.add_argument("--prefix", help="Filename prefix (default: source stem)")
+    parser.add_argument("--json-out", help="Also write the JSON report to this path")
+    args = parser.parse_args()
+
+    if args.ranges and args.every:
+        fail("use either --ranges or --every, not both")
+    if args.every is not None and args.every < 1:
+        fail("--every must be at least 1")
+
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        fail(f"input not found: {source}", code=2)
+    out_dir = Path(args.out_dir).expanduser()
+    prefix = args.prefix or source.stem
+
+    try:
+        document = pymupdf.open(str(source))
+    except Exception as exc:
+        fail(f"cannot open PDF: {exc}", code=2)
+    if document.needs_pass:
+        document.close()
+        fail("PDF is encrypted; decrypt it before splitting", code=3)
+    page_count = document.page_count
+    if page_count == 0:
+        document.close()
+        fail("the PDF has no pages", code=3)
+
+    if args.ranges:
+        spans = parse_ranges(args.ranges, page_count)
+    elif args.every:
+        spans = [(start, min(start + args.every - 1, page_count)) for start in range(1, page_count + 1, args.every)]
+    else:
+        spans = [(number, number) for number in range(1, page_count + 1)]
+
+    out_dir.mkdir(parents=True, exist_ok=True)
+    parts = []
+    for start, end in spans:
+        name = f"{prefix}-p{start}.pdf" if start == end else f"{prefix}-p{start}-{end}.pdf"
+        target = out_dir / name
+        if target.resolve() == source.resolve():
+            document.close()
+            fail(f"refusing to overwrite the source PDF: {target}", code=3)
+        part = pymupdf.open()
+        part.insert_pdf(document, from_page=start - 1, to_page=end - 1)
+        try:
+            part.set_metadata(document.metadata or {})
+        except Exception:
+            pass
+        try:
+            part.save(str(target), garbage=3, deflate=True)
+        except Exception as exc:
+            part.close()
+            document.close()
+            fail(f"cannot write {target}: {exc}", code=2)
+        written_pages = part.page_count
+        part.close()
+        parts.append({"file": str(target), "first_page": start, "last_page": end, "pages": written_pages})
+
+    document.close()
+    result = {
+        "ok": True,
+        "input": str(source),
+        "source_pages": page_count,
+        "out_dir": str(out_dir),
+        "parts": parts,
+        "parts_total_pages": sum(part["pages"] for part in parts),
+    }
+    if result["parts_total_pages"] != page_count:
+        fail(
+            f"wrote {result['parts_total_pages']} pages but the source has {page_count}; check the ranges",
+            code=3,
+        )
+    emit(result, args.json_out)
+
+
+if __name__ == "__main__":
+    main()

package/assets/skills/office-pdf/scripts/stamp_overlay.py

@@ -0,0 +1,199 @@
+#!/usr/bin/env python3
+"""Stamp a running footer, header, or label onto selected pages of a PDF.
+
+Draws the text on a transparent overlay with reportlab, then merges that overlay
+into each chosen page with pypdf. The text supports {page} and {pages}, so one
+template produces "Page 3 of 12" per page. Nothing in the source content stream
+is rewritten, which keeps existing fonts, links, and form widgets intact.
+
+Exit codes: 0 success, 1 bad arguments, 2 unreadable input or write failure,
+3 refused (encrypted document, bad page selection, or source overwrite).
+"""
+
+from __future__ import annotations
+
+import argparse
+import io
+import json
+import sys
+from pathlib import Path
+
+for _stream in (sys.stdout, sys.stderr):
+    try:
+        _stream.reconfigure(encoding="utf-8", errors="replace")
+    except (AttributeError, ValueError):
+        pass
+
+from pypdf import PdfReader, PdfWriter
+from reportlab.lib.colors import HexColor
+from reportlab.pdfgen import canvas
+
+try:
+    import pymupdf
+except ImportError:  # pragma: no cover - PyMuPDF is a required dependency
+    import fitz as pymupdf  # type: ignore[no-redef]
+
+POSITIONS = {
+    "bottom-left": "left",
+    "bottom-center": "center",
+    "bottom-right": "right",
+    "top-left": "left",
+    "top-center": "center",
+    "top-right": "right",
+}
+
+
+def emit(value, out=None):
+    text = json.dumps(value, ensure_ascii=False, indent=2, default=str)
+    if out:
+        target = Path(out).expanduser()
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.write_text(text + "\n", encoding="utf-8")
+    print(text)
+
+
+def fail(message, code=1):
+    print(json.dumps({"ok": False, "error": message}, ensure_ascii=False, indent=2), file=sys.stderr)
+    raise SystemExit(code)
+
+
+def parse_pages(spec, page_count):
+    if spec.strip().lower() in {"all", ""}:
+        return list(range(1, page_count + 1))
+    selected = []
+    for part in spec.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        if "-" not in part:
+            selected.append(int(part))
+        else:
+            first, last = part.split("-", 1)
+            selected.extend(range(int(first or 1), int(last or page_count) + 1))
+    for number in selected:
+        if number < 1 or number > page_count:
+            fail(f"page {number} is outside 1-{page_count}", code=3)
+    return sorted(set(selected))
+
+
+def main():
+    parser = argparse.ArgumentParser(
+        description="Draw a text stamp on selected pages and merge it over the page content.",
+        epilog='Example: stamp_overlay.py --input report.pdf --out stamped.pdf --text "Page {page} of {pages}" --position bottom-right',
+    )
+    parser.add_argument("--input", required=True, help="Source PDF; it is never modified")
+    parser.add_argument("--out", required=True, help="Destination PDF")
+    parser.add_argument("--text", required=True, help='Stamp text; {page} and {pages} are replaced, e.g. "Confidential - Page {page}/{pages}"')
+    parser.add_argument(
+        "--position",
+        choices=sorted(POSITIONS),
+        default="bottom-center",
+        help="Anchor of the stamp (default: bottom-center)",
+    )
+    parser.add_argument("--font", default="Helvetica", help="reportlab base-14 font name (default: Helvetica)")
+    parser.add_argument("--font-size", type=float, default=9.0, help="Font size in points (default: 9)")
+    parser.add_argument("--color", default="#666666", help="Hex text colour (default: #666666)")
+    parser.add_argument("--margin", type=float, default=28.0, help="Page-edge margin in points (default: 28)")
+    parser.add_argument("--opacity", type=float, default=1.0, help="Text opacity 0-1 (default: 1)")
+    parser.add_argument("--pages", default="all", help='1-based selection, e.g. "1,3-5" (default: all)')
+    parser.add_argument("--render-dir", help="Rasterise the stamped pages here for a visual check")
+    parser.add_argument("--dpi", type=int, default=110, help="Render resolution (default: 110)")
+    parser.add_argument("--json-out", help="Also write the JSON report to this path")
+    args = parser.parse_args()
+
+    source = Path(args.input).expanduser()
+    if not source.is_file():
+        fail(f"input not found: {source}", code=2)
+    out = Path(args.out).expanduser()
+    if out.resolve() == source.resolve():
+        fail("refusing to overwrite the source PDF; choose a different --out", code=3)
+    if args.font_size <= 0 or args.font_size > 96:
+        fail("--font-size must be between 0 and 96")
+    if not 0 < args.opacity <= 1:
+        fail("--opacity must be greater than 0 and at most 1")
+    if args.margin < 0 or args.margin > 200:
+        fail("--margin must be between 0 and 200 points")
+    try:
+        colour = HexColor(args.color)
+    except Exception:
+        fail("--color must be a hex colour like #666666")
+
+    try:
+        reader = PdfReader(str(source))
+    except Exception as exc:
+        fail(f"cannot open PDF: {exc}", code=2)
+    if reader.is_encrypted:
+        fail("PDF is encrypted; decrypt it before stamping", code=3)
+    page_count = len(reader.pages)
+    selected = parse_pages(args.pages, page_count)
+
+    writer = PdfWriter()
+    stamped = []
+    for index, page in enumerate(reader.pages, start=1):
+        if index in selected:
+            box = page.mediabox
+            width = float(box.width)
+            height = float(box.height)
+            label = args.text.format(page=index, pages=page_count)
+            buffer = io.BytesIO()
+            stamp = canvas.Canvas(buffer, pagesize=(width, height))
+            stamp.setFillColor(colour)
+            stamp.setFont(args.font, args.font_size)
+            stamp.setFillAlpha(args.opacity)
+            text_width = stamp.stringWidth(label, args.font, args.font_size)
+            anchor = POSITIONS[args.position]
+            if anchor == "left":
+                x = args.margin
+            elif anchor == "right":
+                x = width - args.margin - text_width
+            else:
+                x = (width - text_width) / 2
+            baseline = args.margin if args.position.startswith("bottom") else height - args.margin - args.font_size * 0.35
+            stamp.drawString(x, baseline, label)
+            stamp.save()
+            buffer.seek(0)
+            overlay = PdfReader(buffer).pages[0]
+            page.merge_page(overlay)
+            stamped.append({"page": index, "text": label, "x": round(x, 2), "y": round(baseline, 2)})
+        writer.add_page(page)
+
+    out.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        with out.open("wb") as handle:
+            writer.write(handle)
+    except Exception as exc:
+        fail(f"cannot write {out}: {exc}", code=2)
+
+    rendered = []
+    if args.render_dir:
+        if args.dpi < 24 or args.dpi > 600:
+            fail("--dpi must be between 24 and 600")
+        target_dir = Path(args.render_dir).expanduser()
+        target_dir.mkdir(parents=True, exist_ok=True)
+        zoom = args.dpi / 72.0
+        with pymupdf.open(str(out)) as rendered_doc:
+            for page_number in selected:
+                page = rendered_doc[page_number - 1]
+                target = target_dir / f"page-{page_number}.png"
+                page.get_pixmap(matrix=pymupdf.Matrix(zoom, zoom), alpha=False).save(str(target))
+                rendered.append(str(target))
+
+    result = {
+        "ok": True,
+        "input": str(source),
+        "output": str(out),
+        "pages": page_count,
+        "stamped_pages": stamped,
+        "position": args.position,
+        "font": args.font,
+        "font_size": args.font_size,
+        "color": args.color,
+        "rendered_pages": rendered,
+    }
+    if len(result["stamped_pages"]) != len(selected):
+        fail(f"stamped {len(result['stamped_pages'])} pages but selected {len(selected)}", code=3)
+    emit(result, args.json_out)
+
+
+if __name__ == "__main__":
+    main()

package/assets/skills/office-pdf/tasks/annotations.md

@@ -0,0 +1,98 @@
+# Resolve an `office-annotations` region on a PDF
+
+`page` is the 1-based page of the file, and `region × page.rect` is the real rectangle in the page's coordinate system. Convert once; then everything you do — read, redact, stamp, fill — uses that rect.
+
+## 1. Reproduce the page first
+
+```bash
+"<python>" "<cli>" pdf render --input "<file.pdf>" --out-dir "<render>" --dpi 110
+```
+
+Open `"<render>/page-<N>.png"` with `read_image`. The geometry is only meaningful against the page the user saw, so never resolve a region on a page you have not rendered.
+
+## 2. Convert the region and read what it covers
+
+```bash
+"<python>" - <<'PY'
+import pymupdf
+doc = pymupdf.open("in.pdf")
+page = doc[0]                       # page 1
+r = page.rect
+region = (0.064, 0.318, 0.891, 0.153)   # left, top, width, height
+left, top, width, height = region
+rect = pymupdf.Rect(r.x0 + left * r.width, r.y0 + top * r.height,
+                    r.x0 + (left + width) * r.width, r.y0 + (top + height) * r.height)
+print("rect", rect)
+print("words:", " ".join(w[4] for w in page.get_text("words", clip=rect)))
+print("textbox:", repr(page.get_textbox(rect)[:300]))
+print("images:", page.get_image_info(clip=rect))
+PY
+```
+
+Compare the words with the annotation's `text`. If `text` is present and those words are not in the region, trust `text` and say the region was off — do not shift the rectangle to make it land. If `imageName` came with the payload, open that screenshot with `read_image` to see exactly what was marked.
+
+## 3. Pick the smallest operation that satisfies `requirement`
+
+| What the region covers | Operation |
+| --- | --- |
+| A metadata line, title, author | `scripts/metadata.py --set ...` |
+| A whole block to delete | `scripts/redact_region.py` |
+| A widget or a form label | `scripts/forms.py fill` / `inspect` |
+| A footer, header, or label to add | `scripts/stamp_overlay.py` |
+| Page order, rotation, deletion | `scripts/page_ops.py` or `scripts/split_pages.py` |
+| A single word or sentence to change | redact the old line, then stamp the new text (below) |
+| A picture to replace | overlay a cover rect and draw the new image with reportlab |
+
+A requirement like "make this sentence shorter" is a content edit; do not rebuild the whole page for it when the block is one line.
+
+## 4. Patch one line in place
+
+Delete the old glyphs first, then draw the replacement at the same baseline. Covering without deleting leaves the original text extractable.
+
+```bash
+"<python>" - <<'PY'
+import io
+import pymupdf
+from pypdf import PdfReader, PdfWriter
+from reportlab.pdfgen import canvas
+
+old = "Revenue grew 18.4% year over year."
+new = "Revenue grew 19% year over year."
+doc = pymupdf.open("in.pdf")
+page = doc[3]                                  # page 4
+hits = page.search_for(old)
+assert hits, "text not found; re-read the page"
+rect = hits[0] + (-1, -1, 1, 1)                # a little air around the line
+page.add_redact_annot(rect, fill=None)
+page.apply_redactions(images=pymupdf.PDF_REDACT_IMAGE_NONE,
+                      graphics=pymupdf.PDF_REDACT_LINE_ART_REMOVE_IF_TOUCHED)
+doc.save("cleaned.pdf", garbage=3, deflate=True)
+
+reader = PdfReader("cleaned.pdf")
+writer = PdfWriter()
+with pymupdf.open("in.pdf") as source:
+    font_size = 11
+for index, page in enumerate(reader.pages):
+    if index == 3:
+        buffer = io.BytesIO()
+        c = canvas.Canvas(buffer, pagesize=(float(page.mediabox.width), float(page.mediabox.height)))
+        c.setFont("Helvetica", font_size)
+        c.drawString(float(rect.x0), float(page.mediabox.height) - float(rect.y0) - font_size, new)
+        c.save()
+        buffer.seek(0)
+        page.merge_page(PdfReader(buffer).pages[0])
+    writer.add_page(page)
+with open("out.pdf", "wb") as handle:
+    writer.write(handle)
+PY
+```
+
+Line height and font size must match the original text; read them from the original spans (`page.get_text("dict")` → blocks → lines → spans → `size`, `font`, `origin`). A different font or size is visible in the render and reads as a patch job.
+
+## 5. When the payload cannot be tied to an object
+
+Say which part you could not locate: the render page, the words you found under the region, and the item that is missing. Then ask for the text of the target or a clearer region. Genuinely blocked cases and their resolutions are in `references/limits.md` — name the missing capability and what the user can do about it, never a bare "unsupported".
+
+## 6. Re-render and confirm
+
+Apply the edit, render the same page, and `read_image` it again. The region must show the requested result, the neighbouring text must be untouched, and the layout must still hold. Then check extraction (`pdf read`) so the change is real in the text layer, not only in pixels. Report what you resolved back to the user in the same terms they annotated with: page number and a one-line description of the change.

package/assets/skills/office-pdf/tasks/create.md

@@ -0,0 +1,75 @@
+# Create a PDF
+
+A new PDF is a set of pages, each holding a content stream plus fonts and resources. Two routes exist here, and both end with the same verification.
+
+## Fast path: the helper CLI spec
+
+```bash
+"<python>" "<cli>" pdf create --spec "<spec.json>" --out "<output.pdf>"
+```
+
+```json
+{
+  "title": "Field report",
+  "author": "Ada Lovelace",
+  "page_size": "A4",
+  "blocks": [
+    { "type": "title", "text": "Field report" },
+    { "type": "paragraph", "text": "One sentence of body copy." },
+    { "type": "bullets", "items": ["First", "Second"] },
+    { "type": "table", "headers": ["Item", "Value"], "rows": [["Pump", "3"]] },
+    { "type": "page_break" }
+  ]
+}
+```
+
+Blocks: `title`, `heading` (`level` 1–2), `paragraph`, `quote`, `bullets`, `numbered`, `table` (`headers`, `rows`), `image` (`path`, `width` inches, height derived at 0.66 aspect), `page_break`, `spacer` (`height` inches). Use `pages: [{ "blocks": [...], "break": true }]` when the page grouping matters. `page_size` accepts `A4` or `Letter`.
+
+## Direct path: reportlab
+
+Reach for reportlab when the layout does not fit the block model — columns, absolute placement, custom rules, rotated text.
+
+```bash
+"<python>" - <<'PY'
+from reportlab.lib.pagesizes import A4
+from reportlab.pdfgen import canvas
+from reportlab.lib.units import mm
+
+c = canvas.Canvas("out.pdf", pagesize=A4)
+width, height = A4
+c.setTitle("Field report")
+c.setFont("Helvetica-Bold", 18)
+c.drawString(22 * mm, height - 30 * mm, "Field report")
+c.setFont("Helvetica", 11)
+text = c.beginText(22 * mm, height - 45 * mm)
+for line in ["One sentence of body copy.", "A second line."]:
+    text.textLine(line)
+c.drawText(text)
+c.showPage()
+c.save()
+PY
+```
+
+`drawString` takes a baseline point measured from the bottom-left corner, not the top. Convert top-down coordinates once (for a page height `h`, baseline `y = h - top - font_size`), or every following measurement will drift.
+
+## Fonts
+
+Base-14 fonts (`Helvetica`, `Times-Roman`, `Courier`) need no embedding and cover Latin text. Non-Latin text needs a real font file registered with `pdfmetrics.registerFont(TTFont("Body", "<path>.ttf"))`; a font that cannot render a glyph produces a blank box in the output, which the render step will show. The CLI tries the first available CJK system font, and says so when none exists.
+
+## Quality rules
+
+- One heading scale, one body size, one margin system per document.
+- Keep body text inside 12–16 pt leading; below 9 pt text becomes unreliable on print.
+- ASCII hyphens only in prose; do not paste typographic dashes into generated copy unless the source used them.
+- Give every page a consistent header/footer treatment, or none at all.
+- Do not put a table wider than the text column; wrap long cell text instead of letting it clip.
+
+## Verify
+
+Render and look at every page; a created PDF has no text layer surprises, so problems are layout problems: text past the margin, blocks overlapping, table columns squeezed, a `page_break` landing on an empty page, or a CJK line silently blank.
+
+```bash
+"<python>" "<cli>" pdf render --input "out.pdf" --out-dir "render" --dpi 110
+```
+
+Then confirm the structure you intended with `"<python>" "<cli>" pdf read --input "out.pdf"` (page count and per-page text) before `present`.

package/assets/skills/office-pdf/tasks/edit-pages.md

@@ -0,0 +1,71 @@
+# Merge, split, reorder, rotate, delete pages
+
+Pages are objects referenced from a page tree; changing the order or removing a page changes references, not content. Nothing is re-flowed, so a page moved into a document with a different page size keeps its own box and fonts.
+
+## Fast path: `scripts/page_ops.py`
+
+```bash
+"<python>" "<skill>/scripts/page_ops.py" --input "<file.pdf>" --out "<file-edited.pdf>" \
+  --rotate 90 --pages 0,2 --remove 3 --merge "<other.pdf>" --order 2,0,1
+```
+
+- Operations run in a fixed order: merge, then order, then remove, then rotate — a command means the same thing every time.
+- Every index is zero-based and addresses the combined page list (input pages first, appended pages after).
+- `--order` keeps and reorders; pages it does not list are dropped, which also makes it the duplicate/select tool when you repeat an index.
+- `--remove` drops indices from the list left by `--order`.
+- `--rotate` takes 90, 180, or 270 clockwise and defaults to every remaining page; `--pages` limits it.
+- `--out` defaults to `<input>-edited.pdf`; the input is never overwritten.
+
+The script carries page content streams over as they are and reopens the result to report page count, rotation, and page size per page. When one call cannot express the operation, chain two calls into two output files rather than reusing a name.
+
+## Metadata
+
+```bash
+"<python>" "<skill>/scripts/metadata.py" --input "<file.pdf>" --set "/Title=Field report" --set "/Author=Ada" --out "<file-edited.pdf>"
+```
+
+Keys are the document information fields (`Title`, `Author`, `Subject`, `Keywords`, `Creator`, `Producer`, `CreationDate`, `ModDate`), plain or `/Name`, in any case. The script writes a new file and reopens it, so `applied` and `not_applied` tell you what actually persisted.
+
+## Split
+
+```bash
+"<python>" "<skill>/scripts/split_pages.py" --input "<file.pdf>" --out-dir "<parts>" --ranges "1-2,3,5-"
+```
+
+1-based inclusive ranges, `--every N` for equal chunks, default one file per page. The script copies the source metadata, refuses overlapping or out-of-range ranges, and fails if the parts do not add up to the source page count — that check is what catches a typo in the range string. `--prefix` sets the filename stem.
+
+## Direct page-tree work
+
+Reorder, duplicate, or delete with pypdf when `page_ops.py` does not fit:
+
+```bash
+"<python>" - <<'PY'
+from pypdf import PdfReader, PdfWriter
+reader = PdfReader("in.pdf")
+writer = PdfWriter()
+order = [2, 0, 1, 0]            # 0-based; repeat an index to duplicate a page
+for index in order:
+    writer.add_page(reader.pages[index])
+writer.add_metadata({"/Title": "Reordered"})
+with open("out.pdf", "wb") as handle:
+    writer.write(handle)
+print("pages", len(writer.pages))
+PY
+```
+
+`add_page` copies the page and its resources into the new file; annotations that point across pages (links) can break when their target is removed. After a reorder or deletion, check the links and bookmarks on the render, not only the text.
+
+## Rotate
+
+Page rotation is a `/Rotate` entry (multiples of 90) applied by viewers; it does not transpose the content stream. `page.rotate(90)` in pypdf, or `page_ops.py --rotate 90 --pages ...`, is enough. If a page was scanned sideways and also carries a stale `/Rotate`, the two add up — the render shows whether you are looking at the wrong one, and `scripts/render_pages.py` reports each page's rotation.
+
+## Verify
+
+After any structural edit:
+
+- compare page counts (`pdf read` or the split report) — one missing page is easy to miss in a long render;
+- render at least the first and last page of every part, and every page you rotated or reordered;
+- for merges, confirm the page size and orientation of the appended pages did not change, and that page numbers or bates stamps do not collide;
+- for deletions of numbered pages, tell the user which numbers were removed, because the remaining page labels will shift.
+
+`scripts/render_pages.py --input "<file.pdf>" --region 0,0,1,1 --json-out ...` prints per-page character and drawing counts, which is a cheap way to confirm a page is not blank before you deliver.

package/assets/skills/office-pdf/tasks/forms.md

@@ -0,0 +1,67 @@
+# AcroForm inspection and filling
+
+A form PDF carries `/AcroForm` in the catalog. Its `/Fields` array holds field dictionaries: `/T` the partial name, `/FT` the type (`Tx` text, `Btn` button, `Ch` choice, `Sig` signature), `/V` the value, `/Ff` flags, `/DA` the default appearance, and `/AP` appearance streams. A widget is the field's visual rectangle (`/Rect`, `/P` parent page, `/AS` its currently selected state name). A field can own several widgets (radio groups), and a widget can be a separate object from its field, reached through `/Parent`. Text in a filled field is usually not in the page content stream — it lives in the widget's `/AP /N` appearance, which is why "the value is in `/V`" and "the page shows the value" are two different facts to check.
+
+## Inspect first
+
+```bash
+"<python>" "<skill>/scripts/forms.py" inspect --input "<file.pdf>"
+```
+
+Reports, per field: id/name, type, value, read-only/required, widget count, page numbers, current states for buttons, and whether each widget has an `/AP` stream. Read the whole report before touching values: duplicate names, missing appearance streams, and read-only flags are the usual reason a fill "does nothing".
+
+## Fill
+
+```bash
+"<python>" "<skill>/scripts/forms.py" fill --input "<file.pdf>" --out "<file-filled.pdf>" --values "<values.json>"
+```
+
+```json
+{ "full_name": "Ada Lovelace", "email": "ada@example.org", "agree": true, "plan": "/basic" }
+```
+
+Text fields take strings, checkboxes take booleans or the state name, radio groups take the state you want selected, choice fields take a string or list. The dictionary is keyed by field name (`/T`, nested names joined with dots). The script fails with a non-zero exit when a name does not exist instead of silently skipping it, when a value is not one of the allowed states, and when the saved file fails the verification below. Pass `--flatten` to bake the values into the page and drop the form.
+
+## The discipline that makes a fill real
+
+pypdf writes `/V` and rebuilds the widget appearance. Both must be re-checked after saving, because a writer can update one and not the other:
+
+1. Reopen the saved file.
+2. For every field you set, read `/V` from the field dictionary and compare it with the requested value.
+3. For every widget, confirm `/AP /N` exists and is a non-empty stream with a `/BBox`; for radio and checkbox groups, confirm `/AS` names a state that exists in `/AP /N`.
+4. Render the page and look at the field.
+
+Steps 1–3 catch a stale or missing appearance; step 4 catches a `/V` that is right while the page still shows the old text. The script does 1–3 itself and prints `applied`/`not_applied`; treat `not_applied` as a failure to fix, never as a warning.
+
+When you build the check by hand:
+
+```bash
+"<python>" - <<'PY'
+from pypdf import PdfReader
+reader = PdfReader("filled.pdf")
+fields = reader.get_fields() or {}
+root = reader.trailer["/Root"].get("/AcroForm")
+for name, field in fields.items():
+    widgets = field.get("/Kids") or []
+    for widget in widgets:
+        states = list((widget.get("/AP", {}).get("/N", {}) or {}).keys())
+        print(name, field.get("/V"), widget.get("/AS"), states, "bbox" in str(widget.get("/AP")))
+PY
+```
+
+Radio groups are the common failure: pypdf updates the group `/V`, but the widget-level `/AS` for the previously selected button can stay behind, so two buttons look selected. The script resynchronises every widget's `/AS` from the group value; if you fill by hand, do the same.
+
+## Flatten
+
+Flattening is for files that must no longer be editable. Update with `flatten=True` (the value is painted into the page content), then remove every widget annotation (`subtypes="/Widget"`) and drop `/AcroForm` from the catalog. Verify afterwards: no `/Widget` annotations remain and the catalog has no `/AcroForm`. If widgets remain, the file still looks editable in readers even though the content carries the value.
+
+## What cannot be filled, and the fix
+
+- **A field with no appearance stream and a broken `/DA`**: the reader may refuse to show a new value. Render after filling; if the value is invisible, rebuild that widget's appearance with reportlab and merge it over the page.
+- **A signature field (`/FT /Sig`)**: signing requires a certificate and a signer implementation that this runtime does not ship. Adding text to a signed field invalidates the signature. Tell the user the signature cannot be created here and what would (a certificate plus a signing tool).
+- **A form where the values are drawn as static text, not widgets**: the file is not a form. Inspect with `page.get_text()` — if the labels and lines are plain content and `reader.get_fields()` is empty, treat it as an edit job, not a fill job.
+- **A flat, scanned form**: no field tree exists; filling means drawing text at coordinates (a stamp overlay) and the render decides whether it lines up.
+
+## Verify
+
+Always: reopen, check `/V`, check `/AP`, then `"<python>" "<cli>" pdf render --input "<file-filled.pdf>" --out-dir "render"` and `read_image` the page. The filled value must be visible inside its widget box, without clipping or overlapping the box border.