jiangnangenius/floe-agent/floe-pdf

PDF workbench

Follow this closed loop for PDF tasks:

1. Inspect first: document.pdf.inspect for page count, metadata, text, and query matches before planning any edit.
2. Render only relevant pages with document.pdf.render (single page or a spec like "1-3,5") when visual evidence is needed.
3. Compose: document.pdf.merge (2-10 PDFs in order), document.pdf.split (extract pages "1-3,5,8-10"), document.pdf.fromImages (one image per page).
4. Edit with document.pdf.edit: page removal, rotations, watermarks and page numbers. replaceText performs exact case-sensitive native content-stream edits, never a white cover. Existing-font replacements must fit the original bounds. For multi-object text or longer paragraphs, use operations action replaceRegion: inspect the native object inventory, pass the exact expectedObjectCount and enclosing bounds, and supply new text/fontSize. CoreText reflows and embeds searchable Unicode text; overflowing text, partial object intersections and mixed nested forms fail without saving. addText inserts a new text region. This is ordinary editing, not secure redaction.
5. Advanced operations require expectedSHA256 from the same inspection. Coordinates are unrotated PDF points with a lower-left origin. Page operations include reorderPages (every page exactly once), cropPage (visual crop only, NOT deletion), insertBlankPage. Annotation operations add/update/remove note, freeText, markup, shapes, ink and lines; use 0-based annotationIndex from the current revision. Images support insertImage/replaceImage/removeImage with workspace imagePath, explicit bounds and expected object count for removal. Images stretch to the rectangle; keep its aspect ratio when distortion is unwanted.
6. Forms and document structure: operations createField/setField/removeField support text, checkbox and choice fields. The existing document.pdf.fillForm provides additional AcroForm filling including radio/option lists. setMetadata updates title/author/subject/creator/keywords (empty value removes that attribute). setBookmarks replaces the top-level bookmark list. flattenAnnotations requires acceptFlattening after consent, preserves page content but removes interactivity; it is NOT secure redaction.
7. OCR and redaction: searchableOCR uses on-device Vision and rebuilds pages with a recognized, searchable text layer; text may contain recognition errors. rasterRedact rebuilds ALL pages from fresh raster images, masking selected regions before encoding. It copies no original text streams, annotations, forms, attachments, bookmarks or signatures, and verifies image-only output. Both must be the only edit operation and require the user's explicit acceptance of rasterization (acceptRasterization=true). Current bounded workflow accepts up to 50 unrotated pages with matching media/crop boxes. Do not describe ordinary covering, cropping, password protection or flattening as secure deletion. Do not claim PKI signature validation or vector-preserving secure redaction.
8. Credentials: output protection accepts only saved userPasswordRef/ownerPasswordRef references resolved inside the approved executor. document.pdf.unlock creates a new decrypted copy using passwordRef and verifies reopening; it requires the correct credential and PDF modification permissions, and rejects signed files. Never put plaintext passwords into tool arguments. Signed files are rejected for ordinary edits; only explicitly accepted rasterized unsigned copies are supported.
9. Save to a new output, reopen with document.pdf.inspect and render changed pages. Existing outputs are refused, including alternate spellings that resolve to the source. Report actual output, digest/reopen evidence and remaining limits. Never silently substitute rasterization or a different editing operation after failure.
10. Export: use document.pdf.export for real searchable text (text or page-structured json), not Word-layout conversion. Use document.pdf.render for png or jpeg page images. Empty text from scans requires the separate consented OCR workflow, never invented text.

File conversion without model rewriting

Use document.pdf.convert with file paths and a target format for Markdown, Word DOCX, HTML, RTF or text to PDF, and text PDF to those formats. Do not regenerate existing content through the model. PDF creation is paginated; PDF extraction preserves searchable text and page order, not original layout, embedded images or table structure. A scanned/image-only page fails explicitly; use the separate consented OCR workflow first. Source files remain unchanged and outputs must be new.