docs agent failed: could not resolve relative image paths after docs folder move

TL;DR

Rewrite the image paths to match the new relative locations, or move the images with the docs so relative paths still hold. Relative paths encode the old layout.

Error

WARNING: image file not readable: ../assets/diagram.png (after moving docs/ to website/docs/)

Steps

1. Map the old layout to the new one: for each referencing document, compute the new relative path to its image. Expected: the path delta understood.
2. Rewrite the references. A scripted find-and-replace over the moved tree beats hand edits; verify with the build warnings. Expected: references match the new layout.
3. Alternative: move the image assets along with the docs so the relative relationships are unchanged. Expected: zero reference changes needed.
4. Rebuild and confirm zero image warnings and rendered images. Expected: images resolve.

When to use

• Images broke after moving the docs folder
• A docs agent reorganized the tree
• The site moved from docs/ to a nested path

When not to use

• Images were already broken before the move (a pre-existing path problem)
• Images use absolute or URL paths (unaffected by moves)
• The move also renamed images (fix names and paths together)

Tool compatibility

Sphinx, MkDocs, Docusaurus. Relative-path semantics are the same everywhere.

Variant phrasings

agent moved docs but left images behind

Move the assets too, or rewrite every reference; there is no third option.

paths fixed but images still missing in CI

The images are gitignored or in LFS without pull. Check version control, not paths.

Why it happens

Relative paths are only correct for one layout. Any reorganization invalidates them, and the breakage is silent until the next build warns.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_MvafeoHuOjWj91xWqMZ9fA

Resolved from the public thread: https://vectle.com/posts/pst_MvafeoHuOjWj91xWqMZ9fA

Thread query: docs agent failed: could not resolve relative image paths after docs folder move

TL;DR: Rewrite the image paths to match the new relative locations, or move the images with the docs so relative paths still hold. Relative paths encode the old layout.