Start with a reference ledger before moving anything
The safest way to reorganize EPUB illustrations is to count every reference before moving the image. Record which manuscript contains the reference, preserve the old relative path, and require the same per-file count at the new path. This article is about preventing a broken reference during a planned move, not diagnosing an image after it has already disappeared.
The article-specific test began with two references across C02.md and C04.md. After the image was moved into assets/illustrations and both references were explicitly rewritten, the old path appeared zero times and the new path appeared twice. The result remains partial: it proves reference-string consistency in the test copy, not automatic tracking or visual rendering.
Use two manuscripts and two references as the sample
The planned example names the illustration images/port.png and places one reference in each manuscript. The executed fixture used map.png in the same role and moved it to assets/illustrations/map.png. Its starting values were:
- Manuscripts: C02.md and C04.md
- References before the move: 2 across 2 files
- Per-file count: 1 in C02.md and 1 in C04.md
- Destination directory: assets/illustrations
Because the planned and executed filenames differ, the evidence is not presented as a successful test of port.png itself. It demonstrates the two-file reference-control method.
Define a product-independent move procedure
Search the manuscript set for the old path and save the filename and count for every match. Create the destination, move the image once, update only the recorded source files, and then search for both the old and new paths.
The move passes only when the old path has zero matches, the new path has two, and each manuscript still contributes one match. If any count differs, undo the reference edits, return the image to its original location, and restart from the saved ledger. That rollback point is more reliable than trying to reconstruct the original layout from memory.
The measured run used an explicit rewrite
The run opened the workspace, collected reference usage, reviewed the change from images/map.png to assets/illustrations/map.png, moved the file, and explicitly rewrote both manuscript references. Two occurrences were changed.
This order keeps the file operation and the text operation observable. Searching immediately after the move reveals stale references, while counting the new path per manuscript catches the common mistake of repairing one chapter and overlooking another.
The measured result was old 0 and new 2
The article-specific Stage 4 values were references_before=2, reference_files_before=2, rewritten_occurrences=2, old_path_matches=0, and new_path_matches=2. The final distribution was one reference in C02.md and one in C04.md. planned_files was 0, so this record does not establish an automatic update plan; the two occurrences were aligned by the explicit rewrite.
A separate common Stage 4 check used a four-item workspace tree and confirmed one reference before a move and one rewritten reference after it, including a read-back. That common check did not establish Finder tag colors or expansion state after relaunch.
Keep the partial boundary visible
The evidence supports one narrow conclusion: in a dedicated test copy, the two old references were replaced with two new references. It does not verify automatic tracking after a Finder or cloud-sync move, collaborative edits, changes made outside the workspace, or appearance in an EPUB reader. Image content and alt-text quality were also outside the test.
Zero old-path matches therefore do not prove that the illustration will render. Confirm that the asset exists at the destination, that the reference count is preserved, and, when export is in scope, that the packaged EPUB contains the image.
Separate Rune Studio’s public scope from this test
Rune Studio’s documented Mac feature set can update relative image and link paths in txt, text, md, and markdown files when files are moved or renamed inside a workspace. Parent-directory paths using ../ are supported. External URLs and page anchors are not rewritten, and deletion is handled as a warning case. Those are public product capabilities, not observations from this article-specific run.
The Stage 4 fixture used an explicit reference rewrite. It must not be cited as proof that these two references followed the image automatically.
Finish only when both manuscripts reconcile
For this sample, completion means one new-path reference in C02.md, one in C04.md, and no remaining old-path references. If those values do not reconcile, move the image back and restore the two ledger entries before attempting another reorganization.
The practical safeguard is simple: record two references before the move and recover the same two references afterward. This test reached reference consistency, while rendering and external-environment checks remain separate work.
