@case-framework/survey-assistant 0.6.0 → 0.8.0

package/dist/references/assistant-operations.md

@@ -16,7 +16,7 @@ the latest cumulative change set for browser apply.
 6. Use `survey-json-patch` through `survey_change` only for assistant-editable fields not covered by
    typed or expression operations.
 7. Mutation calls submit deltas to one request-scoped draft. Each successful call automatically accumulates with earlier successful calls, and later calls may target ids or assets introduced by the draft.
-8. A rejected delta leaves the validated draft unchanged and blocks turn authorization. Correct the same target in another mutation call; an unrelated valid edit does not clear the block. Successful turn completion authorizes only the latest cumulative draft for one editor apply.
+8. A rejected delta leaves the validated draft unchanged and blocks turn authorization. Correct every rejected operation and surface; unrelated valid edits do not clear the block. `pendingRepairs` reports outstanding obligations after each mutation. When `requiresExplicitRetry` is true, supply the rejected change id in `retryOfChangeIds` with the complete corrected scope. Correct unavailable or invalid target identities. Only when `allowsAcknowledgment` is true, inspect the validator-confirmed no-op and acknowledge it with `survey_change` using `operations: []` and `retryOfChangeIds`; do not invent an unrelated edit. Acknowledgments may be batched and cannot discharge identifiable pending edits. Malformed operations, invalid targets, and failed creations require a linked non-empty corrected retry. An ordinary empty call is invalid and must also be reconciled by a linked non-empty retry. Successful completion authorizes only the latest cumulative draft for one editor apply; acknowledgment alone never creates an empty editor commit.
 
 ## `survey_change` Typed Operations
 
@@ -25,16 +25,22 @@ For the canonical fields of one operation, call `survey_authoring_reference` aga
 from the same validator used by `survey_change`, so this reference does not duplicate a static
 operation catalog.
 
+Generated operation schemas describe the canonical post-normalization contract. The model-facing
+`survey_change` input also accepts the compact `richTextBlocks` shorthand documented in
+`rich-text-content` wherever a typed translation accepts structured `content`; it is normalized to
+canonical `content` before these schemas run. Never combine shorthand with `plainText` or `content`
+in the same translation.
+
 `create-item`
 
 - Creates a new item under `target.parentItemId`.
-- Use root group id/key for top-level items.
+- Use exact root group ID for top-level items.
 - Put visible text in top-level `translations`, not inside `item`.
-- Each translation accepts either `plainText` or a complete structured `content` value.
-- When a new item must contain an image, prefer putting the `richText` value with the image block directly in `create-item.translations[].content`.
+- Each canonical translation contains exactly one of `plainText` or a complete structured `content` value. Model-authored `survey_change` input may use `richTextBlocks` instead as described above.
+- When a new item must contain an image, prefer `richTextBlocks` and place the canonical image block inside that array. Use canonical `content` for the whole translation only when the compact interface is unsuitable.
 - Use the actual content locale in `translations[].locale`. Missing locales are introduced when translations are applied.
 - Put item configuration inside `item.config`, not beside `item`.
-- Item key must be unique among siblings.
+- IDs must be unique. Duplicate editor names are allowed; response variable names must be unique survey-wide.
 - Use explicit item ids when you need to reference the new item in the same proposal.
 
 Minimal valid examples:
@@ -42,10 +48,11 @@ Minimal valid examples:
 ```json
 {
   "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>" },
+  "target": {
+    "parentItemId": "<root-group-id>"
+  },
   "item": {
     "id": "intro_privacy",
-    "key": "intro_privacy",
     "itemType": "infoItem",
     "config": {}
   },
@@ -62,22 +69,39 @@ Minimal valid examples:
 ```json
 {
   "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>" },
+  "target": {
+    "parentItemId": "<root-group-id>"
+  },
   "item": {
     "id": "overall_satisfaction",
-    "key": "overall_satisfaction",
     "itemType": "choiceItem",
     "config": {
       "id": "overall_satisfaction",
       "maxSelection": 1,
       "shuffleOptions": false,
       "options": [
-        { "id": "very_dissatisfied", "key": "VERY_DISSATISFIED" },
-        { "id": "dissatisfied", "key": "DISSATISFIED" },
-        { "id": "neutral", "key": "NEUTRAL" },
-        { "id": "satisfied", "key": "SATISFIED" },
-        { "id": "very_satisfied", "key": "VERY_SATISFIED" }
-      ]
+        {
+          "id": "very_dissatisfied",
+          "code": "VERY_DISSATISFIED"
+        },
+        {
+          "id": "dissatisfied",
+          "code": "DISSATISFIED"
+        },
+        {
+          "id": "neutral",
+          "code": "NEUTRAL"
+        },
+        {
+          "id": "satisfied",
+          "code": "SATISFIED"
+        },
+        {
+          "id": "very_satisfied",
+          "code": "VERY_SATISFIED"
+        }
+      ],
+      "variableName": "overall_satisfaction"
     }
   },
   "translations": [
@@ -91,10 +115,26 @@ Minimal valid examples:
       "contentKey": "options.very_dissatisfied.label",
       "plainText": "Very dissatisfied"
     },
-    { "locale": "en", "contentKey": "options.dissatisfied.label", "plainText": "Dissatisfied" },
-    { "locale": "en", "contentKey": "options.neutral.label", "plainText": "Neutral" },
-    { "locale": "en", "contentKey": "options.satisfied.label", "plainText": "Satisfied" },
-    { "locale": "en", "contentKey": "options.very_satisfied.label", "plainText": "Very satisfied" }
+    {
+      "locale": "en",
+      "contentKey": "options.dissatisfied.label",
+      "plainText": "Dissatisfied"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.neutral.label",
+      "plainText": "Neutral"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.satisfied.label",
+      "plainText": "Satisfied"
+    },
+    {
+      "locale": "en",
+      "contentKey": "options.very_satisfied.label",
+      "plainText": "Very satisfied"
+    }
   ]
 }
 ```
@@ -102,10 +142,11 @@ Minimal valid examples:
 ```json
 {
   "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>" },
+  "target": {
+    "parentItemId": "<root-group-id>"
+  },
   "item": {
     "id": "personal_data",
-    "key": "personal_data",
     "itemType": "formItem",
     "config": {
       "id": "personal_data",
@@ -113,15 +154,29 @@ Minimal valid examples:
       "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": "email",
-              "key": "EMAIL",
               "type": "input",
               "required": false,
-              "controller": { "type": "input", "inputMode": "email" },
-              "validations": [{ "id": "email", "type": "email" }]
+              "controller": {
+                "type": "input",
+                "inputMode": "email"
+              },
+              "validations": [
+                {
+                  "id": "email",
+                  "type": "email"
+                }
+              ],
+              "variableName": "email"
             }
           ]
         }
@@ -129,15 +184,24 @@ Minimal valid examples:
     }
   },
   "translations": [
-    { "locale": "en", "contentKey": "title", "plainText": "Personal information" },
-    { "locale": "en", "contentKey": "fields.email.label", "plainText": "Email address" }
+    {
+      "locale": "en",
+      "contentKey": "title",
+      "plainText": "Personal information"
+    },
+    {
+      "locale": "en",
+      "contentKey": "fields.email.label",
+      "plainText": "Email address"
+    }
   ]
 }
 ```
 
-`update-item-key`
+`update-response-settings`
 
-- Changes item coding key. This affects fullKey paths and response naming.
+- Applies scalar names, matrix naming components, option export codes and slot export defaults atomically. Load response-variables.md for the exact shape.
+- Preserve persistent IDs, expressions, labels and numeric scores. Shared validation rejects invalid names, collisions and direct matrix-cell renames.
 
 `update-item-label`
 
@@ -155,7 +219,7 @@ Minimal valid examples:
 - Use this with a new locale code when adding translated content for a locale that is not yet present.
 - Use for titles, subtitles, top/bottom content, card footer, info content, and simple field/option labels when the key is known.
 - Use `plainText` for simple unformatted text.
-- Use `content` for structured survey content. For formatted text, set `content.type` to `richText`; do not use markdown syntax to request formatting.
+- For a complete formatted replacement, prefer top-level `richTextBlocks`; it normalizes to canonical `content`. Use canonical `content` directly when needed. Do not use markdown syntax to request formatting.
 
 `update-placed-image`
 
@@ -176,18 +240,40 @@ Minimal valid examples:
 `add-choice-option`, `update-choice-option-label`, `remove-choice-option`, `reorder-choice-options`
 
 - Use for ordinary choice option edits on existing choice items.
-- For option identifiers, prefer exact id; validation can also normalize key or visible label.
-- For `add-choice-option`, use `option: { id?, key?, label: "visible text" }`. The label is a plain string, not a nested translation object; the operation writes its matching `options.<optionId>.label` translation automatically. `update-choice-option-label.label` is also a plain string.
+- Use exact option IDs. Codes and labels are not target aliases.
+- For `add-choice-option`, use `option: { id?, code?, label: "visible text" }`. The label is a plain string, not a nested translation object; the operation writes its matching `options.<optionId>.label` translation automatically. `update-choice-option-label.label` is also a plain string.
 
 `upsert-form-field-group`, `remove-form-field-group`, `reorder-form-field-groups`, `upsert-form-field`, `remove-form-field`, `move-form-field`
 
 - Target a top-level form with `{ "itemId": "<form-id>" }` or a choice option's form with `{ "itemId": "<choice-id>", "optionId": "<option-id>" }`.
 - Add visible labels, placeholders, option labels, and validation messages in the operation's `translations` array so structure and content remain atomic.
 - Group and field identifiers are stable ids; reorder operations require the complete current id set.
+- To update only an existing field group's responsive layout, use `upsert-form-field-group` with the existing group id and a `group` containing `id` and `layout`. Omitted fields and other existing group properties are preserved.
 - Simple forms contain one group and one field. Compatible updates to that same field may remain
   simple; structural changes automatically make the form custom. This applies to top-level and
   embedded forms and is intentionally one-way.
 
+Update an existing form field group's layout without replacing its fields:
+
+```json
+{
+  "kind": "upsert-form-field-group",
+  "target": {
+    "itemId": "profile"
+  },
+  "group": {
+    "id": "main",
+    "layout": {
+      "base": 1,
+      "xs": 1,
+      "sm": 2,
+      "md": 2,
+      "xl": 3
+    }
+  }
+}
+```
+
 `set-embedded-form`, `remove-embedded-form`
 
 - Add or remove a choice option's inline form using item and option ids, without raw array-index patches.
@@ -198,7 +284,10 @@ Minimal valid examples:
 
 `move-item`, `reorder-items`
 
-- Move an existing item to a group/index or set a group's complete direct-child order.
+- `create-item.target.index` and `move-item.target.index` are zero-based; omission appends and `0` inserts first. Move uses a different parent; change sibling order with `reorder-items`.
+- Reorder shape: `{ kind: "reorder-items", parentItemId, itemIds }`; `parentItemId` is top-level, not inside `target`.
+- Inspect the parent with `survey_inspect` action `current-context`, scopes `["outline"]`, `outlineMode: "children"`, and `itemRef` before reordering. Page until the complete child list is retrieved.
+- Verify position against the returned stored placement or child order. A shuffled group can display a different respondent order.
 - The validator rejects root moves, cycles, missing children, duplicates, and incomplete reorder lists.
 
 `update-survey-metadata`, `update-survey-pagination`, `update-survey-translation`, `add-survey-locale`, `remove-survey-locale`
@@ -231,53 +320,39 @@ Minimal valid examples:
   validation messages are ordinary config/content, not expression mutations.
 - Use it for field controller internals and any existing custom-registry item config that is not covered by a typed helper.
 
-## Raw Patch Examples
+## Raw Patch Example
 
-Update a form field-group layout:
+Use a raw patch only for an existing, inspected survey-root extension that has no typed operation,
+`patch-item-config` helper, or `survey_expression` mutation. Obtain the exact path and current value
+from `survey_inspect` first. A guarded replacement has this shape:
 
 ```json
 {
   "kind": "survey-json-patch",
   "patches": [
+    {
+      "op": "test",
+      "path": "/<inspected-extension>/<leaf>",
+      "value": "<current-value>"
+    },
     {
       "op": "replace",
-      "path": "/surveyItems/3/config/fieldGroups/0/layout",
-      "value": { "base": 1, "xs": 1, "sm": 2, "md": 2, "xl": 3 }
+      "path": "/<inspected-extension>/<leaf>",
+      "value": "<requested-value>"
     }
   ]
 }
 ```
 
-Only when the user explicitly requests an empty registration, add a missing locale shell after inspection confirms that the locale does not exist:
-
-```json
-{
-  "kind": "add-survey-locale",
-  "locale": "nl"
-}
-```
-
-Never use this whole-branch operation for an existing locale. Patch the required leaf key instead,
-or use `update-item-translation`, so sibling translations are preserved.
-
-Add a form field and matching label in one proposal:
-
-- Patch the form item config fieldGroups array.
-- Patch `/translations/<locale>/itemTranslations/<itemId>/fields.<fieldId>.label`. This is REQUIRED, not optional — a field with no label translation shows no visible label to respondents.
-- Include any placeholder, unit, option labels, or validation messages that the new field needs.
-
-Survey-level translation branches:
-
-- `/translations/<locale>/surveyCardContent` stores survey-card copy such as title/description content.
-- `/translations/<locale>/navigationContent` stores participant navigation labels.
-- `/translations/<locale>/validationMessages` stores survey-level validation copy such as `invalidResponse`.
-- Use `survey-json-patch` for these branches today.
-
-Add an embedded input to an existing choice option:
+The placeholders describe the shape only; never send them literally or invent an extension path.
+Keep every related raw edit in the same `patches` array, and keep this `survey-json-patch` operation
+as the proposal's only operation.
 
-- Inspect the choice item with `survey_inspect action=raw-json` and use its returned `/surveyItems/<choiceIndex>` path; item-details alone is not sufficient for JSON Pointer construction.
-- Patch the target option object under `/surveyItems/<choiceIndex>/config/options/<optionIndex>/embeddedForm`.
-- Patch `/translations/<locale>/itemTranslations/<choiceItemId>/embeddedForms.<optionId>.fields.<fieldId>.label` with a complete Content value such as `{ "type": "md", "content": "Please specify" }`. This is REQUIRED, not optional — a field with no label translation shows no visible label to respondents (only its raw control type, e.g. "Input"). Never add, replace, or remove the surrounding locale or itemTranslations container; it would discard sibling text.
-- Do not patch `allowOther`; it is not part of the current choice config.
+### Raw Patch Rules
 
-Before raw patches, use `survey_inspect` with raw JSON paths for the exact item index and current object shape.
+- Paths are survey-root JSON Pointers from current raw inspection. Each `/` separates path segments; within a segment, encode `~` as `~0` and `/` as `~1`.
+- Patches run sequentially, so each operation sees the result of the previous operations. Parent paths must already exist; create missing containers explicitly in dependency order when the inspected extension contract permits them.
+- Use `add` to create or replace an object member, insert before an existing array index, or append to an array with `/-`. Use `replace`, `remove`, or `test` only when the target path already exists.
+- `move` and `copy` require an existing `from` path and use `path` as an add destination. A move removes the source before resolving the destination, so later array indexes refer to the already-modified array.
+- A `test` compares the complete JSON value and type. Preserve booleans, numbers, `null`, arrays, and objects as those JSON types rather than converting them to strings. Put a matching `test` immediately before an overwrite, removal, or move when current inspection provides the expected value.
+- Never patch `/$schema`, translation roots or whole existing locale branches, expression-owned paths, or another protected location rejected by the validator. Use the specialized operation or tool named by validation instead.

package/dist/references/core-rules.md

@@ -3,15 +3,18 @@
 Use this skill whenever you create, edit, validate, inspect, or explain CASE survey definitions.
 
 Core rules:
+
 - Static survey knowledge comes from this skill. Do not inspect an existing survey merely to learn the data model.
 - Live survey state still comes from tools. Inspect the current context, item details, raw paths, locales, and response slots before editing existing content.
 - For long surveys, do not rely on the compact outline alone. Use survey_inspect action=current-context with scope=outline, cursor/limit, and outlineMode=full for survey-wide order; outlineMode=children with itemRef for a specific parent; search-items for text lookup. Never guess append indexes or references from an outline that says it is truncated.
 - Use typed `survey_change` operations for common edits and `survey_expression` for expressions on existing state. Use raw JSON Patch only for assistant-editable fields not covered by either specialized path.
 - Always validate/propose edits through `survey_change` or `survey_expression` prepare mode. A validated candidate is not proof of browser application; never present rejected, superseded, or incomplete work as completed.
-- Treat every identifier as exact data across every item type: item ids/keys, response-slot ids,
-  option ids/keys, field and group ids/keys, component keys, validation keys, prefill ids, template
+- Treat every identifier as exact data across every item type: item IDs, response-slot IDs and variable names,
+  option IDs/codes, field and group IDs, component keys, validation keys, prefill ids, template
   keys, content keys, and custom-capability identifiers. Never humanize them by changing case,
   inserting/removing separators, splitting camelCase, or substituting a label/title/name. Visible
   prose belongs in translations or editor labels. When explaining an existing survey, quote the
   exact inspected identifier.
-- Load only the reference you need: survey-data-model.md, source-material-surveys.md, localization.md, rich-text-content.md, item-types.md, embedded-forms.md, expressions.md, or assistant-operations.md.
+- Load only the reference you need: survey-data-model.md, source-material-surveys.md, localization.md, rich-text-content.md, item-types.md, embedded-forms.md, expressions.md, response-variables.md, or assistant-operations.md.
+
+Survey schema version 2 separates identity from naming. Use exact item IDs for mutations. Discover items by resolved editor name or breadcrumb with search; duplicated names are legal. Response variables, including embedded inputs and matrix computed slots, come from the shared declarations. Use structured `{slotId,method}` references and `update-response-settings` for coding. Moving, relabeling or translating an item does not change its response identity.

package/dist/references/embedded-forms.md

@@ -36,27 +36,36 @@ breakpoint for one full-width field. Supported counts are `1` through `4`.
 ```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"
 }
 ```
 
@@ -71,19 +80,31 @@ inside a choice option.
   "fieldGroups": [
     {
       "id": "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": "contact_name",
-          "key": "contact_name",
           "type": "input",
-          "controller": { "type": "input", "inputMode": "text" }
+          "controller": {
+            "type": "input",
+            "inputMode": "text"
+          },
+          "variableName": "contact_name"
         },
         {
           "id": "contact_note",
-          "key": "contact_note",
           "type": "textarea",
-          "controller": { "type": "textarea", "rows": 3 }
+          "controller": {
+            "type": "textarea",
+            "rows": 3
+          },
+          "variableName": "contact_note"
         }
       ]
     }
@@ -94,7 +115,7 @@ inside a choice option.
 Use an explicit, stable option id. The config option id, translation prefix, and embedded response
 reference must agree exactly. When editing an existing option, copy its current `id` exactly,
 including case. The `embeddedForms.<optionId>` translation segment always comes from the containing
-choice option's `id`; it does not come from the option `key` or the nested `embeddedForm.id`.
+choice option's `id`; it does not come from the option `code` or the nested `embeddedForm.id`.
 
 ## Required Content
 
@@ -122,5 +143,4 @@ specify”, use option label “Other” and field label “Please specify”.
 6. Before adding/reordering groups or fields on a simple follow-up, let the typed mutation promote
    it to custom; do not construct multi-field data with `authoringMode: "simple"`.
 
-Embedded response slots use `embedded.<optionId>.<fieldKey>`, for example
-`embedded.other.other_text`.
+Embedded response slots are the persistent field IDs, exactly as declared in the shared slot registry. They are not reconstructed from option IDs or variable names. Every field has a survey-wide unique `variableName`. Inspect declarations before authoring expressions; translations keep the `embeddedForms.<optionId>.fields.<fieldId>` prefix.