I had same exact experience with macOS and iCloud. macOS by default enables offloading Documents to cloud, transparently. Problem is if you try to get those files back to store them offline, it gets very tricky very quickly with ambiguous verbiage and lengthy process that you never actually know status of. I ended up losing some files as a result, which came as a total shock to me. I was already in the process of moving back to Linux (hence downloading of the Documents) and this was final straw.