The reference guide is your friend.
Thank you very much - that nearly explains everything. I guess the reason I was a bit confused is I am already using a portlet-instances.xml file - just coded a bit differently. I just redid both the portlet-instances.xml and the -object.xml and redeployed without incident.
One question that the document does not make clear: I am not coding any page or window specific descriptors in my -object.xml file - I use the admin area to put portlets on specific pages instead. So that means that I now have nothing real in my -object.xml, just empty deployments and deploment tags.
It ran without problems, but is this correct practice?
-object.xml file provides an initial configuration to the portal to populate the database. The admin interface works directly on the database. The portal always reflect the state of the database and any work done in the portal admin interface is NOT ported back to the descriptors. This is a functionality that might or might not appear in a future release.