manor-os/manor-ai/file-engine

File Engine

Use this skill when the user asks to create, update, or AI-edit a Knowledge file and no more specific file-type skill has already taken over.

Workflow

1. Use inspect_file_engine when you are unsure whether a file type supports patching.
2. Use search_documents or list_documents to resolve the user-visible Knowledge file.
3. Use read_file with the resolved fs_path before editing. Keep its source_sha256 (the exact file-byte hash, including formatting). Pass include_structure=true to obtain DOCX paragraph/table indices, PPTX slide/shape IDs and first-master layout indices, or Excel sheet/table/column names. Never guess selectors; if the bounded structure result is truncated, do not assume omitted items are absent.
4. Use generate_file when creating a new file, including format conversion with source.
5. Use patch_file when editing an existing file. Pass expected_sha256 from read_file.
6. Use replace_file only when the user wants one existing file's exact bytes to overwrite another existing file. Read both files first and pass both returned SHA-256 values. It preserves the target path and Knowledge document identity, leaves the source unchanged, and never creates a missing target.

Do not regenerate an existing Office file just to make a small edit. Patch the existing file so the original package structure, editable source, and Knowledge document identity are preserved. When a change needs several edits to the same file, send them as multiple ordered operations in one patch_file call so they are saved through one Knowledge projection.

Convert an existing file

For Office-to-PDF conversion, call generate_file(kind="document", source={"path": "original.docx", "expected_sha256": "<source_sha256 from read_file>"}, name="converted.pdf", file_type="pdf"). This converts the exact original file with LibreOffice and creates a new Knowledge Document; do not pass extracted text as content or invoke a sandbox skill just to convert a supported file. The source stays unchanged. DOCX/PPTX/XLSX/XLSM and legacy DOC/PPT/XLS/WPS/DPS/ET can be exported to PDF; legacy files can also be converted to their corresponding DOCX/PPTX/XLSX format. inspect_file_engine reports the exact pairs and size limits. PDF-to-Office is not supported. Fonts available on the server can affect pagination, so inspect the result before claiming exact layout fidelity. If conversion fails, report the error; never silently replace the document with a text-only reconstruction.

Current patch coverage

For image format conversion (including HEIC/HEIF), read the uploaded image's resolved path with read_file(include_image=false), then call generate_file(kind="image", source={"path":"<resolved_path>","expected_sha256":"<source_sha256>"}, name="converted.png", file_type="png"). Call once per image when converting several attachments. PNG, JPEG and WebP outputs preserve full resolution and apply EXIF orientation; PNG/WebP keep alpha, JPEG uses a white background. This deterministic conversion requires no media model search, generation provider or sandbox. The source stays unchanged and the result is a new Knowledge Document. Multi-frame images and images over 40 megapixels are rejected rather than silently losing frames or resizing.

Template layout operations use the same executor in generation and patching:

• paragraph.format targets the same paragraph as text.set, without replacing text. Its non-empty format accepts bold, italic, underline, strike (booleans), font_name, font_size, font_color (six RGB hex digits), alignment (left, center, right, justify), space_before, space_after, indent_left, indent_right, first_line_indent (points), and line_spacing (a line-height multiple). Negative first-line indents create hanging indents. Word also accepts keep_with_next, keep_together, page_break_before, widow_control booleans and an existing paragraph style name (a style alone is allowed). PPT accepts level 0–8; changing level selects the existing list level, not a new bullet definition. Other text, links and properties remain unchanged. All existing runs and empty-paragraph typing styles are formatted; mixed-run range styling is not yet supported. The same plain-paragraph restrictions as text.set apply.
• page.setup changes page geometry through a non-empty format in points. Word requires zero-based section_index and supports width, height, margin_top, margin_bottom, margin_left, margin_right, header_distance, footer_distance. Set explicit dimensions to change orientation; width greater than height is landscape. Margins must leave positive content space. PPT supports whole-deck width/height (72–4032 points); this changes the canvas only, never scales or moves existing objects. Use shape.transform for an intentional object-layout adjustment. Word distances require twentieth-point precision, PPT distances hundredth-point precision; font sizes keep their existing half-/hundredth-point limits.

read_file(include_structure=true) reports Word sections, paragraph_styles, paragraph_style_definitions, native text_boxes and body/header/footer inline or floating pictures, PPT page_size, explicit shape/picture format and bounded native chart data/format, and Excel sheet layout/page_setup plus bounded native table/merge/data-validation/conditional-format/picture/chart selectors, metadata, references and data, so template selectors and dimensions can be inspected before modification. PPT inherited theme styles are not materialized in this discovery result. These are runtime document operations, not a new tool or MCP. Do not claim full template parity for unsupported inherited or vendor-extension features.

Word/PPT text.set replaces exactly one existing plain-text paragraph, even if empty or duplicated elsewhere. DOCX uses a zero-based story-local index; omit story for the body, pass a header/footer story plus section_index, or pass package-wide text_box_index plus that text box's local paragraph index. PPTX uses one-based slide, slide-unique text-frame shape_id (top-level or inside a group), and zero-based paragraph index. Discover these with read_file(include_structure=true); Word reports story_structures and text_boxes, while PPT shapes report group_path, has_text_frame, paragraph count and bounded indexed text samples. The required text string may be empty to clear content. Newlines become soft line breaks, not extra paragraphs; CRLF/CR normalize to LF. Paragraph layout, list properties, Word section properties, PPT geometry, and other paragraphs are retained. Replacement inherits the first text run's style/link, or an empty paragraph's saved typing style; it does not redistribute new text across old mixed styles. Text is limited to 32,767 characters with no invalid control characters. Fields, embedded content, revisions, annotations/bookmarks and explicit page/column breaks are rejected atomically; text.replace remains available for supported text around them. Table cells continue to use cell.set. This operation works identically during generation and patching.

Color formatting uses opaque RGB: previous theme/tint/brightness/alpha modifiers are cleared only when the corresponding color is explicitly set. PPT shape formatting can additionally specify fill/line opacity.