api: PUT changes only what differs

1 files changed, 5 insertions, 4 deletions

diff --git a/docs/openapi.yaml b/docs/openapi.yaml
index a6b7d84..662b46b 100644
--- a/docs/openapi.yaml
+++ b/docs/openapi.yaml
@@ -96,9 +96,10 @@ paths:
       tags: [Store]
       summary: Write a value
       description: |
-        Writes the value, creating intermediate maps (not lists). In a list, an index
-        replaces the item there, the list's length appends, and past it is `404`. One
-        request is one Automerge change. Answers with the value written (JSON, or text with
+        Writes the value, creating intermediate maps (not lists): the path then reads as
+        the value, what was there changed only where it differs (`api.md`, Concurrent
+        writes). In a list, an index overwrites the item there, the list's length
+        appends, and past it is `404`. One request is one Automerge change. Answers with the value written (JSON, or text with
         `Accept: text/plain`).
 
         JSON maps and arrays become Automerge maps and lists; numbers become integers
@@ -137,7 +138,7 @@ paths:
         Inserts the value (as `PUT` takes it) into a list: the path ends in the index
         it goes to (`queue/2`), the items from there on moving up one; the list's
         length, or `-1` (a `307` to it), appends. One request is one Automerge change.
-        To add a key to a map, `PUT` it; to replace an item, `PUT` its index.
+        To add a key to a map, `PUT` it; to overwrite an item, `PUT` its index.
       requestBody:
         required: true
         content: