what is the "Forget all...." for preferences supposed to do? Reset Pd to
first install state?
You're only half right.
There are *two* preferences:
* core preferences: paths, libs, audio devs, startup flags
* GUI-only preferences
Forget all... clears the core preferences only.
If so I would assume when I "forget all" I would get
the "Would you like to create a folder in ~/Documents/Pd?" dialog but
instead if I "Forget all..." and $ rm ~/Documents/Pd I get:
Pd documents directory cannot be found:
/Users/megrimm/Documents/Pd
Choose a new location?
Your assumption is wrong. You did not clear the GUI preferences and the pd_docsdir plugin checks if the previous path exists. In your case it does not so it falls back by letting you know it doesn't exist and let's you choose/make a new one.
Should it not just reset to initial "Would you like to create a folder in
~/Documents/Pd?" ?
No, because, again, the docspath is still set in the GUI preferences. If you want to do a full purge, you need to clear the GUI preferences as well. On macOS, use:
defaults delete org.puredata.pd.pd-gui
Sorry if this sounds like "You're doing it wrong" but this release now has this split preferences system and I used the GUI prefs for the docspath as it's really a GUI-only setting.