new swap conflict handling; improve docs