entities refactor + docs"