My last, not very helpful, contribution...
If I add a file to an empty ~/Library/Containers/<app>/Data/Documents then the <app> suddenly appears in Finder as ~/Documents/<app>
I wish I could reproduce that; I'd love to see how that's represented in the file system. I think both of you are saying it's not represented by symbolic links from Containers to Documents. Obviously the contents of these two new directories have to stay in sync. I guess Catalina's new firmlinks could be involved. I'm a bit skeptical, but if a firmlink was being used, I think you would see "sunlnk" as a file flag on the linked directories (run "ls -lO" to see the file flag).
Complete guess - I wonder if this automation is handled by containermanagerd, a process I can see in Activity Monitor. I bet Apple doesn't want you to directly manipulate the contents of Containers. It could be that the side effect you're seeing would not happen if an application were directly manipulating it's own container and using an appropriate API call. That's not to say that Apple didn't mess things up during the transition from Catalina to Big Sur, but it could mean you won't get further pollution of the Documents folder moving forward unless an application you're using intends to do it.
And in addition the finder displays different names for some of the files in
All of the following directories;
~/Library/Containers/com.apple.mail
...
are shown simply as "Mail" in the finder, you have to guess which is which.
This a horrific situation that exists in Finder and Pathfinder. You can tell which is which by inspecting the contents of .com.apple.containermanagerd.metadata in each folder. It seems clear that Apple doesn't mean you to be looking in the containers folder. This is unpleasant for the more technical people (you guys). Consider
this post.
I to have symbolic links within the folders in ~/Library/Containers/, but the do only link to other folders beneath the same root, not to my ~/Documents folder.
Bizarre. I have so many such links and have had them for a many of previous OS versions. For example, the BBEdit container has many symbolic links to locations outside of Containers: Desktop, Downloads, "Documents/BBEdit backups", many different directories under Library (at various levels). This list goes on and on. The same is true for every other application's container that I checked.
Nothing to do with iCloud, favourites, etc. (as far as I can see).
I respect your intuition. Just be aware that I'm not seeing any of the behavior you guys are seeing and I have my entire Documents and Desktop stored in iCloud. I do have a second computer to upgrade. I hope I see the behavior you're seeing.
The only reason I got side tracked on favorites in Finder is that the initial symptom reported was that a folder was visible in Finder but neither in Terminal nor Pathfinder. That symptom was dropped from all subsequent discussion, so it seems like I was focused on an unimportant part of the issue.
Best of luck getting some resolution on this.
