@case-framework/survey-assistant 0.1.0

package/dist/references/assistant-operations.md

@@ -0,0 +1,287 @@
+# Assistant Operations
+
+Use `survey_change` for ordinary survey mutations. Use `survey_expression` with
+`action: "prepare"` for expression mutations on items and survey state that already exist in the
+immutable turn snapshot. Both tools validate their input and register candidate change sets in the
+same turn collector. Only successful completion of the whole turn authorizes the collector's final
+candidate ids for browser apply.
+
+Expressions for items created in the current turn are the deliberate exception: embed them in the
+new item's raw structure inside the same `survey_change` proposal. A later tool call cannot inspect
+an item that has not been applied yet.
+
+## 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 common 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. Treat a validated candidate as intended for apply after successful turn completion, never as a dry run. Omit `continuationMode` only on the first mutation call in the response. On every later mutation call across either mutation tool, use `continuationMode: "append"` for independent additional work or `continuationMode: "replace"` for a complete correction that should discard currently active candidates.
+8. Any rejected mutation blocks the entire turn and authorizes no survey changes. Recover by retrying the complete intended proposal with `continuationMode: "replace"`; only a validated replacement clears the block, and only then may later independent chunks use `append`. A rejected or superseded candidate is not applied. Before claiming completion, reconcile every requested item with the final validated candidates; if any requested work was rejected or discarded, either re-emit it or report the result as incomplete.
+
+## `survey_change` Typed Operations
+
+`create-item`
+
+- Creates a new item under `target.parentItemId`.
+- Use root group id/key for top-level items.
+- Put visible text in top-level `translations`, not inside `item`.
+- Each translation accepts either `plainText` or a complete structured `content` value.
+- When a new item must contain an image, put a `richText` value with the image block directly in `create-item.translations[].content`. Do not create placeholder content and call `update-placed-image` afterward: new items do not exist in the immutable turn snapshot.
+- 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.
+- Use explicit item ids when you need to reference the new item in the same proposal.
+
+Minimal valid examples:
+
+```json
+{
+  "kind": "create-item",
+  "target": { "parentItemId": "<root-group-id-or-key>" },
+  "item": {
+    "id": "intro_privacy",
+    "key": "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."
+    }
+  ]
+}
+```
+
+```json
+{
+  "kind": "create-item",
+  "target": { "parentItemId": "<root-group-id-or-key>" },
+  "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" }
+      ]
+    }
+  },
+  "translations": [
+    {
+      "locale": "en",
+      "contentKey": "title",
+      "plainText": "Overall, how satisfied are you with your experience?"
+    },
+    {
+      "locale": "en",
+      "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" }
+  ]
+}
+```
+
+```json
+{
+  "kind": "create-item",
+  "target": { "parentItemId": "<root-group-id-or-key>" },
+  "item": {
+    "id": "personal_data",
+    "key": "personal_data",
+    "itemType": "formItem",
+    "config": {
+      "id": "personal_data",
+      "fieldGroups": [
+        {
+          "id": "main",
+          "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" }]
+            }
+          ]
+        }
+      ]
+    }
+  },
+  "translations": [
+    { "locale": "en", "contentKey": "title", "plainText": "Personal information" },
+    { "locale": "en", "contentKey": "fields.email.label", "plainText": "Email address" }
+  ]
+}
+```
+
+`update-item-key`
+
+- Changes item coding key. This affects fullKey paths and response naming.
+
+`update-item-label`
+
+- Changes internal editor label at `metadata.itemLabel`.
+- This is what the UI means by item header "Add label...".
+
+`update-item-color`
+
+- 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`
+
+- 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.
+- Use `content` for structured survey content. For formatted text, set `content.type` to `richText`; do not use markdown syntax to request formatting.
+
+`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.
+
+`patch-item-config`
+
+- 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.
+
+`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.
+
+`upsert-form-field-group`, `remove-form-field-group`, `reorder-form-field-groups`, `upsert-form-field`, `remove-form-field`, `move-form-field`
+
+- Target a top-level form with `{ "itemId": "<form-id>" }` or a choice option's form with `{ "itemId": "<choice-id>", "optionId": "<option-id>" }`.
+- Add visible labels, placeholders, option labels, and validation messages in the operation's `translations` array so structure and content remain atomic.
+- Group and field identifiers are stable ids; reorder operations require the complete current id set.
+
+`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.
+
+`move-item`, `reorder-items`
+
+- Move an existing item to a group/index or set a group's complete direct-child order.
+- The validator rejects root moves, cycles, missing children, duplicates, and incomplete reorder lists.
+
+`update-survey-metadata`, `update-survey-pagination`, `update-survey-translation`, `remove-survey-locale`
+
+- Use typed survey-level operations for metadata, page limits, survey-card/navigation/validation content, and locale removal.
+- Removing the final locale is rejected. Locale removal is intentionally explicit and destructive.
+
+`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 one `survey_change` call using `continuationMode: "append"` and embed `{ "type": "image", "source": { "type": "asset", "assetId": "<returned-id>" } }` directly in the new item's rich-text translation.
+- Metadata and removal are typed and validated. `survey_asset remove` refuses an asset that is still referenced in the immutable snapshot.
+- 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`
+
+- Removes an item.
+- Set `includeChildren: true` only when intentionally deleting a group subtree.
+
+`survey-json-patch`
+
+- 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.
+
+## Raw Patch Examples
+
+Update a form field-group layout:
+
+```json
+{
+  "kind": "survey-json-patch",
+  "patches": [
+    {
+      "op": "replace",
+      "path": "/surveyItems/3/config/fieldGroups/0/layout",
+      "value": { "base": 1, "xs": 1, "sm": 2, "md": 2, "xl": 3 }
+    }
+  ]
+}
+```
+
+Add a missing locale shell only after inspection confirms that the locale does not exist:
+
+```json
+{
+  "kind": "survey-json-patch",
+  "patches": [
+    {
+      "op": "add",
+      "path": "/translations/nl",
+      "value": {
+        "itemTranslations": {},
+        "surveyCardContent": {},
+        "navigationContent": {},
+        "validationMessages": {}
+      }
+    }
+  ]
+}
+```
+
+Never use this whole-branch operation for an existing locale. Patch the required leaf key instead,
+or use `update-item-translation`, so sibling translations are preserved.
+
+Add a form field and matching label in one proposal:
+
+- Patch the form item config fieldGroups array.
+- Patch `/translations/<locale>/itemTranslations/<itemId>/fields.<fieldId>.label`. This is REQUIRED, not optional — a field with no label translation shows no visible label to respondents.
+- Include any placeholder, unit, option labels, or validation messages that the new field needs.
+
+Survey-level translation branches:
+
+- `/translations/<locale>/surveyCardContent` stores survey-card copy such as title/description content.
+- `/translations/<locale>/navigationContent` stores participant navigation labels.
+- `/translations/<locale>/validationMessages` stores survey-level validation copy such as `invalidResponse`.
+- Use `survey-json-patch` for these branches today.
+
+Add an embedded input to an existing choice option:
+
+- Inspect the choice item with `survey_inspect action=raw-json` and use its returned `/surveyItems/<choiceIndex>` path; item-details alone is not sufficient for JSON Pointer construction.
+- Patch the target option object under `/surveyItems/<choiceIndex>/config/options/<optionIndex>/embeddedForm`.
+- Patch `/translations/<locale>/itemTranslations/<choiceItemId>/embeddedForms.<optionId>.fields.<fieldId>.label` with a complete Content value such as `{ "type": "md", "content": "Please specify" }`. This is REQUIRED, not optional — a field with no label translation shows no visible label to respondents (only its raw control type, e.g. "Input"). Never add, replace, or remove the surrounding locale or itemTranslations container; it would discard sibling text.
+- Do not patch `allowOther`; it is not part of the current choice config.
+
+Before raw patches, use `survey_inspect` with raw JSON paths for the exact item index and current object shape.

package/dist/references/core-rules.md

@@ -0,0 +1,11 @@
+# CASE Survey Authoring
+
+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.
+- 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.

package/dist/references/embedded-forms.md

@@ -0,0 +1,80 @@
+# Choice Option Embedded Forms
+
+Use this reference when a choice option needs an inline input such as “Other, please specify”,
+“Yes, explain”, or an option-specific text, number, date, or select field.
+
+## Tool And Transaction Choice
+
+- There is no `allowOther` flag. The option config field is `embeddedForm`.
+- For a newly created choice item, put the option and its `embeddedForm` directly in the same
+  `create-item` operation, with every required translation in `create-item.translations`.
+- For an existing choice item, inspect the exact item and option with `survey_inspect`, including
+  its survey-root raw path. Then make one `survey_change` call containing exactly one
+  `survey-json-patch` operation. Put the config patch and every translation patch together in that
+  operation's single plural `patches` array.
+- Never combine a `survey-json-patch` operation with typed translation operations in the same
+  proposal. A raw patch must be the only operation.
+
+## Exact Config Shape
+
+The config key is singular `embeddedForm`, but translation content-key prefixes are plural
+`embeddedForms.<optionId>`. Do not interchange them.
+
+`embeddedForm` is a flat object containing `id` and `fieldGroups`. Fields belong inside each field
+group; there is no `itemType`, `config`, or top-level `fields` wrapper.
+
+```json
+{
+  "id": "other",
+  "key": "other",
+  "embeddedForm": {
+    "id": "other",
+    "fieldGroups": [
+      {
+        "id": "other_details",
+        "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": []
+          }
+        ]
+      }
+    ]
+  }
+}
+```
+
+Use an explicit, stable option id. The config option id, translation prefix, and embedded response
+reference must agree exactly.
+
+## Required Content
+
+Every embedded field requires a visible label translation in the same atomic proposal:
+
+- option label: `options.other.label`;
+- field label: `embeddedForms.other.fields.other_text.label`;
+- optional placeholder: `embeddedForms.other.fields.other_text.placeholder`;
+- validation message, when configured:
+  `embeddedForms.other.fields.other_text.validations.<validationId>.message`;
+- select option label, when applicable:
+  `embeddedForms.other.fields.other_text.options.<selectOptionId>.label`.
+
+Do not duplicate completion wording in both the option and field labels. For “Other, please
+specify”, use option label “Other” and field label “Please specify”.
+
+## Existing-Item Raw Patch Checklist
+
+1. Inspect the existing choice item and identify the exact option index/id and item JSON Pointer.
+2. Add or replace `<itemPath>/config/options/<optionIndex>/embeddedForm`.
+3. Add each required dotted content-key leaf under
+   `/translations/<locale>/itemTranslations/<itemId>/...`.
+4. Preserve the existing locale and item-translation containers; never replace either whole branch.
+5. Submit all entries as one `survey-json-patch` operation in one `survey_change` call.
+
+Embedded response slots use `embedded.<optionId>.<fieldKey>`, for example
+`embedded.other.other_text`.