many improvements, fixes and docs update