fix: localize document summaries and refine mobile coach

docs/api/openapi.yaml

@@ -1,7 +1,7 @@
 openapi: 3.1.0
 info:
   title: HealthLog API
-  version: 1.31.2
+  version: 1.31.3
   description: >-
     Self-hosted personal-health-tracking PWA — public API surface for the iOS native client and external ingest.
 
@@ -10219,13 +10219,13 @@ paths:
     post:
       tags:
         - Documents
-      summary: Summarise or transcribe a document (session-only)
-      description: 'On-demand, SESSION-ONLY description of a stored document. `?mode=summary` (default) returns a short
-        plain-language summary of WHAT the document is; `?mode=text` returns its raw transcribed text. The result is
-        transient — nothing is persisted except the AI-budget ledger + audit log; it never reaches coach memory,
-        snapshots, the structured stores, or the search index. The summary is descriptive only and never a diagnosis.
-        Same VISION (empty body) / TEXT (`application/json` `{ mode: "text", text }`, opt-in local OCR) dispatch as
-        extract. AI-consent / rate / budget gated. 422 with no provider.'
+      summary: Summarise or transcribe a document
+      description: 'On-demand description of a stored document. `?mode=summary` (default) returns a short plain-language
+        summary of WHAT the document is; it remains transient unless `persist=true` fills the empty stored-summary slot,
+        while `persist=true&replace=true` explicitly replaces an existing summary. `?mode=text` returns transient raw
+        transcribed text. Neither result reaches coach memory, snapshots, structured stores, or the search index. The
+        summary is descriptive only and never a diagnosis. Same VISION (empty body) / TEXT (`application/json` `{ mode:
+        "text", text }`, opt-in local OCR) dispatch as extract. AI-consent / rate / budget gated. 422 with no provider.'
       parameters:
         - name: id
           in: path
@@ -10242,6 +10242,20 @@ paths:
               - text
             default: summary
           description: "`summary` (plain-language description) or `text` (raw)."
+        - name: persist
+          in: query
+          required: false
+          schema:
+            type: boolean
+            default: false
+          description: "For summary mode only: persist into an empty stored-summary slot."
+        - name: replace
+          in: query
+          required: false
+          schema:
+            type: boolean
+            default: false
+          description: With `persist=true`, explicitly replace an existing stored summary.
       requestBody:
         required: false
         content:
@@ -10271,7 +10285,7 @@ paths:
                 - text
       responses:
         "200":
-          description: The session-only summary (`{ summary }`) or extracted text (`{ text }`).
+          description: The summary and its persistence outcome, or transient extracted text.
           content:
             application/json:
               schema:
@@ -30389,6 +30403,12 @@ components:
           type: string
         text:
           type: string
+        persistence:
+          type: string
+          enum:
+            - stored
+            - withheld
+            - failed
       additionalProperties: false
     DocumentIndexEnvelope:
       type: object