framework tweaks, added class ref docs, updated upgrade docs