@case-framework/survey-assistant 0.7.0 → 0.9.0

package/dist/{tools-BvSovehT.mjs → tools-D0KBDolR.mjs}

@@ -1,11 +1,15 @@
-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 { f as surveyChangeSetSchema } from "./protocol-BQ7uIDYT.mjs";
+import { E as surveyOperationSchemasByKind, T as surveyOperationSchema, a as SURVEY_OPERATION_KINDS, r as assistantElementTypeManifestSchema } from "./capabilities-D55dq-fO.mjs";
+import { stableStringify } from "./digest.mjs";
+import { A as itemSummarySchema, B as summarizeItemIndexEntries, D as getRawSurveyItems, E as getRawSurvey, G as unique, H as summarizeOutlineNode, I as resolveItemSummary, K as buildExpressionMutationBatch, L as sliceWithCursor, M as mapOutlineById, N as mapRawItemsById, O as itemConfigDetailsSchema, P as normalizeText, R as summarizeFocusItemNode, T as getItemIndexEntries, U as summarizeRawItem, W as translationEntrySchema, X as getSurveyAssistantExpressionDiagnosticGuidance, Y as analyzeSurveyAssistantExpressionReferences, a as collectExpressionMutationRecoveryTargets, b as buildItemTranslationEntries, c as auditSurvey, f as createSurveyChangeSet, h as normalizeSurveyChangeOperations, i as collectExpressionMutationRecoveryRefinements, j as mapItemIndexById, k as itemMatchesQuery, nt as createAssistantSurvey, o as collectMalformedSurveyOperationRecoveryTargets, q as expressionMutationSchema, rt as getAssistantVisibilityIssues, s as collectSurveyOperationRecoveryTargets, v as buildConfigSearchText, w as findDirectChildrenByParentId, x as clampLimit, y as buildItemConfigDetails, z as summarizeItemById } from "./engine-D950TfvC.mjs";
+import { c as getDeterministicCreateElementTypes, l as inspectAssistantElement, u as resolveAssistantCapabilityReference } from "./default-D22AKTqE.mjs";
+import { r as getSurveyAssistantEngineContext, s as requireSurveyAssistantTurnState } from "./request-context-KVh8VjgH.mjs";
+import { a as surveyAuthoringReferences, i as surveyAuthoringReferenceTopics, r as getBuiltInElementTypeAuthoringReference, t as builtInSurveyAuthoringElementTypes } from "./authoring-references-CmwLc_C8.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";
+import { stringRecord } from "@case-framework/survey-core/schema";
+import { SURVEY_EDITOR_ITEM_COLORS } from "@case-framework/survey-core/editor/colors";
+import { JsonPatchError, SURVEY_LOCALIZATION_SURFACES as SURVEY_LOCALIZATION_SURFACES$1, encodeJsonPointerSegment, getContentPlainText, getLocalizationEntryKey, getValueAtJsonPointer, hasLocalizationText, listLocalizationEntries, ownValue, schemaAnnotation, setOwnValue } from "@case-framework/survey-core";
+import { createHash, randomUUID } from "node:crypto";
 import { createTool, isValidationError } from "@mastra/core/tools";
 //#region src/server/operation-contract-reference.ts
 const isSurveyOperationKind = (value) => SURVEY_OPERATION_KINDS.includes(value);
@@ -19,64 +23,97 @@ const summarizeLargeSchema = (schema, propertyName) => {
 		description: `${description} The deeply nested schema is omitted from this compact reference; load the dedicated authoring reference when this structured value is needed.`
 	};
 };
-const compactJsonSchema = (value, propertyName, depth = 0) => {
-	if (Array.isArray(value)) return value.map((entry) => compactJsonSchema(entry, propertyName, depth + 1));
-	if (!isRecord$2(value)) return value;
-	if (typeof value.$ref === "string") return { description: "Recursive structured value omitted from this compact reference; request full detail only for protocol debugging." };
-	if (depth >= 3 && JSON.stringify(value).length > 12e3) return summarizeLargeSchema(value, propertyName);
-	const compact = {};
-	for (const key of [
-		"type",
-		"const",
-		"enum",
-		"description",
-		"minimum",
-		"maximum",
-		"minLength",
-		"maxLength",
-		"minItems",
-		"maxItems",
-		"required",
-		"additionalProperties"
-	]) if (value[key] !== void 0) compact[key] = value[key];
-	if (isRecord$2(value.properties)) compact.properties = Object.fromEntries(Object.entries(value.properties).map(([key, schema]) => [key, compactJsonSchema(schema, key, depth + 1)]));
-	if (value.items !== void 0) compact.items = compactJsonSchema(value.items, propertyName, depth + 1);
-	for (const unionKey of ["oneOf", "anyOf"]) if (Array.isArray(value[unionKey])) compact[unionKey] = value[unionKey].map((entry) => compactJsonSchema(entry, propertyName, depth + 1));
-	return compact;
+/** Compact explanatory material without deleting the grammar behind recursive references. */
+const compactJsonSchema = (root) => {
+	const targets = /* @__PURE__ */ new Set();
+	const collect = (value) => {
+		if (!value || typeof value !== "object") return;
+		if ("$ref" in value && typeof value.$ref === "string" && value.$ref.startsWith("#")) targets.add(decodeURIComponent(value.$ref.slice(1)));
+		Object.values(value).forEach(collect);
+	};
+	collect(root);
+	const segment = (key) => String(key).replace(/~/g, "~0").replace(/\//g, "~1");
+	const compact = (value, pointer = "", propertyName, depth = 0) => {
+		if (targets.has(pointer)) return value;
+		if (Array.isArray(value)) return value.map((entry, index) => compact(entry, `${pointer}/${index}`, propertyName, depth + 1));
+		if (!isRecord$2(value)) return value;
+		if (typeof value.$ref === "string") return value;
+		if (![...targets].some((target) => target.startsWith(`${pointer}/`)) && depth >= 3 && JSON.stringify(value).length > 12e3) return summarizeLargeSchema(value, propertyName);
+		const result = {};
+		for (const key of [
+			"type",
+			"const",
+			"enum",
+			"description",
+			"minimum",
+			"maximum",
+			"exclusiveMinimum",
+			"exclusiveMaximum",
+			"multipleOf",
+			"pattern",
+			"format",
+			"minLength",
+			"maxLength",
+			"minItems",
+			"maxItems",
+			"uniqueItems",
+			"minProperties",
+			"maxProperties",
+			"required",
+			"additionalProperties"
+		]) if (value[key] !== void 0) result[key] = value[key];
+		if (isRecord$2(value.properties)) result.properties = Object.fromEntries(Object.entries(value.properties).map(([key, schema]) => [key, compact(schema, `${pointer}/properties/${segment(key)}`, key, depth + 1)]));
+		if (value.items !== void 0) result.items = compact(value.items, `${pointer}/items`, propertyName, depth + 1);
+		for (const key of [
+			"oneOf",
+			"anyOf",
+			"allOf"
+		]) if (Array.isArray(value[key])) result[key] = value[key].map((entry, index) => compact(entry, `${pointer}/${key}/${index}`, propertyName, depth + 1));
+		for (const key of ["$defs", "definitions"]) if (value[key] !== void 0) result[key] = value[key];
+		return result;
+	};
+	return compact(root);
 };
-const formatItemCapabilityProfile = (manifest, kind) => {
-	const fixedSurfaces = manifest.contentSurfaces.filter((surface) => !surface.pattern);
-	const patternedSurfaces = manifest.contentSurfaces.filter((surface) => surface.pattern);
-	const requiredSurfaces = fixedSurfaces.filter((surface) => surface.requiredOnCreate);
-	const lines = [
-		`## Item capability: \`${manifest.itemType}\``,
-		"",
-		`${manifest.displayName}: ${manifest.description ?? "No additional description."}`,
-		`Creation mode: ${manifest.create}.`,
-		`Supported operations: ${manifest.supportedOperations.join(", ")}.`,
+const formatElementCapabilityProfile = (manifest, kind) => {
+	return [
+		`## Element capability: ${manifest.elementType}`,
+		`${manifest.displayName}: ${manifest.description ?? ""}`,
+		`Creation mode: ${manifest.create}. Supported operations: ${manifest.supportedOperations.join(", ")}.`,
 		manifest.authoring?.compactHint,
-		manifest.authoring?.configSummary ? `Configuration: ${manifest.authoring.configSummary}` : void 0,
-		manifest.creationPresets?.length ? `Available creation preset ids: ${manifest.creationPresets.map((preset) => `\`${preset.id}\``).join(", ")}. Use the server-trusted configuration guidance above for their semantics.` : void 0,
-		fixedSurfaces.length > 0 ? `Fixed content surfaces: ${fixedSurfaces.map((surface) => `${surface.key} (format=${surface.format})`).join(", ")}.` : "Fixed content surfaces: none.",
-		patternedSurfaces.length > 0 ? `Dynamic content surfaces: ${patternedSurfaces.map((surface) => `${surface.key} (format=${surface.format})`).join(", ")}.` : void 0,
-		(!kind || kind === "create-item") && requiredSurfaces.length > 0 ? `Required on creation: ${requiredSurfaces.map((surface) => surface.key).join(", ")}.` : void 0,
-		manifest.referenceTopics?.length ? `Load dedicated guidance with survey_authoring_reference using these exact arguments: ${manifest.referenceTopics.map((topic) => JSON.stringify({
+		manifest.authoring?.configSummary,
+		manifest.creationPresets?.length ? `Creation presets: ${manifest.creationPresets.map((preset) => preset.id).join(", ")}.` : void 0,
+		manifest.referenceTopics?.length ? `Additional reference topics: ${manifest.referenceTopics.join(", ")}. Load a topic with survey_authoring_reference: ${manifest.referenceTopics.map((topic) => JSON.stringify({
 			topic,
-			itemType: manifest.itemType
-		})).join("; ")}.` : void 0
-	].filter((line) => Boolean(line));
-	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");
+			elementType: manifest.elementType
+		})).join("; ")}.` : void 0,
+		"Configuration, identity, expressions and owned components come from the trusted registry's canonical schema. Inspect item details for actual owners, roles, slots and paths. Keep existing IDs during edits."
+	].filter((line) => Boolean(line)).join("\n\n");
 };
+const formatElementContract = (schema, detail = "compact") => [
+	"## Canonical element schema",
+	"This is the trusted element schema. patch-element-config paths are relative to its config property. The envelope also carries placement, response settings, prefills and conditions. Inspect owned roles for translated text; preserve surviving IDs.",
+	"Objects with x-survey-content-roles own localized content under their id. Use those exact role names and inline/block policies in ownerId/role translation entries; do not put translated wording in configuration fields.",
+	"```json",
+	JSON.stringify(z.toJSONSchema(schema, {
+		io: "input",
+		reused: "ref",
+		unrepresentable: "any",
+		override: ({ zodSchema, jsonSchema }) => {
+			const annotation = schemaAnnotation(zodSchema);
+			if (annotation?.kind === "owner") jsonSchema["x-survey-content-roles"] = annotation.roles;
+		}
+	}), null, detail === "full" ? 2 : void 0),
+	"```"
+].join("\n\n");
 const formatSurveyOperationContractReference = (kind, options = {}) => {
 	const { $schema: _schemaVersion, ...contract } = z.toJSONSchema(surveyOperationSchemasByKind[kind], {
 		io: "input",
-		reused: "inline",
+		reused: "ref",
 		unrepresentable: "any"
 	});
 	const detail = options.detail ?? "compact";
 	const renderedContract = detail === "full" ? contract : compactJsonSchema(contract);
-	const itemCapability = options.itemCapability;
+	const elementCapability = options.elementCapability;
 	return [
 		`# \`${kind}\` operation contract`,
 		"",
@@ -84,12 +121,23 @@ const formatSurveyOperationContractReference = (kind, options = {}) => {
 		"the canonical post-normalization field shape. Cross-field and snapshot-dependent rules are",
 		"enforced when the proposal is validated. Follow focused authoring guidance when it recommends",
 		"a supported model-facing shorthand; otherwise use this canonical shape.",
-		detail === "compact" ? "This compact view preserves the operation structure while omitting deeply nested value schemas. Request detail \"full\" only for protocol debugging; load a focused rich-text, expression, form, or item-type reference for authoring guidance." : "This full view is intended for protocol debugging and may be large.",
+		detail === "compact" ? "This compact view preserves the operation structure while omitting deeply nested value schemas. Request detail \"full\" only for protocol debugging; load a focused rich-text, expression, follow-up, or element-type reference for authoring guidance." : "This full view is intended for protocol debugging and may be large.",
 		"",
+		...[
+			"create-item",
+			"insert-element",
+			"insert-blocks",
+			"patch-element-config",
+			"patch-item-config",
+			"update-content",
+			"update-survey-translation"
+		].includes(kind) ? ["Localized content accepts exactly one of plainText, canonical content, or richTextBlocks shorthand. Load rich-text-content for the full block grammar. Translation entries use locale, ownerId and role; survey surfaces use their declared contentKey."] : [],
+		...kind === "survey-json-patch" ? ["Use this fallback only for exact inspected paths when no typed operation fits. It must be the only operation in a delta. Preserve existing localized values and schema identity; use survey_expression for expressions."] : [],
 		"```json",
-		JSON.stringify(renderedContract, null, 2),
+		JSON.stringify(renderedContract, null, detail === "full" ? 2 : void 0),
 		"```",
-		...itemCapability ? ["", formatItemCapabilityProfile(itemCapability, kind)] : []
+		...elementCapability ? ["", formatElementCapabilityProfile(elementCapability, kind)] : [],
+		...options.elementSchema && (kind === "patch-element-config" || kind === "insert-element" || kind === "insert-preset" || kind === "create-item") ? [formatElementContract(options.elementSchema, detail)] : []
 	].join("\n");
 };
 //#endregion
@@ -167,7 +215,7 @@ const TOOL_ID$6 = "survey_authoring_reference";
 const topicSchema = z.string().min(1).max(120);
 const inputSchema$10 = z.object({
 	topic: topicSchema.describe("The narrow authoring reference to load."),
-	itemType: z.string().min(1).max(120).optional().describe("Installed item type to focus. With topic \"item-types\", returns only that item type section instead of the combined reference."),
+	elementType: z.string().min(1).max(120).optional().describe("Installed element type to focus. With topic \"element-types\", returns only that element type section instead of the combined reference."),
 	operationKind: z.string().min(1).max(120).optional().describe("For topic assistant-operations, return only this operation's generated canonical field contract."),
 	detail: z.enum(SURVEY_OPERATION_CONTRACT_DETAIL_LEVELS).optional().describe("Contract detail for assistant-operations. Use \"compact\" for authoring and \"full\" only for protocol debugging."),
 	reason: z.string().max(500).optional().describe("Short reason this reference is needed.")
@@ -175,7 +223,7 @@ const inputSchema$10 = z.object({
 const outputSchema$8 = z.object({
 	ok: z.boolean(),
 	topic: topicSchema,
-	itemType: z.string().optional(),
+	elementType: z.string().optional(),
 	operationKind: z.string().optional(),
 	detail: z.enum(SURVEY_OPERATION_CONTRACT_DETAIL_LEVELS).optional(),
 	title: z.string(),
@@ -187,7 +235,7 @@ const formatCanonicalNameRecovery = (input, candidates, noun) => {
 };
 const surveyAuthoringReferenceTool = createTool({
 	id: TOOL_ID$6,
-	description: "Load one narrow CASE authoring reference. With topic \"item-types\", pass itemType to load only that type. For a survey_change operation, use topic \"assistant-operations\" with operationKind and optionally itemType to compose the structural contract with that installed item capability. Compact detail is the authoring default; full detail is only for protocol debugging.",
+	description: "Load one narrow CASE authoring reference. With topic \"element-types\", pass elementType to load only that type. For a survey_change operation, use topic \"assistant-operations\" with operationKind and optionally elementType to compose the structural contract with that installed element capability. Compact detail is the authoring default; full detail is only for protocol debugging.",
 	inputSchema: inputSchema$10,
 	outputSchema: outputSchema$8,
 	mcp: { annotations: {
@@ -200,12 +248,20 @@ const surveyAuthoringReferenceTool = createTool({
 	execute: async (inputData, context) => {
 		const contractDetail = inputData.detail ?? "compact";
 		const engineContext = getSurveyAssistantEngineContext(context?.requestContext);
-		const itemCapability = inputData.itemType ? engineContext?.trustedCapabilities?.byItemType.get(inputData.itemType)?.manifest ?? engineContext?.capabilities.itemTypes.find((entry) => entry.itemType === inputData.itemType) : void 0;
-		const availableItemTypes = [...builtInSurveyAuthoringItemTypes, ...engineContext?.capabilities.itemTypes.map((entry) => entry.itemType) ?? []];
+		const elementCapability = inputData.elementType ? engineContext?.trustedCapabilities?.byElementType.get(inputData.elementType)?.manifest ?? engineContext?.capabilities.elementTypes.find((entry) => entry.elementType === inputData.elementType) : void 0;
+		const availableElementTypes = engineContext ? engineContext.capabilities.elementTypes.map((entry) => entry.elementType) : builtInSurveyAuthoringElementTypes;
+		if (inputData.elementType && engineContext && !elementCapability) return {
+			ok: false,
+			topic: inputData.topic,
+			elementType: inputData.elementType,
+			operationKind: inputData.operationKind,
+			title: "Element capability unavailable",
+			content: `No installed survey element capability named "${inputData.elementType}" is available.` + formatCanonicalNameRecovery(inputData.elementType, availableElementTypes, "element type")
+		};
 		if (inputData.operationKind && inputData.topic !== "assistant-operations") return {
 			ok: false,
 			topic: inputData.topic,
-			itemType: inputData.itemType,
+			elementType: inputData.elementType,
 			operationKind: inputData.operationKind,
 			title: "Operation contract unavailable",
 			content: "operationKind is supported only with topic assistant-operations."
@@ -219,61 +275,65 @@ const surveyAuthoringReferenceTool = createTool({
 				title: "Operation contract unavailable",
 				content: `No built-in survey_change operation named "${inputData.operationKind}" is available.` + formatCanonicalNameRecovery(inputData.operationKind, SURVEY_OPERATION_KINDS, "operation")
 			};
-			if (inputData.itemType && !itemCapability && !getBuiltInItemTypeAuthoringReference(inputData.itemType)) return {
+			if (inputData.elementType && !elementCapability && !getBuiltInElementTypeAuthoringReference(inputData.elementType)) return {
 				ok: false,
 				topic: inputData.topic,
-				itemType: inputData.itemType,
+				elementType: inputData.elementType,
 				operationKind: inputData.operationKind,
 				detail: contractDetail,
 				title: "Item capability unavailable",
-				content: `No installed survey item capability named "${inputData.itemType}" is available.` + formatCanonicalNameRecovery(inputData.itemType, availableItemTypes, "item type")
+				content: `No installed survey item capability named "${inputData.elementType}" is available.` + formatCanonicalNameRecovery(inputData.elementType, availableElementTypes, "item type")
 			};
-			if (itemCapability && !itemCapability.supportedOperations.includes(inputData.operationKind)) return {
+			if (elementCapability && !elementCapability.supportedOperations.includes(inputData.operationKind)) return {
 				ok: false,
 				topic: inputData.topic,
-				itemType: inputData.itemType,
+				elementType: inputData.elementType,
 				operationKind: inputData.operationKind,
 				detail: contractDetail,
 				title: "Operation unsupported for item type",
-				content: `Item type "${itemCapability.itemType}" does not support survey_change operation "${inputData.operationKind}".`
+				content: `Item type "${elementCapability.elementType}" does not support survey_change operation "${inputData.operationKind}".`
 			};
 			return {
 				ok: true,
 				topic: inputData.topic,
-				itemType: inputData.itemType,
+				elementType: inputData.elementType,
 				operationKind: inputData.operationKind,
 				detail: contractDetail,
-				title: itemCapability ? `${inputData.operationKind} for ${itemCapability.displayName}` : `${inputData.operationKind} operation contract`,
+				title: elementCapability ? `${inputData.operationKind} for ${elementCapability.displayName}` : `${inputData.operationKind} operation contract`,
 				content: formatSurveyOperationContractReference(inputData.operationKind, {
 					detail: contractDetail,
-					itemCapability
+					elementCapability,
+					elementSchema: inputData.elementType ? engineContext?.trustedCapabilities?.registry.get(inputData.elementType).schema : void 0
 				})
 			};
 		}
 		const builtInEntry = surveyAuthoringReferenceTopics.includes(inputData.topic) ? surveyAuthoringReferences[inputData.topic] : void 0;
-		const capability = inputData.itemType ? engineContext?.trustedCapabilities?.byItemType.get(inputData.itemType) : void 0;
-		const capabilityReference = inputData.itemType ? resolveAssistantCapabilityReference({
+		const capability = inputData.elementType ? engineContext?.trustedCapabilities?.byElementType.get(inputData.elementType) : void 0;
+		const capabilityReference = inputData.elementType ? resolveAssistantCapabilityReference({
 			capabilities: engineContext?.trustedCapabilities,
-			itemType: inputData.itemType,
+			elementType: inputData.elementType,
 			topic: inputData.topic
 		}) : void 0;
-		const focusedBuiltInItemTypeReference = inputData.topic === "item-types" && inputData.itemType ? getBuiltInItemTypeAuthoringReference(inputData.itemType) : void 0;
-		if (inputData.itemType && !focusedBuiltInItemTypeReference && !capability && !capabilityReference) return {
+		const focusedBuiltInElementTypeReference = inputData.topic === "element-types" && inputData.elementType ? getBuiltInElementTypeAuthoringReference(inputData.elementType) : void 0;
+		if (inputData.elementType && !focusedBuiltInElementTypeReference && !capability && !capabilityReference) return {
 			ok: false,
 			topic: inputData.topic,
-			itemType: inputData.itemType,
+			elementType: inputData.elementType,
 			title: "Item capability unavailable",
-			content: `No installed survey item capability named "${inputData.itemType}" is available.` + formatCanonicalNameRecovery(inputData.itemType, availableItemTypes, "item type")
+			content: `No installed survey item capability named "${inputData.elementType}" is available.` + formatCanonicalNameRecovery(inputData.elementType, availableElementTypes, "item type")
 		};
 		const capabilityEntry = capabilityReference ? {
 			title: capabilityReference.title ?? `${capability?.manifest.displayName} authoring`,
 			content: capabilityReference.markdown
 		} : void 0;
-		const focusedCapabilityProfile = inputData.topic === "item-types" && itemCapability ? {
-			title: itemCapability.displayName,
-			content: formatItemCapabilityProfile(itemCapability)
+		const focusedCapabilityProfile = inputData.topic === "element-types" && elementCapability ? {
+			title: elementCapability.displayName,
+			content: formatElementCapabilityProfile(elementCapability)
 		} : void 0;
-		const baseEntry = inputData.topic === "item-types" && inputData.itemType ? focusedBuiltInItemTypeReference ?? focusedCapabilityProfile : builtInEntry;
+		const baseEntry = inputData.topic === "element-types" && inputData.elementType ? focusedBuiltInElementTypeReference && focusedCapabilityProfile ? {
+			...focusedBuiltInElementTypeReference,
+			content: [focusedBuiltInElementTypeReference.content, focusedCapabilityProfile.content].join("\n\n")
+		} : focusedBuiltInElementTypeReference ?? focusedCapabilityProfile : builtInEntry;
 		const entry = baseEntry && capabilityEntry ? {
 			title: baseEntry.title,
 			content: baseEntry.content === capabilityEntry.content ? baseEntry.content : [
@@ -286,18 +346,18 @@ const surveyAuthoringReferenceTool = createTool({
 		if (!entry) return {
 			ok: false,
 			topic: inputData.topic,
-			itemType: inputData.itemType,
+			elementType: inputData.elementType,
 			operationKind: inputData.operationKind,
 			title: "Reference unavailable",
-			content: (inputData.itemType ? `No reference named "${inputData.topic}" is installed for item type "${inputData.itemType}".` : `No built-in reference named "${inputData.topic}" is available.`) + formatCanonicalNameRecovery(inputData.topic, [...surveyAuthoringReferenceTopics, ...itemCapability?.referenceTopics ?? []], "reference")
+			content: (inputData.elementType ? `No reference named "${inputData.topic}" is installed for item type "${inputData.elementType}".` : `No built-in reference named "${inputData.topic}" is available.`) + formatCanonicalNameRecovery(inputData.topic, [...surveyAuthoringReferenceTopics, ...elementCapability?.referenceTopics ?? []], "reference")
 		};
 		return {
 			ok: true,
 			topic: inputData.topic,
-			itemType: inputData.itemType,
+			elementType: inputData.elementType,
 			operationKind: inputData.operationKind,
 			title: entry.title,
-			content: entry.content
+			content: inputData.topic === "element-types" && inputData.elementType && engineContext?.trustedCapabilities ? `${entry.content}\n\n${formatElementContract(engineContext.trustedCapabilities.registry.get(inputData.elementType).schema)}` : entry.content
 		};
 	},
 	toModelOutput: (value) => toTextModelOutput(value, (output) => `# ${output.title}\n\n${output.content}`)
@@ -318,24 +378,18 @@ const summarizePendingRepairs = (event) => {
 //#region src/server/tools/survey-change-tool.ts
 const TOOL_ID$5 = "survey_change";
 const OPERATIONS_DESCRIPTION = [
-	"Typed survey operation objects to validate and package as one undoable change. Every object uses discriminator \"kind\", never \"type\".",
-	"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.",
-	"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.",
-	`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-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.",
-	"Keep each delta bounded; this is a per-call constraint, not a reason to end the turn. Successful chunks accumulate automatically, so substantial requests should continue with later deltas while capacity remains."
+	"Typed operations use \"kind\". Load survey_authoring_reference topic=assistant-operations with operationKind for the exact generated schema.",
+	"Use insert-preset with elementType, presetId, locale and target {parentItemId,index?} for a familiar standalone question; target {layoutId,index?} adds it to an existing layout. Presets materialize fresh IDs once, before staging. Inspect the result before later edits.",
+	"For authored composition use create-item with a canonical content/group/page-break item, insert-element into a layout or insert-blocks into a body. Include ownerId/role/locale translations in the same operation. Sections are full-width vertical blocks, with one section level and one follow-up level enforced independently.",
+	"Use update-content with ref {scope:\"content\",ownerId,role} or a survey ref, locale and exactly one of plainText, content or richTextBlocks shorthand. content:null clears a value. Text belongs to declared owners, never flattened item keys. Keep all locales intact when moving content.",
+	"Use patch-element-config for choice options, matrix rows/cells and element settings. Paths are relative to the inspected config. Use move-element/move-block for moves and explicit ruleTransfer when required. Use survey_expression for expressions; never route them through generic configuration patches.",
+	"Use update-response-settings for variable names, matrix naming, option codes and exports. Never rename a single computed matrix slot.",
+	"Every reorder supplies all current children exactly once. Use move-item for flow moves and reorder-items for flow sibling order.",
+	`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.`,
+	"Image placement edits use update-placed-image with the same owner/survey ref. For imported bytes use survey_asset; remove placements before removing an asset.",
+	"Register an empty locale only if explicitly requested. Translation writes can introduce a locale; remove-survey-locale deletes its translations.",
+	"A raw survey-json-patch must be the only operation in a delta. Inspect its exact pointers first, preserve existing translations, and never change schema identity. All nested elements still require trusted authoring grants.",
+	"Successful deltas accumulate in the same turn draft; rejected deltas leave it unchanged and require repair of the same target. The live editor changes once, through its normal undo path, after successful completion. An empty operations array is only for a linked validator-confirmed no-op acknowledgment."
 ].join(" ");
 const inputSchema$9 = z.object({
 	retryOfChangeIds: retryOfChangeIdsSchema,
@@ -362,39 +416,8 @@ const rejectedOperationParseEvent = ({ issueText, summary, turnId }) => ({
 	createdAt: (/* @__PURE__ */ new Date()).toISOString()
 });
 const describeOperationTarget = (operation) => {
-	switch (operation.kind) {
-		case "update-item-translation": return `${operation.kind} ${operation.locale}:${operation.itemId}:${operation.contentKey}`;
-		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}`;
-		case "upsert-form-field-group": return `${operation.kind} ${operation.target.itemId}:${operation.group.id}`;
-		case "remove-form-field-group": return `${operation.kind} ${operation.target.itemId}:${operation.groupId}`;
-		case "reorder-form-field-groups": return `${operation.kind} ${operation.target.itemId}`;
-		case "upsert-form-field": return `${operation.kind} ${operation.target.itemId}:${operation.field.id}`;
-		case "remove-form-field":
-		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 "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-survey-metadata":
-		case "update-survey-pagination": return operation.kind;
-		case "update-survey-translation": return `${operation.kind} ${operation.locale}:${operation.surface}:${operation.contentKey}`;
-		case "add-survey-locale":
-		case "remove-survey-locale": return `${operation.kind} ${operation.locale}`;
-		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 "survey-json-patch": return `${operation.kind} ${operation.patches.map((patch) => patch.path).join(", ")}`;
-	}
+	const target = "itemId" in operation ? operation.itemId : "elementId" in operation ? operation.elementId : "ownerId" in operation ? operation.ownerId : "ref" in operation ? JSON.stringify(operation.ref) : "assetId" in operation ? operation.assetId : "item" in operation ? operation.item.id : "target" in operation ? JSON.stringify(operation.target) : "bodyOwnerId" in operation ? operation.bodyOwnerId : "layoutId" in operation ? operation.layoutId : "parentItemId" in operation ? operation.parentItemId : "locale" in operation ? operation.locale : "survey";
+	return `${operation.kind} ${target}`;
 };
 const summarizeValidation = (event) => {
 	const lines = [`${event.status === "validated" ? "Validated" : "Rejected"} survey change: ${event.summary}`];
@@ -410,11 +433,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"}`);
+				const translations = item.translations.map(({ ownerId, role, locale, textLength, textPreview, truncated }) => truncated ? `${locale}:${ownerId}/${role}=${JSON.stringify(`${textPreview}…`)} [truncated preview; ${textLength} characters total]` : `${locale}:${ownerId}/${role}=${JSON.stringify(textPreview)}`).join("; ");
+				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.");
 		}
@@ -427,7 +458,7 @@ const summarizeValidation = (event) => {
 				const location = [
 					finding.itemId,
 					finding.locale,
-					finding.contentKey
+					finding.localizationRefs ? JSON.stringify(finding.localizationRefs) : void 0
 				].filter(Boolean).join(":");
 				lines.push(`- ${finding.severity} ${finding.code}${location ? ` (${location})` : ""}: ${finding.messagePreview}${finding.truncated ? `… [truncated preview; ${finding.messageLength} characters total]` : ""}`);
 			}
@@ -438,7 +469,6 @@ const summarizeValidation = (event) => {
 		lines.push("Issues:");
 		for (const issue of event.validation.issues) lines.push(`- ${issue.code}: ${issue.message}`);
 		const issueCodes = new Set(event.validation.issues.map((issue) => issue.code));
-		if (issueCodes.has("missing-create-content") || issueCodes.has("missing-field-groups-wrapper") || issueCodes.has("missing-choice-options") || issueCodes.has("missing-choice-option-labels") || issueCodes.has("missing-form-field-content") || issueCodes.has("missing-form-select-option-labels") || issueCodes.has("missing-form-field-labels") || issueCodes.has("missing-embedded-form-field-labels")) lines.push("Recovery hint: load the assistant-operations reference, then retry only the rejected delta. Put visible text in top-level translations[] beside item, config inside item.config, choice options in item.config.options, and form fields inside item.config.fieldGroups[].fields. Every choice option id needs a matching top-level translation whose contentKey is options.<optionId>.label.");
 		if (issueCodes.has("too-many-operations")) lines.push("Recovery hint: keep the same inspected survey context and split this rejected delta into smaller survey_change calls. Each successful call extends the same turn draft.");
 		if (issueCodes.has("item-already-in-target-parent")) lines.push("Recovery hint: remove unchanged same-parent move-item operations. To change sibling order within one parent, inspect its complete current children and use reorder-items instead.");
 	}
@@ -500,12 +530,12 @@ 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."),
 	summary: z.string().max(500).optional().describe("Prepare action only: required user-facing summary."),
-	mutations: z.array(z.unknown()).min(1).max(MAX_EXPRESSION_MUTATIONS_PER_PROPOSAL).optional().describe(`Prepare action only: an array of 1-${MAX_EXPRESSION_MUTATIONS_PER_PROPOSAL} canonical expression mutation objects from the loaded expressions reference. Example entry: {"kind":"set-item-display-condition","itemId":"<existing-item-id>","expression":{"type":"function","functionName":"eq","arguments":[...]}}. expression is CASE expression JSON, never an expression-language snippet.`)
+	mutations: z.array(z.unknown()).min(1).max(MAX_EXPRESSION_MUTATIONS_PER_PROPOSAL).optional().describe(`Prepare action only: an array of 1-${MAX_EXPRESSION_MUTATIONS_PER_PROPOSAL} canonical expression mutation objects from the loaded expressions reference. Example entry: {"kind":"set-condition","ownerId":"<existing-owner-id>","property":"visibility","expression":{"type":"function","functionName":"eq","arguments":[...]}}. expression is CASE expression JSON, never an expression-language snippet.`)
 }).strict().superRefine((value, ctx) => {
 	if (value.action === "context") {
 		if (value.summary?.trim()) ctx.addIssue({
@@ -535,19 +565,31 @@ const contextOutputSchema = z.object({
 	ok: z.boolean(),
 	action: z.literal("context"),
 	modelSummary: z.string(),
-	listOrdering: z.record(z.string(), z.string()).describe("Meaning of each returned list. Expression references are not positional."),
+	listOrdering: stringRecord(z.string(), z.string()).describe("Meaning of each returned list. Expression references are not positional."),
 	nextCursor: z.string().optional(),
 	totalResponseSlots: z.number().int().nonnegative().optional(),
 	surveyResponseSlotCount: z.number().int().nonnegative().optional(),
 	totalExpressionLocations: z.number().int().nonnegative().optional(),
+	totalStateTargets: z.number().int().nonnegative().optional(),
+	stateTargets: z.array(z.object({
+		targetRef: z.object({ ownerId: z.string() }),
+		state: z.literal("disabled"),
+		itemId: z.string(),
+		kind: z.string()
+	})).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())
@@ -558,7 +600,6 @@ const createIssue = ({ severity = "error", ...input }) => ({
 	severity,
 	...input
 });
-const buildResponseSlotTypes = (snapshot) => snapshot.responseSlotTypes;
 const rejectedEvent = ({ issues, summary, turnId, warnings = [] }) => ({
 	protocolVersion: 1,
 	id: randomUUID(),
@@ -591,39 +632,52 @@ 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)?.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 = snapshot.responseVariables.filter((slot) => !itemFilter || itemFilter.has(slot.itemId)).flatMap((slot) => [{
+		ref: {
+			slotId: slot.slotId,
+			method: "get"
+		},
+		valueType: slot.valueType,
+		variableName: slot.variableName,
+		itemId: slot.itemId
+	}, {
+		ref: {
+			slotId: slot.slotId,
+			method: "isDefined"
+		},
+		valueType: "boolean",
+		variableName: slot.variableName,
+		itemId: slot.itemId
+	}]);
+	const allStateTargets = [...snapshot.model.owners.values()].filter((owner) => !itemFilter || itemFilter.has(owner.itemId)).map((owner) => ({
+		targetRef: { ownerId: owner.id },
+		itemId: owner.itemId,
+		kind: owner.kind,
+		state: "disabled"
 	}));
 	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;
-		const locations = [
-			item.displayConditions?.root ? "displayConditions.root" : void 0,
-			...Object.keys(item.displayConditions?.components ?? {}).map((componentId) => `displayConditions.components.${componentId}`),
-			...Object.keys(item.disabledConditions?.components ?? {}).map((componentId) => `disabledConditions.components.${componentId}`),
-			...Object.keys(item.validations ?? {}).map((validationKey) => `validations.${validationKey}`),
-			...(item.prefills ?? []).map((prefill) => `prefills.${prefill.id}`)
-		].filter((location) => Boolean(location));
+		if (itemFilter && !itemFilter.has(item.id)) return;
+		const locations = snapshot.model.expressions.filter((entry) => entry.path[0] === "surveyItems" && entry.path[1] === rawIndex).map((entry) => `/${entry.path.map((part) => encodeJsonPointerSegment(String(part))).join("/")}`);
 		return {
 			itemId: item.id,
-			key: item.key,
+			editorName: names.get(item.id) ?? item.id,
 			itemType: item.itemType,
 			rawIndex,
 			locations
 		};
 	}).filter((entry) => Boolean(entry)) : void 0;
 	const expressionLocations = allExpressionLocations?.slice(offset, offset + limit);
-	const totalAvailable = Math.max(allResponseSlots.length, allExpressionLocations?.length ?? 0);
+	const totalAvailable = Math.max(allResponseSlots.length, allStateTargets.length, allExpressionLocations?.length ?? 0);
 	const nextCursor = offset + limit < totalAvailable ? String(offset + limit) : void 0;
 	return {
 		ok: true,
@@ -631,31 +685,36 @@ const buildContextOutput = (snapshot, input) => {
 		modelSummary: [
 			"Expression capability loaded.",
 			"Use prepare mutations for display conditions, disabled conditions, validations, prefills, and template values.",
-			"Display, disabled, validation, and prefill.when expressions must return boolean.",
+			"Visibility, disabled and validation 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.",
+			"State nodes use {type:'ownerState',state:'disabled',targetRef:{ownerId}} (isDisabled in the editor). They include inherited disabling but do not mean hidden, missing or unchangeable due to selection limits. State references participate in the same dependency graph and cycle checks as answers.",
+			"Disabled answers remain active and are submitted. For selected-and-enabled behavior combine selection with not(isDisabled(option)); a disabled ancestor also makes that condition false. Use ordinary selection for read-only prefilled answers that must still drive branching.",
+			"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. An absent visibility condition shows its target; an evaluated missing/nonboolean condition hides it. All expressions use the canonical JSON grammar.",
 			"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(", ")}`,
+			itemFilter ? `Response-slot scope: filtered to itemIds=${JSON.stringify(input.itemIds)}; ${allResponseSlots.length} matching of ${snapshot.responseVariables.length * 2} 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 (${snapshot.responseVariables.length * 2} slots).`,
+			`State targets (${allStateTargets.length}): ${JSON.stringify(allStateTargets.slice(offset, offset + limit))}`,
+			`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
+			"Functions: and, or, not, eq, gt, gte, lt, lte, in_range, list_contains, list_count, if, sum, min, max, str_eq, date_eq.",
+			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,
+		surveyResponseSlotCount: snapshot.responseVariables.length * 2,
 		...allExpressionLocations ? { totalExpressionLocations: allExpressionLocations.length } : {},
 		...nextCursor ? { nextCursor } : {},
 		...unresolvedItemIds.length ? { unresolvedItemIds } : {},
 		listOrdering: {
 			responseSlots: "Set-like deterministic snapshot construction order; position has no survey or respondent-visible meaning.",
 			expressionLocations: "Stored surveyItems array order; locations within an item are grouped by expression surface, not ranked or respondent-visible order.",
-			"expressionLocations[].locations": "Grouped by expression surface (root, components, validations, prefills); position has no semantic meaning."
+			"expressionLocations[].locations": "Canonical schema traversal order; paths locate conditions, rules, prefills and element expressions."
 		},
 		responseSlots,
+		stateTargets: allStateTargets.slice(offset, offset + limit),
+		totalStateTargets: allStateTargets.length,
 		...expressionLocations ? { expressionLocations } : {}
 	};
 };
@@ -719,7 +778,7 @@ const surveyExpressionTool = createTool({
 		}), collectExpressionMutationRecoveryTargets(input.mutations, snapshot));
 		const prepareInput = prepareParse.data;
 		const addressedTargets = collectExpressionMutationRecoveryTargets(prepareInput.mutations, snapshot);
-		const { issues, patches } = buildExpressionMutationBatch(prepareInput.mutations, snapshot);
+		const { issues, patches } = buildExpressionMutationBatch(prepareInput.mutations, snapshot.model);
 		const errors = issues.filter((issue) => issue.severity === "error");
 		const warnings = issues.filter((issue) => issue.severity === "warning");
 		if (errors.length > 0) return reject(rejectedEvent({
@@ -765,6 +824,104 @@ const surveyExpressionTool = createTool({
 	toModelOutput: (value) => toTextModelOutput(value, (output) => "action" in output && output.action === "context" ? output.modelSummary : summarizeDraftEvent(output))
 });
 //#endregion
+//#region src/server/tools/localization-inspection.ts
+function describeContent(content, locale, ref) {
+	const text = getContentPlainText(content);
+	const path = `/translations/${encodeJsonPointerSegment(locale)}/${ref.scope === "content" ? `content/${encodeJsonPointerSegment(ref.ownerId)}` : ref.surface}/${encodeJsonPointerSegment(ref.scope === "content" ? ref.role : ref.contentKey)}`;
+	return {
+		locale,
+		type: content.type,
+		text: text.slice(0, 2e3),
+		textLength: text.length,
+		truncated: text.length > 2e3,
+		path,
+		...content.type === "richText" ? { content } : { textPath: `${path}/content` }
+	};
+}
+function inspectLocalization(input, snapshot) {
+	const survey = snapshot.survey;
+	const fail = (reason) => ({
+		ok: false,
+		reason
+	});
+	if (input.sourceLocale === input.targetLocale) return fail("Source and target locales must differ.");
+	if (input.sourceLocale && !ownValue(survey.translations, input.sourceLocale)) return fail(`Source locale "${input.sourceLocale}" is not present in the current survey draft.`);
+	const itemId = input.itemRef === "selected" ? snapshot.ui.selectedItemId : input.itemRef;
+	if (input.itemRef && (!itemId || !survey.surveyItems.some((item) => item.id === itemId))) return fail("Unknown localization item. Use an existing canonical item id.");
+	const targetTranslations = ownValue(survey.translations, input.targetLocale);
+	let entries = listLocalizationEntries(snapshot.model, {
+		sourceLocale: input.sourceLocale,
+		...itemId ? { itemIds: [itemId] } : {}
+	}).filter((entry) => Object.entries(entry.contents).some(([locale, content]) => locale !== input.targetLocale && hasLocalizationText(content)));
+	const unavailableRefs = [];
+	if (input.localizationRefs) {
+		const wanted = new Set(input.localizationRefs.map(getLocalizationEntryKey));
+		const available = new Set(entries.map((entry) => entry.key));
+		for (const ref of input.localizationRefs) if (!available.has(getLocalizationEntryKey(ref))) unavailableRefs.push(ref);
+		entries = entries.filter((entry) => wanted.has(entry.key));
+	}
+	const referenceValues = (entry) => Object.fromEntries(Object.entries(entry.contents).filter(([locale]) => locale !== input.targetLocale));
+	const fingerprint = createHash("sha256").update(stableStringify({
+		sourceLocale: input.sourceLocale,
+		targetLocale: input.targetLocale,
+		itemId,
+		refs: input.localizationRefs?.map(getLocalizationEntryKey).sort(),
+		missingOnly: Boolean(input.missingOnly),
+		entries: entries.map((entry) => [entry.key, referenceValues(entry)])
+	})).digest("hex");
+	let position = 0;
+	if (input.cursor) {
+		const parsed = /^(\d+)\.([a-f0-9]{64})$/.exec(input.cursor);
+		if (!parsed || parsed[2] !== fingerprint || !Number.isSafeInteger(Number(parsed[1])) || Number(parsed[1]) > entries.length) return fail("Localization cursor is stale or invalid. Reference content, order, or scope changed. Restart without a cursor; for review, start a fresh pass and report earlier corrections separately.");
+		position = Number(parsed[1]);
+	}
+	const missingCount = entries.filter((entry) => !hasLocalizationText(ownValue(entry.contents, input.targetLocale))).length;
+	const matches = (entry) => !input.missingOnly || !hasLocalizationText(ownValue(entry.contents, input.targetLocale));
+	const page = [];
+	while (position < entries.length && page.length < (input.limit ?? 20)) {
+		const entry = entries[position++];
+		if (matches(entry)) page.push(entry);
+	}
+	const names = new Map(snapshot.inspection.itemIndex.map((item) => [item.itemId, item.editorName]));
+	return {
+		ok: true,
+		result: {
+			...input.sourceLocale ? { sourceLocale: input.sourceLocale } : {},
+			targetLocale: input.targetLocale,
+			scope: itemId ? {
+				itemId,
+				includesDescendants: true
+			} : { survey: true },
+			...input.localizationRefs ? {
+				localizationRefs: input.localizationRefs,
+				unavailableRefs,
+				unavailableReason: "These requested fields no longer exist in scope or lack reference wording in another language. Process the available fields, report unavailable refs separately, and never widen the scope."
+			} : {},
+			targetLocalePresent: Boolean(targetTranslations),
+			missingOnly: Boolean(input.missingOnly),
+			totalTexts: entries.length,
+			missingCount,
+			translatedCount: entries.length - missingCount,
+			totalAvailable: input.missingOnly ? missingCount : entries.length,
+			returned: page.length,
+			...entries.slice(position).some(matches) ? { nextCursor: `${position}.${fingerprint}` } : {},
+			contentCoverage: "references contains all available non-target translations, not a single authoritative source. text is a preview. Read truncated plain/md values via raw-json paths: [textPath] and follow nextTextOffset using textOffset until complete. Rich-text content is complete. Read complete references and target before reviewing. targetPresent means presence, not correctness. Ask about material disagreements between references. sourceLocale, when supplied, identifies the explicitly requested source.",
+			listOrdering: { surfaces: "Survey texts first, then outline order. Cursor positions are in the complete scoped list before missingOnly. Target-text edits preserve cursors; changes to reference content, query, or entry order require a fresh pass." },
+			surfaces: page.map((entry) => ({
+				...entry.ref,
+				entryKey: entry.key,
+				...entry.ref.scope === "content" ? {
+					itemId: snapshot.model.owners.get(entry.ref.ownerId)?.itemId,
+					itemKey: names.get(snapshot.model.owners.get(entry.ref.ownerId)?.itemId ?? "")
+				} : {},
+				references: Object.entries(referenceValues(entry)).filter(([, content]) => hasLocalizationText(content)).map(([locale, content]) => describeContent(content, locale, entry.ref)),
+				targetPresent: hasLocalizationText(ownValue(entry.contents, input.targetLocale)),
+				...ownValue(entry.contents, input.targetLocale) ? { target: describeContent(ownValue(entry.contents, input.targetLocale), input.targetLocale, entry.ref) } : {}
+			}))
+		}
+	};
+}
+//#endregion
 //#region src/server/tools/parse-inspection-output.ts
 const parseInspectionOutput = (schema, value, backend) => {
 	const parsed = schema.safeParse(value);
@@ -772,6 +929,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(),
+	elementId: 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: stringRecord(z.string(), z.string()).optional(),
+	referenceValueScores: stringRecord(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,
+		elementId: slot.elementId,
+		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.elementId,
+	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",
@@ -788,15 +1008,16 @@ const outlineModeSchema$1 = z.enum([
 ]);
 const translationSnippetSchema = z.object({
 	locale: z.string(),
-	contentKey: z.string(),
+	ownerId: z.string(),
+	role: z.string(),
 	text: z.string()
 });
 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({
@@ -805,11 +1026,12 @@ const outputSchema$6 = z.object({
 	revision: z.number().int().nonnegative().optional(),
 	contentHash: z.string().optional(),
 	scopes: z.array(contextScopeSchema).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."),
+	listOrdering: stringRecord(z.string(), z.string()).optional().describe("Meaning of each returned list. A list is positional only when its entry says so."),
 	summary: 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()),
@@ -820,9 +1042,9 @@ const outputSchema$6 = z.object({
 		outlineItemCount: z.number().int().nonnegative(),
 		responseSlotCount: z.number().int().nonnegative(),
 		rootItem: itemSummarySchema.optional(),
-		availableItemTypes: z.array(z.string()),
-		deterministicCreateItemTypes: z.array(z.string()),
-		itemTypeDetails: z.array(assistantItemTypeManifestSchema)
+		availableElementTypes: z.array(z.string()),
+		deterministicCreateElementTypes: z.array(z.string()),
+		elementTypeDetails: z.array(assistantElementTypeManifestSchema)
 	}).optional(),
 	selectedItem: z.object({
 		available: z.boolean(),
@@ -859,7 +1081,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({
@@ -871,7 +1093,13 @@ const outputSchema$6 = z.object({
 			componentId: z.string().optional(),
 			label: z.string().optional(),
 			details: z.string().optional()
-		}))
+		})),
+		task: z.object({
+			kind: z.string(),
+			title: z.string().optional(),
+			instructions: z.string().optional(),
+			data: z.unknown().optional()
+		}).optional()
 	}).optional(),
 	history: z.object({
 		currentIndex: z.number().int(),
@@ -913,13 +1141,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,15 +1156,15 @@ 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),
-	itemTypeDetails: snapshot.capabilities.itemTypes
+	availableElementTypes: snapshot.capabilities.elementTypes.map((entry) => entry.elementType),
+	deterministicCreateElementTypes: getDeterministicCreateElementTypes(snapshot.capabilities),
+	elementTypeDetails: snapshot.capabilities.elementTypes
 });
 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 +1197,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 +1211,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 = 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 +1233,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 +1246,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 +1270,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) => {
@@ -1049,9 +1289,9 @@ const inspectSurveyCurrentContext = (inputData, requestContext) => {
 	if (scopes.includes("summary")) Object.assign(listOrdering, {
 		"summary.recentItemIds": "Most-recent-first UI history; not survey structure.",
 		"summary.locales": "Selected locale first, then remaining source locale order; locale position has no survey meaning.",
-		"summary.availableItemTypes": "Capability registry order; treat as a set of available types.",
-		"summary.deterministicCreateItemTypes": "Capability registry order; treat as a set of available types.",
-		"summary.itemTypeDetails": "Capability registry order; treat as a set of available type definitions."
+		"summary.availableElementTypes": "Capability registry order; treat as a set of available types.",
+		"summary.deterministicCreateElementTypes": "Capability registry order; treat as a set of available types.",
+		"summary.elementTypeDetails": "Capability registry order; treat as a set of available type definitions."
 	});
 	if (scopes.includes("selected-item")) Object.assign(listOrdering, {
 		"selectedItem.pathItems": "Root-to-selected survey-tree path.",
@@ -1079,7 +1319,8 @@ const inspectSurveyCurrentContext = (inputData, requestContext) => {
 	if (scopes.includes("ui-context")) output.uiContext = {
 		activeSurface: snapshot.ui.activeSurface,
 		openPanels: snapshot.ui.openPanels ?? [],
-		highlights: snapshot.ui.highlights ?? []
+		highlights: snapshot.ui.highlights ?? [],
+		...snapshot.ui.task ? { task: snapshot.ui.task } : {}
 	};
 	if (scopes.includes("history") && snapshot.ui.history) output.history = snapshot.ui.history;
 	return parseInspectionOutput(outputSchema$6, output, "Current-context inspection");
@@ -1087,12 +1328,13 @@ 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."),
 	includeSurveyChildren: z.boolean().default(false).describe("Whether to include a shallow list of this item's direct survey-tree children, such as group members."),
-	includeItemConfig: z.boolean().default(true).describe("Whether to include item-internal config details such as choice options and form field groups."),
+	includeItemConfig: z.boolean().default(true).describe("Whether to include item-internal config details including elements, owned components and follow-up bodies."),
 	childrenLimit: z.number().int().min(1).max(50).default(20).describe("Maximum number of direct survey-tree children to return.")
 });
 const outputSchema$5 = z.object({
@@ -1102,63 +1344,75 @@ const outputSchema$5 = z.object({
 	translations: z.array(translationEntrySchema).optional(),
 	surveyChildren: z.array(itemSummarySchema).optional(),
 	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."),
+	listOrdering: stringRecord(z.string(), z.string()).optional().describe("Meaning of each returned list. A list is positional only when its entry says so."),
 	configDetails: itemConfigDetailsSchema.optional(),
-	capabilityDetails: z.object({
+	responseVariables: z.array(responseVariableSummarySchema).optional(),
+	responseVariablesTotal: z.number().optional(),
+	responseVariablesTruncated: z.boolean().optional(),
+	responseVariablesNextCursor: z.string().optional(),
+	responseVariablesNote: z.string().optional(),
+	capabilityDetails: z.array(z.object({
+		elementId: z.string(),
+		elementType: z.string(),
 		summary: z.string(),
 		details: z.unknown().optional()
-	}).optional()
+	})).optional()
 });
 const inspectSurveyItemDetails = (inputData, requestContext) => {
-	const input = inputSchema$6.parse({
-		...inputData,
-		includeSurveyChildren: inputData.includeSurveyChildren ?? inputData.includeChildren
-	});
+	const input = inputSchema$6.parse(inputData);
 	const snapshot = getSurveyAssistantEngineContext(requestContext);
 	if (!snapshot) return {
 		ok: false,
 		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;
 	const output = {
 		ok: true,
 		item,
 		translations: buildItemTranslationEntries(snapshot, item.itemId, input),
 		listOrdering: {
-			translations: "Grouped by locale and then source translation-key order; this list is not positional survey content.",
-			surveyChildren: rawConfig?.shuffleItems === true ? "Stored group-child order; respondents see shuffled children, so this is not a stable respondent-visible order." : "Stored group-child order; this is the respondent-visible order when the parent is a group."
+			translations: "Grouped by locale and then declared content-owner and role order; this list is not positional survey content.",
+			surveyChildren: rawItem?.itemType === "group" && rawItem.config.shuffleItems === true ? "Stored group-child order; respondents see shuffled children, so this is not a stable respondent-visible order." : "Stored group-child order; this is the respondent-visible order when the parent is a group."
 		}
 	};
 	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) {
-		output.configDetails = rawItem ? buildItemConfigDetails(rawItem) : void 0;
-		output.capabilityDetails = rawItem ? inspectAssistantItem({
-			capabilities: snapshot.trustedCapabilities,
-			item: rawItem
-		}) : void 0;
-		if (rawItem?.itemType === "choiceItem" && output.configDetails?.choiceOptions) {
-			const rawChoiceConfig = rawItem.config && typeof rawItem.config === "object" && !Array.isArray(rawItem.config) ? rawItem.config : void 0;
-			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);
-				if (embeddedFormDetails?.formFieldGroups?.length) output.configDetails.formFieldGroups = [...output.configDetails.formFieldGroups ?? [], ...embeddedFormDetails.formFieldGroups];
-			}
-		}
+		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 itemId 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, snapshot.model) : void 0;
+		output.capabilityDetails = [...snapshot.model.elements.values()].filter((element) => element.itemId === item.itemId).flatMap(({ node }) => {
+			const details = inspectAssistantElement({
+				capabilities: snapshot.trustedCapabilities,
+				element: node
+			});
+			return details ? [{
+				elementId: node.id,
+				elementType: node.elementType,
+				...details
+			}] : [];
+		});
 	}
 	return parseInspectionOutput(outputSchema$5, output, "Item-details inspection");
 };
@@ -1166,17 +1420,17 @@ const inspectSurveyItemDetails = (inputData, requestContext) => {
 //#region src/server/tools/inspect-raw-survey.ts
 const DEFAULT_VALUE_CHARACTER_LIMIT = 12e3;
 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 jsonPointerPathSchema = z.string().max(500).describe("JSON Pointer path into the survey document. Examples: \"/surveyItems/0/config/items\", \"/metadata\", \"/translations/en/content/<ownerId>/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()
@@ -1186,7 +1440,7 @@ const outputSchema$4 = z.object({
 	reason: z.string().optional(),
 	revision: z.number().int().nonnegative().optional(),
 	contentHash: z.string().optional(),
-	listOrdering: z.record(z.string(), z.string()).optional().describe("Meaning of each returned list. Raw JSON arrays retain their stored order."),
+	listOrdering: stringRecord(z.string(), z.string()).optional().describe("Meaning of each returned list. Raw JSON arrays retain their stored order."),
 	overview: z.object({
 		topLevelKeys: z.array(z.string()),
 		surveyItemCount: z.number().int().nonnegative(),
@@ -1216,7 +1470,7 @@ const outputSchema$4 = z.object({
 		rawItemPreview: z.string().optional(),
 		rawItemTruncated: z.boolean().optional(),
 		translationPaths: z.array(z.string()).optional(),
-		translationsByLocale: z.record(z.string(), z.unknown()).optional(),
+		translationsByLocale: stringRecord(z.string(), z.unknown()).optional(),
 		translationsPreview: z.string().optional(),
 		translationsTruncated: z.boolean().optional(),
 		error: z.string().optional()
@@ -1237,6 +1491,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 +1499,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 +1560,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;
@@ -1314,26 +1569,30 @@ const findRawItemByIdentifier = (snapshot, identifier) => {
 		index: resolvedIndex
 	};
 };
-const getTranslationsByLocaleForItem = (rawSurvey, itemId) => {
+const getTranslationsByLocaleForItem = (snapshot, itemId) => {
 	const entries = {};
-	for (const [locale, localeTranslations] of Object.entries(rawSurvey.translations ?? {})) {
-		const itemTranslations = localeTranslations?.itemTranslations?.[itemId];
-		if (itemTranslations) entries[locale] = itemTranslations;
+	const ownerIds = [...snapshot.model.owners.values()].filter((owner) => owner.itemId === itemId).map((owner) => owner.id);
+	for (const [locale, translations] of Object.entries(snapshot.survey.translations ?? {})) {
+		const content = Object.fromEntries(ownerIds.flatMap((ownerId) => {
+			const content = ownValue(translations.content, ownerId);
+			return content ? [[ownerId, content]] : [];
+		}));
+		if (Object.keys(content).length) setOwnValue(entries, locale, content);
 	}
 	return entries;
 };
 const buildItemValues = (snapshot, input) => {
-	const rawSurvey = getRawSurvey(snapshot);
 	return input.itemIdentifiers.map((identifier) => {
 		const resolved = findRawItemByIdentifier(snapshot, identifier);
 		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(snapshot, itemId);
+		const translationsOutput = toOutputValue(translationsByLocale, input.valueCharacterLimit);
 		const translationsValue = "value" in translationsOutput && isRecord$1(translationsOutput.value) ? translationsOutput.value : void 0;
 		return {
 			identifier,
@@ -1343,7 +1602,7 @@ const buildItemValues = (snapshot, input) => {
 			rawItem: "value" in rawItemOutput ? rawItemOutput.value : void 0,
 			rawItemPreview: "preview" in rawItemOutput ? rawItemOutput.preview : void 0,
 			rawItemTruncated: rawItemOutput.truncated,
-			translationPaths: snapshot.inspection.locales.map((locale) => `/translations/${encodeJsonPointerSegment(locale)}/itemTranslations/${encodeJsonPointerSegment(itemId)}`),
+			translationPaths: snapshot.inspection.locales.flatMap((locale) => [...snapshot.model.owners.values()].filter((owner) => owner.itemId === itemId).map((owner) => `/translations/${encodeJsonPointerSegment(locale)}/content/${encodeJsonPointerSegment(owner.id)}`)),
 			translationsByLocale: translationsValue,
 			translationsPreview: "preview" in translationsOutput ? translationsOutput.preview : void 0,
 			translationsTruncated: translationsOutput.truncated
@@ -1393,7 +1652,8 @@ const searchMatchSchema = z.object({
 	]),
 	field: z.string().optional(),
 	locale: z.string().optional(),
-	contentKey: z.string().optional(),
+	ownerId: z.string().optional(),
+	role: z.string().optional(),
 	text: z.string(),
 	score: z.number()
 });
@@ -1404,7 +1664,8 @@ const searchResultSchema = z.object({
 });
 const inputSchema$4 = z.object({
 	query: z.string().min(1).max(MAX_QUERY_LENGTH).describe("Text to search for across all survey items, including visible translated content such as titles, option labels, and form field labels. Examples: \"age\", \"consent\", \"blood pressure\"."),
-	itemTypes: z.array(z.string()).optional().describe("Optional item types to restrict results to, such as choiceItem or formItem."),
+	itemTypes: z.array(z.string()).optional().describe("Optional item types to restrict results to, content, group or page-break."),
+	elementTypes: z.array(z.string()).optional().describe("Optional registered element types. Return items containing at least one matching element, including option follow-ups."),
 	locales: z.array(z.string()).optional().describe("Optional locale codes to restrict translation-content matches to."),
 	cursor: z.string().optional().describe("Optional numeric cursor returned by a previous search."),
 	limit: z.number().int().min(1).max(50).default(12).describe("Maximum number of matching items to return.")
@@ -1420,7 +1681,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",
@@ -1463,7 +1724,7 @@ const scoreText = (value, query, terms, baseScore) => {
 const addMatch = (matches, match) => {
 	const text = match.text?.trim();
 	if (!text) return;
-	if (!matches.some((existing) => existing.source === match.source && existing.field === match.field && existing.locale === match.locale && existing.contentKey === match.contentKey && existing.text === text)) matches.push({
+	if (!matches.some((existing) => existing.source === match.source && existing.field === match.field && existing.locale === match.locale && existing.ownerId === match.ownerId && existing.role === match.role && existing.text === text)) matches.push({
 		...match,
 		text
 	});
@@ -1473,7 +1734,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,
@@ -1492,13 +1753,21 @@ const candidateItems = (snapshot) => {
 const searchItems = (snapshot, input) => {
 	const terms = queryTerms(input.query);
 	const itemTypeFilter = input.itemTypes?.length ? new Set(input.itemTypes) : void 0;
-	return candidateItems(snapshot).filter(({ item }) => !itemTypeFilter || itemTypeFilter.has(item.itemType)).map(({ item, rawItem }) => {
+	const elementTypeFilter = input.elementTypes?.length ? new Set(input.elementTypes) : void 0;
+	const typesByItem = /* @__PURE__ */ new Map();
+	for (const element of snapshot.model.elements.values()) {
+		const types = typesByItem.get(element.itemId) ?? /* @__PURE__ */ new Set();
+		types.add(element.node.elementType);
+		typesByItem.set(element.itemId, types);
+	}
+	return candidateItems(snapshot).filter(({ item }) => !elementTypeFilter || [...typesByItem.get(item.itemId) ?? []].some((type) => elementTypeFilter.has(type))).filter(({ item }) => !itemTypeFilter || itemTypeFilter.has(item.itemType)).map(({ item, rawItem }) => {
 		const matches = [];
 		const structuralFields = [
 			["itemId", item.itemId],
 			["itemType", item.itemType],
-			["key", item.key],
-			["fullKey", item.fullKey],
+			["elementTypes", [...typesByItem.get(item.itemId) ?? []].join(" ")],
+			["key", item.editorName],
+			["breadcrumb", item.breadcrumb],
 			["itemLabel", item.itemLabel],
 			["path", item.path?.join(" ")]
 		];
@@ -1516,16 +1785,17 @@ const searchItems = (snapshot, input) => {
 			locales: input.locales,
 			textLimit: DEFAULT_TEXT_LIMIT
 		})) {
-			const score = scoreText(`${translation.contentKey} ${translation.text}`, input.query, terms, 100);
+			const score = scoreText(`${translation.ownerId} ${translation.role} ${translation.text}`, input.query, terms, 100);
 			if (score !== null) addMatch(matches, {
 				source: "translation",
 				locale: translation.locale,
-				contentKey: translation.contentKey,
+				ownerId: translation.ownerId,
+				role: translation.role,
 				text: translation.text,
 				score
 			});
 		}
-		if (rawItem) for (const text of buildConfigSearchText(rawItem)) {
+		if (rawItem) for (const text of buildConfigSearchText(rawItem, snapshot.model)) {
 			const score = scoreText(text, input.query, terms, 60);
 			if (score !== null) addMatch(matches, {
 				source: "config",
@@ -1540,7 +1810,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 +1829,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 +1866,30 @@ 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."),
-	sourceLocale: optionalNonBlankString(40).describe("For localization: source locale to translate. Defaults to the selected editor locale."),
+	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."),
+	itemTypes: optionalArrayInput(z.array(z.enum([
+		"content",
+		"group",
+		"page-break"
+	]))).describe("For search-items: optional flow item types."),
+	elementTypes: optionalArrayInput(z.array(z.string().min(1).max(120))).describe("For search-items: optional registered element types contained in matching items."),
+	locales: optionalArrayInput(z.array(z.string().min(1).max(40))).describe("For search-items: optional languages for translation matches."),
+	sourceLocale: optionalNonBlankString(40).describe("For localization: optional explicitly requested source locale. Omit to use all available language versions as references; the selected UI locale does not establish a source."),
 	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.`),
+	localizationRefs: optionalArrayInput(z.array(z.discriminatedUnion("scope", [z.object({
+		scope: z.literal("content"),
+		ownerId: z.string().min(1).max(240),
+		role: z.string().min(1).max(500)
+	}), z.object({
+		scope: z.literal("survey"),
+		surface: z.enum(SURVEY_LOCALIZATION_SURFACES$1),
+		contentKey: z.string().min(1).max(500)
+	})])).min(1).max(200)).describe("For localization: optional exact text field references selected by the author. Process larger selections in groups of at most 200 references."),
+	missingOnly: optionalInput(z.boolean()).describe("For localization: return only texts missing in the target locale and present in at least one reference language."),
+	itemRef: optionalNonBlankString(240).describe("For localization: an existing canonical item id or \"selected\"; scopes to its subtree, excluding survey texts. For current-context outline, item-details, or raw-json: item reference."),
+	cursor: optionalNonBlankString(240).describe("Use the exact cursor returned by the previous result. Localization uses position.fingerprint, stable across target-text edits. Other actions use numeric offsets."),
+	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."),
@@ -1642,148 +1928,27 @@ const inspectionBackendFailure = (action, reason) => ({
 	modelSummary: reason
 });
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
-const MAX_LOCALIZATION_TEXT_CHARS = 2e3;
-const SURVEY_TRANSLATION_SURFACES = [
-	"surveyCardContent",
-	"navigationContent",
-	"validationMessages"
-];
-const truncateLocalizationText = (content) => {
-	const text = getContentPlainText(content).trim();
-	return text.length > MAX_LOCALIZATION_TEXT_CHARS ? `${text.slice(0, MAX_LOCALIZATION_TEXT_CHARS)}...` : text;
-};
-const listLocalizationSurfaces = (input, snapshot, targetLocale) => {
-	const survey = snapshot.survey;
-	const sourceLocale = input.sourceLocale ?? snapshot.ui.selectedLocale;
-	const sourceTranslations = survey.translations?.[sourceLocale];
-	const targetTranslations = survey.translations?.[targetLocale];
-	if (!sourceTranslations) return {
-		ok: false,
-		reason: `Source locale "${sourceLocale}" is not present in the current survey draft.`
-	};
-	const surfaces = [];
-	const addSurface = ({ contentKey, itemId, itemKey, itemType, sourceContent, surface, targetContent }) => {
-		const sourceText = truncateLocalizationText(sourceContent);
-		if (!sourceText) return;
-		const sourcePath = `/translations/${encodeJsonPointerSegment(sourceLocale)}/${itemId ? `itemTranslations/${encodeJsonPointerSegment(itemId)}` : surface}/${encodeJsonPointerSegment(contentKey)}`;
-		surfaces.push({
-			scope: itemId ? "item" : "survey",
-			...surface ? { surface } : {},
-			...itemId ? {
-				itemId,
-				itemKey,
-				itemType
-			} : {},
-			contentKey,
-			sourceType: sourceContent.type,
-			sourceText,
-			sourceTextLength: getContentPlainText(sourceContent).trim().length,
-			sourceTruncated: getContentPlainText(sourceContent).trim().length > MAX_LOCALIZATION_TEXT_CHARS,
-			sourcePath,
-			...sourceContent.type !== "richText" ? { sourceTextPath: `${sourcePath}/content` } : {},
-			...sourceContent.type === "richText" ? { sourceContent } : {},
-			targetPresent: Boolean(targetContent && truncateLocalizationText(targetContent)),
-			...targetContent ? {
-				targetType: targetContent.type,
-				targetText: truncateLocalizationText(targetContent),
-				targetTextLength: getContentPlainText(targetContent).trim().length,
-				targetTruncated: getContentPlainText(targetContent).trim().length > MAX_LOCALIZATION_TEXT_CHARS
-			} : {}
-		});
-	};
-	for (const surface of SURVEY_TRANSLATION_SURFACES) {
-		const targetSurface = targetTranslations?.[surface];
-		for (const [contentKey, sourceContent] of Object.entries(sourceTranslations[surface] ?? {})) addSurface({
-			surface,
-			contentKey,
-			sourceContent,
-			targetContent: targetSurface?.[contentKey]
-		});
-	}
-	for (const item of survey.surveyItems) for (const [contentKey, sourceContent] of Object.entries(sourceTranslations.itemTranslations?.[item.id] ?? {})) addSurface({
-		itemId: item.id,
-		itemKey: item.key,
-		itemType: item.itemType,
-		contentKey,
-		sourceContent,
-		targetContent: targetTranslations?.itemTranslations?.[item.id]?.[contentKey]
-	});
-	const missingCount = surfaces.filter((surface) => !surface.targetPresent).length;
-	const filteredSurfaces = input.missingOnly ? surfaces.filter((surface) => !surface.targetPresent) : surfaces;
-	const parsedCursor = Number.parseInt(input.cursor ?? "0", 10);
-	const offset = Number.isFinite(parsedCursor) && parsedCursor >= 0 ? parsedCursor : 0;
-	const limit = input.limit ?? 20;
-	const page = filteredSurfaces.slice(offset, offset + limit);
-	const nextOffset = offset + page.length;
-	return {
-		ok: true,
-		result: {
-			sourceLocale,
-			targetLocale,
-			missingOnly: input.missingOnly ?? false,
-			contentCoverage: "sourceText and targetText are previews. For sourceTruncated plain text, inspect raw-json paths: [sourceTextPath] and follow nextTextOffset with textOffset until complete before translating. Rich-text sourceContent is the complete canonical value. Never translate only a truncated preview or treat targetPresent as proof of translation completeness.",
-			totalSourceSurfaces: surfaces.length,
-			totalAvailable: filteredSurfaces.length,
-			missingCount,
-			returned: page.length,
-			...nextOffset < filteredSurfaces.length ? { nextCursor: String(nextOffset) } : {},
-			listOrdering: { surfaces: "Survey-level translation surfaces first, then item translations in stored survey-item and source content-key order. Cursor pagination preserves this order only while the draft is unchanged; restart without a cursor after mutations." },
-			surfaces: page
-		}
-	};
-};
 const resolveItemRef = (input, snapshot) => {
 	if (input.itemRef && input.itemRef !== "selected") return input.itemRef;
 	return snapshot?.ui.selectedItemId;
 };
-const listAssetUsageSummaries = (survey) => {
-	const usagesByAssetId = /* @__PURE__ */ new Map();
-	const addContent = (content, usage) => {
-		for (const assetUsage of getAssetUsagesFromContent(content)) {
-			const usages = usagesByAssetId.get(assetUsage.assetId) ?? [];
-			usages.push({
-				...usage,
-				blockIndex: assetUsage.blockIndex
-			});
-			usagesByAssetId.set(assetUsage.assetId, usages);
-		}
-	};
-	for (const [locale, localeTranslations] of Object.entries(survey.translations ?? {})) {
-		for (const scope of [
-			"surveyCardContent",
-			"navigationContent",
-			"validationMessages"
-		]) for (const [contentKey, content] of Object.entries(localeTranslations[scope] ?? {})) addContent(content, {
-			locale,
-			scope,
-			contentKey
-		});
-		for (const [itemId, itemTranslations] of Object.entries(localeTranslations.itemTranslations ?? {})) for (const [contentKey, content] of Object.entries(itemTranslations ?? {})) addContent(content, {
-			locale,
-			scope: "itemTranslation",
-			itemId,
-			contentKey
-		});
-	}
-	return usagesByAssetId;
-};
 const summarizeAssetSource = (asset) => ({
 	type: asset.source.type,
 	mediaType: asset.source.mediaType
 });
 const listAssets = (input, snapshot) => {
 	const survey = snapshot.survey;
-	const usagesByAssetId = listAssetUsageSummaries(survey);
+	const usages = snapshot.model.getAssetUsages();
 	const query = input.query?.trim().toLowerCase();
 	const allAssets = Object.entries(survey.assets ?? {}).map(([assetId, asset]) => {
-		const usages = usagesByAssetId.get(assetId) ?? [];
+		const assetUsages = usages.filter((usage) => usage.assetId === assetId);
 		return {
 			assetId,
 			kind: asset.kind,
 			source: summarizeAssetSource(asset),
 			...asset.metadata ? { metadata: asset.metadata } : {},
-			usageCount: usages.length,
-			usages
+			usageCount: assetUsages.length,
+			usages: assetUsages
 		};
 	}).filter((asset) => {
 		if (!query) return true;
@@ -1813,7 +1978,7 @@ const listAssets = (input, snapshot) => {
 };
 const surveyInspectTool = createTool({
 	id: TOOL_ID$3,
-	description: "Inspect the current request-scoped survey draft through one compact interface: current context, item search, item details, paged source/target localization surfaces, image assets with explicit asset IDs and usages, expression-reference diagnostics, or focused raw JSON. For expression diagnostics, valid means there are no blocking diagnostics; advisories remain counted. At turn start the draft equals the live snapshot; successful same-turn edits appear immediately.",
+	description: "Inspect the current request-scoped survey draft through one compact interface: current context, item search, item details, paged multilingual localization surfaces, image assets with explicit asset IDs and usages, expression-reference diagnostics, or focused raw JSON. For expression diagnostics, valid means there are no blocking diagnostics; advisories remain counted. At turn start the draft equals the live snapshot; successful same-turn edits appear immediately.",
 	inputSchema: inputSchema$3,
 	outputSchema: outputSchema$2,
 	mcp: { annotations: {
@@ -1862,7 +2027,10 @@ const surveyInspectTool = createTool({
 			const inspection = runInspectionBackend(() => searchSurveyItems({
 				query,
 				limit: input.limit,
-				cursor: input.cursor
+				cursor: input.cursor,
+				itemTypes: input.itemTypes,
+				elementTypes: input.elementTypes,
+				locales: input.locales
 			}, requestContext));
 			if (!inspection.ok) return inspectionBackendFailure(input.action, inspection.reason);
 			const result = inspection.value;
@@ -1885,7 +2053,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,32 +2067,36 @@ 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;
-			const orderedDiagnostics = [...diagnostics].sort((left, right) => Number(isBlockingSurveyExpressionReferenceDiagnostic(right)) - Number(isBlockingSurveyExpressionReferenceDiagnostic(left)));
-			const blockingCount = diagnostics.filter(isBlockingSurveyExpressionReferenceDiagnostic).length;
+			const orderedDiagnostics = [...diagnostics].sort((left, right) => Number(right.severity === "error") - Number(left.severity === "error"));
+			const blockingCount = diagnostics.filter((diagnostic) => diagnostic.severity === "error").length;
 			const advisoryCount = diagnostics.length - blockingCount;
 			const limit = input.limit ?? 50;
 			const limitedDiagnostics = orderedDiagnostics.slice(0, limit);
-			const guidanceByDispositionAndCategory = {};
+			const guidanceByCode = {};
 			for (const diagnostic of orderedDiagnostics) {
-				const byCategory = guidanceByDispositionAndCategory[diagnostic.disposition] ??= {};
-				byCategory[diagnostic.category] = getSurveyAssistantExpressionDiagnosticGuidance(diagnostic);
+				const guidance = getSurveyAssistantExpressionDiagnosticGuidance(diagnostic);
+				const existing = ownValue(guidanceByCode, diagnostic.code);
+				setOwnValue(guidanceByCode, diagnostic.code, existing && !existing.includes(guidance) ? `${existing} ${guidance}` : guidance);
 			}
 			const result = {
-				valid: blockingCount === 0,
+				valid: blockingCount === 0 && visibilityIssues.length === 0,
+				visibilityIssues,
+				visibilityScope: "survey",
 				count: diagnostics.length,
 				blockingCount,
 				advisoryCount,
 				diagnostics: limitedDiagnostics,
-				guidanceByDispositionAndCategory,
+				guidanceByCode,
 				truncated: diagnostics.length > limit
 			};
 			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
 			};
 		}
@@ -1933,7 +2107,10 @@ const surveyInspectTool = createTool({
 				reason: "Localization inspection requires a targetLocale.",
 				modelSummary: "Localization inspection requires a targetLocale."
 			};
-			const localization = listLocalizationSurfaces(input, snapshot, input.targetLocale);
+			const localization = inspectLocalization({
+				...input,
+				targetLocale: input.targetLocale
+			}, snapshot);
 			if (!localization.ok) return {
 				ok: false,
 				action: input.action,
@@ -1975,7 +2152,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) ? {
@@ -1990,38 +2167,53 @@ const surveyInspectTool = createTool({
 			result
 		};
 	},
-	toModelOutput: (value) => toTextModelOutput(value, (output) => output.modelSummary)
+	toModelOutput: (value) => toTextModelOutput(value, (output) => output.ok && output.action === "item-details" && isRecord(output.result) && output.result.ok === true ? JSON.stringify({
+		capabilityDetails: output.result.capabilityDetails,
+		...output.result
+	}) : output.modelSummary)
 });
 //#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 +2222,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 +2239,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 +2294,7 @@ const surveyAttachmentTool = createTool({
 					...request?.focus ? { focus: request.focus } : {}
 				};
 			}),
+			...unavailable.length > 0 ? { unavailable } : {},
 			...warnings.length > 0 ? { warnings } : {}
 		};
 	},
@@ -2135,14 +2367,14 @@ const formatAuditForModel = (output) => {
 			const location = [
 				finding.itemId,
 				finding.locale,
-				finding.contentKey
+				finding.localizationRefs ? JSON.stringify(finding.localizationRefs) : finding.path?.join("/")
 			].filter(Boolean).join(":");
 			return `- [${finding.severity}] ${finding.code}${location ? ` (${location})` : ""}: ${previewAuditMessage(finding.message)}${finding.suggestion ? ` Guidance: ${previewAuditMessage(finding.suggestion)}` : ""}`;
 		}).join("\n")}` : void 0,
 		report.qualityReviewPrinciples.length > 0 ? `Qualitative review rubric:\n${report.qualityReviewPrinciples.map((principle) => `- ${principle.id}: ${principle.prompt}`).join("\n")}` : void 0,
 		report.keyReview.entries.length > 0 ? `Key/content review evidence (${report.keyReview.offset + 1}-${report.keyReview.offset + report.keyReview.returnedEntryCount} of ${report.keyReview.entryCount}, source locale ${report.keyReview.sourceLocale ?? "unavailable"}${report.keyReview.truncated ? "; more pages available" : ""}):\n${report.keyReview.entries.map((entry) => {
 			const content = entry.content ? `; current content=${JSON.stringify(previewAuditMessage(entry.content))}` : "; current content unavailable";
-			return `- ${entry.kind} item=${entry.itemId} itemKey=${JSON.stringify(entry.itemKey)} key=${JSON.stringify(entry.key)} (${entry.keySource})${entry.contentKey ? ` contentKey=${entry.contentKey}` : ""}${content}`;
+			return `- ${entry.kind} item=${entry.itemId} itemKey=${JSON.stringify(entry.itemKey)} key=${JSON.stringify(entry.key)} (${entry.keySource})${entry.localizationRefs?.length ? ` contentRefs=${JSON.stringify(entry.localizationRefs)}` : ""}${content}`;
 		}).join("\n")}\n${report.keyReview.note}` : `Key/content review evidence: none returned (${report.keyReview.entryCount} total entries).`,
 		report.note,
 		"This audit checks the current survey deterministically. It does not compare the draft with an attached source document, so a clean audit does not establish source fidelity or completeness."
@@ -2193,21 +2425,7 @@ const inputSchema = z.object({
 const slug = (value) => value.toLowerCase().replace(/\.[^.]+$/, "").replace(/[^a-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 100) || "image";
 const OMITTED_EMBEDDED_IMAGE_DATA = "[embedded image data omitted from transcript]";
 const getAssetReferenceLabels = (snapshot, assetId) => {
-	const translations = (snapshot?.survey)?.translations;
-	if (!translations) return [];
-	const references = [];
-	const inspectContent = (content, label) => {
-		if (getAssetUsagesFromContent(content).some((usage) => usage.assetId === assetId)) references.push(label);
-	};
-	for (const [locale, localeTranslations] of Object.entries(translations)) {
-		for (const surface of [
-			"surveyCardContent",
-			"navigationContent",
-			"validationMessages"
-		]) for (const [contentKey, content] of Object.entries(localeTranslations[surface] ?? {})) inspectContent(content, `${locale}:${surface}:${contentKey}`);
-		for (const [itemId, itemTranslations] of Object.entries(localeTranslations.itemTranslations ?? {})) for (const [contentKey, content] of Object.entries(itemTranslations ?? {})) inspectContent(content, `${locale}:item:${itemId}:${contentKey}`);
-	}
-	return references;
+	return snapshot?.model.getAssetUsages(assetId).map((usage) => `${usage.locale}:${usage.ref.scope === "content" ? `${usage.ref.ownerId}:${usage.ref.role}` : `${usage.ref.surface}:${usage.ref.contentKey}`}`) ?? [];
 };
 const getToolOutput = (value) => value && typeof value === "object" && "output" in value && value.output !== void 0 ? value.output : value;
 const describeAssetOperation = (operation) => {
@@ -2227,8 +2445,8 @@ const summarizeAssetChange = (event) => {
 			lines.push(`Imported: ${event.operations.filter((operation) => operation.kind === "set-image-asset").map(describeAssetOperation).join(", ")}`);
 			lines.push(`Asset id to reference: ${importedAssetIds.join(", ")}`);
 			lines.push("The asset is now available to later mutation calls in this turn. To use it in a new item, reference it from that item's create-item translation. If a later delta is rejected, fix only that delta; this import remains in the draft.");
-			lines.push(`New info-item image source: { "type": "asset", "assetId": "${importedAssetIds[0]}" }. Embed the canonical image block inside the create-item translation richTextBlocks array.`);
-			lines.push(`New info-item translation example: { "locale": "<selected-locale>", "contentKey": "content", "richTextBlocks": [{ "type": "image", "source": { "type": "asset", "assetId": "${importedAssetIds[0]}" }, "alt": "<meaningful description>" }] }.`);
+			lines.push(`Information element image source: { "type": "asset", "assetId": "${importedAssetIds[0]}" }. Embed the canonical image block inside the create-item translation richTextBlocks array.`);
+			lines.push(`Information element translation example: { "locale": "<selected-locale>", "ownerId": "<information-element-id>", "role": "body", "richTextBlocks": [{ "type": "image", "source": { "type": "asset", "assetId": "${importedAssetIds[0]}" }, "alt": "<meaningful description>" }] }.`);
 		}
 	}
 	if (event.validation.issues.length > 0) lines.push(`Issues:\n${event.validation.issues.map((issue) => `- ${issue.code}: ${issue.message}`).join("\n")}`);
@@ -2277,13 +2495,13 @@ 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;
 			let suffix = 2;
 			const stagedAssetIds = new Set(turnDraft.draftOperations.flatMap((draftOperation) => draftOperation.kind === "set-image-asset" ? [draftOperation.assetId] : []));
-			while (snapshot?.survey.assets?.[assetId] || stagedAssetIds.has(assetId)) assetId = `${base}-${suffix++}`;
+			while (ownValue(snapshot?.survey.assets, assetId) || stagedAssetIds.has(assetId)) assetId = `${base}-${suffix++}`;
 			operation = {
 				kind: "set-image-asset",
 				assetId,
@@ -2334,7 +2552,7 @@ const surveyAssetTool = createTool({
 				validation: {
 					...event.validation,
 					valid: false,
-					issues: [...event.validation.issues, {
+					issues: [...event.validation.issues.filter((issue) => issue.code !== "image-asset-still-referenced"), {
 						severity: "error",
 						code: "image-asset-still-referenced",
 						message: `Image asset "${operation.assetId}" is still referenced by ${referenceLabels.slice(0, 3).join(", ")}. Prepare one survey_change delta containing every reference-removal operation first and remove-image-asset last.`,
@@ -2378,4 +2596,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-D0KBDolR.mjs.map