@case-framework/survey-assistant 0.8.0 → 0.9.0

package/dist/references/assistant-operations.md

@@ -1,70 +1,28 @@
 # Assistant Operations
 
-Use `survey_change` for typed survey mutations and `survey_expression` with
-`action: "prepare"` for expression mutations. Both tools submit deltas to one
-request-scoped draft. Only successful completion of the whole turn authorizes
-the latest cumulative change set for browser apply.
-
-## Common Workflow
-
-1. Load only the narrow authoring reference needed for the requested convention.
-2. Use `survey_inspect` for revision, selected item, root group, locale, available item types, response slots, item details, or focused raw JSON.
-3. For existing items, inspect item details or exact raw paths before editing.
-   For image assets, use `survey_inspect` with `action: "assets"`; it returns each explicit `assetId`, metadata, and usage locations without embedded bytes.
-4. Prefer typed `survey_change` operations for supported edits.
-5. Use `survey_expression` for expression mutations on existing state.
-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 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
-
-For the canonical fields of one operation, call `survey_authoring_reference` again with
-`topic: "assistant-operations"` and that `operationKind`. The returned JSON Schema is generated
-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 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`.
-- 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:
+Use `survey_change` for typed survey edits and `survey_expression` for expression-bearing changes. Load this reference with `operationKind` and, when relevant, `elementType` to obtain the generated payload contract and installed capability guidance. Those contracts are authoritative; examples below show complete authoring patterns, not alternative schemas.
 
-```json
-{
-  "kind": "create-item",
-  "target": {
-    "parentItemId": "<root-group-id>"
-  },
-  "item": {
-    "id": "intro_privacy",
-    "itemType": "infoItem",
-    "config": {}
-  },
-  "translations": [
-    {
-      "locale": "en",
-      "contentKey": "content",
-      "plainText": "This survey asks about your customer experience. Please do not include sensitive personal information."
-    }
-  ]
-}
-```
+## Creation
+
+`insert-preset`
+
+- Use an advertised `elementType` and `presetId` for a toolbox starting point. `target: {parentItemId, index?}` creates a content item containing just that element; `target: {layoutId, index?}` puts the element into an existing layout. This is the ordinary way to work with one question at a time.
+- Set the respondent locale explicitly. The registry allocates persistent IDs and unique response names. Inspect the resulting draft before changing labels, options, names or expressions; never guess generated IDs.
+- A preset is an editable starting configuration, not completed respondent content. Add the actual prompt, labels and constraints requested by the user.
+
+`create-item`, `insert-element`, `insert-blocks`
+
+- Use `create-item` when the complete authored structure is already known. Flow items are `content`, `group`, or `page-break`. The target must be an existing group; create groups empty and children in parent-before-child order.
+- A content item has `config.body.blocks`. Layout blocks have `kind: "layout"`, `id`, `layout` and `elements`. Elements have `kind: "element"`, `id`, `elementType` and their registered `config`. Do not put elements directly into the survey flow.
+- Section blocks have `kind: "section"`, `id` and `body`. They occupy a full row and contain layouts, never sections. They are semantic groups within one item, distinct from flow groups. Translate their `title` role when they need an accessible group name.
+- `insert-element` inserts a complete registered element into a layout. `insert-blocks` inserts `body.blocks` into a content item's, section's or triggering option's body identified by `bodyOwnerId`.
+- Every newly owned ID is survey-wide unique. Allocate explicit IDs for owners you will translate or reference in the same call. Persistent owner IDs, slot IDs, variable names and option export codes are separate; do not humanize or reuse inspected identifiers.
+- Include new wording in `translations: [{ownerId, role, locale, plainText|content}]` so structure and content are atomic. Supply a usable label for every input and option, or use a single input's unambiguous enclosing title. Do not repeat the same title as an element label unnecessarily.
+- New owners may contain expressions in their creation payload. Create controlling slots before dependents; load expressions for a complete dependent-item example. Change expressions on existing state through `survey_expression`.
+
+### Full worked example: a single-choice question
+
+Use the actual inspected root group ID in place of `<root-group-id>`. These explicit IDs illustrate new allocations; choose unused IDs in the current survey.
 
 ```json
 {
@@ -73,72 +31,103 @@ Minimal valid examples:
     "parentItemId": "<root-group-id>"
   },
   "item": {
-    "id": "overall_satisfaction",
-    "itemType": "choiceItem",
+    "id": "satisfaction",
+    "itemType": "content",
     "config": {
-      "id": "overall_satisfaction",
-      "maxSelection": 1,
-      "shuffleOptions": false,
-      "options": [
-        {
-          "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"
+      "body": {
+        "blocks": [
+          {
+            "kind": "layout",
+            "id": "satisfaction-layout",
+            "layout": {
+              "mode": "automatic",
+              "maxColumns": 1
+            },
+            "elements": [
+              {
+                "kind": "element",
+                "id": "satisfaction-choice",
+                "elementType": "choice",
+                "config": {
+                  "slotId": "satisfaction-slot",
+                  "variableName": "overall_satisfaction",
+                  "presentation": "radio",
+                  "shuffleOptions": false,
+                  "options": [
+                    {
+                      "id": "satisfaction-very_dissatisfied",
+                      "code": "VERY_DISSATISFIED"
+                    },
+                    {
+                      "id": "satisfaction-dissatisfied",
+                      "code": "DISSATISFIED"
+                    },
+                    {
+                      "id": "satisfaction-neutral",
+                      "code": "NEUTRAL"
+                    },
+                    {
+                      "id": "satisfaction-satisfied",
+                      "code": "SATISFIED"
+                    },
+                    {
+                      "id": "satisfaction-very_satisfied",
+                      "code": "VERY_SATISFIED"
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+        ]
+      }
     }
   },
   "translations": [
     {
+      "ownerId": "satisfaction",
+      "role": "title",
       "locale": "en",
-      "contentKey": "title",
       "plainText": "Overall, how satisfied are you with your experience?"
     },
     {
+      "ownerId": "satisfaction-very_dissatisfied",
+      "role": "label",
       "locale": "en",
-      "contentKey": "options.very_dissatisfied.label",
       "plainText": "Very dissatisfied"
     },
     {
+      "ownerId": "satisfaction-dissatisfied",
+      "role": "label",
       "locale": "en",
-      "contentKey": "options.dissatisfied.label",
       "plainText": "Dissatisfied"
     },
     {
+      "ownerId": "satisfaction-neutral",
+      "role": "label",
       "locale": "en",
-      "contentKey": "options.neutral.label",
       "plainText": "Neutral"
     },
     {
+      "ownerId": "satisfaction-satisfied",
+      "role": "label",
       "locale": "en",
-      "contentKey": "options.satisfied.label",
       "plainText": "Satisfied"
     },
     {
+      "ownerId": "satisfaction-very_satisfied",
+      "role": "label",
       "locale": "en",
-      "contentKey": "options.very_satisfied.label",
       "plainText": "Very satisfied"
     }
   ]
 }
 ```
 
+### Full worked example: a composed question with two inputs
+
+Use ordinary elements in a shared layout, with independent persistent response slots. The automatic column count is a maximum, not a requirement to squeeze every input onto one row.
+
 ```json
 {
   "kind": "create-item",
@@ -146,61 +135,94 @@ Minimal valid examples:
     "parentItemId": "<root-group-id>"
   },
   "item": {
-    "id": "personal_data",
-    "itemType": "formItem",
+    "id": "personal-data",
+    "itemType": "content",
     "config": {
-      "id": "personal_data",
-      "authoringMode": "simple",
-      "fieldGroups": [
-        {
-          "id": "main",
-          "layout": {
-            "base": 1,
-            "xs": 1,
-            "sm": 1,
-            "md": 1,
-            "xl": 1
-          },
-          "fields": [
-            {
-              "id": "email",
-              "type": "input",
-              "required": false,
-              "controller": {
-                "type": "input",
-                "inputMode": "email"
+      "body": {
+        "blocks": [
+          {
+            "kind": "layout",
+            "id": "personal-data-layout",
+            "layout": {
+              "mode": "automatic",
+              "maxColumns": 2
+            },
+            "elements": [
+              {
+                "kind": "element",
+                "id": "profile-email",
+                "elementType": "text",
+                "config": {
+                  "slotId": "profile-email-slot",
+                  "variableName": "email",
+                  "presentation": "short",
+                  "purpose": "email",
+                  "required": false,
+                  "validations": [
+                    {
+                      "id": "profile-email-valid",
+                      "type": "email"
+                    }
+                  ]
+                }
               },
-              "validations": [
-                {
-                  "id": "email",
-                  "type": "email"
+              {
+                "kind": "element",
+                "id": "profile-age",
+                "elementType": "number",
+                "config": {
+                  "slotId": "profile-age-slot",
+                  "variableName": "age_years",
+                  "presentation": "input",
+                  "min": 0,
+                  "validations": [
+                    {
+                      "id": "profile-age-integer",
+                      "type": "integer"
+                    }
+                  ]
                 }
-              ],
-              "variableName": "email"
-            }
-          ]
-        }
-      ]
+              }
+            ]
+          }
+        ]
+      }
     }
   },
   "translations": [
     {
+      "ownerId": "personal-data",
+      "role": "title",
       "locale": "en",
-      "contentKey": "title",
       "plainText": "Personal information"
     },
     {
+      "ownerId": "profile-email",
+      "role": "label",
       "locale": "en",
-      "contentKey": "fields.email.label",
       "plainText": "Email address"
+    },
+    {
+      "ownerId": "profile-email-valid",
+      "role": "message",
+      "locale": "en",
+      "plainText": "Enter a valid email address."
+    },
+    {
+      "ownerId": "profile-age",
+      "role": "label",
+      "locale": "en",
+      "plainText": "Age in years"
     }
   ]
 }
 ```
 
+## Content, coding and editor presentation
+
 `update-response-settings`
 
-- Applies scalar names, matrix naming components, option export codes and slot export defaults atomically. Load response-variables.md for the exact shape.
+- Applies scalar names, matrix naming components, option export codes and slot export defaults atomically. Load response-variables 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`
@@ -213,112 +235,65 @@ Minimal valid examples:
 - Changes the editor-only color stored at `metadata.editorItemColor`.
 - Use an editor palette value from item-types. This has no respondent-facing effect.
 
-`update-item-translation`
+`update-content`, `update-survey-translation`
 
-- Changes respondent-visible content for one locale/contentKey.
-- 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.
-- 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.
+- Use `update-content` with `ref: {scope: "content", ownerId, role}` for respondent content, or a survey ref with `scope: "survey"`, `surface` and `contentKey`. A localized leaf belongs to its declared owner, independent of where it sits in the survey.
+- Use `plainText` for ordinary unformatted copy. For complete formatted values, load rich-text-content and prefer `richTextBlocks`; it normalizes to canonical `content`. Full `content` is available for structures the shorthand cannot express. Markdown syntax does not request rich formatting.
+- Provide exactly one representation. `content: null` clears the locale's value; never replace the surrounding owner, locale or translation map just to change a leaf.
+- Use the actual requested locale even when absent. A real translation introduces it and reports a warning so accidental locale codes can be spotted. Do not write target-language text into an existing wrong locale.
 
 `update-placed-image`
 
-- Updates one image block already placed in an item's rich-text translation without replacing the surrounding content.
-- Identify the placement with `itemId`, `locale`, `contentKey`, and a zero-based `imageIndex` that counts image blocks only. Include `expectedAssetId` when the current source is a local asset so stale content cannot cause the wrong image to be edited.
-- `changes.source` accepts either `{ "type": "asset", "assetId": "..." }` or `{ "type": "external", "url": "https://..." }`, so a placement can switch between local and external sources.
-- `changes` can also set or clear `alt`, `caption`, `width`, `height`, `maxWidth`, `maxHeight`, and `alignment`. Dimensions use `{ "unit": "px" | "%", "value": number }`; use `null` to remove an optional property.
-- This changes the rendered placement. `update-image-asset-metadata` changes only reusable global asset metadata and does not rewrite ALT text or layout on existing placements.
+- Updates a placed image without replacing its surrounding rich text. Identify it with the owner/survey `ref`, `locale`, and zero-based `imageIndex` counting image blocks only. Include `expectedAssetId` for a local asset to detect stale placement.
+- `changes.source` accepts `{type: "asset", assetId}` or `{type: "external", url}`. Other changes are `alt`, `caption`, `width`, `height`, `maxWidth`, `maxHeight`, and `alignment`. Dimensions use `{unit: "px" | "%", value: number}`; `null` removes an optional property.
+- Placement changes affect the rendered image. `update-image-asset-metadata` changes reusable metadata and does not rewrite existing placements' ALT text or layout.
 
-`patch-item-config`
+## Configuration and composition
 
-- Updates one existing item's configuration without requiring its global survey array index.
-- Every JSON Patch path is relative to the inspected item config root. For example, `/max` targets `item.config.max`.
-- Load the item type's advertised authoring reference when one exists, inspect the current item, and preserve unrelated config fields.
-- If the item capability provides a validator, it validates the resulting config before the change can be applied.
-- Prefer this operation over `survey-json-patch` for custom-item settings and ordinary item-local configuration.
+`patch-element-config`, `patch-item-config`
 
-`add-choice-option`, `update-choice-option-label`, `remove-choice-option`, `reorder-choice-options`
+- Inspect the target and use JSON Pointers relative to its config root. `/options/0/code` on a choice element targets its first option's code; it is not a survey-root pointer. Array indices must come from the current draft.
+- Prefer `patch-element-config` for choice options, matrix rows/cells, validation settings and custom element settings. `patch-item-config` handles flow-item configuration. Preserve unrelated fields and surviving IDs.
+- Group related structural edits and new owner-role translations in the same operation. Matrix row/column changes must produce a complete rectangle; follow-up creation must include its layout, elements and visible content. Load the relevant element-types/follow-ups reference first.
+- Do not copy an object's persistent IDs to duplicate it. New objects, nested options, validation rules and slots need fresh IDs; preserve translations in every existing locale.
+- An existing answer ID cannot change value type, including through config or raw patches. A requested type change needs a fresh slot ID (a matrix cell's ID is also its slot ID) and explicit repair of all dependent expressions, prefills and export settings within the same turn. Inspect and preserve these dependencies first. Stage individually valid steps: clear dependent logic/prefills through `survey_expression`; remove old slot-keyed export settings with an exact leaf `survey-json-patch` (the settings operation does not remove entries); change the type with a fresh ID; then restore the authorized, adapted logic, prefills and settings against the new ID through their normal tools. Do not silently rebind references or discard settings. Verify the complete result before finalizing; the accepted turn applies as one undoable edit, and unresolved rejected proposals prevent application. If the intended repairs are unclear or unauthorized, report the dependencies without starting a partial repair.
+- Use `survey_expression` for conditions, expression rules, prefills and template values on existing state. Ordinary validation constraints and their message translations are config/content edits.
 
-- Use for ordinary choice option edits on existing choice items.
-- 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.
+`update-layout`
 
-`upsert-form-field-group`, `remove-form-field-group`, `reorder-form-field-groups`, `upsert-form-field`, `remove-form-field`, `move-form-field`
+- Targets an exact layout ID and replaces its layout policy without replacing its elements. Automatic policy is `{mode: "automatic", maxColumns: 1..12}`. Advanced breakpoint policies are described in the generated contract.
+- All rows share column alignment. Full-width elements use a whole row; semantic sections remain vertical blocks. Do not simulate a semantic section by placing a titled container alongside another element.
 
-- 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.
+`move-item`, `reorder-items`, `move-element`, `move-block`
 
-Update an existing form field group's layout without replacing its fields:
+- Indexes are zero-based; omission appends and `0` inserts first. Use flow item operations for survey structure, `move-element` for layout children, and `move-block` for layouts/sections in a body.
+- `reorder-items` takes top-level `parentItemId` and the COMPLETE inspected `itemIds` list. Page inspection until all direct children are known. Root moves, cycles, duplicates and incomplete lists are rejected.
+- Moves retain identities and translated content. If a move crosses validation ownership, the default `ruleTransfer: "reject"` protects existing rules. Use `"move-with-targets"` only for an intentional move whose complete target set moves together; inspect and resolve a split rule rather than dropping it.
+- Verify the stored placement or child order. A shuffled group may show a different respondent order.
 
-```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.
-- `set-embedded-form` accepts the full form config plus its visible translations in the same operation.
-- Set `form.authoringMode` to `simple` only for exactly one group with one field; otherwise use
-  `custom`. Malformed simple input is normalized to custom without dropping form data.
-- Form layout values are responsive column counts from 1 to 4, not spans; one column makes a lone field full width.
+`remove-item`, `remove-content`
 
-`move-item`, `reorder-items`
+- `remove-item` removes a flow item; set `includeChildren: true` only for intentionally deleting a group subtree. `remove-content` removes an element or block by its owner ID.
+- Before removing referenced owners/slots, inspect what depends on them. In the same turn, first update or clear dependent conditions, validation rules and prefills with `survey_expression`, then remove the content. Dependent content that should go too can be removed in the same `survey_change` as its target, in any order. A change that still leaves references to removed content is rejected with `deletion-has-dependencies` and removes nothing. Preserve the requested deletion when retrying; an unrelated edit cannot resolve its rejection.
+- Authors may keep broken references while restructuring; the editor reports them as blocking diagnostics until they are repaired. Never leave new ones behind. Repair existing ones when the request concerns them or the user asks, choosing the intended replacement from current slots and options or removing a dependent that no longer applies.
 
-- `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`, `add-survey-locale`, `remove-survey-locale`
 
-`update-survey-metadata`, `update-survey-pagination`, `update-survey-translation`, `add-survey-locale`, `remove-survey-locale`
-
-- Use typed survey-level operations for metadata, page limits, survey-card/navigation/validation content, and locale lifecycle.
-- `add-survey-locale` registers an empty locale and is only for an explicitly requested empty registration. An ordinary request to add/localize/translate a language requires real respondent-facing translations; those translation operations introduce an absent locale themselves. `remove-survey-locale` is intentionally explicit and destructive: it deletes all survey-level and item-level translations stored for that locale.
+- Use typed operations for survey metadata, page limits and locale lifecycle.
+- `add-survey-locale` is only for an explicitly requested empty registration. An ordinary request to add/localize/translate a language requires real respondent-facing translations. `remove-survey-locale` explicitly deletes every translation in that locale; do not emulate it with leaf-by-leaf deletion or raw patches.
 
 `set-image-asset`, `update-image-asset-metadata`, `remove-image-asset`
 
 - Prefer `survey_asset import-attachment` for binary image imports so the model never copies attachment base64.
 - To use that import in a new item, follow it with a `survey_change` call and embed `{ "type": "image", "source": { "type": "asset", "assetId": "<returned-id>" } }` directly in the new item's rich-text translation. The import is retained automatically in the turn draft.
 - Metadata and removal are typed and validated. `survey_asset remove` refuses an asset that is still referenced in the current request-scoped draft.
-- To remove referenced images and their asset atomically, use one `survey_change` call whose `operations` contain every reference removal first and `{ "kind": "remove-image-asset", "assetId": "..." }` last. For example, deleting an image-only info card and its asset is `[remove-item, remove-image-asset]` in one candidate.
-
-`remove-item`
+- To remove referenced images and their asset atomically, use one `survey_change` call whose `operations` contain every reference removal first and `{ "kind": "remove-image-asset", "assetId": "..." }` last. For example, deleting an image-only information item and its asset is `[remove-item, remove-image-asset]` in one candidate.
 
-- Removes an item.
-- Set `includeChildren: true` only when intentionally deleting a group subtree.
+## Transaction behavior
 
-`survey-json-patch`
+Successful operations accumulate in the request-scoped draft. Later tools see earlier accepted changes. The live editor applies the authorized final draft as one normal undoable action only after a successful turn. A rejected delta leaves the draft unchanged and blocks authorization until that same request is repaired. Do not announce unapplied edits as complete.
 
-- Universal escape hatch for raw survey edits.
-- Must be the only operation in a proposal, but may contain many patch entries.
-- Use it for assistant-editable raw survey fields that have no narrow typed or expression helper.
-- It cannot modify `/$schema`, bypass item capability constraints, or create item types that are not
-  deterministically creatable.
-- Use it for advanced choice config and other inspected fields without typed coverage.
-- Use `survey_expression` for template values, display/disabled conditions, expression-based item
-  validations, and prefills on existing state. Form-field validation configuration and translated
-  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.
+`survey-json-patch` is an escape hatch for inspected survey-root fields without a typed operation or expression helper. It must be the only operation in its proposal, but can contain many patches. It cannot replace schema identity, bypass installed capabilities, replace translation containers or modify existing expressions.
 
 ## Raw Patch Example
 

package/dist/references/core-rules.md

@@ -15,6 +15,6 @@ Core rules:
   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, response-variables.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, element-types.md, follow-ups.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.
+Survey schema version 3 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 follow-up 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.