Getting Started

Install with Composer: composer require visuellverstehen/statamic-asset-atlas. v0.6.3 requires statamic/cms ^5.71, so upgrade Statamic first if you are below that.
Publish and run the package’s migrations/config as described in its docs, then build or refresh the Atlas index for existing content.
First use case: move, rename, or delete an asset in the control panel that is referenced by an entry, then verify the entry and any draft/working copy references were updated. v0.6.3 specifically fixes stale paths for items supplied through Statamic’s additional reference hook.
Start by inspecting the package service provider, config, migrations, and its override of Statamic’s UpdateAssetReferences listener.

Implementation Patterns

Let Asset Atlas own the asset-reference update flow. Do not create a parallel asset-move listener that also rewrites references; rely on the package’s UpdateAssetReferences override.
Register custom additional hooks on Statamic’s UpdateAssetReferences listener class, not on a custom listener or replacement class. The package override calls that hook so items like drafts, working copies, or custom element sources get updated too.
Use the Atlas reference data before deleting or bulk-moving assets. For content imports, seeders, or large restructures, run the package’s indexing/refresh step afterward so Atlas stays in sync.
In deployments, run migrations, clear caches, and reindex when asset references have changed outside the normal control-panel flow.
For custom item sources, keep the additional hook focused: return items that Statamic’s default lookup would miss, and confirm their asset fields contain the paths Atlas indexes.

The statamic/cms ^5.71 requirement is meaningful: older Statamic versions do not have the additional hook. If you are pinned below 5.71, upgrade before adopting v0.6.3.
v0.6.3 fixes a real stale-reference bug: before this release, the Asset Atlas override could skip Statamic’s additional hook, leaving drafts and working copies with old asset paths after a move. Upgrade if editors rely on drafts or custom reference sources.
Keep hooks registered on Statamic’s listener class. Moving them to your own listener can make them invisible to Asset Atlas’s override.
When debugging missing reference updates, check listener registration, cache state, queue workers, index freshness, and whether your additional hook is returning the expected items with the expected asset fields.
Prefer the additional hook as the extension point rather than replacing the listener. Re-test asset moves against both published and draft content after upgrading.