[Experimental] Default starter content hero/section images break after theme update (referenced from theme dir, never sideloaded to Media Library)

[ineagu]

Summary

Neve's built-in Default starter content embeds its hero and section images as absolute theme-directory URLs ({{theme_uri}}assets/img/starter-content/*.jpeg, resolved to get_template_directory_uri()) directly in the published page markup. Unlike the logo and site icon — which are declared in the starter-content attachments array and are therefore sideloaded into the Media Library by core — these content images are never imported. They render straight from wp-content/themes/neve/….

When the theme is updated and those bundled assets are renamed/removed (as happened when the starter content was revamped to the current folio-* set), every published page that references them shows a broken image, and the file is nowhere in the Media Library because it was never there. The user perceives it as "the image disappeared from my Media Library after a theme update."

Customer context

A user published Neve's default homepage, then updated the theme; the homepage hero image disappeared and was absent from the Media Library. Support had to provide a direct GitHub link to the old asset and walk the user through downloading and manually re-uploading it. This affects any site that published the Default starter content and later updated across a starter-content asset change.

Reproduction or evidence

Code:

• inc/compatibility/starter_content.php — get()'s attachments array only sideloads default-logo and default-icon; the folio-* content images are not included, so core never imports them into the Media Library.
• inc/compatibility/starter-content/home.php — the hero wp:cover uses "url":"{{theme_uri}}assets/img/starter-content/folio-design.jpeg" plus an inline '<img ... src="{{theme_uri}}assets/img/starter-content/folio-design.jpeg">'. Same theme-URL pattern in about.php, services.php, work.php.
• inc/compatibility/starter-content/{home,about,services,work,pricing,contact,blog}.php — str_replace( [ '{{theme_uri}}', '{{home_url}}' ], [ trailingslashit( get_template_directory_uri() ), trailingslashit( home_url() ) ], $post_content ) confirms {{theme_uri}} resolves to the theme directory URL, not a Media Library upload.

Steps:

1. On a fresh site, activate Neve and publish the Default starter content from the Customizer.
2. Confirm the homepage hero renders from wp-content/themes/neve/assets/img/starter-content/… and that no corresponding attachment exists in the Media Library.
3. Update Neve to a version whose starter-content assets were renamed/removed (or manually rename/remove the bundled file to simulate).
4. The published homepage hero (and About/Services/Work images) 404, with no recoverable copy in the Media Library.

Suggested direction: sideload the starter-content images into the Media Library using the same mechanism already applied to the logo/icon (the attachments array), and reference the resulting attachment URLs — so published pages no longer depend on theme-version-specific asset paths.

Source

• Surfaced by: Codeinwp/docs-site#1645
• HelpScout thread(s): wp.org forum thread, conv id 3373669267
• Helpdesk pattern: single thread, but the failure mode is confirmed in code and applies to every site that publishes the Default starter content and later updates across an asset change — not host- or config-specific.
• Reviewer classification: bug