update docs && comments, fix logic errors, pwd() returns references