@case-framework/survey-assistant 0.7.0 → 0.8.0

package/dist/{tools-BvSovehT.mjs → tools-CEsv-WoO.mjs}

@@ -1,8 +1,8 @@
-import { X as SURVEY_OPERATION_KINDS, bt as surveyOperationSchemasByKind, f as surveyChangeSetSchema, q as assistantItemTypeManifestSchema, yt as surveyOperationSchema } from "./protocol-BhzQbx81.mjs";
-import { a as getDeterministicCreateItemTypes, o as inspectAssistantItem, s as resolveAssistantCapabilityReference } from "./capabilities-1KNnNO1_.mjs";
-import { $ as sliceWithCursor, A as buildEmbeddedFormDetails, C as buildExpressionMutationBatch, F as clampLimit, G as itemMatchesQuery, H as getRawSurvey, I as findDirectChildrenByFullKey, J as mapOutlineById, K as itemSummarySchema, M as buildItemTranslationEntries, Q as resolveItemSummary, S as normalizeSurveyChangeOperations, T as expressionMutationSchema, U as getRawSurveyItems, V as getKeyIndexEntries, W as itemConfigDetailsSchema, X as normalizeText, Y as mapRawItemsById, at as summarizeRawItem, ct as analyzeSurveyAssistantExpressionReferences, d as collectExpressionMutationRecoveryTargets, et as summarizeFocusItemNode, f as collectMalformedSurveyOperationRecoveryTargets, it as summarizeOutlineNode, j as buildItemConfigDetails, k as buildConfigSearchText, m as auditSurvey, nt as summarizeKeyIndexEntries, ot as translationEntrySchema, p as collectSurveyOperationRecoveryTargets, q as mapKeyIndexById, st as unique, tt as summarizeItemById, u as collectExpressionMutationRecoveryRefinements, ut as getSurveyAssistantExpressionDiagnosticGuidance, v as createSurveyChangeSet } from "./engine-Bo85Oyj0.mjs";
-import { r as getSurveyAssistantEngineContext, s as requireSurveyAssistantTurnState } from "./request-context-CG4SWijt.mjs";
-import { a as surveyAuthoringReferences, i as surveyAuthoringReferenceTopics, r as getBuiltInItemTypeAuthoringReference, t as builtInSurveyAuthoringItemTypes } from "./authoring-references-BJQ_1nMX.mjs";
+import { Q as SURVEY_OPERATION_KINDS, Y as assistantItemTypeManifestSchema, bt as surveyOperationSchema, f as surveyChangeSetSchema, xt as surveyOperationSchemasByKind } from "./protocol-CF4Bh_Ch.mjs";
+import { C as isRecord$3, D as expressionMutationSchema, G as getRawSurveyItems, J as itemSummarySchema, K as itemConfigDetailsSchema, L as clampLimit, M as buildEmbeddedFormDetails, N as buildItemConfigDetails, P as buildItemTranslationEntries, Q as normalizeText, R as findDirectChildrenByParentId, T as buildExpressionMutationBatch, U as getItemIndexEntries, W as getRawSurvey, X as mapOutlineById, Y as mapItemIndexById, Z as mapRawItemsById, _t as createAssistantSurvey, ct as translationEntrySchema, d as collectExpressionMutationRecoveryTargets, et as resolveItemSummary, f as collectMalformedSurveyOperationRecoveryTargets, ft as getSurveyAssistantExpressionDiagnosticGuidance, it as summarizeItemIndexEntries, j as buildConfigSearchText, lt as unique, m as auditSurvey, nt as summarizeFocusItemNode, ot as summarizeOutlineNode, p as collectSurveyOperationRecoveryTargets, q as itemMatchesQuery, rt as summarizeItemById, st as summarizeRawItem, tt as sliceWithCursor, u as collectExpressionMutationRecoveryRefinements, ut as analyzeSurveyAssistantExpressionReferences, v as createSurveyChangeSet, vt as getAssistantVisibilityIssues, w as normalizeSurveyChangeOperations } from "./engine-nXoCWYpQ.mjs";
+import { a as getDeterministicCreateItemTypes, o as inspectAssistantItem, s as resolveAssistantCapabilityReference } from "./capabilities-DCMA71PP.mjs";
+import { r as getSurveyAssistantEngineContext, s as requireSurveyAssistantTurnState } from "./request-context-Dg4jSwN1.mjs";
+import { a as surveyAuthoringReferences, i as surveyAuthoringReferenceTopics, r as getBuiltInItemTypeAuthoringReference, t as builtInSurveyAuthoringItemTypes } from "./authoring-references-DbuOKerg.mjs";
 import { z } from "zod";
 import { JsonPatchError, SURVEY_EDITOR_ITEM_COLORS, encodeJsonPointerSegment, getAssetUsagesFromContent, getContentPlainText, getValueAtJsonPointer, isBlockingSurveyExpressionReferenceDiagnostic } from "@case-framework/survey-core";
 import { randomUUID } from "node:crypto";
@@ -68,6 +68,16 @@ const formatItemCapabilityProfile = (manifest, kind) => {
 	if (kind === "create-item") lines.push("", "Creation scope: include the initial structure, configuration, and visible translations that are already known. A later successful mutation call in the same turn may target the created id; the server adds that delta to the validated turn draft.");
 	return lines.join("\n");
 };
+const formatItemConfigurationContract = (schema) => [
+	"## Validated item configuration",
+	"This schema validates the resulting configuration after creation or an atomic patch. patch-item-config paths are relative to this object. Inspect existing configuration and preserve surviving identities; include related translations in the same proposal.",
+	"```json",
+	JSON.stringify(z.toJSONSchema(schema, {
+		io: "input",
+		unrepresentable: "any"
+	}), null, 2),
+	"```"
+].join("\n\n");
 const formatSurveyOperationContractReference = (kind, options = {}) => {
 	const { $schema: _schemaVersion, ...contract } = z.toJSONSchema(surveyOperationSchemasByKind[kind], {
 		io: "input",
@@ -89,7 +99,8 @@ const formatSurveyOperationContractReference = (kind, options = {}) => {
 		"```json",
 		JSON.stringify(renderedContract, null, 2),
 		"```",
-		...itemCapability ? ["", formatItemCapabilityProfile(itemCapability, kind)] : []
+		...itemCapability ? ["", formatItemCapabilityProfile(itemCapability, kind)] : [],
+		...options.itemConfigurationSchema && (kind === "patch-item-config" || kind === "create-item") ? [formatItemConfigurationContract(options.itemConfigurationSchema)] : []
 	].join("\n");
 };
 //#endregion
@@ -246,7 +257,8 @@ const surveyAuthoringReferenceTool = createTool({
 				title: itemCapability ? `${inputData.operationKind} for ${itemCapability.displayName}` : `${inputData.operationKind} operation contract`,
 				content: formatSurveyOperationContractReference(inputData.operationKind, {
 					detail: contractDetail,
-					itemCapability
+					itemCapability,
+					itemConfigurationSchema: inputData.itemType ? engineContext?.trustedCapabilities?.byItemType.get(inputData.itemType)?.configurationSchema : void 0
 				})
 			};
 		}
@@ -297,7 +309,7 @@ const surveyAuthoringReferenceTool = createTool({
 			itemType: inputData.itemType,
 			operationKind: inputData.operationKind,
 			title: entry.title,
-			content: entry.content
+			content: inputData.topic === "item-types" && capability?.configurationSchema ? `${entry.content}\n\n${formatItemConfigurationContract(capability.configurationSchema)}` : entry.content
 		};
 	},
 	toModelOutput: (value) => toTextModelOutput(value, (output) => `# ${output.title}\n\n${output.content}`)
@@ -322,16 +334,17 @@ const OPERATIONS_DESCRIPTION = [
 	"For an unfamiliar canonical shape, load survey_authoring_reference with topic \"assistant-operations\" and operationKind; it returns only that operation schema, generated from the validator.",
 	"Any translations owned by an operation must be inside that same operation object. Never put translations beside the survey_change operations array.",
 	"Every translation payload uses exactly one representation: plainText, canonical content, or the model-facing richTextBlocks shorthand. Shorthand is accepted wherever a typed translation accepts structured content and is normalized to canonical content before validation. Use it only for surfaces that focused guidance identifies as rendering rich text.",
-	"Canonical create-item shape: put parentItemId and optional index in target; put the required key and itemType, plus optional id, config, and creation-time expressions, in item; put respondent-visible plainText or structured content in top-level translations. Put choice maxSelection and options inside item.config. For top-level creation, target the root group identified by the snapshot or inspection.",
+	"Canonical create-item shape: put parentItemId and optional zero-based index in target (omitting index appends; index: 0 inserts first); put the required itemType, plus optional id, config, and creation-time expressions, in item; put respondent-visible plainText or structured content in top-level translations. Put choice maxSelection and options inside item.config. For top-level creation, target the root group identified by the snapshot or inspection.",
 	"Use update-item-translation with itemId, locale, contentKey, and plainText for ordinary respondent-visible text. For a complete formatted replacement, prefer the richTextBlocks shorthand from rich-text-content; canonical content remains available when needed. Item title, subtitle, topContent, bottomContent, cardFooter, info content, option labels, and field labels are translations, not item labels.",
 	"Use add-survey-locale only when the user explicitly requests an empty language registration. An ordinary localization request requires real translation operations, which introduce the locale themselves.",
 	"Use remove-survey-locale with locale to destructively remove an existing survey language and all translations stored for it.",
 	"Each call adds a delta to this turn's validated draft. Later calls may target ids created by earlier successful calls in the same turn.",
 	"Use operations: [] only with retryOfChangeIds when pendingRepairs.allowsAcknowledgment is true, after inspecting the validator-confirmed no-op. This does not discharge identifiable pending edits or create an editor commit by itself.",
-	"For an existing choice item, use add-choice-option with itemId, optional locale/index, and option: { id?, key?, label }; label is a plain string and creates its translation.",
-	"Every reorder replaces the complete inspected list: reorder-choice-options uses optionIds, reorder-form-field-groups uses groupIds, and reorder-items uses itemIds for every direct child. Include every existing entry exactly once in desired order.",
+	"For an existing choice item, use add-choice-option with itemId, optional locale/index, and option: { id?, code?, label }; label is a plain string and creates its translation.",
+	"Every reorder replaces the complete inspected list: reorder-choice-options uses optionIds, reorder-form-field-groups uses groupIds, and reorder-items uses top-level parentItemId (not target.parentItemId) and itemIds for every direct child. Include every existing entry exactly once in desired order.",
 	`Use update-item-color only with a supported swatch. ${`Allowed editor item-color swatches: ${SURVEY_EDITOR_ITEM_COLORS.join(", ")}. Use one of these exact values for update-item-color; do not wait for validation feedback to choose a swatch.`}`,
-	"Use patch-item-config with itemId and plural patches whose JSON Pointer paths are relative to that item config root.",
+	"Use update-response-settings with naming and settings arrays for variable names, matrix coding components, option export codes and export formats. Load response-variables for the shared coding contract.",
+	"Use patch-item-config with itemId and plural patches whose JSON Pointer paths are relative to that item config root. Include related translations inside the operation. Load the focused item capability reference for its configuration and content keys.",
 	"Use update-placed-image only for an image already embedded in rich text in the live survey or validated turn draft. It can switch the placement between a local asset and an external URL and update its rendered ALT text, caption, width, height, maximum dimensions, and alignment. For a new item, prefer putting the canonical image block inside create-item.translations[].richTextBlocks. Do not use image asset metadata when the user asked to change one placed image.",
 	"When deleting referenced images and assets, include every reference-removal operation and remove-image-asset last in the same operations array.",
 	"A survey-json-patch proposal contains exactly one operation with kind survey-json-patch and one plural patches array containing every related raw edit. It must be the only operation in that survey_change call. Paths are rooted at the survey document, such as /surveyItems/<index>/config or /translations/<locale>; never start at /config or modify /$schema. Patch translation leaves rather than replacing existing locale or item-translation containers.",
@@ -367,7 +380,6 @@ const describeOperationTarget = (operation) => {
 		case "update-placed-image": return `${operation.kind} ${operation.locale}:${operation.itemId}:${operation.contentKey}#${operation.imageIndex}`;
 		case "update-item-label":
 		case "update-item-color":
-		case "update-item-key":
 		case "patch-item-config":
 		case "remove-item":
 		case "move-item": return `${operation.kind} ${operation.itemId}`;
@@ -379,11 +391,12 @@ const describeOperationTarget = (operation) => {
 		case "move-form-field": return `${operation.kind} ${operation.target.itemId}:${operation.fieldId}`;
 		case "set-embedded-form":
 		case "remove-embedded-form": return `${operation.kind} ${operation.itemId}:${operation.optionId}`;
-		case "add-choice-option": return `${operation.kind} ${operation.itemId}:${operation.option.id ?? operation.option.key ?? operation.option.label}`;
+		case "add-choice-option": return `${operation.kind} ${operation.itemId}:${operation.option.id ?? operation.option.code ?? operation.option.label}`;
 		case "update-choice-option-label":
 		case "remove-choice-option": return `${operation.kind} ${operation.itemId}:${operation.optionId}`;
 		case "reorder-choice-options": return `${operation.kind} ${operation.itemId}`;
 		case "reorder-items": return `${operation.kind} ${operation.parentItemId}`;
+		case "update-response-settings":
 		case "update-survey-metadata":
 		case "update-survey-pagination": return operation.kind;
 		case "update-survey-translation": return `${operation.kind} ${operation.locale}:${operation.surface}:${operation.contentKey}`;
@@ -392,7 +405,7 @@ const describeOperationTarget = (operation) => {
 		case "set-image-asset":
 		case "update-image-asset-metadata":
 		case "remove-image-asset": return `${operation.kind} ${operation.assetId}`;
-		case "create-item": return `${operation.kind} ${operation.item.id ?? operation.item.key ?? operation.item.itemType}`;
+		case "create-item": return `${operation.kind} ${operation.item.id ?? operation.item.metadata?.itemLabel ?? operation.item.id ?? operation.item.itemType}`;
 		case "survey-json-patch": return `${operation.kind} ${operation.patches.map((patch) => patch.path).join(", ")}`;
 	}
 };
@@ -410,11 +423,19 @@ const summarizeValidation = (event) => {
 		lines.push(`Draft updated (${event.operations.length} total operation${event.operations.length === 1 ? "" : "s"}). Later tools can inspect and edit the resulting draft state. The live editor is unchanged until successful turn completion.`);
 		if (event.postChange) {
 			const unavailableItemCount = event.postChange.touchedItemCount - event.postChange.availableTouchedItemCount;
-			lines.push(`Canonical post-change preview (first occurrence in operation order; projected fields only): ${event.postChange.itemCount} survey item(s); locales ${event.postChange.locales.length}/${event.postChange.localeCount} shown; targets ${event.postChange.touchedTargets.length}/${event.postChange.targetCount} shown; available touched-item snapshots ${event.postChange.touchedItems.length}/${event.postChange.availableTouchedItemCount} shown${unavailableItemCount > 0 ? `; ${unavailableItemCount} touched item target(s) are absent after the change` : ""}.`);
+			lines.push(`Canonical post-change preview (mutation targets first, then affected parents; projected fields only): ${event.postChange.itemCount} survey item(s); locales ${event.postChange.locales.length}/${event.postChange.localeCount} shown; targets ${event.postChange.touchedTargets.length}/${event.postChange.targetCount} shown; available touched-item snapshots ${event.postChange.touchedItems.length}/${event.postChange.availableTouchedItemCount} shown${unavailableItemCount > 0 ? `; ${unavailableItemCount} touched item target(s) are absent after the change` : ""}.`);
 			lines.push(`Target preview: ${event.postChange.touchedTargets.join(", ") || "none"}. Absence from this bounded projection does not prove that a field or target is absent from the canonical draft.`);
 			for (const item of event.postChange.touchedItems) {
 				const translations = item.translations.map(({ contentKey, locale, textLength, textPreview, truncated }) => truncated ? `${locale}:${contentKey}=${JSON.stringify(`${textPreview}…`)} [truncated preview; ${textLength} characters total]` : `${locale}:${contentKey}=${JSON.stringify(textPreview)}`).join("; ");
-				lines.push(`- ${item.fullKey} (${item.itemType}, id ${item.itemId}); response slots ${item.responseSlots.length}/${item.responseSlotCount}: ${item.responseSlots.join(", ") || "none"}; translations ${item.translations.length}/${item.translationCount}: ${translations || "none"}`);
+				lines.push(`- ${item.breadcrumb} (${item.itemType}, id ${item.itemId}); response slots ${item.responseSlots.length}/${item.responseSlotCount}: ${item.responseSlots.join(", ") || "none"}; translations ${item.translations.length}/${item.translationCount}: ${translations || "none"}`);
+				if (item.placement) {
+					const p = item.placement;
+					lines.push(`  Stored placement: parent ${p.parentItemId}; index ${p.index} (zero-based), ${p.index + 1}/${p.siblingCount}; previous ${p.previousItemId ?? "none"}; next ${p.nextItemId ?? "none"}.${p.shuffled ? " Parent shuffles children; respondent order may differ." : ""}`);
+				}
+				if (item.childOrder) {
+					const order = item.childOrder;
+					lines.push(`  Stored child order (${order.itemIds.length}/${order.total}${order.truncated ? "; truncated" : ""}): ${JSON.stringify(order.itemIds)}.${order.shuffled ? " Group shuffles children; respondent order may differ." : ""}`);
+				}
 			}
 			if (event.postChange.truncated) lines.push("The post-change preview is truncated. The validated draft still contains the complete change; inspect any relevant omitted target or field before claiming its exact post-change value.");
 		}
@@ -500,7 +521,7 @@ const inputSchema$8 = z.object({
 	retryOfChangeIds: retryOfChangeIdsSchema,
 	action: z.enum(["context", "prepare"]).describe("Choose exactly one envelope. Inspect with action=\"context\" and optional reason, itemIds, or includeRawLocations. Create edits with action=\"prepare\", summary, and mutations."),
 	reason: z.string().max(500).optional().describe("Context action only: optional inspection reason."),
-	itemIds: z.array(z.string().min(1).max(240)).max(12).optional().describe("Context action only: filter response slots and expression locations by item ids, keys, or fullKeys. Omit to inspect survey-wide references, including controlling questions outside the conditioned item."),
+	itemIds: z.array(z.string().min(1).max(240)).max(12).optional().describe("Context action only: filter response slots and expression locations by exact item IDs. Omit to inspect survey-wide references, including controlling questions outside the conditioned item."),
 	cursor: z.string().regex(/^\d+$/).max(12).optional().describe("Context action only: nextCursor from the preceding page, with the same itemIds and includeRawLocations. Restart after a draft mutation."),
 	limit: z.number().int().min(1).max(80).optional().describe("Context action only: rows per catalog page; defaults to 80."),
 	includeRawLocations: z.boolean().optional().describe("Context action only: include existing expression locations by raw item."),
@@ -542,12 +563,17 @@ const contextOutputSchema = z.object({
 	totalExpressionLocations: z.number().int().nonnegative().optional(),
 	unresolvedItemIds: z.array(z.string()).optional(),
 	responseSlots: z.array(z.object({
-		ref: z.string(),
-		valueType: z.string().optional()
+		ref: z.object({
+			slotId: z.string(),
+			method: z.enum(["get", "isDefined"])
+		}),
+		valueType: z.string().optional(),
+		variableName: z.string().optional(),
+		itemId: z.string().optional()
 	})),
 	expressionLocations: z.array(z.object({
 		itemId: z.string(),
-		key: z.string(),
+		editorName: z.string(),
 		itemType: z.string(),
 		rawIndex: z.number().int().nonnegative(),
 		locations: z.array(z.string())
@@ -591,22 +617,32 @@ const summarizeDraftEvent = (event) => {
 };
 const buildContextOutput = (snapshot, input) => {
 	const rawItems = getRawSurveyItems(snapshot);
+	const names = new Map(snapshot.inspection.itemIndex.map((item) => [item.itemId, item.editorName]));
 	const resolvedItems = input.itemIds?.map((identifier) => ({
 		identifier,
-		itemId: snapshot.inspection.keyIndex.find((entry) => entry.itemId === identifier || entry.key === identifier || entry.fullKey === identifier)?.itemId
+		itemId: snapshot.inspection.itemIndex.find((entry) => entry.itemId === identifier || entry.editorName === identifier || entry.breadcrumb === identifier)?.itemId
 	}));
 	const itemFilter = resolvedItems?.length ? new Set(resolvedItems.flatMap((entry) => entry.itemId ? [entry.itemId] : [])) : void 0;
 	const unresolvedItemIds = resolvedItems?.filter((entry) => !entry.itemId).map((entry) => entry.identifier) ?? [];
 	const surveyResponseSlots = Object.entries(buildResponseSlotTypes(snapshot));
-	const allResponseSlots = surveyResponseSlots.filter(([ref]) => !itemFilter || [...itemFilter].some((id) => ref.startsWith(`${id}...`))).map(([ref, valueType]) => ({
-		ref,
-		...valueType ? { valueType } : {}
-	}));
+	const allResponseSlots = surveyResponseSlots.filter(([ref]) => !itemFilter || snapshot.responseVariables.some((slot) => itemFilter.has(slot.itemId) && JSON.parse(ref)[0] === slot.slotId)).map(([key, valueType]) => {
+		const [slotId, method] = JSON.parse(key);
+		const slot = snapshot.responseVariables.find((slot) => slot.slotId === slotId);
+		return {
+			ref: {
+				slotId,
+				method
+			},
+			valueType,
+			variableName: slot?.variableName,
+			itemId: slot?.itemId
+		};
+	});
 	const offset = Number(input.cursor ?? 0);
 	const limit = input.limit ?? 80;
 	const responseSlots = allResponseSlots.slice(offset, offset + limit);
 	const allExpressionLocations = input.action === "context" && input.includeRawLocations === true ? rawItems.map((item, rawIndex) => {
-		if (itemFilter && !itemFilter.has(item.id) && !itemFilter.has(item.key)) return;
+		if (itemFilter && !itemFilter.has(item.id)) return;
 		const locations = [
 			item.displayConditions?.root ? "displayConditions.root" : void 0,
 			...Object.keys(item.displayConditions?.components ?? {}).map((componentId) => `displayConditions.components.${componentId}`),
@@ -616,7 +652,7 @@ const buildContextOutput = (snapshot, input) => {
 		].filter((location) => Boolean(location));
 		return {
 			itemId: item.id,
-			key: item.key,
+			editorName: names.get(item.id) ?? item.id,
 			itemType: item.itemType,
 			rawIndex,
 			locations
@@ -633,17 +669,17 @@ const buildContextOutput = (snapshot, input) => {
 			"Use prepare mutations for display conditions, disabled conditions, validations, prefills, and template values.",
 			"Display, disabled, validation, and prefill.when expressions must return boolean.",
 			"Use response refs exactly as listed and check their value types before choosing functions.",
-			"An isDefined ref means only that the respondent answered; it never means a particular answer such as Yes, selected, eligible, or has children.",
+			"An isDefined ref means only that an active answer exists; it never means a particular answer such as Yes, selected, eligible, or has children.",
 			"When the condition names or implies a choice, inspect the source choice item for the exact option id, then compare its get ref with that reference using eq or list_contains.",
-			"Avoid accidental item display-condition response cycles, including self-reference or A-to-B-to-A chains. Shared analysis reports them as advisory because prefills can make them intentional; prefer an acyclic controlling source item unless the dependency is deliberate.",
+			"Visibility must be acyclic, including item, ancestor, component and computed-response dependencies. Prefills do not permit cycles. Use an independent controlling answer or serialized context value. Hidden answers are retained but inactive: get is undefined and isDefined is false. Undefined/nonboolean visibility hides its target; customExpression callbacks are not supported in visibility.",
 			"For choice options: use eq(response reference, reference const) when the slot type is reference; use list_contains(response reference[], reference const) only when the slot type is reference[].",
 			"Response-slot order: set-like deterministic snapshot construction order; it has no survey or respondent-visible meaning.",
 			itemFilter ? `Response-slot scope: filtered to itemIds=${JSON.stringify(input.itemIds)}; ${allResponseSlots.length} matching of ${surveyResponseSlots.length} survey-wide slots. References outside this filter are omitted, not absent. To find controlling questions elsewhere, call survey_expression action=context without itemIds or cursor.` : `Response-slot scope: survey-wide (${surveyResponseSlots.length} slots).`,
-			`Response slots (${responseSlots.length}/${allResponseSlots.length}, offset ${offset}): ${responseSlots.map((slot) => `${slot.ref}${slot.valueType ? `:${slot.valueType}` : ""}`).join(", ")}`,
+			`Response slots (${responseSlots.length}/${allResponseSlots.length}, offset ${offset}): ${responseSlots.map((slot) => `${JSON.stringify(slot.ref)}${slot.valueType ? `:${slot.valueType}` : ""}`).join(", ")}`,
 			nextCursor ? `More expression context is available. Call survey_expression action=context with cursor="${nextCursor}" and the same itemIds, includeRawLocations, and limit. Restart without a cursor after a draft mutation.` : "Expression context pagination complete for this scope.",
 			unresolvedItemIds.length > 0 ? `Unresolved item identifiers: ${JSON.stringify(unresolvedItemIds)}. Inspect current context or search-items to resolve them; no references for these targets are implied.` : void 0,
 			"Functions: and, or, not, eq, gt, gte, lt, lte, in_range, list_contains, sum, min, max, str_eq, date_eq.",
-			expressionLocations ? `Existing expression locations: ${expressionLocations.filter((entry) => entry.locations.length > 0).map((entry) => `${entry.key}(${entry.itemId}) -> ${entry.locations.join("|")}`).join("; ") || "none"}` : void 0
+			expressionLocations ? `Existing expression locations: ${expressionLocations.filter((entry) => entry.locations.length > 0).map((entry) => `${entry.editorName}(${entry.itemId}) -> ${entry.locations.join("|")}`).join("; ") || "none"}` : void 0
 		].filter((line) => Boolean(line)).join("\n"),
 		totalResponseSlots: allResponseSlots.length,
 		surveyResponseSlotCount: surveyResponseSlots.length,
@@ -772,6 +808,69 @@ const parseInspectionOutput = (schema, value, backend) => {
 	return parsed.data;
 };
 //#endregion
+//#region src/server/tools/response-variable-summary.ts
+const MAX_COMPONENTS = 50;
+const responseVariableSummarySchema = z.object({
+	slotId: z.string(),
+	itemId: z.string(),
+	variableName: z.string(),
+	valueType: z.string(),
+	primitiveId: z.string().optional(),
+	rowId: z.string().optional(),
+	columnId: z.string().optional(),
+	namingKind: z.enum(["variable", "matrix"]).optional(),
+	computed: z.object({
+		operation: z.string(),
+		sourceSlotIds: z.array(z.string())
+	}).optional(),
+	computedSourcesTruncated: z.boolean(),
+	referenceValueKeys: z.record(z.string(), z.string()).optional(),
+	referenceValueScores: z.record(z.string(), z.number()).optional(),
+	optionIds: z.array(z.string()),
+	optionsTotal: z.number(),
+	optionsTruncated: z.boolean()
+});
+const responseOptionIds = (slot) => [.../* @__PURE__ */ new Set([
+	...Object.keys(slot.referenceValueKeys ?? {}),
+	...Object.keys(slot.referenceValueScores ?? {}),
+	...(slot.allowedValues ?? []).flatMap((value) => value.type === "reference" ? [value.value] : value.type === "reference[]" ? value.value : [])
+])];
+/** Coding discovery excludes config paths and duplicated translations for every survey locale. */
+const summarizeResponseVariable = (slot) => {
+	const optionIds = responseOptionIds(slot);
+	const take = (values) => values && Object.fromEntries(optionIds.slice(0, MAX_COMPONENTS).filter((id) => Object.hasOwn(values, id)).map((id) => [id, values[id]]));
+	return {
+		slotId: slot.slotId,
+		itemId: slot.itemId,
+		variableName: slot.variableName,
+		valueType: slot.valueType,
+		primitiveId: slot.primitiveId,
+		rowId: slot.rowId,
+		columnId: slot.columnId,
+		namingKind: slot.naming?.kind,
+		computed: slot.computed && {
+			...slot.computed,
+			sourceSlotIds: slot.computed.sourceSlotIds.slice(0, MAX_COMPONENTS)
+		},
+		computedSourcesTruncated: (slot.computed?.sourceSlotIds.length ?? 0) > MAX_COMPONENTS,
+		referenceValueKeys: take(slot.referenceValueKeys),
+		referenceValueScores: take(slot.referenceValueScores),
+		optionIds: optionIds.slice(0, MAX_COMPONENTS),
+		optionsTotal: optionIds.length,
+		optionsTruncated: optionIds.length > MAX_COMPONENTS
+	};
+};
+const responseVariableMatchesQuery = (slot, query) => [
+	slot.slotId,
+	slot.itemId,
+	slot.variableName,
+	slot.primitiveId,
+	slot.rowId,
+	slot.columnId,
+	...responseOptionIds(slot),
+	...Object.values(slot.referenceValueKeys ?? {})
+].some((value) => value?.toLowerCase().includes(query));
+//#endregion
 //#region src/server/tools/inspect-current-context.ts
 const contextScopeSchema = z.enum([
 	"summary",
@@ -794,9 +893,9 @@ const translationSnippetSchema = z.object({
 const inputSchema$7 = z.object({
 	scopes: z.array(contextScopeSchema).min(1).default(["summary"]).describe("Which current editor context sections to inspect."),
 	itemId: z.string().optional().describe("Optional item id to inspect. Defaults to the selected/focused item."),
-	query: z.string().max(180).optional().describe("Optional text used to find matching item ids, keys, labels, or response slots."),
+	query: z.string().max(180).optional().describe("Optional text used to find matching item IDs, editor names, labels, or response variables."),
 	cursor: z.string().optional().describe("Optional numeric cursor returned by a previous outline or response slot request."),
-	outlineMode: outlineModeSchema$1.default("full").optional().describe("For outline scope: \"full\" pages the complete survey key index, \"focused\" returns the selected/focused neighborhood, and \"children\" returns direct children of itemId."),
+	outlineMode: outlineModeSchema$1.default("full").optional().describe("For outline scope: \"full\" pages the complete survey item index, \"focused\" returns the selected/focused neighborhood, and \"children\" returns direct children of itemId."),
 	limit: z.number().int().min(1).max(50).default(12).describe("Maximum number of rows to return for list-like scopes.")
 });
 const outputSchema$6 = z.object({
@@ -810,6 +909,7 @@ const outputSchema$6 = z.object({
 		sessionId: z.string().nullable(),
 		view: z.string(),
 		selectedItemId: z.string().optional(),
+		responseSlotId: z.string().optional(),
 		focusItemId: z.string().optional(),
 		selectedLocale: z.string(),
 		recentItemIds: z.array(z.string()),
@@ -859,7 +959,7 @@ const outputSchema$6 = z.object({
 		nextCursor: z.string().optional(),
 		truncated: z.boolean(),
 		ordering: z.string(),
-		slots: z.array(z.string()),
+		slots: z.array(responseVariableSummarySchema),
 		note: z.string().optional()
 	}).optional(),
 	uiContext: z.object({
@@ -913,13 +1013,14 @@ const flattenFocusDescendants = (node) => {
 };
 const getCandidateItems = (snapshot) => {
 	const outlineById = mapOutlineById(snapshot);
-	return summarizeKeyIndexEntries(getKeyIndexEntries(snapshot), outlineById);
+	return summarizeItemIndexEntries(getItemIndexEntries(snapshot), outlineById);
 };
 const buildSummary = (snapshot) => ({
 	rootItem: snapshot.inspection.outline.filter((item) => item.depth === 0).map(summarizeOutlineNode)[0],
 	sessionId: snapshot.version.sessionId,
 	view: snapshot.ui.view,
 	selectedItemId: snapshot.ui.selectedItemId,
+	responseSlotId: snapshot.ui.responseSlotId,
 	focusItemId: snapshot.ui.focusItemId,
 	selectedLocale: snapshot.ui.selectedLocale,
 	recentItemIds: snapshot.ui.recentItemIds ?? [],
@@ -927,7 +1028,7 @@ const buildSummary = (snapshot) => ({
 	locales: snapshot.inspection.locales,
 	itemCount: snapshot.inspection.itemCount,
 	historyIndex: snapshot.version.historyIndex,
-	outlineItemCount: snapshot.inspection.keyIndex.length,
+	outlineItemCount: snapshot.inspection.itemIndex.length,
 	responseSlotCount: snapshot.inspection.responseSlots.length,
 	availableItemTypes: snapshot.capabilities.itemTypes.map((entry) => entry.itemType),
 	deterministicCreateItemTypes: getDeterministicCreateItemTypes(snapshot.capabilities),
@@ -935,7 +1036,7 @@ const buildSummary = (snapshot) => ({
 });
 const buildSelectedItem = (snapshot, input) => {
 	const outlineById = mapOutlineById(snapshot);
-	const indexById = mapKeyIndexById(snapshot);
+	const indexById = mapItemIndexById(snapshot);
 	const resolvedInputItem = input.itemId ? resolveItemSummary(input.itemId, indexById, outlineById) : void 0;
 	const requestedItemId = resolvedInputItem?.itemId ?? input.itemId ?? snapshot.ui.selectedItemId ?? snapshot.ui.focusItemId;
 	if (!requestedItemId) return {
@@ -968,11 +1069,12 @@ const buildSelectedItem = (snapshot, input) => {
 const buildOutline = (snapshot, input) => {
 	const query = normalizeText(input.query);
 	const outlineById = mapOutlineById(snapshot);
-	const indexById = mapKeyIndexById(snapshot);
+	const indexById = mapItemIndexById(snapshot);
 	const resolvedInputItem = input.itemId ? resolveItemSummary(input.itemId, indexById, outlineById) : void 0;
 	const requestedItemId = resolvedInputItem?.itemId ?? input.itemId ?? snapshot.ui.focusItemId ?? snapshot.ui.selectedItemId;
 	const outlineMode = input.outlineMode ?? "full";
 	let strategy = "focused-snapshot-outline";
+	let parentShuffled;
 	let items;
 	let note;
 	if (query) {
@@ -981,8 +1083,12 @@ const buildOutline = (snapshot, input) => {
 	} else if (outlineMode === "children" && requestedItemId) {
 		strategy = "direct-children";
 		const parent = resolvedInputItem ?? summarizeItemById(requestedItemId, indexById, outlineById);
-		items = parent ? findDirectChildrenByFullKey(getKeyIndexEntries(snapshot), outlineById, parent.fullKey) : [];
-		if (!parent) note = "The requested item could not be resolved by item id, key, or fullKey.";
+		items = parent ? findDirectChildrenByParentId(getItemIndexEntries(snapshot), outlineById, parent.itemId) : [];
+		if (!parent) note = "The requested item could not be resolved by exact item ID.";
+		else {
+			const rawParent = snapshot.survey.surveyItems.find((item) => item.id === parent.itemId);
+			if (rawParent?.itemType === "group") parentShuffled = isRecord$3(rawParent.config) && rawParent.config.shuffleItems === true;
+		}
 	} else if (outlineMode === "focused" && requestedItemId && snapshot.inspection.focus?.focusItemId === requestedItemId) {
 		const focus = snapshot.inspection.focus;
 		const descendantIds = snapshot.inspection.focusItem ? flattenFocusDescendants(snapshot.inspection.focusItem).map((item) => item.itemId) : [];
@@ -999,7 +1105,7 @@ const buildOutline = (snapshot, input) => {
 		items = item ? [item] : [];
 		note = "The requested item is outside the selected focus tree in this snapshot.";
 	} else {
-		strategy = "full-key-index";
+		strategy = "full-item-index";
 		items = getCandidateItems(snapshot);
 	}
 	const page = sliceWithCursor(items, input);
@@ -1012,15 +1118,21 @@ const buildOutline = (snapshot, input) => {
 		returned: page.items.length,
 		nextCursor: page.nextCursor,
 		truncated: page.truncated,
-		ordering: strategy === "focused-snapshot-outline" ? "Survey-tree preorder: configured group-child order is preserved; unparented items are appended by item id." : strategy === "direct-children" ? "Stored group-child order; this is not a stable respondent-visible order if that group shuffles children." : strategy === "query-match" ? "Survey-tree preorder after filtering by the query; this is not relevance-ranked." : "Relationship grouping for the focused item, not a single positional survey order.",
+		ordering: {
+			"full-item-index": "Survey-tree preorder: configured group-child order is preserved; unparented items are appended by item id. Shuffled groups may render a different respondent order.",
+			"direct-children": parentShuffled === void 0 ? "No resolved parent group; this result does not establish sibling order." : parentShuffled ? "Stored group-child order; this group shuffles children, so respondent order may differ." : "Stored group-child order; this group does not shuffle children.",
+			"query-match": "Survey-tree preorder after filtering by the query; this is not relevance-ranked.",
+			"item-match": "Single matched item; this does not establish sibling order.",
+			"focused-snapshot-outline": "Relationship grouping for the focused item, not a single positional survey order."
+		}[strategy],
 		items: page.items,
 		note
 	};
 };
 const buildResponseSlots = (snapshot, input) => {
-	const responseSlots = snapshot.inspection.responseSlots;
+	const responseSlots = snapshot.responseVariables;
 	const query = normalizeText(input.query);
-	const filtered = query ? responseSlots.filter((slot) => slot.toLowerCase().includes(query)) : responseSlots;
+	const filtered = query ? responseSlots.filter((slot) => responseVariableMatchesQuery(slot, query)) : responseSlots;
 	const page = sliceWithCursor(filtered, input);
 	return {
 		available: true,
@@ -1030,7 +1142,7 @@ const buildResponseSlots = (snapshot, input) => {
 		nextCursor: page.nextCursor,
 		truncated: page.truncated,
 		ordering: "Set-like response references in deterministic snapshot construction order; do not interpret their position as survey or respondent order.",
-		slots: page.items
+		slots: page.items.map(summarizeResponseVariable)
 	};
 };
 const inspectSurveyCurrentContext = (inputData, requestContext) => {
@@ -1087,7 +1199,9 @@ const inspectSurveyCurrentContext = (inputData, requestContext) => {
 //#endregion
 //#region src/server/tools/inspect-item-details.ts
 const inputSchema$6 = z.object({
-	itemId: z.string().describe("Identifier of the item to inspect: its itemId, key (e.g. \"info_1\"), or fullKey (e.g. \"survey.info_1\"). Discover candidates first via survey_inspect search or current context."),
+	cursor: z.string().optional(),
+	responseVariablesLimit: z.number().int().min(1).max(50).default(20),
+	itemId: z.string().describe("Exact persistent itemId. Discover candidates by editor name, breadcrumb or content using survey_inspect search; duplicate names are allowed, so select the intended ID."),
 	locales: z.array(z.string()).optional().describe("Optional locale codes to restrict returned translations to. Defaults to all locales."),
 	textLimit: z.number().int().min(20).max(2e3).default(400).describe("Maximum characters returned per translation snippet."),
 	includeChildren: z.boolean().optional().describe("Deprecated alias for includeSurveyChildren. This means survey-tree children only, not choice options or form fields."),
@@ -1104,6 +1218,11 @@ const outputSchema$5 = z.object({
 	surveyChildrenTruncated: z.boolean().optional(),
 	listOrdering: z.record(z.string(), z.string()).optional().describe("Meaning of each returned list. A list is positional only when its entry says so."),
 	configDetails: itemConfigDetailsSchema.optional(),
+	responseVariables: z.array(responseVariableSummarySchema).optional(),
+	responseVariablesTotal: z.number().optional(),
+	responseVariablesTruncated: z.boolean().optional(),
+	responseVariablesNextCursor: z.string().optional(),
+	responseVariablesNote: z.string().optional(),
 	capabilityDetails: z.object({
 		summary: z.string(),
 		details: z.unknown().optional()
@@ -1120,12 +1239,12 @@ const inspectSurveyItemDetails = (inputData, requestContext) => {
 		reason: "No live editor snapshot was provided with this assistant turn."
 	};
 	const outlineById = mapOutlineById(snapshot);
-	const indexById = mapKeyIndexById(snapshot);
+	const indexById = mapItemIndexById(snapshot);
 	const rawItemsById = mapRawItemsById(snapshot);
 	const item = resolveItemSummary(input.itemId, indexById, outlineById);
 	if (!item) return {
 		ok: false,
-		reason: `No item matching "${input.itemId}" (by itemId, key, or fullKey) was found in the current context snapshot.`
+		reason: `No item matching "${input.itemId}" (by exact itemId) was found in the current context snapshot.`
 	};
 	const rawItem = rawItemsById.get(item.itemId);
 	const rawConfig = rawItem?.config && typeof rawItem.config === "object" && !Array.isArray(rawItem.config) ? rawItem.config : void 0;
@@ -1139,12 +1258,23 @@ const inspectSurveyItemDetails = (inputData, requestContext) => {
 		}
 	};
 	if (input.includeSurveyChildren) {
-		const allChildren = findDirectChildrenByFullKey(getKeyIndexEntries(snapshot), outlineById, item.fullKey);
+		const entries = getItemIndexEntries(snapshot);
+		const allChildren = findDirectChildrenByParentId(entries, outlineById, item.itemId);
 		const limit = clampLimit(input.childrenLimit);
 		output.surveyChildren = allChildren.slice(0, limit);
 		output.surveyChildrenTruncated = allChildren.length > limit;
 	}
 	if (input.includeItemConfig) {
+		const variables = snapshot.responseVariables.filter((slot) => slot.itemId === item.itemId);
+		const page = sliceWithCursor(variables, {
+			cursor: input.cursor,
+			limit: input.responseVariablesLimit
+		});
+		output.responseVariables = page.items.map(summarizeResponseVariable);
+		output.responseVariablesTotal = variables.length;
+		output.responseVariablesTruncated = page.truncated;
+		output.responseVariablesNextCursor = page.nextCursor;
+		output.responseVariablesNote = "Use responseVariablesNextCursor as cursor with the same itemRef to continue. Option and computed-source summaries include up to 50 entries; inspect exact raw-json config paths for complete domains and export settings. Restart pagination after mutations.";
 		output.configDetails = rawItem ? buildItemConfigDetails(rawItem) : void 0;
 		output.capabilityDetails = rawItem ? inspectAssistantItem({
 			capabilities: snapshot.trustedCapabilities,
@@ -1155,7 +1285,8 @@ const inspectSurveyItemDetails = (inputData, requestContext) => {
 			const rawOptions = Array.isArray(rawChoiceConfig?.options) ? rawChoiceConfig.options : [];
 			for (const option of output.configDetails.choiceOptions) {
 				const rawOption = rawOptions.find((candidate) => candidate && typeof candidate === "object" && "id" in candidate && candidate.id === option.id);
-				const embeddedFormDetails = buildEmbeddedFormDetails(option, rawOption && typeof rawOption === "object" && "embeddedForm" in rawOption ? rawOption.embeddedForm : void 0);
+				const embeddedForm = rawOption && typeof rawOption === "object" && "embeddedForm" in rawOption ? rawOption.embeddedForm : void 0;
+				const embeddedFormDetails = buildEmbeddedFormDetails(option, embeddedForm);
 				if (embeddedFormDetails?.formFieldGroups?.length) output.configDetails.formFieldGroups = [...output.configDetails.formFieldGroups ?? [], ...embeddedFormDetails.formFieldGroups];
 			}
 		}
@@ -1169,14 +1300,14 @@ const MAX_VALUE_CHARACTER_LIMIT = 6e4;
 const jsonPointerPathSchema = z.string().max(500).describe("JSON Pointer path into the survey document. Examples: \"/surveyItems/0/config/items\", \"/metadata\", \"/translations/en/itemTranslations/<itemId>/title\".");
 const inputSchema$5 = z.object({
 	paths: z.array(jsonPointerPathSchema).min(1).max(20).optional().describe("Optional exact JSON Pointer paths to inspect. Omit paths and itemIdentifiers for a top-level raw survey overview."),
-	itemIdentifiers: z.array(z.string().min(1).max(240)).min(1).max(20).optional().describe("Optional item ids, keys, or fullKeys to inspect. Returns exact /surveyItems/<index> paths plus item translation paths for each item."),
+	itemIdentifiers: z.array(z.string().min(1).max(240)).min(1).max(20).optional().describe("Optional exact item IDs to inspect. Returns exact /surveyItems/<index> paths plus item translation paths for each item."),
 	textOffset: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER).optional(),
 	valueCharacterLimit: z.number().int().min(1e3).max(MAX_VALUE_CHARACTER_LIMIT).default(DEFAULT_VALUE_CHARACTER_LIMIT).describe("Maximum serialized characters returned per requested value.")
 });
 const rawSurveyItemPathSchema = z.object({
 	path: z.string(),
 	id: z.string(),
-	key: z.string(),
+	editorName: z.string(),
 	itemType: z.string(),
 	parentId: z.string().optional(),
 	childCount: z.number().int().nonnegative().optional()
@@ -1237,6 +1368,7 @@ const buildOverview = (snapshot) => {
 	const rawSurvey = getRawSurvey(snapshot);
 	const rawItems = getRawSurveyItems(snapshot);
 	const parentByChildId = buildParentByChildId(rawSurvey);
+	const names = new Map(snapshot.inspection.itemIndex.map((item) => [item.itemId, item.editorName]));
 	return {
 		topLevelKeys: Object.keys(rawSurvey).sort(),
 		surveyItemCount: rawItems.length,
@@ -1244,7 +1376,7 @@ const buildOverview = (snapshot) => {
 		itemPaths: rawItems.map((item, index) => ({
 			path: `/surveyItems/${index}`,
 			id: item.id,
-			key: item.key,
+			editorName: names.get(item.id) ?? item.id,
 			itemType: item.itemType,
 			parentId: parentByChildId.get(item.id),
 			childCount: getGroupChildren(item).length || void 0
@@ -1305,7 +1437,7 @@ const findRawItemByIdentifier = (snapshot, identifier) => {
 		item: rawItems[directIndex],
 		index: directIndex
 	};
-	const resolved = resolveItemSummary(identifier, mapKeyIndexById(snapshot), mapOutlineById(snapshot));
+	const resolved = resolveItemSummary(identifier, mapItemIndexById(snapshot), mapOutlineById(snapshot));
 	if (!resolved) return;
 	const resolvedIndex = rawItems.findIndex((item) => item.id === resolved.itemId);
 	if (resolvedIndex < 0) return;
@@ -1329,11 +1461,12 @@ const buildItemValues = (snapshot, input) => {
 		if (!resolved) return {
 			identifier,
 			found: false,
-			error: `No item matching "${identifier}" was found by item id, key, or fullKey.`
+			error: `No item matching "${identifier}" was found by exact item ID.`
 		};
 		const itemId = resolved.item.id;
 		const rawItemOutput = toOutputValue(resolved.item, input.valueCharacterLimit);
-		const translationsOutput = toOutputValue(getTranslationsByLocaleForItem(rawSurvey, itemId), input.valueCharacterLimit);
+		const translationsByLocale = getTranslationsByLocaleForItem(rawSurvey, itemId);
+		const translationsOutput = toOutputValue(translationsByLocale, input.valueCharacterLimit);
 		const translationsValue = "value" in translationsOutput && isRecord$1(translationsOutput.value) ? translationsOutput.value : void 0;
 		return {
 			identifier,
@@ -1420,7 +1553,7 @@ const outputSchema$3 = z.object({
 	ordering: z.string().optional().describe("How results and their matches are ordered; this search output is not survey order."),
 	results: z.array(searchResultSchema).optional()
 });
-const STOP_WORDS = new Set([
+const STOP_WORDS = /* @__PURE__ */ new Set([
 	"a",
 	"about",
 	"an",
@@ -1473,7 +1606,7 @@ const candidateItems = (snapshot) => {
 	const rawItemsById = mapRawItemsById(snapshot);
 	const seen = /* @__PURE__ */ new Set();
 	const candidates = [];
-	for (const entry of summarizeKeyIndexEntries(snapshot.inspection.keyIndex, outlineById)) {
+	for (const entry of summarizeItemIndexEntries(snapshot.inspection.itemIndex, outlineById)) {
 		seen.add(entry.itemId);
 		candidates.push({
 			item: entry,
@@ -1497,8 +1630,8 @@ const searchItems = (snapshot, input) => {
 		const structuralFields = [
 			["itemId", item.itemId],
 			["itemType", item.itemType],
-			["key", item.key],
-			["fullKey", item.fullKey],
+			["key", item.editorName],
+			["breadcrumb", item.breadcrumb],
 			["itemLabel", item.itemLabel],
 			["path", item.path?.join(" ")]
 		];
@@ -1540,7 +1673,7 @@ const searchItems = (snapshot, input) => {
 			matches: matches.slice(0, MAX_MATCHES_PER_ITEM),
 			score: matches.reduce((sum, match) => sum + match.score, 0)
 		};
-	}).filter((result) => Boolean(result)).sort((a, b) => b.score - a.score || a.item.fullKey.localeCompare(b.item.fullKey));
+	}).filter((result) => Boolean(result)).sort((a, b) => b.score - a.score || a.item.breadcrumb.localeCompare(b.item.breadcrumb));
 };
 const searchSurveyItems = (inputData, requestContext) => {
 	const input = inputSchema$4.parse(inputData);
@@ -1559,7 +1692,7 @@ const searchSurveyItems = (inputData, requestContext) => {
 		returned: page.items.length,
 		nextCursor: page.nextCursor,
 		truncated: page.truncated,
-		ordering: "Results are ranked by descending text-match score, then item full key. Matches within each result are ranked by descending score. Neither order is survey or respondent-visible order.",
+		ordering: "Results are ranked by descending text-match score, then structural breadcrumb. Matches within each result are ranked by descending score. Neither order is survey or respondent-visible order.",
 		results: page.items
 	}, "Survey-item search");
 };
@@ -1596,14 +1729,14 @@ const inputSchema$3 = z.object({
 		"ui-context",
 		"history"
 	])).min(1).max(6)).describe("For current-context: context sections to inspect. Empty means omitted."),
-	query: optionalNonBlankString(180).describe("For search-items: text to search across survey content. For assets: optional asset id, filename, name, ALT text, or media type filter. For current-context outline: optional key/fullKey/label filter."),
+	query: optionalNonBlankString(180).describe("For search-items: text to search across survey content. For assets: optional asset id, filename, name, ALT text, or media type filter. For current-context outline: optional editor-name/breadcrumb/label filter."),
 	sourceLocale: optionalNonBlankString(40).describe("For localization: source locale to translate. Defaults to the selected editor locale."),
 	targetLocale: optionalNonBlankString(40).describe("For localization: required target locale whose coverage should be inspected."),
 	missingOnly: optionalInput(z.boolean()).describe("For localization: return only source surfaces that do not yet exist in the target locale."),
-	itemRef: optionalNonBlankString(240).describe("For current-context outline, item-details, or raw-json: item id, key, fullKey, visible label, or \"selected\"."),
-	cursor: optionalNonBlankString(240).describe("For current-context, search-items, or localization pagination: numeric cursor from a previous result."),
-	outlineMode: optionalInput(outlineModeSchema).describe("For current-context outline: \"full\" pages all survey items, \"focused\" returns the selected/focused neighborhood, and \"children\" returns direct children of itemRef."),
-	paths: optionalArrayInput(z.array(z.string().min(1).max(500)).min(1).max(MAX_RAW_JSON_PATHS_PER_REQUEST)).describe(`For raw-json: exact JSON Pointer paths to inspect in request order. itemRef takes precedence when both are supplied. Up to ${MAX_RAW_JSON_PATHS_PER_RESULT} paths are returned per call; larger valid requests receive explicit coverage and retry guidance instead of failing input validation. Empty means omitted.`),
+	itemRef: optionalNonBlankString(240).describe("For current-context outline, item-details, or raw-json: item id, key, breadcrumb, visible label, or \"selected\"."),
+	cursor: optionalNonBlankString(240).describe("For current-context, item-details response variables, search-items, or localization pagination: numeric cursor from a previous result."),
+	outlineMode: optionalInput(outlineModeSchema).describe("For current-context outline: \"full\" pages all survey items, \"focused\" returns the selected/focused neighborhood, and \"children\" returns direct children of itemRef in stored sibling order. To verify placement or prepare a reorder, use \"children\" with the parent itemRef and page until complete; shuffled groups may render a different respondent order."),
+	paths: optionalArrayInput(z.array(z.string().max(500)).min(1).max(MAX_RAW_JSON_PATHS_PER_REQUEST)).describe(`For raw-json: exact JSON Pointer paths to inspect in request order. itemRef takes precedence when both are supplied. Up to ${MAX_RAW_JSON_PATHS_PER_RESULT} paths are returned per call; larger valid requests receive explicit coverage and retry guidance instead of failing input validation. An empty paths array means omitted; a path of "" selects the document root (JSON Pointer), while "/" selects an empty property name.`),
 	textOffset: optionalInput(z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER)).describe("For raw-json exact string paths: nextTextOffset from a partial result. Continue with the same single path until nextTextOffset is absent; restart after mutations."),
 	includeChildren: optionalInput(z.boolean()).describe("For item-details: include direct survey-tree children."),
 	includeItemConfig: optionalInput(z.boolean()).describe("For item-details: include choice/form/internal item config details."),
@@ -1654,6 +1787,7 @@ const truncateLocalizationText = (content) => {
 };
 const listLocalizationSurfaces = (input, snapshot, targetLocale) => {
 	const survey = snapshot.survey;
+	const names = new Map(snapshot.inspection.itemIndex.map((item) => [item.itemId, item.editorName]));
 	const sourceLocale = input.sourceLocale ?? snapshot.ui.selectedLocale;
 	const sourceTranslations = survey.translations?.[sourceLocale];
 	const targetTranslations = survey.translations?.[targetLocale];
@@ -1702,7 +1836,7 @@ const listLocalizationSurfaces = (input, snapshot, targetLocale) => {
 	}
 	for (const item of survey.surveyItems) for (const [contentKey, sourceContent] of Object.entries(sourceTranslations.itemTranslations?.[item.id] ?? {})) addSurface({
 		itemId: item.id,
-		itemKey: item.key,
+		itemKey: names.get(item.id) ?? item.id,
 		itemType: item.itemType,
 		contentKey,
 		sourceContent,
@@ -1885,7 +2019,9 @@ const surveyInspectTool = createTool({
 				itemId,
 				includeSurveyChildren: input.includeChildren ?? false,
 				includeItemConfig: input.includeItemConfig ?? true,
-				childrenLimit: input.limit
+				childrenLimit: input.limit,
+				responseVariablesLimit: input.limit,
+				cursor: input.cursor
 			}, requestContext));
 			if (!inspection.ok) return inspectionBackendFailure(input.action, inspection.reason);
 			const result = inspection.value;
@@ -1897,6 +2033,7 @@ const surveyInspectTool = createTool({
 			};
 		}
 		if (input.action === "expression-diagnostics") {
+			const visibilityIssues = getAssistantVisibilityIssues(createAssistantSurvey(snapshot.survey, snapshot.trustedCapabilities));
 			const allDiagnostics = analyzeSurveyAssistantExpressionReferences(snapshot.survey, snapshot.trustedCapabilities);
 			const itemId = input.itemRef ? resolveItemRef(input, snapshot) : void 0;
 			const diagnostics = itemId ? allDiagnostics.filter((diagnostic) => diagnostic.ownerItemId === itemId) : allDiagnostics;
@@ -1911,7 +2048,9 @@ const surveyInspectTool = createTool({
 				byCategory[diagnostic.category] = getSurveyAssistantExpressionDiagnosticGuidance(diagnostic);
 			}
 			const result = {
-				valid: blockingCount === 0,
+				valid: blockingCount === 0 && visibilityIssues.length === 0,
+				visibilityIssues,
+				visibilityScope: "survey",
 				count: diagnostics.length,
 				blockingCount,
 				advisoryCount,
@@ -1922,7 +2061,7 @@ const surveyInspectTool = createTool({
 			return {
 				ok: true,
 				action: input.action,
-				modelSummary: diagnostics.length === 0 ? "No expression reference diagnostics were found in the current survey draft." : blockingCount === 0 ? `${advisoryCount} advisory expression diagnostic${advisoryCount === 1 ? " was" : "s were"} found. Review each listed diagnostic according to its category-specific guidance.\n${stringifyForModel(result)}` : `${blockingCount} blocking expression reference diagnostic${blockingCount === 1 ? " was" : "s were"} found${advisoryCount > 0 ? ` alongside ${advisoryCount} advisory expression diagnostic${advisoryCount === 1 ? "" : "s"}` : ""}. Repair every blocking location, preserve advisories unless their category-specific guidance or the user requires a change, then run expression-diagnostics again before claiming the blocking repair is complete.\n${stringifyForModel(result)}`,
+				modelSummary: visibilityIssues.length > 0 ? `Survey-wide visibility validation failed. Repair cyclic or callback-based visibility using independent controlling answers or serialized context values. These checks include ancestor, component and computed dependencies outside any item filter.\n${stringifyForModel(result)}` : diagnostics.length === 0 ? "No expression reference diagnostics were found in the current survey draft." : blockingCount === 0 ? `${advisoryCount} advisory expression diagnostic${advisoryCount === 1 ? " was" : "s were"} found. Review each listed diagnostic according to its category-specific guidance.\n${stringifyForModel(result)}` : `${blockingCount} blocking expression reference diagnostic${blockingCount === 1 ? " was" : "s were"} found${advisoryCount > 0 ? ` alongside ${advisoryCount} advisory expression diagnostic${advisoryCount === 1 ? "" : "s"}` : ""}. Repair every blocking location, preserve advisories unless their category-specific guidance or the user requires a change, then run expression-diagnostics again before claiming the blocking repair is complete.\n${stringifyForModel(result)}`,
 				result
 			};
 		}
@@ -1975,7 +2114,7 @@ const surveyInspectTool = createTool({
 			inspectedPathCount: boundedPaths?.length ?? 0,
 			ignoredPathCount,
 			omittedPathCount,
-			...omittedPathCount > 0 ? { nextPaths: requestedPaths?.slice(MAX_RAW_JSON_PATHS_PER_RESULT, MAX_RAW_JSON_PATHS_PER_RESULT * 2) } : {},
+			...omittedPathCount > 0 ? { nextPaths: requestedPaths?.slice(MAX_RAW_JSON_PATHS_PER_RESULT, 40) } : {},
 			recovery: itemIdentifiers ? "Use a separate raw-json call without itemRef if the explicit paths are still needed." : "Retry the returned nextPaths in a separate raw-json call if they are still needed."
 		} : void 0;
 		const result = requestCoverage && isRecord(rawResult) ? {
@@ -1995,33 +2134,45 @@ const surveyInspectTool = createTool({
 //#endregion
 //#region src/server/tools/survey-attachment-tool.ts
 const TOOL_ID$2 = "survey_attachment";
+const inputSchema$2 = z.object({
+	documentIds: z.array(z.string().min(1)).min(1).max(4).optional().describe("Stored attachment IDs to load completely when no page/section focus is needed."),
+	documentRequests: z.array(z.object({
+		documentId: z.string().min(1),
+		pages: z.object({
+			start: z.number().int().min(1).max(1e5),
+			end: z.number().int().min(1).max(1e5)
+		}).optional().describe("One-based inclusive PDF page range to prioritize."),
+		focus: z.string().min(1).max(300).optional().describe("Short section, question range, or fact to prioritize in the original file.")
+	})).min(1).max(4).optional().describe("Stored attachments with an optional bounded reading focus.")
+});
+const outputSchema$1 = z.object({
+	loaded: z.array(z.object({
+		id: z.string(),
+		filename: z.string(),
+		mediaType: z.string(),
+		pages: z.object({
+			start: z.number().int(),
+			end: z.number().int()
+		}).optional(),
+		focus: z.string().optional()
+	})),
+	unavailable: z.array(z.object({
+		id: z.string(),
+		filename: z.string().optional(),
+		mediaType: z.string().optional(),
+		reason: z.enum([
+			"not-listed",
+			"content-unavailable",
+			"attachment-limit"
+		])
+	})).optional(),
+	warnings: z.array(z.string()).optional()
+});
 const surveyAttachmentTool = createTool({
 	id: TOOL_ID$2,
 	description: "Attach only the stored PDFs or images needed for the current task to the next native model request. For source continuation, use this before conversational recall and provide a page or section focus when known. The original file remains authoritative.",
-	inputSchema: z.object({
-		documentIds: z.array(z.string().min(1)).min(1).max(4).optional().describe("Stored attachment IDs to load completely when no page/section focus is needed."),
-		documentRequests: z.array(z.object({
-			documentId: z.string().min(1),
-			pages: z.object({
-				start: z.number().int().min(1).max(1e5),
-				end: z.number().int().min(1).max(1e5)
-			}).optional().describe("One-based inclusive PDF page range to prioritize."),
-			focus: z.string().min(1).max(300).optional().describe("Short section, question range, or fact to prioritize in the original file.")
-		})).min(1).max(4).optional().describe("Stored attachments with an optional bounded reading focus.")
-	}),
-	outputSchema: z.object({
-		loaded: z.array(z.object({
-			id: z.string(),
-			filename: z.string(),
-			mediaType: z.string(),
-			pages: z.object({
-				start: z.number().int(),
-				end: z.number().int()
-			}).optional(),
-			focus: z.string().optional()
-		})),
-		warnings: z.array(z.string()).optional()
-	}),
+	inputSchema: inputSchema$2,
+	outputSchema: outputSchema$1,
 	mcp: { annotations: {
 		title: "Load chat attachment",
 		readOnlyHint: true,
@@ -2030,8 +2181,8 @@ const surveyAttachmentTool = createTool({
 		openWorldHint: false
 	} },
 	execute: async (inputData, context) => {
-		const access = (context?.requestContext)?.get("attachmentAccess");
-		if (!access) return { loaded: [] };
+		const requestContext = context?.requestContext;
+		const access = requestContext?.get("attachmentAccess");
 		const warnings = [];
 		const requests = /* @__PURE__ */ new Map();
 		for (const documentId of inputData.documentIds ?? []) requests.set(documentId, {});
@@ -2047,11 +2198,50 @@ const surveyAttachmentTool = createTool({
 			});
 		}
 		const requestedIds = [...requests.keys()];
-		const authorized = access.documents.filter((document) => requestedIds.includes(document.id));
-		const attachments = await access.load(authorized.map((document) => document.id));
-		access.selectedAttachments.splice(0, access.selectedAttachments.length, ...attachments);
+		const authorized = access?.documents.filter((document) => requests.has(document.id)) ?? [];
+		const unavailable = requestedIds.filter((id) => !authorized.some((document) => document.id === id)).map((id) => ({
+			id,
+			reason: "not-listed"
+		}));
+		for (const { id } of unavailable) warnings.push(`Stored attachment ${id} is not in the available manifest.`);
+		if (!access) return {
+			loaded: [],
+			unavailable,
+			warnings
+		};
+		const attachments = await access.load(authorized.filter((document) => !access.selectedAttachments.some((attachment) => attachment.documentId === document.id)).map((document) => document.id));
+		const selected = new Map(access.selectedAttachments.map((attachment) => [attachment.documentId, attachment]));
+		const nativePayloads = new Map([...requestContext?.get("modelAttachments") ?? [], ...selected.values()].map((attachment) => [`${attachment.mediaType}\u0000${attachment.contentHash}`, Buffer.byteLength(attachment.data, "base64")]));
+		let totalBytes = [...nativePayloads.values()].reduce((sum, bytes) => sum + bytes, 0);
+		for (const document of authorized) {
+			if (selected.has(document.id)) continue;
+			const attachment = attachments.find((candidate) => candidate.documentId === document.id);
+			let reason = "content-unavailable";
+			if (attachment) {
+				const key = `${attachment.mediaType}\u0000${attachment.contentHash}`;
+				const bytes = Buffer.byteLength(attachment.data, "base64");
+				const alreadyIncluded = nativePayloads.has(key);
+				if (bytes <= access.limits.maxAttachmentBytes && (alreadyIncluded || nativePayloads.size < access.limits.maxAttachments && totalBytes + bytes <= access.limits.maxTotalAttachmentBytes)) {
+					selected.set(document.id, attachment);
+					if (!alreadyIncluded) {
+						nativePayloads.set(key, bytes);
+						totalBytes += bytes;
+					}
+					continue;
+				}
+				reason = "attachment-limit";
+			}
+			unavailable.push({
+				id: document.id,
+				filename: document.name,
+				mediaType: document.mediaType,
+				reason
+			});
+			warnings.push(reason === "attachment-limit" ? `Stored attachment ${document.name} (${document.id}) exceeds this turn's attachment limit and was not loaded. Use a new turn with fewer or smaller sources.` : `Stored attachment ${document.name} (${document.id}) is unavailable. No content was loaded for it. Retry loading it or ask the user to upload it again.`);
+		}
+		access.selectedAttachments.splice(0, access.selectedAttachments.length, ...selected.values());
 		return {
-			loaded: authorized.map((document) => {
+			loaded: authorized.filter((document) => selected.has(document.id)).map((document) => {
 				const request = requests.get(document.id);
 				const pages = document.mediaType === "application/pdf" ? request?.pages : void 0;
 				if (request?.pages && !pages) warnings.push(`Ignored a PDF page focus for non-PDF attachment ${document.name}.`);
@@ -2063,6 +2253,7 @@ const surveyAttachmentTool = createTool({
 					...request?.focus ? { focus: request.focus } : {}
 				};
 			}),
+			...unavailable.length > 0 ? { unavailable } : {},
 			...warnings.length > 0 ? { warnings } : {}
 		};
 	},
@@ -2277,7 +2468,7 @@ const surveyAssetTool = createTool({
 			const manifest = access?.documents.find((entry) => entry.id === input.documentId);
 			if (!access || !manifest) throw new Error(`Attachment "${input.documentId}" is not available for this turn.`);
 			if (!manifest.mediaType.startsWith("image/")) throw new Error(`Attachment "${manifest.name}" is not an image.`);
-			const [loaded] = await access.load([input.documentId]);
+			const loaded = (await access.load([input.documentId])).find((document) => document.documentId === input.documentId);
 			if (!loaded) throw new Error(`Attachment "${manifest.name}" could not be loaded.`);
 			const base = input.assetId ?? slug(manifest.name);
 			let assetId = base;
@@ -2378,4 +2569,4 @@ const surveyAssistantTools = Object.freeze({
 //#endregion
 export { surveyAuditTool as i, surveyAssistantTools as n, surveyAssetTool as r, SURVEY_ASSISTANT_TOOL_IDS as t };
 
-//# sourceMappingURL=tools-BvSovehT.mjs.map
+//# sourceMappingURL=tools-CEsv-WoO.mjs.map