@case-framework/survey-assistant 0.7.0 → 0.9.0

package/dist/references/fair-by-design.md

@@ -14,7 +14,7 @@ not a universal override of the user's request or an established survey conventi
 
 1. **Presentation:** respondent-visible questions, instructions, and answer labels. These are
    localized content and may be reworded.
-2. **Stored identifiers and codes:** stable item and option identifiers, coding keys, typed values,
+2. **Stored identifiers and codes:** stable item and option identifiers, variable names, typed values,
    and standard formats. These are for machines and should not depend on display language.
 3. **Metadata:** definitions, labels for codes, units, data types, missing-value meanings, versions,
    provenance, and mappings to standards. Meaning belongs here rather than being packed into a
@@ -22,13 +22,13 @@ not a universal override of the user's request or an established survey conventi
 
 Do not use a respondent-visible label as though it were a stable stored code. Do not expose a raw
 identifier as respondent wording. In CASE, visible item, option, field, and validation text belongs
-in locale translations; ids, keys, option values, and response-slot references remain exact data.
+in locale translations; IDs, variable names, option codes, and response-slot references remain exact data.
 
-## Identifiers and coding keys
+## Identifiers and variable names
 
-- Preserve stable internal ids and existing keys unless the user asks to change them. Never
+- Preserve stable internal ids and existing variable names unless the user asks to change them. Never
   silently repurpose an existing identifier when meaning changes.
-- When FAIR item-key naming is relevant, start with a letter; use lowercase ASCII letters, digits,
+- When FAIR-oriented variable naming is relevant, start with a letter; use lowercase ASCII letters, digits,
   and underscores; use `snake_case`; stay at or below 32 characters; avoid programming and
   database reserved words; prefer a stable, language-neutral English concept name; reuse the same
   concept name across waves and studies; use established instrument prefixes and sortable item
@@ -37,7 +37,7 @@ in locale translations; ids, keys, option values, and response-slot references r
   metadata.
 - For a standard instrument, preserve its established identity and predictable structure, such as
   an instrument prefix plus a zero-padded item number, rather than inventing unrelated names.
-- Choice option ids, keys, and values should be stable and coding-friendly. Their localized labels
+- Choice option IDs and export codes should be stable and coding-friendly. Their localized labels
   remain separate translations.
 - Follow an explicit user-supplied identifier or established local convention when FAIR naming was
   not requested. If a FAIR alternative would materially help, explain the tradeoff rather than
@@ -51,9 +51,7 @@ in locale translations; ids, keys, option values, and response-slot references r
 - Reuse established code lists and formats when the task calls for interoperability: ISO 8601 for
   dates, ISO 3166 for countries, ISO 639 for languages, UCUM for units, and appropriate domain
   vocabularies such as LOINC or SNOMED CT when supported and relevant.
-- Treat not applicable, skipped by routing, do not know, refused, and not asked as distinct missing
-  reasons. Never invent an ordinary numeric value such as `99` or `-9` that could be analyzed as a
-  real response unless the surrounding data model explicitly declares and documents it as missing.
+- The current response envelope distinguishes typed answers from missing answers. It does not encode every missingness reason. Explain that limitation; do not claim skipped, refused, not asked and not applicable are automatically distinguishable. Explicit questionnaire options can represent such meanings when deliberately authored. Never conflate absent answers with zero, false, or an empty selection. Do not invent sentinel values.
 - Do not invent CASE fields or ad hoc codes to simulate missing-value semantics that the installed
   editor capabilities do not support. Explain the capability gap instead.
 
@@ -78,3 +76,5 @@ capabilities before changing existing identifiers, codes, values, or metadata. D
 rewrite a survey merely because this reference was loaded. Apply the parts material to the user's
 goal, state important tradeoffs, and identify platform-level FAIR requirements that remain outside
 the editor.
+
+These naming rules are CASE project conventions supporting FAIR practice, not requirements imposed by FAIR. Names alone do not make data FAIR; metadata, provenance, access, licensing and documented meaning remain necessary.

package/dist/references/follow-ups.md

@@ -0,0 +1,151 @@
+# Option-inline follow-ups
+
+A follow-up is a composition body directly below the visible option that triggers it, keeping the option-to-input connection clear. Use it for “Other, please specify”, “Yes, explain”, or option-specific quantities and dates. It is stored as `config.options[index].followUp` on a radio or checkbox **choice element**. There is no form wrapper, `allowOther` flag or simple/custom authoring mode.
+
+## Structure and mutations
+
+A follow-up has the same `{ "blocks": [...] }` structure as an item body. It can contain layouts, elements and semantic sections. It cannot contain another follow-up, even indirectly through sections or custom elements. The owning element occupies a full row. Dropdowns cannot own follow-ups; put another conditionally visible element after the dropdown instead.
+
+For a new element, include the complete option and follow-up in its creation payload, with owner-role translations in the same operation. For an existing element, inspect its exact option index and current config, then use `patch-element-config` to add or update the option's `followUp`. Once the body exists, `insert-blocks` can target its triggering option's `bodyOwnerId`, and `insert-element` targets a layout ID. Use shared move/remove operations for existing children so rules, identities and owned content stay consistent. Load the focused operation contract before writing payloads.
+
+Example follow-up value:
+
+```json
+{
+  "blocks": [
+    {
+      "kind": "layout",
+      "id": "other-layout",
+      "layout": { "mode": "automatic", "maxColumns": 1 },
+      "elements": [
+        {
+          "kind": "element",
+          "id": "other-details",
+          "elementType": "text",
+          "config": {
+            "slotId": "other-details-slot",
+            "variableName": "other_details",
+            "presentation": "short",
+            "required": true
+          }
+        }
+      ]
+    }
+  ]
+}
+```
+
+Translate `option-other` role `label` as “Other” and `other-details` role `label` as “Please specify”. Avoid repeating the completion cue in both labels. Every input needs a usable accessible label, explicit or unambiguously inherited; supply an explicit label when the enclosing question would be ambiguous.
+
+## Activation and answers
+
+The choice must be active, the option visible, and that option present in the checked stored selection. Sibling option visibility is not a dependency of this gate. No separate visibility expression is needed just to activate a follow-up. Hidden or unselected follow-up answers are retained in session storage but absent from active expressions, validation and submission. Showing the same follow-up again restores its answer.
+
+Disabling does not close an otherwise active follow-up or erase answers. Ancestor locks prevent participant edits and make its validation non-blocking; active disabled answers still participate in expressions and submission. Use visibility for inapplicability, disabling for locking. Follow-up inputs retain their own persistent slot IDs through movement, copying with remapping, and localization.
+
+Custom elements may own follow-ups only when their installed capability explicitly declares the same trigger and activation contract. Do not invent custom container semantics or bypass the one-level rule.
+
+## Full worked example: multiple choice with an Other input
+
+Create the option, follow-up and their wording together. The text input's required rule applies only while its follow-up is active and changeable. Replace `<root-group-id>` with the current root; use unused IDs.
+
+```json
+{
+  "kind": "create-item",
+  "target": {
+    "parentItemId": "<root-group-id>"
+  },
+  "item": {
+    "id": "transport",
+    "itemType": "content",
+    "config": {
+      "body": {
+        "blocks": [
+          {
+            "kind": "layout",
+            "id": "transport-layout",
+            "layout": {
+              "mode": "automatic",
+              "maxColumns": 1
+            },
+            "elements": [
+              {
+                "kind": "element",
+                "id": "transport-choice",
+                "elementType": "choice",
+                "config": {
+                  "slotId": "transport-slot",
+                  "variableName": "transport",
+                  "presentation": "checkbox",
+                  "maxSelection": null,
+                  "options": [
+                    {
+                      "id": "transport-walk",
+                      "code": "WALK"
+                    },
+                    {
+                      "id": "transport-other",
+                      "code": "OTHER",
+                      "followUp": {
+                        "blocks": [
+                          {
+                            "kind": "layout",
+                            "id": "transport-other-layout",
+                            "layout": {
+                              "mode": "automatic",
+                              "maxColumns": 1
+                            },
+                            "elements": [
+                              {
+                                "kind": "element",
+                                "id": "transport-other-text",
+                                "elementType": "text",
+                                "config": {
+                                  "slotId": "transport-other-slot",
+                                  "variableName": "transport_other",
+                                  "presentation": "short",
+                                  "required": true
+                                }
+                              }
+                            ]
+                          }
+                        ]
+                      }
+                    }
+                  ]
+                }
+              }
+            ]
+          }
+        ]
+      }
+    }
+  },
+  "translations": [
+    {
+      "ownerId": "transport",
+      "role": "title",
+      "locale": "en",
+      "plainText": "How do you travel? Select all that apply."
+    },
+    {
+      "ownerId": "transport-walk",
+      "role": "label",
+      "locale": "en",
+      "plainText": "On foot"
+    },
+    {
+      "ownerId": "transport-other",
+      "role": "label",
+      "locale": "en",
+      "plainText": "Other"
+    },
+    {
+      "ownerId": "transport-other-text",
+      "role": "label",
+      "locale": "en",
+      "plainText": "Please specify"
+    }
+  ]
+}
+```

package/dist/references/localization.md

@@ -4,6 +4,7 @@ Use this reference when the user asks to translate, localize, add a language, or
 
 ## Locale Lifecycle
 
+- When continuing a retained UI task, check the live locale list. If its target was removed, ask whether to restore it before writing unless the current message explicitly asks to add or restore that language.
 - A target locale may be absent. That is a normal starting state, not an error and not a reason to inspect a nonexistent translation branch.
 - An unqualified request to "add a German localization", "add German", or translate/localize the survey means make the existing respondent-facing content available in that language. Registering an empty locale does not complete that request.
 - Use `add-survey-locale` only when the user explicitly wants the language registered before it has translated content. It rejects blank and already-present locale codes.
@@ -14,18 +15,31 @@ Use this reference when the user asks to translate, localize, add a language, or
 - Never put target-language respondent text into an existing source-language locale just because that locale already exists.
 - Coding keys and editor-only item labels are not respondent translations. Translate them only when the user explicitly asks.
 
-## Scope A Complete Localization Correctly
+## Scope and reference languages
 
-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. 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.
+Translation-workspace launches state the request briefly and attach its exact parameters as the UI-launched task: `kind` is `localization.translate-missing` or `localization.review-existing`, and `data` holds `targetLocale`, `scope` (`survey`, `item`, or `fields`), `itemId` for an item scope, and `localizationRefs` for selected fields. Use these values exactly; the visible message names the fields only for the user.
 
-## Bounded Execution
+The task is retained with the thread and replayed on follow-ups and reopened chats. Continue within that original scope unless the user explicitly changes it; a different current UI selection does not change the task.
 
-- Prefer one atomic proposal for a coherent localization when it fits the advertised operation limit. The limit is a hard safety bound, not a target chunk size.
-- Split only an oversized localization into independent, coherent chunks by section or item set. Each successful chunk updates the request-scoped draft for the next inspection.
-- After each chunk, call the localization inspection again with `missingOnly: true` and no cursor, because a draft change invalidates offsets into the previous missing-only result. Completion means it returns no remaining source surfaces for the target locale.
-- If live inspection or a source translation cannot determine a phrase accurately, ask a focused clarification rather than inventing domain-specific wording.
+1. Use `survey_inspect` with `action: "localization"` and `targetLocale`. Omit `sourceLocale` unless the user explicitly chose an authoritative source language. All available non-target language versions are returned as `references`; the UI's selected language and visible columns are not a source-language instruction.
+2. Pass `itemRef` as an existing canonical item id for a content item or flow group. This includes its descendants and excludes survey-level texts. For selected text fields, pass their exact `localizationRefs` (at most 200 per request; split larger selections and track every group). The result lists unavailable exact refs separately. Continue with available refs, report unavailable refs, and never widen the scope. An invalid item scope is an error. Entries without reference text in another language cannot be translated or comparatively reviewed; report them separately.
+3. Read complete reference texts and complete targets before judging meaning. Each reference and target has a `text` preview and canonical `path`. For truncated plain or md values, inspect `raw-json` with `paths: [textPath]`, following `nextTextOffset` with `textOffset` until complete. Rich-text `content` is the complete canonical value, including links, images, templates, and metadata. Never translate or review just the preview.
+4. Cross-check references for terminology, register, omitted clauses, negation, numbers, units, and response-option meaning. If versions disagree materially and the user did not establish authority, ask a focused question. Do not silently choose a source or blend contradictory meanings. Existing target wording is context, not proof of correctness.
+5. Use `update-content` with the inspected owner/role localization ref, or `update-survey-translation` with the exact destination locale. Preserve other languages, item structure, option identifiers, links, templates, extensions, and metadata. Use canonical rich `content` to retain rich text; `plainText` is not a replacement for rich content.
+
+## Translate missing
+
+- Inspect with `missingOnly: true`. Only add missing target texts; do not revise existing translations.
+- Work in coherent chunks within the advertised operation limit. Each successful change updates the same-turn draft.
+- After a chunk, re-inspect missing texts without a cursor until the complete scope is covered. Completion means no remaining missing texts that have a usable reference, not merely the last page being empty.
+- Report completed work, remaining entries, unresolved conflicts, or failures honestly. Do not introduce dummy translations to reach zero missing.
+
+## Review and correct
+
+- Inspect with `missingOnly: false`. Skip entries with `targetPresent: false` (including stored empty content). Review complete references and target, correct concrete problems, and leave acceptable translations unchanged. Do not fill missing values during a review.
+- Traverse every page. Apply corrections per page, then continue with the returned cursor. Cursors survive target-text edits, including translating the anchor; they reject changes to reference content, order, scope, and query.
+- A rejected cursor starts a fresh review pass: recompute the initial translated count, reset reviewed/changed counts, and report corrections retained from earlier passes separately. Never combine counts from incompatible passes.
+- `translatedCount` supplies the initial number of present targets for that pass. Count an entry as reviewed only after reading complete content and reaching a judgment. Count changed entries only after successful application. Failed reads, unapplied corrections, interruptions, or unresolved disagreements mean a partial result, not a completed review.
+- Report which texts changed and why, how many were reviewed, and what remains. Presence counts do not establish accuracy, completeness within a text, approval, or freshness.
+
+Authoring readiness uses the currently selected locale. A usable source translation does not make an empty target translation ready. Translation coverage is reported separately; do not turn missing content in unrelated locales into structural failures. Content owner IDs and roles survive moves without path rewriting.

package/dist/references/response-variables.md

@@ -0,0 +1,38 @@
+# Response variables and coding
+
+Items have stable IDs and resolved editor names. Use exact item IDs in operation targets; inspect names, breadcrumbs and response-variable metadata to find them. Duplicate display names are legal and never identify a unique item by themselves. Editing an editor name does not rename data.
+
+A response variable has a persistent survey-unique slotId, itemId owner, elementId, variableName, valueType, and optional finite allowedValues, naming source, option codes, labels, scores, and computed dependencies. Inspect response slots or item details; never construct slot IDs from names, paths, or suffixes. Scalar elements declare config.slotId; matrix rows/cells and computed scores declare their own persistent IDs. Follow-up inputs use the same element contracts as root inputs.
+
+Expressions use {"type":"responseVariable","variableRef":{"slotId":"exact-slot-id","method":"get"}} or method "isDefined". Categorical values and constants use stable option IDs, not labels or export codes. Dropdowns are reference-valued too. False, zero, empty selection, and missing are distinct; do not introduce sentinel answers. The host supplies schema-bound flat answers[slotId] values.
+
+Use survey_change with kind "update-response-settings", naming and settings arrays for atomic coding changes:
+
+```json
+{
+  "kind": "update-response-settings",
+  "naming": [
+    {
+      "slotId": "age-slot",
+      "variableName": "age_years"
+    }
+  ],
+  "settings": [
+    {
+      "slotId": "choice-slot",
+      "optionCodes": {
+        "option-yes": "yes",
+        "option-no": "no"
+      }
+    }
+  ]
+}
+```
+
+Scalar naming: {slotId,variableName}. Matrix naming: {elementId,prefix?,rows?:{rowId:rowName},columns?:{columnId:columnName}}. A matrix cell name is derived from its prefix, row and column; choice matrices derive row answers and computed scores from the same family. Never set per-cell names or export headers. Preview all affected family names and edit components together. Configuration overrides remain supported for form-matrix cells.
+
+Settings: {slotId,optionCodes?,exportSettings?}. optionCodes changes source option export codes by stable option ID; it does not change IDs, labels or scores. Shared matrix/dropdown options affect every slot that uses them. exportSettings replaces that slot's defaults: include, mode (default/dateFormat/mask), categorical (codes/labels/ids), multiple (json/delimited/indicators), delimiter, locale, optionCodes, optionLabels, booleanValues {true,false}, precision, durationUnit, dateFormat {pattern}, maskText. Inspect existing settings first and retain settings you are not asked to change. Profiles override these defaults outside authoring. Defaults are codes, JSON arrays, TRUE/FALSE, seconds and excluded computed slots.
+
+The shared core validates survey-wide variable-name and projected-header uniqueness, typed domains, and matrix restrictions. Coding changes preserve answer/expression identities and apply through normal editor history. Do not use raw patches to bypass these constraints. Wording, translation, movement, layout, and editor-name changes preserve existing variable names and codes.
+
+Generate meaningful initial variableName values (and matrix prefix/rowName/columnName components) and option codes when creating inputs. Names must start with a letter, use lowercase ASCII snake_case, and contain at most 32 characters. Prefer stable English concepts, units where useful, supplied instrument prefixes and sortable numbering; distinguish raw and computed values. Infer conventions from other variables, not the selected field's placeholder. Respect supplied standard codes; similar wording does not prove equivalence. FAIR guidance supports documentation and reuse; naming alone does not make a dataset FAIR. Publication provenance, access policies and licensing remain host responsibilities.

package/dist/references/rich-text-content.md

@@ -5,12 +5,11 @@ Do not use markdown syntax for formatting; `md` content is displayed as plain te
 
 Use typed translation operations for formatted text. Prefer `plainText` for all unformatted text, including a simple title, label, or one-paragraph info item. Use richText only when formatting carries meaning or structure. In canonical operation payloads, a complete structured value belongs in `content`. Use `survey-json-patch` for rich text only when you need to edit raw paths that typed translation operations cannot address.
 
-For `survey_change`, compact `richTextBlocks` shorthand is accepted wherever a typed translation accepts structured `content`. This includes translation entries on `create-item`, `upsert-form-field-group`, `upsert-form-field`, and `set-embedded-form`, plus the top level of `update-item-translation` and `update-survey-translation`. It is normalized to canonical `content` before validation. This is an input convenience, not evidence that every accepting surface renders formatting. For an item surface whose capability profile marks `format=rich`, prefer the shorthand when creating or replacing its complete formatted value because it avoids unnecessary deeply nested payloads. It is especially useful for source-document imports:
+For `survey_change`, compact `richTextBlocks` shorthand is accepted wherever a typed translation accepts structured `content`. This includes translation entries on `create-item`, `insert-element`, `insert-blocks`, and configuration edits, plus the top level of `update-content` and `update-survey-translation`. It is normalized to canonical `content` before validation. This is an input convenience, not evidence that every accepting surface renders formatting. For an owner role whose declared inline/block policy permits the intended formatting, prefer the shorthand when creating or replacing its complete formatted value because it avoids unnecessary deeply nested payloads. It is especially useful for source-document imports:
 
 ```json
 {
   "locale": "en",
-  "contentKey": "content",
   "richTextBlocks": [
     { "type": "heading", "level": 2, "text": "How should I complete this survey?" },
     { "type": "paragraph", "text": "Read each question carefully before answering." },
@@ -32,7 +31,7 @@ Provide exactly one representation for a translation: `plainText`, canonical `co
 model-facing `richTextBlocks` shorthand. Never combine them. `richTextBlocks` must contain at least
 one block. Put it at the same level where the canonical `content` property would appear: inside a
 translation entry for operations with a `translations` array, or at the operation top level for
-`update-item-translation` and `update-survey-translation`. Do not nest shorthand nodes inside a
+`update-content` and `update-survey-translation`. Do not nest shorthand nodes inside a
 canonical `content.doc` tree. The shorter `blocks` property is accepted as a compatibility alias at
 the same locations, but prefer `richTextBlocks` in new operations.
 
@@ -45,7 +44,8 @@ The shorthand also supports inline runs through `children`. Use it when a paragr
 ```json
 {
   "locale": "en",
-  "contentKey": "title",
+  "ownerId": "<item-id>",
+  "role": "title",
   "richTextBlocks": [
     {
       "type": "paragraph",
@@ -139,7 +139,7 @@ Style values:
 Supported block types:
 
 - `paragraph`
-- `heading` with `level` 1 for section headings or `level` 2 for subsection headings. Do not author levels 3 through 6; the player offsets/clamps these stored levels to semantic page headings.
+- `heading` with `level` 1 for section headings or `level` 2 for subsection headings. Do not author levels 3 through 6; the player offsets/clamps these stored levels to semantic page headings. Any other level, in canonical blocks or `richTextBlocks` shorthand alike, is rejected rather than rounded.
 - `bulletList` with `listItem` entries
 - `image` with `source: { "type": "asset", "assetId": "..." }` or `source: { "type": "external", "url": "..." }`
 - `infoBox` with `tone: "info"` or `"warning"`
@@ -147,19 +147,12 @@ Supported block types:
 
 ## Where Rich Text Is Used
 
-For item translations, the installed item capability manifest is authoritative. Load
-`assistant-operations` with both `operationKind` and `itemType`; its item capability profile labels
-every fixed and dynamic content surface as `format=rich` or `format=plain`. Use rich text only for a
-surface marked `format=rich`. This covers custom item capabilities and avoids maintaining a second
-hardcoded surface list in guidance.
+For owner-role content, inspect the installed schema's declared roles via item-details. Each role has `policy: "inline"` or `"block"`; custom elements use the same contract. Load `assistant-operations` with `operationKind` and `elementType` for its schema and focused guidance. A typed field accepting structured content does not authorize arbitrary formatting on every surface.
 
-For the built-in item types, these additional rendering constraints apply:
-
-- Info items: content key `content`; full block editor with paragraphs, headings, bullet lists, images, separators, and info boxes.
-- Choice item `topContent` / `bottomContent`: block rich text with paragraphs, headings, bullet lists, images, separators, and info boxes.
-- Form item `topContent` / `bottomContent`: block rich text with paragraphs, bullet lists, images, and separators only. Do not use headings or info boxes there.
-- Question `title` and `cardFooter`: compact rich text with paragraph blocks only. Inline styles may use bold, italic, underline, and color.
-- Question `subtitle`: compact rich text with paragraph blocks only. Inline styles may use bold, underline, and color. Do not rely on italic in subtitles.
+- `inline` roles support paragraph text and inline styles/links; do not put headings, lists or images into a compact label. Item/section titles, input labels, option labels and consent headings use this policy.
+- `block` roles support structured paragraphs, headings, lists, images, separators and info boxes. Information and consent bodies, item subtitles/footers, input help and section descriptions use this policy.
+- Place the complete source document in the information/consent element's `body` role; keep the identifying title on its item/section or explicit element label. Avoid repeating the same heading inside the body unless the source or user calls for it.
+- Content addresses are `{scope: "content", ownerId, role}`; creation translations carry `ownerId`, `role` and `locale`. An option's label belongs to the option ID, not a dotted key on the containing item. Inspect roles rather than inventing topContent/bottomContent or form fields.
 
 Survey-level `surveyCardContent`, `navigationContent`, and `validationMessages` are not item
 capability surfaces. Use `plainText` for them. They are metadata and interface-copy surfaces rather
@@ -172,14 +165,13 @@ the nearest supported representation.
 
 ## Updating Existing Rich Text
 
-Inspect the item first, then use `update-item-translation`. When replacing the complete surface with the common structures above, prefer `richTextBlocks`:
+Inspect the item first, then use `update-content`. When replacing the complete surface with the common structures above, prefer `richTextBlocks`:
 
 ```json
 {
-  "kind": "update-item-translation",
-  "itemId": "info_1",
+  "kind": "update-content",
+  "ref": { "scope": "content", "ownerId": "info_1", "role": "body" },
   "locale": "en",
-  "contentKey": "content",
   "richTextBlocks": [
     { "type": "heading", "level": 2, "text": "Instructions" },
     {
@@ -194,33 +186,20 @@ Inspect the item first, then use `update-item-translation`. When replacing the c
 
 This replaces that translation key for the target locale. Preserve existing blocks you still want; do not send only the new block unless the user asked to replace the whole content.
 
-## Creating A Formatted Info Item
+## Creating formatted information
 
-For a new formatted info item, use one typed `create-item` operation with a compact `richTextBlocks` translation:
+Use an information element in a content item (or an existing layout). Supply the formatted translation on that element's owner ID with role `body`, not the containing item's title. The complete generated create-item/insert-element contract defines the structural payload. For example, its translations entry may be:
 
 ```json
 {
-  "kind": "create-item",
-  "target": { "parentItemId": "<root-group-id-or-key>", "index": 0 },
-  "item": { "id": "info_intro", "key": "intro", "itemType": "infoItem", "config": {} },
-  "translations": [
-    {
-      "locale": "en",
-      "contentKey": "content",
-      "richTextBlocks": [
-        { "type": "heading", "level": 2, "text": "Before you start" },
-        { "type": "paragraph", "text": "This survey asks about your preferences." }
-      ]
-    }
+  "ownerId": "intro-information",
+  "role": "body",
+  "locale": "en",
+  "richTextBlocks": [
+    { "type": "heading", "level": 2, "text": "Instructions" },
+    { "type": "paragraph", "text": "Please answer about the last seven days." }
   ]
 }
 ```
 
-Use the full `content.doc` form from the Block Nodes section only when you need a
-structure that the compact forms above do not cover.
-
-The raw item can still be minimal:
-
-```json
-{ "id": "info_intro", "key": "intro", "itemType": "infoItem", "config": {} }
-```
+Owner-role references remain the same when the element moves. Preserve existing links, templates, assets and content metadata when translating or editing structured content.

package/dist/references/source-material-surveys.md

@@ -15,7 +15,7 @@ Use this reference when the user asks to implement, recreate, convert, import, o
 - Implement every distinct question, instruction, answer option, section heading, and respondent input implied by the source unless the user explicitly asks for a summary.
 - Do not collapse multiple real questions into one text field. A text field is appropriate only when the source asks for open-ended text, an unsupported structured response cannot be represented more precisely, or the user explicitly asks for a free-text capture.
 - If the questionnaire body asks the respondent to record information, the digital survey must include an input control for it. Do not leave respondent-entered information as static text.
-- Empty lines, blanks, underscores, table cells intended for handwriting, parenthetical "specify" prompts, and inline write-in areas in actual questions imply an input field. Model them as form fields or embedded option forms as appropriate.
+- Empty lines, blanks, underscores, table cells intended for handwriting, parenthetical "specify" prompts, and inline write-in areas in actual questions imply an input field. Model them as elements or option-inline follow-ups as appropriate.
 - Do not create respondent questions for front-cover study identifiers, barcodes, prefilled participant names, prefilled dates of birth, page numbers, institutional logos, or duplicate administrative fields when those values should come from digital participant metadata or are asked later as real survey questions.
 - Printed examples that demonstrate how to fill in a paper form should be preserved as instructional text when useful, not converted into real inputs.
 - Preserve question order, numbering intent, and section structure. For long sources, use multiple bounded mutation calls rather than omitting details. Bounded applies to each call, not the whole assistant turn; each successful call automatically extends the same turn draft.
@@ -26,49 +26,45 @@ Use this reference when the user asks to implement, recreate, convert, import, o
 
 ## Item Mapping
 
-- Map supported item types directly. Use `choiceItem` for single choice, multiple choice, and scale-like questions until a dedicated scale item exists.
-- For scale questions, create an ordered `choiceItem` with stable option ids/keys and labels that preserve the endpoints and intermediate labels. Include the scale instruction in `subtitle` or `topContent` when it is not part of the actual question.
-- Use a simple `formItem` preset for a single text, long-text, number, slider, dropdown, date, or switch response. Use custom form mode for grouped personal data, tables, repeated inputs, contact details, or unsupported compound controls.
-- Prefer the supported semantic field type for the respondent value instead of copying the paper
-  form's box layout. Use one `datepicker` with mode `year-month-day` for an ordinary full calendar
-  date; use separate day/month/year fields only when the source measures those components
-  independently or the user requests literal paper-form reproduction.
-- Use choice option embedded forms for choices that include an open field, such as "Other, specify", "Yes, explain", or an option-specific quantity/date/text input.
+- Use the installed element registry. Ordinary questions usually become one element in a content item, using a preset where suitable. Use radio/checkbox/dropdown choice presentation as appropriate. For repeated common scales, use a choice matrix; preserve ordered endpoints, codes, scores and non-scoring responses.
+- Use text, number, date or boolean elements for their actual value domains. Multiple related fields can share layouts and semantic sections inside one item. There is no separate form item or simple/custom mode.
+- Use a date element with precision `year-month-day` for a full calendar date. Separate components only when the source measures them independently or the user explicitly requests that reproduction.
+- Use radio/checkbox option-inline follow-ups for option-specific inputs such as “Other, specify”. Dropdown follow-ons use separately conditional elements. Follow-ups cannot own further follow-ups.
 - Preserve option-level parenthetical instructions, side notes, and footnote markers. If the current choice option UI has no separate option-description surface, fold short option notes into the visible option label, for example `Uitgenodigde persoon zelf (zie hiervoor de naam op de brief en/of geboortedatum op de voorkant van de vragenlijst)`, and keep markers such as `Iemand anders*`.
-- For sentence-completion options with an embedded input, put the completion cue on the embedded field label, not twice. Source text like `Iemand anders*, namelijk ____`, `Andere bedrijfstak, namelijk ____`, or `Other, please specify ____` should become option label `Iemand anders*` / `Andere bedrijfstak` / `Other` and embedded field label `Namelijk` / `Please specify`.
-- Use info items for non-interactive section introductions, explanations, consent/instruction text, and visible page/section headings. Keep a simple one-paragraph info item as plainText. Use richText only when the source requires headings, lists, links, separators, or meaningful emphasis.
-- Preserve major chapters/sections as survey structure. If page boundaries matter, use available page-break structure and/or a heading info item so respondents see the section break.
-- Include respondent-facing "before you begin", "how to complete this survey", consent, eligibility, safety, and contact/help sections as info items when still relevant digitally. Rewrite or omit paper-only return/postage instructions unless the user wants a literal reproduction.
+- For sentence-completion options with a follow-up input, put the completion cue on the follow-up element label, not twice. Source text like `Iemand anders*, namelijk ____`, `Andere bedrijfstak, namelijk ____`, or `Other, please specify ____` should become option label `Iemand anders*` / `Andere bedrijfstak` / `Other` and follow-up element label `Namelijk` / `Please specify`.
+- Use information elements in content items for non-interactive section introductions, explanations, instruction text, and visible page/section headings. Use a consent element when the participant must explicitly agree or decline, with the full information in the consent owner's `body` role. Keep simple paragraphs as plainText; use richText for headings, lists, links, separators, or meaningful emphasis.
+- Preserve major chapters/sections as survey structure. If page boundaries matter, use available page-break structure and/or a content item with a heading so respondents see the section break.
+- Include respondent-facing "before you begin", "how to complete this survey", eligibility, safety, and contact/help sections as information elements in content items when still relevant digitally. Preserve consent information and any requested decision using the appropriate information or consent element. Rewrite or omit paper-only return/postage instructions unless the user wants a literal reproduction.
 
 ## Layout And Grouping
 
-- Treat source layout as meaningful when it communicates that fields belong together, form a repeated row or table, or have labels and inputs that must stay associated. Preserve that relationship with an appropriate form item, field groups, field order, and responsive group layout. Do not reproduce spacing or columns that are only decorative or optimized for paper.
-- For adjacent related fields, choose responsive column counts according to their semantic grouping and the space their labels and controls need. Prefer one column in narrow containers and use two to four columns at wider breakpoints when the fields remain clear and usable.
-- Form field-group layouts support one to four columns. Never attempt a larger column count. When a source places more than four fields in one row, use the closest clear supported arrangement; for example, six similarly sized fields can use three columns and flow into two rows. Do not ask a follow-up question only because the exact printed column count is unsupported.
+- Treat source layout as meaningful when it communicates that fields belong together, form a repeated row or table, or have labels and inputs that must stay associated. Preserve that relationship with content items, semantic sections, element order and responsive layouts. Do not reproduce spacing or columns that are only decorative or optimized for paper.
+- Prefer automatic layouts with an intuitive maximum column count; columns align across rows. Minimum widths and full-row elements determine actual packing. Use advanced breakpoints only when the source or user requires them. Avoid reproducing decorative paper columns. Sections are full-width vertical blocks, not cells in a layout.
 - Follow an explicit user layout request when the supported responsive layout can represent it. When it cannot, apply the closest clear supported arrangement and briefly disclose the adaptation after completing the work.
 
 ## Conditions And Follow-Ups
 
 - Implement implied conditions, branching, conditional follow-up questions, conditional option visibility, and skip logic when the source text clearly implies them. Do not skip conditions just because they require extra work.
-- If newly created items depend on other newly created items, place displayConditions/disabledConditions/validations/prefills directly on the created item objects in the same survey_change call when possible.
+- If newly created items depend on other newly created items, place visibility/disabled conditions on their owners, prefills on elements and cross-input validation rules on content items in the same survey_change call when possible.
 - Load the expressions reference and use the expression tool for complex expression work or existing/applied items.
 
 ## Text Shaping
 
 - Rephrase only enough to make the digital survey clear and grammatically coherent. Preserve measurement meaning, recall periods, answer scales, and eligibility wording.
-- Split source text into the right visible content keys: concise question in `title`; instructions like "multiple answers possible" or recall-period guidance in `subtitle` or `topContent`; explanations after the control in `bottomContent`; non-question prose in info item `content`.
+- Split source text into the right visible content keys: concise question in `title`; instructions like "multiple answers possible" or recall-period guidance in `subtitle` or an information element; explanations after the control in `footer` or a following information element; non-question prose in information element `body`.
+- For consent, put the main heading in the item title or nearest semantic section title, a separate introduction in the item's subtitle or section's description when needed, and the full terms in the consent element's body role. An explicit consent label overrides inherited context; `subtitleMode: "custom"` uses its subtitle role and `none` omits it. Avoid repeating the main heading, but preserve meaningful document headings and the full terms. Honor verbatim reproduction when requested.
 - Use plainText for ordinary unformatted prose. Use richText, not plainText, only when info item content has headings, subheadings, boxed sections, bullet/list structure, examples, emphasized phrases, separators, footnotes, URLs, email links, or mixed inline formatting. Preserve the hierarchy with heading blocks, paragraph blocks, bullet lists, info boxes, or separators as supported.
 - Preserve meaningful inline source formatting, not only block layout. A URL or email address that is intended as a destination must be a richText `link` node with a canonical `href`; do not rely on automatic link detection. If source text emphasizes or highlights individual words in a question title, subtitle, option, or info text, author that content key as richText with styled inline runs instead of flattening it to plainText. Use emphasis only where it carries source meaning or scanning value.
 - For source-import surfaces documented as rendering rich text, prefer the compact `richTextBlocks` shorthand; `survey_change` normalizes it to strict richText. Do not infer formatting support merely because a typed field accepts structured content. Load `rich-text-content` for supported surfaces, compact and canonical nodes, and examples. Invalid or unknown nodes are rejected rather than silently omitted.
-- Preserve footnote markers and footnote text when they change interpretation, eligibility, instructions, privacy, or coding. If a question/option has `*`, keep the marker in the visible title/option text and place the note in `subtitle`, `topContent`, `bottomContent`, or a following info item close to the referenced question. Do not silently drop source footnotes.
-- Do not put respondent-visible option labels, form field labels, dropdown option labels, validation messages, or embedded-form labels only in config. They need translation entries.
+- Preserve footnote markers and footnote text when they change interpretation, eligibility, instructions, privacy, or coding. If a question/option has `*`, keep the marker in the visible title/option text and place the note in `subtitle`, `footer` or a nearby information element close to the referenced question. Do not silently drop source footnotes.
+- Do not put respondent-visible option labels, form field labels, dropdown option labels, validation messages, or follow-up labels only in config. They need translation entries.
 
 ## Workflow
 
-- For complex source implementation, load this source-material reference once, then load item-types
-  with the specific `itemType` needed for the current chunk and assistant-operations for unfamiliar
-  operation shapes. Do not load the combined item-types reference merely because a source contains
-  several types. Load rich-text-content before formatted info items and expressions before complex
+- For complex source implementation, load this source-material reference once, then load element-types
+  with the specific `elementType` needed for the current chunk and assistant-operations for unfamiliar
+  operation shapes. Do not load the combined element-types reference merely because a source contains
+  several types. Load rich-text-content before formatted information elements in content items and expressions before complex
   branching.
 - Use survey_inspect for the root group and long-survey insertion points. Use full outline paging or children lookup; do not guess append indexes from truncated context.
 - Before calling survey_change for a source-derived chunk, do a quick fidelity pass against the source: every question title, option label, option parenthetical, blank/input, meaningful field grouping/layout, section heading, footnote marker, and footnote text in that chunk should either be represented digitally or intentionally omitted or adapted as print-only/admin material.