Update docs to add note about back-compat

Also add some very basic upgrading notes for the early adopters.

I also updated the tutorial to use client objects.

cc @danielgtaylor @kyleknap 
Yeah, it is sort of hard without docs. Maybe the models? Or suggest the cli since it uses most of the same arguments?  Otherwise, I am fine leaving it.