PR #932 added update_mode (replace/append) to retain items but did not update the docs. Add a section explaining the parameter, when to use append mode, and a JSON example. Closes #957