minor modifications in the shell, examples and tips, github tips and README