You’re misinterpreting what Apple is saying there, I’m afraid:
The key word is “directory” - this does not include zip files, which are not directories (even though they may compress and contain directories) but are technically single files, and not file packages (in Apple’s terminology). Pages and iWork do not save their files as packages, but as zip files, and a zip file is not a file package. A file package is just a regular folder of files that macOS presents in the Finder as if it were a single file, because an app is registered with the system that recognises the extension and tells macOS to treat it as a single file. If you move a .scriv file to a Windows machine or to any Mac that does not have Scrivener installed, it will appear as a regular file in the Finder. The same is not true of a .pages file.
You can test this for yourself by Ctrl-clicking on a file in the Finder. Any file that shows the “Show Package Contents” menu item in the contextual menu when you do this is a package file (this allows you to see inside the package); any file that does not show this option is not. Try this on a .scriv file and a .pages file, and you will clearly see that Pages files are not packages where Scrivener is.
The difference is crucial because a zip file will not have problems with its components uploading and downloading separately (because any syncing system treats a zip file as a single file), whereas a file package will (because it is just a folder of different files). Zip files are perfect for many things. .pages, .docx and .epub are all zip files containing XML files, subfolders and resources. It is possible to read files separately from, and save them separately into, a zip file (although macOS doesn’t have any standard libraries good for that, unfortunately), but they are prone to the same problems as any other monolithic file format: if the zip file gets corrupted, you can’t access any of the data in it. That’s not a problem for file packages. If a single file gets corrupted in a file package, everything else is still fine. File packages (folders of files) are perfect for Scrivener; unfortunately, they aren’t so great for automatic sync solutions.
That’s a very good question, and not something I have explored properly yet. I would hope that macOS is sensible enough to treat file packages as single files that have to be kept intact here, but we need to do some extra testing on that. I certainly wouldn’t risk it, though. I chose not to turn that feature on, as I like having all of my files on my machine and not hidden away on the cloud (I regularly back up files to Dropbox and to an external hard drive, and share many files in my Dropbox folder, so that all my crucial files are safe anyway).
Oh, I hope I’m not coming across in any way defensive. It’s a hugely thorny and complex problem, so it’s often difficult to get across the technical issues involved because they are so complicated. From the outside, in part because of how Apple has always presented it, iCloud seems as though it provides “magic” syncing that is perfect for everything. And iCloud is a wonderful technology, but it has been built to work amazingly and easily for, say, 90% of apps. If you fall outside of the areas it was built for, though, it does not offer any advantages over other solutions and is actually more difficult to implement. Apple is adding to it all the time, though, and I still have my tech support incident out with them which I intend to follow up and investigate more as soon as I get time.
Syncing is the number one gripe users have with our iOS version, and I knew when creating it that this would be the case. It’s hugely frustrating, because I’d love to offer syncing across many solutions and have it work in the background, propagating across platforms without any user interaction. But because of the way Scrivener works and the things it needs to do, that’s not really possible at the moment. Well, it might be possible if we had the engineers of Apple or Google, of course, but sadly we don’t! We’re a really small team - I am the sole designer and developer of Scrivener for both macOS and iOS. There are no other programmers working on them but me. The Windows version has two developers working on it. Ultimately I’d love to find another programmer to come on board and work with me, and I’d like to find somebody who has some expertise in syncing. Finding someone is not easy, though, especially since we don’t even have offices…
All the best,
Keith