I just re-read the docs and it appears that my general approach is wrong. I should first create the file in the sandbox and then move it to the cloud. In other words, Apple seems to suggest that I should have three versions of the same file at all times: one in the directory of my app, one in the iCloud demon directory of my device (which is also accessible if offline) and one in the cloud:
Apps use the same technologies to manage files and directories in iCloud that they do for local files and directories. Files and
directories in iCloud are still just files and directories. You can
open them, create them, move them, copy them, read and write from
them, delete them, or any of the other operations you might want to
do. The only differences between local files and directories and
iCloud files and directories is the URL you use to access them.
Instead of URLs being relative to your app’s sandbox, URLs for iCloud
files and directories are relative to the corresponding iCloud
container directory.To move a file or directory to iCloud:
Create the file or directory locally in your app sandbox. While in
use, the file or directory must be managed by a file presenter, such
as a UIDocument object.Use the URLForUbiquityContainerIdentifier: method to retrieve a URL
for the iCloud container directory in which you want to store the
item. Use the container directory URL to build a new URL that
specifies the item’s location in iCloud. Call the
setUbiquitous:itemAtURL:destinationURL:error: method of NSFileManager
to move the item to iCloud. Never call this method from your app’s
main thread; doing so could block your main thread for an extended
period of time or cause a deadlock with one of your app’s own file
presenters. When you move a file or directory to iCloud, the system
copies that item out of your app sandbox and into a private local
directory so that it can be monitored by the iCloud daemon. Even
though the file is no longer in your sandbox, your app still has full
access to it. Although a copy of the file remains local to the current
device, the file is also sent to iCloud so that it can be distributed
to other devices. The iCloud daemon handles all of the work of making
sure that the local copies are the same. So from the perspective of
your app, the file just is in iCloud.All changes you make to a file or directory in iCloud must be made
using a file coordinator object. These changes include moving,
deleting, copying, or renaming the item. The file coordinator ensures
that the iCloud daemon does not change the file or directory at the
same time and ensures that other interested parties are notified of
the changes you make.
However, if you dig a little deeper into the docs concerning setUbiquitous, you’ll find:
Use this method to move a file from its current location to iCloud. For files located in an application’s sandbox, this involves physically removing the file from the sandbox directory. (The system extends your application’s sandbox privileges to give it access to files it moves to iCloud.) You can also use this method to move files out of iCloud and back into a local directory.
So this appears to mean that a file / directory gets deleted form the local sandbox and moved into the cloud.