Response to most comments, except for:

1) new flow API + associated documentation
2) check whether flat file listing for input files is correct
3) removing new lines (prefer to keep as is for the most part)

Obviously I will squash this commit before pushing to master ...