add remarks about the framework organization; rebuild docs