How to sync Documents on macOS Monterey (and probably later)

In macOS Monterey (and probably later), the Dropbox folder is moved from $HOME/Dropbox to $HOME/Library/CloudStorage/Dropbox. I'll use $DROPBOX to refer to the actual absolute path of the Dropbox folder.

The "traditional" way to sync $HOME/Documents is:

1. move or copy $HOME/Documents (and its contents) into $DROPBOX -- this will sync in the usual way
2. remove any remaining files from $HOME/Documents (including .localized and .DS_Store, etc.)
3. sudo rmdir Documents   # sudo is required to remove a "system" directory
4. ln -s $DROPBOX/Documents $HOME

On macOS Monterey this fails -- immediately after #3 the OS creates an empty folder $HOME/Documents, and #4 fails.

Perseverance paid off, and I found a way to do this. You should have a good backup before starting.

1. DROPBOX=$HOME/Library/CloudStorage/Dropbox    # or wherever it is actually located
2. move or copy $HOME/Documents (and its contents) into $DROPBOX -- this will sync in the usual way
3. remove any remaining files from $HOME/Documents (including .localized and .DS_Store, etc.)
4. cd $HOME
5. sudo rmdir Documents ; ln -s $DROPBOX/Documents $HOME     # two commands on one line
6. in the finder, remove the "Documents" item from the sidebar
7. in the finder, select "Dropbox" in the sidebar and drag its "Documents" into the sidebar
8. in AppleMenu/ForceQuit force the Finder to relaunch

The key is using a single command-line in #5, so the link is created before the OS notices that Documents went missing.

If you don't do #8, the Finder won't see Documents until you reboot.

If you have multiple machines that will sync Documents, do the above on ONE machine, and do this on the others:

1. Wait until $DROPBOX/Documents has synced with the first machine.
2. DROPBOX=$HOME/Library/CloudStorage/Dropbox    # or wherever it is actually located
3. cd $HOME
4. sudo mv Documents OldDocuments ; ln -s $DROPBOX/Documents $HOME     # two commands on one line
5. in the finder, remove the "Documents" item from the sidebar
6. in the finder, select "Dropbox" in the sidebar and move its "Documents" into the sidebar
7. in AppleMenu/ForceQuit force the Finder to relaunch
8. Once you check that Documents is correct, do sudo rm -fr OldDocuments