sync README.md with latest API doc + rewrite SCALE.md for better clarity