Finish the insertion decision before reorganizing files
When an image will be inserted and later moved, lock down its manuscript position, relative path, and alt text first. Then record the reference count, move the asset, update the reference, and inspect the exported EPUB. Combining insertion and relocation makes it difficult to tell whether a failure came from the markup or the move.
The article-specific sample used two chapters, one inline image, and no cover. One pre-move reference became zero old-path matches and one new-path match after an explicit rewrite. The EPUB contained one image, zero missing images, five spine items, two chapter links in both nav and NCX, and valid=true. The status remains partial.
Design one image for the third paragraph
The planned scenario places diagram01.png in the third paragraph of chapter01.md with descriptive alt text; chapter02.md has no image. The executed fixture used figure01.png in the same one-image role and moved it from images/figure01.png to assets/illustrations/figure01.png.
The starting values were two input chapters, one inline image, no cover, and one reference before the move. The recorded result values do not capture the third-paragraph position or the alt-text wording. Those remain design requirements, not measured successes.
Split insertion and relocation into two stages
First add the image with a path relative to the manuscript and review its position and alt text. Save the old-path reference count. Then create the destination, move the image once, update the reference, and require zero old-path matches and one new-path match before exporting.
The process fails if the old path remains, if the new path appears more than once, or if the EPUB does not contain the image. Undo the reference edit, return the image to images, and restart from the single verified insertion.
The run connected one moved reference to a two-chapter export
Stage 4 created two chapters and one image, collected reference usage, reviewed the move, moved the asset into assets/illustrations, explicitly rewrote one reference, and searched both path values. It then set series and volume data, selected the manuscripts, reviewed the plan, exported, inspected, and read the package, nav, NCX, and XHTML. command_count was 17.
planned_reference_files was 0, so this one occurrence cannot be presented as automatic tracking. The measured update was explicit.
The result was old 0, new 1, and packaged 1
Reference values were references_before_move=1, rewritten_occurrences=1, old_path_matches=0, and new_path_matches=1. Export values were input_chapters=2, inline_image_files=1, cover_files=0, image_count=1, missing_images=0, spine_count=5, nav_item_count=2, ncx_item_count=2, and valid=true.
These values show that one reference pointed to the new path and one image entered the two-chapter package. They do not establish the third-paragraph placement, the quality of the alt text, or visual image quality.
A separate common Stage 4 run exported four chapters, one image, and version 1.8, producing spine 8, zero missing images, nav and NCX, and valid=true. It is supporting evidence from a different fixture.
Partial preserves the insertion-quality boundary
The run did not verify the planned third-paragraph position, appropriate alt text, automatic tracking after Finder or cloud moves, rendering in every reader, or KDP acceptance. valid=true applies only to the local package inspection.
An image can be present in the package and still be poorly placed or described. Position and alt text therefore remain visual and editorial checks.
Rune Studio supports the workflow as documented
Rune Studio’s documented Mac capabilities support image references in Markdown-family manuscripts, relative-path updates after workspace moves or renames, and packaging images into EPUB 3. Parent-directory references using ../ are included, while external URLs and page anchors are not rewritten.
That is Stage 3 product scope. This Stage 4 run established one explicitly rewritten reference and one packaged image.
Reconcile one reference and one packaged asset
For this fixture, the measured gate is old 0, new 1, packaged images 1, missing images 0, two chapter links in each navigation structure, and valid=true. Before publication, separately review the planned insertion position and alt text.
The key is to complete insertion before treating relocation as a separate operation. The current values support reference and package consistency; insertion quality and automatic tracking remain outside the partial result.
