A great Link, Jake.
I haven't had time to take in the whole article;
but my previous "understanding" was that Desktop and Documents folders were really meant to allow working on documents across multiple devices - and that the "other aspects" of this weren't the primary focus?
Ian
No, that isn't what it was for. The sharing across machines was the function of iCloud Drive, in that all systems connected to the same AppleID could see all of the items stored in iCloud Drive if iCloud drive was on, and Optimize Mac Storage was also on. Kind of like Dropbox and others in that regard.
But if you turned on the Desktop and Documents option, what happened was the the contents of Desktop and Documents were moved on the local machine to iCloud Drive, and therefore shared just like anything else in iCloud Drive. The folders where Documents and Desktops used to be locally disappeared as a result of the move, but they worked from iCloud drive. Eventually the system would also "evict" seldom-used files from the iCloud Drive by replacing the local copy with a pointer to the iCloud location where the file really was stored. That happens as a part of the "Optimize" function for anything in iCloud Drive. Any evicted file would then be downloaded "on demand" when the user wanted it, assuming the Mac had Internet connectivity and was logged into the AppleID account. What became scary for some folks what that when you turn OFF the Desktop and Documents option, the system recreated new, empty, Documents and Desktop folders where they had been originally, leading users to think that everything had been erased. The "fix" for this is to move the contents from the iCloud Drive Desktop folder and the iCloud Drive Documents folder to the new, empty locations and all is restored. Evicted files will be downloaded again, if needed, so that at the end of the process, all files will be where they "normally" are. The article goes into a lot of technical detail about HOW that process happens.
What gets ugly is that if you have two machines, lets say "Mac1" and "Mac2" and both are on the same AppleID and both have "Optimize" and "Desktop and Documents" selected, then what appears gets complex. In the cloud iCloud drive there are now three varieties of files/folders: 1) Files stored in iCloud drive on each machine that are NOT in Documets or Desktop, 2) Documents and Desktop folders from Mac1, and 3) Documents and Desktop folders from Mac2. My understanding is that iCloud does NOT merge the two machines' Documents and Desktop folders, but keeps them unique, so they have to be renamed to separate them. The system appends the name of the source machine somehow. l haven't tried it myself, but I've heard that what would appear is somethiing like "Desktop Mac1" and "Desktop Mac2" on both machines, etc. "Normally" shared files on iCloud Drive that are NOT in the Desktop or Documents folder will NOT have the appended machine because they are meant to be shared.
At least, that's how I've heard it works, and the article seems to confirm that.
I don't think Apple could have made it harder if they assigned a full time team on it!