docs(admin): document external storage change detection and limitations

[skjnldsv]

☑️ Resolves

• Fixes Explanation why using external storage outside of Nextcloud is unreliable and hints to make it work with limitations #7849

What changed and why

Expanded the external storage admin documentation to explain a common source of confusion: changes made directly on a mounted storage (outside Nextcloud) are not automatically visible to Nextcloud, desktop clients, or mobile apps.

The thin "Adding files to external storage" section has been replaced with a proper Detecting changes made outside Nextcloud section that covers:

• Why it happens: Nextcloud maintains an internal filecache; external changes are invisible until a rescan updates it.
• How "Filesystem check frequency" actually works: it only fires during a WebDAV PROPFIND, driven by user actions, not background polling. The mount option bullet in the UI description is also expanded to make this clear.
• Why desktop clients miss deep changes: clients only PROPFIND the sync root and rely on etag propagation up the tree; without a rescan at the changed level there is no trail to follow.
• Solution A (SMB): occ files_external:notify for near-real-time detection via SMB change events.
• Solution B (all others): periodic occ files_external:scan <mount_id> cron job.
• Rename limitation: any rescan (periodic or on direct access) cannot detect renames reliably; the old entry is treated as deleted, causing permanent metadata loss (shares, tags, comments, activities). Documented as a .. warning::.

A .. seealso:: cross-reference was added to smb.rst at the top of the "SMB update notifications" section pointing back to the new anchor (external_storage_change_detection_label).

📸 Screenshots

✅ Checklist

• I have built the documentation locally and reviewed the output
• Screenshots are included for visual changes
• I have not moved or renamed pages (or added a redirect if I did)
• I have run codespell or similar and addressed any spelling issues

[github-actions]

📖 Documentation Preview

🔍 Open preview →

📄 2 changed documentation pages

• admin_manual/configuration_files/external_storage/smb.rst
• admin_manual/configuration_files/external_storage_configuration_gui.rst

Last updated: Thu, 21 May 2026 16:17:30 GMT

[skjnldsv]

@artonge done in d400487 !

• reworded both bullets (once per direct access + never) per your suggeestions
• dropped the trailing clause from the etag paragraph
• swapped files:scan --all and the --path variant for files_external:scan <mount_id>, also removed the AIO note and webcron recommendation
• broadened the rename limitation, its not just for periodic rescan but also for "once per direct access" as you pointed out

let me know if anything still looks off!

[artonge]

We should keep the AIO part, I assume Simon put it there because the question come frequently.

[skjnldsv]

Thanks for taking the time, I adjusted a few areas, and fixed the wrong listed option 🚀
Rebased and squashed!