A picture can exist in the project and still disappear from the EPUB. The failure occurs when a manuscript continues to point at the picture’s old relative path. The useful question is not merely “Does this filename exist?” It is “Which source file refers to which path, relative to what directory?” Answer that question before moving an asset, preview the planned rewrites, and read the saved manuscript back from disk.
The STUDIO-163 controlled specimen moved assets/figure.png to moved/renamed-figure.png. Its source was draft/chapter.md. The following workflow ties each command to its input, destination, measured result, failure route, and acceptance condition.
Begin at the referring manuscript
Before the move, the manuscript contained one image reference: !Test figure. Looking only inside the asset directory cannot reveal where that old text remains. Identify the source file first and distinguish an image reference from an ordinary link.
This specimen also contained Notes. A broad replacement of every assets string could damage the notes link. The work ticket therefore named exactly one old image, one new image, and one referring document. Everything else was out of scope.
Relative paths are interpreted from the location of the referring file. Because the source lives in draft, the new stored reference must be ../moved/renamed-figure.png. Copying an absolute Finder path into Markdown would make the project depend on one computer and would not be an acceptable repair.
Record both ends of the asset move
The actual rune file move result identified the old fromPath under assets and the new path under moved. That proves the file operation, but it does not prove that any manuscript changed. Treat the move and the reference rewrite as two separate transactions.
Keep a recoverable copy until the new reference resolves. In a production project, use version control or a dated backup. The controlled run used an isolated STUDIO-163 workspace and did not modify a published EPUB or WordPress page.
If the destination already contains a file with the same name, stop and compare identities. A successful filesystem move to the wrong asset is still a content failure. Give project assets descriptive names when practical, and record the expected source hash when images are visually similar.
Count consumers with rune refs usage
The command rune refs usage --workspace <workspace> --path <old-image> reported one referring file and one occurrence. The consumer was draft/chapter.md. Those numbers describe references, not the number of image files in the folder.
A result of zero is not automatic permission to delete the old asset. The path may be misspelled, represented in another syntax, or used by a source outside the selected workspace. Open the manuscript and search for the literal old relative path. More matches than expected also require review because a cover, sample chapter, or archived source may not belong in the same rewrite.
Write the expected count beside the command result. That turns a vague “looks unused” judgment into a small contract that can be checked after the move.
Preview with refs plan, then apply refs rewrite
The planning command received the workspace, old asset path, and new asset path. It proposed one change in draft/chapter.md. The proposed replacement was the correctly recalculated relative path, not the asset’s absolute location.
Only after reviewing that candidate did the run apply rune refs rewrite. The execution also reported one changed occurrence. If planning reports one item but execution reports zero or several, reject the result. The manuscript may have changed between the two commands, or the selected workspace may no longer be the intended one. Read the current file and create a fresh plan.
This preview is especially important when directory names repeat. A text replacement that happens to produce a plausible string may still climb the wrong number of parent directories.
Read chapter.md back from its saved destination
The independent rune file read call returned the saved manuscript from draft/chapter.md. Its image line was !Test figure, while the separate notes link still targeted ../assets/note.txt. A follow-up reference check found zero old occurrences and one new occurrence.
That readback supplies the acceptance values: the moved image exists, the old reference count is zero, the new reference count is one, and an unrelated link remains unchanged. Do not substitute the editor’s current buffer for this disk result. Closing and reopening the document is a reasonable UI equivalent when the command interface is not used.
If the saved source still contains the old path, return to the rewrite step. If the source contains the new path but it does not resolve, return to relative-path calculation. If both are correct but the EPUB later omits the image, investigate packaging and content selection instead of rewriting the manuscript again.
Do not hide the fault with a same-named copy
Placing another figure.png at the old location may make a preview look correct, but it creates two possible sources of truth. A later cleanup can expose the same break again, and an incorrect yet similar picture can pass a casual visual review.
If an emergency restoration is necessary, record it as a temporary rollback with an expiry date. The permanent acceptance criterion remains a deliberate source reference that resolves to the intended asset.
This is why broken EPUB image paths are a relationship problem. File presence is necessary, but the manuscript-to-asset edge must also be correct.
Perform the same sequence manually when commands are unavailable
Rune Studio’s published product material describes reference discovery and rewriting. A UI-only operator can still follow the measured sequence: search the manuscript for the old relative path, note the number of matches, move the image, edit only those matches, save, close, and reopen the file. Record the counts rather than relying on memory.
The current evidence did not measure a colored warning, an automatic repair prompt, or behavior in every reader. Those interface outcomes should not be claimed from this run. Manual confirmation of the stored path remains available even when automation cannot be used.
Grant export permission only after resolution
For this specimen, the final source-side values were one referring file, zero old references, and one new reference. The saved source showed the intended new path and preserved the non-image link. Those are the conditions for proceeding to a test export.
Package inspection remains a later gate. A valid EPUB does not excuse an old reference left in another source file, and a corrected source does not guarantee that an unrelated export setting selected the right chapters. Keep the source-reference ticket beside the package report.
To resolve broken EPUB image paths without carrying the accident forward, count first, move second, preview the rewrite, apply it, and inspect the saved manuscript. When a value disagrees, return to the stage that owns that value rather than changing unrelated assets.