documents API call return formats

Figures out how to resolve a catpath.
shifts ls above rm in TODO

This is because we need the catpath walking machinery for rm anyway, so
we might as well support ls which is just catpath + printing.
clarifies usage in README