Pdfcraft Documents

---
name: pdfcraft-documents
description: "Edit, secure, fill, sign, redact, OCR, compare and check PDFs in PdfCraft (ArtCraft's Acrobat-class PDF editor, driven through the `pdfcraft` MCP server, tools mcp__pdfcraft__*). Use whenever the user mentions PdfCraft or the pdfcraft MCP tools, or asks to work on an existing PDF in/with PdfCraft: reorganise pages (merge, split, extract, rotate, reorder, delete), edit text, add text/images/stamps/watermarks/headers/footers/bookmarks/links, fill or build forms, redact or sanitise sensitive content, sign or certify, OCR scans, compare versions, make it accessible (PDF/UA tags, alt text), convert to PDF/A, protect with passwords, reduce size, export to Word/text/images. Covers the safe-copy workflow, redaction apply-and-verify, render-and-verify, save and the mandatory show-and-approve phase. Not for cases where the user explicitly asked for another tool or format (a PDF generated by code/reportlab/LaTeX, the generic pdf skill's scripts, Word/Docs documents, spreadsheets, slides)."
license: MIT
metadata:
  author: dnviti
  version: "1.0.0" # x-release-please-version
---

# PdfCraft documents

PdfCraft is an Acrobat-class PDF app (page organiser, text and object editing, forms, redaction,
digital signatures, OCR, accessibility checker, compare, PDF/A, optimiser). You drive it through
the `pdfcraft` MCP server (`pdfcraft-cli mcp`). This skill says **how to work safely, which tool
does what, how to verify, and how to hand the file to the user**.

- Task map (tool per job, with params): `references/task-map.md`
- Recipes (redaction, form, sign, OCR, compare, accessibility, merge/split, protect): `references/workflows.md`
- Traps and fixes: `references/gotchas.md`

## 0. Ground rules for the tools

The tools are deferred: load schemas with ToolSearch before calling (`select:mcp__pdfcraft__doc_open,
mcp__pdfcraft__page_render,...`; a keyword query returns at most ~40 at a time, so select by name).
There are ~170 tools; the registry commands (`command_list {filter}` -> `command_run {id, params}`,
`command_batch {steps}`) map onto the same tools (`doc.compare` = `doc_compare`), so prefer the named
tools. Unknown params are ignored with a warning: read `warnings`.

- **Session model**: `doc_open {path, password?}` returns a **document id** (`doc`); every other tool
  takes it. `doc_create {from: blank|images|text}` makes an unsaved doc. `doc_list` shows open docs and
  dirty state. Edits live **in memory** and are undoable (`edit_undo`/`edit_redo`) until `doc_save`.
  `doc_close {doc, discard_changes:true}` when finished.
- **Coordinates**: points (1/72 inch), **origin top-left, y down**, page numbers **1-based**, for
  `rect [x0,y0,x1,y1]`, `at [x,y]`, text_find rects, comments, form `rect`. Exceptions: `doc_compare`
  rects and `form_detect_fields` rects are **bottom-left** origin (PDF space); `doc_watermark offset_y`
  is up-positive. US Letter is 612x792, A4 595x842.
- Page ranges are arrays (`pages:[1,3,5]`); `doc_combine` takes range strings (`"1-3, 6"`).
- Text edited or added must be Western European (WinAnsi) in standard fonts (helvetica/times/courier)
  unless the build has extra faces; unsupported characters draw as `?` (see `warnings`).
- `render_preview {doc, page, max_side}` (PNG, default 1024) and `page_render {doc, page, dpi}`
  (default 96, max 600) show what a page really looks like; neither changes the document.
- Path confinement: the server may be started with read/write roots; a refused path says so.
- `pdfcraft-cli` (shell): `info`, `render`, `text`, `edit`, `combine`, `extract`, `split`, `audit`
  (faux-redaction finder, non-zero exit if found), `check`, `batch`. Handy for independent checks.

## 1. Workflow

1. **Understand the job and the file**: what must change, what must not; is it signed, encrypted,
   scanned (no text), a form (AcroForm/XFA)? `doc_open`, then `doc_info` (pages, sizes, metadata, bookmarks,
   annotations, form fields, signatures, security, fonts, repair notes) and `render_preview` of the first
   pages. `text_extract` empty on a page means a scan: OCR first if text work is needed.
2. **Work on a copy** (section 2). Never modify the user's original.
3. **Plan** the edits in order of structure: pages first (organise), then content (text/images),
   then annotations/forms, then redaction, then metadata/accessibility, then security/signature last.
   Signing and encryption must be the final steps: any later change breaks the signature (or must
   be a permitted incremental change).
4. **Edit** with named tools; batch same-kind edits; check each result's `warnings`.
5. **Verify loop** (section 5): render the changed pages, extract text, run the task-specific audit.
6. **Save** to a new file (section 6).
7. **Show and approve** (mandatory, always last): section 7.

State the acceptance checklist before mutating; report at phase boundaries.

## 2. PDF safety rules (non-negotiable)

- **Keep originals.** Never overwrite or modify the source file unless the user explicitly asked.
  Save results to a **new file** next to it or in the project dir (`contract-redacted.pdf`,
  `form-filled.pdf`). `doc_save` with `path` is a full rewrite to a new file (original untouched);
  `doc_save` **without** `path` saves in place (incremental update): do that only when told to.
  If the target name exists and the user did not ask to replace it, pick another name.
- **Redaction must be applied AND verified**: `redact_mark` alone removes nothing. After
  `redact_apply`, **save, reopen the saved file** and prove the content is gone (recipe in
  `references/workflows.md` A): `text_find`/`text_extract` for each sensitive string, `doc_audit_redactions`
  (must report zero findings), render and look, `doc_hidden_info` for metadata/comments/attachments/form
  fields/hidden text that still carry the data, and optionally `pdfcraft-cli audit` + `pdftotext` on the saved
  file. Never "redact" by drawing a black rectangle (`comment_add rectangle`, `page_add_*`) over text:
  that is a faux redaction and the text stays extractable. Redaction is irreversible once saved;
  say so, keep the unredacted original, and don't send/upload the original.
- **Sanitise on request** (`doc_hidden_info` shows categories; `doc_remove_hidden` removes them and
  flattens form fields). Remember metadata (Title, Author, XMP) can leak names.
- **Signatures**: `sign_document` always saves to `out` and the document then shows the signed file.
  Do not edit a signed PDF without telling the user it invalidates (or adds a revision to) the
  signature; certify levels restrict changes. `sign_list` validates (status valid / unknown = untrusted
  self-signed / invalid). A self-signed ID is "unknown" until `sign_trust` is given its certificate.
  Never create or use a digital ID, password or signature image on someone's behalf without being given
  it/asked; a typed "signature" (`fill_sign_add`) is a visual mark, not a cryptographic signature.
- **Passwords**: choose none by yourself; use the user's. Don't echo them. `doc_protect` applies at the
  next `doc_save` (full rewrite). Keep the unprotected original.
- **Compare/OCR/optimise write new files**; they leave the open document unchanged.
- Don't fabricate content in legal/financial documents: edit only what was asked; show before/after.

## 3. Tool families (details in `references/task-map.md`)

| Job | Tools |
|---|---|
| Open/create/save | `doc_open`, `doc_create`, `doc_save`, `doc_close`, `doc_list`, `doc_info`, `doc_inspect` |
| Pages | `page_delete/move/rotate/extract/duplicate/reverse/replace/insert_blank/insert_file/set_box/number`, `doc_combine`, `doc_split` |
| Text | `text_extract/find/lines/paragraphs/fonts/word_count`, `text_edit`, `page_add_text`, `content_list/update/copy/delete` |
| Images/objects | `page_add_image`, `page_images`, `image_edit`, `object_list/move`, `doc_export_images/all_images` |
| Marks | `doc_watermark`, `doc_background`, `doc_header_footer`, `stamp_custom`, `doc_remove_marks` |
| Navigation | `bookmark_*`, `link_*`, `links_from_urls`, `doc_initial_view`, `attachment_*` |
| Comments | `comment_add/list/edit/reply/set_status/delete`, `comments_summarize/hide` |
| Forms | `form_fields`, `form_fill`, `form_add_field`, `form_detect_fields`, `form_set_props`, `form_reset`, `form_tab_order`, `doc_import_data/export_data`, `doc_flatten` |
| Redaction/privacy | `redact_mark/apply/clear`, `doc_audit_redactions`, `doc_hidden_info`, `doc_remove_hidden` |
| Signing | `sign_id_create`, `sign_document`, `sign_list`, `sign_trust`, `fill_sign_add` |
| OCR | `ocr_status`, `ocr_recognize`, `ocr_recognize_files`, `page_enhance_camera` |
| Accessibility | `accessibility_check/fix/report/tags/figures/set_alt/autotag_*` |
| Compare | `doc_compare {doc:newer, other:older, visual?}`, `doc_compare_mark`, `doc_compare_report` |
| Standards/size | `pdfa_verify/convert`, `print_readiness`, `doc_optimize`, `doc_reduce`, `doc_audit_space` |
| Security | `doc_protect`, `doc_unprotect` |
| Export | `doc_export_text`, `doc_export_office` (.docx/.pptx/.html/.rtf by extension), `doc_export_data` |

## 4. Domain know-how

- **Form filling**: `form_fields` for names/types/options/required; `form_fill {values:{name:value}}`
  (text/combo/radio: string; checkbox: true/false; multi-select list: array). A PDF with no fields: use
  `form_detect_fields {add:true}` to create fields from blanks, or `fill_sign_add` to place text/check marks.
  Verify by `form_fields` and a render. Keep the form editable unless asked to flatten (`doc_flatten`).
  XFA forms: `xfa_to_static` first (irreversible for scripts; ask).
- **Added marks belong to the document**: headers/footers, stamps, watermarks and added text take the
  standard face closest to the existing type (`text_fonts`), its colours and its margins, not a stock
  grey diagonal "CONFIDENTIAL" in Helvetica, unless the user asks for exactly that.
- **Merging/splitting**: `doc_combine {paths, pages?, out}` (ordered; keeps bookmarks, renames clashing
  form fields); `doc_split {doc, every|before|bookmarks|max_mb, out_dir}`; `page_extract`.
- **Text edits**: `text_paragraphs {page}` gives paragraph numbers and boxes; `text_edit {paragraph|line,
  text, font, size, color}` rewraps in place with standard fonts; for scans OCR first. Edited text may not
  match the original embedded font exactly: render and compare.
- **Accessibility**: `accessibility_check` (32 rules) -> fix what can be fixed (`accessibility_fix`
  title/primary-language/tab-order; `accessibility_set_alt` for figures; `accessibility_autotag_*` only for
  simple untagged text-only/forms). The checker never certifies compliance: report failed and manual rules
  honestly. Set the document Title (`doc_set_info`) and language.
- **PDF/A**: `pdfa_verify` -> `pdfa_convert {level:"2b"|"3b"}` -> verify again; non-embedded fonts remain
  as unfixable findings.
- **Size**: `doc_optimize {path, preset:"standard"|"mobile"}` or `doc_reduce {path}`; compare sizes, render
  to check legibility; signed documents are refused.
- **OCR**: `ocr_status` first (English only); `ocr_recognize {pages, dpi}` adds invisible text over the scan;
  verify with `text_find` and by spot-checking text vs image (OCR errors on numbers/names matter).

## 5. Verify loop (mandatory)

After each phase on the working copy:
1. `doc_info` / `doc_list`: page count, dirty state, fields, signatures, security as expected.
2. `render_preview`/`page_render` every changed page and **look**: placement, clipping, overlap, fonts.
3. Content: `text_extract`/`text_find` to confirm presence (edits) or absence (redactions).
4. Task audit: `doc_audit_redactions`, `sign_list`, `accessibility_check`, `pdfa_verify`, `form_fields`,
   `doc_compare` of original vs result (only the intended changes appear).
5. Fix with `edit_undo`/new edits; repeat.
For saved results, **reopen the saved file** (`doc_open` on the new path) for the final check, not only
the in-memory doc.

## 6. Save / export

- `doc_save {doc, path:"/abs/new.pdf"}` (new file, full rewrite, atomic). `flatten_fill_sign:true` bakes
  Fill & Sign marks in. `full:true/false` forces rewrite/incremental. Encryption and sanitising take
  effect in the save.
- Other outputs: `doc_export_office {path:".docx|.pptx|.html|.rtf"}`, `doc_export_text`, `doc_export_images`,
  `doc_optimize`, `doc_split`, `page_extract {out}`, `doc_compare_report {path}`: all create new files;
  tell the user the paths.
- Close docs and delete scratch files afterwards.

## 7. Show and approve (mandatory final phase)

Every PDF job ends here, after the verify loop. The headless `pdfcraft-cli mcp` session has no window,
so the user cannot see the result until you save it and open the real app on it.

1. **Save to a new file** (never over the original unless the user said so) with `doc_save {path}` in
   the project directory or the path the user named; descriptive name (`contract-redacted.pdf`); for signed
   output the `out` of `sign_document`. Note the full absolute path. Reopen it once to verify.
2. **Open PdfCraft on that file**, detached so it doesn't block:
   `setsid pdfcraft /abs/path/result.pdf >/dev/null 2>&1 &`
   (`pdfcraft [options] [files...]` is the desktop app, `/usr/bin/pdfcraft`, MIME `application/pdf`;
   optional `--page N`, `--zoom 150`, `--theme dark`, `--new-window`. If a PdfCraft window is already
   running, the file is passed to it.)
3. **Stop and ask.** Give the full path (and the original's path, kept untouched) and ask the user to accept
   the result or describe changes. Never continue on your own: nothing is sent, uploaded, emailed, signed,
   deleted, replaced or exported to another format/handed to another tool before explicit acceptance.
   Silence or a vague reaction is not acceptance. For redactions, ask the user to look at the black boxes.
4. **Loop on changes**: apply them (from the in-memory working copy or a fresh `doc_open` of the saved file),
   re-run the verify loop, save again (new version name or the same new file), reopen/refresh PdfCraft,
   ask again, until accepted.
5. **Inside a subagent** (cannot talk to the user): do steps 1 and 2, then return the file path, the
   original path, a short summary of changes, the verification results, and state clearly that **user
   approval is pending**. The orchestrator asks the user and relays changes back.

## 8. Top gotchas (more in `references/gotchas.md`)

- `redact_mark` removes nothing; `redact_apply` + save + reopen + audit does. Black rectangles are not redaction.
- `doc_save` without `path` overwrites in place: never by default.
- `sign_document` writes `out` itself; sign last; later edits break signatures.
- Coordinates: top-left origin, points, 1-based pages (compare and detect_fields rects are bottom-left).
- `doc_protect` and `doc_remove_hidden` only apply at the next save (full rewrite).
- `doc_compare {doc: newer, other: older}`: order matters.
- Scans have no text: OCR before searching/redacting by text; `redact_mark rect` works without text.
- Added text is limited to standard fonts/WinAnsi; others draw `?`.
- Open docs stay in the session: close them and delete scratch files.