@case-framework/survey-assistant 0.7.0 → 0.8.0

package/dist/references/assistant-operations.md

@@ -34,13 +34,13 @@ 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 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:
@@ -48,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": {}
   },
@@ -68,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": [
@@ -97,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"
+    }
   ]
 }
 ```
@@ -108,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",
@@ -119,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"
             }
           ]
         }
@@ -135,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`
 
@@ -182,8 +240,8 @@ 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`
 
@@ -200,10 +258,18 @@ Update an existing form field group's layout without replacing its fields:
 ```json
 {
   "kind": "upsert-form-field-group",
-  "target": { "itemId": "profile" },
+  "target": {
+    "itemId": "profile"
+  },
   "group": {
     "id": "main",
-    "layout": { "base": 1, "xs": 1, "sm": 2, "md": 2, "xl": 3 }
+    "layout": {
+      "base": 1,
+      "xs": 1,
+      "sm": 2,
+      "md": 2,
+      "xl": 3
+    }
   }
 }
 ```
@@ -218,7 +284,10 @@ Update an existing form field group's layout without replacing its fields:
 
 `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`

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.