## 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
```text
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