Read a template's paragraphs (paginated) so the chatbot can understand its structure before composing edits.

USE WHEN: You want a sequential, page-aware view of the template — e.g. to scan section headings, see how bullets are organized, or quote surrounding context for the user. DO NOT USE WHEN: You just need a flat list of every editable spot — use list_template_targets() instead.

Provide the template either as template_path (file on the server's machine) or as template_b64 + template_filename (inline base64 bytes for cross-filesystem calls). Paginate large documents with start + limit; next_start in the response says where to resume.

List every editable target in the template (paragraphs, runs, cells, tables, images) so the chatbot can build a precise edit list.

USE WHEN: Canonical first call before fill_and_save. You need target_ids

• text_hashes to construct edits, and char_count / display_width / max_recommended_chars to keep generated content within container limits. DO NOT USE WHEN: You only need a human-readable overview — use inspect_template instead.

Provide the template either as template_path or as template_b64 + template_filename. Filter with target_kinds (any subset of {paragraph, run, cell, table, image}); leave None for all kinds. Paginate via start + limit; next_start is non-None when more targets remain. (max_targets is a deprecated alias for limit.)

Each target carries (where applicable):

• target_id, target_kind, current_text, text_hash

• char_count (code points), display_width (EAW-aware), max_recommended_chars

• page_number

• parent_paragraph_id / parent_table_id — the container

• row_index / column_index / rowspan / colspan — for cells

One-call summary of a template's overall shape — page count, target counts by kind, and a small text sample.

USE WHEN: first encounter with a template. You want to know format, page count, presence of tables/images, and a sample of headings before pulling the full target list. DO NOT USE WHEN: you already need the full edit list — go straight to list_template_targets().

Provide the template either as template_path or as template_b64 + template_filename.

Returns: dict with source_doc_type, total_paragraphs, target_counts (per target_kind), page_count, top_paragraphs (first 5 non-empty), has_tables, has_images.

Apply a batch of edits to the template and write/return the result.

USE WHEN: You have called list_template_targets() and composed an edits list mapping the chatbot's generated content into the right target_ids. DO NOT USE WHEN: You have not yet fetched target_ids and text_hashes from list_template_targets() — fill_and_save will fail validation.

INPUT modes: provide the template via template_path OR template_b64 + template_filename.

OUTPUT modes: provide output_path (server-side write) OR set return_output_bytes=True (response includes output_b64). Required unless dry_run=True. Use bytes when the chatbot is in a different filesystem than the MCP server.

Each edit dict must include edit_type ("text" | "structural" | "style") plus the fields required for that type:

• text: target_id, expected_text_hash, new_text (+ optional target_kind, reason)

• structural: operation, target_id (+ position, text/rows/values, row_index, column_index)

• style: target_id (+ any style fields: bold, color, font_size_pt, etc.)

STYLE EDIT TARGETING: Run-level fields (bold / italic / underline / color / font_size_pt) must use target_kind='run' against a run target. Paragraph-level fields (paragraph_align / left_indent_pt / etc.) use target_kind='paragraph'. Mixing the two raises a clean style_field_target_mismatch response.

BUILT-IN ROBUSTNESS:

1. Auto-skip of container/child edit conflicts (cell↔paragraph, paragraph↔run). Skipped entries in skipped_redundant_edits.

2. Pre-check for duplicate target_id.

3. Output extension validation.

4. Defensive type coercion (None edits → empty list).

Output format follows the template: DOCX→DOCX, HWP/HWPX→HWPX. PDF input cannot be written back as PDF.

Returns: dict with

• status: ok / dry_run_ok / validation_failed / apply_failed / edit_parse_failed / not_found / duplicate_target_id / style_field_target_mismatch / format_requires_java / file_error / permission_error / runtime_error / bad_argument / output_extension_mismatch / format_not_writable

• output_path OR output_b64 + output_size_bytes (status=ok)

• length_safe, length_warnings, skipped_redundant_edits

• recovery_hint (when status != ok)

• edits_applied