update examples and discuss idempotence