@case-framework/survey-assistant 0.6.0 → 0.8.0

package/dist/references/item-types.md

@@ -9,7 +9,10 @@ Structure/container item:
 ```json
 {
   "itemType": "group",
-  "config": { "items": [], "shuffleItems": false }
+  "config": {
+    "items": [],
+    "shuffleItems": false
+  }
 }
 ```
 
@@ -22,7 +25,7 @@ Use a group when its children form a meaningful, independently managed section o
 
 Every item has three distinct naming/presentation surfaces:
 
-- `key`: stable coding key used in expressions and response paths. Change it with `update-item-key`.
+- `editorName`: resolved display name returned by inspection; use the persistent item ID for edits. Response coding belongs to slots, not item names; change it with `update-response-settings`.
 - `metadata.itemLabel`: internal editor label, not shown to respondents. Change it with `update-item-label`.
 - `metadata.editorItemColor`: editor-only color swatch, not shown to respondents. Change it with `update-item-color`.
 
@@ -38,7 +41,29 @@ Page-break/structural item. It has no response slots. Visible title uses content
 
 Non-interactive content item. Config is normally an empty object. Visible body text uses content key `content`.
 For plain text, create or update `content` with typed translation operations.
-For formatted text, create or update `content` with typed translation operations using a `richText` `content` value; see rich-text-content.md.
+For formatted text, load `assistant-operations` with the operation and item type and use only content surfaces marked `format=rich` in its capability profile. Prefer the model-facing `richTextBlocks` shorthand there; it normalizes to canonical richText `content`. A typed field accepting structured `content` does not by itself guarantee formatted rendering. See rich-text-content.md.
+
+## consentItem
+
+Use one consent item for each independent permission. The item presents a title, supporting subtitle, and full `consentBody` translation, then records an explicit agreement or refusal. Both title and body are needed in each participant language. Use `infoItem` for information that does not ask for a decision.
+
+Organize the participant-facing content in the question fields:
+
+- `title`: the main heading identifying the agreement or permission. Prefer the supplied document's main heading when available. This field stays visible on the question card and names the dialog unless `consentTitle` overrides it; do not put the only title inside the body.
+- `subtitle`: an optional brief introduction or reading instruction directly below the title. Leave it out when no separate introduction is needed.
+- `consentTitle`: optional rich consent-specific heading. Empty inherits `title` in the same locale. Supply only when a distinct local heading is useful; it appears above the inline document or in the dialog summary and dialog heading.
+- `consentSubtitle`: optional rich consent-specific introduction, used only with `config.subtitleMode="custom"`.
+- `consentBody`: the actual content the participant needs to read before deciding, including the agreement, terms, or explanation of the permission. It is the document itself, not a description, summary, or instruction to read an absent document. Avoid repeating the question title as an opening body heading; retain meaningful section headings, paragraphs, lists, and links within the document. Follow an explicit request to preserve the source verbatim.
+
+Follow supplied content: preserve its terms and meaning instead of replacing it with generic wording, silently changing its meaning, or adding unrequested provisions. When helping create new wording, be proactive: write useful, concrete draft terms and make reasonable creative choices from the available context. Do the useful work first, then identify the result as a draft and explain material assumptions or missing details in your reply. Do not present invented wording as facts or as a document supplied by the user. Use placeholders sparingly for details the user must supply, while still drafting the substantive content. Do not fill `consentBody` with only a description of a document or a statement agreeing to unspecified terms elsewhere. Ask a focused question before acting only when useful progress is blocked, such as when exact reproduction requires unavailable source text. Missing optional details are a reason to note gaps afterward, not to delay a useful draft.
+
+Config supports `presentation`: `"inline"` (default) or `"dialog"`, and `subtitleMode`: `"inherit"` (default), `"custom"`, or `"none"`. Subtitle mode applies to all languages. Inherit uses the question subtitle; custom uses `consentSubtitle` for the current locale (empty stays absent); none omits the consent subtitle. The question subtitle remains visible in every mode. Inherited title/subtitle are not repeated inline or in the dialog summary, but are shown inside the dialog. Custom titles also identify the inline consent and dialog summary. Custom subtitles appear above the inline document or inside the dialog, never in the dialog summary.
+
+Optional plain `acceptLabel` and `declineLabel` translations override choice wording. `unansweredLabel`, `acceptedLabel`, and `declinedLabel` override dialog status; `reviewLabel` and `changeLabel` override dialog actions. Empty values use the host UI defaults. Close, missing-title and unavailable-information messages belong to host player localization; do not create item translations for them. Languages without host translations require host localization for those generic messages. There is no separate decision heading. Without existing response data there is no automatic selection. Consent supports the ordinary initial-response and item-level prefill paths using the boolean slot identified by `config.slotId`. There is no `required` setting or config effects list. Closing the dialog leaves the answer unchanged.
+
+Config has independent persistent `id` and `slotId`, plus an editable `variableName` (for example `research_consent`). The assistant can allocate omitted IDs at creation; inspect the result before referencing them. Boolean true means agreement, false means refusal, and absence means unanswered. Compare `{ "slotId": "<config.slotId>", "method": "get" }` with a boolean constant. `isDefined` tests either recorded decision. Never use the literal `accepted` as a universal slot ID.
+
+To show a section only after agreement, place the agreement expression on the dependent item's or group's root display condition. Hiding retains previously entered answers in the session but omits hidden items from submission and subsequent exports; showing the section again restores them. Required-question navigation enforcement is planned separately.
 
 ## choiceItem
 
@@ -51,7 +76,12 @@ Interactive choice question:
     "id": "<itemId>",
     "maxSelection": 1,
     "shuffleOptions": false,
-    "options": [{ "id": "fuji", "key": "FUJI" }]
+    "options": [
+      {
+        "id": "fuji",
+        "code": "FUJI"
+      }
+    ]
   }
 }
 ```
@@ -65,31 +95,27 @@ Choice conventions:
 - If the user says "choose up to N", "select at most N", or "maximum N", create a `choiceItem` with `maxSelection: N`.
 - If the user says "single choice", "choose one", or options are mutually exclusive by wording, create a `choiceItem` with `maxSelection: 1`.
 - `options[].id` is the stable option id.
-- `options[].key` is optional but should be stable and coding-friendly. When you provide it, use lowercase snake-style keys such as `other` or `opt_1`, matching the editor's choice key normalization.
+- `options[].code` is an export code. Responses and expressions continue to use the exact option ID; codes, labels and IDs are independent.
 - `options[].hasDisplayCondition` is an optional boolean used by the editor to mark options that participate in branching/display logic.
 - Option labels are translations at `options.<optionId>.label`.
 - Do not use provider-specific label metadata such as `labelKey`. CASE resolves every respondent-visible option label from `options.<optionId>.label` translations.
 - CASE choice options do not currently have a separate visible option-description field. If source material has an option-specific parenthetical/note, include it in the option label or move it to nearby question content. The `survey_change` normalizer preserves shorthand `option.note`, `option.description`, `option.helpText`, and `option.footnoteMarker` by folding them into the label translation.
 - If an option has an embedded form, do not duplicate trailing completion words in both the option label and field label. The normalizer strips trailing `, namelijk`, `, please specify`, `, specify`, `, explain`, and `, toelichting` from embedded-form option labels before validation.
-- The main response slot is `<itemId>...get...<config.id>`. For a new choice item, always set
-  `config.id` to the exact same value as `item.id`; do not invent a second semantic name from the
-  question wording and do not add ordering suffixes such as `q1`. The choice response-slot ID has no
-  direct editor control and expressions refer to it exactly, so changing it later requires updating
-  every reference in the same change.
+- The main response slot is the persistent `config.id`; new assistant-created choices default it to `item.id`. `config.variableName` is its independent coding name. Preserve both IDs on later edits and use structured response references.
 - Single select returns `reference`; multiple select returns `reference[]`.
 
 Embedded option forms:
 
 - There is no `allowOther` flag in the current choice item model. Do not use `allowOther` to create free-text "Other" inputs.
-- CRITICAL — exact key name: the field on the option object is `embeddedForm` (singular, one object). It is NEVER `embeddedForms` (plural) and NEVER an array. The option's recognized keys are only: `id`, `key`, `label`, `hasDisplayCondition`, `embeddedFormItemId`, `embeddedForm`. Any other key (including a typo'd/pluralized `embeddedForms`) is silently dropped during validation — no error is raised, the field simply never appears, and you must not report the change as successful if you are not certain you used the exact singular key.
+- CRITICAL — exact key name: the field on the option object is `embeddedForm` (singular, one object). It is NEVER `embeddedForms` (plural) and NEVER an array. The option's recognized keys are only: `id`, `code`, `label`, `hasDisplayCondition`, `embeddedFormItemId`, `embeddedForm`. Any other key (including a typo'd/pluralized `embeddedForms`) is silently dropped during validation — no error is raised, the field simply never appears, and you must not report the change as successful if you are not certain you used the exact singular key.
 - CRITICAL — exact shape: `embeddedForm` fields are never listed directly as `embeddedForm.fields`. They must be nested inside `embeddedForm.fieldGroups`, an array of groups, each with its own `fields` array: `{ "id": "...", "fieldGroups": [ { "id": "...", "fields": [ { "id": "...", "type": "input", "controller": { "type": "input", ... } } ] } ] }`. A top-level `fields` array with no `fieldGroups` wrapper will not render anything.
 - CRITICAL — `embeddedForm` is a FLAT object with `id`, `authoringMode`, and `fieldGroups`. Do NOT invent an envelope like `{ "itemType": "formItem", "config": { "fields": [...] } }`. There is no `itemType`/`config` wrapper anywhere inside `embeddedForm`; `fieldGroups` sits directly on the `embeddedForm` object itself.
-- CRITICAL — always set an explicit `id` on any option that will have an `embeddedForm` (e.g. `"id": "other"`, lowercase, coding-friendly). If you omit `id`, one is auto-generated from `label` and PRESERVES THE EXACT CASE of the label text (e.g. label "Other" auto-generates id "Other", not "other") — you cannot reliably predict it, and every embedded-form translation content key (`embeddedForms.<optionId>...`) and response slot (`embedded.<optionId>...`) must match that exact generated id, including case. Setting an explicit lowercase `id` yourself removes this guesswork entirely.
+- CRITICAL — always set an explicit `id` on any option that will have an `embeddedForm` (e.g. `"id": "other"`, lowercase, coding-friendly). If you omit `id`, one is auto-generated from `label` and PRESERVES THE EXACT CASE of the label text (e.g. label "Other" auto-generates id "Other", not "other") — you cannot reliably predict it, and every embedded-form translation content key (`embeddedForms.<optionId>...`) must match that exact generated id, including case. Setting an explicit lowercase `id` yourself removes this guesswork entirely.
 - To attach input controls to a choice option, put an `embeddedForm` on that option. It uses the same `FormItemConfig` shape as a `formItem` (`id` + `authoringMode` + `fieldGroups`), but it is embedded directly on the option object — it is never a separate `formItem` sibling and never uses `embeddedFormItemId` unless you are intentionally referencing a shared/reusable form item defined elsewhere (rare; prefer inline `embeddedForm`).
-- Use `authoringMode: "simple"` only for one internal group containing exactly one field. Use `custom` for a blank or multi-field follow-up. Adding, removing, moving, retyping, or rekeying fields, or changing groups/layouts, is a one-way transition to `custom`; preserve the existing field and translations during that transition.
+- Use `authoringMode: "simple"` only for one internal group containing exactly one field. Use `custom` for a blank or multi-field follow-up. Adding, removing, moving, retyping, or renaming fields, or changing groups/layouts, is a one-way transition to `custom`; preserve the existing field and translations during that transition.
 - The embedded form renders only while that option is selected. When the option is deselected, existing embedded responses are cleared after user confirmation.
 - Embedded form translation keys are prefixed with `embeddedForms.<optionId>`; for example `embeddedForms.other.fields.other_text.label`. Note this translation content-key prefix IS plural (`embeddedForms`) even though the config field on the option is singular (`embeddedForm`) — these are two different things; do not confuse them.
-- Embedded form response slots are `embedded.<optionId>.<fieldKey>`; for example `embedded.other.other_text`.
+- Embedded response slots are persistent field IDs. Use their independent survey-wide unique variable names for coding; never reconstruct a slot ID from a translation namespace.
 - Use `create-item` with embedded form config and matching translations when creating a new choice item. For an existing choice option, inspect its exact item and option ids and use `set-embedded-form`; its relative form translations are prefixed automatically. If the option is also new, put `add-choice-option` with an explicit id immediately before `set-embedded-form` in the same proposal.
 - MANDATORY: every embedded form field needs a matching `embeddedForms.<optionId>.fields.<fieldId>.label` translation entry when it is introduced. There is no fallback/derived label text — a field without this translation renders its raw key to respondents.
 
@@ -98,27 +124,36 @@ Example "Other, please specify" option:
 ```json
 {
   "id": "other",
-  "key": "other",
   "embeddedForm": {
     "id": "other",
     "authoringMode": "simple",
     "fieldGroups": [
       {
         "id": "other_details",
-        "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+        "layout": {
+          "base": 1,
+          "xs": 1,
+          "sm": 1,
+          "md": 1,
+          "xl": 1
+        },
         "fields": [
           {
             "id": "other_text",
-            "key": "other_text",
             "type": "input",
             "required": true,
-            "controller": { "type": "input", "inputMode": "text" },
-            "validations": []
+            "controller": {
+              "type": "input",
+              "inputMode": "text"
+            },
+            "validations": [],
+            "variableName": "other_text"
           }
         ]
       }
     ]
-  }
+  },
+  "code": "other"
 }
 ```
 
@@ -145,50 +180,84 @@ One `create-item` operation carries the whole item plus every translation it nee
 ```json
 {
   "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>", "index": 1 },
+  "target": {
+    "parentItemId": "<root-group-id>",
+    "index": 1
+  },
   "item": {
     "id": "choice_2",
-    "key": "choice_2",
     "itemType": "choiceItem",
     "config": {
       "id": "choice_2",
       "maxSelection": 1,
       "shuffleOptions": false,
       "options": [
-        { "id": "strawberry", "key": "strawberry" },
-        { "id": "blueberry", "key": "blueberry" },
+        {
+          "id": "strawberry",
+          "code": "strawberry"
+        },
+        {
+          "id": "blueberry",
+          "code": "blueberry"
+        },
         {
           "id": "other",
-          "key": "other",
           "embeddedForm": {
             "id": "other",
             "authoringMode": "simple",
             "fieldGroups": [
               {
                 "id": "other_details",
-                "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+                "layout": {
+                  "base": 1,
+                  "xs": 1,
+                  "sm": 1,
+                  "md": 1,
+                  "xl": 1
+                },
                 "fields": [
                   {
                     "id": "other_text",
-                    "key": "other_text",
                     "type": "input",
                     "required": true,
-                    "controller": { "type": "input", "inputMode": "text" },
-                    "validations": []
+                    "controller": {
+                      "type": "input",
+                      "inputMode": "text"
+                    },
+                    "validations": [],
+                    "variableName": "other_text"
                   }
                 ]
               }
             ]
-          }
+          },
+          "code": "other"
         }
-      ]
+      ],
+      "variableName": "choice_2"
     }
   },
   "translations": [
-    { "locale": "en", "contentKey": "title", "plainText": "Favorite berry" },
-    { "locale": "en", "contentKey": "options.strawberry.label", "plainText": "Strawberry" },
-    { "locale": "en", "contentKey": "options.blueberry.label", "plainText": "Blueberry" },
-    { "locale": "en", "contentKey": "options.other.label", "plainText": "Other" },
+    {
+      "locale": "en",
+      "contentKey": "title",
+      "plainText": "Favorite berry"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.strawberry.label",
+      "plainText": "Strawberry"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.blueberry.label",
+      "plainText": "Blueberry"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.other.label",
+      "plainText": "Other"
+    },
     {
       "locale": "en",
       "contentKey": "embeddedForms.other.fields.other_text.label",
@@ -207,20 +276,32 @@ Use `maxSelection: null` for "select all that apply" / checkbox-style questions:
 ```json
 {
   "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>", "index": 1 },
+  "target": {
+    "parentItemId": "<root-group-id>",
+    "index": 1
+  },
   "item": {
     "id": "industries_worked",
-    "key": "industries_worked",
     "itemType": "choiceItem",
     "config": {
       "id": "industries_worked",
       "maxSelection": null,
       "shuffleOptions": false,
       "options": [
-        { "id": "healthcare", "key": "HEALTHCARE" },
-        { "id": "education", "key": "EDUCATION" },
-        { "id": "food_service", "key": "FOOD_SERVICE" }
-      ]
+        {
+          "id": "healthcare",
+          "code": "HEALTHCARE"
+        },
+        {
+          "id": "education",
+          "code": "EDUCATION"
+        },
+        {
+          "id": "food_service",
+          "code": "FOOD_SERVICE"
+        }
+      ],
+      "variableName": "industries_worked"
     }
   },
   "translations": [
@@ -229,9 +310,21 @@ Use `maxSelection: null` for "select all that apply" / checkbox-style questions:
       "contentKey": "title",
       "plainText": "Which industries have you worked in? Select all that apply."
     },
-    { "locale": "en", "contentKey": "options.healthcare.label", "plainText": "Healthcare" },
-    { "locale": "en", "contentKey": "options.education.label", "plainText": "Education" },
-    { "locale": "en", "contentKey": "options.food_service.label", "plainText": "Food service" }
+    {
+      "locale": "en",
+      "contentKey": "options.healthcare.label",
+      "plainText": "Healthcare"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.education.label",
+      "plainText": "Education"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.food_service.label",
+      "plainText": "Food service"
+    }
   ]
 }
 ```
@@ -249,7 +342,13 @@ Interactive form question:
     "fieldGroups": [
       {
         "id": "main",
-        "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+        "layout": {
+          "base": 1,
+          "xs": 1,
+          "sm": 1,
+          "md": 1,
+          "xl": 1
+        },
         "fields": []
       }
     ]
@@ -264,8 +363,8 @@ Authoring modes and Add item presets:
 - `Text` → `input`, `Long text` → `textarea`, `Number` → `number`, `Slider` → `slider`, `Dropdown` → `select`, `Date` → `datepicker`, and `Switch` → `switch`.
 - These seven presets use `authoringMode: "simple"` with exactly one internal field group containing exactly one field. The field group remains part of persisted/runtime data; hiding it is only an editor abstraction.
 - `Blank form` uses `authoringMode: "custom"`. Any finished multi-field/group form also uses custom mode.
-- Simple mode exposes the existing field's label, description, required state, and compatible controller settings. It does not expose groups, layouts, field reordering, field keys, or field-type switching.
-- Adding/removing/moving fields or groups, changing layout, or changing the sole field's key/type is a one-way transition to custom. Preserve the existing field and every translation. Never leave a multi-field, empty, or multi-group structure marked simple.
+- Simple mode exposes the existing field's label, description, required state, and compatible controller settings. It does not expose groups, layouts, field reordering, field variable names, or field-type switching.
+- Adding/removing/moving fields or groups, changing layout, or changing the sole field's variableName/type is a one-way transition to custom. Preserve the existing field and every translation. Never leave a multi-field, empty, or multi-group structure marked simple.
 - If a stored simple form lacks its sole first field, treat it as custom without deleting any remaining data.
 
 Fields normally need at least one non-empty group to be useful. An explicit `authoringMode: "custom"` with one empty group is the supported Blank form starting preset.
@@ -282,7 +381,13 @@ Example field group layout:
 {
   "id": "main",
   "hasDisplayCondition": true,
-  "layout": { "base": 1, "xs": 1, "sm": 2, "md": 2, "xl": 3 },
+  "layout": {
+    "base": 1,
+    "xs": 1,
+    "sm": 2,
+    "md": 2,
+    "xl": 3
+  },
   "fields": []
 }
 ```
@@ -297,21 +402,18 @@ Field shape:
 ```json
 {
   "id": "age",
-  "key": "AGE",
   "type": "number",
   "required": true,
-  "controller": { "type": "number", "step": 1 },
-  "validations": []
+  "controller": {
+    "type": "number",
+    "step": 1
+  },
+  "validations": [],
+  "variableName": "age"
 }
 ```
 
-`key` is the field's exact response-slot identifier. Choose a stable coding key for the field's
-role within this form item. Do not copy the question wording, duplicate context already present in
-the item key, or add ordering suffixes such as `q1`. For a single-field form, concise keys such as
-`response`, `selection`, `value`, or `other_text` are often appropriate. Keys only need to be unique
-within the form item, so the same general key can be reused in another item. A user can edit the
-field key in the form editor, but changing it also changes the response-slot identifier; any
-expressions that use the old slot must be updated in the same change.
+`id` is the persistent response-slot ID, also used in field translation keys. `variableName` is its independent survey-wide unique coding name. Name each field for its meaning and units, including embedded fields. Renaming preserves slot IDs, answers and expressions. Do not reuse generic variable names across unrelated items.
 
 Field types and default controllers:
 
@@ -336,11 +438,14 @@ Supported controller properties by type:
 Select controller option shape:
 
 ```json
-{ "id": "weekly", "value": "weekly" }
+{
+  "id": "weekly",
+  "code": "weekly"
+}
 ```
 
 Visible select-option labels do NOT live in the controller config. They live in translations at `fields.<fieldId>.options.<optionId>.label`.
-If a select controller option has `id: "minder_7_dagen", value: "minder_7_dagen"`, the visible Dutch label still needs a separate translation such as `fields.<fieldId>.options.minder_7_dagen.label`: "minder dan 7 dagen". Without this translation, respondents see the raw key/value in the dropdown.
+If a select controller option has `id: "minder_7_dagen", code: "minder_7_dagen"`, the visible Dutch label still needs a separate translation such as `fields.<fieldId>.options.minder_7_dagen.label`: "minder dan 7 dagen". Without this translation, respondents see the raw identifier/code in the dropdown.
 
 Field translation keys:
 
@@ -365,10 +470,12 @@ MANDATORY: every `select` option needs a matching `fields.<fieldId>.options.<opt
 ```json
 {
   "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>", "index": 1 },
+  "target": {
+    "parentItemId": "<root-group-id>",
+    "index": 1
+  },
   "item": {
     "id": "form_1",
-    "key": "form_1",
     "itemType": "formItem",
     "config": {
       "id": "form_1",
@@ -376,22 +483,34 @@ MANDATORY: every `select` option needs a matching `fields.<fieldId>.options.<opt
       "fieldGroups": [
         {
           "id": "main",
-          "layout": { "base": 1, "xs": 1, "sm": 1, "md": 1, "xl": 1 },
+          "layout": {
+            "base": 1,
+            "xs": 1,
+            "sm": 1,
+            "md": 1,
+            "xl": 1
+          },
           "fields": [
             {
               "id": "age",
-              "key": "AGE",
               "type": "number",
               "required": true,
-              "controller": { "type": "number", "step": 1 },
-              "validations": []
+              "controller": {
+                "type": "number",
+                "step": 1
+              },
+              "validations": [],
+              "variableName": "age"
             },
             {
               "id": "comments",
-              "key": "COMMENTS",
               "type": "textarea",
-              "controller": { "type": "textarea", "rows": 3 },
-              "validations": []
+              "controller": {
+                "type": "textarea",
+                "rows": 3
+              },
+              "validations": [],
+              "variableName": "comments"
             }
           ]
         }
@@ -399,9 +518,124 @@ MANDATORY: every `select` option needs a matching `fields.<fieldId>.options.<opt
     }
   },
   "translations": [
-    { "locale": "en", "contentKey": "title", "plainText": "About you" },
-    { "locale": "en", "contentKey": "fields.age.label", "plainText": "Your age" },
-    { "locale": "en", "contentKey": "fields.comments.label", "plainText": "Any comments?" }
+    {
+      "locale": "en",
+      "contentKey": "title",
+      "plainText": "About you"
+    },
+    {
+      "locale": "en",
+      "contentKey": "fields.age.label",
+      "plainText": "Your age"
+    },
+    {
+      "locale": "en",
+      "contentKey": "fields.comments.label",
+      "plainText": "Any comments?"
+    }
   ]
 }
 ```
+
+## choiceMatrix
+
+Toolbox presets have exact server-supported IDs on `create-item.presetId`:
+
+| User wording           | presetId                   | Actual toolbox defaults                              |
+| ---------------------- | -------------------------- | ---------------------------------------------------- |
+| Yes / No matrix        | `choiceMatrix.yesNo`       | Yes, No; scores 1, 2                                 |
+| 5-point scale / Likert | `choiceMatrix.fivePoint`   | Strongly disagree through Strongly agree; scores 1–5 |
+| 7-point scale / Likert | `choiceMatrix.sevenPoint`  | Seven agreement options; scores 1–7                  |
+| 5-point bipolar scale  | `choiceMatrix.bipolarFive` | Five numbered options, scores 1–5, `bipolar: true`   |
+
+These are editable starting configurations, not fixed measurement instruments. The bipolar preset does NOT imply scores −2…2: request those scores explicitly when wanted. Preset option labels are localized by the shared toolbox factory (English, Dutch, German). Supply `item.config.rows` and translations for `title` and every row label. Optional config values override preset defaults. Set an explicit primitive `config.id` if adding `<config.id>.startLabel`/`endLabel` at creation. The validated result exposes the generated option IDs for subsequent edits; do not guess them. With no `presetId`, author the complete custom scale. Existing toolbox items are ordinary matrices and all their settings remain editable.
+
+Match the response wording to the question's construct: agreement labels answer statements, while liking, satisfaction, frequency and intensity need corresponding anchors. Preserve exact toolbox wording when the user explicitly requests those defaults. When custom anchors are already known, include the complete ordered `item.config.options` with explicit stable IDs, scores and matching `<optionId>.label` translations in the creation operation; these replace preset options. This creates the intended scale directly without a second pass over generated IDs. For later edits, copy the existing IDs exactly and preserve them.
+
+Use a choice matrix for several row statements sharing the same categorical scale. Persistent IDs identify the primitive, rows, options, per-row computed scores and total. `prefix` and each `rowName` derive survey-wide unique names: `<prefix>_<rowName>`, `<prefix>_<rowName>_score` and `<prefix>_sum`. Inspect declared slots; do not synthesize IDs from those names.
+
+```json
+{
+  "id": "wellbeing_matrix",
+  "itemType": "choiceMatrix",
+  "config": {
+    "id": "wellbeing_primitive",
+    "prefix": "wellbeing",
+    "sumSlotId": "wellbeing_total",
+    "rows": [{ "id": "sleep_answer", "scoreSlotId": "sleep_score", "rowName": "sleep" }],
+    "options": [
+      { "id": "never", "code": "never", "score": 0 },
+      { "id": "always", "code": "always", "score": 4 }
+    ],
+    "layout": "automatic"
+  }
+}
+```
+
+Create with translations for `title`, `sleep_answer.label`, `never.label` and `always.label`. Option scores are numeric scoring semantics; codes are export strings and labels are translated wording. Supply all scores or leave them all absent. Optional `leadingNonScoring`/`trailingNonScoring` each hold ONE `{id, code?}` object (never an array and never a score). Each participates in answers but not scoring. There is at most one leading and one trailing non-scoring choice; a second at the same end requires an explicit product decision, not silently overwriting the first. Optional bipolar endpoints use `<config.id>.startLabel`/`endLabel`. Layout accepts `automatic`, `stacked` or `matrix`; `rowLabelPosition` accepts `beside` or `above`.
+
+Stored row answers are `reference` values containing exact option IDs. Computed score and sum slots are read-only and excluded from default exports unless explicitly included. A non-scoring or unanswered row has no score; a numeric score of zero is a defined score. The sum is absent when no visible rows have scored answers. Required rows use `required: true`. Use config patches for structural row/option/layout edits, translations for visible text, and `update-response-settings` for naming components, export codes and formats. Preserve surviving IDs. Reinspect expression diagnostics after removing slots/options.
+
+### Editing a choice matrix
+
+Inspect the current config before choosing array indices. Put all related patches and new translations in one `patch-item-config` operation. Example adding a final “Don't know” answer:
+
+```json
+{
+  "kind": "patch-item-config",
+  "itemId": "<inspected item ID>",
+  "patches": [
+    { "op": "add", "path": "/trailingNonScoring", "value": { "id": "dont_know", "code": "DK" } }
+  ],
+  "translations": [{ "locale": "en", "contentKey": "dont_know.label", "plainText": "Don't know" }]
+}
+```
+
+- Add a row at `/rows/-` with fresh `id`, `scoreSlotId`, unique `rowName` and its `<id>.label` translation. Duplicate by copying the row settings and all relevant locales into NEW IDs. Keep surviving IDs unchanged.
+- Remove rows/options with `remove` at the inspected index; reorder with `move` or replace the complete inspected array without changing IDs. `copy` alone duplicates IDs and is invalid. Remove or repair dependent expressions in the same turn.
+- Add scale options at `/options/-` with `id`, optional `code`, and a score if the existing scale is scored. Include `<optionId>.label`. To disable scoring, remove every scale score in one operation. To reverse scoring, reverse score VALUES in the existing options; do not reorder options or labels. For zero-based/one-based/bipolar scoring, assign 0…n−1 / 1…n / −(n−1)/2…(n−1)/2 to all scale options in one patch. Non-scoring choices stay outside this array.
+- Add or remove `/leadingNonScoring` or `/trailingNonScoring` as object properties. To move a non-scoring option from one end to the other, preserve its ID and label. To switch an option between scale and non-scoring roles, move the same ID atomically and add/remove its score appropriately.
+- Set `/bipolar` true and translate `<config.id>.startLabel` and `<config.id>.endLabel` for endpoints. Set `/rowLabelPosition` to `beside` or `above`. Layout and positive `stackingBreakpoint` affect presentation, not responses.
+- Row display conditions use `survey_expression` mutation `set-component-display-condition` with the exact row ID; required-row messages use `<rowId>.message`. Whole-question visibility uses `set-item-display-condition`. The current matrix player supports row visibility, not individual option/column/cell visibility or component disabling; do not claim those effects from merely storing an expression.
+
+## formMatrix
+
+Use a form matrix for independent row/column cells, with a column-level field type and optional cell overrides. Names derive from `<prefix>_<rowName>_<columnName>`; IDs and existing answers survive naming, ordering and layout edits. Every row/column intersection needs a persistent cell object, including static or empty cells, although only interactive cells declare response slots.
+
+```json
+{
+  "id": "visits_matrix",
+  "itemType": "formMatrix",
+  "config": {
+    "id": "visits_primitive",
+    "prefix": "visits",
+    "rows": [{ "id": "visit_row", "rowName": "baseline" }],
+    "columns": [
+      {
+        "id": "weight_column",
+        "columnName": "weight_kg",
+        "field": { "type": "number", "unit": "kg", "validations": [] }
+      }
+    ],
+    "cells": [{ "id": "baseline_weight", "rowId": "visit_row", "columnId": "weight_column" }],
+    "layout": "automatic"
+  }
+}
+```
+
+Translate `title`, `<rowId>.label`, `<columnId>.label`, and cell-specific labels/help when needed. Field types are `text` (optional multiline), `number` (step/unit), `date` (mode `year`, `year-month`, `year-month-day`), `dropdown` (options `[{id,code}]`), `boolean`, `static`, `empty`. Interactive field definitions carry `validations: []` and optional `required`. Dropdown answers contain option IDs; visible option labels use `<optionId>.label`. Cell overrides use the same field schema. Static cells use `<cellId>.content`. Use the capability's declared content surfaces for localization.
+
+### Editing a form matrix
+
+Config patches handle structural cells, overrides, columns and rows. Every structural edit must produce a complete rectangle in ONE `patch-item-config` operation:
+
+- For multi-row/column duplication, inspect the current arrays first, then construct the complete desired rows, columns and cells while retaining all surviving objects and IDs. Replacing these arrays together can be clearer than a long chain of index-sensitive patches. A duplicate is an addition; never rename or repurpose its source. Keep existing coding unchanged; choose short coding components for new units.
+- Adding a row also adds one fresh `{id,rowId,columnId}` cell per existing column; adding a column adds a cell for every row. Removing a row/column removes its associated cells in the same patch. The executor automatically cleans translations owned by removed components in every locale and inactive cell content after resetting overrides; inspect the result before attempting any extra raw translation removals. Reordering rows/columns changes only array order; preserve cell IDs and coordinates.
+- A column's `field` defines inherited settings. A cell `override` is a COMPLETE field definition, not a partial patch; use `add` at `/cells/<index>/override` when absent, or replace it when already present. Its content belongs to the cell ID. Reset it with `remove` to inherit the column again. Static and empty cells remain in `cells`, but have no response slot. Retyping a cell or column retains cell IDs, and may invalidate answers or expressions; inspect diagnostics and repair dependent logic when needed.
+- Shared field content belongs to `<columnId>.<role>`; overridden content belongs to `<cellId>.<role>`. Column headers always use `<columnId>.label`. Roles are `label`, `description`, `placeholder`, `message`, `content`, `yesLabel`, `noLabel`. Static text belongs to `<columnId>.content` when inherited or `<cellId>.content` when overridden. Number `unit` is a config string, not a content key.
+- Dropdown fields use `options: [{id,code}]`, with globally distinct component IDs and `<optionId>.label` translations. For an independent cell override copied from a shared dropdown, allocate new option and validation IDs and copy their translations in all existing locales. Reusing column-owned option/rule IDs in an override is invalid. Duplicate rows/columns the same way: new unit and cell IDs; deep-copy every existing override with new option/rule IDs and translated content. An override on the source must remain an override on the duplicate; omitting it silently changes that cell to the column default. After duplication, compare source and destination effective field types, settings, option codes and translated content, allowing only explicitly requested differences.
+- Interactive fields require `validations: []` even when empty. Required is the field's boolean `required` property. Text validations: `minLength`, `maxLength`, `pattern`; number: `integer`, `min`, `max`; date: `minDate`, `maxDate`; boolean: `mustBeTrue`; dropdown has no additional rules. Each rule has a fresh `id`, `type`, and a `value` where needed. Date values are calendar strings matching precision, e.g. `2026-09`, not timestamps. Date expressions go in `valueExpression` and use the expression grammar. Rule messages are `<ruleId>.message`; field required messages are `<fieldOwnerId>.message`. Bounds must be compatible, and minimum cannot exceed maximum.
+- Column `width` and `rowLabelWidth` accept `{mode:"default"}`, `{mode:"fixed",pixels:160}`, or `{mode:"fit",minPixels:120}` (numeric minima 48). Layout is `automatic`, `stacked`, or `matrix`; `stackingBreakpoint` is a positive pixel width. Boolean arrangement is `horizontal` or `vertical`; text uses `multiline`; dates use `mode`; numbers use `step` and `unit`.
+- Put new visible translations inside the patch operation; blank or incorrect namespaces are rejected. For row visibility, use `survey_expression` mutation `set-component-display-condition` with the row ID. Whole-question visibility uses `set-item-display-condition`. The matrix player currently supports row visibility, not column/cell visibility or component disabling. Hidden-row answers are retained in the session and restored when shown, but excluded from expressions, validation, scoring and submission while hidden.
+
+Coding uses one matrix naming edit with `primitiveId`, `prefix`, `rows` and/or `columns`; never set arbitrary names or headers on derived cells. A shared dropdown code change affects all cells using that option set. Keep numeric scores, identities and translated wording separate from coding changes.

package/dist/references/localization.md

@@ -17,10 +17,11 @@ Use this reference when the user asks to translate, localize, add a language, or
 ## Scope A Complete Localization Correctly
 
 1. Use `survey_inspect` with `action: "localization"`, the source locale, and the target locale. Page until `nextCursor` is absent; this covers existing respondent-visible item and survey translation surfaces without one item-details call per item.
-2. Inspect item configuration separately only when the localization surface result or an audit indicates that the source survey itself is missing a visible content key. This includes choice-option labels, form-field labels, select-option labels, embedded-form labels, and validation copy.
-3. Preserve the source language while writing each target-language value under the target locale. Do not replace source content or translation containers.
-4. Use `update-item-translation` for ordinary item content. Use typed choice operations only when also changing the choice structure. Use a focused raw patch only for a supported survey-level translation surface that has no typed operation.
-5. Before proposing, check that every visible label implied by the inspected item configuration has a target-locale translation. A title alone is not a complete localization of a choice or form item.
+2. Treat `sourceText` and `targetText` as previews. When `sourceTruncated` is true for plain text, retrieve `sourceTextPath` through `survey_inspect` action `raw-json`, then follow `nextTextOffset` using `textOffset` and that same path until all segments are read. Translate the complete source, never only the preview. Rich-text `sourceContent` already contains the full canonical value. `targetPresent` proves presence, not translation fidelity or completeness.
+3. Inspect item configuration separately only when the localization surface result or an audit indicates that the source survey itself is missing a visible content key. This includes choice-option labels, form-field labels, select-option labels, embedded-form labels, and validation copy.
+4. Preserve the source language while writing each target-language value under the target locale. Do not replace source content or translation containers.
+5. Use `update-item-translation` for ordinary item content. Use typed choice operations only when also changing the choice structure. Use a focused raw patch only for a supported survey-level translation surface that has no typed operation.
+6. Before proposing, check that every visible label implied by the inspected item configuration has a target-locale translation. A title alone is not a complete localization of a choice or form item.
 
 ## Bounded Execution