documentation update
steps towards a new "world model"