error messages,doc clarity, and improved perf