READY: doc and work out the spec

Work in Progress

NOT ready to merge until READY in title.